What happens in the flow
Your contract requests randomness
Your consumer contract calls
requestRandomNumberWithTraceId on the VRF system and pays the exact fee returned by requestFee().The request waits for fulfillment
The coordinator records request state while the off-chain system gathers the round data needed to fulfill the request.
roll.codes calls your callback
The coordinator calls your
randomNumberCallback(uint256 requestId, uint256 randomNumber) function with the delivered value.What you own as the integrator
- Store request metadata as soon as
requestRandomNumberreturns. - Reject callbacks from any address other than the coordinator.
- Reject unknown or already-settled request IDs.
- Keep callback logic deterministic and cheap enough to fit inside your chosen callback gas limit.
What roll.codes operates
- the coordinator contract you call
- the off-chain system that prepares fulfillment
- the callback delivery flow into your consumer
Same-round randomness
Requests fulfilled from the same drand round receive the same baserandomNumber. If your app needs a distinct value per request, derive it locally from requestId and randomNumber.
Why the flow is asynchronous
The request and callback happen in separate transactions. That separation lets the coordinator deliver a verified result later, but it also means you need to design around pending state. Typical integration patterns include:- storing a
requestIdper player or session - marking requests as settled only inside the callback
- rendering pending state in your app until fulfillment lands
Choose the right page next
Request lifecycle
Learn the states a request moves through from creation to terminal settlement.
Callback security
Review the callback invariants you should enforce in every consumer.
Integration pattern
Start from a minimal consumer implementation you can copy into your contract.
Quickstart
Build and deploy a working starter before customizing your own flow.