Pass VRF Costs to the End Users

Objective

The VRF direct funding method calculates costs at request time. In this tutorial, you will use VRF direct funding and map VRF request IDs to their corresponding responses from the VRF service, along with the cost of each request.

Before you begin

Before you start this tutorial, complete the following items:

• Install Foundry.

  macOSWindows

  1. Open a Terminal window and run:

     curl -L https://foundry.paradigm.xyz | bash
     

  2. Follow the instructions in your terminal to add foundryup to your CLI.
  3. Run foundryup. After successful installation, you should get output that contains a Foundry banner. After that, you should see foundryup installing forge and other packages:

     foundryup: installing foundry (version nightly, tag nightly-74c03182d41c75c40e5a1c398aca9400305ff678)
     foundryup: downloading latest forge, cast, anvil, and chisel
     ########################################################################################################## 100.0%
     foundryup: downloading manpages
     ########################################################################################################## 100.0%
     foundryup: installed - forge 0.2.0 (74c0318 2023-09-14T00:27:34.321593000Z)
     foundryup: installed - cast 0.2.0 (74c0318 2023-09-14T00:27:34.059889000Z)
     foundryup: installed - anvil 0.2.0 (74c0318 2023-09-14T00:27:34.192518000Z)
     foundryup: installed - chisel 0.2.0 (74c0318 2023-09-14T00:27:33.928662000Z)
     foundryup: done!
     

• Install make if you do not already have it.

  macOSWindows

  1. The Xcode command line tools include make. If you've previously installed Xcode, skip to step 2 to verify your installation. Otherwise, open a Terminal window and run:

     xcode-select --install
     

     Alternatively, if you prefer to use Homebrew, be aware that GNU make is installed as gmake.
  2. Verify your make installation:

     make
     

     If make is installed successfully, you will get the following output:

     make: *** No targets specified or no makefile found. Stop.
     

• Run git --version to check your git installation. You should see an output similar to git version x.x.x. If not, install git.

• Get your Etherscan API key for contract verification. If you do not already have one:

  • Create an Etherscan account.
  • Create an Etherscan API key.

• 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.

Steps to implement

git clone [email protected]:smartcontractkit/vrf-direct-funding-example.git

make install

make deploy

Code example

This section explains how the VRFDirectFundingConsumer.sol contract maps each request to its cost.

This RequestStatus struct is used to map attributes of each VRF request to its request ID, including its cost, its fulfillment status, and the random values generated by the VRF service in response to the request:

struct RequestStatus {
        uint256 paid;
        bool fulfilled;
        uint256[] randomWords;
    }

mapping(uint256 => RequestStatus) public s_requests;

The requestRandomWords function calls the calculateRequestPrice function on the VRF wrapper contract to calculate the request cost upfront, and then transfers enough LINK to the VRF wrapper to cover the request. After sending the request, the requestRandomWords function stores the RequestStatus with the cost and other request attributes, and emits a RequestSent event.

function requestRandomWords() external returns (uint256) {
   // Calculate the price required for the VRF request based on the configured parameters.
   uint256 requestPrice = calculateRequestPrice();

   // Transfer the required LINK tokens from the caller's address to this contract.
   transferLinkFromUser(requestPrice);

   // Send the randomness request to the VRF Wrapper contract and retrieve the request ID and the paid price.
   bytes memory extraArgs = VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: false}));
   (uint256 requestId, uint256 reqPrice) = requestRandomness(
      requestConfig.callbackGasLimit, requestConfig.requestConfirmations, requestConfig.numWords, extraArgs
   );
   // Record the request details.
   s_requests[requestId] = RequestStatus({paid: reqPrice, randomWords: new uint256[](0), fulfilled: false});
   requestIds.push(requestId);
   lastRequestId = requestId;

   // Emit an event indicating that a request has been sent.
   emit RequestSent(requestId, requestConfig.numWords);

   return requestId;
}

[...]

function calculateRequestPrice() internal view returns (uint256) {
   return i_vrfV2PlusWrapper.calculateRequestPrice(requestConfig.callbackGasLimit, requestConfig.numWords);
}

After the VRF service fulfills your randomness request, it calls back your fulfillRandomWords function, where you implement logic to handle the random values. It's recommended to keep the processing in your callback function minimal to save on gas costs. In this case, the example contract updates the RequestStatus in the request mapping, and emits an event indicating that the request has been fulfilled. Another part of your application can listen for this event and further process the random values separately from the callback function.

function fulfillRandomWords(uint256 _requestId, uint256[] memory _randomWords) internal override {
   require(s_requests[_requestId].paid > 0, "request not found");
   s_requests[_requestId].fulfilled = true;
   s_requests[_requestId].randomWords = _randomWords;
   emit RequestFulfilled(_requestId, _randomWords, s_requests[_requestId].paid);
}