@unicitylabs/sphere-sdk 0.5.0 → 0.5.1

package/dist/index.d.cts

@@ -2572,6 +2572,11 @@ declare class PaymentsModule {
     private proofPollingInterval;
     private static readonly PROOF_POLLING_INTERVAL_MS;
     private static readonly PROOF_POLLING_MAX_ATTEMPTS;
+    private resolveUnconfirmedTimer;
+    private static readonly RESOLVE_UNCONFIRMED_INTERVAL_MS;
+    private loadedPromise;
+    private loaded;
+    private processedSplitGroupIds;
     private storageEventUnsubscribers;
     private syncDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
@@ -2869,6 +2874,13 @@ declare class PaymentsModule {
      * @returns Summary with counts of resolved, still-pending, and failed tokens plus per-token details.
      */
     resolveUnconfirmed(): Promise<UnconfirmedResolutionResult>;
+    /**
+     * Start a periodic interval that retries resolveUnconfirmed() until all
+     * tokens are confirmed or failed.  Stops automatically when nothing is
+     * pending and is cleaned up by destroy().
+     */
+    private scheduleResolveUnconfirmed;
+    private stopResolveUnconfirmedPolling;
     /**
      * Process a single V5 token through its finalization stages with quick-timeout proof checks.
      */
@@ -2902,6 +2914,16 @@ declare class PaymentsModule {
      * Called during load() to restore tokens that TXF format can't represent.
      */
     private loadPendingV5Tokens;
+    /**
+     * Persist the set of processed splitGroupIds to KV storage.
+     * This ensures Nostr re-deliveries are ignored across page reloads,
+     * even when the confirmed token's in-memory ID differs from v5split_{id}.
+     */
+    private saveProcessedSplitGroupIds;
+    /**
+     * Load processed splitGroupIds from KV storage.
+     */
+    private loadProcessedSplitGroupIds;
     /**
      * Add a token to the wallet.
      *
@@ -3755,6 +3777,8 @@ declare const STORAGE_KEYS_ADDRESS: {
     readonly GROUP_CHAT_MEMBERS: "group_chat_members";
     /** Group chat: processed event IDs for deduplication */
     readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
+    /** Processed V5 split group IDs for Nostr re-delivery dedup */
+    readonly PROCESSED_SPLIT_GROUP_IDS: "processed_split_group_ids";
 };
 /** @deprecated Use STORAGE_KEYS_GLOBAL and STORAGE_KEYS_ADDRESS instead */
 declare const STORAGE_KEYS: {
@@ -3778,6 +3802,8 @@ declare const STORAGE_KEYS: {
     readonly GROUP_CHAT_MEMBERS: "group_chat_members";
     /** Group chat: processed event IDs for deduplication */
     readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
+    /** Processed V5 split group IDs for Nostr re-delivery dedup */
+    readonly PROCESSED_SPLIT_GROUP_IDS: "processed_split_group_ids";
     /** Encrypted BIP39 mnemonic */
     readonly MNEMONIC: "mnemonic";
     /** Encrypted master private key */

package/dist/index.d.ts

@@ -2572,6 +2572,11 @@ declare class PaymentsModule {
     private proofPollingInterval;
     private static readonly PROOF_POLLING_INTERVAL_MS;
     private static readonly PROOF_POLLING_MAX_ATTEMPTS;
+    private resolveUnconfirmedTimer;
+    private static readonly RESOLVE_UNCONFIRMED_INTERVAL_MS;
+    private loadedPromise;
+    private loaded;
+    private processedSplitGroupIds;
     private storageEventUnsubscribers;
     private syncDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
@@ -2869,6 +2874,13 @@ declare class PaymentsModule {
      * @returns Summary with counts of resolved, still-pending, and failed tokens plus per-token details.
      */
     resolveUnconfirmed(): Promise<UnconfirmedResolutionResult>;
+    /**
+     * Start a periodic interval that retries resolveUnconfirmed() until all
+     * tokens are confirmed or failed.  Stops automatically when nothing is
+     * pending and is cleaned up by destroy().
+     */
+    private scheduleResolveUnconfirmed;
+    private stopResolveUnconfirmedPolling;
     /**
      * Process a single V5 token through its finalization stages with quick-timeout proof checks.
      */
@@ -2902,6 +2914,16 @@ declare class PaymentsModule {
      * Called during load() to restore tokens that TXF format can't represent.
      */
     private loadPendingV5Tokens;
+    /**
+     * Persist the set of processed splitGroupIds to KV storage.
+     * This ensures Nostr re-deliveries are ignored across page reloads,
+     * even when the confirmed token's in-memory ID differs from v5split_{id}.
+     */
+    private saveProcessedSplitGroupIds;
+    /**
+     * Load processed splitGroupIds from KV storage.
+     */
+    private loadProcessedSplitGroupIds;
     /**
      * Add a token to the wallet.
      *
@@ -3755,6 +3777,8 @@ declare const STORAGE_KEYS_ADDRESS: {
     readonly GROUP_CHAT_MEMBERS: "group_chat_members";
     /** Group chat: processed event IDs for deduplication */
     readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
+    /** Processed V5 split group IDs for Nostr re-delivery dedup */
+    readonly PROCESSED_SPLIT_GROUP_IDS: "processed_split_group_ids";
 };
 /** @deprecated Use STORAGE_KEYS_GLOBAL and STORAGE_KEYS_ADDRESS instead */
 declare const STORAGE_KEYS: {
@@ -3778,6 +3802,8 @@ declare const STORAGE_KEYS: {
     readonly GROUP_CHAT_MEMBERS: "group_chat_members";
     /** Group chat: processed event IDs for deduplication */
     readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
+    /** Processed V5 split group IDs for Nostr re-delivery dedup */
+    readonly PROCESSED_SPLIT_GROUP_IDS: "processed_split_group_ids";
     /** Encrypted BIP39 mnemonic */
     readonly MNEMONIC: "mnemonic";
     /** Encrypted master private key */

package/dist/index.js

@@ -91,7 +91,9 @@ var init_constants = __esm({
       /** Group chat: members for this address */
       GROUP_CHAT_MEMBERS: "group_chat_members",
       /** Group chat: processed event IDs for deduplication */
-      GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events"
+      GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events",
+      /** Processed V5 split group IDs for Nostr re-delivery dedup */
+      PROCESSED_SPLIT_GROUP_IDS: "processed_split_group_ids"
     };
     STORAGE_KEYS = {
       ...STORAGE_KEYS_GLOBAL,
@@ -4595,6 +4597,17 @@ var PaymentsModule = class _PaymentsModule {
   // Poll every 2s
   static PROOF_POLLING_MAX_ATTEMPTS = 30;
   // Max 30 attempts (~60s)
+  // Periodic retry for resolveUnconfirmed (V5 lazy finalization)
+  resolveUnconfirmedTimer = null;
+  static RESOLVE_UNCONFIRMED_INTERVAL_MS = 1e4;
+  // Retry every 10s
+  // Guard: ensure load() completes before processing incoming bundles
+  loadedPromise = null;
+  loaded = false;
+  // Persistent dedup: tracks splitGroupIds that have been fully processed.
+  // Survives page reloads via KV storage so Nostr re-deliveries are ignored
+  // even when the confirmed token's in-memory ID differs from v5split_{id}.
+  processedSplitGroupIds = /* @__PURE__ */ new Set();
   // Storage event subscriptions (push-based sync)
   storageEventUnsubscribers = [];
   syncDebounceTimer = null;
@@ -4680,31 +4693,40 @@ var PaymentsModule = class _PaymentsModule {
    */
   async load() {
     this.ensureInitialized();
-    await TokenRegistry.waitForReady();
-    const providers = this.getTokenStorageProviders();
-    for (const [id, provider] of providers) {
-      try {
-        const result = await provider.load();
-        if (result.success && result.data) {
-          this.loadFromStorageData(result.data);
-          this.log(`Loaded metadata from provider ${id}`);
-          break;
+    const doLoad = async () => {
+      await TokenRegistry.waitForReady();
+      const providers = this.getTokenStorageProviders();
+      for (const [id, provider] of providers) {
+        try {
+          const result = await provider.load();
+          if (result.success && result.data) {
+            this.loadFromStorageData(result.data);
+            this.log(`Loaded metadata from provider ${id}`);
+            break;
+          }
+        } catch (err) {
+          console.error(`[Payments] Failed to load from provider ${id}:`, err);
         }
-      } catch (err) {
-        console.error(`[Payments] Failed to load from provider ${id}:`, err);
       }
-    }
-    await this.loadPendingV5Tokens();
-    await this.loadHistory();
-    const pending2 = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
-    if (pending2) {
-      const transfers = JSON.parse(pending2);
-      for (const transfer of transfers) {
-        this.pendingTransfers.set(transfer.id, transfer);
+      const loadedTokens = Array.from(this.tokens.values()).map((t) => `${t.id.slice(0, 12)}(${t.status})`);
+      console.log(`[Payments][DEBUG] load(): from TXF providers: ${this.tokens.size} tokens [${loadedTokens.join(", ")}]`);
+      await this.loadPendingV5Tokens();
+      await this.loadProcessedSplitGroupIds();
+      await this.loadHistory();
+      const pending2 = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
+      if (pending2) {
+        const transfers = JSON.parse(pending2);
+        for (const transfer of transfers) {
+          this.pendingTransfers.set(transfer.id, transfer);
+        }
       }
-    }
+      this.loaded = true;
+    };
+    this.loadedPromise = doLoad();
+    await this.loadedPromise;
     this.resolveUnconfirmed().catch(() => {
     });
+    this.scheduleResolveUnconfirmed();
   }
   /**
    * Cleanup all subscriptions, polling jobs, and pending resolvers.
@@ -4723,6 +4745,7 @@ var PaymentsModule = class _PaymentsModule {
     this.paymentRequestResponseHandlers.clear();
     this.stopProofPolling();
     this.proofPollingJobs.clear();
+    this.stopResolveUnconfirmedPolling();
     for (const [, resolver] of this.pendingResponseResolvers) {
       clearTimeout(resolver.timeout);
       resolver.reject(new Error("Module destroyed"));
@@ -5129,13 +5152,16 @@ var PaymentsModule = class _PaymentsModule {
    */
   async processInstantSplitBundle(bundle, senderPubkey, memo) {
     this.ensureInitialized();
+    if (!this.loaded && this.loadedPromise) {
+      await this.loadedPromise;
+    }
     if (!isInstantSplitBundleV5(bundle)) {
       return this.processInstantSplitBundleSync(bundle, senderPubkey, memo);
     }
     try {
       const deterministicId = `v5split_${bundle.splitGroupId}`;
-      if (this.tokens.has(deterministicId)) {
-        this.log(`V5 bundle ${deterministicId.slice(0, 16)}... already exists, skipping duplicate`);
+      if (this.tokens.has(deterministicId) || this.processedSplitGroupIds.has(bundle.splitGroupId)) {
+        console.log(`[Payments] V5 bundle ${bundle.splitGroupId.slice(0, 12)}... already processed, skipping`);
         return { success: true, durationMs: 0 };
       }
       const registry = TokenRegistry.getInstance();
@@ -5161,7 +5187,8 @@ var PaymentsModule = class _PaymentsModule {
         sdkData: JSON.stringify({ _pendingFinalization: pendingData })
       };
       await this.addToken(uiToken);
-      this.log(`V5 bundle saved as unconfirmed: ${uiToken.id.slice(0, 8)}...`);
+      this.processedSplitGroupIds.add(bundle.splitGroupId);
+      await this.saveProcessedSplitGroupIds();
       const senderInfo = await this.resolveSenderInfo(senderPubkey);
       await this.addToHistory({
         type: "RECEIVED",
@@ -5185,6 +5212,7 @@ var PaymentsModule = class _PaymentsModule {
       await this.save();
       this.resolveUnconfirmed().catch(() => {
       });
+      this.scheduleResolveUnconfirmed();
       return { success: true, durationMs: 0 };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -5931,28 +5959,70 @@ var PaymentsModule = class _PaymentsModule {
     };
     const stClient = this.deps.oracle.getStateTransitionClient?.();
     const trustBase = this.deps.oracle.getTrustBase?.();
-    if (!stClient || !trustBase) return result;
+    if (!stClient || !trustBase) {
+      console.log(`[V5-RESOLVE] resolveUnconfirmed: EARLY EXIT \u2014 stClient=${!!stClient} trustBase=${!!trustBase}`);
+      return result;
+    }
     const signingService = await this.createSigningService();
+    const submittedCount = Array.from(this.tokens.values()).filter((t) => t.status === "submitted").length;
+    console.log(`[V5-RESOLVE] resolveUnconfirmed: ${submittedCount} submitted token(s) to process`);
     for (const [tokenId, token] of this.tokens) {
       if (token.status !== "submitted") continue;
       const pending2 = this.parsePendingFinalization(token.sdkData);
       if (!pending2) {
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 16)}: no pending finalization metadata, skipping`);
         result.stillPending++;
         continue;
       }
       if (pending2.type === "v5_bundle") {
+        console.log(`[V5-RESOLVE] Processing ${tokenId.slice(0, 16)}... stage=${pending2.stage} attempt=${pending2.attemptCount}`);
         const progress = await this.resolveV5Token(tokenId, token, pending2, stClient, trustBase, signingService);
+        console.log(`[V5-RESOLVE] Result for ${tokenId.slice(0, 16)}...: ${progress} (stage now: ${pending2.stage})`);
         result.details.push({ tokenId, stage: pending2.stage, status: progress });
         if (progress === "resolved") result.resolved++;
         else if (progress === "failed") result.failed++;
         else result.stillPending++;
       }
     }
-    if (result.resolved > 0 || result.failed > 0) {
+    if (result.resolved > 0 || result.failed > 0 || result.stillPending > 0) {
+      console.log(`[V5-RESOLVE] Saving: resolved=${result.resolved} failed=${result.failed} stillPending=${result.stillPending}`);
       await this.save();
     }
     return result;
   }
+  /**
+   * Start a periodic interval that retries resolveUnconfirmed() until all
+   * tokens are confirmed or failed.  Stops automatically when nothing is
+   * pending and is cleaned up by destroy().
+   */
+  scheduleResolveUnconfirmed() {
+    if (this.resolveUnconfirmedTimer) return;
+    const hasUnconfirmed = Array.from(this.tokens.values()).some(
+      (t) => t.status === "submitted"
+    );
+    if (!hasUnconfirmed) {
+      console.log(`[V5-RESOLVE] scheduleResolveUnconfirmed: no submitted tokens, not starting timer`);
+      return;
+    }
+    console.log(`[V5-RESOLVE] scheduleResolveUnconfirmed: starting periodic retry (every ${_PaymentsModule.RESOLVE_UNCONFIRMED_INTERVAL_MS}ms)`);
+    this.resolveUnconfirmedTimer = setInterval(async () => {
+      try {
+        const result = await this.resolveUnconfirmed();
+        if (result.stillPending === 0) {
+          console.log(`[V5-RESOLVE] All tokens resolved, stopping periodic retry`);
+          this.stopResolveUnconfirmedPolling();
+        }
+      } catch (err) {
+        console.log(`[V5-RESOLVE] Periodic retry error:`, err);
+      }
+    }, _PaymentsModule.RESOLVE_UNCONFIRMED_INTERVAL_MS);
+  }
+  stopResolveUnconfirmedPolling() {
+    if (this.resolveUnconfirmedTimer) {
+      clearInterval(this.resolveUnconfirmedTimer);
+      this.resolveUnconfirmedTimer = null;
+    }
+  }
   // ===========================================================================
   // Private - V5 Lazy Resolution Helpers
   // ===========================================================================
@@ -5965,10 +6035,12 @@ var PaymentsModule = class _PaymentsModule {
     pending2.lastAttemptAt = Date.now();
     try {
       if (pending2.stage === "RECEIVED") {
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: RECEIVED \u2192 submitting mint commitment...`);
         const mintDataJson = JSON.parse(bundle.recipientMintData);
         const mintData = await MintTransactionData3.fromJSON(mintDataJson);
         const mintCommitment = await MintCommitment3.create(mintData);
         const mintResponse = await stClient.submitMintCommitment(mintCommitment);
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint response status=${mintResponse.status}`);
         if (mintResponse.status !== "SUCCESS" && mintResponse.status !== "REQUEST_ID_EXISTS") {
           throw new Error(`Mint submission failed: ${mintResponse.status}`);
         }
@@ -5976,22 +6048,27 @@ var PaymentsModule = class _PaymentsModule {
         this.updatePendingFinalization(token, pending2);
       }
       if (pending2.stage === "MINT_SUBMITTED") {
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: MINT_SUBMITTED \u2192 checking mint proof...`);
         const mintDataJson = JSON.parse(bundle.recipientMintData);
         const mintData = await MintTransactionData3.fromJSON(mintDataJson);
         const mintCommitment = await MintCommitment3.create(mintData);
         const proof = await this.quickProofCheck(stClient, trustBase, mintCommitment);
         if (!proof) {
+          console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint proof not yet available, staying MINT_SUBMITTED`);
           this.updatePendingFinalization(token, pending2);
           return "pending";
         }
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint proof obtained!`);
         pending2.mintProofJson = JSON.stringify(proof);
         pending2.stage = "MINT_PROVEN";
         this.updatePendingFinalization(token, pending2);
       }
       if (pending2.stage === "MINT_PROVEN") {
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: MINT_PROVEN \u2192 submitting transfer commitment...`);
         const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
         const transferCommitment = await TransferCommitment4.fromJSON(transferCommitmentJson);
         const transferResponse = await stClient.submitTransferCommitment(transferCommitment);
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer response status=${transferResponse.status}`);
         if (transferResponse.status !== "SUCCESS" && transferResponse.status !== "REQUEST_ID_EXISTS") {
           throw new Error(`Transfer submission failed: ${transferResponse.status}`);
         }
@@ -5999,13 +6076,16 @@ var PaymentsModule = class _PaymentsModule {
         this.updatePendingFinalization(token, pending2);
       }
       if (pending2.stage === "TRANSFER_SUBMITTED") {
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: TRANSFER_SUBMITTED \u2192 checking transfer proof...`);
         const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
         const transferCommitment = await TransferCommitment4.fromJSON(transferCommitmentJson);
         const proof = await this.quickProofCheck(stClient, trustBase, transferCommitment);
         if (!proof) {
+          console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer proof not yet available, staying TRANSFER_SUBMITTED`);
           this.updatePendingFinalization(token, pending2);
           return "pending";
         }
+        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer proof obtained! Finalizing...`);
         const finalizedToken = await this.finalizeFromV5Bundle(bundle, pending2, signingService, stClient, trustBase);
         const confirmedToken = {
           id: token.id,
@@ -6021,6 +6101,12 @@ var PaymentsModule = class _PaymentsModule {
           sdkData: JSON.stringify(finalizedToken.toJSON())
         };
         this.tokens.set(tokenId, confirmedToken);
+        this.deps.emitEvent("transfer:confirmed", {
+          id: crypto.randomUUID(),
+          status: "completed",
+          tokens: [confirmedToken],
+          tokenTransfers: []
+        });
         this.log(`V5 token resolved: ${tokenId.slice(0, 8)}...`);
         return "resolved";
       }
@@ -6162,11 +6248,20 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
     if (pendingTokens.length > 0) {
+      const json = JSON.stringify(pendingTokens);
+      this.log(`[V5-PERSIST] Saving ${pendingTokens.length} pending V5 token(s): ${pendingTokens.map((t) => t.id.slice(0, 16)).join(", ")} (${json.length} bytes)`);
       await this.deps.storage.set(
         STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS,
-        JSON.stringify(pendingTokens)
+        json
       );
+      const verify = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS);
+      if (!verify) {
+        console.error("[Payments][V5-PERSIST] CRITICAL: KV write succeeded but read-back is empty!");
+      } else {
+        this.log(`[V5-PERSIST] Verified: read-back ${verify.length} bytes`);
+      }
     } else {
+      this.log(`[V5-PERSIST] No pending V5 tokens to save (total tokens: ${this.tokens.size}), clearing KV`);
       await this.deps.storage.set(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS, "");
     }
   }
@@ -6176,16 +6271,47 @@ var PaymentsModule = class _PaymentsModule {
    */
   async loadPendingV5Tokens() {
     const data = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS);
+    this.log(`[V5-PERSIST] loadPendingV5Tokens: KV data = ${data ? `${data.length} bytes` : "null/empty"}`);
     if (!data) return;
     try {
       const pendingTokens = JSON.parse(data);
+      this.log(`[V5-PERSIST] Parsed ${pendingTokens.length} pending V5 token(s): ${pendingTokens.map((t) => t.id.slice(0, 16)).join(", ")}`);
       for (const token of pendingTokens) {
         if (!this.tokens.has(token.id)) {
           this.tokens.set(token.id, token);
+          this.log(`[V5-PERSIST] Restored token ${token.id.slice(0, 16)} (status=${token.status})`);
+        } else {
+          this.log(`[V5-PERSIST] Token ${token.id.slice(0, 16)} already in map, skipping`);
         }
       }
-      if (pendingTokens.length > 0) {
-        this.log(`Restored ${pendingTokens.length} pending V5 token(s)`);
+    } catch (err) {
+      console.error("[Payments][V5-PERSIST] Failed to parse pending V5 tokens:", err);
+    }
+  }
+  /**
+   * Persist the set of processed splitGroupIds to KV storage.
+   * This ensures Nostr re-deliveries are ignored across page reloads,
+   * even when the confirmed token's in-memory ID differs from v5split_{id}.
+   */
+  async saveProcessedSplitGroupIds() {
+    const ids = Array.from(this.processedSplitGroupIds);
+    if (ids.length > 0) {
+      await this.deps.storage.set(
+        STORAGE_KEYS_ADDRESS.PROCESSED_SPLIT_GROUP_IDS,
+        JSON.stringify(ids)
+      );
+    }
+  }
+  /**
+   * Load processed splitGroupIds from KV storage.
+   */
+  async loadProcessedSplitGroupIds() {
+    const data = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PROCESSED_SPLIT_GROUP_IDS);
+    if (!data) return;
+    try {
+      const ids = JSON.parse(data);
+      for (const id of ids) {
+        this.processedSplitGroupIds.add(id);
       }
     } catch {
     }
@@ -6840,7 +6966,32 @@ var PaymentsModule = class _PaymentsModule {
         try {
           const result = await provider.sync(localData);
           if (result.success && result.merged) {
+            const savedTokens = new Map(this.tokens);
             this.loadFromStorageData(result.merged);
+            let restoredCount = 0;
+            for (const [tokenId, token] of savedTokens) {
+              if (this.tokens.has(tokenId)) continue;
+              const sdkTokenId = extractTokenIdFromSdkData(token.sdkData);
+              const stateHash = extractStateHashFromSdkData(token.sdkData);
+              if (sdkTokenId && stateHash && this.isStateTombstoned(sdkTokenId, stateHash)) {
+                continue;
+              }
+              if (sdkTokenId) {
+                let hasEquivalent = false;
+                for (const existing of this.tokens.values()) {
+                  if (extractTokenIdFromSdkData(existing.sdkData) === sdkTokenId) {
+                    hasEquivalent = true;
+                    break;
+                  }
+                }
+                if (hasEquivalent) continue;
+              }
+              this.tokens.set(tokenId, token);
+              restoredCount++;
+            }
+            if (restoredCount > 0) {
+              console.log(`[Payments] Sync: restored ${restoredCount} token(s) lost by loadFromStorageData`);
+            }
             if (this.nametags.length === 0 && savedNametags.length > 0) {
               this.nametags = savedNametags;
             }
@@ -7174,8 +7325,9 @@ var PaymentsModule = class _PaymentsModule {
         return;
       }
       this.tokens.set(token.id, token);
+      console.log(`[Payments][DEBUG] NOSTR-FIRST: saving token id=${token.id.slice(0, 16)} status=${token.status} sdkData.length=${token.sdkData?.length}`);
       await this.save();
-      this.log(`NOSTR-FIRST: Token ${token.id.slice(0, 8)}... added as submitted (unconfirmed)`);
+      console.log(`[Payments][DEBUG] NOSTR-FIRST: save() completed, tokens.size=${this.tokens.size}`);
       const senderInfo = await this.resolveSenderInfo(transfer.senderTransportPubkey);
       const incomingTransfer = {
         id: transfer.id,
@@ -7332,8 +7484,12 @@ var PaymentsModule = class _PaymentsModule {
     }
   }
   async handleIncomingTransfer(transfer) {
+    if (!this.loaded && this.loadedPromise) {
+      await this.loadedPromise;
+    }
     try {
       const payload = transfer.payload;
+      console.log("[Payments][DEBUG] handleIncomingTransfer: keys=", Object.keys(payload).join(","));
       let instantBundle = null;
       if (isInstantSplitBundle(payload)) {
         instantBundle = payload;
@@ -7365,7 +7521,7 @@ var PaymentsModule = class _PaymentsModule {
         return;
       }
       if (payload.sourceToken && payload.commitmentData && !payload.transferTx) {
-        this.log("Processing NOSTR-FIRST commitment-only transfer...");
+        console.log("[Payments][DEBUG] >>> NOSTR-FIRST commitment-only transfer detected");
         await this.handleCommitmentOnlyTransfer(transfer, payload);
         return;
       }
@@ -7528,17 +7684,24 @@ var PaymentsModule = class _PaymentsModule {
   // ===========================================================================
   async save() {
     const providers = this.getTokenStorageProviders();
-    if (providers.size === 0) {
-      this.log("No token storage providers - tokens not persisted");
-      return;
-    }
-    const data = await this.createStorageData();
-    for (const [id, provider] of providers) {
-      try {
-        await provider.save(data);
-      } catch (err) {
-        console.error(`[Payments] Failed to save to provider ${id}:`, err);
+    const tokenStats = Array.from(this.tokens.values()).map((t) => {
+      const txf = tokenToTxf(t);
+      return `${t.id.slice(0, 12)}(${t.status},txf=${!!txf})`;
+    });
+    console.log(`[Payments][DEBUG] save(): providers=${providers.size}, tokens=[${tokenStats.join(", ")}]`);
+    if (providers.size > 0) {
+      const data = await this.createStorageData();
+      const dataKeys = Object.keys(data).filter((k) => k.startsWith("token-"));
+      console.log(`[Payments][DEBUG] save(): TXF keys=${dataKeys.length} (${dataKeys.join(", ")})`);
+      for (const [id, provider] of providers) {
+        try {
+          await provider.save(data);
+        } catch (err) {
+          console.error(`[Payments] Failed to save to provider ${id}:`, err);
+        }
       }
+    } else {
+      console.log("[Payments][DEBUG] save(): No token storage providers - TXF not persisted");
     }
     await this.savePendingV5Tokens();
   }
@@ -7574,6 +7737,7 @@ var PaymentsModule = class _PaymentsModule {
   }
   loadFromStorageData(data) {
     const parsed = parseTxfStorageData(data);
+    console.log(`[Payments][DEBUG] loadFromStorageData: parsed ${parsed.tokens.length} tokens, ${parsed.tombstones.length} tombstones, errors=[${parsed.validationErrors.join("; ")}]`);
     this.tombstones = parsed.tombstones;
     this.tokens.clear();
     for (const token of parsed.tokens) {