Migration to dVRF 3.0 on EVM (thirdparty)

This page introduces the new features of Supra dVRF 3.0 and provides migration steps. Clients are encouraged to migrate at their convenience before the VRF 2.0 contracts are phased out soon.

Why Migrate to dVRF 3.0?

Moving to VRF 3.0 offers several key advantages over the previous version, especially for users focused on reliability, customization, and future-proofing their integration.

dVRF 3.0 introduces major upgrades focused on reliability, configurability, and developer experience.

Check all the New Features & Benefits introduced in dVRF 3.0 Below:

What’s New in dVRF 3.0?

Request Retry Mechanism

Failed callback transactions (due to insufficient gas) are automatically retried every 6 hours, for up to 48 hours. Greatly improves reliability without manual resubmission.

Custom Callback Gas Settings

Clients can now set: callbackGasPrice and callbackGasLimit. This gives full control over callback execution costs and helps adapt to varying network conditions.

Request & Response Tracking

Every client now has counters to track: Total RNG requests made, and total responses fulfilled.

Self-whitelisting

Clients can whitelist themselves, specifying “maxGasPrice” and “maxGasLimit” which acts as default values for their contracts.

On-chain Request Validation

A hash of request parameters is stored and validated during callbacks for data integrity: Includes nonce, caller, clientSeed, gas details, etc. It prevents tampering and enhances security.

Upgradeable & Migration-Friendly Deposit Contract

The Deposit contract is now upgradeable and backward-compatible with older versions. It supports seamless client migration, dynamic gas balance requirements, auto-whitelisting during migration

Dynamic Minimum Balance Enforcement

“minBalanceLimit” for a client is calculated dynamically as follows:

uint128 minBalanceLimit = minRequests * _maxGasPrice * (_maxGasLimit +  verificationGasValue);

Introduction of “supraMinimumPerTx”

It is the gas used by 'generateRngCallback()' for transaction initialization and calldata. If a transaction fails due to insufficient funds, “supraMinimumPerTx” is deducted from the client.

Client removal

removeClientFromWhitelist(address _clientAddress, bool _forceRemove) removes the client and their contracts. It transfers back the client fund if no pending requests exist or transfers the client fund to “supraFund” if pending requests exist and “_forceRemove” is true.

Benefits of dVRF 3.0

Improved Reliability with Retry Mechanism

If a random number callback fails due to insufficient gas funds, the RequestRetry mechanism caches it and retries every 6 hours (for up to 48 hours). This significantly reduces the chance of missed callbacks.

Custom Gas Controls for Callback Transactions

Users can now specify both callbackGasPrice and callbackGasLimit, giving more control over costs and ensuring successful delivery during network volatility.

Enhanced Security & Integrity

On-chain calldata hash verification prevents tampering and validates the request origin, seed, and other key parameters before fulfilling a callback.

Dynamic Minimum Balance Enforcement

Prevents underfunded requests by enforcing a minimum balance, calculated dynamically.

Self-whitelisting

Clients can whitelist themselves, specifying “maxGasPrice” and “maxGasLimit” which acts as default values for their contracts

Who Needs to Migrate?

You need to migrate to VRF 3.0 if you are currently using VRF 2 and want access to VRF 3.0 features and improvements.

---

Migration Guide

Code for existing clients to Migrate

Before migrating, the client must withdraw their existing funds from the old Deposit contract.

The client must decide the following values:

1. maxGasPrice— the maximum callback gas price they are willing to pay

2. maxGasLimit— the maximum callback gas limit with which the callback transaction can get executed.

The client can call getMinBalanceLimit(maxGasPrice, maxGasLimit) to compute their minimum balance required:

function getMinBalanceLimit(uint128 _maxGasPrice, uint128 _maxGasLimit)

external view returns (uint128);

You can learn more about the maxGasPrice & maxGasLimit functions from Here.

Interface to interact with the Deposit contract

interface IDeposit {
   function getMinBalanceLimit(uint128 maxGasPrice, uint128 maxGasLimit) external view returns (uint128);
}
contract MigrateToVRF3 {
   IDeposit public deposit;  // The address of the Deposit contract (VRF 3.0)
   constructor(address _deposit) {
       deposit = IDeposit(_deposit);
   }
   /// @notice Get the minimum balance required.
   function checkMinRequiredBalance(uint128 maxGasPrice, uint128 maxGasLimit) external view returns (uint128) {
       return deposit.getMinBalanceLimit(maxGasPrice, maxGasLimit);
   } }

