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

package/dist/index.d.cts

@@ -7432,6 +7432,25 @@ interface PaymentsRequestsApi {
     decline(id: string): Promise<void>;
     dismissProcessed(): void;
 }
+/**
+ * A pending-transfers row, derived ON READ from the §6 stores (intent backstop
+ * + delivery journal + shortfalls) — never a cached mirror. kind 'shortfall' =
+ * a completed partial (#690) whose `amount` is the remainder still owed;
+ * legs.certified counts journaled legs (certified, delivery still owed).
+ */
+interface PendingTransfer {
+    transferId: string;
+    kind: 'open' | 'shortfall';
+    recipient: string;
+    coinId: string;
+    amount: string;
+    legs: {
+        certified: number;
+        total: number;
+    };
+    deliveryPending: boolean;
+    createdAt: number;
+}
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -7446,6 +7465,8 @@ interface PaymentsV2 {
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
+    pendingTransfers(): Promise<PendingTransfer[]>;
+    resumeNow(): Promise<void>;
     readonly requests: PaymentsRequestsApi;
 }
 

package/dist/index.d.ts

@@ -7432,6 +7432,25 @@ interface PaymentsRequestsApi {
     decline(id: string): Promise<void>;
     dismissProcessed(): void;
 }
+/**
+ * A pending-transfers row, derived ON READ from the §6 stores (intent backstop
+ * + delivery journal + shortfalls) — never a cached mirror. kind 'shortfall' =
+ * a completed partial (#690) whose `amount` is the remainder still owed;
+ * legs.certified counts journaled legs (certified, delivery still owed).
+ */
+interface PendingTransfer {
+    transferId: string;
+    kind: 'open' | 'shortfall';
+    recipient: string;
+    coinId: string;
+    amount: string;
+    legs: {
+        certified: number;
+        total: number;
+    };
+    deliveryPending: boolean;
+    createdAt: number;
+}
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -7446,6 +7465,8 @@ interface PaymentsV2 {
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
+    pendingTransfers(): Promise<PendingTransfer[]>;
+    resumeNow(): Promise<void>;
     readonly requests: PaymentsRequestsApi;
 }
 

package/dist/index.js

@@ -27486,6 +27486,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) {
@@ -28123,6 +28127,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;
+}
+
 // modules/payments-v2/history/History.ts
 var WIRE_TOKEN_ID = /^(?:[0-9a-f]{2}){1,64}$/;
 var WIRE_PUBKEY = /^0[23][0-9a-f]{64}$/;
@@ -29512,6 +29727,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;
@@ -29528,10 +29758,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", () => {
@@ -29544,20 +29782,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);
@@ -29565,6 +29794,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 = [];
@@ -29590,6 +29820,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));
@@ -29602,6 +29836,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);
@@ -29651,12 +29901,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);
     }
   }
   /**
@@ -29665,7 +29918,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;
@@ -29823,6 +30079,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);
@@ -29859,6 +30116,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",
@@ -29903,21 +30161,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) {
@@ -29926,6 +30192,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 };
@@ -29948,18 +30215,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)) {
@@ -29967,7 +30238,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
@@ -29976,6 +30247,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 {
@@ -30001,17 +30273,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++) {
@@ -30025,7 +30286,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,
@@ -30420,6 +30681,7 @@ var WalletApiSession = class {
   reseedChain = Promise.resolve();
   reseedsPending = 0;
   handlers = /* @__PURE__ */ new Map();
+  statusHandlers = /* @__PURE__ */ new Set();
   socket = null;
   started = false;
   stopped = false;
@@ -30570,10 +30832,16 @@ var WalletApiSession = class {
   status() {
     return this.lastStatus ?? "offline";
   }
+  /** Transition feed off the existing emitStatus point (FacadeSession.subscribeStatus). */
+  subscribeStatus(handler) {
+    this.statusHandlers.add(handler);
+    return () => this.statusHandlers.delete(handler);
+  }
   emitStatus(status) {
     if (this.stopped || this.lastStatus === status) return;
     this.lastStatus = status;
     this.deps.emitStatus(status);
+    for (const handler of this.statusHandlers) handler(status);
   }
   async connect() {
     if (this.stopped) return;