Integration

Consumer contract

Extend D20VRFConsumer with the verified coordinator proxy address. Its base authenticates callbacks. The local example below tracks outstanding request IDs and stores the delivered word. Keep delivery small and apply application actions separately. The same consumer works on Arc and Robinhood Chain. Find the testnet addresses in the Deployed contracts guide and verify the active implementation before connecting a consumer.

1// SPDX-License-Identifier: MIT2pragma solidity 0.8.28;3import {D20VRFConsumer} from "./protocol/D20VRFConsumer.sol";4import {ID20VRF} from "./protocol/interfaces/ID20VRF.sol";56contract RandomApp is D20VRFConsumer {7    ID20VRF public immutable rng;8    mapping(uint256 => bytes32) public results;9    mapping(uint256 => bool) private requested;1011    constructor(address coordinator) D20VRFConsumer(coordinator) {12        rng = ID20VRF(coordinator);13    }1415    function request(bytes32 input) external payable returns (uint256 id) {16        require(msg.value >= rng.quoteFee(100_000), "Fee below quote");17        id = rng.requestRandomness{value: msg.value}(input, 100_000, msg.sender);18        requested[id] = true;19    }2021    function _fulfillRandomness(uint256 id, bytes32 word) internal override {22        require(requested[id], "Unknown request");23        delete requested[id];24        results[id] = word;25    }26}

Request and fee

The fee is max(minFee, feeMultiplier × baseFee × (fulfillGasOverhead + callbackGasLimit)); pricing() returns the live parameters. A consumer contract pays quoteFee(callbackGasLimit) inside the requesting transaction, which is exact. An off-chain sender quotes quoteFeeAt(callbackGasLimit, latestBlock.baseFeePerGas) plus a buffer because eth_call usually reports a base fee of 0; the SDK's quoteRequestFee does this. requestRandomness(clientSeed, callbackGasLimit, refundAddress) reverts with IncorrectFee below the quote, and any excess becomes refund credit for the refund address, withdrawn with withdrawRefundCredit. The fee is paid in the native token: USDC on Arc, ETH on Robinhood Chain. On Arc, the request checkpoints its epoch's canonical anchor, escrows the charged fee (requestFeePaid) and refund ratio (requestRefundBps) and pins its epoch ID, consumer, client seed, mapping, request block and fixed refund recipient. It can be accepted before its epoch packet is published. Until publication, the epoch hash and randomness target are unresolved. An absent packet or unaccepted proof can lead to expiry; there is no automatic refund or guaranteed delivery SLA. On Robinhood Chain, the request binds its drand round at once (RoundAssigned) and escrows the same fields; there is no publication step.

Result handling

On Arc, after publication, the target block is max(requestBlock, epochCommitBlock + 1). Its hash becomes part of the fixed VRF input, so the packet is committed before that hash is known. Track the request until proof acceptance and callback delivery are separately established. Accepted proof earns the configured keeper and treasury fee shares even if the callback fails. Retry delivery with the stored word; do not request a replacement outcome for callback failure. After expiry without accepted proof, claim the refundable share of the escrowed fee by transaction for the fixed refund recipient. To wait for a result, read requestId from the RandomnessRequested log in the request receipt, then poll getRequest (getRoundRequest on Robinhood Chain): read the latest block first, stop when fulfilled is true (then read getMappedResult or your consumer's stored value), and treat the request as expired once that block's timestamp is past deadline. Choose polling intervals and loading states from the measured completion times at https://d20dao.org/benchmarks (Arc Testnet, a primary and a backup keeper, isolated and burst load, reproducible with https://github.com/d20dao/benchmarks), but treat only the 60-second deadline as a rule. On Robinhood Chain a typical delivery takes 5–8 seconds. Give recovery transactions explicit gas limits: refundRequest 400,000; retryCallback the callback gas limit plus 250,000; retryRefundCallback the gas limit plus 150,000.

Best practices

The SDK README explains each rule.

1. Quote with quoteFee inside the requesting transaction; off-chain, use quoteFeeAt with the latest base fee plus a buffer, never eth_call.
2. Request from a contract; a wallet call reverts with ContractConsumerRequired.
3. Keep the callback small: store the word and do the work later. retryCallback redelivers the same word.
4. Record each request ID with its context, and reject unknown or finished IDs in the callback.
5. Derive many values from one word: a diceRoll count, chooseMany, shuffle or keccak256(abi.encode(word, i)).
6. Handle expiry, and choose a refund address that can receive the native token or call withdrawRefundCredit.
7. Never re-roll a result you dislike; the word is final once fulfilled is true.
8. Close bets and entries when you request: the pending fulfillment reveals the word about one block before it lands.
9. Freeze any list before requesting an index into it, for example by hashing it into clientSeed.
10. Withdraw leftover refund credit, or return the change in the requesting transaction.
11. Never use blockhash or block.timestamp as randomness.
12. On Robinhood Chain: Send requests as normal transactions through the sequencer. A request forced through Ethereum's delayed inbox takes an earlier timestamp and may bind a round that is already public.

Browser applications

Bundle the ESM package with Vite, webpack or esbuild. quoteRequestFee expects an ethers v6 provider; with viem, read the latest block's baseFeePerGas, add a buffer and call quoteFeeAt. Add Arc to a wallet with wallet_addEthereumChain: chain ID 0x13b2 (5042) or 0x4cef52 (5042002), native currency USDC with 18 decimals, and the RPC and explorer URLs from the deployment manifest. Robinhood Chain is 0x1237 (4663) and its testnet 0xb626 (46630), native currency ETH with 18 decimals. Common ad-block lists block *.arc.io, so public Arc RPC reads can fail in visitors' browsers (net::ERR_BLOCKED_BY_CLIENT); read through the connected wallet or a same-origin read-only relay, as github.com/d20dao/randomizer-demo does. Decode coordinator reverts with coordinatorAbi from @d20dao/vrf-sdk/abi. In ethers v6, a struct field named like an array member, such as values or length, must be read by position, getValue(name) or toObject().

SDK and agent resources

Install @d20dao/vrf-sdk from npm. Start with the packaged AGENTS.md and the Getting started guide, or copy the task prompt below into your agent. Additional integration skills live at github.com/d20dao/skills. API.md in the package (github.com/d20dao/d20-sdk/blob/main/API.md) lists every coordinator and registry function, event and error with its caller and what to do about each error. github.com/d20dao/randomizer-demo is a complete dapp that uses every randomness option (live at mainnet-demo.d20dao.org). Independently verify chain, proxy, registry, implementation history, public key and configuration. A stable proxy address does not guarantee unchanged behavior.