@uuaid/pillar 0.2.0-alpha.9 → 2.0.1

package/src/escrow/rails/evm-rail.mjs

@@ -0,0 +1,427 @@
+/**
+ * EVM rail — native coin (POL/ETH) and ERC-20 payments for the blind escrow.
+ *
+ * Same security posture as the Zilligon rail, mapped onto chain instruments:
+ *   - ATTESTATION is escrow-side and independent of the buyer's story: the
+ *     claimed txId is only a LOOKUP KEY — what is verified is the chain's own
+ *     receipt (status 1, to == escrow, from == buyer, exact amount, and a
+ *     configurable confirmation depth) read over the escrow's OWN rpc.
+ *   - PAYOUT is sign-then-journal-then-broadcast: preparePayout() signs a
+ *     complete tx (fixed nonce) and returns {txId, rawTx} for the journal
+ *     BEFORE anything hits the chain.  Crash recovery re-broadcasts the SAME
+ *     bytes — same nonce, same hash — so a double-spend is impossible by
+ *     construction (the chain accepts one tx per nonce).  findPriorPayout()
+ *     is an exact receipt lookup, not a heuristic wallet scan.
+ *   - The signing key is never stored on this object and never logged: a
+ *     privateKeyProvider callback is invoked per signature and the result
+ *     dropped.  Production custody: provider fetches from a secrets manager;
+ *     the default reads process.env.PILLAR_EVM_KEY at call time.
+ *
+ * Crypto pipeline (keccak-256, RLP, EIP-1559 payload, recovered-signature
+ * layout, address derivation) was verified byte-exact against live Polygon
+ * transactions on 2026-08-26 — the unit test embeds one as a fixture:
+ * hash match AND sender recovery on tx 0x7f299a0c…d78456 (block 92702633).
+ *
+ * Amounts cross this interface as DECIMAL STRINGS of base units (wei); all
+ * arithmetic is BigInt.  1 POL = 10^18 wei never fits a JS number.
+ *
+ * assets: "native" or "erc20:0x<tokenAddress>".
+ */
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+
+/* ------------------------------------------------ bytes / hex ---------- */
+
+const strip0x = (h) => (typeof h === "string" && h.startsWith("0x") ? h.slice(2) : h ?? "");
+
+export function hexToBytes(h) {
+  let s = strip0x(h);
+  if (s.length % 2) s = "0" + s;
+  return Uint8Array.from(Buffer.from(s, "hex"));
+}
+
+const bytesToHex = (b) => "0x" + Buffer.from(b).toString("hex");
+
+/** bigint -> minimal big-endian bytes (0n -> empty), the RLP integer form. */
+function bnToBytes(v) {
+  if (v === 0n) return new Uint8Array(0);
+  let h = v.toString(16);
+  if (h.length % 2) h = "0" + h;
+  return Uint8Array.from(Buffer.from(h, "hex"));
+}
+
+/** hex quantity ("0x1a") -> minimal bytes. */
+const qty = (h) => bnToBytes(BigInt(h ?? "0x0"));
+
+const pad32 = (b) => Buffer.concat([Buffer.alloc(32 - b.length), Buffer.from(b)]);
+
+const DEC = /^(0|[1-9][0-9]*)$/;
+export const MAX_UINT256 = (1n << 256n) - 1n;
+
+/** Decimal base-unit string -> BigInt, rejecting anything non-canonical. */
+export function toWei(amount) {
+  if (typeof amount === "bigint") return amount;
+  if (typeof amount === "string" && DEC.test(amount)) {
+    const v = BigInt(amount);
+    if (v <= MAX_UINT256) return v;
+  }
+  throw new Error(`evm: amount must be a canonical decimal base-unit string, got ${JSON.stringify(amount)}`);
+}
+
+export const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const sameAddr = (a, b) => typeof a === "string" && typeof b === "string" && a.toLowerCase() === b.toLowerCase();
+
+/* ------------------------------------------------ RLP ------------------ */
+
+/** Minimal RLP encoder (Uint8Array items and nested arrays only). */
+export function rlpEncode(item) {
+  if (Array.isArray(item)) {
+    const parts = item.map(rlpEncode);
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    let head;
+    if (total <= 55) head = Uint8Array.of(0xc0 + total);
+    else {
+      const lb = bnToBytes(BigInt(total));
+      head = Buffer.concat([Uint8Array.of(0xf7 + lb.length), lb]);
+    }
+    return Buffer.concat([head, ...parts]);
+  }
+  const b = item;
+  if (b.length === 1 && b[0] <= 0x7f) return Buffer.from(b);
+  if (b.length <= 55) return Buffer.concat([Uint8Array.of(0x80 + b.length), b]);
+  const lb = bnToBytes(BigInt(b.length));
+  return Buffer.concat([Uint8Array.of(0xb7 + lb.length), lb, b]);
+}
+
+/* ------------------------------------------------ EIP-1559 signing ----- */
+
+export function addressOfPrivateKey(privHex) {
+  const pub = secp256k1.getPublicKey(hexToBytes(privHex), false); // uncompressed 65B
+  return bytesToHex(keccak_256(pub.slice(1)).slice(12));
+}
+
+/**
+ * Serialize + sign an EIP-1559 tx.  All numeric fields BigInt.
+ * Returns { txId, rawTx } — public-after-broadcast data, journal-safe.
+ */
+export function signEip1559(tx, privHex) {
+  const unsigned = [
+    bnToBytes(tx.chainId), bnToBytes(tx.nonce),
+    bnToBytes(tx.maxPriorityFeePerGas), bnToBytes(tx.maxFeePerGas),
+    bnToBytes(tx.gasLimit), hexToBytes(tx.to), bnToBytes(tx.value),
+    hexToBytes(tx.data ?? "0x"), [],
+  ];
+  const sighash = keccak_256(Buffer.concat([Uint8Array.of(0x02), rlpEncode(unsigned)]));
+  // noble "recovered" layout: [recovery(1) || r(32) || s(32)]
+  const sig = secp256k1.sign(sighash, hexToBytes(privHex), { format: "recovered", prehash: false });
+  const parity = sig[0];
+  // r/s enter RLP as minimal integers (BigInt round-trip strips leading zeros)
+  const rInt = BigInt(bytesToHex(sig.slice(1, 33))), sInt = BigInt(bytesToHex(sig.slice(33, 65)));
+  const signed = [...unsigned, bnToBytes(BigInt(parity)), bnToBytes(rInt), bnToBytes(sInt)];
+  const raw = Buffer.concat([Uint8Array.of(0x02), rlpEncode(signed)]);
+  return { txId: bytesToHex(keccak_256(raw)), rawTx: bytesToHex(raw) };
+}
+
+/** Recover the from-address of a signed EIP-1559 payload (test instrument). */
+export function recoverEip1559Sender({ chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, yParity, r, s }) {
+  const unsigned = [
+    bnToBytes(chainId), bnToBytes(nonce), bnToBytes(maxPriorityFeePerGas), bnToBytes(maxFeePerGas),
+    bnToBytes(gasLimit), hexToBytes(to), bnToBytes(value), hexToBytes(data ?? "0x"), [],
+  ];
+  const sighash = keccak_256(Buffer.concat([Uint8Array.of(0x02), rlpEncode(unsigned)]));
+  const rec = Uint8Array.from(Buffer.concat([
+    Uint8Array.of(Number(yParity >= 27n ? yParity - 27n : yParity)),
+    pad32(bnToBytes(r)), pad32(bnToBytes(s)),
+  ]));
+  const point = secp256k1.Point.fromBytes(secp256k1.recoverPublicKey(rec, sighash, { prehash: false }));
+  return bytesToHex(keccak_256(point.toBytes(false).slice(1)).slice(12));
+}
+
+/* ------------------------------------------------ ERC-20 --------------- */
+
+// Self-derived from the (chain-anchored) keccak — the unit test asserts the
+// well-known literals so a hash regression cannot pass silently.
+export const ERC20_TRANSFER_SELECTOR = bytesToHex(keccak_256(Buffer.from("transfer(address,uint256)", "utf-8")).slice(0, 4));
+export const ERC20_TRANSFER_TOPIC = bytesToHex(keccak_256(Buffer.from("Transfer(address,address,uint256)", "utf-8")));
+
+export function erc20TransferData(to, amount) {
+  return ERC20_TRANSFER_SELECTOR +
+    pad32(hexToBytes(to)).toString("hex") +
+    pad32(bnToBytes(toWei(amount))).toString("hex");
+}
+
+const ASSET_RE = /^erc20:0x[0-9a-fA-F]{40}$/;
+export function parseAsset(asset) {
+  if (asset === "native" || asset == null) return { kind: "native" };
+  if (typeof asset === "string" && ASSET_RE.test(asset)) return { kind: "erc20", token: asset.slice(6).toLowerCase() }; // token keeps its 0x prefix
+  throw new Error(`evm: unknown asset ${JSON.stringify(asset)}`);
+}
+
+/* ------------------------------------------------ rail ----------------- */
+
+const KNOWN_TX_ERRORS = /already known|alreadyknown|nonce too low|known transaction|already exists/i;
+
+export class EvmRail {
+  /**
+   * @param rpcUrl          escrow's own JSON-RPC endpoint (the attestation instrument)
+   * @param chainId         pinned; verified against eth_chainId on first use (fail closed)
+   * @param handle          escrow's 0x address on this chain
+   * @param privateKeyProvider  async () -> 0x-hex key, called per signature, never stored
+   * @param confirmations   depth required to attest a payment (and payout receipts)
+   * @param maxFeePerGasWei hard cap on maxFeePerGas (fail closed if the chain wants more)
+   * @param fetchImpl       injectable for tests
+   */
+  constructor({
+    rpcUrl, chainId, handle,
+    privateKeyProvider = async () => {
+      const k = process.env.PILLAR_EVM_KEY;
+      if (!k) throw new Error("evm: no signing key (set PILLAR_EVM_KEY or inject privateKeyProvider)");
+      return k;
+    },
+    confirmations = 15,
+    maxFeePerGasWei = 2_000_000_000_000n, // 2000 gwei — generous for Polygon, a cap not a price
+    gasLimitNative = 21_000n,
+    gasLimitErc20 = 120_000n,
+    attempts = 6, delayMs = 5000,
+    fetchImpl = fetch,
+  }) {
+    if (!rpcUrl) throw new Error("EvmRail: rpcUrl required");
+    if (!Number.isInteger(chainId) || chainId < 1) throw new Error("EvmRail: integer chainId required");
+    if (!ADDRESS_RE.test(handle ?? "")) throw new Error("EvmRail: handle must be the escrow's 0x address");
+    this.name = "evm";
+    this.rpcUrl = rpcUrl;
+    this.chainId = chainId;
+    this.handle = handle;
+    this.privateKeyProvider = privateKeyProvider;
+    this.confirmations = confirmations;
+    this.maxFeePerGasWei = maxFeePerGasWei;
+    this.gasLimitNative = gasLimitNative;
+    this.gasLimitErc20 = gasLimitErc20;
+    this.attempts = attempts;
+    this.delayMs = delayMs;
+    this._fetch = fetchImpl;
+    this._chainChecked = false;
+    // Per-account prep serialization: concurrent preparePayout calls in this
+    // process are chained, and _nonceFloor hands out strictly increasing
+    // nonces even before the chain sees the earlier broadcasts.  Cross-process
+    // / cross-restart races are caught by payoutStatus() -> re-prepare.
+    this._prepLock = Promise.resolve();
+    this._nonceFloor = -1n;
+  }
+
+  get railKey() { return `evm:${this.chainId}`; }
+
+  async _rpc(method, params) {
+    const res = await this._fetch(this.rpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    });
+    const json = await res.json();
+    if (json.error) { const e = new Error(`evm ${method}: ${json.error.message ?? JSON.stringify(json.error)}`); e.rpcError = json.error; throw e; }
+    return json.result;
+  }
+
+  /** Pinned-chain guard: the configured chainId must be the endpoint's. */
+  async _assertChain() {
+    if (this._chainChecked) return;
+    const got = Number(BigInt(await this._rpc("eth_chainId", [])));
+    if (got !== this.chainId) throw new Error(`evm: rpc serves chain ${got}, rail pinned to ${this.chainId}`);
+    this._chainChecked = true;
+  }
+
+  async _confirmedReceipt(txId) {
+    const rcpt = await this._rpc("eth_getTransactionReceipt", [txId]);
+    if (!rcpt) return null;
+    if (rcpt.status !== "0x1") return { rcpt, ok: false, reason: "reverted" };
+    const latest = BigInt(await this._rpc("eth_blockNumber", []));
+    const depth = latest - BigInt(rcpt.blockNumber) + 1n;
+    if (depth < BigInt(this.confirmations)) return { rcpt, ok: false, reason: "unconfirmed" };
+    return { rcpt, ok: true };
+  }
+
+  /**
+   * Attest the buyer's payment from the chain itself.  txId is required on
+   * this rail (there is no amount+window fallback: without an indexer the
+   * escrow cannot enumerate inbound txs, and the claim already carries it).
+   * Polls to ride out inclusion + confirmation lag.  Returns
+   * { txId, sourceId: null, raw } or null.
+   */
+  async attestPayment({ fromHandle, amount, txId, asset }) {
+    if (typeof txId !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(txId)) return null;
+    await this._assertChain();
+    const want = toWei(amount);
+    const a = parseAsset(asset);
+    for (let i = 0; i < this.attempts; i++) {
+      const hit = await this._attestOnce({ fromHandle, want, txId, a }).catch(() => null);
+      if (hit) return hit;
+      if (i < this.attempts - 1) await new Promise((r) => setTimeout(r, this.delayMs));
+    }
+    return null;
+  }
+
+  async _attestOnce({ fromHandle, want, txId, a }) {
+    const conf = await this._confirmedReceipt(txId);
+    if (!conf?.ok) return null;
+    const { rcpt } = conf;
+    const tx = await this._rpc("eth_getTransactionByHash", [txId]);
+    if (!tx) return null;
+    if (fromHandle && !sameAddr(tx.from, fromHandle)) return null;
+    if (a.kind === "native") {
+      if (!sameAddr(tx.to, this.handle)) return null;
+      if (BigInt(tx.value) !== want) return null;
+    } else {
+      // exact Transfer(from=buyer, to=escrow, value=want) log emitted by THE token
+      const log = (rcpt.logs ?? []).find((l) =>
+        sameAddr(l.address, a.token) &&
+        (l.topics?.[0] ?? "").toLowerCase() === ERC20_TRANSFER_TOPIC &&
+        sameAddr("0x" + strip0x(l.topics?.[1] ?? "").slice(-40), fromHandle ?? tx.from) &&
+        sameAddr("0x" + strip0x(l.topics?.[2] ?? "").slice(-40), this.handle) &&
+        BigInt(l.data ?? "0x0") === want);
+      if (!log) return null;
+    }
+    return { txId, sourceId: null, raw: { blockNumber: rcpt.blockNumber, from: tx.from } };
+  }
+
+  /**
+   * Build + sign the payout WITHOUT broadcasting.  The result is journaled by
+   * the caller before sendPayout — the crash-recovery anchor.  Nonce is read
+   * at "latest": the escrow account must have a single writer (this service).
+   */
+  async preparePayout(args) {
+    // serialize concurrent preps on this account (finding #2: two offers
+    // preparing at once would both read the same "latest" nonce)
+    const run = this._prepLock.then(() => this._prepareLocked(args));
+    this._prepLock = run.catch(() => {}); // a failed prep never wedges the lock
+    return run;
+  }
+
+  async _prepareLocked({ toHandle, amount, asset }) {
+    await this._assertChain();
+    if (!ADDRESS_RE.test(toHandle ?? "")) throw new Error("evm: payout recipient must be a 0x address");
+    const value = toWei(amount);
+    const a = parseAsset(asset);
+    const chainNonce = BigInt(await this._rpc("eth_getTransactionCount", [this.handle, "latest"]));
+    const nonce = chainNonce > this._nonceFloor ? chainNonce : this._nonceFloor + 1n;
+    this._nonceFloor = nonce;
+    const block = await this._rpc("eth_getBlockByNumber", ["latest", false]);
+    const baseFee = BigInt(block?.baseFeePerGas ?? "0x0");
+    let tip;
+    try { tip = BigInt(await this._rpc("eth_maxPriorityFeePerGas", [])); }
+    catch (_e) { tip = 30_000_000_000n; } // 30 gwei — Polygon's floor
+    let maxFee = baseFee * 2n + tip;
+    if (baseFee + tip > this.maxFeePerGasWei) throw new Error(`evm: fee cap exceeded (base+tip ${baseFee + tip} > cap ${this.maxFeePerGasWei})`);
+    if (maxFee > this.maxFeePerGasWei) maxFee = this.maxFeePerGasWei;
+    const txReq = a.kind === "native"
+      ? { to: toHandle, value, data: "0x", gasLimit: this.gasLimitNative }
+      : { to: a.token, value: 0n, data: erc20TransferData(toHandle, value), gasLimit: this.gasLimitErc20 };
+    const priv = await this.privateKeyProvider();
+    try {
+      const { txId, rawTx } = signEip1559({
+        chainId: BigInt(this.chainId), nonce,
+        maxPriorityFeePerGas: tip > maxFee ? maxFee : tip, maxFeePerGas: maxFee,
+        gasLimit: txReq.gasLimit, to: txReq.to, value: txReq.value, data: txReq.data,
+      }, priv);
+      return { txId, rawTx, nonce: nonce.toString(), chainId: this.chainId };
+    } finally { /* the key was a local; nothing retained on this */ }
+  }
+
+  /**
+   * Broadcast a prepared payout and wait for its confirmed receipt.
+   * Re-broadcasting the same rawTx is idempotent by nonce — "already known" /
+   * "nonce too low" fall through to the receipt check.
+   */
+  async sendPayout({ prepared }) {
+    if (!prepared?.rawTx || !prepared?.txId) throw new Error("evm: sendPayout needs a prepared payout");
+    await this._assertChain();
+    try {
+      await this._rpc("eth_sendRawTransaction", [prepared.rawTx]);
+    } catch (e) {
+      if (!KNOWN_TX_ERRORS.test(String(e?.rpcError?.message ?? e?.message ?? ""))) throw e;
+    }
+    for (let i = 0; i < this.attempts; i++) {
+      const conf = await this._confirmedReceipt(prepared.txId).catch(() => null);
+      if (conf?.ok) return { txId: prepared.txId, sourceId: null };
+      if (conf && conf.reason === "reverted") throw new Error(`evm: payout ${prepared.txId} reverted on-chain`);
+      await new Promise((r) => setTimeout(r, this.delayMs));
+    }
+    throw new Error(`evm: payout ${prepared.txId} not confirmed after ${this.attempts} attempts (reconcile will retry)`);
+  }
+
+  /** Crash-recovery instrument: exact receipt lookup of the journaled txId. */
+  async findPriorPayout({ prepared }) {
+    if (!prepared?.txId) return null;
+    await this._assertChain();
+    const conf = await this._confirmedReceipt(prepared.txId).catch(() => null);
+    return conf?.ok ? { txId: prepared.txId, sourceId: null } : null;
+  }
+
+  /**
+   * Fate of a prepared payout — can its exact bytes still land?
+   *   { state: "confirmed" }           receipt at depth, status 1
+   *   { state: "pending" }             may still land (keep re-broadcasting)
+   *   { state: "invalidated", reason } provably dead: the tx reverted, or its
+   *     nonce was consumed at FINALIZED depth by a different hash — safe to
+   *     re-prepare (a reorg deeper than `confirmations` is the documented
+   *     residual, same posture as attestation).
+   */
+  async payoutStatus({ prepared }) {
+    if (!prepared?.txId || prepared.nonce == null) return { state: "pending" };
+    await this._assertChain();
+    const conf = await this._confirmedReceipt(prepared.txId).catch(() => null);
+    if (conf?.ok) return { state: "confirmed" };
+    if (conf?.reason === "reverted") return { state: "invalidated", reason: "reverted" };
+    if (conf?.reason === "unconfirmed") return { state: "pending" };
+    const latest = BigInt(await this._rpc("eth_blockNumber", []));
+    let finalized = latest - BigInt(this.confirmations);
+    if (finalized < 0n) finalized = 0n;
+    const count = BigInt(await this._rpc("eth_getTransactionCount", [this.handle, "0x" + finalized.toString(16)]));
+    if (count > BigInt(prepared.nonce)) return { state: "invalidated", reason: "nonce-superseded" };
+    return { state: "pending" };
+  }
+
+  /**
+   * Standalone transfer verification — the attestation instrument opened to
+   * ANY (from, to) pair, not just payments into this escrow.  Verifies from
+   * the chain's own record at confirmation depth: status 1, exact amount,
+   * exact parties; for ERC-20, the Transfer log emitted by THE token.
+   * One read, no polling.  Returns
+   *   { verified: true, blockNumber, depth, from, to, amount, asset }
+   * or { verified: false, reason }.
+   */
+  async verifyTransfer({ txId, from, to, amount, asset }) {
+    if (typeof txId !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(txId)) return { verified: false, reason: "bad-txid" };
+    if (!ADDRESS_RE.test(to ?? "")) return { verified: false, reason: "bad-to" };
+    if (from != null && !ADDRESS_RE.test(from)) return { verified: false, reason: "bad-from" };
+    await this._assertChain();
+    const want = toWei(amount);
+    const a = parseAsset(asset);
+    const conf = await this._confirmedReceipt(txId).catch(() => null);
+    if (!conf) return { verified: false, reason: "not-found" };
+    if (!conf.ok) return { verified: false, reason: conf.reason };
+    const { rcpt } = conf;
+    const tx = await this._rpc("eth_getTransactionByHash", [txId]);
+    if (!tx) return { verified: false, reason: "not-found" };
+    if (from && !sameAddr(tx.from, from)) return { verified: false, reason: "from-mismatch" };
+    if (a.kind === "native") {
+      if (!sameAddr(tx.to, to)) return { verified: false, reason: "to-mismatch" };
+      if (BigInt(tx.value) !== want) return { verified: false, reason: "amount-mismatch" };
+    } else {
+      const log = (rcpt.logs ?? []).find((l) =>
+        sameAddr(l.address, a.token) &&
+        (l.topics?.[0] ?? "").toLowerCase() === ERC20_TRANSFER_TOPIC &&
+        sameAddr("0x" + strip0x(l.topics?.[1] ?? "").slice(-40), from ?? tx.from) &&
+        sameAddr("0x" + strip0x(l.topics?.[2] ?? "").slice(-40), to) &&
+        BigInt(l.data ?? "0x0") === want);
+      if (!log) return { verified: false, reason: "no-matching-transfer-log" };
+    }
+    const latest = BigInt(await this._rpc("eth_blockNumber", []));
+    return {
+      verified: true,
+      blockNumber: Number(BigInt(rcpt.blockNumber)),
+      depth: Number(latest - BigInt(rcpt.blockNumber) + 1n),
+      from: (from ?? tx.from).toLowerCase(), to: to.toLowerCase(),
+      amount: want.toString(), asset: a.kind === "native" ? "native" : `erc20:${a.token}`,
+    };
+  }
+}

