Migrate from VRF v1

Chainlink VRF v2.5 includes several improvements and changes to the way you fund and request randomness for your smart contracts.

• Subscription management: Chainlink VRF v2.5 introduces a Subscription Manager application that allows smart contract applications to pre-fund multiple requests for randomness using either a LINK token balance or a native token balance. This reduces the gas fees for VRF requests by eliminating the need to transfer tokens for each individual request. You transfer tokens to the subscription balance only when it requires additional funding.

• Variable Callback Gas Limit: Chainlink VRF v2.5 lets you adjust the callback gas limit when your smart contract application receives verifiable randomness. Consuming contracts can execute more complex logic in the callback request function that receives the random values. Tasks involving the delivered randomness are handled during the response process. The new gas limits are higher than the VRF V1 limit, and vary depending on the underlying blockchain you use. See the gas limits on the VRF V2.5 Supported Networks page.

• More configuration capability: You can define how many block confirmations must pass before verifiable randomness is generated and delivered onchain when your application makes a request transaction. The range is from 3 to 200 blocks. VRF V1 always waited 10 blocks on Ethereum before delivering onchain randomness. Select a value that protects your application from block re-organizations while still providing sufficiently low latency from request to response. See the Security Considerations page to learn more.

• Multiple Random Outputs in a Single Request: The VRF Coordinator contracts in VRF v2.5 allow you to request multiple random numbers (multi-word) in a single onchain transaction, which reduces gas costs. The fulfillment is also a single transaction, which reduces the latency of responses.

• Unified Billing - Delegate Subscription Balance to Multiple Addresses: Chainlink VRF v2.5 allows up to 100 smart contract addresses to fund their requests for verifiable randomness from a single subscription, which is managed by the subscription owner. Your subscription has balances for LINK and for native tokens.

The main similarity between VRF v1 and the VRF v2.5 Direct funding method is that consuming contracts must be funded to pay for requests. However, Chainlink VRF v2.5 includes several improvements:

• Native token billing: Chainlink VRF v2.5 lets you fund your consuming contract with either LINK or native tokens to pay for VRF requests.

• Variable Callback Gas Limit: Chainlink VRF v2.5 lets you adjust the callback gas limit when your smart contract application receives verifiable randomness. Consuming contracts can execute more complex logic in the callback request function that receives the random values. Tasks involving the delivered randomness are handled during the response process. The new gas limits are higher than the VRF V1 limit, and vary depending on the underlying blockchain that you use. See the gas limits on the Supported networks page.

• More configuration capability: You can define how many block confirmations must pass before verifiable randomness is generated and delivered onchain when your application makes a request transaction. The range is from 3 to 200 blocks. VRF V1 always waited 10 blocks on Ethereum before delivering onchain randomness. Select a value that protects your application from block re-organizations while still providing sufficiently low latency from request to response. See the Security Considerations page to learn more.

• Multiple Random Outputs in a Single Request: The VRF Wrapper contracts in VRF v2.5 allow you to request multiple random numbers (multi-word) in a single onchain transaction, which reduces gas costs. The fulfillment is also a single transaction, which reduces the latency of responses.

To modify your existing smart contract code to work with VRF v2.5, complete the following changes. See the Migration from V2 guide for an example.

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

   Open the Subscription Manager

2. Import the VRFConsumerBaseV2Plus contract and remove the v1 VRFConsumerBase.sol import. This contract includes the fulfillRandomWords function.

3. Import the VRF v2.5 coordinator, VRFCoordinatorV2_5. This interface includes the new requestRandomWords function.

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

5. Change requestRandomness function calls to requestRandomWords. The requestRandomWords function requires several additional parameters. Make sure to include the extraArgs part of the VRFV2PlusClient.RandomWordsRequest mapping, and use nativePayment to 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}))
       })
   );
   

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

To modify your existing smart contract code to work with VRF v2, complete the following changes. See the Migration from V2 guide for an example.

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

2. Add a VRFV2WrapperConsumerBase constructor, passing in the VRF wrapper address for the network you're using.

3. You can still call the requestRandomness function. However, the v2.5 requestRandomness function requires several different parameters (callbackGasLimit , requestConfirmations , numWords and extraArgs). See the Supported networks page to adjust them for your own needs.

   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. Change fulfillRandomness function calls to fulfillRandomWords. Update the call to handle the returned uint256[] array instead of the single uint256 variable.