Skip to main content
Use this page to reason about request state in your consumer and in your application UI.

​
Lifecycle at a glance

  1. Your contract submits a request and receives a requestId.
  2. Your contract stores any metadata needed to settle that request later.
  3. The coordinator progresses the request toward fulfillment.
  4. Your callback receives requestId and randomNumber.
  5. Your consumer marks the request as settled.

​
What to store when a request is created

Store enough information to finish the user action when the callback arrives. Typical fields include:
  • the player or account that initiated the request
  • the game, round, or session identifier
  • whether the request has already been settled
  • any amount, guess, or configuration needed to compute the outcome

​
What can go wrong

A request can stay pending longer than your frontend expects. Design the user experience around eventual completion rather than synchronous settlement.
Common failure modes:
  • your contract never stored request metadata
  • the callback reverts because request state is incomplete
  • callback logic is too expensive for the selected gas limit
  • your app assumes fulfillment happens immediately after the request transaction

​
Design guidance

  • Treat requestId as the join key between request creation and callback settlement.
  • Emit or index request IDs in your app layer so you can reconcile status later.
  • Keep the callback focused on validation, state transition, and outcome settlement.

Integration pattern

Copy a minimal implementation that stores and settles request state safely.

Consumer patterns

See common ways to map request IDs back to users and outcomes.

Troubleshooting

Diagnose requests that stay pending or callbacks that never settle.
Last modified on March 6, 2026