@unicitylabs/sphere-sdk 0.14.3 → 0.14.4

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

@@ -1066,6 +1066,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     private readonly passChain;
     /** §7 ownership: ids with an in-process machine attempt — the pass never adopts one. */
     private readonly activeMoneyOps;
+    /** #737: the ledger holds exactly the sources of the still-open intents. */
+    private readonly pins;
     constructor(deps: PaymentsFacadeDeps);
     start(): Promise<void>;
     /** §7 same-address restart gate: resolves only after in-flight ops settle. */

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

@@ -1066,6 +1066,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     private readonly passChain;
     /** §7 ownership: ids with an in-process machine attempt — the pass never adopts one. */
     private readonly activeMoneyOps;
+    /** #737: the ledger holds exactly the sources of the still-open intents. */
+    private readonly pins;
     constructor(deps: PaymentsFacadeDeps);
     start(): Promise<void>;
     /** §7 same-address restart gate: resolves only after in-flight ops settle. */

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

@@ -458,6 +458,7 @@ import { CertificationResponse, CertificationStatus } from "@unicitylabs/state-t
 import { StateId } from "@unicitylabs/state-transition-sdk/lib/api/StateId.js";
 import { InclusionProof } from "@unicitylabs/state-transition-sdk/lib/api/InclusionProof.js";
 import { InclusionProofResponse } from "@unicitylabs/state-transition-sdk/lib/api/InclusionProofResponse.js";
+import { JsonRpcNetworkError } from "@unicitylabs/state-transition-sdk/lib/api/json-rpc/JsonRpcNetworkError.js";
 import { RootTrustBase } from "@unicitylabs/state-transition-sdk/lib/api/bft/RootTrustBase.js";
 import { waitInclusionProof } from "@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils.js";
 import { InclusionProofVerificationStatus } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/rule/InclusionProofVerificationRule.js";
@@ -1417,6 +1418,29 @@ async function derivePendingTransfers(stores, decryptPayload) {
   }
   return out;
 }
