Contract API

Call the hub proxy for the selected chain. RUFF currently uses the contract name RandomnessHub and reports version 1.0.0.

Download the hub ABI · Solidity interface · Deployment reference

Request methods

All overloads are payable and return an assigned uint64 sequence. The caller must be a deployed consumer contract.

Method	Provider	User contribution	Callback budget
`requestV2()`	Hub	Zero	Tariff default
`requestV2(uint32 gasLimit)`	Hub	Zero	Requested gas or default if zero
`requestV2(address provider, uint32 gasLimit)`	Must equal hub	Zero	Requested gas or default if zero
`requestV2(address provider, bytes32 userRandomNumber, uint32 gasLimit)`	Must equal hub	Supplied value	Requested gas or default if zero

Acceptance fixes the lane, index, consumer, contribution, request block, callback gas, and fee paid. A request emits Requested.

Quote methods

Method	Result
`getFeeV2()`	`uint128` fee for the caller and default gas.
`getFeeV2(uint32 gasLimit)`	`uint128` fee for the caller and selected gas.
`getFeeV2(address provider, uint32 gasLimit)`	Same caller-specific fee; validates the provider.
`quote(address consumer, uint32 gasLimit)`	`(uint128 fee, uint32 callbackGas)` for an explicit consumer.
`getDefaultProvider()`	The hub proxy address.

Use quote from a frontend or another off-chain client. getFeeV2 called from an externally owned account quotes that account’s tariff, not a consumer contract’s custom tariff.

Request reads

enum Status { None, Pending, Fulfilled, Expired }

struct Request {
    address consumer;
    uint32 laneId;
    uint64 index;
    uint64 blockNumber;
    uint32 callbackGas;
    Status status;
    bool callbackFailed;
    uint128 feePaid;
    bytes32 userContribution;
}

Method	Result
`requestOf(uint64 sequence)`	Request struct; an unused sequence has status `None`.
`randomOf(uint64 sequence)`	Stored `bytes32`; inspect status first because zero is valid.
`nextSequenceNumber()`	Next unused sequence, not the last allocated sequence.
`pendingOf(address consumer)`	`uint32` pending count for the consumer.
`pendingTotal()`	`uint32` pending count across the hub.

Lane reads

struct Lane {
    bytes32 head;
    bytes32 anchor;
    uint64 anchorIndex;
    uint64 nextIndex;
    uint64 length;
}

nextIndex stores the highest allocated index; a new request takes nextIndex + 1.

Method	Result
`laneOf(uint32 laneId)`	Lane struct.
`checkpointOf(uint32 laneId, uint64 index)`	Stored checkpoint link.
`remaining(uint32 laneId)`	Number of unallocated links.
`activeLane()`	Active lane ID for new requests.
`laneCount()`	Number of published lanes.

Delivery and expiry

Method	Authorization	Effect
`fulfill(uint64 sequence, bytes32 seed)`	`isRelayer` address	Verify the effective seed, store a result, and attempt the callback.
`advanceAnchor(uint64 expiredSequence, bytes32 seed)`	`isRelayer` address	Advance through an allocated, expired request; no result is delivered.
`expire(uint64 sequence)`	Anyone	Close a Pending request whose age is greater than 8191 blocks.

fulfill and advanceAnchor are unavailable while paused. expire remains available. Expiry accepts no seed and does not enable public delivery.

Consumer callback

_entropyCallback(uint64 sequence, address provider, bytes32 random)

The provider is the hub. The callback is sent to the consumer stored in the request, with a bounded gas budget. Use IEntropyConsumer to authenticate the caller.

Configuration and administration

Read tariffOf(consumer), defaultTariff(), limits(), paused(), owner(), pendingOwner(), and isRelayer(account) for the current configuration. tariffOf also returns whether the tariff is custom.

Owner methods manage tariffs, limits, relayers, lane publication and activation, pause state, and withdrawals. accruedFees() and totalFeesEarned() report fee accounting. Ownership transfer uses a separate acceptance step. renounceOwnership() always reverts with OwnershipRenounceDisabled().

Implementation upgrades are controlled through the proxy’s administration path. They are separate from hub operational ownership. See Trust and security model.