@kirkelabs/walletless-kit 0.1.0

package/src/audit.js

@@ -0,0 +1,183 @@
+/**
+ * audit.js — a tamper-evident audit trail.
+ *
+ * Two layers, both built on @kirkelabs/open-agent-access-core:
+ *   1. An append-only HASH-CHAINED event log (each event commits to the previous
+ *      one's hash) — editing or removing any event breaks the chain. This is
+ *      core's `appendAccessEvent` / `verifyAccessEventTrail`.
+ *   2. A MERKLE ROOT over the events — a single 32-byte commitment you can anchor
+ *      on-chain cheaply and use for inclusion proofs.
+ *
+ * The Merkle construction is the only new cryptographic primitive in this package,
+ * 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';
+
+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');
+}
+
+/**
+ * Inclusion proof for the item at `index`. Returns the sibling hashes (hex) and
+ * their side, which `verifyMerkleProof` replays to recompute the root.
+ */
+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 };
+}
+
+/** 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}` };
+  }
+}
+
+/** A fresh empty trail. */
+export function createTrail() {
+  return { events: [] };
+}
+
+/**
+ * Append an event to the trail (hash-chained via core). Returns a NEW trail.
+ * Pass deterministic `eventId`/`timestamp` in `input` if you need reproducibility.
+ */
+export function append(trail, input) {
+  const events = appendAccessEvent(trail?.events ?? [], input ?? {});
+  return { events };
+}
+
+/** sha256 commitment over the event hashes (cheap integrity digest). */
+export function trailHash(trail) {
+  return hashAccessEvents(trail?.events ?? []);
+}
+
+/** Merkle root over the trail's events. */
+export function trailRoot(trail) {
+  return merkleRoot(trail?.events ?? []);
+}
+
+/**
+ * Verify the trail end-to-end. Robust to malformed input (never throws). Reports
+ * whether the hash-chain is intact and returns the current Merkle root.
+ * @returns {{ok:boolean, count:number, errors:string[], root:string|null}}
+ */
+export function verifyTrail(trail) {
+  try {
+    const events = Array.isArray(trail) ? trail : trail?.events;
+    if (!Array.isArray(events)) return { ok: false, count: 0, errors: ['not_a_trail'], root: null };
+    const res = verifyAccessEventTrail(events);
+    return {
+      ok: res.valid,
+      count: res.count,
+      errors: res.errors,
+      root: res.valid ? merkleRoot(events) : null,
+    };
+  } catch (e) {
+    return { ok: false, count: 0, errors: [`verify_error:${e.message}`], root: null };
+  }
+}
+
+/**
+ * Anchor a Merkle root on-chain as a compact, NON-PII checkpoint: a 0-amount
+ * self-payment whose note is `walletless-anchor:v1:<root>`. Network-bound (the
+ * transaction carries the node's genesis hash) and size-bounded (note ≤ 1 KB).
+ *
+ * @param {algosdk.Algodv2} algod
+ * @param {{address:string, signTxns:Function}} signer e.g. an oaa-agent-kit LocalOwnerSigner
+ * @param {string} root hex Merkle root
+ * @returns {Promise<{txid:string, confirmedRound:number, root:string}>}
+ */
+export async function anchor(algod, signer, root) {
+  if (!/^[0-9a-f]{2,128}$/i.test(String(root)))
+    throw new Error('anchor: root must be a hex string');
+  const note = new TextEncoder().encode(`walletless-anchor:v1:${root}`);
+  if (note.length > 1024) throw new Error('anchor: note exceeds 1KB');
+  const sp = await algod.getTransactionParams().do();
+  const txn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+    sender: signer.address,
+    receiver: signer.address, // self-payment: moves nothing, just records the note
+    amount: 0,
+    note,
+    suggestedParams: sp,
+  });
+  const [signed] = await signer.signTxns([txn]);
+  const { txid } = await algod.sendRawTransaction(signed).do();
+  const res = await algosdk.waitForConfirmation(algod, txid, 10);
+  return {
+    txid,
+    confirmedRound: Number(res.confirmedRound ?? res['confirmed-round']),
+    root: String(root),
+  };
+}

