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.
What is 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.
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:
maxGasPrice— the maximum callback gas price they are willing to paymaxGasLimit— 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
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 maxGasPrice and 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 with maxGasPrice and maxGasLimit |
| Min Balance Calculation | Static or fixed value | Dynamically computed |
| Upgradeable Contracts | Only Generator | Generator and Deposit |
| Custom Gas Config for Callbacks | Not available | Configurable per client & contract (callbackGasPrice, callbackGasLimit) |
| Fund Locking for Pending Requests | Funds always withdrawable | Funds locked if pending RNG requests exist |
| Request Retry Mechanism | Not available | Failed callbacks retried for 48 hours |
| Backward Compatibility | Not applicable | Supported via Generator and Deposit |
| On-chain Calldata Hash Storage | Only validated on-chain | Stored and validated 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. |