@unicitylabs/sphere-sdk 0.14.0-dev.5 → 0.14.0-dev.6

package/dist/modules/payments-v2/index.cjs

@@ -31,6 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var payments_v2_exports = {};
 __export(payments_v2_exports, {
   ATTENTION_MINT_UNRESOLVED: () => ATTENTION_MINT_UNRESOLVED,
+  HEARTBEAT_CAP_MS: () => HEARTBEAT_CAP_MS,
+  HEARTBEAT_SEED_MS: () => HEARTBEAT_SEED_MS,
   MAX_RESELECT: () => MAX_RESELECT,
   PaymentsFacade: () => PaymentsFacade,
   STORE_KEYS: () => STORE_KEYS,
@@ -590,6 +592,10 @@ function isValidationReject(err) {
   if (e === null) return false;
   return e.status === 422 || e.statusCode === 422 || e.code === "VALIDATION" || e.code === "VALIDATION_FAILED";
 }
+function retryAfterMsOf(err) {
+  const retryAfter = err !== null && typeof err === "object" ? err.retryAfter : void 0;
+  return typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter : null;
+}
 var chainRegistry = /* @__PURE__ */ new WeakMap();
 var replayRegistry = /* @__PURE__ */ new WeakMap();
 function registryFor(registry, kv, storeKey, make) {
@@ -1266,6 +1272,217 @@ function validatePayload(raw) {
   return p;
 }
 
+// modules/payments-v2/convergence.ts
+var HEARTBEAT_SEED_MS = 5e3;
+var HEARTBEAT_CAP_MS = 12e4;
+var ConvergenceHeartbeat = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  timer = null;
+  delayMs = HEARTBEAT_SEED_MS;
+  notBefore = 0;
+  running = false;
+  start() {
+    this.running = true;
+    this.delayMs = HEARTBEAT_SEED_MS;
+    this.notBefore = 0;
+  }
+  /** §7 quiescence unchanged: a mid-backoff stop() cancels cleanly. */
+  stop() {
+    this.running = false;
+    this.clearTimer();
+  }
+  /** Reset to seed on progress, ×2 to the cap otherwise; idle stops rescheduling. */
+  settle(outcome, pending) {
+    if (outcome.retryAfterMs !== null) {
+      this.notBefore = Math.max(this.notBefore, this.deps.now() + outcome.retryAfterMs);
+    }
+    if (!pending) {
+      this.delayMs = HEARTBEAT_SEED_MS;
+      return;
+    }
+    const delay = outcome.progress ? HEARTBEAT_SEED_MS : this.delayMs;
+    this.delayMs = Math.min(delay * 2, HEARTBEAT_CAP_MS);
+    this.schedule(delay);
+  }
+  /** New pending work (keep-open park / journaled delivery / mint hold): prompt retry. */
+  arm() {
+    if (!this.running) return;
+    this.delayMs = Math.min(HEARTBEAT_SEED_MS * 2, HEARTBEAT_CAP_MS);
+    this.schedule(HEARTBEAT_SEED_MS);
+  }
+  /** connection:status recovery: the backoff resets; a pending tick re-fires at the seed. */
+  recovered() {
+    this.delayMs = HEARTBEAT_SEED_MS;
+    if (this.timer !== null) this.arm();
+  }
+  schedule(delayMs) {
+    this.clearTimer();
+    if (!this.running) return;
+    const floored = Math.max(delayMs, this.notBefore - this.deps.now());
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.deps.onTick();
+    }, floored);
+  }
+  clearTimer() {
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+  }
+};
+var Converger = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /** Resume open intents, then drain the delivery + mint journals (all idempotent). */
+  async convergeOnce() {
+    let progress = false;
+    let retryAfterMs = null;
+    try {
+      progress = await this.resumePass();
+    } catch (err) {
+      retryAfterMs = retryAfterMsOf(err);
+    }
+    try {
+      const stats = await this.deps.stores.deliveryJournal.replay(this.replayDeps());
+      progress = progress || stats.delivered > 0;
+    } catch (err) {
+      retryAfterMs ??= retryAfterMsOf(err);
+    }
+    try {
+      progress = await this.deps.replayMints() > 0 || progress;
+    } catch (err) {
+      retryAfterMs ??= retryAfterMsOf(err);
+    }
+    return { progress, retryAfterMs };
+  }
+  /** §4 heartbeat predicate — read fresh from the §6 stores, never cached. */
+  async pendingWork() {
+    const [backstop, journal, mints] = await Promise.all([
+      this.deps.stores.backstop.list(),
+      this.deps.stores.deliveryJournal.list(),
+      this.deps.stores.mintJournal.list()
+    ]);
+    return backstop.length > 0 || journal.some((e) => e.undeliverable !== true) || mints.length > 0;
+  }
+  async resumePass() {
+    const report = await resumeAll(this.filteredMachineDeps());
+    const progress = report.resumed.length > 0 || report.conflicted.length > 0;
+    await this.deps.reconcile({
+      resumed: report.resumed,
+      conflicted: report.conflicted,
+      open: report.failed
+    });
+    if (progress) await this.deps.refreshView().catch(() => void 0);
+    return progress;
+  }
+  filteredMachineDeps() {
+    const intents = this.deps.machineDeps.intents;
+    return {
+      ...this.deps.machineDeps,
+      intents: {
+        ...intents,
+        listOpen: async () => (await intents.listOpen()).filter((intent) => !this.deps.isActiveOp(intent.transferId))
+      }
+    };
+  }
+  replayDeps() {
+    return {
+      delivery: this.deps.delivery,
+      now: () => this.deps.now(),
+      attention: (transferId, code, detail) => {
+        this.deps.emit(
+          "transfer:attention",
+          detail === void 0 ? { transferId, code } : { transferId, code, detail }
+        );
+      }
+    };
+  }
+};
+async function derivePendingTransfers(stores, decryptPayload) {
+  const [backstop, journal, shortfalls] = await Promise.all([
+    stores.backstop.list(),
+    stores.deliveryJournal.list(),
+    stores.shortfalls.list()
+  ]);
+  const byTransfer = groupJournal(journal);
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of backstop) {
+    if (entry.disposition !== "open") continue;
+    seen.add(entry.transferId);
+    out.push(await openRow(entry, byTransfer.get(entry.transferId) ?? [], decryptPayload));
+  }
+  for (const [transferId, entries] of byTransfer) {
+    if (seen.has(transferId)) continue;
+    seen.add(transferId);
+    out.push(journalOnlyRow(transferId, entries));
+  }
+  for (const entry of shortfalls) {
+    if (!seen.has(entry.transferId)) out.push(shortfallRow(entry));
+  }
+  return out;
+}
+function groupJournal(journal) {
+  const byTransfer = /* @__PURE__ */ new Map();
+  for (const entry of journal) {
+    const mine = byTransfer.get(entry.transferId);
+    if (mine === void 0) byTransfer.set(entry.transferId, [entry]);
+    else mine.push(entry);
+  }
+  return byTransfer;
+}
+async function openRow(entry, journal, decryptPayload) {
+  let payload = null;
+  try {
+    const raw = await decryptPayload(entry.payloadEnvelope);
+    if (raw !== null && typeof raw === "object") payload = raw;
+  } catch {
+    payload = null;
+  }
+  const total = Array.isArray(payload?.direct) ? payload.direct.length + (payload.split !== void 0 ? 1 : 0) : 0;
+  const certified = distinctOpCount(journal);
+  return {
+    transferId: entry.transferId,
+    kind: "open",
+    recipient: typeof payload?.recipient === "string" ? payload.recipient : "",
+    coinId: typeof payload?.coinId === "string" ? payload.coinId : "",
+    amount: typeof payload?.amount === "string" ? payload.amount : "",
+    legs: { certified, total: Math.max(total, certified) },
+    deliveryPending: journal.length > 0,
+    createdAt: entry.createdAt
+  };
+}
+function journalOnlyRow(transferId, entries) {
+  const certified = distinctOpCount(entries);
+  return {
+    transferId,
+    kind: "open",
+    recipient: entries[0].recipientPubkey,
+    coinId: "",
+    amount: "",
+    legs: { certified, total: certified },
+    deliveryPending: true,
+    createdAt: 0
+  };
+}
+function shortfallRow(entry) {
+  return {
+    transferId: entry.transferId,
+    kind: "shortfall",
+    recipient: entry.recipient,
+    coinId: entry.coinId,
+    amount: entry.remainingAmount,
+    legs: { certified: entry.committedTokenIds.length, total: entry.committedTokenIds.length },
+    deliveryPending: false,
+    createdAt: entry.createdAt
+  };
+}
+function distinctOpCount(entries) {
+  return new Set(entries.map((entry) => entry.opIndex)).size;
+}
+
 // node_modules/@noble/ciphers/utils.js
 function isBytes2(a) {
   return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array" && "BYTES_PER_ELEMENT" in a && a.BYTES_PER_ELEMENT === 1;
@@ -3597,6 +3814,21 @@ var PaymentsFacade = class {
     this.ownPubkeyBytes = parts.ownPubkeyBytes;
     this.requests = parts.requests;
     deps.deliveryPort.bindDeliveryKeys((blob) => this.engine().deliveryKeys(blob));
+    this.heartbeat = new ConvergenceHeartbeat({
+      now: () => this.nowMs(),
+      onTick: () => this.trackTail(this.runConvergencePass())
+    });
+    this.converger = new Converger({
+      machineDeps: this.machineDeps,
+      stores: this.machineStores,
+      delivery: deps.deliveryPort,
+      reconcile: (report) => this.requests.reconcile(report),
+      refreshView: () => this.view.delta(),
+      replayMints: () => this.replayMints(),
+      isActiveOp: (id) => this.activeMoneyOps.has(id),
+      emit: deps.emit,
+      now: () => this.nowMs()
+    });
   }
   view;
   ledger;
@@ -3613,10 +3845,18 @@ var PaymentsFacade = class {
   pendingOps = /* @__PURE__ */ new Set();
   unsubscribers = [];
   started = false;
+  // §7 heartbeat: in-memory timing cell + pass runner (see convergence.ts).
+  heartbeat;
+  converger;
+  /** Resume single-flight (§7): ticks, start() and resumeNow() coalesce onto ONE pass. */
+  resumeFlight = new SingleFlight();
+  /** §7 ownership: ids with an in-process machine attempt — the pass never adopts one. */
+  activeMoneyOps = /* @__PURE__ */ new Set();
   // ── lifecycle ──────────────────────────────────────────────────────────────
   async start() {
     if (this.started) return;
     this.started = true;
+    this.heartbeat.start();
     await this.deps.session.start();
     this.unsubscribers.push(
       this.deps.session.subscribeStream("mailbox", () => {
@@ -3629,20 +3869,11 @@ var PaymentsFacade = class {
         this.trackTail(this.requests.drainIncoming());
       })
     );
-    this.trackTail(this.runResume());
-    this.trackTail(
-      this.machineStores.deliveryJournal.replay({
-        delivery: this.deps.deliveryPort,
-        now: this.deps.now ?? Date.now,
-        attention: (transferId, code, detail) => {
-          this.deps.emit(
-            "transfer:attention",
-            detail === void 0 ? { transferId, code } : { transferId, code, detail }
-          );
-        }
-      })
-    );
-    this.trackTail(this.replayMints());
+    const statusUnsub = this.deps.session.subscribeStatus?.((status) => {
+      if (status === "connected") this.heartbeat.recovered();
+    });
+    if (statusUnsub !== void 0) this.unsubscribers.push(statusUnsub);
+    this.trackTail(this.runConvergencePass());
     this.trackTail(this.seedHeldStates());
     await this.view.fullPull().catch(() => void 0);
     this.receiveLoop.start(this.deps.receivePollMs);
@@ -3650,6 +3881,7 @@ var PaymentsFacade = class {
   /** §7 same-address restart gate: resolves only after in-flight ops settle. */
   async stop() {
     this.started = false;
+    this.heartbeat.stop();
     this.receiveLoop.stop();
     for (const unsubscribe of this.unsubscribers) unsubscribe();
     this.unsubscribers = [];
@@ -3675,6 +3907,10 @@ var PaymentsFacade = class {
   history(page) {
     return this.historyStore.page(page ?? {});
   }
+  /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
+  pendingTransfers() {
+    return derivePendingTransfers(this.machineStores, this.machineDeps.decryptPayload);
+  }
   // ── money movement ─────────────────────────────────────────────────────────
   send(request) {
     return this.track(this.sendWithPolicy(request));
@@ -3687,6 +3923,22 @@ var PaymentsFacade = class {
   mint(coinId, amount) {
     return this.track(this.mintInner(coinId, amount));
   }
+  // §4 retry verb: coalesces onto the running pass — NEVER re-issue send() (#631/#676).
+  async resumeNow() {
+    if (!this.started) return;
+    await this.track(this.runConvergencePass());
+  }
+  /** One single-flighted pass + its reschedule: concurrent callers coalesce. */
+  runConvergencePass() {
+    return this.resumeFlight.run(async () => {
+      const outcome = await this.converger.convergeOnce();
+      const pending = await this.converger.pendingWork().catch(() => true);
+      this.heartbeat.settle(outcome, pending);
+    });
+  }
+  nowMs() {
+    return (this.deps.now ?? Date.now)();
+  }
   // ── send policy (§5.5 + old-loop parity; the machine stays policy-free) ────
   async sendWithPolicy(request) {
     const recipient = await this.requireSameNetworkRecipient(request.recipient);
@@ -3736,12 +3988,15 @@ var PaymentsFacade = class {
     return recipient;
   }
   async runAttempt(ctx) {
+    this.activeMoneyOps.add(ctx.transferId);
     try {
       const { deliveryPending } = await this.machine.run(ctx.plan);
       this.settleSuccess(ctx, ctx.sourceIds);
       return { kind: "success", deliveryPending };
     } catch (err) {
-      return this.disposeFailedAttempt(ctx, err);
+      return await this.disposeFailedAttempt(ctx, err);
+    } finally {
+      this.activeMoneyOps.delete(ctx.transferId);
     }
   }
   /**
@@ -3750,7 +4005,10 @@ var PaymentsFacade = class {
    * the remainder under a NEW transferId — never the full amount.
    */
   async consumePartial(ctx, disposition, run, attempt) {
-    run.pendingAny = run.pendingAny || disposition.deliveryPending;
+    if (disposition.deliveryPending) {
+      run.pendingAny = true;
+      this.heartbeat.arm();
+    }
     const partial = disposition.entry;
     run.delivered.push(...partial.committedTokenIds);
     run.firstPartialId ??= partial.transferId;
@@ -3908,6 +4166,7 @@ var PaymentsFacade = class {
   /** Open intent: sources stay reserved + in-flight (§5.2) until resume adopts them. */
   settleKeepOpen(ctx) {
     this.queue.clearExpectedChange(ctx.transferId);
+    this.heartbeat.arm();
   }
   settlePartial(ctx, partial) {
     this.ledger.cancel(ctx.transferId);
@@ -3944,6 +4203,7 @@ var PaymentsFacade = class {
     for (const id of run.settledShortfalls.splice(0)) {
       await this.machineStores.shortfalls.removeByKey(id).catch(() => void 0);
     }
+    if (run.pendingAny) this.heartbeat.arm();
     const result = {
       id: transferId,
       status: run.pendingAny ? "confirmed" : "delivered",
@@ -3988,21 +4248,29 @@ var PaymentsFacade = class {
     if (!/^(?:[0-9a-f]{2})+$/.test(coinId) || amount <= 0n) {
       return { success: false, error: "coinId must be even-length lowercase hex and amount positive" };
     }
-    const engine = this.engine();
     const mintId = this.newId();
-    const params = this.mintParams(coinId, amount);
+    this.activeMoneyOps.add(mintId);
+    try {
+      return await this.mintUnderJournal(mintId, coinId, amount);
+    } finally {
+      this.activeMoneyOps.delete(mintId);
+    }
+  }
+  async mintUnderJournal(mintId, coinId, amount) {
+    const engine = this.engine();
     const entry = {
       mintId,
       coinId,
       amount: amount.toString(),
       tokenId: "",
-      createdAt: (this.deps.now ?? Date.now)()
+      createdAt: this.nowMs()
     };
     await this.machineStores.mintJournal.upsert(entry);
     let token;
     try {
-      token = await engine.mint(params, { transferId: mintId });
+      token = await engine.mint(this.mintParams(coinId, amount), { transferId: mintId });
     } catch (err) {
+      this.heartbeat.arm();
       return { success: false, error: messageOf(err) };
     }
     if (token.blob.tokenId !== entry.tokenId) {
@@ -4011,6 +4279,7 @@ var PaymentsFacade = class {
     try {
       await this.finalizeMint(engine, mintId, token, coinId, amount.toString());
     } catch (err) {
+      this.heartbeat.arm();
       return { success: false, tokenId: token.blob.tokenId, error: messageOf(err) };
     }
     return { success: true, tokenId: token.blob.tokenId };
@@ -4033,18 +4302,22 @@ var PaymentsFacade = class {
     this.heldStates.set(token.blob.tokenId, (await engine.deliveryKeys(bytes)).stateHash);
     this.trackTail(this.view.delta());
   }
+  /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
   async replayMints() {
+    let resolved = 0;
     for (const entry of await this.machineStores.mintJournal.list()) {
+      if (this.activeMoneyOps.has(entry.mintId)) continue;
       try {
-        await this.replayMint(entry);
+        if (await this.replayMint(entry)) resolved += 1;
       } catch {
       }
     }
+    return resolved;
   }
   async replayMint(entry) {
     if (entry.tokenId !== "" && await this.tokenInServerInventory(entry.tokenId)) {
       await this.machineStores.mintJournal.removeByKey(entry.mintId);
-      return;
+      return true;
     }
     const engine = this.engine();
     if (!supportsDeterministicMint(engine)) {
@@ -4052,7 +4325,7 @@ var PaymentsFacade = class {
         transferId: entry.mintId,
         code: ATTENTION_MINT_UNRESOLVED
       });
-      return;
+      return false;
     }
     const token = await engine.mint(this.mintParams(entry.coinId, BigInt(entry.amount)), {
       transferId: entry.mintId
@@ -4061,6 +4334,7 @@ var PaymentsFacade = class {
       await this.machineStores.mintJournal.upsert({ ...entry, tokenId: token.blob.tokenId });
     }
     await this.finalizeMint(engine, entry.mintId, token, entry.coinId, entry.amount);
+    return true;
   }
   mintParams(coinId, amount) {
     return {
@@ -4086,17 +4360,6 @@ var PaymentsFacade = class {
   newId() {
     return (this.deps.newId ?? randomUUID)();
   }
-  async runResume() {
-    const report = await resumeAll(this.machineDeps);
-    await this.requests.reconcile({
-      resumed: report.resumed,
-      conflicted: report.conflicted,
-      open: report.failed
-    });
-    if (report.resumed.length > 0 || report.conflicted.length > 0) {
-      await this.view.delta().catch(() => void 0);
-    }
-  }
   async seedHeldStates() {
     let page = await this.deps.storagePort.listInventory();
     for (let i = 0; i < INVENTORY_SCAN_PAGE_LIMIT; i++) {
@@ -4110,7 +4373,7 @@ var PaymentsFacade = class {
   toUiToken(tokenId, coinId, amount) {
     const registry = this.deps.registry;
     const iconUrl = registry.getIconUrl(coinId);
-    const now = (this.deps.now ?? Date.now)();
+    const now = this.nowMs();
     return {
       id: tokenId,
       coinId,
@@ -4162,6 +4425,8 @@ function messageOf(err) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ATTENTION_MINT_UNRESOLVED,
+  HEARTBEAT_CAP_MS,
+  HEARTBEAT_SEED_MS,
   MAX_RESELECT,
   PaymentsFacade,
   STORE_KEYS,