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

​
requestRandomNumberWithTraceId

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

function requestFee() external view returns (uint256);
This is a roll.codes-specific behavior: msg.value must equal requestFee() when you create a request.

​
deliverSignedRandomNumber

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

struct Request {
    address callbackAddress;
    uint256 traceId;
    uint64 requestedAt;
    uint64 fulfilledAt;
    RequestStatus status;
}
status is None, Pending, or Fulfilled.

​
Consumer callback interface

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.

Integration pattern

See a minimal consumer that uses this interface correctly.

Callback security

Apply the required caller and request-state checks in your callback.

Troubleshooting

Fix fee mismatches and callback failures with the reference beside you.
Last modified on March 9, 2026