@uuaid/pillar 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/escrow/terms.mjs

@@ -0,0 +1,368 @@
+/**
+ * Escrow terms, signatures, and receipts — the signed agreements of a
+ * blind-escrow exchange on the Zilligon ZGN rail.
+ *
+ * A deal is a TERMS object signed by the seller, then counter-signed by the
+ * buyer (acceptance), then executed by an escrow agent that:
+ *   1. holds the 32-byte content key K (blind to the payload itself),
+ *   2. attests the buyer's payment from ITS OWN wallet transactions,
+ *   3. pays the seller, releases K to the buyer, and issues a signed
+ *      completion RECEIPT to each side.
+ *
+ * offerId is derived: sha256(jcs(terms-minus-offerId))[:16] — any party can
+ * recompute it, and the escrow keys its state by it.  All signatures are
+ * Ed25519 over RFC-8785 JCS (same discipline as tier grants).
+ *
+ * The rail's tip fee stays OUTSIDE the two-party agreement: signed terms carry
+ * only fee-free numbers (priceGons, sellerPayoutGons), and who absorbs the
+ * rail fee (fee(amount) = floor(amount * 0.005), mirroring the rewards
+ * service config.ts tipFeePercent) is the parties' own deal — allocateFee
+ * offers buyer / seller / split-50-50 modes, or "mutual" where the parties
+ * pick explicit numbers themselves.  The escrow NEVER derives a payout
+ * default: no explicit allocation, no signed terms.
+ *
+ * Escrow-side rail mechanics remain: feeFor mirrors the rail exactly;
+ * smallestSendFor finds the MINIMAL transfer whose receiver nets a promised
+ * amount; validatePayout checks a payout is affordable from the escrow's
+ * receipt (price - fee(price)).
+ */
+import { createHash } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+
+export const TERMS_VERSION = 1;
+export const TERMS_VERSION_2 = 2; // multi-rail terms: string base-unit amounts
+export const RAIL = "zilligon";
+export const DEFAULT_TIP_FEE = 0.005;
+export const TERMS_MAX_LIFETIME_MS = 30 * 24 * 3600 * 1000; // bound the escrow's liability window
+export const PAID_GRACE_MS = 15 * 60 * 1000; // accept a paid-claim this late after expiry (clock skew)
+
+const HEX64 = /^[0-9a-f]{64}$/i;
+// v2 amounts are DECIMAL STRINGS of rail base units (wei never fits a JS
+// number); canonical form only — no leading zeros, no sign, no decimals.
+const DEC_STR = /^(0|[1-9][0-9]*)$/;
+const MAX_UINT256 = (1n << 256n) - 1n;
+const EVM_ADDR = /^0x[0-9a-fA-F]{40}$/;
+const EVM_ASSET = /^(native|erc20:0x[0-9a-fA-F]{40})$/;
+/** Rails v2 terms may name today.  zilligon stays v1-only: its fee economics
+ *  (validatePayout) are baked into the v1 shape and the live path stays
+ *  byte-compatible. */
+export const V2_RAILS = ["evm"];
+
+/** Zilligon fee on an amount, in Gons: floor(amount * tipFeePercent). */
+export function feeFor(amount, tipFeePercent = DEFAULT_TIP_FEE) {
+  return Math.floor(amount * tipFeePercent);
+}
+
+/**
+ * Minimal transfer X such that the recipient nets >= payout Gons after the
+ * rail fee.  Ascending search bounded by the proven ceiling: net(x) =
+ * x - floor(x*r) >= x - x*r = x*(1-r), so x >= payout/(1-r) always suffices
+ * (r must be < 1 — otherwise no finite X can ever satisfy it).
+ *
+ * At DEFAULT_TIP_FEE the overshoot is ~payout/199, e.g. smallestSendFor(999)
+ * = 1004 (999 nets 995; 1004 nets 999 exactly).
+ */
+export function smallestSendFor(payout, tipFeePercent = DEFAULT_TIP_FEE) {
+  if (!(tipFeePercent >= 0 && tipFeePercent < 1)) throw new Error("smallestSendFor: tipFeePercent must be in [0, 1)");
+  const max = Math.ceil(payout / (1 - tipFeePercent));
+  for (let x = payout; x <= max; x++) {
+    if (x - feeFor(x, tipFeePercent) >= payout) return x;
+  }
+  return max; // exact at the boundary: net(max) >= payout
+}
+
+/**
+ * Split the rail's tip fee between the two parties — or don't.  The signed
+ * terms stay fee-free (priceGons + sellerPayoutGons); this helper only
+ * computes the numbers each allocation implies:
+ *   "seller"  — former alpha formula, kept as an EXPLICIT choice: payout =
+ *               net(net(price)) (seller eats the fee on both rail hops);
+ *   "buyer"   — buyer grosses the transfer up so the escrow receives exactly
+ *               priceGons (s = smallestSendFor(price); buyer sends
+ *               smallestSendFor(s); seller gets priceGons);
+ *   "split"   — 50/50: buyer sends x = smallestSendFor(price) (escrow
+ *               receives exactly price), seller's payout y = 2*price - x, so
+ *               each side absorbs exactly x - price.  Feasible by
+ *               construction: y <= net(price) implies smallestSendFor(y) <=
+ *               price (verified 2026-08-21: price 1000 -> {1005, 995},
+ *               price 200 -> {201, 199}, price 999 -> {1004, 994}).
+ *   "mutual"   — the parties agree explicit numbers themselves; returns null
+ *               (the CLI then REQUIRES --payout).
+ */
+export function allocateFee(priceGons, allocation = "mutual", tipFeePercent = DEFAULT_TIP_FEE) {
+  if (!Number.isInteger(priceGons) || priceGons < 1) throw new Error("allocateFee: priceGons must be an integer >= 1");
+  switch (allocation) {
+    case "seller": {
+      const escrowReceived = priceGons - feeFor(priceGons, tipFeePercent);
+      return { priceGons, sellerPayoutGons: escrowReceived - feeFor(escrowReceived, tipFeePercent) };
+    }
+    case "buyer": {
+      const s = smallestSendFor(priceGons, tipFeePercent);
+      return { priceGons: smallestSendFor(s, tipFeePercent), sellerPayoutGons: priceGons };
+    }
+    case "split": {
+      const x = smallestSendFor(priceGons, tipFeePercent);
+      return { priceGons: x, sellerPayoutGons: 2 * priceGons - x };
+    }
+    case "mutual":
+      return null;
+    default:
+      throw new Error(`allocateFee: unknown allocation "${allocation}"`);
+  }
+}
+
+/**
+ * Check that a payout is affordable from the escrow's receipt, and compute
+ * the exact transfer it must make.  escrowReceived = price - fee(price);
+ * escrow sends escrowSend, seller nets sellerPayoutGons, escrow keeps the
+ * (usually 0) remainder.
+ */
+export function validatePayout(priceGons, sellerPayoutGons, tipFeePercent = DEFAULT_TIP_FEE) {
+  const escrowReceived = priceGons - feeFor(priceGons, tipFeePercent);
+  const escrowSend = smallestSendFor(sellerPayoutGons, tipFeePercent);
+  if (escrowSend > escrowReceived) {
+    return { ok: false, reason: "payout-exceeds-received", escrowReceived, escrowSend };
+  }
+  return { ok: true, escrowReceived, escrowSend, commission: escrowReceived - escrowSend };
+}
+
+/** offerId = sha256(jcs(terms without offerId))[:16 hex] — self-binding. */
+export function fingerprint(terms) {
+  const { offerId, ...rest } = terms;
+  return createHash("sha256").update(jcs(rest)).digest("hex").slice(0, 16);
+}
+
+/**
+ * Assemble a terms object.  All three parties' UUAIDs AND their Zilligon
+ * handles AND their ed25519 pubkeys are signed in — the escrow needs the
+ * handles to attest/pay on the rail, and the pubkeys to reply without a
+ * directory lookup.
+ */
+export function makeTerms({
+  escrow, escrowPubKeyHex, escrowHandle,
+  seller, sellerPubKeyHex, sellerHandle,
+  buyer, buyerPubKeyHex, buyerHandle,
+  itemHash, priceGons, sellerPayoutGons,
+  expiresAt, createdAt = new Date().toISOString(),
+}) {
+  const terms = {
+    v: TERMS_VERSION,
+    escrow, escrowPubKeyHex, escrowHandle,
+    seller, sellerPubKeyHex, sellerHandle,
+    buyer, buyerPubKeyHex, buyerHandle,
+    itemHash, priceGons, sellerPayoutGons,
+    rail: RAIL, expiresAt, createdAt,
+  };
+  terms.offerId = fingerprint(terms);
+  return terms;
+}
+
+/**
+ * Assemble a v2 (multi-rail) terms object.  Amounts are decimal strings of
+ * base units; handles are rail addresses (0x… for EVM).  The rail fee model
+ * lives OUTSIDE the signed numbers, exactly like v1's tip fee: on EVM the
+ * escrow pays gas from its commission (price - sellerPayout) — the parties
+ * price that in when they set sellerPayout.
+ */
+export function makeTermsV2({
+  escrow, escrowPubKeyHex, escrowHandle,
+  seller, sellerPubKeyHex, sellerHandle,
+  buyer, buyerPubKeyHex, buyerHandle,
+  itemHash, rail = "evm", chainId, asset = "native",
+  price, sellerPayout,
+  expiresAt, createdAt = new Date().toISOString(),
+}) {
+  const terms = {
+    v: TERMS_VERSION_2,
+    escrow, escrowPubKeyHex, escrowHandle,
+    seller, sellerPubKeyHex, sellerHandle,
+    buyer, buyerPubKeyHex, buyerHandle,
+    itemHash, rail, chainId, asset,
+    price, sellerPayout,
+    expiresAt, createdAt,
+  };
+  terms.offerId = fingerprint(terms);
+  return terms;
+}
+
+/** Seller / buyer signatures over jcs(terms). */
+export function signTerms(keychain, terms) {
+  return keychain.sign(Buffer.from(jcs(terms), "utf-8")).toString("hex");
+}
+
+export function verifyTermsSig(publicKeyHex, terms, sig) {
+  try {
+    return Keychain.verifyDetached(publicKeyHex, Buffer.from(jcs(terms), "utf-8"), Buffer.from(sig, "hex"));
+  } catch (_e) {
+    return false;
+  }
+}
+
+function isUuaid(s) {
+  return typeof s === "string" && s.startsWith("uuaid:") && s.split(":").length === 4;
+}
+
+/**
+ * Structural + economic validation a receiving escrow runs on any terms
+ * object before acting.  escrowUuaid/escrowHandle must be THIS escrow.
+ */
+export function validateTerms(terms, opts = {}) {
+  if (terms?.v === TERMS_VERSION_2) return validateTermsV2(terms, opts);
+  return validateTermsV1(terms, opts);
+}
+
+function validateTermsV1(terms, { now = Date.now(), escrowUuaid, escrowHandle } = {}) {
+  if (!terms || terms.v !== TERMS_VERSION) return { ok: false, reason: "bad-version" };
+  // v1 IS the zilligon rail; a stray rail label is a signature-bound lie —
+  // routing ignores it (railKeyOfTerms pins v1 to zilligon), but reject it
+  // anyway so no receipt can carry a mislabel.
+  if (terms.rail != null && terms.rail !== RAIL) return { ok: false, reason: "bad-rail" };
+  // Field checks BEFORE the fingerprint: a hostile terms object can carry
+  // non-integer numbers (which JCS refuses to canonicalize), and the specific
+  // field reason is more useful than bad-offerId for a multi-defect object.
+  for (const f of ["escrow", "seller", "buyer"]) {
+    if (!isUuaid(terms[f])) return { ok: false, reason: `bad-${f}-uuaid` };
+    if (!HEX64.test(terms[`${f}PubKeyHex`] ?? "")) return { ok: false, reason: `bad-${f}-pubkey` };
+    if (typeof terms[`${f}Handle`] !== "string" || !terms[`${f}Handle`]) return { ok: false, reason: `bad-${f}-handle` };
+  }
+  if (escrowUuaid && terms.escrow !== escrowUuaid) return { ok: false, reason: "not-my-offer" };
+  if (escrowHandle && terms.escrowHandle !== escrowHandle) return { ok: false, reason: "not-my-rail-handle" };
+  if (typeof terms.itemHash !== "string" || !HEX64.test(terms.itemHash)) return { ok: false, reason: "bad-itemHash" };
+  if (!Number.isInteger(terms.priceGons) || terms.priceGons < 1) return { ok: false, reason: "bad-price" };
+  if (!Number.isInteger(terms.sellerPayoutGons) || terms.sellerPayoutGons < 0) return { ok: false, reason: "bad-payout" };
+  let fp;
+  try {
+    fp = fingerprint(terms);
+  } catch (_e) {
+    // JCS throws on non-integers anywhere (e.g. a float expiresAt) — an
+    // object our own serializer can't canonicalize can never be a valid
+    // offer, but it must REJECT, not crash the caller's handler.
+    return { ok: false, reason: "bad-offerId" };
+  }
+  if (typeof terms.offerId !== "string" || terms.offerId !== fp) return { ok: false, reason: "bad-offerId" };
+  const pay = validatePayout(terms.priceGons, terms.sellerPayoutGons);
+  if (!pay.ok) return { ok: false, reason: pay.reason };
+  const exp = Date.parse(terms.expiresAt);
+  if (!Number.isFinite(exp) || exp <= now) return { ok: false, reason: "expired" };
+  const created = Date.parse(terms.createdAt);
+  if (!Number.isFinite(created) || exp - created > TERMS_MAX_LIFETIME_MS) return { ok: false, reason: "lifetime-too-long" };
+  return { ok: true, ...pay };
+}
+
+/** Canonical uint256 decimal string -> BigInt, or null. */
+function decStr(v) {
+  if (typeof v !== "string" || !DEC_STR.test(v)) return null;
+  const n = BigInt(v);
+  return n <= MAX_UINT256 ? n : null;
+}
+
+function validateTermsV2(terms, { now = Date.now(), escrowUuaid, escrowHandle } = {}) {
+  for (const f of ["escrow", "seller", "buyer"]) {
+    if (!isUuaid(terms[f])) return { ok: false, reason: `bad-${f}-uuaid` };
+    if (!HEX64.test(terms[`${f}PubKeyHex`] ?? "")) return { ok: false, reason: `bad-${f}-pubkey` };
+    if (typeof terms[`${f}Handle`] !== "string" || !terms[`${f}Handle`]) return { ok: false, reason: `bad-${f}-handle` };
+  }
+  if (escrowUuaid && terms.escrow !== escrowUuaid) return { ok: false, reason: "not-my-offer" };
+  if (!V2_RAILS.includes(terms.rail)) return { ok: false, reason: "bad-rail" };
+  if (terms.rail === "evm") {
+    if (!Number.isInteger(terms.chainId) || terms.chainId < 1) return { ok: false, reason: "bad-chainid" };
+    if (typeof terms.asset !== "string" || !EVM_ASSET.test(terms.asset)) return { ok: false, reason: "bad-asset" };
+    for (const f of ["escrow", "seller", "buyer"]) {
+      if (!EVM_ADDR.test(terms[`${f}Handle`])) return { ok: false, reason: `bad-${f}-handle` };
+    }
+  }
+  // rail addresses are case-insensitive — compare lowercased
+  if (escrowHandle && terms.escrowHandle.toLowerCase() !== escrowHandle.toLowerCase()) {
+    return { ok: false, reason: "not-my-rail-handle" };
+  }
+  if (typeof terms.itemHash !== "string" || !HEX64.test(terms.itemHash)) return { ok: false, reason: "bad-itemHash" };
+  const price = decStr(terms.price);
+  if (price === null || price < 1n) return { ok: false, reason: "bad-price" };
+  const payout = decStr(terms.sellerPayout);
+  if (payout === null) return { ok: false, reason: "bad-payout" };
+  // The whole fee model of v2: the rail's costs (gas) live OUTSIDE the signed
+  // numbers; the escrow's only economic invariant is payout <= price.
+  if (payout > price) return { ok: false, reason: "payout-exceeds-received" };
+  let fp;
+  try {
+    fp = fingerprint(terms);
+  } catch (_e) {
+    return { ok: false, reason: "bad-offerId" };
+  }
+  if (typeof terms.offerId !== "string" || terms.offerId !== fp) return { ok: false, reason: "bad-offerId" };
+  const exp = Date.parse(terms.expiresAt);
+  if (!Number.isFinite(exp) || exp <= now) return { ok: false, reason: "expired" };
+  const created = Date.parse(terms.createdAt);
+  if (!Number.isFinite(created) || exp - created > TERMS_MAX_LIFETIME_MS) return { ok: false, reason: "lifetime-too-long" };
+  return { ok: true, escrowReceived: terms.price, escrowSend: terms.sellerPayout, commission: (price - payout).toString() };
+}
+
+/**
+ * Uniform rail-facing view of any terms version — what the escrow service
+ * feeds the rail interface.  Amounts are decimal strings; escrowSend is the
+ * exact transfer the escrow must make (v1: post-fee smallestSendFor; v2: the
+ * signed sellerPayout — gas rides outside).
+ */
+export function railViewOfTerms(terms) {
+  if (terms.v === TERMS_VERSION_2) {
+    return {
+      v: 2, rail: terms.rail, chainId: terms.chainId, asset: terms.asset,
+      price: terms.price, sellerPayout: terms.sellerPayout, escrowSend: terms.sellerPayout,
+    };
+  }
+  const pay = validatePayout(terms.priceGons, terms.sellerPayoutGons);
+  return {
+    v: 1, rail: RAIL, chainId: null, asset: null,
+    price: String(terms.priceGons), sellerPayout: String(terms.sellerPayoutGons),
+    escrowSend: String(pay.escrowSend),
+  };
+}
+
+/**
+ * Completion receipt, signed by the escrow.  The buyer's receipt travels
+ * WITH the released key; the seller's with the payout transfer id.  Both
+ * are independently checkable by the end users (and any third party):
+ * verifyReceiptSig with the escrow's pubkey from the signed terms.
+ */
+export function makeReceipt(keychain, {
+  v = TERMS_VERSION,
+  offerId, role, escrow, buyer, seller,
+  itemHash, priceGons, sellerPayoutGons,
+  rail = RAIL, chainId = null, asset = null, price = null, sellerPayout = null,
+  payTxId, releaseTxId,
+  paySourceId = null, releaseSourceId = null,
+  deliveredAt = new Date().toISOString(),
+}) {
+  if (!["buyer", "seller"].includes(role)) throw new Error(`bad receipt role "${role}"`);
+  if (keychain._identity.uuaid !== escrow) throw new Error("receipt: escrow must be the signing identity");
+  const receipt = v === TERMS_VERSION_2
+    ? {
+        v: TERMS_VERSION_2,
+        offerId, role, escrow, buyer, seller,
+        itemHash, rail, chainId, asset, price, sellerPayout,
+        payTxId, releaseTxId,
+        paySourceId, releaseSourceId,
+        deliveredAt,
+      }
+    : {
+        v: TERMS_VERSION,
+        offerId, role, escrow, buyer, seller,
+        itemHash, priceGons, sellerPayoutGons,
+        payTxId, releaseTxId,
+        paySourceId, releaseSourceId,
+        rail: RAIL, deliveredAt,
+      };
+  receipt.sig = keychain.sign(Buffer.from(jcs(receipt), "utf-8")).toString("hex");
+  return receipt;
+}
+
+export function verifyReceiptSig(publicKeyHex, receipt) {
+  try {
+    const { sig, ...rest } = receipt;
+    if (![TERMS_VERSION, TERMS_VERSION_2].includes(receipt.v) || typeof sig !== "string") return false;
+    return Keychain.verifyDetached(publicKeyHex, Buffer.from(jcs(rest), "utf-8"), Buffer.from(sig, "hex"));
+  } catch (_e) {
+    return false;
+  }
+}

