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

Subscription method#

Subscriptions#

VRF requests receive funding from subscription accounts. The Subscription Manager lets you create an account and pre-pay for VRF , so you don’t provide funding each time your application requests randomness. This reduces the total gas cost to use VRF . It also provides a simple way to fund your use of OKTC products from a single location, so you don’t have to manage multiple wallets across several different systems and applications.

Subscriptions have the following core concepts:

  • Subscription id: 64-bit unsigned integer representing the unique identifier of the subscription.
  • Subscription accounts: An account that holds OKT tokens and makes them available to fund requests to OKTC VRF coordinators.
  • Subscription owner: The wallet address that creates and manages a subscription account. Any account can add OKT to the subscription balance, but only the owner can add approved consuming contracts or withdraw funds.
  • Consumers: Consuming contracts that are approved to use funding from your subscription account.
  • Subscription balance: The amount of OKT maintained on your subscription account. Requests from consuming contracts will continue to be funded until the balance runs out, so be sure to maintain sufficient funds in your subscription balance to pay for the requests and keep your applications running.

For OKTC VRF to fulfill your requests, you must maintain a sufficient amount of OKT in your subscription balance. 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.

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. The cost of each request is final only after the transaction is complete, but you define the limits you are willing to spend for the request with the following variables:

  • Gas lane: The maximum gas price you are willing to pay for a request in wei. Define this limit by specifying the appropriate keyHash in your request. The limits of each gas lane are important for handling gas price spikes when OKTC VRF bumps the gas price to fulfill your request quickly.
  • 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.

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 only be initiated by EOAs.
  • Smart contract: A 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 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 coordinator processes the request and determines the final charge to your subscription using the following steps:

  1. The consuming contract must inherit VRFConsumerBase and implement the fulfillRandomWords function, which is the callback VRF function. Submit your VRF request by calling requestRandomWords of the VRF Coordinator with:
  • keyHash: Identifier that maps to a job and a private key on the VRF service and that represents a specified gas lane. If your request is urgent, specify a gas lane with a higher gas price limit. The configuration for your network can be found here.
  • s_subscriptionId: The subscription ID that the consuming contract is registered to. OKT funds are deducted from this subscription.
  • 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 a user is willing to pay for completing the callback VRF function. Note that you cannot put a value larger than maxGasLimit of the VRF Coordinator contract (read coordinator contract limits for more details).
  • numWords: The number of random numbers to request. The maximum random values that can be requested for your network can be found here.

  1. The VRF coordinator emits an event.

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

  3. The VRF coordinator verifies the proof on-chain then calls back the consuming contract fulfillRandomWords function. After the request is complete, the final gas cost is recorded based on how much gas is required for the verification and callback. The total gas cost in wei for your request uses the following formula:

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

    The OKT premium is added to the total gas cost. The premium is defined in the coordinator contract with the fulfillmentFlatFeeOKTPPMTier1 parameter in millionths of OKT.

    (total gas cost + OKT premium) = total request cost

    The total request cost is charged to your subscription balance.

Limits#

OKTC VRF has some subscription limits and coordinator contract limits.

Subscription limits#

Each subscription has the following limits:

  • Each subscription supports up to 100 consuming contracts. If you need more than 100 consuming contracts, create multiple subscriptions.

Coordinator contract limits#

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

  • Each coordinator has a MAX_NUM_WORDS parameter that limits the maximum number of random values you can receive in each request.
  • Each coordinator has a maxGasLimit parameter, which is the maximum allowed callbackGasLimit value for your requests. You must specify a sufficient callbackGasLimit to fund the callback request to your consuming contract. This depends on the number of random values you request and how you process them in your fulfillRandomWords() function. If your callbackGasLimit is not sufficient, the callback fails but your subscription is still charged for the work done to generate your requested random values.

What’s next#