Clients need to call “migrateClient(uint128 _maxGasPrice, uint128 _maxGasLimit) payable”, specifying the max gas price, max gas limit for their contracts and sending along the ether to deposit. During the migration process, users must ensure their deposit amount is significantly higher than the minimum balance returned by the function: deposit.getMinBalanceLimit(maxGasPrice, maxGasLimit) The Minimum Balance Limit is the threshold below which the client can no longer issue new VRF requests. If the client’s balance drops to or near this limit, VRF functionality will be blocked, potentially affecting operations or availability. They can only migrate before the end of migration time.

function migrateClient(uint128 _maxGasPrice, uint128 _maxGasLimit) external payable;

Please refer to THIS REPO for Sample Contract with VRF3 Implementation.

---

Self-whitelisting Guide

Via Deposit ContractFunction

Requirements:

• You must not already be whitelisted.

• _maxGasPrice and _maxGasLimit must be greater than 0.

Clients can call the “addClientToWhitelist” function to whitelist themselves:

function addClientToWhitelist(uint128 _maxGasPrice, uint128 _maxGasLimit) 
external;

Via Subscription Manager

Whitelist Your Consumer Contracts

The parameter this function takes is the User’s contract address along with callbackGasPrice and callbackGasLimit for the contract which should be smaller than the maxGasPriceand maxGasLimit respectively.

addContractToWhitelist(address _contractAddress, uint128 _callbackGasPrice, uint128 _callbackGasLimit)

You can learn more about the callbackGasPrice and callbackGasLimit functions from Here.

---

Comparing dVRF 2 vs dVRF 3.0

Feature	dVRF 2	dVRF 3
Client Whitelisting	Manual only (admin-controlled)	Self-whitelisting enabled with maxGasPrice and maxGasLimit inputs
Min Balance Calculation	Static or fixed value	Dynamically computed
Upgradeable Contracts	Only Generator	Generator and Deposit
Custom Gas Config for Callbacks	Not available	Fully configurable per client and per contract (callbackGasPrice, callbackGasLimit)
Fund Locking for Pending Requests	Funds always withdrawable	Funds locked if there are pending RNG requests
Request Retry Mechanism	Not available	Failed RNG callbacks due to low balance retried for 48 hours
Backward Compatibility	Not applicable	Generator and Deposit allow compatibility with older structure
On chain storing calldata hash of request	Only validated on chain	Stored on chain and validated also on chain

---

Functions Introduced in dVRF 3

Function Name	Contract	Utility
addClientToWhitelist(uint128, uint128)	Deposit	Allows new clients to self-whitelist, specifying their max gas price and gas limit.
getMinBalanceLimit(uint128, uint128)	Deposit	Returns the minimum balance required to maintain based on client’s gas settings.
addContractToWhitelist(address, uint128, uint128)	Deposit	Allows whitelisted clients to add their contract while specifying the callback gas price and callback gas limit.
withdrawFundClient(uint128)	Deposit	Allows whitelisted clients to withdraw their funds if they don’t have any pending requests.
getContractDetails(address) external view returns (uint128, uint128)	Deposit	Returns callback gas price and callback gas limit of a whitelisted contract.
checkMinBalanceClient(address) public view returns (uint128)	Deposit	Returns the minimum balance limit for a given client address.
checkMaxGasPriceClient(address) public view returns (uint128)	Deposit	Returns the 'maxGasPrice' for a given client address.
checkMaxGasLimitClient(address) public view returns (uint128)	Deposit	Returns the 'maxGasLimit' for a given client address.
updateMaxGasPrice(uint128)	Deposit	Allows a whitelisted client to update their maxGasPrice, which impacts the minBalanceLimit.
updateMaxGasLimit(uint128)	Deposit	Allows a whitelisted client to update their maxGasLimit, which affects the minBalanceLimit.
updateCallbackGasPrice(address, uint128)	Deposit	Allows clients to set callbackGasPrice for specific contracts.
updateCallbackGasLimit(address, uint128)	Deposit	Allows clients to set callbackGasLimit for specific contracts.
migrateClient(uint128, uint128)	Deposit	Enables existing clients to migrate their subscription and settings from VRF 2 to VRF 3.0.