@kirkelabs/walletless-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 All notable changes are documented here. Format: [Keep a Changelog](https://keepachangelog.com/);
 versioning: [SemVer](https://semver.org/).
 
+## [0.2.0] — 2026-06-20
+
+Verifiable-trust release: make every result independently checkable against a
+published spec, and close the draw-fairness gap with real drand verification.
+Backwards-compatible — all 0.1.0 APIs are unchanged; everything below is additive.
+
+### Added
+
+- **Independent, zero-dependency verifier** (`@kirkelabs/walletless-kit/verify`) —
+  `verifyDrawProof`, `verifyBundle`, `bundleProof`. Re-derives a draw / receipt
+  chain / trail from scratch with only `node:crypto`, so a result can be checked
+  without trusting the producing code (runs in a browser / offline). `bundleProof`
+  packs a draw + entries + seed source + receipts + trail into one portable,
+  self-verifying artifact (`walletless-proof/v1`).
+- **Proof format spec** (`SPEC.md`) + frozen conformance vectors
+  (`test/vectors.json`) — a second implementation that reproduces them interoperates.
+- **RFC 6962 consistency proofs** (`consistencyProof`, `verifyConsistencyProof`,
+  `trailConsistencyProof`, `verifyTrailConsistency`) — prove an audit log only ever
+  grew between two anchored roots (provably append-only history).
+- **Entrant inclusion proofs** for draws (`entryProof`, `verifyEntryProof`) — a
+  participant verifies "my entry was counted" against the published `entriesRoot`
+  without seeing the rest of the field.
+- **Non-manipulable drand randomness** (`drandSeed`, `drandRoundAt`,
+  `fetchDrandRound`) — commit a future drand round before entries close; enforces
+  the `randomness == SHA256(signature)` binding (SHA-256 only).
+- **Real BLS verification of drand beacons** (`@kirkelabs/walletless-kit/drand-bls`:
+  `makeDrandVerifier`, `verifyDrandBeacon`, `DRAND_QUICKNET_SCHEME`,
+  `DRAND_DEFAULT_SCHEME`) — proves a seed is a genuine League-of-Entropy threshold
+  signature (quicknet + legacy chained). Cross-checked against live beacon rounds
+  frozen in `test/drand-vectors.json`. Backed by `@noble/curves` as an **optional
+  peer dependency**, exposed only at the subpath, so the core entrypoint and the
+  verifier stay dependency-free.
+- **Ledger conservation invariants** (`Ledger.conservation`,
+  `Ledger.assertConservation`) — allocations + fees can never exceed inflow.
+- **`canonicalJson`** exported — the deterministic JSON primitive shared by the kit.
+
+### Changed
+
+- `audit.js` now sources its Merkle math from a new zero-dependency `src/merkle.js`
+  core; the Merkle roots are byte-for-byte identical (frozen vectors unchanged).
+- `fetchDrandRound` / `drandSeed` now carry `previousSignature` (needed for chained
+  beacon verification).
+- Test suite expanded from 47 to 85 passing; lint and `npm audit` clean.
+
 ## [0.1.0] — 2026-06-20
 
 - Initial release. A walletless web-architecture toolkit built on

package/README.md

@@ -22,11 +22,15 @@ Built on [`@kirkelabs/open-agent-access-core`](https://www.npmjs.com/package/@ki
 | **onboarding** | `createEphemeralAccount` / `rotateAccount` / `expireAccount` / `isExpired` — tightly-scoped, **round-relative auto-expiring** custodial accounts; authority bounded by an oaa-agent-kit mandate. |
 | **identity** | `OtpIdentity` — email/SMS OTP: CSPRNG codes, single-use, expiring, rate-limited, lockout, constant-time compare; stores only **keyed (peppered) pseudonymous** contact refs. |
 | **receipt** | `buildOrderReceipt` / `deterministicOrderId` / `signReceipt` / `verifyReceiptChain` / `attestOnChain` — hash-chained, signed, **non-PII** receipts; only the receipt *hash* goes on-chain. x402 actions via `chargeForAction`. |
-| **audit** | `createTrail` / `append` / `merkleRoot` / `merkleProof` / `verifyMerkleProof` / `anchor` / `verifyTrail` — append-only hash-chained events + an **RFC 6962** Merkle root, periodically anchored on-chain. |
-| **ledger** | `createLedger` — three segregated append-only books (inflow / charity / escrow), **integer-only money**, immutable snapshots, and a per-draw `reconciliationSheet`. |
-| **draw** | `runDraw` / `publishDrawProof` / `verifyDraw` + `commitSeedSource` / `blockHashSeed` / `vrfSeed` / `beaconSeed` — deterministic, recomputable winner selection (no `Math.random`). |
+| **audit** | `createTrail` / `append` / `merkleRoot` / `merkleProof` / `verifyMerkleProof` / `anchor` / `verifyTrail` + `consistencyProof` / `verifyConsistencyProof` / `trailConsistencyProof` — append-only hash-chained events + an **RFC 6962** Merkle root and **consistency proofs** (provably append-only between two anchors), periodically anchored on-chain. |
+| **ledger** | `createLedger` — three segregated append-only books (inflow / charity / escrow), **integer-only money**, immutable snapshots, a per-draw `reconciliationSheet`, and `conservation()` / `assertConservation()` invariants (allocations + fees can never exceed inflow). |
+| **draw** | `runDraw` / `publishDrawProof` / `verifyDraw` + `entryProof` / `verifyEntryProof` (entrant "was my ticket counted?" proofs) + `commitSeedSource` / `blockHashSeed` / `vrfSeed` / `beaconSeed` / `drandSeed` / `drandRoundAt` / `fetchDrandRound` — deterministic, recomputable winner selection (no `Math.random`) with **non-manipulable drand** randomness. |
+| **verify** | `bundleProof` / `verifyBundle` / `verifyDrawProof` — a **zero-dependency** verifier (runs in a browser / offline) and a portable, self-verifying **proof bundle**. Don't trust the producer — recompute it. |
+| **drand-bls** | `makeDrandVerifier` / `verifyDrandBeacon` (`@kirkelabs/walletless-kit/drand-bls`) — **real BLS12-381 verification** that a drand seed is a genuine League-of-Entropy threshold signature, not just well-formed. **Opt-in:** install the optional peer dep (`npm i @noble/curves`); not loaded by the core entrypoint, so the rest of the kit installs no pairing crypto. |
 | **privacy** | `hashPii` / `pseudonymRef` / `eraseSubject` / `assertNoPii` — keyed hashing and random, **erasable** references; PII stays off-chain. |
 
+> **Proof format spec:** the on-the-wire formats are specified in **[SPEC.md](./SPEC.md)** (`walletless-proof/v1`) with frozen conformance vectors in [`test/vectors.json`](./test/vectors.json) — anything that reproduces them interoperates and can verify a draw, trail, or receipt chain independently of this package.
+
 ## Quickstart
 
 ```js

package/SPEC.md

@@ -0,0 +1,189 @@
+# walletless-kit proof formats — `SPEC.md`
+
+**Status:** v1 · **Scope:** the on-the-wire formats a *second implementation* must
+reproduce to interoperate with `@kirkelabs/walletless-kit`. This is the contract
+behind the project's core claim — *anyone can recompute the result without trusting
+the software that produced it.* The frozen conformance vectors live in
+[`test/vectors.json`](./test/vectors.json); a conforming implementation MUST
+reproduce every hash, root, and proof there byte-for-byte.
+
+Everything in this spec is computable with only SHA-256 and canonical JSON — no
+blockchain, no network, no dependency on this package. The reference verifier
+([`src/verify.js`](./src/verify.js)) depends only on
+[`src/merkle.js`](./src/merkle.js), which depends only on `node:crypto`.
+
+The key words MUST / MUST NOT / SHOULD are used per RFC 2119.
+
+---
+
+## 1. Canonical JSON
+
+All hashing is over **canonical JSON**:
+
+- Objects: keys sorted by Unicode code point (ascending), no insignificant
+  whitespace, `undefined`-valued keys omitted.
+- Arrays: element order preserved.
+- Primitives: standard JSON encoding (`JSON.stringify` semantics); `null` kept.
+
+This is byte-identical to `@kirkelabs/open-agent-access-core`'s `canonicalizeJson`
+(cross-checked in `test/canonical.test.js`), so roots match whichever side produced
+them. Reference: [`canonicalJson`](./src/merkle.js).
+
+## 2. Merkle tree (RFC 6962)
+
+Domain-separated, to prevent a leaf being reinterpreted as an internal node
+(second-preimage forgery):
+
+```
+leaf(d)        = SHA256( 0x00 ‖ canonicalJSON(d) )
+node(l, r)     = SHA256( 0x01 ‖ l ‖ r )
+MTH({})        = SHA256("")            # empty tree
+MTH({d0})      = leaf(d0)
+MTH(D[0:n]),     n>1:
+    k = largest power of two strictly less than n
+    MTH = node( MTH(D[0:k]), MTH(D[k:n]) )
+```
+
+A lone (odd) node is **promoted** unchanged to the next level — never duplicated
+(duplicating it is the Bitcoin CVE-2012-2459 ambiguity). The iterative
+"pair-adjacent, promote-odd" construction in this kit equals the recursive
+definition above for all `n` (verified `n = 0..40`).
+
+- **Root:** lowercase hex of `MTH`.
+- **Inclusion proof:** `{ index, leaf, path[] }`, each `path` step
+  `{ side: "left"|"right", hash }`. Verify by folding siblings into `leaf` and
+  comparing to the root. Reference: [`merkleProof` / `verifyMerkleProof`](./src/merkle.js).
+
+## 3. Consistency proof (RFC 6962 §2.1.2)
+
+Proves the tree of size `m` is a **prefix** of the tree of size `n` (`m ≤ n`): the
+log only grew and was never rewritten. Format:
+
+```
+{ oldSize: m, newSize: n, proof: [ hex, … ] }
+```
+
+Verification (against `oldRoot`, `newRoot`) follows the certificate-transparency
+reference algorithm; see [`verifyConsistencyProof`](./src/merkle.js). Pair with the
+on-chain anchors (§7): anchor `oldRoot` at size `m`, later anchor `newRoot` at size
+`n`, and the `m → n` transition is provably append-only.
+
+## 4. Draw proof
+
+Winner selection is a deterministic function of `(seed, entryCount)` — no
+`Math.random`. Algorithm id `fisher-yates-sha256-v1`:
+
+```
+rng stream:  block_i = SHA256( seed ‖ ":" ‖ uint64LE(i) ), i = 0,1,2,…
+uniformInt(maxExclusive):                     # unbiased, rejection-sampled
+    span  = 2^48
+    limit = floor(span / maxExclusive) * maxExclusive
+    draw 6 bytes big-endian as v; reject while v ≥ limit; return v mod maxExclusive
+shuffle:  for i = n-1 … 1:  j = uniformInt(i+1);  swap(a[i], a[j])
+winners:  first k of shuffle([0..n-1]); map indices → entries
+```
+
+Proof object:
+
+```
+{ algorithm, seed, entryCount, entriesRoot, winners[], winnerIndices[] }
+```
+
+`entriesRoot` is the Merkle root (§2) over the **exact ordered entry set**.
+Verify by (a) recomputing `entriesRoot` from the entries, (b) re-running the
+shuffle, (c) comparing indices and mapped winners. Reference:
+[`verifyDrawProof`](./src/verify.js) (independent of the producer code).
+
+### 4.1 Entrant inclusion proof
+
+A single entrant proves membership against `entriesRoot` alone, without seeing the
+rest of the field: `{ entry, index, leaf, path }`. Verify that `leaf == leaf(entry)`
+**and** the path recomputes `entriesRoot`. Reference: [`verifyEntryProof`](./src/draw.js).
+
+## 5. Seed sources
+
+A seed is `{ source, value, … }`. Fairness equals the seed — no more. Sources:
+
+| `source`              | Manipulable? | Notes |
+|-----------------------|--------------|-------|
+| `algorand-block-seed` | **yes** (`manipulable:true`) | A proposer can withhold/grind. Only with `commitSeedSource` + low value. |
+| `drand`               | no           | BLS threshold beacon. MUST satisfy `randomness == SHA256(signature)`; optionally full BLS-verified. |
+| `vrf`                 | depends      | Caller supplies a verified VRF value+proof. |
+| `beacon`              | depends      | Generic public beacon wrapper. |
+
+**drand binding (verifiable with SHA-256 only):** `randomness = SHA256(signature)`,
+both lowercase hex; `signature` is the BLS signature bytes. A future round committed
+**before entries close** (via `commitSeedSource` / `drandRoundAt`) is unpredictable
+and non-grindable. Reference: [`drandSeed`](./src/draw.js).
+
+**drand BLS verification (full provenance):** that the signature is a valid League-
+of-Entropy threshold signature — i.e. the randomness really came from the network —
+is checked with BLS12-381 pairings. Message hashing per scheme:
+
+| `schemeID` | sig group | pubkey group | message digest | hash-to-curve DST |
+|---|---|---|---|---|
+| `bls-unchained-g1-rfc9380` (quicknet) | G1 (48 B) | G2 (96 B) | `SHA256(round_be8)` | `BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_` |
+| `pedersen-bls-chained` (legacy mainnet) | G2 (96 B) | G1 (48 B) | `SHA256(previous_signature ‖ round_be8)` | `BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_` |
+
+`round_be8` is the round as an unsigned 64-bit big-endian integer. This check is
+**optional** and lives in a separate module/import subpath
+([`src/drand-bls.js`](./src/drand-bls.js), `@kirkelabs/walletless-kit/drand-bls`).
+It is backed by `@noble/curves`, declared as an **optional peer dependency** —
+install it (`npm i @noble/curves`) only if you want BLS verification; the core
+package and the §1–§4 / §8 verifier pull in no pairing crypto. Frozen real-beacon
+vectors: [`test/drand-vectors.json`](./test/drand-vectors.json).
+
+## 6. Receipt chain
+
+Each receipt is non-PII and hash-chained:
+
+```
+receiptHash = SHA256( canonicalJSON( receipt without {receiptHash, signature} ) )
+receipt[i].previousHash == receipt[i-1].receiptHash   (null for the first)
+```
+
+Verify by recomputing each `receiptHash` and checking the links. An optional
+ed25519 `signature` over the receipt MAY be present (verified by the producing side
+via oaa-core); the zero-dep verifier checks hashes and links only. Reference:
+[`verifyReceiptChain`](./src/verify.js).
+
+## 7. On-chain anchors (optional, non-normative for verification)
+
+Commitments are written on-chain as a 0-amount self-payment whose note is
+ASCII-tagged and ≤ 1 KB — **never** any PII or receipt/event body:
+
+```
+audit anchor:   walletless-anchor:v1:<merkleRoot hex>
+receipt attest: walletless-receipt:v1:<receiptHash hex>
+```
+
+The chain is a timestamping/availability layer only; all verification in §1–§6 is
+independent of it.
+
+## 8. Proof bundle (`walletless-proof/v1`)
+
+A single portable artifact packing a draw + optional entries, seed source, receipt
+chain, trail root, and anchors:
+
+```
+{ bundleVersion: "walletless-proof/v1",
+  draw, seedSource, entries|null, receipts|null,
+  trail: { root, count }|null, anchors|null, meta|null,
+  bundleHash }                          # SHA256(canonicalJSON(bundle without bundleHash))
+```
+
+`verifyBundle` re-derives each present section and returns a per-section verdict.
+A bundle **with** `entries` is fully self-verifying; **without** them it is a
+commitment that entrants check with their own §4.1 inclusion proofs. Reference:
+[`bundleProof` / `verifyBundle`](./src/verify.js).
+
+---
+
+## Conformance
+
+An implementation conforms to **walletless-proof/v1** if, given
+[`test/vectors.json`](./test/vectors.json), it reproduces: the Merkle roots (§2),
+the consistency proof and its verification (§3), the draw proof and winners (§4),
+the entrant inclusion proof (§4.1), and the drand `randomness = SHA256(signature)`
+binding (§5). Version this document and the `bundleVersion` tag together; any change
+to a hashing rule is a new major version with new frozen vectors.

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "@kirkelabs/walletless-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Walletless web architecture toolkit: low-friction onboarding (ephemeral custodial accounts), receipt-only on-chain proofs, a tamper-evident hash-chained + Merkle audit trail, segregated money ledgers, and a verifiable, recomputable draw. Charity prize-draws are the flagship example; every module is reusable for any walletless commerce flow. Built on @kirkelabs/open-agent-access-core and @kirkelabs/oaa-agent-kit. Free & open source from Kirke Labs.",
   "type": "module",
   "bin": {
     "walletless": "bin/cli.js"
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./drand-bls": "./src/drand-bls.js",
+    "./verify": "./src/verify.js"
   },
   "files": [
     "bin/",
     "src/",
     "examples/",
+    "test/vectors.json",
+    "test/drand-vectors.json",
     "LICENSE",
     "LEGAL.md",
     "README.md",
+    "SPEC.md",
     "CHANGELOG.md"
   ],
   "publishConfig": {
@@ -62,11 +67,20 @@
     "node": ">=20"
   },
   "dependencies": {
-    "algosdk": "^3.6.0",
+    "@kirkelabs/oaa-agent-kit": "^0.7.1",
     "@kirkelabs/open-agent-access-core": "^0.1.0",
-    "@kirkelabs/oaa-agent-kit": "^0.7.1"
+    "algosdk": "^3.6.0"
+  },
+  "peerDependencies": {
+    "@noble/curves": "^1.9.7"
+  },
+  "peerDependenciesMeta": {
+    "@noble/curves": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@noble/curves": "^1.9.7",
     "eslint": "^9.0.0",
     "prettier": "^3.0.0"
   }

package/src/audit.js

@@ -12,96 +12,41 @@
  * so it is built defensively (see `merkleRoot`).
  */
 
-import { createHash } from 'node:crypto';
 import algosdk from 'algosdk';
 import {
   appendAccessEvent,
   verifyAccessEventTrail,
   hashAccessEvents,
-  canonicalizeJson,
 } from '@kirkelabs/open-agent-access-core';
+// The Merkle math lives in the zero-dependency `merkle.js` core so the standalone
+// verifier (`verify.js`) and any second implementation can reproduce these exact
+// roots without pulling in algosdk or oaa-core.
+import {
+  merkleRoot,
+  merkleProof,
+  verifyMerkleProof,
+  consistencyProof,
+  verifyConsistencyProof,
+} from './merkle.js';
 
-const MAX_LEAVES = 1_000_000; // DoS bound
-// RFC 6962 domain-separation tags: leaves and internal nodes are hashed in
-// DIFFERENT domains so a leaf can never be reinterpreted as an internal node
-// (which would otherwise enable second-preimage forgery of the root).
-const LEAF = Buffer.from([0x00]);
-const NODE = Buffer.from([0x01]);
-
-function sha256(...bufs) {
-  const h = createHash('sha256');
-  for (const b of bufs) h.update(b);
-  return h.digest();
-}
-/** Injective leaf encoding via canonical JSON, then domain-tagged hash. */
-function leafHash(item) {
-  return sha256(LEAF, Buffer.from(canonicalizeJson(item), 'utf8'));
-}
-
-/**
- * Deterministic Merkle root (hex) over an ordered list of items.
- *
- * Defensive choices:
- *  - Domain separation: leaf = H(0x00‖data), node = H(0x01‖left‖right).
- *  - A lone (odd) node is PROMOTED to the next level unchanged — it is NOT
- *    duplicated (duplicating the last node is the Bitcoin CVE-2012-2459
- *    ambiguity, where two different trees share a root).
- *  - Empty list → H("") (RFC 6962 empty-tree root). Single item → its leaf hash.
- */
-export function merkleRoot(items) {
-  if (!Array.isArray(items)) throw new Error('merkleRoot: items must be an array');
-  if (items.length > MAX_LEAVES) throw new Error('merkleRoot: too many leaves');
-  if (items.length === 0) return sha256(Buffer.alloc(0)).toString('hex');
-  let level = items.map(leafHash);
-  while (level.length > 1) {
-    const next = [];
-    for (let i = 0; i < level.length; i += 2) {
-      next.push(i + 1 < level.length ? sha256(NODE, level[i], level[i + 1]) : level[i]);
-    }
-    level = next;
-  }
-  return level[0].toString('hex');
-}
+export { merkleRoot, merkleProof, verifyMerkleProof, consistencyProof, verifyConsistencyProof };
 
 /**
- * Inclusion proof for the item at `index`. Returns the sibling hashes (hex) and
- * their side, which `verifyMerkleProof` replays to recompute the root.
+ * Consistency proof that the first `oldSize` events of `trail` (an earlier,
+ * already-anchored state) are a verbatim prefix of the trail as it stands now —
+ * i.e. the operator only APPENDED and never rewrote history. This is the RFC 6962
+ * append-only guarantee; pair it with the on-chain anchors from `anchor()`:
+ * anchor the root at size m, later anchor the root at size n, and anyone can prove
+ * the m→n transition was append-only with `verifyTrailConsistency`.
+ * @returns {{oldSize:number,newSize:number,proof:string[]}}
  */
-export function merkleProof(items, index) {
-  if (!Array.isArray(items) || index < 0 || index >= items.length)
-    throw new Error('merkleProof: index out of range');
-  let level = items.map(leafHash);
-  let idx = index;
-  const path = [];
-  while (level.length > 1) {
-    const next = [];
-    for (let i = 0; i < level.length; i += 2) {
-      if (i + 1 < level.length) {
-        next.push(sha256(NODE, level[i], level[i + 1]));
-        if (i === idx) path.push({ side: 'right', hash: level[i + 1].toString('hex') });
-        else if (i + 1 === idx) path.push({ side: 'left', hash: level[i].toString('hex') });
-      } else {
-        next.push(level[i]); // promoted; no sibling recorded for the lone node
-      }
-    }
-    idx = Math.floor(idx / 2);
-    level = next;
-  }
-  return { index, leaf: leafHash(items[index]).toString('hex'), path };
+export function trailConsistencyProof(trail, oldSize) {
+  return consistencyProof(trail?.events ?? [], oldSize);
 }
 
-/** Verify an inclusion proof against an expected root. */
-export function verifyMerkleProof({ leaf, path, root }) {
-  try {
-    let acc = Buffer.from(String(leaf), 'hex');
-    for (const step of path || []) {
-      const sib = Buffer.from(String(step.hash), 'hex');
-      acc = step.side === 'left' ? sha256(NODE, sib, acc) : sha256(NODE, acc, sib);
-    }
-    return { ok: acc.toString('hex') === String(root) };
-  } catch (e) {
-    return { ok: false, reason: `verify_error:${e.message}` };
-  }
+/** Verify a trail consistency proof between two anchored roots. Never throws. */
+export function verifyTrailConsistency(args) {
+  return verifyConsistencyProof(args);
 }
 
 /** A fresh empty trail. */

package/src/drand-bls.js

@@ -0,0 +1,164 @@
+/**
+ * drand-bls.js — REAL BLS verification of drand beacons.
+ *
+ * `draw.js`'s `drandSeed` enforces the cheap, SHA-256-only binding
+ * `randomness == SHA256(signature)`. This module adds the strong guarantee: that
+ * the signature is a valid League-of-Entropy THRESHOLD signature over the round
+ * under the network's public key — i.e. the randomness was genuinely produced by
+ * the drand network and not fabricated. With this, a drand-seeded draw is
+ * non-manipulable AND its provenance is cryptographically proven, not asserted.
+ *
+ * It is kept in a SEPARATE module (and a separate import subpath) so the
+ * zero-dependency verifier in `verify.js` stays dependency-free: pull in the
+ * BLS18-381 pairing math (@noble/curves) only if and when you want this check.
+ *
+ * Two drand schemes are supported, matched by `schemeID`:
+ *   - `bls-unchained-g1-rfc9380` (quicknet): signatures on G1, public key on G2,
+ *     message = SHA256(round_be8). The recommended network for new draws.
+ *   - `pedersen-bls-chained`   (legacy mainnet): signatures on G2, public key on
+ *     G1, message = SHA256(previous_signature ‖ round_be8).
+ *
+ * Verification math is provided by @noble/curves; its default hash-to-curve DSTs
+ * (`BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_` / `…G2…`) match drand's exactly.
+ * Cross-checked against live beacon rounds, frozen into `test/drand-vectors.json`.
+ */
+
+import { createHash } from 'node:crypto';
+
+// @noble/curves is an OPTIONAL peer dependency: the BLS12-381 pairing math is only
+// needed for this module, so the core package (receipts / audit / ledger / draw /
+// the zero-dep verifier) installs nothing extra. Load it lazily and fail with a
+// clear, actionable message if a consumer reaches for BLS without installing it.
+let bls = null;
+try {
+  ({ bls12_381: bls } = await import('@noble/curves/bls12-381'));
+} catch {
+  bls = null;
+}
+
+function requireBls() {
+  if (!bls)
+    throw new Error(
+      'drand BLS verification needs the optional peer dependency "@noble/curves". ' +
+        'Install it to enable this check:  npm i @noble/curves',
+    );
+  return bls;
+}
+
+function sha256(buf) {
+  return createHash('sha256').update(buf).digest();
+}
+
+/** drand serialises the round number as an unsigned 64-bit big-endian integer. */
+function roundBytes(round) {
+  const b = Buffer.alloc(8);
+  b.writeBigUInt64BE(BigInt(round));
+  return b;
+}
+
+/**
+ * Frozen drand network parameters. Public keys are published constants; pass your
+ * own `publicKey` to `makeDrandVerifier` to pin a different network.
+ */
+export const DRAND_QUICKNET_SCHEME = Object.freeze({
+  schemeID: 'bls-unchained-g1-rfc9380',
+  chainHash: '52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971',
+  publicKey:
+    '83cf0f2896adee7eb8b5f01fcad3912212c437e0073e911fb90022d3e760183c8c4b450b6a0a6c3ac6a5776a2d1064510d1fec758c921cc22b0e17e63aaf4bcb5ed66304de9cf809bd274ca73bab4af5a6e9c76a4bc09e76eae8991ef5ece45a',
+  genesisTime: 1692803367,
+  period: 3,
+});
+
+export const DRAND_DEFAULT_SCHEME = Object.freeze({
+  schemeID: 'pedersen-bls-chained',
+  chainHash: '8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce',
+  publicKey:
+    '868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31',
+  genesisTime: 1595431050,
+  period: 30,
+});
+
+/** Look up a known scheme by its `schemeID`. */
+function knownScheme(schemeID) {
+  if (schemeID === DRAND_QUICKNET_SCHEME.schemeID) return DRAND_QUICKNET_SCHEME;
+  if (schemeID === DRAND_DEFAULT_SCHEME.schemeID) return DRAND_DEFAULT_SCHEME;
+  return null;
+}
+
+/**
+ * Verify a single drand beacon's BLS signature (and, by default, the
+ * `randomness == SHA256(signature)` binding). Returns a boolean and never throws
+ * on bad beacon data — but DOES throw if the optional `@noble/curves` peer
+ * dependency is not installed (so a missing library is never mistaken for an
+ * invalid beacon). Selects the curve/message construction from `schemeID`.
+ *
+ * @param {object} beacon  `{ round, signature, randomness?, previousSignature? }` (hex)
+ * @param {object} opts
+ * @param {string} opts.publicKey  network public key (hex)
+ * @param {string} opts.schemeID   one of the supported scheme ids
+ * @param {boolean} [opts.checkRandomness=true]  also enforce randomness binding
+ * @returns {boolean}
+ */
+export function verifyDrandBeacon(beacon, { publicKey, schemeID, checkRandomness = true } = {}) {
+  const b = requireBls(); // throws a clear install error if the peer dep is absent
+  try {
+    const { round, signature, randomness } = beacon || {};
+    // Accept either the camelCase field (from `fetchDrandRound`) or the raw
+    // `previous_signature` field (straight from the drand HTTP API).
+    const previousSignature = beacon?.previousSignature ?? beacon?.previous_signature ?? null;
+    if (round == null || !signature || !publicKey || !schemeID) return false;
+
+    if (checkRandomness && randomness != null) {
+      if (sha256(Buffer.from(String(signature), 'hex')).toString('hex') !== String(randomness).toLowerCase())
+        return false;
+    }
+
+    if (schemeID === DRAND_QUICKNET_SCHEME.schemeID) {
+      // Unchained, signature on G1: message = SHA256(round_be8).
+      const digest = sha256(roundBytes(round));
+      const point = b.shortSignatures.hash(digest);
+      return b.shortSignatures.verify(String(signature), point, String(publicKey)) === true;
+    }
+    if (schemeID === DRAND_DEFAULT_SCHEME.schemeID) {
+      // Chained, signature on G2: message = SHA256(previous_signature ‖ round_be8).
+      if (!previousSignature) return false;
+      const digest = sha256(Buffer.concat([Buffer.from(String(previousSignature), 'hex'), roundBytes(round)]));
+      const point = b.longSignatures.hash(digest);
+      return b.longSignatures.verify(String(signature), point, String(publicKey)) === true;
+    }
+    return false; // unknown scheme — fail closed
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a `verifySignature` function for `drandSeed`. Bind it to a network and it
+ * returns an async predicate `({ round, signature, randomness, previousSignature })
+ * => boolean` that `drandSeed` will enforce.
+ *
+ *   import { drandSeed, fetchDrandRound } from '@kirkelabs/walletless-kit';
+ *   import { makeDrandVerifier, DRAND_QUICKNET_SCHEME } from '@kirkelabs/walletless-kit/drand-bls';
+ *
+ *   const verify = makeDrandVerifier(DRAND_QUICKNET_SCHEME);
+ *   const beacon = await fetchDrandRound(committedRound);     // after the round exists
+ *   const seed = await drandSeed(beacon, verify);             // throws unless BLS-valid
+ *   // seed.blsVerified === true
+ *
+ * @param {object} scheme `{ schemeID, publicKey }` (e.g. DRAND_QUICKNET_SCHEME). A
+ *   bare scheme id string also works, resolving a known network's public key.
+ * @param {object} [overrides] e.g. `{ publicKey }` to pin a custom network key
+ */
+export function makeDrandVerifier(scheme, overrides = {}) {
+  const base = typeof scheme === 'string' ? knownScheme(scheme) : scheme;
+  if (!base) throw new Error('makeDrandVerifier: unknown scheme — pass { schemeID, publicKey }');
+  const schemeID = base.schemeID;
+  const publicKey = overrides.publicKey ?? base.publicKey;
+  if (!schemeID || !publicKey)
+    throw new Error('makeDrandVerifier: schemeID and publicKey are required');
+  // Defensive: public key length must match the scheme's group (G2=96B, G1=48B).
+  const expectBytes = schemeID === DRAND_QUICKNET_SCHEME.schemeID ? 96 : 48;
+  if (String(publicKey).length !== expectBytes * 2)
+    throw new Error(`makeDrandVerifier: publicKey must be ${expectBytes} bytes for ${schemeID}`);
+  return async (beacon) => verifyDrandBeacon(beacon, { publicKey, schemeID });
+}