BUILD / GUIDE

Use cases

Example uses and the operation that fits each. Every result carries a proof anyone can check.

See the SDK examples

With the agent API

0.05 USDC per call over x402. No contract.

Break a tie or pick a winner between agents or options: chooseOne.
Draw raffle and giveaway winners: chooseMany.
Roll dice and draw cards in agent-run games: dice, shuffle.
Sample records for an evaluation or audit: chooseMany, or range for one index into a larger set.
Assign A/B variants: coinFlip for two arms, range for more.

For agents

In contracts

A consumer contract requests a built-in mapping on Arc and receives the result in its callback.

Loot drops and NPC behaviour in games: numberRange over the drop table's total weight.
Lottery and prize draws in dApps: chooseOne, or chooseMany for several prizes.
Tournament brackets and turn order: shuffle.

Integration Live demo

Work with your agents

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

Plain text Agent guide

View prompt

Find where verifiable randomness fits in my application and which D20DAO operation suits each case. Then implement the one I choose: in a consumer contract with the SDK, or over HTTP with the agent API if there is no contract.

Read these public references first; do not guess signatures, addresses or limits:
- This guide: https://d20dao.org/docs/use-cases (full text of every guide: https://d20dao.org/llms-full.txt, agent guide: https://d20dao.org/agents.md)
- SDK README and AGENTS.md: https://github.com/d20dao/d20-sdk (also inside the installed package). It lists the randomness options, callback gas bounds, how to wait for results, compiler setup and gas needs for refunds and retries.
- Protocol source (contracts and replay library): https://github.com/d20dao/d20-sdk/tree/main/protocol, pinned to commit de5f82eb9fc749c80e83270f57cde9908ddcf1f3 by PROTOCOL-PROVENANCE.json
- Deployment manifests: https://d20dao.org/deployments/arc-mainnet.json and https://d20dao.org/deployments/arc-testnet.json
- Integration skills and templates: https://github.com/d20dao/skills (d20-consumer: methods.md, RandomnessConsumer.sol, mappings.mjs)
- Explorer for checking requests: https://d20dao.org/explorer (arc.d20dao.org for mainnet, arc-testnet.d20dao.org for testnet)
- Agent API, for agents and services without a contract: https://d20dao.org/docs/agents (0.05 USDC per call over x402)
If a link is unavailable, use the installed package's README, AGENTS.md, ABIs and protocol sources.

Networks: Arc Mainnet chain 5042 (live, real USDC) and Arc Testnet chain 5042002 (build and test here first). Native USDC has 18 decimals. RPC: https://rpc.mainnet.arc.io and https://rpc.testnet.arc.io; explorers: https://explorer.arc.io and https://testnet.arcscan.app. Compile with Solidity 0.8.28 and EVM version cancun, importing contracts from the installed @d20dao/vrf-sdk package. Take the coordinator proxy address from the manifest of the network you target and check that its implementation matches the manifest. Any consumer contract can request; there is no allowlist, and EOAs cannot request.

Requests and fees: use the D20VRFRequests helpers from the SDK for every randomness option (raw word, dice, custom dice, coin flip, ranges, choose one or many, shuffle). Never hardcode the fee. In a contract, quote with quoteFee(callbackGasLimit) inside the requesting transaction. Off chain, quote with quoteFeeAt(callbackGasLimit, latest block baseFeePerGas) plus a buffer, or the SDK's quoteRequestFee with an ethers v6 provider, because eth_call reports a base fee of 0. Choose one payment pattern deliberately: collect a buffered quote from the user, pay the exact fee from the contract and return the change; or forward msg.value and accept that the excess becomes refund credit of the refund address.

Results: store the delivered word or mapped result in your consumer when the authenticated callback arrives, keyed by request ID, and have the application read that state. Off chain, wait for the coordinator's fulfillment events or poll getRequest; the SDK documents the fields and mapped-result readers. A browser app must bundle the ESM package. Delivery usually takes a few seconds; measured Arc Testnet completion times, including under burst load, are at https://d20dao.org/benchmarks (observations of the testnet keepers, not an SLA). An unserved request can be refunded strictly after its 60-second deadline at the refund ratio fixed when it was requested. Give refund and callback-retry transactions explicit gas limits as documented.

Keep callbacks small and authenticated through D20VRFConsumer, and never request randomness from inside a callback. An accepted proof with a failed callback is paid service: retry the same stored result, never reroll. Optional _onRefund(requestId) means the refund recipient was paid or credited, not that the consumer received funds, and notification retries must not pay twice. Keep application assets and settlement separate from RNG fees.

For verification, keep the original epoch packet, request and target context and accepted proof evidence. Mathematical replay alone does not prove chain inclusion; check receipts and the implementation history too.

Implement only the requested changes. Do not ask for keeper, VRF, deployer or bot secrets, and do not send funded or mainnet transactions without my explicit authorization. Compile, run lifecycle tests on a local chain or Arc Testnet, then report changed files, results, anything unverified, and any documentation that was unclear or missing.