Skip to content

README.md

Latest commit

 

History

History
110 lines (79 loc) · 2.91 KB

README.md

File metadata and controls

110 lines (79 loc) · 2.91 KB

TimeCapsule Smart Contract 🕰️

A Solidity smart contract that enables users to create time-locked messages on the Ethereum blockchain. Perfect for storing messages that can only be retrieved after a specified time period has elapsed.

Features

  • Create time-locked messages (capsules)
  • Retrieve messages only after the lock period expires
  • View capsule details including lock time and retrieval status
  • Gas-efficient implementation
  • Comprehensive test coverage

Technical Stack

  • Solidity ^0.8.0
  • Hardhat Development Environment
  • Ethers.js
  • Chai for testing

Contract Architecture

The contract implements a simple but effective time-locking mechanism using the following structure:

struct Capsule {
    string message;
    uint256 unlockTime;
    bool retrieved;
}

Key Functions

  1. createCapsule(string calldata _message, uint256 _lockTime)

    • Creates a new time-locked capsule
    • Validates that user doesn't have an existing capsule
    • Sets unlock time based on current block timestamp

  2. retrieveCapsule()

    • Retrieves the message after the lock period
    • Implements multiple security checks
    • Marks capsule as retrieved to prevent multiple retrievals

  3. viewCapsule()

    • Returns capsule details without modifying state
    • Useful for checking lock status and message availability

Security Considerations

  • Implements checks-effects-interactions pattern
  • Uses require statements for input validation
  • Time-based operations account for block.timestamp
  • Single capsule per address to prevent spam
  • Retrieved status tracking to prevent multiple retrievals

Testing

The contract includes a comprehensive test suite written in JavaScript using the Hardhat testing framework. To run the tests:

npm install
npx hardhat test

Tests cover:

  • Capsule creation
  • Time-lock enforcement
  • Retrieval mechanics
  • Edge cases and error conditions

Example Usage

// Deploy contract
const TimeCapsule = await ethers.getContractFactory("TimeCapsule");
const timeCapsule = await TimeCapsule.deploy();
await timeCapsule.deployed();

// Create a capsule
const lockTime = 3600; // 1 hour in seconds
const message = "Message from 2025!";
await timeCapsule.createCapsule(message, lockTime);

// Retrieve after lock period
await timeCapsule.retrieveCapsule();

Events

The contract emits events for important actions:

  • CapsuleCreated(address indexed sender, uint256 unlockTime)
  • CapsuleRetrieved(address indexed sender, string message)

Gas Optimization

The contract is optimized for gas efficiency:

  • Uses mapping for O(1) access
  • Implements struct packing
  • Minimizes storage operations
  • Uses calldata for string inputs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Created with 💙 by Gautam Manchandani(me🙋‍♂️)

Feel free to connect with me on GitHub