Migrating from VRF v2

Benefits of VRF v2.5

Chainlink VRF v2.5 includes all the same key benefits as VRF v2, along with the following additional benefits and changes:

Easier upgrades to future versions by using the new setCoordinator function
The option to pay for requests in either LINK or native tokens
New, flexible request format in requestRandomWords to make any future upgrades easier

Code changes

VRF v2.5 introduces a new request format and the setCoordinator function. See the full migration walkthrough or the code example for more details.

New request format

The request format for VRF v2.5 has changed:

The requestRandomWords function now uses VRFV2PlusClient.RandomWordsRequest with a mapping labeling each part of the request:

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

You must include a value for the new extraArgs key, which allows you to add extra arguments related to new VRF features. Use the nativePayment argument to enable or disable payment in native tokens.

The requestRandomness function in the wrapper contract requires a new extraArgs argument that allows you to add extra arguments related to new VRF features. Use the nativePayment argument to enable or disable payment in native tokens.

Additionally, the requestRandomness function now returns two arguments instead of one: the request ID and the request price.

bytes memory extraArgs = VRFV2PlusClient._argsToBytes(
    VRFV2PlusClient.ExtraArgsV1({nativePayment: false})
);
(uint256 reqId, uint256 reqPrice) = requestRandomness(
    callbackGasLimit,
    requestConfirmations,
    numWords,
    extraArgs
);

setCoordinator function

Add the setCoordinator function to your contract so that you can easily update the VRF coordinator for future VRF releases.

Subscription ID type change

Note that the subscription ID has changed types from uint64 in VRF V2 to uint256 in VRF V2.5.

Billing changes

You have the option to use either native tokens or LINK to pay for VRF requests. To accommodate this, the premium fee has changed from a flat LINK premium amount per request, to a percentage-based premium per request. Refer to the Billing page for more details. To find out the new premium percentages for the networks you use, see the Supported Networks page.

For direct funding, the configurations for overhead gas have changed:

The amount of wrapper overhead gas is reduced compared to V2.
The amount of coordinator overhead gas used varies depending on the network used for your request, whether you're paying in LINK or native tokens, and how many random values you want in each VRF request. Refer to the Billing page for more details and examples, and see the new configurations on the Supported Networks page.

Migration walkthrough

VRF v2.5 currently supports subscriptions and direct funding on all supported networks. To migrate, you need to update your existing smart contract code and redeploy your contracts.

If using subscriptions, create and fund a new VRF v2.5 subscription.

For direct funding, deploy the DirectFundingConsumer example, which directly includes the latest V2.5 wrapper and interface:

Open in Remix What is Remix?

Update your code

To modify your existing smart contract code to work with VRF v2.5, complete the following changes:

Import the VRFConsumerBaseV2Plus contract and remove the v2 VRFConsumerBaseV2 import.
Import the VRF v2.5 coordinator, VRFCoordinatorV2_5, and update any old references to the VRF V2 coordinator in your contract.
Add a VRFConsumerBaseV2Plus constructor, passing in the LINK token address for the network you're using.
Update your requestRandomWords function calls to reflect the new request structure for VRF v2.5. Make sure to include the new extraArgs part of the VRFV2PlusClient.RandomWordsRequest mapping, and specify whether or not you want to pay for VRF requests using native tokens:
uint256 requestId = s_vrfCoordinator.requestRandomWords( VRFV2PlusClient.RandomWordsRequest({ keyHash: keyHash, subId: s_vrfSubscriptionId, requestConfirmations: requestConfirmations, callbackGasLimit: callbackGasLimit, numWords: numWords, extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: false})) }) );
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})) }) );

Import the VRFV2PlusWrapperConsumerBase contract and remove the v2 VRFV2WrapperConsumerBase import.
Add a VRFV2PlusWrapperConsumerBase constructor, passing in the VRF wrapper address for the network you're using. Unlike V2, you don't have to pass the LINK token address to the constructor.

You can still call the requestRandomness function. However, the V2.5 requestRandomness function requires one additional parameter, extraArgs. Use nativePayment to specify whether or not you want to pay for VRF requests using native tokens:

