@uuaid/pillar 0.2.0-alpha.8 → 2.0.1

package/src/escrow/escrow-service.mjs

@@ -0,0 +1,538 @@
+/**
+ * EscrowService — the blind-escrow state machine.
+ *
+ *   OPEN --offer--> OPEN --accept--> ACCEPTED --paid+attest--> PAID
+ *   --release--> RELEASED
+ *
+ * The escrow holds ONLY the 32-byte content key K (plus sha256(item) inside
+ * the signed terms) — it never sees the deliverable, which the seller sends
+ * to the buyer directly as a ciphertext box.  Payment rides the Zilligon ZGN
+ * rail; the escrow attests the buyer's payment from ITS OWN wallet rows (an
+ * instrument independent of the buyer's claimed txId), then:
+ *   1. attests payment           (zilligon.findPayment)
+ *   2. pays the seller           (rail transfer of escrowSend)
+ *   3. releases K + buyer receipt to the buyer
+ *   4. sends the seller receipt
+ *
+ * Journal-first JSONL: every state change and every release step is appended
+ * to the journal BEFORE (or right after, with a recovery marker before) the
+ * irreversible rail action, so reconcile() can re-run release after a crash
+ * without double-paying: payout-attempt precedes the transfer, payout-sent
+ * records the rail txId, and a payout-attempt without payout-sent is de-duped
+ * against the escrow's own wallet rows before re-attempting.
+ *
+ * All replies are ordinary pillar envelopes (E2E-encrypted by the envelope
+ * layer — carriers stay payload-blind).  Party pubkeys ride in the terms, so
+ * no directory lookups are needed.
+ */
+import { appendFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import {
+  validateTerms, verifyTermsSig, verifyReceiptSig,
+  PAID_GRACE_MS, makeReceipt, railViewOfTerms,
+} from "./terms.mjs";
+import { RailSet, ZilligonRail, railKeyOfTerms } from "./rails/index.mjs";
+import { Observability } from "../observability.mjs";
+
+const HEX64 = /^[0-9a-f]{64}$/i;
+
+export const STATES = { OPEN: "open", ACCEPTED: "accepted", PAID: "paid", RELEASED: "released" };
+
+export class EscrowService {
+  /**
+   * @param keychain  escrow's Keychain (loaded identity; uuaid must equal the
+   *                  escrow named in incoming terms)
+   * @param pillar    started Pillar instance (carrier-only in tests)
+   * @param zilligon  ZilligonClient bound to the escrow's own @handle + apiKey
+   * @param journalPath  JSONL journal file
+   * @param railHandle   escrow's Zilligon handle (must match terms.escrowHandle)
+   */
+  constructor({ keychain, pillar, zilligon, rails, journalPath, railHandle, metrics = null, tokenRegistry = null }) {
+    this.keychain = keychain;
+    this.pillar = pillar;
+    this.zilligon = zilligon ?? null;
+    this.rails = rails instanceof RailSet ? rails : new RailSet(Array.isArray(rails) ? rails : rails ? [rails] : []);
+    if (zilligon && !this.rails.get("zilligon")) this.rails.add(new ZilligonRail({ client: zilligon }));
+    // Asset allowlist (token-registry.mjs).  When wired, v2 offers naming an
+    // unregistered chain/token are rejected at the door — fail closed.
+    this.tokenRegistry = tokenRegistry;
+    this.journalPath = journalPath;
+    this.railHandle = railHandle ?? zilligon?.handle ?? null;
+    this.metrics = metrics ?? new Observability();
+    this.offers = new Map(); // offerId -> {state, terms, contentKeyHex, sellerSig, buyerSig, payTxId, releaseTxId, payoutAttempted}
+    // One on-chain payment attests ONE offer: rail-scoped keys of every
+    // attested payment, bound to the offer that consumed them.  Consumption
+    // happens only on ATTESTED success (never on a mere claim — a bogus
+    // claim must not be able to squat a stranger's txId).
+    this.consumedPayTx = new Map(); // "railKey|tx|<txId>" / "railKey|src|<sourceId>" -> offerId
+    if (journalPath) {
+      mkdirSync(dirname(journalPath), { recursive: true });
+      this._loadJournal();
+    }
+  }
+
+  /* ------------------------------------------------ journal ------------ */
+
+  _append(event) {
+    if (!this.journalPath) return;
+    appendFileSync(this.journalPath, JSON.stringify({ ...event, at: new Date().toISOString() }) + "\n");
+  }
+
+  _loadJournal() {
+    let lines = "";
+    try {
+      lines = readFileSync(this.journalPath, "utf-8");
+    } catch (_e) {
+      return; // no journal yet — fresh escrow
+    }
+    for (const line of lines.split("\n")) {
+      if (!line.trim()) continue;
+      let ev;
+      try {
+        ev = JSON.parse(line);
+      } catch (_e) {
+        continue; // torn tail line from a crash — the next lines self-heal
+      }
+      if (!ev.event || !ev.offerId) continue;
+      const o = this.offers.get(ev.offerId) ?? { state: STATES.OPEN, terms: null, payoutAttempted: false, payoutDone: false };
+      switch (ev.event) {
+        case "offered":
+          Object.assign(o, { terms: ev.terms, contentKeyHex: ev.contentKeyHex, sellerSig: ev.sellerSig });
+          break;
+        case "accepted":
+          o.buyerSig = ev.buyerSig;
+          o.state = STATES.ACCEPTED;
+          break;
+        case "paid":
+          // Latest claim wins (corrected claims re-journal; payout-attempt pins)
+          o.payTxId = ev.txId;
+          o.paySourceId = ev.sourceId ?? undefined;
+          o.state = STATES.PAID;
+          break;
+        case "payout-attempt":
+          o.payoutAttempted = true;
+          if (ev.prepared) o.payoutPrepared = ev.prepared; // EVM: signed-but-maybe-unbroadcast tx
+          break;
+        case "payout-invalidated":
+          // The prepared bytes are provably dead (reverted / nonce superseded)
+          // — never re-broadcast them; the next payout-attempt re-prepares.
+          o.payoutPrepared = null;
+          break;
+        case "payout-sent":
+          o.releaseTxId = ev.releaseTxId;
+          if (ev.releaseSourceId) o.releaseSourceId = ev.releaseSourceId;
+          o.payoutDone = true;
+          break;
+        case "released":
+          o.state = STATES.RELEASED;
+          break;
+        case "key-sent":
+          break; // marker only; state stays PAID until "released"
+        case "pay-consumed":
+          for (const k of ev.keys ?? []) this.consumedPayTx.set(k, ev.offerId);
+          break;
+      }
+      this.offers.set(ev.offerId, o);
+    }
+    // Pre-fix journals carry no pay-consumed events.  payout-attempt only
+    // ever follows a SUCCESSFUL attestation, so for those offers the claimed
+    // payment ids were genuinely consumed — backfill them.  (Offers merely
+    // PAID are NOT backfilled: an unattested claim must never squat an id.)
+    for (const [offerId, o] of this.offers) {
+      if (!o.payoutAttempted || !o.terms) continue;
+      const railKey = railKeyOfTerms(o.terms);
+      if (!railKey) continue;
+      for (const k of this._payKeys(railKey, o.payTxId, o.paySourceId ?? null)) {
+        if (!this.consumedPayTx.has(k)) this.consumedPayTx.set(k, offerId);
+      }
+    }
+    this._gaugeOffers();
+  }
+
+  /** Rail-scoped consumption keys of a payment (txId + wallet row, if any). */
+  _payKeys(railKey, txId, sourceId) {
+    const keys = [];
+    if (txId) keys.push(`${railKey}|tx|${String(txId).toLowerCase()}`);
+    if (sourceId) keys.push(`${railKey}|src|${String(sourceId).toLowerCase()}`);
+    return keys;
+  }
+
+  /* ------------------------------------------------ routing ------------ */
+
+  attach() {
+    this.pillar.onEnvelope((env) => {
+      const kind = env.kind;
+      if (kind === "escrow.offer") return this.onOffer(env);
+      if (kind === "escrow.accept") return this.onAccept(env);
+      if (kind === "escrow.paid") return this.onPaid(env);
+      return undefined; // not ours
+    });
+  }
+
+  /** Reconcile poll: re-run release for every PAID offer (crash recovery). */
+  start({ reconcileMs = 30_000 } = {}) {
+    this.attach();
+    const t = setInterval(() => {
+      this.reconcileOnce().catch(() => {}); // never let the timer die
+    }, reconcileMs);
+    t.unref?.();
+    return { stop: () => clearInterval(t) };
+  }
+
+  async reconcileOnce() {
+    for (const [offerId, o] of this.offers) {
+      if (o.state === STATES.PAID) await this._release(offerId, o);
+    }
+  }
+
+  /* ------------------------------------------------ handlers ----------- */
+
+  async onOffer(env) {
+    const p = env.payload ?? {};
+    const { terms, sellerSig, contentKeyHex } = p;
+    // escrowHandle is rail-scoped: this escrow's identity on the rail the
+    // terms name (v1: the zilligon handle; v2 evm: the 0x address).
+    const rail = this.rails.for(terms ?? {});
+    const v = validateTerms(terms, { escrowUuaid: this.keychain._identity.uuaid, escrowHandle: rail?.handle ?? this.railHandle });
+    const senderOk = env.sender === terms?.seller;
+    const keyOk =
+      env.transportSignature?.publicKey != null && env.transportSignature.publicKey === terms?.sellerPubKeyHex;
+    const bad = (code, message) => this._errorTo(terms, "seller", code, message);
+    if (!terms || !v.ok) return bad(v?.reason ?? "bad-terms", "terms invalid");
+    if (!rail) return bad("rail-unsupported", "this escrow has no rail for these terms");
+    if (this.tokenRegistry) {
+      const pol = this.tokenRegistry.checkTerms(terms);
+      if (!pol.ok) return bad(pol.reason, pol.message);
+    }
+    if (!senderOk || !keyOk) return bad("identity-mismatch", "offer sender does not match signed terms");
+    if (!HEX64.test(contentKeyHex ?? "")) return bad("bad-key", "contentKeyHex must be 64 hex chars (32 bytes)");
+    if (!verifyTermsSig(terms.sellerPubKeyHex, terms, sellerSig)) return bad("bad-signature", "seller signature invalid");
+
+    const existing = this.offers.get(terms.offerId);
+    if (!existing) {
+      this.offers.set(terms.offerId, {
+        state: STATES.OPEN, terms, contentKeyHex, sellerSig, payoutAttempted: false, payoutDone: false,
+      });
+      this._append({ event: "offered", offerId: terms.offerId, terms, sellerSig, contentKeyHex });
+      this.metrics.inc("escrow.offer");
+      this._gaugeOffers();
+    }
+    await this._sendTo(terms, "seller", "escrow.offer-ack", { offerId: terms.offerId });
+  }
+
+  async onAccept(env) {
+    const p = env.payload ?? {};
+    const { offerId, buyerSig } = p;
+    const o = this.offers.get(offerId);
+    const bad = (code, message) => this._errorTo(o?.terms, "buyer", code, message);
+    if (!o || !o.terms) return bad("unknown-offer", "no such open offer");
+    const { terms } = o;
+    if (o.state !== STATES.OPEN) {
+      if (o.state === STATES.ACCEPTED) return this._ackAccept(o); // idempotent re-ack
+      return bad("not-open", `offer is ${o.state}`);
+    }
+    if (env.sender !== terms.buyer) return bad("identity-mismatch", "only the named buyer may accept");
+    if (env.transportSignature?.publicKey !== terms.buyerPubKeyHex) return bad("identity-mismatch", "accept key does not match terms");
+    if (!verifyTermsSig(terms.buyerPubKeyHex, terms, buyerSig)) return bad("bad-signature", "buyer signature invalid");
+    if (Date.now() > Date.parse(terms.expiresAt)) return bad("expired", "offer expired");
+
+    o.state = STATES.ACCEPTED;
+    o.buyerSig = buyerSig;
+    this._append({ event: "accepted", offerId, buyerSig });
+    this.metrics.inc("escrow.accept");
+    this._gaugeOffers();
+    await this._ackAccept(o);
+  }
+
+  async _ackAccept(o) {
+    await this._sendTo(o.terms, "buyer", "escrow.accept-ack", { offerId: o.terms.offerId });
+  }
+
+  async onPaid(env) {
+    const p = env.payload ?? {};
+    const { offerId, txId, sourceId } = p;
+    const o = this.offers.get(offerId);
+    const bad = (code, message) => this._errorTo(o?.terms, "buyer", code, message);
+    if (!o || !o.terms) return bad("unknown-offer", "no such offer");
+    const { terms } = o;
+    if (env.sender !== terms.buyer) return bad("identity-mismatch", "only the named buyer may claim payment");
+    if (typeof txId !== "string" || !txId) return bad("bad-txid", "txId required");
+    if (sourceId !== undefined && (typeof sourceId !== "string" || !sourceId)) return bad("bad-sourceid", "sourceId must be a non-empty string");
+    if (o.state === STATES.OPEN) return bad("not-accepted", "buyer must accept before paying");
+    if (o.state === STATES.RELEASED) return; // already done — nothing to do
+    if (Date.now() > Date.parse(terms.expiresAt) + PAID_GRACE_MS) return bad("expired", "paid-claim past grace window");
+
+    // A corrected claim may replace a wrong txId any time before the payout
+    // is attempted — after that the settled instrument is pinned for good.
+    const claimChanged = Boolean(o.payTxId) &&
+      (txId !== o.payTxId || (sourceId ?? null) !== (o.paySourceId ?? null));
+    if (o.state === STATES.ACCEPTED || !o.payTxId || (claimChanged && !o.payoutAttempted)) {
+      o.state = STATES.PAID;
+      o.payTxId = txId;
+      o.paySourceId = sourceId ?? undefined;
+      this._append({ event: "paid", offerId, txId, sourceId: sourceId ?? null });
+      this.metrics.inc("escrow.paid");
+      this._gaugeOffers();
+    }
+    await this._release(offerId, o);
+  }
+
+  /* ------------------------------------------------ release ------------- */
+
+  /**
+   * Per-offer in-flight guard.  _release has awaits between "check
+   * payoutAttempted" and "set payoutAttempted"; unserialized entry points
+   * (onPaid, the reconcile timer, carrier redelivery) racing through that
+   * gap would each prepare a payout — at DISTINCT nonces now that the rail
+   * serializes preps — and pay the seller twice.  The flag is set
+   * synchronously before the first await, so the single-threaded event loop
+   * makes the check-and-set atomic; a bounced caller simply leaves the offer
+   * to the run in flight (reconcile retries anything unfinished).
+   * Transient by design: never journaled, resets on restart.
+   */
+  async _release(offerId, o) {
+    if (o._releasing) return;
+    o._releasing = true;
+    try {
+      return await this._releaseLocked(offerId, o);
+    } finally {
+      o._releasing = false;
+    }
+  }
+
+  async _releaseLocked(offerId, o) {
+    const t0 = Date.now();
+    const { terms } = o;
+    const rail = this.rails.for(terms);
+    if (!rail) {
+      await this._errorTo(terms, "buyer", "rail-unsupported", "this escrow has no rail for these terms");
+      return;
+    }
+    const view = railViewOfTerms(terms); // decimal-string amounts, any version
+
+    // 1. attest the buyer's payment from the escrow's OWN instrument
+    //    (zilligon: its wallet rows; evm: the chain's receipt at depth) —
+    //    independent of the claimed txId.  Not found -> tell the buyer; stay
+    //    PAID so a later reconcile or a corrected claim can retry.
+    const tAttest = Date.now();
+    const hit = await rail.attestPayment({
+      fromHandle: terms.buyerHandle,
+      amount: view.price,
+      txId: o.payTxId,
+      sourceId: o.paySourceId ?? null,
+      asset: view.asset,
+    });
+    this.metrics.observe("escrow.attest.latencyMs", Date.now() - tAttest);
+    if (!hit) {
+      await this._errorTo(terms, "buyer", "payment-not-attested", "no matching payment on the escrow's rail instrument");
+      this.metrics.observe("escrow.release.latencyMs", Date.now() - t0);
+      return;
+    }
+    const payTxId = hit.txId ?? o.payTxId;
+    const paySourceId = hit.sourceId ?? o.paySourceId ?? null;
+
+    // Single-use payment: the attested instrument (txId, and the wallet row
+    // on rails that have one) is consumed by exactly one offer.  Without
+    // this, one real payment could attest N same-priced offers and drain
+    // the escrow's rail balance via sock-puppet sellers.
+    const payKeys = this._payKeys(rail.railKey, payTxId, paySourceId);
+    const clash = payKeys.find((k) => this.consumedPayTx.get(k) !== undefined && this.consumedPayTx.get(k) !== offerId);
+    if (clash) {
+      this.metrics.inc("escrow.payment-already-consumed");
+      await this._errorTo(terms, "buyer", "payment-already-consumed", "this payment already settled a different offer");
+      this.metrics.observe("escrow.release.latencyMs", Date.now() - t0);
+      return;
+    }
+    if (payKeys.some((k) => !this.consumedPayTx.has(k))) {
+      for (const k of payKeys) this.consumedPayTx.set(k, offerId);
+      this._append({ event: "pay-consumed", offerId, keys: payKeys });
+    }
+
+    // 2. pay the seller (escrowSend recomputed from the signed terms — no
+    //    in-memory state needed after a crash).  Journal payout-attempt
+    //    BEFORE the irreversible rail action; rails with a prepare step
+    //    (evm) sign FIRST so the journaled attempt carries the exact bytes
+    //    a recovery re-broadcasts (same nonce -> double-pay impossible).
+    //    Rails without one (zilligon) de-dup on recovery via
+    //    findPriorPayout's wallet scan.  escrowSend can legitimately be 0
+    //    (explicit zero payout): nothing to send, mark done.
+    if (!o.payoutDone) {
+      const escrowSend = view.escrowSend;
+      const zeroSend = BigInt(escrowSend) === 0n;
+      if (!o.payoutAttempted) {
+        let prepared = null;
+        if (!zeroSend) {
+          try {
+            prepared = await rail.preparePayout({ toHandle: terms.sellerHandle, amount: escrowSend, asset: view.asset });
+          } catch (e) {
+            this.metrics.inc("escrow.payout-failed");
+            await this._errorTo(terms, "seller", "payout-failed", String(e.message ?? e));
+            this.metrics.observe("escrow.release.latencyMs", Date.now() - t0);
+            return; // nothing journaled, nothing signed reached the rail
+          }
+        }
+        o.payoutAttempted = true;
+        o.payoutPrepared = prepared ?? null;
+        this._append({
+          event: "payout-attempt", offerId,
+          amount: view.v === 1 ? Number(escrowSend) : escrowSend,
+          ...(prepared ? { prepared } : {}),
+        });
+        this.metrics.inc("escrow.payout-attempt");
+      } else if (!zeroSend) {
+        // crashed between attempt and sent?  ask the rail for the payout we
+        // may already have made (evm: exact receipt of the journaled tx;
+        // zilligon: wallet-row scan with retries)
+        const prior = await rail.findPriorPayout({
+          toHandle: terms.sellerHandle, amount: escrowSend,
+          prepared: o.payoutPrepared ?? null, asset: view.asset,
+        });
+        if (prior?.txId) {
+          o.releaseTxId = prior.txId;
+          o.releaseSourceId = prior.sourceId ?? null;
+          o.payoutDone = true;
+          this._append({ event: "payout-sent", offerId, releaseTxId: o.releaseTxId, releaseSourceId: o.releaseSourceId });
+        } else if (typeof rail.payoutStatus === "function") {
+          // Not landed.  If the prepared bytes are provably DEAD (reverted,
+          // or the nonce was consumed at finalized depth by a different tx —
+          // e.g. a concurrent offer's payout), re-prepare with a fresh nonce.
+          // "pending" keeps re-broadcasting the same bytes — never two live
+          // signed payouts for one offer.  A missing prepared (journal tail
+          // from a crash mid-recovery) is treated as invalidated: the bytes
+          // are unrecoverable and were never broadcast.
+          const st = !o.payoutPrepared
+            ? { state: "invalidated", reason: "missing-prepared" }
+            : await rail.payoutStatus({ prepared: o.payoutPrepared }).catch(() => ({ state: "pending" }));
+          if (st.state === "invalidated") {
+            // Re-prepare FIRST, then journal ONE combined event (the fresh
+            // attempt, carrying what it supersedes).  A crash between the two
+            // replays to the OLD prepared bytes; payoutStatus re-derives
+            // "invalidated" and this branch re-runs — idempotent, and the
+            // lost signed bytes were never broadcast.
+            const dead = o.payoutPrepared;
+            let prepared;
+            try {
+              prepared = await rail.preparePayout({ toHandle: terms.sellerHandle, amount: escrowSend, asset: view.asset });
+            } catch (e) {
+              this.metrics.inc("escrow.payout-failed");
+              await this._errorTo(terms, "seller", "payout-failed", String(e.message ?? e));
+              this.metrics.observe("escrow.release.latencyMs", Date.now() - t0);
+              return; // nothing journaled, nothing broadcast; retry next reconcile
+            }
+            o.payoutPrepared = prepared ?? null;
+            this._append({
+              event: "payout-attempt", offerId,
+              amount: view.v === 1 ? Number(escrowSend) : escrowSend,
+              ...(prepared ? { prepared } : {}),
+              supersedes: { ...(dead ? { txId: dead.txId, nonce: dead.nonce } : {}), reason: st.reason },
+            });
+            this.metrics.inc("escrow.payout-invalidated");
+            this.metrics.inc("escrow.payout-attempt");
+          }
+        }
+      }
+      if (!o.payoutDone) {
+        if (!zeroSend) {
+          let res;
+          try {
+            res = await rail.sendPayout({
+              toHandle: terms.sellerHandle, amount: escrowSend,
+              prepared: o.payoutPrepared ?? null, asset: view.asset,
+            });
+          } catch (e) {
+            this.metrics.inc("escrow.payout-failed");
+            await this._errorTo(terms, "seller", "payout-failed", String(e.message ?? e));
+            this.metrics.observe("escrow.release.latencyMs", Date.now() - t0);
+            return; // stay PAID; reconcile will de-dup and retry
+          }
+          o.releaseTxId = res?.txId ?? null;
+          o.releaseSourceId = res?.sourceId ?? null;
+        } else {
+          o.releaseTxId = null; // zero payout — nothing to send on the rail
+          o.releaseSourceId = null;
+          this.metrics.inc("escrow.payout-zero");
+        }
+        o.payoutDone = true;
+        this._append({ event: "payout-sent", offerId, releaseTxId: o.releaseTxId, releaseSourceId: o.releaseSourceId ?? null });
+        this.metrics.inc("escrow.payout-sent");
+      }
+    }
+
+    // Receipt economics mirror the terms version: v1 keeps the Gons fields
+    // byte-compatible; v2 carries {rail, chainId, asset, price, sellerPayout}.
+    const econ = view.v === 2
+      ? { v: 2, rail: terms.rail, chainId: terms.chainId, asset: terms.asset, price: terms.price, sellerPayout: terms.sellerPayout }
+      : { priceGons: terms.priceGons, sellerPayoutGons: terms.sellerPayoutGons };
+
+    // 3. release K + buyer receipt to the buyer (re-sending is harmless —
+    //    decryption is idempotent — but the marker keeps the journal tidy).
+    if (!o.keySent) {
+      const receipt = makeReceipt(this.keychain, {
+        offerId, role: "buyer", escrow: terms.escrow, buyer: terms.buyer, seller: terms.seller,
+        itemHash: terms.itemHash, ...econ,
+        payTxId, releaseTxId: o.releaseTxId,
+        paySourceId, releaseSourceId: o.releaseSourceId ?? null,
+      });
+      await this._sendTo(terms, "buyer", "escrow.key", {
+        offerId, contentKeyHex: o.contentKeyHex, receipt,
+      });
+      o.keySent = true;
+      this._append({ event: "key-sent", offerId });
+      this.metrics.inc("escrow.key-sent");
+    }
+
+    // 4. seller receipt — the seller's proof of completion.
+    if (o.state !== STATES.RELEASED) {
+      const receipt = makeReceipt(this.keychain, {
+        offerId, role: "seller", escrow: terms.escrow, buyer: terms.buyer, seller: terms.seller,
+        itemHash: terms.itemHash, ...econ,
+        payTxId, releaseTxId: o.releaseTxId,
+        paySourceId, releaseSourceId: o.releaseSourceId ?? null,
+      });
+      await this._sendTo(terms, "seller", "escrow.receipt", { offerId, receipt });
+      o.state = STATES.RELEASED;
+      this._append({ event: "released", offerId });
+      this.metrics.inc("escrow.released");
+      this._gaugeOffers();
+    }
+    this.metrics.observe("escrow.release.latencyMs", Date.now() - t0);
+  }
+
+  /* ------------------------------------------------ metrics ------------- */
+
+  /** Mirror offer-map state into gauges so dashboards see the escrow queue. */
+  _gaugeOffers() {
+    this.metrics.setGauge("escrow.offers.total", this.offers.size);
+    for (const state of Object.values(STATES)) {
+      let n = 0;
+      for (const o of this.offers.values()) if (o.state === state) n += 1;
+      this.metrics.setGauge(`escrow.offers.${state}`, n);
+    }
+  }
+
+  /* ------------------------------------------------ helpers ------------- */
+
+  async _sendTo(terms, party, kind, payload) {
+    if (!terms) return;
+    await this.pillar.send({
+      recipient: terms[party],
+      recipientPublicKey: terms[`${party}PubKeyHex`],
+      kind,
+      payload,
+    });
+  }
+
+  async _errorTo(terms, party, code, message) {
+    this.metrics.inc(`escrow.error.${code}`);
+    if (!terms) return;
+    try {
+      await this._sendTo(terms, party, "escrow.error", {
+        offerId: terms.offerId ?? null, code, message,
+      });
+    } catch (_e) {
+      /* error path is best-effort */
+    }
+  }
+}
+
+export { verifyReceiptSig };