@unicitylabs/sphere-sdk 0.14.3 → 0.14.5

package/dist/token-engine/index.d.cts

@@ -341,7 +341,11 @@ interface EngineConfig {
     readonly trustBaseJson: unknown;
     /** Inclusion-proof poll cadence in ms (engine owns the await policy; Spike S1). */
     readonly proofPollIntervalMs?: number;
-    /** Inclusion-proof overall timeout in ms (0/undefined = no engine-side cap). */
+    /**
+     * Deadline for ONE inclusion-proof wait, in ms. Undefined → 10s. Must be
+     * positive: an unbounded wait hangs the op and with it teardown (#739), so
+     * there is no "no cap" value — 0 or negative throws INVALID_CONFIG.
+     */
     readonly proofTimeoutMs?: number;
     /**
      * Opt in to parallel verification. Omitted → the sequential verifier, i.e. the

package/dist/token-engine/index.d.ts

@@ -341,7 +341,11 @@ interface EngineConfig {
     readonly trustBaseJson: unknown;
     /** Inclusion-proof poll cadence in ms (engine owns the await policy; Spike S1). */
     readonly proofPollIntervalMs?: number;
-    /** Inclusion-proof overall timeout in ms (0/undefined = no engine-side cap). */
+    /**
+     * Deadline for ONE inclusion-proof wait, in ms. Undefined → 10s. Must be
+     * positive: an unbounded wait hangs the op and with it teardown (#739), so
+     * there is no "no cap" value — 0 or negative throws INVALID_CONFIG.
+     */
     readonly proofTimeoutMs?: number;
     /**
      * Opt in to parallel verification. Omitted → the sequential verifier, i.e. the

package/dist/token-engine/index.js

@@ -7,6 +7,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";
@@ -284,6 +285,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);
+  }
+}
+
 // core/uuid.ts
 function randomUUID() {
   const c = globalThis.crypto;
@@ -941,11 +1011,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) };
@@ -1288,14 +1360,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}`) {
@@ -1311,6 +1386,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)) {
@@ -1410,6 +1492,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) } : {}
   };