BUILD / GUIDE

Getting started

Install the SDK, connect your application and verify your first result.

Work with your agents

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

View prompt

Integrate D20DAO verifiable randomness into my existing application. Inspect its stack and request lifecycle, then implement the smallest working consumer and validation flow.

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/d20-sdk#getting-started
- 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.

Choose the deployment

Start with the restricted Arc Testnet pilot, chain ID 5042002. Open Deployed contracts and use the coordinator proxy, not an implementation address. Check the active implementation and code hashes against the manifest. Arrange consumer allowlisting before sending live requests. The request fee is currently 0.05 native test USDC; read requestFee() at runtime. Native USDC uses 18 decimals, and transaction gas is separate.

View deployed contracts

Install the SDK

Install @d20dao/vrf-sdk in your application. Use Node 22.13 or newer, Solidity 0.8.28 and your project's npm import resolver. The package includes consumer contracts, coordinator and registry ABIs, replay helpers and an AGENTS.md integration guide. Its PROTOCOL-PROVENANCE.json records the reviewed contract source.

npm install @d20dao/vrf-sdk

Add an authenticated consumer

Extend D20VRFConsumer and configure the coordinator proxy. Read requestFee(), forward that exact value, fix the refund recipient and persist the returned request ID with your application's operation. Override _fulfillRandomness to authenticate through the base, validate the expected ID and store the raw bytes32 result with minimal work. Choose raw randomness or a built-in mapping such as a range, selection or shuffle. See Integration for the Solidity example.

Open the consumer example

Handle delivery and expiry

Track proof acceptance, callback delivery and refunds separately. Accepted proofs earn the fee even if the consumer callback fails; retryCallback redelivers the same word. Unfulfilled requests become refundable strictly after their 60-second deadline. The current pilot supports optional _onRefund(requestId) after payment or backed credit; keep it within the initial 100,000-gas budget. Failed notifications retry without another payment. Application payments and assets need their own settlement rules.

Test and verify the result

Test exact-fee rejection, authenticated and duplicate callbacks, callback failure with same-word retry, expiry/refund and any application refund hook. Confirm consumer onboarding before a funded testnet request. In Explorer, verify the signed epoch packet, fixed request context, VRF, mapping and transcript, then separately confirm canonical receipts and historical code. No keeper credentials or direct keeper API are needed.