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

package/bin/pillar-escrow.mjs

@@ -0,0 +1,674 @@
+#!/usr/bin/env node
+/**
+ * pillar-escrow — ZGN token exchange WITHOUT crypto exchanges: a blind
+ * escrow on the UUAID pillar + Zilligon ZGN rail.
+ *
+ * Roles (three ordinary identities; the escrow holds only a 32-byte key):
+ *
+ *   seller ──offer(signed terms + K)──▶ escrow
+ *   seller ◀─────────offer-ack───────── escrow
+ *   seller ──deliverable(ciphertext)──▶ buyer      (escrow never sees it)
+ *   buyer ───accept(signed terms)─────▶ escrow
+ *   buyer ◀────────accept-ack────────── escrow
+ *   buyer ──rail transfer of price───▶ escrowHandle (Zilligon ZGN rail)
+ *   buyer ─────paid {offerId,txId}───▶ escrow
+ *   escrow attests from its own wallet, then:
+ *     rail transfer of payout ─▶ sellerHandle
+ *     key {K, receipt} ────────▶ buyer        (buyer opens box, checks hash)
+ *     receipt ─────────────────▶ seller
+ *
+ * Subcommands:
+ *   init        create a home identity (+ zilligon.json template)
+ *   run-escrow  run the escrow service (journal-first, crash-recoverable)
+ *   sell        one-shot seller flow (needs buyer+escrow identities, no rail creds)
+ *   buy         one-shot buyer flow (pays on the rail, then opens the box)
+ *
+ * Carrier-only by default (outbound HTTPS only).  Secrets: the Zilligon
+ * apiKey is read from a keyfile and NEVER printed.
+ *
+ *   pillar-escrow init --home ~/.pillar-escrow
+ *   pillar-escrow run-escrow --home ~/.pillar-escrow --carrier https://carrier.example
+ *   pillar-escrow sell --home ~/.pillar-seller --file deliverable.bin \
+ *     --buyer uuaid:... --buyer-pubkey <hex> --buyer-handle @b \
+ *     --escrow uuaid:... --escrow-pubkey <hex> --escrow-handle @e \
+ *     --seller-handle @s --price 100 --fee-allocation split \
+ *     --carrier https://carrier.example
+ *   pillar-escrow buy --home ~/.pillar-buyer --terms terms.json \
+ *     --zilligon-keyfile ~/.pillar-buyer/zilligon.json \
+ *     --out received.bin --carrier https://carrier.example
+ *
+ * The rail's tip fee is OUTSIDE the two-party agreement: sell derives the
+ * payout ONLY from an explicit choice — --fee-allocation seller|buyer|split
+ * (who absorbs the fee: the seller, the buyer, or 50/50) or --payout N (the
+ * parties' own number; a "mutual" agreement).  No default is ever derived.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { argv, exit } from "node:process";
+import { randomBytes } from "node:crypto";
+import { Keychain } from "../src/identity/keychain.mjs";
+import { Pillar } from "../src/pillar.mjs";
+import { ZilligonClient, txIdOf } from "../src/escrow/zilligon.mjs";
+import { EscrowService } from "../src/escrow/escrow-service.mjs";
+import { EvmRail } from "../src/escrow/rails/evm-rail.mjs";
+import { RailSet } from "../src/escrow/rails/index.mjs";
+import { TokenRegistry } from "../src/escrow/token-registry.mjs";
+import { TransferVerifier } from "../src/escrow/verify.mjs";
+import { verifyReceipt, quorumReport, verifyEnvelope, envelopeSha256, RECEIPT_KIND, VDA_V } from "../src/vda/core.mjs";
+import { VerifierDirectory } from "../src/vda/directory.mjs";
+import { makeDeliveryAck, attestDataDelivery, contentHashOf } from "../src/vda/instruments.mjs";
+import {
+  makeTerms, signTerms, verifyReceiptSig, validatePayout, fingerprint, allocateFee,
+} from "../src/escrow/terms.mjs";
+import { sealBox, openBox, sha256Hex } from "../src/escrow/box.mjs";
+
+const MAX_CONTENT_BYTES = 64 * 1024; // alpha cap
+const HEX64 = /^[0-9a-f]{64}$/i;
+const DEFAULT_OFFER_TTL_MS = 24 * 3600_000;
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, ...rest] = a.slice(2).split("=");
+      args[k] = rest.length ? rest.join("=") : (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true);
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function homePath(args) {
+  return args.home || process.env.PILLAR_HOME || join(homedir(), ".pillar");
+}
+
+function loadKeychain(home, args) {
+  const kcPath = join(home, "kc.json");
+  if (!existsSync(kcPath)) {
+    console.error(`no pillar identity at ${home}. run: pillar-escrow init --home ${home}`);
+    exit(2);
+  }
+  const kc = new Keychain(kcPath);
+  kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  return kc;
+}
+
+function carriersOf(args, cfg) {
+  return args.carrier
+    ? [args.carrier]
+    : (process.env.PILLAR_CARRIERS ? process.env.PILLAR_CARRIERS.split(",") : (cfg.carriers ?? []));
+}
+
+function requireCarriers(carriers) {
+  if (!carriers.length) {
+    console.error("needs at least one carrier: --carrier URL, PILLAR_CARRIERS, or carriers[] in config.json");
+    exit(2);
+  }
+}
+
+async function makePillar(home, kc, carriers) {
+  const p = new Pillar({
+    keychain: kc,
+    mailboxPath: join(home, "mailbox.db"),
+    carriers,
+    enableLibp2p: false,
+  });
+  await p.start();
+  return p;
+}
+
+function readZilligonKeyfile(path) {
+  if (!existsSync(path)) {
+    console.error(`zilligon keyfile not found: ${path} (run init — it writes a template; put the apiKey inside)`);
+    exit(2);
+  }
+  const f = JSON.parse(readFileSync(path, "utf-8"));
+  if (!f.apiKey) {
+    console.error(`zilligon keyfile ${path} has no apiKey field`);
+    exit(2);
+  }
+  return f; // { apiKey, handle? } — values never printed
+}
+
+const offerIdOf = (env) => env.payload?.offerId ?? env.payload?.receipt?.offerId;
+
+/**
+ * Wait for any of the given kinds carrying a matching offerId, polling the
+ * carrier inbox.  Racing the success kind against "escrow.error" means a
+ * failure surfaces as soon as it arrives instead of after the full timeout.
+ * Returns {kind, env} or null on timeout.
+ */
+function waiter(pillar) {
+  const q = new Map(); // kind -> [env]
+  pillar.onEnvelope((env) => {
+    if (!q.has(env.kind)) q.set(env.kind, []);
+    q.get(env.kind).push(env);
+  });
+  return async function waitEither(offerId, kinds, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      for (const kind of kinds) {
+        const hit = (q.get(kind) ?? []).find((env) => offerIdOf(env) === offerId);
+        if (hit) return { kind, env: hit };
+      }
+      if (Date.now() > deadline) return null;
+      await pillar.drainCarrierInbox();
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+  };
+}
+
+const die = (msg) => { console.error(msg); exit(2); };
+const say = (msg) => console.error(`[pillar-escrow] ${msg}`); // stderr: progress; stdout: machine results
+const escrowErr = (r) => `escrow error: ${r.env.payload.code} — ${r.env.payload.message}`;
+
+/* ------------------------------------------------ init ------------------- */
+
+async function cmdInit(args) {
+  const home = homePath(args);
+  const kcPath = join(home, "kc.json");
+  if (existsSync(kcPath)) die(`identity already exists at ${kcPath}`);
+  mkdirSync(home, { recursive: true });
+  const kc = new Keychain(kcPath);
+  kc.save(Keychain.generate(), { passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  const zf = join(home, "zilligon.json");
+  if (!existsSync(zf)) {
+    writeFileSync(zf, JSON.stringify({ apiKey: "", handle: "" }, null, 2) + "\n", { mode: 0o600 });
+  }
+  const cfg = join(home, "config.json");
+  if (!existsSync(cfg)) writeFileSync(cfg, JSON.stringify({ carriers: [] }, null, 2) + "\n");
+  console.log(JSON.stringify({
+    home,
+    uuaid: kc._identity.uuaid,
+    publicKeyHex: kc._identity.publicKeyHex,
+    next: [
+      "register a handle on zilligon.com if you don't have one",
+      `put {apiKey, handle} into ${zf} (chmod 600)`,
+      "for a carrier: pillar-escrow run-escrow --carrier <url>",
+    ],
+  }, null, 2));
+}
+
+/* ------------------------------------------------ run-escrow ------------- */
+
+async function cmdRunEscrow(args) {
+  const home = homePath(args);
+  const cfg = existsSync(join(home, "config.json")) ? JSON.parse(readFileSync(join(home, "config.json"), "utf-8")) : {};
+  const kc = loadKeychain(home, args);
+  const carriers = carriersOf(args, cfg);
+  requireCarriers(carriers);
+  const zf = readZilligonKeyfile(args["zilligon-keyfile"] ?? join(home, "zilligon.json"));
+  const railHandle = args["zilligon-handle"] ?? zf.handle ?? cfg.zilligon?.handle;
+  if (!railHandle) die("escrow needs a Zilligon handle (--zilligon-handle or handle in the keyfile)");
+  const zilligon = new ZilligonClient({ apiKey: zf.apiKey, handle: railHandle, baseUrl: args["zilligon-base"] ?? "https://zilligon.com" });
+
+  // Optional EVM rail (v2 terms): --evm-rpc + --evm-chain + --evm-address
+  // (or cfg.evm / PILLAR_EVM_RPC, PILLAR_EVM_CHAIN, PILLAR_EVM_ADDRESS).
+  // The signing key is NEVER a flag or a config value: EvmRail reads
+  // PILLAR_EVM_KEY at signing time (or a custom provider in library use).
+  const rails = [];
+  const evmRpc = args["evm-rpc"] ?? process.env.PILLAR_EVM_RPC ?? cfg.evm?.rpcUrl;
+  if (evmRpc) {
+    const evmChain = Number(args["evm-chain"] ?? process.env.PILLAR_EVM_CHAIN ?? cfg.evm?.chainId);
+    const evmAddress = args["evm-address"] ?? process.env.PILLAR_EVM_ADDRESS ?? cfg.evm?.address;
+    if (!Number.isInteger(evmChain) || !evmAddress) die("evm rail needs --evm-chain and --evm-address alongside --evm-rpc");
+    rails.push(new EvmRail({
+      rpcUrl: evmRpc, chainId: evmChain, handle: evmAddress,
+      confirmations: Number(args["evm-confirmations"] ?? cfg.evm?.confirmations ?? 15),
+    }));
+  }
+
+  // Asset allowlist: when the EVM rail is on, the token registry is wired by
+  // DEFAULT (fail closed — unregistered chains/tokens are rejected at offer
+  // time).  --no-token-registry opts a private bilateral escrow out.
+  let tokenRegistry = null;
+  if (rails.length && !args["no-token-registry"]) {
+    tokenRegistry = new TokenRegistry({ dir: registryDir(args, home, cfg) });
+  }
+
+  const pillar = await makePillar(home, kc, carriers);
+  const service = new EscrowService({
+    keychain: kc, pillar, zilligon, rails,
+    journalPath: join(home, "escrow-journal.jsonl"),
+    railHandle, tokenRegistry,
+  });
+  service.start({ reconcileMs: Number(args["reconcile-ms"] ?? 30_000) });
+  pillar.startCarrierPolling({ waitS: Number(args["poll-wait"] ?? 20) });
+  console.error(`escrow up: ${kc._identity.uuaid} | rail @${railHandle}${rails.length ? ` + ${rails.map((r) => r.railKey).join(", ")}` : ""} | journal ${home}/escrow-journal.jsonl`);
+  console.error(`carriers: ${carriers.join(", ")}`);
+}
+
+/* ------------------------------------------------ sell ------------------- */
+
+async function cmdSell(args) {
+  const home = homePath(args);
+  const cfg = existsSync(join(home, "config.json")) ? JSON.parse(readFileSync(join(home, "config.json"), "utf-8")) : {};
+  const kc = loadKeychain(home, args);
+  const carriers = carriersOf(args, cfg);
+  requireCarriers(carriers);
+  const file = args.file;
+  const price = Number(args.price);
+  if (!file || !existsSync(file)) die("sell needs --file <path>");
+  if (!Number.isInteger(price) || price < 1) die("--price must be an integer >= 1 Gons");
+  if (!args["seller-handle"]) die("sell needs --seller-handle (your Zilligon @handle — the escrow pays it)");
+  for (const k of ["buyer", "escrow"]) {
+    if (!args[k] || !args[`${k}-pubkey`] || !args[`${k}-handle`]) die(`sell needs --${k}, --${k}-pubkey, --${k}-handle`);
+    if (!HEX64.test(args[`${k}-pubkey`])) die(`--${k}-pubkey must be 64 hex chars`);
+  }
+  const buf = readFileSync(file);
+  if (buf.length > MAX_CONTENT_BYTES) die(`file larger than ${MAX_CONTENT_BYTES} bytes (alpha cap)`);
+  // Fee allocation is the PARTIES' deal, never the escrow's: an explicit
+  // --payout (mutual agreement) or an explicit --fee-allocation — no default.
+  let finalPrice = price;
+  let sellerPayout;
+  const allocation = args["fee-allocation"];
+  if (args.payout !== undefined) {
+    if (allocation !== undefined) die("--payout and --fee-allocation are mutually exclusive");
+    sellerPayout = Number(args.payout);
+    if (!Number.isInteger(sellerPayout) || sellerPayout < 0) die("--payout must be an integer >= 0");
+  } else if (allocation !== undefined) {
+    if (!["seller", "buyer", "split", "mutual"].includes(allocation)) {
+      die(`--fee-allocation must be seller|buyer|split|mutual, got "${allocation}"`);
+    }
+    const alloc = allocateFee(price, allocation);
+    if (alloc === null) die('--fee-allocation mutual requires explicit --payout (the parties agree the number themselves)');
+    finalPrice = alloc.priceGons;
+    sellerPayout = alloc.sellerPayoutGons;
+  } else {
+    die("sell needs --fee-allocation seller|buyer|split (who absorbs the rail tip fee) or an explicit --payout (a mutual agreement) — no default is derived");
+  }
+  const pay = validatePayout(finalPrice, sellerPayout);
+  if (!pay.ok) die(`infeasible payout: ${pay.reason} (escrow receives ${pay.escrowReceived}, would send ${pay.escrowSend})`);
+
+  const K = randomBytes(32);
+  const box = sealBox(K, buf);
+  const itemHash = sha256Hex(buf);
+  const terms = makeTerms({
+    escrow: args.escrow, escrowPubKeyHex: args["escrow-pubkey"], escrowHandle: args["escrow-handle"],
+    seller: kc._identity.uuaid, sellerPubKeyHex: kc._identity.publicKeyHex, sellerHandle: args["seller-handle"],
+    buyer: args.buyer, buyerPubKeyHex: args["buyer-pubkey"], buyerHandle: args["buyer-handle"],
+    itemHash, priceGons: finalPrice, sellerPayoutGons: sellerPayout,
+    expiresAt: args.expires ?? new Date(Date.now() + DEFAULT_OFFER_TTL_MS).toISOString(),
+  });
+  const sellerSig = signTerms(kc, terms);
+  const pillar = await makePillar(home, kc, carriers);
+  const waitEither = waiter(pillar);
+  const send = async (recipient, pubkey, kind, payload) => pillar.send({ recipient, recipientPublicKey: pubkey, kind, payload });
+
+  say(`offer ${terms.offerId} — ${buf.length} bytes, price ${finalPrice} Gons`);
+  await send(terms.escrow, terms.escrowPubKeyHex, "escrow.offer", { terms, sellerSig, contentKeyHex: K.toString("hex") });
+  const ack = await waitEither(terms.offerId, ["escrow.offer-ack", "escrow.error"], 90_000);
+  if (!ack) die(`no escrow ack within 90s (escrow ${terms.escrow} unreachable?)`);
+  if (ack.kind === "escrow.error") die(escrowErr(ack));
+  say("escrow accepted the offer — sending deliverable to buyer");
+  await send(terms.buyer, terms.buyerPubKeyHex, "escrow.deliverable", { offerId: terms.offerId, box, itemHash, terms });
+
+  const done = await waitEither(terms.offerId, ["escrow.receipt", "escrow.error"], 10 * 60_000);
+  if (!done) die("no receipt within 10 min — buyer never completed (offer still open; re-run to re-offer)");
+  if (done.kind === "escrow.error") die(escrowErr(done));
+  const { receipt } = done.env.payload;
+  if (!verifyReceiptSig(terms.escrowPubKeyHex, receipt)) die("RECEIPT SIGNATURE INVALID — do not trust this completion");
+  const out = args["receipt-out"] ?? join(home, "sell-receipts", `${terms.offerId}.json`);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, JSON.stringify(receipt, null, 2) + "\n");
+  console.log(JSON.stringify({
+    ok: true, offerId: terms.offerId, role: "seller",
+    priceGons: finalPrice, payoutGons: sellerPayout, feeAllocation: allocation ?? "mutual",
+    receiptPath: out,
+  }, null, 2));
+}
+
+/* ------------------------------------------------ buy -------------------- */
+
+async function cmdBuy(args) {
+  const home = homePath(args);
+  const cfg = existsSync(join(home, "config.json")) ? JSON.parse(readFileSync(join(home, "config.json"), "utf-8")) : {};
+  const kc = loadKeychain(home, args);
+  const carriers = carriersOf(args, cfg);
+  requireCarriers(carriers);
+  const termsPath = args.terms;
+  const out = args.out;
+  if (!termsPath || !existsSync(termsPath)) die("buy needs --terms <terms.json> (from the seller, out of band)");
+  if (!out) die("buy needs --out <file> for the decrypted deliverable");
+  const terms = JSON.parse(readFileSync(termsPath, "utf-8"));
+  if (terms.offerId !== fingerprint(terms)) die("terms tampered: offerId does not match contents");
+  if (terms.buyer !== kc._identity.uuaid) die(`terms are for buyer ${terms.buyer}, this identity is ${kc._identity.uuaid}`);
+  if (terms.buyerPubKeyHex !== kc._identity.publicKeyHex) die("terms.buyerPubKeyHex does not match this identity's key — escrow would reject the accept");
+  if (Date.now() > Date.parse(terms.expiresAt)) die("offer expired");
+  const zf = readZilligonKeyfile(args["zilligon-keyfile"] ?? join(home, "zilligon.json"));
+  if (!zf.handle || zf.handle !== terms.buyerHandle) die(`keyfile handle ${zf.handle} does not match terms.buyerHandle ${terms.buyerHandle}`);
+
+  const pillar = await makePillar(home, kc, carriers);
+  const waitEither = waiter(pillar);
+  const send = async (recipient, pubkey, kind, payload) => pillar.send({ recipient, recipientPublicKey: pubkey, kind, payload });
+
+  const buyerSig = signTerms(kc, terms);
+  say(`accepting offer ${terms.offerId} (price ${terms.priceGons} Gons)`);
+  await send(terms.escrow, terms.escrowPubKeyHex, "escrow.accept", { offerId: terms.offerId, buyerSig });
+  const ack = await waitEither(terms.offerId, ["escrow.accept-ack", "escrow.error"], 90_000);
+  if (!ack) die("no accept-ack within 90s");
+  if (ack.kind === "escrow.error") die(escrowErr(ack));
+  say("accepted — waiting for the deliverable box");
+  const dv = await waitEither(terms.offerId, ["escrow.deliverable", "escrow.error"], 90_000);
+  if (!dv) die("no deliverable within 90s (seller gone?)");
+  if (dv.kind === "escrow.error") die(escrowErr(dv));
+
+  // Money moves here — on the rail, directly to the escrow's handle.
+  const zilligon = new ZilligonClient({
+    apiKey: zf.apiKey, handle: terms.buyerHandle, baseUrl: args["zilligon-base"] ?? "https://zilligon.com",
+  });
+  say(`paying ${terms.priceGons} Gons to @${terms.escrowHandle} on the Zilligon rail`);
+  const res = await zilligon.transfer({
+    recipientHandle: terms.escrowHandle, amount: terms.priceGons, message: `escrow ${terms.offerId.slice(0, 8)}`,
+  });
+  const txId = txIdOf(res?.data?.transaction ?? res?.data ?? {});
+  say(`rail transfer done (tx ${txId ?? "unknown-id"}) — claiming payment with the escrow`);
+  // The transfer response's transactionId IS both wallet rows' sourceId
+  // (verified live 2026-08-21) — claim it so the escrow can counterparty-bind.
+  await send(terms.escrow, terms.escrowPubKeyHex, "escrow.paid", {
+    offerId: terms.offerId, txId, ...(txId ? { sourceId: txId } : {}),
+  });
+
+  const keyEnv = await waitEither(terms.offerId, ["escrow.key", "escrow.error"], 10 * 60_000);
+  if (!keyEnv) die("no key within 10 min (escrow could not attest the payment?)");
+  if (keyEnv.kind === "escrow.error") die(escrowErr(keyEnv));
+  const { contentKeyHex, receipt } = keyEnv.env.payload;
+  if (!verifyReceiptSig(terms.escrowPubKeyHex, receipt)) die("RECEIPT SIGNATURE INVALID — do not trust this completion");
+  const plain = openBox(Buffer.from(contentKeyHex, "hex"), dv.env.payload.box);
+  if (sha256Hex(plain) !== terms.itemHash) die("deliverable hash mismatch — box does not match the signed terms");
+  writeFileSync(out, plain);
+  const receiptOut = args["receipt-out"] ?? join(home, "buy-receipts", `${terms.offerId}.json`);
+  mkdirSync(dirname(receiptOut), { recursive: true });
+  writeFileSync(receiptOut, JSON.stringify(receipt, null, 2) + "\n");
+  console.log(JSON.stringify({ ok: true, offerId: terms.offerId, role: "buyer", priceGons: terms.priceGons, file: out, receiptPath: receiptOut }, null, 2));
+}
+
+/* ------------------------------------------------ token registry --------- */
+
+function registryDir(args, home, cfg = {}) {
+  return args["token-registry"] ?? cfg.tokenRegistry ?? join(home, "token-registry");
+}
+
+function openRegistry(args) {
+  const home = homePath(args);
+  const cfg = existsSync(join(home, "config.json")) ? JSON.parse(readFileSync(join(home, "config.json"), "utf-8")) : {};
+  return new TokenRegistry({ dir: registryDir(args, home, cfg) });
+}
+
+/**
+ * File a chain or token inclusion application.  Open to any developer — the
+ * application is untrusted input by design; the reviewer decision is the gate.
+ */
+async function cmdTokenApply(args) {
+  const reg = openRegistry(args);
+  const kind = args._[0] === "chain-apply" ? "chain" : "token";
+  const sub = { kind, chainId: Number(args.chain), name: args.name, applicant: args.applicant };
+  if (args.contact) sub.contact = args.contact;
+  if (args.evidence) sub.evidence = String(args.evidence).split(",").map((s) => s.trim()).filter(Boolean);
+  if (kind === "chain") {
+    sub.nativeSymbol = args["native-symbol"];
+    sub.nativeDecimals = Number(args["native-decimals"] ?? 18);
+    if (args.rpc) sub.rpcUrl = args.rpc;
+    if (args.explorer) sub.explorerUrl = args.explorer;
+  } else {
+    sub.address = args.address;
+    sub.symbol = args.symbol;
+    sub.decimals = Number(args.decimals ?? 18);
+  }
+  const r = reg.submitApplication(sub);
+  if (!r.ok) die(`application rejected: ${r.reason}`);
+  console.log(JSON.stringify(r, null, 2));
+}
+
+async function cmdTokenList(args) {
+  const reg = openRegistry(args);
+  const status = typeof args.status === "string" ? args.status : null;
+  console.log(JSON.stringify({
+    chains: reg.chains, tokens: reg.tokens,
+    applications: reg.listApplications(status).map(({ id, status: s, submittedAt, reviewer, submission }) => ({
+      id, status: s, submittedAt, ...(reviewer ? { reviewer } : {}),
+      kind: submission.kind, chainId: submission.chainId,
+      ...(submission.address ? { address: submission.address } : {}),
+      ...(submission.symbol ? { symbol: submission.symbol } : {}),
+      name: submission.name, applicant: submission.applicant,
+    })),
+  }, null, 2));
+}
+
+/** Operator-side decision.  Approval writes the allowlist entry with provenance. */
+async function cmdTokenReview(args) {
+  const reg = openRegistry(args);
+  const id = args._[1];
+  if (!id) die("token-review needs an application id (see token-list)");
+  const approve = Boolean(args.approve);
+  if (!approve && !args.reject) die("token-review needs --approve or --reject");
+  const reviewer = typeof args.reviewer === "string" ? args.reviewer : null;
+  if (!reviewer) die("token-review needs --reviewer <name>");
+  const r = reg.decideApplication(id, { approve, reviewer, notes: typeof args.notes === "string" ? args.notes : "" });
+  if (!r.ok) die(`review failed: ${r.reason}${r.message ? ` — ${r.message}` : ""}`);
+  console.log(JSON.stringify(r, null, 2));
+}
+
+/* ------------------------------------------------ verify ----------------- */
+
+/**
+ * Standalone transfer verification: attest ANY (from, to, amount, asset)
+ * transfer from the chain's own record and emit a signed, content-addressed
+ * attestation any holder can check offline (verify-attestation).  No carrier,
+ * no escrow, no rail credentials — read-only RPC + the local identity.
+ *
+ *   pillar-escrow verify --tx 0x... --to 0x... --amount 15000000000000000 \
+ *     --chain 137 [--from 0x...] [--asset erc20:0x...] [--evm-rpc URL] \
+ *     [--confirmations 15] [--out att.json] [--no-sign] [--no-token-registry]
+ *   pillar-escrow verify-attestation --file att.json --pubkey <hex>
+ *
+ * Exit code mirrors the verdict: 0 verified, 3 pending, 1 anything else —
+ * scriptable as a settlement gate.
+ */
+async function cmdVerify(args) {
+  const home = homePath(args);
+  const cfg = existsSync(join(home, "config.json")) ? JSON.parse(readFileSync(join(home, "config.json"), "utf-8")) : {};
+  const chainId = Number(args.chain ?? process.env.PILLAR_EVM_CHAIN ?? cfg.evm?.chainId);
+  if (!Number.isInteger(chainId)) die("verify needs --chain <id>");
+  const registry = args["no-token-registry"] ? null : new TokenRegistry({ dir: registryDir(args, home, cfg) });
+  const rpcUrl = args["evm-rpc"] ?? process.env.PILLAR_EVM_RPC ?? cfg.evm?.rpcUrl ?? registry?.chains?.[String(chainId)]?.rpcUrl;
+  if (!rpcUrl) die("verify needs an rpc (--evm-rpc, PILLAR_EVM_RPC, config, or a registered chain with rpcUrl)");
+  if (typeof args.to !== "string" || typeof args.tx !== "string" || args.amount == null) {
+    die("verify needs --tx <hash> --to <0xaddr> --amount <base-units>");
+  }
+  // handle is only used as the rail's self-address; standalone claims never
+  // reference it, so a syntactically valid placeholder is fine.
+  const rail = new EvmRail({
+    rpcUrl, chainId, handle: "0x" + "00".repeat(20),
+    confirmations: Number(args.confirmations ?? cfg.evm?.confirmations ?? 15),
+  });
+  const kcPath = join(home, "kc.json");
+  const kc = !args["no-sign"] && existsSync(kcPath) ? loadKeychain(home, args) : null;
+  const verifier = new TransferVerifier({ rails: new RailSet([rail]), keychain: kc, tokenRegistry: registry });
+  const att = await verifier.verify({
+    rail: "evm", chainId, txId: args.tx,
+    from: typeof args.from === "string" ? args.from : null,
+    to: args.to, amount: String(args.amount),
+    asset: typeof args.asset === "string" ? args.asset : "native",
+  });
+  if (typeof args.out === "string") {
+    mkdirSync(dirname(args.out), { recursive: true });
+    writeFileSync(args.out, JSON.stringify(att, null, 2) + "\n");
+  }
+  console.log(JSON.stringify(att, null, 2));
+  exit(att.verdict === "verified" ? 0 : att.verdict === "pending" ? 3 : 1);
+}
+
+/** Offline check of a signed attestation against the verifier's pubkey. */
+async function cmdVerifyAttestation(args) {
+  if (typeof args.file !== "string" || typeof args.pubkey !== "string") {
+    die("verify-attestation needs --file <attestation.json> --pubkey <verifier-ed25519-hex>");
+  }
+  const att = JSON.parse(readFileSync(args.file, "utf-8"));
+  // verifyEnvelope handles both VDA-1 (full-hash id + claim-conformance) and
+  // legacy transfer-attestation (16-hex id) envelopes.
+  const r = verifyEnvelope(args.pubkey, att);
+  console.log(JSON.stringify({ ...r, verdict: att.verdict, attestationId: att.attestationId, verifier: att.verifier }, null, 2));
+  exit(r.ok ? 0 : 1);
+}
+
+/* ------------------------------------------------ vda -------------------- */
+
+function loadDirectory(args, { warnUnpinned = false } = {}) {
+  if (typeof args.directory !== "string") return null;
+  const expectedId = typeof args["directory-id"] === "string" ? args["directory-id"] : null;
+  if (!expectedId && warnUnpinned) {
+    // spec §8: the directory is the identity root; an unpinned load is
+    // trust-on-first-use of whatever file is at the path
+    console.error("[pillar-escrow] WARNING: --directory loaded WITHOUT --directory-id — identity root is unpinned (TOFU); supply the out-of-band directoryId for a conformant verification");
+  }
+  return VerifierDirectory.fromFile(args.directory, { expectedId });
+}
+
+function directoryOrPubkeyResolver(args) {
+  const dir = loadDirectory(args, { warnUnpinned: true });
+  if (dir) return dir.resolver();
+  if (typeof args.pubkey === "string") return () => args.pubkey;
+  return null;
+}
+
+/**
+ * Recipient side of data-delivery: sign an acknowledgment for received bytes.
+ *   pillar-escrow ack --file <bytes> --from <uuaid> [--envelope-id ID] [--out ack.json]
+ */
+async function cmdAck(args) {
+  const home = homePath(args);
+  const kc = loadKeychain(home, args);
+  if (typeof args.file !== "string" || typeof args.from !== "string") {
+    die("ack needs --file <received-bytes> --from <sender-uuaid>");
+  }
+  const bytes = readFileSync(args.file);
+  const r = makeDeliveryAck({
+    keychain: kc, contentHash: contentHashOf(bytes),
+    from: args.from, to: kc._identity.uuaid,
+    envelopeId: typeof args["envelope-id"] === "string" ? args["envelope-id"] : null,
+  });
+  const doc = { v: 1, kind: "vda-delivery-ack-bundle", ...r };
+  if (typeof args.out === "string") {
+    mkdirSync(dirname(args.out), { recursive: true });
+    writeFileSync(args.out, JSON.stringify(doc, null, 2) + "\n");
+  }
+  console.log(JSON.stringify(doc, null, 2));
+}
+
+/**
+ * Attest a data delivery from a signed ack (spec §6.2), optionally binding
+ * the settlement attestation into a dual-proof receipt (spec §7).
+ *   pillar-escrow attest-delivery --ack ack.json --content-hash H --from U1 --to U2 \
+ *     [--directory dir.json] [--binds attId,attId] [--bundle settlement.json] [--out receipt.json]
+ */
+async function cmdAttestDelivery(args) {
+  const home = homePath(args);
+  const kc = existsSync(join(home, "kc.json")) && !args["no-sign"] ? loadKeychain(home, args) : null;
+  if (typeof args.ack !== "string" || typeof args["content-hash"] !== "string" || typeof args.from !== "string" || typeof args.to !== "string") {
+    die("attest-delivery needs --ack <ack.json> --content-hash <sha256> --from <uuaid> --to <uuaid>");
+  }
+  const ackDoc = JSON.parse(readFileSync(args.ack, "utf-8"));
+  const binds = typeof args.binds === "string" ? args.binds.split(",").map((s) => s.trim()).filter(Boolean) : [];
+  const att = attestDataDelivery({
+    claim: {
+      contentHash: args["content-hash"], from: args.from, to: args.to,
+      recipientPubKey: typeof args["recipient-pubkey"] === "string" ? args["recipient-pubkey"] : (ackDoc.recipientPubKey ?? null),
+      envelopeId: typeof args["envelope-id"] === "string" ? args["envelope-id"] : null,
+    },
+    ack: ackDoc.ack, ackSig: ackDoc.ackSig, recipientPubKey: ackDoc.recipientPubKey ?? null,
+    directory: loadDirectory(args), keychain: kc, binds: binds.length ? binds : null,
+  });
+  const final = att;
+  let out = final;
+  if (typeof args.bundle === "string") {
+    const others = JSON.parse(readFileSync(args.bundle, "utf-8"));
+    const list = Array.isArray(others) ? others : others?.kind === RECEIPT_KIND ? others.attestations : [others];
+    const attestations = [...list, final];
+    // manifest declares the full member set by ENVELOPE hash — subsetting is detectable (spec §7)
+    out = { v: VDA_V, kind: RECEIPT_KIND, manifest: attestations.map((a) => envelopeSha256(a)), attestations };
+  }
+  if (typeof args.out === "string") {
+    mkdirSync(dirname(args.out), { recursive: true });
+    writeFileSync(args.out, JSON.stringify(out, null, 2) + "\n");
+  }
+  console.log(JSON.stringify(out, null, 2));
+  exit(final.verdict === "verified" ? 0 : final.verdict === "pending" ? 3 : 1);
+}
+
+/**
+ * Offline composite verification of a vda-receipt bundle (spec §7).
+ *   pillar-escrow verify-receipt --file receipt.json (--directory dir.json | --pubkey HEX)
+ */
+async function cmdVerifyReceipt(args) {
+  if (typeof args.file !== "string") die("verify-receipt needs --file <receipt.json>");
+  const resolver = directoryOrPubkeyResolver(args);
+  if (!resolver) die("verify-receipt needs --directory <dir.json> or --pubkey <hex>");
+  const receipt = JSON.parse(readFileSync(args.file, "utf-8"));
+  const r = verifyReceipt(receipt, resolver);
+  console.log(JSON.stringify(r, null, 2));
+  exit(r.ok && r.verdict === "verified" ? 0 : 1);
+}
+
+/**
+ * M-of-N quorum over independent attestations of one claim (spec §9).
+ *   pillar-escrow verify-quorum --files a.json,b.json,c.json --require 2 \
+ *     (--directory dir.json | --pubkey HEX)
+ */
+async function cmdVerifyQuorum(args) {
+  if (typeof args.files !== "string") die("verify-quorum needs --files <att.json,att.json,…>");
+  const resolver = directoryOrPubkeyResolver(args);
+  if (!resolver) die("verify-quorum needs --directory <dir.json> or --pubkey <hex>");
+  const atts = args.files.split(",").map((s) => s.trim()).filter(Boolean).map((f) => JSON.parse(readFileSync(f, "utf-8")));
+  const r = quorumReport(atts, resolver, { require: Number(args.require ?? 2) });
+  console.log(JSON.stringify(r, null, 2));
+  exit(r.ok ? 0 : 1);
+}
+
+/**
+ * Verifier key directory maintenance (spec §8): append-only add/revoke/show.
+ *   pillar-escrow directory --dir dir.json add --uuaid U --pubkey HEX --valid-from ISO
+ *   pillar-escrow directory --dir dir.json revoke --uuaid U --pubkey HEX --revoked-at ISO
+ *   pillar-escrow directory --dir dir.json show
+ */
+async function cmdDirectory(args) {
+  if (typeof args.dir !== "string") die("directory needs --dir <dir.json>");
+  const sub = args._[1];
+  const d = VerifierDirectory.fromFile(args.dir);
+  if (sub === "add") {
+    d.add({ uuaid: args.uuaid, publicKeyHex: args.pubkey, validFrom: args["valid-from"] ?? new Date().toISOString() });
+    d.toFile(args.dir);
+  } else if (sub === "revoke") {
+    d.revoke({ uuaid: args.uuaid, publicKeyHex: args.pubkey, revokedAt: args["revoked-at"] ?? new Date().toISOString() });
+    d.toFile(args.dir);
+  } else if (sub !== "show") {
+    die("directory needs a subcommand: add | revoke | show");
+  }
+  console.log(JSON.stringify({ directoryId: d.id(), records: d.records }, null, 2));
+}
+
+/* ------------------------------------------------ main ------------------- */
+
+const args = parseArgs(argv.slice(2));
+const cmd = args._[0];
+const handlers = {
+  init: cmdInit, "run-escrow": cmdRunEscrow, sell: cmdSell, buy: cmdBuy,
+  "token-apply": cmdTokenApply, "chain-apply": cmdTokenApply,
+  "token-list": cmdTokenList, "token-review": cmdTokenReview,
+  verify: cmdVerify, "verify-attestation": cmdVerifyAttestation,
+  ack: cmdAck, "attest-delivery": cmdAttestDelivery,
+  "verify-receipt": cmdVerifyReceipt, "verify-quorum": cmdVerifyQuorum,
+  directory: cmdDirectory,
+};
+if (!handlers[cmd]) {
+  console.error("usage: pillar-escrow <init|run-escrow|sell|buy|token-apply|chain-apply|token-list|token-review|verify|verify-attestation|ack|attest-delivery|verify-receipt|verify-quorum|directory> [--home DIR] [--carrier URL] ...");
+  exit(2);
+}
+handlers[cmd](args).catch((e) => {
+  console.error(`[pillar-escrow] ${cmd} failed: ${e?.message ?? e}`);
+  exit(1);
+});