@unicitylabs/sphere-sdk 0.7.1-dev.2 → 0.7.1

package/dist/index.js

@@ -1389,6 +1389,17 @@ var NostrTransportProvider = class _NostrTransportProvider {
   getStorageAdapter() {
     return this.storage;
   }
+  /**
+   * Get the underlying NostrClient (or null if not yet connected).
+   *
+   * Exposed so {@link MultiAddressTransportMux} can share the same
+   * client/socket pair instead of opening a duplicate WebSocket per
+   * relay (#123). The transport owns the client's lifecycle — callers
+   * MUST NOT call {@code disconnect()} on the returned instance.
+   */
+  getNostrClient() {
+    return this.nostrClient;
+  }
   /**
    * Suppress event subscriptions — unsubscribe wallet/chat filters
    * but keep the connection alive for resolve/identity-binding operations.
@@ -3027,9 +3038,6 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
   chatSubscriptionId = null;
   chatEoseFired = false;
   resubscribeTimer = null;
-  lastWalletEventAt = Date.now();
-  lastChatEventAt = Date.now();
-  healthCheckTimer = null;
   chatEoseHandlers = [];
   // Dedup — bounded to prevent memory leak in long-running sessions.
   // Set preserves insertion order; evict oldest entries when cap is reached.
@@ -3040,6 +3048,19 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
   // Identity key for the Mux's NostrClient — relays may filter gift-wrap
   // delivery to the recipient's subscription key.
   identityPrivateKey;
+  // Resolves the shared NostrClient at use-time (the source provider may
+  // create its client lazily, after the Mux is constructed). null means
+  // "no shared client; create our own."
+  sharedNostrClientGetter;
+  // True when this Mux is using a shared NostrClient and therefore must
+  // not call connect()/disconnect() on it.
+  usingSharedClient = false;
+  // Listener registered on the underlying NostrClient. Tracked so we can
+  // remove it on disconnect / rebind — otherwise a long-lived shared
+  // client accumulates listeners across address switches and (worse)
+  // a "disconnected" Mux still sees onReconnected callbacks fire and
+  // re-establish subscriptions it shouldn't have.
+  connectionListener = null;
   constructor(config) {
     this.identityPrivateKey = config.identityPrivateKey;
     this.config = {
@@ -3052,6 +3073,14 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
       generateUUID: config.generateUUID ?? defaultUUIDGenerator
     };
     this.storage = config.storage ?? null;
+    if (typeof config.sharedNostrClient === "function") {
+      this.sharedNostrClientGetter = config.sharedNostrClient;
+    } else if (config.sharedNostrClient) {
+      const c = config.sharedNostrClient;
+      this.sharedNostrClientGetter = () => c;
+    } else {
+      this.sharedNostrClientGetter = null;
+    }
   }
   // ===========================================================================
   // Address Management
@@ -3142,53 +3171,49 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
     if (this.status === "connected") return;
     this.status = "connecting";
     try {
-      if (!this.primaryKeyManager) {
-        if (this.identityPrivateKey) {
-          this.primaryKeyManager = NostrKeyManager2.fromPrivateKey(
-            Buffer3.from(this.identityPrivateKey)
+      const shared = this.sharedNostrClientGetter ? this.sharedNostrClientGetter() : null;
+      if (shared) {
+        if (!shared.isConnected()) {
+          throw new SphereError(
+            "sharedNostrClient is not connected; the Mux cannot share a closed socket",
+            "TRANSPORT_ERROR"
           );
-        } else {
-          const tempKey = Buffer3.alloc(32);
-          crypto.getRandomValues(tempKey);
-          this.primaryKeyManager = NostrKeyManager2.fromPrivateKey(tempKey);
         }
+        this.nostrClient = shared;
+        this.usingSharedClient = true;
+      } else {
+        if (!this.primaryKeyManager) {
+          if (this.identityPrivateKey) {
+            this.primaryKeyManager = NostrKeyManager2.fromPrivateKey(
+              Buffer3.from(this.identityPrivateKey)
+            );
+          } else {
+            const tempKey = Buffer3.alloc(32);
+            crypto.getRandomValues(tempKey);
+            this.primaryKeyManager = NostrKeyManager2.fromPrivateKey(tempKey);
+          }
+        }
+        this.nostrClient = new NostrClient2(this.primaryKeyManager, {
+          autoReconnect: this.config.autoReconnect,
+          reconnectIntervalMs: this.config.reconnectDelay,
+          maxReconnectIntervalMs: this.config.reconnectDelay * 16,
+          pingIntervalMs: 15e3
+        });
       }
-      this.nostrClient = new NostrClient2(this.primaryKeyManager, {
-        autoReconnect: this.config.autoReconnect,
-        reconnectIntervalMs: this.config.reconnectDelay,
-        maxReconnectIntervalMs: this.config.reconnectDelay * 16,
-        pingIntervalMs: 15e3
-      });
-      this.nostrClient.addConnectionListener({
-        onConnect: (url) => {
-          logger.debug("Mux", "Connected to relay:", url);
-          this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
-        },
-        onDisconnect: (url, reason) => {
-          logger.debug("Mux", "Disconnected from relay:", url, "reason:", reason);
-        },
-        onReconnecting: (url, attempt) => {
-          logger.debug("Mux", "Reconnecting to relay:", url, "attempt:", attempt);
-          this.emitEvent({ type: "transport:reconnecting", timestamp: Date.now() });
-        },
-        onReconnected: (url) => {
-          logger.debug("Mux", "Reconnected to relay:", url);
-          this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
-          this.updateSubscriptions().catch((err) => {
-            logger.error("Mux", "Failed to re-subscribe after reconnect:", err);
-          });
+      this.connectionListener = this.buildConnectionListener();
+      this.nostrClient.addConnectionListener(this.connectionListener);
+      if (!this.usingSharedClient) {
+        await Promise.race([
+          this.nostrClient.connect(...this.config.relays),
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error(
+              `Transport connection timed out after ${this.config.timeout}ms`
+            )), this.config.timeout)
+          )
+        ]);
+        if (!this.nostrClient.isConnected()) {
+          throw new SphereError("Failed to connect to any relay", "TRANSPORT_ERROR");
         }
-      });
-      await Promise.race([
-        this.nostrClient.connect(...this.config.relays),
-        new Promise(
-          (_, reject) => setTimeout(() => reject(new Error(
-            `Transport connection timed out after ${this.config.timeout}ms`
-          )), this.config.timeout)
-        )
-      ]);
-      if (!this.nostrClient.isConnected()) {
-        throw new SphereError("Failed to connect to any relay", "TRANSPORT_ERROR");
       }
       this.status = "connected";
       this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
@@ -3197,6 +3222,21 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
       }
     } catch (error) {
       this.status = "error";
+      if (this.connectionListener && this.nostrClient) {
+        try {
+          this.nostrClient.removeConnectionListener(this.connectionListener);
+        } catch {
+        }
+      }
+      this.connectionListener = null;
+      if (this.nostrClient && !this.usingSharedClient) {
+        try {
+          this.nostrClient.disconnect();
+        } catch {
+        }
+      }
+      this.nostrClient = null;
+      this.usingSharedClient = false;
       throw error;
     }
   }
@@ -3205,25 +3245,153 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
       clearTimeout(this.resubscribeTimer);
       this.resubscribeTimer = null;
     }
-    if (this.healthCheckTimer) {
-      clearInterval(this.healthCheckTimer);
-      this.healthCheckTimer = null;
-    }
     if (this.nostrClient) {
-      this.nostrClient.disconnect();
+      if (this.walletSubscriptionId) {
+        try {
+          this.nostrClient.unsubscribe(this.walletSubscriptionId);
+        } catch {
+        }
+      }
+      if (this.chatSubscriptionId) {
+        try {
+          this.nostrClient.unsubscribe(this.chatSubscriptionId);
+        } catch {
+        }
+      }
+      if (this.connectionListener) {
+        try {
+          this.nostrClient.removeConnectionListener(this.connectionListener);
+        } catch {
+        }
+      }
+      if (!this.usingSharedClient) {
+        this.nostrClient.disconnect();
+      }
       this.nostrClient = null;
     }
+    this.connectionListener = null;
+    this.usingSharedClient = false;
     this.walletSubscriptionId = null;
     this.chatSubscriptionId = null;
     this.chatEoseFired = false;
-    this.lastWalletEventAt = Date.now();
-    this.lastChatEventAt = Date.now();
     this.status = "disconnected";
     this.emitEvent({ type: "transport:disconnected", timestamp: Date.now() });
   }
   isConnected() {
     return this.status === "connected" && this.nostrClient?.isConnected() === true;
   }
+  /**
+   * Build the connection listener used by both {@link connect} and
+   * {@link rebindToSharedClient}.
+   *
+   * Behavioral notes:
+   * - When the Mux is sharing a {@link NostrClient} with the host
+   *   transport (#123), we deliberately do NOT emit
+   *   {@code transport:connected} / {@code transport:reconnecting} here
+   *   — the host transport's own listener already emits those for the
+   *   same socket event. Re-subscribing after a reconnect IS still our
+   *   responsibility, since the host has
+   *   {@code suppressSubscriptions()}'d its own filters.
+   * - {@code onConnect} does not emit {@code transport:connected}.
+   *   The SDK only fires {@code onConnect} on the initial socket
+   *   connection (subsequent reconnects use {@code onReconnected}),
+   *   and {@link connect()}'s bottom already emits
+   *   {@code transport:connected} once that returns. Emitting here too
+   *   would double-fire on every initial connect.
+   * - Each callback bails out early when the Mux is not in an active
+   *   state ({@code disconnected} / {@code error}). Listeners are
+   *   removed on {@code disconnect()} before the callback can fire,
+   *   so this guard is mainly defense-in-depth against any in-flight
+   *   callback that lands during teardown — but having it at the top
+   *   means we never emit a misleading {@code transport:connected}
+   *   from a Mux that has already torn down.
+   */
+  buildConnectionListener() {
+    const isInactive = () => this.status === "disconnected" || this.status === "error";
+    return {
+      onConnect: (url) => {
+        if (isInactive()) return;
+        logger.debug("Mux", "Connected to relay:", url);
+      },
+      onDisconnect: (url, reason) => {
+        logger.debug("Mux", "Disconnected from relay:", url, "reason:", reason);
+      },
+      onReconnecting: (url, attempt) => {
+        if (isInactive()) return;
+        logger.debug("Mux", "Reconnecting to relay:", url, "attempt:", attempt);
+        if (!this.usingSharedClient) {
+          this.emitEvent({ type: "transport:reconnecting", timestamp: Date.now() });
+        }
+      },
+      onReconnected: (url) => {
+        if (isInactive()) return;
+        logger.debug("Mux", "Reconnected to relay:", url);
+        if (!this.usingSharedClient) {
+          this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
+        }
+        this.updateSubscriptions().catch((err) => {
+          logger.error("Mux", "Failed to re-subscribe after reconnect:", err);
+        });
+      }
+    };
+  }
+  /**
+   * Re-attach to a freshly-created shared NostrClient.
+   *
+   * Call this after the host (e.g. {@link NostrTransportProvider}) has
+   * recreated its NostrClient — typically because the wallet's active
+   * identity changed and the SDK's NostrClient does not support
+   * changing identity at runtime. The previous client has already
+   * been disconnected by the host, so its server-side subscriptions
+   * are gone — we just adopt the new client and re-issue our own.
+   *
+   * The caller is responsible for ordering: by the time rebind runs,
+   * the host transport's new NostrClient must already be created and
+   * connected. In Sphere this is guaranteed because we await
+   * {@code transport.setIdentity()} before calling rebind.
+   *
+   * Returns silently in two cases that are not caller errors:
+   *   - the Mux owns its own client (not sharing) — nothing to rebind
+   *   - the shared client reference hasn't changed (rebind is a no-op)
+   *
+   * Throws otherwise (rather than silently no-op'ing) so a wiring
+   * mistake — for instance, calling rebind before the host's new
+   * client is ready — surfaces immediately instead of leaving the
+   * Mux pinned to a stale client.
+   */
+  async rebindToSharedClient() {
+    if (!this.usingSharedClient) return;
+    if (!this.sharedNostrClientGetter) return;
+    const newClient = this.sharedNostrClientGetter();
+    if (!newClient) {
+      throw new SphereError(
+        "rebindToSharedClient: shared client getter returned null. The host transport must finish (re)creating its NostrClient before rebind is called.",
+        "TRANSPORT_ERROR"
+      );
+    }
+    if (this.nostrClient === newClient) return;
+    if (!newClient.isConnected()) {
+      throw new SphereError(
+        "rebindToSharedClient: new shared client is not connected. Await transport.setIdentity() / transport.connect() before rebinding.",
+        "TRANSPORT_ERROR"
+      );
+    }
+    if (this.nostrClient && this.connectionListener && this.nostrClient !== newClient) {
+      try {
+        this.nostrClient.removeConnectionListener(this.connectionListener);
+      } catch {
+      }
+    }
+    this.nostrClient = newClient;
+    this.walletSubscriptionId = null;
+    this.chatSubscriptionId = null;
+    this.chatEoseFired = false;
+    this.connectionListener = this.buildConnectionListener();
+    this.nostrClient.addConnectionListener(this.connectionListener);
+    if (this.addresses.size > 0) {
+      await this.updateSubscriptions();
+    }
+  }
   /**
    * One-shot fetch of pending events from the relay.
    * Creates a temporary subscription, waits for EOSE (or timeout),
@@ -3352,8 +3520,6 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
       this.nostrClient.unsubscribe(this.chatSubscriptionId);
       this.chatSubscriptionId = null;
     }
-    this.lastWalletEventAt = Date.now();
-    this.lastChatEventAt = Date.now();
     if (this.addresses.size === 0) return;
     const allPubkeys = [];
     for (const entry of this.addresses.values()) {
@@ -3440,25 +3606,6 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
       }
     });
     logger.debug("Mux", `updateSubscriptions: walletSub=${this.walletSubscriptionId} chatSub=${this.chatSubscriptionId}`);
-    this.startHealthCheck();
-  }
-  startHealthCheck() {
-    if (this.healthCheckTimer) return;
-    this.healthCheckTimer = setInterval(() => {
-      if (!this.isConnected()) return;
-      const chatElapsed = Date.now() - this.lastChatEventAt;
-      const walletElapsed = Date.now() - this.lastWalletEventAt;
-      const needResubscribe = chatElapsed > 6e4 || walletElapsed > 3e5;
-      if (needResubscribe) {
-        const reason = chatElapsed > 6e4 ? `No chat events for ${Math.round(chatElapsed / 1e3)}s` : `No wallet events for ${Math.round(walletElapsed / 1e3)}s`;
-        logger.warn("Mux", `${reason} \u2014 re-subscribing`);
-        this.lastChatEventAt = Date.now();
-        this.lastWalletEventAt = Date.now();
-        this.updateSubscriptions().catch((err) => {
-          logger.warn("Mux", "Health check re-subscription failed:", err);
-        });
-      }
-    }, 3e4);
   }
   /**
    * Schedule a re-subscription after a relay-initiated subscription closure.
@@ -3519,12 +3666,6 @@ var MultiAddressTransportMux = class _MultiAddressTransportMux {
         }
       }
     }
-    if (event.kind !== EventKinds2.GIFT_WRAP) {
-      this.lastWalletEventAt = Date.now();
-    }
-    if (event.kind === EventKinds2.GIFT_WRAP) {
-      this.lastChatEventAt = Date.now();
-    }
     try {
       if (event.kind === EventKinds2.GIFT_WRAP) {
         await this.routeGiftWrap(event);
@@ -12206,6 +12347,132 @@ var PaymentsModule = class _PaymentsModule {
       };
     }
   }
+  /**
+   * Mint a fungible token directly to this wallet (genesis mint).
+   *
+   * Useful for test setups that need to seed a wallet with specific token
+   * balances WITHOUT depending on the testnet faucet HTTP service. The
+   * resulting token has the canonical CoinId bytes (passed in `coinIdHex`)
+   * — when those bytes match a registered symbol in the TokenRegistry,
+   * the token shows up under the symbol's name (e.g. "UCT"). There is no
+   * cryptographic restriction on which key may issue a given CoinId; the
+   * aggregator records the mint regardless of issuer identity.
+   *
+   * The flow:
+   *   1. Generate a random TokenId.
+   *   2. Build TokenCoinData with [(coinId, amount)].
+   *   3. Build MintTransactionData with recipient = self (UnmaskedPredicate
+   *      from this wallet's signing service).
+   *   4. Submit MintCommitment to the aggregator.
+   *   5. Wait for the inclusion proof.
+   *   6. Construct an SDK Token via Token.mint().
+   *   7. Convert to wallet Token format and call addToken().
+   *
+   * @param coinIdHex - 64-char lowercase hex CoinId. Must match the bytes
+   *   used by the registered symbol if you want the wallet to recognize
+   *   the token as that symbol (e.g. UCT's coinId from the public registry).
+   * @param amount - Amount in smallest units (multiply by 10^decimals
+   *   when converting from human values).
+   * @returns Result with the resulting wallet Token and its on-chain id.
+   */
+  async mintFungibleToken(coinIdHex, amount) {
+    this.ensureInitialized();
+    const stClient = this.deps.oracle.getStateTransitionClient?.();
+    if (!stClient) {
+      return { success: false, error: "State transition client not available" };
+    }
+    const trustBase = this.deps.oracle.getTrustBase?.();
+    if (!trustBase) {
+      return { success: false, error: "Trust base not available" };
+    }
+    try {
+      const signingService = await this.createSigningService();
+      const { TokenId: TokenId5 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenId");
+      const { TokenCoinData: TokenCoinData3 } = await import("@unicitylabs/state-transition-sdk/lib/token/fungible/TokenCoinData");
+      const { UnmaskedPredicateReference: UnmaskedPredicateReference4 } = await import("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
+      const tokenTypeBytes = fromHex4("f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509");
+      const tokenType = new TokenType3(tokenTypeBytes);
+      const tokenIdBytes = new Uint8Array(32);
+      crypto.getRandomValues(tokenIdBytes);
+      const tokenId = new TokenId5(tokenIdBytes);
+      const coinIdBytes = fromHex4(coinIdHex);
+      const coinId = new CoinId4(coinIdBytes);
+      const coinData = TokenCoinData3.create([[coinId, amount]]);
+      const addressRef = await UnmaskedPredicateReference4.create(
+        tokenType,
+        signingService.algorithm,
+        signingService.publicKey,
+        HashAlgorithm5.SHA256
+      );
+      const ownerAddress = await addressRef.toAddress();
+      const salt = new Uint8Array(32);
+      crypto.getRandomValues(salt);
+      const mintData = await MintTransactionData3.create(
+        tokenId,
+        tokenType,
+        null,
+        // tokenData: no metadata
+        coinData,
+        // fungible coin data
+        ownerAddress,
+        // recipient = self
+        salt,
+        null,
+        // recipientDataHash
+        null
+        // reason: null (genesis, no burn predecessor)
+      );
+      const commitment = await MintCommitment3.create(mintData);
+      const MAX_RETRIES = 3;
+      let lastStatus;
+      for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        const response = await stClient.submitMintCommitment(commitment);
+        lastStatus = response.status;
+        if (response.status === "SUCCESS" || response.status === "REQUEST_ID_EXISTS") break;
+        if (attempt === MAX_RETRIES) {
+          return { success: false, error: `Mint submit failed after ${MAX_RETRIES} attempts: ${response.status}` };
+        }
+        await new Promise((r) => setTimeout(r, 1e3 * attempt));
+      }
+      if (lastStatus !== "SUCCESS" && lastStatus !== "REQUEST_ID_EXISTS") {
+        return { success: false, error: `Mint submit failed: ${lastStatus}` };
+      }
+      const inclusionProof = await waitInclusionProof5(trustBase, stClient, commitment);
+      const genesisTransaction = commitment.toTransaction(inclusionProof);
+      const predicate = await UnmaskedPredicate5.create(
+        tokenId,
+        tokenType,
+        signingService,
+        HashAlgorithm5.SHA256,
+        salt
+      );
+      const tokenState = new TokenState5(predicate, null);
+      const sdkToken = await SdkToken2.mint(trustBase, tokenState, genesisTransaction);
+      const tokenIdHex = tokenId.toJSON();
+      const symbol = this.getCoinSymbol(coinIdHex);
+      const name = this.getCoinName(coinIdHex);
+      const decimals = this.getCoinDecimals(coinIdHex);
+      const iconUrl = this.getCoinIconUrl(coinIdHex);
+      const uiToken = {
+        id: tokenIdHex,
+        coinId: coinIdHex,
+        symbol,
+        name,
+        decimals,
+        ...iconUrl !== void 0 ? { iconUrl } : {},
+        amount: amount.toString(),
+        status: "confirmed",
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        sdkData: JSON.stringify(sdkToken.toJSON())
+      };
+      await this.addToken(uiToken);
+      return { success: true, token: uiToken, tokenId: tokenIdHex };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: `Local mint failed: ${msg}` };
+    }
+  }
   /**
    * Check if a nametag is available for minting
    * @param nametag - The nametag to check (e.g., "alice" or "@alice")
@@ -18416,6 +18683,24 @@ var AccountingModule = class _AccountingModule {
   dirtyLedgerEntries = /* @__PURE__ */ new Set();
   /** Count of unknown (not in invoiceTermsCache) invoice IDs in the ledger. */
   unknownLedgerCount = 0;
+  /**
+   * Per-unknown-invoice first-seen timestamp for TTL eviction.
+   *
+   * W1 (steelman round-4): without TTL, an attacker who can deliver 500
+   * inbound transfers with synthesized memo invoiceIds permanently exhausts
+   * the unknown-ledger cap, after which legitimate orphan transfers (out-of-
+   * order delivery for real swaps) are silently dropped at the cap-check.
+   *
+   * Round-5 perf: gated by `unknownLedgerNextSweepMs` to amortize the
+   * sweep cost. The naive every-call sweep is O(N) where N=cap=500;
+   * combined with the per-token cleanup loop inside the sweep it became
+   * O(N×M) on every transfer under flood. Now we sweep at most every
+   * `UNKNOWN_LEDGER_SWEEP_INTERVAL_MS` (60s) UNLESS the cap is currently
+   * full, in which case we sweep on each call (the only path that can
+   * actually drop a legitimate orphan).
+   */
+  unknownLedgerFirstSeen = /* @__PURE__ */ new Map();
+  unknownLedgerNextSweepMs = 0;
   /** W17: Tracks whether tokenScanState has been mutated since last flush. */
   tokenScanDirty = false;
   /** W2 fix: Serialization guard for _flushDirtyLedgerEntries. */
@@ -19406,6 +19691,7 @@ var AccountingModule = class _AccountingModule {
     }
     if (this.invoiceLedger.has(tokenId) && !this.invoiceTermsCache.has(tokenId)) {
       this.unknownLedgerCount = Math.max(0, this.unknownLedgerCount - 1);
+      this.unknownLedgerFirstSeen.delete(tokenId);
     }
     this.invoiceTermsCache.set(tokenId, terms);
     this._addToHashIndex(tokenId);
@@ -19674,6 +19960,29 @@ var AccountingModule = class _AccountingModule {
       closed: this.closedInvoices.has(invoiceId)
     };
   }
