@d20dao/vrf-sdk 0.3.4 → 0.5.0

package/dist/epoch.js

@@ -1,13 +1,162 @@
-import { AbiCoder, id, keccak256, getBytes, toUtf8Bytes, toUtf8String, verifyMessage } from "ethers";
-import { canonicalApiRequest, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
+import { AbiCoder, Contract, getAddress, hexlify, id, keccak256, getBytes, toUtf8Bytes, verifyMessage } from "ethers";
+import { canonicalApiRequest, canonicalPassthroughRequest, parsePassthroughRequest, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
+import { encodeDataTemplate, matchesDataTemplate, validateDataTemplate } from "./templates.js";
+import { BEACON_TEMPLATE, beaconCanonicalRequest, beaconRoundTime, beaconSlotSigner, decodeBeaconRound, verifyBeaconRound } from "./beacon.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 jsonRpcCall = (network) => ({ method: "POST", path: "/ogrpc", query: { network },
+    body: JSON.stringify({ jsonrpc: "2.0", id: null, method: "eth_call", params: [{ to: MULTICALL3, data: GET_LAST_BLOCK_HASH }, "latest"] }) });
+/// Each built-in recipe's listing reached through the gateway's passthrough (/api) instead of POST /: the same parameters
+/// and projection, answered with the same signed record, so it keeps the built-in template. The gateway signs it under
+/// another request hash, so it is a separate recipe the owner registers; EpochEntropy does not register it.
+export const PASSTHROUGH_EPOCH_REQUESTS = frozen([
+    { method: "POST", path: "/info", body: '{"type":"metaAndAssetCtxs","dex":""}', projection: { symbol: "/0/universe/0/name", value: "/1/0/dayNtlVlm" } },
+    jsonRpcCall("ethereum"),
+    { method: "GET", path: "/crypto/trade/last/BTCUSD" },
+    { method: "GET", path: "/crypto/trade/last/ETHUSD" },
+    { method: "GET", path: "/feed/latest", query: { name: "ETH/USD" } },
+    jsonRpcCall("base"),
+]);
+/// The passthrough recipe of a built-in recipe id: its canonical request is also its body.
+export function passthroughEpochRecipe(builtinRecipe) {
+    const request = PASSTHROUGH_EPOCH_REQUESTS[builtinRecipe];
+    if (request === undefined)
+        throw new Error(`Built-in recipe ${builtinRecipe} has no passthrough form`);
+    const canonicalRequest = canonicalPassthroughRequest(request);
+    return { canonicalRequest, template: BUILTIN_EPOCH_RECIPES[builtinRecipe].template, body: canonicalRequest };
+}
+const byteLength = (text) => toUtf8Bytes(text).length;
+/// Throws unless a recipe satisfies the registry's registration rules: bounded sizes and a well-formed template.
+/// A beacon recipe must also be exactly what registerBeacon appends for its registration.
+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);
+    const { beacon } = recipe;
+    if (beacon === undefined)
+        return;
+    if (BigInt(beacon.verifier) === 0n || BigInt(beacon.chainHash) === 0n || beacon.genesis < 1n || beacon.period < 1n || getBytes(beacon.publicKey).length !== 128)
+        throw new Error("Invalid beacon registration");
+    const request = beaconCanonicalRequest(beacon.chainHash);
+    if (recipe.canonicalRequest !== request || recipe.body !== request || recipe.template !== BEACON_TEMPLATE)
+        throw new Error("A beacon recipe's canonical request and body name its chain hash, and its template is one round number");
+}
+/// The canonical request of a recipe body. An object is a POST / gateway body with a string operation, a parameters
+/// object and an optional responseProjection object; an array is a passthrough request, which is its own canonical
+/// request. Keepers refuse a recipe whose body does not canonicalize to its request.
+export function canonicalRequestOfBody(body) {
+    const parsed = JSON.parse(body);
+    if (Array.isArray(parsed)) {
+        parsePassthroughRequest(body);
+        return 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)",
+    "function beaconOf(uint8 recipe) view returns (tuple(address verifier,uint64 genesis,uint64 period,bytes32 chainHash,bytes publicKey))"];
+/// Read registered recipes from a registry. Each definition is checked against its query hash and the registration rules.
+/// A recipe whose canonical request names drand is asked for its beacon registration, which a signed recipe lacks.
+/// With a blockTag the recipes and registrations are read as of that block instead of the latest one. A registry that was rolled back to an
+/// implementation without beaconOf no longer answers it, so a beacon epoch published earlier replays from a block of the implementation
+/// that had it, for example the epoch's commit block; that needs an RPC that serves the state of past blocks.
+export async function readEpochRecipes(runner, registry, ids, options = {}) {
+    const view = new Contract(registry, RECIPE_VIEW, runner), book = {};
+    const overrides = options.blockTag === undefined ? {} : { blockTag: options.blockTag };
+    for (const recipe of new Set(ids)) {
+        const [queryHash, canonicalRequest, template, body] = await view.getRecipe(recipe, overrides);
+        const entry = { canonicalRequest, template: hexlify(template), body };
+        if (keccak256(toUtf8Bytes(canonicalRequest)) !== queryHash)
+            throw new Error(`Recipe ${recipe} query hash mismatch`);
+        if (canonicalRequest.startsWith('["drand","')) {
+            const { verifier, genesis, period, chainHash, publicKey } = await view.beaconOf(recipe, overrides);
+            if (BigInt(verifier) !== 0n)
+                entry.beacon = { verifier, chainHash, publicKey: hexlify(publicKey), genesis, period };
+        }
+        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 +165,48 @@ 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, beacon } = epochRecipe(catalog, recipe);
+    return { source, recipe, attempt, airnode: catalog.signers[source], selector, canonicalRequest, queryHash: keccak256(toUtf8Bytes(canonicalRequest)), template, body, ...(beacon && { beacon }) };
 }
 export function verifyEpochAttestation(selected, a, commitTimestamp) {
-    validateApiSignatureEncoding(a.signature);
+    const { beacon } = selected;
+    if (beacon === undefined)
+        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);
+    if (beacon !== undefined) {
+        // A beacon round is scheduled, so its number fixes the timestamp; the verifier's check stands in for the signer's, and
+        // the catalog's signer must be the identity this registration derives.
+        const round = decodeBeaconRound(a.data);
+        if (a.timestamp !== beaconRoundTime(beacon, round))
+            throw new Error("Invalid epoch attestation time");
+        if (!verifyBeaconRound(beacon.publicKey, round, a.signature))
+            throw new Error("Invalid beacon signature");
+        if (selected.airnode.toLowerCase() !== beaconSlotSigner(beacon).toLowerCase())
+            throw new Error("Wrong epoch signer/query");
+        return { dataHash: keccak256(a.data), attestationHash: hashAttestation(selected.queryHash, a), signer: selected.airnode };
+    }
     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 +225,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 +237,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 +250,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

