Quiver API reference
Complete reference for the on-chain interface (IQuiverCoordinator), the consumer
callback (IQuiverConsumer / QuiverConsumer), the data types, events, and errors.
Signatures are authoritative in src/interfaces/.
IQuiverCoordinator
Randomness — requester functions
request(address provider, bytes32 userCommitment, bool useBlockhash) payable → uint64
Pull flow. Reserves the next sequence number from provider. userCommitment is
keccak256(userRandomNumber); keep userRandomNumber secret. Set useBlockhash to fold
blockhash(requestBlock) into the result (reveal within 256 blocks). Requires
msg.value ≥ getFee(provider); overpayment is refunded. Returns the assigned sequence
number. Reverts: ProviderNotRegistered, ProviderChainExhausted, TooManyHashes,
InsufficientFee. Blocked while paused.
requestWithCallback(address provider, bytes32 userRandomNumber) payable → uint64
Push flow. Commits keccak256(userRandomNumber) and emits the raw userRandomNumber for
the keeper. The caller should implement IQuiverConsumer. Same fee rules and reverts as
request. Returns the assigned sequence number.
reveal(address provider, uint64 sequenceNumber, bytes32 userRevelation, bytes32 providerRevelation) → bytes32
Completes a pull-flow request and returns the random number. Verifies both revelations,
advances the provider anchor, deletes the request. Reverts: NoSuchRequest,
RequestCallbackMismatch(true) (if it was a callback request), IncorrectUserRevelation,
IncorrectProviderRevelation. nonReentrant.
revealWithCallback(address provider, uint64 sequenceNumber, bytes32 userRandomNumber, bytes32 providerRevelation)
Completes a push-flow request and delivers randomness to the requester's
quiverCallback. On callback revert/OOG, buffers the value (CallbackFailed) instead of
reverting the whole tx. Reverts: NoSuchRequest, RequestCallbackMismatch(false),
IncorrectUserRevelation, IncorrectProviderRevelation. nonReentrant.
retryCallback(address provider, uint64 sequenceNumber)
Re-delivers buffered randomness for a previously-failed callback. Reverts
NoFailedCallback if none. If the callback reverts again, the whole tx reverts and the
buffer is preserved. nonReentrant.
Provider management
register(uint128 feeInWei, bytes32 commitment, bytes commitmentMetadata, uint64 chainLength, uint64 maxNumHashes, bytes uri)
Registers msg.sender as a provider. commitment = keccak256^chainLength(seed).
chainLength ≥ 2; 1 ≤ maxNumHashes ≤ 10_000. Reverts ProviderAlreadyRegistered,
InvalidChainLength, InvalidMaxNumHashes.
rotateCommitment(bytes32 newCommitment, bytes commitmentMetadata, uint64 newChainLength, bytes uri)
Rotates msg.sender onto a fresh chain, anchored at sequenceNumber - 1. In-flight
requests are unaffected. Reverts ProviderNotRegistered, InvalidChainLength.
setProviderFee(uint128) / setProviderFeeAsFeeManager(address, uint128)
Update a provider's per-request fee — by the provider itself, or its delegated fee
manager. Emits ProviderFeeUpdated.
setFeeManager(address feeManager)
Delegate fee-setting and withdrawals for msg.sender's provider. Emits
ProviderFeeManagerUpdated.
withdraw(uint128 amount) / withdrawAsFeeManager(address provider, uint128 amount)
Withdraw accrued provider fees to msg.sender. Reverts InsufficientAccruedFees,
NotFeeManager. nonReentrant.
Administration (onlyOwner)
| Function | Effect |
|---|---|
setProtocolFee(uint128) | Set the protocol fee added to every request |
withdrawProtocolFees(address to, uint128 amount) | Withdraw accrued protocol fees |
pause() / unpause() | Halt / resume new requests (reveals stay enabled) |
Ownership is Ownable2Step — transfers require the new owner to accept.
Views
| Function | Returns |
|---|---|
getFee(address provider) | provider fee + protocol fee (wei) |
getProtocolFee() | protocol fee component |
getAccruedProtocolFees() | withdrawable protocol fees |
getProviderInfo(address) | full ProviderInfo struct |
getProviderSequenceNumber(address) | next sequence number |
getRequest(address, uint64) | the Request struct (zeroed if none) |
getFailedCallback(address, uint64) | (bool exists, bytes32 randomNumber) |
constructUserCommitment(bytes32) | keccak256(abi.encodePacked(userRandomNumber)) |
combineRandomValues(bytes32,bytes32,bytes32) | keccak256(abi.encodePacked(u,p,b)) |
Constants
| Name | Value | Meaning |
|---|---|---|
MAX_NUM_HASHES | 10_000 | ceiling on a provider's maxNumHashes |
MIN_CHAIN_LENGTH | 2 | minimum registrable chain length |
IQuiverConsumer
quiverCallback(uint64 sequenceNumber, address provider, bytes32 randomNumber)
Implement to receive push-flow randomness. Must require
msg.sender == coordinator. Prefer inheriting QuiverConsumer, which enforces this and
dispatches to _fulfillRandomness.
QuiverConsumer (abstract base)
| Member | Purpose |
|---|---|
constructor(address quiver, address provider) | Bind coordinator + default provider |
_requestRandomness(bytes32 userRandom) → uint64 | Draw from the default provider, paying the fee |
_requestRandomness(address provider, bytes32 userRandom) → uint64 | Draw from a specific provider |
_fulfillRandomness(uint64 seq, address provider, bytes32 rnd) | override — your logic |
_randomnessFee() → uint128 | Fee for the default provider |
getCoordinator() → address / getProvider() → address | Bound addresses |
Data types (QuiverStructs)
ProviderInfo
feeInWei, accruedFeesInWei, originalCommitment, currentCommitment,
originalChainLength, currentCommitmentSequenceNumber, sequenceNumber,
endSequenceNumber, maxNumHashes, feeManager, uri, commitmentMetadata.
Request
provider, sequenceNumber, numHashes, userCommitment, providerCommitment
(verification anchor), requester, blockNumber, useBlockhash, isRequestWithCallback.
A zero provider means "no active request".
FailedCallback
randomNumber, requester, exists.
Events
| Event | When |
|---|---|
ProviderRegistered(provider, feeInWei, commitment, chainLength, maxNumHashes) | register |
ProviderCommitmentRotated(provider, newCommitment, newChainLength, anchorSequenceNumber) | rotateCommitment |
ProviderFeeUpdated(provider, oldFeeInWei, newFeeInWei) | fee change |
ProviderFeeManagerUpdated(provider, feeManager) | delegate change |
ProviderWithdrawal(provider, to, amount) | fee withdrawal |
RandomnessRequested(provider, requester, sequenceNumber, userContribution, numHashes, withCallback, useBlockhash) | a request. userContribution = commitment (pull) or raw value (callback) |
RandomnessRevealed(provider, sequenceNumber, requester, randomNumber, userRevelation, providerRevelation) | a reveal |
CallbackSucceeded(provider, sequenceNumber, requester, randomNumber) | callback delivered |
CallbackFailed(provider, sequenceNumber, requester, randomNumber, reason) | callback reverted → buffered |
ProtocolFeeUpdated(oldFeeInWei, newFeeInWei) / ProtocolFeeWithdrawal(to, amount) | admin fee ops |
Indexed fields: provider / requester / sequenceNumber are indexed on the core events for efficient filtering.
Errors
| Error | Meaning |
|---|---|
ProviderNotRegistered(provider) | provider unknown |
ProviderAlreadyRegistered(provider) | double register — use rotateCommitment |
InvalidChainLength(chainLength) | < MIN_CHAIN_LENGTH |
InvalidMaxNumHashes(maxNumHashes) | 0 or > MAX_NUM_HASHES |
ProviderChainExhausted(provider, endSequenceNumber) | chain fully consumed — rotate |
TooManyHashes(required, maxNumHashes) | too many outstanding requests; provider must reveal |
NoSuchRequest(provider, sequenceNumber) | no active request (or already revealed) |
IncorrectUserRevelation() | user revelation ≠ commitment |
IncorrectProviderRevelation() | provider revelation doesn't chain to the anchor |
RequestCallbackMismatch(isRequestWithCallback) | wrong reveal function for the request type |
NoFailedCallback(provider, sequenceNumber) | nothing buffered to retry |
InsufficientFee(provided, required) | msg.value too low |
InsufficientAccruedFees(requested, available) | over-withdrawal |
TransferFailed(to, amount) | native transfer failed |
NotFeeManager(caller, provider) | not the delegated fee manager |
ZeroAddress() | zero address where non-zero required |
SDK surface (@quiver/sdk)
QuiverClient—getFee,getProviderInfo,getRequest,getFailedCallback,request,requestRandomness,reveal,waitForFulfillment; staticgenerateUserRandom,userCommitment.- Hash-chain utils —
buildQuiver,commitmentOf,revelationOf,userCommitmentOf,combineRandomValues. - Chains —
robinhoodMainnet,robinhoodTestnet,anvilLocal,QUIVER_CHAINS. - ABIs —
quiverCoordinatorAbi,quiverConsumerAbi.