Get a Random Number

This guide explains how to get random values using a simple contract to request and receive random values from Chainlink VRF v2.5 without managing a subscription. To explore more applications of VRF, refer to our blog.

Requirements

This guide assumes that you know how to create and deploy smart contracts on Ethereum testnets using the following tools:

• The Remix IDE
• MetaMask
• Sepolia testnet ETH

If you are new to developing smart contracts on Ethereum, see the Getting Started guide to learn the basics.

Create and deploy a VRF compatible contract

For this example, use the DirectFundingConsumer.sol sample contract. This contract imports the following dependencies:

• VRFV2PlusWrapperConsumerBase.sol(link)
• VRFV2PlusClient.sol(link)

The contract also includes pre-configured values for the necessary request parameters such as callbackGasLimit, requestConfirmations, the number of random words numWords, the VRF v2.5 Wrapper address wrapperAddress, and the LINK token address linkAddress. You can change these parameters if you want to experiment on different testnets.

Build and deploy the contract on Sepolia.

1. Open the DirectFundingConsumer.sol contract in Remix.

   Open in Remix What is Remix?

2. On the Compile tab in Remix, compile the DirectFundingConsumer contract.

3. Configure your deployment. On the Deploy tab in Remix, select the Injected Web3 Environment and select the DirectFundingConsumer contract from the contract list.

4. Click the Deploy button to deploy your contract onchain. MetaMask opens and asks you to confirm the transaction.

5. After you deploy your contract, copy the address from the Deployed Contracts list in Remix. Before you can request randomness from VRF v2.5, you must fund your consuming contract with enough tokens in order to request for randomness. Next, fund your contract.

Fund your contract

Requests for randomness will fail unless your consuming contract has enough tokens. VRF V2.5 allows you to use either native tokens or LINK to pay for your requests.

