@d20dao/vrf-sdk 0.4.0 → 0.5.0

package/dist/epoch.js

@@ -1,6 +1,7 @@
 import { AbiCoder, Contract, getAddress, hexlify, id, keccak256, getBytes, toUtf8Bytes, verifyMessage } from "ethers";
-import { canonicalApiRequest, attestationDigest, hashAttestation, validateApiSignatureEncoding } from "./sources.js";
+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();
@@ -40,19 +41,54 @@ export const BUILTIN_EPOCH_RECIPES = frozen([
     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 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.
+/// 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");
@@ -61,15 +97,26 @@ export function canonicalRequestOfBody(body) {
         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)"];
+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.
-export async function readEpochRecipes(runner, registry, ids) {
+/// 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);
+        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;
     }
@@ -131,14 +178,28 @@ export function selectEpoch(catalog, epochId, anchorHash, attempt = 0) {
         throw new Error("Invalid fallback attempt");
     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 };
+    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");
     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");

package/dist/index.d.ts

@@ -2,13 +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 { 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 { 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,8 +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 { 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 { 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

@@ -15,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/notices/BLS-BN254-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Kevin Charm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/notices/PROVENANCE.md

@@ -9,3 +9,15 @@
 - Modifications: none. `npm run vendor:check` verifies the original bytes.
 
 This is the Chainlink secp256k1/Keccak VRF construction described in that source, with its documented differences from the referenced IETF draft. It is not advertised as RFC 9381 wire-format interoperability. Reusing this file neither makes D20DAO a Chainlink service nor extends any upstream audit to our coordinator, mapping, consumer or keeper.
+
+# Vendored BLS library on BN254
+
+- Upstream: https://github.com/kevincharm/bls-bn254
+- Commit: `9f70fb4dff2cd0921dc2144929dc0aff6f21a9b9` (release 2.0.0)
+- Files, in `bls-bn254/`:
+  - `contracts/BLS.sol`, SHA-256 `887fd94553b9d6d0a247900bdb05523d3b9ef3b8ca049e2a0524a0b1a9d37e69`
+  - `contracts/ModExp.sol`, SHA-256 `fd91ae9291511668914b05fece03fb9bf6e2b57f7784d2edddc82456af12b495`
+- License: MIT, preserved in `bls-bn254/LICENSE`, SHA-256 `af36460fa628a7aca8c5b1f1b6b3615376f00212284fa0fd61a013ee982a3666`.
+- Modifications: none. `npm run vendor:check` verifies the original bytes, the license included.
+
+`D20BeaconVerifier` uses this library's RFC 9380 hash-to-curve onto G1 (expand_message_xmd with keccak256 and the Shallue-van de Woestijne map) and its point checks. These are the operations of drand's `bls-bn254-unchained-on-g1` scheme. The verifier runs the pairing itself, with a fixed gas allowance, instead of the library's `verifySingle`, which forwards all remaining gas to the precompile. Reusing this file neither makes D20DAO a drand or League of Entropy service nor extends any upstream review to our registry or keeper.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@d20dao/vrf-sdk",
-  "version": "0.4.0",
-  "description": "D20DAO verifiable randomness: Solidity consumer helpers, contract ABIs and public proof replay",
+  "version": "0.5.0",
+  "description": "Verifiable randomness (VRF) for onchain apps: Solidity consumers, contract ABIs, USDC fee quotes and public proof replay. Live on Arc.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -28,6 +28,7 @@
     },
     "./abi/D20VRFCoordinator.json": "./abi/D20VRFCoordinator.json",
     "./abi/EpochEntropy.json": "./abi/EpochEntropy.json",
+    "./abi/D20BeaconVerifier.json": "./abi/D20BeaconVerifier.json",
     "./contracts/*": "./contracts/*",
     "./examples/*": "./examples/*",
     "./AGENTS.md": "./AGENTS.md",
@@ -47,7 +48,8 @@
     "BUILD-MANIFEST.json",
     "PROTOCOL-PROVENANCE.json",
     "abi/D20VRFCoordinator.json",
-    "abi/EpochEntropy.json"
+    "abi/EpochEntropy.json",
+    "abi/D20BeaconVerifier.json"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -76,5 +78,29 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/d20dao/d20-sdk.git"
-  }
+  },
+  "homepage": "https://d20dao.org",
+  "bugs": {
+    "url": "https://github.com/d20dao/d20-sdk/issues"
+  },
+  "keywords": [
+    "vrf",
+    "verifiable-random-function",
+    "verifiable-randomness",
+    "randomness",
+    "random-number",
+    "rng",
+    "oracle",
+    "arc",
+    "arc-network",
+    "usdc",
+    "solidity",
+    "smart-contracts",
+    "evm",
+    "ethers",
+    "onchain",
+    "dice",
+    "raffle",
+    "d20dao"
+  ]
 }