@unicitylabs/sphere-sdk 0.2.2 → 0.2.5

package/dist/core/index.cjs

@@ -520,6 +520,7 @@ __export(core_exports, {
   initSphere: () => initSphere,
   isEncryptedData: () => isEncryptedData,
   isValidBech32: () => isValidBech32,
+  isValidNametag: () => isValidNametag,
   isValidPrivateKey: () => isValidPrivateKey,
   loadSphere: () => loadSphere,
   mnemonicToEntropy: () => mnemonicToEntropy2,
@@ -1553,7 +1554,7 @@ var L1PaymentsModule = class {
   _transport;
   constructor(config) {
     this._config = {
-      electrumUrl: config?.electrumUrl ?? "wss://fulcrum.alpha.unicity.network:50004",
+      electrumUrl: config?.electrumUrl ?? "wss://fulcrum.unicity.network:50004",
       network: config?.network ?? "mainnet",
       defaultFeeRate: config?.defaultFeeRate ?? 10,
       enableVesting: config?.enableVesting ?? true
@@ -1585,10 +1586,17 @@ var L1PaymentsModule = class {
         });
       }
     }
-    if (this._config.electrumUrl) {
+    this._initialized = true;
+  }
+  /**
+   * Ensure the Fulcrum WebSocket is connected. Called lazily before any
+   * operation that needs the network. If the singleton is already connected
+   * (e.g. by the address scanner), this is a no-op.
+   */
+  async ensureConnected() {
+    if (!isWebSocketConnected() && this._config.electrumUrl) {
       await connect(this._config.electrumUrl);
     }
-    this._initialized = true;
   }
   destroy() {
     if (isWebSocketConnected()) {
@@ -1646,6 +1654,7 @@ var L1PaymentsModule = class {
   }
   async send(request) {
     this.ensureInitialized();
+    await this.ensureConnected();
     if (!this._wallet || !this._identity) {
       return { success: false, error: "No wallet available" };
     }
@@ -1680,6 +1689,7 @@ var L1PaymentsModule = class {
   }
   async getBalance() {
     this.ensureInitialized();
+    await this.ensureConnected();
     const addresses = this._getWatchedAddresses();
     let totalAlpha = 0;
     let vestedSats = BigInt(0);
@@ -1711,6 +1721,7 @@ var L1PaymentsModule = class {
   }
   async getUtxos() {
     this.ensureInitialized();
+    await this.ensureConnected();
     const result = [];
     const currentHeight = await getCurrentBlockHeight();
     const allUtxos = await this._getAllUtxos();
@@ -1746,42 +1757,73 @@ var L1PaymentsModule = class {
     return result;
   }
   async getHistory(limit) {
+    await this.ensureConnected();
     this.ensureInitialized();
     const addresses = this._getWatchedAddresses();
     const transactions = [];
     const seenTxids = /* @__PURE__ */ new Set();
     const currentHeight = await getCurrentBlockHeight();
+    const txCache = /* @__PURE__ */ new Map();
+    const fetchTx = async (txid) => {
+      if (txCache.has(txid)) return txCache.get(txid);
+      const detail = await getTransaction(txid);
+      txCache.set(txid, detail);
+      return detail;
+    };
+    const addressSet = new Set(addresses.map((a) => a.toLowerCase()));
     for (const address of addresses) {
       const history = await getTransactionHistory(address);
       for (const item of history) {
         if (seenTxids.has(item.tx_hash)) continue;
         seenTxids.add(item.tx_hash);
-        const tx = await getTransaction(item.tx_hash);
+        const tx = await fetchTx(item.tx_hash);
         if (!tx) continue;
-        const isSend = tx.vin?.some(
-          (vin) => addresses.includes(vin.txid ?? "")
-        );
-        let amount = "0";
+        let isSend = false;
+        for (const vin of tx.vin ?? []) {
+          if (!vin.txid) continue;
+          const prevTx = await fetchTx(vin.txid);
+          if (prevTx?.vout?.[vin.vout]) {
+            const prevOut = prevTx.vout[vin.vout];
+            const prevAddrs = [
+              ...prevOut.scriptPubKey?.addresses ?? [],
+              ...prevOut.scriptPubKey?.address ? [prevOut.scriptPubKey.address] : []
+            ];
+            if (prevAddrs.some((a) => addressSet.has(a.toLowerCase()))) {
+              isSend = true;
+              break;
+            }
+          }
+        }
+        let amountToUs = 0;
+        let amountToOthers = 0;
         let txAddress = address;
+        let externalAddress = "";
         if (tx.vout) {
           for (const vout of tx.vout) {
-            const voutAddresses = vout.scriptPubKey?.addresses ?? [];
-            if (vout.scriptPubKey?.address) {
-              voutAddresses.push(vout.scriptPubKey.address);
-            }
-            const matchedAddr = voutAddresses.find((a) => addresses.includes(a));
-            if (matchedAddr) {
-              amount = Math.floor((vout.value ?? 0) * 1e8).toString();
-              txAddress = matchedAddr;
-              break;
+            const voutAddresses = [
+              ...vout.scriptPubKey?.addresses ?? [],
+              ...vout.scriptPubKey?.address ? [vout.scriptPubKey.address] : []
+            ];
+            const isOurs = voutAddresses.some((a) => addressSet.has(a.toLowerCase()));
+            const valueSats = Math.floor((vout.value ?? 0) * 1e8);
+            if (isOurs) {
+              amountToUs += valueSats;
+              if (!txAddress) txAddress = voutAddresses[0];
+            } else {
+              amountToOthers += valueSats;
+              if (!externalAddress && voutAddresses.length > 0) {
+                externalAddress = voutAddresses[0];
+              }
             }
           }
         }
+        const amount = isSend ? amountToOthers.toString() : amountToUs.toString();
+        const displayAddress = isSend ? externalAddress || txAddress : txAddress;
         transactions.push({
           txid: item.tx_hash,
           type: isSend ? "send" : "receive",
           amount,
-          address: txAddress,
+          address: displayAddress,
           confirmations: item.height > 0 ? currentHeight - item.height : 0,
           timestamp: tx.time ? tx.time * 1e3 : Date.now(),
           blockHeight: item.height > 0 ? item.height : void 0
@@ -1793,6 +1835,7 @@ var L1PaymentsModule = class {
   }
   async getTransaction(txid) {
     this.ensureInitialized();
+    await this.ensureConnected();
     const tx = await getTransaction(txid);
     if (!tx) return null;
     const addresses = this._getWatchedAddresses();
@@ -1828,6 +1871,7 @@ var L1PaymentsModule = class {
   }
   async estimateFee(to, amount) {
     this.ensureInitialized();
+    await this.ensureConnected();
     if (!this._wallet) {
       return { fee: "0", feeRate: this._config.defaultFeeRate ?? 10 };
     }
@@ -2167,6 +2211,7 @@ var import_MintCommitment = require("@unicitylabs/state-transition-sdk/lib/trans
 var import_HashAlgorithm2 = require("@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm");
 var import_UnmaskedPredicate2 = require("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate");
 var import_InclusionProofUtils2 = require("@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils");
+var import_nostr_js_sdk = require("@unicitylabs/nostr-js-sdk");
 var UNICITY_TOKEN_TYPE_HEX = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
 var NametagMinter = class {
   client;
@@ -2191,7 +2236,8 @@ var NametagMinter = class {
    */
   async isNametagAvailable(nametag) {
     try {
-      const cleanNametag = nametag.replace("@", "").trim();
+      const stripped = nametag.startsWith("@") ? nametag.slice(1) : nametag;
+      const cleanNametag = (0, import_nostr_js_sdk.normalizeNametag)(stripped);
       const nametagTokenId = await import_TokenId2.TokenId.fromNameTag(cleanNametag);
       const isMinted = await this.client.isMinted(this.trustBase, nametagTokenId);
       return !isMinted;
@@ -2208,7 +2254,8 @@ var NametagMinter = class {
    * @returns MintNametagResult with token if successful
    */
   async mintNametag(nametag, ownerAddress) {
-    const cleanNametag = nametag.replace("@", "").trim();
+    const stripped = nametag.startsWith("@") ? nametag.slice(1) : nametag;
+    const cleanNametag = (0, import_nostr_js_sdk.normalizeNametag)(stripped);
     this.log(`Starting mint for nametag: ${cleanNametag}`);
     try {
       const nametagTokenId = await import_TokenId2.TokenId.fromNameTag(cleanNametag);
@@ -2347,7 +2394,9 @@ var STORAGE_KEYS_GLOBAL = {
   /** Nametag cache per address (separate from tracked addresses registry) */
   ADDRESS_NAMETAGS: "address_nametags",
   /** Active addresses registry (JSON: TrackedAddressesStorage) */
-  TRACKED_ADDRESSES: "tracked_addresses"
+  TRACKED_ADDRESSES: "tracked_addresses",
+  /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
+  LAST_WALLET_EVENT_TS: "last_wallet_event_ts"
 };
 var STORAGE_KEYS_ADDRESS = {
   /** Pending transfers for this address */
@@ -2359,7 +2408,9 @@ var STORAGE_KEYS_ADDRESS = {
   /** Messages for this address */
   MESSAGES: "messages",
   /** Transaction history for this address */
-  TRANSACTION_HISTORY: "transaction_history"
+  TRANSACTION_HISTORY: "transaction_history",
+  /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
+  PENDING_V5_TOKENS: "pending_v5_tokens"
 };
 var STORAGE_KEYS = {
   ...STORAGE_KEYS_GLOBAL,
@@ -2378,16 +2429,6 @@ function getAddressId(directAddress) {
 }
 var DEFAULT_BASE_PATH = "m/44'/0'/0'";
 var DEFAULT_DERIVATION_PATH2 = `${DEFAULT_BASE_PATH}/0/0`;
-var LIMITS = {
-  /** Min nametag length */
-  NAMETAG_MIN_LENGTH: 3,
-  /** Max nametag length */
-  NAMETAG_MAX_LENGTH: 20,
-  /** Max memo length */
-  MEMO_MAX_LENGTH: 500,
-  /** Max message length */
-  MESSAGE_MAX_LENGTH: 1e4
-};
 
 // types/txf.ts
 var ARCHIVED_PREFIX = "archived-";
@@ -2680,6 +2721,18 @@ function parseTxfStorageData(data) {
           result.validationErrors.push(`Forked token ${parsed.tokenId}: invalid structure`);
         }
       }
+    } else if (key.startsWith("token-")) {
+      try {
+        const entry = storageData[key];
+        const txfToken = entry?.token;
+        if (txfToken?.genesis?.data?.tokenId) {
+          const tokenId = txfToken.genesis.data.tokenId;
+          const token = txfToToken(tokenId, txfToken);
+          result.tokens.push(token);
+        }
+      } catch (err) {
+        result.validationErrors.push(`Token ${key}: ${err}`);
+      }
     }
   }
   return result;
@@ -3180,8 +3233,9 @@ 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) {
-        this.submitBackgroundV5(senderMintCommitment, recipientMintCommitment, transferCommitment, {
+        backgroundPromise = this.submitBackgroundV5(senderMintCommitment, recipientMintCommitment, transferCommitment, {
           signingService: this.signingService,
           tokenType: tokenToSplit.type,
           coinId,
@@ -3197,7 +3251,8 @@ var InstantSplitExecutor = class {
         nostrEventId,
         splitGroupId,
         criticalPathDurationMs: criticalPathDuration,
-        backgroundStarted: !options?.skipBackground
+        backgroundStarted: !options?.skipBackground,
+        backgroundPromise
       };
     } catch (error) {
       const duration = performance.now() - startTime;
@@ -3259,7 +3314,7 @@ var InstantSplitExecutor = class {
       this.client.submitMintCommitment(recipientMintCommitment).then((res) => ({ type: "recipientMint", status: res.status })).catch((err) => ({ type: "recipientMint", status: "ERROR", error: err })),
       this.client.submitTransferCommitment(transferCommitment).then((res) => ({ type: "transfer", status: res.status })).catch((err) => ({ type: "transfer", status: "ERROR", error: err }))
     ]);
-    submissions.then(async (results) => {
+    return submissions.then(async (results) => {
       const submitDuration = performance.now() - startTime;
       console.log(`[InstantSplit] Background: Submissions complete in ${submitDuration.toFixed(0)}ms`);
       context.onProgress?.({
@@ -3724,6 +3779,11 @@ var import_AddressScheme = require("@unicitylabs/state-transition-sdk/lib/addres
 var import_UnmaskedPredicate5 = require("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate");
 var import_TokenState5 = require("@unicitylabs/state-transition-sdk/lib/token/TokenState");
 var import_HashAlgorithm5 = require("@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm");
+var import_TokenType3 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+var import_MintCommitment3 = require("@unicitylabs/state-transition-sdk/lib/transaction/MintCommitment");
+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 enrichWithRegistry(info) {
   const registry = TokenRegistry.getInstance();
   const def = registry.getDefinition(info.coinId);
@@ -3751,7 +3811,7 @@ async function parseTokenInfo(tokenData) {
     try {
       const sdkToken = await import_Token6.Token.fromJSON(data);
       if (sdkToken.id) {
-        defaultInfo.tokenId = sdkToken.id.toString();
+        defaultInfo.tokenId = sdkToken.id.toJSON();
       }
       if (sdkToken.coins && sdkToken.coins.coins) {
         const rawCoins = sdkToken.coins.coins;
@@ -3921,6 +3981,13 @@ function extractTokenStateKey(token) {
   if (!tokenId || !stateHash) return null;
   return createTokenStateKey(tokenId, stateHash);
 }
+function fromHex4(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes;
+}
 function hasSameGenesisTokenId(t1, t2) {
   const id1 = extractTokenIdFromSdkData(t1.sdkData);
   const id2 = extractTokenIdFromSdkData(t2.sdkData);
@@ -4010,6 +4077,7 @@ var PaymentsModule = class _PaymentsModule {
   // Token State
   tokens = /* @__PURE__ */ new Map();
   pendingTransfers = /* @__PURE__ */ new Map();
+  pendingBackgroundTasks = [];
   // Repository State (tombstones, archives, forked, history)
   tombstones = [];
   archivedTokens = /* @__PURE__ */ new Map();
@@ -4034,6 +4102,12 @@ var PaymentsModule = class _PaymentsModule {
   // Poll every 2s
   static PROOF_POLLING_MAX_ATTEMPTS = 30;
   // Max 30 attempts (~60s)
+  // Storage event subscriptions (push-based sync)
+  storageEventUnsubscribers = [];
+  syncDebounceTimer = null;
+  static SYNC_DEBOUNCE_MS = 500;
+  /** Sync coalescing: concurrent sync() calls share the same operation */
+  _syncInProgress = null;
   constructor(config) {
     this.moduleConfig = {
       autoSync: config?.autoSync ?? true,
@@ -4042,10 +4116,13 @@ var PaymentsModule = class _PaymentsModule {
       maxRetries: config?.maxRetries ?? 3,
       debug: config?.debug ?? false
     };
-    const l1Enabled = config?.l1?.electrumUrl && config.l1.electrumUrl.length > 0;
-    this.l1 = l1Enabled ? new L1PaymentsModule(config?.l1) : null;
+    this.l1 = config?.l1 === null ? null : new L1PaymentsModule(config?.l1);
   }
-  /** Get module configuration */
+  /**
+   * Get the current module configuration (excluding L1 config).
+   *
+   * @returns Resolved configuration with all defaults applied.
+   */
   getConfig() {
     return this.moduleConfig;
   }
@@ -4086,9 +4163,9 @@ var PaymentsModule = class _PaymentsModule {
         transport: deps.transport
       });
     }
-    this.unsubscribeTransfers = deps.transport.onTokenTransfer((transfer) => {
-      this.handleIncomingTransfer(transfer);
-    });
+    this.unsubscribeTransfers = deps.transport.onTokenTransfer(
+      (transfer) => this.handleIncomingTransfer(transfer)
+    );
     if (deps.transport.onPaymentRequest) {
       this.unsubscribePaymentRequests = deps.transport.onPaymentRequest((request) => {
         this.handleIncomingPaymentRequest(request);
@@ -4099,9 +4176,14 @@ var PaymentsModule = class _PaymentsModule {
         this.handlePaymentRequestResponse(response);
       });
     }
+    this.subscribeToStorageEvents();
   }
   /**
-   * Load tokens from storage
+   * Load all token data from storage providers and restore wallet state.
+   *
+   * Loads tokens, nametag data, transaction history, and pending transfers
+   * from configured storage providers. Restores pending V5 tokens and
+   * triggers a fire-and-forget {@link resolveUnconfirmed} call.
    */
   async load() {
     this.ensureInitialized();
@@ -4118,6 +4200,7 @@ var PaymentsModule = class _PaymentsModule {
         console.error(`[Payments] Failed to load from provider ${id}:`, err);
       }
     }
+    await this.loadPendingV5Tokens();
     await this.loadTokensFromFileStorage();
     await this.loadNametagFromFileStorage();
     const historyData = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
@@ -4135,9 +4218,14 @@ var PaymentsModule = class _PaymentsModule {
         this.pendingTransfers.set(transfer.id, transfer);
       }
     }
+    this.resolveUnconfirmed().catch(() => {
+    });
   }
   /**
-   * Cleanup resources
+   * Cleanup all subscriptions, polling jobs, and pending resolvers.
+   *
+   * Should be called when the wallet is being shut down or the module is
+   * no longer needed. Also destroys the L1 sub-module if present.
    */
   destroy() {
     this.unsubscribeTransfers?.();
@@ -4155,6 +4243,7 @@ var PaymentsModule = class _PaymentsModule {
       resolver.reject(new Error("Module destroyed"));
     }
     this.pendingResponseResolvers.clear();
+    this.unsubscribeStorageEvents();
     if (this.l1) {
       this.l1.destroy();
     }
@@ -4171,7 +4260,8 @@ var PaymentsModule = class _PaymentsModule {
     const result = {
       id: crypto.randomUUID(),
       status: "pending",
-      tokens: []
+      tokens: [],
+      tokenTransfers: []
     };
     try {
       const peerInfo = await this.deps.transport.resolve?.(request.recipient) ?? null;
@@ -4208,69 +4298,147 @@ var PaymentsModule = class _PaymentsModule {
       await this.saveToOutbox(result, recipientPubkey);
       result.status = "submitted";
       const recipientNametag = request.recipient.startsWith("@") ? request.recipient.slice(1) : void 0;
+      const transferMode = request.transferMode ?? "instant";
       if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
-        this.log("Executing token split...");
-        const executor = new TokenSplitExecutor({
-          stateTransitionClient: stClient,
-          trustBase,
-          signingService
-        });
-        const splitResult = await executor.executeSplit(
-          splitPlan.tokenToSplit.sdkToken,
-          splitPlan.splitAmount,
-          splitPlan.remainderAmount,
-          splitPlan.coinId,
-          recipientAddress
-        );
-        const changeTokenData = splitResult.tokenForSender.toJSON();
-        const changeToken = {
-          id: crypto.randomUUID(),
-          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: "confirmed",
-          createdAt: Date.now(),
-          updatedAt: Date.now(),
-          sdkData: JSON.stringify(changeTokenData)
-        };
-        await this.addToken(changeToken, true);
-        this.log(`Change token saved: ${changeToken.id}, amount: ${changeToken.amount}`);
-        console.log(`[Payments] Sending split token to ${recipientPubkey.slice(0, 8)}... via Nostr`);
-        await this.deps.transport.sendTokenTransfer(recipientPubkey, {
-          sourceToken: JSON.stringify(splitResult.tokenForRecipient.toJSON()),
-          transferTx: JSON.stringify(splitResult.recipientTransferTx.toJSON()),
-          memo: request.memo
-        });
-        console.log(`[Payments] Split token sent successfully`);
-        await this.removeToken(splitPlan.tokenToSplit.uiToken.id, recipientNametag, true);
-        result.txHash = "split-" + Date.now().toString(16);
-        this.log(`Split transfer completed`);
+        if (transferMode === "conservative") {
+          this.log("Executing conservative split...");
+          const splitExecutor = new TokenSplitExecutor({
+            stateTransitionClient: stClient,
+            trustBase,
+            signingService
+          });
+          const splitResult = await splitExecutor.executeSplit(
+            splitPlan.tokenToSplit.sdkToken,
+            splitPlan.splitAmount,
+            splitPlan.remainderAmount,
+            splitPlan.coinId,
+            recipientAddress
+          );
+          const changeTokenData = splitResult.tokenForSender.toJSON();
+          const changeUiToken = {
+            id: crypto.randomUUID(),
+            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: "confirmed",
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            sdkData: JSON.stringify(changeTokenData)
+          };
+          await this.addToken(changeUiToken, true);
+          this.log(`Conservative split: change token saved: ${changeUiToken.id}`);
+          await this.deps.transport.sendTokenTransfer(recipientPubkey, {
+            sourceToken: JSON.stringify(splitResult.tokenForRecipient.toJSON()),
+            transferTx: JSON.stringify(splitResult.recipientTransferTx.toJSON()),
+            memo: request.memo
+          });
+          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);
+          result.tokenTransfers.push({
+            sourceTokenId: splitPlan.tokenToSplit.uiToken.id,
+            method: "split",
+            requestIdHex: splitRequestIdHex
+          });
+          this.log(`Conservative split transfer completed`);
+        } else {
+          this.log("Executing instant split...");
+          const devMode = this.deps.oracle.isDevMode?.() ?? false;
+          const executor = new InstantSplitExecutor({
+            stateTransitionClient: stClient,
+            trustBase,
+            signingService,
+            devMode
+          });
+          const instantResult = await executor.executeSplitInstant(
+            splitPlan.tokenToSplit.sdkToken,
+            splitPlan.splitAmount,
+            splitPlan.remainderAmount,
+            splitPlan.coinId,
+            recipientAddress,
+            this.deps.transport,
+            recipientPubkey,
+            {
+              onChangeTokenCreated: async (changeToken) => {
+                const changeTokenData = changeToken.toJSON();
+                const uiToken = {
+                  id: crypto.randomUUID(),
+                  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: "confirmed",
+                  createdAt: Date.now(),
+                  updatedAt: Date.now(),
+                  sdkData: JSON.stringify(changeTokenData)
+                };
+                await this.addToken(uiToken, true);
+                this.log(`Change token saved via background: ${uiToken.id}`);
+              },
+              onStorageSync: async () => {
+                await this.save();
+                return true;
+              }
+            }
+          );
+          if (!instantResult.success) {
+            throw new Error(instantResult.error || "Instant split failed");
+          }
+          if (instantResult.backgroundPromise) {
+            this.pendingBackgroundTasks.push(instantResult.backgroundPromise);
+          }
+          await this.removeToken(splitPlan.tokenToSplit.uiToken.id, recipientNametag);
+          result.tokenTransfers.push({
+            sourceTokenId: splitPlan.tokenToSplit.uiToken.id,
+            method: "split",
+            splitGroupId: instantResult.splitGroupId,
+            nostrEventId: instantResult.nostrEventId
+          });
+          this.log(`Instant split transfer completed`);
+        }
       }
       for (const tokenWithAmount of splitPlan.tokensToTransferDirectly) {
         const token = tokenWithAmount.uiToken;
         const commitment = await this.createSdkCommitment(token, recipientAddress, signingService);
-        const response = await stClient.submitTransferCommitment(commitment);
-        if (response.status !== "SUCCESS" && response.status !== "REQUEST_ID_EXISTS") {
-          throw new Error(`Transfer commitment failed: ${response.status}`);
-        }
-        if (!this.deps.oracle.waitForProofSdk) {
-          throw new Error("Oracle provider must implement waitForProofSdk()");
+        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
+          });
+          console.log(`[Payments] NOSTR-FIRST: Direct token sent successfully`);
+          stClient.submitTransferCommitment(commitment).catch(
+            (err) => console.error("[Payments] Background commitment submit failed:", err)
+          );
         }
-        const inclusionProof = await this.deps.oracle.waitForProofSdk(commitment);
-        const transferTx = commitment.toTransaction(inclusionProof);
         const requestIdBytes = commitment.requestId;
-        result.txHash = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
-        console.log(`[Payments] Sending direct token ${token.id.slice(0, 8)}... to ${recipientPubkey.slice(0, 8)}... via Nostr`);
-        await this.deps.transport.sendTokenTransfer(recipientPubkey, {
-          sourceToken: JSON.stringify(tokenWithAmount.sdkToken.toJSON()),
-          transferTx: JSON.stringify(transferTx.toJSON()),
-          memo: request.memo
+        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] Direct token sent successfully`);
-        this.log(`Token ${token.id} transferred, txHash: ${result.txHash}`);
+        this.log(`Token ${token.id} sent via ${transferMode.toUpperCase()}, requestId: ${requestIdHex}`);
         await this.removeToken(token.id, recipientNametag, true);
       }
       result.status = "delivered";
@@ -4283,7 +4451,8 @@ var PaymentsModule = class _PaymentsModule {
         coinId: request.coinId,
         symbol: this.getCoinSymbol(request.coinId),
         timestamp: Date.now(),
-        recipientNametag
+        recipientNametag,
+        transferId: result.id
       });
       this.deps.emitEvent("transfer:confirmed", result);
       return result;
@@ -4419,6 +4588,9 @@ var PaymentsModule = class _PaymentsModule {
         }
       );
       if (result.success) {
+        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.addToHistory({
@@ -4460,6 +4632,63 @@ var PaymentsModule = class _PaymentsModule {
    */
   async processInstantSplitBundle(bundle, senderPubkey) {
     this.ensureInitialized();
+    if (!isInstantSplitBundleV5(bundle)) {
+      return this.processInstantSplitBundleSync(bundle, senderPubkey);
+    }
+    try {
+      const deterministicId = `v5split_${bundle.splitGroupId}`;
+      if (this.tokens.has(deterministicId)) {
+        this.log(`V5 bundle ${deterministicId.slice(0, 16)}... already exists, skipping duplicate`);
+        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, false);
+      this.log(`V5 bundle saved as unconfirmed: ${uiToken.id.slice(0, 8)}...`);
+      this.deps.emitEvent("transfer:incoming", {
+        id: bundle.splitGroupId,
+        senderPubkey,
+        tokens: [uiToken],
+        receivedAt: Date.now()
+      });
+      await this.save();
+      this.resolveUnconfirmed().catch(() => {
+      });
+      return { success: true, durationMs: 0 };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        error: errorMessage,
+        durationMs: 0
+      };
+    }
+  }
+  /**
+   * Synchronous V4 bundle processing (dev mode only).
+   * Kept for backward compatibility with V4 bundles.
+   */
+  async processInstantSplitBundleSync(bundle, senderPubkey) {
     try {
       const signingService = await this.createSigningService();
       const stClient = this.deps.oracle.getStateTransitionClient?.();
@@ -4545,7 +4774,10 @@ var PaymentsModule = class _PaymentsModule {
     }
   }
   /**
-   * Check if a payload is an instant split bundle
+   * Type-guard: check whether a payload is a valid {@link InstantSplitBundle} (V4 or V5).
+   *
+   * @param payload - The object to test.
+   * @returns `true` if the payload matches the InstantSplitBundle shape.
    */
   isInstantSplitBundle(payload) {
     return isInstantSplitBundle(payload);
@@ -4626,39 +4858,57 @@ var PaymentsModule = class _PaymentsModule {
     return [...this.paymentRequests];
   }
   /**
-   * Get pending payment requests count
+   * Get the count of payment requests with status `'pending'`.
+   *
+   * @returns Number of pending incoming payment requests.
    */
   getPendingPaymentRequestsCount() {
     return this.paymentRequests.filter((r) => r.status === "pending").length;
   }
   /**
-   * Accept a payment request (marks it as accepted, user should then call send())
+   * Accept a payment request and notify the requester.
+   *
+   * Marks the request as `'accepted'` and sends a response via transport.
+   * The caller should subsequently call {@link send} to fulfill the payment.
+   *
+   * @param requestId - ID of the incoming payment request to accept.
    */
   async acceptPaymentRequest(requestId2) {
     this.updatePaymentRequestStatus(requestId2, "accepted");
     await this.sendPaymentRequestResponse(requestId2, "accepted");
   }
   /**
-   * Reject a payment request
+   * Reject a payment request and notify the requester.
+   *
+   * @param requestId - ID of the incoming payment request to reject.
    */
   async rejectPaymentRequest(requestId2) {
     this.updatePaymentRequestStatus(requestId2, "rejected");
     await this.sendPaymentRequestResponse(requestId2, "rejected");
   }
   /**
-   * Mark a payment request as paid (after successful transfer)
+   * Mark a payment request as paid (local status update only).
+   *
+   * Typically called after a successful {@link send} to record that the
+   * request has been fulfilled.
+   *
+   * @param requestId - ID of the incoming payment request to mark as paid.
    */
   markPaymentRequestPaid(requestId2) {
     this.updatePaymentRequestStatus(requestId2, "paid");
   }
   /**
-   * Clear processed (non-pending) payment requests
+   * Remove all non-pending incoming payment requests from memory.
+   *
+   * Keeps only requests with status `'pending'`.
    */
   clearProcessedPaymentRequests() {
     this.paymentRequests = this.paymentRequests.filter((r) => r.status === "pending");
   }
   /**
-   * Remove a specific payment request
+   * Remove a specific incoming payment request by ID.
+   *
+   * @param requestId - ID of the payment request to remove.
    */
   removePaymentRequest(requestId2) {
     this.paymentRequests = this.paymentRequests.filter((r) => r.id !== requestId2);
@@ -4705,13 +4955,16 @@ var PaymentsModule = class _PaymentsModule {
     if (this.paymentRequests.find((r) => r.id === transportRequest.id)) {
       return;
     }
+    const coinId = transportRequest.request.coinId;
+    const registry = TokenRegistry.getInstance();
+    const coinDef = registry.getDefinition(coinId);
     const request = {
       id: transportRequest.id,
       senderPubkey: transportRequest.senderTransportPubkey,
+      senderNametag: transportRequest.senderNametag,
       amount: transportRequest.request.amount,
-      coinId: transportRequest.request.coinId,
-      symbol: transportRequest.request.coinId,
-      // Use coinId as symbol for now
+      coinId,
+      symbol: coinDef?.symbol || coinId.slice(0, 8),
       message: transportRequest.request.message,
       recipientNametag: transportRequest.request.recipientNametag,
       requestId: transportRequest.request.requestId,
@@ -4780,7 +5033,11 @@ var PaymentsModule = class _PaymentsModule {
     });
   }
   /**
-   * Cancel waiting for a payment response
+   * Cancel an active {@link waitForPaymentResponse} call.
+   *
+   * The pending promise is rejected with a `'Cancelled'` error.
+   *
+   * @param requestId - The outgoing request ID whose wait should be cancelled.
    */
   cancelWaitForPaymentResponse(requestId2) {
     const resolver = this.pendingResponseResolvers.get(requestId2);
@@ -4791,14 +5048,16 @@ var PaymentsModule = class _PaymentsModule {
     }
   }
   /**
-   * Remove an outgoing payment request
+   * Remove an outgoing payment request and cancel any pending wait.
+   *
+   * @param requestId - ID of the outgoing request to remove.
    */
   removeOutgoingPaymentRequest(requestId2) {
     this.outgoingPaymentRequests.delete(requestId2);
     this.cancelWaitForPaymentResponse(requestId2);
   }
   /**
-   * Clear completed/expired outgoing payment requests
+   * Remove all outgoing payment requests that are `'paid'`, `'rejected'`, or `'expired'`.
    */
   clearCompletedOutgoingPaymentRequests() {
     for (const [id, request] of this.outgoingPaymentRequests) {
@@ -4870,6 +5129,71 @@ var PaymentsModule = class _PaymentsModule {
     }
   }
   // ===========================================================================
+  // Public API - Receive
+  // ===========================================================================
+  /**
+   * Fetch and process pending incoming transfers from the transport layer.
+   *
+   * Performs a one-shot query to fetch all pending events, processes them
+   * through the existing pipeline, and resolves after all stored events
+   * are handled. Useful for batch/CLI apps that need explicit receive.
+   *
+   * When `finalize` is true, polls resolveUnconfirmed() + load() until all
+   * tokens are confirmed or the timeout expires. Otherwise calls
+   * resolveUnconfirmed() once to submit pending commitments.
+   *
+   * @param options - Optional receive options including finalization control
+   * @param callback - Optional callback invoked for each newly received transfer
+   * @returns ReceiveResult with transfers and finalization metadata
+   */
+  async receive(options, callback) {
+    this.ensureInitialized();
+    if (!this.deps.transport.fetchPendingEvents) {
+      throw new Error("Transport provider does not support fetchPendingEvents");
+    }
+    const opts = options ?? {};
+    const tokensBefore = new Set(this.tokens.keys());
+    await this.deps.transport.fetchPendingEvents();
+    await this.load();
+    const received = [];
+    for (const [tokenId, token] of this.tokens) {
+      if (!tokensBefore.has(tokenId)) {
+        const transfer = {
+          id: tokenId,
+          senderPubkey: "",
+          tokens: [token],
+          receivedAt: Date.now()
+        };
+        received.push(transfer);
+        if (callback) callback(transfer);
+      }
+    }
+    const result = { transfers: received };
+    if (opts.finalize) {
+      const timeout = opts.timeout ?? 6e4;
+      const pollInterval = opts.pollInterval ?? 2e3;
+      const startTime = Date.now();
+      while (Date.now() - startTime < timeout) {
+        const resolution = await this.resolveUnconfirmed();
+        result.finalization = resolution;
+        if (opts.onProgress) opts.onProgress(resolution);
+        const stillUnconfirmed = Array.from(this.tokens.values()).some(
+          (t) => t.status === "submitted" || t.status === "pending"
+        );
+        if (!stillUnconfirmed) break;
+        await new Promise((r) => setTimeout(r, pollInterval));
+        await this.load();
+      }
+      result.finalizationDurationMs = Date.now() - startTime;
+      result.timedOut = Array.from(this.tokens.values()).some(
+        (t) => t.status === "submitted" || t.status === "pending"
+      );
+    } else {
+      result.finalization = await this.resolveUnconfirmed();
+    }
+    return result;
+  }
+  // ===========================================================================
   // Public API - Balance & Tokens
   // ===========================================================================
   /**
@@ -4879,10 +5203,20 @@ var PaymentsModule = class _PaymentsModule {
     this.priceProvider = provider;
   }
   /**
-   * Get total portfolio value in USD
-   * Returns null if PriceProvider is not configured
+   * Wait for all pending background operations (e.g., instant split change token creation).
+   * Call this before process exit to ensure all tokens are saved.
    */
-  async getBalance() {
+  async waitForPendingOperations() {
+    if (this.pendingBackgroundTasks.length > 0) {
+      await Promise.allSettled(this.pendingBackgroundTasks);
+      this.pendingBackgroundTasks = [];
+    }
+  }
+  /**
+   * Get total portfolio value in USD.
+   * Returns null if PriceProvider is not configured.
+   */
+  async getFiatBalance() {
     const assets = await this.getAssets();
     if (!this.priceProvider) {
       return null;
@@ -4898,19 +5232,95 @@ var PaymentsModule = class _PaymentsModule {
     return hasAnyPrice ? total : null;
   }
   /**
-   * Get aggregated assets (tokens grouped by coinId) with price data
-   * Only includes confirmed tokens
+   * Get token balances grouped by coin type.
+   *
+   * Returns an array of {@link Asset} objects, one per coin type held.
+   * Each entry includes confirmed and unconfirmed breakdowns. Tokens with
+   * status `'spent'`, `'invalid'`, or `'transferring'` are excluded.
+   *
+   * This is synchronous — no price data is included. Use {@link getAssets}
+   * for the async version with fiat pricing.
+   *
+   * @param coinId - Optional coin ID to filter by (e.g. hex string). When omitted, all coin types are returned.
+   * @returns Array of balance summaries (synchronous — no await needed).
+   */
+  getBalance(coinId) {
+    return this.aggregateTokens(coinId);
+  }
+  /**
+   * Get aggregated assets (tokens grouped by coinId) with price data.
+   * Includes both confirmed and unconfirmed tokens with breakdown.
    */
   async getAssets(coinId) {
+    const rawAssets = this.aggregateTokens(coinId);
+    if (!this.priceProvider || rawAssets.length === 0) {
+      return rawAssets;
+    }
+    try {
+      const registry = TokenRegistry.getInstance();
+      const nameToCoins = /* @__PURE__ */ new Map();
+      for (const asset of rawAssets) {
+        const def = registry.getDefinition(asset.coinId);
+        if (def?.name) {
+          const existing = nameToCoins.get(def.name);
+          if (existing) {
+            existing.push(asset.coinId);
+          } else {
+            nameToCoins.set(def.name, [asset.coinId]);
+          }
+        }
+      }
+      if (nameToCoins.size > 0) {
+        const tokenNames = Array.from(nameToCoins.keys());
+        const prices = await this.priceProvider.getPrices(tokenNames);
+        return rawAssets.map((raw) => {
+          const def = registry.getDefinition(raw.coinId);
+          const price = def?.name ? prices.get(def.name) : void 0;
+          let fiatValueUsd = null;
+          let fiatValueEur = null;
+          if (price) {
+            const humanAmount = Number(raw.totalAmount) / Math.pow(10, raw.decimals);
+            fiatValueUsd = humanAmount * price.priceUsd;
+            if (price.priceEur != null) {
+              fiatValueEur = humanAmount * price.priceEur;
+            }
+          }
+          return {
+            ...raw,
+            priceUsd: price?.priceUsd ?? null,
+            priceEur: price?.priceEur ?? null,
+            change24h: price?.change24h ?? null,
+            fiatValueUsd,
+            fiatValueEur
+          };
+        });
+      }
+    } catch (error) {
+      console.warn("[Payments] Failed to fetch prices, returning assets without price data:", error);
+    }
+    return rawAssets;
+  }
+  /**
+   * Aggregate tokens by coinId with confirmed/unconfirmed breakdown.
+   * Excludes tokens with status 'spent', 'invalid', or 'transferring'.
+   */
+  aggregateTokens(coinId) {
     const assetsMap = /* @__PURE__ */ new Map();
     for (const token of this.tokens.values()) {
-      if (token.status !== "confirmed") continue;
+      if (token.status === "spent" || token.status === "invalid" || token.status === "transferring") continue;
       if (coinId && token.coinId !== coinId) continue;
       const key = token.coinId;
+      const amount = BigInt(token.amount);
+      const isConfirmed = token.status === "confirmed";
       const existing = assetsMap.get(key);
       if (existing) {
-        existing.totalAmount = (BigInt(existing.totalAmount) + BigInt(token.amount)).toString();
-        existing.tokenCount++;
+        if (isConfirmed) {
+          existing.confirmedAmount += amount;
+          existing.confirmedTokenCount++;
+        } else {
+          existing.unconfirmedAmount += amount;
+          existing.unconfirmedTokenCount++;
+        }
       } else {
         assetsMap.set(key, {
           coinId: token.coinId,
@@ -4918,78 +5328,42 @@ var PaymentsModule = class _PaymentsModule {
           name: token.name,
           decimals: token.decimals,
           iconUrl: token.iconUrl,
-          totalAmount: token.amount,
-          tokenCount: 1
+          confirmedAmount: isConfirmed ? amount : 0n,
+          unconfirmedAmount: isConfirmed ? 0n : amount,
+          confirmedTokenCount: isConfirmed ? 1 : 0,
+          unconfirmedTokenCount: isConfirmed ? 0 : 1
         });
       }
     }
-    const rawAssets = Array.from(assetsMap.values());
-    let priceMap = null;
-    if (this.priceProvider && rawAssets.length > 0) {
-      try {
-        const registry = TokenRegistry.getInstance();
-        const nameToCoins = /* @__PURE__ */ new Map();
-        for (const asset of rawAssets) {
-          const def = registry.getDefinition(asset.coinId);
-          if (def?.name) {
-            const existing = nameToCoins.get(def.name);
-            if (existing) {
-              existing.push(asset.coinId);
-            } else {
-              nameToCoins.set(def.name, [asset.coinId]);
-            }
-          }
-        }
-        if (nameToCoins.size > 0) {
-          const tokenNames = Array.from(nameToCoins.keys());
-          const prices = await this.priceProvider.getPrices(tokenNames);
-          priceMap = /* @__PURE__ */ new Map();
-          for (const [name, coinIds] of nameToCoins) {
-            const price = prices.get(name);
-            if (price) {
-              for (const cid of coinIds) {
-                priceMap.set(cid, {
-                  priceUsd: price.priceUsd,
-                  priceEur: price.priceEur,
-                  change24h: price.change24h
-                });
-              }
-            }
-          }
-        }
-      } catch (error) {
-        console.warn("[Payments] Failed to fetch prices, returning assets without price data:", error);
-      }
-    }
-    return rawAssets.map((raw) => {
-      const price = priceMap?.get(raw.coinId);
-      let fiatValueUsd = null;
-      let fiatValueEur = null;
-      if (price) {
-        const humanAmount = Number(raw.totalAmount) / Math.pow(10, raw.decimals);
-        fiatValueUsd = humanAmount * price.priceUsd;
-        if (price.priceEur != null) {
-          fiatValueEur = humanAmount * price.priceEur;
-        }
-      }
+    return Array.from(assetsMap.values()).map((raw) => {
+      const totalAmount = (raw.confirmedAmount + raw.unconfirmedAmount).toString();
       return {
         coinId: raw.coinId,
         symbol: raw.symbol,
         name: raw.name,
         decimals: raw.decimals,
         iconUrl: raw.iconUrl,
-        totalAmount: raw.totalAmount,
-        tokenCount: raw.tokenCount,
-        priceUsd: price?.priceUsd ?? null,
-        priceEur: price?.priceEur ?? null,
-        change24h: price?.change24h ?? null,
-        fiatValueUsd,
-        fiatValueEur
+        totalAmount,
+        tokenCount: raw.confirmedTokenCount + raw.unconfirmedTokenCount,
+        confirmedAmount: raw.confirmedAmount.toString(),
+        unconfirmedAmount: raw.unconfirmedAmount.toString(),
+        confirmedTokenCount: raw.confirmedTokenCount,
+        unconfirmedTokenCount: raw.unconfirmedTokenCount,
+        priceUsd: null,
+        priceEur: null,
+        change24h: null,
+        fiatValueUsd: null,
+        fiatValueEur: null
       };
     });
   }
   /**
-   * Get all tokens
+   * Get all tokens, optionally filtered by coin type and/or status.
+   *
+   * @param filter - Optional filter criteria.
+   * @param filter.coinId - Return only tokens of this coin type.
+   * @param filter.status - Return only tokens with this status (e.g. `'submitted'` for unconfirmed).
+   * @returns Array of matching {@link Token} objects (synchronous).
    */
   getTokens(filter) {
     let tokens = Array.from(this.tokens.values());
@@ -5002,19 +5376,327 @@ var PaymentsModule = class _PaymentsModule {
     return tokens;
   }
   /**
-   * Get single token
+   * Get a single token by its local ID.
+   *
+   * @param id - The local UUID assigned when the token was added.
+   * @returns The token, or `undefined` if not found.
    */
   getToken(id) {
     return this.tokens.get(id);
   }
   // ===========================================================================
+  // Public API - Unconfirmed Token Resolution
+  // ===========================================================================
+  /**
+   * Attempt to resolve unconfirmed (status `'submitted'`) tokens by acquiring
+   * their missing aggregator proofs.
+   *
+   * Each unconfirmed V5 token progresses through stages:
+   * `RECEIVED` → `MINT_SUBMITTED` → `MINT_PROVEN` → `TRANSFER_SUBMITTED` → `FINALIZED`
+   *
+   * Uses 500 ms quick-timeouts per proof check so the call returns quickly even
+   * when proofs are not yet available. Tokens that exceed 50 failed attempts are
+   * marked `'invalid'`.
+   *
+   * Automatically called (fire-and-forget) by {@link load}.
+   *
+   * @returns Summary with counts of resolved, still-pending, and failed tokens plus per-token details.
+   */
+  async resolveUnconfirmed() {
+    this.ensureInitialized();
+    const result = {
+      resolved: 0,
+      stillPending: 0,
+      failed: 0,
+      details: []
+    };
+    const stClient = this.deps.oracle.getStateTransitionClient?.();
+    const trustBase = this.deps.oracle.getTrustBase?.();
+    if (!stClient || !trustBase) return result;
+    const signingService = await this.createSigningService();
+    for (const [tokenId, token] of this.tokens) {
+      if (token.status !== "submitted") continue;
+      const pending2 = this.parsePendingFinalization(token.sdkData);
+      if (!pending2) {
+        result.stillPending++;
+        continue;
+      }
+      if (pending2.type === "v5_bundle") {
+        const progress = await this.resolveV5Token(tokenId, token, pending2, stClient, trustBase, signingService);
+        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) {
+      await this.save();
+    }
+    return result;
+  }
+  // ===========================================================================
+  // Private - V5 Lazy Resolution Helpers
+  // ===========================================================================
+  /**
+   * Process a single V5 token through its finalization stages with quick-timeout proof checks.
+   */
+  async resolveV5Token(tokenId, token, pending2, stClient, trustBase, signingService) {
+    const bundle = JSON.parse(pending2.bundleJson);
+    pending2.attemptCount++;
+    pending2.lastAttemptAt = Date.now();
+    try {
+      if (pending2.stage === "RECEIVED") {
+        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);
+        if (mintResponse.status !== "SUCCESS" && mintResponse.status !== "REQUEST_ID_EXISTS") {
+          throw new Error(`Mint submission failed: ${mintResponse.status}`);
+        }
+        pending2.stage = "MINT_SUBMITTED";
+        this.updatePendingFinalization(token, pending2);
+      }
+      if (pending2.stage === "MINT_SUBMITTED") {
+        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) {
+          this.updatePendingFinalization(token, pending2);
+          return "pending";
+        }
+        pending2.mintProofJson = JSON.stringify(proof);
+        pending2.stage = "MINT_PROVEN";
+        this.updatePendingFinalization(token, pending2);
+      }
+      if (pending2.stage === "MINT_PROVEN") {
+        const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
+        const transferCommitment = await import_TransferCommitment4.TransferCommitment.fromJSON(transferCommitmentJson);
+        const transferResponse = await stClient.submitTransferCommitment(transferCommitment);
+        if (transferResponse.status !== "SUCCESS" && transferResponse.status !== "REQUEST_ID_EXISTS") {
+          throw new Error(`Transfer submission failed: ${transferResponse.status}`);
+        }
+        pending2.stage = "TRANSFER_SUBMITTED";
+        this.updatePendingFinalization(token, pending2);
+      }
+      if (pending2.stage === "TRANSFER_SUBMITTED") {
+        const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
+        const transferCommitment = await import_TransferCommitment4.TransferCommitment.fromJSON(transferCommitmentJson);
+        const proof = await this.quickProofCheck(stClient, trustBase, transferCommitment);
+        if (!proof) {
+          this.updatePendingFinalization(token, pending2);
+          return "pending";
+        }
+        const finalizedToken = await this.finalizeFromV5Bundle(bundle, pending2, signingService, stClient, trustBase);
+        const confirmedToken = {
+          id: token.id,
+          coinId: token.coinId,
+          symbol: token.symbol,
+          name: token.name,
+          decimals: token.decimals,
+          iconUrl: token.iconUrl,
+          amount: token.amount,
+          status: "confirmed",
+          createdAt: token.createdAt,
+          updatedAt: Date.now(),
+          sdkData: JSON.stringify(finalizedToken.toJSON())
+        };
+        this.tokens.set(tokenId, confirmedToken);
+        await this.saveTokenToFileStorage(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";
+      }
+      return "pending";
+    } catch (error) {
+      console.error(`[Payments] resolveV5Token failed for ${tokenId.slice(0, 8)}:`, error);
+      if (pending2.attemptCount > 50) {
+        token.status = "invalid";
+        token.updatedAt = Date.now();
+        this.tokens.set(tokenId, token);
+        return "failed";
+      }
+      this.updatePendingFinalization(token, pending2);
+      return "pending";
+    }
+  }
+  /**
+   * Non-blocking proof check with 500ms timeout.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async quickProofCheck(stClient, trustBase, commitment, timeoutMs = 500) {
+    try {
+      const proof = await Promise.race([
+        (0, import_InclusionProofUtils5.waitInclusionProof)(trustBase, stClient, commitment),
+        new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs))
+      ]);
+      return proof;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Perform V5 bundle finalization from stored bundle data and proofs.
+   * Extracted from InstantSplitProcessor.processV5Bundle() steps 4-10.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async finalizeFromV5Bundle(bundle, pending2, signingService, stClient, trustBase) {
+    const mintDataJson = JSON.parse(bundle.recipientMintData);
+    const mintData = await import_MintTransactionData3.MintTransactionData.fromJSON(mintDataJson);
+    const mintCommitment = await import_MintCommitment3.MintCommitment.create(mintData);
+    const mintProofJson = JSON.parse(pending2.mintProofJson);
+    const mintProof = import_InclusionProof.InclusionProof.fromJSON(mintProofJson);
+    const mintTransaction = mintCommitment.toTransaction(mintProof);
+    const tokenType = new import_TokenType3.TokenType(fromHex4(bundle.tokenTypeHex));
+    const senderMintedStateJson = JSON.parse(bundle.mintedTokenStateJson);
+    const tokenJson = {
+      version: "2.0",
+      state: senderMintedStateJson,
+      genesis: mintTransaction.toJSON(),
+      transactions: [],
+      nametags: []
+    };
+    const mintedToken = await import_Token6.Token.fromJSON(tokenJson);
+    const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
+    const transferCommitment = await import_TransferCommitment4.TransferCommitment.fromJSON(transferCommitmentJson);
+    const transferProof = await (0, import_InclusionProofUtils5.waitInclusionProof)(trustBase, stClient, transferCommitment);
+    const transferTransaction = transferCommitment.toTransaction(transferProof);
+    const transferSalt = fromHex4(bundle.transferSaltHex);
+    const recipientPredicate = await import_UnmaskedPredicate5.UnmaskedPredicate.create(
+      mintData.tokenId,
+      tokenType,
+      signingService,
+      import_HashAlgorithm5.HashAlgorithm.SHA256,
+      transferSalt
+    );
+    const recipientState = new import_TokenState5.TokenState(recipientPredicate, null);
+    let nametagTokens = [];
+    const recipientAddressStr = bundle.recipientAddressJson;
+    if (recipientAddressStr.startsWith("PROXY://")) {
+      if (bundle.nametagTokenJson) {
+        try {
+          const nametagToken = await import_Token6.Token.fromJSON(JSON.parse(bundle.nametagTokenJson));
+          const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
+          const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
+          if (proxy.address === recipientAddressStr) {
+            nametagTokens = [nametagToken];
+          }
+        } catch {
+        }
+      }
+      if (nametagTokens.length === 0 && this.nametag?.token) {
+        try {
+          const nametagToken = await import_Token6.Token.fromJSON(this.nametag.token);
+          const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
+          const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
+          if (proxy.address === recipientAddressStr) {
+            nametagTokens = [nametagToken];
+          }
+        } catch {
+        }
+      }
+    }
+    return stClient.finalizeTransaction(trustBase, mintedToken, recipientState, transferTransaction, nametagTokens);
+  }
+  /**
+   * Parse pending finalization metadata from token's sdkData.
+   */
+  parsePendingFinalization(sdkData) {
+    if (!sdkData) return null;
+    try {
+      const data = JSON.parse(sdkData);
+      if (data._pendingFinalization && data._pendingFinalization.type === "v5_bundle") {
+        return data._pendingFinalization;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Update pending finalization metadata in token's sdkData.
+   * Creates a new token object since sdkData is readonly.
+   */
+  updatePendingFinalization(token, pending2) {
+    const updated = {
+      id: token.id,
+      coinId: token.coinId,
+      symbol: token.symbol,
+      name: token.name,
+      decimals: token.decimals,
+      iconUrl: token.iconUrl,
+      amount: token.amount,
+      status: token.status,
+      createdAt: token.createdAt,
+      updatedAt: Date.now(),
+      sdkData: JSON.stringify({ _pendingFinalization: pending2 })
+    };
+    this.tokens.set(token.id, updated);
+  }
+  /**
+   * Save pending V5 tokens to key-value storage.
+   * These tokens can't be serialized to TXF format (no genesis/state),
+   * so we persist them separately and restore on load().
+   */
+  async savePendingV5Tokens() {
+    const pendingTokens = [];
+    for (const token of this.tokens.values()) {
+      if (this.parsePendingFinalization(token.sdkData)) {
+        pendingTokens.push(token);
+      }
+    }
+    if (pendingTokens.length > 0) {
+      await this.deps.storage.set(
+        STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS,
+        JSON.stringify(pendingTokens)
+      );
+    } else {
+      await this.deps.storage.set(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS, "");
+    }
+  }
+  /**
+   * Load pending V5 tokens from key-value storage and merge into tokens map.
+   * Called during load() to restore tokens that TXF format can't represent.
+   */
+  async loadPendingV5Tokens() {
+    const data = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS);
+    if (!data) return;
+    try {
+      const pendingTokens = JSON.parse(data);
+      for (const token of pendingTokens) {
+        if (!this.tokens.has(token.id)) {
+          this.tokens.set(token.id, token);
+        }
+      }
+      if (pendingTokens.length > 0) {
+        this.log(`Restored ${pendingTokens.length} pending V5 token(s)`);
+      }
+    } catch {
+    }
+  }
+  // ===========================================================================
   // Public API - Token Operations
   // ===========================================================================
   /**
-   * Add a token
-   * Tokens are uniquely identified by (tokenId, stateHash) composite key.
-   * Multiple historic states of the same token can coexist.
-   * @returns false if exact duplicate (same tokenId AND same stateHash)
+   * Add a token to the wallet.
+   *
+   * Tokens are uniquely identified by a `(tokenId, stateHash)` composite key.
+   * Duplicate detection:
+   * - **Tombstoned** — rejected if the exact `(tokenId, stateHash)` pair has a tombstone.
+   * - **Exact duplicate** — rejected if a token with the same composite key already exists.
+   * - **State replacement** — if the same `tokenId` exists with a *different* `stateHash`,
+   *   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) {
     this.ensureInitialized();
@@ -5072,7 +5754,9 @@ var PaymentsModule = class _PaymentsModule {
       });
     }
     await this.save();
-    await this.saveTokenToFileStorage(token);
+    if (!this.parsePendingFinalization(token.sdkData)) {
+      await this.saveTokenToFileStorage(token);
+    }
     this.log(`Added token ${token.id}, total: ${this.tokens.size}`);
     return true;
   }
@@ -5129,6 +5813,9 @@ var PaymentsModule = class _PaymentsModule {
             const data = fileData;
             const tokenJson = data.token;
             if (!tokenJson) continue;
+            if (typeof tokenJson === "object" && tokenJson !== null && "_pendingFinalization" in tokenJson) {
+              continue;
+            }
             let sdkTokenId;
             if (typeof tokenJson === "object" && tokenJson !== null) {
               const tokenObj = tokenJson;
@@ -5180,7 +5867,12 @@ var PaymentsModule = class _PaymentsModule {
     this.log(`Loaded ${this.tokens.size} tokens from file storage`);
   }
   /**
-   * Update an existing token
+   * Update an existing token or add it if not found.
+   *
+   * Looks up the token by genesis `tokenId` (from `sdkData`) first, then by
+   * `token.id`. If no match is found, falls back to {@link addToken}.
+   *
+   * @param token - The token with updated data. Must include a valid `id`.
    */
   async updateToken(token) {
     this.ensureInitialized();
@@ -5204,7 +5896,15 @@ var PaymentsModule = class _PaymentsModule {
     this.log(`Updated token ${token.id}`);
   }
   /**
-   * Remove a token by ID
+   * Remove a token from the wallet.
+   *
+   * The token is archived first, then a tombstone `(tokenId, stateHash)` is
+   * created to prevent re-addition via Nostr re-delivery. A `SENT` history
+   * 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) {
     this.ensureInitialized();
@@ -5266,13 +5966,22 @@ var PaymentsModule = class _PaymentsModule {
   // Public API - Tombstones
   // ===========================================================================
   /**
-   * Get all tombstones
+   * Get all tombstone entries.
+   *
+   * Each tombstone is keyed by `(tokenId, stateHash)` and prevents a spent
+   * token state from being re-added (e.g. via Nostr re-delivery).
+   *
+   * @returns A shallow copy of the tombstone array.
    */
   getTombstones() {
     return [...this.tombstones];
   }
   /**
-   * Check if token state is tombstoned
+   * Check whether a specific `(tokenId, stateHash)` combination is tombstoned.
+   *
+   * @param tokenId - The genesis token ID.
+   * @param stateHash - The state hash of the token version to check.
+   * @returns `true` if the exact combination has been tombstoned.
    */
   isStateTombstoned(tokenId, stateHash) {
     return this.tombstones.some(
@@ -5280,8 +5989,13 @@ var PaymentsModule = class _PaymentsModule {
     );
   }
   /**
-   * Merge remote tombstones
-   * @returns number of local tokens removed
+   * Merge tombstones received from a remote sync source.
+   *
+   * Any local token whose `(tokenId, stateHash)` matches a remote tombstone is
+   * removed. The remote tombstones are then added to the local set (union merge).
+   *
+   * @param remoteTombstones - Tombstone entries from the remote source.
+   * @returns Number of local tokens that were removed.
    */
   async mergeTombstones(remoteTombstones) {
     this.ensureInitialized();
@@ -5317,7 +6031,9 @@ var PaymentsModule = class _PaymentsModule {
     return removedCount;
   }
   /**
-   * Prune old tombstones
+   * Remove tombstones older than `maxAge` and cap the list at 100 entries.
+   *
+   * @param maxAge - Maximum age in milliseconds (default: 30 days).
    */
   async pruneTombstones(maxAge) {
     const originalCount = this.tombstones.length;
@@ -5331,20 +6047,38 @@ var PaymentsModule = class _PaymentsModule {
   // Public API - Archives
   // ===========================================================================
   /**
-   * Get archived tokens
+   * Get all archived (spent/superseded) tokens in TXF format.
+   *
+   * Archived tokens are kept for recovery and sync purposes. The map key is
+   * the genesis token ID.
+   *
+   * @returns A shallow copy of the archived token map.
    */
   getArchivedTokens() {
     return new Map(this.archivedTokens);
   }
   /**
-   * Get best archived version of a token
+   * Get the best (most committed transactions) archived version of a token.
+   *
+   * Searches both archived and forked token maps and returns the version with
+   * the highest number of committed transactions.
+   *
+   * @param tokenId - The genesis token ID to look up.
+   * @returns The best TXF token version, or `null` if not found.
    */
   getBestArchivedVersion(tokenId) {
     return findBestTokenVersion(tokenId, this.archivedTokens, this.forkedTokens);
   }
   /**
-   * Merge remote archived tokens
-   * @returns number of tokens updated/added
+   * Merge archived tokens from a remote sync source.
+   *
+   * For each remote token:
+   * - If missing locally, it is added.
+   * - If the remote version is an incremental update of the local, it replaces it.
+   * - If the histories diverge (fork), the remote version is stored via {@link storeForkedToken}.
+   *
+   * @param remoteArchived - Map of genesis token ID → TXF token from remote.
+   * @returns Number of tokens that were updated or added locally.
    */
   async mergeArchivedTokens(remoteArchived) {
     let mergedCount = 0;
@@ -5367,7 +6101,11 @@ var PaymentsModule = class _PaymentsModule {
     return mergedCount;
   }
   /**
-   * Prune archived tokens
+   * Prune archived tokens to keep at most `maxCount` entries.
+   *
+   * Oldest entries (by insertion order) are removed first.
+   *
+   * @param maxCount - Maximum number of archived tokens to retain (default: 100).
    */
   async pruneArchivedTokens(maxCount = 100) {
     if (this.archivedTokens.size <= maxCount) return;
@@ -5380,13 +6118,24 @@ var PaymentsModule = class _PaymentsModule {
   // Public API - Forked Tokens
   // ===========================================================================
   /**
-   * Get forked tokens
+   * Get all forked token versions.
+   *
+   * Forked tokens represent alternative histories detected during sync.
+   * The map key is `{tokenId}_{stateHash}`.
+   *
+   * @returns A shallow copy of the forked tokens map.
    */
   getForkedTokens() {
     return new Map(this.forkedTokens);
   }
   /**
-   * Store a forked token
+   * Store a forked token version (alternative history).
+   *
+   * No-op if the exact `(tokenId, stateHash)` key already exists.
+   *
+   * @param tokenId - Genesis token ID.
+   * @param stateHash - State hash of this forked version.
+   * @param txfToken - The TXF token data to store.
    */
   async storeForkedToken(tokenId, stateHash, txfToken) {
     const key = `${tokenId}_${stateHash}`;
@@ -5396,8 +6145,10 @@ var PaymentsModule = class _PaymentsModule {
     await this.save();
   }
   /**
-   * Merge remote forked tokens
-   * @returns number of tokens added
+   * Merge forked tokens from a remote sync source. Only new keys are added.
+   *
+   * @param remoteForked - Map of `{tokenId}_{stateHash}` → TXF token from remote.
+   * @returns Number of new forked tokens added.
    */
   async mergeForkedTokens(remoteForked) {
     let addedCount = 0;
@@ -5413,7 +6164,9 @@ var PaymentsModule = class _PaymentsModule {
     return addedCount;
   }
   /**
-   * Prune forked tokens
+   * Prune forked tokens to keep at most `maxCount` entries.
+   *
+   * @param maxCount - Maximum number of forked tokens to retain (default: 50).
    */
   async pruneForkedTokens(maxCount = 50) {
     if (this.forkedTokens.size <= maxCount) return;
@@ -5426,13 +6179,19 @@ var PaymentsModule = class _PaymentsModule {
   // Public API - Transaction History
   // ===========================================================================
   /**
-   * Get transaction history
+   * Get the transaction history sorted newest-first.
+   *
+   * @returns Array of {@link TransactionHistoryEntry} objects in descending timestamp order.
    */
   getHistory() {
     return [...this.transactionHistory].sort((a, b) => b.timestamp - a.timestamp);
   }
   /**
-   * Add to transaction history
+   * Append an entry to the transaction history.
+   *
+   * A unique `id` is auto-generated. The entry is immediately persisted to storage.
+   *
+   * @param entry - History entry fields (without `id`).
    */
   async addToHistory(entry) {
     this.ensureInitialized();
@@ -5450,7 +6209,11 @@ var PaymentsModule = class _PaymentsModule {
   // Public API - Nametag
   // ===========================================================================
   /**
-   * Set nametag for current identity
+   * Set the nametag data for the current identity.
+   *
+   * Persists to both key-value storage and file storage (lottery compatibility).
+   *
+   * @param nametag - The nametag data including minted token JSON.
    */
   async setNametag(nametag) {
     this.ensureInitialized();
@@ -5460,19 +6223,23 @@ var PaymentsModule = class _PaymentsModule {
     this.log(`Nametag set: ${nametag.name}`);
   }
   /**
-   * Get nametag
+   * Get the current nametag data.
+   *
+   * @returns The nametag data, or `null` if no nametag is set.
    */
   getNametag() {
     return this.nametag;
   }
   /**
-   * Check if has nametag
+   * Check whether a nametag is currently set.
+   *
+   * @returns `true` if nametag data is present.
    */
   hasNametag() {
     return this.nametag !== null;
   }
   /**
-   * Clear nametag
+   * Remove the current nametag data from memory and storage.
    */
   async clearNametag() {
     this.ensureInitialized();
@@ -5566,9 +6333,9 @@ var PaymentsModule = class _PaymentsModule {
     try {
       const signingService = await this.createSigningService();
       const { UnmaskedPredicateReference: UnmaskedPredicateReference4 } = await import("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
-      const { TokenType: TokenType5 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+      const { TokenType: TokenType6 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenType");
       const UNICITY_TOKEN_TYPE_HEX3 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
-      const tokenType = new TokenType5(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
+      const tokenType = new TokenType6(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
       const addressRef = await UnmaskedPredicateReference4.create(
         tokenType,
         signingService.algorithm,
@@ -5629,11 +6396,27 @@ var PaymentsModule = class _PaymentsModule {
   // Public API - Sync & Validate
   // ===========================================================================
   /**
-   * Sync with all token storage providers (IPFS, MongoDB, etc.)
-   * Syncs with each provider and merges results
+   * Sync local token state with all configured token storage providers (IPFS, file, etc.).
+   *
+   * For each provider, the local data is packaged into TXF storage format, sent
+   * to the provider's `sync()` method, and the merged result is applied locally.
+   * Emits `sync:started`, `sync:completed`, and `sync:error` events.
+   *
+   * @returns Summary with counts of tokens added and removed during sync.
    */
   async sync() {
     this.ensureInitialized();
+    if (this._syncInProgress) {
+      return this._syncInProgress;
+    }
+    this._syncInProgress = this._doSync();
+    try {
+      return await this._syncInProgress;
+    } finally {
+      this._syncInProgress = null;
+    }
+  }
+  async _doSync() {
     this.deps.emitEvent("sync:started", { source: "payments" });
     try {
       const providers = this.getTokenStorageProviders();
@@ -5671,6 +6454,9 @@ var PaymentsModule = class _PaymentsModule {
           });
         }
       }
+      if (totalAdded > 0 || totalRemoved > 0) {
+        await this.save();
+      }
       this.deps.emitEvent("sync:completed", {
         source: "payments",
         count: this.tokens.size
@@ -5684,6 +6470,66 @@ var PaymentsModule = class _PaymentsModule {
       throw error;
     }
   }
+  // ===========================================================================
+  // Storage Event Subscription (Push-Based Sync)
+  // ===========================================================================
+  /**
+   * Subscribe to 'storage:remote-updated' events from all token storage providers.
+   * When a provider emits this event, a debounced sync is triggered.
+   */
+  subscribeToStorageEvents() {
+    this.unsubscribeStorageEvents();
+    const providers = this.getTokenStorageProviders();
+    for (const [providerId, provider] of providers) {
+      if (provider.onEvent) {
+        const unsub = provider.onEvent((event) => {
+          if (event.type === "storage:remote-updated") {
+            this.log("Remote update detected from provider", providerId, event.data);
+            this.debouncedSyncFromRemoteUpdate(providerId, event.data);
+          }
+        });
+        this.storageEventUnsubscribers.push(unsub);
+      }
+    }
+  }
+  /**
+   * Unsubscribe from all storage provider events and clear debounce timer.
+   */
+  unsubscribeStorageEvents() {
+    for (const unsub of this.storageEventUnsubscribers) {
+      unsub();
+    }
+    this.storageEventUnsubscribers = [];
+    if (this.syncDebounceTimer) {
+      clearTimeout(this.syncDebounceTimer);
+      this.syncDebounceTimer = null;
+    }
+  }
+  /**
+   * Debounced sync triggered by a storage:remote-updated event.
+   * Waits 500ms to batch rapid updates, then performs sync.
+   */
+  debouncedSyncFromRemoteUpdate(providerId, eventData) {
+    if (this.syncDebounceTimer) {
+      clearTimeout(this.syncDebounceTimer);
+    }
+    this.syncDebounceTimer = setTimeout(() => {
+      this.syncDebounceTimer = null;
+      this.sync().then((result) => {
+        const data = eventData;
+        this.deps?.emitEvent("sync:remote-update", {
+          providerId,
+          name: data?.name ?? "",
+          sequence: data?.sequence ?? 0,
+          cid: data?.cid ?? "",
+          added: result.added,
+          removed: result.removed
+        });
+      }).catch((err) => {
+        this.log("Auto-sync from remote update failed:", err);
+      });
+    }, _PaymentsModule.SYNC_DEBOUNCE_MS);
+  }
   /**
    * Get all active token storage providers
    */
@@ -5699,15 +6545,24 @@ var PaymentsModule = class _PaymentsModule {
     return /* @__PURE__ */ new Map();
   }
   /**
-   * Update token storage providers (called when providers are added/removed dynamically)
+   * Replace the set of token storage providers at runtime.
+   *
+   * Use when providers are added or removed dynamically (e.g. IPFS node started).
+   *
+   * @param providers - New map of provider ID → TokenStorageProvider.
    */
   updateTokenStorageProviders(providers) {
     if (this.deps) {
       this.deps.tokenStorageProviders = providers;
+      this.subscribeToStorageEvents();
     }
   }
   /**
-   * Validate tokens with aggregator
+   * Validate all tokens against the aggregator (oracle provider).
+   *
+   * Tokens that fail validation or are detected as spent are marked `'invalid'`.
+   *
+   * @returns Object with arrays of valid and invalid tokens.
    */
   async validate() {
     this.ensureInitialized();
@@ -5728,7 +6583,9 @@ var PaymentsModule = class _PaymentsModule {
     return { valid, invalid };
   }
   /**
-   * Get pending transfers
+   * Get all in-progress (pending) outgoing transfers.
+   *
+   * @returns Array of {@link TransferResult} objects for transfers that have not yet completed.
    */
   getPendingTransfers() {
     return Array.from(this.pendingTransfers.values());
@@ -5792,9 +6649,9 @@ var PaymentsModule = class _PaymentsModule {
    */
   async createDirectAddressFromPubkey(pubkeyHex) {
     const { UnmaskedPredicateReference: UnmaskedPredicateReference4 } = await import("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
-    const { TokenType: TokenType5 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+    const { TokenType: TokenType6 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenType");
     const UNICITY_TOKEN_TYPE_HEX3 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
-    const tokenType = new TokenType5(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
+    const tokenType = new TokenType6(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
     const pubkeyBytes = new Uint8Array(
       pubkeyHex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16))
     );
@@ -6006,7 +6863,8 @@ var PaymentsModule = class _PaymentsModule {
       this.deps.emitEvent("transfer:confirmed", {
         id: crypto.randomUUID(),
         status: "completed",
-        tokens: [finalizedToken]
+        tokens: [finalizedToken],
+        tokenTransfers: []
       });
       await this.addToHistory({
         type: "RECEIVED",
@@ -6029,14 +6887,26 @@ var PaymentsModule = class _PaymentsModule {
   async handleIncomingTransfer(transfer) {
     try {
       const payload = transfer.payload;
+      let instantBundle = null;
       if (isInstantSplitBundle(payload)) {
+        instantBundle = payload;
+      } else if (payload.token) {
+        try {
+          const inner = typeof payload.token === "string" ? JSON.parse(payload.token) : payload.token;
+          if (isInstantSplitBundle(inner)) {
+            instantBundle = inner;
+          }
+        } catch {
+        }
+      }
+      if (instantBundle) {
         this.log("Processing INSTANT_SPLIT bundle...");
         try {
           if (!this.nametag) {
             await this.loadNametagFromFileStorage();
           }
           const result = await this.processInstantSplitBundle(
-            payload,
+            instantBundle,
             transfer.senderTransportPubkey
           );
           if (result.success) {
@@ -6049,6 +6919,11 @@ var PaymentsModule = class _PaymentsModule {
         }
         return;
       }
+      if (payload.sourceToken && payload.commitmentData && !payload.transferTx) {
+        this.log("Processing NOSTR-FIRST commitment-only transfer...");
+        await this.handleCommitmentOnlyTransfer(transfer, payload);
+        return;
+      }
       let tokenData;
       let finalizedSdkToken = null;
       if (payload.sourceToken && payload.transferTx) {
@@ -6204,6 +7079,7 @@ var PaymentsModule = class _PaymentsModule {
         console.error(`[Payments] Failed to save to provider ${id}:`, err);
       }
     }
+    await this.savePendingV5Tokens();
   }
   async saveToOutbox(transfer, recipient) {
     const outbox = await this.loadOutbox();
@@ -6221,8 +7097,7 @@ var PaymentsModule = class _PaymentsModule {
   }
   async createStorageData() {
     return await buildTxfStorageData(
-      [],
-      // Empty - active tokens stored as token-xxx files
+      Array.from(this.tokens.values()),
       {
         version: 1,
         address: this.deps.identity.l1Address,
@@ -6407,7 +7282,7 @@ function createPaymentsModule(config) {
 // modules/payments/TokenRecoveryService.ts
 var import_TokenId4 = require("@unicitylabs/state-transition-sdk/lib/token/TokenId");
 var import_TokenState6 = require("@unicitylabs/state-transition-sdk/lib/token/TokenState");
-var import_TokenType3 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+var import_TokenType4 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
 var import_CoinId5 = require("@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId");
 var import_HashAlgorithm6 = require("@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm");
 var import_UnmaskedPredicate6 = require("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate");
@@ -7556,15 +8431,20 @@ async function parseAndDecryptWalletDat(data, password, onProgress) {
 
 // core/Sphere.ts
 var import_SigningService2 = require("@unicitylabs/state-transition-sdk/lib/sign/SigningService");
-var import_TokenType4 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+var import_TokenType5 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
 var import_HashAlgorithm7 = require("@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm");
 var import_UnmaskedPredicateReference3 = require("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
+var import_nostr_js_sdk2 = require("@unicitylabs/nostr-js-sdk");
+function isValidNametag(nametag) {
+  if ((0, import_nostr_js_sdk2.isPhoneNumber)(nametag)) return true;
+  return /^[a-z0-9_-]{3,20}$/.test(nametag);
+}
 var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
 async function deriveL3PredicateAddress(privateKey) {
   const secret = Buffer.from(privateKey, "hex");
   const signingService = await import_SigningService2.SigningService.createFromSecret(secret);
   const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
-  const tokenType = new import_TokenType4.TokenType(tokenTypeBytes);
+  const tokenType = new import_TokenType5.TokenType(tokenTypeBytes);
   const predicateRef = import_UnmaskedPredicateReference3.UnmaskedPredicateReference.create(
     tokenType,
     signingService.algorithm,
@@ -7730,8 +8610,8 @@ var Sphere = class _Sphere {
     if (options.nametag) {
       await sphere.registerNametag(options.nametag);
     } else {
-      await sphere.syncIdentityWithTransport();
       await sphere.recoverNametagFromTransport();
+      await sphere.syncIdentityWithTransport();
     }
     return sphere;
   }
@@ -7778,9 +8658,14 @@ var Sphere = class _Sphere {
     if (!options.mnemonic && !options.masterKey) {
       throw new Error("Either mnemonic or masterKey is required");
     }
+    console.log("[Sphere.import] Starting import...");
+    console.log("[Sphere.import] Clearing existing wallet data...");
     await _Sphere.clear({ storage: options.storage, tokenStorage: options.tokenStorage });
+    console.log("[Sphere.import] Clear done");
     if (!options.storage.isConnected()) {
+      console.log("[Sphere.import] Reconnecting storage...");
       await options.storage.connect();
+      console.log("[Sphere.import] Storage reconnected");
     }
     const sphere = new _Sphere(
       options.storage,
@@ -7794,9 +8679,12 @@ var Sphere = class _Sphere {
       if (!_Sphere.validateMnemonic(options.mnemonic)) {
         throw new Error("Invalid mnemonic");
       }
+      console.log("[Sphere.import] Storing mnemonic...");
       await sphere.storeMnemonic(options.mnemonic, options.derivationPath, options.basePath);
+      console.log("[Sphere.import] Initializing identity from mnemonic...");
       await sphere.initializeIdentityFromMnemonic(options.mnemonic, options.derivationPath);
     } else if (options.masterKey) {
+      console.log("[Sphere.import] Storing master key...");
       await sphere.storeMasterKey(
         options.masterKey,
         options.chainCode,
@@ -7804,24 +8692,43 @@ var Sphere = class _Sphere {
         options.basePath,
         options.derivationMode
       );
+      console.log("[Sphere.import] Initializing identity from master key...");
       await sphere.initializeIdentityFromMasterKey(
         options.masterKey,
         options.chainCode,
         options.derivationPath
       );
     }
+    console.log("[Sphere.import] Initializing providers...");
     await sphere.initializeProviders();
+    console.log("[Sphere.import] Providers initialized. Initializing modules...");
     await sphere.initializeModules();
+    console.log("[Sphere.import] Modules initialized");
     if (!options.nametag) {
+      console.log("[Sphere.import] Recovering nametag from transport...");
       await sphere.recoverNametagFromTransport();
+      console.log("[Sphere.import] Nametag recovery done");
+      await sphere.syncIdentityWithTransport();
     }
+    console.log("[Sphere.import] Finalizing wallet creation...");
     await sphere.finalizeWalletCreation();
     sphere._initialized = true;
     _Sphere.instance = sphere;
+    console.log("[Sphere.import] Tracking address 0...");
     await sphere.ensureAddressTracked(0);
     if (options.nametag) {
+      console.log("[Sphere.import] Registering nametag...");
       await sphere.registerNametag(options.nametag);
     }
+    if (sphere._tokenStorageProviders.size > 0) {
+      try {
+        const syncResult = await sphere._payments.sync();
+        console.log(`[Sphere.import] Auto-sync: +${syncResult.added} -${syncResult.removed}`);
+      } catch (err) {
+        console.warn("[Sphere.import] Auto-sync failed (non-fatal):", err);
+      }
+    }
+    console.log("[Sphere.import] Import complete");
     return sphere;
   }
   /**
@@ -7846,6 +8753,10 @@ var Sphere = class _Sphere {
   static async clear(storageOrOptions) {
     const storage = "get" in storageOrOptions ? storageOrOptions : storageOrOptions.storage;
     const tokenStorage = "get" in storageOrOptions ? void 0 : storageOrOptions.tokenStorage;
+    if (!storage.isConnected()) {
+      await storage.connect();
+    }
+    console.log("[Sphere.clear] Removing storage keys...");
     await storage.remove(STORAGE_KEYS_GLOBAL.MNEMONIC);
     await storage.remove(STORAGE_KEYS_GLOBAL.MASTER_KEY);
     await storage.remove(STORAGE_KEYS_GLOBAL.CHAIN_CODE);
@@ -7858,12 +8769,30 @@ var Sphere = class _Sphere {
     await storage.remove(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS);
     await storage.remove(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
     await storage.remove(STORAGE_KEYS_ADDRESS.OUTBOX);
+    console.log("[Sphere.clear] Storage keys removed");
     if (tokenStorage?.clear) {
-      await tokenStorage.clear();
+      console.log("[Sphere.clear] Clearing token storage...");
+      try {
+        await Promise.race([
+          tokenStorage.clear(),
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error("tokenStorage.clear() timed out after 2s")), 2e3)
+          )
+        ]);
+        console.log("[Sphere.clear] Token storage cleared");
+      } catch (err) {
+        console.warn("[Sphere.clear] Token storage clear failed/timed out:", err);
+      }
     }
+    console.log("[Sphere.clear] Destroying vesting classifier...");
     await vestingClassifier.destroy();
+    console.log("[Sphere.clear] Vesting classifier destroyed");
     if (_Sphere.instance) {
+      console.log("[Sphere.clear] Destroying Sphere instance...");
       await _Sphere.instance.destroy();
+      console.log("[Sphere.clear] Sphere instance destroyed");
+    } else {
+      console.log("[Sphere.clear] No Sphere instance to destroy");
     }
   }
   /**
@@ -8244,7 +9173,8 @@ var Sphere = class _Sphere {
           storage: options.storage,
           transport: options.transport,
           oracle: options.oracle,
-          tokenStorage: options.tokenStorage
+          tokenStorage: options.tokenStorage,
+          l1: options.l1
         });
         return { success: true, mnemonic };
       }
@@ -8257,7 +9187,8 @@ var Sphere = class _Sphere {
           storage: options.storage,
           transport: options.transport,
           oracle: options.oracle,
-          tokenStorage: options.tokenStorage
+          tokenStorage: options.tokenStorage,
+          l1: options.l1
         });
         return { success: true };
       }
@@ -8316,7 +9247,8 @@ var Sphere = class _Sphere {
         transport: options.transport,
         oracle: options.oracle,
         tokenStorage: options.tokenStorage,
-        nametag: options.nametag
+        nametag: options.nametag,
+        l1: options.l1
       });
       return { success: true, sphere, mnemonic };
     }
@@ -8345,7 +9277,8 @@ var Sphere = class _Sphere {
         transport: options.transport,
         oracle: options.oracle,
         tokenStorage: options.tokenStorage,
-        nametag: options.nametag
+        nametag: options.nametag,
+        l1: options.l1
       });
       return { success: true, sphere };
     }
@@ -8376,7 +9309,8 @@ var Sphere = class _Sphere {
         transport: options.transport,
         oracle: options.oracle,
         tokenStorage: options.tokenStorage,
-        nametag: options.nametag
+        nametag: options.nametag,
+        l1: options.l1
       });
       return { success: true, sphere };
     }
@@ -8395,7 +9329,8 @@ var Sphere = class _Sphere {
           storage: options.storage,
           transport: options.transport,
           oracle: options.oracle,
-          tokenStorage: options.tokenStorage
+          tokenStorage: options.tokenStorage,
+          l1: options.l1
         });
         if (result.success) {
           const sphere2 = _Sphere.getInstance();
@@ -8444,7 +9379,8 @@ var Sphere = class _Sphere {
           transport: options.transport,
           oracle: options.oracle,
           tokenStorage: options.tokenStorage,
-          nametag: options.nametag
+          nametag: options.nametag,
+          l1: options.l1
         });
         return { success: true, sphere: sphere2, mnemonic };
       }
@@ -8457,7 +9393,8 @@ var Sphere = class _Sphere {
         transport: options.transport,
         oracle: options.oracle,
         tokenStorage: options.tokenStorage,
-        nametag: options.nametag
+        nametag: options.nametag,
+        l1: options.l1
       });
       return { success: true, sphere };
     }
@@ -8661,9 +9598,9 @@ var Sphere = class _Sphere {
     if (index < 0) {
       throw new Error("Address index must be non-negative");
     }
-    const newNametag = options?.nametag?.startsWith("@") ? options.nametag.slice(1) : options?.nametag;
-    if (newNametag && !this.validateNametag(newNametag)) {
-      throw new Error("Invalid nametag format. Use alphanumeric characters, 3-20 chars.");
+    const newNametag = options?.nametag ? this.cleanNametag(options.nametag) : void 0;
+    if (newNametag && !isValidNametag(newNametag)) {
+      throw new Error("Invalid nametag format. Use lowercase alphanumeric, underscore, or hyphen (3-20 chars), or a valid phone number.");
     }
     const addressInfo = this.deriveAddress(index, false);
     const ipnsHash = sha256(addressInfo.publicKey, "hex").slice(0, 40);
@@ -9047,9 +9984,9 @@ var Sphere = class _Sphere {
    */
   async registerNametag(nametag) {
     this.ensureReady();
-    const cleanNametag = nametag.startsWith("@") ? nametag.slice(1) : nametag;
-    if (!this.validateNametag(cleanNametag)) {
-      throw new Error("Invalid nametag format. Use alphanumeric characters, 3-20 chars.");
+    const cleanNametag = this.cleanNametag(nametag);
+    if (!isValidNametag(cleanNametag)) {
+      throw new Error("Invalid nametag format. Use lowercase alphanumeric, underscore, or hyphen (3-20 chars), or a valid phone number.");
     }
     if (this._identity?.nametag) {
       throw new Error(`Nametag already registered for address ${this._currentAddressIndex}: @${this._identity.nametag}`);
@@ -9320,46 +10257,49 @@ var Sphere = class _Sphere {
     if (this._identity?.nametag) {
       return;
     }
-    if (!this._transport.recoverNametag) {
+    let recoveredNametag = null;
+    if (this._transport.recoverNametag) {
+      try {
+        recoveredNametag = await this._transport.recoverNametag();
+      } catch {
+      }
+    }
+    if (!recoveredNametag && this._transport.resolveAddressInfo && this._identity?.l1Address) {
+      try {
+        const info = await this._transport.resolveAddressInfo(this._identity.l1Address);
+        if (info?.nametag) {
+          recoveredNametag = info.nametag;
+        }
+      } catch {
+      }
+    }
+    if (!recoveredNametag) {
       return;
     }
     try {
-      const recoveredNametag = await this._transport.recoverNametag();
-      if (recoveredNametag) {
-        if (this._identity) {
-          this._identity.nametag = recoveredNametag;
-          await this._updateCachedProxyAddress();
-        }
-        const entry = await this.ensureAddressTracked(this._currentAddressIndex);
-        let nametags = this._addressNametags.get(entry.addressId);
-        if (!nametags) {
-          nametags = /* @__PURE__ */ new Map();
-          this._addressNametags.set(entry.addressId, nametags);
-        }
-        const nextIndex = nametags.size;
-        nametags.set(nextIndex, recoveredNametag);
-        await this.persistAddressNametags();
-        if (this._transport.publishIdentityBinding) {
-          await this._transport.publishIdentityBinding(
-            this._identity.chainPubkey,
-            this._identity.l1Address,
-            this._identity.directAddress || "",
-            recoveredNametag
-          );
-        }
-        this.emitEvent("nametag:recovered", { nametag: recoveredNametag });
+      if (this._identity) {
+        this._identity.nametag = recoveredNametag;
+        await this._updateCachedProxyAddress();
+      }
+      const entry = await this.ensureAddressTracked(this._currentAddressIndex);
+      let nametags = this._addressNametags.get(entry.addressId);
+      if (!nametags) {
+        nametags = /* @__PURE__ */ new Map();
+        this._addressNametags.set(entry.addressId, nametags);
       }
+      const nextIndex = nametags.size;
+      nametags.set(nextIndex, recoveredNametag);
+      await this.persistAddressNametags();
+      this.emitEvent("nametag:recovered", { nametag: recoveredNametag });
     } catch {
     }
   }
   /**
-   * Validate nametag format
+   * Strip @ prefix and normalize a nametag (lowercase, phone E.164, strip @unicity suffix).
    */
-  validateNametag(nametag) {
-    const pattern = new RegExp(
-      `^[a-zA-Z0-9_-]{${LIMITS.NAMETAG_MIN_LENGTH},${LIMITS.NAMETAG_MAX_LENGTH}}$`
-    );
-    return pattern.test(nametag);
+  cleanNametag(raw) {
+    const stripped = raw.startsWith("@") ? raw.slice(1) : raw;
+    return (0, import_nostr_js_sdk2.normalizeNametag)(stripped);
   }
   // ===========================================================================
   // Public Methods - Lifecycle
@@ -9557,8 +10497,12 @@ var Sphere = class _Sphere {
     for (const provider of this._tokenStorageProviders.values()) {
       provider.setIdentity(this._identity);
     }
-    await this._storage.connect();
-    await this._transport.connect();
+    if (!this._storage.isConnected()) {
+      await this._storage.connect();
+    }
+    if (!this._transport.isConnected()) {
+      await this._transport.connect();
+    }
     await this._oracle.initialize();
     for (const provider of this._tokenStorageProviders.values()) {
       await provider.initialize();
@@ -9716,6 +10660,7 @@ init_bech32();
   initSphere,
   isEncryptedData,
   isValidBech32,
+  isValidNametag,
   isValidPrivateKey,
   loadSphere,
   mnemonicToEntropy,