BUILD / GUIDE

Integration

Request general-purpose randomness and receive an authenticated callback.

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. Find the Arc Testnet addresses in the Deployed contracts guide and verify the active implementation before connecting a consumer.

RandomApp.solSolidity / 26 lines

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.requestFee(), "Exact fee required");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}

Authenticated callback. Exact request fee.View source

Request and fee

Read requestFee() and send exactly that amount to requestRandomness(clientSeed, callbackGasLimit, refundAddress). The request checkpoints its epoch's canonical anchor, escrows the fee and pins its epoch ID, consumer, client seed, mapping, request block and fixed refund recipient. It can be accepted before an API 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.

Result handling

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 escrowed RNG fee by transaction for the fixed refund recipient.

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. Independently verify chain, proxy, registry, implementation history, public key and configuration. A stable proxy address does not guarantee unchanged behavior.

Work with your agent

Copy a task-specific prompt with the protocol references and integration rules.

Plain text Agent guide

View prompt

Implement a D20DAO consumer in my existing application. Preserve its access controls and payment model; associate every request ID with one application operation and store authenticated results.

Read these references before choosing APIs:
- Agent guide: https://github.com/d20dao/web/blob/main/public/agents.md
- Full text docs: https://github.com/d20dao/web/blob/main/public/llms-full.txt
- This guide: https://github.com/d20dao/keeper/blob/d7e785dda57499220bd37d73bc6fad9226872dcc/contracts/interfaces/ID20VRF.sol
- Current deployment and upgrade history: https://github.com/d20dao/keeper/blob/main/deployments/arc-testnet.json
- SDK and packaging instructions: https://github.com/d20dao/d20-sdk
- Integration skills: https://github.com/d20dao/skills
- Reviewed protocol source: https://github.com/d20dao/keeper/tree/d7e785dda57499220bd37d73bc6fad9226872dcc
If a reference needs repository access, use the installed package's AGENTS.md and provenance or request the reviewed files. Do not invent signatures or addresses.

Use the existing project toolchain. Install @d20dao/vrf-sdk from npm and read its AGENTS.md and PROTOCOL-PROVENANCE.json. Use Solidity 0.8.28. Configure the actual chain and coordinator proxy; Arc Testnet is 5042002 and requires consumer allowlisting. Read requestFee() instead of hardcoding the fee.

Keep callbacks small and authenticated through D20VRFConsumer. Mapped requests still deliver a raw bytes32 word. Accepted proof with a failed callback is paid service; retry the same stored result, never reroll it. Unfulfilled requests are refundable strictly after 60 seconds. Optional _onRefund(requestId) means the fixed recipient was paid or credited, not that the consumer received funds; notification retries must not pay twice. Do not request randomness from inside a callback. Separate application assets and settlement rules.

For verification, retain original epoch packets, request/target context and accepted proof evidence. Mathematical replay alone does not establish chain inclusion. An implementation upgrade inside a relevant block requires transaction-ordered evidence; block-end storage alone cannot prove which code ran.

Implement only the requested application changes. Do not request keeper, VRF, deployer or bot secrets. Respect my authorization for any deployment or funded transaction. Run relevant compilation and lifecycle tests; report changed files, results, missing inputs and any remaining onboarding step.