+  /**
+   * Return the set of token IDs that are currently linked to the given
+   * invoice. Populated by both the on-chain `_processTokenTransactions`
+   * path (tokens with `inv:` references) and the transport-memo orphan
+   * buffering path in `_handleIncomingTransfer`.
+   *
+   * Used by callers that want to scope per-invoice operations (e.g.
+   * SwapModule.verifyPayout's L3 validation) to only the tokens that
+   * cover this invoice — avoiding false negatives when the wallet
+   * contains unrelated tokens of the same currency in unconfirmed or
+   * spent state.
+   *
+   * Returns an empty set if no tokens are currently linked.
+   */
+  getTokenIdsForInvoice(invoiceId) {
+    const result = /* @__PURE__ */ new Set();
+    for (const [tokenId, invoiceIds] of this.tokenInvoiceMap) {
+      if (invoiceIds.has(invoiceId)) {
+        result.add(tokenId);
+      }
+    }
+    return result;
+  }
   /**
    * Explicitly close an invoice. Only target parties may close (§8.3).
    *
@@ -19993,6 +20302,7 @@ var AccountingModule = class _AccountingModule {
           ledger.set(entryKey, forwardRef);
           this.dirtyLedgerEntries.add(invoiceId);
           this.balanceCache.delete(invoiceId);
+          await this._persistProvisionalAndVerify(invoiceId, "payInvoice");
         }
         return result;
       } finally {
@@ -20160,6 +20470,7 @@ var AccountingModule = class _AccountingModule {
             this.dirtyLedgerEntries.add(invoiceId);
           }
           this.balanceCache.delete(invoiceId);
+          await this._persistProvisionalAndVerify(invoiceId, "returnInvoicePayment");
         }
         return result;
       } finally {
@@ -21239,9 +21550,30 @@ var AccountingModule = class _AccountingModule {
             continue;
           }
           innerMap.set(entryKey, ref);
-          if (!ref.transferId.startsWith("provisional:") && ref.transferId.includes(":")) {
+          const HEX_64 = /^[a-f0-9]{64}$/i;
+          if (entryKey.startsWith("mt:")) {
+            const firstColon = entryKey.indexOf(":");
+            const secondColon = entryKey.indexOf(":", firstColon + 1);
+            if (secondColon > firstColon + 1) {
+              const tokenIdFromKey2 = entryKey.slice(firstColon + 1, secondColon);
+              if (HEX_64.test(tokenIdFromKey2)) {
+                this._addToTokenInvoiceMap(tokenIdFromKey2, invoiceId);
+              }
+            }
+          } else if (entryKey.startsWith("synthetic:")) {
+            const afterPrefix = entryKey.slice("synthetic:".length);
+            const tokenIdEnd = afterPrefix.indexOf(":");
+            if (tokenIdEnd > 0) {
+              const tokenId = afterPrefix.slice(0, tokenIdEnd);
+              if (HEX_64.test(tokenId) && ref.transferId !== tokenId) {
+                this._addToTokenInvoiceMap(tokenId, invoiceId);
+              }
+            }
+          } else if (!ref.transferId.startsWith("provisional:") && ref.transferId.includes(":")) {
             const tokenIdFromRef = ref.transferId.slice(0, ref.transferId.indexOf(":"));
-            this._addToTokenInvoiceMap(tokenIdFromRef, invoiceId);
+            if (HEX_64.test(tokenIdFromRef)) {
+              this._addToTokenInvoiceMap(tokenIdFromRef, invoiceId);
+            }
           }
         }
       } catch (err) {
@@ -21442,7 +21774,14 @@ var AccountingModule = class _AccountingModule {
           }
         }
         for (const [existingKey, existingRef] of ledger) {
-          if (existingKey.startsWith("synthetic:") && existingRef.coinId === coinId && existingRef.paymentDirection === paymentDirection) {
+          if ((existingKey.startsWith("synthetic:") || existingKey.startsWith("synthetic-tx:")) && existingRef.coinId === coinId && existingRef.paymentDirection === paymentDirection) {
+            keysToDelete.push(existingKey);
+            break;
+          }
+        }
+        const mtPrefix = `mt:${tokenId}:`;
+        for (const [existingKey, existingRef] of ledger) {
+          if (existingKey.startsWith(mtPrefix) && existingRef.coinId === coinId && existingRef.paymentDirection === paymentDirection) {
             keysToDelete.push(existingKey);
             break;
           }
@@ -21559,6 +21898,49 @@ var AccountingModule = class _AccountingModule {
       });
     }
   }
+  /**
+   * Synchronously persist any pending provisional ledger entry for `invoiceId`
+   * before returning to the caller. Used by `payInvoice` and
+   * `returnInvoicePayment` to make the in-memory provisional entry durable
+   * inside the same per-invoice gate that wrote it, closing the
+   * crash-mid-conclude race that produces over-coverage on receivers.
+   *
+   * Implementation:
+   *   1. Schedule a flush via the existing `_flushPromise` chain (so
+   *      concurrent `_handleTokenChange` callers waiting on the chain
+   *      observe ours as part of the sequence).
+   *   2. Await OUR flush directly — NOT `_drainFlushPromise()`, which would
+   *      spin while concurrent token changes keep extending the chain and
+   *      hold the per-invoice gate for an unbounded number of additional
+   *      flushes. We only need OUR provisional entry durable.
+   *   3. `_flushDirtyLedgerEntries` swallows per-invoice `storage.set`
+   *      rejections internally (sets a local `step1Failed` flag), leaving
+   *      the dirty entry on the set without re-throwing. So we post-check
+   *      `dirtyLedgerEntries.has(invoiceId)` and throw a `STORAGE_ERROR`
+   *      `SphereError` if our entry is still dirty — propagating to the
+   *      caller so they learn about the durability failure rather than
+   *      receiving a silent "success" return that lies on disk.
+   *
+   * @param invoiceId    The invoice whose provisional entry must be durable.
+   * @param callContext  Used in the error message so the caller is named
+   *                     ('payInvoice' / 'returnInvoicePayment') without
+   *                     forcing a stack-trace inspection.
+   */
+  async _persistProvisionalAndVerify(invoiceId, callContext) {
+    const flushTrigger = (this._flushPromise ?? Promise.resolve()).then(() => this._flushDirtyLedgerEntries());
+    const tracked = flushTrigger.catch(() => {
+    }).finally(() => {
+      if (this._flushPromise === tracked) this._flushPromise = null;
+    });
+    this._flushPromise = tracked;
+    await flushTrigger;
+    if (this.dirtyLedgerEntries.has(invoiceId)) {
+      throw new SphereError(
+        `${callContext}: provisional ledger entry for invoice ${invoiceId} failed to persist \u2014 caller should retry`,
+        "STORAGE_ERROR"
+      );
+    }
+  }
   // ===========================================================================
   // Internal: Event handlers
   // ===========================================================================
