Welcome to Proof of Play’s Verified Random Number Generator (vRNG) documentation. We’ve been running this tool at scale for Pirate Nation on Polygon, Arbitrum Nova, Proof of Play Apex, Proof of Play Boss with over 100 million random numbers served.

Our vRNG is also deployed to ApeChain, Abstract, Avalanche, BASE, Berachain, BNB Chain, and HyperEVM.

Because speed matters, we’re heavily focused on serving random numbers as fast as possible to reduce latency in applications. On chains like Proof of Play Apex and Boss we see average times from requested to delivered in as fast as 900ms. We also deeply care about reliability and scaleabily because at peak, our vRNG was performing 1.5M transactions per day in Pirate Nation without issue.

​

Registration

During early access, all users of the Verified Random Number Generator system must be manually registered. In order to use it your contract address must be approved, otherwise any requests will revert.

​

Supported Networks

​

Usage

​

Requesting a Random Number

The following interface provides a method for requesting random numbers.

Your contract can call the VRFSystem deployed on each chain. You can optionally provide a traceId, which will be annotated to each event (Useful if you have one transaction that does many steps, users can trace their transactions on chain). This is not required and can be left as 0.

// SPDX-License-Identifier: MIT LICENSE

pragma solidity ^0.8.26;

uint256 constant ID = uint256(keccak256('com.proofofplay.vrfsystem.v1'));

interface IVRFSystem {
  /**
   * Starts a VRF random number request
   *
   * @param traceId Optional Id to use when tracing the request
   * @return requestId for the random number, will be passed to the callback contract
   */
  function requestRandomNumberWithTraceId(uint256 traceId) external returns (uint256);
}

​

Random Number Callbacks

Every random number requested is delivered as soon as the first available number from drand is available to be delievered. This can take as long as 3 seconds.

// SPDX-License-Identifier: MIT LICENSE

pragma solidity ^0.8.26;

interface IVRFSystemCallback {
  /**
   * Callback for when a Random Number is delivered
   *
   * @param requestId     Id of the request
   * @param randomNumber   Random number that was generated by the Verified Random Number Generator Tool
   */
  function randomNumberCallback(uint256 requestId, uint256 randomNumber) external;
}

​

What if I want to have different numbers in the same 3 second window?

By default, we deliver the same number to all requests inside the same 3 second window that drand provides. This is great to be able to verify, but if you would like to have users all have different numbers over this time period, we recommend you add a source of entropy.

Here’s a couple of examples of having unique random numbers per transaction.

// Add the requestId (Most Gas Efficient)
uint256 newRandomNumber = requestId + randomNumber;

// Hash with requestId
uint256 newRandomNumber = uint256(keccak256(abi.encodePacked(requestId, randomNumber)

// More expensive, but more normalized, hash based on requestId in last 256 block hashes
uint256 newRandomNumber = uint256(keccak256(abi.encodePacked(blockhash(block.number - (requestId % 256)), randomNumber)

Note: These are not guaranteed to be normalized, but will retain the randomness properties of the above. We recommend adjusting to your liking to achieve more or less normalized (for instance, adding sequenceId to the randomNumber would be very skewed, whereas using a blockhash would be very normalized).

If you would like to have different numbers on the same block, recommend re-hashing the same number multiple times in the same transaction

functionThatUsesNumber(randomNumber);
randomNumber = uint256(keccak256(randomNumber));
functionThatUsesNumber(randomNumber);

​

What if I want to have different numbers in the same transaction?

By default, we will give you only one number per transaction. We encourage developers to use this number to dervive other numbers from this to create new numbers.

//Example 1: Keccak dervive
uint256 randomNumber = 12398012938091283113928;
uint256 randomNumber2 = keccak256(randomNumber);
uint256 randomNumber3 = keccak256(randomNumber2);

//Example 2: Split the number and use both sides
uint256 randomNumber = 234345234523452345;
uint256 randomNumber2 = randomNumber >> 128;  // Take upper 128 bits
uint256 randomNumber3 = randomNumber & ((1 << 128) - 1); // Take lower 128 bits

​

Blockchain Events

The contract will emit the following events.

/// @notice Emitted when a random number request is initiated
/// @param requestId The unique identifier for the random number request
/// @param callbackAddress The address the random number is requested to
/// @param traceId The trace ID used to track the request across transactions (0 if no trace ID)
event RandomNumberRequested(uint256 indexed requestId, address indexed callbackAddress, uint256 indexed traceId);

/// @notice Emitted when a random number is successfully delivered
/// @param requestId The unique identifier of the fulfilled request
/// @param callbackAddress the adddress was random number is requested to
/// @param traceId The trace ID associated with the request
/// @param number The round number that was used for the random number
/// @param randomNumber The random number that was generated
event RandomNumberDelivered(uint256 indexed requestId, address indexed callbackAddress, uint256 indexed traceId, uint256 roundNumber, uint256 randomNumber);

You can query these events on RPC level to see if they were delivered or use the block explorer to view a stream of events.

​

Verifying the round number / random number with drand

If you want to verify the random number, you can check directly with drand for this. We use drand’s quicknet for this.

For instance, to see the roundNumber 11:

GET https://api.drand.sh/52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971/public/11

{
  "round": 11,
  "randomness": "ebdcbfe855d10c56db22455fa5a18963c1f62d85f859c35c310273449b49d284",
  "signature": "163d14081e191a3f5d81e2f580eab591ea608402fda4f6e44b5a0bde11e368070e77d07ad3240726ea33e410c84d4b09ea0a4a0291f6c3c485d8630e1c0edf0a"
}

We can see here the random number in hex is ebdcbfe855d10c56db22455fa5a18963c1f62d85f859c35c310273449b49d284

​

Manual Retries with EIP712 signatures

🧪 This feature is in Preview. Please contact us on slack if you wish to use this.

In a very rare instance, you may see random numbers fail to be delivered. In most cases this will be an issue on the contract side.

In these situations, you can choose to deliver this number yourself. First you should request the EIP712 signature from our API servers which you can use to deliver the random nummber directly to the contract on the blockchain.

Request:

Try the API!

GET https://vrf.proofofplay.com/v1/vrf/{chainId}/{txHash}

Response:

{
  "requestId": Number,
  "roundNumber": Number,
  "randomNumber": BigInt,
  "signature": String // bytes data of signature
}

With the response you can now call the VRFSystem contract

vrf.deliverSignedRandomNumber(requestId, roundNumber, randomNumber, signature);

⚠️ Warning: You will be racing the normal relay flow. If you get a tx revert with InvalidRequestId, this means that a relay has already delivered this random number. Random numbers can only be delivered once.