@unicitylabs/sphere-sdk 0.14.3 → 0.14.5

package/dist/index.js

@@ -9218,6 +9218,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";
@@ -9383,6 +9384,75 @@ function decodeSpherePaymentData(bytes) {
   return Promise.resolve(SpherePaymentData.fromCBOR(bytes));
 }
 
+// token-engine/proof-wait.ts
+var DEFAULT_PROOF_TIMEOUT_MS = 1e4;
+function resolveProofTimeoutMs(configured) {
+  if (configured === void 0) return DEFAULT_PROOF_TIMEOUT_MS;
+  if (!Number.isFinite(configured) || configured <= 0) {
+    throw new SphereError(
+      `proofTimeoutMs must be a positive number of milliseconds (got ${String(configured)}); an unbounded inclusion-proof wait is not supported`,
+      "INVALID_CONFIG"
+    );
+  }
+  return configured;
+}
+var TRANSIENT_HTTP_STATUSES = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+function isTransientGatewayError(err) {
+  return err instanceof JsonRpcNetworkError && TRANSIENT_HTTP_STATUSES.has(err.status);
+}
+function pause(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+async function awaitProofBounded(deps, transaction, external) {
+  const controller = new AbortController();
+  const relayAbort = () => {
+    controller.abort(external?.reason);
+  };
+  if (external !== void 0) {
+    if (external.aborted) relayAbort();
+    else external.addEventListener("abort", relayAbort, { once: true });
+  }
+  const timer = setTimeout(() => {
+    controller.abort(
+      new SphereError(
+        `inclusion proof not confirmed within ${String(deps.timeoutMs)} ms`,
+        "AGGREGATOR_ERROR"
+      )
+    );
+  }, deps.timeoutMs);
+  try {
+    for (; ; ) {
+      try {
+        return await waitInclusionProof(
+          deps.client,
+          deps.trustBase,
+          deps.predicateVerifier,
+          transaction,
+          controller.signal,
+          deps.intervalMs
+        );
+      } catch (err) {
+        if (controller.signal.aborted) throw err;
+        if (!isTransientGatewayError(err)) throw err;
+        await pause(deps.intervalMs, controller.signal);
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+    external?.removeEventListener("abort", relayAbort);
+  }
+}
+
 // token-engine/errors.ts
 var TransferConflictError = class extends SphereError {
   /**
@@ -9607,11 +9677,13 @@ var SphereTokenEngine = class {
   constructor(deps) {
     this.deps = deps;
     this.privateKeyHex = HexConverter.encode(deps.privateKey);
+    this.proofTimeoutMs = resolveProofTimeoutMs(deps.proofTimeoutMs);
   }
   /** F13 advertisement: mint under a (transferId, opIndex) seed is idempotent-recoverable — a same-seed re-call converges, never double-mints. */
   deterministicMint = true;
   /** Hex form of the wallet key — deriveRealization's ikm input (Part E.1). */
   privateKeyHex;
+  proofTimeoutMs;
   // ── identity ────────────────────────────────────────────────────────────────
   getIdentity() {
     return { chainPubkey: new Uint8Array(this.deps.signingService.publicKey) };
@@ -9954,14 +10026,17 @@ var SphereTokenEngine = class {
       submitError = err ?? new SphereError(`${failLabel}: submit failed`, failCode);
     }
     try {
-      return await waitInclusionProof(
-        this.deps.client,
-        this.deps.trustBase,
-        this.deps.predicateVerifier,
+      return await awaitProofBounded(
+        {
+          client: this.deps.client,
+          trustBase: this.deps.trustBase,
+          predicateVerifier: this.deps.predicateVerifier,
+          timeoutMs: this.proofTimeoutMs,
+          intervalMs: this.deps.proofPollIntervalMs ?? DEFAULT_PROOF_POLL_INTERVAL_MS
+          // #683
+        },
         transaction,
-        options?.signal,
-        this.deps.proofPollIntervalMs ?? DEFAULT_PROOF_POLL_INTERVAL_MS
-        // #683 finer poll cadence
+        options?.signal
       );
     } catch (err) {
       if (err instanceof Error && err.message === `Invalid inclusion proof status: ${InclusionProofVerificationStatus.TRANSACTION_HASH_MISMATCH}`) {
@@ -9977,6 +10052,13 @@ var SphereTokenEngine = class {
       );
     }
   }
+  /**
+   * One inclusion-proof wait, with the deadline OWNED here (#739). The SDK's own
+   * default deadline is unreliable — see lateDeliveringSignal — and a lost one
+   * means an op that never settles, which also wedges PaymentsFacade.stop().
+   * A deadline hit throws, and the caller maps that to ProofUnconfirmedError
+   * (keep-open), which is the correct posture: the spend may be on-chain.
+   */
   /** Fail fast if this engine's key does not own the token's current state. */
   assertOwned(token) {
     if (!this.isOwnedBy(token, this.deps.signingService.publicKey)) {
@@ -10076,6 +10158,8 @@ async function createSphereTokenEngine(config) {
     networkId: trustBase.networkId,
     // #683: forward the (optional) proof-poll cadence; undefined → the engine default.
     proofPollIntervalMs: config.proofPollIntervalMs,
+    proofTimeoutMs: config.proofTimeoutMs,
+    // #739: was declared but never wired
     // Opt-in parallel verification (2.0.2). Absent → the sequential verifier.
     ...config.verification ? { tokenVerifier: createWorkerTokenVerifier(config.verification) } : {}
   };
@@ -11985,6 +12069,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) {
@@ -12395,10 +12502,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) });
@@ -12414,7 +12532,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))
         })
       );
@@ -12422,7 +12540,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);
   }
@@ -13108,6 +13226,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");
@@ -13134,6 +13266,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();
@@ -13146,6 +13285,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;
@@ -13236,6 +13413,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;
@@ -13248,12 +13430,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) {
@@ -13303,11 +13483,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 });
@@ -13352,18 +13531,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;
@@ -13405,13 +13592,17 @@ function supportsDeterministicMint(engine) {
 }
 function composeFacadeParts(deps, hooks) {
   const ownPubkeyBytes = hexToBytes4(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),
@@ -13432,6 +13623,7 @@ function composeFacadeParts(deps, hooks) {
     ownPubkeyBytes,
     view,
     ledger,
+    pins: buildPins(deps, hooks, { ledger, view, machineStores, machineDeps }),
     queue,
     historyStore,
     machineStores,
@@ -13443,6 +13635,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,
@@ -13552,7 +13755,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;
@@ -13566,6 +13770,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(),
@@ -13608,6 +13813,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;
@@ -13630,6 +13837,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);
@@ -13700,6 +13908,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);
   }
@@ -13939,6 +14148,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) {