@@ -21619,13 +22001,96 @@ var AccountingModule = class _AccountingModule {
       }
     }
     if (!this.invoiceTermsCache.has(invoiceId)) {
-      const syntheticRef = this._buildSyntheticTransferRef(
-        transfer,
-        invoiceId,
-        paymentDirection,
-        confirmed
-      );
-      deps.emitEvent("invoice:unknown_reference", { invoiceId, transfer: syntheticRef });
+      let gracefullyGraduated = false;
+      await this.withInvoiceGate(invoiceId, async () => {
+        if (this.invoiceTermsCache.has(invoiceId)) {
+          gracefullyGraduated = true;
+          return;
+        }
+        const syntheticRef = this._buildSyntheticTransferRef(
+          transfer,
+          invoiceId,
+          paymentDirection,
+          confirmed
+        );
+        deps.emitEvent("invoice:unknown_reference", { invoiceId, transfer: syntheticRef });
+        const MAX_UNKNOWN_INVOICE_IDS = 500;
+        const UNKNOWN_LEDGER_TTL_MS = 30 * 60 * 1e3;
+        const MAX_ORPHAN_ENTRIES_PER_INVOICE = 50;
+        const UNKNOWN_LEDGER_SWEEP_INTERVAL_MS = 6e4;
+        const nowMs = Date.now();
+        const capFull = this.unknownLedgerCount >= MAX_UNKNOWN_INVOICE_IDS;
+        const sweepDue = nowMs >= this.unknownLedgerNextSweepMs;
+        if (this.unknownLedgerFirstSeen.size > 0 && (capFull || sweepDue)) {
+          this.unknownLedgerNextSweepMs = nowMs + UNKNOWN_LEDGER_SWEEP_INTERVAL_MS;
+          const expiredIds = [];
+          for (const [unkId, firstSeen] of this.unknownLedgerFirstSeen) {
+            if (nowMs - firstSeen > UNKNOWN_LEDGER_TTL_MS) {
+              expiredIds.push(unkId);
+            }
+          }
+          for (const expiredId of expiredIds) {
+            if (!this.invoiceTermsCache.has(expiredId) && this.invoiceLedger.has(expiredId)) {
+              this.invoiceLedger.delete(expiredId);
+              this.unknownLedgerCount = Math.max(0, this.unknownLedgerCount - 1);
+              for (const [tokenId, invoiceSet] of this.tokenInvoiceMap) {
+                if (invoiceSet.has(expiredId)) {
+                  invoiceSet.delete(expiredId);
+                  if (invoiceSet.size === 0) this.tokenInvoiceMap.delete(tokenId);
+                }
+              }
+            }
+            this.unknownLedgerFirstSeen.delete(expiredId);
+          }
+        }
+        if (!this.invoiceLedger.has(invoiceId)) {
+          if (this.unknownLedgerCount >= MAX_UNKNOWN_INVOICE_IDS) {
+            return;
+          }
+          this.invoiceLedger.set(invoiceId, /* @__PURE__ */ new Map());
+          this.unknownLedgerCount++;
+          this.unknownLedgerFirstSeen.set(invoiceId, nowMs);
+        }
+        const orphanLedger = this.invoiceLedger.get(invoiceId);
+        let mtEntryCount = 0;
+        for (const k of orphanLedger.keys()) {
+          if (k.startsWith("mt:")) mtEntryCount++;
+        }
+        if (mtEntryCount >= MAX_ORPHAN_ENTRIES_PER_INVOICE) {
+          return;
+        }
+        for (const token of transfer.tokens) {
+          if (!token.id) continue;
+          let onChainAttributed = false;
+          const tokenKeyPrefix = `${token.id}:`;
+          for (const existingKey of orphanLedger.keys()) {
+            if (existingKey.startsWith(tokenKeyPrefix) && !existingKey.startsWith("mt:")) {
+              onChainAttributed = true;
+              break;
+            }
+          }
+          if (!onChainAttributed) {
+            if (mtEntryCount >= MAX_ORPHAN_ENTRIES_PER_INVOICE) {
+              break;
+            }
+            const orphanKey = `mt:${token.id}:${transfer.id}`;
+            if (!orphanLedger.has(orphanKey)) {
+              orphanLedger.set(orphanKey, syntheticRef);
+              mtEntryCount++;
+            }
+          }
+          if (!this.tokenInvoiceMap.has(token.id)) {
+            this.tokenInvoiceMap.set(token.id, /* @__PURE__ */ new Set());
+          }
+          this.tokenInvoiceMap.get(token.id).add(invoiceId);
+        }
+        this.dirtyLedgerEntries.add(invoiceId);
+        this.balanceCache.delete(invoiceId);
+        await this._flushDirtyLedgerEntries();
+      });
+      if (gracefullyGraduated) {
+        await this._processInvoiceTransferEvent(transfer, invoiceId, paymentDirection, confirmed);
+      }
       return;
     }
     await this._processInvoiceTransferEvent(transfer, invoiceId, paymentDirection, confirmed);
