@d20dao/vrf-sdk 0.3.3 → 0.4.0

package/dist/epoch.js

@@ -1,13 +1,115 @@
-import { AbiCoder, id, keccak256, getBytes, toUtf8Bytes, toUtf8String, verifyMessage } from "ethers";
+import { AbiCoder, Contract, getAddress, hexlify, id, keccak256, getBytes, toUtf8Bytes, verifyMessage } from "ethers";
 import { canonicalApiRequest, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
+import { encodeDataTemplate, matchesDataTemplate, validateDataTemplate } from "./templates.js";
 import { deriveRequestSeed, hashPublicKey, hashProof, verifyVRFProof } from "./verification.js";
 import { hashMapping, mapRandomness } from "./mapping.js";
 const abi = AbiCoder.defaultAbiCoder();
 export const EPOCH_LENGTH = 200n;
 export const MAX_ATTESTATION_AGE = 240n;
 export const EPOCH_RECIPE_DOMAIN = id("D20_EPOCH_RECIPES");
-export function epochCatalogHash(signers) {
-    return keccak256(abi.encode(["bytes32", "address[4]"], [EPOCH_RECIPE_DOMAIN, signers]));
+/// A catalog lists 1 to MAX_EPOCH_SOURCES distinct recipes; attempt n of an epoch opens n × FALLBACK_DELAY_BLOCKS into it.
+export const MAX_EPOCH_SOURCES = 10, FALLBACK_DELAY_BLOCKS = 20n;
+function frozen(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            frozen(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+const MULTICALL3 = "0xcA11bde05977b3631167028862bE2a173976CA11", GET_LAST_BLOCK_HASH = "0x27e86d6e";
+/// Recipe ids are uint8; canonical requests and bodies are bounded so every EpochCommitted packet fits 2048 bytes.
+export const MAX_EPOCH_RECIPES = 256, MAX_RECIPE_REQUEST_BYTES = 1024, MAX_RECIPE_BODY_BYTES = 2048;
+function builtin(id, provider, description, request, template) {
+    return { id, provider, description, request, canonicalRequest: canonicalApiRequest(request), template: encodeDataTemplate(template), body: JSON.stringify(request) };
+}
+const blockHash = (network) => ({ operation: "jsonRpc", parameters: { network, method: "eth_call", params: [{ to: MULTICALL3, data: GET_LAST_BLOCK_HASH }, "latest"] } });
+const lastTrade = (symbol) => ({ operation: "lastTrade", parameters: { assetClass: "crypto", symbol } });
+const jsonNumber = { decimal: { fraction: true, exponent: true } };
+const blockHashRecord = [{ literal: '{"id":null,"jsonrpc":"2.0","result":"0x' }, { hex: 64 }, { literal: '"}' }];
+const tradeRecord = (symbol) => [{ literal: `{"symbol":"${symbol}","price":` }, jsonNumber, { literal: ',"size":' }, jsonNumber,
+    { literal: ',"timestamp":' }, { integer: { minDigits: 1, maxDigits: 16 } }, { literal: "}" }];
+/// The recipes EpochEntropy registers itself, at initialization or in its recipe-registry upgrade, with exactly these ids,
+/// canonical requests, templates and bodies. Ids 0-3 form the initial catalog and keep their earlier canonical requests.
+export const BUILTIN_EPOCH_RECIPES = frozen([
+    builtin(0, "hyperliquid", "BTC daily notional volume", { operation: "metaAndAssetCtxs", parameters: { dex: "" }, responseProjection: { symbol: "/0/universe/0/name", value: "/1/0/dayNtlVlm" } }, [{ literal: '{"symbol":"BTC","value":"' }, { decimal: { fraction: true, exponent: false } }, { literal: '"}' }]),
+    builtin(1, "drpc", "Ethereum mainnet block hash", blockHash("ethereum"), blockHashRecord),
+    builtin(2, "tickerlayer", "BTCUSD last trade", lastTrade("BTCUSD"), tradeRecord("BTCUSD")),
+    builtin(3, "tickerlayer", "ETHUSD last trade", lastTrade("ETHUSD"), tradeRecord("ETHUSD")),
+    builtin(4, "nodary", "ETH/USD feed", { operation: "latestFeeds", parameters: { name: "ETH/USD" } }, [{ literal: '{"ETH/USD":{"value":' }, jsonNumber, { literal: ',"timestamp":' }, { integer: { minDigits: 13, maxDigits: 13 } }, { literal: ',"category":"crypto"}}' }]),
+    builtin(5, "drpc", "Base block hash", blockHash("base"), blockHashRecord),
+]);
+export const INITIAL_EPOCH_RECIPES = frozen([0, 1, 2, 3]);
+const byteLength = (text) => toUtf8Bytes(text).length;
+/// Throws unless a recipe satisfies the registry's registration rules: bounded sizes and a well-formed template.
+export function validateEpochRecipe(recipe) {
+    if (typeof recipe?.canonicalRequest !== "string" || byteLength(recipe.canonicalRequest) === 0 || byteLength(recipe.canonicalRequest) > MAX_RECIPE_REQUEST_BYTES)
+        throw new Error(`A recipe canonical request must be 1 to ${MAX_RECIPE_REQUEST_BYTES} bytes`);
+    if (typeof recipe.body !== "string" || byteLength(recipe.body) === 0 || byteLength(recipe.body) > MAX_RECIPE_BODY_BYTES)
+        throw new Error(`A recipe body must be 1 to ${MAX_RECIPE_BODY_BYTES} bytes`);
+    validateDataTemplate(recipe.template);
+}
+/// The canonical request of a JSON gateway body: an object with a string operation, a parameters object and an
+/// optional responseProjection object. Keepers refuse a recipe whose body does not canonicalize to its request.
+export function canonicalRequestOfBody(body) {
+    const parsed = JSON.parse(body);
+    const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+    if (!isObject(parsed))
+        throw new Error("A recipe body must be a JSON object");
+    const request = parsed;
+    if (typeof request.operation !== "string" || !isObject(request.parameters) || (request.responseProjection !== undefined && !isObject(request.responseProjection)))
+        throw new Error("A recipe body needs a string operation, a parameters object and an optional responseProjection object");
+    return canonicalApiRequest(request);
+}
+const RECIPE_VIEW = ["function getRecipe(uint8 recipe) view returns (bytes32 queryHash,string canonicalRequest,bytes template,string body)"];
+/// Read registered recipes from a registry. Each definition is checked against its query hash and the registration rules.
+export async function readEpochRecipes(runner, registry, ids) {
+    const view = new Contract(registry, RECIPE_VIEW, runner), book = {};
+    for (const recipe of new Set(ids)) {
+        const [queryHash, canonicalRequest, template, body] = await view.getRecipe(recipe);
+        const entry = { canonicalRequest, template: hexlify(template), body };
+        if (keccak256(toUtf8Bytes(canonicalRequest)) !== queryHash)
+            throw new Error(`Recipe ${recipe} query hash mismatch`);
+        validateEpochRecipe(entry);
+        book[recipe] = entry;
+    }
+    return book;
+}
+/// The exact signed bytes EpochEntropy accepts for a recipe template: at most 128 bytes, never cropped or reformatted.
+export function validateEpochData(template, data) {
+    if (!matchesDataTemplate(template, data))
+        throw new Error("Invalid exact epoch data");
+}
+/// The recipe ids of a catalog in slot order; throws unless it follows the registry's catalog rules.
+export function epochCatalogRecipes(catalog) {
+    const recipes = catalog.recipes ?? INITIAL_EPOCH_RECIPES;
+    if (recipes.length < 1 || recipes.length > MAX_EPOCH_SOURCES || catalog.signers.length !== recipes.length || new Set(recipes).size !== recipes.length ||
+        recipes.some(recipe => !Number.isInteger(recipe) || recipe < 0 || recipe >= MAX_EPOCH_RECIPES) || catalog.signers.some(signer => BigInt(signer) === 0n))
+        throw new Error("Invalid epoch catalog");
+    return recipes;
+}
+/// A recipe definition from the catalog's recipe book, or the built-in recipe with that id, which every registry registers identically.
+export function epochRecipe(catalog, recipe) {
+    const entry = catalog.recipeBook?.[recipe] ?? BUILTIN_EPOCH_RECIPES[recipe];
+    if (entry === undefined)
+        throw new Error(`Unknown epoch recipe ${recipe}: supply its registered definition, for example from readEpochRecipes`);
+    validateEpochRecipe(entry);
+    return entry;
+}
+export function epochCatalogHash(signers, recipes) {
+    epochCatalogRecipes({ signers, recipes });
+    return recipes === undefined ? keccak256(abi.encode(["bytes32", "address[4]"], [EPOCH_RECIPE_DOMAIN, signers]))
+        : keccak256(abi.encode(["bytes32", "uint8[]", "address[]"], [EPOCH_RECIPE_DOMAIN, recipes, signers]));
+}
+/// Build an epoch's catalog from the registry's catalogAt(epoch) view, identifying the initial catalog by its hash.
+/// A recipeBook in base, for example from readEpochRecipes, is kept; without one the built-in recipes are used.
+export function resolveEpochCatalog(base, view) {
+    const signers = view.signers.map(signer => getAddress(signer)), recipes = view.recipes.map(Number);
+    if (recipes.join() === INITIAL_EPOCH_RECIPES.join() && epochCatalogHash(signers) === view.hash)
+        return { ...base, signers };
+    if (epochCatalogHash(signers, recipes) !== view.hash)
+        throw new Error("Catalog hash mismatch");
+    return { ...base, signers, recipes };
 }
 export function epochStart(firstEpochStart, epochId) {
     if (epochId < 1n)
@@ -16,44 +118,34 @@ export function epochStart(firstEpochStart, epochId) {
 }
 export function epochForBlock(firstEpochStart, block) { return block < firstEpochStart ? 0n : 1n + (block - firstEpochStart) / EPOCH_LENGTH; }
 /// A fallback attempt n uses the source n slots after the selected one, from n × FALLBACK_DELAY_BLOCKS into the epoch.
-export const FALLBACK_DELAY_BLOCKS = 20n, MAX_FALLBACK_ATTEMPT = 3;
 export function fallbackOpensAt(firstEpochStart, epochId, attempt) {
-    if (!Number.isInteger(attempt) || attempt < 0 || attempt > MAX_FALLBACK_ATTEMPT)
+    if (!Number.isInteger(attempt) || attempt < 0 || attempt >= MAX_EPOCH_SOURCES)
         throw new Error("Invalid fallback attempt");
     return epochStart(firstEpochStart, epochId) + BigInt(attempt) * FALLBACK_DELAY_BLOCKS;
 }
 export function selectEpoch(catalog, epochId, anchorHash, attempt = 0) {
     if (epochId < 1n || BigInt(anchorHash) === 0n)
         throw new Error("Invalid epoch anchor");
-    if (!Number.isInteger(attempt) || attempt < 0 || attempt > MAX_FALLBACK_ATTEMPT)
+    const recipes = epochCatalogRecipes(catalog), count = recipes.length;
+    if (!Number.isInteger(attempt) || attempt < 0 || attempt >= count)
         throw new Error("Invalid fallback attempt");
-    const catalogHash = epochCatalogHash(catalog.signers);
-    const selector = keccak256(abi.encode(["bytes32", "bytes32", "uint64", "bytes32"], [id("D20_EPOCH_SELECT"), catalogHash, epochId, anchorHash]));
-    const source = (Number(BigInt(selector) % 4n) + attempt) % 4;
-    const request = source === 0 ? { operation: "metaAndAssetCtxs", parameters: { dex: "" }, responseProjection: { symbol: "/0/universe/0/name", value: "/1/0/dayNtlVlm" } }
-        : source === 1 ? { operation: "randomNumbers", parameters: { type: "hex8", length: 4, size: 8 } }
-            : { operation: "lastTrade", parameters: { assetClass: "crypto", symbol: source === 2 ? "BTCUSD" : "ETHUSD" } };
-    const canonicalRequest = canonicalApiRequest(request);
-    return { source, attempt, airnode: catalog.signers[source], selector, canonicalRequest, queryHash: keccak256(toUtf8Bytes(canonicalRequest)), request };
+    const selector = keccak256(abi.encode(["bytes32", "bytes32", "uint64", "bytes32"], [id("D20_EPOCH_SELECT"), epochCatalogHash(catalog.signers, catalog.recipes), epochId, anchorHash]));
+    const source = (Number(BigInt(selector) % BigInt(count)) + attempt) % count, recipe = recipes[source];
+    const { canonicalRequest, template, body } = epochRecipe(catalog, recipe);
+    return { source, recipe, attempt, airnode: catalog.signers[source], selector, canonicalRequest, queryHash: keccak256(toUtf8Bytes(canonicalRequest)), template, body };
 }
 export function verifyEpochAttestation(selected, a, commitTimestamp) {
     validateApiSignatureEncoding(a.signature);
     if (a.timestamp > commitTimestamp || commitTimestamp - a.timestamp > MAX_ATTESTATION_AGE)
         throw new Error("Invalid epoch attestation time");
-    const body = toUtf8String(a.data);
-    const number = "(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?(?:[eE][+-]?[0-9]+)?";
-    const pattern = selected.source === 0 ? /^\{"symbol":"BTC","value":"(?:0|[1-9][0-9]*)(?:\.[0-9]+)?"\}$/
-        : selected.source === 1 ? /^\{"success":true,"type":"hex8","length":"4","data":\["[0-9a-f]{16}","[0-9a-f]{16}","[0-9a-f]{16}","[0-9a-f]{16}"\]\}$/
-            : new RegExp(`^\\{"symbol":"${selected.source === 2 ? "BTCUSD" : "ETHUSD"}","price":${number},"size":${number},"timestamp":[1-9][0-9]{0,15}\\}$`);
-    if (getBytes(a.data).length > 128 || !pattern.test(body))
-        throw new Error("Invalid exact epoch data");
+    validateEpochData(selected.template, a.data);
     const signer = verifyMessage(getBytes(attestationDigest(selected.queryHash, a)), a.signature);
     if (signer.toLowerCase() !== selected.airnode.toLowerCase())
         throw new Error("Wrong epoch signer/query");
     return { dataHash: keccak256(a.data), attestationHash: hashAttestation(selected.queryHash, a), signer };
 }
 export function epochCommitmentHash(catalog, epochId, anchorHash, source, queryHash, dataHash, attestationHash) {
-    return keccak256(abi.encode(["bytes32", "uint256", "address", "bytes32", "uint64", "uint64", "bytes32", "uint8", "bytes32", "bytes32", "bytes32"], [id("D20_EPOCH"), catalog.chainId, catalog.registry, epochCatalogHash(catalog.signers), epochId, epochStart(catalog.firstEpochStart, epochId), anchorHash, source, queryHash, dataHash, attestationHash]));
+    return keccak256(abi.encode(["bytes32", "uint256", "address", "bytes32", "uint64", "uint64", "bytes32", "uint8", "bytes32", "bytes32", "bytes32"], [id("D20_EPOCH"), catalog.chainId, catalog.registry, epochCatalogHash(catalog.signers, catalog.recipes), epochId, epochStart(catalog.firstEpochStart, epochId), anchorHash, source, queryHash, dataHash, attestationHash]));
 }
 const packetTypes = ["string", "tuple(uint256 timestamp,bytes data,bytes signature)"];
 export function encodeEpochEvidencePacket(canonicalRequest, attestation) {
@@ -72,9 +164,11 @@ export function decodeEpochEvidencePacket(packet) {
     return { canonicalRequest: canonicalRequest, attestation };
 }
 export function replayEpochCommitment(input) {
-    const { catalog, epochId, record } = input;
+    const { catalog, epochId, record } = input, count = epochCatalogRecipes(catalog).length;
+    if (!Number.isInteger(Number(record.source)) || Number(record.source) < 0 || Number(record.source) >= count)
+        throw new Error("Epoch record mismatch");
     // The committed source fixes the attempt; a fallback is valid only if it was committed after its window opened.
-    const attempt = (Number(record.source) - selectEpoch(catalog, epochId, record.anchorHash).source + 4) % 4;
+    const attempt = (Number(record.source) - selectEpoch(catalog, epochId, record.anchorHash).source + count) % count;
     if (record.committedBlock < fallbackOpensAt(catalog.firstEpochStart, epochId, attempt))
         throw new Error("Invalid epoch commit block");
     const selected = selectEpoch(catalog, epochId, record.anchorHash, attempt), evidence = decodeEpochEvidencePacket(input.packet);
@@ -82,7 +176,7 @@ export function replayEpochCommitment(input) {
         throw new Error("Epoch recipe mismatch");
     const verified = verifyEpochAttestation(selected, evidence.attestation, input.commitTimestamp);
     const epochHash = epochCommitmentHash(catalog, epochId, record.anchorHash, selected.source, selected.queryHash, verified.dataHash, verified.attestationHash);
-    if (record.epochHash !== epochHash || record.catalogHash !== epochCatalogHash(catalog.signers) || Number(record.source) !== selected.source || record.queryHash !== selected.queryHash ||
+    if (record.epochHash !== epochHash || record.catalogHash !== epochCatalogHash(catalog.signers, catalog.recipes) || Number(record.source) !== selected.source || record.queryHash !== selected.queryHash ||
         record.dataHash !== verified.dataHash || record.attestationHash !== verified.attestationHash || record.signedAt !== evidence.attestation.timestamp)
         throw new Error("Epoch record mismatch");
     return { epochHash, selected, ...verified };
@@ -95,8 +189,8 @@ export function epochTranscriptHash(c, configurationHash, proofHash, randomness)
 }
 /// Canonical blocks, transaction inclusion/timestamps and the proxy implementation code active
 /// at each receipt must be independently trusted chain context. A proxy code hash alone is insufficient.
-/// The signer catalog is per epoch: epoch.catalog.signers must be the catalog in force for context.epochId
-/// (CatalogScheduled events or signersAt on the registry); replayEpochCommitment binds them to record.catalogHash,
+/// The catalog is per epoch: epoch.catalog must be the catalog in force for context.epochId (catalogAt on the
+/// registry, or CatalogScheduled events and the initial catalog); replayEpochCommitment binds it to record.catalogHash,
 /// while configuration.catalogHash remains the initial catalog bound into protocolConfigurationHash.
 export function replayEpochCoordinator(input) {
     const c = input.context, cfg = input.configuration, e = input.epoch;

package/dist/index.d.ts

@@ -6,7 +6,9 @@ export { canonicalApiRequest, attestationDigest, hashAttestation, validateApiSig
 export type { ApiRequest, ApiAttestation } from "./sources.js";
 export { replayCoordinator, transcriptHash } from "./replay.js";
 export { encodeEvidencePacket, decodeEvidencePacket, EVIDENCE_PACKET_BYTES } from "./evidence.js";
-export { EPOCH_LENGTH, EPOCH_RECIPE_DOMAIN, epochCatalogHash, epochStart, epochForBlock, selectEpoch, verifyEpochAttestation, epochCommitmentHash, encodeEpochEvidencePacket, decodeEpochEvidencePacket, replayEpochCommitment, epochProtocolConfigurationHash } from "./epoch.js";
-export type { EpochCatalog, EpochSigners, EpochRecord, EpochProtocolConfiguration } from "./epoch.js";
+export { MAX_EPOCH_DATA_BYTES, MAX_DATA_TEMPLATE_BYTES, encodeDataTemplate, decodeDataTemplate, isValidDataTemplate, validateDataTemplate, matchesDataTemplate } from "./templates.js";
+export type { DataTemplateSegment } from "./templates.js";
+export { EPOCH_LENGTH, EPOCH_RECIPE_DOMAIN, BUILTIN_EPOCH_RECIPES, INITIAL_EPOCH_RECIPES, MAX_EPOCH_SOURCES, MAX_EPOCH_RECIPES, MAX_RECIPE_REQUEST_BYTES, MAX_RECIPE_BODY_BYTES, FALLBACK_DELAY_BLOCKS, validateEpochRecipe, canonicalRequestOfBody, readEpochRecipes, epochRecipe, epochCatalogHash, epochCatalogRecipes, resolveEpochCatalog, epochStart, epochForBlock, fallbackOpensAt, selectEpoch, validateEpochData, verifyEpochAttestation, epochCommitmentHash, encodeEpochEvidencePacket, decodeEpochEvidencePacket, replayEpochCommitment, epochProtocolConfigurationHash } from "./epoch.js";
+export type { EpochCatalog, EpochSigners, EpochRecord, EpochRecipe, EpochRecipeBook, BuiltinEpochRecipe, EpochProvider, EpochProtocolConfiguration } from "./epoch.js";
 export { quoteRequestFee, DEFAULT_FEE_BUFFER_BPS } from "./fees.js";
 export type { FeeQuote, FeeQuoteOptions, FeeQuoteProvider } from "./fees.js";

package/dist/index.js

@@ -3,5 +3,6 @@ export { deriveRequestSeed, hashPublicKey, hashProof, verifyVRFProof } from "./v
 export { canonicalApiRequest, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
 export { replayCoordinator, transcriptHash } from "./replay.js";
 export { encodeEvidencePacket, decodeEvidencePacket, EVIDENCE_PACKET_BYTES } from "./evidence.js";
-export { EPOCH_LENGTH, EPOCH_RECIPE_DOMAIN, epochCatalogHash, epochStart, epochForBlock, selectEpoch, verifyEpochAttestation, epochCommitmentHash, encodeEpochEvidencePacket, decodeEpochEvidencePacket, replayEpochCommitment, epochProtocolConfigurationHash } from "./epoch.js";
+export { MAX_EPOCH_DATA_BYTES, MAX_DATA_TEMPLATE_BYTES, encodeDataTemplate, decodeDataTemplate, isValidDataTemplate, validateDataTemplate, matchesDataTemplate } from "./templates.js";
+export { EPOCH_LENGTH, EPOCH_RECIPE_DOMAIN, BUILTIN_EPOCH_RECIPES, INITIAL_EPOCH_RECIPES, MAX_EPOCH_SOURCES, MAX_EPOCH_RECIPES, MAX_RECIPE_REQUEST_BYTES, MAX_RECIPE_BODY_BYTES, FALLBACK_DELAY_BLOCKS, validateEpochRecipe, canonicalRequestOfBody, readEpochRecipes, epochRecipe, epochCatalogHash, epochCatalogRecipes, resolveEpochCatalog, epochStart, epochForBlock, fallbackOpensAt, selectEpoch, validateEpochData, verifyEpochAttestation, epochCommitmentHash, encodeEpochEvidencePacket, decodeEpochEvidencePacket, replayEpochCommitment, epochProtocolConfigurationHash } from "./epoch.js";
 export { quoteRequestFee, DEFAULT_FEE_BUFFER_BPS } from "./fees.js";

package/dist/sources.js

@@ -1,5 +1,7 @@
 import { AbiCoder, getBytes, hexlify, keccak256, solidityPacked } from "ethers";
 const abi = AbiCoder.defaultAbiCoder();
+// AirnodeHub request canonicalization: every object, at any depth, becomes its [key, value] entries sorted by key,
+// and arrays keep their order. The request hash is keccak256 of the UTF-8 JSON of [operation, parameters(, projection)].
 function canonical(value) {
     if (Array.isArray(value))
         return value.map(canonical);

package/dist/templates.d.ts

@@ -0,0 +1,22 @@
+import { type BytesLike } from "ethers";
+export declare const MAX_EPOCH_DATA_BYTES = 128, MAX_DATA_TEMPLATE_BYTES = 256;
+export type DataTemplateSegment = {
+    literal: string;
+} | {
+    hex: number;
+} | {
+    decimal: {
+        fraction: boolean;
+        exponent: boolean;
+    };
+} | {
+    integer: {
+        minDigits: number;
+        maxDigits: number;
+    };
+};
+export declare function encodeDataTemplate(segments: readonly DataTemplateSegment[]): string;
+export declare function isValidDataTemplate(template: BytesLike): boolean;
+export declare function validateDataTemplate(template: BytesLike): void;
+export declare function decodeDataTemplate(template: BytesLike): DataTemplateSegment[];
+export declare function matchesDataTemplate(template: BytesLike, data: BytesLike): boolean;

package/dist/templates.js

@@ -0,0 +1,220 @@
+import { getBytes, hexlify, toUtf8Bytes, toUtf8String } from "ethers";
+/// Data templates: the exact signed-data grammar of an epoch recipe, with the verdicts of EpochEntropy's DataTemplate.
+/// A template is a byte sequence of segments, each an opcode and its operands:
+///   0x01 LITERAL len bytes[len]  exactly these bytes (1 <= len <= 128)
+///   0x02 HEX     n               exactly n characters 0-9 or a-f (1 <= n <= 128)
+///   0x03 DECIMAL flags           unsigned JSON number: 0 or a nonzero digit then digits, then an optional fraction
+///                                when flags & 1 and an optional exponent when flags & 2 (flags <= 3)
+///   0x04 INTEGER min max         a nonzero digit then digits, min <= digit count <= max (1 <= min <= max <= 128)
+/// Variable segments are greedy and never backtrack; data matches when the segments consume it exactly. A well-formed
+/// template has at most 256 bytes, at least one variable segment, and a shortest match of at most 128 bytes.
+export const MAX_EPOCH_DATA_BYTES = 128, MAX_DATA_TEMPLATE_BYTES = 256;
+const LITERAL = 0x01, HEX = 0x02, DECIMAL = 0x03, INTEGER = 0x04, FRACTION = 0x01, EXPONENT = 0x02;
+const byteOperand = (value, name) => {
+    if (!Number.isInteger(value) || value < 1 || value > MAX_EPOCH_DATA_BYTES)
+        throw new Error(`Data template ${name} must be an integer from 1 to ${MAX_EPOCH_DATA_BYTES}`);
+    return value;
+};
+/// Encode readable segments as template bytes; throws with the rule a segment breaks.
+export function encodeDataTemplate(segments) {
+    if (!Array.isArray(segments))
+        throw new Error("A data template is a list of segments");
+    const bytes = [];
+    segments.forEach((segment, index) => {
+        const keys = segment !== null && typeof segment === "object" ? Object.keys(segment) : [];
+        if (keys.length !== 1)
+            throw new Error(`Data template segment ${index} must have exactly one of literal, hex, decimal or integer`);
+        if ("literal" in segment) {
+            if (typeof segment.literal !== "string")
+                throw new Error(`Data template segment ${index}: literal must be a string`);
+            const text = toUtf8Bytes(segment.literal);
+            byteOperand(text.length, `segment ${index} literal length in bytes`);
+            bytes.push(LITERAL, text.length, ...text);
+        }
+        else if ("hex" in segment) {
+            bytes.push(HEX, byteOperand(segment.hex, `segment ${index} hex length`));
+        }
+        else if ("decimal" in segment) {
+            const { fraction, exponent } = segment.decimal ?? {};
+            if (typeof fraction !== "boolean" || typeof exponent !== "boolean" || Object.keys(segment.decimal).length !== 2)
+                throw new Error(`Data template segment ${index}: decimal needs boolean fraction and exponent`);
+            bytes.push(DECIMAL, (fraction ? FRACTION : 0) | (exponent ? EXPONENT : 0));
+        }
+        else if ("integer" in segment) {
+            const { minDigits, maxDigits } = segment.integer ?? {};
+            byteOperand(minDigits, `segment ${index} integer minDigits`);
+            byteOperand(maxDigits, `segment ${index} integer maxDigits`);
+            if (minDigits > maxDigits || Object.keys(segment.integer).length !== 2)
+                throw new Error(`Data template segment ${index}: integer needs minDigits <= maxDigits`);
+            bytes.push(INTEGER, minDigits, maxDigits);
+        }
+        else
+            throw new Error(`Data template segment ${index} must have exactly one of literal, hex, decimal or integer`);
+    });
+    const template = hexlify(Uint8Array.from(bytes));
+    const problem = templateProblem(Uint8Array.from(bytes));
+    if (problem)
+        throw new Error(`Invalid data template: ${problem}`);
+    return template;
+}
+/// Why a template is not well-formed, or undefined when it is. Same rules as DataTemplate.isValid.
+function templateProblem(t) {
+    if (t.length === 0 || t.length > MAX_DATA_TEMPLATE_BYTES)
+        return `it must be 1 to ${MAX_DATA_TEMPLATE_BYTES} bytes`;
+    let at = 0, shortest = 0, variable = false;
+    while (at < t.length) {
+        const op = t[at];
+        if (op === LITERAL) {
+            if (at + 1 >= t.length)
+                return `truncated literal at byte ${at}`;
+            const n = t[at + 1];
+            if (n === 0 || n > MAX_EPOCH_DATA_BYTES || at + 2 + n > t.length)
+                return `invalid literal length at byte ${at}`;
+            shortest += n;
+            at += 2 + n;
+        }
+        else if (op === HEX) {
+            if (at + 1 >= t.length)
+                return `truncated hex segment at byte ${at}`;
+            const n = t[at + 1];
+            if (n === 0 || n > MAX_EPOCH_DATA_BYTES)
+                return `invalid hex length at byte ${at}`;
+            shortest += n;
+            at += 2;
+            variable = true;
+        }
+        else if (op === DECIMAL) {
+            if (at + 1 >= t.length || t[at + 1] > (FRACTION | EXPONENT))
+                return `invalid decimal flags at byte ${at}`;
+            shortest += 1;
+            at += 2;
+            variable = true;
+        }
+        else if (op === INTEGER) {
+            if (at + 2 >= t.length)
+                return `truncated integer segment at byte ${at}`;
+            const min = t[at + 1], max = t[at + 2];
+            if (min === 0 || min > max || max > MAX_EPOCH_DATA_BYTES)
+                return `invalid integer digit bounds at byte ${at}`;
+            shortest += min;
+            at += 3;
+            variable = true;
+        }
+        else
+            return `unknown segment opcode ${op} at byte ${at}`;
+    }
+    if (!variable)
+        return "it needs at least one hex, decimal or integer segment";
+    if (shortest > MAX_EPOCH_DATA_BYTES)
+        return `its shortest match exceeds ${MAX_EPOCH_DATA_BYTES} bytes`;
+    return undefined;
+}
+export function isValidDataTemplate(template) { return templateProblem(getBytes(template)) === undefined; }
+/// Throws unless the template is well-formed.
+export function validateDataTemplate(template) {
+    const problem = templateProblem(getBytes(template));
+    if (problem)
+        throw new Error(`Invalid data template: ${problem}`);
+}
+/// The readable segments of a well-formed template whose literals are UTF-8 text.
+export function decodeDataTemplate(template) {
+    const t = getBytes(template);
+    validateDataTemplate(t);
+    const segments = [];
+    for (let at = 0; at < t.length;) {
+        const op = t[at];
+        if (op === LITERAL) {
+            segments.push({ literal: toUtf8String(t.slice(at + 2, at + 2 + t[at + 1])) });
+            at += 2 + t[at + 1];
+        }
+        else if (op === HEX) {
+            segments.push({ hex: t[at + 1] });
+            at += 2;
+        }
+        else if (op === DECIMAL) {
+            segments.push({ decimal: { fraction: (t[at + 1] & FRACTION) !== 0, exponent: (t[at + 1] & EXPONENT) !== 0 } });
+            at += 2;
+        }
+        else {
+            segments.push({ integer: { minDigits: t[at + 1], maxDigits: t[at + 2] } });
+            at += 3;
+        }
+    }
+    return segments;
+}
+const isDigit = (c) => c !== undefined && c >= 0x30 && c <= 0x39;
+function digits(d, p) { while (isDigit(d[p]))
+    p++; return p; }
+/// End of an unsigned JSON number starting at p, or -1.
+function decimalEnd(d, p, fraction, exponent) {
+    if (!isDigit(d[p]))
+        return -1;
+    if (d[p] === 0x30) {
+        p++;
+        if (isDigit(d[p]))
+            return -1;
+    }
+    else
+        p = digits(d, p);
+    if (fraction && d[p] === 0x2e) {
+        const first = p + 1;
+        p = digits(d, first);
+        if (p === first)
+            return -1;
+    }
+    if (exponent && (d[p] === 0x65 || d[p] === 0x45)) {
+        p++;
+        if (d[p] === 0x2b || d[p] === 0x2d)
+            p++;
+        const first = p;
+        p = digits(d, first);
+        if (p === first)
+            return -1;
+    }
+    return p;
+}
+/// Whether data is exactly a record the template describes; false for a malformed template.
+export function matchesDataTemplate(template, data) {
+    const t = getBytes(template), d = getBytes(data);
+    if (templateProblem(t) !== undefined || d.length === 0 || d.length > MAX_EPOCH_DATA_BYTES)
+        return false;
+    let p = 0;
+    for (let at = 0; at < t.length;) {
+        const op = t[at];
+        if (op === LITERAL) {
+            const n = t[at + 1];
+            if (p + n > d.length)
+                return false;
+            for (let i = 0; i < n; i++)
+                if (d[p + i] !== t[at + 2 + i])
+                    return false;
+            p += n;
+            at += 2 + n;
+        }
+        else if (op === HEX) {
+            const end = p + t[at + 1];
+            if (end > d.length)
+                return false;
+            for (; p < end; p++)
+                if (!isDigit(d[p]) && (d[p] < 0x61 || d[p] > 0x66))
+                    return false;
+            at += 2;
+        }
+        else if (op === DECIMAL) {
+            p = decimalEnd(d, p, (t[at + 1] & FRACTION) !== 0, (t[at + 1] & EXPONENT) !== 0);
+            if (p < 0)
+                return false;
+            at += 2;
+        }
+        else {
+            if (!isDigit(d[p]) || d[p] === 0x30)
+                return false;
+            const end = digits(d, p), count = end - p;
+            if (count < t[at + 1] || count > t[at + 2])
+                return false;
+            p = end;
+            at += 3;
+        }
+    }
+    return p === d.length;
+}

package/examples/DiceConsumer.sol

@@ -3,48 +3,56 @@ pragma solidity 0.8.28;
 
 import {D20VRFConsumer} from "@d20dao/vrf-sdk/contracts/D20VRFConsumer.sol";
 import {ID20VRF} from "@d20dao/vrf-sdk/contracts/interfaces/ID20VRF.sol";
-import {RandomnessMapping} from "@d20dao/vrf-sdk/contracts/libraries/RandomnessMapping.sol";
-
-/// @notice Minimal request/storage starter; no game payment, proof, mint or deployment policy.
-/// @dev The player pays the request. A wallet cannot know the exact same-transaction quote in advance, so it quotes
-///      off-chain with quoteFeeAt(callbackGasLimit, latestBlock.baseFeePerGas) plus a buffer (the SDK's quoteRequestFee
-///      helper does this) and sends that value. The whole payment is forwarded: the coordinator escrows exactly
-///      quoteFee(callbackGasLimit) and credits any excess to the player (the refund address) as refund credit that only
-///      the player can pull with withdrawRefundCredit. Underpayment reverts inside the coordinator with
-///      IncorrectFee(expected, actual). A contract that funds requests from its own balance would instead pay
-///      rng.quoteFee(callbackGasLimit) in the same transaction, as the D20VRFRequests helpers do.
+import {D20VRFRequests} from "@d20dao/vrf-sdk/contracts/libraries/D20VRFRequests.sol";
+
+/// @notice One d20 per player, paid by the player. Swap `d20` for `d6` or `coinFlip` and nothing else moves.
 contract DiceConsumer is D20VRFConsumer {
-    struct Roll { address player; bytes32 rawWord; bool ready; }
+    using D20VRFRequests for ID20VRF;
+
+    /// The callback does two storage writes and nothing else, and the fee grows with this number.
+    uint32 private constant CALLBACK_GAS = 100_000;
+
+    struct Roll { address player; bytes32 word; bool ready; }
     mapping(uint256 => Roll) public rolls;
-    mapping(uint256 => bool) public refunded;
+
+    error Underpaid(uint256 quoted, uint256 sent);
+    error ChangeRefused();
     error UnexpectedCallback();
     error NotReady();
 
     constructor(address coordinator) D20VRFConsumer(coordinator) {}
 
-    function roll(bytes32 clientSeed, uint32 callbackGasLimit) external payable returns (uint256 requestId) {
-        // One d20. The callback still receives the raw word; result() reads the canonical mapped value.
-        RandomnessMapping.Spec memory spec = RandomnessMapping.Spec(RandomnessMapping.Operation.DiceRoll, 0, 20, 1, 0);
-        requestId = ID20VRF(vrfCoordinator).requestMappedRandomness{value: msg.value}(
-            clientSeed, callbackGasLimit, msg.sender, spec
-        );
+    function roll() external payable returns (uint256 requestId) {
+        ID20VRF rng = ID20VRF(vrfCoordinator);
+        // quoteFee prices from block.basefee, so it is exact here and only here. A wallet cannot read it in
+        // advance: off-chain it quotes quoteFeeAt(gas, the latest header's baseFeePerGas) plus a buffer and
+        // sends that, never through eth_call, where the base fee is reported as 0.
+        uint256 fee = rng.quoteFee(CALLBACK_GAS);
+        if (msg.value < fee) revert Underpaid(fee, msg.value);
+        // The helper pays exactly `fee` out of this contract's balance, which msg.value just funded.
+        // The player is the refund address, so if the request expires, refundRequest returns the fee straight to them.
+        requestId = rng.d20(D20VRFRequests.Options(keccak256(abi.encode(msg.sender)), CALLBACK_GAS, msg.sender));
         rolls[requestId] = Roll(msg.sender, bytes32(0), false);
+        // Hand the player's buffer back now. Left with the coordinator it becomes refund credit they would
+        // have to claim in a separate withdrawRefundCredit transaction.
+        if (msg.value > fee) {
+            (bool sent,) = payable(msg.sender).call{value: msg.value - fee}("");
+            if (!sent) revert ChangeRefused();
+        }
     }
 
     function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal override {
-        Roll storage result = rolls[requestId];
-        if (result.player == address(0) || result.ready || refunded[requestId]) revert UnexpectedCallback();
-        result.rawWord = randomness;
-        result.ready = true;
-    }
-
-    // Called after an expired request's refund share was paid to the player or recorded as the player's refund credit.
-    function _onRefund(uint256 requestId) internal override {
-        Roll storage result = rolls[requestId];
-        if (result.player == address(0) || result.ready) revert UnexpectedCallback();
-        refunded[requestId] = true;
+        Roll storage entry = rolls[requestId];
+        // Refuse a request this contract never made, and a repeat of one it already holds. A failed delivery is
+        // retried by anyone with retryCallback and a successful one is never repeated; the check costs one read.
+        if (entry.player == address(0) || entry.ready) revert UnexpectedCallback();
+        // Store, do not compute. The callback runs inside CALLBACK_GAS; work that overruns it fails the
+        // delivery, and although the request stays served and paid, someone must retryCallback it.
+        entry.word = randomness;
+        entry.ready = true;
     }
 
+    /// @return 1 to 20. The coordinator maps the stored word; a losing roll is never re-rolled.
     function result(uint256 requestId) external view returns (uint256) {
         if (!rolls[requestId].ready) revert NotReady();
         return ID20VRF(vrfCoordinator).getMappedResult(requestId)[0];

package/examples/LootDropConsumer.sol

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {D20VRFConsumer} from "@d20dao/vrf-sdk/contracts/D20VRFConsumer.sol";
+import {ID20VRF} from "@d20dao/vrf-sdk/contracts/interfaces/ID20VRF.sol";
+import {RandomnessMapping} from "@d20dao/vrf-sdk/contracts/libraries/RandomnessMapping.sol";
+
+/// @notice A weighted drop: common 60%, uncommon 25%, rare 13%, legendary 2%. Edit weights and TOTAL_WEIGHT
+///         together to move the odds; nothing else changes.
+contract LootDropConsumer is D20VRFConsumer {
+    uint32 private constant CALLBACK_GAS = 100_000;
+    uint256 private constant TOTAL_WEIGHT = 1000;
+    /// Tier 0 to 3, rarest last. Must sum to TOTAL_WEIGHT.
+    uint256[4] private weights = [uint256(600), 250, 130, 20];
+
+    struct Drop { address player; bytes32 word; bool ready; }
+    mapping(uint256 => Drop) public drops;
+
+    error UnexpectedCallback();
+    error NotReady();
+
+    constructor(address coordinator) D20VRFConsumer(coordinator) {}
+
+    function open() external payable returns (uint256 requestId) {
+        // One draw in [1, TOTAL_WEIGHT]. The coordinator samples the range without modulo bias and stores the
+        // mapping with the request, so the draw is read back from getMappedResult and anyone can replay it.
+        // Asking for the range you actually want is what makes the weights below mean what they say.
+        RandomnessMapping.Spec memory spec =
+            RandomnessMapping.Spec(RandomnessMapping.Operation.NumberRange, 1, TOTAL_WEIGHT, 1, 0);
+        // Forwards everything sent: the coordinator keeps exactly its quote for this transaction, reverts
+        // IncorrectFee if that is more than arrived, and credits the surplus to msg.sender as refund credit.
+        requestId = ID20VRF(vrfCoordinator).requestMappedRandomness{value: msg.value}(
+            keccak256(abi.encode(msg.sender, block.number)), CALLBACK_GAS, msg.sender, spec
+        );
+        drops[requestId] = Drop(msg.sender, bytes32(0), false);
+    }
+
+    function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal override {
+        Drop storage drop = drops[requestId];
+        // Unknown request, or a repeat of one already delivered: neither may touch a finished drop.
+        if (drop.player == address(0) || drop.ready) revert UnexpectedCallback();
+        // Store the word and stop. The tier walk below is cheap, but it belongs on the reading side: a
+        // callback that runs out of CALLBACK_GAS fails delivery, while a stored word can be read forever.
+        drop.word = randomness;
+        drop.ready = true;
+    }
+
+    /// @return tier 0 common, 1 uncommon, 2 rare, 3 legendary. Read-only: one request, one answer, forever.
+    function tierOf(uint256 requestId) external view returns (uint256 tier) {
+        if (!drops[requestId].ready) revert NotReady();
+        uint256 draw = ID20VRF(vrfCoordinator).getMappedResult(requestId)[0];
+        uint256 cursor;
+        // Weights become adjacent ranges: 1-600 common, 601-850 uncommon, 851-980 rare, the rest legendary.
+        for (uint256 i; i + 1 < weights.length; ++i) {
+            cursor += weights[i];
+            if (draw <= cursor) return i;
+        }
+        return weights.length - 1;
+    }
+}