Migrating from VRF v1

To modify your existing smart contract code to work with VRF v2.5, complete the following changes. See the Get a Random Number guide for an example.

1. Set up and fund a subscription in the Subscription Manager at vrf.chain.link.

   Open the Subscription Manager

2. Add the following imports to your contract:

   • VRFConsumerBaseV2Plus. Remove the v1 VRFConsumerBase.sol import. VRFConsumerBaseV2Plus includes the fulfillRandomWords function. The VRFConsumerBaseV2Plus contract imports the IVRFCoordinatorV2Plus interface, which includes the requestRandomWords function.
   • VRFV2PlusClient is a library used to format your VRF requests.

   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";
   

3. Add a VRFConsumerBaseV2Plus constructor, passing in the LINK token address for the network you're using, as shown in the Get a Random Number example.

4. Change requestRandomness function calls to requestRandomWords. The requestRandomWords function requires several additional parameters. The extraArgs key allows you to add extra arguments related to new VRF features. Use the nativePayment argument to enable or disable payment in 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: true}))
        })
    );
   

5. Change fulfillRandomness function calls to fulfillRandomWords. Update the call to handle the returned uint256[] array instead of the single uint256 variable.

6. Use the setCoordinator function in your contract so that you can easily update the VRF coordinator for future VRF releases. This function is inherited from the IVRFCoordinatorV2Plus interface.

To modify your existing smart contract code to work with VRF v2.5, complete the following changes. See the Get a Random Number guide for an example.

1. Import and inherit the VRFV2PlusWrapperConsumerBase contract and remove the v1 VRFConsumerBase.sol import. This contract includes the fulfillRandomWords function.

2. Add a VRFV2PlusWrapperConsumerBase constructor, passing in the VRF wrapper address for the network you're using, as shown in the Get a Random Number example.

3. You can still call the requestRandomness function. However, the v2 requestRandomness function requires several different parameters. See the Supported networks page to adjust them for your own needs.

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

4. If you're paying for requests with LINK, you can still call the requestRandomness function. However, if you're paying with native tokens, call the requestRandomnessPayInNative function instead.

   • Both functions return two arguments instead of one: the request ID and the request price.

   • Both functions require one additional parameter, extraArgs. Use nativePayment to specify whether or not you want to pay for VRF requests using native tokens:

     LINKNative tokens

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

5. Change fulfillRandomness function calls to fulfillRandomWords. Update the call to handle the returned uint256[] array instead of the single uint256 variable.

1. Import the VRFConsumerBaseV2Plus contract and remove the v2 VRFConsumerBaseV2 import.

2. Import the VRF v2.5 coordinator, VRFCoordinatorV2_5, and update any old references to the VRF V2 coordinator in your contract.

3. Add a VRFConsumerBaseV2Plus constructor, passing in the LINK token address for the network you're using.

4. 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 object, and specify whether or not you want to pay for VRF requests using native tokens:

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

5. When using the @chainlink/contracts package version 1.1.1 and later, update your fulfillRandomWords function signature to match the VRFConsumerBaseV2Plus contract, which has changed to:

   function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords)
   

   In the @chainlink/contracts package version 1.1.0 and earlier, the randomWords parameter has a memory storage location.

1. Import the VRFV2PlusWrapperConsumerBase contract and remove the v2 VRFV2WrapperConsumerBase import.

2. Add a VRFV2PlusWrapperConsumerBase constructor, passing in the VRF wrapper address for the network you're using. Unlike in V2, you don't have to pass the LINK token address to the constructor.

3. If you're paying for requests with LINK, you can still call the requestRandomness function. However, if you're paying with native tokens, call the requestRandomnessPayInNative function instead.

   Both functions require one additional parameter, extraArgs. Use nativePayment to specify whether or not you want to pay for VRF requests using native tokens:

   LINKNative tokens

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

4. The V2.5 requestRandomness and requestRandomnessPayInNative functions both return a tuple: (uint256 requestId, uint256 requestPrice). Adjust your requestRandomWords function or any other functions in your code where you call the V2.5 wrapper's requestRandomness or requestRandomnessPayInNative functions.

5. Make sure your contract has a withdraw function for both native tokens and LINK. Both are included in the direct funding example code and the VRFV2PlusWrapperConsumerExample contract.