package/src/escrow/rails/index.mjs

@@ -0,0 +1,41 @@
+/**
+ * Rail registry — resolves the rail instance a terms object rides on.
+ *
+ * Rail keys: "zilligon" (v1 terms and the classic rail), "evm:<chainId>"
+ * (v2 terms carry rail:"evm" + an integer chainId).  A terms object whose
+ * key has no registered rail is REJECTED by the escrow ("rail-unsupported")
+ * — never guessed at.
+ */
+import { ZilligonRail } from "./zilligon-rail.mjs";
+import { EvmRail } from "./evm-rail.mjs";
+
+export { ZilligonRail, EvmRail };
+
+/** The registry key a terms object addresses. */
+export function railKeyOfTerms(terms) {
+  if (!terms) return null;
+  if (terms.v === 1) return "zilligon";
+  if (terms.rail === "evm") return Number.isInteger(terms.chainId) ? `evm:${terms.chainId}` : null;
+  return typeof terms.rail === "string" ? terms.rail : null;
+}
+
+export class RailSet {
+  constructor(rails = []) {
+    this.byKey = new Map();
+    for (const r of rails) this.add(r);
+  }
+
+  add(rail) {
+    if (!rail?.railKey) throw new Error("RailSet: rail must expose railKey");
+    this.byKey.set(rail.railKey, rail);
+    return this;
+  }
+
+  get(key) { return this.byKey.get(key) ?? null; }
+
+  /** Rail for a terms object, or null (caller rejects the offer). */
+  for(terms) {
+    const key = railKeyOfTerms(terms);
+    return key ? this.get(key) : null;
+  }
+}

