Build a Lottery Smart Contract with Chainlink VRF: A Technical Guide

Overview

In this article, we will be exploring how to create a lottery smart contract using Chainlink VRF (Verifiable Random Function) random numbers. Chainlink VRF is a secure and reliable way to generate random numbers on the blockchain, making it ideal for use in lotteries and other games of chance.

By using Chainlink VRF, we can ensure that our lottery is fair and tamper-proof, giving players the confidence to participate and the assurance that the results are unbiased. We will walk through the steps of building a lottery smart contract using Chainlink VRF, and by the end of the tutorial, you will have a fully functional lottery smart contract that you can use as a template for your own projects.

You can find the entire code for the contract in the GitHub Repository

https://github.com/Envoy-VC/Smart-Contracts

Prerequisites

Before you begin with this tutorial make sure you are comfortable with the following:

Basic knowledge of Solidity and the Ethereum blockchain
Experience with compiling and deploying contracts using Remix IDE
Passion for building cool things

Before starting to build the actual Lottery Contract let's take a look at Chainlink VRF and set up the needed stuff to use it in our Contract

Create a Chainlink VRF Subscription

Chainlink VRF is a powerful tool for generating random numbers on the blockchain, and it offers two methods for requesting randomness: subscription and direct funding. In this article, we'll focus on the subscription method, which allows you to fund requests for multiple consumer contracts from a single subscription account.

To create a Chainlink VRF subscription, you'll need to follow a few simple steps.

Step 1 - Creating a Subscription

To create a subscription for Chainlink VRF, follow these steps:

Navigate to the subscription manager page at https://vrf.chain.link and connect your Metamask wallet. Ensure that your wallet is set to the Sepolia testnet.
Click on the "Create Subscription" button and fill in the required details. Once you have entered the necessary information, click on "Create Subscription" again.
You will be prompted to approve the transaction on Metamask. Approve the transaction and wait until it is confirmed on the chain.

Step 2 - Fund your Subscription

To fund your subscription and obtain random numbers, you will need to pay LINK tokens. To obtain testnet LINK tokens, visit https://faucets.chain.link/sepolia.

After obtaining LINK tokens, return to your subscription dashboard and click on the "Fund Subscription" button located under the "Actions" dropdown in the top right corner of the page. Enter the number of LINK tokens you wish to fund in the input box and click on "Confirm". You will then be prompted with a Metamask popup. Click on "Approve" to complete the transaction.

That's It. We have successfully created a subscription to get Random Numbers, now we can move to the smart contract.

Create Lottery Contract

Initializing Contract

To begin creating the lottery smart contract, we need to specify the license of the contract, and the pragma version, and import the necessary modules.

We will be using the Strings module from @openzeppelin/contracts to provide custom error messages, and the VRFConsumerBaseV2 and VRFCoordinatorV2Interface modules from @chainlink/contracts to implement random number functionality.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.14;

import "@openzeppelin/contracts/utils/Strings.sol";
import "@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol";
import "@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol";

Next, we will create a contract called Lottery that will inherit from VRFConsumerBaseV2.

contract Lottery is VRFConsumerBaseV2 {
    // Code...
}

State Variables

To pass on the configuration to the VRFConsumerBaseV2 contract, we need to declare some state variables.

VRFCoordinatorV2Interface COORDINATOR;
uint64 subscriptionId;
address vrfCoordinator = 0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625;
bytes32 keyHash =
    0x474e34a077df58807dbe9c96d3c009b23b3c6d0cce433e59bbf5b34f823bc56c;
uint32 callbackGasLimit = 100000;
uint16 requestConfirmations = 3;
uint32 numWords = 1;

uint256 public lotteryCount = 0;

Here is what each variable does:

COORDINATOR - This is the contract address that we will use to request randomness.
subscriptionId - This is the subscription ID that this contract uses for funding requests.
vrfCoordinator - This is the address of the coordinator on the Sepolia testnet.
keyHash - This is the gas lane key hash value, which functions as an ID of the off-chain VRF job that runs in response to requests.
callbackGasLimit - This is the limit for how much gas to use for the callback request to your contract's function.
requestConfirmations - This is how many confirmations the Chainlink node should wait before responding. The longer the node waits, the more secure the random value is.
numWords - This is how many random values to request. If you can use several random values in a single callback, you can reduce the amount of gas that you spend per random value.
lotteryCount - This is the variable that keeps track of the total lotteries.

To keep track of the data for the lottery, we need to create some structures and mappings.

struct LotteryData {
        address lotteryOperator;
        uint256 ticketPrice;
        uint256 maxTickets;
        uint256 operatorCommissionPercentage;
        uint256 expiration;
        address lotteryWinner;
        address[] tickets;
}

struct LotteryStatus {
    uint256 lotteryId;
    bool fulfilled;
    bool exists;
    uint256[] randomNumber;
}

