Skip to main content

Verifiable randomness (VRF)

A VRF consumer pays for random words, receives a request ID, then handles a coordinator-authenticated callback after a worker submits a valid proof. The JSN implementation includes Paintswap-derived secp256k1 proving and verification libraries. Application VRF is separate from the protocol's consensus randomness.

Consumer integration​

Public coordinator addresses, ABI and consumer SDK release details are TBD. The integration flow is:

  1. Commit the participant and action before requesting randomness.
  2. Obtain the coordinator's calculateRequestPriceNative quote for the callback gas and requested word count. Transaction gas is additional.
  3. Pay for the request and store its request ID against that action.
  4. Accept the result only through a coordinator-authenticated callback, then settle the matching action once.
  5. Define an expiry outcome for requests that receive no result.

Callbacks must authenticate their sender. Do not expose an unauthenticated game-settlement hook, allow a result to settle a different action or leave ambiguous outstanding requests.

Delivery and failure​

Base VRF requests expire after one day. Fulfillment is at-most-once. A consumer revert records CallbackFailed and pays the worker; it does not automatically retry the game's side effects. An insufficiently supplied callback-gas transaction reverts without consuming the request. After expiry, anyone can call cancelExpired, crediting the consumer; excess request payments and credits use withdrawCredits.

Keep callbacks bounded and avoid dependencies that routinely revert. Persist the request/result association before presenting a final game outcome. The World dice table is a sample consumer.

What verification guarantees​

A valid proof binds the result to the committed request and configured proving identity. It does not force the prover to respond or make withholding impossible. A single prover can predict its outputs and choose not to deliver. Worker failover is not threshold randomness. Financial games need explicit expiry/refund handling and a reviewed policy for non-delivery.