@@ -22061,7 +22526,8 @@ var AccountingModule = class _AccountingModule {
       }
       const existingLedger = this.invoiceLedger.get(invoiceId);
       const firstTokenId = transfer.tokens.find((t) => t.id)?.id;
-      const syntheticKey = firstTokenId ? `synthetic:${firstTokenId}::${syntheticRef.coinId}` : `synthetic:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      const syntheticKey = firstTokenId ? `synthetic:${firstTokenId}::${syntheticRef.coinId}` : `synthetic-tx:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      let mutated = false;
       if (!existingLedger.has(syntheticKey)) {
         let hasRealEntry = false;
         for (const tok of transfer.tokens) {
@@ -22076,8 +22542,25 @@ var AccountingModule = class _AccountingModule {
         }
         if (!hasRealEntry) {
           existingLedger.set(syntheticKey, { ...syntheticRef });
+          mutated = true;
+        }
+      }
+      for (const tok of transfer.tokens) {
+        if (!tok.id) continue;
+        if (!this.tokenInvoiceMap.has(tok.id)) {
+          this.tokenInvoiceMap.set(tok.id, /* @__PURE__ */ new Set());
+          mutated = true;
+        }
+        const beforeSize = this.tokenInvoiceMap.get(tok.id).size;
+        this.tokenInvoiceMap.get(tok.id).add(invoiceId);
+        if (this.tokenInvoiceMap.get(tok.id).size !== beforeSize) {
+          mutated = true;
         }
       }
+      if (mutated) {
+        this.dirtyLedgerEntries.add(invoiceId);
+        this.balanceCache.delete(invoiceId);
+      }
       deps.emitEvent("invoice:payment", {
         invoiceId,
         transfer: syntheticRef,
@@ -22227,7 +22710,8 @@ var AccountingModule = class _AccountingModule {
         this.invoiceLedger.set(invoiceId, /* @__PURE__ */ new Map());
       }
       const hLedger = this.invoiceLedger.get(invoiceId);
-      const hKey = entry.tokenId ? `synthetic:${entry.tokenId}::${syntheticRef.coinId}` : `synthetic:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      const hKey = entry.tokenId ? `synthetic:${entry.tokenId}::${syntheticRef.coinId}` : `synthetic-tx:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      let hMutated = false;
       if (!hLedger.has(hKey)) {
         let hasRealEntry = false;
         if (entry.tokenId) {
@@ -22240,8 +22724,24 @@ var AccountingModule = class _AccountingModule {
         }
         if (!hasRealEntry) {
           hLedger.set(hKey, { ...syntheticRef });
+          hMutated = true;
+        }
+      }
+      if (entry.tokenId) {
+        if (!this.tokenInvoiceMap.has(entry.tokenId)) {
+          this.tokenInvoiceMap.set(entry.tokenId, /* @__PURE__ */ new Set());
+          hMutated = true;
+        }
+        const beforeSize = this.tokenInvoiceMap.get(entry.tokenId).size;
+        this.tokenInvoiceMap.get(entry.tokenId).add(invoiceId);
+        if (this.tokenInvoiceMap.get(entry.tokenId).size !== beforeSize) {
+          hMutated = true;
         }
       }
+      if (hMutated) {
+        this.dirtyLedgerEntries.add(invoiceId);
+        this.balanceCache.delete(invoiceId);
+      }
       deps.emitEvent("invoice:payment", {
         invoiceId,
         transfer: syntheticRef,
@@ -24787,17 +25287,63 @@ var SwapModule = class {
     for (const addr of allAddresses) {
       myDirectAddresses.add(addr.directAddress);
     }
-    let assetIndex;
-    if (myDirectAddresses.has(swap.manifest.party_a_address)) {
-      assetIndex = 0;
-    } else if (myDirectAddresses.has(swap.manifest.party_b_address)) {
-      assetIndex = 1;
+    const matchesPartyA = myDirectAddresses.has(swap.manifest.party_a_address);
+    const matchesPartyB = myDirectAddresses.has(swap.manifest.party_b_address);
+    if (matchesPartyA && matchesPartyB) {
+      throw new SphereError(
+        "Ambiguous party identity: local wallet matches both party_a_address and party_b_address",
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    let myExpectedCurrency;
+    if (matchesPartyA) {
+      myExpectedCurrency = swap.manifest.party_a_currency_to_change;
+    } else if (matchesPartyB) {
+      myExpectedCurrency = swap.manifest.party_b_currency_to_change;
     } else {
       throw new SphereError(
         "Local wallet address does not match either party in the swap manifest",
         "SWAP_DEPOSIT_FAILED"
       );
     }
+    if (!myExpectedCurrency || myExpectedCurrency === "") {
+      throw new SphereError(
+        "Manifest currency_to_change is empty for this party",
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    const invoiceRefForAssetLookup = deps.accounting.getInvoice(swap.depositInvoiceId);
+    if (!invoiceRefForAssetLookup) {
+      throw new SphereError(
+        "Deposit invoice not yet imported into accounting module",
+        "SWAP_WRONG_STATE"
+      );
+    }
+    const depositTarget = invoiceRefForAssetLookup.terms.targets[0];
+    if (!depositTarget) {
+      throw new SphereError(
+        "Deposit invoice has no targets",
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    const assetIndex = depositTarget.assets.findIndex(
+      (a) => a.coin !== void 0 && coinIdsMatch(a.coin[0], myExpectedCurrency)
+    );
+    if (assetIndex < 0) {
+      throw new SphereError(
+        `No asset matching expected currency ${myExpectedCurrency} found in deposit invoice`,
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    for (let i = assetIndex + 1; i < depositTarget.assets.length; i += 1) {
+      const a = depositTarget.assets[i];
+      if (a?.coin !== void 0 && coinIdsMatch(a.coin[0], myExpectedCurrency)) {
+        throw new SphereError(
+          `Ambiguous asset match in deposit invoice: slots ${assetIndex} and ${i} both match currency ${myExpectedCurrency}`,
+          "SWAP_DEPOSIT_FAILED"
+        );
+      }
+    }
     return this.withSwapGate(swapId, async () => {
       if (swap.progress !== "announced") {
         throw new SphereError(
@@ -24903,7 +25449,6 @@ var SwapModule = class {
           swap.updatedAt = Date.now();
           this.clearLocalTimer(swap.swapId);
           this.terminalSwapIds.add(swap.swapId);
-          const entryIdx = this._storedTerminalEntries.length;
           this._storedTerminalEntries.push({
             swapId: swap.swapId,
             progress: "failed",
@@ -24918,7 +25463,13 @@ var SwapModule = class {
             swap.error = prevError;
             swap.updatedAt = prevUpdatedAt;
             this.terminalSwapIds.delete(swap.swapId);
-            this._storedTerminalEntries.splice(entryIdx, 1);
+            for (let i = this._storedTerminalEntries.length - 1; i >= 0; i--) {
+              const entry = this._storedTerminalEntries[i];
+              if (entry.swapId === swap.swapId && entry.progress === "failed") {
+                this._storedTerminalEntries.splice(i, 1);
+                break;
+              }
+            }
             logger.warn(LOG_TAG3, `failPayout: persistSwap failed for ${swapId}; fraud detection will retry on next load:`, persistErr);
             throw persistErr;
           }
@@ -24962,9 +25513,25 @@ var SwapModule = class {
       if (!targetStatus.coinAssets[0].isCovered) {
         return returnFalse();
       }
-      if (BigInt(targetStatus.coinAssets[0].netCoveredAmount) < BigInt(expectedAmount)) {
+      let netCoveredAmount;
+      let expectedAmountBigInt;
+      try {
+        netCoveredAmount = BigInt(targetStatus.coinAssets[0].netCoveredAmount);
+        expectedAmountBigInt = BigInt(expectedAmount);
+      } catch (parseErr) {
+        return failPayout(
+          `MALFORMED_AMOUNT: failed to parse coverage amounts (netCoveredAmount=${targetStatus.coinAssets[0].netCoveredAmount}, expectedAmount=${expectedAmount}): ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`
+        );
+      }
+      if (netCoveredAmount < expectedAmountBigInt) {
         return returnFalse();
       }
+      if (netCoveredAmount > expectedAmountBigInt) {
+        const surplus = netCoveredAmount - expectedAmountBigInt;
+        return failPayout(
+          `OVER_COVERAGE: net=${netCoveredAmount.toString()}, expected=${expectedAmount}, surplus=${surplus.toString()} \u2014 surplus refund expected via auto-return; settlement halted`
+        );
+      }
       const escrowAddr = swap.deal.escrowAddress ?? this.config.defaultEscrowAddress;
       if (escrowAddr) {
         const escrowPeer = await deps.resolve(escrowAddr);
@@ -24974,8 +25541,28 @@ var SwapModule = class {
       }
       const validationResult = await deps.payments.validate();
       if (validationResult.invalid.length > 0) {
-        logger.warn(LOG_TAG3, `verifyPayout for ${swapId.slice(0, 12)}: L3 validation found ${validationResult.invalid.length} invalid token(s) \u2014 retry after wallet sync`);
-        return returnFalse();
+        const payoutTokenIds = deps.accounting.getTokenIdsForInvoice?.(swap.payoutInvoiceId) ?? /* @__PURE__ */ new Set();
+        if (payoutTokenIds.size === 0) {
+          logger.warn(
+            LOG_TAG3,
+            `verifyPayout for ${swapId.slice(0, 12)}: ${validationResult.invalid.length} invalid token(s) but tokenInvoiceMap is empty for this payout invoice \u2014 failing closed until reverse index rebuilds`
+          );
+          return returnFalse();
+        }
+        const relevantInvalid = validationResult.invalid.filter(
+          (t) => payoutTokenIds.has(t.id)
+        );
+        if (relevantInvalid.length > 0) {
+          logger.warn(
+            LOG_TAG3,
+            `verifyPayout for ${swapId.slice(0, 12)}: L3 validation found ${relevantInvalid.length} invalid token(s) covering this payout invoice \u2014 retry after wallet sync`
+          );
+          return returnFalse();
+        }
+        logger.debug(
+          LOG_TAG3,
+          `verifyPayout for ${swapId.slice(0, 12)}: ${validationResult.invalid.length} unrelated invalid token(s) ignored (not linked to this payout invoice)`
+        );
       }
       if (swap.progress === "completed") {
         swap.payoutVerified = true;
@@ -25154,8 +25741,22 @@ var SwapModule = class {
    * @param dm - The incoming direct message.
    */
   handleIncomingDM(dm) {
+    if (dm.content.startsWith("{") && dm.content.includes('"invoice_delivery"')) {
+      logger.warn(
+        LOG_TAG3,
+        `diag_swap_dm_arrived sender=${dm.senderPubkey.slice(0, 16)} length=${dm.content.length}`
+      );
+    }
     const parsed = parseSwapDM(dm.content);
-    if (!parsed) return;
+    if (!parsed) {
+      if (dm.content.startsWith("{") && dm.content.includes('"invoice_delivery"')) {
+        logger.warn(
+          LOG_TAG3,
+          `diag_swap_dm_parse_rejected sender=${dm.senderPubkey.slice(0, 16)} prefix=${dm.content.slice(0, 80)}`
+        );
+      }
+      return;
+    }
     void (async () => {
       try {
         switch (parsed.kind) {
@@ -25521,16 +26122,43 @@ var SwapModule = class {
               // invoice_delivery (§12.4.2 + §12.4.3)
               // ---------------------------------------------------------------
               case "invoice_delivery": {
-                if (!swapId) return;
+                logger.warn(
+                  LOG_TAG3,
+                  `diag_invoice_delivery_received swap_id=${swapId?.slice(0, 16)} sender=${dm.senderPubkey.slice(0, 16)} invoice_type=${msg.invoice_type} invoice_id=${msg.invoice_id?.slice(0, 16)}`
+                );
+                if (!swapId) {
+                  logger.warn(LOG_TAG3, "diag_invoice_delivery_dropped reason=no_swap_id");
+                  return;
+                }
                 const swap = this.swaps.get(swapId);
-                if (!swap) return;
-                if (!this.isFromExpectedEscrow(dm.senderPubkey, swap)) return;
+                if (!swap) {
+                  logger.warn(
+                    LOG_TAG3,
+                    `diag_invoice_delivery_dropped reason=swap_not_in_map swap_id=${swapId.slice(0, 16)} known_swap_ids_count=${this.swaps.size}`
+                  );
+                  return;
+                }
+                if (!this.isFromExpectedEscrow(dm.senderPubkey, swap)) {
+                  logger.warn(
+                    LOG_TAG3,
+                    `diag_invoice_delivery_dropped reason=not_expected_escrow swap_id=${swapId.slice(0, 16)} sender=${dm.senderPubkey.slice(0, 16)} expected_escrow_pubkey=${swap.escrowPubkey?.slice(0, 16)} expected_escrow_addr=${swap.escrowDirectAddress?.slice(0, 24)}`
+                  );
+                  return;
+                }
                 const deps = this.deps;
                 if (msg.invoice_type === "deposit") {
+                  logger.warn(
+                    LOG_TAG3,
+                    `diag_invoice_delivery_proceeding_to_import swap_id=${swapId.slice(0, 16)} progress=${swap.progress} invoice_id=${(msg.invoice_id ?? "").slice(0, 16)}`
+                  );
                   await this.withSwapGate(swapId, async () => {
                     if (isTerminalProgress(swap.progress)) return;
                     try {
                       await deps.accounting.importInvoice(msg.invoice_token);
+                      logger.warn(
+                        LOG_TAG3,
+                        `diag_invoice_imported swap_id=${swapId.slice(0, 16)} invoice_id=${(msg.invoice_id ?? "").slice(0, 16)} type=deposit`
+                      );
                     } catch (err) {
                       if (err instanceof SphereError && err.code === "INVOICE_ALREADY_EXISTS") {
                         logger.debug(LOG_TAG3, `Deposit invoice for swap ${swapId} already imported \u2014 relay re-delivery, continuing`);
@@ -26169,6 +26797,65 @@ init_constants();
 init_errors();
 init_logger();
 import CryptoJS6 from "crypto-js";
+var DEFAULT_ITERATIONS = 1e5;
+var KEY_SIZE = 256;
+var SALT_SIZE = 16;
+var IV_SIZE = 16;
+function deriveKey(password, salt, iterations) {
+  return CryptoJS6.PBKDF2(password, salt, {
+    keySize: KEY_SIZE / 32,
+    // WordArray uses 32-bit words
+    iterations,
+    hasher: CryptoJS6.algo.SHA256
+  });
+}
+function encrypt2(plaintext, password, options = {}) {
+  const iterations = options.iterations ?? DEFAULT_ITERATIONS;
+  const data = typeof plaintext === "string" ? plaintext : JSON.stringify(plaintext);
+  const salt = CryptoJS6.lib.WordArray.random(SALT_SIZE);
+  const iv = CryptoJS6.lib.WordArray.random(IV_SIZE);
+  const key = deriveKey(password, salt, iterations);
+  const encrypted = CryptoJS6.AES.encrypt(data, key, {
+    iv,
+    mode: CryptoJS6.mode.CBC,
+    padding: CryptoJS6.pad.Pkcs7
+  });
+  return {
+    ciphertext: encrypted.ciphertext.toString(CryptoJS6.enc.Base64),
+    iv: iv.toString(CryptoJS6.enc.Hex),
+    salt: salt.toString(CryptoJS6.enc.Hex),
+    algorithm: "aes-256-cbc",
+    kdf: "pbkdf2",
+    iterations
+  };
+}
+function decrypt2(encryptedData, password) {
+  const salt = CryptoJS6.enc.Hex.parse(encryptedData.salt);
+  const iv = CryptoJS6.enc.Hex.parse(encryptedData.iv);
+  const key = deriveKey(password, salt, encryptedData.iterations);
+  const ciphertext = CryptoJS6.enc.Base64.parse(encryptedData.ciphertext);
+  const cipherParams = CryptoJS6.lib.CipherParams.create({
+    ciphertext
+  });
+  const decrypted = CryptoJS6.AES.decrypt(cipherParams, key, {
+    iv,
+    mode: CryptoJS6.mode.CBC,
+    padding: CryptoJS6.pad.Pkcs7
+  });
+  const result = decrypted.toString(CryptoJS6.enc.Utf8);
+  if (!result) {
+    throw new SphereError("Decryption failed: invalid password or corrupted data", "DECRYPTION_ERROR");
+  }
+  return result;
+}
+function decryptJson(encryptedData, password) {
+  const decrypted = decrypt2(encryptedData, password);
+  try {
+    return JSON.parse(decrypted);
+  } catch {
+    throw new SphereError("Decryption failed: invalid JSON data", "DECRYPTION_ERROR");
+  }
+}
 function encryptSimple(plaintext, password) {
   return CryptoJS6.AES.encrypt(plaintext, password).toString();
 }
@@ -26195,6 +26882,12 @@ function decryptWithSalt(ciphertext, password, salt) {
     return null;
   }
 }
+function encryptMnemonic(mnemonic, password) {
+  return encryptSimple(mnemonic, password);
+}
+function decryptMnemonic(encryptedMnemonic, password) {
+  return decryptSimple(encryptedMnemonic, password);
+}
 
 // core/scan.ts
 init_logger();
@@ -26938,27 +27631,42 @@ async function parseAndDecryptWalletDat(data, password, onProgress) {
 
 // core/Sphere.ts
 import { SigningService as SigningService2 } from "@unicitylabs/state-transition-sdk/lib/sign/SigningService";
+import { normalizeNametag as normalizeNametag2, isPhoneNumber } from "@unicitylabs/nostr-js-sdk";
+
+// core/address-derivation.ts
 import { TokenType as TokenType5 } 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";
-import { normalizeNametag as normalizeNametag2, isPhoneNumber } from "@unicitylabs/nostr-js-sdk";
+var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
+var COMPRESSED_PUBKEY_RE = /^(02|03)[0-9a-fA-F]{64}$/;
+async function computeDirectAddressFromChainPubkey(chainPubkey) {
+  if (typeof chainPubkey !== "string" || !COMPRESSED_PUBKEY_RE.test(chainPubkey)) {
+    throw new Error(
+      `computeDirectAddressFromChainPubkey: chainPubkey must be 66-char hex with 02/03 prefix, got "${String(chainPubkey).slice(0, 12)}..."`
+    );
+  }
+  const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
+  const tokenType = new TokenType5(tokenTypeBytes);
+  const publicKeyBytes = Buffer.from(chainPubkey, "hex");
+  const predicateRef = await UnmaskedPredicateReference3.create(
+    tokenType,
+    "secp256k1",
+    publicKeyBytes,
+    HashAlgorithm7.SHA256
+  );
+  return (await predicateRef.toAddress()).toString();
+}
+
+// core/Sphere.ts
 function isValidNametag2(nametag) {
   if (isPhoneNumber(nametag)) return true;
   return /^[a-z0-9_-]{3,20}$/.test(nametag);
 }
-var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
 async function deriveL3PredicateAddress(privateKey) {
   const secret = Buffer.from(privateKey, "hex");
   const signingService = await SigningService2.createFromSecret(secret);
-  const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
-  const tokenType = new TokenType5(tokenTypeBytes);
-  const predicateRef = UnmaskedPredicateReference3.create(
-    tokenType,
-    signingService.algorithm,
-    signingService.publicKey,
-    HashAlgorithm7.SHA256
-  );
-  return (await (await predicateRef).toAddress()).toString();
+  const pubkeyHex = Buffer.from(signingService.publicKey).toString("hex");
+  return computeDirectAddressFromChainPubkey(pubkeyHex);
 }
 var Sphere = class _Sphere {
   // Singleton
@@ -28412,6 +29120,9 @@ var Sphere = class _Sphere {
       this._transport.setFallbackSince(fallbackTs);
     }
     await this._transport.setIdentity(this._identity);
+    if (this._transportMux && typeof this._transportMux.rebindToSharedClient === "function") {
+      await this._transportMux.rebindToSharedClient();
+    }
     this.emitEvent("identity:changed", {
       l1Address: this._identity.l1Address,
       directAddress: this._identity.directAddress,
@@ -28622,7 +29333,12 @@ var Sphere = class _Sphere {
       this._transportMux = new MultiAddressTransportMux({
         relays: nostrTransport.getConfiguredRelays(),
         createWebSocket: nostrTransport.getWebSocketFactory(),
-        storage: nostrTransport.getStorageAdapter() ?? void 0
+        storage: nostrTransport.getStorageAdapter() ?? void 0,
+        // #123: share the original transport's NostrClient instead of
+        // opening a second WebSocket per relay. Pass a getter so the
+        // Mux resolves it at connect-time (after the transport finishes
+        // its own connect()).
+        sharedNostrClient: typeof nostrTransport.getNostrClient === "function" ? () => nostrTransport.getNostrClient() : void 0
       });
       await this._transportMux.connect();
       if (typeof nostrTransport.suppressSubscriptions === "function") {
@@ -30969,7 +31685,37 @@ function createPriceProvider(config) {
       throw new SphereError(`Unsupported price platform: ${String(config.platform)}`, "INVALID_CONFIG");
   }
 }
+
+// core/auth.ts
+var AuthVerificationError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "AuthVerificationError";
+    this.code = code;
+  }
+};
+async function verifySphereAuth(input) {
+  const { challenge, signature, chainPubkey } = input;
+  let directAddress;
+  try {
+    directAddress = await computeDirectAddressFromChainPubkey(chainPubkey);
+  } catch (err) {
+    throw new AuthVerificationError(
+      `chainPubkey is malformed: ${err.message}`,
+      "PUBKEY_MALFORMED"
+    );
+  }
+  if (!verifySignedMessage(challenge, signature, chainPubkey)) {
+    throw new AuthVerificationError(
+      "Signature does not verify against chainPubkey",
+      "SIGNATURE_INVALID"
+    );
+  }
+  return { chainPubkey, directAddress };
+}
 export {
+  AuthVerificationError,
   COIN_TYPES,
   CoinGeckoPriceProvider,
   CommunicationsModule,
@@ -31019,6 +31765,8 @@ export {
   buildTxfStorageData,
   bytesToHex3 as bytesToHex,
   checkNetworkHealth,
+  coinIdsMatch,
+  computeDirectAddressFromChainPubkey,
   computeSwapId,
   countCommittedTransactions,
   createAddress,
@@ -31037,22 +31785,34 @@ export {
   createSwapModule,
   createTokenValidator,
   decodeBech32,
+  decrypt2 as decrypt,
   decryptCMasterKey,
+  decryptJson,
+  decryptMnemonic,
   decryptNametag2 as decryptNametag,
   decryptPrivateKey,
+  decryptSimple,
   decryptTextFormatKey,
+  decryptWallet,
+  decryptWithSalt,
   deriveAddressInfo,
   deriveChildKey,
   deriveKeyAtPath,
   doubleSha256,
   encodeBech32,
+  encrypt2 as encrypt,
+  encryptMnemonic,
   encryptNametag,
+  encryptSimple,
+  encryptWallet,
   extractFromText,
   findPattern,
   forkedKeyFromTokenIdAndState,
   formatAmount,
+  generateAddressFromMasterKey,
   generateMasterKey,
   generateMnemonic2 as generateMnemonic,
+  generatePrivateKey,
   getAddressHrp,
   getAddressId,
   getAddressStorageKey,
@@ -31075,6 +31835,7 @@ export {
   hashNametag,
   hashSignMessage,
   hexToBytes2 as hexToBytes,
+  hexToWIF,
   identityFromMnemonicSync,
   initSphere,
   isArchivedKey,
@@ -31104,6 +31865,7 @@ export {
   logger,
   mnemonicToSeedSync2 as mnemonicToSeedSync,
   normalizeAddress,
+  normalizeCoinId,
   normalizeNametag3 as normalizeNametag,
   normalizeSdkTokenToStorage,
   objectToTxf,
@@ -31134,6 +31896,7 @@ export {
   verifyManifestIntegrity,
   verifyNametagBinding,
   verifySignedMessage,
+  verifySphereAuth,
   verifySwapSignature
 };
 /*! Bundled license information: