> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roll.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# How roll.codes works

> Understand the request, verification, and callback flow behind roll.codes randomness delivery.

roll.codes delivers one verifiable random number to your Solidity contract through an asynchronous callback. You use the coordinator that roll.codes deploys and operates on the target network.

## What happens in the flow

<Steps>
  <Step title="Your contract requests randomness">
    Your consumer contract calls `requestRandomNumberWithTraceId` on the VRF system and pays the exact fee returned by `requestFee()`.
  </Step>

  <Step title="The request waits for fulfillment">
    The coordinator records request state while the off-chain system gathers the round data needed to fulfill the request.
  </Step>

  <Step title="roll.codes calls your callback">
    The coordinator calls your `randomNumberCallback(uint256 requestId, uint256 randomNumber)` function with the delivered value.
  </Step>

  <Step title="Your contract settles application logic">
    Your callback validates the caller, loads stored request state, and applies the random number to your game or app logic.
  </Step>
</Steps>

## What you own as the integrator

* Store request metadata as soon as `requestRandomNumber` returns.
* 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 base `randomNumber`. 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 `requestId` per 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

<CardGroup cols={2}>
  <Card title="Request lifecycle" icon="git-branch" href="/concepts/request-lifecycle">
    Learn the states a request moves through from creation to terminal settlement.
  </Card>

  <Card title="Callback security" icon="shield-check" href="/concepts/callback-security">
    Review the callback invariants you should enforce in every consumer.
  </Card>

  <Card title="Integration pattern" icon="blocks" href="/contracts/integration-pattern">
    Start from a minimal consumer implementation you can copy into your contract.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build and deploy a working starter before customizing your own flow.
  </Card>
</CardGroup>