Introduction to Subscriptions

Subscriptions

The VRF Oracle allows users to create subscriptions to fund on-chain requests for random numbers. Subscriptions have the following components:

• Subscription ID
  • A 64-bit unsigned integer that uniquely identifies the subscription
  • Used to call oracle functions to request random numbers
• Subscription Account
  • Holds tokens to fund requests
  • Tokens are made available to fund requests from registered consumers
• Subscription Owner
  • The wallet address that created the subscription
  • Has management privileges like adding/removing consumers and deleting subscription
  • Anyone can add tokens to a subscription's balance, not just the owner
• Consumers
  • Consumer contracts that are approved to use funding from the subscription
  • Requests from consumer contracts will be funded until the balance runs out
• Balance
  • The token balance maintained to pay for requests
  • Requests are funded until the balance runs out
  • The owner should maintain sufficient funds to pay for requests and keep applications running

For Pythia VRF to fulfill your requests, you must maintain a sufficient amount of token 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.

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.

Request and Receive Data

Requests to VRF follow the request and receive data cycle. This end-to-end diagram shows each step in the lifecycle of a VRF subscription request, and registering a smart contract with a VRF subscription account:

Two types of accounts exist in the Ethereum ecosystem, and both are used in VRF:

• 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 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.

Setup Consumer Contract

Set up your consuming contract:

1. Your contract must inherit VRFConsumer.
2. Your contract must implement the fulfillRandomWords function, which is the callback VRF function. Here, you add logic to handle the random values after they are returned to your contract.
3. Submit your VRF request by calling requestRandomWords of the VRF Coordinator. Include the following parameters in your request:

• 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.
• subscriptionId: The subscription ID that the consuming contract is registered to. Funds are deducted from this subscription.
• numberOfRandoms: The number of random numbers to request. The maximum random values that can be requested for your network can be found here.
• callbackGasLimit: The maximum amount of gas that can be used for the callback function. This limit is set to prevent excessive gas usage. If the callback function requires more gas than this limit, the request will fail. The gas limit should be set according to the complexity of your callback function.

How VRF processes your request

After you submit your request, it is processed using the Request & Receive Data cycle. The VRF coordinator processes the request and determines the final charge to your subscription using the following steps:

• The VRF coordinator emits an event.
• The VRF service picks up the event and respond back to the VRF coordinator with the random values and a proof (requestConfirmations).