@unicitylabs/sphere-sdk 0.14.10 → 0.14.11-dev.2

package/dist/modules/payments-v2/index.d.cts

@@ -228,6 +228,8 @@ interface PendingTransfer {
 }
 type ConnectionStatus = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
+    prewarmSend(request: SendRequest): Promise<void>;
+    discardPrewarm(): void;
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
         coinId?: string;
@@ -1042,6 +1044,7 @@ declare const MAX_RESELECT = 8;
 declare const ATTENTION_MINT_UNRESOLVED = "mint:unresolved";
 declare class PaymentsFacade implements PaymentsV2 {
     private readonly deps;
+    private readonly prewarmed;
     private readonly view;
     private readonly ledger;
     private readonly queue;
@@ -1086,6 +1089,9 @@ declare class PaymentsFacade implements PaymentsV2 {
     connectionStatus(): ConnectionStatus;
     /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
     pendingTransfers(): Promise<PendingTransfer[]>;
+    prewarmSend(request: SendRequest): Promise<void>;
+    discardPrewarm(): void;
+    private warmDeps;
     send(request: SendRequest): Promise<TransferResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
@@ -1142,12 +1148,10 @@ declare class PaymentsFacade implements PaymentsV2 {
     /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
     private replayMints;
     private replayMint;
-    private mintParams;
     private tokenInServerInventory;
     private engine;
     private newId;
     private seedHeldStates;
-    private toUiToken;
     private track;
     private trackTail;
 }

package/dist/modules/payments-v2/index.d.ts

@@ -228,6 +228,8 @@ interface PendingTransfer {
 }
 type ConnectionStatus = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
+    prewarmSend(request: SendRequest): Promise<void>;
+    discardPrewarm(): void;
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
         coinId?: string;
@@ -1042,6 +1044,7 @@ declare const MAX_RESELECT = 8;
 declare const ATTENTION_MINT_UNRESOLVED = "mint:unresolved";
 declare class PaymentsFacade implements PaymentsV2 {
     private readonly deps;
+    private readonly prewarmed;
     private readonly view;
     private readonly ledger;
     private readonly queue;
@@ -1086,6 +1089,9 @@ declare class PaymentsFacade implements PaymentsV2 {
     connectionStatus(): ConnectionStatus;
     /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
     pendingTransfers(): Promise<PendingTransfer[]>;
+    prewarmSend(request: SendRequest): Promise<void>;
+    discardPrewarm(): void;
+    private warmDeps;
     send(request: SendRequest): Promise<TransferResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
@@ -1142,12 +1148,10 @@ declare class PaymentsFacade implements PaymentsV2 {
     /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
     private replayMints;
     private replayMint;
-    private mintParams;
     private tokenInServerInventory;
     private engine;
     private newId;
     private seedHeldStates;
-    private toUiToken;
     private track;
     private trackTail;
 }

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

@@ -1600,6 +1600,90 @@ async function splitOpIndex(deps, envelope) {
   return Array.isArray(payload.direct) ? payload.direct.length : 0;
 }
 
+// modules/payments-v2/mint-params.ts
+function mintParams(recipientPubkey, coinId, amount) {
+  return { recipientPubkey, value: { assets: [{ coinId, amount }] } };
+}
+
+// modules/payments-v2/prewarm-cache.ts
+var PrewarmCache = class _PrewarmCache {
+  entries = /* @__PURE__ */ new Map();
+  generation = 0;
+  static key(tokenId, stateHash) {
+    return `${tokenId}:${stateHash}`;
+  }
+  /** Claim the cache for a warm about to start; supersedes any warm already running. */
+  begin() {
+    this.entries.clear();
+    this.generation += 1;
+    return this.generation;
+  }
+  /**
+   * Publish a warm's result, unless it was cancelled or superseded while its
+   * fetch was in flight — a cancel that only cleared what had landed so far
+   * would be undone by the continuation of the very warm it cancelled.
+   */
+  commit(generation, warmed) {
+    if (generation !== this.generation) return;
+    for (const [tokenId, stateHash, bytes] of warmed) {
+      this.entries.set(_PrewarmCache.key(tokenId, stateHash), bytes);
+    }
+  }
+  get(tokenId, stateHash) {
+    if (stateHash === void 0) return void 0;
+    return this.entries.get(_PrewarmCache.key(tokenId, stateHash));
+  }
+  clear() {
+    this.entries.clear();
+    this.generation += 1;
+  }
+  get size() {
+    return this.entries.size;
+  }
+};
+async function warmSendSources(deps, request) {
+  const ids = deps.queue.previewSelection(request);
+  if (ids.length === 0) return;
+  const generation = deps.cache.begin();
+  const at = new Map(ids.map((id) => [id, deps.view.stateHashOf(id)]));
+  let blobs;
+  try {
+    blobs = await deps.storagePort.getBlobs([...ids]);
+  } catch {
+    return;
+  }
+  const warmed = [];
+  for (const [tokenId, bytes] of blobs) {
+    const stateHash = at.get(tokenId);
+    if (stateHash !== void 0) warmed.push([tokenId, stateHash, bytes]);
+  }
+  deps.cache.commit(generation, warmed);
+}
+async function takeSourceBlobs(deps, sourceIds) {
+  const blobs = /* @__PURE__ */ new Map();
+  const missing = [];
+  let trustCache = deps.cache.size > 0;
+  if (trustCache) {
+    try {
+      await deps.view.delta();
+    } catch {
+      trustCache = false;
+    }
+  }
+  for (const tokenId of sourceIds) {
+    const warm = trustCache ? deps.cache.get(tokenId, deps.view.stateHashOf(tokenId)) : void 0;
+    if (warm === void 0) missing.push(tokenId);
+    else blobs.set(tokenId, warm);
+  }
+  deps.cache.clear();
+  if (missing.length > 0) {
+    for (const [tokenId, bytes] of await deps.storagePort.getBlobs(missing)) {
+      blobs.set(tokenId, bytes);
+    }
+  }
+  return blobs;
+}
+
 // modules/payments-v2/inventory/presentation.ts
 function toToken(tokenId, snapshot, asset, registry, flags) {
   const iconUrl = registry.getIconUrl(asset.coinId);
@@ -1686,6 +1770,13 @@ function priceOne(asset, quote) {
     fiatValueEur: quote.priceEur != null ? human * quote.priceEur : null
   };
 }
+function transferringToken(tokenId, coinId, amount, registry, now) {
+  const snapshot = { assets: [], createdAt: now, updatedAt: now };
+  return toToken(tokenId, snapshot, { coinId, amount: amount.toString() }, registry, {
+    transferring: true,
+    suspectedSpent: false
+  });
+}
 
 // modules/payments-v2/machine/payload.ts
 function buildPayload(recipientPubkey, request, spend, spentStates) {
@@ -2774,6 +2865,15 @@ var InventoryView = class {
     }
     return out;
   }
+  /**
+   * Current mirrored state of an ACTIVE token, or undefined when it is unknown
+   * or tombstoned. Exists so a cached blob can be state-scoped (F6): a blob is
+   * only reusable while the token still sits at the state it was fetched at.
+   */
+  stateHashOf(tokenId) {
+    const entry = this.mirror.get(tokenId);
+    return entry !== void 0 && entry.status === "active" ? entry.stateHash : void 0;
+  }
   tokens(registry, filter) {
     const out = [];
     for (const [tokenId, entry] of this.mirror) {
@@ -3053,6 +3153,7 @@ var logger = {
 
 // modules/payments-v2/receive/Receive.ts
 var ACK_BATCH_SIZE = 200;
+var REFRESH_INTERVAL_MS = 750;
 var POLL_INTERVAL_MS = 3e4;
 var ATTENTION_CLAIM_CONFLICT = "claim:conflict";
 function receivedDedupKey(tokenId, stateHash) {
@@ -3069,6 +3170,7 @@ var Receive = class {
   drainFlight = new SingleFlight();
   pollTimer = null;
   unsubscribeWake = null;
+  lastRefreshAt = 0;
   drainOnce() {
     return this.drainFlight.run(() => this.doDrain());
   }
@@ -3086,6 +3188,14 @@ var Receive = class {
     this.unsubscribeWake?.();
     this.unsubscribeWake = null;
   }
+  /** Ask for a mirror refresh at most once per REFRESH_INTERVAL_MS. */
+  maybeRefresh(deps) {
+    if (deps.refreshView === void 0) return;
+    const now = deps.now?.() ?? Date.now();
+    if (now - this.lastRefreshAt < REFRESH_INTERVAL_MS) return;
+    this.lastRefreshAt = now;
+    deps.refreshView();
+  }
   async doDrain() {
     const deps = this.deps;
     const engine = deps.engine();
@@ -3099,6 +3209,7 @@ var Receive = class {
         for await (const entry of deps.delivery.incoming(basis === null ? void 0 : String(basis.cursor))) {
           await this.processEntry(deps, engine, entry, pending, stored);
           if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
+          if (stored.length > 0) this.maybeRefresh(deps);
         }
         await flushAcks(deps, pending, pageEpoch);
         const served = deps.delivery.incomingEpoch();
@@ -3785,6 +3896,31 @@ var SpendQueue = class {
     }
     return { kind: "queued", settled: this.enqueue(reservationId, request.coinId, amount) };
   }
+  /**
+   * The sources `plan()` WOULD pick right now, reserving nothing and queueing
+   * nothing — a read-only probe used to warm blobs while the user is still
+   * looking at the confirm screen.
+   *
+   * Deliberately side-effect free: reserving here would pin the user's balance
+   * across think-time and strand it if they never press send. The consequence is
+   * that the real `plan()` may pick differently (inventory moves, another send
+   * reserves first); callers must treat the result as a HINT and tolerate a miss,
+   * never as a commitment that these sources will be spent.
+   */
+  previewSelection(request) {
+    if (this.destroyed) return [];
+    let amount;
+    try {
+      amount = parseAmount(request.amount);
+    } catch {
+      return [];
+    }
+    const { freeView, freeTotal } = this.freeView(request.coinId);
+    if (freeTotal < amount) return [];
+    const plan = selectCoins(freeView, amount, { workBudget: this.deps.workBudget });
+    if (plan === null) return [];
+    return [...plan.direct, ...plan.split !== void 0 ? [plan.split.tokenId] : []];
+  }
   // Coverage math: free + Σ declared expected change of in-flight sends —
   // never the full amount of in-flight sources (§5.3).
   declareExpectedChange(transferId, coinId, amount) {
@@ -3973,7 +4109,7 @@ function composeFacadeParts(deps, hooks) {
     machineDeps,
     machine: new TransferMachine(machineDeps),
     heldStates,
-    receiveLoop: buildReceive(deps, hooks, historyStore, heldStates),
+    receiveLoop: buildReceive(deps, hooks, historyStore, heldStates, view),
     requests: buildRequests(deps, hooks),
     restoreDeps: buildRestoreDeps(deps, machineDeps, machineStores, view)
   };
@@ -4040,7 +4176,7 @@ function buildMachineDeps(deps, hooks, historyStore) {
     }
   };
 }
-function buildReceive(deps, hooks, historyStore, heldStates) {
+function buildReceive(deps, hooks, historyStore, heldStates, view) {
   return new Receive({
     delivery: deps.deliveryPort,
     engine: () => hooks.engine(),
@@ -4054,6 +4190,11 @@ function buildReceive(deps, hooks, historyStore, heldStates) {
     registry: deps.registry,
     recordReceived: (record) => recordReceived(historyStore, record),
     emit: (event, transfer) => deps.emit(event, transfer),
+    // The mirror is the balance the wallet renders; refresh it as the drain runs
+    // so a multi-token receive lands progressively instead of all at the end.
+    refreshView: () => {
+      void view.delta().catch(() => void 0);
+    },
     attention: (transferId, code, detail) => {
       deps.emit(
         "transfer:attention",
@@ -4134,6 +4275,7 @@ var PaymentsFacade = class {
       now: () => this.nowMs()
     });
   }
+  prewarmed = new PrewarmCache();
   view;
   ledger;
   queue;
@@ -4227,6 +4369,15 @@ var PaymentsFacade = class {
     return derivePendingTransfers(this.machineStores, this.machineDeps.decryptPayload);
   }
   // ── money movement ─────────────────────────────────────────────────────────
+  async prewarmSend(request) {
+    await warmSendSources(this.warmDeps(), request);
+  }
+  discardPrewarm() {
+    this.prewarmed.clear();
+  }
+  warmDeps() {
+    return { queue: this.queue, view: this.view, storagePort: this.deps.storagePort, cache: this.prewarmed };
+  }
   send(request) {
     return this.track(this.sendOutcome(request));
   }
@@ -4436,7 +4587,7 @@ var PaymentsFacade = class {
   }
   async materialize(transferId, recipientPubkey, request, spend, sourceIds) {
     const engine = this.engine();
-    const blobs = await this.deps.storagePort.getBlobs([...sourceIds]);
+    const blobs = await takeSourceBlobs(this.warmDeps(), sourceIds);
     const sources = /* @__PURE__ */ new Map();
     const sourceTokens = [];
     const spentStates = {};
@@ -4449,7 +4600,7 @@ var PaymentsFacade = class {
       const keys = await engine.deliveryKeys(bytes);
       spentStates[tokenId] = { local: keys.stateHash, protocol: keys.stateHash };
       sources.set(tokenId, token);
-      sourceTokens.push(this.toUiToken(tokenId, request.coinId, engine.balanceOf(token, request.coinId)));
+      sourceTokens.push(transferringToken(tokenId, request.coinId, engine.balanceOf(token, request.coinId), this.deps.registry, this.nowMs()));
     }
     const payload = buildPayload(recipientPubkey, request, spend, spentStates);
     const plan = {
@@ -4593,7 +4744,7 @@ var PaymentsFacade = class {
     await this.machineStores.mintJournal.upsert(entry);
     let token;
     try {
-      token = await engine.mint(this.mintParams(coinId, amount), { transferId: mintId });
+      token = await engine.mint(mintParams(this.ownPubkeyBytes, coinId, amount), { transferId: mintId });
     } catch (err) {
       this.heartbeat.arm();
       return { success: false, error: messageOf(err) };
@@ -4652,7 +4803,7 @@ var PaymentsFacade = class {
       });
       return false;
     }
-    const token = await engine.mint(this.mintParams(entry.coinId, BigInt(entry.amount)), {
+    const token = await engine.mint(mintParams(this.ownPubkeyBytes, entry.coinId, BigInt(entry.amount)), {
       transferId: entry.mintId
     });
     if (token.blob.tokenId !== entry.tokenId) {
@@ -4661,12 +4812,6 @@ var PaymentsFacade = class {
     await this.finalizeMint(engine, entry.mintId, token, entry.coinId, entry.amount);
     return true;
   }
-  mintParams(coinId, amount) {
-    return {
-      recipientPubkey: this.ownPubkeyBytes,
-      value: { assets: [{ coinId, amount }] }
-    };
-  }
   async tokenInServerInventory(tokenId) {
     let page = await this.deps.storagePort.listInventory();
     for (let i = 0; i < INVENTORY_SCAN_PAGE_LIMIT; i++) {
@@ -4695,12 +4840,6 @@ var PaymentsFacade = class {
       page = await this.deps.storagePort.listInventory(page.cursor);
     }
   }
-  toUiToken(tokenId, coinId, amount) {
-    const now = this.nowMs();
-    const snapshot = { assets: [], createdAt: now, updatedAt: now };
-    const flags = { transferring: true, suspectedSpent: false };
-    return toToken(tokenId, snapshot, { coinId, amount: amount.toString() }, this.deps.registry, flags);
-  }
   track(op) {
     const settled = op.then(() => void 0, () => void 0);
     this.pendingOps.add(settled);