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

# Coordinator reference

> Reference for the public VRFSystem calls, callback interface, and events used by roll.codes consumers.

Use this page while implementing or reviewing a consumer contract that talks to the roll.codes hosted coordinator.

## `requestRandomNumberWithTraceId`

```solidity theme={null}
function requestRandomNumberWithTraceId(uint256 traceId) external payable returns (uint256 requestId);
```

Use this function to create a request for the calling contract. The callback target is always `msg.sender`.

You call the roll.codes coordinator that we deploy and maintain for your network. You do not deploy your own coordinator to use this interface.

### Parameters

* `traceId`: optional tracing ID that is echoed in `RandomNumberRequested` and `RandomNumberDelivered`

### Usage note

Send the exact fee returned by `requestFee()` in `msg.value`.

## `requestFee`

```solidity theme={null}
function requestFee() external view returns (uint256);
```

This is a roll.codes-specific behavior: `msg.value` must equal `requestFee()` when you create a request.

## `deliverSignedRandomNumber`

```solidity theme={null}
function deliverSignedRandomNumber(
    uint256 requestId,
    uint256 roundNumber,
    uint256 randomNumber,
    bytes calldata signature
) external;
```

This is the delivery entrypoint used by the relayer and by the manual retry flow. Consumer contracts do not call this function during normal request creation.

## `getRequest`

```solidity theme={null}
struct Request {
    address callbackAddress;
    uint256 traceId;
    uint64 requestedAt;
    uint64 fulfilledAt;
    RequestStatus status;
}
```

`status` is `None`, `Pending`, or `Fulfilled`.

## Consumer callback interface

```solidity theme={null}
interface IVRFSystemCallback {
    function randomNumberCallback(uint256 requestId, uint256 randomNumber) external;
}
```

Your callback should:

* authorize the coordinator as the caller
* look up request state by `requestId`
* reject duplicate settlement
* settle the outcome without unnecessary complexity

## Events you are likely to index

* `RandomNumberRequested`
* `RandomNumberDelivered`

These events are useful for apps, dashboards, and reconciliation jobs.

## Same-round randomness semantics

Requests delivered from the same drand round receive the same base `randomNumber`. If your app needs a distinct per-request value inside the same round, derive it locally from `requestId` and `randomNumber`.

## Related pages

<CardGroup cols={2}>
  <Card title="Integration pattern" icon="blocks" href="/contracts/integration-pattern">
    See a minimal consumer that uses this interface correctly.
  </Card>

  <Card title="Callback security" icon="shield-check" href="/concepts/callback-security">
    Apply the required caller and request-state checks in your callback.
  </Card>

  <Card title="Troubleshooting" icon="life-buoy" href="/faq/troubleshooting">
    Fix fee mismatches and callback failures with the reference beside you.
  </Card>
</CardGroup>