@unicitylabs/sphere-sdk 0.1.9 → 0.2.1

package/dist/index.js

@@ -1539,7 +1539,6 @@ var L1PaymentsModule = class {
   _initialized = false;
   _config;
   _identity;
-  _chainCode;
   _addresses = [];
   _wallet;
   _transport;
@@ -1553,7 +1552,6 @@ var L1PaymentsModule = class {
   }
   async initialize(deps) {
     this._identity = deps.identity;
-    this._chainCode = deps.chainCode;
     this._addresses = deps.addresses ?? [];
     this._transport = deps.transport;
     this._wallet = {
@@ -1589,7 +1587,6 @@ var L1PaymentsModule = class {
     }
     this._initialized = false;
     this._identity = void 0;
-    this._chainCode = void 0;
     this._addresses = [];
     this._wallet = void 0;
   }
@@ -1624,10 +1621,10 @@ var L1PaymentsModule = class {
    * Resolve nametag to L1 address using transport provider
    */
   async resolveNametagToL1Address(nametag) {
-    if (!this._transport?.resolveNametagInfo) {
-      throw new Error("Transport provider does not support nametag resolution");
+    if (!this._transport?.resolve) {
+      throw new Error("Transport provider does not support resolution");
     }
-    const info = await this._transport.resolveNametagInfo(nametag);
+    const info = await this._transport.resolve(nametag);
     if (!info) {
       throw new Error(`Nametag not found: ${nametag}`);
     }
@@ -1904,25 +1901,11 @@ var TokenSplitCalculator = class {
    * 3. If no exact match, determine which token to split
    */
   async calculateOptimalSplit(availableTokens, targetAmount, targetCoinIdHex) {
-    console.log(
-      `[SplitCalculator] Calculating split for ${targetAmount} of ${targetCoinIdHex}`
-    );
-    console.log(`[SplitCalculator] Available tokens: ${availableTokens.length}`);
     const candidates = [];
     for (const t of availableTokens) {
-      console.log(`[SplitCalculator] Token ${t.id}: coinId=${t.coinId}, status=${t.status}, hasSdkData=${!!t.sdkData}`);
-      if (t.coinId !== targetCoinIdHex) {
-        console.log(`[SplitCalculator] Skipping token ${t.id}: coinId mismatch (${t.coinId} !== ${targetCoinIdHex})`);
-        continue;
-      }
-      if (t.status !== "confirmed") {
-        console.log(`[SplitCalculator] Skipping token ${t.id}: status is ${t.status}`);
-        continue;
-      }
-      if (!t.sdkData) {
-        console.log(`[SplitCalculator] Skipping token ${t.id}: no sdkData`);
-        continue;
-      }
+      if (t.coinId !== targetCoinIdHex) continue;
+      if (t.status !== "confirmed") continue;
+      if (!t.sdkData) continue;
       try {
         const parsed = JSON.parse(t.sdkData);
         const sdkToken = await SdkToken.fromJSON(parsed);
@@ -1950,14 +1933,12 @@ var TokenSplitCalculator = class {
     }
     const exactMatch = candidates.find((t) => t.amount === targetAmount);
     if (exactMatch) {
-      console.log("[SplitCalculator] Found exact match token");
       return this.createDirectPlan([exactMatch], targetAmount, targetCoinIdHex);
     }
     const maxCombinationSize = Math.min(5, candidates.length);
     for (let size = 2; size <= maxCombinationSize; size++) {
       const combo = this.findCombinationOfSize(candidates, targetAmount, size);
       if (combo) {
-        console.log(`[SplitCalculator] Found exact combination of ${size} tokens`);
         return this.createDirectPlan(combo, targetAmount, targetCoinIdHex);
       }
     }
@@ -1974,9 +1955,6 @@ var TokenSplitCalculator = class {
       } else {
         const neededFromThisToken = targetAmount - currentSum;
         const remainderForSender = candidate.amount - neededFromThisToken;
-        console.log(
-          `[SplitCalculator] Split required. Sending: ${neededFromThisToken}, Remainder: ${remainderForSender}`
-        );
         return {
           tokensToTransferDirectly: toTransfer,
           tokenToSplit: candidate,
@@ -1995,16 +1973,10 @@ var TokenSplitCalculator = class {
    */
   getTokenBalance(sdkToken, coinIdHex) {
     try {
-      if (!sdkToken.coins) {
-        console.log("[SplitCalculator] Token has no coins");
-        return 0n;
-      }
+      if (!sdkToken.coins) return 0n;
       const coinId = CoinId.fromJSON(coinIdHex);
-      const balance = sdkToken.coins.get(coinId);
-      console.log(`[SplitCalculator] Token balance for ${coinIdHex.slice(0, 8)}...: ${balance ?? 0n}`);
-      return balance ?? 0n;
-    } catch (e) {
-      console.error("[SplitCalculator] Error getting token balance:", e);
+      return sdkToken.coins.get(coinId) ?? 0n;
+    } catch {
       return 0n;
     }
   }
@@ -2233,20 +2205,18 @@ var NametagMinter = class {
     const cleanNametag = nametag.replace("@", "").trim();
     this.log(`Starting mint for nametag: ${cleanNametag}`);
     try {
-      const isAvailable = await this.isNametagAvailable(cleanNametag);
-      if (!isAvailable) {
-        return {
-          success: false,
-          error: `Nametag "${cleanNametag}" is already taken`
-        };
-      }
       const nametagTokenId = await TokenId2.fromNameTag(cleanNametag);
       const nametagTokenType = new TokenType(
         Buffer.from(UNICITY_TOKEN_TYPE_HEX, "hex")
       );
-      const salt = new Uint8Array(32);
-      crypto.getRandomValues(salt);
-      this.log("Generated salt");
+      const nametagBytes = new TextEncoder().encode(cleanNametag);
+      const pubKey = this.signingService.publicKey;
+      const saltInput = new Uint8Array(pubKey.length + nametagBytes.length);
+      saltInput.set(pubKey, 0);
+      saltInput.set(nametagBytes, pubKey.length);
+      const saltBuffer = await crypto.subtle.digest("SHA-256", saltInput);
+      const salt = new Uint8Array(saltBuffer);
+      this.log("Generated deterministic salt");
       const mintData = await MintTransactionData.createFromNametag(
         cleanNametag,
         nametagTokenType,
@@ -2369,8 +2339,10 @@ var STORAGE_KEYS_GLOBAL = {
   WALLET_EXISTS: "wallet_exists",
   /** Current active address index */
   CURRENT_ADDRESS_INDEX: "current_address_index",
-  /** Index of address nametags (JSON: { "0": "alice", "1": "bob" }) - for discovery */
-  ADDRESS_NAMETAGS: "address_nametags"
+  /** Nametag cache per address (separate from tracked addresses registry) */
+  ADDRESS_NAMETAGS: "address_nametags",
+  /** Active addresses registry (JSON: TrackedAddressesStorage) */
+  TRACKED_ADDRESSES: "tracked_addresses"
 };
 var STORAGE_KEYS_ADDRESS = {
   /** Pending transfers for this address */
@@ -2819,11 +2791,16 @@ function getCurrentStateHash(txf) {
     if (lastTx?.newStateHash) {
       return lastTx.newStateHash;
     }
-    return void 0;
+    if (lastTx?.inclusionProof?.authenticator?.stateHash) {
+      return lastTx.inclusionProof.authenticator.stateHash;
+    }
   }
   if (txf._integrity?.currentStateHash) {
     return txf._integrity.currentStateHash;
   }
+  if (txf.genesis?.inclusionProof?.authenticator?.stateHash) {
+    return txf.genesis.inclusionProof.authenticator.stateHash;
+  }
   return void 0;
 }
 function hasValidTxfData(token) {
@@ -3184,16 +3161,733 @@ function getCoinIdByName(name) {
   return TokenRegistry.getInstance().getCoinIdByName(name);
 }
 
-// modules/payments/PaymentsModule.ts
-import { Token as SdkToken2 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
+// modules/payments/InstantSplitExecutor.ts
+import { Token as Token3 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
+import { TokenId as TokenId3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenId";
+import { TokenState as TokenState3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
 import { CoinId as CoinId3 } from "@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId";
+import { TokenCoinData as TokenCoinData2 } from "@unicitylabs/state-transition-sdk/lib/token/fungible/TokenCoinData";
+import { TokenSplitBuilder as TokenSplitBuilder2 } from "@unicitylabs/state-transition-sdk/lib/transaction/split/TokenSplitBuilder";
+import { HashAlgorithm as HashAlgorithm3 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
+import { UnmaskedPredicate as UnmaskedPredicate3 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
+import { UnmaskedPredicateReference as UnmaskedPredicateReference2 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference";
 import { TransferCommitment as TransferCommitment2 } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment";
+import { waitInclusionProof as waitInclusionProof3 } from "@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils";
+async function sha2563(input) {
+  const data = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const buffer = new ArrayBuffer(data.length);
+  new Uint8Array(buffer).set(data);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+  return new Uint8Array(hashBuffer);
+}
+function toHex2(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function fromHex2(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;
+}
+var InstantSplitExecutor = class {
+  client;
+  trustBase;
+  signingService;
+  devMode;
+  constructor(config) {
+    this.client = config.stateTransitionClient;
+    this.trustBase = config.trustBase;
+    this.signingService = config.signingService;
+    this.devMode = config.devMode ?? false;
+  }
+  /**
+   * Execute an instant split transfer with V5 optimized flow.
+   *
+   * Critical path (~2.3s):
+   * 1. Create and submit burn commitment
+   * 2. Wait for burn proof
+   * 3. Create mint commitments with SplitMintReason
+   * 4. Create transfer commitment (no mint proof needed)
+   * 5. Send bundle via transport
+   *
+   * @param tokenToSplit - The SDK token to split
+   * @param splitAmount - Amount to send to recipient
+   * @param remainderAmount - Amount to keep as change
+   * @param coinIdHex - Coin ID in hex format
+   * @param recipientAddress - Recipient's address (PROXY or DIRECT)
+   * @param transport - Transport provider for sending the bundle
+   * @param recipientPubkey - Recipient's transport public key
+   * @param options - Optional configuration
+   * @returns InstantSplitResult with success status and timing info
+   */
+  async executeSplitInstant(tokenToSplit, splitAmount, remainderAmount, coinIdHex, recipientAddress, transport, recipientPubkey, options) {
+    const startTime = performance.now();
+    const splitGroupId = crypto.randomUUID();
+    const tokenIdHex = toHex2(tokenToSplit.id.bytes);
+    console.log(`[InstantSplit] Starting V5 split for token ${tokenIdHex.slice(0, 8)}...`);
+    try {
+      const coinId = new CoinId3(fromHex2(coinIdHex));
+      const seedString = `${tokenIdHex}_${splitAmount.toString()}_${remainderAmount.toString()}_${Date.now()}`;
+      const recipientTokenId = new TokenId3(await sha2563(seedString));
+      const senderTokenId = new TokenId3(await sha2563(seedString + "_sender"));
+      const recipientSalt = await sha2563(seedString + "_recipient_salt");
+      const senderSalt = await sha2563(seedString + "_sender_salt");
+      const senderAddressRef = await UnmaskedPredicateReference2.create(
+        tokenToSplit.type,
+        this.signingService.algorithm,
+        this.signingService.publicKey,
+        HashAlgorithm3.SHA256
+      );
+      const senderAddress = await senderAddressRef.toAddress();
+      const builder = new TokenSplitBuilder2();
+      const coinDataA = TokenCoinData2.create([[coinId, splitAmount]]);
+      builder.createToken(
+        recipientTokenId,
+        tokenToSplit.type,
+        new Uint8Array(0),
+        coinDataA,
+        senderAddress,
+        // Mint to sender first, then transfer
+        recipientSalt,
+        null
+      );
+      const coinDataB = TokenCoinData2.create([[coinId, remainderAmount]]);
+      builder.createToken(
+        senderTokenId,
+        tokenToSplit.type,
+        new Uint8Array(0),
+        coinDataB,
+        senderAddress,
+        senderSalt,
+        null
+      );
+      const split = await builder.build(tokenToSplit);
+      console.log("[InstantSplit] Step 1: Creating and submitting burn...");
+      const burnSalt = await sha2563(seedString + "_burn_salt");
+      const burnCommitment = await split.createBurnCommitment(burnSalt, this.signingService);
+      const burnResponse = await this.client.submitTransferCommitment(burnCommitment);
+      if (burnResponse.status !== "SUCCESS" && burnResponse.status !== "REQUEST_ID_EXISTS") {
+        throw new Error(`Burn submission failed: ${burnResponse.status}`);
+      }
+      console.log("[InstantSplit] Step 2: Waiting for burn proof...");
+      const burnProof = this.devMode ? await this.waitInclusionProofWithDevBypass(burnCommitment, options?.burnProofTimeoutMs) : await waitInclusionProof3(this.trustBase, this.client, burnCommitment);
+      const burnTransaction = burnCommitment.toTransaction(burnProof);
+      const burnDuration = performance.now() - startTime;
+      console.log(`[InstantSplit] Burn proof received in ${burnDuration.toFixed(0)}ms`);
+      options?.onBurnCompleted?.(JSON.stringify(burnTransaction.toJSON()));
+      console.log("[InstantSplit] Step 3: Creating mint commitments...");
+      const mintCommitments = await split.createSplitMintCommitments(this.trustBase, burnTransaction);
+      const recipientIdHex = toHex2(recipientTokenId.bytes);
+      const senderIdHex = toHex2(senderTokenId.bytes);
+      const recipientMintCommitment = mintCommitments.find(
+        (c) => toHex2(c.transactionData.tokenId.bytes) === recipientIdHex
+      );
+      const senderMintCommitment = mintCommitments.find(
+        (c) => toHex2(c.transactionData.tokenId.bytes) === senderIdHex
+      );
+      if (!recipientMintCommitment || !senderMintCommitment) {
+        throw new Error("Failed to find expected mint commitments");
+      }
+      console.log("[InstantSplit] Step 4: Creating transfer commitment...");
+      const transferSalt = await sha2563(seedString + "_transfer_salt");
+      const transferCommitment = await this.createTransferCommitmentFromMintData(
+        recipientMintCommitment.transactionData,
+        recipientAddress,
+        transferSalt,
+        this.signingService
+      );
+      const mintedPredicate = await UnmaskedPredicate3.create(
+        recipientTokenId,
+        tokenToSplit.type,
+        this.signingService,
+        HashAlgorithm3.SHA256,
+        recipientSalt
+      );
+      const mintedState = new TokenState3(mintedPredicate, null);
+      console.log("[InstantSplit] Step 5: Packaging V5 bundle...");
+      const senderPubkey = toHex2(this.signingService.publicKey);
+      let nametagTokenJson;
+      const recipientAddressStr = recipientAddress.toString();
+      if (recipientAddressStr.startsWith("PROXY://") && tokenToSplit.nametagTokens?.length > 0) {
+        nametagTokenJson = JSON.stringify(tokenToSplit.nametagTokens[0].toJSON());
+      }
+      const bundle = {
+        version: "5.0",
+        type: "INSTANT_SPLIT",
+        burnTransaction: JSON.stringify(burnTransaction.toJSON()),
+        recipientMintData: JSON.stringify(recipientMintCommitment.transactionData.toJSON()),
+        transferCommitment: JSON.stringify(transferCommitment.toJSON()),
+        amount: splitAmount.toString(),
+        coinId: coinIdHex,
+        tokenTypeHex: toHex2(tokenToSplit.type.bytes),
+        splitGroupId,
+        senderPubkey,
+        recipientSaltHex: toHex2(recipientSalt),
+        transferSaltHex: toHex2(transferSalt),
+        mintedTokenStateJson: JSON.stringify(mintedState.toJSON()),
+        finalRecipientStateJson: "",
+        // Recipient creates their own
+        recipientAddressJson: recipientAddressStr,
+        nametagTokenJson
+      };
+      console.log("[InstantSplit] Step 6: Sending via transport...");
+      const nostrEventId = await transport.sendTokenTransfer(recipientPubkey, {
+        token: JSON.stringify(bundle),
+        proof: null,
+        // Proof is included in the bundle
+        memo: "INSTANT_SPLIT_V5",
+        sender: {
+          transportPubkey: senderPubkey
+        }
+      });
+      const criticalPathDuration = performance.now() - startTime;
+      console.log(`[InstantSplit] V5 complete in ${criticalPathDuration.toFixed(0)}ms`);
+      options?.onNostrDelivered?.(nostrEventId);
+      if (!options?.skipBackground) {
+        this.submitBackgroundV5(senderMintCommitment, recipientMintCommitment, transferCommitment, {
+          signingService: this.signingService,
+          tokenType: tokenToSplit.type,
+          coinId,
+          senderTokenId,
+          senderSalt,
+          onProgress: options?.onBackgroundProgress,
+          onChangeTokenCreated: options?.onChangeTokenCreated,
+          onStorageSync: options?.onStorageSync
+        });
+      }
+      return {
+        success: true,
+        nostrEventId,
+        splitGroupId,
+        criticalPathDurationMs: criticalPathDuration,
+        backgroundStarted: !options?.skipBackground
+      };
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(`[InstantSplit] Failed after ${duration.toFixed(0)}ms:`, error);
+      return {
+        success: false,
+        splitGroupId,
+        criticalPathDurationMs: duration,
+        error: errorMessage,
+        backgroundStarted: false
+      };
+    }
+  }
+  /**
+   * Create a TransferCommitment from MintTransactionData WITHOUT waiting for mint proof.
+   *
+   * Key insight: TransferCommitment.create() only needs token.state and token.nametagTokens.
+   * It does NOT need the genesis transaction or mint proof.
+   */
+  async createTransferCommitmentFromMintData(mintData, recipientAddress, transferSalt, signingService, nametagTokens) {
+    const predicate = await UnmaskedPredicate3.create(
+      mintData.tokenId,
+      mintData.tokenType,
+      signingService,
+      HashAlgorithm3.SHA256,
+      mintData.salt
+    );
+    const state = new TokenState3(predicate, null);
+    const minimalToken = {
+      state,
+      nametagTokens: nametagTokens || [],
+      id: mintData.tokenId,
+      type: mintData.tokenType
+    };
+    const transferCommitment = await TransferCommitment2.create(
+      minimalToken,
+      recipientAddress,
+      transferSalt,
+      null,
+      // recipientData
+      null,
+      // recipientDataHash
+      signingService
+    );
+    return transferCommitment;
+  }
+  /**
+   * V5 background submission.
+   *
+   * Submits mint commitments to aggregator in PARALLEL after transport delivery.
+   * Then waits for sender's mint proof, reconstructs change token, and saves it.
+   */
+  submitBackgroundV5(senderMintCommitment, recipientMintCommitment, transferCommitment, context) {
+    console.log("[InstantSplit] Background: Starting parallel mint submission...");
+    const startTime = performance.now();
+    const submissions = Promise.all([
+      this.client.submitMintCommitment(senderMintCommitment).then((res) => ({ type: "senderMint", status: res.status })).catch((err) => ({ type: "senderMint", status: "ERROR", error: err })),
+      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) => {
+      const submitDuration = performance.now() - startTime;
+      console.log(`[InstantSplit] Background: Submissions complete in ${submitDuration.toFixed(0)}ms`);
+      context.onProgress?.({
+        stage: "MINTS_SUBMITTED",
+        message: `All commitments submitted in ${submitDuration.toFixed(0)}ms`
+      });
+      const senderMintResult = results.find((r) => r.type === "senderMint");
+      if (senderMintResult?.status !== "SUCCESS" && senderMintResult?.status !== "REQUEST_ID_EXISTS") {
+        console.error("[InstantSplit] Background: Sender mint failed - cannot save change token");
+        context.onProgress?.({
+          stage: "FAILED",
+          message: "Sender mint submission failed",
+          error: String(senderMintResult?.error)
+        });
+        return;
+      }
+      console.log("[InstantSplit] Background: Waiting for sender mint proof...");
+      const proofStartTime = performance.now();
+      try {
+        const senderMintProof = this.devMode ? await this.waitInclusionProofWithDevBypass(senderMintCommitment) : await waitInclusionProof3(this.trustBase, this.client, senderMintCommitment);
+        const proofDuration = performance.now() - proofStartTime;
+        console.log(`[InstantSplit] Background: Sender mint proof received in ${proofDuration.toFixed(0)}ms`);
+        context.onProgress?.({
+          stage: "MINTS_PROVEN",
+          message: `Mint proof received in ${proofDuration.toFixed(0)}ms`
+        });
+        const mintTransaction = senderMintCommitment.toTransaction(senderMintProof);
+        const predicate = await UnmaskedPredicate3.create(
+          context.senderTokenId,
+          context.tokenType,
+          context.signingService,
+          HashAlgorithm3.SHA256,
+          context.senderSalt
+        );
+        const state = new TokenState3(predicate, null);
+        const changeToken = await Token3.mint(this.trustBase, state, mintTransaction);
+        if (!this.devMode) {
+          const verification = await changeToken.verify(this.trustBase);
+          if (!verification.isSuccessful) {
+            throw new Error(`Change token verification failed`);
+          }
+        }
+        console.log("[InstantSplit] Background: Change token created");
+        context.onProgress?.({
+          stage: "CHANGE_TOKEN_SAVED",
+          message: "Change token created and verified"
+        });
+        if (context.onChangeTokenCreated) {
+          await context.onChangeTokenCreated(changeToken);
+          console.log("[InstantSplit] Background: Change token saved");
+        }
+        if (context.onStorageSync) {
+          try {
+            const syncSuccess = await context.onStorageSync();
+            console.log(`[InstantSplit] Background: Storage sync ${syncSuccess ? "completed" : "deferred"}`);
+            context.onProgress?.({
+              stage: "STORAGE_SYNCED",
+              message: syncSuccess ? "Storage synchronized" : "Sync deferred"
+            });
+          } catch (syncError) {
+            console.warn("[InstantSplit] Background: Storage sync error:", syncError);
+          }
+        }
+        const totalDuration = performance.now() - startTime;
+        console.log(`[InstantSplit] Background: Complete in ${totalDuration.toFixed(0)}ms`);
+        context.onProgress?.({
+          stage: "COMPLETED",
+          message: `Background processing complete in ${totalDuration.toFixed(0)}ms`
+        });
+      } catch (proofError) {
+        console.error("[InstantSplit] Background: Failed to get sender mint proof:", proofError);
+        context.onProgress?.({
+          stage: "FAILED",
+          message: "Failed to get mint proof",
+          error: String(proofError)
+        });
+      }
+    }).catch((err) => {
+      console.error("[InstantSplit] Background: Submission batch failed:", err);
+      context.onProgress?.({
+        stage: "FAILED",
+        message: "Background submission failed",
+        error: String(err)
+      });
+    });
+  }
+  /**
+   * Dev mode bypass for waitInclusionProof.
+   * In dev mode, we create a mock proof for testing.
+   */
+  async waitInclusionProofWithDevBypass(commitment, timeoutMs = 6e4) {
+    if (this.devMode) {
+      try {
+        return await Promise.race([
+          waitInclusionProof3(this.trustBase, this.client, commitment),
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error("Dev mode timeout")), Math.min(timeoutMs, 5e3))
+          )
+        ]);
+      } catch {
+        console.log("[InstantSplit] Dev mode: Using mock proof");
+        return {
+          toJSON: () => ({ mock: true })
+        };
+      }
+    }
+    return waitInclusionProof3(this.trustBase, this.client, commitment);
+  }
+};
+
+// modules/payments/InstantSplitProcessor.ts
+import { Token as Token4 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
+import { TokenState as TokenState4 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
+import { TokenType as TokenType2 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
+import { HashAlgorithm as HashAlgorithm4 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
+import { UnmaskedPredicate as UnmaskedPredicate4 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
+import { TransferCommitment as TransferCommitment3 } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment";
 import { TransferTransaction } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction";
+import { MintCommitment as MintCommitment2 } from "@unicitylabs/state-transition-sdk/lib/transaction/MintCommitment";
+import { MintTransactionData as MintTransactionData2 } from "@unicitylabs/state-transition-sdk/lib/transaction/MintTransactionData";
+import { waitInclusionProof as waitInclusionProof4 } from "@unicitylabs/state-transition-sdk/lib/util/InclusionProofUtils";
+
+// types/instant-split.ts
+function isInstantSplitBundle(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  const bundle = obj;
+  if (bundle.type !== "INSTANT_SPLIT") return false;
+  if (typeof bundle.recipientMintData !== "string") return false;
+  if (typeof bundle.transferCommitment !== "string") return false;
+  if (typeof bundle.amount !== "string") return false;
+  if (typeof bundle.coinId !== "string") return false;
+  if (typeof bundle.splitGroupId !== "string") return false;
+  if (typeof bundle.senderPubkey !== "string") return false;
+  if (typeof bundle.recipientSaltHex !== "string") return false;
+  if (typeof bundle.transferSaltHex !== "string") return false;
+  if (bundle.version === "4.0") {
+    return typeof bundle.burnCommitment === "string";
+  } else if (bundle.version === "5.0") {
+    return typeof bundle.burnTransaction === "string" && typeof bundle.mintedTokenStateJson === "string" && typeof bundle.finalRecipientStateJson === "string" && typeof bundle.recipientAddressJson === "string";
+  }
+  return false;
+}
+function isInstantSplitBundleV4(obj) {
+  return isInstantSplitBundle(obj) && obj.version === "4.0";
+}
+function isInstantSplitBundleV5(obj) {
+  return isInstantSplitBundle(obj) && obj.version === "5.0";
+}
+
+// modules/payments/InstantSplitProcessor.ts
+function fromHex3(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;
+}
+var InstantSplitProcessor = class {
+  client;
+  trustBase;
+  devMode;
+  constructor(config) {
+    this.client = config.stateTransitionClient;
+    this.trustBase = config.trustBase;
+    this.devMode = config.devMode ?? false;
+  }
+  /**
+   * Process a received INSTANT_SPLIT bundle.
+   *
+   * @param bundle - The received bundle (V4 or V5)
+   * @param signingService - Recipient's signing service
+   * @param senderPubkey - Sender's public key (for verification)
+   * @param options - Processing options
+   * @returns Processing result with finalized token if successful
+   */
+  async processReceivedBundle(bundle, signingService, senderPubkey, options) {
+    if (isInstantSplitBundleV5(bundle)) {
+      return this.processV5Bundle(bundle, signingService, senderPubkey, options);
+    } else if (isInstantSplitBundleV4(bundle)) {
+      return this.processV4Bundle(bundle, signingService, senderPubkey, options);
+    }
+    return {
+      success: false,
+      error: `Unknown bundle version: ${bundle.version}`,
+      durationMs: 0
+    };
+  }
+  /**
+   * Process a V5 bundle (production mode).
+   *
+   * V5 Flow:
+   * 1. Burn transaction already has proof (just validate)
+   * 2. Submit mint commitment -> wait for proof
+   * 3. Reconstruct minted token (use sender's state from bundle)
+   * 4. Submit transfer commitment -> wait for proof
+   * 5. Create recipient's final state and finalize token
+   */
+  async processV5Bundle(bundle, signingService, senderPubkey, options) {
+    console.log("[InstantSplitProcessor] Processing V5 bundle...");
+    const startTime = performance.now();
+    try {
+      if (bundle.senderPubkey !== senderPubkey) {
+        console.warn("[InstantSplitProcessor] Sender pubkey mismatch (non-fatal)");
+      }
+      const burnTxJson = JSON.parse(bundle.burnTransaction);
+      const burnTransaction = await TransferTransaction.fromJSON(burnTxJson);
+      console.log("[InstantSplitProcessor] Burn transaction validated");
+      const mintDataJson = JSON.parse(bundle.recipientMintData);
+      const mintData = await MintTransactionData2.fromJSON(mintDataJson);
+      const mintCommitment = await MintCommitment2.create(mintData);
+      console.log("[InstantSplitProcessor] Mint commitment recreated");
+      const mintResponse = await this.client.submitMintCommitment(mintCommitment);
+      if (mintResponse.status !== "SUCCESS" && mintResponse.status !== "REQUEST_ID_EXISTS") {
+        throw new Error(`Mint submission failed: ${mintResponse.status}`);
+      }
+      console.log(`[InstantSplitProcessor] Mint submitted: ${mintResponse.status}`);
+      const mintProof = this.devMode ? await this.waitInclusionProofWithDevBypass(mintCommitment, options?.proofTimeoutMs) : await waitInclusionProof4(this.trustBase, this.client, mintCommitment);
+      const mintTransaction = mintCommitment.toTransaction(mintProof);
+      console.log("[InstantSplitProcessor] Mint proof received");
+      const tokenType = new TokenType2(fromHex3(bundle.tokenTypeHex));
+      const senderMintedStateJson = JSON.parse(bundle.mintedTokenStateJson);
+      const tokenJson = {
+        version: "2.0",
+        state: senderMintedStateJson,
+        genesis: mintTransaction.toJSON(),
+        transactions: [],
+        nametags: []
+      };
+      const mintedToken = await Token4.fromJSON(tokenJson);
+      console.log("[InstantSplitProcessor] Minted token reconstructed from sender state");
+      const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
+      const transferCommitment = await TransferCommitment3.fromJSON(transferCommitmentJson);
+      const transferResponse = await this.client.submitTransferCommitment(transferCommitment);
+      if (transferResponse.status !== "SUCCESS" && transferResponse.status !== "REQUEST_ID_EXISTS") {
+        throw new Error(`Transfer submission failed: ${transferResponse.status}`);
+      }
+      console.log(`[InstantSplitProcessor] Transfer submitted: ${transferResponse.status}`);
+      const transferProof = this.devMode ? await this.waitInclusionProofWithDevBypass(transferCommitment, options?.proofTimeoutMs) : await waitInclusionProof4(this.trustBase, this.client, transferCommitment);
+      const transferTransaction = transferCommitment.toTransaction(transferProof);
+      console.log("[InstantSplitProcessor] Transfer proof received");
+      const transferSalt = fromHex3(bundle.transferSaltHex);
+      const finalRecipientPredicate = await UnmaskedPredicate4.create(
+        mintData.tokenId,
+        tokenType,
+        signingService,
+        HashAlgorithm4.SHA256,
+        transferSalt
+      );
+      const finalRecipientState = new TokenState4(finalRecipientPredicate, null);
+      console.log("[InstantSplitProcessor] Final recipient state created");
+      let nametagTokens = [];
+      const recipientAddressStr = bundle.recipientAddressJson;
+      if (recipientAddressStr.startsWith("PROXY://")) {
+        console.log("[InstantSplitProcessor] PROXY address detected, finding nametag token...");
+        if (bundle.nametagTokenJson) {
+          try {
+            const nametagToken = await Token4.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) {
+              console.warn("[InstantSplitProcessor] Nametag PROXY address mismatch, ignoring bundle token");
+            } else {
+              nametagTokens = [nametagToken];
+              console.log("[InstantSplitProcessor] Using nametag token from bundle (address validated)");
+            }
+          } catch (err) {
+            console.warn("[InstantSplitProcessor] Failed to parse nametag token from bundle:", err);
+          }
+        }
+        if (nametagTokens.length === 0 && options?.findNametagToken) {
+          const token = await options.findNametagToken(recipientAddressStr);
+          if (token) {
+            nametagTokens = [token];
+            console.log("[InstantSplitProcessor] Found nametag token via callback");
+          }
+        }
+        if (nametagTokens.length === 0 && !this.devMode) {
+          throw new Error(
+            `PROXY address transfer requires nametag token for verification. Address: ${recipientAddressStr}`
+          );
+        }
+      }
+      let finalToken;
+      if (this.devMode) {
+        console.log("[InstantSplitProcessor] Dev mode: finalizing without verification");
+        const tokenJson2 = mintedToken.toJSON();
+        tokenJson2.state = finalRecipientState.toJSON();
+        tokenJson2.transactions = [transferTransaction.toJSON()];
+        finalToken = await Token4.fromJSON(tokenJson2);
+      } else {
+        finalToken = await this.client.finalizeTransaction(
+          this.trustBase,
+          mintedToken,
+          finalRecipientState,
+          transferTransaction,
+          nametagTokens
+        );
+      }
+      console.log("[InstantSplitProcessor] Token finalized");
+      if (!this.devMode) {
+        const verification = await finalToken.verify(this.trustBase);
+        if (!verification.isSuccessful) {
+          throw new Error(`Token verification failed`);
+        }
+        console.log("[InstantSplitProcessor] Token verified");
+      }
+      const duration = performance.now() - startTime;
+      console.log(`[InstantSplitProcessor] V5 bundle processed in ${duration.toFixed(0)}ms`);
+      return {
+        success: true,
+        token: finalToken,
+        durationMs: duration
+      };
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(`[InstantSplitProcessor] V5 processing failed:`, error);
+      return {
+        success: false,
+        error: errorMessage,
+        durationMs: duration
+      };
+    }
+  }
+  /**
+   * Process a V4 bundle (dev mode only).
+   *
+   * V4 Flow:
+   * 1. Submit burn commitment -> wait for proof
+   * 2. Submit mint commitment -> wait for proof
+   * 3. Reconstruct minted token
+   * 4. Submit transfer commitment -> wait for proof
+   * 5. Finalize token
+   */
+  async processV4Bundle(bundle, signingService, _senderPubkey, options) {
+    if (!this.devMode) {
+      return {
+        success: false,
+        error: "INSTANT_SPLIT V4 is only supported in dev mode",
+        durationMs: 0
+      };
+    }
+    console.log("[InstantSplitProcessor] Processing V4 bundle (dev mode)...");
+    const startTime = performance.now();
+    try {
+      const burnCommitmentJson = JSON.parse(bundle.burnCommitment);
+      const burnCommitment = await TransferCommitment3.fromJSON(burnCommitmentJson);
+      const burnResponse = await this.client.submitTransferCommitment(burnCommitment);
+      if (burnResponse.status !== "SUCCESS" && burnResponse.status !== "REQUEST_ID_EXISTS") {
+        throw new Error(`Burn submission failed: ${burnResponse.status}`);
+      }
+      await this.waitInclusionProofWithDevBypass(burnCommitment, options?.proofTimeoutMs);
+      console.log("[InstantSplitProcessor] V4: Burn proof received");
+      const mintDataJson = JSON.parse(bundle.recipientMintData);
+      const mintData = await MintTransactionData2.fromJSON(mintDataJson);
+      const mintCommitment = await MintCommitment2.create(mintData);
+      const mintResponse = await this.client.submitMintCommitment(mintCommitment);
+      if (mintResponse.status !== "SUCCESS" && mintResponse.status !== "REQUEST_ID_EXISTS") {
+        throw new Error(`Mint submission failed: ${mintResponse.status}`);
+      }
+      const mintProof = await this.waitInclusionProofWithDevBypass(
+        mintCommitment,
+        options?.proofTimeoutMs
+      );
+      const mintTransaction = mintCommitment.toTransaction(mintProof);
+      console.log("[InstantSplitProcessor] V4: Mint proof received");
+      const tokenType = new TokenType2(fromHex3(bundle.tokenTypeHex));
+      const recipientSalt = fromHex3(bundle.recipientSaltHex);
+      const recipientPredicate = await UnmaskedPredicate4.create(
+        mintData.tokenId,
+        tokenType,
+        signingService,
+        HashAlgorithm4.SHA256,
+        recipientSalt
+      );
+      const recipientState = new TokenState4(recipientPredicate, null);
+      const tokenJson = {
+        version: "2.0",
+        state: recipientState.toJSON(),
+        genesis: mintTransaction.toJSON(),
+        transactions: [],
+        nametags: []
+      };
+      const mintedToken = await Token4.fromJSON(tokenJson);
+      console.log("[InstantSplitProcessor] V4: Minted token reconstructed");
+      const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
+      const transferCommitment = await TransferCommitment3.fromJSON(transferCommitmentJson);
+      const transferResponse = await this.client.submitTransferCommitment(transferCommitment);
+      if (transferResponse.status !== "SUCCESS" && transferResponse.status !== "REQUEST_ID_EXISTS") {
+        throw new Error(`Transfer submission failed: ${transferResponse.status}`);
+      }
+      const transferProof = await this.waitInclusionProofWithDevBypass(
+        transferCommitment,
+        options?.proofTimeoutMs
+      );
+      const transferTransaction = transferCommitment.toTransaction(transferProof);
+      console.log("[InstantSplitProcessor] V4: Transfer proof received");
+      const transferSalt = fromHex3(bundle.transferSaltHex);
+      const finalPredicate = await UnmaskedPredicate4.create(
+        mintData.tokenId,
+        tokenType,
+        signingService,
+        HashAlgorithm4.SHA256,
+        transferSalt
+      );
+      const finalState = new TokenState4(finalPredicate, null);
+      const finalTokenJson = mintedToken.toJSON();
+      finalTokenJson.state = finalState.toJSON();
+      finalTokenJson.transactions = [transferTransaction.toJSON()];
+      const finalToken = await Token4.fromJSON(finalTokenJson);
+      console.log("[InstantSplitProcessor] V4: Token finalized");
+      const duration = performance.now() - startTime;
+      console.log(`[InstantSplitProcessor] V4 bundle processed in ${duration.toFixed(0)}ms`);
+      return {
+        success: true,
+        token: finalToken,
+        durationMs: duration
+      };
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(`[InstantSplitProcessor] V4 processing failed:`, error);
+      return {
+        success: false,
+        error: errorMessage,
+        durationMs: duration
+      };
+    }
+  }
+  /**
+   * Dev mode bypass for waitInclusionProof.
+   */
+  async waitInclusionProofWithDevBypass(commitment, timeoutMs = 6e4) {
+    if (this.devMode) {
+      try {
+        return await Promise.race([
+          waitInclusionProof4(this.trustBase, this.client, commitment),
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error("Dev mode timeout")), Math.min(timeoutMs, 5e3))
+          )
+        ]);
+      } catch {
+        console.log("[InstantSplitProcessor] Dev mode: Using mock proof");
+        return {
+          toJSON: () => ({ mock: true })
+        };
+      }
+    }
+    return waitInclusionProof4(this.trustBase, this.client, commitment);
+  }
+};
+
+// modules/payments/PaymentsModule.ts
+import { Token as SdkToken2 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
+import { CoinId as CoinId4 } from "@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId";
+import { TransferCommitment as TransferCommitment4 } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment";
+import { TransferTransaction as TransferTransaction2 } from "@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction";
 import { SigningService } from "@unicitylabs/state-transition-sdk/lib/sign/SigningService";
 import { AddressScheme } from "@unicitylabs/state-transition-sdk/lib/address/AddressScheme";
-import { UnmaskedPredicate as UnmaskedPredicate3 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
-import { TokenState as TokenState3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
-import { HashAlgorithm as HashAlgorithm3 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
+import { UnmaskedPredicate as UnmaskedPredicate5 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
+import { TokenState as TokenState5 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
+import { HashAlgorithm as HashAlgorithm5 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
 function enrichWithRegistry(info) {
   const registry = TokenRegistry.getInstance();
   const def = registry.getDefinition(info.coinId);
@@ -3232,7 +3926,7 @@ async function parseTokenInfo(tokenData) {
           if (Array.isArray(firstCoin) && firstCoin.length === 2) {
             [coinIdObj, amount] = firstCoin;
           }
-          if (coinIdObj instanceof CoinId3) {
+          if (coinIdObj instanceof CoinId4) {
             const coinIdHex = coinIdObj.toJSON();
             return enrichWithRegistry({
               coinId: coinIdHex,
@@ -3365,21 +4059,48 @@ function extractStateHashFromSdkData(sdkData) {
   if (!sdkData) return "";
   try {
     const txf = JSON.parse(sdkData);
-    return getCurrentStateHash(txf) || "";
+    const stateHash = getCurrentStateHash(txf);
+    if (!stateHash) {
+      if (txf.state?.hash) {
+        return txf.state.hash;
+      }
+      if (txf.stateHash) {
+        return txf.stateHash;
+      }
+      if (txf.currentStateHash) {
+        return txf.currentStateHash;
+      }
+    }
+    return stateHash || "";
   } catch {
     return "";
   }
 }
-function isSameToken(t1, t2) {
-  if (t1.id === t2.id) return true;
+function createTokenStateKey(tokenId, stateHash) {
+  return `${tokenId}_${stateHash}`;
+}
+function extractTokenStateKey(token) {
+  const tokenId = extractTokenIdFromSdkData(token.sdkData);
+  const stateHash = extractStateHashFromSdkData(token.sdkData);
+  if (!tokenId || !stateHash) return null;
+  return createTokenStateKey(tokenId, stateHash);
+}
+function hasSameGenesisTokenId(t1, t2) {
   const id1 = extractTokenIdFromSdkData(t1.sdkData);
   const id2 = extractTokenIdFromSdkData(t2.sdkData);
   return !!(id1 && id2 && id1 === id2);
 }
+function isSameTokenState(t1, t2) {
+  const key1 = extractTokenStateKey(t1);
+  const key2 = extractTokenStateKey(t2);
+  return !!(key1 && key2 && key1 === key2);
+}
 function createTombstoneFromToken(token) {
   const tokenId = extractTokenIdFromSdkData(token.sdkData);
-  if (!tokenId) return null;
   const stateHash = extractStateHashFromSdkData(token.sdkData);
+  if (!tokenId || !stateHash) {
+    return null;
+  }
   return {
     tokenId,
     stateHash,
@@ -3445,7 +4166,7 @@ function findBestTokenVersion(tokenId, archivedTokens, forkedTokens) {
   candidates.sort((a, b) => countCommittedTxns(b) - countCommittedTxns(a));
   return candidates[0];
 }
-var PaymentsModule = class {
+var PaymentsModule = class _PaymentsModule {
   moduleConfig;
   deps = null;
   /** L1 (ALPHA blockchain) payments sub-module (null if disabled) */
@@ -3470,6 +4191,13 @@ var PaymentsModule = class {
   unsubscribeTransfers = null;
   unsubscribePaymentRequests = null;
   unsubscribePaymentRequestResponses = null;
+  // NOSTR-FIRST proof polling (background proof verification)
+  proofPollingJobs = /* @__PURE__ */ new Map();
+  proofPollingInterval = null;
+  static PROOF_POLLING_INTERVAL_MS = 2e3;
+  // Poll every 2s
+  static PROOF_POLLING_MAX_ATTEMPTS = 30;
+  // Max 30 attempts (~60s)
   constructor(config) {
     this.moduleConfig = {
       autoSync: config?.autoSync ?? true,
@@ -3485,6 +4213,8 @@ var PaymentsModule = class {
   getConfig() {
     return this.moduleConfig;
   }
+  /** Price provider (optional) */
+  priceProvider = null;
   log(...args) {
     if (this.moduleConfig.debug) {
       console.log("[PaymentsModule]", ...args);
@@ -3497,7 +4227,21 @@ var PaymentsModule = class {
    * Initialize module with dependencies
    */
   initialize(deps) {
+    this.unsubscribeTransfers?.();
+    this.unsubscribeTransfers = null;
+    this.unsubscribePaymentRequests?.();
+    this.unsubscribePaymentRequests = null;
+    this.unsubscribePaymentRequestResponses?.();
+    this.unsubscribePaymentRequestResponses = null;
+    this.tokens.clear();
+    this.pendingTransfers.clear();
+    this.tombstones = [];
+    this.archivedTokens.clear();
+    this.forkedTokens.clear();
+    this.transactionHistory = [];
+    this.nametag = null;
     this.deps = deps;
+    this.priceProvider = deps.price ?? null;
     if (this.l1) {
       this.l1.initialize({
         identity: deps.identity,
@@ -3568,6 +4312,8 @@ var PaymentsModule = class {
     this.unsubscribePaymentRequestResponses = null;
     this.paymentRequestHandlers.clear();
     this.paymentRequestResponseHandlers.clear();
+    this.stopProofPolling();
+    this.proofPollingJobs.clear();
     for (const [, resolver] of this.pendingResponseResolvers) {
       clearTimeout(resolver.timeout);
       resolver.reject(new Error("Module destroyed"));
@@ -3592,8 +4338,9 @@ var PaymentsModule = class {
       tokens: []
     };
     try {
-      const recipientPubkey = await this.resolveRecipient(request.recipient);
-      const recipientAddress = await this.resolveRecipientAddress(request.recipient);
+      const peerInfo = await this.deps.transport.resolve?.(request.recipient) ?? null;
+      const recipientPubkey = this.resolveTransportPubkey(request.recipient, peerInfo);
+      const recipientAddress = await this.resolveRecipientAddress(request.recipient, request.addressMode, peerInfo);
       const signingService = await this.createSigningService();
       const stClient = this.deps.oracle.getStateTransitionClient?.();
       if (!stClient) {
@@ -3613,7 +4360,6 @@ var PaymentsModule = class {
       if (!splitPlan) {
         throw new Error("Insufficient balance");
       }
-      this.log(`Split plan: requiresSplit=${splitPlan.requiresSplit}, directTokens=${splitPlan.tokensToTransferDirectly.length}`);
       const tokensToSend = splitPlan.tokensToTransferDirectly.map((t) => t.uiToken);
       if (splitPlan.tokenToSplit) {
         tokensToSend.push(splitPlan.tokenToSplit.uiToken);
@@ -3656,11 +4402,13 @@ var PaymentsModule = class {
         };
         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);
         result.txHash = "split-" + Date.now().toString(16);
         this.log(`Split transfer completed`);
@@ -3679,11 +4427,13 @@ var PaymentsModule = class {
         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
         });
+        console.log(`[Payments] Direct token sent successfully`);
         this.log(`Token ${token.id} transferred, txHash: ${result.txHash}`);
         await this.removeToken(token.id, recipientNametag);
       }
@@ -3737,26 +4487,255 @@ var PaymentsModule = class {
     return TokenRegistry.getInstance().getIconUrl(coinId) ?? void 0;
   }
   // ===========================================================================
-  // Public API - Payment Requests
+  // Public API - Instant Split (V5 Optimized)
   // ===========================================================================
   /**
-   * Send a payment request to someone
-   * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
-   * @param request - Payment request details
-   * @returns Result with event ID
+   * Send tokens using INSTANT_SPLIT V5 optimized flow.
+   *
+   * This achieves ~2.3s critical path latency instead of ~42s by:
+   * 1. Waiting only for burn proof (required)
+   * 2. Creating transfer commitment from mint data (no mint proof needed)
+   * 3. Sending bundle via Nostr immediately
+   * 4. Processing mints in background
+   *
+   * @param request - Transfer request with recipient, amount, and coinId
+   * @param options - Optional instant split configuration
+   * @returns InstantSplitResult with timing info
    */
-  async sendPaymentRequest(recipientPubkeyOrNametag, request) {
+  async sendInstant(request, options) {
     this.ensureInitialized();
-    if (!this.deps.transport.sendPaymentRequest) {
-      return {
-        success: false,
-        error: "Transport provider does not support payment requests"
-      };
-    }
+    const startTime = performance.now();
     try {
-      const recipientPubkey = await this.resolveRecipient(recipientPubkeyOrNametag);
-      const payload = {
-        amount: request.amount,
+      const peerInfo = await this.deps.transport.resolve?.(request.recipient) ?? null;
+      const recipientPubkey = this.resolveTransportPubkey(request.recipient, peerInfo);
+      const recipientAddress = await this.resolveRecipientAddress(request.recipient, request.addressMode, peerInfo);
+      const signingService = await this.createSigningService();
+      const stClient = this.deps.oracle.getStateTransitionClient?.();
+      if (!stClient) {
+        throw new Error("State transition client not available");
+      }
+      const trustBase = this.deps.oracle.getTrustBase?.();
+      if (!trustBase) {
+        throw new Error("Trust base not available");
+      }
+      const calculator = new TokenSplitCalculator();
+      const availableTokens = Array.from(this.tokens.values());
+      const splitPlan = await calculator.calculateOptimalSplit(
+        availableTokens,
+        BigInt(request.amount),
+        request.coinId
+      );
+      if (!splitPlan) {
+        throw new Error("Insufficient balance");
+      }
+      if (!splitPlan.requiresSplit || !splitPlan.tokenToSplit) {
+        this.log("No split required, falling back to standard send()");
+        const result2 = await this.send(request);
+        return {
+          success: result2.status === "completed",
+          criticalPathDurationMs: performance.now() - startTime,
+          error: result2.error
+        };
+      }
+      this.log(`InstantSplit: amount=${splitPlan.splitAmount}, remainder=${splitPlan.remainderAmount}`);
+      const tokenToSplit = splitPlan.tokenToSplit.uiToken;
+      tokenToSplit.status = "transferring";
+      this.tokens.set(tokenToSplit.id, tokenToSplit);
+      const devMode = options?.devMode ?? this.deps.oracle.isDevMode?.() ?? false;
+      const executor = new InstantSplitExecutor({
+        stateTransitionClient: stClient,
+        trustBase,
+        signingService,
+        devMode
+      });
+      const result = await executor.executeSplitInstant(
+        splitPlan.tokenToSplit.sdkToken,
+        splitPlan.splitAmount,
+        splitPlan.remainderAmount,
+        splitPlan.coinId,
+        recipientAddress,
+        this.deps.transport,
+        recipientPubkey,
+        {
+          ...options,
+          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 (result.success) {
+        const recipientNametag = request.recipient.startsWith("@") ? request.recipient.slice(1) : void 0;
+        await this.removeToken(tokenToSplit.id, recipientNametag);
+        await this.addToHistory({
+          type: "SENT",
+          amount: request.amount,
+          coinId: request.coinId,
+          symbol: this.getCoinSymbol(request.coinId),
+          timestamp: Date.now(),
+          recipientNametag
+        });
+        await this.save();
+      } else {
+        tokenToSplit.status = "confirmed";
+        this.tokens.set(tokenToSplit.id, tokenToSplit);
+      }
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        criticalPathDurationMs: performance.now() - startTime,
+        error: errorMessage
+      };
+    }
+  }
+  /**
+   * Process a received INSTANT_SPLIT bundle.
+   *
+   * This should be called when receiving an instant split bundle via transport.
+   * It handles the recipient-side processing:
+   * 1. Validate burn transaction
+   * 2. Submit and wait for mint proof
+   * 3. Submit and wait for transfer proof
+   * 4. Finalize and save the token
+   *
+   * @param bundle - The received InstantSplitBundle (V4 or V5)
+   * @param senderPubkey - Sender's public key for verification
+   * @returns Processing result with finalized token
+   */
+  async processInstantSplitBundle(bundle, senderPubkey) {
+    this.ensureInitialized();
+    try {
+      const signingService = await this.createSigningService();
+      const stClient = this.deps.oracle.getStateTransitionClient?.();
+      if (!stClient) {
+        throw new Error("State transition client not available");
+      }
+      const trustBase = this.deps.oracle.getTrustBase?.();
+      if (!trustBase) {
+        throw new Error("Trust base not available");
+      }
+      const devMode = this.deps.oracle.isDevMode?.() ?? false;
+      const processor = new InstantSplitProcessor({
+        stateTransitionClient: stClient,
+        trustBase,
+        devMode
+      });
+      const result = await processor.processReceivedBundle(
+        bundle,
+        signingService,
+        senderPubkey,
+        {
+          findNametagToken: async (proxyAddress) => {
+            if (this.nametag?.token) {
+              try {
+                const nametagToken = await SdkToken2.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 === proxyAddress) {
+                  return nametagToken;
+                }
+                this.log(`Nametag PROXY address mismatch: ${proxy.address} !== ${proxyAddress}`);
+                return null;
+              } catch (err) {
+                this.log("Failed to parse nametag token:", err);
+                return null;
+              }
+            }
+            return null;
+          }
+        }
+      );
+      if (result.success && result.token) {
+        const tokenData = result.token.toJSON();
+        const info = await parseTokenInfo(tokenData);
+        const uiToken = {
+          id: crypto.randomUUID(),
+          coinId: info.coinId,
+          symbol: info.symbol,
+          name: info.name,
+          decimals: info.decimals,
+          iconUrl: info.iconUrl,
+          amount: bundle.amount,
+          status: "confirmed",
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+          sdkData: JSON.stringify(tokenData)
+        };
+        await this.addToken(uiToken);
+        await this.addToHistory({
+          type: "RECEIVED",
+          amount: bundle.amount,
+          coinId: info.coinId,
+          symbol: info.symbol,
+          timestamp: Date.now(),
+          senderPubkey
+        });
+        await this.save();
+        this.deps.emitEvent("transfer:incoming", {
+          id: bundle.splitGroupId,
+          senderPubkey,
+          tokens: [uiToken],
+          receivedAt: Date.now()
+        });
+      }
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        error: errorMessage,
+        durationMs: 0
+      };
+    }
+  }
+  /**
+   * Check if a payload is an instant split bundle
+   */
+  isInstantSplitBundle(payload) {
+    return isInstantSplitBundle(payload);
+  }
+  // ===========================================================================
+  // Public API - Payment Requests
+  // ===========================================================================
+  /**
+   * Send a payment request to someone
+   * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
+   * @param request - Payment request details
+   * @returns Result with event ID
+   */
+  async sendPaymentRequest(recipientPubkeyOrNametag, request) {
+    this.ensureInitialized();
+    if (!this.deps.transport.sendPaymentRequest) {
+      return {
+        success: false,
+        error: "Transport provider does not support payment requests"
+      };
+    }
+    try {
+      const peerInfo = await this.deps.transport.resolve?.(recipientPubkeyOrNametag) ?? null;
+      const recipientPubkey = this.resolveTransportPubkey(recipientPubkeyOrNametag, peerInfo);
+      const payload = {
+        amount: request.amount,
         coinId: request.coinId,
         message: request.message,
         recipientNametag: request.recipientNametag,
@@ -4058,47 +5037,46 @@ var PaymentsModule = class {
   // Public API - Balance & Tokens
   // ===========================================================================
   /**
-   * Get balance for coin type
+   * Set or update price provider
    */
-  getBalance(coinId) {
-    const balances = /* @__PURE__ */ new Map();
-    for (const token of this.tokens.values()) {
-      if (token.status !== "confirmed") continue;
-      if (coinId && token.coinId !== coinId) continue;
-      const key = token.coinId;
-      const existing = balances.get(key);
-      if (existing) {
-        existing.totalAmount = (BigInt(existing.totalAmount) + BigInt(token.amount)).toString();
-        existing.tokenCount++;
-      } else {
-        balances.set(key, {
-          coinId: token.coinId,
-          symbol: token.symbol,
-          name: token.name,
-          totalAmount: token.amount,
-          tokenCount: 1,
-          decimals: 8
-        });
+  setPriceProvider(provider) {
+    this.priceProvider = provider;
+  }
+  /**
+   * Get total portfolio value in USD
+   * Returns null if PriceProvider is not configured
+   */
+  async getBalance() {
+    const assets = await this.getAssets();
+    if (!this.priceProvider) {
+      return null;
+    }
+    let total = 0;
+    let hasAnyPrice = false;
+    for (const asset of assets) {
+      if (asset.fiatValueUsd != null) {
+        total += asset.fiatValueUsd;
+        hasAnyPrice = true;
       }
     }
-    return Array.from(balances.values());
+    return hasAnyPrice ? total : null;
   }
   /**
-   * Get aggregated assets (tokens grouped by coinId)
+   * Get aggregated assets (tokens grouped by coinId) with price data
    * Only includes confirmed tokens
    */
-  getAssets(coinId) {
-    const assets = /* @__PURE__ */ new Map();
+  async getAssets(coinId) {
+    const assetsMap = /* @__PURE__ */ new Map();
     for (const token of this.tokens.values()) {
       if (token.status !== "confirmed") continue;
       if (coinId && token.coinId !== coinId) continue;
       const key = token.coinId;
-      const existing = assets.get(key);
+      const existing = assetsMap.get(key);
       if (existing) {
         existing.totalAmount = (BigInt(existing.totalAmount) + BigInt(token.amount)).toString();
         existing.tokenCount++;
       } else {
-        assets.set(key, {
+        assetsMap.set(key, {
           coinId: token.coinId,
           symbol: token.symbol,
           name: token.name,
@@ -4109,7 +5087,66 @@ var PaymentsModule = class {
         });
       }
     }
-    return Array.from(assets.values());
+    const rawAssets = Array.from(assetsMap.values());
+    let priceMap = null;
+    if (this.priceProvider && rawAssets.length > 0) {
+      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
+              });
+            }
+          }
+        }
+      }
+    }
+    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 {
+        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
+      };
+    });
   }
   /**
    * Get all tokens
@@ -4135,14 +5172,52 @@ var PaymentsModule = class {
   // ===========================================================================
   /**
    * Add a token
-   * @returns false if duplicate
+   * 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)
    */
   async addToken(token, skipHistory = false) {
     this.ensureInitialized();
-    for (const existing of this.tokens.values()) {
-      if (isSameToken(existing, token)) {
-        this.log(`Duplicate token detected: ${token.id}`);
-        return false;
+    const incomingTokenId = extractTokenIdFromSdkData(token.sdkData);
+    const incomingStateHash = extractStateHashFromSdkData(token.sdkData);
+    const incomingStateKey = incomingTokenId && incomingStateHash ? createTokenStateKey(incomingTokenId, incomingStateHash) : null;
+    if (incomingTokenId && incomingStateHash && this.isStateTombstoned(incomingTokenId, incomingStateHash)) {
+      this.log(`Rejecting tombstoned token: ${incomingTokenId.slice(0, 8)}..._${incomingStateHash.slice(0, 8)}...`);
+      return false;
+    }
+    if (incomingStateKey) {
+      for (const [existingId, existing] of this.tokens) {
+        if (isSameTokenState(existing, token)) {
+          this.log(`Duplicate token state ignored: ${incomingTokenId?.slice(0, 8)}..._${incomingStateHash?.slice(0, 8)}...`);
+          return false;
+        }
+      }
+    }
+    for (const [existingId, existing] of this.tokens) {
+      if (hasSameGenesisTokenId(existing, token)) {
+        const existingStateHash = extractStateHashFromSdkData(existing.sdkData);
+        if (incomingStateHash && existingStateHash && incomingStateHash === existingStateHash) {
+          continue;
+        }
+        if (existing.status === "spent" || existing.status === "invalid") {
+          this.log(`Replacing spent/invalid token ${incomingTokenId?.slice(0, 8)}...`);
+          this.tokens.delete(existingId);
+          break;
+        }
+        if (incomingStateHash && existingStateHash && incomingStateHash !== existingStateHash) {
+          this.log(`Token ${incomingTokenId?.slice(0, 8)}... state updated: ${existingStateHash.slice(0, 8)}... -> ${incomingStateHash.slice(0, 8)}...`);
+          await this.archiveToken(existing);
+          this.tokens.delete(existingId);
+          break;
+        }
+        if (!incomingStateHash || !existingStateHash) {
+          if (existingId !== token.id) {
+            this.log(`Token ${incomingTokenId?.slice(0, 8)}... .id changed, replacing`);
+            await this.archiveToken(existing);
+            this.tokens.delete(existingId);
+            break;
+          }
+        }
       }
     }
     this.tokens.set(token.id, token);
@@ -4297,8 +5372,10 @@ var PaymentsModule = class {
       );
       if (!alreadyTombstoned) {
         this.tombstones.push(tombstone);
-        this.log(`Created tombstone for ${tombstone.tokenId.slice(0, 8)}...`);
+        this.log(`Created tombstone for ${tombstone.tokenId.slice(0, 8)}..._${tombstone.stateHash.slice(0, 8)}...`);
       }
+    } else {
+      this.log(`Warning: Could not create tombstone for token ${tokenId.slice(0, 8)}... (missing tokenId or stateHash)`);
     }
     this.tokens.delete(tokenId);
     if (!skipHistory && token.coinId && token.amount) {
@@ -4616,15 +5693,15 @@ var PaymentsModule = class {
     }
     try {
       const signingService = await this.createSigningService();
-      const { UnmaskedPredicateReference: UnmaskedPredicateReference3 } = await import("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
-      const { TokenType: TokenType3 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+      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 UNICITY_TOKEN_TYPE_HEX3 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
-      const tokenType = new TokenType3(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
-      const addressRef = await UnmaskedPredicateReference3.create(
+      const tokenType = new TokenType5(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
+      const addressRef = await UnmaskedPredicateReference4.create(
         tokenType,
         signingService.algorithm,
         signingService.publicKey,
-        HashAlgorithm3.SHA256
+        HashAlgorithm5.SHA256
       );
       const ownerAddress = await addressRef.toAddress();
       const minter = new NametagMinter({
@@ -4791,40 +5868,22 @@ var PaymentsModule = class {
    * Detect if a string is an L3 address (not a nametag)
    * Returns true for: hex pubkeys (64+ chars), PROXY:, DIRECT: prefixed addresses
    */
-  isL3Address(value) {
-    if (value.startsWith("PROXY:") || value.startsWith("DIRECT:")) {
-      return true;
-    }
-    if (value.length >= 64 && /^[0-9a-fA-F]+$/.test(value)) {
-      return true;
-    }
-    return false;
-  }
   /**
-   * Resolve recipient to Nostr pubkey for messaging
-   * Supports: nametag (with or without @), hex pubkey
+   * Resolve recipient to transport pubkey for messaging.
+   * Uses pre-resolved PeerInfo if available, otherwise resolves via transport.
    */
-  async resolveRecipient(recipient) {
-    if (recipient.startsWith("@")) {
-      const nametag = recipient.slice(1);
-      const pubkey = await this.deps.transport.resolveNametag?.(nametag);
-      if (!pubkey) {
-        throw new Error(`Nametag not found: ${nametag}`);
-      }
-      return pubkey;
+  resolveTransportPubkey(recipient, peerInfo) {
+    if (peerInfo?.transportPubkey) {
+      return peerInfo.transportPubkey;
     }
-    if (this.isL3Address(recipient)) {
-      return recipient;
-    }
-    if (this.deps?.transport.resolveNametag) {
-      const pubkey = await this.deps.transport.resolveNametag(recipient);
-      if (pubkey) {
-        this.log(`Resolved "${recipient}" as nametag to pubkey`);
-        return pubkey;
+    if (recipient.length >= 64 && /^[0-9a-fA-F]+$/.test(recipient)) {
+      if (recipient.length === 66 && (recipient.startsWith("02") || recipient.startsWith("03"))) {
+        return recipient.slice(2);
       }
+      return recipient;
     }
     throw new Error(
-      `Recipient "${recipient}" is not a valid nametag or address. Use @nametag for explicit nametag or a valid hex pubkey/PROXY:/DIRECT: address.`
+      `Cannot resolve transport pubkey for "${recipient}". No binding event found. The recipient must publish their identity first.`
     );
   }
   /**
@@ -4834,7 +5893,7 @@ var PaymentsModule = class {
     const tokenData = token.sdkData ? typeof token.sdkData === "string" ? JSON.parse(token.sdkData) : token.sdkData : token;
     const sdkToken = await SdkToken2.fromJSON(tokenData);
     const salt = crypto.getRandomValues(new Uint8Array(32));
-    const commitment = await TransferCommitment2.create(
+    const commitment = await TransferCommitment4.create(
       sdkToken,
       recipientAddress,
       salt,
@@ -4860,75 +5919,264 @@ var PaymentsModule = class {
    * Create DirectAddress from a public key using UnmaskedPredicateReference
    */
   async createDirectAddressFromPubkey(pubkeyHex) {
-    const { UnmaskedPredicateReference: UnmaskedPredicateReference3 } = await import("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
-    const { TokenType: TokenType3 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+    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 UNICITY_TOKEN_TYPE_HEX3 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
-    const tokenType = new TokenType3(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
+    const tokenType = new TokenType5(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
     const pubkeyBytes = new Uint8Array(
       pubkeyHex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16))
     );
-    const addressRef = await UnmaskedPredicateReference3.create(
+    const addressRef = await UnmaskedPredicateReference4.create(
       tokenType,
       "secp256k1",
       pubkeyBytes,
-      HashAlgorithm3.SHA256
+      HashAlgorithm5.SHA256
     );
     return addressRef.toAddress();
   }
   /**
-   * Resolve nametag to 33-byte compressed public key using resolveNametagInfo
-   * Returns null if nametag not found or publicKey not available
+   * Resolve recipient to IAddress for L3 transfers.
+   * Uses pre-resolved PeerInfo when available to avoid redundant network queries.
    */
-  async resolveNametagToPublicKey(nametag) {
-    if (!this.deps?.transport.resolveNametagInfo) {
-      this.log("resolveNametagInfo not available on transport");
-      return null;
+  async resolveRecipientAddress(recipient, addressMode = "auto", peerInfo) {
+    const { AddressFactory } = await import("@unicitylabs/state-transition-sdk/lib/address/AddressFactory");
+    const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
+    if (recipient.startsWith("PROXY:") || recipient.startsWith("DIRECT:")) {
+      return AddressFactory.createAddress(recipient);
     }
-    const info = await this.deps.transport.resolveNametagInfo(nametag);
+    if (recipient.length === 66 && /^[0-9a-fA-F]+$/.test(recipient)) {
+      this.log(`Creating DirectAddress from 33-byte compressed pubkey`);
+      return this.createDirectAddressFromPubkey(recipient);
+    }
+    const info = peerInfo ?? await this.deps?.transport.resolve?.(recipient) ?? null;
     if (!info) {
-      this.log(`Nametag "${nametag}" not found`);
-      return null;
+      throw new Error(
+        `Recipient "${recipient}" not found. Use @nametag, a valid PROXY:/DIRECT: address, or a 33-byte hex pubkey.`
+      );
     }
-    if (!info.chainPubkey) {
-      this.log(`Nametag "${nametag}" has no 33-byte chainPubkey (legacy event)`);
-      return null;
+    const nametag = recipient.startsWith("@") ? recipient.slice(1) : info.nametag || recipient;
+    if (addressMode === "proxy") {
+      console.log(`[Payments] Using PROXY address for "${nametag}" (forced)`);
+      return ProxyAddress.fromNameTag(nametag);
     }
-    return info.chainPubkey;
+    if (addressMode === "direct") {
+      if (!info.directAddress) {
+        throw new Error(`"${nametag}" has no DirectAddress stored. It may be a legacy registration.`);
+      }
+      console.log(`[Payments] Using DirectAddress for "${nametag}" (forced): ${info.directAddress.slice(0, 30)}...`);
+      return AddressFactory.createAddress(info.directAddress);
+    }
+    if (info.directAddress) {
+      this.log(`Using DirectAddress for "${nametag}": ${info.directAddress.slice(0, 30)}...`);
+      return AddressFactory.createAddress(info.directAddress);
+    }
+    this.log(`Using PROXY address for legacy nametag "${nametag}"`);
+    return ProxyAddress.fromNameTag(nametag);
   }
   /**
-   * Resolve recipient to IAddress for L3 transfers
-   * Supports: nametag (with or without @), PROXY:, DIRECT:, hex pubkey
+   * Handle NOSTR-FIRST commitment-only transfer (recipient side)
+   * This is called when receiving a transfer with only commitmentData and no proof yet.
+   * We create the token as 'submitted', submit commitment (idempotent), and poll for proof.
    */
-  async resolveRecipientAddress(recipient) {
-    const { AddressFactory } = await import("@unicitylabs/state-transition-sdk/lib/address/AddressFactory");
-    if (recipient.startsWith("@")) {
-      const nametag = recipient.slice(1);
-      const publicKey2 = await this.resolveNametagToPublicKey(nametag);
-      if (publicKey2) {
-        this.log(`Resolved @${nametag} to 33-byte publicKey for DirectAddress`);
-        return this.createDirectAddressFromPubkey(publicKey2);
+  async handleCommitmentOnlyTransfer(transfer, payload) {
+    try {
+      const sourceTokenInput = typeof payload.sourceToken === "string" ? JSON.parse(payload.sourceToken) : payload.sourceToken;
+      const commitmentInput = typeof payload.commitmentData === "string" ? JSON.parse(payload.commitmentData) : payload.commitmentData;
+      if (!sourceTokenInput || !commitmentInput) {
+        console.warn("[Payments] Invalid NOSTR-FIRST transfer format");
+        return;
       }
-      throw new Error(`Nametag "${nametag}" not found or missing publicKey`);
-    }
-    if (recipient.startsWith("PROXY:") || recipient.startsWith("DIRECT:")) {
-      return AddressFactory.createAddress(recipient);
-    }
-    if (recipient.length === 66 && /^[0-9a-fA-F]+$/.test(recipient)) {
-      this.log(`Creating DirectAddress from 33-byte compressed pubkey`);
-      return this.createDirectAddressFromPubkey(recipient);
+      const tokenInfo = await parseTokenInfo(sourceTokenInput);
+      const token = {
+        id: tokenInfo.tokenId ?? crypto.randomUUID(),
+        coinId: tokenInfo.coinId,
+        symbol: tokenInfo.symbol,
+        name: tokenInfo.name,
+        decimals: tokenInfo.decimals,
+        iconUrl: tokenInfo.iconUrl,
+        amount: tokenInfo.amount,
+        status: "submitted",
+        // NOSTR-FIRST: unconfirmed until proof
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        sdkData: typeof sourceTokenInput === "string" ? sourceTokenInput : JSON.stringify(sourceTokenInput)
+      };
+      const nostrTokenId = extractTokenIdFromSdkData(token.sdkData);
+      const nostrStateHash = extractStateHashFromSdkData(token.sdkData);
+      if (nostrTokenId && nostrStateHash && this.isStateTombstoned(nostrTokenId, nostrStateHash)) {
+        this.log(`NOSTR-FIRST: Rejecting tombstoned token ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`);
+        return;
+      }
+      this.tokens.set(token.id, token);
+      await this.save();
+      this.log(`NOSTR-FIRST: Token ${token.id.slice(0, 8)}... added as submitted (unconfirmed)`);
+      const incomingTransfer = {
+        id: transfer.id,
+        senderPubkey: transfer.senderTransportPubkey,
+        tokens: [token],
+        memo: payload.memo,
+        receivedAt: transfer.timestamp
+      };
+      this.deps.emitEvent("transfer:incoming", incomingTransfer);
+      try {
+        const commitment = await TransferCommitment4.fromJSON(commitmentInput);
+        const requestIdBytes = commitment.requestId;
+        const requestIdHex = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
+        const stClient = this.deps.oracle.getStateTransitionClient?.();
+        if (stClient) {
+          const response = await stClient.submitTransferCommitment(commitment);
+          this.log(`NOSTR-FIRST recipient commitment submit: ${response.status}`);
+        }
+        this.addProofPollingJob({
+          tokenId: token.id,
+          requestIdHex,
+          commitmentJson: JSON.stringify(commitmentInput),
+          startedAt: Date.now(),
+          attemptCount: 0,
+          lastAttemptAt: 0,
+          onProofReceived: async (tokenId) => {
+            await this.finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput, transfer.senderTransportPubkey);
+          }
+        });
+      } catch (err) {
+        console.error("[Payments] Failed to parse commitment for proof polling:", err);
+      }
+    } catch (error) {
+      console.error("[Payments] Failed to process NOSTR-FIRST transfer:", error);
     }
-    const publicKey = await this.resolveNametagToPublicKey(recipient);
-    if (publicKey) {
-      this.log(`Resolved "${recipient}" as nametag to 33-byte publicKey for DirectAddress`);
-      return this.createDirectAddressFromPubkey(publicKey);
+  }
+  /**
+   * Shared finalization logic for received transfers.
+   * Handles both PROXY (with nametag token + address validation) and DIRECT schemes.
+   */
+  async finalizeTransferToken(sourceToken, transferTx, stClient, trustBase) {
+    const recipientAddress = transferTx.data.recipient;
+    const addressScheme = recipientAddress.scheme;
+    const signingService = await this.createSigningService();
+    const transferSalt = transferTx.data.salt;
+    const recipientPredicate = await UnmaskedPredicate5.create(
+      sourceToken.id,
+      sourceToken.type,
+      signingService,
+      HashAlgorithm5.SHA256,
+      transferSalt
+    );
+    const recipientState = new TokenState5(recipientPredicate, null);
+    let nametagTokens = [];
+    if (addressScheme === AddressScheme.PROXY) {
+      const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
+      if (!this.nametag?.token) {
+        throw new Error("Cannot finalize PROXY transfer - no nametag token");
+      }
+      const nametagToken = await SdkToken2.fromJSON(this.nametag.token);
+      const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
+      if (proxy.address !== recipientAddress.address) {
+        throw new Error(
+          `PROXY address mismatch: nametag resolves to ${proxy.address} but transfer targets ${recipientAddress.address}`
+        );
+      }
+      nametagTokens = [nametagToken];
     }
-    throw new Error(
-      `Recipient "${recipient}" is not a valid nametag or L3 address. Use @nametag for explicit nametag or a valid 33-byte hex pubkey/PROXY:/DIRECT: address.`
+    return stClient.finalizeTransaction(
+      trustBase,
+      sourceToken,
+      recipientState,
+      transferTx,
+      nametagTokens
     );
   }
+  /**
+   * Finalize a received token after proof is available
+   */
+  async finalizeReceivedToken(tokenId, sourceTokenInput, commitmentInput, senderPubkey) {
+    try {
+      const token = this.tokens.get(tokenId);
+      if (!token) {
+        this.log(`Token ${tokenId} not found for finalization`);
+        return;
+      }
+      const commitment = await TransferCommitment4.fromJSON(commitmentInput);
+      if (!this.deps.oracle.waitForProofSdk) {
+        this.log("Cannot finalize - no waitForProofSdk");
+        token.status = "confirmed";
+        token.updatedAt = Date.now();
+        await this.save();
+        return;
+      }
+      const inclusionProof = await this.deps.oracle.waitForProofSdk(commitment);
+      const transferTx = commitment.toTransaction(inclusionProof);
+      const sourceToken = await SdkToken2.fromJSON(sourceTokenInput);
+      const stClient = this.deps.oracle.getStateTransitionClient?.();
+      const trustBase = this.deps.oracle.getTrustBase?.();
+      if (!stClient || !trustBase) {
+        this.log("Cannot finalize - missing state transition client or trust base");
+        token.status = "confirmed";
+        token.updatedAt = Date.now();
+        await this.save();
+        return;
+      }
+      const finalizedSdkToken = await this.finalizeTransferToken(
+        sourceToken,
+        transferTx,
+        stClient,
+        trustBase
+      );
+      const finalizedToken = {
+        ...token,
+        status: "confirmed",
+        updatedAt: Date.now(),
+        sdkData: JSON.stringify(finalizedSdkToken.toJSON())
+      };
+      this.tokens.set(tokenId, finalizedToken);
+      await this.save();
+      await this.saveTokenToFileStorage(finalizedToken);
+      this.log(`NOSTR-FIRST: Token ${tokenId.slice(0, 8)}... finalized and confirmed`);
+      this.deps.emitEvent("transfer:confirmed", {
+        id: crypto.randomUUID(),
+        status: "completed",
+        tokens: [finalizedToken]
+      });
+      await this.addToHistory({
+        type: "RECEIVED",
+        amount: finalizedToken.amount,
+        coinId: finalizedToken.coinId,
+        symbol: finalizedToken.symbol,
+        timestamp: Date.now(),
+        senderPubkey
+      });
+    } catch (error) {
+      console.error("[Payments] Failed to finalize received token:", error);
+      const token = this.tokens.get(tokenId);
+      if (token && token.status === "submitted") {
+        token.status = "confirmed";
+        token.updatedAt = Date.now();
+        await this.save();
+      }
+    }
+  }
   async handleIncomingTransfer(transfer) {
     try {
       const payload = transfer.payload;
+      if (isInstantSplitBundle(payload)) {
+        this.log("Processing INSTANT_SPLIT bundle...");
+        try {
+          if (!this.nametag) {
+            await this.loadNametagFromFileStorage();
+          }
+          const result = await this.processInstantSplitBundle(
+            payload,
+            transfer.senderTransportPubkey
+          );
+          if (result.success) {
+            this.log("INSTANT_SPLIT processed successfully");
+          } else {
+            console.warn("[Payments] INSTANT_SPLIT processing failed:", result.error);
+          }
+        } catch (err) {
+          console.error("[Payments] INSTANT_SPLIT processing error:", err);
+        }
+        return;
+      }
       let tokenData;
       let finalizedSdkToken = null;
       if (payload.sourceToken && payload.transferTx) {
@@ -4939,82 +6187,71 @@ var PaymentsModule = class {
           console.warn("[Payments] Invalid Sphere wallet transfer format");
           return;
         }
-        const sourceToken = await SdkToken2.fromJSON(sourceTokenInput);
-        const transferTx = await TransferTransaction.fromJSON(transferTxInput);
-        const recipientAddress = transferTx.data.recipient;
-        const addressScheme = recipientAddress.scheme;
-        if (addressScheme === AddressScheme.PROXY) {
-          if (!this.nametag?.token) {
-            console.error("[Payments] Cannot finalize PROXY transfer - no nametag token. Token rejected.");
-            return;
-          }
-          {
-            try {
-              const nametagToken = await SdkToken2.fromJSON(this.nametag.token);
-              const signingService = await this.createSigningService();
-              const transferSalt = transferTx.data.salt;
-              const recipientPredicate = await UnmaskedPredicate3.create(
-                sourceToken.id,
-                sourceToken.type,
-                signingService,
-                HashAlgorithm3.SHA256,
-                transferSalt
-              );
-              const recipientState = new TokenState3(recipientPredicate, null);
-              const stClient = this.deps.oracle.getStateTransitionClient?.();
-              const trustBase = this.deps.oracle.getTrustBase?.();
-              if (!stClient || !trustBase) {
-                console.error("[Payments] Cannot finalize - missing state transition client or trust base. Token rejected.");
-                return;
-              }
-              finalizedSdkToken = await stClient.finalizeTransaction(
-                trustBase,
-                sourceToken,
-                recipientState,
-                transferTx,
-                [nametagToken]
-              );
-              tokenData = finalizedSdkToken.toJSON();
-              this.log("Token finalized successfully");
-            } catch (finalizeError) {
-              console.error("[Payments] Finalization failed:", finalizeError);
+        let sourceToken;
+        let transferTx;
+        try {
+          sourceToken = await SdkToken2.fromJSON(sourceTokenInput);
+        } catch (err) {
+          console.error("[Payments] Failed to parse sourceToken:", err);
+          return;
+        }
+        try {
+          const hasInclusionProof = transferTxInput.inclusionProof !== void 0;
+          const hasData = transferTxInput.data !== void 0;
+          const hasTransactionData = transferTxInput.transactionData !== void 0;
+          const hasAuthenticator = transferTxInput.authenticator !== void 0;
+          if (hasData && hasInclusionProof) {
+            transferTx = await TransferTransaction2.fromJSON(transferTxInput);
+          } else if (hasTransactionData && hasAuthenticator) {
+            const commitment = await TransferCommitment4.fromJSON(transferTxInput);
+            const stClient = this.deps.oracle.getStateTransitionClient?.();
+            if (!stClient) {
+              console.error("[Payments] Cannot process commitment - no state transition client");
               return;
             }
-          }
-        } else {
-          this.log("Finalizing DIRECT address transfer for state tracking...");
-          try {
-            const signingService = await this.createSigningService();
-            const transferSalt = transferTx.data.salt;
-            const recipientPredicate = await UnmaskedPredicate3.create(
-              sourceToken.id,
-              sourceToken.type,
-              signingService,
-              HashAlgorithm3.SHA256,
-              transferSalt
-            );
-            const recipientState = new TokenState3(recipientPredicate, null);
-            const stClient = this.deps.oracle.getStateTransitionClient?.();
-            const trustBase = this.deps.oracle.getTrustBase?.();
-            if (!stClient || !trustBase) {
-              this.log("Cannot finalize DIRECT transfer - missing client, using source token");
-              tokenData = sourceTokenInput;
-            } else {
-              finalizedSdkToken = await stClient.finalizeTransaction(
-                trustBase,
-                sourceToken,
-                recipientState,
-                transferTx,
-                []
-                // No nametag tokens needed for DIRECT
-              );
-              tokenData = finalizedSdkToken.toJSON();
-              this.log("DIRECT transfer finalized successfully");
+            const response = await stClient.submitTransferCommitment(commitment);
+            if (response.status !== "SUCCESS" && response.status !== "REQUEST_ID_EXISTS") {
+              console.error("[Payments] Transfer commitment submission failed:", response.status);
+              return;
+            }
+            if (!this.deps.oracle.waitForProofSdk) {
+              console.error("[Payments] Cannot wait for proof - missing oracle method");
+              return;
+            }
+            const inclusionProof = await this.deps.oracle.waitForProofSdk(commitment);
+            transferTx = commitment.toTransaction(inclusionProof);
+          } else {
+            try {
+              transferTx = await TransferTransaction2.fromJSON(transferTxInput);
+            } catch {
+              const commitment = await TransferCommitment4.fromJSON(transferTxInput);
+              const stClient = this.deps.oracle.getStateTransitionClient?.();
+              if (!stClient || !this.deps.oracle.waitForProofSdk) {
+                throw new Error("Cannot submit commitment - missing oracle methods");
+              }
+              await stClient.submitTransferCommitment(commitment);
+              const inclusionProof = await this.deps.oracle.waitForProofSdk(commitment);
+              transferTx = commitment.toTransaction(inclusionProof);
             }
-          } catch (finalizeError) {
-            this.log("DIRECT finalization failed, using source token:", finalizeError);
-            tokenData = sourceTokenInput;
           }
+        } catch (err) {
+          console.error("[Payments] Failed to parse transferTx:", err);
+          return;
+        }
+        try {
+          const stClient = this.deps.oracle.getStateTransitionClient?.();
+          const trustBase = this.deps.oracle.getTrustBase?.();
+          if (!stClient || !trustBase) {
+            console.error("[Payments] Cannot finalize - missing state transition client or trust base. Token rejected.");
+            return;
+          }
+          finalizedSdkToken = await this.finalizeTransferToken(sourceToken, transferTx, stClient, trustBase);
+          tokenData = finalizedSdkToken.toJSON();
+          const addressScheme = transferTx.data.recipient.scheme;
+          this.log(`${addressScheme === AddressScheme.PROXY ? "PROXY" : "DIRECT"} finalization successful`);
+        } catch (finalizeError) {
+          console.error(`[Payments] Finalization FAILED - token rejected:`, finalizeError);
+          return;
         }
       } else if (payload.token) {
         tokenData = payload.token;
@@ -5041,12 +6278,6 @@ var PaymentsModule = class {
         updatedAt: Date.now(),
         sdkData: typeof tokenData === "string" ? tokenData : JSON.stringify(tokenData)
       };
-      const sdkTokenId = extractTokenIdFromSdkData(token.sdkData);
-      const stateHash = extractStateHashFromSdkData(token.sdkData);
-      if (sdkTokenId && stateHash && this.isStateTombstoned(sdkTokenId, stateHash)) {
-        this.log(`Rejected tombstoned token ${sdkTokenId.slice(0, 8)}...`);
-        return;
-      }
       await this.addToken(token);
       const incomingTransfer = {
         id: transfer.id,
@@ -5134,14 +6365,159 @@ var PaymentsModule = class {
   }
   loadFromStorageData(data) {
     const parsed = parseTxfStorageData(data);
+    this.tombstones = parsed.tombstones;
     this.tokens.clear();
     for (const token of parsed.tokens) {
+      const sdkTokenId = extractTokenIdFromSdkData(token.sdkData);
+      const stateHash = extractStateHashFromSdkData(token.sdkData);
+      if (sdkTokenId && stateHash && this.isStateTombstoned(sdkTokenId, stateHash)) {
+        this.log(`Skipping tombstoned token ${sdkTokenId.slice(0, 8)}... during load (exact state match)`);
+        continue;
+      }
       this.tokens.set(token.id, token);
     }
-    this.tombstones = parsed.tombstones;
     this.archivedTokens = parsed.archivedTokens;
     this.forkedTokens = parsed.forkedTokens;
-    this.nametag = parsed.nametag;
+    if (parsed.nametag !== null) {
+      this.nametag = parsed.nametag;
+    }
+  }
+  // ===========================================================================
+  // Private: NOSTR-FIRST Proof Polling
+  // ===========================================================================
+  /**
+   * Submit commitment to aggregator and start background proof polling
+   * (NOSTR-FIRST pattern: fire-and-forget submission)
+   */
+  async submitAndPollForProof(tokenId, commitment, requestIdHex, onProofReceived) {
+    try {
+      const stClient = this.deps.oracle.getStateTransitionClient?.();
+      if (!stClient) {
+        this.log("Cannot submit commitment - no state transition client");
+        return;
+      }
+      const response = await stClient.submitTransferCommitment(commitment);
+      if (response.status !== "SUCCESS" && response.status !== "REQUEST_ID_EXISTS") {
+        this.log(`Transfer commitment submission failed: ${response.status}`);
+        const token = this.tokens.get(tokenId);
+        if (token) {
+          token.status = "invalid";
+          token.updatedAt = Date.now();
+          this.tokens.set(tokenId, token);
+          await this.save();
+        }
+        return;
+      }
+      this.addProofPollingJob({
+        tokenId,
+        requestIdHex,
+        commitmentJson: JSON.stringify(commitment.toJSON()),
+        startedAt: Date.now(),
+        attemptCount: 0,
+        lastAttemptAt: 0,
+        onProofReceived
+      });
+    } catch (error) {
+      this.log("submitAndPollForProof error:", error);
+    }
+  }
+  /**
+   * Add a proof polling job to the queue
+   */
+  addProofPollingJob(job) {
+    this.proofPollingJobs.set(job.tokenId, job);
+    this.log(`Added proof polling job for token ${job.tokenId.slice(0, 8)}...`);
+    this.startProofPolling();
+  }
+  /**
+   * Start the proof polling interval if not already running
+   */
+  startProofPolling() {
+    if (this.proofPollingInterval) return;
+    if (this.proofPollingJobs.size === 0) return;
+    this.log("Starting proof polling...");
+    this.proofPollingInterval = setInterval(
+      () => this.processProofPollingQueue(),
+      _PaymentsModule.PROOF_POLLING_INTERVAL_MS
+    );
+  }
+  /**
+   * Stop the proof polling interval
+   */
+  stopProofPolling() {
+    if (this.proofPollingInterval) {
+      clearInterval(this.proofPollingInterval);
+      this.proofPollingInterval = null;
+      this.log("Stopped proof polling");
+    }
+  }
+  /**
+   * Process all pending proof polling jobs
+   */
+  async processProofPollingQueue() {
+    if (this.proofPollingJobs.size === 0) {
+      this.stopProofPolling();
+      return;
+    }
+    const completedJobs = [];
+    for (const [tokenId, job] of this.proofPollingJobs) {
+      try {
+        job.attemptCount++;
+        job.lastAttemptAt = Date.now();
+        if (job.attemptCount >= _PaymentsModule.PROOF_POLLING_MAX_ATTEMPTS) {
+          this.log(`Proof polling timeout for token ${tokenId.slice(0, 8)}...`);
+          const token2 = this.tokens.get(tokenId);
+          if (token2 && token2.status === "submitted") {
+            token2.status = "invalid";
+            token2.updatedAt = Date.now();
+            this.tokens.set(tokenId, token2);
+          }
+          completedJobs.push(tokenId);
+          continue;
+        }
+        const commitment = await TransferCommitment4.fromJSON(JSON.parse(job.commitmentJson));
+        let inclusionProof = null;
+        try {
+          const abortController = new AbortController();
+          const timeoutId = setTimeout(() => abortController.abort(), 500);
+          if (this.deps.oracle.waitForProofSdk) {
+            inclusionProof = await Promise.race([
+              this.deps.oracle.waitForProofSdk(commitment, abortController.signal),
+              new Promise((resolve) => setTimeout(() => resolve(null), 500))
+            ]);
+          } else {
+            const proof = await this.deps.oracle.getProof(job.requestIdHex);
+            if (proof) {
+              inclusionProof = proof;
+            }
+          }
+          clearTimeout(timeoutId);
+        } catch (err) {
+          continue;
+        }
+        if (!inclusionProof) {
+          continue;
+        }
+        const token = this.tokens.get(tokenId);
+        if (token) {
+          token.status = "spent";
+          token.updatedAt = Date.now();
+          this.tokens.set(tokenId, token);
+          await this.save();
+          this.log(`Proof received for token ${tokenId.slice(0, 8)}..., status: spent`);
+        }
+        job.onProofReceived?.(tokenId);
+        completedJobs.push(tokenId);
+      } catch (error) {
+        this.log(`Proof polling attempt ${job.attemptCount} for ${tokenId.slice(0, 8)}...: ${error}`);
+      }
+    }
+    for (const tokenId of completedJobs) {
+      this.proofPollingJobs.delete(tokenId);
+    }
+    if (this.proofPollingJobs.size === 0) {
+      this.stopProofPolling();
+    }
   }
   // ===========================================================================
   // Private: Helpers
@@ -5156,6 +6532,14 @@ function createPaymentsModule(config) {
   return new PaymentsModule(config);
 }
 
+// modules/payments/TokenRecoveryService.ts
+import { TokenId as TokenId4 } from "@unicitylabs/state-transition-sdk/lib/token/TokenId";
+import { TokenState as TokenState6 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
+import { TokenType as TokenType3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
+import { CoinId as CoinId5 } from "@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId";
+import { HashAlgorithm as HashAlgorithm6 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
+import { UnmaskedPredicate as UnmaskedPredicate6 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
+
 // modules/communications/CommunicationsModule.ts
 var CommunicationsModule = class {
   config;
@@ -6124,20 +7508,20 @@ async function parseAndDecryptWalletDat(data, password, onProgress) {
 
 // core/Sphere.ts
 import { SigningService as SigningService2 } from "@unicitylabs/state-transition-sdk/lib/sign/SigningService";
-import { TokenType as TokenType2 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
-import { HashAlgorithm as HashAlgorithm4 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
-import { UnmaskedPredicateReference as UnmaskedPredicateReference2 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference";
+import { TokenType as TokenType4 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
+import { HashAlgorithm as HashAlgorithm7 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
+import { UnmaskedPredicateReference as UnmaskedPredicateReference3 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference";
 var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
 async function deriveL3PredicateAddress(privateKey) {
   const secret = Buffer.from(privateKey, "hex");
   const signingService = await SigningService2.createFromSecret(secret);
   const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
-  const tokenType = new TokenType2(tokenTypeBytes);
-  const predicateRef = UnmaskedPredicateReference2.create(
+  const tokenType = new TokenType4(tokenTypeBytes);
+  const predicateRef = UnmaskedPredicateReference3.create(
     tokenType,
     signingService.algorithm,
     signingService.publicKey,
-    HashAlgorithm4.SHA256
+    HashAlgorithm7.SHA256
   );
   return (await (await predicateRef).toAddress()).toString();
 }
@@ -6153,7 +7537,11 @@ var Sphere = class _Sphere {
   _derivationMode = "bip32";
   _basePath = DEFAULT_BASE_PATH;
   _currentAddressIndex = 0;
-  /** Map of addressId -> (nametagIndex -> nametag). Supports multiple nametags per address (e.g., from Nostr recovery) */
+  /** Registry of all tracked (activated) addresses, keyed by HD index */
+  _trackedAddresses = /* @__PURE__ */ new Map();
+  /** Reverse lookup: addressId -> HD index */
+  _addressIdToIndex = /* @__PURE__ */ new Map();
+  /** Nametag cache: addressId -> (nametagIndex -> nametag). Separate from tracked addresses. */
   _addressNametags = /* @__PURE__ */ new Map();
   /** Cached PROXY address (computed once when nametag is set) */
   _cachedProxyAddress = void 0;
@@ -6162,6 +7550,7 @@ var Sphere = class _Sphere {
   _tokenStorageProviders = /* @__PURE__ */ new Map();
   _transport;
   _oracle;
+  _priceProvider;
   // Modules
   _payments;
   _communications;
@@ -6170,10 +7559,11 @@ var Sphere = class _Sphere {
   // ===========================================================================
   // Constructor (private)
   // ===========================================================================
-  constructor(storage, transport, oracle, tokenStorage, l1Config) {
+  constructor(storage, transport, oracle, tokenStorage, l1Config, priceProvider) {
     this._storage = storage;
     this._transport = transport;
     this._oracle = oracle;
+    this._priceProvider = priceProvider ?? null;
     if (tokenStorage) {
       this._tokenStorageProviders.set(tokenStorage.id, tokenStorage);
     }
@@ -6233,7 +7623,8 @@ var Sphere = class _Sphere {
         transport: options.transport,
         oracle: options.oracle,
         tokenStorage: options.tokenStorage,
-        l1: options.l1
+        l1: options.l1,
+        price: options.price
       });
       return { sphere: sphere2, created: false };
     }
@@ -6257,7 +7648,8 @@ var Sphere = class _Sphere {
       tokenStorage: options.tokenStorage,
       derivationPath: options.derivationPath,
       nametag: options.nametag,
-      l1: options.l1
+      l1: options.l1,
+      price: options.price
     });
     return { sphere, created: true, generatedMnemonic };
   }
@@ -6276,7 +7668,8 @@ var Sphere = class _Sphere {
       options.transport,
       options.oracle,
       options.tokenStorage,
-      options.l1
+      options.l1,
+      options.price
     );
     await sphere.storeMnemonic(options.mnemonic, options.derivationPath);
     await sphere.initializeIdentityFromMnemonic(options.mnemonic, options.derivationPath);
@@ -6285,10 +7678,12 @@ var Sphere = class _Sphere {
     await sphere.finalizeWalletCreation();
     sphere._initialized = true;
     _Sphere.instance = sphere;
+    await sphere.ensureAddressTracked(0);
     if (options.nametag) {
       await sphere.registerNametag(options.nametag);
     } else {
-      await sphere.recoverNametagFromNostr();
+      await sphere.syncIdentityWithTransport();
+      await sphere.recoverNametagFromTransport();
     }
     return sphere;
   }
@@ -6304,14 +7699,28 @@ var Sphere = class _Sphere {
       options.transport,
       options.oracle,
       options.tokenStorage,
-      options.l1
+      options.l1,
+      options.price
     );
     await sphere.loadIdentityFromStorage();
     await sphere.initializeProviders();
     await sphere.initializeModules();
-    await sphere.syncNametagWithNostr();
+    await sphere.syncIdentityWithTransport();
     sphere._initialized = true;
     _Sphere.instance = sphere;
+    if (sphere._identity?.nametag && !sphere._payments.hasNametag()) {
+      console.log(`[Sphere] Nametag @${sphere._identity.nametag} has no token, attempting to mint...`);
+      try {
+        const result = await sphere.mintNametag(sphere._identity.nametag);
+        if (result.success) {
+          console.log(`[Sphere] Nametag token minted successfully on load`);
+        } else {
+          console.warn(`[Sphere] Could not mint nametag token: ${result.error}`);
+        }
+      } catch (err) {
+        console.warn(`[Sphere] Nametag token mint failed:`, err);
+      }
+    }
     return sphere;
   }
   /**
@@ -6327,7 +7736,8 @@ var Sphere = class _Sphere {
       options.transport,
       options.oracle,
       options.tokenStorage,
-      options.l1
+      options.l1,
+      options.price
     );
     if (options.mnemonic) {
       if (!_Sphere.validateMnemonic(options.mnemonic)) {
@@ -6352,11 +7762,12 @@ var Sphere = class _Sphere {
     await sphere.initializeProviders();
     await sphere.initializeModules();
     if (!options.nametag) {
-      await sphere.recoverNametagFromNostr();
+      await sphere.recoverNametagFromTransport();
     }
     await sphere.finalizeWalletCreation();
     sphere._initialized = true;
     _Sphere.instance = sphere;
+    await sphere.ensureAddressTracked(0);
     if (options.nametag) {
       await sphere.registerNametag(options.nametag);
     }
@@ -6392,6 +7803,7 @@ var Sphere = class _Sphere {
     await storage.remove(STORAGE_KEYS_GLOBAL.DERIVATION_MODE);
     await storage.remove(STORAGE_KEYS_GLOBAL.WALLET_SOURCE);
     await storage.remove(STORAGE_KEYS_GLOBAL.WALLET_EXISTS);
+    await storage.remove(STORAGE_KEYS_GLOBAL.TRACKED_ADDRESSES);
     await storage.remove(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS);
     await storage.remove(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
     await storage.remove(STORAGE_KEYS_ADDRESS.OUTBOX);
@@ -6516,6 +7928,13 @@ var Sphere = class _Sphere {
   hasTokenStorageProvider(providerId) {
     return this._tokenStorageProviders.has(providerId);
   }
+  /**
+   * Set or update the price provider after initialization
+   */
+  setPriceProvider(provider) {
+    this._priceProvider = provider;
+    this._payments.setPriceProvider(provider);
+  }
   getTransport() {
     return this._transport;
   }
@@ -7003,10 +8422,9 @@ var Sphere = class _Sphere {
    * @returns Primary nametag (index 0) or undefined if not registered
    */
   getNametagForAddress(addressId) {
-    const id = addressId ?? this.getCurrentAddressId();
+    const id = addressId ?? this._trackedAddresses.get(this._currentAddressIndex)?.addressId;
     if (!id) return void 0;
-    const nametagsMap = this._addressNametags.get(id);
-    return nametagsMap?.get(0);
+    return this._addressNametags.get(id)?.get(0);
   }
   /**
    * Get all nametags for a specific address
@@ -7015,29 +8433,89 @@ var Sphere = class _Sphere {
    * @returns Map of nametagIndex to nametag, or undefined if no nametags
    */
   getNametagsForAddress(addressId) {
-    const id = addressId ?? this.getCurrentAddressId();
+    const id = addressId ?? this._trackedAddresses.get(this._currentAddressIndex)?.addressId;
     if (!id) return void 0;
-    const nametagsMap = this._addressNametags.get(id);
-    return nametagsMap ? new Map(nametagsMap) : void 0;
+    const nametags = this._addressNametags.get(id);
+    return nametags && nametags.size > 0 ? new Map(nametags) : void 0;
   }
   /**
    * Get all registered address nametags
-   *
+   * @deprecated Use getActiveAddresses() or getAllTrackedAddresses() instead
    * @returns Map of addressId to (nametagIndex -> nametag)
    */
   getAllAddressNametags() {
     const result = /* @__PURE__ */ new Map();
-    this._addressNametags.forEach((nametagsMap, addressId) => {
-      result.set(addressId, new Map(nametagsMap));
-    });
+    for (const [addressId, nametags] of this._addressNametags.entries()) {
+      if (nametags.size > 0) {
+        result.set(addressId, new Map(nametags));
+      }
+    }
     return result;
   }
   /**
-   * Get current address identifier (DIRECT://xxx format)
+   * Get all active (non-hidden) tracked addresses.
+   * Returns addresses that have been activated through create, switchToAddress,
+   * registerNametag, or nametag recovery.
+   *
+   * @returns Array of TrackedAddress entries sorted by index, excluding hidden ones
+   */
+  getActiveAddresses() {
+    this.ensureReady();
+    const result = [];
+    for (const entry of this._trackedAddresses.values()) {
+      if (!entry.hidden) {
+        const nametag = this._addressNametags.get(entry.addressId)?.get(0);
+        result.push({ ...entry, nametag });
+      }
+    }
+    return result.sort((a, b) => a.index - b.index);
+  }
+  /**
+   * Get all tracked addresses, including hidden ones.
+   *
+   * @returns Array of all TrackedAddress entries sorted by index
+   */
+  getAllTrackedAddresses() {
+    this.ensureReady();
+    const result = [];
+    for (const entry of this._trackedAddresses.values()) {
+      const nametag = this._addressNametags.get(entry.addressId)?.get(0);
+      result.push({ ...entry, nametag });
+    }
+    return result.sort((a, b) => a.index - b.index);
+  }
+  /**
+   * Get tracked address info by index.
+   *
+   * @param index - Address index
+   * @returns TrackedAddress or undefined if not tracked
+   */
+  getTrackedAddress(index) {
+    this.ensureReady();
+    const entry = this._trackedAddresses.get(index);
+    if (!entry) return void 0;
+    const nametag = this._addressNametags.get(entry.addressId)?.get(0);
+    return { ...entry, nametag };
+  }
+  /**
+   * Set visibility of a tracked address.
+   * Hidden addresses are not returned by getActiveAddresses() but remain tracked.
+   *
+   * @param index - Address index to hide/unhide
+   * @param hidden - true to hide, false to show
+   * @throws Error if address index is not tracked
    */
-  getCurrentAddressId() {
-    if (!this._identity?.directAddress) return void 0;
-    return getAddressId(this._identity.directAddress);
+  async setAddressHidden(index, hidden) {
+    this.ensureReady();
+    const entry = this._trackedAddresses.get(index);
+    if (!entry) {
+      throw new Error(`Address at index ${index} is not tracked. Switch to it first.`);
+    }
+    if (entry.hidden === hidden) return;
+    entry.hidden = hidden;
+    await this.persistTrackedAddresses();
+    const eventType = hidden ? "address:hidden" : "address:unhidden";
+    this.emitEvent(eventType, { index, addressId: entry.addressId });
   }
   /**
    * Switch to a different address by index
@@ -7058,7 +8536,7 @@ var Sphere = class _Sphere {
    * await sphere.switchToAddress(0);
    * ```
    */
-  async switchToAddress(index) {
+  async switchToAddress(index, options) {
     this.ensureReady();
     if (!this._masterKey) {
       throw new Error("HD derivation requires master key with chain code. Cannot switch addresses.");
@@ -7066,12 +8544,28 @@ 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 addressInfo = this.deriveAddress(index, false);
     const ipnsHash = sha256(addressInfo.publicKey, "hex").slice(0, 40);
     const predicateAddress = await deriveL3PredicateAddress(addressInfo.privateKey);
+    await this.ensureAddressTracked(index);
     const addressId = getAddressId(predicateAddress);
-    const nametagsMap = this._addressNametags.get(addressId);
-    const nametag = nametagsMap?.get(0);
+    if (newNametag) {
+      const existing = await this._transport.resolveNametag?.(newNametag);
+      if (existing) {
+        throw new Error(`Nametag @${newNametag} is already taken`);
+      }
+      let nametags = this._addressNametags.get(addressId);
+      if (!nametags) {
+        nametags = /* @__PURE__ */ new Map();
+        this._addressNametags.set(addressId, nametags);
+      }
+      nametags.set(0, newNametag);
+    }
+    const nametag = this._addressNametags.get(addressId)?.get(0);
     this._identity = {
       privateKey: addressInfo.privateKey,
       chainPubkey: addressInfo.publicKey,
@@ -7084,11 +8578,47 @@ var Sphere = class _Sphere {
     await this._updateCachedProxyAddress();
     await this._storage.set(STORAGE_KEYS_GLOBAL.CURRENT_ADDRESS_INDEX, index.toString());
     this._storage.setIdentity(this._identity);
-    this._transport.setIdentity(this._identity);
+    await this._transport.setIdentity(this._identity);
     for (const provider of this._tokenStorageProviders.values()) {
       provider.setIdentity(this._identity);
+      await provider.initialize();
     }
     await this.reinitializeModulesForNewAddress();
+    if (this._identity.nametag) {
+      await this.syncIdentityWithTransport();
+    }
+    if (newNametag) {
+      await this.persistAddressNametags();
+      if (!this._payments.hasNametag()) {
+        console.log(`[Sphere] Minting nametag token for @${newNametag}...`);
+        try {
+          const result = await this.mintNametag(newNametag);
+          if (result.success) {
+            console.log(`[Sphere] Nametag token minted successfully`);
+          } else {
+            console.warn(`[Sphere] Could not mint nametag token: ${result.error}`);
+          }
+        } catch (err) {
+          console.warn(`[Sphere] Nametag token mint failed:`, err);
+        }
+      }
+      this.emitEvent("nametag:registered", {
+        nametag: newNametag,
+        addressIndex: index
+      });
+    } else if (this._identity.nametag && !this._payments.hasNametag()) {
+      console.log(`[Sphere] Nametag @${this._identity.nametag} has no token after switch, minting...`);
+      try {
+        const result = await this.mintNametag(this._identity.nametag);
+        if (result.success) {
+          console.log(`[Sphere] Nametag token minted successfully after switch`);
+        } else {
+          console.warn(`[Sphere] Could not mint nametag token after switch: ${result.error}`);
+        }
+      } catch (err) {
+        console.warn(`[Sphere] Nametag token mint failed after switch:`, err);
+      }
+    }
     this.emitEvent("identity:changed", {
       l1Address: this._identity.l1Address,
       directAddress: this._identity.directAddress,
@@ -7110,7 +8640,8 @@ var Sphere = class _Sphere {
       transport: this._transport,
       oracle: this._oracle,
       emitEvent,
-      chainCode: this._masterKey?.chainCode
+      chainCode: this._masterKey?.chainCode,
+      price: this._priceProvider ?? void 0
     });
     this._communications.initialize({
       identity: this._identity,
@@ -7143,6 +8674,14 @@ var Sphere = class _Sphere {
    */
   deriveAddress(index, isChange = false) {
     this.ensureReady();
+    return this._deriveAddressInternal(index, isChange);
+  }
+  /**
+   * Internal address derivation without ensureReady() check.
+   * Used during initialization (loadTrackedAddresses, ensureAddressTracked)
+   * when _initialized is still false.
+   */
+  _deriveAddressInternal(index, isChange = false) {
     if (!this._masterKey) {
       throw new Error("HD derivation requires master key with chain code");
     }
@@ -7281,6 +8820,22 @@ var Sphere = class _Sphere {
   getProxyAddress() {
     return this._cachedProxyAddress;
   }
+  /**
+   * Resolve any identifier to full peer information.
+   * Accepts @nametag, bare nametag, DIRECT://, PROXY://, L1 address, or transport pubkey.
+   *
+   * @example
+   * ```ts
+   * const peer = await sphere.resolve('@alice');
+   * const peer = await sphere.resolve('DIRECT://...');
+   * const peer = await sphere.resolve('alpha1...');
+   * const peer = await sphere.resolve('ab12cd...'); // 64-char hex transport pubkey
+   * ```
+   */
+  async resolve(identifier) {
+    this.ensureReady();
+    return this._transport.resolve?.(identifier) ?? null;
+  }
   /** Compute and cache the PROXY address from the current nametag */
   async _updateCachedProxyAddress() {
     const nametag = this._identity?.nametag;
@@ -7319,11 +8874,12 @@ var Sphere = class _Sphere {
     if (this._identity?.nametag) {
       throw new Error(`Nametag already registered for address ${this._currentAddressIndex}: @${this._identity.nametag}`);
     }
-    if (this._transport.registerNametag) {
-      const success = await this._transport.registerNametag(
-        cleanNametag,
+    if (this._transport.publishIdentityBinding) {
+      const success = await this._transport.publishIdentityBinding(
         this._identity.chainPubkey,
-        this._identity.directAddress || ""
+        this._identity.l1Address,
+        this._identity.directAddress || "",
+        cleanNametag
       );
       if (!success) {
         throw new Error("Failed to register nametag. It may already be taken.");
@@ -7331,14 +8887,14 @@ var Sphere = class _Sphere {
     }
     this._identity.nametag = cleanNametag;
     await this._updateCachedProxyAddress();
-    const addressId = this.getCurrentAddressId();
-    if (addressId) {
-      let nametagsMap = this._addressNametags.get(addressId);
-      if (!nametagsMap) {
-        nametagsMap = /* @__PURE__ */ new Map();
-        this._addressNametags.set(addressId, nametagsMap);
+    const currentAddressId = this._trackedAddresses.get(this._currentAddressIndex)?.addressId;
+    if (currentAddressId) {
+      let nametags = this._addressNametags.get(currentAddressId);
+      if (!nametags) {
+        nametags = /* @__PURE__ */ new Map();
+        this._addressNametags.set(currentAddressId, nametags);
       }
-      nametagsMap.set(0, cleanNametag);
+      nametags.set(0, cleanNametag);
     }
     await this.persistAddressNametags();
     if (!this._payments.hasNametag()) {
@@ -7357,19 +8913,19 @@ var Sphere = class _Sphere {
     console.log(`[Sphere] Nametag registered for address ${this._currentAddressIndex}:`, cleanNametag);
   }
   /**
-   * Persist address nametags to storage
-   * Format: { "DIRECT://abc...xyz": { "0": "alice", "1": "alice2" }, ... }
+   * Persist tracked addresses to storage (only minimal fields via StorageProvider)
    */
-  async persistAddressNametags() {
-    const result = {};
-    this._addressNametags.forEach((nametagsMap, addressId) => {
-      const innerObj = {};
-      nametagsMap.forEach((nametag, index) => {
-        innerObj[index.toString()] = nametag;
+  async persistTrackedAddresses() {
+    const entries = [];
+    for (const entry of this._trackedAddresses.values()) {
+      entries.push({
+        index: entry.index,
+        hidden: entry.hidden,
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt
       });
-      result[addressId] = innerObj;
-    });
-    await this._storage.set(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS, JSON.stringify(result));
+    }
+    await this._storage.saveTrackedAddresses(entries);
   }
   /**
    * Mint a nametag token on-chain (like Sphere wallet and lottery)
@@ -7403,63 +8959,184 @@ var Sphere = class _Sphere {
     return this._payments.isNametagAvailable(nametag);
   }
   /**
-   * Load address nametags from storage
-   * Supports new format: { "DIRECT://abc...xyz": { "0": "alice" } }
-   * And legacy format: { "0": "alice" } (migrates to new format on save)
+   * Load tracked addresses from storage.
+   * Falls back to migrating from old ADDRESS_NAMETAGS format.
    */
-  async loadAddressNametags() {
+  async loadTrackedAddresses() {
+    this._trackedAddresses.clear();
+    this._addressIdToIndex.clear();
     try {
-      const saved = await this._storage.get(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS);
-      if (saved) {
-        const parsed = JSON.parse(saved);
-        this._addressNametags.clear();
-        for (const [key, value] of Object.entries(parsed)) {
-          if (typeof value === "object" && value !== null) {
-            const nametagsMap = /* @__PURE__ */ new Map();
-            for (const [indexStr, nametag] of Object.entries(value)) {
-              nametagsMap.set(parseInt(indexStr, 10), nametag);
-            }
-            this._addressNametags.set(key, nametagsMap);
-          } else if (typeof value === "string") {
-          }
+      const entries = await this._storage.loadTrackedAddresses();
+      if (entries.length > 0) {
+        for (const stored of entries) {
+          const addrInfo = this._deriveAddressInternal(stored.index, false);
+          const directAddress = await deriveL3PredicateAddress(addrInfo.privateKey);
+          const addressId = getAddressId(directAddress);
+          const entry = {
+            ...stored,
+            addressId,
+            l1Address: addrInfo.address,
+            directAddress,
+            chainPubkey: addrInfo.publicKey
+          };
+          this._trackedAddresses.set(entry.index, entry);
+          this._addressIdToIndex.set(addressId, entry.index);
         }
+        return;
+      }
+      const oldData = await this._storage.get(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS);
+      if (oldData) {
+        const parsed = JSON.parse(oldData);
+        await this.migrateFromOldNametagFormat(parsed);
+        await this.persistTrackedAddresses();
       }
     } catch {
     }
   }
   /**
-   * Sync nametag with Nostr on wallet load
-   * If local nametag exists but not registered on Nostr, re-register it
+   * Migrate from old ADDRESS_NAMETAGS format to tracked addresses.
+   * Scans HD indices 0..19 to match addressIds from the old format.
+   * Populates both _trackedAddresses and _addressNametags.
    */
-  async syncNametagWithNostr() {
-    const nametag = this._identity?.nametag;
-    if (!nametag) {
-      return;
+  async migrateFromOldNametagFormat(parsed) {
+    const addressIdToNametags = /* @__PURE__ */ new Map();
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "object" && value !== null) {
+        addressIdToNametags.set(key, value);
+      }
+    }
+    if (addressIdToNametags.size === 0 || !this._masterKey) return;
+    const SCAN_LIMIT = 20;
+    for (let i = 0; i < SCAN_LIMIT && addressIdToNametags.size > 0; i++) {
+      try {
+        const addrInfo = this._deriveAddressInternal(i, false);
+        const directAddress = await deriveL3PredicateAddress(addrInfo.privateKey);
+        const addressId = getAddressId(directAddress);
+        if (addressIdToNametags.has(addressId)) {
+          const nametagsObj = addressIdToNametags.get(addressId);
+          const nametagMap = /* @__PURE__ */ new Map();
+          for (const [idx, tag] of Object.entries(nametagsObj)) {
+            nametagMap.set(parseInt(idx, 10), tag);
+          }
+          if (nametagMap.size > 0) {
+            this._addressNametags.set(addressId, nametagMap);
+          }
+          const now = Date.now();
+          const entry = {
+            index: i,
+            addressId,
+            l1Address: addrInfo.address,
+            directAddress,
+            chainPubkey: addrInfo.publicKey,
+            nametag: nametagMap.get(0),
+            hidden: false,
+            createdAt: now,
+            updatedAt: now
+          };
+          this._trackedAddresses.set(i, entry);
+          this._addressIdToIndex.set(addressId, i);
+          addressIdToNametags.delete(addressId);
+        }
+      } catch {
+      }
+    }
+    await this.persistAddressNametags();
+  }
+  /**
+   * Ensure an address is tracked in the registry.
+   * If not yet tracked, derives full info and creates the entry.
+   */
+  async ensureAddressTracked(index) {
+    const existing = this._trackedAddresses.get(index);
+    if (existing) return existing;
+    const addrInfo = this._deriveAddressInternal(index, false);
+    const directAddress = await deriveL3PredicateAddress(addrInfo.privateKey);
+    const addressId = getAddressId(directAddress);
+    const now = Date.now();
+    const nametag = this._addressNametags.get(addressId)?.get(0);
+    const entry = {
+      index,
+      addressId,
+      l1Address: addrInfo.address,
+      directAddress,
+      chainPubkey: addrInfo.publicKey,
+      nametag,
+      hidden: false,
+      createdAt: now,
+      updatedAt: now
+    };
+    this._trackedAddresses.set(index, entry);
+    this._addressIdToIndex.set(addressId, index);
+    await this.persistTrackedAddresses();
+    this.emitEvent("address:activated", { address: { ...entry } });
+    return entry;
+  }
+  /**
+   * Persist nametag cache to storage.
+   * Format: { addressId: { "0": "alice", "1": "alice2" } }
+   */
+  async persistAddressNametags() {
+    const result = {};
+    for (const [addressId, nametags] of this._addressNametags.entries()) {
+      const obj = {};
+      for (const [idx, tag] of nametags.entries()) {
+        obj[idx.toString()] = tag;
+      }
+      result[addressId] = obj;
+    }
+    await this._storage.set(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS, JSON.stringify(result));
+  }
+  /**
+   * Load nametag cache from storage.
+   */
+  async loadAddressNametags() {
+    this._addressNametags.clear();
+    try {
+      const data = await this._storage.get(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS);
+      if (!data) return;
+      const parsed = JSON.parse(data);
+      for (const [addressId, nametags] of Object.entries(parsed)) {
+        const map = /* @__PURE__ */ new Map();
+        for (const [idx, tag] of Object.entries(nametags)) {
+          map.set(parseInt(idx, 10), tag);
+        }
+        this._addressNametags.set(addressId, map);
+      }
+    } catch {
     }
-    if (!this._transport.resolveNametag || !this._transport.registerNametag) {
+  }
+  /**
+   * Publish identity binding via transport.
+   * Always publishes base identity (chainPubkey, l1Address, directAddress).
+   * If nametag is set, also publishes nametag hash, proxy address, encrypted nametag.
+   */
+  async syncIdentityWithTransport() {
+    if (!this._transport.publishIdentityBinding) {
       return;
     }
     try {
-      const success = await this._transport.registerNametag(
-        nametag,
+      const nametag = this._identity?.nametag;
+      const success = await this._transport.publishIdentityBinding(
         this._identity.chainPubkey,
-        this._identity.directAddress || ""
+        this._identity.l1Address,
+        this._identity.directAddress || "",
+        nametag || void 0
       );
       if (success) {
-        console.log(`[Sphere] Nametag @${nametag} synced with Nostr`);
-      } else {
+        console.log(`[Sphere] Identity binding published${nametag ? ` with nametag @${nametag}` : ""}`);
+      } else if (nametag) {
         console.warn(`[Sphere] Nametag @${nametag} is taken by another pubkey`);
       }
     } catch (error) {
-      console.warn(`[Sphere] Nametag sync failed:`, error);
+      console.warn(`[Sphere] Identity binding sync failed:`, error);
     }
   }
   /**
-   * Recover nametag from Nostr after wallet import
+   * Recover nametag from transport after wallet import.
    * Searches for encrypted nametag events authored by this wallet's pubkey
-   * and decrypts them to restore the nametag association
+   * and decrypts them to restore the nametag association.
    */
-  async recoverNametagFromNostr() {
+  async recoverNametagFromTransport() {
     if (this._identity?.nametag) {
       return;
     }
@@ -7473,22 +9150,21 @@ var Sphere = class _Sphere {
           this._identity.nametag = recoveredNametag;
           await this._updateCachedProxyAddress();
         }
-        const addressId = this.getCurrentAddressId();
-        if (addressId) {
-          let nametagsMap = this._addressNametags.get(addressId);
-          if (!nametagsMap) {
-            nametagsMap = /* @__PURE__ */ new Map();
-            this._addressNametags.set(addressId, nametagsMap);
-          }
-          const nextIndex = nametagsMap.size;
-          nametagsMap.set(nextIndex, recoveredNametag);
+        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.registerNametag) {
-          await this._transport.registerNametag(
-            recoveredNametag,
+        if (this._transport.publishIdentityBinding) {
+          await this._transport.publishIdentityBinding(
             this._identity.chainPubkey,
-            this._identity.directAddress || ""
+            this._identity.l1Address,
+            this._identity.directAddress || "",
+            recoveredNametag
           );
         }
         this.emitEvent("nametag:recovered", { nametag: recoveredNametag });
@@ -7516,6 +9192,9 @@ var Sphere = class _Sphere {
     await this._oracle.disconnect();
     this._initialized = false;
     this._identity = null;
+    this._trackedAddresses.clear();
+    this._addressIdToIndex.clear();
+    this._addressNametags.clear();
     this.eventHandlers.clear();
     if (_Sphere.instance === this) {
       _Sphere.instance = null;
@@ -7613,14 +9292,14 @@ var Sphere = class _Sphere {
     if (this._identity) {
       this._storage.setIdentity(this._identity);
     }
+    await this.loadTrackedAddresses();
     await this.loadAddressNametags();
+    const trackedEntry = await this.ensureAddressTracked(this._currentAddressIndex);
+    const nametag = this._addressNametags.get(trackedEntry.addressId)?.get(0);
     if (this._currentAddressIndex > 0 && this._masterKey) {
-      const addressInfo = this.deriveAddress(this._currentAddressIndex, false);
+      const addressInfo = this._deriveAddressInternal(this._currentAddressIndex, false);
       const ipnsHash = sha256(addressInfo.publicKey, "hex").slice(0, 40);
       const predicateAddress = await deriveL3PredicateAddress(addressInfo.privateKey);
-      const addressId = getAddressId(predicateAddress);
-      const nametagsMap = this._addressNametags.get(addressId);
-      const nametag = nametagsMap?.get(0);
       this._identity = {
         privateKey: addressInfo.privateKey,
         chainPubkey: addressInfo.publicKey,
@@ -7631,13 +9310,8 @@ var Sphere = class _Sphere {
       };
       this._storage.setIdentity(this._identity);
       console.log(`[Sphere] Restored to address ${this._currentAddressIndex}:`, this._identity.l1Address);
-    } else if (this._identity) {
-      const addressId = this.getCurrentAddressId();
-      const nametagsMap = addressId ? this._addressNametags.get(addressId) : void 0;
-      const nametag = nametagsMap?.get(0);
-      if (nametag) {
-        this._identity.nametag = nametag;
-      }
+    } else if (this._identity && nametag) {
+      this._identity.nametag = nametag;
     }
     await this._updateCachedProxyAddress();
   }
@@ -7695,7 +9369,7 @@ var Sphere = class _Sphere {
   // ===========================================================================
   async initializeProviders() {
     this._storage.setIdentity(this._identity);
-    this._transport.setIdentity(this._identity);
+    await this._transport.setIdentity(this._identity);
     for (const provider of this._tokenStorageProviders.values()) {
       provider.setIdentity(this._identity);
     }
@@ -7716,7 +9390,8 @@ var Sphere = class _Sphere {
       oracle: this._oracle,
       emitEvent,
       // Pass chain code for L1 HD derivation
-      chainCode: this._masterKey?.chainCode
+      chainCode: this._masterKey?.chainCode,
+      price: this._priceProvider ?? void 0
     });
     this._communications.initialize({
       identity: this._identity,
@@ -7798,6 +9473,65 @@ function formatAmount(amount, options = {}) {
   return symbol ? `${readable} ${symbol}` : readable;
 }
 
+// types/payment-session.ts
+function createPaymentSession(params) {
+  const now = Date.now();
+  const deadlineMs = params.deadlineMs ?? 3e5;
+  return {
+    id: crypto.randomUUID(),
+    direction: params.direction,
+    status: "INITIATED",
+    createdAt: now,
+    updatedAt: now,
+    deadline: now + deadlineMs,
+    error: null,
+    sourceTokenId: params.sourceTokenId,
+    recipientNametag: params.recipientNametag,
+    recipientPubkey: params.recipientPubkey,
+    amount: params.amount,
+    coinId: params.coinId,
+    salt: params.salt
+  };
+}
+function createSplitPaymentSession(params) {
+  const now = Date.now();
+  return {
+    id: crypto.randomUUID(),
+    direction: "SEND",
+    sourceTokenId: params.sourceTokenId,
+    paymentAmount: params.paymentAmount,
+    changeAmount: params.changeAmount,
+    recipientNametag: params.recipientNametag,
+    recipientPubkey: params.recipientPubkey,
+    splitGroupId: params.splitGroupId,
+    phases: {
+      burn: "PENDING",
+      mints: "PENDING",
+      transfer: "PENDING"
+    },
+    timing: {},
+    createdAt: now,
+    updatedAt: now,
+    error: null
+  };
+}
+function isPaymentSessionTimedOut(session) {
+  if (!("deadline" in session) || !session.deadline) return false;
+  return Date.now() > session.deadline;
+}
+function isPaymentSessionTerminal(session) {
+  return session.status === "COMPLETED" || session.status === "FAILED" || session.status === "TIMED_OUT";
+}
+function createPaymentSessionError(code, message, recoverable = false, details) {
+  return {
+    code,
+    message,
+    timestamp: Date.now(),
+    recoverable,
+    details
+  };
+}
+
 // types/index.ts
 var SphereError = class extends Error {
   code;
@@ -7985,14 +9719,30 @@ var TokenValidator = class {
     }
   }
   /**
-   * Check which tokens are spent
+   * Check which tokens are spent using SDK Token object to calculate state hash.
+   *
+   * Follows the same approach as the Sphere webgui TokenValidationService:
+   * 1. Parse TXF using SDK's Token.fromJSON()
+   * 2. Calculate CURRENT state hash via sdkToken.state.calculateHash()
+   * 3. Create RequestId via RequestId.create(walletPubKey, calculatedHash)
+   *
+   * Uses wallet's own pubkey (not source state predicate key) because "spent" means
+   * the CURRENT OWNER committed this state. Using the source state key would falsely
+   * detect received tokens as "spent" (sender's commitment matches source state).
    */
   async checkSpentTokens(tokens, publicKey, options) {
     const spentTokens = [];
     const errors = [];
+    if (!this.aggregatorClient) {
+      errors.push("Aggregator client not available");
+      return { spentTokens, errors };
+    }
     const batchSize = options?.batchSize ?? 3;
     const total = tokens.length;
     let completed = 0;
+    const { Token: SdkToken3 } = await import("@unicitylabs/state-transition-sdk/lib/token/Token");
+    const { RequestId } = await import("@unicitylabs/state-transition-sdk/lib/api/RequestId");
+    const pubKeyBytes = Buffer.from(publicKey, "hex");
     for (let i = 0; i < tokens.length; i += batchSize) {
       const batch = tokens.slice(i, i + batchSize);
       const batchResults = await Promise.allSettled(
@@ -8002,13 +9752,39 @@ var TokenValidator = class {
             if (!txf) {
               return { tokenId: token.id, localId: token.id, stateHash: "", spent: false, error: "Invalid TXF" };
             }
-            const tokenId = txf.genesis.data.tokenId;
-            const stateHash = getCurrentStateHash(txf);
-            if (!stateHash) {
-              return { tokenId, localId: token.id, stateHash: "", spent: false, error: "No state hash" };
+            const tokenId = txf.genesis?.data?.tokenId || token.id;
+            const sdkToken = await SdkToken3.fromJSON(txf);
+            const calculatedStateHash = await sdkToken.state.calculateHash();
+            const calculatedStateHashStr = calculatedStateHash.toJSON();
+            const cacheKey = `${tokenId}:${calculatedStateHashStr}:${publicKey}`;
+            const cached = this.spentStateCache.get(cacheKey);
+            if (cached !== void 0) {
+              if (cached.isSpent) {
+                return { tokenId, localId: token.id, stateHash: calculatedStateHashStr, spent: true };
+              }
+              if (Date.now() - cached.timestamp < this.UNSPENT_CACHE_TTL_MS) {
+                return { tokenId, localId: token.id, stateHash: calculatedStateHashStr, spent: false };
+              }
+            }
+            const { DataHash } = await import("@unicitylabs/state-transition-sdk/lib/hash/DataHash");
+            const stateHashObj = DataHash.fromJSON(calculatedStateHashStr);
+            const requestId2 = await RequestId.create(pubKeyBytes, stateHashObj);
+            const response = await this.aggregatorClient.getInclusionProof(requestId2);
+            let isSpent = false;
+            if (response.inclusionProof) {
+              const proof = response.inclusionProof;
+              const pathResult = await proof.merkleTreePath.verify(
+                requestId2.toBitString().toBigInt()
+              );
+              if (pathResult.isPathValid && pathResult.isPathIncluded && proof.authenticator !== null) {
+                isSpent = true;
+              }
             }
-            const spent = await this.isTokenStateSpent(tokenId, stateHash, publicKey);
-            return { tokenId, localId: token.id, stateHash, spent };
+            this.spentStateCache.set(cacheKey, {
+              isSpent,
+              timestamp: Date.now()
+            });
+            return { tokenId, localId: token.id, stateHash: calculatedStateHashStr, spent: isSpent };
           } catch (err) {
             return {
               tokenId: token.id,
@@ -8067,8 +9843,8 @@ var TokenValidator = class {
   }
   async verifyWithSdk(txfToken) {
     try {
-      const { Token: Token3 } = await import("@unicitylabs/state-transition-sdk/lib/token/Token");
-      const sdkToken = await Token3.fromJSON(txfToken);
+      const { Token: Token5 } = await import("@unicitylabs/state-transition-sdk/lib/token/Token");
+      const sdkToken = await Token5.fromJSON(txfToken);
       if (!this.trustBase) {
         return { success: true };
       }
@@ -8091,8 +9867,116 @@ var TokenValidator = class {
 function createTokenValidator(options) {
   return new TokenValidator(options);
 }
+
+// price/CoinGeckoPriceProvider.ts
+var CoinGeckoPriceProvider = class {
+  platform = "coingecko";
+  cache = /* @__PURE__ */ new Map();
+  apiKey;
+  cacheTtlMs;
+  timeout;
+  debug;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config?.apiKey;
+    this.cacheTtlMs = config?.cacheTtlMs ?? 6e4;
+    this.timeout = config?.timeout ?? 1e4;
+    this.debug = config?.debug ?? false;
+    this.baseUrl = config?.baseUrl ?? (this.apiKey ? "https://pro-api.coingecko.com/api/v3" : "https://api.coingecko.com/api/v3");
+  }
+  async getPrices(tokenNames) {
+    if (tokenNames.length === 0) {
+      return /* @__PURE__ */ new Map();
+    }
+    const now = Date.now();
+    const result = /* @__PURE__ */ new Map();
+    const uncachedNames = [];
+    for (const name of tokenNames) {
+      const cached = this.cache.get(name);
+      if (cached && cached.expiresAt > now) {
+        if (cached.price !== null) {
+          result.set(name, cached.price);
+        }
+      } else {
+        uncachedNames.push(name);
+      }
+    }
+    if (uncachedNames.length === 0) {
+      return result;
+    }
+    try {
+      const ids = uncachedNames.join(",");
+      const url = `${this.baseUrl}/simple/price?ids=${encodeURIComponent(ids)}&vs_currencies=usd,eur&include_24hr_change=true`;
+      const headers = { Accept: "application/json" };
+      if (this.apiKey) {
+        headers["x-cg-pro-api-key"] = this.apiKey;
+      }
+      if (this.debug) {
+        console.log(`[CoinGecko] Fetching prices for: ${uncachedNames.join(", ")}`);
+      }
+      const response = await fetch(url, {
+        headers,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+      if (!response.ok) {
+        throw new Error(`CoinGecko API error: ${response.status} ${response.statusText}`);
+      }
+      const data = await response.json();
+      for (const [name, values] of Object.entries(data)) {
+        if (values && typeof values === "object") {
+          const price = {
+            tokenName: name,
+            priceUsd: values.usd ?? 0,
+            priceEur: values.eur,
+            change24h: values.usd_24h_change,
+            timestamp: now
+          };
+          this.cache.set(name, { price, expiresAt: now + this.cacheTtlMs });
+          result.set(name, price);
+        }
+      }
+      for (const name of uncachedNames) {
+        if (!result.has(name)) {
+          this.cache.set(name, { price: null, expiresAt: now + this.cacheTtlMs });
+        }
+      }
+      if (this.debug) {
+        console.log(`[CoinGecko] Fetched ${result.size} prices`);
+      }
+    } catch (error) {
+      if (this.debug) {
+        console.warn("[CoinGecko] Fetch failed, using stale cache:", error);
+      }
+      for (const name of uncachedNames) {
+        const stale = this.cache.get(name);
+        if (stale?.price) {
+          result.set(name, stale.price);
+        }
+      }
+    }
+    return result;
+  }
+  async getPrice(tokenName) {
+    const prices = await this.getPrices([tokenName]);
+    return prices.get(tokenName) ?? null;
+  }
+  clearCache() {
+    this.cache.clear();
+  }
+};
+
+// price/index.ts
+function createPriceProvider(config) {
+  switch (config.platform) {
+    case "coingecko":
+      return new CoinGeckoPriceProvider(config);
+    default:
+      throw new Error(`Unsupported price platform: ${String(config.platform)}`);
+  }
+}
 export {
   COIN_TYPES,
+  CoinGeckoPriceProvider,
   CommunicationsModule,
   DEFAULT_AGGREGATOR_TIMEOUT,
   DEFAULT_AGGREGATOR_URL,
@@ -8128,8 +10012,12 @@ export {
   createCommunicationsModule,
   createKeyPair,
   createL1PaymentsModule,
+  createPaymentSession,
+  createPaymentSessionError,
   createPaymentsModule,
+  createPriceProvider,
   createSphere,
+  createSplitPaymentSession,
   createTokenValidator,
   decodeBech32,
   decryptCMasterKey,
@@ -8167,7 +10055,12 @@ export {
   initSphere,
   isArchivedKey,
   isForkedKey,
+  isInstantSplitBundle,
+  isInstantSplitBundleV4,
+  isInstantSplitBundleV5,
   isKnownToken,
+  isPaymentSessionTerminal,
+  isPaymentSessionTimedOut,
   isSQLiteDatabase,
   isTextWalletEncrypted,
   isTokenKey,