bytes memory extraArgs = VRFV2PlusClient._argsToBytes(
    VRFV2PlusClient.ExtraArgsV1({nativePayment: false})
);
(uint256 reqId, uint256 reqPrice) = requestRandomness(
    callbackGasLimit,
    requestConfirmations,
    numWords,
    extraArgs
);

bytes memory extraArgs = VRFV2PlusClient._argsToBytes(
    VRFV2PlusClient.ExtraArgsV1({nativePayment: true})
);
(uint256 reqId, uint256 reqPrice) = requestRandomness(
    callbackGasLimit,
    requestConfirmations,
    numWords,
    extraArgs
);

The V2.5 requestRandomness function returns a tuple: (uint256 requestId, uint256 requestPrice). Adjust your requestRandomWords function or any other functions in your code where you call requestRandomness.
Make sure your contract has a withdraw function for both native tokens and LINK. Refer to the withdrawLink and withdrawNative functions in the VRFV2PlusWrapperConsumerExample contract.

Compare example code

Subscription example code

The example SubscriptionConsumer contract shows the migration steps above, applied to the example code from this VRF V2 tutorial. Both of these examples use the subscription method.

Open the full example SubscriptionConsumer contract:

Open in Remix What is Remix?

Compare the major changes between V2.5 and V2:

// SPDX-License-Identifier: MIT
// An example of a consumer contract that relies on a subscription for funding.
pragma solidity 0.8.19;

///// UPDATE IMPORTS TO V2.5 /////
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.
  \*/

///// INHERIT NEW CONSUMER BASE CONTRACT /////
contract SubscriptionConsumer is VRFConsumerBaseV2Plus {
...
    ///// No need to declare a coordinator variable /////
    ///// Use the `s_vrfCoordinator` from VRFConsumerBaseV2Plus.sol /////

    ///// SUBSCRIPTION ID IS NOW UINT256 /////
    uint256 s_subscriptionId;

    ...

    ///// USE NEW KEYHASH FOR VRF 2.5 GAS LANE /////
    // For a list of available gas lanes on each network,
    // see https://docs.chain.link/docs/vrf/v2-5/supported-networks
    bytes32 keyHash =
        0x787d74caea10b2b357790d5b5247c2f63d1d91572a9846f780606e4d953677ae;

    ...

    ///// USE NEW CONSUMER BASE CONSTRUCTOR /////
    constructor(
        ///// UPDATE TO UINT256 /////
        uint256 subscriptionId
    )
        VRFConsumerBaseV2Plus(0x9DdfaCa8183c41ad55329BdeeD9F6A8d53168B1B)
    {
        s_subscriptionId = subscriptionId;
    }

    function requestRandomWords()
        external
        onlyOwner
        returns (uint256 requestId)
    {
        ///// UPDATE TO NEW V2.5 REQUEST FORMAT /////
        // To enable payment in native tokens, set nativePayment to true.
        // Use the `s_vrfCoordinator` from VRFConsumerBaseV2Plus.sol
        requestId = s_vrfCoordinator.requestRandomWords(
            VRFV2PlusClient.RandomWordsRequest({
                keyHash: keyHash,
                subId: s_subscriptionId,
                requestConfirmations: requestConfirmations,
                callbackGasLimit: callbackGasLimit,
                numWords: numWords,
                extraArgs: VRFV2PlusClient._argsToBytes(
                    VRFV2PlusClient.ExtraArgsV1({nativePayment: false})
                )
            })
        );
        ...
    }
    ...

}

// SPDX-License-Identifier: MIT
// An example of a consumer contract that relies on a subscription for funding.
pragma solidity ^0.8.7;

///// USES V2 IMPORTS /////
import {VRFCoordinatorV2Interface} from "@chainlink/contracts/src/v0.8/vrf/interfaces/VRFCoordinatorV2Interface.sol";
import {VRFConsumerBaseV2} from "@chainlink/contracts/src/v0.8/vrf/VRFConsumerBaseV2.sol";
import {ConfirmedOwner} from "@chainlink/contracts/src/v0.8/shared/access/ConfirmedOwner.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.
  \*/

