Automated Provably Fair Raffle

A decentralized, autonomous gaming protocol secured by Cryptographic Randomness.
Powered by Chainlink VRF for fairness and Chainlink Automation for self-execution.

   

• 🧠 Executive Summary
• 🏗 System Architecture
• ⚙️ Core Logic & Modules
• 💎 Key Features
• 🛡 Security & Testing
• 🛠 Development Workflow
• 💡 Use Cases

The Raffle Protocol is a robust smart contract system designed to eliminate trust from online gaming. Unlike traditional lotteries where the "house" controls the draw and holds custody of funds, this protocol is:

1. Immutable: The rules are codified on-chain and cannot be altered by an admin.
2. Autonomous: Chainlink Automation triggers the draw based on time intervals, removing manual intervention.
3. Provably Fair: Winners are selected using Verifiable Random Functions (VRF), making the outcome mathematically tamper-proof.

The system operates as a finite State Machine (OPEN $\rightarrow$ CALCULATING $\rightarrow$ OPEN), ensuring atomic transitions and preventing new entries during the critical random number generation phase.

[Image of System Architecture Diagram]

graph TD
    User((👤 User))
    Automation{🤖 Chainlink Automation}
    VRF{🎲 Chainlink VRF}
    
    subgraph "Raffle Protocol"
        State[State: OPEN]
        Check[checkUpkeep]
        Perform[performUpkeep]
        Fulfill[fulfillRandomWords]
    end

    User -- 1. Enter Raffle (ETH) --> State
    Automation -- 2. Trigger Time Check --> Check
    Check -- True --> Perform
    Perform -- 3. Request Randomness --> VRF
    VRF -- 4. Return Random Words --> Fulfill
    Fulfill -- 5. Pick Winner & Payout --> User
    
    style User fill:#1a1a1a,stroke:#b298dc
    style Automation fill:#1a1a1a,stroke:#fff
    style VRF fill:#1a1a1a,stroke:#9d4edd
    style State fill:#2d1b4e,stroke:#9d4edd,stroke-width:2px

The repository is structured for modularity and environment-agnostic deployment (Local vs Testnet).

src/
├── Raffle.sol              // [CORE] Main Lottery Logic & State Machine
script/
├── DeployRaffle.s.sol      // [OPS] Deployment with Config Injection
├── HelperConfig.s.sol      // [CONF] Multi-chain Config (Sepolia/Anvil)
└── Interactions.s.sol      // [UTILS] Subscription Management
test/
├── unit/                   // Isolated State Tests
└── fuzz/                   // Stateless Edge-Case Testing

The project employs a Test-Driven Development (TDD) approach with a comprehensive Foundry suite.

1. Unit Tests: Validate entrance fees, state transitions, and array recording.
2. Mock Simulation: Uses VRFCoordinatorV2Mock to simulate random number generation locally on Anvil.
3. Fuzz Testing: Random input generation to ensure the contract handles unexpected data (e.g., 0 fees, massive arrays).
4. Invariant Analysis: Ensures contract balance == players * fee at all times during the OPEN state.

• Checks-Effects-Interactions (CEI): State is updated before external calls (ETH transfer) to prevent reentrancy attacks.
• Atomic Transitions: The contract locks immediately upon requesting randomness, ensuring no "sniping" or front-running occurs.

This project utilizes a Makefile to streamline the development process.

This architecture serves as a foundational blueprint for broader Web3 applications:

• 🎟️ NFT Whitelisting: Fairly selecting users for high-demand mints.
• 🗳️ DAO Governance: Randomly selecting a sub-committee for dispute resolution.
• 🎁 Reward Distribution: Automated weekly airdrops to community members.
• 🎮 GameFi Mechanics: Critical hit calculations or loot box openings.