Overview

This guide explains how to participate in the Single Entry Raffle, a decentralized lottery application built on the Ethereum blockchain. You will learn how to use the user interface (UI) to enter the raffle, check the status, and understand how the smart contract ensures fairness and transparency.

Note on Testnet

All transactions in this guide use Sepolia ETH, a testnet currency. I refer to it as 'ETH' for simplicity, but no real funds are used.

What is the Raffle?

The Raffle is a lottery where users send a small amount of ETH (the entry fee) to participate. After a predefined time interval, the contract automatically picks one winner in a verifiable and fair way using Chainlink VRF and sends the entire balance in the contract to the winner. This version of the raffle only allows one entry per wallet.

How to participate

1. Connect your wallet on the correct network.
2. Check the entry fee displayed.
3. Click 'Enter Raffle' and confirm the transaction sending at least the entry fee. You can only enter once per wallet per raffle.
4. Wait for the draw: after the interval, Automation checks and triggers the process.
5. If you win, the contract transfers the prize to your wallet and restarts the raffle.

Tips

Track status in the UI: number of participants, last winner, and time remaining. Each entry adds your address to the player list for the next draw.

Connecting Your Wallet

To interact with the raffle, you need to connect a web3 wallet (e.g., MetaMask). Click the 'Connect Wallet' button in the top right corner of the application and approve the connection in your wallet.

The Raffle Card

The main raffle card displays all the important information about the current raffle round. You will find the current entry fee, the total number of participants, the time remaining until the next draw, and the most recent winner.

Entering the Raffle

1. Once your wallet is connected, you can enter the raffle by clicking the 'Enter Raffle' button on the raffle card.
2. A transaction will be initiated in your wallet. You need to confirm the transaction and send the specified entry fee.
3. Important: This is a single-entry raffle, so you can only enter once per wallet for each round. If you try to enter more than once, the transaction will be reverted.

Leaderboard

The leaderboard shows the top winners of the raffle. You can see the addresses of the winners and the amount they have won.

Wallet History

The wallet history side panel shows your past raffle entries and winnings.

How It Works

The UI interacts with the `SingleEntryRaffle.sol` smart contract deployed on the Sepolia testnet. All actions, such as entering the raffle and drawing a winner, are executed through this contract.

Winner Selection

The winner is selected in a provably fair and random manner using Chainlink VRF (Verifiable Random Function). When the raffle interval ends, Chainlink Automation triggers the `performUpkeep` function in the contract, which in turn requests a random number from the VRF. The `fulfillRandomWords` function then uses this random number to select a winner from the list of participants.

Key Contract Functions

1. `enterRaffle()`: This function is called when you click the 'Enter Raffle' button. It registers you as a participant and transfers the entry fee to the contract.
2. `checkUpkeep()`: This function is called by Chainlink Automation to check if the conditions for a new draw are met.
3. `performUpkeep()`: This function initiates the process of requesting a random number from Chainlink VRF.
4. `fulfillRandomWords()`: This function receives the random number and selects the winner.
5. `getPlayerHasEntered(address player)`: This function allows the UI to check if a player has already entered the current raffle round.

How the winner is chosen

Users enter via `enterRaffle()` by sending ETH ≥ entry fee. Periodically, `checkUpkeep` validates conditions. If true, `performUpkeep` requests a random number from Chainlink VRF. When VRF responds, `fulfillRandomWords()` picks the winner index, stores the recent winner, resets players and timer, and transfers the balance.

Contract states

OPEN: open for new entries. CALCULATING: entries are blocked while awaiting and processing VRF randomness.

Useful events

`RaffleEntered(address player)`: emitted on entry. `RequestRaffleWinner(uint256 requestId)`: emitted when requesting randomness. `WinnerPicked(address player)`: emitted when the winner is determined.

Costs and limits

You pay the entry fee and gas. The contract uses a callback gas limit for VRF. Network parameters such as `keyHash` and `subscriptionId` are configured at deploy.

Useful view functions

1. `getEntranceFee()`: minimum entry fee.
2. `getInterval()`: interval between draws.
3. `getNumberOfPlayers()`: participants in the current round.
4. `getRecentWinner()`: the last winner.
5. `getRaffleState()`: current state (open or calculating).
6. `getPlayerHasEntered(address player)`: returns true if the player has entered in the current round.

Where to verify the contract

View on Etherscan (placeholder). Replace with the correct address after deployment.

Useful links

1. Chainlink VRF 2.5
2. Chainlink Automation
3. Solidity docs
4. CEI pattern

FAQ

1. Can I enter multiple times? No, in this version of the raffle you can only enter once per round.
2. What if I try to enter while it’s calculating? The transaction will revert.
3. Who pays for VRF? The subscription is configured per network.