@@ -2,11 +2,15 @@ export { builtins, Operation, validateMapping, hashMapping, mapRandomness } from
 export type { MappingSpec } from "./mapping.js";
 export { deriveRequestSeed, hashPublicKey, hashProof, verifyVRFProof } from "./verification.js";
 export type { RequestContext, VRFProof, XY } from "./verification.js";
-export { canonicalApiRequest, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
-export type { ApiRequest, ApiAttestation } from "./sources.js";
+export { canonicalApiRequest, PASSTHROUGH, canonicalPassthroughRequest, parsePassthroughRequest, passthroughUrl, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
+export type { ApiRequest, ApiAttestation, PassthroughRequest } 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 { BEACON_DST, BEACON_DOMAIN, BEACON_TEMPLATE, DRAND_EVMNET, beaconCanonicalRequest, beaconSlotSigner, beaconRoundTime, beaconRoundAt, encodeBeaconRound, decodeBeaconRound, beaconRoundMessage, verifyBeaconRound } from "./beacon.js";
+export type { BeaconRegistration } from "./beacon.js";
+export { EPOCH_LENGTH, EPOCH_RECIPE_DOMAIN, BUILTIN_EPOCH_RECIPES, INITIAL_EPOCH_RECIPES, PASSTHROUGH_EPOCH_REQUESTS, passthroughEpochRecipe, 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

@@ -1,7 +1,9 @@
 export { builtins, Operation, validateMapping, hashMapping, mapRandomness } from "./mapping.js";
 export { deriveRequestSeed, hashPublicKey, hashProof, verifyVRFProof } from "./verification.js";
-export { canonicalApiRequest, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
+export { canonicalApiRequest, PASSTHROUGH, canonicalPassthroughRequest, parsePassthroughRequest, passthroughUrl, 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 { BEACON_DST, BEACON_DOMAIN, BEACON_TEMPLATE, DRAND_EVMNET, beaconCanonicalRequest, beaconSlotSigner, beaconRoundTime, beaconRoundAt, encodeBeaconRound, decodeBeaconRound, beaconRoundMessage, verifyBeaconRound } from "./beacon.js";
+export { EPOCH_LENGTH, EPOCH_RECIPE_DOMAIN, BUILTIN_EPOCH_RECIPES, INITIAL_EPOCH_RECIPES, PASSTHROUGH_EPOCH_REQUESTS, passthroughEpochRecipe, 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.d.ts

@@ -9,6 +9,17 @@ export interface ApiAttestation {
     signature: string;
 }
 export declare function canonicalApiRequest(request: ApiRequest): string;
+export interface PassthroughRequest {
+    method: "GET" | "POST";
+    path: string;
+    query?: Record<string, string>;
+    body?: string;
+    projection?: Record<string, string>;
+}
+export declare const PASSTHROUGH = "passthrough";
+export declare function canonicalPassthroughRequest(request: PassthroughRequest): string;
+export declare function parsePassthroughRequest(text: string): PassthroughRequest;
+export declare function passthroughUrl(gateway: string, request: PassthroughRequest): string;
 export declare function attestationDigest(requestHash: string, a: ApiAttestation): string;
 export declare function hashAttestation(requestHash: string, a: ApiAttestation): string;
 export declare function validateApiSignatureEncoding(signature: string): void;

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);
@@ -13,6 +15,78 @@ export function canonicalApiRequest(request) {
         parts.push(canonical(request.responseProjection));
     return JSON.stringify(parts);
 }
+export const PASSTHROUGH = "passthrough";
+// Path segments, query names and projection aliases are unreserved characters, so they reach the gateway unambiguously.
+const UNRESERVED = /^[A-Za-z0-9._~-]+$/;
+const sortedEntries = (entries) => Object.entries(entries).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+export function canonicalPassthroughRequest(request) {
+    const parts = [PASSTHROUGH, request.method, request.path, sortedEntries(request.query ?? {}), request.body ?? ""];
+    if (request.projection !== undefined)
+        parts.push(sortedEntries(request.projection));
+    const text = JSON.stringify(parts);
+    parsePassthroughRequest(text);
+    return text;
+}
+function passthroughEntries(value, what) {
+    if (!Array.isArray(value))
+        throw new Error(`A passthrough ${what} is an array of [name, value] entries`);
+    return value.map((entry, index) => {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || typeof entry[1] !== "string" || !UNRESERVED.test(entry[0]))
+            throw new Error(`Passthrough ${what} entry ${index} is not a [name, value] pair with an unreserved name`);
+        if (index > 0 && !(value[index - 1][0] < entry[0]))
+            throw new Error(`Passthrough ${what} entries must be sorted by name without repeats`);
+        return [entry[0], entry[1]];
+    });
+}
+/// The request a passthrough recipe's canonical request describes. Throws unless the text is exactly the compact JSON the
+/// gateway hashes and names one request a keeper sends unambiguously: GET without a body or POST with a JSON body, a path
+/// of unreserved segments, query names outside the gateway's own x-airnode- parameters, and projection JSON Pointers.
+export function parsePassthroughRequest(text) {
+    const parts = JSON.parse(text);
+    if (!Array.isArray(parts) || (parts.length !== 5 && parts.length !== 6) || parts[0] !== PASSTHROUGH || JSON.stringify(parts) !== text)
+        throw new Error('A passthrough request is the compact JSON array ["passthrough", method, path, query, body(, projection)]');
+    const [, method, path, query, body, projection] = parts;
+    if (method !== "GET" && method !== "POST")
+        throw new Error("A passthrough method is GET or POST");
+    if (typeof path !== "string" || !path.startsWith("/") || path.slice(1).split("/").some(segment => !UNRESERVED.test(segment) || segment === "." || segment === ".."))
+        throw new Error("A passthrough path is / followed by segments of unreserved characters");
+    const queryEntries = passthroughEntries(query, "query");
+    if (queryEntries.some(([name]) => name.toLowerCase().startsWith("x-airnode-")))
+        throw new Error("x-airnode- query parameters belong to the gateway");
+    if (typeof body !== "string")
+        throw new Error("A passthrough body is a string");
+    if (method === "GET" && body !== "")
+        throw new Error("A passthrough GET has no body");
+    if (method === "POST") {
+        try {
+            JSON.parse(body);
+        }
+        catch {
+            throw new Error("A passthrough POST body is JSON text");
+        }
+    }
+    const request = { method, path };
+    if (queryEntries.length)
+        request.query = Object.fromEntries(queryEntries);
+    if (body !== "")
+        request.body = body;
+    if (parts.length === 6) {
+        const projectionEntries = passthroughEntries(projection, "projection");
+        if (!projectionEntries.length || projectionEntries.some(([, pointer]) => !/^\/(?:[^~]|~[01])*$/.test(pointer)))
+            throw new Error("A passthrough projection lists alias and JSON Pointer entries");
+        request.projection = Object.fromEntries(projectionEntries);
+    }
+    return request;
+}
+const percentEncode = (text) => Array.from(new TextEncoder().encode(text), byte => UNRESERVED.test(String.fromCharCode(byte)) ? String.fromCharCode(byte) : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`).join("");
+/// Where a keeper sends a passthrough request: the gateway's /api and the path, then the query entries and one
+/// x-airnode-project parameter per projection entry, all in canonical order, with names and values percent-encoded except
+/// unreserved characters. The gateway decodes them before hashing; projected fields come back in the order sent.
+export function passthroughUrl(gateway, request) {
+    const params = [...sortedEntries(request.query ?? {}).map(([name, value]) => `${percentEncode(name)}=${percentEncode(value)}`),
+        ...sortedEntries(request.projection ?? {}).map(([alias, pointer]) => `x-airnode-project=${percentEncode(`${alias}:${pointer}`)}`)];
+    return `${gateway.replace(/\/+$/, "")}/api${request.path}${params.length ? `?${params.join("&")}` : ""}`;
+}
 export function attestationDigest(requestHash, a) {
     return keccak256(solidityPacked(["bytes32", "uint256", "bytes"], [requestHash, a.timestamp, a.data]));
 }

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;