@unicitylabs/sphere-sdk 0.4.8 → 0.5.0

package/dist/core/index.cjs

@@ -610,6 +610,8 @@ function disconnect() {
     if (cb.timeoutId) clearTimeout(cb.timeoutId);
   });
   connectionCallbacks.length = 0;
+  blockSubscribers.length = 0;
+  lastBlockHeader = null;
 }
 var DEFAULT_ENDPOINT, ws, isConnected, isConnecting, requestId, intentionalClose, reconnectAttempts, isBlockSubscribed, lastBlockHeader, pending, blockSubscribers, connectionCallbacks, MAX_RECONNECT_ATTEMPTS, BASE_DELAY, MAX_DELAY, RPC_TIMEOUT, CONNECTION_TIMEOUT;
 var init_network = __esm({
@@ -3511,7 +3513,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
         }
@@ -4070,6 +4072,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);
@@ -4368,7 +4375,7 @@ var PaymentsModule = class _PaymentsModule {
   tombstones = [];
   archivedTokens = /* @__PURE__ */ new Map();
   forkedTokens = /* @__PURE__ */ new Map();
-  transactionHistory = [];
+  _historyCache = [];
   nametags = [];
   // Payment Requests State (Incoming)
   paymentRequests = [];
@@ -4437,7 +4444,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;
@@ -4488,14 +4495,7 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
     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 = [];
-      }
-    }
+    await this.loadHistory();
     const pending2 = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
     if (pending2) {
       const transfers = JSON.parse(pending2);
@@ -4582,7 +4582,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") {
@@ -4613,7 +4613,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()),
@@ -4622,7 +4622,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",
@@ -4647,6 +4647,7 @@ var PaymentsModule = class _PaymentsModule {
             this.deps.transport,
             recipientPubkey,
             {
+              memo: request.memo,
               onChangeTokenCreated: async (changeToken) => {
                 const changeTokenData = changeToken.toJSON();
                 const uiToken = {
@@ -4662,7 +4663,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 () => {
@@ -4677,7 +4678,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",
@@ -4724,20 +4725,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;
@@ -4848,6 +4854,7 @@ var PaymentsModule = class _PaymentsModule {
         recipientPubkey,
         {
           ...options,
+          memo: request.memo,
           onChangeTokenCreated: async (changeToken) => {
             const changeTokenData = changeToken.toJSON();
             const uiToken = {
@@ -4863,7 +4870,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 () => {
@@ -4876,15 +4883,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 {
@@ -4915,10 +4927,10 @@ 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 (!isInstantSplitBundleV5(bundle)) {
-      return this.processInstantSplitBundleSync(bundle, senderPubkey);
+      return this.processInstantSplitBundleSync(bundle, senderPubkey, memo);
     }
     try {
       const deterministicId = `v5split_${bundle.splitGroupId}`;
@@ -4948,12 +4960,26 @@ var PaymentsModule = class _PaymentsModule {
         updatedAt: Date.now(),
         sdkData: JSON.stringify({ _pendingFinalization: pendingData })
       };
-      await this.addToken(uiToken, false);
+      await this.addToken(uiToken);
       this.log(`V5 bundle saved as unconfirmed: ${uiToken.id.slice(0, 8)}...`);
+      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();
@@ -4973,7 +4999,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?.();
@@ -5033,19 +5059,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()
         });
       }
@@ -5788,14 +5821,6 @@ 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.log(`V5 token resolved: ${tokenId.slice(0, 8)}...`);
         return "resolved";
       }
@@ -5979,10 +6004,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);
@@ -6028,15 +6052,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;
@@ -6063,7 +6078,7 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
     if (!found) {
-      await this.addToken(token, true);
+      await this.addToken(token);
       return;
     }
     await this.archiveToken(token);
@@ -6078,10 +6093,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;
@@ -6099,16 +6112,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();
   }
   // ===========================================================================
@@ -6333,26 +6336,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
@@ -6895,14 +6976,27 @@ var PaymentsModule = class _PaymentsModule {
       this.tokens.set(token.id, token);
       await this.save();
       this.log(`NOSTR-FIRST: Token ${token.id.slice(0, 8)}... added as submitted (unconfirmed)`);
+      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;
@@ -6920,7 +7014,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) {
@@ -6979,7 +7073,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) {
@@ -7027,14 +7121,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);
@@ -7065,7 +7151,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");
@@ -7183,10 +7270,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