Chainlink VRF

Chainlink VRF

Chainlink VRF (Verifiable Random Function) is a provably fair and verifiable random number generator (RNG) that enables smart contracts to access random values without compromising security or usability.

Back

Overview

Chainlink VRF (Verifiable Random Function) is a provably fair and verifiable random number generator (RNG) that enables smart contracts to access random values without compromising security or usability. For each request, Chainlink VRF generates one or more random values and cryptographic proof of how those values were determined. The proof is published and verified onchain before any consuming applications can use it. This process ensures that results cannot be tampered with or manipulated by any single entity including oracle operators, miners, users, or smart contract developers.

Use Chainlink VRF to build reliable smart contracts for any applications that rely on unpredictable outcomes:

Two methods to request randomness

To use Chainlink VRF on the Avalanche Primary Network using subscription, utilize the following information from Chainlink:

ItemValue
LINK Token0x5947BB275c521040051D82396192181b413227A3
VRF Coordinator0xE40895D055bccd2053dD0638C9695E326152b1A4
200 gwei Key Hash0xea7f56be19583eeb8255aa79f16d8bd8a64cedf68e42fefee1c9ac5372b1a102
500 gwei Key Hash0x84213dcadf1f89e4097eb654e3f284d7d5d5bda2bd4748d8b7fada5b3a6eaa0d
1000 gwei Key Hash0xe227ebd10a873dde8e58841197a07b410038e405f1180bd117be6f6557fa491c
Premium percentage (paying with AVAX)60
Premium percentage (paying with LINK)50
Max Gas Limit2,500,000
Minimum Confirmations0
Maximum Confirmations200
Maximum Random Values500

This repository provides example contracts for how an Avalanche L1 could leverage Chainlink VRF functionality (available on the C-Chain) using Teleporter. This allows newly launched L1s to immediately utilize VRF without any trusted intermediaries or third-party integration requirements.

Avalanche L1 VRF Example Contracts

Best Practices

These are example best practices for using Chainlink VRF. To explore more applications of VRF, refer to Chainlink's blog.

Getting a random number within a range

If you need to generate a random number within a given range, use modulo to define the limits of your range. Below you can see how to get a random number in a range from 1 to 50.

function fulfillRandomWords(
  uint256, /* requestId */
  uint256[] memory randomWords
) internal override {
  // Assuming only one random word was requested.
  s_randomRange = (randomWords[0] % 50) + 1;
}

Getting multiple random values

If you want to get multiple random values from a single VRF request, you can request this directly with the numWords argument:

Processing simultaneous VRF requests

If you want to have multiple VRF requests processing simultaneously, create a mapping between requestId and the response. You might also create a mapping between the requestId and the address of the requester to track which address made each request.

mapping(uint256 => uint256[]) public s_requestIdToRandomWords;
mapping(uint256 => address) public s_requestIdToAddress;
uint256 public s_requestId;
 
function requestRandomWords() external onlyOwner returns (uint256) {
  uint256 requestId = s_vrfCoordinator.requestRandomWords(
      VRFV2PlusClient.RandomWordsRequest({
          keyHash: keyHash,
          subId: s_vrfSubscriptionId,
          requestConfirmations: requestConfirmations,
          callbackGasLimit: callbackGasLimit,
          numWords: numWords,
          extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: true})) // new parameter
      })
  );
  s_requestIdToAddress[requestId] = msg.sender;
 
  // Store the latest requestId for this example.
  s_requestId = requestId;
 
  // Return the requestId to the requester.
  return requestId;
}
 
function fulfillRandomWords(
    uint256 requestId,
    uint256[] memory randomWords
  ) internal override {
  // You can return the value to the requester,
  // but this example simply stores it.
  s_requestIdToRandomWords[requestId] = randomWords;
}

You could also map the requestId to an index to keep track of the order in which a request was made.

Processing VRF responses through different execution paths

If you want to process VRF responses depending on predetermined conditions, you can create an enum. When requesting for randomness, map each requestId to an enum. This way, you can handle different execution paths in fulfillRandomWords. See the following example:

