> ## 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.

# Consumer patterns

> Use these request-tracking and settlement patterns to keep roll.codes consumers easy to reason about.

These patterns help you adapt the minimal integration flow to real application state.

## Pattern 1: Derive a bounded outcome in the callback

Use the delivered `randomNumber` to derive the game-specific result only after the callback arrives.

```solidity theme={null}
uint8 roll = uint8((randomNumber % 6) + 1);
bool won = roll == guess;
```

This keeps the outcome tied to the delivered value and avoids storing redundant derived state too early.

## Pattern 2: Track requests per user or session

Map the returned `requestId` to the state you need for settlement.

```solidity theme={null}
mapping(address => uint256) public latestRequestIdByPlayer;
mapping(uint256 => Match) public matchesByRequestId;
```

Store this metadata immediately after `requestRandomNumber` returns.

## Pattern 3: Keep callback checks at the top

Fail fast before you touch application logic.

```solidity theme={null}
if (msg.sender != address(coordinator)) revert Unauthorized();
if (matchData.player == address(0)) revert RequestNotFound(requestId);
if (matchData.settled) revert AlreadySettled(requestId);
```

Put these checks before outcome calculation or transfers.

## Pattern 4: Separate pending state from settled state

Model the request as pending until the callback succeeds. Your app and frontend can then render a clear in-progress state instead of assuming synchronous completion.

This is especially useful when:

* a player can create multiple requests over time
* you need to reconcile requests from emitted events
* you want to retry UI polling or indexing until the callback lands

## Choosing a pattern

<CardGroup cols={2}>
  <Card title="Simple game outcome" icon="dice-3">
    Use a single mapping from `requestId` to a compact pending struct.
  </Card>

  <Card title="Session-based app" icon="route">
    Track both `requestId -> session` and `user -> latest requestId` so your frontend can reconcile state quickly.
  </Card>
</CardGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Integration pattern" icon="blocks" href="/contracts/integration-pattern">
    Start from the minimal consumer before adding extra state.
  </Card>

  <Card title="Request lifecycle" icon="git-branch" href="/concepts/request-lifecycle">
    Understand why pending state matters for asynchronous settlement.
  </Card>

  <Card title="Coordinator reference" icon="file-text" href="/contracts/coordinator-reference">
    Check the request interface and fee call while adapting these patterns.
  </Card>
</CardGroup>