///// USES V2 CONSUMER BASE CONTRACT /////
contract VRFv2Consumer is VRFConsumerBaseV2, ConfirmedOwner {
...

    ///// OLD TYPE FOR SUBSCRIPTION ID /////
    uint64 s_subscriptionId;

    ...

    ///// KEYHASH FOR VRF V2 GAS LANE /////
    // 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/subscription/supported-networks/#configurations
    bytes32 keyHash =
        0x474e34a077df58807dbe9c96d3c009b23b3c6d0cce433e59bbf5b34f823bc56c;

    ...

     ///// USES V2 CONSUMER BASE AND COORDINATOR CONSTRUCTORS /////
    constructor(
        uint64 subscriptionId
    )
        VRFConsumerBaseV2(0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625)
        ConfirmedOwner(msg.sender)
    {
        COORDINATOR = VRFCoordinatorV2Interface(
            0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625
        );
        s_subscriptionId = subscriptionId;
    }

    ...

    function requestRandomWords()
        external
        onlyOwner
        returns (uint256 requestId)
    {   ///// USES V2 REQUEST FORMAT /////
        requestId = COORDINATOR.requestRandomWords(
            keyHash,
            s_subscriptionId,
            requestConfirmations,
            callbackGasLimit,
            numWords
        );
        ...
    }

...
}

Direct funding example code

The example DirectFundingConsumer contract shows the migration steps above, applied to the example code from this VRF V2 tutorial. Both of these examples use the direct funding method.

Open the full example DirectFundingConsumer contract:

Open in Remix What is Remix?

Compare the major changes between V2.5 and V2:

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

///// UPDATE IMPORTS TO V2.5 /////
import {ConfirmedOwner} from "@chainlink/contracts/src/v0.8/shared/access/ConfirmedOwner.sol";
import {VRFV2PlusWrapperConsumerBase} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFV2PlusWrapperConsumerBase.sol";
import {LinkTokenInterface} from "@chainlink/contracts/src/v0.8/shared/interfaces/LinkTokenInterface.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.
 */

 ///// INHERIT NEW WRAPPER CONSUMER BASE CONTRACT /////
contract DirectFundingConsumer is VRFV2PlusWrapperConsumerBase, ConfirmedOwner {

    ...
    ///// USE NEW WRAPPER CONSUMER BASE CONSTRUCTOR /////
    constructor()
        ConfirmedOwner(msg.sender)
        VRFV2PlusWrapperConsumerBase(wrapperAddress) ///// ONLY PASS IN WRAPPER ADDRESS /////
    {}

    function requestRandomWords()
        external
        onlyOwner
        returns (uint256)
    {
        ///// UPDATE TO NEW V2.5 REQUEST FORMAT: ADD EXTRA ARGS /////
        bytes memory extraArgs = VRFV2PlusClient._argsToBytes(
            VRFV2PlusClient.ExtraArgsV1({nativePayment: false})
        );

        ///// REQUESTRANDOMNESS RETURNS A TUPLE /////
        (uint256 reqId, uint256 reqPrice) = requestRandomness(
            callbackGasLimit,
            requestConfirmations,
            numWords,
            extraArgs ///// PASS IN EXTRA ARGS /////
        );

        ...
        return reqId;
    }
   ...
}

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

///// USES V2 IMPORTS /////
import {ConfirmedOwner} from "@chainlink/contracts/src/v0.8/shared/access/ConfirmedOwner.sol";
import {VRFV2WrapperConsumerBase} from "@chainlink/contracts/src/v0.8/vrf/VRFV2WrapperConsumerBase.sol";
import {LinkTokenInterface} from "@chainlink/contracts/src/v0.8/shared/interfaces/LinkTokenInterface.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.
  \*/

///// USES V2 WRAPPER CONSUMER BASE CONTRACT /////
contract VRFv2DirectFundingConsumer is
VRFV2WrapperConsumerBase,
ConfirmedOwner
{
...

    ///// USES V2 WRAPPER CONSUMER BASE CONSTRUCTOR /////
    constructor()
        ConfirmedOwner(msg.sender)
        VRFV2WrapperConsumerBase(linkAddress, wrapperAddress) ///// TWO PARAMETERS /////
    {}

    function requestRandomWords()
        external
        onlyOwner
        returns (uint256 requestId)
    {
        ///// USES V2 REQUEST FORMAT /////
        requestId = requestRandomness(
            callbackGasLimit,
            requestConfirmations,
            numWords
        );
        ...
        return requestId;
    }

...

}

Migrating from VRF v2

Stay updated on the latest Chainlink news