@unicitylabs/sphere-sdk 0.14.11-dev.8 → 0.15.0-dev.1

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

@@ -39,13 +39,123 @@ __export(payments_v2_exports, {
   PaymentsFacade: () => PaymentsFacade,
   STORE_KEYS: () => STORE_KEYS,
   createScopedKV: () => createScopedKV,
-  supportsDeterministicMint: () => supportsDeterministicMint
+  isRetryableAckError: () => isRetryableAckError,
+  supportsDeterministicMint: () => supportsDeterministicMint,
+  sweepSupersededState: () => sweepSupersededState
 });
 module.exports = __toCommonJS(payments_v2_exports);
 
+// modules/payments-v2/ports.ts
+function isRetryableAckError(err) {
+  return err !== null && typeof err === "object" && err.retryable === true;
+}
+
+// core/logger.ts
+var LOGGER_KEY = "__sphere_sdk_logger__";
+function getState() {
+  const g = globalThis;
+  if (!g[LOGGER_KEY]) {
+    g[LOGGER_KEY] = { debug: false, tags: {}, handler: null };
+  }
+  return g[LOGGER_KEY];
+}
+function isEnabled(tag) {
+  const state = getState();
+  if (tag in state.tags) return state.tags[tag];
+  return state.debug;
+}
+var logger = {
+  /**
+   * Configure the logger. Can be called multiple times (last write wins).
+   * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
+   */
+  configure(config) {
+    const state = getState();
+    if (config.debug !== void 0) state.debug = config.debug;
+    if (config.handler !== void 0) state.handler = config.handler;
+  },
+  /**
+   * Enable/disable debug logging for a specific tag.
+   * Per-tag setting overrides the global debug flag.
+   *
+   * @example
+   * ```ts
+   * logger.setTagDebug('Nostr', true);  // enable only Nostr logs
+   * logger.setTagDebug('Nostr', false); // disable Nostr logs even if global debug=true
+   * ```
+   */
+  setTagDebug(tag, enabled) {
+    getState().tags[tag] = enabled;
+  },
+  /**
+   * Clear per-tag override, falling back to global debug flag.
+   */
+  clearTagDebug(tag) {
+    delete getState().tags[tag];
+  },
+  /** Returns true if debug mode is enabled for the given tag (or globally). */
+  isDebugEnabled(tag) {
+    if (tag) return isEnabled(tag);
+    return getState().debug;
+  },
+  /**
+   * Debug-level log. Only shown when debug is enabled (globally or for this tag).
+   * Use for detailed operational information.
+   */
+  debug(tag, message, ...args) {
+    if (!isEnabled(tag)) return;
+    const state = getState();
+    if (state.handler) {
+      state.handler("debug", tag, message, ...args);
+    } else {
+      console.log(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Warning-level log. ALWAYS shown regardless of debug flag.
+   * Use for important but non-critical issues (timeouts, retries, degraded state).
+   */
+  warn(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("warn", tag, message, ...args);
+    } else {
+      console.warn(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Error-level log. ALWAYS shown regardless of debug flag.
+   * Use for critical failures that should never be silenced.
+   */
+  error(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("error", tag, message, ...args);
+    } else {
+      console.error(`[${tag}]`, message, ...args);
+    }
+  },
+  /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
+  reset() {
+    const g = globalThis;
+    delete g[LOGGER_KEY];
+  }
+};
+
 // modules/payments-v2/stores.ts
+var KV_PREFIX = "pv2g2:";
+var SUPERSEDED_KV_PREFIXES = ["pv2:"];
+async function sweepSupersededState(storage) {
+  for (const prefix of SUPERSEDED_KV_PREFIXES) {
+    try {
+      await storage.clear(prefix);
+    } catch (err) {
+      logger.warn("PaymentsV2", `could not clear superseded state under "${prefix}": ${String(err)}`);
+    }
+  }
+}
 function createScopedKV(storage, network, chainPubkey) {
-  const prefix = `pv2:${network}:${chainPubkey}:`;
+  const prefix = `${KV_PREFIX}${network}:${chainPubkey}:`;
   return {
     async get(key) {
       const raw = await storage.get(prefix + key);
@@ -494,69 +604,6 @@ function randomUUID() {
   return `${h[0]}${h[1]}${h[2]}${h[3]}-${h[4]}${h[5]}-${h[6]}${h[7]}-${h[8]}${h[9]}-${h[10]}${h[11]}${h[12]}${h[13]}${h[14]}${h[15]}`;
 }
 
-// token-engine/sdk.ts
-var import_StateTransitionClient = require("@unicitylabs/state-transition-sdk/lib/StateTransitionClient.js");
-var import_AggregatorClient = require("@unicitylabs/state-transition-sdk/lib/api/AggregatorClient.js");
-var import_NetworkId = require("@unicitylabs/state-transition-sdk/lib/api/NetworkId.js");
-var import_CertificationData = require("@unicitylabs/state-transition-sdk/lib/api/CertificationData.js");
-var import_CertificationResponse = require("@unicitylabs/state-transition-sdk/lib/api/CertificationResponse.js");
-var import_StateId = require("@unicitylabs/state-transition-sdk/lib/api/StateId.js");
-var import_InclusionProof = require("@unicitylabs/state-transition-sdk/lib/api/InclusionProof.js");
-var import_InclusionProofResponse = require("@unicitylabs/state-transition-sdk/lib/api/InclusionProofResponse.js");
-var import_JsonRpcNetworkError = require("@unicitylabs/state-transition-sdk/lib/api/json-rpc/JsonRpcNetworkError.js");
-var import_RootTrustBase = require("@unicitylabs/state-transition-sdk/lib/api/bft/RootTrustBase.js");
-var import_InclusionProofUtils = require("@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils.js");
-var import_InclusionProofVerificationRule = require("@unicitylabs/state-transition-sdk/lib/transaction/verification/rule/InclusionProofVerificationRule.js");
-var import_Token = require("@unicitylabs/state-transition-sdk/lib/transaction/Token.js");
-var import_MintTransaction = require("@unicitylabs/state-transition-sdk/lib/transaction/MintTransaction.js");
-var import_TransferTransaction = require("@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction.js");
-var import_CertifiedMintTransaction = require("@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js");
-var import_CertifiedTransferTransaction = require("@unicitylabs/state-transition-sdk/lib/transaction/CertifiedTransferTransaction.js");
-var import_TokenId = require("@unicitylabs/state-transition-sdk/lib/transaction/TokenId.js");
-var import_TokenType = require("@unicitylabs/state-transition-sdk/lib/transaction/TokenType.js");
-var import_TokenSalt = require("@unicitylabs/state-transition-sdk/lib/transaction/TokenSalt.js");
-var import_StateMask = require("@unicitylabs/state-transition-sdk/lib/transaction/StateMask.js");
-var import_MintJustificationVerifierService = require("@unicitylabs/state-transition-sdk/lib/transaction/verification/MintJustificationVerifierService.js");
-var import_TokenIssuanceVerifierService = require("@unicitylabs/state-transition-sdk/lib/transaction/verification/TokenIssuanceVerifierService.js");
-var import_VerificationContext = require("@unicitylabs/state-transition-sdk/lib/transaction/verification/VerificationContext.js");
-var import_UnicityCertificateVerifier = require("@unicitylabs/state-transition-sdk/lib/api/bft/verification/UnicityCertificateVerifier.js");
-var import_UnicitySealQuorumSignaturesVerificationRule = require("@unicitylabs/state-transition-sdk/lib/api/bft/verification/rule/UnicitySealQuorumSignaturesVerificationRule.js");
-var import_VerifiedSealCache = require("@unicitylabs/state-transition-sdk/lib/api/bft/verification/VerifiedSealCache.js");
-var import_Secp256k1SignatureVerifier = require("@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/Secp256k1SignatureVerifier.js");
-var import_WorkerTokenVerifier = require("@unicitylabs/state-transition-sdk/lib/transaction/verification/worker/WorkerTokenVerifier.js");
-var import_EncodedPredicate = require("@unicitylabs/state-transition-sdk/lib/predicate/EncodedPredicate.js");
-var import_SignaturePredicate = require("@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicate.js");
-var import_SignaturePredicateUnlockScript = require("@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicateUnlockScript.js");
-var import_BurnPredicate = require("@unicitylabs/state-transition-sdk/lib/predicate/builtin/BurnPredicate.js");
-var import_PredicateVerifierService = require("@unicitylabs/state-transition-sdk/lib/predicate/verification/PredicateVerifierService.js");
-var import_SigningService = require("@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/SigningService.js");
-var import_Signature = require("@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/Signature.js");
-var import_MintSigningService = require("@unicitylabs/state-transition-sdk/lib/crypto/MintSigningService.js");
-var import_HashAlgorithm = require("@unicitylabs/state-transition-sdk/lib/crypto/hash/HashAlgorithm.js");
-var import_DataHash = require("@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHash.js");
-var import_DataHasher = require("@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasher.js");
-var import_DataHasherFactory = require("@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasherFactory.js");
-var import_CborSerializer = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborSerializer.js");
-var import_CborDeserializer = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborDeserializer.js");
-var import_CborError = require("@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborError.js");
-var import_Asset = require("@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js");
-var import_AssetId = require("@unicitylabs/state-transition-sdk/lib/payment/asset/AssetId.js");
-var import_PaymentAssetCollection = require("@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js");
-var import_TokenSplit = require("@unicitylabs/state-transition-sdk/lib/payment/TokenSplit.js");
-var import_SplitTokenRequest = require("@unicitylabs/state-transition-sdk/lib/payment/SplitTokenRequest.js");
-var import_SplitToken = require("@unicitylabs/state-transition-sdk/lib/payment/SplitToken.js");
-var import_SplitAllocationProof = require("@unicitylabs/state-transition-sdk/lib/payment/SplitAllocationProof.js");
-var import_SplitMintJustification = require("@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustification.js");
-var import_SplitMintJustificationVerifier = require("@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustificationVerifier.js");
-var import_VerificationStatus = require("@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js");
-var import_VerificationResult = require("@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js");
-var import_HexConverter = require("@unicitylabs/state-transition-sdk/lib/util/HexConverter.js");
-var import_BigintConverter = require("@unicitylabs/state-transition-sdk/lib/util/BigintConverter.js");
-var import_BitString = require("@unicitylabs/state-transition-sdk/lib/util/BitString.js");
-
-// token-engine/token-blob.ts
-var TOKEN_BLOB_VERSION = 1;
-
 // modules/payments-v2/async.ts
 var SingleFlight = class {
   flight = null;
@@ -1201,12 +1248,7 @@ var TransferMachine = class {
     let total = 0n;
     for (const outcome of committed) {
       if (outcome.recipientBlob === void 0) continue;
-      const token = await engine.decodeToken({
-        v: TOKEN_BLOB_VERSION,
-        network: 0,
-        tokenId: "",
-        token: outcome.recipientBlob
-      });
+      const token = await engine.decodeToken({ tokenId: "", token: outcome.recipientBlob });
       total += engine.balanceOf(token, coinId);
     }
     return total.toString();
@@ -1322,8 +1364,9 @@ async function fetchSources(deps, jobs) {
   const engine = deps.engine();
   for (const [tokenId, bytes] of blobs) {
     try {
-      decoded.set(tokenId, await engine.decodeToken({ v: TOKEN_BLOB_VERSION, network: 0, tokenId, token: bytes }));
-    } catch {
+      decoded.set(tokenId, await engine.decodeToken({ tokenId, token: bytes }));
+    } catch (err) {
+      logger.warn("PaymentsV2", `resume: source ${tokenId} did not decode \u2014 ${String(err)}`);
     }
   }
   return decoded;
@@ -3147,103 +3190,6 @@ var InventoryView = class {
   }
 };
 
-// core/logger.ts
-var LOGGER_KEY = "__sphere_sdk_logger__";
-function getState() {
-  const g = globalThis;
-  if (!g[LOGGER_KEY]) {
-    g[LOGGER_KEY] = { debug: false, tags: {}, handler: null };
-  }
-  return g[LOGGER_KEY];
-}
-function isEnabled(tag) {
-  const state = getState();
-  if (tag in state.tags) return state.tags[tag];
-  return state.debug;
-}
-var logger = {
-  /**
-   * Configure the logger. Can be called multiple times (last write wins).
-   * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
-   */
-  configure(config) {
-    const state = getState();
-    if (config.debug !== void 0) state.debug = config.debug;
-    if (config.handler !== void 0) state.handler = config.handler;
-  },
-  /**
-   * Enable/disable debug logging for a specific tag.
-   * Per-tag setting overrides the global debug flag.
-   *
-   * @example
-   * ```ts
-   * logger.setTagDebug('Nostr', true);  // enable only Nostr logs
-   * logger.setTagDebug('Nostr', false); // disable Nostr logs even if global debug=true
-   * ```
-   */
-  setTagDebug(tag, enabled) {
-    getState().tags[tag] = enabled;
-  },
-  /**
-   * Clear per-tag override, falling back to global debug flag.
-   */
-  clearTagDebug(tag) {
-    delete getState().tags[tag];
-  },
-  /** Returns true if debug mode is enabled for the given tag (or globally). */
-  isDebugEnabled(tag) {
-    if (tag) return isEnabled(tag);
-    return getState().debug;
-  },
-  /**
-   * Debug-level log. Only shown when debug is enabled (globally or for this tag).
-   * Use for detailed operational information.
-   */
-  debug(tag, message, ...args) {
-    if (!isEnabled(tag)) return;
-    const state = getState();
-    if (state.handler) {
-      state.handler("debug", tag, message, ...args);
-    } else {
-      console.log(`[${tag}]`, message, ...args);
-    }
-  },
-  /**
-   * Warning-level log. ALWAYS shown regardless of debug flag.
-   * Use for important but non-critical issues (timeouts, retries, degraded state).
-   */
-  warn(tag, message, ...args) {
-    const state = getState();
-    if (state.handler) {
-      state.handler("warn", tag, message, ...args);
-    } else {
-      console.warn(`[${tag}]`, message, ...args);
-    }
-  },
-  /**
-   * Error-level log. ALWAYS shown regardless of debug flag.
-   * Use for critical failures that should never be silenced.
-   */
-  error(tag, message, ...args) {
-    const state = getState();
-    if (state.handler) {
-      state.handler("error", tag, message, ...args);
-    } else {
-      console.error(`[${tag}]`, message, ...args);
-    }
-  },
-  /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
-  reset() {
-    const g = globalThis;
-    delete g[LOGGER_KEY];
-  }
-};
-
-// modules/payments-v2/ports.ts
-function isRetryableAckError(err) {
-  return err !== null && typeof err === "object" && err.retryable === true;
-}
-
 // modules/payments-v2/receive/Receive.ts
 var ACK_BATCH_SIZE = 200;
 var REFRESH_INTERVAL_MS = 2500;
@@ -3292,22 +3238,24 @@ var Receive = class {
    * the tokens just accepted, and the balance would still only move at the end.
    * Ordering is preserved: store() still precedes the ack (§5.7).
    */
-  async maybeRefresh(deps, pending, epochOf) {
+  async maybeRefresh(ctx) {
+    const { deps, pending, pageEpoch } = ctx;
     if (deps.refreshView === void 0) return;
     const now = deps.now?.() ?? Date.now();
     if (now - this.lastRefreshAt < REFRESH_INTERVAL_MS) return;
     this.lastRefreshAt = now;
-    await flushAcks(deps, pending, epochOf);
-    deps.refreshView();
+    if ((await flushAcks(deps, pending, pageEpoch)).progressed) deps.refreshView();
   }
   /** One listing pass: process each entry, flushing and refreshing as it goes. */
   async drainPages(ctx, basis) {
-    const { deps, engine, pending, stored, pageEpoch } = ctx;
+    const { deps, pending, pageEpoch, claimable } = ctx;
     for await (const entry of deps.delivery.incoming(basis === null ? void 0 : String(basis.cursor))) {
-      const storedBefore = stored.length;
-      await this.processEntry(deps, engine, entry, pending, stored);
-      if (pending.length >= ACK_BATCH_SIZE) await flushAcks(deps, pending, pageEpoch);
-      if (stored.length > storedBefore) await this.maybeRefresh(deps, pending, pageEpoch);
+      const claimableBefore = claimable.n;
+      await this.processEntry(ctx, entry);
+      if (pending.length >= ACK_BATCH_SIZE) {
+        if (!(await flushAcks(deps, pending, pageEpoch)).progressed) return;
+      }
+      if (claimable.n > claimableBefore) await this.maybeRefresh(ctx);
     }
     await flushAcks(deps, pending, pageEpoch);
   }
@@ -3318,11 +3266,16 @@ var Receive = class {
     const stored = [];
     const pending = [];
     const pageEpoch = () => deps.delivery.incomingEpoch() ?? deps.syncEpoch();
+    const claimable = { n: 0 };
+    const finish = () => {
+      if (claimable.n > 0) deps.refreshView?.();
+      return stored;
+    };
     try {
       const record = await deps.kv.get(STORE_KEYS.streamCursor("mailbox"));
       let basis = record !== null && record.syncEpoch === deps.syncEpoch() ? record : null;
       for (let pass = 0; pass < 2; pass++) {
-        await this.drainPages({ deps, engine, pending, stored, pageEpoch }, basis);
+        await this.drainPages({ deps, engine, pending, stored, pageEpoch, claimable }, basis);
         const served = deps.delivery.incomingEpoch();
         if (basis === null || served === null || served === basis.syncEpoch) break;
         await deps.kv.remove(STORE_KEYS.streamCursor("mailbox"));
@@ -3330,22 +3283,25 @@ var Receive = class {
       }
     } catch (err) {
       logger.warn("PaymentsV2", "receive drain interrupted \u2014 unacked entries retry next drain:", err);
-      if (isRetryableAckError(err)) return stored;
+      if (isRetryableAckError(err)) return finish();
       await flushAcks(deps, pending, pageEpoch).catch((flushErr) => {
         logger.warn("PaymentsV2", "receive ack flush failed \u2014 cursor holds at the acked prefix:", flushErr);
+        return { progressed: false };
       });
     }
-    if (stored.length > 0) deps.refreshView?.();
-    return stored;
+    return finish();
   }
-  async processEntry(deps, engine, entry, pending, stored) {
+  async processEntry(ctx, entry) {
+    const { deps, engine, pending, stored, claimable } = ctx;
     const screened = await screen(deps, engine, entry);
     if (screened.kind === "ack") {
       pending.push(screened.ack);
+      if (screened.ack.disposition === "claimed") claimable.n += 1;
       return;
     }
     await deps.view.store(screened.record);
     pending.push(claimAck(entry));
+    claimable.n += 1;
     const transfer = await announce(deps, entry, screened.record);
     stored.push(transfer);
     deps.emit("transfer:incoming", transfer);
@@ -3355,13 +3311,9 @@ async function screen(deps, engine, entry) {
   const blobBytes = await entry.fetchBlob();
   let token;
   try {
-    token = await engine.decodeToken({
-      v: TOKEN_BLOB_VERSION,
-      network: 0,
-      tokenId: "",
-      token: blobBytes
-    });
-  } catch {
+    token = await engine.decodeToken({ tokenId: "", token: blobBytes });
+  } catch (err) {
+    logger.warn("PaymentsV2", `receive: undecodable blob rejected \u2014 ${String(err)}`);
     return { kind: "ack", ack: rejectAck(entry, "invalid") };
   }
   const verdict = await engine.verify(token);
@@ -3406,7 +3358,8 @@ async function announce(deps, entry, record) {
   };
 }
 async function flushAcks(deps, pending, epochOf) {
-  if (pending.length === 0) return;
+  if (pending.length === 0) return { progressed: true };
+  const before = pending.length;
   let lastAcked = null;
   try {
     const settled = await settleAcks(deps, pending);
@@ -3424,6 +3377,7 @@ async function flushAcks(deps, pending, epochOf) {
       await deps.kv.set(STORE_KEYS.streamCursor("mailbox"), record);
     }
   }
+  return { progressed: pending.length < before };
 }
 async function settleAcks(deps, pending) {
   const batch = deps.delivery.ackBatch?.bind(deps.delivery);
@@ -4762,7 +4716,7 @@ var PaymentsFacade = class {
       if (bytes === void 0) {
         throw new SphereError(`Selected source ${tokenId} has no blob in storage`, "STORAGE_ERROR");
       }
-      const token = await engine.decodeToken({ v: TOKEN_BLOB_VERSION, network: 0, tokenId, token: bytes });
+      const token = await engine.decodeToken({ tokenId, token: bytes });
       const keys = await engine.deliveryKeys(bytes);
       spentStates[tokenId] = { local: keys.stateHash, protocol: keys.stateHash };
       sources.set(tokenId, token);
@@ -5027,7 +4981,9 @@ var PaymentsFacade = class {
   PaymentsFacade,
   STORE_KEYS,
   createScopedKV,
-  supportsDeterministicMint
+  isRetryableAckError,
+  supportsDeterministicMint,
+  sweepSupersededState
 });
 /*! Bundled license information: