Provably Fair Raffle Smart Contract

A decentralized, provably fair lottery system built with Solidity and Foundry, leveraging Chainlink VRF for verifiable randomness and Chainlink Automation for automated winner selection.

Table of Contents

• Provably Fair Raffle Smart Contract
  • Table of Contents
  • Overview
  • Features
  • Technology Stack
  • Getting Started
    • Prerequisites
    • Installation
  • Usage
    • Deploy
    • Testing
    • Interact
  • How It Works
  • Smart Contract Functions
    • Main Functions
    • View Functions
  • Configuration
  • Project Structure
  • Security Considerations
  • Gas Optimization
  • Author
  • Acknowledgments
  • License
  • Resources
  • Contributing
    • Built as part of the Cyfrin Foundry Solidity Course

Overview

This project implements a transparent and trustless raffle/lottery system on the blockchain where:

• Users can enter by paying an entrance fee
• Winners are selected randomly using Chainlink VRF (Verifiable Random Function)
• Winner selection is automated using Chainlink Automation (formerly Keepers)
• The entire prize pool is automatically transferred to the winner

Features

• Provably Fair Randomness: Utilizes Chainlink VRF V2 to generate verifiable random numbers for winner selection
• Automated Execution: Chainlink Automation triggers winner selection at predetermined intervals
• Transparent & Trustless: All logic is on-chain and verifiable
• Gas Optimized: Built with best practices for gas efficiency
• Comprehensive Testing: Includes unit tests, integration tests, and fork tests

Technology Stack

• Solidity - Smart contract programming language
• Foundry - Development framework and testing suite
• Chainlink VRF V2 - Verifiable random number generation
• Chainlink Automation - Decentralized automation network

Getting Started

Prerequisites

• Git
• Foundry

Installation

1. Clone the repository

git clone https://github.com/BuildsWithKing/raffle-contract
cd raffle-contract

2. Install dependencies

make install

3. Build the project

make build

Usage

Deploy

Deploy to Sepolia testnet:

make deploy-sepolia

Testing

Run all tests:

make test

Run tests with verbosity:

make test -vvv

Run specific test:

forge test --match-test testFunctionName

Test coverage:

make coverage

Interact

Enter the raffle:

cast send <RAFFLE_ADDRESS> "enterRaffle()" --value 0.01ether --rpc-url $SEPOLIA_RPC_URL --account myaccount

Check raffle state:

cast call <RAFFLE_ADDRESS> "getRaffleState()" --rpc-url $SEPOLIA_RPC_URL

How It Works

1. Entry Phase: Users call enterRaffle() and pay the entrance fee. Their addresses are stored in an array.

2. Upkeep Check: Chainlink Automation nodes continuously call checkUpkeep() to determine if it's time to pick a winner based on:

   • Time interval has passed
   • Raffle is in OPEN state
   • Contract has ETH balance (at least two player)
   • Subscription is funded with LINK

3. Winner Selection: When conditions are met, performUpkeep() is called:

   • Raffle state changes to CALCULATING
   • Request is sent to Chainlink VRF for random number

4. Fulfillment: Chainlink VRF calls fulfillRandomWords():

   • Random winner is selected using modulo operation
   • Prize pool is transferred to winner
   • Raffle resets for next round

Smart Contract Functions

Main Functions

• enterRaffle() - Enter the lottery by paying entrance fee
• checkUpkeep() - Check if conditions are met for winner selection
• performUpkeep() - Trigger the winner selection process
• fulfillRandomWords() - Callback function for Chainlink VRF

View Functions

• getEntranceFee() - Get the entrance fee amount
• getRaffleState() - Get current raffle state (OPEN/CALCULATING)
• getPlayer(uint256) - Get player address at index
• getRecentWinner() - Get the most recent winner

Configuration

Create a .env file with the following variables:

SEPOLIA_RPC_URL=your_sepolia_rpc_url
ETHERSCAN_API_KEY=your_etherscan_api_key

Project Structure

    ├── script
    │   ├── DeployRaffle.s.sol
    │   ├── HelperConfig.s.sol
    │   └── Interaction.s.sol
    ├── src
    │   └── Raffle.sol
    └── test
        ├── integration
        │   └── IntegrationTest.t.sol
        ├── mocks
        │   └── LinkToken.sol
        └── unit
            └── RaffleTest.t.sol
        ├── foundry.toml
        └── README.md

Security Considerations

• Uses Chainlink VRF for cryptographically secure randomness
• Implements checks-effects-interactions pattern
• State changes before external calls to prevent reentrancy
• Comprehensive test coverage
• Audited Chainlink contracts

Gas Optimization

• Uses custom errors instead of require strings
• Efficient storage patterns
• Optimized loops and array operations

Author

Michealking

• GitHub: @BuildsWithKing
• Twitter: @BuildsWithKing
• Discord: @BuildsWithKing

Acknowledgments

• Cyfrin Updraft - Foundry Solidity Course
• Patrick Collins - Course instructor
• Chainlink - VRF and Automation services

License

This project is licensed under the MIT License.

Resources

• Foundry Book
• Chainlink VRF Documentation
• Chainlink Automation Documentation
• Cyfrin Updraft Course

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

---

Built as part of the Cyfrin Foundry Solidity Course