REFERENCE / GUIDE

Service rules

Escrowed requests, earned fee shares, retries and refunds.

Estimated completion

Estimated average completion is around 8 blocks. This is a product estimate, not a measured rolling average or guaranteed block deadline. Epoch readiness and network conditions affect actual timing. Request and fulfillment blocks can be checked in the Explorer. The onchain acceptance and refund threshold remains 60 seconds.

60-second acceptance deadline

A valid proof must be accepted onchain at or before request timestamp plus 60 seconds. This is a timestamp rule, not a guaranteed number of blocks or delivery SLA. API publication and target-block waiting consume that same window. Crossing an epoch boundary does not shorten an existing request's deadline. A request can be accepted before its epoch packet is published and remain unfulfilled if publication or proof acceptance does not complete.

Fee settlement and callback delivery

Accepted proof earns the configured keeper and treasury shares, including when the callback fails. The keeper share goes to the configured committer, not the transaction submitter; failed transfers become backed credits. The pilot currently assigns 20% to the keeper: 0.01 from the 0.05 test USDC request fee. This is configurable, not a permanent pricing promise. Administered recipients and split can change. Delivery retry uses the same stored word and does not earn another service fee. Failed callbacks do not qualify for the unfulfilled-request refund.

Refund transactions

After expiry without an accepted proof, the RNG service fee is refundable to the fixed recipient. A transaction is required; gas and application fees are excluded. Publication is not permission to spend unfulfilled-request escrow, and fees cannot be earned merely by submitting a pending proof. A rejecting refund recipient can receive a backed credit. Inspect request, refund and credit state before retrying a claim.

Optional refund notification

The current consumer source supports authenticated onRefund(requestId), after the fixed recipient has been paid or credited. Override _onRefund for a bounded application update within the initial 100,000-gas budget. Failed notification does not undo the refund; retryRefundCallback retries only notification, without another payment. Reentry into coordinator request, refund and retry paths is blocked. Verify the deployed implementation supports this hook before relying on it; a new SDK does not upgrade an existing proxy.

Work with your agents

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

Plain text Agent guide

View prompt

Review and implement my application's D20DAO request lifecycle: pending publication, proof acceptance, callback delivery, same-word retries, expiry, refund credits and optional refund notification. Keep RNG fees separate from application payments.

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/docs/epoch-protocol.md
- 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.