VRF-Enabled LootBox/Pack Contract

Overview

The lootbox utility contract uses Chainlink VRF to determine a random reward that you can distribute as a Loot Box to users. This allows you to issue rewards fairly and transparently using verified randomness that the recipients can verify onchain.

Objective

This tutorial demonstrates how to create a reward distribution dApp to distribute in-game rewards to players. In this tutorial, you will use example code from the smartcontractkit/quickstarts-lootbox repository. You will configure the example to work on a testnet of your choice, use an RPC endpoint of your choice, and distribute in-game rewards to players by using a lootbox contract. This example uses the HardHat framework to help you complete the testing and deployment steps.

This example contract supports distributing any rewards that adhere to fungible, non-fungible, and other configuration standards. For example, you can create a set of in-game rewards, transfer them to the lootbox contract when you deploy it, and then the lootbox contract manages in-game reward distributions.

Before you begin

Before you start this tutorial, complete the following items:

• Install git
  • Run git --version to check the installation. You should see an output similar to git version x.x.x.
• Install Nodejs 16.0.0 or higher
  • Run node --version to check the installation. You should see an output similar to v16.x.x.
  • Optionally, you can also Install Yarn and use it to run this example instead of using npm.
• Create an Etherscan API key if you do not already have one.
• Create an account with Infura or Alchemy to use as an RPC endpoint if you do not already have one. Alternatively, you can use your own testnet clients.

Your deployer account is the main account that you will use to deploy the lootbox contract, distribute rewards, pay for transaction fees, and pay for VRF costs. This is also the owner account.

• Ensure the deployer account owns all the assets you wish to distribute as rewards.

• To deploy this contract on testnets, ensure the deployer account has testnet LINK and testnet ETH (Sepolia). Use the LINK faucet to retrieve 20 testnet LINK and 0.1 Sepolia ETH.

• Ensure the deployer account has enough LINK to fund the VRF subscription. If you don't already have a VRF subscription, the deployment script will create and fund one for you.

  • Estimate the minimum subscription balance that VRF requires to process your randomness request. The minimum subscription balance provides a buffer against gas volatility, and only the actual cost of your request will be deducted from your account. If your subscription is underfunded, your VRF request will be pending for 24 hours. If that happens, check the Subscription Manager to see the additional balance needed.
  • The initial funding amount is set to 10 LINK. Optionally, you can modify the initial funding amount in network-config.ts.

• Create a second account in your MetaMask wallet. This account is called the receiving account in this tutorial, and its address is called the opener address. You will use this receiving account to open a test lootbox and receive the rewards as a user. Configure the account to display the rewards that you want to distribute from the lootbox.

Steps to implement

git clone git@github.com:smartcontractkit/quickstarts-lootbox.git && \
cd quickstarts-lootbox && \
npm install

git clone git@github.com:smartcontractkit/quickstarts-lootbox.git && \
cd quickstarts-lootbox && \
yarn install

cp .env.example .env

{
  "tokenType": "ERC20",
  "assetContract": "0x0000000000000000000000000000000000000001",
  "totalAmount": "100000000000000000000",
  "amountPerUnit": "10000000"
}

{
  "tokenType": "ERC721",
  "assetContract": "0x0000000000000000000000000000000000000002",
  "tokenIds": ["1", "2"]
}

{
  "tokenType": "ERC1155",
  "assetContract": "0x0000000000000000000000000000000000000003",
  "tokenId": "0",
  "totalAmount": "100",
  "amountPerUnit": "10"
}

npx hardhat run scripts/deploy.ts --network <network>

Reference

Access control

You can control access to the lootbox with two modes: private and public. Use these modes to determine which users can open the lootbox. The owner account can update this setting after deployment, so you can test the opening functionality privately before making the lootbox available to the public.

Private mode

In this mode, the lootbox is only open to addresses on the allowlist by calling the privateOpen function and providing Merkle proof for the address. You can generate the Merkle proof locally using merkletreejs:

merkleTree.getHexProof(keccak256(whitelistedUserAddress))

The allowlist is set on contract deployment and can be changed by calling the setWhitelistRoot function from the owner account. The private mode can be enabled or disabled at any time by calling the setPrivateOpen function from the owner account.

Public mode

When the private mode is disabled, anyone can open the lootbox by calling the publicOpen function. It will do the same thing as the privateOpen function but without the Merkle proof.

Randomness

The contract uses Chainlink VRF to generate randomness which is used to determine the rewards the user receives.

Because the randomness is generated offchain, the contract will not be able to transfer the rewards immediately. Instead, it will store the request and once the randomness is received, the user or anyone else can call the claimRewards function to transfer the rewards to the user.

The lootbox creator can also call the claimRewards function and improve the user experience by transferring the rewards to the user immediately. You can automate this further by using Chainlink Automation.

Claim rewards

The rewards for an open request can be claimed by calling the claimRewards function and passing the opener address as the parameter. This will transfer the rewards to the opener address.

The claim function can only be called after the randomness is fulfilled. To check this, call the canClaimRewards function and pass the opener address as the parameter.

One address can only have one open request at a time. If you try to open the lootbox again before the previous request is fulfilled, the transaction reverts with a PendingOpenRequest error.

Withdraw funds

At any time, the owner can withdraw funds from the collected fees by calling the withdraw function. By doing so, the contract balance will be transferred to the owner account.

Code walkthrough

The main part of this tutorial is in the Lootbox.sol contract. The Lootbox contract manages the following tasks:

• Requests a random value from VRF for each open request
• Uses the random value as a seed to determine the reward
• Tracks and validates requests to open the lootbox
• Transfers rewards to the user, for valid requests
• Tracks how many rewards remain in the lootbox
• Validates user addresses against the allowlist, if in private mode

This section focuses on how VRF is used in the lootbox contract.

How the lootbox interacts with the VRF service

The processing done in the fulfillRandomWords callback function is minimal. Here, the function simply stores the randomness result from VRF and emits an event to indicate that the randomness is ready, so the lootbox open request can now be fulfilled. Reducing the computational processing in your fulfillRandomWords callback function makes the callback more gas efficient, and it reduces the chance that your callbackGasLimit will be too low for the VRF request to go through.

...
/// @notice Requests randomness from Chainlink VRF
/// @dev The VRF subscription must be active and sufficient LINK must be available
/// @return requestId The ID of the request
function _requestRandomness() internal returns (uint256 requestId) {
    requestId = VRFCoordinatorV2Interface(i_vrfCoordinatorV2)
        .requestRandomWords(
            i_vrfKeyHash,
            i_vrfSubscriptionId,
            REQUEST_CONFIRMATIONS,
            CALLBACK_GASLIMIT,
            NUMWORDS
        );
}

/// @inheritdoc VRFConsumerBaseV2
function fulfillRandomWords(
    uint256 requestId,
    uint256[] memory randomWords
) internal override {
    s_requests[requestId].randomness = randomWords[0];
    emit OpenRequestFulfilled(requestId, randomWords[0]);
}