@unicitylabs/sphere-sdk 0.5.1 → 0.5.3

package/dist/core/index.cjs

@@ -105,7 +105,9 @@ var init_constants = __esm({
       /** Group chat: processed event IDs for deduplication */
       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"
+      PROCESSED_SPLIT_GROUP_IDS: "processed_split_group_ids",
+      /** Processed V6 combined transfer IDs for Nostr re-delivery dedup */
+      PROCESSED_COMBINED_TRANSFER_IDS: "processed_combined_transfer_ids"
     };
     STORAGE_KEYS = {
       ...STORAGE_KEYS_GLOBAL,
@@ -2599,7 +2601,7 @@ init_constants();
 // types/txf.ts
 var ARCHIVED_PREFIX = "archived-";
 var FORKED_PREFIX = "_forked_";
-var RESERVED_KEYS = ["_meta", "_nametag", "_nametags", "_tombstones", "_invalidatedNametags", "_outbox", "_mintOutbox", "_sent", "_invalid", "_integrity"];
+var RESERVED_KEYS = ["_meta", "_nametag", "_nametags", "_tombstones", "_invalidatedNametags", "_outbox", "_mintOutbox", "_sent", "_invalid", "_integrity", "_history"];
 function isTokenKey(key) {
   return key.startsWith("_") && !key.startsWith(ARCHIVED_PREFIX) && !key.startsWith(FORKED_PREFIX) && !RESERVED_KEYS.includes(key);
 }
@@ -3184,6 +3186,9 @@ async function buildTxfStorageData(tokens, meta, options) {
   if (options?.invalidatedNametags && options.invalidatedNametags.length > 0) {
     storageData._invalidatedNametags = options.invalidatedNametags;
   }
+  if (options?.historyEntries && options.historyEntries.length > 0) {
+    storageData._history = options.historyEntries;
+  }
   for (const token of tokens) {
     const txf = tokenToTxf(token);
     if (txf) {
@@ -3217,6 +3222,7 @@ function parseTxfStorageData(data) {
     outboxEntries: [],
     mintOutboxEntries: [],
     invalidatedNametags: [],
+    historyEntries: [],
     validationErrors: []
   };
   if (!data || typeof data !== "object") {
@@ -3270,6 +3276,13 @@ function parseTxfStorageData(data) {
       }
     }
   }
+  if (Array.isArray(storageData._history)) {
+    for (const entry of storageData._history) {
+      if (typeof entry === "object" && entry !== null && typeof entry.dedupKey === "string" && typeof entry.type === "string") {
+        result.historyEntries.push(entry);
+      }
+    }
+  }
   for (const key of Object.keys(storageData)) {
     if (isTokenKey(key)) {
       const tokenId = tokenIdFromKey(key);
@@ -3381,14 +3394,149 @@ var InstantSplitExecutor = class {
     this.devMode = config.devMode ?? false;
   }
   /**
-   * Execute an instant split transfer with V5 optimized flow.
+   * Build a V5 split bundle WITHOUT sending it via transport.
    *
-   * Critical path (~2.3s):
+   * Steps 1-5 of the V5 flow:
    * 1. Create and submit burn commitment
    * 2. Wait for burn proof
    * 3. Create mint commitments with SplitMintReason
    * 4. Create transfer commitment (no mint proof needed)
-   * 5. Send bundle via transport
+   * 5. Package V5 bundle
+   *
+   * The caller is responsible for sending the bundle and then calling
+   * `startBackground()` on the result to begin mint proof + change token creation.
+   */
+  async buildSplitBundle(tokenToSplit, splitAmount, remainderAmount, coinIdHex, recipientAddress, options) {
+    const splitGroupId = crypto.randomUUID();
+    const tokenIdHex = toHex2(tokenToSplit.id.bytes);
+    console.log(`[InstantSplit] Building V5 bundle for token ${tokenIdHex.slice(0, 8)}...`);
+    const coinId = new import_CoinId3.CoinId(fromHex2(coinIdHex));
+    const seedString = `${tokenIdHex}_${splitAmount.toString()}_${remainderAmount.toString()}_${Date.now()}`;
+    const recipientTokenId = new import_TokenId3.TokenId(await sha2563(seedString));
+    const senderTokenId = new import_TokenId3.TokenId(await sha2563(seedString + "_sender"));
+    const recipientSalt = await sha2563(seedString + "_recipient_salt");
+    const senderSalt = await sha2563(seedString + "_sender_salt");
+    const senderAddressRef = await import_UnmaskedPredicateReference2.UnmaskedPredicateReference.create(
+      tokenToSplit.type,
+      this.signingService.algorithm,
+      this.signingService.publicKey,
+      import_HashAlgorithm3.HashAlgorithm.SHA256
+    );
+    const senderAddress = await senderAddressRef.toAddress();
+    const builder = new import_TokenSplitBuilder2.TokenSplitBuilder();
+    const coinDataA = import_TokenCoinData2.TokenCoinData.create([[coinId, splitAmount]]);
+    builder.createToken(
+      recipientTokenId,
+      tokenToSplit.type,
+      new Uint8Array(0),
+      coinDataA,
+      senderAddress,
+      // Mint to sender first, then transfer
+      recipientSalt,
+      null
+    );
+    const coinDataB = import_TokenCoinData2.TokenCoinData.create([[coinId, remainderAmount]]);
+    builder.createToken(
+      senderTokenId,
+      tokenToSplit.type,
+      new Uint8Array(0),
+      coinDataB,
+      senderAddress,
+      senderSalt,
+      null
+    );
+    const split = await builder.build(tokenToSplit);
+    console.log("[InstantSplit] Step 1: Creating and submitting burn...");
+    const burnSalt = await sha2563(seedString + "_burn_salt");
+    const burnCommitment = await split.createBurnCommitment(burnSalt, this.signingService);
+    const burnResponse = await this.client.submitTransferCommitment(burnCommitment);
+    if (burnResponse.status !== "SUCCESS" && burnResponse.status !== "REQUEST_ID_EXISTS") {
+      throw new Error(`Burn submission failed: ${burnResponse.status}`);
+    }
+    console.log("[InstantSplit] Step 2: Waiting for burn proof...");
+    const burnProof = this.devMode ? await this.waitInclusionProofWithDevBypass(burnCommitment, options?.burnProofTimeoutMs) : await (0, import_InclusionProofUtils3.waitInclusionProof)(this.trustBase, this.client, burnCommitment);
+    const burnTransaction = burnCommitment.toTransaction(burnProof);
+    console.log(`[InstantSplit] Burn proof received`);
+    options?.onBurnCompleted?.(JSON.stringify(burnTransaction.toJSON()));
+    console.log("[InstantSplit] Step 3: Creating mint commitments...");
+    const mintCommitments = await split.createSplitMintCommitments(this.trustBase, burnTransaction);
+    const recipientIdHex = toHex2(recipientTokenId.bytes);
+    const senderIdHex = toHex2(senderTokenId.bytes);
+    const recipientMintCommitment = mintCommitments.find(
+      (c) => toHex2(c.transactionData.tokenId.bytes) === recipientIdHex
+    );
+    const senderMintCommitment = mintCommitments.find(
+      (c) => toHex2(c.transactionData.tokenId.bytes) === senderIdHex
+    );
+    if (!recipientMintCommitment || !senderMintCommitment) {
+      throw new Error("Failed to find expected mint commitments");
+    }
+    console.log("[InstantSplit] Step 4: Creating transfer commitment...");
+    const transferSalt = await sha2563(seedString + "_transfer_salt");
+    const transferCommitment = await this.createTransferCommitmentFromMintData(
+      recipientMintCommitment.transactionData,
+      recipientAddress,
+      transferSalt,
+      this.signingService
+    );
+    const mintedPredicate = await import_UnmaskedPredicate3.UnmaskedPredicate.create(
+      recipientTokenId,
+      tokenToSplit.type,
+      this.signingService,
+      import_HashAlgorithm3.HashAlgorithm.SHA256,
+      recipientSalt
+    );
+    const mintedState = new import_TokenState3.TokenState(mintedPredicate, null);
+    console.log("[InstantSplit] Step 5: Packaging V5 bundle...");
+    const senderPubkey = toHex2(this.signingService.publicKey);
+    let nametagTokenJson;
+    const recipientAddressStr = recipientAddress.toString();
+    if (recipientAddressStr.startsWith("PROXY://") && tokenToSplit.nametagTokens?.length > 0) {
+      nametagTokenJson = JSON.stringify(tokenToSplit.nametagTokens[0].toJSON());
+    }
+    const bundle = {
+      version: "5.0",
+      type: "INSTANT_SPLIT",
+      burnTransaction: JSON.stringify(burnTransaction.toJSON()),
+      recipientMintData: JSON.stringify(recipientMintCommitment.transactionData.toJSON()),
+      transferCommitment: JSON.stringify(transferCommitment.toJSON()),
+      amount: splitAmount.toString(),
+      coinId: coinIdHex,
+      tokenTypeHex: toHex2(tokenToSplit.type.bytes),
+      splitGroupId,
+      senderPubkey,
+      recipientSaltHex: toHex2(recipientSalt),
+      transferSaltHex: toHex2(transferSalt),
+      mintedTokenStateJson: JSON.stringify(mintedState.toJSON()),
+      finalRecipientStateJson: "",
+      // Recipient creates their own
+      recipientAddressJson: recipientAddressStr,
+      nametagTokenJson
+    };
+    return {
+      bundle,
+      splitGroupId,
+      startBackground: async () => {
+        if (!options?.skipBackground) {
+          await this.submitBackgroundV5(senderMintCommitment, recipientMintCommitment, transferCommitment, {
+            signingService: this.signingService,
+            tokenType: tokenToSplit.type,
+            coinId,
+            senderTokenId,
+            senderSalt,
+            onProgress: options?.onBackgroundProgress,
+            onChangeTokenCreated: options?.onChangeTokenCreated,
+            onStorageSync: options?.onStorageSync
+          });
+        }
+      }
+    };
+  }
+  /**
+   * Execute an instant split transfer with V5 optimized flow.
+   *
+   * Builds the bundle via buildSplitBundle(), sends via transport,
+   * and starts background processing.
    *
    * @param tokenToSplit - The SDK token to split
    * @param splitAmount - Amount to send to recipient
@@ -3402,117 +3550,19 @@ var InstantSplitExecutor = class {
    */
   async executeSplitInstant(tokenToSplit, splitAmount, remainderAmount, coinIdHex, recipientAddress, transport, recipientPubkey, options) {
     const startTime = performance.now();
-    const splitGroupId = crypto.randomUUID();
-    const tokenIdHex = toHex2(tokenToSplit.id.bytes);
-    console.log(`[InstantSplit] Starting V5 split for token ${tokenIdHex.slice(0, 8)}...`);
     try {
-      const coinId = new import_CoinId3.CoinId(fromHex2(coinIdHex));
-      const seedString = `${tokenIdHex}_${splitAmount.toString()}_${remainderAmount.toString()}_${Date.now()}`;
-      const recipientTokenId = new import_TokenId3.TokenId(await sha2563(seedString));
-      const senderTokenId = new import_TokenId3.TokenId(await sha2563(seedString + "_sender"));
-      const recipientSalt = await sha2563(seedString + "_recipient_salt");
-      const senderSalt = await sha2563(seedString + "_sender_salt");
-      const senderAddressRef = await import_UnmaskedPredicateReference2.UnmaskedPredicateReference.create(
-        tokenToSplit.type,
-        this.signingService.algorithm,
-        this.signingService.publicKey,
-        import_HashAlgorithm3.HashAlgorithm.SHA256
-      );
-      const senderAddress = await senderAddressRef.toAddress();
-      const builder = new import_TokenSplitBuilder2.TokenSplitBuilder();
-      const coinDataA = import_TokenCoinData2.TokenCoinData.create([[coinId, splitAmount]]);
-      builder.createToken(
-        recipientTokenId,
-        tokenToSplit.type,
-        new Uint8Array(0),
-        coinDataA,
-        senderAddress,
-        // Mint to sender first, then transfer
-        recipientSalt,
-        null
-      );
-      const coinDataB = import_TokenCoinData2.TokenCoinData.create([[coinId, remainderAmount]]);
-      builder.createToken(
-        senderTokenId,
-        tokenToSplit.type,
-        new Uint8Array(0),
-        coinDataB,
-        senderAddress,
-        senderSalt,
-        null
-      );
-      const split = await builder.build(tokenToSplit);
-      console.log("[InstantSplit] Step 1: Creating and submitting burn...");
-      const burnSalt = await sha2563(seedString + "_burn_salt");
-      const burnCommitment = await split.createBurnCommitment(burnSalt, this.signingService);
-      const burnResponse = await this.client.submitTransferCommitment(burnCommitment);
-      if (burnResponse.status !== "SUCCESS" && burnResponse.status !== "REQUEST_ID_EXISTS") {
-        throw new Error(`Burn submission failed: ${burnResponse.status}`);
-      }
-      console.log("[InstantSplit] Step 2: Waiting for burn proof...");
-      const burnProof = this.devMode ? await this.waitInclusionProofWithDevBypass(burnCommitment, options?.burnProofTimeoutMs) : await (0, import_InclusionProofUtils3.waitInclusionProof)(this.trustBase, this.client, burnCommitment);
-      const burnTransaction = burnCommitment.toTransaction(burnProof);
-      const burnDuration = performance.now() - startTime;
-      console.log(`[InstantSplit] Burn proof received in ${burnDuration.toFixed(0)}ms`);
-      options?.onBurnCompleted?.(JSON.stringify(burnTransaction.toJSON()));
-      console.log("[InstantSplit] Step 3: Creating mint commitments...");
-      const mintCommitments = await split.createSplitMintCommitments(this.trustBase, burnTransaction);
-      const recipientIdHex = toHex2(recipientTokenId.bytes);
-      const senderIdHex = toHex2(senderTokenId.bytes);
-      const recipientMintCommitment = mintCommitments.find(
-        (c) => toHex2(c.transactionData.tokenId.bytes) === recipientIdHex
-      );
-      const senderMintCommitment = mintCommitments.find(
-        (c) => toHex2(c.transactionData.tokenId.bytes) === senderIdHex
-      );
-      if (!recipientMintCommitment || !senderMintCommitment) {
-        throw new Error("Failed to find expected mint commitments");
-      }
-      console.log("[InstantSplit] Step 4: Creating transfer commitment...");
-      const transferSalt = await sha2563(seedString + "_transfer_salt");
-      const transferCommitment = await this.createTransferCommitmentFromMintData(
-        recipientMintCommitment.transactionData,
+      const buildResult = await this.buildSplitBundle(
+        tokenToSplit,
+        splitAmount,
+        remainderAmount,
+        coinIdHex,
         recipientAddress,
-        transferSalt,
-        this.signingService
-      );
-      const mintedPredicate = await import_UnmaskedPredicate3.UnmaskedPredicate.create(
-        recipientTokenId,
-        tokenToSplit.type,
-        this.signingService,
-        import_HashAlgorithm3.HashAlgorithm.SHA256,
-        recipientSalt
+        options
       );
-      const mintedState = new import_TokenState3.TokenState(mintedPredicate, null);
-      console.log("[InstantSplit] Step 5: Packaging V5 bundle...");
+      console.log("[InstantSplit] Sending via transport...");
       const senderPubkey = toHex2(this.signingService.publicKey);
-      let nametagTokenJson;
-      const recipientAddressStr = recipientAddress.toString();
-      if (recipientAddressStr.startsWith("PROXY://") && tokenToSplit.nametagTokens?.length > 0) {
-        nametagTokenJson = JSON.stringify(tokenToSplit.nametagTokens[0].toJSON());
-      }
-      const bundle = {
-        version: "5.0",
-        type: "INSTANT_SPLIT",
-        burnTransaction: JSON.stringify(burnTransaction.toJSON()),
-        recipientMintData: JSON.stringify(recipientMintCommitment.transactionData.toJSON()),
-        transferCommitment: JSON.stringify(transferCommitment.toJSON()),
-        amount: splitAmount.toString(),
-        coinId: coinIdHex,
-        tokenTypeHex: toHex2(tokenToSplit.type.bytes),
-        splitGroupId,
-        senderPubkey,
-        recipientSaltHex: toHex2(recipientSalt),
-        transferSaltHex: toHex2(transferSalt),
-        mintedTokenStateJson: JSON.stringify(mintedState.toJSON()),
-        finalRecipientStateJson: "",
-        // Recipient creates their own
-        recipientAddressJson: recipientAddressStr,
-        nametagTokenJson
-      };
-      console.log("[InstantSplit] Step 6: Sending via transport...");
       const nostrEventId = await transport.sendTokenTransfer(recipientPubkey, {
-        token: JSON.stringify(bundle),
+        token: JSON.stringify(buildResult.bundle),
         proof: null,
         // Proof is included in the bundle
         memo: options?.memo,
@@ -3523,25 +3573,13 @@ var InstantSplitExecutor = class {
       const criticalPathDuration = performance.now() - startTime;
       console.log(`[InstantSplit] V5 complete in ${criticalPathDuration.toFixed(0)}ms`);
       options?.onNostrDelivered?.(nostrEventId);
-      let backgroundPromise;
-      if (!options?.skipBackground) {
-        backgroundPromise = this.submitBackgroundV5(senderMintCommitment, recipientMintCommitment, transferCommitment, {
-          signingService: this.signingService,
-          tokenType: tokenToSplit.type,
-          coinId,
-          senderTokenId,
-          senderSalt,
-          onProgress: options?.onBackgroundProgress,
-          onChangeTokenCreated: options?.onChangeTokenCreated,
-          onStorageSync: options?.onStorageSync
-        });
-      }
+      const backgroundPromise = buildResult.startBackground();
       return {
         success: true,
         nostrEventId,
-        splitGroupId,
+        splitGroupId: buildResult.splitGroupId,
         criticalPathDurationMs: criticalPathDuration,
-        backgroundStarted: !options?.skipBackground,
+        backgroundStarted: true,
         backgroundPromise
       };
     } catch (error) {
@@ -3550,7 +3588,6 @@ var InstantSplitExecutor = class {
       console.error(`[InstantSplit] Failed after ${duration.toFixed(0)}ms:`, error);
       return {
         success: false,
-        splitGroupId,
         criticalPathDurationMs: duration,
         error: errorMessage,
         backgroundStarted: false
@@ -3755,6 +3792,11 @@ function isInstantSplitBundleV4(obj) {
 function isInstantSplitBundleV5(obj) {
   return isInstantSplitBundle(obj) && obj.version === "5.0";
 }
+function isCombinedTransferBundleV6(obj) {
+  if (typeof obj !== "object" || obj === null) return false;
+  const b = obj;
+  return b.version === "6.0" && b.type === "COMBINED_TRANSFER";
+}
 
 // modules/payments/InstantSplitProcessor.ts
 function fromHex3(hex) {
@@ -4079,6 +4121,7 @@ function computeHistoryDedupKey(type, tokenId, transferId) {
   if (tokenId) return `${type}_${tokenId}`;
   return `${type}_${crypto.randomUUID()}`;
 }
+var MAX_SYNCED_HISTORY_ENTRIES = 5e3;
 function enrichWithRegistry(info) {
   const registry = TokenRegistry.getInstance();
   const def = registry.getDefinition(info.coinId);
@@ -4408,6 +4451,8 @@ var PaymentsModule = class _PaymentsModule {
   // 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();
+  // Persistent dedup: tracks V6 combined transfer IDs that have been processed.
+  processedCombinedTransferIds = /* @__PURE__ */ new Set();
   // Storage event subscriptions (push-based sync)
   storageEventUnsubscribers = [];
   syncDebounceTimer = null;
@@ -4501,6 +4546,10 @@ var PaymentsModule = class _PaymentsModule {
           const result = await provider.load();
           if (result.success && result.data) {
             this.loadFromStorageData(result.data);
+            const txfData = result.data;
+            if (txfData._history && txfData._history.length > 0) {
+              await this.importRemoteHistoryEntries(txfData._history);
+            }
             this.log(`Loaded metadata from provider ${id}`);
             break;
           }
@@ -4508,10 +4557,23 @@ var PaymentsModule = class _PaymentsModule {
           console.error(`[Payments] Failed to load from provider ${id}:`, err);
         }
       }
+      for (const [id, token] of this.tokens) {
+        try {
+          if (token.sdkData) {
+            const data = JSON.parse(token.sdkData);
+            if (data?._placeholder) {
+              this.tokens.delete(id);
+              console.log(`[Payments] Removed stale placeholder token: ${id}`);
+            }
+          }
+        } catch {
+        }
+      }
       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.loadProcessedCombinedTransferIds();
       await this.loadHistory();
       const pending2 = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
       if (pending2) {
@@ -4603,12 +4665,13 @@ var PaymentsModule = class _PaymentsModule {
         token.status = "transferring";
         this.tokens.set(token.id, token);
       }
+      await this.save();
       await this.saveToOutbox(result, recipientPubkey);
       result.status = "submitted";
       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") {
+      if (transferMode === "conservative") {
+        if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
           this.log("Executing conservative split...");
           const splitExecutor = new TokenSplitExecutor({
             stateTransitionClient: stClient,
@@ -4652,27 +4715,59 @@ var PaymentsModule = class _PaymentsModule {
             requestIdHex: splitRequestIdHex
           });
           this.log(`Conservative split transfer completed`);
-        } else {
-          this.log("Executing instant split...");
-          const devMode = this.deps.oracle.isDevMode?.() ?? false;
+        }
+        for (const tokenWithAmount of splitPlan.tokensToTransferDirectly) {
+          const token = tokenWithAmount.uiToken;
+          const commitment = await this.createSdkCommitment(token, recipientAddress, signingService);
+          console.log(`[Payments] CONSERVATIVE: Sending direct token ${token.id.slice(0, 8)}... to ${recipientPubkey.slice(0, 8)}...`);
+          const submitResponse = await stClient.submitTransferCommitment(commitment);
+          if (submitResponse.status !== "SUCCESS" && submitResponse.status !== "REQUEST_ID_EXISTS") {
+            throw new Error(`Transfer commitment failed: ${submitResponse.status}`);
+          }
+          const inclusionProof = await (0, import_InclusionProofUtils5.waitInclusionProof)(trustBase, stClient, commitment);
+          const transferTx = commitment.toTransaction(inclusionProof);
+          await this.deps.transport.sendTokenTransfer(recipientPubkey, {
+            sourceToken: JSON.stringify(tokenWithAmount.sdkToken.toJSON()),
+            transferTx: JSON.stringify(transferTx.toJSON()),
+            memo: request.memo
+          });
+          console.log(`[Payments] CONSERVATIVE: Direct token sent successfully`);
+          const requestIdBytes = commitment.requestId;
+          const requestIdHex = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
+          result.tokenTransfers.push({
+            sourceTokenId: token.id,
+            method: "direct",
+            requestIdHex
+          });
+          this.log(`Token ${token.id} sent via CONSERVATIVE, requestId: ${requestIdHex}`);
+          await this.removeToken(token.id);
+        }
+      } else {
+        const devMode = this.deps.oracle.isDevMode?.() ?? false;
+        const senderPubkey = this.deps.identity.chainPubkey;
+        let changeTokenPlaceholderId = null;
+        let builtSplit = null;
+        if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
+          this.log("Building instant split bundle...");
           const executor = new InstantSplitExecutor({
             stateTransitionClient: stClient,
             trustBase,
             signingService,
             devMode
           });
-          const instantResult = await executor.executeSplitInstant(
+          builtSplit = await executor.buildSplitBundle(
             splitPlan.tokenToSplit.sdkToken,
             splitPlan.splitAmount,
             splitPlan.remainderAmount,
             splitPlan.coinId,
             recipientAddress,
-            this.deps.transport,
-            recipientPubkey,
             {
               memo: request.memo,
               onChangeTokenCreated: async (changeToken) => {
                 const changeTokenData = changeToken.toJSON();
+                if (changeTokenPlaceholderId && this.tokens.has(changeTokenPlaceholderId)) {
+                  this.tokens.delete(changeTokenPlaceholderId);
+                }
                 const uiToken = {
                   id: crypto.randomUUID(),
                   coinId: request.coinId,
@@ -4695,65 +4790,103 @@ var PaymentsModule = class _PaymentsModule {
               }
             }
           );
-          if (!instantResult.success) {
-            throw new Error(instantResult.error || "Instant split failed");
-          }
-          if (instantResult.backgroundPromise) {
-            this.pendingBackgroundTasks.push(instantResult.backgroundPromise);
-          }
+          this.log(`Split bundle built: splitGroupId=${builtSplit.splitGroupId}`);
+        }
+        const directCommitments = await Promise.all(
+          splitPlan.tokensToTransferDirectly.map(
+            (tw) => this.createSdkCommitment(tw.uiToken, recipientAddress, signingService)
+          )
+        );
+        const directTokenEntries = splitPlan.tokensToTransferDirectly.map(
+          (tw, i) => ({
+            sourceToken: JSON.stringify(tw.sdkToken.toJSON()),
+            commitmentData: JSON.stringify(directCommitments[i].toJSON()),
+            amount: tw.uiToken.amount,
+            coinId: tw.uiToken.coinId,
+            tokenId: extractTokenIdFromSdkData(tw.uiToken.sdkData) || void 0
+          })
+        );
+        const combinedBundle = {
+          version: "6.0",
+          type: "COMBINED_TRANSFER",
+          transferId: result.id,
+          splitBundle: builtSplit?.bundle ?? null,
+          directTokens: directTokenEntries,
+          totalAmount: request.amount.toString(),
+          coinId: request.coinId,
+          senderPubkey,
+          memo: request.memo
+        };
+        console.log(
+          `[Payments] Sending V6 combined bundle: transfer=${result.id.slice(0, 8)}... split=${!!builtSplit} direct=${directTokenEntries.length}`
+        );
+        await this.deps.transport.sendTokenTransfer(recipientPubkey, {
+          token: JSON.stringify(combinedBundle),
+          proof: null,
+          memo: request.memo,
+          sender: { transportPubkey: senderPubkey }
+        });
+        console.log(`[Payments] V6 combined bundle sent successfully`);
+        if (builtSplit) {
+          const bgPromise = builtSplit.startBackground();
+          this.pendingBackgroundTasks.push(bgPromise);
+        }
+        if (builtSplit && splitPlan.remainderAmount) {
+          changeTokenPlaceholderId = crypto.randomUUID();
+          const placeholder = {
+            id: changeTokenPlaceholderId,
+            coinId: request.coinId,
+            symbol: this.getCoinSymbol(request.coinId),
+            name: this.getCoinName(request.coinId),
+            decimals: this.getCoinDecimals(request.coinId),
+            iconUrl: this.getCoinIconUrl(request.coinId),
+            amount: splitPlan.remainderAmount.toString(),
+            status: "transferring",
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            sdkData: JSON.stringify({ _placeholder: true })
+          };
+          this.tokens.set(placeholder.id, placeholder);
+          this.log(`Placeholder change token created: ${placeholder.id} (${placeholder.amount})`);
+        }
+        for (const commitment of directCommitments) {
+          stClient.submitTransferCommitment(commitment).catch(
+            (err) => console.error("[Payments] Background commitment submit failed:", err)
+          );
+        }
+        if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
           await this.removeToken(splitPlan.tokenToSplit.uiToken.id);
           result.tokenTransfers.push({
             sourceTokenId: splitPlan.tokenToSplit.uiToken.id,
             method: "split",
-            splitGroupId: instantResult.splitGroupId,
-            nostrEventId: instantResult.nostrEventId
+            splitGroupId: builtSplit.splitGroupId
           });
-          this.log(`Instant split transfer completed`);
         }
-      }
-      for (const tokenWithAmount of splitPlan.tokensToTransferDirectly) {
-        const token = tokenWithAmount.uiToken;
-        const commitment = await this.createSdkCommitment(token, recipientAddress, signingService);
-        if (transferMode === "conservative") {
-          console.log(`[Payments] CONSERVATIVE: Sending direct token ${token.id.slice(0, 8)}... to ${recipientPubkey.slice(0, 8)}...`);
-          const submitResponse = await stClient.submitTransferCommitment(commitment);
-          if (submitResponse.status !== "SUCCESS" && submitResponse.status !== "REQUEST_ID_EXISTS") {
-            throw new Error(`Transfer commitment failed: ${submitResponse.status}`);
-          }
-          const inclusionProof = await (0, import_InclusionProofUtils5.waitInclusionProof)(trustBase, stClient, commitment);
-          const transferTx = commitment.toTransaction(inclusionProof);
-          await this.deps.transport.sendTokenTransfer(recipientPubkey, {
-            sourceToken: JSON.stringify(tokenWithAmount.sdkToken.toJSON()),
-            transferTx: JSON.stringify(transferTx.toJSON()),
-            memo: request.memo
-          });
-          console.log(`[Payments] CONSERVATIVE: Direct token sent successfully`);
-        } else {
-          console.log(`[Payments] NOSTR-FIRST: Sending direct token ${token.id.slice(0, 8)}... to ${recipientPubkey.slice(0, 8)}...`);
-          await this.deps.transport.sendTokenTransfer(recipientPubkey, {
-            sourceToken: JSON.stringify(tokenWithAmount.sdkToken.toJSON()),
-            commitmentData: JSON.stringify(commitment.toJSON()),
-            memo: request.memo
+        for (let i = 0; i < splitPlan.tokensToTransferDirectly.length; i++) {
+          const token = splitPlan.tokensToTransferDirectly[i].uiToken;
+          const commitment = directCommitments[i];
+          const requestIdBytes = commitment.requestId;
+          const requestIdHex = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
+          result.tokenTransfers.push({
+            sourceTokenId: token.id,
+            method: "direct",
+            requestIdHex
           });
-          console.log(`[Payments] NOSTR-FIRST: Direct token sent successfully`);
-          stClient.submitTransferCommitment(commitment).catch(
-            (err) => console.error("[Payments] Background commitment submit failed:", err)
-          );
+          await this.removeToken(token.id);
         }
-        const requestIdBytes = commitment.requestId;
-        const requestIdHex = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
-        result.tokenTransfers.push({
-          sourceTokenId: token.id,
-          method: "direct",
-          requestIdHex
-        });
-        this.log(`Token ${token.id} sent via ${transferMode.toUpperCase()}, requestId: ${requestIdHex}`);
-        await this.removeToken(token.id);
+        this.log(`V6 combined transfer completed`);
       }
       result.status = "delivered";
       await this.save();
       await this.removeFromOutbox(result.id);
       result.status = "completed";
+      const tokenMap = new Map(result.tokens.map((t) => [t.id, t]));
+      const sentTokenIds = result.tokenTransfers.map((tt) => ({
+        id: tt.sourceTokenId,
+        // For split tokens, use splitAmount (the portion sent), not the original token amount
+        amount: tt.method === "split" ? splitPlan.splitAmount?.toString() || "0" : tokenMap.get(tt.sourceTokenId)?.amount || "0",
+        source: tt.method === "split" ? "split" : "direct"
+      }));
       const sentTokenId = result.tokens[0] ? extractTokenIdFromSdkData(result.tokens[0].sdkData) : void 0;
       await this.addToHistory({
         type: "SENT",
@@ -4766,7 +4899,8 @@ var PaymentsModule = class _PaymentsModule {
         recipientAddress: peerInfo?.directAddress || recipientAddress?.toString() || recipientPubkey,
         memo: request.memo,
         transferId: result.id,
-        tokenId: sentTokenId || void 0
+        tokenId: sentTokenId || void 0,
+        tokenIds: sentTokenIds.length > 0 ? sentTokenIds : void 0
       });
       this.deps.emitEvent("transfer:confirmed", result);
       return result;
@@ -4936,6 +5070,267 @@ var PaymentsModule = class _PaymentsModule {
       };
     }
   }
+  // ===========================================================================
+  // Shared Helpers for V5 and V6 Receiver Processing
+  // ===========================================================================
+  /**
+   * Save a V5 split bundle as an unconfirmed token (shared by V5 standalone and V6 combined).
+   * Returns the created UI token, or null if deduped.
+   *
+   * @param deferPersistence - If true, skip addToken/save calls (caller batches them).
+   *   The token is still added to the in-memory map for dedup; caller must call save().
+   */
+  async saveUnconfirmedV5Token(bundle, senderPubkey, deferPersistence = false) {
+    const deterministicId = `v5split_${bundle.splitGroupId}`;
+    if (this.tokens.has(deterministicId) || this.processedSplitGroupIds.has(bundle.splitGroupId)) {
+      console.log(`[Payments] V5 bundle ${bundle.splitGroupId.slice(0, 12)}... already processed, skipping`);
+      return null;
+    }
+    const registry = TokenRegistry.getInstance();
+    const pendingData = {
+      type: "v5_bundle",
+      stage: "RECEIVED",
+      bundleJson: JSON.stringify(bundle),
+      senderPubkey,
+      savedAt: Date.now(),
+      attemptCount: 0
+    };
+    const uiToken = {
+      id: deterministicId,
+      coinId: bundle.coinId,
+      symbol: registry.getSymbol(bundle.coinId) || bundle.coinId,
+      name: registry.getName(bundle.coinId) || bundle.coinId,
+      decimals: registry.getDecimals(bundle.coinId) ?? 8,
+      amount: bundle.amount,
+      status: "submitted",
+      // UNCONFIRMED
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      sdkData: JSON.stringify({ _pendingFinalization: pendingData })
+    };
+    this.processedSplitGroupIds.add(bundle.splitGroupId);
+    if (deferPersistence) {
+      this.tokens.set(uiToken.id, uiToken);
+    } else {
+      await this.addToken(uiToken);
+      await this.saveProcessedSplitGroupIds();
+    }
+    return uiToken;
+  }
+  /**
+   * Save a commitment-only (NOSTR-FIRST) token and start proof polling.
+   * Shared by standalone NOSTR-FIRST handler and V6 combined handler.
+   * Returns the created UI token, or null if deduped/tombstoned.
+   *
+   * @param deferPersistence - If true, skip save() and commitment submission
+   *   (caller batches them). Token is added to in-memory map + proof polling is queued.
+   * @param skipGenesisDedup - If true, skip genesis-ID-only dedup. V6 handler sets this
+   *   because bundle-level dedup protects against replays, and split children share genesis IDs.
+   */
+  async saveCommitmentOnlyToken(sourceTokenInput, commitmentInput, senderPubkey, deferPersistence = false, skipGenesisDedup = false) {
+    const tokenInfo = await parseTokenInfo(sourceTokenInput);
+    const sdkData = typeof sourceTokenInput === "string" ? sourceTokenInput : JSON.stringify(sourceTokenInput);
+    const nostrTokenId = extractTokenIdFromSdkData(sdkData);
+    const nostrStateHash = extractStateHashFromSdkData(sdkData);
+    if (nostrTokenId && nostrStateHash && this.isStateTombstoned(nostrTokenId, nostrStateHash)) {
+      this.log(`NOSTR-FIRST: Rejecting tombstoned token ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`);
+      return null;
+    }
+    if (nostrTokenId) {
+      for (const existing of this.tokens.values()) {
+        const existingTokenId = extractTokenIdFromSdkData(existing.sdkData);
+        if (existingTokenId !== nostrTokenId) continue;
+        const existingStateHash = extractStateHashFromSdkData(existing.sdkData);
+        if (nostrStateHash && existingStateHash === nostrStateHash) {
+          console.log(
+            `[Payments] NOSTR-FIRST: Skipping duplicate token state ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`
+          );
+          return null;
+        }
+        if (!skipGenesisDedup) {
+          console.log(
+            `[Payments] NOSTR-FIRST: Skipping replay of finalized token ${nostrTokenId.slice(0, 8)}...`
+          );
+          return null;
+        }
+      }
+    }
+    const token = {
+      id: crypto.randomUUID(),
+      coinId: tokenInfo.coinId,
+      symbol: tokenInfo.symbol,
+      name: tokenInfo.name,
+      decimals: tokenInfo.decimals,
+      iconUrl: tokenInfo.iconUrl,
+      amount: tokenInfo.amount,
+      status: "submitted",
+      // NOSTR-FIRST: unconfirmed until proof
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      sdkData
+    };
+    this.tokens.set(token.id, token);
+    if (!deferPersistence) {
+      await this.save();
+    }
+    try {
+      const commitment = await import_TransferCommitment4.TransferCommitment.fromJSON(commitmentInput);
+      const requestIdBytes = commitment.requestId;
+      const requestIdHex = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
+      if (!deferPersistence) {
+        const stClient = this.deps.oracle.getStateTransitionClient?.();
+        if (stClient) {
+          const response = await stClient.submitTransferCommitment(commitment);
+          this.log(`NOSTR-FIRST recipient commitment submit: ${response.status}`);
+        }
+      }
+      this.addProofPollingJob({
+        tokenId: token.id,
+        requestIdHex,
+        commitmentJson: JSON.stringify(commitmentInput),
+        startedAt: Date.now(),
+        attemptCount: 0,
+        lastAttemptAt: 0,
+        onProofReceived: async (tokenId) => {
+          await this.finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput);
+        }
+      });
+    } catch (err) {
+      console.error("[Payments] Failed to parse commitment for proof polling:", err);
+    }
+    return token;
+  }
+  // ===========================================================================
+  // Combined Transfer V6 — Receiver
+  // ===========================================================================
+  /**
+   * Process a received COMBINED_TRANSFER V6 bundle.
+   *
+   * Unpacks a single Nostr message into its component tokens:
+   * - Optional V5 split bundle (saved as unconfirmed, resolved lazily)
+   * - Zero or more direct tokens (saved as unconfirmed, proof-polled)
+   *
+   * Emits ONE transfer:incoming event and records ONE history entry.
+   */
+  async processCombinedTransferBundle(bundle, senderPubkey) {
+    this.ensureInitialized();
+    if (!this.loaded && this.loadedPromise) {
+      await this.loadedPromise;
+    }
+    if (this.processedCombinedTransferIds.has(bundle.transferId)) {
+      console.log(`[Payments] V6 combined transfer ${bundle.transferId.slice(0, 12)}... already processed, skipping`);
+      return;
+    }
+    console.log(
+      `[Payments] Processing V6 combined transfer ${bundle.transferId.slice(0, 12)}... (split=${!!bundle.splitBundle}, direct=${bundle.directTokens.length})`
+    );
+    const allTokens = [];
+    const tokenBreakdown = [];
+    const parsedDirectEntries = bundle.directTokens.map((entry) => ({
+      sourceToken: typeof entry.sourceToken === "string" ? JSON.parse(entry.sourceToken) : entry.sourceToken,
+      commitment: typeof entry.commitmentData === "string" ? JSON.parse(entry.commitmentData) : entry.commitmentData
+    }));
+    if (bundle.splitBundle) {
+      const splitToken = await this.saveUnconfirmedV5Token(bundle.splitBundle, senderPubkey, true);
+      if (splitToken) {
+        allTokens.push(splitToken);
+        tokenBreakdown.push({ id: splitToken.id, amount: splitToken.amount, source: "split" });
+      } else {
+        console.warn(`[Payments] V6: split token was deduped/failed \u2014 amount=${bundle.splitBundle.amount}`);
+      }
+    }
+    const directResults = await Promise.all(
+      parsedDirectEntries.map(
+        ({ sourceToken, commitment }) => this.saveCommitmentOnlyToken(sourceToken, commitment, senderPubkey, true, true)
+      )
+    );
+    for (let i = 0; i < directResults.length; i++) {
+      const token = directResults[i];
+      if (token) {
+        allTokens.push(token);
+        tokenBreakdown.push({ id: token.id, amount: token.amount, source: "direct" });
+      } else {
+        const entry = bundle.directTokens[i];
+        console.warn(
+          `[Payments] V6: direct token #${i} dropped (amount=${entry.amount}, tokenId=${entry.tokenId?.slice(0, 12) ?? "N/A"})`
+        );
+      }
+    }
+    if (allTokens.length === 0) {
+      console.log(`[Payments] V6 combined transfer: all tokens deduped, nothing to save`);
+      return;
+    }
+    this.processedCombinedTransferIds.add(bundle.transferId);
+    const [senderInfo] = await Promise.all([
+      this.resolveSenderInfo(senderPubkey),
+      this.save(),
+      this.saveProcessedCombinedTransferIds(),
+      ...bundle.splitBundle ? [this.saveProcessedSplitGroupIds()] : []
+    ]);
+    const stClient = this.deps.oracle.getStateTransitionClient?.();
+    if (stClient) {
+      for (const { commitment } of parsedDirectEntries) {
+        import_TransferCommitment4.TransferCommitment.fromJSON(commitment).then(
+          (c) => stClient.submitTransferCommitment(c)
+        ).catch(
+          (err) => console.error("[Payments] V6 background commitment submit failed:", err)
+        );
+      }
+    }
+    this.deps.emitEvent("transfer:incoming", {
+      id: bundle.transferId,
+      senderPubkey,
+      senderNametag: senderInfo.senderNametag,
+      tokens: allTokens,
+      memo: bundle.memo,
+      receivedAt: Date.now()
+    });
+    const actualAmount = allTokens.reduce((sum, t) => sum + BigInt(t.amount || "0"), 0n).toString();
+    await this.addToHistory({
+      type: "RECEIVED",
+      amount: actualAmount,
+      coinId: bundle.coinId,
+      symbol: allTokens[0]?.symbol || bundle.coinId,
+      timestamp: Date.now(),
+      senderPubkey,
+      ...senderInfo,
+      memo: bundle.memo,
+      transferId: bundle.transferId,
+      tokenId: allTokens[0]?.id,
+      tokenIds: tokenBreakdown
+    });
+    if (bundle.splitBundle) {
+      this.resolveUnconfirmed().catch(() => {
+      });
+      this.scheduleResolveUnconfirmed();
+    }
+  }
+  /**
+   * Persist processed combined transfer IDs to KV storage.
+   */
+  async saveProcessedCombinedTransferIds() {
+    const ids = Array.from(this.processedCombinedTransferIds);
+    if (ids.length > 0) {
+      await this.deps.storage.set(
+        STORAGE_KEYS_ADDRESS.PROCESSED_COMBINED_TRANSFER_IDS,
+        JSON.stringify(ids)
+      );
+    }
+  }
+  /**
+   * Load processed combined transfer IDs from KV storage.
+   */
+  async loadProcessedCombinedTransferIds() {
+    const data = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PROCESSED_COMBINED_TRANSFER_IDS);
+    if (!data) return;
+    try {
+      const ids = JSON.parse(data);
+      for (const id of ids) {
+        this.processedCombinedTransferIds.add(id);
+      }
+    } catch {
+    }
+  }
   /**
    * Process a received INSTANT_SPLIT bundle.
    *
@@ -4959,36 +5354,10 @@ var PaymentsModule = class _PaymentsModule {
       return this.processInstantSplitBundleSync(bundle, senderPubkey, memo);
     }
     try {
-      const deterministicId = `v5split_${bundle.splitGroupId}`;
-      if (this.tokens.has(deterministicId) || this.processedSplitGroupIds.has(bundle.splitGroupId)) {
-        console.log(`[Payments] V5 bundle ${bundle.splitGroupId.slice(0, 12)}... already processed, skipping`);
+      const uiToken = await this.saveUnconfirmedV5Token(bundle, senderPubkey);
+      if (!uiToken) {
         return { success: true, durationMs: 0 };
       }
-      const registry = TokenRegistry.getInstance();
-      const pendingData = {
-        type: "v5_bundle",
-        stage: "RECEIVED",
-        bundleJson: JSON.stringify(bundle),
-        senderPubkey,
-        savedAt: Date.now(),
-        attemptCount: 0
-      };
-      const uiToken = {
-        id: deterministicId,
-        coinId: bundle.coinId,
-        symbol: registry.getSymbol(bundle.coinId) || bundle.coinId,
-        name: registry.getName(bundle.coinId) || bundle.coinId,
-        decimals: registry.getDecimals(bundle.coinId) ?? 8,
-        amount: bundle.amount,
-        status: "submitted",
-        // UNCONFIRMED
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-        sdkData: JSON.stringify({ _pendingFinalization: pendingData })
-      };
-      await this.addToken(uiToken);
-      this.processedSplitGroupIds.add(bundle.splitGroupId);
-      await this.saveProcessedSplitGroupIds();
       const senderInfo = await this.resolveSenderInfo(senderPubkey);
       await this.addToHistory({
         type: "RECEIVED",
@@ -4999,7 +5368,7 @@ var PaymentsModule = class _PaymentsModule {
         senderPubkey,
         ...senderInfo,
         memo,
-        tokenId: deterministicId
+        tokenId: uiToken.id
       });
       this.deps.emitEvent("transfer:incoming", {
         id: bundle.splitGroupId,
@@ -5649,16 +6018,18 @@ var PaymentsModule = class _PaymentsModule {
   }
   /**
    * Aggregate tokens by coinId with confirmed/unconfirmed breakdown.
-   * Excludes tokens with status 'spent', 'invalid', or 'transferring'.
+   * Excludes tokens with status 'spent' or 'invalid'.
+   * Tokens with status 'transferring' are counted as unconfirmed (visible in UI as "Sending").
    */
   aggregateTokens(coinId) {
     const assetsMap = /* @__PURE__ */ new Map();
     for (const token of this.tokens.values()) {
-      if (token.status === "spent" || token.status === "invalid" || token.status === "transferring") continue;
+      if (token.status === "spent" || token.status === "invalid") continue;
       if (coinId && token.coinId !== coinId) continue;
       const key = token.coinId;
       const amount = BigInt(token.amount);
       const isConfirmed = token.status === "confirmed";
+      const isTransferring = token.status === "transferring";
       const existing = assetsMap.get(key);
       if (existing) {
         if (isConfirmed) {
@@ -5668,6 +6039,7 @@ var PaymentsModule = class _PaymentsModule {
           existing.unconfirmedAmount += amount;
           existing.unconfirmedTokenCount++;
         }
+        if (isTransferring) existing.transferringTokenCount++;
       } else {
         assetsMap.set(key, {
           coinId: token.coinId,
@@ -5678,7 +6050,8 @@ var PaymentsModule = class _PaymentsModule {
           confirmedAmount: isConfirmed ? amount : 0n,
           unconfirmedAmount: isConfirmed ? 0n : amount,
           confirmedTokenCount: isConfirmed ? 1 : 0,
-          unconfirmedTokenCount: isConfirmed ? 0 : 1
+          unconfirmedTokenCount: isConfirmed ? 0 : 1,
+          transferringTokenCount: isTransferring ? 1 : 0
         });
       }
     }
@@ -5696,6 +6069,7 @@ var PaymentsModule = class _PaymentsModule {
         unconfirmedAmount: raw.unconfirmedAmount.toString(),
         confirmedTokenCount: raw.confirmedTokenCount,
         unconfirmedTokenCount: raw.unconfirmedTokenCount,
+        transferringTokenCount: raw.transferringTokenCount,
         priceUsd: null,
         priceEur: null,
         change24h: null,
@@ -6548,6 +6922,33 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
   }
+  /**
+   * Import history entries from remote TXF data into local store.
+   * Delegates to the local TokenStorageProvider's importHistoryEntries() for
+   * persistent storage, with in-memory fallback.
+   * Reused by both load() (initial IPFS fetch) and _doSync() (merge result).
+   */
+  async importRemoteHistoryEntries(entries) {
+    if (entries.length === 0) return 0;
+    const provider = this.getLocalTokenStorageProvider();
+    if (provider?.importHistoryEntries) {
+      const imported2 = await provider.importHistoryEntries(entries);
+      if (imported2 > 0) {
+        this._historyCache = await provider.getHistoryEntries();
+      }
+      return imported2;
+    }
+    const existingKeys = new Set(this._historyCache.map((e) => e.dedupKey));
+    let imported = 0;
+    for (const entry of entries) {
+      if (!existingKeys.has(entry.dedupKey)) {
+        this._historyCache.push(entry);
+        existingKeys.add(entry.dedupKey);
+        imported++;
+      }
+    }
+    return imported;
+  }
   /**
    * Get the first local token storage provider (for history operations).
    */
@@ -6795,6 +7196,13 @@ var PaymentsModule = class _PaymentsModule {
             if (this.nametags.length === 0 && savedNametags.length > 0) {
               this.nametags = savedNametags;
             }
+            const txfData = result.merged;
+            if (txfData._history && txfData._history.length > 0) {
+              const imported = await this.importRemoteHistoryEntries(txfData._history);
+              if (imported > 0) {
+                this.log(`Imported ${imported} history entries from IPFS sync`);
+              }
+            }
             totalAdded += result.added;
             totalRemoved += result.removed;
           }
@@ -7093,7 +7501,7 @@ var PaymentsModule = class _PaymentsModule {
   /**
    * Handle NOSTR-FIRST commitment-only transfer (recipient side)
    * This is called when receiving a transfer with only commitmentData and no proof yet.
-   * We create the token as 'submitted', submit commitment (idempotent), and poll for proof.
+   * Delegates to saveCommitmentOnlyToken() helper, then emits event + records history.
    */
   async handleCommitmentOnlyTransfer(transfer, payload) {
     try {
@@ -7103,41 +7511,22 @@ var PaymentsModule = class _PaymentsModule {
         console.warn("[Payments] Invalid NOSTR-FIRST transfer format");
         return;
       }
-      const tokenInfo = await parseTokenInfo(sourceTokenInput);
-      const token = {
-        id: tokenInfo.tokenId ?? crypto.randomUUID(),
-        coinId: tokenInfo.coinId,
-        symbol: tokenInfo.symbol,
-        name: tokenInfo.name,
-        decimals: tokenInfo.decimals,
-        iconUrl: tokenInfo.iconUrl,
-        amount: tokenInfo.amount,
-        status: "submitted",
-        // NOSTR-FIRST: unconfirmed until proof
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-        sdkData: typeof sourceTokenInput === "string" ? sourceTokenInput : JSON.stringify(sourceTokenInput)
-      };
-      const nostrTokenId = extractTokenIdFromSdkData(token.sdkData);
-      const nostrStateHash = extractStateHashFromSdkData(token.sdkData);
-      if (nostrTokenId && nostrStateHash && this.isStateTombstoned(nostrTokenId, nostrStateHash)) {
-        this.log(`NOSTR-FIRST: Rejecting tombstoned token ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`);
-        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();
-      console.log(`[Payments][DEBUG] NOSTR-FIRST: save() completed, tokens.size=${this.tokens.size}`);
+      const token = await this.saveCommitmentOnlyToken(
+        sourceTokenInput,
+        commitmentInput,
+        transfer.senderTransportPubkey
+      );
+      if (!token) return;
       const senderInfo = await this.resolveSenderInfo(transfer.senderTransportPubkey);
-      const incomingTransfer = {
+      this.deps.emitEvent("transfer:incoming", {
         id: transfer.id,
         senderPubkey: transfer.senderTransportPubkey,
         senderNametag: senderInfo.senderNametag,
         tokens: [token],
         memo: payload.memo,
         receivedAt: transfer.timestamp
-      };
-      this.deps.emitEvent("transfer:incoming", incomingTransfer);
+      });
+      const nostrTokenId = extractTokenIdFromSdkData(token.sdkData);
       await this.addToHistory({
         type: "RECEIVED",
         amount: token.amount,
@@ -7149,29 +7538,6 @@ var PaymentsModule = class _PaymentsModule {
         memo: payload.memo,
         tokenId: nostrTokenId || token.id
       });
-      try {
-        const commitment = await import_TransferCommitment4.TransferCommitment.fromJSON(commitmentInput);
-        const requestIdBytes = commitment.requestId;
-        const requestIdHex = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
-        const stClient = this.deps.oracle.getStateTransitionClient?.();
-        if (stClient) {
-          const response = await stClient.submitTransferCommitment(commitment);
-          this.log(`NOSTR-FIRST recipient commitment submit: ${response.status}`);
-        }
-        this.addProofPollingJob({
-          tokenId: token.id,
-          requestIdHex,
-          commitmentJson: JSON.stringify(commitmentInput),
-          startedAt: Date.now(),
-          attemptCount: 0,
-          lastAttemptAt: 0,
-          onProofReceived: async (tokenId) => {
-            await this.finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput);
-          }
-        });
-      } catch (err) {
-        console.error("[Payments] Failed to parse commitment for proof polling:", err);
-      }
     } catch (error) {
       console.error("[Payments] Failed to process NOSTR-FIRST transfer:", error);
     }
@@ -7290,6 +7656,28 @@ var PaymentsModule = class _PaymentsModule {
     try {
       const payload = transfer.payload;
       console.log("[Payments][DEBUG] handleIncomingTransfer: keys=", Object.keys(payload).join(","));
+      let combinedBundle = null;
+      if (isCombinedTransferBundleV6(payload)) {
+        combinedBundle = payload;
+      } else if (payload.token) {
+        try {
+          const inner = typeof payload.token === "string" ? JSON.parse(payload.token) : payload.token;
+          if (isCombinedTransferBundleV6(inner)) {
+            combinedBundle = inner;
+          }
+        } catch {
+        }
+      }
+      if (combinedBundle) {
+        this.log("Processing COMBINED_TRANSFER V6 bundle...");
+        try {
+          await this.processCombinedTransferBundle(combinedBundle, transfer.senderTransportPubkey);
+          this.log("COMBINED_TRANSFER V6 processed successfully");
+        } catch (err) {
+          console.error("[Payments] COMBINED_TRANSFER V6 processing error:", err);
+        }
+        return;
+      }
       let instantBundle = null;
       if (isInstantSplitBundle(payload)) {
         instantBundle = payload;
@@ -7441,17 +7829,19 @@ var PaymentsModule = class _PaymentsModule {
           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
+        };
+        this.deps.emitEvent("transfer:incoming", incomingTransfer);
+        this.log(`Incoming transfer processed: ${token.id}, ${token.amount} ${token.symbol}`);
+      } else {
+        this.log(`Duplicate transfer ignored: ${token.id}, ${token.amount} ${token.symbol}`);
       }
-      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);
-      this.log(`Incoming transfer processed: ${token.id}, ${token.amount} ${token.symbol}`);
     } catch (error) {
       console.error("[Payments] Failed to process incoming transfer:", error);
     }
@@ -7520,6 +7910,7 @@ var PaymentsModule = class _PaymentsModule {
     return data ? JSON.parse(data) : [];
   }
   async createStorageData() {
+    const sorted = [...this._historyCache].sort((a, b) => b.timestamp - a.timestamp);
     return await buildTxfStorageData(
       Array.from(this.tokens.values()),
       {
@@ -7531,7 +7922,8 @@ var PaymentsModule = class _PaymentsModule {
         nametags: this.nametags,
         tombstones: this.tombstones,
         archivedTokens: this.archivedTokens,
-        forkedTokens: this.forkedTokens
+        forkedTokens: this.forkedTokens,
+        historyEntries: sorted.slice(0, MAX_SYNCED_HISTORY_ENTRIES)
       }
     );
   }