@unicitylabs/sphere-sdk 0.4.9 → 0.5.1

package/dist/index.cjs

@@ -107,7 +107,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,
@@ -3874,7 +3876,7 @@ var InstantSplitExecutor = class {
         token: JSON.stringify(bundle),
         proof: null,
         // Proof is included in the bundle
-        memo: "INSTANT_SPLIT_V5",
+        memo: options?.memo,
         sender: {
           transportPubkey: senderPubkey
         }
@@ -4433,6 +4435,11 @@ var import_MintCommitment3 = require("@unicitylabs/state-transition-sdk/lib/tran
 var import_MintTransactionData3 = require("@unicitylabs/state-transition-sdk/lib/transaction/MintTransactionData");
 var import_InclusionProofUtils5 = require("@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils");
 var import_InclusionProof = require("@unicitylabs/state-transition-sdk/lib/transaction/InclusionProof");
+function computeHistoryDedupKey(type, tokenId, transferId) {
+  if (type === "SENT" && transferId) return `${type}_transfer_${transferId}`;
+  if (tokenId) return `${type}_${tokenId}`;
+  return `${type}_${crypto.randomUUID()}`;
+}
 function enrichWithRegistry(info) {
   const registry = TokenRegistry.getInstance();
   const def = registry.getDefinition(info.coinId);
@@ -4731,7 +4738,7 @@ var PaymentsModule = class _PaymentsModule {
   tombstones = [];
   archivedTokens = /* @__PURE__ */ new Map();
   forkedTokens = /* @__PURE__ */ new Map();
-  transactionHistory = [];
+  _historyCache = [];
   nametags = [];
   // Payment Requests State (Incoming)
   paymentRequests = [];
@@ -4751,6 +4758,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;
@@ -4800,7 +4818,7 @@ var PaymentsModule = class _PaymentsModule {
     this.tombstones = [];
     this.archivedTokens.clear();
     this.forkedTokens.clear();
-    this.transactionHistory = [];
+    this._historyCache = [];
     this.nametags = [];
     this.deps = deps;
     this.priceProvider = deps.price ?? null;
@@ -4836,38 +4854,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();
-    const historyData = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
-    if (historyData) {
-      try {
-        this.transactionHistory = JSON.parse(historyData);
-      } catch {
-        this.transactionHistory = [];
       }
-    }
-    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.
@@ -4886,6 +4906,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"));
@@ -4945,7 +4966,7 @@ var PaymentsModule = class _PaymentsModule {
       }
       await this.saveToOutbox(result, recipientPubkey);
       result.status = "submitted";
-      const recipientNametag = request.recipient.startsWith("@") ? request.recipient.slice(1) : void 0;
+      const recipientNametag = peerInfo?.nametag || (request.recipient.startsWith("@") ? request.recipient.slice(1) : void 0);
       const transferMode = request.transferMode ?? "instant";
       if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
         if (transferMode === "conservative") {
@@ -4976,7 +4997,7 @@ var PaymentsModule = class _PaymentsModule {
             updatedAt: Date.now(),
             sdkData: JSON.stringify(changeTokenData)
           };
-          await this.addToken(changeUiToken, true);
+          await this.addToken(changeUiToken);
           this.log(`Conservative split: change token saved: ${changeUiToken.id}`);
           await this.deps.transport.sendTokenTransfer(recipientPubkey, {
             sourceToken: JSON.stringify(splitResult.tokenForRecipient.toJSON()),
@@ -4985,7 +5006,7 @@ var PaymentsModule = class _PaymentsModule {
           });
           const splitCommitmentRequestId = splitResult.recipientTransferTx?.data?.requestId ?? splitResult.recipientTransferTx?.requestId;
           const splitRequestIdHex = splitCommitmentRequestId instanceof Uint8Array ? Array.from(splitCommitmentRequestId).map((b) => b.toString(16).padStart(2, "0")).join("") : splitCommitmentRequestId ? String(splitCommitmentRequestId) : void 0;
-          await this.removeToken(splitPlan.tokenToSplit.uiToken.id, recipientNametag, true);
+          await this.removeToken(splitPlan.tokenToSplit.uiToken.id);
           result.tokenTransfers.push({
             sourceTokenId: splitPlan.tokenToSplit.uiToken.id,
             method: "split",
@@ -5010,6 +5031,7 @@ var PaymentsModule = class _PaymentsModule {
             this.deps.transport,
             recipientPubkey,
             {
+              memo: request.memo,
               onChangeTokenCreated: async (changeToken) => {
                 const changeTokenData = changeToken.toJSON();
                 const uiToken = {
@@ -5025,7 +5047,7 @@ var PaymentsModule = class _PaymentsModule {
                   updatedAt: Date.now(),
                   sdkData: JSON.stringify(changeTokenData)
                 };
-                await this.addToken(uiToken, true);
+                await this.addToken(uiToken);
                 this.log(`Change token saved via background: ${uiToken.id}`);
               },
               onStorageSync: async () => {
@@ -5040,7 +5062,7 @@ var PaymentsModule = class _PaymentsModule {
           if (instantResult.backgroundPromise) {
             this.pendingBackgroundTasks.push(instantResult.backgroundPromise);
           }
-          await this.removeToken(splitPlan.tokenToSplit.uiToken.id, recipientNametag);
+          await this.removeToken(splitPlan.tokenToSplit.uiToken.id);
           result.tokenTransfers.push({
             sourceTokenId: splitPlan.tokenToSplit.uiToken.id,
             method: "split",
@@ -5087,20 +5109,25 @@ var PaymentsModule = class _PaymentsModule {
           requestIdHex
         });
         this.log(`Token ${token.id} sent via ${transferMode.toUpperCase()}, requestId: ${requestIdHex}`);
-        await this.removeToken(token.id, recipientNametag, true);
+        await this.removeToken(token.id);
       }
       result.status = "delivered";
       await this.save();
       await this.removeFromOutbox(result.id);
       result.status = "completed";
+      const sentTokenId = result.tokens[0] ? extractTokenIdFromSdkData(result.tokens[0].sdkData) : void 0;
       await this.addToHistory({
         type: "SENT",
         amount: request.amount,
         coinId: request.coinId,
         symbol: this.getCoinSymbol(request.coinId),
         timestamp: Date.now(),
+        recipientPubkey,
         recipientNametag,
-        transferId: result.id
+        recipientAddress: peerInfo?.directAddress || recipientAddress?.toString() || recipientPubkey,
+        memo: request.memo,
+        transferId: result.id,
+        tokenId: sentTokenId || void 0
       });
       this.deps.emitEvent("transfer:confirmed", result);
       return result;
@@ -5211,6 +5238,7 @@ var PaymentsModule = class _PaymentsModule {
         recipientPubkey,
         {
           ...options,
+          memo: request.memo,
           onChangeTokenCreated: async (changeToken) => {
             const changeTokenData = changeToken.toJSON();
             const uiToken = {
@@ -5226,7 +5254,7 @@ var PaymentsModule = class _PaymentsModule {
               updatedAt: Date.now(),
               sdkData: JSON.stringify(changeTokenData)
             };
-            await this.addToken(uiToken, true);
+            await this.addToken(uiToken);
             this.log(`Change token saved via background: ${uiToken.id}`);
           },
           onStorageSync: async () => {
@@ -5239,15 +5267,20 @@ var PaymentsModule = class _PaymentsModule {
         if (result.backgroundPromise) {
           this.pendingBackgroundTasks.push(result.backgroundPromise);
         }
-        const recipientNametag = request.recipient.startsWith("@") ? request.recipient.slice(1) : void 0;
-        await this.removeToken(tokenToSplit.id, recipientNametag, true);
+        await this.removeToken(tokenToSplit.id);
+        const recipientNametag = peerInfo?.nametag || (request.recipient.startsWith("@") ? request.recipient.slice(1) : void 0);
+        const splitTokenId = extractTokenIdFromSdkData(tokenToSplit.sdkData);
         await this.addToHistory({
           type: "SENT",
           amount: request.amount,
           coinId: request.coinId,
           symbol: this.getCoinSymbol(request.coinId),
           timestamp: Date.now(),
-          recipientNametag
+          recipientPubkey,
+          recipientNametag,
+          recipientAddress: peerInfo?.directAddress || recipientAddress?.toString() || recipientPubkey,
+          memo: request.memo,
+          tokenId: splitTokenId || void 0
         });
         await this.save();
       } else {
@@ -5278,15 +5311,18 @@ var PaymentsModule = class _PaymentsModule {
    * @param senderPubkey - Sender's public key for verification
    * @returns Processing result with finalized token
    */
-  async processInstantSplitBundle(bundle, senderPubkey) {
+  async processInstantSplitBundle(bundle, senderPubkey, memo) {
     this.ensureInitialized();
+    if (!this.loaded && this.loadedPromise) {
+      await this.loadedPromise;
+    }
     if (!isInstantSplitBundleV5(bundle)) {
-      return this.processInstantSplitBundleSync(bundle, senderPubkey);
+      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();
@@ -5311,17 +5347,33 @@ var PaymentsModule = class _PaymentsModule {
         updatedAt: Date.now(),
         sdkData: JSON.stringify({ _pendingFinalization: pendingData })
       };
-      await this.addToken(uiToken, false);
-      this.log(`V5 bundle saved as unconfirmed: ${uiToken.id.slice(0, 8)}...`);
+      await this.addToken(uiToken);
+      this.processedSplitGroupIds.add(bundle.splitGroupId);
+      await this.saveProcessedSplitGroupIds();
+      const senderInfo = await this.resolveSenderInfo(senderPubkey);
+      await this.addToHistory({
+        type: "RECEIVED",
+        amount: bundle.amount,
+        coinId: bundle.coinId,
+        symbol: uiToken.symbol,
+        timestamp: Date.now(),
+        senderPubkey,
+        ...senderInfo,
+        memo,
+        tokenId: deterministicId
+      });
       this.deps.emitEvent("transfer:incoming", {
         id: bundle.splitGroupId,
         senderPubkey,
+        senderNametag: senderInfo.senderNametag,
         tokens: [uiToken],
+        memo,
         receivedAt: Date.now()
       });
       await this.save();
       this.resolveUnconfirmed().catch(() => {
       });
+      this.scheduleResolveUnconfirmed();
       return { success: true, durationMs: 0 };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -5336,7 +5388,7 @@ var PaymentsModule = class _PaymentsModule {
    * Synchronous V4 bundle processing (dev mode only).
    * Kept for backward compatibility with V4 bundles.
    */
-  async processInstantSplitBundleSync(bundle, senderPubkey) {
+  async processInstantSplitBundleSync(bundle, senderPubkey, memo) {
     try {
       const signingService = await this.createSigningService();
       const stClient = this.deps.oracle.getStateTransitionClient?.();
@@ -5396,19 +5448,26 @@ var PaymentsModule = class _PaymentsModule {
           sdkData: JSON.stringify(tokenData)
         };
         await this.addToken(uiToken);
+        const receivedTokenId = extractTokenIdFromSdkData(uiToken.sdkData);
+        const senderInfo = await this.resolveSenderInfo(senderPubkey);
         await this.addToHistory({
           type: "RECEIVED",
           amount: bundle.amount,
           coinId: info.coinId,
           symbol: info.symbol,
           timestamp: Date.now(),
-          senderPubkey
+          senderPubkey,
+          ...senderInfo,
+          memo,
+          tokenId: receivedTokenId || uiToken.id
         });
         await this.save();
         this.deps.emitEvent("transfer:incoming", {
           id: bundle.splitGroupId,
           senderPubkey,
+          senderNametag: senderInfo.senderNametag,
           tokens: [uiToken],
+          memo,
           receivedAt: Date.now()
         });
       }
@@ -6061,28 +6120,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
   // ===========================================================================
@@ -6095,10 +6196,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 import_MintTransactionData3.MintTransactionData.fromJSON(mintDataJson);
         const mintCommitment = await import_MintCommitment3.MintCommitment.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}`);
         }
@@ -6106,22 +6209,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 import_MintTransactionData3.MintTransactionData.fromJSON(mintDataJson);
         const mintCommitment = await import_MintCommitment3.MintCommitment.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 import_TransferCommitment4.TransferCommitment.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}`);
         }
@@ -6129,13 +6237,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 import_TransferCommitment4.TransferCommitment.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,
@@ -6151,13 +6262,11 @@ var PaymentsModule = class _PaymentsModule {
           sdkData: JSON.stringify(finalizedToken.toJSON())
         };
         this.tokens.set(tokenId, confirmedToken);
-        await this.addToHistory({
-          type: "RECEIVED",
-          amount: confirmedToken.amount,
-          coinId: confirmedToken.coinId,
-          symbol: confirmedToken.symbol || "UNK",
-          timestamp: Date.now(),
-          senderPubkey: pending2.senderPubkey
+        this.deps.emitEvent("transfer:confirmed", {
+          id: crypto.randomUUID(),
+          status: "completed",
+          tokens: [confirmedToken],
+          tokenTransfers: []
         });
         this.log(`V5 token resolved: ${tokenId.slice(0, 8)}...`);
         return "resolved";
@@ -6300,11 +6409,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, "");
     }
   }
@@ -6314,16 +6432,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 {
     }
@@ -6342,10 +6491,9 @@ var PaymentsModule = class _PaymentsModule {
    *   the old state is archived and replaced with the incoming one.
    *
    * @param token - The token to add.
-   * @param skipHistory - When `true`, do not create a `RECEIVED` transaction history entry (default `false`).
    * @returns `true` if the token was added, `false` if rejected as duplicate or tombstoned.
    */
-  async addToken(token, skipHistory = false) {
+  async addToken(token) {
     this.ensureInitialized();
     const incomingTokenId = extractTokenIdFromSdkData(token.sdkData);
     const incomingStateHash = extractStateHashFromSdkData(token.sdkData);
@@ -6391,15 +6539,6 @@ var PaymentsModule = class _PaymentsModule {
     }
     this.tokens.set(token.id, token);
     await this.archiveToken(token);
-    if (!skipHistory && token.coinId && token.amount) {
-      await this.addToHistory({
-        type: "RECEIVED",
-        amount: token.amount,
-        coinId: token.coinId,
-        symbol: token.symbol || "UNK",
-        timestamp: token.createdAt || Date.now()
-      });
-    }
     await this.save();
     this.log(`Added token ${token.id}, total: ${this.tokens.size}`);
     return true;
@@ -6426,7 +6565,7 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
     if (!found) {
-      await this.addToken(token, true);
+      await this.addToken(token);
       return;
     }
     await this.archiveToken(token);
@@ -6441,10 +6580,8 @@ var PaymentsModule = class _PaymentsModule {
    * entry is created unless `skipHistory` is `true`.
    *
    * @param tokenId - Local UUID of the token to remove.
-   * @param recipientNametag - Optional nametag of the transfer recipient (for history).
-   * @param skipHistory - When `true`, skip creating a transaction history entry (default `false`).
    */
-  async removeToken(tokenId, recipientNametag, skipHistory = false) {
+  async removeToken(tokenId) {
     this.ensureInitialized();
     const token = this.tokens.get(tokenId);
     if (!token) return;
@@ -6462,16 +6599,6 @@ var PaymentsModule = class _PaymentsModule {
       this.log(`Warning: Could not create tombstone for token ${tokenId.slice(0, 8)}... (missing tokenId or stateHash)`);
     }
     this.tokens.delete(tokenId);
-    if (!skipHistory && token.coinId && token.amount) {
-      await this.addToHistory({
-        type: "SENT",
-        amount: token.amount,
-        coinId: token.coinId,
-        symbol: token.symbol || "UNK",
-        timestamp: Date.now(),
-        recipientNametag
-      });
-    }
     await this.save();
   }
   // ===========================================================================
@@ -6696,26 +6823,104 @@ var PaymentsModule = class _PaymentsModule {
    * @returns Array of {@link TransactionHistoryEntry} objects in descending timestamp order.
    */
   getHistory() {
-    return [...this.transactionHistory].sort((a, b) => b.timestamp - a.timestamp);
+    return [...this._historyCache].sort((a, b) => b.timestamp - a.timestamp);
+  }
+  /**
+   * Best-effort resolve sender's DIRECT address and nametag from their transport pubkey.
+   * Returns empty object if transport doesn't support resolution or lookup fails.
+   */
+  async resolveSenderInfo(senderTransportPubkey) {
+    try {
+      if (this.deps?.transport?.resolveTransportPubkeyInfo) {
+        const peerInfo = await this.deps.transport.resolveTransportPubkeyInfo(senderTransportPubkey);
+        if (peerInfo) {
+          return {
+            senderAddress: peerInfo.directAddress || void 0,
+            senderNametag: peerInfo.nametag || void 0
+          };
+        }
+      }
+    } catch {
+    }
+    return {};
   }
   /**
    * Append an entry to the transaction history.
    *
-   * A unique `id` is auto-generated. The entry is immediately persisted to storage.
+   * A unique `id` and `dedupKey` are auto-generated. The entry is persisted to
+   * the local token storage provider's `history` store (IndexedDB / file).
+   * Duplicate entries with the same `dedupKey` are silently ignored (upsert).
    *
-   * @param entry - History entry fields (without `id`).
+   * @param entry - History entry fields (without `id` and `dedupKey`).
    */
   async addToHistory(entry) {
     this.ensureInitialized();
+    const dedupKey = computeHistoryDedupKey(entry.type, entry.tokenId, entry.transferId);
     const historyEntry = {
       id: crypto.randomUUID(),
+      dedupKey,
       ...entry
     };
-    this.transactionHistory.push(historyEntry);
-    await this.deps.storage.set(
-      STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY,
-      JSON.stringify(this.transactionHistory)
-    );
+    const provider = this.getLocalTokenStorageProvider();
+    if (provider?.addHistoryEntry) {
+      await provider.addHistoryEntry(historyEntry);
+    }
+    const existingIdx = this._historyCache.findIndex((e) => e.dedupKey === dedupKey);
+    if (existingIdx >= 0) {
+      this._historyCache[existingIdx] = historyEntry;
+    } else {
+      this._historyCache.push(historyEntry);
+    }
+    this.deps.emitEvent("history:updated", historyEntry);
+  }
+  /**
+   * Load history from the local token storage provider into the in-memory cache.
+   * Also performs one-time migration from legacy KV storage.
+   */
+  async loadHistory() {
+    const provider = this.getLocalTokenStorageProvider();
+    if (provider?.getHistoryEntries) {
+      this._historyCache = await provider.getHistoryEntries();
+      const legacyData = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
+      if (legacyData) {
+        try {
+          const legacyEntries = JSON.parse(legacyData);
+          const records = legacyEntries.map((e) => ({
+            ...e,
+            dedupKey: e.dedupKey || computeHistoryDedupKey(e.type, e.tokenId, e.transferId)
+          }));
+          const imported = await provider.importHistoryEntries?.(records) ?? 0;
+          if (imported > 0) {
+            this._historyCache = await provider.getHistoryEntries();
+            this.log(`Migrated ${imported} history entries from KV to history store`);
+          }
+          await this.deps.storage.remove(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
+        } catch {
+        }
+      }
+    } else {
+      const historyData = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
+      if (historyData) {
+        try {
+          this._historyCache = JSON.parse(historyData);
+        } catch {
+          this._historyCache = [];
+        }
+      }
+    }
+  }
+  /**
+   * Get the first local token storage provider (for history operations).
+   */
+  getLocalTokenStorageProvider() {
+    const providers = this.getTokenStorageProviders();
+    for (const [, provider] of providers) {
+      if (provider.type === "local") return provider;
+    }
+    for (const [, provider] of providers) {
+      return provider;
+    }
+    return null;
   }
   // ===========================================================================
   // Public API - Nametag
@@ -6922,7 +7127,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;
             }
@@ -7256,16 +7486,30 @@ 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,
         senderPubkey: transfer.senderTransportPubkey,
+        senderNametag: senderInfo.senderNametag,
         tokens: [token],
         memo: payload.memo,
         receivedAt: transfer.timestamp
       };
       this.deps.emitEvent("transfer:incoming", incomingTransfer);
+      await this.addToHistory({
+        type: "RECEIVED",
+        amount: token.amount,
+        coinId: token.coinId,
+        symbol: token.symbol,
+        timestamp: Date.now(),
+        senderPubkey: transfer.senderTransportPubkey,
+        ...senderInfo,
+        memo: payload.memo,
+        tokenId: nostrTokenId || token.id
+      });
       try {
         const commitment = await import_TransferCommitment4.TransferCommitment.fromJSON(commitmentInput);
         const requestIdBytes = commitment.requestId;
@@ -7283,7 +7527,7 @@ var PaymentsModule = class _PaymentsModule {
           attemptCount: 0,
           lastAttemptAt: 0,
           onProofReceived: async (tokenId) => {
-            await this.finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput, transfer.senderTransportPubkey);
+            await this.finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput);
           }
         });
       } catch (err) {
@@ -7342,7 +7586,7 @@ var PaymentsModule = class _PaymentsModule {
   /**
    * Finalize a received token after proof is available
    */
-  async finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput, senderPubkey) {
+  async finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput) {
     try {
       const token = this.tokens.get(tokenId);
       if (!token) {
@@ -7390,14 +7634,6 @@ var PaymentsModule = class _PaymentsModule {
         tokens: [finalizedToken],
         tokenTransfers: []
       });
-      await this.addToHistory({
-        type: "RECEIVED",
-        amount: finalizedToken.amount,
-        coinId: finalizedToken.coinId,
-        symbol: finalizedToken.symbol,
-        timestamp: Date.now(),
-        senderPubkey
-      });
     } catch (error) {
       console.error("[Payments] Failed to finalize received token:", error);
       const token = this.tokens.get(tokenId);
@@ -7409,8 +7645,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;
@@ -7428,7 +7668,8 @@ var PaymentsModule = class _PaymentsModule {
         try {
           const result = await this.processInstantSplitBundle(
             instantBundle,
-            transfer.senderTransportPubkey
+            transfer.senderTransportPubkey,
+            payload.memo
           );
           if (result.success) {
             this.log("INSTANT_SPLIT processed successfully");
@@ -7441,7 +7682,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;
       }
@@ -7546,10 +7787,26 @@ var PaymentsModule = class _PaymentsModule {
         updatedAt: Date.now(),
         sdkData: typeof tokenData === "string" ? tokenData : JSON.stringify(tokenData)
       };
-      await this.addToken(token);
+      const added = await this.addToken(token);
+      const senderInfo = await this.resolveSenderInfo(transfer.senderTransportPubkey);
+      if (added) {
+        const incomingTokenId = extractTokenIdFromSdkData(token.sdkData);
+        await this.addToHistory({
+          type: "RECEIVED",
+          amount: token.amount,
+          coinId: token.coinId,
+          symbol: token.symbol,
+          timestamp: Date.now(),
+          senderPubkey: transfer.senderTransportPubkey,
+          ...senderInfo,
+          memo: payload.memo,
+          tokenId: incomingTokenId || token.id
+        });
+      }
       const incomingTransfer = {
         id: transfer.id,
         senderPubkey: transfer.senderTransportPubkey,
+        senderNametag: senderInfo.senderNametag,
         tokens: [token],
         memo: payload.memo,
         receivedAt: transfer.timestamp
@@ -7588,17 +7845,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();
   }
@@ -7634,6 +7898,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) {