mapping(uint256 => LotteryData) public lottery;
mapping(uint256 => LotteryStatus) public requests;

Here is what each structure and mapping does:

LotteryData struct - This structure keeps a record of the lotteryOperator, which is the address that can start and end a lottery, ticketPrice, which is the price of each ticket, maxTickets, which is the maximum number of tickets, operatorCommissionPercentage, which is a percentage of the total pool that is sent to the operator, expiration, which is the time when the lottery ends, lotteryWinner, which is the address of the winner, and tickets, which stores all the tickets for the lottery.
LotteryStatus struct - This structure keeps track of the request sent to the VRFCoordinator after the lottery is ended. It stores some states like the request fulfilled status and the randomNumber.
lottery mapping - This mapping maps lotteryCount to the LotteryData struct.
requests mapping - This mapping maps to LotteryStatus.

Constructor

The constructor function is used to initialize the Lottery contract. It takes in a subscriptionId as a parameter, which is used to fund requests for random numbers.

Inside the constructor function, the COORDINATOR variable is set to an instance of the VRFCoordinatorV2Interface contract using the vrfCoordinator address. The subscriptionId variable is set to the _subscriptionId parameter passed to the function.

constructor(uint64 _subscriptionId) VRFConsumerBaseV2(vrfCoordinator) {
    COORDINATOR = VRFCoordinatorV2Interface(vrfCoordinator);
    subscriptionId = _subscriptionId;
}

Events

The Lottery contract has several events that are emitted during different stages of the lottery process.

event LotteryCreated(
    address lotteryOperator,
    uint256 ticketPrice,
    uint256 maxTickets,
    uint256 operatorCommissionPercentage,
    uint256 expiration
);

event LogTicketCommission(
    uint256 lotteryId,
    address lotteryOperator,
    uint256 amount
);

event TicketsBought(
    address buyer,
    uint256 lotteryId,
    uint256 ticketsBought
);

event LotteryWinnerRequestSent(
    uint256 lotteryId,
    uint256 requestId,
    uint32 numWords
);

event RequestFulfilled(uint256 requestId, uint256[] randomWords);

event LotteryWinnerDrawn(uint256 lotteryId, address lotteryWinner);

event LotteryClaimed(
    uint256 lotteryId,
    address lotteryWinner,
    uint256 amount
);

Here is what each event does:

LotteryCreated - This event is emitted when a new lottery is created. It includes information about the lotteryOperator, ticketPrice, maxTickets, operatorCommissionPercentage, and expiration.
LogTicketCommission - This event is emitted when lottery commission is sent to the operator. It includes information about the lotteryId, lotteryOperator, and amount.
TicketsBought - This event is emitted when a user buys tickets. It includes information about the buyer, lotteryId, and ticketsBought.
LotteryWinnerRequestSent - This event is emitted when a random number request is sent to Chainlink VRF. It includes information about the lotteryId, requestId, and numWords.
RequestFulfilled - This event is emitted when a random number request is fulfilled by Chainlink VRF. It includes information about the requestId and randomWords.
LotteryWinnerDrawn - This event is emitted when a lottery winner is drawn. It includes information about the lotteryId and lotteryWinner.
LotteryClaimed - This event is emitted when a lottery winner claims their prize. It includes information about the lotteryId, lotteryWinner, and amount.

Modifiers

The Lottery contract has two modifiers that are used to restrict access to certain functions.

modifier onlyOperator(uint256 _lotteryId) {
    require(
        (msg.sender == lottery[_lotteryId].lotteryOperator),
        "Error: Caller is not the lottery operator"
    );
    _;
}

modifier canClaimLottery(uint256 _lotteryId) {
    require(
        (lottery[_lotteryId].lotteryWinner != address(0x0)),
        "Error: Lottery Winner not yet drawn"
    );
    require(
        (msg.sender == lottery[_lotteryId].lotteryWinner ||
            msg.sender == lottery[_lotteryId].lotteryOperator),
        "Error: Caller is not the lottery winner"
    );
    _;
}

Here is what each modifier does:

onlyOperator - This modifier restricts access to functions that can only be called by the lotteryOperator. It takes in a _lotteryId parameter to ensure that the caller is the operator of the specified lottery. If the caller is not the operator, an error message is returned.
canClaimLottery - This modifier restricts access to functions that can only be called by the lotteryWinner or lotteryOperator after the winner has been drawn. It takes in a _lotteryId parameter to ensure that the caller is either the winner or the operator of the specified lottery. If the winner has not been drawn yet or the caller is not the winner or operator, an error message is returned.

Read Functions

The Lottery contract has a read function called getRemainingTickets that returns the number of remaining tickets for a specified lottery.

function getRemainingTickets(uint256 _lotteryId) public view returns (uint256) {
    return lottery[_lotteryId].maxTickets - lottery[_lotteryId].tickets.length;
}