+async function deriveOpenIntentHolds(stores, decryptPayload) {
+  const holds = /* @__PURE__ */ new Map();
+  let complete = true;
+  for (const entry of await stores.backstop.list()) {
+    if (entry.disposition !== "open") continue;
+    let payload = null;
+    try {
+      const raw = await decryptPayload(entry.payloadEnvelope);
+      if (raw !== null && typeof raw === "object") payload = raw;
+    } catch {
+      complete = false;
+      continue;
+    }
+    if (payload === null) {
+      complete = false;
+      continue;
+    }
+    const direct = Array.isArray(payload?.direct) ? payload.direct.filter((id) => typeof id === "string") : [];
+    const split = typeof payload?.split?.tokenId === "string" ? [payload.split.tokenId] : [];
+    holds.set(entry.transferId, [...direct, ...split]);
+  }
+  return { open: holds, complete };
+}
 function groupJournal(journal) {
   const byTransfer = /* @__PURE__ */ new Map();
   for (const entry of journal) {
@@ -2677,10 +2701,21 @@ var InventoryView = class {
   release(tokenId) {
     if (this.inFlight.delete(tokenId)) this.deps.emit("inventory:updated");
   }
+  pinned(tokenId) {
+    return this.deps.isPinned?.(tokenId) ?? false;
+  }
+  /** In flight here OR pinned by a reservation: either way not spendable (#737). */
+  held(tokenId) {
+    return this.inFlight.has(tokenId) || this.pinned(tokenId);
+  }
+  // A PINNED token stays in the pool: the queue applies the ledger filter itself
+  // and needs the entry to say how much is pinned when it refuses (#737). In
+  // flight without a pin (spent, awaiting the mirror refresh) stays out.
   pool(coinId) {
     const out = [];
     for (const [tokenId, entry] of this.mirror) {
-      if (entry.status !== "active" || this.inFlight.has(tokenId)) continue;
+      if (entry.status !== "active") continue;
+      if (this.inFlight.has(tokenId) && !this.pinned(tokenId)) continue;
       if (this.suspected.has(stateKey(tokenId, entry.stateHash))) continue;
       const asset = entry.assets.find((a) => a.coinId === coinId);
       if (asset) out.push({ tokenId, amount: BigInt(asset.amount) });
@@ -2696,7 +2731,7 @@ var InventoryView = class {
       if (filter?.coinId !== void 0 && asset.coinId !== filter.coinId) continue;
       out.push(
         toToken(tokenId, entry, asset, registry, {
-          transferring: this.inFlight.has(tokenId),
+          transferring: this.held(tokenId),
           suspectedSpent: this.suspected.has(stateKey(tokenId, entry.stateHash))
         })
       );
@@ -2704,7 +2739,7 @@ var InventoryView = class {
     return out;
   }
   async assets(registry, price) {
-    const raw = aggregateAssets(this.activeEntries(), (tokenId) => this.inFlight.has(tokenId), registry);
+    const raw = aggregateAssets(this.activeEntries(), (tokenId) => this.held(tokenId), registry);
     if (!price || raw.length === 0) return raw;
     return withPrices(raw, registry, price);
   }
@@ -3482,6 +3517,20 @@ var Requests = class {
 var ReservationLedger = class {
   reservations = /* @__PURE__ */ new Map();
   tokenHolder = /* @__PURE__ */ new Map();
+  // #738: the held-set is RECONSTRUCTED from the open intents, so until
+  // IntentPins proves every one of them "no holder" means unknown, not free.
+  authoritative = false;
+  /** Sole writer: IntentPins.sync(), true only if it reconstructed every open intent.
+   *  Returns whether the gate actually moved, so callers signal transitions, not passes. */
+  setAuthoritative(value) {
+    const moved = this.authoritative !== value;
+    this.authoritative = value;
+    return moved;
+  }
+  /** Non-null while the held-set is unproven: nothing plans, nothing reads free. */
+  unprovenReason() {
+    return this.authoritative ? null : "Cannot yet verify which tokens are held by transfers still converging \u2014 spending is paused until that check succeeds";
+  }
   // All-or-nothing: every entry is validated before any state mutates.
   reserve(reservationId, entries) {
     if (entries.length === 0) throw new Error("EMPTY_RESERVATION");
@@ -3508,6 +3557,13 @@ var ReservationLedger = class {
   getFreeAmount(tokenId, tokenAmount) {
     return this.tokenHolder.has(tokenId) ? 0n : tokenAmount;
   }
+  /** #737: who pins this token — the reporting side reads it so a held token is never called spendable. */
+  holderOf(tokenId) {
+    return this.tokenHolder.get(tokenId);
+  }
+  tokensOf(reservationId) {
+    return [...this.reservations.get(reservationId) ?? []];
+  }
   clear() {
     this.reservations.clear();
     this.tokenHolder.clear();
@@ -3520,6 +3576,44 @@ var ReservationLedger = class {
   }
 };
 
+// modules/payments-v2/select/pins.ts
+var IntentPins = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  pinned = /* @__PURE__ */ new Set();
+  /** The keep-open reservation IS this intent's pin from now on. */
+  adopt(transferId) {
+    this.pinned.add(transferId);
+  }
+  async sync() {
+    const { open, complete } = await this.deps.openIntents();
+    let changed = false;
+    for (const transferId of [...this.pinned]) {
+      if (open.has(transferId) || this.deps.isActive(transferId)) continue;
+      this.pinned.delete(transferId);
+      for (const tokenId of this.deps.ledger.tokensOf(transferId)) this.deps.release(tokenId);
+      this.deps.ledger.cancel(transferId);
+      changed = true;
+    }
+    for (const [transferId, tokenIds] of open) {
+      if (this.deps.isActive(transferId)) continue;
+      this.pinned.add(transferId);
+      changed = this.pin(transferId, tokenIds) || changed;
+    }
+    const gateMoved = this.deps.ledger.setAuthoritative(complete);
+    if (changed || gateMoved) this.deps.changed();
+  }
+  /** Every pass, not just on adoption; the free subset, since a partial pin beats none. */
+  pin(transferId, tokenIds) {
+    if (this.deps.ledger.tokensOf(transferId).length > 0) return false;
+    const free = tokenIds.filter((tokenId) => this.deps.ledger.holderOf(tokenId) === void 0);
+    if (free.length === 0) return false;
+    this.deps.ledger.reserve(transferId, free.map((tokenId) => ({ tokenId })));
+    return true;
+  }
+};
+
 // modules/payments-v2/select/selector.ts
 var DEFAULT_WORK_BUDGET = 2e4;
 var MAX_COMBINATION_SIZE = 5;
@@ -3610,6 +3704,11 @@ function searchCombinationsOfSize(window, size, target, search) {
 // modules/payments-v2/select/queue.ts
 var QUEUE_TIMEOUT_MS = 3e4;
 var QUEUE_MAX_SIZE = 100;
+function insufficientBalance(view, amount) {
+  if (view.unproven !== null) return new SphereError(view.unproven, "SEND_INSUFFICIENT_BALANCE");
+  const message = view.pinnedTotal > 0n ? `Insufficient spendable balance: need ${amount.toString()}, ${view.freeTotal.toString()} free, ${view.pinnedTotal.toString()} pinned by ${String(view.pinnedBy)} transfer(s) still converging \u2014 see payments.pendingTransfers(); do not re-send.` : "Insufficient balance for this transaction";
+  return new SphereError(message, "SEND_INSUFFICIENT_BALANCE");
+}
 var SpendQueue = class {
   constructor(deps) {
     this.deps = deps;
@@ -3622,12 +3721,10 @@ var SpendQueue = class {
       throw new SphereError("Module has been destroyed", "MODULE_DESTROYED");
     }
     const amount = parseAmount(request.amount);
-    const { freeView, freeTotal } = this.freeView(request.coinId);
+    const view = this.freeView(request.coinId);
+    const { freeView, freeTotal } = view;
     if (freeTotal + this.expectedChangeTotal(request.coinId) < amount) {
-      throw new SphereError(
-        "Insufficient balance for this transaction",
-        "SEND_INSUFFICIENT_BALANCE"
-      );
+      throw insufficientBalance(view, amount);
     }
     const plan = selectCoins(freeView, amount, { workBudget: this.deps.workBudget });
     if (plan !== null) {
@@ -3677,11 +3774,10 @@ var SpendQueue = class {
       entry.reject(new SphereError("Send queue timeout", "SEND_QUEUE_TIMEOUT"));
       return "rejected";
     }
-    const { freeView, freeTotal } = this.freeView(entry.coinId);
+    const view = this.freeView(entry.coinId);
+    const { freeView, freeTotal } = view;
     if (freeTotal + this.expectedChangeTotal(entry.coinId) < entry.amount) {
-      entry.reject(
-        new SphereError("Insufficient balance for this transaction", "SEND_INSUFFICIENT_BALANCE")
-      );
+      entry.reject(insufficientBalance(view, entry.amount));
       return "rejected";
     }
     const plan = selectCoins(freeView, entry.amount, { workBudget: this.deps.workBudget });
@@ -3726,18 +3822,26 @@ var SpendQueue = class {
     entry.reject(new SphereError("Send queue timeout", "SEND_QUEUE_TIMEOUT"));
     if (entries.length === 0) this.queues.delete(coinId);
   }
-  // Whole-token semantics: only fully-free tokens enter the selector pool.
+  // Whole-token semantics: only fully-free tokens enter the selector pool. What
+  // the reservations hold back is counted too — the refusal has to name it (#737).
   freeView(coinId) {
     const freeView = [];
     let freeTotal = 0n;
+    let pinnedTotal = 0n;
+    const holders = /* @__PURE__ */ new Set();
+    const unproven = this.deps.ledger.unprovenReason();
     for (const entry of this.deps.getPool(coinId)) {
       if (entry.amount <= 0n) continue;
-      if (this.deps.ledger.getFreeAmount(entry.tokenId, entry.amount) === entry.amount) {
+      const holder = unproven === null ? this.deps.ledger.holderOf(entry.tokenId) : entry.tokenId;
+      if (holder === void 0) {
         freeView.push(entry);
         freeTotal += entry.amount;
+      } else {
+        pinnedTotal += entry.amount;
+        holders.add(holder);
       }
     }
-    return { freeView, freeTotal };
+    return { freeView, freeTotal, pinnedTotal, pinnedBy: holders.size, unproven };
   }
   expectedChangeTotal(coinId) {
     let total = 0n;
@@ -3779,13 +3883,17 @@ function supportsDeterministicMint(engine) {
 }
 function composeFacadeParts(deps, hooks) {
   const ownPubkeyBytes = hexToBytes(deps.ownPubkey);
+  const ledger = new ReservationLedger();
   const view = new InventoryView({
     port: deps.storagePort,
     kv: deps.kv,
     emit: (event) => deps.emit(event, {}),
+    // #737: a reserved token is unselectable, so it is never confirmed balance.
+    // #738: while the held-set is unproven, EVERY token reads pinned — the report
+    // must not call a token spendable that the queue is about to refuse to spend.
+    isPinned: (tokenId) => ledger.unprovenReason() !== null || ledger.holderOf(tokenId) !== void 0,
     ...deps.now !== void 0 ? { now: deps.now } : {}
   });
-  const ledger = new ReservationLedger();
   const queue = new SpendQueue({
     ledger,
     getPool: (coinId) => view.pool(coinId),
@@ -3806,6 +3914,7 @@ function composeFacadeParts(deps, hooks) {
     ownPubkeyBytes,
     view,
     ledger,
+    pins: buildPins(deps, hooks, { ledger, view, machineStores, machineDeps }),
     queue,
     historyStore,
     machineStores,
@@ -3817,6 +3926,17 @@ function composeFacadeParts(deps, hooks) {
     restoreDeps: buildRestoreDeps(deps, machineDeps, machineStores, view)
   };
 }
+function buildPins(deps, hooks, parts) {
+  return new IntentPins({
+    ledger: parts.ledger,
+    openIntents: () => deriveOpenIntentHolds(parts.machineStores, parts.machineDeps.decryptPayload),
+    isActive: (transferId) => hooks.isActiveOp(transferId),
+    release: (tokenId) => {
+      parts.view.release(tokenId);
+    },
+    changed: () => deps.emit("inventory:updated", {})
+  });
+}
 function buildRestoreDeps(deps, machineDeps, machineStores, view) {
   return {
     stores: machineStores,
@@ -3926,7 +4046,8 @@ var PaymentsFacade = class {
     this.deps = deps;
     const parts = composeFacadeParts(deps, {
       engine: () => this.engine(),
-      send: (request) => this.send(request)
+      send: (request) => this.send(request),
+      isActiveOp: (id) => this.activeMoneyOps.has(id)
     });
     this.view = parts.view;
     this.ledger = parts.ledger;
@@ -3940,6 +4061,7 @@ var PaymentsFacade = class {
     this.ownPubkeyBytes = parts.ownPubkeyBytes;
     this.restoreDeps = parts.restoreDeps;
     this.requests = parts.requests;
+    this.pins = parts.pins;
     deps.deliveryPort.bindDeliveryKeys((blob) => this.engine().deliveryKeys(blob));
     this.heartbeat = new ConvergenceHeartbeat({
       now: () => this.nowMs(),
@@ -3982,6 +4104,8 @@ var PaymentsFacade = class {
   passChain = new SerialChain();
   /** §7 ownership: ids with an in-process machine attempt — the pass never adopts one. */
   activeMoneyOps = /* @__PURE__ */ new Set();
+  /** #737: the ledger holds exactly the sources of the still-open intents. */
+  pins;
   // ── lifecycle ──────────────────────────────────────────────────────────────
   async start() {
     if (this.started) return;
@@ -4004,6 +4128,7 @@ var PaymentsFacade = class {
     });
     if (statusUnsub !== void 0) this.unsubscribers.push(statusUnsub);
     await this.deps.session.start();
+    await this.pins.sync().catch(() => void 0);
     this.trackTail(this.runConvergencePass());
     this.trackTail(this.seedHeldStates());
     await this.view.fullPull().catch(() => void 0);
@@ -4074,6 +4199,7 @@ var PaymentsFacade = class {
   }
   async convergeBody() {
     const outcome = await this.converger.convergeOnce();
+    await this.pins.sync().catch(() => void 0);
     const pending = await this.converger.pendingWork().catch(() => true);
     this.heartbeat.settle(outcome, pending);
   }
@@ -4313,6 +4439,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.pins.adopt(ctx.transferId);
     this.heartbeat.arm();
   }
   settlePartial(ctx, partial) {