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

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

@@ -356,6 +356,11 @@ type AckOutcome = {
     readonly deliveryId: string;
     readonly status: 'conflict';
 };
+/** ackBatch failed in a way a per-entry retry would hit too — do not fall back. */
+interface RetryableAckError extends Error {
+    readonly retryable: true;
+}
+declare function isRetryableAckError(err: unknown): err is RetryableAckError;
 
 interface IntentPayload {
     v: 2;
@@ -437,6 +442,8 @@ interface StorageProvider extends BaseProvider {
     loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
 }
 
+/** Never `storage.clear()` — that takes the keys too. */
+declare function sweepSupersededState(storage: StorageProvider): Promise<void>;
 interface ScopedKV {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T): Promise<void>;
@@ -539,10 +546,6 @@ interface SphereValue {
  * `token`, so it is NOT stored — only cached at runtime on SphereToken.value.
  */
 interface TokenBlob {
-    /** Blob format version (sphere storage migrations; independent of SDK CBOR). */
-    readonly v: number;
-    /** NetworkId.id the token belongs to (mainnet=1 / testnet=2 / local=3). */
-    readonly network: number;
     /**
      * Genesis-stable token id — 64-char lowercase hex of the v2 `TokenId.bytes`
      * (same across every state of the token). Stored on the blob so dedup / listing
@@ -1174,4 +1177,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, isRetryableAckError, supportsDeterministicMint, sweepSupersededState };

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

@@ -356,6 +356,11 @@ type AckOutcome = {
     readonly deliveryId: string;
     readonly status: 'conflict';
 };
+/** ackBatch failed in a way a per-entry retry would hit too — do not fall back. */
+interface RetryableAckError extends Error {
+    readonly retryable: true;
+}
+declare function isRetryableAckError(err: unknown): err is RetryableAckError;
 
 interface IntentPayload {
     v: 2;
@@ -437,6 +442,8 @@ interface StorageProvider extends BaseProvider {
     loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
 }
 
+/** Never `storage.clear()` — that takes the keys too. */
+declare function sweepSupersededState(storage: StorageProvider): Promise<void>;
 interface ScopedKV {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T): Promise<void>;
@@ -539,10 +546,6 @@ interface SphereValue {
  * `token`, so it is NOT stored — only cached at runtime on SphereToken.value.
  */
 interface TokenBlob {
-    /** Blob format version (sphere storage migrations; independent of SDK CBOR). */
-    readonly v: number;
-    /** NetworkId.id the token belongs to (mainnet=1 / testnet=2 / local=3). */
-    readonly network: number;
     /**
      * Genesis-stable token id — 64-char lowercase hex of the v2 `TokenId.bytes`
      * (same across every state of the token). Stored on the blob so dedup / listing
@@ -1174,4 +1177,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, supportsDeterministicMint };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, isRetryableAckError, supportsDeterministicMint, sweepSupersededState };

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

@@ -1,6 +1,114 @@
+// 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);
@@ -449,69 +557,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
-import { StateTransitionClient } from "@unicitylabs/state-transition-sdk/lib/StateTransitionClient.js";
-import { AggregatorClient } from "@unicitylabs/state-transition-sdk/lib/api/AggregatorClient.js";
-import { NetworkId } from "@unicitylabs/state-transition-sdk/lib/api/NetworkId.js";
-import { CertificationData } from "@unicitylabs/state-transition-sdk/lib/api/CertificationData.js";
-import { CertificationResponse, CertificationStatus } from "@unicitylabs/state-transition-sdk/lib/api/CertificationResponse.js";
-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";
-import { Token } from "@unicitylabs/state-transition-sdk/lib/transaction/Token.js";
-import { MintTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/MintTransaction.js";
-import { TransferTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction.js";
-import { CertifiedMintTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/CertifiedMintTransaction.js";
-import { CertifiedTransferTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/CertifiedTransferTransaction.js";
-import { TokenId } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenId.js";
-import { TokenType } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenType.js";
-import { TokenSalt } from "@unicitylabs/state-transition-sdk/lib/transaction/TokenSalt.js";
-import { StateMask } from "@unicitylabs/state-transition-sdk/lib/transaction/StateMask.js";
-import { MintJustificationVerifierService } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/MintJustificationVerifierService.js";
-import { TokenIssuanceVerifierService } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/TokenIssuanceVerifierService.js";
-import { VerificationContext } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/VerificationContext.js";
-import { UnicityCertificateVerifier } from "@unicitylabs/state-transition-sdk/lib/api/bft/verification/UnicityCertificateVerifier.js";
-import { UnicitySealQuorumSignaturesVerificationRule } from "@unicitylabs/state-transition-sdk/lib/api/bft/verification/rule/UnicitySealQuorumSignaturesVerificationRule.js";
-import { VerifiedSealCache } from "@unicitylabs/state-transition-sdk/lib/api/bft/verification/VerifiedSealCache.js";
-import { Secp256k1SignatureVerifier } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/Secp256k1SignatureVerifier.js";
-import { WorkerTokenVerifier } from "@unicitylabs/state-transition-sdk/lib/transaction/verification/worker/WorkerTokenVerifier.js";
-import { EncodedPredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/EncodedPredicate.js";
-import { SignaturePredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicate.js";
-import { SignaturePredicateUnlockScript } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/SignaturePredicateUnlockScript.js";
-import { BurnPredicate } from "@unicitylabs/state-transition-sdk/lib/predicate/builtin/BurnPredicate.js";
-import { PredicateVerifierService } from "@unicitylabs/state-transition-sdk/lib/predicate/verification/PredicateVerifierService.js";
-import { SigningService } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/SigningService.js";
-import { Signature } from "@unicitylabs/state-transition-sdk/lib/crypto/secp256k1/Signature.js";
-import { MintSigningService } from "@unicitylabs/state-transition-sdk/lib/crypto/MintSigningService.js";
-import { HashAlgorithm } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/HashAlgorithm.js";
-import { DataHash } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHash.js";
-import { DataHasher } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasher.js";
-import { DataHasherFactory } from "@unicitylabs/state-transition-sdk/lib/crypto/hash/DataHasherFactory.js";
-import { CborSerializer } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborSerializer.js";
-import { CborDeserializer } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborDeserializer.js";
-import { CborError } from "@unicitylabs/state-transition-sdk/lib/serialization/cbor/CborError.js";
-import { Asset } from "@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js";
-import { AssetId } from "@unicitylabs/state-transition-sdk/lib/payment/asset/AssetId.js";
-import { PaymentAssetCollection } from "@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js";
-import { TokenSplit } from "@unicitylabs/state-transition-sdk/lib/payment/TokenSplit.js";
-import { SplitTokenRequest } from "@unicitylabs/state-transition-sdk/lib/payment/SplitTokenRequest.js";
-import { SplitToken } from "@unicitylabs/state-transition-sdk/lib/payment/SplitToken.js";
-import { SplitAllocationProof } from "@unicitylabs/state-transition-sdk/lib/payment/SplitAllocationProof.js";
-import { SplitMintJustification } from "@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustification.js";
-import { SplitMintJustificationVerifier } from "@unicitylabs/state-transition-sdk/lib/payment/SplitMintJustificationVerifier.js";
-import { VerificationStatus } from "@unicitylabs/state-transition-sdk/lib/verification/VerificationStatus.js";
-import { VerificationResult } from "@unicitylabs/state-transition-sdk/lib/verification/VerificationResult.js";
-import { HexConverter } from "@unicitylabs/state-transition-sdk/lib/util/HexConverter.js";
-import { BigintConverter } from "@unicitylabs/state-transition-sdk/lib/util/BigintConverter.js";
-import { BitString } from "@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;
@@ -1156,12 +1201,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();
@@ -1277,8 +1317,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;
@@ -3102,103 +3143,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;
@@ -3247,22 +3191,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);
   }
@@ -3273,11 +3219,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"));
@@ -3285,22 +3236,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);
@@ -3310,13 +3264,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);
@@ -3361,7 +3311,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);
@@ -3379,6 +3330,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);
@@ -4717,7 +4669,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);
@@ -4981,7 +4933,9 @@ export {
   PaymentsFacade,
   STORE_KEYS,
   createScopedKV,
-  supportsDeterministicMint
+  isRetryableAckError,
+  supportsDeterministicMint,
+  sweepSupersededState
 };
 /*! Bundled license information: