@d20dao/vrf-sdk 0.3.3 → 0.4.0

package/API.md

@@ -0,0 +1,2190 @@
+# D20DAO coordinator API reference
+
+<!-- Generated by scripts/api-reference.mjs from abi/*.json and scripts/api-descriptions.mjs. Do not edit by hand. -->
+
+Every function, event and error of `D20VRFCoordinator` and `EpochEntropy`, generated from the ABIs of `@d20dao/vrf-sdk` 0.4.0. Regenerate with `npm run build && npm run api-reference`; `npm test` fails when this file is out of date.
+
+- Package: `@d20dao/vrf-sdk` 0.4.0
+- Protocol source: commit `de5f82eb9fc749c80e83270f57cde9908ddcf1f3`, copied to [`protocol/contracts/`](protocol/contracts/) (hashes in `PROTOCOL-PROVENANCE.json`)
+- Compiler: solc 0.8.28+commit.7893614a.Emscripten.clang, EVM version `cancun`
+- `abi/D20VRFCoordinator.json` SHA-256: `4764ba62745e109f3b968b21ed23e88da739a4a26906fc2ed3192fa23b8d79c1`
+- `abi/EpochEntropy.json` SHA-256: `684ee3dfe0745f141831aee896db6436d490d5e9715e61661c86b044d1c3260e`
+
+This reference describes that source. A deployment runs it only while the implementation behind each proxy is the one the deployment manifest records for that commit: check when you integrate and whenever a proxy emits `Upgraded` (README [Security and trust](README.md#security-and-trust)).
+
+## Conventions
+
+- **Addresses.** Call the proxies listed in README [Deployments](README.md#deployments). The ABIs are those of the implementations; `D20Proxy` adds no functions of its own.
+- **Units.** Fees and credits are wei of native USDC, which has 18 decimals (`1e18` is 1 USDC). Deadlines and timestamps are Unix seconds. Ratios are basis points (10000 is 100%).
+- **Callers.** "Anyone" means any account or contract; "Any contract" means `msg.sender` must have code. Owner-only functions revert `OwnableUnauthorizedAccount` for other callers.
+- **Selectors.** Functions and errors show their 4-byte selector, events their topic 0, so revert data and logs can be matched by hand.
+- **Decoding errors.** `coordinatorAbi` and `epochEntropyAbi` (`@d20dao/vrf-sdk/abi`) contain every custom error below. When your consumer calls the coordinator with an ordinary Solidity call, a coordinator revert is passed through unchanged, so a wallet sending a transaction to your consumer sees the coordinator's selector. Decode with `coordinator.interface.parseError(data)` in ethers or `decodeErrorResult({ abi: coordinatorAbi, data })` in viem, or build your consumer's contract object from its ABI plus the coordinator's error entries. Your consumer's own errors, such as `OnlyCoordinator` and `InvalidCoordinator` from `D20VRFConsumer`, are only in your consumer's ABI. Arithmetic overflow reverts with `Panic(uint256)`.
+- **ethers v6 results.** Structs and multiple return values arrive as `Result` objects, which are arrays. A named value is also a property unless its name collides with an `Array` or `Result` member, such as `length`, `values`, `keys`, `map` or `filter`; read such a value with `result.getValue(name)`, by position, or from `result.toObject()`. Unnamed outputs, such as those of `pricing()`, are positional only.
+- **Consumer contracts.** `D20VRFConsumer` implements `rawFulfillRandomness(requestId, randomness)` and `onRefund(requestId)`; both revert `OnlyCoordinator` unless called by the coordinator proxy given to its constructor, which reverts `InvalidCoordinator` for an address without code.
+
+## Contents
+
+- [D20VRFCoordinator](#coordinator)
+  - [Types](#coordinator-types)
+  - [Requesting](#coordinator-requesting)
+  - [Pricing and refund settings](#coordinator-pricing-and-refund-settings)
+  - [Reading request state and results](#coordinator-reading-request-state-and-results)
+  - [Settlement, refunds and credits](#coordinator-settlement-refunds-and-credits)
+  - [Settlement balances](#coordinator-settlement-balances)
+  - [Keeper and proof functions](#coordinator-keeper-and-proof-functions)
+  - [Keeper, key and configuration reads](#coordinator-keeper-key-and-configuration-reads)
+  - [Owner administration](#coordinator-owner-administration)
+  - [Constants](#coordinator-constants)
+  - [Events](#coordinator-events)
+  - [Errors](#coordinator-errors)
+- [EpochEntropy](#registry)
+  - [Types](#registry-types)
+  - [Epoch state for consumers and verifiers](#registry-epoch-state-for-consumers-and-verifiers)
+  - [Registry reads](#registry-registry-reads)
+  - [Source selection and publication](#registry-source-selection-and-publication)
+  - [Recipes and catalogs](#registry-recipes-and-catalogs)
+  - [Owner administration](#registry-owner-administration)
+  - [Constants](#registry-constants)
+  - [Events](#registry-events)
+  - [Errors](#registry-errors)
+
+## <a id="coordinator"></a>D20VRFCoordinator
+
+The consumer entry point. Call the coordinator proxy for your chain (README [Deployments](README.md#deployments)). `ID20VRF` in `contracts/interfaces/ID20VRF.sol` declares the five functions a consumer contract needs (`quoteFee`, `quoteFeeAt`, `requestRandomness`, `requestMappedRandomness`, `getMappedResult`); `coordinatorAbi` from `@d20dao/vrf-sdk/abi` carries everything below. In Solidity, declare a local interface for any other function you call.
+
+Requests, fulfillment, `storeBlockHash`, retries, `refundRequest` and withdrawals are `nonReentrant`. A consumer callback (`rawFulfillRandomness`, `onRefund`) that calls one of them fails with `ReentrancyGuardReentrantCall`, and the coordinator records the callback as failed. Views stay callable from callbacks.
+
+### <a id="coordinator-types"></a>Types
+
+#### <a id="coordinator-type-d20vrfcoordinator-request"></a>`D20VRFCoordinator.Request`
+
+Returned by `getRequest`. It does not contain the escrowed fee or the refund ratio; read `requestFeePaid` and `requestRefundBps`.
+
+Source: `D20VRFCoordinator.sol` lines 59–77
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `consumer` | `address` | Contract that made the request; receives `rawFulfillRandomness` and `onRefund`. |
+| `callbackGasLimit` | `uint32` | Gas forwarded to `rawFulfillRandomness` at fulfillment, and the lowest `gasLimit` that `retryCallback` accepts. |
+| `requestBlock` | `uint64` | Block of the request transaction. |
+| `targetBlock` | `uint64` | Block whose hash enters the seed: `max(requestBlock, committedBlock + 1)` of the epoch. 0 until the epoch packet is published. |
+| `deadline` | `uint64` | Request block timestamp plus `RESPONSE_TIMEOUT` (60 seconds), in Unix seconds. A proof accepted in a block with timestamp at or before `deadline` serves the request; `refundRequest` needs a block timestamp after it. |
+| `refundAddress` | `address` | Fixed recipient of the expiry refund and of any overpayment credit. |
+| `clientSeed` | `bytes32` | Value supplied by the consumer, bound into the seed and emitted in `RandomnessRequested`. |
+| `mappingHash` | `bytes32` | `keccak256(abi.encode(operation, lower, upper, count, population))` of the stored spec; `hashMapping(spec)` in TypeScript. |
+| `blockHash` | `bytes32` | Target block hash once `storeBlockHash` or fulfillment stored it; zero before. |
+| `randomness` | `bytes32` | Accepted VRF output. Zero until `fulfilled`. |
+| `proofHash` | `bytes32` | `keccak256(abi.encode(proof))` of the accepted proof. Zero until `fulfilled`. |
+| `transcriptHash` | `bytes32` | `keccak256(abi.encode(TRANSCRIPT_DOMAIN, chainId, coordinator, requestId, protocolConfigurationHash, blockHash, proofHash, randomness, mappingHash, epochId, epochHash))`. Zero until `fulfilled`. |
+| `fulfilled` | `bool` | A proof was accepted. Final: the word can no longer change. |
+| `delivered` | `bool` | A callback attempt succeeded. Stays false after a failed callback until `retryCallback` succeeds; it says nothing about acceptance. |
+| `refunded` | `bool` | `refundRequest` settled the request. Never true together with `fulfilled`. |
+| `epochId` | `uint64` | Epoch of `requestBlock`, fixed at creation; never zero for an existing request. |
+| `epochHash` | `bytes32` | Commitment of the published epoch packet. Zero until the packet is published. |
+
+#### <a id="coordinator-type-randomnessmapping-spec"></a>`RandomnessMapping.Spec`
+
+A randomness mapping stored with a request ("mapping" here is not a Solidity `mapping`). The TypeScript `MappingSpec` returned by `builtins` has the same five fields in the same order, with `lower` and `upper` as `bigint`, and ethers encodes it for this struct unchanged. Valid combinations: README [Randomness options](README.md#randomness-options).
+
+Source: `libraries/RandomnessMapping.sol` lines 7–14
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `operation` | `RandomnessMapping.Operation` | Enum encoded as uint8: 0 Raw, 1 DiceRoll, 2 CoinFlip, 3 NumberRange, 4 ChooseOne, 5 ChooseMany, 6 Shuffle. |
+| `lower` | `uint256` | NumberRange minimum; zero for every other operation. |
+| `upper` | `uint256` | DiceRoll sides or NumberRange maximum; zero otherwise. |
+| `count` | `uint32` | Values returned: the dice count; 1 for CoinFlip, NumberRange and ChooseOne; the number of choices for ChooseMany; the population for Shuffle; 0 for Raw. |
+| `population` | `uint32` | Number of items (1 to 256) for ChooseOne, ChooseMany and Shuffle; zero otherwise. |
+
+#### <a id="coordinator-type-vrf-proof"></a>`VRF.Proof`
+
+Chainlink secp256k1 VRF proof, verified by the unmodified vendored `VRF.sol`. ABI-encoded it is 416 bytes: the `FulfillmentEvidence` packet.
+
+Source: `vendor/VRF.sol` lines 570–580
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `pk` | `uint256[2]` | VRF public key; must equal `(publicKeyX, publicKeyY)`. |
+| `gamma` | `uint256[2]` | Proof point. The accepted word is `keccak256(abi.encode(3, gamma))`. |
+| `c` | `uint256` | Proof challenge scalar. |
+| `s` | `uint256` | Proof response scalar. |
+| `seed` | `uint256` | Must equal `requestSeed(requestId)`. |
+| `uWitness` | `address` | Address of `c·pk + s·G`, checked by the verifier. |
+| `cGammaWitness` | `uint256[2]` | Precomputed `c·gamma`, checked by the verifier. |
+| `sHashWitness` | `uint256[2]` | Precomputed `s·hashToCurve(pk, seed)`, checked by the verifier. |
+| `zInv` | `uint256` | Inverse of the projective z coordinate of `cGammaWitness + sHashWitness`. |
+
+### <a id="coordinator-requesting"></a>Requesting
+
+Requests must come from a contract and pay at least the fee computed in their own transaction; see README [Paying for a request](README.md#paying-for-a-request). The registry call a request makes (`checkpointEpoch` for the current epoch) cannot fail in practice, so requests revert only with the errors listed.
+
+#### <a id="coordinator-fn-quotefee"></a>`quoteFee`
+
+```solidity
+function quoteFee(uint32 callbackGasLimit) external view returns (uint256)
+```
+
+Selector `0xc9caa0c3` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 228–233
+
+Fee for a request with this `callbackGasLimit` priced at `block.basefee`, that is `quoteFeeAt(callbackGasLimit, block.basefee)`. Exact inside the requesting transaction, which is how `D20VRFRequests` helpers pay. Through `eth_call` the base fee is commonly reported as 0 (observed on Arc), so the answer collapses to `minFee` and a transaction sent with it reverts `IncorrectFee`. Off-chain, quote with `quoteFeeAt` and the latest header base fee plus a buffer, as `quoteRequestFee` does. It does not check the gas limit range.
+
+**Errors:** [`FeeOverflow`](#coordinator-error-feeoverflow).
+
+#### <a id="coordinator-fn-quotefeeat"></a>`quoteFeeAt`
+
+```solidity
+function quoteFeeAt(uint32 callbackGasLimit, uint256 baseFee) external view returns (uint256)
+```
+
+Selector `0x26fa8481` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 220–227
+
+`max(minFee, feeMultiplier × baseFee × (fulfillGasOverhead + callbackGasLimit))` over the live pricing for a base fee in wei that you supply; with `feeMultiplier` 0 it returns `minFee`. A quote, not a reservation: pricing can change before your transaction. A `baseFee` large enough to overflow uint256 reverts with `Panic(0x11)` instead of `FeeOverflow`.
+
+**Errors:** [`FeeOverflow`](#coordinator-error-feeoverflow).
+
+#### <a id="coordinator-fn-requestrandomness"></a>`requestRandomness`
+
+```solidity
+function requestRandomness(bytes32 clientSeed, uint32 callbackGasLimit, address _refundAddress) external payable returns (uint256 requestId)
+```
+
+Selector `0x9849d1e5` · Caller: Any contract · Source: `D20VRFCoordinator.sol` lines 235–240, 248–287
+
+Creates a raw request (spec all zero) with `msg.sender` as consumer and returns its ID. Needs `msg.value` at least the fee computed in this transaction; escrows exactly that fee and credits any excess to `_refundAddress` as refund credit. Fixes the request block, epoch, client seed, refund address, fee, refund ratio (`refundBps`) and a deadline of `block.timestamp + RESPONSE_TIMEOUT`. After acceptance the consumer receives `rawFulfillRandomness(requestId, randomness)` with exactly `callbackGasLimit` gas. Checks run in this order: caller has code, refund address non-zero, gas limit in range, fee, mapping, epoch started.
+
+**Emits:** [`FeeOverpaymentCredited`](#coordinator-event-feeoverpaymentcredited), [`RandomnessRequested`](#coordinator-event-randomnessrequested), [`MappingRequested`](#coordinator-event-mappingrequested).
+
+**Errors:** [`ContractConsumerRequired`](#coordinator-error-contractconsumerrequired), [`InvalidRefundAddress`](#coordinator-error-invalidrefundaddress), [`InvalidCallbackGas`](#coordinator-error-invalidcallbackgas), [`FeeOverflow`](#coordinator-error-feeoverflow), [`IncorrectFee`](#coordinator-error-incorrectfee), [`EpochUnavailable`](#coordinator-error-epochunavailable).
+
+#### <a id="coordinator-fn-requestmappedrandomness"></a>`requestMappedRandomness`
+
+```solidity
+function requestMappedRandomness(bytes32 clientSeed, uint32 callbackGasLimit, address _refundAddress, RandomnessMapping.Spec spec) external payable returns (uint256 requestId)
+```
+
+Selector `0xe6b41a8c` · Caller: Any contract · Source: `D20VRFCoordinator.sol` lines 242–246, 248–287
+
+Same as `requestRandomness`, storing `spec` with the request (`getMapping`, `mappingHash`). The callback still carries the raw word; read the mapped values with `getMappedResult`. `D20VRFRequests` helpers call this function and pay `quoteFee` from the calling contract balance.
+
+**Emits:** [`FeeOverpaymentCredited`](#coordinator-event-feeoverpaymentcredited), [`RandomnessRequested`](#coordinator-event-randomnessrequested), [`MappingRequested`](#coordinator-event-mappingrequested).
+
+**Errors:** [`ContractConsumerRequired`](#coordinator-error-contractconsumerrequired), [`InvalidRefundAddress`](#coordinator-error-invalidrefundaddress), [`InvalidCallbackGas`](#coordinator-error-invalidcallbackgas), [`FeeOverflow`](#coordinator-error-feeoverflow), [`IncorrectFee`](#coordinator-error-incorrectfee), [`InvalidMapping`](#coordinator-error-invalidmapping), [`EpochUnavailable`](#coordinator-error-epochunavailable).
+
+### <a id="coordinator-pricing-and-refund-settings"></a>Pricing and refund settings
+
+Views, callable by anyone. They describe requests created from now on; an existing request settles from its own snapshots (`requestFeePaid`, `requestRefundBps`).
+
+| Function | Selector | Meaning | Source |
+| --- | --- | --- | --- |
+| <a id="coordinator-fn-pricing"></a>`pricing() returns (uint256, uint16, uint32)` | `0x7ce91411` | Live `(minFee, feeMultiplier, fulfillGasOverhead)`. The outputs are unnamed, so read them by position. | lines 211–213 |
+| <a id="coordinator-fn-minfee"></a>`minFee() returns (uint256)` | `0x24ec7590` | Minimum fee in wei, at most `MAX_MIN_FEE` (10 USDC). | line 44 |
+| <a id="coordinator-fn-feemultiplier"></a>`feeMultiplier() returns (uint16)` | `0xe5a70ef7` | Base-fee multiplier, 0 to `MAX_FEE_MULTIPLIER` (20); 0 makes every fee `minFee`. | lines 46–47 |
+| <a id="coordinator-fn-fulfillgasoverhead"></a>`fulfillGasOverhead() returns (uint32)` | `0x19d40839` | Gas added to `callbackGasLimit` in the fee formula, `MIN_FULFILL_GAS_OVERHEAD` to `MAX_FULFILL_GAS_OVERHEAD`. | line 48 |
+| <a id="coordinator-fn-refundbps"></a>`refundBps() returns (uint16)` | `0xec8c9a0b` | Current refund ratio in basis points (5000 to 10000), copied into each new request. Not the ratio of an existing request: use `requestRefundBps(requestId)`. | lines 49–50 |
+
+### <a id="coordinator-reading-request-state-and-results"></a>Reading request state and results
+
+Views, callable by anyone, including from a callback. Request IDs start at 1 and increase by one; functions taking a `requestId` revert `UnknownRequest` for an ID that was never issued. README [Reading results](README.md#reading-results) shows a polling loop.
+
+#### <a id="coordinator-fn-getrequest"></a>`getRequest`
+
+```solidity
+function getRequest(uint256 requestId) external view returns (D20VRFCoordinator.Request result)
+```
+
+Selector `0xc58343ef` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 289–308, 558–563
+
+Full state of a request, see [`D20VRFCoordinator.Request`](#coordinator-type-d20vrfcoordinator-request). `targetBlock` and `epochHash` are resolved from the registry, so they become non-zero as soon as the epoch packet is published. `fulfilled` means the word is final; `delivered` only reports that a callback succeeded. A request that is not `fulfilled` in a block whose timestamp is after `deadline` has expired and can only be refunded. When polling, read the latest block before `getRequest`, so that a proof included up to that block is visible.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest).
+
+#### <a id="coordinator-fn-getmapping"></a>`getMapping`
+
+```solidity
+function getMapping(uint256 requestId) external view returns (RandomnessMapping.Spec)
+```
+
+Selector `0xede9ba8b` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 340–343
+
+The stored [`RandomnessMapping.Spec`](#coordinator-type-randomnessmapping-spec); all fields zero (Raw) for `requestRandomness`.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest).
+
+#### <a id="coordinator-fn-getmappedresult"></a>`getMappedResult`
+
+```solidity
+function getMappedResult(uint256 requestId) external view returns (uint256[])
+```
+
+Selector `0x8f09a3e6` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 345–349
+
+The accepted word mapped with the stored spec: `[uint256(word)]` for a raw request, otherwise the values in README [Randomness options](README.md#randomness-options). Part of `ID20VRF`. Reverts `NotFulfilled` until a proof is accepted, so an expired or refunded request never has a result. Gas grows with the mapping; a 256-item shuffle is expensive onchain.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotFulfilled`](#coordinator-error-notfulfilled).
+
+#### <a id="coordinator-fn-maprandomness"></a>`mapRandomness`
+
+```solidity
+function mapRandomness(bytes32 randomness, RandomnessMapping.Spec spec) external pure returns (uint256[])
+```
+
+Selector `0x41c2a199` · Caller: Anyone (pure) · Source: `D20VRFCoordinator.sol` lines 351–356
+
+Maps any word with any valid spec, like the SDK `mapRandomness(word, spec)` off-chain. It does not show that a request was fulfilled.
+
+**Errors:** [`InvalidMapping`](#coordinator-error-invalidmapping).
+
+#### <a id="coordinator-fn-requestfeepaid"></a>`requestFeePaid`
+
+```solidity
+function requestFeePaid(uint256 requestId) external view returns (uint256)
+```
+
+Selector `0xef7cc992` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 331–334
+
+Fee escrowed by the request (`feePaid` in `RandomnessRequested`), excluding any overpayment. The keeper share, the protocol share and the refund are computed from it.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest).
+
+#### <a id="coordinator-fn-requestrefundbps"></a>`requestRefundBps`
+
+```solidity
+function requestRefundBps(uint256 requestId) external view returns (uint16)
+```
+
+Selector `0x5d170fd7` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 335–338
+
+Refund ratio the request copied from `refundBps` at creation. An expiry refund pays `requestFeePaid × requestRefundBps / 10000`; a later `setRefundBps` does not change it.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest).
+
+#### <a id="coordinator-fn-refundcallbackdelivered"></a>`refundCallbackDelivered`
+
+```solidity
+function refundCallbackDelivered(uint256) external view returns (bool)
+```
+
+Selector `0x281d3157` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 103, 511
+
+True once an `onRefund` notification for the request succeeded, at `refundRequest` or `retryRefundCallback`. Returns false for unknown IDs instead of reverting.
+
+#### <a id="coordinator-fn-nextrequestid"></a>`nextRequestId`
+
+```solidity
+function nextRequestId() external view returns (uint256)
+```
+
+Selector `0x6a84a985` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 51, 173, 261
+
+ID the next request will receive. Issued IDs are 1 to `nextRequestId() - 1`.
+
+### <a id="coordinator-settlement-refunds-and-credits"></a>Settlement, refunds and credits
+
+Recovery calls need no value or role. They forward gas to the consumer and revert `InsufficientCallbackGas` rather than forward less, so the transaction gas limit must cover it (README [Gas for refund and retry calls](README.md#gas-for-refund-and-retry-calls)). Refund credit and keeper credit are pull balances: only the holder withdraws them.
+
+#### <a id="coordinator-fn-refundrequest"></a>`refundRequest`
+
+```solidity
+function refundRequest(uint256 requestId) external
+```
+
+Selector `0x7411484e` · Caller: Anyone · Source: `D20VRFCoordinator.sol` lines 466–490, 502–513
+
+Refunds an unfulfilled request once a block timestamp is after its deadline. Marks it refunded, sends `feePaid × requestRefundBps / 10000` to the fixed refund address with a 30,000-gas transfer, or adds it to that address's refund credit if the transfer fails, and adds the rest of the fee to `earnedFees`. Then calls `onRefund(requestId)` on the consumer with 100,000 gas; a failed notification does not undo the refund. The caller receives nothing. Measured minimum transaction gas limit 302,558 to 357,517; use 400,000.
+
+**Emits:** [`RequestRefundedTo`](#coordinator-event-requestrefundedto), [`RefundCallbackAttempted`](#coordinator-event-refundcallbackattempted).
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`RefundNotAvailable`](#coordinator-error-refundnotavailable), [`InsufficientCallbackGas`](#coordinator-error-insufficientcallbackgas).
+
+#### <a id="coordinator-fn-retrycallback"></a>`retryCallback`
+
+```solidity
+function retryCallback(uint256 requestId, uint32 gasLimit) external
+```
+
+Selector `0xdd11c275` · Caller: Anyone · Source: `D20VRFCoordinator.sol` lines 456–464, 613–630
+
+Calls `rawFulfillRandomness` again with the same accepted word after a failed callback, forwarding `gasLimit` (30,000 to 1,000,000 and not below the request's `callbackGasLimit`). Sets `delivered` on success. Pays nobody and never changes the word. Transaction gas limit: about `gasLimit + 250,000`.
+
+**Emits:** [`CallbackAttempted`](#coordinator-event-callbackattempted).
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotFulfilled`](#coordinator-error-notfulfilled), [`AlreadyDelivered`](#coordinator-error-alreadydelivered), [`InvalidCallbackGas`](#coordinator-error-invalidcallbackgas), [`InsufficientCallbackGas`](#coordinator-error-insufficientcallbackgas).
+
+#### <a id="coordinator-fn-retryrefundcallback"></a>`retryRefundCallback`
+
+```solidity
+function retryRefundCallback(uint256 requestId, uint32 gasLimit) external
+```
+
+Selector `0x054f6962` · Caller: Anyone · Source: `D20VRFCoordinator.sol` lines 492–500, 502–513
+
+Repeats a failed `onRefund` notification for a refunded request with `gasLimit` (100,000 to 1,000,000). Never transfers funds again. Transaction gas limit: about `gasLimit + 150,000`.
+
+**Emits:** [`RefundCallbackAttempted`](#coordinator-event-refundcallbackattempted).
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotRefunded`](#coordinator-error-notrefunded), [`RefundCallbackAlreadyDelivered`](#coordinator-error-refundcallbackalreadydelivered), [`InvalidCallbackGas`](#coordinator-error-invalidcallbackgas), [`InsufficientCallbackGas`](#coordinator-error-insufficientcallbackgas).
+
+#### <a id="coordinator-fn-withdrawrefundcredit"></a>`withdrawRefundCredit`
+
+```solidity
+function withdrawRefundCredit(address recipient) external
+```
+
+Selector `0x445071f2` · Caller: Refund-credit holder · Source: `D20VRFCoordinator.sol` lines 515–525
+
+Sends all of the caller's refund credit, `refundCredits(msg.sender)`, to `recipient` with all remaining gas. Credit comes from overpayment and from refund transfers that failed, and belongs to the request's refund address, so that address must make the call. If `recipient` rejects the transfer the call reverts and the credit stays.
+
+**Emits:** [`RefundCreditWithdrawn`](#coordinator-event-refundcreditwithdrawn).
+
+**Errors:** [`InvalidRefundAddress`](#coordinator-error-invalidrefundaddress), [`NoRefundCredit`](#coordinator-error-norefundcredit), [`TransferFailed`](#coordinator-error-transferfailed).
+
+#### <a id="coordinator-fn-withdrawfees"></a>`withdrawFees`
+
+```solidity
+function withdrawFees(address recipient) external
+```
+
+Selector `0x164e68de` · Caller: Fee recipient · Source: `D20VRFCoordinator.sol` lines 527–536
+
+Sends all `earnedFees` to `recipient`. Fees accrue at acceptance (fee minus keeper share) and from the part of a refunded fee that is not returned; open escrow is never included. With nothing earned it sends zero without reverting.
+
+**Emits:** [`FeesWithdrawn`](#coordinator-event-feeswithdrawn).
+
+**Errors:** [`OnlyFeeRecipient`](#coordinator-error-onlyfeerecipient), [`InvalidConfig`](#coordinator-error-invalidconfig), [`TransferFailed`](#coordinator-error-transferfailed).
+
+#### <a id="coordinator-fn-withdrawkeepercredit"></a>`withdrawKeeperCredit`
+
+```solidity
+function withdrawKeeperCredit(address recipient) external
+```
+
+Selector `0xf62c546b` · Caller: Keeper-credit holder · Source: `D20VRFCoordinator.sol` lines 538–547
+
+Sends all of the caller's keeper credit (keeper-share transfers that failed) to `recipient`.
+
+**Emits:** [`KeeperCreditWithdrawn`](#coordinator-event-keepercreditwithdrawn).
+
+**Errors:** [`InvalidConfig`](#coordinator-error-invalidconfig), [`NoKeeperCredit`](#coordinator-error-nokeepercredit), [`TransferFailed`](#coordinator-error-transferfailed).
+
+### <a id="coordinator-settlement-balances"></a>Settlement balances
+
+Views, callable by anyone. Amounts are in wei of native USDC.
+
+| Function | Selector | Meaning | Source |
+| --- | --- | --- | --- |
+| <a id="coordinator-fn-refundcredits"></a>`refundCredits(address) returns (uint256)` | `0x61137e40` | Refund credit that an address can withdraw with `withdrawRefundCredit`. | line 57 |
+| <a id="coordinator-fn-totalrefundcredits"></a>`totalRefundCredits() returns (uint256)` | `0x6e0842e1` | Sum of all refund credit held by the coordinator. | line 56 |
+| <a id="coordinator-fn-earnedfees"></a>`earnedFees() returns (uint256)` | `0xb1b3ffd9` | Protocol fees that the fee recipient can withdraw. | line 52 |
+| <a id="coordinator-fn-feerecipient"></a>`feeRecipient() returns (address)` | `0x46904840` | Address allowed to call `withdrawFees`; changed with `setFeeRecipient`. | line 40 |
+| <a id="coordinator-fn-keeperfeebps"></a>`keeperFeeBps() returns (uint16)` | `0x0eab7d63` | Keeper share of each accepted fee in basis points (0 to 10000). Read at acceptance, not snapshotted: a change applies to open requests accepted afterwards. It only splits the escrowed fee; what the consumer paid and can be refunded does not change. | lines 41, 433 |
+| <a id="coordinator-fn-keepercredits"></a>`keeperCredits(address) returns (uint256)` | `0xf5c764f6` | Keeper credit that an address can withdraw with `withdrawKeeperCredit`. | line 42 |
+| <a id="coordinator-fn-totalkeepercredits"></a>`totalKeeperCredits() returns (uint256)` | `0xc7281b7a` | Sum of all keeper credit held by the coordinator. | line 43 |
+
+### <a id="coordinator-keeper-and-proof-functions"></a>Keeper and proof functions
+
+Proof submission is permissionless: anyone holding a valid proof may submit it, and the keeper share goes to the submitting wallet when the registry authorizes it as its committer or a backup committer, and to `committer()` otherwise. Consumers normally only read `getRequest`. Besides the custom errors listed, proof functions can revert with `Error(string)` messages from the vendored VRF verifier, such as `invalid proof`, which are not in the ABI.
+
+#### <a id="coordinator-fn-fulfillrandomness"></a>`fulfillRandomness`
+
+```solidity
+function fulfillRandomness(uint256 requestId, VRF.Proof proof) external
+```
+
+Selector `0xef7c2b19` · Caller: Anyone · Source: `D20VRFCoordinator.sol` lines 389–397, 413–448
+
+Accepts a proof for a request that is not fulfilled, not refunded and not past its deadline; acceptance in a block with timestamp equal to `deadline` is timely. Stores the target block hash if needed, verifies the proof against `requestSeed(requestId)`, stores the word, proof hash and transcript hash, sets `fulfilled`, adds `feePaid` minus the keeper share to `earnedFees` and calls the consumer with `callbackGasLimit` gas. It then sends the keeper share (`keeperFeeBps` of `feePaid`) with 30,000 gas to the submitting wallet when the registry answers `isAuthorizedCommitter` true for it (the committer or an allowed backup committer) and to `committer()` otherwise, or records it as that wallet's keeper credit; a registry call that reverts also pays `committer()`. A failing callback does not revert the fulfillment.
+
+**Emits:** [`BlockHashStored`](#coordinator-event-blockhashstored), [`RequestServed`](#coordinator-event-requestserved), [`ProofVerified`](#coordinator-event-proofverified), [`RandomnessFulfilled`](#coordinator-event-randomnessfulfilled), [`FulfillmentEvidence`](#coordinator-event-fulfillmentevidence), [`CallbackAttempted`](#coordinator-event-callbackattempted), [`KeeperFeePaid`](#coordinator-event-keeperfeepaid).
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`AlreadyFulfilled`](#coordinator-error-alreadyfulfilled), [`RequestRefunded`](#coordinator-error-requestrefunded), [`RequestExpired`](#coordinator-error-requestexpired), [`NotReady`](#coordinator-error-notready), [`BlockHashUnavailable`](#coordinator-error-blockhashunavailable), [`WrongPublicKey`](#coordinator-error-wrongpublickey), [`WrongSeed`](#coordinator-error-wrongseed), [`EvidencePacketTooLarge`](#coordinator-error-evidencepackettoolarge), [`InsufficientCallbackGas`](#coordinator-error-insufficientcallbackgas).
+
+#### <a id="coordinator-fn-fulfillrandomnessbatch"></a>`fulfillRandomnessBatch`
+
+```solidity
+function fulfillRandomnessBatch(uint256[] ids, VRF.Proof[] proofs) external
+```
+
+Selector `0x9497b180` · Caller: Anyone · Source: `D20VRFCoordinator.sol` lines 399–411
+
+Fulfills up to `MAX_FULFILL_BATCH` (16) requests, one proof each. Members already fulfilled, refunded or past their deadline, including an ID repeated in the batch, are skipped with `FulfillmentSkipped`; every other member runs exactly like `fulfillRandomness` and emits the same events, so an unknown ID, an unready member or an invalid proof reverts the whole batch.
+
+**Emits:** [`FulfillmentSkipped`](#coordinator-event-fulfillmentskipped), [`BlockHashStored`](#coordinator-event-blockhashstored), [`RequestServed`](#coordinator-event-requestserved), [`ProofVerified`](#coordinator-event-proofverified), [`RandomnessFulfilled`](#coordinator-event-randomnessfulfilled), [`FulfillmentEvidence`](#coordinator-event-fulfillmentevidence), [`CallbackAttempted`](#coordinator-event-callbackattempted), [`KeeperFeePaid`](#coordinator-event-keeperfeepaid).
+
+**Errors:** [`InvalidBatch`](#coordinator-error-invalidbatch), [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotReady`](#coordinator-error-notready), [`BlockHashUnavailable`](#coordinator-error-blockhashunavailable), [`WrongPublicKey`](#coordinator-error-wrongpublickey), [`WrongSeed`](#coordinator-error-wrongseed), [`EvidencePacketTooLarge`](#coordinator-error-evidencepackettoolarge), [`InsufficientCallbackGas`](#coordinator-error-insufficientcallbackgas).
+
+#### <a id="coordinator-fn-storeblockhash"></a>`storeBlockHash`
+
+```solidity
+function storeBlockHash(uint256 requestId) external returns (bytes32)
+```
+
+Selector `0x262fd733` · Caller: Anyone · Source: `D20VRFCoordinator.sol` lines 368–372, 564–579
+
+Resolves the target block from the published epoch, stores its hash if not stored yet and returns it. Fulfillment does this automatically; calling it earlier keeps a request provable after its target leaves the 256-block `BLOCKHASH` window. Needs `block.number` at least `targetBlock + confirmationBlocks`. Works on any request, whatever its status.
+
+**Emits:** [`BlockHashStored`](#coordinator-event-blockhashstored).
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotReady`](#coordinator-error-notready), [`BlockHashUnavailable`](#coordinator-error-blockhashunavailable).
+
+#### <a id="coordinator-fn-verifyrequestproof"></a>`verifyRequestProof`
+
+```solidity
+function verifyRequestProof(uint256 requestId, VRF.Proof proof) external view returns (bytes32)
+```
+
+Selector `0x0846de99` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 358–366
+
+Returns the word a proof yields for the request's seed, without changing state. A valid proof is not acceptance: check `getRequest(requestId).fulfilled`.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotReady`](#coordinator-error-notready), [`BlockHashUnavailable`](#coordinator-error-blockhashunavailable), [`WrongPublicKey`](#coordinator-error-wrongpublickey), [`WrongSeed`](#coordinator-error-wrongseed).
+
+#### <a id="coordinator-fn-requestseed"></a>`requestSeed`
+
+```solidity
+function requestSeed(uint256 requestId) external view returns (uint256)
+```
+
+Selector `0xa9df851a` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 374–379, 581–589
+
+Seed the proof must use: `keccak256(abi.encode(SEED_DOMAIN, chainId, coordinator, keyHash, requestId, consumer, clientSeed, mappingHash, requestBlock, targetBlock, blockHash, epochId, epochHash))` as uint256. Available only after publication and `confirmationBlocks` confirmations of the target block.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotReady`](#coordinator-error-notready), [`BlockHashUnavailable`](#coordinator-error-blockhashunavailable).
+
+#### <a id="coordinator-fn-getproofcontext"></a>`getProofContext`
+
+```solidity
+function getProofContext(uint256 requestId) external view returns (uint256 seed, uint64 deadline, bool fulfilled, bool refunded)
+```
+
+Selector `0xcf14de9d` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 381–387
+
+`requestSeed` together with `deadline`, `fulfilled` and `refunded`. It reverts `NotReady` like `requestSeed`, so it is not a status read for waiting requests; use `getRequest`.
+
+**Errors:** [`UnknownRequest`](#coordinator-error-unknownrequest), [`NotReady`](#coordinator-error-notready), [`BlockHashUnavailable`](#coordinator-error-blockhashunavailable).
+
+#### <a id="coordinator-fn-getpendingrequestids"></a>`getPendingRequestIds`
+
+```solidity
+function getPendingRequestIds(uint256 fromId, uint256 limit) external view returns (uint256[] ids, uint256 nextCursor)
+```
+
+Selector `0xfdfe72e6` · Caller: Anyone (view) · Source: `D20VRFCoordinator.sol` lines 310–329
+
+Scans `limit` (1 to 256) request IDs from `fromId` (at least 1) and returns those not fulfilled, not refunded and not past their deadline, with the ID to continue from. Continue with `nextCursor` until it equals `nextRequestId()`. The answer can be stale by the time a transaction lands.
+
+**Errors:** [`InvalidScan`](#coordinator-error-invalidscan).
+
+### <a id="coordinator-keeper-key-and-configuration-reads"></a>Keeper, key and configuration reads
+
+Views, callable by anyone. Nothing here has a setter except through an upgrade.
+
+| Function | Selector | Meaning | Source |
+| --- | --- | --- | --- |
+| <a id="coordinator-fn-lastservedrequestid"></a>`lastServedRequestId() returns (uint256)` | `0xef54e226` | ID of the most recently accepted request; 0 before the first. | lines 53, 435 |
+| <a id="coordinator-fn-lastservedindex"></a>`lastServedIndex() returns (uint256)` | `0x7e176eed` | Number of accepted requests so far: the `serveIndex` of the latest `RequestServed`. | lines 54, 436 |
+| <a id="coordinator-fn-servedrequestat"></a>`servedRequestAt(uint256) returns (uint256)` | `0xf9a4acc6` | Request ID accepted at a serve index (from 1); 0 for an index not used yet. | lines 55, 436 |
+| <a id="coordinator-fn-keyhash"></a>`keyHash() returns (bytes32)` | `0x61728f39` | `keccak256(abi.encode(publicKey))` of the VRF key; indexed in `RandomnessRequested` and `ProofVerified`. | lines 37, 180 |
+| <a id="coordinator-fn-publickeyx"></a>`publicKeyX() returns (uint256)` | `0xfa6df55d` | x coordinate of the VRF public key. | line 35 |
+| <a id="coordinator-fn-publickeyy"></a>`publicKeyY() returns (uint256)` | `0xd7a6f6e8` | y coordinate of the VRF public key. | line 36 |
+| <a id="coordinator-fn-confirmationblocks"></a>`confirmationBlocks() returns (uint16)` | `0x460a58aa` | Blocks after the target block before the seed and proofs become available (1 to 64, set at initialization). | lines 45, 566 |
+| <a id="coordinator-fn-epochregistry"></a>`epochRegistry() returns (address)` | `0x2b12cb69` | The `EpochEntropy` proxy that supplies epochs and the keeper-share recipient. | line 33 |
+| <a id="coordinator-fn-protocolconfigurationhash"></a>`protocolConfigurationHash() returns (bytes32)` | `0x155cf49b` | Hash of the initialized configuration (public key, initial fee recipient, initial minimum fee, confirmations, registry, initial catalog hash, first epoch start, epoch length 200) under `CONFIG_DOMAIN`. Bound into every transcript hash. | lines 32, 190 |
+| <a id="coordinator-fn-initialfeerecipient"></a>`initialFeeRecipient() returns (address)` | `0x308c2d6b` | Fee recipient given to `initialize`, used by replay. The live payout address is `feeRecipient()`. | lines 39, 182 |
+| <a id="coordinator-fn-initialminfee"></a>`initialMinFee() returns (uint256)` | `0xb3839295` | Minimum fee given to `initialize`, used by replay. The live minimum is `minFee()`. | lines 105, 185 |
+
+### <a id="coordinator-owner-administration"></a>Owner administration
+
+Owner-only functions revert `OwnableUnauthorizedAccount` for anyone else. No setter can change an existing request, the VRF key, the registry or the confirmations.
+
+#### <a id="coordinator-fn-setpricing"></a>`setPricing`
+
+```solidity
+function setPricing(uint256 nextMinFee, uint16 multiplier, uint32 overhead) external
+```
+
+Selector `0x4c729ce6` · Caller: Owner · Source: `D20VRFCoordinator.sol` lines 205–210
+
+Sets `minFee` (at most `MAX_MIN_FEE`, 10 USDC), `feeMultiplier` (at most `MAX_FEE_MULTIPLIER`, 20) and `fulfillGasOverhead` (`MIN_FULFILL_GAS_OVERHEAD` to `MAX_FULFILL_GAS_OVERHEAD`, 100,000 to 2,000,000 gas). Affects requests created afterwards; open requests keep their escrowed fee.
+
+**Emits:** [`PricingChanged`](#coordinator-event-pricingchanged).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount), [`InvalidConfig`](#coordinator-error-invalidconfig).
+
+#### <a id="coordinator-fn-setrefundbps"></a>`setRefundBps`
+
+```solidity
+function setRefundBps(uint16 next) external
+```
+
+Selector `0x55a94d1b` · Caller: Owner · Source: `D20VRFCoordinator.sol` lines 214–218
+
+Sets the refund ratio for requests created afterwards, `MIN_REFUND_BPS` (5000) to 10000.
+
+**Emits:** [`RefundBpsChanged`](#coordinator-event-refundbpschanged).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount), [`InvalidConfig`](#coordinator-error-invalidconfig).
+
+#### <a id="coordinator-fn-setkeeperfeebps"></a>`setKeeperFeeBps`
+
+```solidity
+function setKeeperFeeBps(uint16 next) external
+```
+
+Selector `0xe140f0ca` · Caller: Owner · Source: `D20VRFCoordinator.sol` lines 201–204
+
+Sets the keeper share, 0 to 10000 basis points. Read at each acceptance, so it also applies to open requests accepted later.
+
+**Emits:** [`KeeperFeeBpsChanged`](#coordinator-event-keeperfeebpschanged).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount), [`InvalidConfig`](#coordinator-error-invalidconfig).
+
+#### <a id="coordinator-fn-setfeerecipient"></a>`setFeeRecipient`
+
+```solidity
+function setFeeRecipient(address next) external
+```
+
+Selector `0xe74b981b` · Caller: Owner · Source: `D20VRFCoordinator.sol` lines 197–200
+
+Sets the address allowed to withdraw `earnedFees`, including fees earned before the change. The zero address is rejected.
+
+**Emits:** [`FeeRecipientChanged`](#coordinator-event-feerecipientchanged).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount), [`InvalidConfig`](#coordinator-error-invalidconfig).
+
+#### <a id="coordinator-fn-owner"></a>`owner`
+
+```solidity
+function owner() external view returns (address)
+```
+
+Selector `0x8da5cb5b` · Caller: Anyone (view)
+
+Current owner: upgrade authority and the only account that can call the setters.
+
+#### <a id="coordinator-fn-pendingowner"></a>`pendingOwner`
+
+```solidity
+function pendingOwner() external view returns (address)
+```
+
+Selector `0xe30c3978` · Caller: Anyone (view)
+
+Account nominated by `transferOwnership` that has not accepted yet; zero when none.
+
+#### <a id="coordinator-fn-transferownership"></a>`transferOwnership`
+
+```solidity
+function transferOwnership(address newOwner) external
+```
+
+Selector `0xf2fde38b` · Caller: Owner
+
+Starts a two-step transfer by nominating `newOwner`; ownership moves only when that account calls `acceptOwnership`. A new call replaces the nomination, and the zero address cancels it.
+
+**Emits:** [`OwnershipTransferStarted`](#coordinator-event-ownershiptransferstarted).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount).
+
+#### <a id="coordinator-fn-acceptownership"></a>`acceptOwnership`
+
+```solidity
+function acceptOwnership() external
+```
+
+Selector `0x79ba5097` · Caller: Pending owner
+
+Completes the transfer to the caller and clears the nomination.
+
+**Emits:** [`OwnershipTransferred`](#coordinator-event-ownershiptransferred).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount).
+
+#### <a id="coordinator-fn-renounceownership"></a>`renounceOwnership`
+
+```solidity
+function renounceOwnership() external view
+```
+
+Selector `0x715018a6` · Caller: Owner · Source: `D20VRFCoordinator.sol` lines 194–195
+
+Disabled and declared `view`: the owner gets `RenounceDisabled` and anyone else `OwnableUnauthorizedAccount`, so the contract always has an owner and upgrade authority can only move through an accepted transfer.
+
+**Errors:** [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount), [`RenounceDisabled`](#coordinator-error-renouncedisabled).
+
+#### <a id="coordinator-fn-upgradetoandcall"></a>`upgradeToAndCall`
+
+```solidity
+function upgradeToAndCall(address newImplementation, bytes data) external payable
+```
+
+Selector `0x4f1ef286` · Caller: Owner, through the proxy
+
+UUPS upgrade: points the proxy at `newImplementation`, which must report the ERC-1967 slot from `proxiableUUID`, and delegatecalls `data` when it is non-empty. An upgrade can change any behavior described here. Integrators check the implementation when they integrate and again whenever a proxy emits `Upgraded` or the deployment manifest records an upgrade (README [Security and trust](README.md#security-and-trust)).
+
+**Emits:** [`Upgraded`](#coordinator-event-upgraded).
+
+**Errors:** [`UUPSUnauthorizedCallContext`](#coordinator-error-uupsunauthorizedcallcontext), [`OwnableUnauthorizedAccount`](#coordinator-error-ownableunauthorizedaccount), [`ERC1967InvalidImplementation`](#coordinator-error-erc1967invalidimplementation), [`UUPSUnsupportedProxiableUUID`](#coordinator-error-uupsunsupportedproxiableuuid), [`ERC1967NonPayable`](#coordinator-error-erc1967nonpayable), [`AddressEmptyCode`](#coordinator-error-addressemptycode), [`FailedCall`](#coordinator-error-failedcall).
+
+#### <a id="coordinator-fn-proxiableuuid"></a>`proxiableUUID`
+
+```solidity
+function proxiableUUID() external view returns (bytes32)
+```
+
+Selector `0x52d1902d` · Caller: Anyone (view)
+
+ERC-1822 check used by `upgradeToAndCall`. Returns the ERC-1967 implementation slot when called on an implementation contract directly and reverts through the proxy.
+
+**Errors:** [`UUPSUnauthorizedCallContext`](#coordinator-error-uupsunauthorizedcallcontext).
+
+#### <a id="coordinator-fn-initialize"></a>`initialize`
+
+```solidity
+function initialize(uint256[2] publicKey, address initialOwner, address recipient, uint256 fee, uint16 confirmations, address registry, uint16 keeperBps) external
+```
+
+Selector `0x56b95b47` · Caller: Once, by `D20Proxy` at deployment · Source: `D20VRFCoordinator.sol` lines 170–191
+
+Sets owner, VRF public key, fee recipient, minimum fee, confirmations, registry and keeper share, with `feeMultiplier` 5, `fulfillGasOverhead` 300,000 and `refundBps` 10000. A public key that is not on the curve can also revert with an `Error(string)` from the verifier.
+
+**Emits:** [`OwnershipTransferred`](#coordinator-event-ownershiptransferred), [`Initialized`](#coordinator-event-initialized).
+
+**Errors:** [`InvalidInitialization`](#coordinator-error-invalidinitialization), [`OwnableInvalidOwner`](#coordinator-error-ownableinvalidowner), [`InvalidConfig`](#coordinator-error-invalidconfig), [`InvalidPublicKey`](#coordinator-error-invalidpublickey).
+
+### <a id="coordinator-constants"></a>Constants
+
+Views returning values fixed in the implementation code.
+
+| Constant | Returns | Value | Selector | Meaning |
+| --- | --- | --- | --- | --- |
+| <a id="coordinator-fn-min_callback_gas"></a>`MIN_CALLBACK_GAS` | `uint32` | `30_000` | `0x4374e10c` | Lowest `callbackGasLimit` and `retryCallback` gas limit. |
+| <a id="coordinator-fn-max_callback_gas"></a>`MAX_CALLBACK_GAS` | `uint32` | `1_000_000` | `0x6d9809a0` | Highest callback or notification gas limit. |
+| <a id="coordinator-fn-response_timeout"></a>`RESPONSE_TIMEOUT` | `uint64` | `60 seconds` | `0x11e219d7` | Seconds from the request block timestamp to `deadline`. |
+| <a id="coordinator-fn-refund_callback_gas"></a>`REFUND_CALLBACK_GAS` | `uint32` | `100_000` | `0x8a8ae284` | Gas for the first `onRefund` notification, and the lowest `retryRefundCallback` gas limit. |
+| <a id="coordinator-fn-max_fulfill_batch"></a>`MAX_FULFILL_BATCH` | `uint256` | `16` | `0x1d7e0cc4` | Most requests per `fulfillRandomnessBatch`. |
+| <a id="coordinator-fn-max_evidence_packet_bytes"></a>`MAX_EVIDENCE_PACKET_BYTES` | `uint256` | `512` | `0x7fcf2f33` | Upper bound on the `FulfillmentEvidence` packet (actual size 416 bytes). |
+| <a id="coordinator-fn-max_min_fee"></a>`MAX_MIN_FEE` | `uint256` | `10e18` | `0x8483d43e` | Highest `minFee`: 10 USDC in 18-decimal native units. |
+| <a id="coordinator-fn-max_fee_multiplier"></a>`MAX_FEE_MULTIPLIER` | `uint16` | `20` | `0xb6994144` | Highest `feeMultiplier`. |
+| <a id="coordinator-fn-min_fulfill_gas_overhead"></a>`MIN_FULFILL_GAS_OVERHEAD` | `uint32` | `100_000` | `0x35ccd0b4` | Lowest `fulfillGasOverhead`. |
+| <a id="coordinator-fn-max_fulfill_gas_overhead"></a>`MAX_FULFILL_GAS_OVERHEAD` | `uint32` | `2_000_000` | `0x2a06b47d` | Highest `fulfillGasOverhead`. |
+| <a id="coordinator-fn-min_refund_bps"></a>`MIN_REFUND_BPS` | `uint16` | `5000` | `0xaf7718f1` | Lowest `refundBps` (50%). |
+| <a id="coordinator-fn-seed_domain"></a>`SEED_DOMAIN` | `bytes32` | `keccak256("D20_VRF_SEED")` | `0x6000054d` | Domain tag of `requestSeed`. |
+| <a id="coordinator-fn-transcript_domain"></a>`TRANSCRIPT_DOMAIN` | `bytes32` | `keccak256("D20_VRF_TRANSCRIPT")` | `0xab2fde00` | Domain tag of the transcript hash. |
+| <a id="coordinator-fn-config_domain"></a>`CONFIG_DOMAIN` | `bytes32` | `keccak256("D20_VRF_CONFIG")` | `0x3624ffed` | Domain tag of `protocolConfigurationHash`. |
+| <a id="coordinator-fn-upgrade_interface_version"></a>`UPGRADE_INTERFACE_VERSION` | `string` | `"5.0.0"` | `0xad3cb1cc` | OpenZeppelin UUPS interface version: upgrades go through `upgradeToAndCall` only. |
+
+### <a id="coordinator-events"></a>Events
+
+**Request lifecycle**
+
+#### <a id="coordinator-event-randomnessrequested"></a>`RandomnessRequested`
+
+```solidity
+event RandomnessRequested(uint256 indexed requestId, address indexed consumer, bytes32 indexed keyHash, bytes32 clientSeed, uint64 requestBlock, uint32 callbackGasLimit, uint256 feePaid, address refundAddress, uint64 deadline)
+```
+
+Topic 0 `0xaf91b17376114a36689aa115062983bda7b43263a891fb8de0cc69d30d4240ad` · Emitted by: [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness) · Source: `D20VRFCoordinator.sol` lines 139–143, 284–285
+
+A request was created. `feePaid` is the escrowed fee, not `msg.value`; `deadline` is the block timestamp plus 60 seconds. Read `requestId` from this log in the request receipt, filtering by the coordinator address and event name: with an overpayment, `FeeOverpaymentCredited` comes first.
+
+#### <a id="coordinator-event-mappingrequested"></a>`MappingRequested`
+
+```solidity
+event MappingRequested(uint256 indexed requestId, bytes32 indexed mappingHash, RandomnessMapping.Spec spec)
+```
+
+Topic 0 `0xbe1c93f40bd74ff9acd22dc40818e36d04e0b8a49b8238d0537c63219c2336dd` · Emitted by: [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness) · Source: `D20VRFCoordinator.sol` lines 158, 286
+
+Emitted right after `RandomnessRequested` with the stored spec (all zero for a raw request) and its hash.
+
+#### <a id="coordinator-event-feeoverpaymentcredited"></a>`FeeOverpaymentCredited`
+
+```solidity
+event FeeOverpaymentCredited(uint256 indexed requestId, address indexed refundAddress, uint256 amount)
+```
+
+Topic 0 `0x8ae693db98f043f48e8f427375449ed5576aba97575e4f7f93ff2c1f6c75dcb5` · Emitted by: [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness) · Source: `D20VRFCoordinator.sol` lines 152, 278–283
+
+`msg.value` exceeded the fee and `amount` was added to `refundCredits(refundAddress)`, independently of what happens to the request. Emitted before `RandomnessRequested`.
+
+#### <a id="coordinator-event-blockhashstored"></a>`BlockHashStored`
+
+```solidity
+event BlockHashStored(uint256 indexed requestId, uint64 targetBlock, bytes32 blockHash)
+```
+
+Topic 0 `0x81bc3b4ec75af0fb9ed3521d7c766d8f995d04b0735c17d61ff9d468b0f04911` · Emitted by: [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch), [`storeBlockHash`](#coordinator-fn-storeblockhash) · Source: `D20VRFCoordinator.sol` lines 144, 572–579
+
+The target block hash of the request was stored. Emitted once per request: by `storeBlockHash`, or by fulfillment if the hash was not stored before.
+
+#### <a id="coordinator-event-requestserved"></a>`RequestServed`
+
+```solidity
+event RequestServed(uint256 indexed requestId, uint256 indexed serveIndex)
+```
+
+Topic 0 `0x2012511e6cebd578bcabff1ef3346edb032cbab8622e9f23d9f15d7d1037267f` · Emitted by: [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch) · Source: `D20VRFCoordinator.sol` lines 160, 435–437
+
+A proof was accepted. `serveIndex` counts accepted requests from 1 (`lastServedIndex`, `servedRequestAt`).
+
+#### <a id="coordinator-event-proofverified"></a>`ProofVerified`
+
+```solidity
+event ProofVerified(uint256 indexed requestId, bytes32 indexed keyHash, uint256 seed, bytes32 proofHash)
+```
+
+Topic 0 `0x55bb25be3ecd9f68ceae7cdabf4eabe2e0940bd8fc1c26c0d68ad5f7c5d08d22` · Emitted by: [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch) · Source: `D20VRFCoordinator.sol` lines 159, 438
+
+Seed and hash of the accepted proof.
+
+#### <a id="coordinator-event-randomnessfulfilled"></a>`RandomnessFulfilled`
+
+```solidity
+event RandomnessFulfilled(uint256 indexed requestId, bytes32 randomness, address indexed submitter)
+```
+
+Topic 0 `0x9c82683ee7932041c254d206bcce4241d66a811d53ee7191799cc120777b2b87` · Emitted by: [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch) · Source: `D20VRFCoordinator.sol` lines 145, 439
+
+A proof was accepted and `randomness` is final. `submitter` sent the transaction; `KeeperFeePaid` names the wallet that received the keeper share, which is `submitter` only when the registry authorizes it.
+
+#### <a id="coordinator-event-fulfillmentevidence"></a>`FulfillmentEvidence`
+
+```solidity
+event FulfillmentEvidence(uint256 indexed requestId, bytes32 indexed transcriptHash, bytes packet)
+```
+
+Topic 0 `0xa121bbea897439460dfb08c3e6d6af064bc1f31e9477471828a87c5596b92e77` · Emitted by: [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch) · Source: `D20VRFCoordinator.sol` lines 163–164, 450–454
+
+The accepted proof as a 416-byte ABI-encoded packet, indexed by `transcriptHash`. Decode it with `decodeEvidencePacket`; take evidence from this log, not from calldata, since a batch carries several proofs.
+
+#### <a id="coordinator-event-callbackattempted"></a>`CallbackAttempted`
+
+```solidity
+event CallbackAttempted(uint256 indexed requestId, bool success, uint32 gasLimit)
+```
+
+Topic 0 `0x70f64c0739e827900ae6f2e1317601653f4080bc857f423671fc58d5822f1f4a` · Emitted by: [`retryCallback`](#coordinator-fn-retrycallback), [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch) · Source: `D20VRFCoordinator.sol` lines 146, 613–630
+
+Result of calling `rawFulfillRandomness` with `gasLimit` gas, at fulfillment and at each `retryCallback`. `success` false means the consumer reverted, ran out of gas or has no code; the word is accepted either way.
+
+#### <a id="coordinator-event-keeperfeepaid"></a>`KeeperFeePaid`
+
+```solidity
+event KeeperFeePaid(uint256 indexed requestId, address indexed keeper, uint256 amount, bool paid)
+```
+
+Topic 0 `0x7605929b04963e0365f647d9ab12e7ac4aeba5474bb80f1e1554fccad0584683` · Emitted by: [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch) · Source: `D20VRFCoordinator.sol` lines 153, 442–447
+
+At acceptance, when the keeper share is non-zero: `amount` went to `keeper`, the submitter when the registry authorizes it and `committer()` otherwise, by a 30,000-gas transfer (`paid` true) or was added to `keeperCredits(keeper)` (`paid` false). Emitted after `CallbackAttempted`.
+
+#### <a id="coordinator-event-fulfillmentskipped"></a>`FulfillmentSkipped`
+
+```solidity
+event FulfillmentSkipped(uint256 indexed requestId, uint8 reason)
+```
+
+Topic 0 `0x45d96bda73a91db41bdeab56114e5d7b9f42c9f38add9e2d2c6d6f5761203ca3` · Emitted by: [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch) · Source: `D20VRFCoordinator.sol` lines 161–162, 407–408
+
+A batch member was left untouched: `reason` 1 already fulfilled, 2 refunded, 3 past its deadline.
+
+#### <a id="coordinator-event-requestrefundedto"></a>`RequestRefundedTo`
+
+```solidity
+event RequestRefundedTo(uint256 indexed requestId, address indexed refundAddress, uint256 amount, bool paid)
+```
+
+Topic 0 `0x0f6107d218fea62a20553f3700dba7c94dcf653bd2027c0bf1ebe0832f42a506` · Emitted by: [`refundRequest`](#coordinator-fn-refundrequest) · Source: `D20VRFCoordinator.sol` lines 155, 488
+
+An expired request was refunded: `amount` (`feePaid × requestRefundBps / 10000`) was sent to `refundAddress` (`paid` true) or added to its refund credit (`paid` false).
+
+#### <a id="coordinator-event-refundcallbackattempted"></a>`RefundCallbackAttempted`
+
+```solidity
+event RefundCallbackAttempted(uint256 indexed requestId, address indexed consumer, bool success, uint32 gasLimit)
+```
+
+Topic 0 `0x88448c9fbcfc67f28f0266e82766e402ccd28115fbb84edb6e5b2597effe83d8` · Emitted by: [`refundRequest`](#coordinator-fn-refundrequest), [`retryRefundCallback`](#coordinator-fn-retryrefundcallback) · Source: `D20VRFCoordinator.sol` lines 157, 502–513
+
+Result of calling `onRefund(requestId)` on `consumer` with `gasLimit` gas: 100,000 at `refundRequest`, the caller's limit at `retryRefundCallback`.
+
+**Credits and withdrawals**
+
+#### <a id="coordinator-event-refundcreditwithdrawn"></a>`RefundCreditWithdrawn`
+
+```solidity
+event RefundCreditWithdrawn(address indexed owner, address indexed recipient, uint256 amount)
+```
+
+Topic 0 `0x9d520065b24fda0469128acd3f3078de7e43d70ab762aeea8c741bde25070192` · Emitted by: [`withdrawRefundCredit`](#coordinator-fn-withdrawrefundcredit) · Source: `D20VRFCoordinator.sol` lines 156, 524
+
+`owner`, the credit holder (not the contract owner), withdrew `amount` of refund credit to `recipient`.
+
+#### <a id="coordinator-event-keepercreditwithdrawn"></a>`KeeperCreditWithdrawn`
+
+```solidity
+event KeeperCreditWithdrawn(address indexed keeper, address indexed recipient, uint256 amount)
+```
+
+Topic 0 `0x22f05c41968705c032a86a65f8fda7e64483ea5e6b6b27a920d1fbfab94267ba` · Emitted by: [`withdrawKeeperCredit`](#coordinator-fn-withdrawkeepercredit) · Source: `D20VRFCoordinator.sol` lines 154, 546
+
+`keeper` withdrew `amount` of keeper credit to `recipient`.
+
+#### <a id="coordinator-event-feeswithdrawn"></a>`FeesWithdrawn`
+
+```solidity
+event FeesWithdrawn(address indexed recipient, uint256 amount)
+```
+
+Topic 0 `0xc0819c13be868895eb93e40eaceb96de976442fa1d404e5c55f14bb65a8c489a` · Emitted by: [`withdrawFees`](#coordinator-fn-withdrawfees) · Source: `D20VRFCoordinator.sol` lines 147, 535
+
+The fee recipient withdrew `amount` of earned fees to `recipient`.
+
+**Administration and upgrades**
+
+#### <a id="coordinator-event-pricingchanged"></a>`PricingChanged`
+
+```solidity
+event PricingChanged(uint256 minFee, uint16 feeMultiplier, uint32 fulfillGasOverhead)
+```
+
+Topic 0 `0x32806eb5e21ac2f5fb7d11f898c2995e19fdf203c8a5aeed8b824506cd0d44ff` · Emitted by: [`setPricing`](#coordinator-fn-setpricing) · Source: `D20VRFCoordinator.sol` lines 150, 209
+
+New `minFee`, `feeMultiplier` and `fulfillGasOverhead` for requests created afterwards.
+
+#### <a id="coordinator-event-refundbpschanged"></a>`RefundBpsChanged`
+
+```solidity
+event RefundBpsChanged(uint16 previousBps, uint16 newBps)
+```
+
+Topic 0 `0x21e3c4cf3007c4ee385a3936593ff4cfa23fc17bca1175b6350c546f9810e0d8` · Emitted by: [`setRefundBps`](#coordinator-fn-setrefundbps) · Source: `D20VRFCoordinator.sol` lines 151, 217
+
+New refund ratio for requests created afterwards.
+
+#### <a id="coordinator-event-keeperfeebpschanged"></a>`KeeperFeeBpsChanged`
+
+```solidity
+event KeeperFeeBpsChanged(uint16 previousBps, uint16 newBps)
+```
+
+Topic 0 `0xa648a60f1d22511c1cc898ca69b633d1a1114079e83734b9ab9a13e0e28c68b7` · Emitted by: [`setKeeperFeeBps`](#coordinator-fn-setkeeperfeebps) · Source: `D20VRFCoordinator.sol` lines 149, 203
+
+New keeper share, applied at later acceptances, including of requests already open.
+
+#### <a id="coordinator-event-feerecipientchanged"></a>`FeeRecipientChanged`
+
+```solidity
+event FeeRecipientChanged(address indexed previousRecipient, address indexed newRecipient)
+```
+
+Topic 0 `0x0bc21fe5c3ab742ff1d15b5c4477ffbacf1167e618228078fa625edebe7f331d` · Emitted by: [`setFeeRecipient`](#coordinator-fn-setfeerecipient) · Source: `D20VRFCoordinator.sol` lines 148, 199
+
+New address allowed to withdraw earned fees.
+
+#### <a id="coordinator-event-ownershiptransferstarted"></a>`OwnershipTransferStarted`
+
+```solidity
+event OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner)
+```
+
+Topic 0 `0x38d16b8cac22d99fc7c124b9cd0de2d3fa1faef420bfe791d8c362d765e22700` · Emitted by: [`transferOwnership`](#coordinator-fn-transferownership)
+
+`transferOwnership` nominated `newOwner`; the zero address means a nomination was cancelled.
+
+#### <a id="coordinator-event-ownershiptransferred"></a>`OwnershipTransferred`
+
+```solidity
+event OwnershipTransferred(address indexed previousOwner, address indexed newOwner)
+```
+
+Topic 0 `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` · Emitted by: [`acceptOwnership`](#coordinator-fn-acceptownership), [`initialize`](#coordinator-fn-initialize)
+
+Ownership moved: from the zero address at initialization, and at each `acceptOwnership`.
+
+#### <a id="coordinator-event-upgraded"></a>`Upgraded`
+
+```solidity
+event Upgraded(address indexed implementation)
+```
+
+Topic 0 `0xbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b` · Emitted by: [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall), proxy deployment
+
+The proxy now runs `implementation`. Emitted by the proxy at deployment and at every `upgradeToAndCall`. Compare the address with the deployment manifest; an implementation you have not reviewed means stop and review before sending more requests.
+
+#### <a id="coordinator-event-initialized"></a>`Initialized`
+
+```solidity
+event Initialized(uint64 version)
+```
+
+Topic 0 `0xc7f505b2f371ae2175ee4913f4499e1f2633a7b5936321eed1cdaeb6115181d2` · Emitted by: [`initialize`](#coordinator-fn-initialize)
+
+`initialize` ran on the proxy (`version` 1). Each implementation contract also emitted it once at construction with `version` 2^64 − 1, which locks the implementation against initialization.
+
+### <a id="coordinator-errors"></a>Errors
+
+**Requesting**
+
+#### <a id="coordinator-error-contractconsumerrequired"></a>`ContractConsumerRequired`
+
+`error ContractConsumerRequired()` · Selector `0x2b99db1e` · Source: `D20VRFCoordinator.sol` lines 111, 251
+
+**Raised by:** [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness).
+
+The caller of a request function has no code: an externally owned account, or a contract still running its constructor.
+
+**What to do:** Send the request through a deployed consumer contract (README [Integrate a consumer](README.md#integrate-a-consumer)), and not from its constructor.
+
+#### <a id="coordinator-error-invalidrefundaddress"></a>`InvalidRefundAddress`
+
+`error InvalidRefundAddress()` · Selector `0xe2fe2726` · Source: `D20VRFCoordinator.sol` lines 125, 252, 517
+
+**Raised by:** [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness), [`withdrawRefundCredit`](#coordinator-fn-withdrawrefundcredit).
+
+A request named the zero address as refund address, or `withdrawRefundCredit` named the zero address as recipient.
+
+**What to do:** Pass a non-zero address that can receive a plain native transfer or call `withdrawRefundCredit`.
+
+#### <a id="coordinator-error-invalidcallbackgas"></a>`InvalidCallbackGas`
+
+`error InvalidCallbackGas()` · Selector `0x35883c54` · Source: `D20VRFCoordinator.sol` lines 113, 462, 498, 609–611
+
+**Raised by:** [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness), [`retryCallback`](#coordinator-fn-retrycallback), [`retryRefundCallback`](#coordinator-fn-retryrefundcallback).
+
+A gas limit is out of range: a request `callbackGasLimit` outside 30,000 to 1,000,000; a `retryCallback` limit outside that range or below the request's `callbackGasLimit`; a `retryRefundCallback` limit outside 100,000 to 1,000,000.
+
+**What to do:** Use a limit inside the range; retry with at least the original limit.
+
+#### <a id="coordinator-error-incorrectfee"></a>`IncorrectFee`
+
+`error IncorrectFee(uint256 expected, uint256 actual)` · Selector `0xdcf6afcb` · Source: `D20VRFCoordinator.sol` lines 112, 255
+
+**Raised by:** [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness).
+
+`actual` (`msg.value`) is below `expected`, the fee computed in the request transaction. No request was created.
+
+**What to do:** Quote again with `quoteFeeAt(callbackGasLimit, latestBlock.baseFeePerGas)` plus a buffer (`quoteRequestFee`) and resend. A contract paying in the same transaction sends `quoteFee(callbackGasLimit)`. Never quote with `quoteFee` through `eth_call`.
+
+#### <a id="coordinator-error-feeoverflow"></a>`FeeOverflow`
+
+`error FeeOverflow()` · Selector `0x8181adca` · Source: `D20VRFCoordinator.sol` lines 136, 225
+
+**Raised by:** [`quoteFee`](#coordinator-fn-quotefee), [`quoteFeeAt`](#coordinator-fn-quotefeeat), [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness).
+
+The dynamic fee exceeds the uint96 escrow limit. Within the pricing bounds that needs a base fee above about 1.3e21 wei.
+
+**What to do:** Not expected on a live chain. For `quoteFeeAt`, check that `baseFee` is in wei.
+
+#### <a id="coordinator-error-invalidmapping"></a>`InvalidMapping`
+
+`error InvalidMapping()` · Selector `0x07a966e0` · Source: `libraries/RandomnessMapping.sol` lines 19, 21–39
+
+**Raised by:** [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness), [`mapRandomness`](#coordinator-fn-maprandomness).
+
+The spec breaks the rules for its operation (README [Randomness options](README.md#randomness-options)). Declared in `RandomnessMapping`.
+
+**What to do:** Build specs with the `D20VRFRequests` helpers or TypeScript `builtins`, which enforce the same bounds.
+
+#### <a id="coordinator-error-epochunavailable"></a>`EpochUnavailable`
+
+`error EpochUnavailable()` · Selector `0x0b3487b8` · Source: `D20VRFCoordinator.sol` lines 109, 259
+
+**Raised by:** [`requestRandomness`](#coordinator-fn-requestrandomness), [`requestMappedRandomness`](#coordinator-fn-requestmappedrandomness).
+
+The request block is before the registry's first epoch: `epochForBlock(block.number)` is 0.
+
+**What to do:** Not expected on the Arc deployments, whose epochs have started. Check that you call the coordinator proxy for your chain; on a new deployment, wait for `firstEpochStart`.
+
+**Reading and recovery**
+
+#### <a id="coordinator-error-unknownrequest"></a>`UnknownRequest`
+
+`error UnknownRequest()` · Selector `0x6d080297` · Source: `D20VRFCoordinator.sol` lines 114, 549–552
+
+**Raised by:** [`getRequest`](#coordinator-fn-getrequest), [`getMapping`](#coordinator-fn-getmapping), [`getMappedResult`](#coordinator-fn-getmappedresult), [`requestFeePaid`](#coordinator-fn-requestfeepaid), [`requestRefundBps`](#coordinator-fn-requestrefundbps), [`refundRequest`](#coordinator-fn-refundrequest), [`retryCallback`](#coordinator-fn-retrycallback), [`retryRefundCallback`](#coordinator-fn-retryrefundcallback), [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch), [`storeBlockHash`](#coordinator-fn-storeblockhash), [`verifyRequestProof`](#coordinator-fn-verifyrequestproof), [`requestSeed`](#coordinator-fn-requestseed), [`getProofContext`](#coordinator-fn-getproofcontext).
+
+No request has this ID: 0, or not below `nextRequestId()`. An unknown ID also reverts a whole `fulfillRandomnessBatch`.
+
+**What to do:** Take `requestId` from the `RandomnessRequested` log of the request receipt, and read from the same chain and coordinator proxy.
+
+#### <a id="coordinator-error-notfulfilled"></a>`NotFulfilled`
+
+`error NotFulfilled()` · Selector `0x07bc6c3e` · Source: `D20VRFCoordinator.sol` lines 118, 347, 459
+
+**Raised by:** [`getMappedResult`](#coordinator-fn-getmappedresult), [`retryCallback`](#coordinator-fn-retrycallback).
+
+`getMappedResult` or `retryCallback` on a request without an accepted proof, including an expired or refunded one.
+
+**What to do:** Poll `getRequest(requestId)` until `fulfilled`. Once a block timestamp is after `deadline` without fulfillment, the request has expired and only `refundRequest` applies.
+
+#### <a id="coordinator-error-alreadydelivered"></a>`AlreadyDelivered`
+
+`error AlreadyDelivered()` · Selector `0xb9f79653` · Source: `D20VRFCoordinator.sol` lines 119, 460
+
+**Raised by:** [`retryCallback`](#coordinator-fn-retrycallback).
+
+`retryCallback` on a request whose callback already succeeded.
+
+**What to do:** Nothing to retry.
+
+#### <a id="coordinator-error-refundnotavailable"></a>`RefundNotAvailable`
+
+`error RefundNotAvailable()` · Selector `0x0b4d6981` · Source: `D20VRFCoordinator.sol` lines 128, 471
+
+**Raised by:** [`refundRequest`](#coordinator-fn-refundrequest).
+
+`refundRequest` on a request that is fulfilled, already refunded, or not yet past its deadline (the block timestamp must be greater than `deadline`).
+
+**What to do:** Read `getRequest`: use the result if `fulfilled`, stop if `refunded`, otherwise retry after a block with a later timestamp than `deadline`.
+
+#### <a id="coordinator-error-notrefunded"></a>`NotRefunded`
+
+`error NotRefunded()` · Selector `0xfae7079c` · Source: `D20VRFCoordinator.sol` lines 131, 495
+
+**Raised by:** [`retryRefundCallback`](#coordinator-fn-retryrefundcallback).
+
+`retryRefundCallback` on a request that has not been refunded.
+
+**What to do:** Call `refundRequest` after the deadline first.
+
+#### <a id="coordinator-error-refundcallbackalreadydelivered"></a>`RefundCallbackAlreadyDelivered`
+
+`error RefundCallbackAlreadyDelivered()` · Selector `0x6502f8ae` · Source: `D20VRFCoordinator.sol` lines 132, 496
+
+**Raised by:** [`retryRefundCallback`](#coordinator-fn-retryrefundcallback).
+
+`retryRefundCallback` after an `onRefund` notification already succeeded (`refundCallbackDelivered`).
+
+**What to do:** Nothing to retry.
+
+#### <a id="coordinator-error-insufficientcallbackgas"></a>`InsufficientCallbackGas`
+
+`error InsufficientCallbackGas()` · Selector `0xa2c23f0d` · Source: `D20VRFCoordinator.sol` lines 122, 480, 505, 621–622
+
+**Raised by:** [`refundRequest`](#coordinator-fn-refundrequest), [`retryCallback`](#coordinator-fn-retrycallback), [`retryRefundCallback`](#coordinator-fn-retryrefundcallback), [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch).
+
+Too little gas remained to forward the full callback budget and keep the coordinator's reserve: `gasLimit + gasLimit/63 + 140,000` before a fulfillment callback, `100,000 + 100,000/63 + 140,000` after refund settlement, `gasLimit + gasLimit/63 + 50,000` before a refund notification. The coordinator reverts instead of forwarding less.
+
+**What to do:** Raise the transaction gas limit: 400,000 for `refundRequest`, `gasLimit + 250,000` for `retryCallback`, `gasLimit + 150,000` for `retryRefundCallback` (README [Gas for refund and retry calls](README.md#gas-for-refund-and-retry-calls)). `eth_estimateGas` finds the minimum.
+
+**Credits and withdrawals**
+
+#### <a id="coordinator-error-norefundcredit"></a>`NoRefundCredit`
+
+`error NoRefundCredit()` · Selector `0x1d59da8e` · Source: `D20VRFCoordinator.sol` lines 129, 519
+
+**Raised by:** [`withdrawRefundCredit`](#coordinator-fn-withdrawrefundcredit).
+
+`withdrawRefundCredit` from an address without refund credit. Credit is keyed by the refund address, which must be `msg.sender`.
+
+**What to do:** Call from the refund address; `refundCredits(address)` shows the balance.
+
+#### <a id="coordinator-error-transferfailed"></a>`TransferFailed`
+
+`error TransferFailed()` · Selector `0x90b8ec18` · Source: `D20VRFCoordinator.sol` lines 124, 523, 534, 545
+
+**Raised by:** [`withdrawRefundCredit`](#coordinator-fn-withdrawrefundcredit), [`withdrawFees`](#coordinator-fn-withdrawfees), [`withdrawKeeperCredit`](#coordinator-fn-withdrawkeepercredit).
+
+The `recipient` of `withdrawRefundCredit`, `withdrawFees` or `withdrawKeeperCredit` rejected the native transfer. Balances are unchanged.
+
+**What to do:** Choose a recipient that accepts plain native transfers.
+
+#### <a id="coordinator-error-onlyfeerecipient"></a>`OnlyFeeRecipient`
+
+`error OnlyFeeRecipient()` · Selector `0x07d8ed3d` · Source: `D20VRFCoordinator.sol` lines 123, 529
+
+**Raised by:** [`withdrawFees`](#coordinator-fn-withdrawfees).
+
+`withdrawFees` from an address other than `feeRecipient()`.
+
+**What to do:** Only the fee recipient withdraws protocol fees.
+
+#### <a id="coordinator-error-nokeepercredit"></a>`NoKeeperCredit`
+
+`error NoKeeperCredit()` · Selector `0x0d106640` · Source: `D20VRFCoordinator.sol` lines 130, 541
+
+**Raised by:** [`withdrawKeeperCredit`](#coordinator-fn-withdrawkeepercredit).
+
+`withdrawKeeperCredit` from an address without keeper credit.
+
+**What to do:** `keeperCredits(address)` shows the balance.
+
+**Proofs and keepers**
+
+#### <a id="coordinator-error-notready"></a>`NotReady`
+
+`error NotReady()` · Selector `0x9488aaa6` · Source: `D20VRFCoordinator.sol` lines 115, 566
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch), [`storeBlockHash`](#coordinator-fn-storeblockhash), [`verifyRequestProof`](#coordinator-fn-verifyrequestproof), [`requestSeed`](#coordinator-fn-requestseed), [`getProofContext`](#coordinator-fn-getproofcontext).
+
+The request cannot be proven yet: its epoch packet is not published, or `block.number` is below `targetBlock + confirmationBlocks`.
+
+**What to do:** For a consumer this only means the request is still waiting. Keepers retry after publication and confirmations.
+
+#### <a id="coordinator-error-blockhashunavailable"></a>`BlockHashUnavailable`
+
+`error BlockHashUnavailable()` · Selector `0xbfc9f0d3` · Source: `D20VRFCoordinator.sol` lines 116, 569
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch), [`storeBlockHash`](#coordinator-fn-storeblockhash), [`verifyRequestProof`](#coordinator-fn-verifyrequestproof), [`requestSeed`](#coordinator-fn-requestseed), [`getProofContext`](#coordinator-fn-getproofcontext).
+
+The target block hash was never stored and is outside the 256-block `BLOCKHASH` window. The request can no longer be fulfilled.
+
+**What to do:** Call `refundRequest` after the deadline. Keepers call `storeBlockHash` before the window closes.
+
+#### <a id="coordinator-error-alreadyfulfilled"></a>`AlreadyFulfilled`
+
+`error AlreadyFulfilled()` · Selector `0x4a4117f9` · Source: `D20VRFCoordinator.sol` lines 117, 393
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness).
+
+`fulfillRandomness` on a fulfilled request.
+
+**What to do:** Nothing to do; read the result.
+
+#### <a id="coordinator-error-requestrefunded"></a>`RequestRefunded`
+
+`error RequestRefunded()` · Selector `0xe0dec416` · Source: `D20VRFCoordinator.sol` lines 127, 394
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness).
+
+`fulfillRandomness` on a refunded request.
+
+**What to do:** The request is settled and will never have a result.
+
+#### <a id="coordinator-error-requestexpired"></a>`RequestExpired`
+
+`error RequestExpired()` · Selector `0xfef01cd2` · Source: `D20VRFCoordinator.sol` lines 126, 395
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness).
+
+`fulfillRandomness` in a block whose timestamp is after the request's deadline.
+
+**What to do:** The request can only be refunded with `refundRequest`.
+
+#### <a id="coordinator-error-wrongpublickey"></a>`WrongPublicKey`
+
+`error WrongPublicKey()` · Selector `0x2b0bb68e` · Source: `D20VRFCoordinator.sol` lines 120, 594
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch), [`verifyRequestProof`](#coordinator-fn-verifyrequestproof).
+
+The proof's `pk` is not the coordinator's VRF key.
+
+**What to do:** Only proofs from the configured key are accepted.
+
+#### <a id="coordinator-error-wrongseed"></a>`WrongSeed`
+
+`error WrongSeed()` · Selector `0xf36cbea4` · Source: `D20VRFCoordinator.sol` lines 121, 596
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch), [`verifyRequestProof`](#coordinator-fn-verifyrequestproof).
+
+The proof's `seed` differs from `requestSeed(requestId)`.
+
+**What to do:** Prove the stored seed; it cannot change.
+
+#### <a id="coordinator-error-evidencepackettoolarge"></a>`EvidencePacketTooLarge`
+
+`error EvidencePacketTooLarge()` · Selector `0xcfbc3ebf` · Source: `D20VRFCoordinator.sol` lines 134, 452
+
+**Raised by:** [`fulfillRandomness`](#coordinator-fn-fulfillrandomness), [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch).
+
+The encoded proof exceeds `MAX_EVIDENCE_PACKET_BYTES`. A proof always encodes to 416 bytes, so valid calls never reach this bound.
+
+**What to do:** None expected.
+
+#### <a id="coordinator-error-invalidbatch"></a>`InvalidBatch`
+
+`error InvalidBatch()` · Selector `0x33b094a1` · Source: `D20VRFCoordinator.sol` lines 137, 404
+
+**Raised by:** [`fulfillRandomnessBatch`](#coordinator-fn-fulfillrandomnessbatch).
+
+`fulfillRandomnessBatch` with no IDs, more than 16, or a different number of proofs.
+
+**What to do:** Send 1 to 16 IDs with one proof each.
+
+#### <a id="coordinator-error-invalidscan"></a>`InvalidScan`
+
+`error InvalidScan()` · Selector `0x3e6249a2` · Source: `D20VRFCoordinator.sol` lines 133, 316
+
+**Raised by:** [`getPendingRequestIds`](#coordinator-fn-getpendingrequestids).
+
+`getPendingRequestIds` with `fromId` 0, `limit` 0 or `limit` above 256.
+
+**What to do:** Start at 1 and page with at most 256.
+
+**Administration, initialization and upgrades**
+
+#### <a id="coordinator-error-invalidconfig"></a>`InvalidConfig`
+
+`error InvalidConfig()` · Selector `0x35be3ac8` · Source: `D20VRFCoordinator.sol` lines 108, 174–175, 198, 202, 207, 216, 530, 539
+
+**Raised by:** [`withdrawFees`](#coordinator-fn-withdrawfees), [`withdrawKeeperCredit`](#coordinator-fn-withdrawkeepercredit), [`setPricing`](#coordinator-fn-setpricing), [`setRefundBps`](#coordinator-fn-setrefundbps), [`setKeeperFeeBps`](#coordinator-fn-setkeeperfeebps), [`setFeeRecipient`](#coordinator-fn-setfeerecipient), [`initialize`](#coordinator-fn-initialize).
+
+A value is out of bounds: in `initialize` (zero fee recipient, confirmations 0 or above 64, keeper share above 10000, minimum fee above 10 USDC, registry without code), `setFeeRecipient` with zero, `setKeeperFeeBps` above 10000, `setPricing` outside its bounds, `setRefundBps` outside 5000 to 10000, or a zero `recipient` for `withdrawFees` or `withdrawKeeperCredit`.
+
+**What to do:** Use values within the bounds given for each function.
+
+#### <a id="coordinator-error-invalidpublickey"></a>`InvalidPublicKey`
+
+`error InvalidPublicKey()` · Selector `0xa2d0fee8` · Source: `D20VRFCoordinator.sol` lines 110, 177
+
+**Raised by:** [`initialize`](#coordinator-fn-initialize).
+
+`initialize` with a VRF public key that is not on secp256k1.
+
+**What to do:** Deployment-time only.
+
+#### <a id="coordinator-error-reentrancyguardreentrantcall"></a>`ReentrancyGuardReentrantCall`
+
+`error ReentrancyGuardReentrantCall()` · Selector `0x3ee5aeb5`
+
+**Raised by:** any `nonReentrant` function entered from a callback or transfer.
+
+A `nonReentrant` coordinator function (a request, `storeBlockHash`, a fulfillment, a retry, `refundRequest` or a withdrawal) was entered while another was running, for example a request made inside `rawFulfillRandomness` or `onRefund`. Inside a callback the coordinator catches it and records the callback as failed.
+
+**What to do:** Do not call coordinator state-changing functions from callbacks; request again in a separate transaction.
+
+#### <a id="coordinator-error-ownableunauthorizedaccount"></a>`OwnableUnauthorizedAccount`
+
+`error OwnableUnauthorizedAccount(address account)` · Selector `0x118cdaa7`
+
+**Raised by:** [`setPricing`](#coordinator-fn-setpricing), [`setRefundBps`](#coordinator-fn-setrefundbps), [`setKeeperFeeBps`](#coordinator-fn-setkeeperfeebps), [`setFeeRecipient`](#coordinator-fn-setfeerecipient), [`transferOwnership`](#coordinator-fn-transferownership), [`acceptOwnership`](#coordinator-fn-acceptownership), [`renounceOwnership`](#coordinator-fn-renounceownership), [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall).
+
+`account` is not the owner (owner-only functions) or not the pending owner (`acceptOwnership`).
+
+**What to do:** Only the owner can administer or upgrade the contract; on Arc Mainnet that is the DAO treasury Safe recorded in the deployment manifest.
+
+#### <a id="coordinator-error-ownableinvalidowner"></a>`OwnableInvalidOwner`
+
+`error OwnableInvalidOwner(address owner)` · Selector `0x1e4fbdf7`
+
+**Raised by:** [`initialize`](#coordinator-fn-initialize).
+
+`initialize` was given the zero address as owner.
+
+**What to do:** Deployment-time only.
+
+#### <a id="coordinator-error-renouncedisabled"></a>`RenounceDisabled`
+
+`error RenounceDisabled()` · Selector `0x89051165` · Source: `D20VRFCoordinator.sol` lines 135, 195
+
+**Raised by:** [`renounceOwnership`](#coordinator-fn-renounceownership).
+
+The owner called `renounceOwnership`, which is disabled.
+
+**What to do:** Move ownership with `transferOwnership` and `acceptOwnership`.
+
+#### <a id="coordinator-error-invalidinitialization"></a>`InvalidInitialization`
+
+`error InvalidInitialization()` · Selector `0xf92ee8a9`
+
+**Raised by:** [`initialize`](#coordinator-fn-initialize).
+
+`initialize` on a proxy that is already initialized, or on an implementation contract, whose initializers are disabled at construction.
+
+**What to do:** None: initialization happens once, atomically, when `D20Proxy` is deployed.
+
+#### <a id="coordinator-error-notinitializing"></a>`NotInitializing`
+
+`error NotInitializing()` · Selector `0xd7e6bcf8`
+
+**Raised by:** no public function (declared by OpenZeppelin `Initializable`).
+
+Declared by the OpenZeppelin initializer helpers. No public function of this contract can reach it.
+
+**What to do:** None.
+
+#### <a id="coordinator-error-uupsunauthorizedcallcontext"></a>`UUPSUnauthorizedCallContext`
+
+`error UUPSUnauthorizedCallContext()` · Selector `0xe07c8dba`
+
+**Raised by:** [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall), [`proxiableUUID`](#coordinator-fn-proxiableuuid).
+
+`upgradeToAndCall` called on the implementation instead of through the proxy, or `proxiableUUID` called through the proxy.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="coordinator-error-uupsunsupportedproxiableuuid"></a>`UUPSUnsupportedProxiableUUID`
+
+`error UUPSUnsupportedProxiableUUID(bytes32 slot)` · Selector `0xaa1d49a4`
+
+**Raised by:** [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall).
+
+The new implementation reports a `proxiableUUID` other than the ERC-1967 implementation slot.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="coordinator-error-erc1967invalidimplementation"></a>`ERC1967InvalidImplementation`
+
+`error ERC1967InvalidImplementation(address implementation)` · Selector `0x4c9c8ce3`
+
+**Raised by:** [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall).
+
+The new implementation has no code or no `proxiableUUID`.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="coordinator-error-erc1967nonpayable"></a>`ERC1967NonPayable`
+
+`error ERC1967NonPayable()` · Selector `0xb398979f`
+
+**Raised by:** [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall).
+
+`upgradeToAndCall` was sent value with empty `data`.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="coordinator-error-addressemptycode"></a>`AddressEmptyCode`
+
+`error AddressEmptyCode(address target)` · Selector `0x9996b315`
+
+**Raised by:** [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall).
+
+Declared by OpenZeppelin `Address` for the delegatecall in `upgradeToAndCall`. Not reachable in practice, because the new implementation must already have code.
+
+**What to do:** None.
+
+#### <a id="coordinator-error-failedcall"></a>`FailedCall`
+
+`error FailedCall()` · Selector `0xd6bda275`
+
+**Raised by:** [`upgradeToAndCall`](#coordinator-fn-upgradetoandcall).
+
+The initialization call made by `upgradeToAndCall` reverted without revert data.
+
+**What to do:** Owner upgrade procedure only.
+
+## <a id="registry"></a>EpochEntropy
+
+The epoch registry. A consumer never needs to call it: a request fixes its epoch automatically, and the coordinator reads the registry for targets and for the keeper-share recipient. The first group and the events matter to consumers and verifiers (README [Replay and verification](README.md#replay-and-verification)); publication and administration are listed for completeness.
+
+Epoch sources are recipes in an owner-managed, append-only registry: each has an id, a canonical request whose `keccak256` is the query hash its signer signs, a data template that fixes the exact signed bytes the registry accepts (README [Data templates](README.md#data-templates)) and the JSON body keepers post to the provider gateway. A catalog lists 1 to `MAX_SOURCES` registered recipes with one signer each; each epoch selects from the catalog in force for it (`catalogAt`).
+
+### <a id="registry-types"></a>Types
+
+#### <a id="registry-type-epochentropy-epoch"></a>`EpochEntropy.Epoch`
+
+Returned by `getEpoch`; all zero until the epoch is published.
+
+Source: `EpochEntropy.sol` lines 45–48
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `epochHash` | `bytes32` | Epoch commitment: `keccak256(abi.encode(EPOCH_DOMAIN, chainId, registry, catalogHash, epochId, epochStart, anchorHash, source, queryHash, dataHash, attestationHash))`. |
+| `catalogHash` | `bytes32` | Hash of the catalog in force for the epoch (`catalogAt`) at publication. |
+| `anchorHash` | `bytes32` | Hash of block `epochStart - 1`, which selects the source. |
+| `source` | `uint8` | Committed slot in the epoch's catalog, 0 to `sourceCountAt(epochId) - 1`: the selected slot or a fallback. The recipe is the catalog's recipe at that slot. |
+| `queryHash` | `bytes32` | `keccak256` of the canonical request of the slot's recipe. |
+| `dataHash` | `bytes32` | `keccak256` of the signed response data. |
+| `attestationHash` | `bytes32` | `keccak256(abi.encode(queryHash, timestamp, dataHash, keccak256(signature)))`. |
+| `signedAt` | `uint256` | Attestation timestamp in Unix seconds. |
+| `committedBlock` | `uint64` | Publication block. Requests of the epoch target `max(requestBlock, committedBlock + 1)`. |
+
+#### <a id="registry-type-epochentropy-selection"></a>`EpochEntropy.Selection`
+
+Returned by `getEpochSelection` and `getEpochFallbackSelection`.
+
+Source: `EpochEntropy.sol` lines 43–44, 262–273
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `source` | `uint8` | Slot in the epoch's catalog. |
+| `recipe` | `uint8` | Registered recipe id at that slot. |
+| `airnode` | `address` | Signer of that slot in the catalog in force for the epoch. |
+| `selector` | `bytes32` | `keccak256(abi.encode(SELECT_DOMAIN, catalogHash, epochId, anchor))`; the slot is `(selector mod count + attempt) mod count` with `count = sourceCountAt(epochId)`. |
+| `queryHash` | `bytes32` | `keccak256` of `canonicalRequest`. |
+| `canonicalRequest` | `string` | Canonical request of the recipe, as `getRecipe` returns it. |
+
+#### <a id="registry-type-epochentropy-attestation"></a>`EpochEntropy.Attestation`
+
+Signed source response passed to `commitEpoch` and `commitEpochFallback`.
+
+Source: `EpochEntropy.sol` lines 42, 280–300
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `timestamp` | `uint256` | Signing time in Unix seconds; not in the future and at most `MAX_ATTESTATION_AGE` old at publication. |
+| `data` | `bytes` | Signed response bytes, at most `MAX_DATA_BYTES` (128), matching the data template of the slot's recipe exactly. |
+| `signature` | `bytes` | Signature over `toEthSignedMessageHash(keccak256(abi.encodePacked(queryHash, timestamp, data)))`. |
+
+### <a id="registry-epoch-state-for-consumers-and-verifiers"></a>Epoch state for consumers and verifiers
+
+Views, callable by anyone. Epoch IDs start at 1; each epoch lasts `EPOCH_LENGTH` (200) blocks.
+
+#### <a id="registry-fn-epochforblock"></a>`epochForBlock`
+
+```solidity
+function epochForBlock(uint256 number) external view returns (uint64)
+```
+
+Selector `0x7018ebb1` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 235–237
+
+Epoch containing a block: 0 before `firstEpochStart`, otherwise `1 + (number - firstEpochStart) / 200`. A request belongs to `epochForBlock(requestBlock)`.
+
+#### <a id="registry-fn-epochstart"></a>`epochStart`
+
+```solidity
+function epochStart(uint64 epochId) external view returns (uint64)
+```
+
+Selector `0xa1587509` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 231–234
+
+First block of an epoch: `firstEpochStart + (epochId - 1) × 200`.
+
+**Errors:** [`InvalidEpoch`](#registry-error-invalidepoch).
+
+#### <a id="registry-fn-getepoch"></a>`getEpoch`
+
+```solidity
+function getEpoch(uint64 epochId) external view returns (EpochEntropy.Epoch)
+```
+
+Selector `0x12a02c82` · Caller: Anyone (view) · Source: `EpochEntropy.sol` line 252
+
+The published [`EpochEntropy.Epoch`](#registry-type-epochentropy-epoch) record, or all zero while unpublished; it never reverts. A non-zero `epochHash` means published.
+
+#### <a id="registry-fn-catalogat"></a>`catalogAt`
+
+```solidity
+function catalogAt(uint64 epochId) external view returns (bytes32 hash, uint8[] recipes, address[] signers)
+```
+
+Selector `0xec993599` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 212–220, 226–230
+
+The catalog in force for an epoch: its hash and the recipe id and signer of each slot, in slot order. That is the latest scheduled version whose `fromEpoch` is at or below `epochId`, otherwise the initial catalog: recipes 0 to 3 with the initial signers and hash `catalogHash()`. Replay needs this catalog, not the initial signer getters.
+
+#### <a id="registry-fn-sourcecountat"></a>`sourceCountAt`
+
+```solidity
+function sourceCountAt(uint64 epochId) external view returns (uint256)
+```
+
+Selector `0x3edc6b12` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 221–225, 226–230
+
+Number of slots in the catalog in force for an epoch, and so the number of selection attempts, 0 to count - 1.
+
+#### <a id="registry-fn-getrecipe"></a>`getRecipe`
+
+```solidity
+function getRecipe(uint8 recipe) external view returns (bytes32 queryHash, string canonicalRequest, bytes template, string body)
+```
+
+Selector `0xba01b103` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 132–136, 139–142
+
+A registered recipe: `queryHash` (`keccak256` of `canonicalRequest`), the canonical request its signer signs, the data template its signed data must match and the JSON body keepers post to the provider gateway. Registered recipes never change. `readEpochRecipes` in `@d20dao/vrf-sdk/epoch` reads recipes with this view and checks each query hash.
+
+**Errors:** [`InvalidConfig`](#registry-error-invalidconfig).
+
+#### <a id="registry-fn-reciperequest"></a>`recipeRequest`
+
+```solidity
+function recipeRequest(uint8 recipe) external view returns (string)
+```
+
+Selector `0x7ce4b6e0` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 137–142
+
+Canonical request of a registered recipe, the same string `getRecipe` returns.
+
+**Errors:** [`InvalidConfig`](#registry-error-invalidconfig).
+
+#### <a id="registry-fn-recipecount"></a>`recipeCount`
+
+```solidity
+function recipeCount() external view returns (uint256)
+```
+
+Selector `0x69cfdf74` · Caller: Anyone (view) · Source: `EpochEntropy.sol` line 131
+
+Number of registered recipes; ids run from 0 to `recipeCount() - 1`.
+
+### <a id="registry-registry-reads"></a>Registry reads
+
+Views, callable by anyone.
+
+| Function | Selector | Meaning | Source |
+| --- | --- | --- | --- |
+| <a id="registry-fn-firstepochstart"></a>`firstEpochStart() returns (uint64)` | `0x219f2428` | First block of epoch 1: the initialization block plus 200. | lines 40, 83 |
+| <a id="registry-fn-committer"></a>`committer() returns (address)` | `0x5bc8e8f9` | Primary publishing address. The coordinator pays it the keeper share of the requests it serves itself and of every request whose proof came from a wallet this registry does not authorize. | lines 39, 281 |
+| <a id="registry-fn-isbackupcommitter"></a>`isBackupCommitter(address account) returns (bool)` | `0x1d97e417` | Whether an address may publish epochs besides `committer()`. | line 118 |
+| <a id="registry-fn-isauthorizedcommitter"></a>`isAuthorizedCommitter(address account) returns (bool)` | `0x1579ab83` | Whether an address may publish epochs at all: `committer()` or an allowed backup committer. The coordinator reads it to decide whether a proof submitter earns the keeper share. | lines 119–121 |
+| <a id="registry-fn-backupcommittercount"></a>`backupCommitterCount() returns (uint256)` | `0xa815c5bf` | Number of allowed backup committers, at most `MAX_BACKUP_COMMITTERS`. | lines 63, 107–117 |
+| <a id="registry-fn-cataloghash"></a>`catalogHash() returns (bytes32)` | `0x830c083a` | Initial catalog hash, bound into `protocolConfigurationHash`. Never changes; `catalogAt` gives the catalog of an epoch. | lines 41, 84 |
+| <a id="registry-fn-epochanchors"></a>`epochAnchors(uint64) returns (bytes32)` | `0x48a030fb` | Checkpointed anchor of an epoch (hash of block `epochStart - 1`); zero until a request, `checkpointEpoch` or publication stores it. | lines 53, 241–244 |
+| <a id="registry-fn-hyperliquidsigner"></a>`hyperliquidSigner() returns (address)` | `0xf2a12563` | Initial-catalog signer of slot 0 (recipe 0, Hyperliquid BTC volume). Never changes; see `catalogAt`. | line 34 |
+| <a id="registry-fn-ethereumblocksigner"></a>`ethereumBlockSigner() returns (address)` | `0xd25eacfc` | Initial-catalog signer of slot 1 (recipe 1, Ethereum block hash). Never changes; see `catalogAt`. | lines 35–36 |
+| <a id="registry-fn-btctradesigner"></a>`btcTradeSigner() returns (address)` | `0xb3b9cbb0` | Initial-catalog signer of slot 2 (recipe 2, TickerLayer BTCUSD). Never changes; see `catalogAt`. | line 37 |
+| <a id="registry-fn-ethtradesigner"></a>`ethTradeSigner() returns (address)` | `0x3a700168` | Initial-catalog signer of slot 3 (recipe 3, TickerLayer ETHUSD). Never changes; see `catalogAt`. | line 38 |
+
+### <a id="registry-source-selection-and-publication"></a>Source selection and publication
+
+Used by keepers. Publication is restricted to the committer and backup committers; the selection views and `checkpointEpoch` are open to anyone.
+
+#### <a id="registry-fn-getepochselection"></a>`getEpochSelection`
+
+```solidity
+function getEpochSelection(uint64 epochId) external view returns (EpochEntropy.Selection s)
+```
+
+Selector `0xec4960ad` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 253, 262–273
+
+The selected source of an epoch, attempt 0, as an [`EpochEntropy.Selection`](#registry-type-epochentropy-selection).
+
+**Errors:** [`InvalidEpoch`](#registry-error-invalidepoch), [`PreparationClosed`](#registry-error-preparationclosed), [`AnchorUnavailable`](#registry-error-anchorunavailable), [`InvalidConfig`](#registry-error-invalidconfig).
+
+#### <a id="registry-fn-getepochfallbackselection"></a>`getEpochFallbackSelection`
+
+```solidity
+function getEpochFallbackSelection(uint64 epochId, uint8 attempt) external view returns (EpochEntropy.Selection s)
+```
+
+Selector `0x0e5a0e02` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 254–255, 262–273
+
+The source for attempt 0 to `sourceCountAt(epochId) - 1`; attempt n uses the slot n positions after the selected one.
+
+**Errors:** [`InvalidFallback`](#registry-error-invalidfallback), [`InvalidEpoch`](#registry-error-invalidepoch), [`PreparationClosed`](#registry-error-preparationclosed), [`AnchorUnavailable`](#registry-error-anchorunavailable), [`InvalidConfig`](#registry-error-invalidconfig).
+
+#### <a id="registry-fn-fallbackopensat"></a>`fallbackOpensAt`
+
+```solidity
+function fallbackOpensAt(uint64 epochId, uint8 attempt) external view returns (uint64)
+```
+
+Selector `0x98208050` · Caller: Anyone (view) · Source: `EpochEntropy.sol` lines 256–260
+
+First block at which an attempt may be published: `epochStart + attempt × FALLBACK_DELAY_BLOCKS` (20). With at most `MAX_SOURCES` (10) slots the last window opens 180 blocks into the epoch.
+
+**Errors:** [`InvalidFallback`](#registry-error-invalidfallback), [`InvalidEpoch`](#registry-error-invalidepoch).
+
+#### <a id="registry-fn-nextepochtoprepare"></a>`nextEpochToPrepare`
+
+```solidity
+function nextEpochToPrepare(uint256 number) external view returns (uint64)
+```
+
+Selector `0xc78fafe2` · Caller: Anyone (view) · Source: `EpochEntropy.sol` line 238
+
+Same value as `epochForBlock(number)`.
+
+#### <a id="registry-fn-checkpointepoch"></a>`checkpointEpoch`
+
+```solidity
+function checkpointEpoch(uint64 epochId) external returns (bytes32 anchor)
+```
+
+Selector `0x16de78cb` · Caller: Anyone · Source: `EpochEntropy.sol` lines 239–244, 245–251
+
+Stores the anchor of a started epoch (hash of block `epochStart - 1`) if not stored yet, and returns it. The coordinator calls it on every request, so the anchor of an epoch with requests survives the 256-block `BLOCKHASH` window.
+
+**Errors:** [`InvalidEpoch`](#registry-error-invalidepoch), [`PreparationClosed`](#registry-error-preparationclosed), [`AnchorUnavailable`](#registry-error-anchorunavailable).
+
+#### <a id="registry-fn-commitepoch"></a>`commitEpoch`
+
+```solidity
+function commitEpoch(uint64 epochId, EpochEntropy.Attestation a) external
+```
+
+Selector `0xb1580277` · Caller: Committer or backup committer · Source: `EpochEntropy.sol` lines 274, 280–300
+
+Publishes the packet of the selected source once per epoch, from the epoch start: checks that the attestation is not future-dated and at most 240 seconds old, that its data matches the data template of the slot's recipe exactly, and that the slot's signer in the epoch's catalog signed it. Stores the record and emits the packet. Publishing earns nothing by itself: the keeper share of each request goes to the authorized wallet that submits its accepted proof, or to `committer()` when the submitter is not authorized.
+
+**Emits:** [`EpochCommitted`](#registry-event-epochcommitted).
+
+**Errors:** [`OnlyCommitter`](#registry-error-onlycommitter), [`AlreadyCommitted`](#registry-error-alreadycommitted), [`InvalidEpoch`](#registry-error-invalidepoch), [`FallbackNotOpen`](#registry-error-fallbacknotopen), [`AnchorUnavailable`](#registry-error-anchorunavailable), [`InvalidConfig`](#registry-error-invalidconfig), [`InvalidTime`](#registry-error-invalidtime), [`InvalidData`](#registry-error-invaliddata), [`ECDSAInvalidSignatureLength`](#registry-error-ecdsainvalidsignaturelength), [`ECDSAInvalidSignatureS`](#registry-error-ecdsainvalidsignatures), [`ECDSAInvalidSignature`](#registry-error-ecdsainvalidsignature), [`InvalidSigner`](#registry-error-invalidsigner), [`PacketTooLarge`](#registry-error-packettoolarge).
+
+#### <a id="registry-fn-commitepochfallback"></a>`commitEpochFallback`
+
+```solidity
+function commitEpochFallback(uint64 epochId, uint8 attempt, EpochEntropy.Attestation a) external
+```
+
+Selector `0x5768d9a1` · Caller: Committer or backup committer · Source: `EpochEntropy.sol` lines 275–279, 280–300
+
+Publishes fallback attempt 1 to `sourceCountAt(epochId) - 1`, using the slot `attempt` positions after the selected source, once `fallbackOpensAt(epochId, attempt)` is reached. Same checks as `commitEpoch`.
+
+**Emits:** [`EpochCommitted`](#registry-event-epochcommitted).
+
+**Errors:** [`InvalidFallback`](#registry-error-invalidfallback), [`OnlyCommitter`](#registry-error-onlycommitter), [`AlreadyCommitted`](#registry-error-alreadycommitted), [`InvalidEpoch`](#registry-error-invalidepoch), [`FallbackNotOpen`](#registry-error-fallbacknotopen), [`AnchorUnavailable`](#registry-error-anchorunavailable), [`InvalidConfig`](#registry-error-invalidconfig), [`InvalidTime`](#registry-error-invalidtime), [`InvalidData`](#registry-error-invaliddata), [`ECDSAInvalidSignatureLength`](#registry-error-ecdsainvalidsignaturelength), [`ECDSAInvalidSignatureS`](#registry-error-ecdsainvalidsignatures), [`ECDSAInvalidSignature`](#registry-error-ecdsainvalidsignature), [`InvalidSigner`](#registry-error-invalidsigner), [`PacketTooLarge`](#registry-error-packettoolarge).
+
+### <a id="registry-recipes-and-catalogs"></a>Recipes and catalogs
+
+Owner-only; on Arc Mainnet the owner is the DAO treasury Safe. A recipe or catalog never changes a published epoch.
+
+#### <a id="registry-fn-registerrecipe"></a>`registerRecipe`
+
+```solidity
+function registerRecipe(string canonicalRequest, bytes template, string body) external returns (uint8 recipe)
+```
+
+Selector `0x5add5c50` · Caller: Owner · Source: `EpochEntropy.sol` lines 123–130, 143–152
+
+Appends an immutable recipe and returns its id, the next index. The canonical request is 1 to `MAX_REQUEST_BYTES` (1024) bytes, the body 1 to `MAX_BODY_BYTES` (2048) bytes, and the template must be a well-formed data template of at most `MAX_TEMPLATE_BYTES` (256) bytes; at most `MAX_RECIPES` (256) recipes exist. The contract does not check that the body canonicalizes to the request; keepers refuse a recipe whose body does not. A changed listing is registered as a new id.
+
+**Emits:** [`RecipeRegistered`](#registry-event-reciperegistered).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount), [`InvalidRecipe`](#registry-error-invalidrecipe), [`InvalidTemplate`](#registry-error-invalidtemplate).
+
+#### <a id="registry-fn-schedulecatalog"></a>`scheduleCatalog`
+
+```solidity
+function scheduleCatalog(uint8[] recipes, address[] signers, uint64 fromEpoch) external
+```
+
+Selector `0x42984450` · Caller: Owner · Source: `EpochEntropy.sol` lines 190–211
+
+Schedules a catalog for epochs from `fromEpoch`, which must be at least two epochs after the current one: 1 to `MAX_SOURCES` (10) distinct registered recipe ids with one non-zero signer each, in slot order. Its hash is `keccak256(abi.encode(RECIPE_DOMAIN, recipes, signers))`. If the latest scheduled version has not taken effect yet (its `fromEpoch` is after the current epoch) it is replaced, so that version never applies; this can return the next epoch to the previous catalog. The current epoch keeps its catalog.
+
+**Emits:** [`CatalogScheduled`](#registry-event-catalogscheduled).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount), [`InvalidConfig`](#registry-error-invalidconfig), [`InvalidEpoch`](#registry-error-invalidepoch).
+
+#### <a id="registry-fn-initializereciperegistry"></a>`initializeRecipeRegistry`
+
+```solidity
+function initializeRecipeRegistry() external
+```
+
+Selector `0x8700b456` · Caller: Owner, once per proxy, as the `upgradeToAndCall` data of the recipe-registry upgrade · Source: `EpochEntropy.sol` lines 87–95
+
+Registers built-in recipes 0 to 5 on a registry initialized before the recipe registry, whose initial catalog selects recipes 0 to 3. It runs once per proxy (reinitializer version 2) and refuses a registry that already has recipes, which includes every registry initialized by this implementation, or a catalog scheduled under the earlier hardcoded recipe ids.
+
+**Emits:** [`RecipeRegistered`](#registry-event-reciperegistered), [`Initialized`](#registry-event-initialized).
+
+**Errors:** [`InvalidInitialization`](#registry-error-invalidinitialization), [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount), [`InvalidConfig`](#registry-error-invalidconfig).
+
+### <a id="registry-owner-administration"></a>Owner administration
+
+Owner-only functions revert `OwnableUnauthorizedAccount` for anyone else. No setter can change a published epoch.
+
+#### <a id="registry-fn-setcommitter"></a>`setCommitter`
+
+```solidity
+function setCommitter(address next) external
+```
+
+Selector `0xdd51ce22` · Caller: Owner · Source: `EpochEntropy.sol` lines 100–103
+
+Changes the primary publishing address, which is also the keeper-share recipient the coordinator reads at each acceptance.
+
+**Emits:** [`CommitterChanged`](#registry-event-committerchanged).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount), [`InvalidConfig`](#registry-error-invalidconfig).
+
+#### <a id="registry-fn-setbackupcommitter"></a>`setBackupCommitter`
+
+```solidity
+function setBackupCommitter(address account, bool allowed) external
+```
+
+Selector `0xd870d0c6` · Caller: Owner · Source: `EpochEntropy.sol` lines 104–117
+
+Allows or removes a backup committer: a separate wallet that may call `commitEpoch` and `commitEpochFallback` under exactly the committer's rules, for example a follower keeper that takes over while the primary keeper is down. It has no other role, and the coordinator pays it the keeper share of the requests whose accepted proofs it submits itself. Reverts for the zero address, for allowing the current committer, for a call that does not change the address's status, and for more than `MAX_BACKUP_COMMITTERS` (4).
+
+**Emits:** [`BackupCommitterSet`](#registry-event-backupcommitterset).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount), [`InvalidConfig`](#registry-error-invalidconfig).
+
+#### <a id="registry-fn-owner"></a>`owner`
+
+```solidity
+function owner() external view returns (address)
+```
+
+Selector `0x8da5cb5b` · Caller: Anyone (view)
+
+Current owner: upgrade authority and the only account that can call the setters.
+
+#### <a id="registry-fn-pendingowner"></a>`pendingOwner`
+
+```solidity
+function pendingOwner() external view returns (address)
+```
+
+Selector `0xe30c3978` · Caller: Anyone (view)
+
+Account nominated by `transferOwnership` that has not accepted yet; zero when none.
+
+#### <a id="registry-fn-transferownership"></a>`transferOwnership`
+
+```solidity
+function transferOwnership(address newOwner) external
+```
+
+Selector `0xf2fde38b` · Caller: Owner
+
+Starts a two-step transfer by nominating `newOwner`; ownership moves only when that account calls `acceptOwnership`. A new call replaces the nomination, and the zero address cancels it.
+
+**Emits:** [`OwnershipTransferStarted`](#registry-event-ownershiptransferstarted).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount).
+
+#### <a id="registry-fn-acceptownership"></a>`acceptOwnership`
+
+```solidity
+function acceptOwnership() external
+```
+
+Selector `0x79ba5097` · Caller: Pending owner
+
+Completes the transfer to the caller and clears the nomination.
+
+**Emits:** [`OwnershipTransferred`](#registry-event-ownershiptransferred).
+
+**Errors:** [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount).
+
+#### <a id="registry-fn-renounceownership"></a>`renounceOwnership`
+
+```solidity
+function renounceOwnership() external view
+```
+
+Selector `0x715018a6` · Caller: Owner · Source: `EpochEntropy.sol` lines 97–98
+
+Disabled and declared `view`: the owner gets `RenounceDisabled` and anyone else `OwnableUnauthorizedAccount`, so the contract always has an owner and upgrade authority can only move through an accepted transfer.
+
+**Errors:** [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount), [`RenounceDisabled`](#registry-error-renouncedisabled).
+
+#### <a id="registry-fn-upgradetoandcall"></a>`upgradeToAndCall`
+
+```solidity
+function upgradeToAndCall(address newImplementation, bytes data) external payable
+```
+
+Selector `0x4f1ef286` · Caller: Owner, through the proxy
+
+UUPS upgrade: points the proxy at `newImplementation`, which must report the ERC-1967 slot from `proxiableUUID`, and delegatecalls `data` when it is non-empty. An upgrade can change any behavior described here. Integrators check the implementation when they integrate and again whenever a proxy emits `Upgraded` or the deployment manifest records an upgrade (README [Security and trust](README.md#security-and-trust)).
+
+**Emits:** [`Upgraded`](#registry-event-upgraded).
+
+**Errors:** [`UUPSUnauthorizedCallContext`](#registry-error-uupsunauthorizedcallcontext), [`OwnableUnauthorizedAccount`](#registry-error-ownableunauthorizedaccount), [`ERC1967InvalidImplementation`](#registry-error-erc1967invalidimplementation), [`UUPSUnsupportedProxiableUUID`](#registry-error-uupsunsupportedproxiableuuid), [`ERC1967NonPayable`](#registry-error-erc1967nonpayable), [`AddressEmptyCode`](#registry-error-addressemptycode), [`FailedCall`](#registry-error-failedcall).
+
+#### <a id="registry-fn-proxiableuuid"></a>`proxiableUUID`
+
+```solidity
+function proxiableUUID() external view returns (bytes32)
+```
+
+Selector `0x52d1902d` · Caller: Anyone (view)
+
+ERC-1822 check used by `upgradeToAndCall`. Returns the ERC-1967 implementation slot when called on an implementation contract directly and reverts through the proxy.
+
+**Errors:** [`UUPSUnauthorizedCallContext`](#registry-error-uupsunauthorizedcallcontext).
+
+#### <a id="registry-fn-initialize"></a>`initialize`
+
+```solidity
+function initialize(address[4] signers, address initialOwner, address initialCommitter) external
+```
+
+Selector `0xfda9f5ca` · Caller: Once, by `D20Proxy` at deployment · Source: `EpochEntropy.sol` lines 78–86
+
+Sets the four initial-catalog signers of recipes 0 to 3, the owner and the committer, and registers built-in recipes 0 to 5. Epoch 1 starts 200 blocks after the initialization block.
+
+**Emits:** [`OwnershipTransferred`](#registry-event-ownershiptransferred), [`RecipeRegistered`](#registry-event-reciperegistered), [`Initialized`](#registry-event-initialized).
+
+**Errors:** [`InvalidInitialization`](#registry-error-invalidinitialization), [`OwnableInvalidOwner`](#registry-error-ownableinvalidowner), [`InvalidConfig`](#registry-error-invalidconfig).
+
+### <a id="registry-constants"></a>Constants
+
+Views returning values fixed in the implementation code.
+
+| Constant | Returns | Value | Selector | Meaning |
+| --- | --- | --- | --- | --- |
+| <a id="registry-fn-epoch_length"></a>`EPOCH_LENGTH` | `uint64` | `200` | `0xac4746ab` | Blocks per epoch. |
+| <a id="registry-fn-max_attestation_age"></a>`MAX_ATTESTATION_AGE` | `uint256` | `240 seconds` | `0xb9f7bb8d` | Oldest attestation accepted at publication, in seconds; also exported by `@d20dao/vrf-sdk/epoch`. |
+| <a id="registry-fn-max_packet_bytes"></a>`MAX_PACKET_BYTES` | `uint256` | `2048` | `0x48cad11b` | Upper bound on the `EpochCommitted` packet. |
+| <a id="registry-fn-fallback_delay_blocks"></a>`FALLBACK_DELAY_BLOCKS` | `uint64` | `20` | `0x0a48a95d` | Blocks between fallback windows. |
+| <a id="registry-fn-max_sources"></a>`MAX_SOURCES` | `uint256` | `10` | `0x64aefc06` | Most slots in a catalog. |
+| <a id="registry-fn-max_recipes"></a>`MAX_RECIPES` | `uint256` | `256` | `0x0c148333` | Most registered recipes; ids are `uint8`. |
+| <a id="registry-fn-max_request_bytes"></a>`MAX_REQUEST_BYTES` | `uint256` | `1024` | `0x4b62e5b4` | Longest canonical request of a recipe. |
+| <a id="registry-fn-max_body_bytes"></a>`MAX_BODY_BYTES` | `uint256` | `2048` | `0x2ade18c2` | Longest gateway request body of a recipe. |
+| <a id="registry-fn-max_data_bytes"></a>`MAX_DATA_BYTES` | `uint256` | `128` | `0xf1d11a6c` | Longest signed data a template accepts. |
+| <a id="registry-fn-max_template_bytes"></a>`MAX_TEMPLATE_BYTES` | `uint256` | `256` | `0x30a3bee5` | Longest data template. |
+| <a id="registry-fn-max_backup_committers"></a>`MAX_BACKUP_COMMITTERS` | `uint256` | `4` | `0xc195af66` | Most backup committers allowed at once. |
+| <a id="registry-fn-recipe_domain"></a>`RECIPE_DOMAIN` | `bytes32` | `keccak256("D20_EPOCH_RECIPES")` | `0xacea73c8` | Domain tag of catalog hashes. |
+| <a id="registry-fn-select_domain"></a>`SELECT_DOMAIN` | `bytes32` | `keccak256("D20_EPOCH_SELECT")` | `0x10181587` | Domain tag of the source selector. |
+| <a id="registry-fn-epoch_domain"></a>`EPOCH_DOMAIN` | `bytes32` | `keccak256("D20_EPOCH")` | `0xbece738c` | Domain tag of the epoch commitment. |
+| <a id="registry-fn-upgrade_interface_version"></a>`UPGRADE_INTERFACE_VERSION` | `string` | `"5.0.0"` | `0xad3cb1cc` | OpenZeppelin UUPS interface version: upgrades go through `upgradeToAndCall` only. |
+
+### <a id="registry-events"></a>Events
+
+**Epochs, recipes and catalogs**
+
+#### <a id="registry-event-epochcommitted"></a>`EpochCommitted`
+
+```solidity
+event EpochCommitted(uint64 indexed epochId, bytes32 indexed epochHash, bytes packet)
+```
+
+Topic 0 `0xc9db8d1389570196eda0f2c6c4e2f78429c2f812db30b6b1022b5e0b5162ef72` · Emitted by: [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback) · Source: `EpochEntropy.sol` lines 71, 297–299
+
+An epoch was published. `packet` is `abi.encode(canonicalRequest, attestation)`: decode it with `decodeEpochEvidencePacket` and verify with `replayEpochCommitment`. Requests of the epoch now have a target block.
+
+#### <a id="registry-event-reciperegistered"></a>`RecipeRegistered`
+
+```solidity
+event RecipeRegistered(uint8 indexed recipe, bytes32 indexed queryHash, string canonicalRequest, bytes template, string body)
+```
+
+Topic 0 `0xbc5c1e3f4647d7f37dc8b4fe5e26e7c58ae35b8c9fb1db0233ddedba0d7f5fd8` · Emitted by: [`registerRecipe`](#registry-fn-registerrecipe), [`initializeRecipeRegistry`](#registry-fn-initializereciperegistry), [`initialize`](#registry-fn-initialize) · Source: `EpochEntropy.sol` lines 74, 151
+
+Recipe `recipe` was registered. The event carries the complete definition, so every recipe can be rebuilt from logs; `getRecipe` returns the same values.
+
+#### <a id="registry-event-catalogscheduled"></a>`CatalogScheduled`
+
+```solidity
+event CatalogScheduled(uint64 indexed fromEpoch, bytes32 indexed catalogHash, uint8[] recipes, address[] signers)
+```
+
+Topic 0 `0xc91bcd562b1edaabdb2772ada76957511610c715ef892b9c9af1f35be93c3c4f` · Emitted by: [`scheduleCatalog`](#registry-fn-schedulecatalog) · Source: `EpochEntropy.sol` lines 73, 210
+
+A catalog was scheduled for epochs from `fromEpoch`: recipe ids and signers in slot order. A later `CatalogScheduled` emitted while this version has not taken effect replaces it, so when rebuilding catalogs from history drop replaced versions, or read `catalogAt(epochId)`.
+
+**Administration and upgrades**
+
+#### <a id="registry-event-committerchanged"></a>`CommitterChanged`
+
+```solidity
+event CommitterChanged(address indexed previousCommitter, address indexed newCommitter)
+```
+
+Topic 0 `0x3f67cc70f736070aaac75db90cef1ab4047521b73e8a38d02852e8bf1a91e7e0` · Emitted by: [`setCommitter`](#registry-fn-setcommitter) · Source: `EpochEntropy.sol` lines 72, 102
+
+New primary publishing address; it also receives the keeper share of proofs submitted by wallets the registry does not authorize.
+
+#### <a id="registry-event-backupcommitterset"></a>`BackupCommitterSet`
+
+```solidity
+event BackupCommitterSet(address indexed account, bool allowed)
+```
+
+Topic 0 `0x20380b8c17d904db7d905a51f1538057d280a6cecca38882832ba0261b39fa66` · Emitted by: [`setBackupCommitter`](#registry-fn-setbackupcommitter) · Source: `EpochEntropy.sol` lines 75, 116
+
+`account` may now publish epochs (`allowed` true) or no longer may (`allowed` false).
+
+#### <a id="registry-event-ownershiptransferstarted"></a>`OwnershipTransferStarted`
+
+```solidity
+event OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner)
+```
+
+Topic 0 `0x38d16b8cac22d99fc7c124b9cd0de2d3fa1faef420bfe791d8c362d765e22700` · Emitted by: [`transferOwnership`](#registry-fn-transferownership)
+
+`transferOwnership` nominated `newOwner`; the zero address means a nomination was cancelled.
+
+#### <a id="registry-event-ownershiptransferred"></a>`OwnershipTransferred`
+
+```solidity
+event OwnershipTransferred(address indexed previousOwner, address indexed newOwner)
+```
+
+Topic 0 `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` · Emitted by: [`acceptOwnership`](#registry-fn-acceptownership), [`initialize`](#registry-fn-initialize)
+
+Ownership moved: from the zero address at initialization, and at each `acceptOwnership`.
+
+#### <a id="registry-event-upgraded"></a>`Upgraded`
+
+```solidity
+event Upgraded(address indexed implementation)
+```
+
+Topic 0 `0xbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b` · Emitted by: [`upgradeToAndCall`](#registry-fn-upgradetoandcall), proxy deployment
+
+The proxy now runs `implementation`. Emitted by the proxy at deployment and at every `upgradeToAndCall`. Compare the address with the deployment manifest; an implementation you have not reviewed means stop and review before sending more requests.
+
+#### <a id="registry-event-initialized"></a>`Initialized`
+
+```solidity
+event Initialized(uint64 version)
+```
+
+Topic 0 `0xc7f505b2f371ae2175ee4913f4499e1f2633a7b5936321eed1cdaeb6115181d2` · Emitted by: [`initializeRecipeRegistry`](#registry-fn-initializereciperegistry), [`initialize`](#registry-fn-initialize)
+
+`initialize` ran on the proxy (`version` 1) or `initializeRecipeRegistry` did (`version` 2). Each implementation contract also emitted it once at construction with `version` 2^64 − 1, which locks the implementation against initialization.
+
+### <a id="registry-errors"></a>Errors
+
+**Epoch reads**
+
+#### <a id="registry-error-invalidepoch"></a>`InvalidEpoch`
+
+`error InvalidEpoch()` · Selector `0xd5b25b63` · Source: `EpochEntropy.sol` lines 66, 204, 232
+
+**Raised by:** [`epochStart`](#registry-fn-epochstart), [`getEpochSelection`](#registry-fn-getepochselection), [`getEpochFallbackSelection`](#registry-fn-getepochfallbackselection), [`fallbackOpensAt`](#registry-fn-fallbackopensat), [`checkpointEpoch`](#registry-fn-checkpointepoch), [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback), [`scheduleCatalog`](#registry-fn-schedulecatalog).
+
+Epoch 0 was passed to `epochStart`, `fallbackOpensAt`, a selection view, `checkpointEpoch` or a commit, or `scheduleCatalog` got a `fromEpoch` less than two epochs after the current one.
+
+**What to do:** Epoch IDs start at 1; schedule at least two epochs ahead.
+
+#### <a id="registry-error-preparationclosed"></a>`PreparationClosed`
+
+`error PreparationClosed()` · Selector `0x8e2a3c7d` · Source: `EpochEntropy.sol` lines 66, 247
+
+**Raised by:** [`getEpochSelection`](#registry-fn-getepochselection), [`getEpochFallbackSelection`](#registry-fn-getepochfallbackselection), [`checkpointEpoch`](#registry-fn-checkpointepoch).
+
+The epoch has not started (`block.number` is below `epochStart(epochId)`), so its anchor block hash does not exist yet.
+
+**What to do:** Wait for the epoch to start.
+
+#### <a id="registry-error-anchorunavailable"></a>`AnchorUnavailable`
+
+`error AnchorUnavailable()` · Selector `0x60776ed3` · Source: `EpochEntropy.sol` lines 66, 250
+
+**Raised by:** [`getEpochSelection`](#registry-fn-getepochselection), [`getEpochFallbackSelection`](#registry-fn-getepochfallbackselection), [`checkpointEpoch`](#registry-fn-checkpointepoch), [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The anchor (hash of block `epochStart - 1`) was never checkpointed and is outside the 256-block `BLOCKHASH` window.
+
+**What to do:** The epoch can no longer be selected or published. Every request checkpoints its epoch's anchor, so an epoch with requests is not affected.
+
+**Publication**
+
+#### <a id="registry-error-onlycommitter"></a>`OnlyCommitter`
+
+`error OnlyCommitter()` · Selector `0xfffe5af3` · Source: `EpochEntropy.sol` lines 67, 281
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+A commit from an address that is neither `committer()` nor an allowed backup committer.
+
+**What to do:** Only the committer and backup committers publish; check `isBackupCommitter`.
+
+#### <a id="registry-error-alreadycommitted"></a>`AlreadyCommitted`
+
+`error AlreadyCommitted()` · Selector `0xbfec5558` · Source: `EpochEntropy.sol` lines 67, 282
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The epoch already has a published packet.
+
+**What to do:** Nothing to publish; read `getEpoch`.
+
+#### <a id="registry-error-fallbacknotopen"></a>`FallbackNotOpen`
+
+`error FallbackNotOpen()` · Selector `0xf8635228` · Source: `EpochEntropy.sol` lines 69, 283
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+`block.number` is below `fallbackOpensAt(epochId, attempt)`; for attempt 0, before the epoch start.
+
+**What to do:** Wait for the window.
+
+#### <a id="registry-error-invalidfallback"></a>`InvalidFallback`
+
+`error InvalidFallback()` · Selector `0x5a93724d` · Source: `EpochEntropy.sol` lines 69, 258, 266, 277
+
+**Raised by:** [`getEpochFallbackSelection`](#registry-fn-getepochfallbackselection), [`fallbackOpensAt`](#registry-fn-fallbackopensat), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+An attempt at or above `sourceCountAt(epochId)`, or attempt 0 passed to `commitEpochFallback`.
+
+**What to do:** Use attempts 1 to `sourceCountAt(epochId) - 1` for fallbacks.
+
+#### <a id="registry-error-invalidtime"></a>`InvalidTime`
+
+`error InvalidTime()` · Selector `0x6f7eac26` · Source: `EpochEntropy.sol` lines 67, 285
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The attestation timestamp is in the future or more than `MAX_ATTESTATION_AGE` (240 seconds) before the publication block.
+
+**What to do:** A saved packet is never refreshed; its requests expire and are refunded.
+
+#### <a id="registry-error-invaliddata"></a>`InvalidData`
+
+`error InvalidData()` · Selector `0x5cb045db` · Source: `EpochEntropy.sol` lines 67, 286–287
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The signed data does not match the data template of the slot's recipe exactly, which includes data longer than `MAX_DATA_BYTES` (128).
+
+**What to do:** Publish only a response that matches the selected recipe's template, unmodified.
+
+#### <a id="registry-error-invalidsigner"></a>`InvalidSigner`
+
+`error InvalidSigner()` · Selector `0x815e1d64` · Source: `EpochEntropy.sol` lines 67, 289
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The signature does not recover to the slot's signer in the epoch's catalog.
+
+**What to do:** Use `catalogAt(epochId)` for the expected signer.
+
+#### <a id="registry-error-ecdsainvalidsignature"></a>`ECDSAInvalidSignature`
+
+`error ECDSAInvalidSignature()` · Selector `0xf645eedf`
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The signature does not recover to any address (OpenZeppelin `ECDSA`).
+
+**What to do:** Publish the exact signature from the response.
+
+#### <a id="registry-error-ecdsainvalidsignaturelength"></a>`ECDSAInvalidSignatureLength`
+
+`error ECDSAInvalidSignatureLength(uint256 length)` · Selector `0xfce698f7`
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The signature is not 65 bytes (OpenZeppelin `ECDSA`).
+
+**What to do:** Publish the exact signature from the response.
+
+#### <a id="registry-error-ecdsainvalidsignatures"></a>`ECDSAInvalidSignatureS`
+
+`error ECDSAInvalidSignatureS(bytes32 s)` · Selector `0xd78bce0c`
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The signature has a high `s` value (OpenZeppelin `ECDSA`).
+
+**What to do:** Publish the exact signature from the response.
+
+#### <a id="registry-error-packettoolarge"></a>`PacketTooLarge`
+
+`error PacketTooLarge()` · Selector `0xda85e8a5` · Source: `EpochEntropy.sol` lines 68, 298
+
+**Raised by:** [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback).
+
+The encoded packet exceeds `MAX_PACKET_BYTES` (2048).
+
+**What to do:** Not reachable: the recipe and data bounds keep every packet within `MAX_PACKET_BYTES`.
+
+**Recipes, administration, initialization and upgrades**
+
+#### <a id="registry-error-invalidrecipe"></a>`InvalidRecipe`
+
+`error InvalidRecipe()` · Selector `0x7b776f4c` · Source: `EpochEntropy.sol` lines 70, 147
+
+**Raised by:** [`registerRecipe`](#registry-fn-registerrecipe).
+
+`registerRecipe` got an empty canonical request or body, a canonical request over `MAX_REQUEST_BYTES` or a body over `MAX_BODY_BYTES`, or `MAX_RECIPES` recipes are already registered.
+
+**What to do:** Shorten the request or body. Recipe ids are never freed.
+
+#### <a id="registry-error-invalidtemplate"></a>`InvalidTemplate`
+
+`error InvalidTemplate()` · Selector `0xec55b8cd` · Source: `EpochEntropy.sol` lines 70, 148
+
+**Raised by:** [`registerRecipe`](#registry-fn-registerrecipe).
+
+`registerRecipe` got a data template that is not well formed (README [Data templates](README.md#data-templates)).
+
+**What to do:** Build the template with `encodeDataTemplate`, which names the broken rule, before registering.
+
+#### <a id="registry-error-invalidconfig"></a>`InvalidConfig`
+
+`error InvalidConfig()` · Selector `0x35be3ac8` · Source: `EpochEntropy.sol` lines 66, 81, 93, 101, 108, 110, 140, 196, 200
+
+**Raised by:** [`getRecipe`](#registry-fn-getrecipe), [`recipeRequest`](#registry-fn-reciperequest), [`getEpochSelection`](#registry-fn-getepochselection), [`getEpochFallbackSelection`](#registry-fn-getepochfallbackselection), [`commitEpoch`](#registry-fn-commitepoch), [`commitEpochFallback`](#registry-fn-commitepochfallback), [`scheduleCatalog`](#registry-fn-schedulecatalog), [`initializeRecipeRegistry`](#registry-fn-initializereciperegistry), [`setCommitter`](#registry-fn-setcommitter), [`setBackupCommitter`](#registry-fn-setbackupcommitter), [`initialize`](#registry-fn-initialize).
+
+A zero signer or committer in `initialize`; a zero address in `setCommitter`; in `setBackupCommitter` the zero address, allowing the committer, an unchanged status or a fifth backup committer; in `scheduleCatalog` an empty or oversized catalog, mismatched lengths, a repeated or unregistered recipe or a zero signer; `initializeRecipeRegistry` on a registry that already has recipes or a scheduled catalog; or a recipe id that is not registered, in `getRecipe` and `recipeRequest` or, on a registry upgraded without `initializeRecipeRegistry`, in selection and publication.
+
+**What to do:** Correct the arguments; recipe ids run from 0 to `recipeCount() - 1`. A registry upgraded without the recipe step needs `initializeRecipeRegistry` from its owner.
+
+#### <a id="registry-error-ownableunauthorizedaccount"></a>`OwnableUnauthorizedAccount`
+
+`error OwnableUnauthorizedAccount(address account)` · Selector `0x118cdaa7`
+
+**Raised by:** [`registerRecipe`](#registry-fn-registerrecipe), [`scheduleCatalog`](#registry-fn-schedulecatalog), [`initializeRecipeRegistry`](#registry-fn-initializereciperegistry), [`setCommitter`](#registry-fn-setcommitter), [`setBackupCommitter`](#registry-fn-setbackupcommitter), [`transferOwnership`](#registry-fn-transferownership), [`acceptOwnership`](#registry-fn-acceptownership), [`renounceOwnership`](#registry-fn-renounceownership), [`upgradeToAndCall`](#registry-fn-upgradetoandcall).
+
+`account` is not the owner (owner-only functions) or not the pending owner (`acceptOwnership`).
+
+**What to do:** Only the owner can administer or upgrade the contract; on Arc Mainnet that is the DAO treasury Safe recorded in the deployment manifest.
+
+#### <a id="registry-error-ownableinvalidowner"></a>`OwnableInvalidOwner`
+
+`error OwnableInvalidOwner(address owner)` · Selector `0x1e4fbdf7`
+
+**Raised by:** [`initialize`](#registry-fn-initialize).
+
+`initialize` was given the zero address as owner.
+
+**What to do:** Deployment-time only.
+
+#### <a id="registry-error-renouncedisabled"></a>`RenounceDisabled`
+
+`error RenounceDisabled()` · Selector `0x89051165` · Source: `EpochEntropy.sol` lines 68, 98
+
+**Raised by:** [`renounceOwnership`](#registry-fn-renounceownership).
+
+The owner called `renounceOwnership`, which is disabled.
+
+**What to do:** Move ownership with `transferOwnership` and `acceptOwnership`.
+
+#### <a id="registry-error-invalidinitialization"></a>`InvalidInitialization`
+
+`error InvalidInitialization()` · Selector `0xf92ee8a9`
+
+**Raised by:** [`initializeRecipeRegistry`](#registry-fn-initializereciperegistry), [`initialize`](#registry-fn-initialize).
+
+`initialize` on a proxy that is already initialized or on an implementation contract, whose initializers are disabled at construction, or `initializeRecipeRegistry` on a proxy that has already reached initializer version 2.
+
+**What to do:** None: `initialize` happens once when `D20Proxy` is deployed, and `initializeRecipeRegistry` once in the recipe-registry upgrade.
+
+#### <a id="registry-error-notinitializing"></a>`NotInitializing`
+
+`error NotInitializing()` · Selector `0xd7e6bcf8`
+
+**Raised by:** no public function (declared by OpenZeppelin `Initializable`).
+
+Declared by the OpenZeppelin initializer helpers. No public function of this contract can reach it.
+
+**What to do:** None.
+
+#### <a id="registry-error-uupsunauthorizedcallcontext"></a>`UUPSUnauthorizedCallContext`
+
+`error UUPSUnauthorizedCallContext()` · Selector `0xe07c8dba`
+
+**Raised by:** [`upgradeToAndCall`](#registry-fn-upgradetoandcall), [`proxiableUUID`](#registry-fn-proxiableuuid).
+
+`upgradeToAndCall` called on the implementation instead of through the proxy, or `proxiableUUID` called through the proxy.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="registry-error-uupsunsupportedproxiableuuid"></a>`UUPSUnsupportedProxiableUUID`
+
+`error UUPSUnsupportedProxiableUUID(bytes32 slot)` · Selector `0xaa1d49a4`
+
+**Raised by:** [`upgradeToAndCall`](#registry-fn-upgradetoandcall).
+
+The new implementation reports a `proxiableUUID` other than the ERC-1967 implementation slot.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="registry-error-erc1967invalidimplementation"></a>`ERC1967InvalidImplementation`
+
+`error ERC1967InvalidImplementation(address implementation)` · Selector `0x4c9c8ce3`
+
+**Raised by:** [`upgradeToAndCall`](#registry-fn-upgradetoandcall).
+
+The new implementation has no code or no `proxiableUUID`.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="registry-error-erc1967nonpayable"></a>`ERC1967NonPayable`
+
+`error ERC1967NonPayable()` · Selector `0xb398979f`
+
+**Raised by:** [`upgradeToAndCall`](#registry-fn-upgradetoandcall).
+
+`upgradeToAndCall` was sent value with empty `data`.
+
+**What to do:** Owner upgrade procedure only.
+
+#### <a id="registry-error-addressemptycode"></a>`AddressEmptyCode`
+
+`error AddressEmptyCode(address target)` · Selector `0x9996b315`
+
+**Raised by:** [`upgradeToAndCall`](#registry-fn-upgradetoandcall).
+
+Declared by OpenZeppelin `Address` for the delegatecall in `upgradeToAndCall`. Not reachable in practice, because the new implementation must already have code.
+
+**What to do:** None.
+
+#### <a id="registry-error-failedcall"></a>`FailedCall`
+
+`error FailedCall()` · Selector `0xd6bda275`
+
+**Raised by:** [`upgradeToAndCall`](#registry-fn-upgradetoandcall).
+
+The initialization call made by `upgradeToAndCall` reverted without revert data.
+
+**What to do:** Owner upgrade procedure only.