1. Acquire testnet LINK and Sepolia ETH.
2. Fund your contract with either testnet LINK or Sepolia ETH, depending on how you want to pay for your VRF requests. For this example, fund your contract with 2 LINK or 0.01 Sepolia ETH. (The actual request cost is closer to 0.877 LINK or 0.001 ETH. You can withdraw the excess funds after you're done with this contract.)

Request random values

The deployed contract requests random values from Chainlink VRF, receives those values, builds a struct RequestStatus containing them, and stores the struct in a mapping s_requests. Run the requestRandomWords() function on your contract to start the request.

1. Return to Remix and view your deployed contract functions in the Deployed Contracts list.

2. Expand the requestRandomWords() function. For enableNativePayment, fill in true if you're paying for your request with Sepolia ETH, or false if you're paying with testnet LINK. Click transact to send the request for random values to Chainlink VRF. MetaMask opens and asks you to confirm the transaction.

   After you approve the transaction, Chainlink VRF processes your request. Chainlink VRF fulfills the request and returns the random values to your contract in a callback to the fulfillRandomWords() function. At this point, a new key requestId is added to the mapping s_requests. Depending on current testnet conditions, it might take a few minutes for the callback to return the requested random values to your contract.

3. To fetch the request ID of your request, call lastRequestId().

4. After the oracle returns the random values to your contract, the mapping s_requests is updated. The received random values are stored in s_requests[_requestId].randomWords.

5. Call getRequestStatus() and specify the requestId to display the random words.

Analyzing the contract

In this example, the consuming contract uses static configuration parameters.

// SPDX-License-Identifier: MIT
// An example of a consumer contract that directly pays for each request.
pragma solidity 0.8.19;

import {ConfirmedOwner} from "@chainlink/contracts/src/v0.8/shared/access/ConfirmedOwner.sol";
import {LinkTokenInterface} from "@chainlink/contracts/src/v0.8/shared/interfaces/LinkTokenInterface.sol";
import {VRFV2PlusWrapperConsumerBase} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFV2PlusWrapperConsumerBase.sol";
import {VRFV2PlusClient} from "@chainlink/contracts/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol";

/**
 * Request testnet LINK and ETH here: https://faucets.chain.link/
 * Find information on LINK Token Contracts and get the latest ETH and LINK faucets here: https://docs.chain.link/docs/link-token-contracts/
 */

/**
 * 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 DirectFundingConsumer is VRFV2PlusWrapperConsumerBase, ConfirmedOwner {
    event RequestSent(uint256 requestId, uint32 numWords);
    event RequestFulfilled(
        uint256 requestId,
        uint256[] randomWords,
        uint256 payment
    );

    struct RequestStatus {
        uint256 paid; // amount paid in link
        bool fulfilled; // whether the request has been successfully fulfilled
        uint256[] randomWords;
    }
    mapping(uint256 => RequestStatus)
        public s_requests; /* requestId --> requestStatus */

    // past requests Id.
    uint256[] public requestIds;
    uint256 public lastRequestId;

    // Depends on the number of requested values that you want sent to the
    // fulfillRandomWords() function. Test and adjust
    // this limit based on the network that you select, the size of the request,
    // and the processing of the callback request in the fulfillRandomWords()
    // function.
    uint32 public callbackGasLimit = 100000;

    // The default is 3, but you can set this higher.
    uint16 public requestConfirmations = 3;

    // For this example, retrieve 2 random values in one request.
    // Cannot exceed VRFV2Wrapper.getConfig().maxNumWords.
    uint32 public numWords = 2;

    // Address LINK - hardcoded for Sepolia
    address public linkAddress = 0x779877A7B0D9E8603169DdbD7836e478b4624789;

    // address WRAPPER - hardcoded for Sepolia
    address public wrapperAddress = 0x195f15F2d49d693cE265b4fB0fdDbE15b1850Cc1;

    constructor()
        ConfirmedOwner(msg.sender)
        VRFV2PlusWrapperConsumerBase(wrapperAddress)
    {}

    function requestRandomWords(
        bool enableNativePayment
    ) external onlyOwner returns (uint256) {
        bytes memory extraArgs = VRFV2PlusClient._argsToBytes(
            VRFV2PlusClient.ExtraArgsV1({nativePayment: enableNativePayment})
        );
        uint256 requestId;
        uint256 reqPrice;
        if (enableNativePayment) {
            (requestId, reqPrice) = requestRandomnessPayInNative(
                callbackGasLimit,
                requestConfirmations,
                numWords,
                extraArgs
            );
        } else {
            (requestId, reqPrice) = requestRandomness(
                callbackGasLimit,
                requestConfirmations,
                numWords,
                extraArgs
            );
        }
        s_requests[requestId] = RequestStatus({
            paid: reqPrice,
            randomWords: new uint256[](0),
            fulfilled: false
        });
        requestIds.push(requestId);
        lastRequestId = requestId;
        emit RequestSent(requestId, numWords);
        return requestId;
    }

    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
        );
    }

    function getRequestStatus(
        uint256 _requestId
    )
        external
        view
        returns (uint256 paid, bool fulfilled, uint256[] memory randomWords)
    {
        require(s_requests[_requestId].paid > 0, "request not found");
        RequestStatus memory request = s_requests[_requestId];
        return (request.paid, request.fulfilled, request.randomWords);
    }

    /**
     * Allow withdraw of Link tokens from the contract
     */
    function withdrawLink() public onlyOwner {
        LinkTokenInterface link = LinkTokenInterface(linkAddress);
        require(
            link.transfer(msg.sender, link.balanceOf(address(this))),
            "Unable to transfer"
        );
    }

    /// @notice withdrawNative withdraws the amount specified in amount to the owner
    /// @param amount the amount to withdraw, in wei
    function withdrawNative(uint256 amount) external onlyOwner {
        (bool success, ) = payable(owner()).call{value: amount}("");
        // solhint-disable-next-line gas-custom-errors
        require(success, "withdrawNative failed");
    }

    event Received(address, uint256);

    receive() external payable {
        emit Received(msg.sender, msg.value);
    }
}

The parameters define how your requests will be processed. You can find the values for your network in the Supported networks page.

• uint32 callbackGasLimit: The limit for how much gas to use for the callback request to your contract's fulfillRandomWords() function. It must be less than the maxGasLimit limit on the coordinator contract minus the wrapperGasOverhead. See the VRF v2.5 Direct funding limits for more details. Adjust this value for larger requests depending on how your fulfillRandomWords() function processes and stores the received random values. If your callbackGasLimit is not sufficient, the callback will fail and your consuming contract is still charged for the work done to generate your requested random values.

• uint16 requestConfirmations: How many confirmations the Chainlink node should wait before responding. The longer the node waits, the more secure the random value is. It must be greater than the minimumRequestBlockConfirmations limit on the coordinator contract.

• uint32 numWords: 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. The total cost of the callback request depends on how your fulfillRandomWords() function processes and stores the received random values, so adjust your callbackGasLimit accordingly.

The contract includes the following functions:

• requestRandomWords(): Takes your specified parameters and submits the request to the VRF v2.5 Wrapper contract.

• fulfillRandomWords(): Receives random values and stores them with your contract.

• getRequestStatus(): Retrive request details for a given _requestId.

• withdrawLink(): At any time, the owner of the contract can withdraw the outstanding LINK balance from it.

• withdrawNative(): At any time, the owner of the contract can withdraw the outstanding native token balance from it.

Clean up

After you are done with this contract, you can retrieve the remaining testnet tokens to use with other examples: