Decentralised Raffle

A decentralized, verifiable, and automated lottery (raffle) smart contract system built with Foundry and Chainlink VRF v2.5. This project demonstrates how to create a secure, fair, and upgradeable raffle contract using modern Solidity best practices and robust testing.

Features

• Decentralised Raffle: Anyone can enter by paying the entrance fee.
• Chainlink VRF Integration: Uses verifiable randomness for winner selection.
• Chainlink Automation (Upkeep): Supports time-based automated raffle execution.
• Comprehensive Testing: Includes unit and integration tests using Foundry cheatcodes and mocks.

Directory Structure

|-- src/
│   |-- Raffle.sol           # Main Raffle contract
|-- script/
│   |-- DeployRaffle.s.sol   # Deployment script
│   |-- HelperConfig.s.sol   # Network config helper
│   |-- Interactions.s.sol   # Interaction scripts
|-- test/
│   |-- unit/                # Unit tests
│   │   |-- RaffleTest.t.sol
│   |-- integration/         # Integration tests
│   |-- mocks/               # Mock contracts (e.g., LinkToken)
|-- lib/                     # External dependencies (Chainlink, Forge Std, etc.)
|-- foundry.toml             # Foundry config
|-- Makefile                 # make commands
|-- README.md                # Project documentation

Getting Started

Prerequisites

• Foundry
• Chainlink VRF
• Chainlink Automation

Installation

git clone https://github.com/YOUR_GITHUB_USERNAME/foundry-chainlink-raffle.git
cd foundry-chainlink-raffle
forge install

Running Tests

forge test

Deploying Locally

forge script script/DeployRaffle.s.sol --broadcast

Deploying to Sepolia Testnet

1. Set up your .env with SEPOLIA_RPC_URL.

2. Make sure your signing wallet has sufficient Sepolia ETH and Sepolia LINK tokens to pay for the deployment and Chainlink subscription costs. You may obtain Sepolia ETH and Sepolia LINK tokens from the Chainlink Faucet.

3. Set your funded wallet address in the account property of the HelperConfig.s.sol. This wallet will be signing all the deployment transactions.

4. Run:

   forge script script/DeployRaffle.s.sol --rpc-url $SEPOLIA_RPC_URL --broadcast
   # A more secure way to do this is by storing your private key in a local keystore by using the `cast wallet import` command and then using the keystore name in the above command this way:
   forge script script/DeployRaffle.s.sol --rpc-url $SEPOLIA_RPC_URL --account your_keystore_name --broadcast

How It Works

• Users enter the raffle by calling the enterRaffle() function with the required entranceFee in ETH, defined in HelperConfig.s.sol.
• After a set interval, defined in Chainlink Automation settings, the winner selection can be triggered.
• It starts with the Chainlink Automation process calling the checkUpkeep function. If that returns true, then the performUpkeep function is called.
• The performUpkeep function requests a random number from Chainlink VRF via the VRF Coordinator Contract's requestRandomWords function.
• Chainlink Nodes generate a Random number off-chain and submit the random value and proof back to the VRF Coordinator contract on-chain.
• The VRF Coordinator contract verifies the cryptographic proof to ensure the randomness is valid.
• If valid, the Coordinator calls the consumer contract’s fulfillRandomWords function, which is the callback function that must be implemented in the Consumer contract to receive the random number.

Security

• Uses Chainlink VRF for provable randomness.
• Follows Checks-Effects-Interactions pattern.
• Includes custom errors and revert conditions.

Usage

• You may choose to Create a Chainlink subscription manually using the website and mention it in HelperConfig.s.sol OR let it be created and get funded automatically by the DeployRaffle.s.sol script at runtime.

  Note: Each of these steps: Subscription creation, Subscription funding, and Adding the Raffle Contract as a consumer are all done automatically by the DeployRaffle script, however, createSubscriptionUsingConfig, fundSubscriptionUsingConfig and addConsumerUsingConfig functions defined in Interactions.s.sol can also be executed using the forge script command. If doing it all manually, make sure to deploy the Raffle contract and use it's address as the Consumer Contract address in Chainlink.

• Next is automating the raffle execution, for this register a new Time based Upkeep and mention the Raffle Contract's address and ABI in the registration form.

• You may call the enterRaffle function from multiple wallets having the required Sepolia ETH, to make them enter the raffle. After the defined interval in the Upkeep the raffle is triggered and a winner is picked. The history of this triggering operation can be viewed on Chainlink's Automation dashboard.

License

MIT

Acknowledgements

• Foundry
• Chainlink