-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
96 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,105 +1,139 @@ | ||
| # Raffle Smart Contract | ||
| # A Fair Smart Contract Raffle | ||
|
|
||
| A decentralized and automated raffle system built on blockchain technology, utilizing Chainlink VRF for verifiable randomness and Chainlink Automation for trustless execution. | ||
|
|
||
| ## Overview | ||
|
|
||
| **Raffle** is a smart contract designed to create a decentralized raffle system on the Ethereum blockchain. It utilizes Chainlink's Verifiable Random Function (VRF) to ensure fair and random winner selection. This project is built using the Foundry toolkit, which provides a fast and modular environment for Ethereum application development. | ||
| This project implements a fully automated raffle system where: | ||
| - Users can enter by paying a set entrance fee | ||
| - A winner is automatically and fairly selected at regular intervals | ||
| - Uses Chainlink VRF (Verifiable Random Function) for provably fair winner selection | ||
| - Leverages Chainlink Automation for automatic draws | ||
| - Implements a robust testing suite | ||
|
|
||
| ## Table of Contents | ||
| ## Features | ||
|
|
||
| - [Features](#features) | ||
| - [Installation](#installation) | ||
| - [Usage](#usage) | ||
| - [Contract Structure](#contract-structure) | ||
| - [Testing](#testing) | ||
| - [Contributing](#contributing) | ||
| - [License](#license) | ||
| - **Fair Entry System**: Fixed entrance fee required to participate | ||
| - **Automated Execution**: No manual intervention needed for picking winners | ||
| - **Verifiable Randomness**: Chainlink VRF v2.5 ensures provably fair winner selection | ||
| - **Time-Based Draws**: Configurable intervals between raffles | ||
| - **Transparent**: Fully verifiable on-chain logic | ||
| - **State Management**: Proper handling of raffle states (OPEN and CALCULATING) | ||
| - **Gas Efficient**: Optimized for minimal gas consumption | ||
|
|
||
| ## Features | ||
| ## Technical Details | ||
|
|
||
| - **Decentralized Raffle**: Participants can enter the raffle by sending Ether. | ||
| - **Random Winner Selection**: Uses Chainlink VRF for secure and verifiable randomness. | ||
| - **Event Logging**: Emits events for key actions like entering the raffle and picking a winner. | ||
| - **Easy Deployment**: Simple deployment scripts included. | ||
| ### Contract Architecture | ||
|
|
||
| ## Installation | ||
| The project consists of several key contracts: | ||
|
|
||
| To get started with the Raffle smart contract, follow these steps: | ||
| - `Raffle.sol`: Main contract implementing the raffle logic | ||
| - `DeployRaffle.s.sol`: Script for deploying the raffle | ||
| - `HelperConfig.s.sol`: Configuration management for different networks | ||
| - `Interactions.s.sol`: Helper scripts for contract interactions | ||
|
|
||
| 1. **Clone the repository**: | ||
| ```bash | ||
| git clone https://github.com/yourusername/raffle.git | ||
| cd raffle | ||
| ``` | ||
| ### Key Dependencies | ||
|
|
||
| 2. **Initialize submodules**: | ||
| ```bash | ||
| git submodule update --init --recursive | ||
| ``` | ||
| - Solidity ^0.8.19 | ||
| - Chainlink VRF V2.5 | ||
| - Forge/Foundry for testing and deployment | ||
| - Solmate for optimized contract implementations | ||
|
|
||
| 3. **Install Foundry**: | ||
| Ensure you have Foundry installed. If not, you can install it by following the instructions on the [Foundry documentation](https://book.getfoundry.sh/). | ||
| ### Testing | ||
|
|
||
| 4. **Install dependencies**: | ||
| ```bash | ||
| forge install | ||
| ``` | ||
| Comprehensive test suite available in `test/unit/RaffleTest.t.sol`, covering: | ||
| - Initialization states | ||
| - Entry conditions | ||
| - Player recording | ||
| - Event emissions | ||
| - State transitions | ||
| - Upkeep checks | ||
| - Winner selection | ||
|
|
||
| ## Usage | ||
| ## Getting Started | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - Foundry installed | ||
| - Node.js and npm (for additional tooling) | ||
| - An RPC URL for deployment | ||
| - LINK tokens for VRF funding (on mainnet/testnet) | ||
|
|
||
| ### Build the Contract | ||
| ### Installation | ||
|
|
||
| To compile the smart contract, run: | ||
| 1. Clone the repository: | ||
| ```bash | ||
| forge build | ||
| git clone <your-repo-url> | ||
| cd raffle-contract | ||
| ``` | ||
|
|
||
| ### Run Tests | ||
| 2. Install dependencies: | ||
| ```bash | ||
| forge install | ||
| ``` | ||
|
|
||
| To execute the tests, use: | ||
| 3. Compile contracts: | ||
| ```bash | ||
| forge build | ||
| ``` | ||
|
|
||
| 4. Run tests: | ||
| ```bash | ||
| forge test | ||
| ``` | ||
|
|
||
| ### Deploy the Contract | ||
| ### Deployment | ||
|
|
||
| 1. Set up your environment variables: | ||
| ```bash | ||
| cp .env.example .env | ||
| # Fill in your environment variables | ||
| ``` | ||
|
|
||
| To deploy the contract, you can use the following command: | ||
| 2. Deploy to a network: | ||
| ```bash | ||
| forge script script/DeployRaffle.s.sol:DeployRaffle --rpc-url <your_rpc_url> --private-key <your_private_key> | ||
| forge script script/DeployRaffle.s.sol --rpc-url <your_rpc_url> --private-key <your_private_key> | ||
| ``` | ||
|
|
||
| ### Enter the Raffle | ||
| ## Usage | ||
|
|
||
| ### Entering the Raffle | ||
|
|
||
| Participants can enter the raffle by sending Ether to the `enterRaffle` function. Ensure that the amount sent is greater than or equal to the entrance fee. | ||
| Users can enter the raffle by calling the `enterRaffle()` function with the required entrance fee: | ||
|
|
||
| ## Contract Structure | ||
| ```solidity | ||
| raffle.enterRaffle{value: entranceFee}() | ||
| ``` | ||
|
|
||
| The Raffle contract is structured as follows: | ||
| ### Checking Raffle Status | ||
|
|
||
| - **State Variables**: Holds the entrance fee, players, and raffle state. | ||
| - **Functions**: | ||
| - `enterRaffle()`: Allows users to enter the raffle. | ||
| - `checkUpKeep()`: Checks if the conditions to pick a winner are met. | ||
| - `performUpkeep()`: Executes the winner selection process. | ||
| - `fulfillRandomWords()`: Handles the random number returned by Chainlink VRF. | ||
| Several view functions are available: | ||
| - `getEntranceFee()`: Get the required entrance fee | ||
| - `getRaffleState()`: Check if raffle is OPEN or CALCULATING | ||
| - `getPlayer(uint256 index)`: Get player at specific index | ||
| - `getNumberOfPlayers()`: Get total number of players | ||
|
|
||
| ## Testing | ||
| ## Security Considerations | ||
|
|
||
| 1. Write Deploy scripts | ||
| 1. Note, these deploy scripts will not work on zkSync. | ||
| 2. Write tests | ||
| 1. Local Chain | ||
| 2. Forked Testnet | ||
| 3. Forked Mainnet | ||
| - Implements CEI (Checks-Effects-Interactions) pattern | ||
| - Uses custom errors for gas efficiency | ||
| - Proper access control mechanisms | ||
| - Comprehensive error handling | ||
| - VRF v2.5 for secure randomness | ||
|
|
||
| ## Contributing | ||
|
|
||
| Contributions are welcome! Please fork the repository and submit a pull request with your changes. | ||
| Contributions are welcome! Please feel free to submit a Pull Request. | ||
|
|
||
| ## License | ||
|
|
||
| This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. | ||
| This project is licensed under the MIT License - see the LICENSE file for details. | ||
|
|
||
| ## Author | ||
|
|
||
| Saksham Gupta | ||
|
|
||
| ## Acknowledgments | ||
|
|
||
| - [Foundry](https://book.getfoundry.sh/) for the development toolkit. | ||
| - [Chainlink](https://chain.link/) for the VRF service. | ||
| - Chainlink VRF team for randomness solution | ||
| - Foundry team for development framework |