package/src/draw.js

@@ -0,0 +1,197 @@
+/**
+ * draw.js — a verifiable, recomputable draw.
+ *
+ * The winner is a DETERMINISTIC function of (public seed, ordered entries), so
+ * anyone can recompute it from the published proof. Fairness is therefore exactly
+ * as strong as the seed — no more (see LEGAL.md / README):
+ *   - A blockchain BLOCK HASH is manipulable: a block producer can withhold or
+ *     grind a block to bias the outcome. Mitigate with `commitSeedSource` (announce
+ *     the exact future round whose hash will be the seed BEFORE entries close, so
+ *     the operator cannot pick a favourable one), and prefer a VRF / drand beacon
+ *     for anything of value.
+ *   - Randomness comes from a CSPRNG-style expansion of the seed (SHA-256 stream)
+ *     with REJECTION SAMPLING (no modulo bias). There is no `Math.random` here.
+ *
+ * `runDraw` and `verifyDraw` are pure and recomputable; ship the frozen test
+ * vector in the tests as the canonical reference.
+ */
+
+import { createHash } from 'node:crypto';
+import { merkleRoot } from './audit.js';
+
+const MAX_ENTRIES = 5_000_000;
+const ALGORITHM = 'fisher-yates-sha256-v1';
+
+function sha256(...bufs) {
+  const h = createHash('sha256');
+  for (const b of bufs) h.update(b);
+  return h.digest();
+}
+
+/** Deterministic byte stream from a seed: SHA-256(seed ‖ ':' ‖ counterLE). */
+function makeRng(seed) {
+  const seedBuf = Buffer.from(String(seed), 'utf8');
+  let counter = 0;
+  let pool = Buffer.alloc(0);
+  let used = 0;
+  const refill = () => {
+    const c = Buffer.alloc(8);
+    c.writeUInt32LE(counter >>> 0, 0);
+    c.writeUInt32LE(Math.floor(counter / 2 ** 32) >>> 0, 4);
+    pool = sha256(seedBuf, Buffer.from(':'), c);
+    counter += 1;
+    used = 0;
+  };
+  return {
+    nextBytes(n) {
+      const out = Buffer.alloc(n);
+      let o = 0;
+      while (o < n) {
+        if (used >= pool.length) refill();
+        const take = Math.min(n - o, pool.length - used);
+        pool.copy(out, o, used, used + take);
+        used += take;
+        o += take;
+      }
+      return out;
+    },
+  };
+}
+
+/** Uniform integer in [0, maxExclusive) via 48-bit rejection sampling (unbiased). */
+function uniformInt(rng, maxExclusive) {
+  if (maxExclusive <= 1) return 0;
+  const span = 0x1000000000000; // 2^48
+  const limit = Math.floor(span / maxExclusive) * maxExclusive;
+  for (;;) {
+    const v = rng.nextBytes(6).readUIntBE(0, 6);
+    if (v < limit) return v % maxExclusive;
+  }
+}
+
+/** Deterministic Fisher–Yates shuffle of a copy of `items`, driven by `seed`. */
+function shuffle(items, seed) {
+  const a = items.slice();
+  const rng = makeRng(seed);
+  for (let i = a.length - 1; i >= 1; i--) {
+    const j = uniformInt(rng, i + 1);
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}
+
+/**
+ * Run a draw. Deterministic and recomputable.
+ * @param {{entries:string[], seed:string, winners?:number, algorithm?:string}} opts
+ * @returns {{winners:string[], winnerIndices:number[], algorithm:string, seed:string, entryCount:number}}
+ */
+export function runDraw({ entries, seed, winners = 1, algorithm = ALGORITHM }) {
+  if (!Array.isArray(entries) || entries.length === 0)
+    throw new Error('runDraw: entries must be a non-empty array');
+  if (entries.length > MAX_ENTRIES) throw new Error('runDraw: too many entries');
+  if (seed == null || String(seed).length === 0) throw new Error('runDraw: seed is required');
+  if (algorithm !== ALGORITHM) throw new Error(`runDraw: unsupported algorithm ${algorithm}`);
+  const k = Number(winners);
+  if (!Number.isInteger(k) || k < 1 || k > entries.length)
+    throw new Error('runDraw: winners must be an integer in [1, entries.length]');
+
+  const order = shuffle(
+    entries.map((_, i) => i),
+    seed,
+  );
+  const winnerIndices = order.slice(0, k);
+  return {
+    winners: winnerIndices.map((i) => entries[i]),
+    winnerIndices,
+    algorithm,
+    seed: String(seed),
+    entryCount: entries.length,
+  };
+}
+
+/**
+ * A publishable proof: the seed, algorithm, a commitment to the exact entry set
+ * (Merkle root), and the resulting winners. Anyone can recompute with `verifyDraw`.
+ */
+export function publishDrawProof({ entries, seed, winners = 1, algorithm = ALGORITHM }) {
+  const result = runDraw({ entries, seed, winners, algorithm });
+  return {
+    algorithm: result.algorithm,
+    seed: result.seed,
+    entryCount: result.entryCount,
+    entriesRoot: merkleRoot(entries), // commits to the exact ordered entry set
+    winners: result.winners,
+    winnerIndices: result.winnerIndices,
+  };
+}
+
+/**
+ * Recompute a draw from its proof + the entry set and confirm the winners match
+ * and the entries match the committed root. Robust to malformed input.
+ * @returns {{ok:boolean, reason?:string}}
+ */
+export function verifyDraw(proof, entries) {
+  try {
+    if (!proof || !Array.isArray(entries)) return { ok: false, reason: 'bad_input' };
+    if (merkleRoot(entries) !== proof.entriesRoot) return { ok: false, reason: 'entries_root_mismatch' };
+    const re = runDraw({
+      entries,
+      seed: proof.seed,
+      winners: proof.winnerIndices?.length ?? 1,
+      algorithm: proof.algorithm,
+    });
+    const same =
+      re.winnerIndices.length === proof.winnerIndices.length &&
+      re.winnerIndices.every((v, i) => v === proof.winnerIndices[i]);
+    return same ? { ok: true } : { ok: false, reason: 'winner_mismatch' };
+  } catch (e) {
+    return { ok: false, reason: `verify_error:${e.message}` };
+  }
+}
+
+// ─── Seed adapters ──────────────────────────────────────────────────────────
+// Each returns { source, value, ...context }. Document manipulability honestly.
+
+/**
+ * Publish a SEED COMMITMENT *before* entries close: it names the exact future
+ * round whose block hash will be the seed, so the operator cannot later pick a
+ * favourable seed. Reveal the hash (via `blockHashSeed`) only after that round.
+ */
+export function commitSeedSource({ source = 'algorand-block', round, committedAtRound }) {
+  if (!Number.isInteger(Number(round))) throw new Error('commitSeedSource: round is required');
+  return {
+    source,
+    round: Number(round),
+    committedAtRound: committedAtRound == null ? null : Number(committedAtRound),
+    note: 'Seed = hash of the named round, knowable only after that round is produced.',
+  };
+}
+
+/**
+ * Derive a seed from an Algorand block's sortition SEED (`block.header.seed`, a
+ * 32-byte VRF-derived value). ⚠ A block proposer can still influence or withhold a
+ * block to bias the outcome — only use with `commitSeedSource` (commit the round
+ * in advance, before entries close) and prefer a VRF/beacon for high-value draws.
+ */
+export async function blockHashSeed(algod, round) {
+  const blk = await algod.block(Number(round)).do();
+  const header = blk?.block?.header ?? blk?.block ?? blk;
+  const seed = header?.seed;
+  let value;
+  if (seed instanceof Uint8Array || Buffer.isBuffer(seed)) value = Buffer.from(seed).toString('hex');
+  else if (typeof seed === 'string') value = Buffer.from(seed, 'base64').toString('hex');
+  else throw new Error(`blockHashSeed: could not read block seed for round ${round}`);
+  return { source: 'algorand-block-seed', round: Number(round), value, manipulable: true };
+}
+
+/** Wrap a VRF output (you supply the verified value+proof from your VRF). */
+export function vrfSeed({ value, proof, publicKey }) {
+  if (!value) throw new Error('vrfSeed: value is required');
+  return { source: 'vrf', value: String(value), proof: proof ?? null, publicKey: publicKey ?? null };
+}
+
+/** Wrap a public randomness-beacon value (e.g. drand). */
+export function beaconSeed({ value, round, beacon = 'drand' }) {
+  if (!value) throw new Error('beaconSeed: value is required');
+  return { source: 'beacon', beacon, round: round == null ? null : Number(round), value: String(value) };
+}

package/src/identity.js

@@ -0,0 +1,110 @@
+/**
+ * identity.js — identity-lite (email/SMS OTP) without storing raw contact data.
+ *
+ * Hardening (see SECURITY.md / LEGAL.md):
+ *   - OTP codes are generated with a CSPRNG (`crypto.randomInt`), never Math.random.
+ *   - Single-use, time-bound (expiry), rate-limited (core InMemoryRateLimiter),
+ *     and locked out after N failed attempts.
+ *   - Codes are compared in constant time and only their KEYED hash is stored —
+ *     never the raw code.
+ *   - Contacts are stored only as KEYED (peppered) hashes — pseudonymous, still
+ *     personal data under GDPR; never the raw email/phone.
+ *   - Failures are generic (anti-enumeration): a caller cannot tell whether a
+ *     given contact has an outstanding challenge.
+ */
+
+import { createHmac, randomInt } from 'node:crypto';
+import { InMemoryRateLimiter } from '@kirkelabs/open-agent-access-core';
+import { hashPii, hashEquals } from './privacy.js';
+
+export class OtpIdentity {
+  /**
+   * @param {object} opts
+   * @param {string}   opts.pepper       secret keyed-hash pepper (>= 16 chars)
+   * @param {Function} [opts.send]       async (contact, code) => deliver out-of-band
+   * @param {number}   [opts.codeLength] digits (default 6)
+   * @param {number}   [opts.ttlMs]      code validity (default 5 min)
+   * @param {number}   [opts.maxAttempts] failures before lockout (default 5)
+   * @param {object}   [opts.rateLimit]  { requests, window } e.g. {requests:5, window:'10m'}
+   */
+  constructor({
+    pepper,
+    send,
+    codeLength = 6,
+    ttlMs = 5 * 60_000,
+    maxAttempts = 5,
+    rateLimit = { requests: 5, window: '10m' },
+  } = {}) {
+    if (typeof pepper !== 'string' || pepper.length < 16)
+      throw new Error('OtpIdentity: pepper must be a secret string of >= 16 chars');
+    this._pepper = pepper;
+    this._send = send;
+    this._codeLength = codeLength;
+    this._ttlMs = ttlMs;
+    this._maxAttempts = maxAttempts;
+    this._rateLimit = rateLimit;
+    this._rl = new InMemoryRateLimiter();
+    this._challenges = new Map(); // contactHash -> { codeHash, expiresAt, attempts, used }
+  }
+
+  /** Keyed, pseudonymous reference for a contact (what you store/de-dup on). */
+  contactRef(contact) {
+    return hashPii(contact, this._pepper);
+  }
+
+  _codeHash(code) {
+    return createHmac('sha256', this._pepper).update(`otp:${code}`, 'utf8').digest('hex');
+  }
+
+  /**
+   * Issue a fresh OTP for a contact and deliver it via `send`. Does NOT return the
+   * code. Rate-limited per contact.
+   * @returns {Promise<{sent:boolean, contactRef:string, expiresAt?:number, reason?:string, retryAfter?:number}>}
+   */
+  async issueChallenge(contact, { now = Date.now() } = {}) {
+    const contactRef = this.contactRef(contact);
+    const rl = this._rl.check(`otp-issue:${contactRef}`, this._rateLimit, now);
+    if (!rl.allowed)
+      return { sent: false, contactRef, reason: 'rate_limited', retryAfter: rl.retryAfter };
+
+    // CSPRNG numeric code, zero-padded to codeLength.
+    const max = 10 ** this._codeLength;
+    const code = String(randomInt(0, max)).padStart(this._codeLength, '0');
+    const expiresAt = now + this._ttlMs;
+    this._challenges.set(contactRef, {
+      codeHash: this._codeHash(code),
+      expiresAt,
+      attempts: 0,
+      used: false,
+    });
+    if (typeof this._send === 'function') await this._send(contact, code);
+    return { sent: true, contactRef, expiresAt };
+  }
+
+  /**
+   * Verify a submitted code. Single-use, expiring, attempt-limited, constant-time.
+   * Returns a GENERIC failure (anti-enumeration) on any invalid/expired/missing case.
+   * @returns {Promise<{ok:boolean, contactRef:string, reason?:string, retryAfter?:number}>}
+   */
+  async verifyChallenge(contact, code, { now = Date.now() } = {}) {
+    const contactRef = this.contactRef(contact);
+    const rl = this._rl.check(`otp-verify:${contactRef}`, this._rateLimit, now);
+    if (!rl.allowed)
+      return { ok: false, contactRef, reason: 'rate_limited', retryAfter: rl.retryAfter };
+
+    const ch = this._challenges.get(contactRef);
+    if (!ch || ch.used || now > ch.expiresAt)
+      return { ok: false, contactRef, reason: 'invalid_or_expired' };
+    if (ch.attempts >= this._maxAttempts)
+      return { ok: false, contactRef, reason: 'locked_out' };
+
+    ch.attempts += 1;
+    const match = hashEquals(this._codeHash(String(code)), ch.codeHash);
+    if (!match) {
+      const locked = ch.attempts >= this._maxAttempts;
+      return { ok: false, contactRef, reason: locked ? 'locked_out' : 'invalid_or_expired' };
+    }
+    ch.used = true; // single-use: consume the challenge on success
+    return { ok: true, contactRef };
+  }
+}

package/src/index.js

@@ -0,0 +1,64 @@
+/**
+ * @kirkelabs/walletless-kit — public API.
+ *
+ * A walletless web-architecture toolkit: ephemeral custodial onboarding,
+ * receipt-only on-chain proofs, a tamper-evident audit trail, segregated money
+ * ledgers, a verifiable recomputable draw, and privacy/erasure helpers. Built on
+ * @kirkelabs/open-agent-access-core and @kirkelabs/oaa-agent-kit. MIT.
+ *
+ * TestNet by default. Some modules are EXPERIMENTAL · UNAUDITED — see LEGAL.md.
+ */
+
+// Convenience: re-export the Algod client + algosdk from oaa-agent-kit so callers
+// need only one import for the chain client.
+export { getAlgod, algosdk } from '@kirkelabs/oaa-agent-kit';
+
+export {
+  hashPii,
+  hashEquals,
+  pseudonymRef,
+  eraseSubject,
+  assertNoPii,
+} from './privacy.js';
+
+export {
+  createTrail,
+  append,
+  merkleRoot,
+  merkleProof,
+  verifyMerkleProof,
+  trailHash,
+  trailRoot,
+  verifyTrail,
+  anchor,
+} from './audit.js';
+
+export {
+  createEphemeralAccount,
+  isExpired,
+  expireAccount,
+  rotateAccount,
+} from './onboarding.js';
+
+export { OtpIdentity } from './identity.js';
+
+export {
+  buildOrderReceipt,
+  deterministicOrderId,
+  signReceipt,
+  verifyReceiptChain,
+  attestOnChain,
+  chargeForAction,
+} from './receipt.js';
+
+export { Ledger, createLedger } from './ledger.js';
+
+export {
+  runDraw,
+  publishDrawProof,
+  verifyDraw,
+  commitSeedSource,
+  blockHashSeed,
+  vrfSeed,
+  beaconSeed,
+} from './draw.js';

package/src/ledger.js

@@ -0,0 +1,112 @@
+/**
+ * ledger.js — segregated, append-only money books for a walletless flow.
+ *
+ * Three independent books — `inflow`, `charity`, `escrow` — keep ticket revenue,
+ * charity allocations, and held funds clearly separated for reconciliation.
+ *
+ * Hardening:
+ *   - Money is ALWAYS integer microALGO (or BigInt-safe integers). Never a JS
+ *     float — floating-point money silently drifts and breaks reconciliation.
+ *   - Books are append-only; `snapshot()` returns a deep-FROZEN copy so a caller
+ *     can't retro-edit history.
+ *   - `reconciliationSheet` is a pure, deterministic function of the books.
+ *
+ * This is bookkeeping/transparency tooling, NOT regulated custody or accounting.
+ * See LEGAL.md (money handling / AML).
+ */
+
+const BOOKS = ['inflow', 'charity', 'escrow'];
+const MAX_SAFE = Number.MAX_SAFE_INTEGER;
+
+function assertMicro(amount) {
+  const n = Number(amount);
+  if (!Number.isInteger(n) || n < 0 || n > MAX_SAFE)
+    throw new Error('ledger: amountMicro must be a non-negative integer (microALGO), never a float');
+  return n;
+}
+
+export class Ledger {
+  constructor() {
+    this._books = { inflow: [], charity: [], escrow: [] };
+    this._seq = 0;
+  }
+
+  /**
+   * Append an entry to a book. `amountMicro` MUST be an integer (microALGO).
+   * @param {{book:string, amountMicro:number, ref?:string, txRef?:string, kind?:string, meta?:object}} e
+   */
+  post({ book, amountMicro, ref = null, txRef = null, kind = 'generic', meta = null }) {
+    if (!BOOKS.includes(book)) throw new Error(`ledger: unknown book "${book}" (use ${BOOKS.join('/')})`);
+    const entry = Object.freeze({
+      seq: ++this._seq,
+      book,
+      amountMicro: assertMicro(amountMicro),
+      ref: ref == null ? null : String(ref),
+      txRef: txRef == null ? null : String(txRef),
+      kind: String(kind),
+      meta: meta == null ? null : Object.freeze({ ...meta }),
+    });
+    this._books[book].push(entry);
+    return entry;
+  }
+
+  /** Integer balance of a book. */
+  balance(book) {
+    if (!BOOKS.includes(book)) throw new Error(`ledger: unknown book "${book}"`);
+    return this._books[book].reduce((s, e) => s + e.amountMicro, 0);
+  }
+
+  /** All three balances. */
+  balances() {
+    return { inflow: this.balance('inflow'), charity: this.balance('charity'), escrow: this.balance('escrow') };
+  }
+
+  /** Deep-frozen immutable snapshot of every book + balances. */
+  snapshot() {
+    const books = {};
+    for (const b of BOOKS) books[b] = Object.freeze(this._books[b].slice());
+    return Object.freeze({ books: Object.freeze(books), balances: Object.freeze(this.balances()) });
+  }
+
+  /**
+   * Human-readable reconciliation sheet for a draw. Pure/deterministic.
+   * @param {string} drawId
+   * @param {{winnerProofLink?:string}} [opts]
+   */
+  reconciliationSheet(drawId, { winnerProofLink = null } = {}) {
+    const inflow = this._books.inflow;
+    const sum = (arr) => arr.reduce((s, e) => s + e.amountMicro, 0);
+    const ticketsSold = inflow.filter((e) => e.kind === 'ticket').length;
+    const gross = sum(inflow);
+    const fees = sum(
+      [...inflow, ...this._books.charity, ...this._books.escrow].filter((e) => e.kind === 'fee'),
+    );
+    const charityTotal = this.balance('charity');
+    const escrowTotal = this.balance('escrow');
+    return {
+      drawId: String(drawId),
+      ticketsSold,
+      grossMicroAlgos: gross,
+      feesMicroAlgos: fees,
+      charity: {
+        totalMicroAlgos: charityTotal,
+        destinations: this._books.charity.map((e) => ({
+          address: e.ref,
+          amountMicroAlgos: e.amountMicro,
+          txRef: e.txRef,
+        })),
+      },
+      escrow: {
+        totalMicroAlgos: escrowTotal,
+        refs: this._books.escrow.map((e) => ({ ref: e.ref, txRef: e.txRef, amountMicroAlgos: e.amountMicro })),
+      },
+      netMicroAlgos: gross - fees - charityTotal - escrowTotal,
+      winnerProofLink,
+    };
+  }
+}
+
+/** Convenience factory. */
+export function createLedger() {
+  return new Ledger();
+}