package/src/escrow/token-registry.mjs

@@ -0,0 +1,231 @@
+/**
+ * Token / chain registry — the escrow's asset allowlist, fed by an OPEN
+ * APPLICATION PROCESS.
+ *
+ * Any EVM-chain or token developer may APPLY to have their chain / ERC-20
+ * included; nothing enters the allowlist without an explicit reviewer
+ * decision.  The escrow enforces the registry FAIL-CLOSED at offer time:
+ * when a registry is wired, v2 terms naming an unregistered chain or token
+ * are rejected before any state is created ("chain-not-registered" /
+ * "token-not-registered").  Without a registry (tests, private bilateral
+ * deployments) behavior is unchanged.
+ *
+ * Why an allowlist at all: exact-amount attestation assumes STANDARD
+ * transfer semantics.  Fee-on-transfer, rebasing, or hook-bearing tokens
+ * break "receipt shows exactly `price`" in ways no static check can catch —
+ * inclusion is a human vetting decision, and the reviewer's attestations are
+ * RECORDED here, not verified here.
+ *
+ * On disk (one directory):
+ *   registry.json          — the approved set {chains, tokens}, provenance on
+ *                            every entry (applicationId, reviewer, approvedAt)
+ *   applications/<id>.json — every application ever filed, decision in place
+ *
+ * Application ids are content-derived — sha256(jcs(submission))[:16] — so a
+ * duplicate filing is the SAME application (idempotent, spam-resistant), and
+ * any party can recompute the id from the submitted fields.
+ *
+ * What is checked mechanically at filing time (offline-checkable facts only):
+ * shapes, ranges, EIP-55 checksum when the address is mixed-case, duplicates
+ * against the registry and pending queue.  What is NOT checked here: source
+ * verification, transfer semantics, liquidity — the reviewer attests those.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { jcs } from "../identity/jcs.mjs";
+import { ADDRESS_RE, parseAsset } from "./rails/evm-rail.mjs";
+
+const SYMBOL_RE = /^[A-Za-z0-9$._-]{1,20}$/;
+const NAME_RE = /^[\x20-\x7E]{1,80}$/; // printable ASCII, bounded
+const URL_RE = /^https?:\/\/[^\s]{1,300}$/;
+
+/** EIP-55 checksum form of a 0x address (also the canonical display form). */
+export function toChecksumAddress(addr) {
+  const hex = addr.slice(2).toLowerCase();
+  const hash = Buffer.from(keccak_256(Buffer.from(hex, "ascii"))).toString("hex");
+  let out = "0x";
+  for (let i = 0; i < 40; i++) out += parseInt(hash[i], 16) >= 8 ? hex[i].toUpperCase() : hex[i];
+  return out;
+}
+
+/** A mixed-case address must BE its own EIP-55 form; all-lower/all-upper pass. */
+function checksumOk(addr) {
+  const body = addr.slice(2);
+  if (body === body.toLowerCase() || body === body.toUpperCase()) return true;
+  return addr === toChecksumAddress(addr);
+}
+
+function fingerprintApplication(sub) {
+  return createHash("sha256").update(jcs(sub)).digest("hex").slice(0, 16);
+}
+
+const tokenKey = (chainId, address) => `${chainId}:${address.toLowerCase()}`;
+
+/**
+ * Validate an application submission (mechanical checks only).
+ * kind "chain":  { kind, chainId, name, nativeSymbol, nativeDecimals,
+ *                  rpcUrl?, explorerUrl?, applicant, contact?, evidence? }
+ * kind "token":  { kind, chainId, address, symbol, name, decimals,
+ *                  applicant, contact?, evidence? }
+ * Returns { ok } or { ok:false, reason }.
+ */
+export function validateApplication(sub) {
+  if (!sub || typeof sub !== "object") return { ok: false, reason: "bad-application" };
+  if (sub.kind !== "chain" && sub.kind !== "token") return { ok: false, reason: "bad-kind" };
+  if (!Number.isInteger(sub.chainId) || sub.chainId < 1) return { ok: false, reason: "bad-chainid" };
+  if (typeof sub.applicant !== "string" || !sub.applicant.trim()) return { ok: false, reason: "bad-applicant" };
+  if (sub.contact != null && (typeof sub.contact !== "string" || sub.contact.length > 200)) return { ok: false, reason: "bad-contact" };
+  if (sub.evidence != null) {
+    if (!Array.isArray(sub.evidence) || sub.evidence.length > 10 || !sub.evidence.every((u) => typeof u === "string" && URL_RE.test(u))) {
+      return { ok: false, reason: "bad-evidence" };
+    }
+  }
+  if (typeof sub.name !== "string" || !NAME_RE.test(sub.name)) return { ok: false, reason: "bad-name" };
+  if (sub.kind === "chain") {
+    if (typeof sub.nativeSymbol !== "string" || !SYMBOL_RE.test(sub.nativeSymbol)) return { ok: false, reason: "bad-symbol" };
+    if (!Number.isInteger(sub.nativeDecimals) || sub.nativeDecimals < 0 || sub.nativeDecimals > 36) return { ok: false, reason: "bad-decimals" };
+    for (const f of ["rpcUrl", "explorerUrl"]) {
+      if (sub[f] != null && !(typeof sub[f] === "string" && URL_RE.test(sub[f]))) return { ok: false, reason: `bad-${f}` };
+    }
+  } else {
+    if (typeof sub.address !== "string" || !ADDRESS_RE.test(sub.address)) return { ok: false, reason: "bad-address" };
+    if (!checksumOk(sub.address)) return { ok: false, reason: "bad-checksum" };
+    if (typeof sub.symbol !== "string" || !SYMBOL_RE.test(sub.symbol)) return { ok: false, reason: "bad-symbol" };
+    if (!Number.isInteger(sub.decimals) || sub.decimals < 0 || sub.decimals > 36) return { ok: false, reason: "bad-decimals" };
+  }
+  return { ok: true };
+}
+
+export class TokenRegistry {
+  /** @param dir directory holding registry.json + applications/ */
+  constructor({ dir }) {
+    if (!dir) throw new Error("TokenRegistry: dir required");
+    this.dir = dir;
+    this.appsDir = join(dir, "applications");
+    mkdirSync(this.appsDir, { recursive: true });
+    this.registryPath = join(dir, "registry.json");
+    this._load();
+  }
+
+  _load() {
+    let data = null;
+    try {
+      data = JSON.parse(readFileSync(this.registryPath, "utf-8"));
+    } catch (_e) { /* fresh registry */ }
+    this.chains = data?.chains ?? {};   // "<chainId>" -> entry
+    this.tokens = data?.tokens ?? {};   // "<chainId>:0x<lower>" -> entry
+  }
+
+  _saveRegistry() {
+    writeFileSync(this.registryPath, JSON.stringify({ v: 1, chains: this.chains, tokens: this.tokens }, null, 2) + "\n");
+  }
+
+  _appPath(id) { return join(this.appsDir, `${id}.json`); }
+
+  _readApp(id) {
+    try {
+      return JSON.parse(readFileSync(this._appPath(id), "utf-8"));
+    } catch (_e) { return null; }
+  }
+
+  /* ------------------------------------------------ enforcement -------- */
+
+  isChainApproved(chainId) { return Boolean(this.chains[String(chainId)]); }
+
+  isAssetApproved(chainId, asset) {
+    if (!this.isChainApproved(chainId)) return false;
+    let a;
+    try { a = parseAsset(asset); } catch (_e) { return false; }
+    if (a.kind === "native") return true;
+    return Boolean(this.tokens[tokenKey(chainId, a.token)]);
+  }
+
+  /**
+   * Escrow-side policy gate for a validated terms object.  v1 terms (the
+   * zilligon rail) are out of this registry's scope and always pass.
+   */
+  checkTerms(terms) {
+    if (terms?.v !== 2) return { ok: true };
+    if (!this.isChainApproved(terms.chainId)) {
+      return { ok: false, reason: "chain-not-registered", message: `chain ${terms.chainId} is not in this escrow's registry (apply via token-registry)` };
+    }
+    if (!this.isAssetApproved(terms.chainId, terms.asset)) {
+      return { ok: false, reason: "token-not-registered", message: `asset ${terms.asset} is not registered on chain ${terms.chainId} (apply via token-registry)` };
+    }
+    return { ok: true };
+  }
+
+  /* ------------------------------------------------ applications ------- */
+
+  /**
+   * File an application.  Idempotent: identical submissions share one id.
+   * Returns { ok, id, status } or { ok:false, reason }.
+   */
+  submitApplication(sub) {
+    const v = validateApplication(sub);
+    if (!v.ok) return v;
+    if (sub.kind === "chain" && this.isChainApproved(sub.chainId)) return { ok: false, reason: "already-registered" };
+    if (sub.kind === "token" && this.tokens[tokenKey(sub.chainId, sub.address)]) return { ok: false, reason: "already-registered" };
+    const id = fingerprintApplication(sub);
+    const existing = this._readApp(id);
+    if (existing) return { ok: true, id, status: existing.status, duplicate: true };
+    const app = { id, status: "pending", submittedAt: new Date().toISOString(), submission: sub };
+    writeFileSync(this._appPath(id), JSON.stringify(app, null, 2) + "\n");
+    return { ok: true, id, status: "pending" };
+  }
+
+  /** All applications, newest first; optionally filtered by status. */
+  listApplications(status = null) {
+    const out = [];
+    for (const f of readdirSync(this.appsDir)) {
+      if (!f.endsWith(".json")) continue;
+      const app = this._readApp(f.slice(0, -5));
+      if (app && (!status || app.status === status)) out.push(app);
+    }
+    return out.sort((a, b) => (b.submittedAt ?? "").localeCompare(a.submittedAt ?? ""));
+  }
+
+  getApplication(id) { return this._readApp(id); }
+
+  /**
+   * Decide a pending application.  Approval writes the registry entry with
+   * full provenance; the decision is annotated into the application file in
+   * place (never deleted).  A token approval requires its chain approved
+   * first — the ordering the enforcement gate assumes.
+   * Returns { ok, id, status } or { ok:false, reason }.
+   */
+  decideApplication(id, { approve, reviewer, notes = "" }) {
+    if (typeof reviewer !== "string" || !reviewer.trim()) return { ok: false, reason: "bad-reviewer" };
+    const app = this._readApp(id);
+    if (!app) return { ok: false, reason: "unknown-application" };
+    if (app.status !== "pending") return { ok: false, reason: "already-decided", status: app.status };
+    const sub = app.submission;
+    if (approve && sub.kind === "token" && !this.isChainApproved(sub.chainId)) {
+      return { ok: false, reason: "chain-not-registered", message: "approve the chain application first" };
+    }
+    app.status = approve ? "approved" : "rejected";
+    app.decidedAt = new Date().toISOString();
+    app.reviewer = reviewer;
+    if (notes) app.notes = notes;
+    writeFileSync(this._appPath(id), JSON.stringify(app, null, 2) + "\n");
+    if (approve) {
+      const provenance = { applicationId: id, reviewer, approvedAt: app.decidedAt };
+      if (sub.kind === "chain") {
+        this.chains[String(sub.chainId)] = {
+          name: sub.name, nativeSymbol: sub.nativeSymbol, nativeDecimals: sub.nativeDecimals,
+          ...(sub.rpcUrl ? { rpcUrl: sub.rpcUrl } : {}), ...(sub.explorerUrl ? { explorerUrl: sub.explorerUrl } : {}),
+          ...provenance,
+        };
+      } else {
+        this.tokens[tokenKey(sub.chainId, sub.address)] = {
+          address: toChecksumAddress(sub.address), symbol: sub.symbol, name: sub.name, decimals: sub.decimals,
+          ...provenance,
+        };
+      }
+      this._saveRegistry();
+    }
+    return { ok: true, id, status: app.status };
+  }
+}