package/src/escrow/rails/zilligon-rail.mjs

@@ -0,0 +1,73 @@
+/**
+ * Zilligon rail adapter — wraps the existing ZilligonClient (or any
+ * duck-typed client with findPayment/transfer/getWallet + handle) behind the
+ * uniform rail interface the EscrowService drives:
+ *
+ *   attestPayment({ fromHandle, amount, txId, sourceId }) -> {txId, sourceId, raw} | null
+ *   preparePayout(...)                                    -> null   (one-shot rail)
+ *   sendPayout({ toHandle, amount })                      -> {txId, sourceId}
+ *   findPriorPayout({ toHandle, amount })                 -> {txId, sourceId} | null
+ *
+ * Behavior is byte-for-byte the logic that lived inline in escrow-service.mjs
+ * (v0.2.0-alpha.11): the transfer-response id extraction, the acked-but-no-id
+ * wallet re-read, and the 3×2s crash-recovery wallet scan all moved here
+ * unchanged.  Amounts arrive as decimal strings (rail interface) and become
+ * the integer Gons the client expects.
+ */
+import { findPayoutInWallet, txIdOf } from "../zilligon.mjs";
+
+const asGons = (amount) => {
+  const n = Number(amount);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`zilligon rail: amount must be integer Gons, got ${amount}`);
+  return n;
+};
+
+export class ZilligonRail {
+  constructor({ client, retryDelayMs = 2000 }) {
+    if (!client?.handle) throw new Error("ZilligonRail: client with a handle required");
+    this.name = "zilligon";
+    this.railKey = "zilligon";
+    this.client = client;
+    this.handle = client.handle;
+    this.retryDelayMs = retryDelayMs;
+  }
+
+  async attestPayment({ fromHandle, amount, txId, sourceId }) {
+    const hit = await this.client.findPayment({
+      buyerHandle: fromHandle, expectedAmount: asGons(amount), txId, sourceId: sourceId ?? null,
+    });
+    if (!hit) return null;
+    return { txId: txIdOf(hit) ?? txId, sourceId: hit?.sourceId ?? null, raw: hit };
+  }
+
+  async preparePayout() { return null; }
+
+  async sendPayout({ toHandle, amount }) {
+    const gons = asGons(amount);
+    const res = await this.client.transfer({ recipientHandle: toHandle, amount: gons });
+    let txId = txIdOf(res?.data?.transaction ?? res?.data ?? {});
+    // The transfer response's transactionId equals the Tip id = both wallet
+    // rows' sourceId (verified live 2026-08-21) — bind to it.
+    let sourceId = txId ?? null;
+    if (!txId) {
+      // rail acked but returned no id we recognize — verify via wallet read
+      const wallet = await this.client.getWallet(this.handle).catch(() => null);
+      const prior = wallet ? findPayoutInWallet(wallet, { sellerHandle: toHandle, amount: gons }) : null;
+      txId = prior ? txIdOf(prior) : null;
+      sourceId = prior?.sourceId ?? null;
+    }
+    return { txId, sourceId };
+  }
+
+  async findPriorPayout({ toHandle, amount }) {
+    const gons = asGons(amount);
+    // a few retries to ride out rail propagation lag
+    let prior = null;
+    for (let i = 0; i < 3 && !prior; i++) {
+      const wallet = await this.client.getWallet(this.handle).catch(() => null);
+      prior = wallet ? findPayoutInWallet(wallet, { sellerHandle: toHandle, amount: gons }) : null;
+      if (!prior) await new Promise((r) => setTimeout(r, this.retryDelayMs));
+    }
+    return prior && txIdOf(prior) ? { txId: txIdOf(prior), sourceId: prior?.sourceId ?? null } : null;
+  }
+}