// SPDX-License-Identifier: MIT
// An example of a consumer contract that relies on a subscription for funding.
// It shows how to setup multiple execution paths for handling a response.
pragma solidity 0.8.19;
 
import {LinkTokenInterface} from "@chainlink/contracts/src/v0.8/shared/interfaces/LinkTokenInterface.sol";
import {IVRFCoordinatorV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/interfaces/IVRFCoordinatorV2Plus.sol";
import {VRFConsumerBaseV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFConsumerBaseV2Plus.sol";
import {VRFV2PlusClient} from "@chainlink/contracts/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol";
 
/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES HARDCODED VALUES FOR CLARITY.
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */
 
contract VRFv2MultiplePaths is VRFConsumerBaseV2Plus {
 
    // Your subscription ID.
    uint256 s_subscriptionId;
 
    // Avalanche Primary Network coordinator.
    address vrfCoordinatorV2Plus = 0xE40895D055bccd2053dD0638C9695E326152b1A4;
 
    // The gas lane to use, which specifies the maximum gas price to bump to.
    // For a list of available gas lanes on each network,
    // see https://docs.chain.link/docs/vrf/v2-5/supported-networks
    bytes32 keyHash =
        0x787d74caea10b2b357790d5b5247c2f63d1d91572a9846f780606e4d953677ae;
 
    uint32 callbackGasLimit = 100000;
 
    // The default is 3, but you can set this higher.
    uint16 requestConfirmations = 3;
 
    // For this example, retrieve 1 random value in one request.
    // Cannot exceed VRFCoordinatorV2_5.MAX_NUM_WORDS.
    uint32 numWords = 1;
 
    enum Variable {
        A,
        B,
        C
    }
 
    uint256 public variableA;
    uint256 public variableB;
    uint256 public variableC;
 
    mapping(uint256 => Variable) public requests;
 
    // events
    event FulfilledA(uint256 requestId, uint256 value);
    event FulfilledB(uint256 requestId, uint256 value);
    event FulfilledC(uint256 requestId, uint256 value);
 
    constructor(uint256 subscriptionId) VRFConsumerBaseV2Plus(vrfCoordinatorV2Plus) {
        s_vrfCoordinator = IVRFCoordinatorV2Plus(vrfCoordinatorV2Plus);
        s_subscriptionId = subscriptionId;
    }
 
    function updateVariable(uint256 input) public {
      uint256 requestId = s_vrfCoordinator.requestRandomWords(VRFV2PlusClient.RandomWordsRequest({
            keyHash: keyHash,
            subId: s_subscriptionId,
            requestConfirmations: requestConfirmations,
            callbackGasLimit: callbackGasLimit,
            numWords: numWords,
            extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: true}))
          })
        );
 
        if (input % 2 == 0) {
            requests[requestId] = Variable.A;
        } else if (input % 3 == 0) {
            requests[requestId] = Variable.B;
        } else {
            requests[requestId] = Variable.C;
        }
    }
 
    function fulfillRandomWords(
        uint256 requestId,
        uint256[] memory randomWords
    ) internal override {
        Variable variable = requests[requestId];
        if (variable == Variable.A) {
            fulfillA(requestId, randomWords[0]);
        } else if (variable == Variable.B) {
            fulfillB(requestId, randomWords[0]);
        } else if (variable == Variable.C) {
            fulfillC(requestId, randomWords[0]);
        }
    }
 
    function fulfillA(uint256 requestId, uint256 randomWord) private {
        // execution path A
        variableA = randomWord;
        emit FulfilledA(requestId, randomWord);
    }
 
    function fulfillB(uint256 requestId, uint256 randomWord) private {
        // execution path B
        variableB = randomWord;
        emit FulfilledB(requestId, randomWord);
    }
 
    function fulfillC(uint256 requestId, uint256 randomWord) private {
        // execution path C
        variableC = randomWord;
        emit FulfilledC(requestId, randomWord);
    }
}

Developer:

Chainlink Labs

Categories:

VRF

Available For:

C-ChainL1s

Website:

https://chain.link/vrf

Documentation:

https://docs.chain.link/vrf
Edit on Github