Quick start
Core concepts
Nodes
Building modules
API
SDK
Smart contract
Developer services
OKTC solutions
Resources

Direct funding method#

This guide explains how to generate random numbers using the Direct funding method. This method doesn’t require a subscription and is optimal for one-off requests for randomness. This method also works best for applications where your end-users must pay the fees for VRF because the cost of the request is determined at request time.

VRF Direct funding#

Unlike the subscription method, the Direct funding method does not require you to create subscriptions and pre-fund them. Instead, you must directly fund consuming contracts with OKT before they request randomness.

For OKTC VRF to fulfill your requests, you must have a sufficient amount of OKT in your consuming contract. Gas cost calculation includes the following variables:

  • Gas price: The current gas price, which fluctuates depending on network conditions.

  • Callback gas: The amount of gas used for the callback request that returns your requested random values.

  • Verification gas: The amount of gas used to verify randomness on-chain.

  • VRF coordinators for subscription funding are available on several networks. To see a list of coordinators for direct funding, see the Direct Funding Configurations page.

The gas price depends on current network conditions. The callback gas depends on your callback function and the number of random values in your request. You define the limits that you are willing to spend for the request with the following variable:

  • Callback gas limit: Specifies the maximum amount of gas you are willing to spend on the callback request. Define this limit by specifying the callbackGasLimit value in your request.

Because the consuming contract directly pays the OKT for the request, the cost is calculated during the request and not during the callback when the randomness is fulfilled. Test your callback function to learn how to correctly estimate the callback gas limit.

  • If the gas limit is underestimated, the callback fails and the consuming contract is still charged for the work done to generate the requested random values.
  • If the gas limit is overestimated, the callback function will be executed but your contract is not refunded for the excess gas amount that you paid.

Make sure that your consuming contracts are funded with enough OKT tokens to cover the transaction costs. If the consuming contract doesn’t have enough OKT tokens, your request will revert.

Request and receive data#

End to end diagram#

Two types of accounts exist in the OKT ecosystem:

  • EOA (Externally Owned Account): An externally owned account that has a private key and can control a smart contract. Transactions can be initiated only by EOAs.
  • Smart contract: A smart contract that does not have a private key and executes what it has been designed for as a decentralized application.

The OKTC VRF solution uses both off-chain and on-chain components:

  • VRF Wrapper (on-chain component): A wrapper for the VRF Coordinator that provides an interface for consuming contracts.
  • VRF Coordinator (on-chain component): A contract designed to interact with the VRF service. It emits an event when a request for randomness is made, and then verifies the random number and proof of how it was generated by the VRF service.
  • VRF service (off-chain component): Listens for requests by subscribing to the VRF Coordinator event logs and calculates a random number based on the block hash and nonce. The VRF service then sends a transaction to the VRFCoordinator including the random number and a proof of how it was generated.

Explanation#

The VRF wrapper calls the coordinator to process the request using the following steps:

  1. The consuming contract must inherit VRFWrapperConsumerBase and implement the fulfillRandomWords function, which is the callback VRF function. Submit your VRF request by calling the requestRandomness function in the VRFWrapperConsumerBase contract. Include the following parameters in your request:
  • requestConfirmations: The number of block confirmations the VRF service will wait to respond. The minimum and maximum confirmations for your network can be found here.
  • callbackGasLimit: The maximum amount of gas to pay for completing the callback VRF function.
  • numWords: The number of random numbers to request. You can find the maximum number of random values per request for your network in the Supported networks page.

  1. The consuming contract calls the VRFWrapper calculateRequestPrice function to estimate the total transaction cost to fulfill randomness. This triggers the VRF VRF Coordinator requestRandomWords function to request randomness. The final gas cost to fulfill randomness is estimated based on how much gas is expected for the verification and callback. The total gas cost in wei uses the following formula:

    (Gas price * (Verification gas + Callback gas limit + Wrapper gas Overhead)) = total gas cost

    A OKT premium is then added to the total gas cost. The premium is divided in two parts:

  • Wrapper premium: The premium percentage. You can find the percentage for your network in the [Supported networks](/dev/oktc-solutions/oktc-vrf/Direct-Funding Method/Supported-Networks/Supported-Networks) page.

  • Coordinator premium: A flat fee. This premium is defined in the fulfillmentFlatFeeOKTPPMTier1 parameter in millionths of OKT. You can find the flat fee of the coordinator for your network in the Supported networks page.

    ((total gas cost * Wrapper premium) + Coordinator premium) = total request cost
  1. The VRF coordinator emits an event.

  • The event is picked up by the VRF service and waits for the specified number of block confirmations to respond back to the VRF coordinator with the random values and a proof (requestConfirmations).

  • The VRF coordinator verifies the proof on-chain. Then, it calls back the wrapper contract fulfillRandomWords function.

  • Finally, the VRF Wrapper calls back your consuming contract.

Limits#

You can see the configuration for each network on the Supported networks page. You can also view the full configuration for each VRF Wrapper contract directly in OKLink. As an example, view the OKT Mainnet VRF Wrapper contract configuration by calling getConfig function.

Each wrapper has a maxNumWords parameter that limits the maximum number of random values you can receive in each request.

The maximum allowed callbackGasLimit value for your requests is defined in the Coordinator contract supported networks page. Because the VRF Wrapper adds an overhead, your callbackGasLimit must not exceed maxGasLimit - wrapperGasOverhead.

What’s next#