@unicitylabs/sphere-sdk 0.6.1 → 0.6.3

package/dist/index.js

@@ -806,6 +806,1112 @@ var init_network = __esm({
 init_logger();
 init_errors();
 
+// transport/MultiAddressTransportMux.ts
+init_logger();
+init_errors();
+import { Buffer as Buffer2 } from "buffer";
+import {
+  NostrKeyManager,
+  NIP04,
+  NIP17,
+  Event as NostrEventClass,
+  EventKinds,
+  NostrClient,
+  Filter,
+  isChatMessage,
+  isReadReceipt
+} from "@unicitylabs/nostr-js-sdk";
+
+// transport/websocket.ts
+function defaultUUIDGenerator() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+
+// transport/MultiAddressTransportMux.ts
+init_constants();
+var EVENT_KINDS = NOSTR_EVENT_KINDS;
+var COMPOSING_INDICATOR_KIND = 25050;
+var MultiAddressTransportMux = class {
+  config;
+  storage = null;
+  // Single NostrClient — one WebSocket connection for all addresses
+  nostrClient = null;
+  // KeyManager used for NostrClient creation (uses first address or temp key)
+  primaryKeyManager = null;
+  status = "disconnected";
+  // Per-address entries
+  addresses = /* @__PURE__ */ new Map();
+  // pubkey → address index (for fast routing)
+  pubkeyToIndex = /* @__PURE__ */ new Map();
+  // Subscription IDs
+  walletSubscriptionId = null;
+  chatSubscriptionId = null;
+  chatEoseFired = false;
+  chatEoseHandlers = [];
+  // Dedup
+  processedEventIds = /* @__PURE__ */ new Set();
+  // Event callbacks (mux-level, forwarded to all adapters)
+  eventCallbacks = /* @__PURE__ */ new Set();
+  constructor(config) {
+    this.config = {
+      relays: config.relays ?? [...DEFAULT_NOSTR_RELAYS],
+      timeout: config.timeout ?? TIMEOUTS.WEBSOCKET_CONNECT,
+      autoReconnect: config.autoReconnect ?? true,
+      reconnectDelay: config.reconnectDelay ?? TIMEOUTS.NOSTR_RECONNECT_DELAY,
+      maxReconnectAttempts: config.maxReconnectAttempts ?? TIMEOUTS.MAX_RECONNECT_ATTEMPTS,
+      createWebSocket: config.createWebSocket,
+      generateUUID: config.generateUUID ?? defaultUUIDGenerator
+    };
+    this.storage = config.storage ?? null;
+  }
+  // ===========================================================================
+  // Address Management
+  // ===========================================================================
+  /**
+   * Add an address to the multiplexer.
+   * Creates an AddressTransportAdapter for this address.
+   * If already connected, updates subscriptions to include the new pubkey.
+   */
+  async addAddress(index, identity, resolveDelegate) {
+    const existing = this.addresses.get(index);
+    if (existing) {
+      existing.identity = identity;
+      existing.keyManager = NostrKeyManager.fromPrivateKey(Buffer2.from(identity.privateKey, "hex"));
+      existing.nostrPubkey = existing.keyManager.getPublicKeyHex();
+      for (const [pk, idx] of this.pubkeyToIndex) {
+        if (idx === index) this.pubkeyToIndex.delete(pk);
+      }
+      this.pubkeyToIndex.set(existing.nostrPubkey, index);
+      logger.debug("Mux", `Updated address ${index}, pubkey: ${existing.nostrPubkey.slice(0, 16)}...`);
+      await this.updateSubscriptions();
+      return existing.adapter;
+    }
+    const keyManager = NostrKeyManager.fromPrivateKey(Buffer2.from(identity.privateKey, "hex"));
+    const nostrPubkey = keyManager.getPublicKeyHex();
+    const adapter = new AddressTransportAdapter(this, index, identity, resolveDelegate);
+    const entry = {
+      index,
+      identity,
+      keyManager,
+      nostrPubkey,
+      adapter,
+      lastEventTs: 0,
+      fallbackSince: null
+    };
+    this.addresses.set(index, entry);
+    this.pubkeyToIndex.set(nostrPubkey, index);
+    logger.debug("Mux", `Added address ${index}, pubkey: ${nostrPubkey.slice(0, 16)}..., total: ${this.addresses.size}`);
+    if (this.addresses.size === 1) {
+      this.primaryKeyManager = keyManager;
+    }
+    if (this.isConnected()) {
+      await this.updateSubscriptions();
+    }
+    return adapter;
+  }
+  /**
+   * Remove an address from the multiplexer.
+   * Stops routing events to this address.
+   */
+  async removeAddress(index) {
+    const entry = this.addresses.get(index);
+    if (!entry) return;
+    this.pubkeyToIndex.delete(entry.nostrPubkey);
+    this.addresses.delete(index);
+    logger.debug("Mux", `Removed address ${index}, remaining: ${this.addresses.size}`);
+    if (this.isConnected() && this.addresses.size > 0) {
+      await this.updateSubscriptions();
+    }
+  }
+  /**
+   * Get adapter for a specific address index.
+   */
+  getAdapter(index) {
+    return this.addresses.get(index)?.adapter;
+  }
+  /**
+   * Set fallback 'since' for an address (consumed once on next subscription setup).
+   */
+  setFallbackSince(index, sinceSeconds) {
+    const entry = this.addresses.get(index);
+    if (entry) {
+      entry.fallbackSince = sinceSeconds;
+    }
+  }
+  // ===========================================================================
+  // Connection Management (delegated from adapters)
+  // ===========================================================================
+  async connect() {
+    if (this.status === "connected") return;
+    this.status = "connecting";
+    try {
+      if (!this.primaryKeyManager) {
+        const tempKey = Buffer2.alloc(32);
+        crypto.getRandomValues(tempKey);
+        this.primaryKeyManager = NostrKeyManager.fromPrivateKey(tempKey);
+      }
+      this.nostrClient = new NostrClient(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() });
+        }
+      });
+      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() });
+      if (this.addresses.size > 0) {
+        await this.updateSubscriptions();
+      }
+    } catch (error) {
+      this.status = "error";
+      throw error;
+    }
+  }
+  async disconnect() {
+    if (this.nostrClient) {
+      this.nostrClient.disconnect();
+      this.nostrClient = null;
+    }
+    this.walletSubscriptionId = null;
+    this.chatSubscriptionId = null;
+    this.chatEoseFired = false;
+    this.status = "disconnected";
+    this.emitEvent({ type: "transport:disconnected", timestamp: Date.now() });
+  }
+  isConnected() {
+    return this.status === "connected" && this.nostrClient?.isConnected() === true;
+  }
+  getStatus() {
+    return this.status;
+  }
+  // ===========================================================================
+  // Relay Management
+  // ===========================================================================
+  getRelays() {
+    return [...this.config.relays];
+  }
+  getConnectedRelays() {
+    if (!this.nostrClient) return [];
+    return Array.from(this.nostrClient.getConnectedRelays());
+  }
+  async addRelay(relayUrl) {
+    if (this.config.relays.includes(relayUrl)) return false;
+    this.config.relays.push(relayUrl);
+    if (this.status === "connected" && this.nostrClient) {
+      try {
+        await this.nostrClient.connect(relayUrl);
+        this.emitEvent({ type: "transport:relay_added", timestamp: Date.now(), data: { relay: relayUrl, connected: true } });
+        return true;
+      } catch (error) {
+        this.emitEvent({ type: "transport:relay_added", timestamp: Date.now(), data: { relay: relayUrl, connected: false, error: String(error) } });
+        return false;
+      }
+    }
+    return true;
+  }
+  async removeRelay(relayUrl) {
+    const idx = this.config.relays.indexOf(relayUrl);
+    if (idx === -1) return false;
+    this.config.relays.splice(idx, 1);
+    this.emitEvent({ type: "transport:relay_removed", timestamp: Date.now(), data: { relay: relayUrl } });
+    return true;
+  }
+  hasRelay(relayUrl) {
+    return this.config.relays.includes(relayUrl);
+  }
+  isRelayConnected(relayUrl) {
+    if (!this.nostrClient) return false;
+    return this.nostrClient.getConnectedRelays().has(relayUrl);
+  }
+  // ===========================================================================
+  // Subscription Management
+  // ===========================================================================
+  /**
+   * Update Nostr subscriptions to listen for events on ALL registered address pubkeys.
+   * Called whenever addresses are added/removed.
+   */
+  async updateSubscriptions() {
+    if (!this.nostrClient || this.addresses.size === 0) return;
+    if (this.walletSubscriptionId) {
+      this.nostrClient.unsubscribe(this.walletSubscriptionId);
+      this.walletSubscriptionId = null;
+    }
+    if (this.chatSubscriptionId) {
+      this.nostrClient.unsubscribe(this.chatSubscriptionId);
+      this.chatSubscriptionId = null;
+    }
+    const allPubkeys = [];
+    for (const entry of this.addresses.values()) {
+      allPubkeys.push(entry.nostrPubkey);
+    }
+    logger.debug("Mux", `Subscribing for ${allPubkeys.length} address(es):`, allPubkeys.map((p) => p.slice(0, 12)).join(", "));
+    let globalSince = Math.floor(Date.now() / 1e3);
+    for (const entry of this.addresses.values()) {
+      const since = await this.getAddressSince(entry);
+      if (since < globalSince) {
+        globalSince = since;
+      }
+    }
+    const walletFilter = new Filter();
+    walletFilter.kinds = [
+      EVENT_KINDS.DIRECT_MESSAGE,
+      EVENT_KINDS.TOKEN_TRANSFER,
+      EVENT_KINDS.PAYMENT_REQUEST,
+      EVENT_KINDS.PAYMENT_REQUEST_RESPONSE
+    ];
+    walletFilter["#p"] = allPubkeys;
+    walletFilter.since = globalSince;
+    this.walletSubscriptionId = this.nostrClient.subscribe(walletFilter, {
+      onEvent: (event) => {
+        this.handleEvent({
+          id: event.id,
+          kind: event.kind,
+          content: event.content,
+          tags: event.tags,
+          pubkey: event.pubkey,
+          created_at: event.created_at,
+          sig: event.sig
+        });
+      },
+      onEndOfStoredEvents: () => {
+        logger.debug("Mux", "Wallet subscription EOSE");
+      },
+      onError: (_subId, error) => {
+        logger.debug("Mux", "Wallet subscription error:", error);
+      }
+    });
+    const chatFilter = new Filter();
+    chatFilter.kinds = [EventKinds.GIFT_WRAP];
+    chatFilter["#p"] = allPubkeys;
+    this.chatSubscriptionId = this.nostrClient.subscribe(chatFilter, {
+      onEvent: (event) => {
+        this.handleEvent({
+          id: event.id,
+          kind: event.kind,
+          content: event.content,
+          tags: event.tags,
+          pubkey: event.pubkey,
+          created_at: event.created_at,
+          sig: event.sig
+        });
+      },
+      onEndOfStoredEvents: () => {
+        logger.debug("Mux", "Chat subscription EOSE");
+        if (!this.chatEoseFired) {
+          this.chatEoseFired = true;
+          for (const handler of this.chatEoseHandlers) {
+            try {
+              handler();
+            } catch {
+            }
+          }
+        }
+      },
+      onError: (_subId, error) => {
+        logger.debug("Mux", "Chat subscription error:", error);
+      }
+    });
+  }
+  /**
+   * Determine 'since' timestamp for an address entry.
+   */
+  async getAddressSince(entry) {
+    if (this.storage) {
+      const storageKey = `${STORAGE_KEYS_GLOBAL.LAST_WALLET_EVENT_TS}_${entry.nostrPubkey.slice(0, 16)}`;
+      try {
+        const stored = await this.storage.get(storageKey);
+        if (stored) {
+          const ts = parseInt(stored, 10);
+          entry.lastEventTs = ts;
+          entry.fallbackSince = null;
+          return ts;
+        } else if (entry.fallbackSince !== null) {
+          const ts = entry.fallbackSince;
+          entry.lastEventTs = ts;
+          entry.fallbackSince = null;
+          return ts;
+        }
+      } catch {
+      }
+    }
+    return Math.floor(Date.now() / 1e3);
+  }
+  // ===========================================================================
+  // Event Routing
+  // ===========================================================================
+  /**
+   * Route an incoming Nostr event to the correct address adapter.
+   */
+  async handleEvent(event) {
+    if (event.id && this.processedEventIds.has(event.id)) return;
+    if (event.id) this.processedEventIds.add(event.id);
+    try {
+      if (event.kind === EventKinds.GIFT_WRAP) {
+        await this.routeGiftWrap(event);
+      } else {
+        const recipientPubkey = this.extractRecipientPubkey(event);
+        if (!recipientPubkey) {
+          logger.debug("Mux", "Event has no #p tag, dropping:", event.id?.slice(0, 12));
+          return;
+        }
+        const addressIndex = this.pubkeyToIndex.get(recipientPubkey);
+        if (addressIndex === void 0) {
+          logger.debug("Mux", "Event for unknown pubkey:", recipientPubkey.slice(0, 16), "dropping");
+          return;
+        }
+        const entry = this.addresses.get(addressIndex);
+        if (!entry) return;
+        await this.dispatchWalletEvent(entry, event);
+      }
+    } catch (error) {
+      logger.debug("Mux", "Failed to handle event:", event.id?.slice(0, 12), error);
+    }
+  }
+  /**
+   * Extract recipient pubkey from event's #p tag.
+   * Returns the first #p value that matches a known address pubkey,
+   * or the first #p value if none match.
+   */
+  extractRecipientPubkey(event) {
+    const pTags = event.tags?.filter((t) => t[0] === "p");
+    if (!pTags || pTags.length === 0) return null;
+    for (const tag of pTags) {
+      if (tag[1] && this.pubkeyToIndex.has(tag[1])) {
+        return tag[1];
+      }
+    }
+    return pTags[0]?.[1] ?? null;
+  }
+  /**
+   * Route a gift wrap event by trying decryption with each address keyManager.
+   */
+  async routeGiftWrap(event) {
+    for (const entry of this.addresses.values()) {
+      try {
+        const pm = NIP17.unwrap(event, entry.keyManager);
+        logger.debug("Mux", `Gift wrap decrypted by address ${entry.index}, sender: ${pm.senderPubkey?.slice(0, 16)}`);
+        if (pm.senderPubkey === entry.nostrPubkey) {
+          try {
+            const parsed = JSON.parse(pm.content);
+            if (parsed?.selfWrap && parsed.recipientPubkey) {
+              const message2 = {
+                id: parsed.originalId || pm.eventId,
+                senderTransportPubkey: pm.senderPubkey,
+                senderNametag: parsed.senderNametag,
+                recipientTransportPubkey: parsed.recipientPubkey,
+                content: parsed.text ?? "",
+                timestamp: pm.timestamp * 1e3,
+                encrypted: true,
+                isSelfWrap: true
+              };
+              entry.adapter.dispatchMessage(message2);
+              return;
+            }
+          } catch {
+          }
+          return;
+        }
+        if (isReadReceipt(pm)) {
+          if (pm.replyToEventId) {
+            const receipt = {
+              senderTransportPubkey: pm.senderPubkey,
+              messageEventId: pm.replyToEventId,
+              timestamp: pm.timestamp * 1e3
+            };
+            entry.adapter.dispatchReadReceipt(receipt);
+          }
+          return;
+        }
+        if (pm.kind === COMPOSING_INDICATOR_KIND) {
+          let senderNametag2;
+          let expiresIn = 3e4;
+          try {
+            const parsed = JSON.parse(pm.content);
+            senderNametag2 = parsed.senderNametag || void 0;
+            expiresIn = parsed.expiresIn ?? 3e4;
+          } catch {
+          }
+          entry.adapter.dispatchComposingIndicator({
+            senderPubkey: pm.senderPubkey,
+            senderNametag: senderNametag2,
+            expiresIn
+          });
+          return;
+        }
+        try {
+          const parsed = JSON.parse(pm.content);
+          if (parsed?.type === "typing") {
+            const indicator = {
+              senderTransportPubkey: pm.senderPubkey,
+              senderNametag: parsed.senderNametag,
+              timestamp: pm.timestamp * 1e3
+            };
+            entry.adapter.dispatchTypingIndicator(indicator);
+            return;
+          }
+        } catch {
+        }
+        if (!isChatMessage(pm)) return;
+        let content = pm.content;
+        let senderNametag;
+        try {
+          const parsed = JSON.parse(content);
+          if (typeof parsed === "object" && parsed.text !== void 0) {
+            content = parsed.text;
+            senderNametag = parsed.senderNametag || void 0;
+          }
+        } catch {
+        }
+        const message = {
+          id: event.id,
+          senderTransportPubkey: pm.senderPubkey,
+          senderNametag,
+          content,
+          timestamp: pm.timestamp * 1e3,
+          encrypted: true
+        };
+        entry.adapter.dispatchMessage(message);
+        return;
+      } catch {
+        continue;
+      }
+    }
+    logger.debug("Mux", "Gift wrap could not be decrypted by any address");
+  }
+  /**
+   * Dispatch a wallet event (non-gift-wrap) to the correct address adapter.
+   */
+  async dispatchWalletEvent(entry, event) {
+    switch (event.kind) {
+      case EVENT_KINDS.DIRECT_MESSAGE:
+        break;
+      case EVENT_KINDS.TOKEN_TRANSFER:
+        await this.handleTokenTransfer(entry, event);
+        break;
+      case EVENT_KINDS.PAYMENT_REQUEST:
+        await this.handlePaymentRequest(entry, event);
+        break;
+      case EVENT_KINDS.PAYMENT_REQUEST_RESPONSE:
+        await this.handlePaymentRequestResponse(entry, event);
+        break;
+    }
+    if (event.created_at) {
+      this.updateLastEventTimestamp(entry, event.created_at);
+    }
+  }
+  async handleTokenTransfer(entry, event) {
+    try {
+      const content = await this.decryptContent(entry, event.content, event.pubkey);
+      const payload = JSON.parse(content);
+      const transfer = {
+        id: event.id,
+        senderTransportPubkey: event.pubkey,
+        payload,
+        timestamp: event.created_at * 1e3
+      };
+      entry.adapter.dispatchTokenTransfer(transfer);
+    } catch (err) {
+      logger.debug("Mux", `Token transfer decrypt failed for address ${entry.index}:`, err?.message?.slice(0, 50));
+    }
+  }
+  async handlePaymentRequest(entry, event) {
+    try {
+      const content = await this.decryptContent(entry, event.content, event.pubkey);
+      const requestData = JSON.parse(content);
+      const request = {
+        id: event.id,
+        senderTransportPubkey: event.pubkey,
+        request: {
+          requestId: requestData.requestId,
+          amount: requestData.amount,
+          coinId: requestData.coinId,
+          message: requestData.message,
+          recipientNametag: requestData.recipientNametag,
+          metadata: requestData.metadata
+        },
+        timestamp: event.created_at * 1e3
+      };
+      entry.adapter.dispatchPaymentRequest(request);
+    } catch (err) {
+      logger.debug("Mux", `Payment request decrypt failed for address ${entry.index}:`, err?.message?.slice(0, 50));
+    }
+  }
+  async handlePaymentRequestResponse(entry, event) {
+    try {
+      const content = await this.decryptContent(entry, event.content, event.pubkey);
+      const responseData = JSON.parse(content);
+      const response = {
+        id: event.id,
+        responderTransportPubkey: event.pubkey,
+        response: {
+          requestId: responseData.requestId,
+          responseType: responseData.responseType,
+          message: responseData.message,
+          transferId: responseData.transferId
+        },
+        timestamp: event.created_at * 1e3
+      };
+      entry.adapter.dispatchPaymentRequestResponse(response);
+    } catch (err) {
+      logger.debug("Mux", `Payment response decrypt failed for address ${entry.index}:`, err?.message?.slice(0, 50));
+    }
+  }
+  // ===========================================================================
+  // Crypto Helpers
+  // ===========================================================================
+  async decryptContent(entry, content, senderPubkey) {
+    const decrypted = await NIP04.decryptHex(
+      content,
+      entry.keyManager.getPrivateKeyHex(),
+      senderPubkey
+    );
+    return this.stripContentPrefix(decrypted);
+  }
+  stripContentPrefix(content) {
+    const prefixes = ["payment_request:", "token_transfer:", "payment_response:"];
+    for (const prefix of prefixes) {
+      if (content.startsWith(prefix)) return content.slice(prefix.length);
+    }
+    return content;
+  }
+  // ===========================================================================
+  // Sending (called by adapters)
+  // ===========================================================================
+  /**
+   * Create an encrypted event using a specific address's keyManager.
+   * Used by AddressTransportAdapter for sending.
+   */
+  async createAndPublishEncryptedEvent(addressIndex, kind, content, tags) {
+    const entry = this.addresses.get(addressIndex);
+    if (!entry) throw new SphereError("Address not registered in mux", "NOT_INITIALIZED");
+    if (!this.nostrClient) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    const recipientTag = tags.find((t) => t[0] === "p");
+    if (!recipientTag?.[1]) throw new SphereError("No recipient pubkey in tags", "VALIDATION_ERROR");
+    const encrypted = await NIP04.encryptHex(
+      content,
+      entry.keyManager.getPrivateKeyHex(),
+      recipientTag[1]
+    );
+    const signedEvent = NostrEventClass.create(entry.keyManager, { kind, content: encrypted, tags });
+    const nostrEvent = NostrEventClass.fromJSON({
+      id: signedEvent.id,
+      kind: signedEvent.kind,
+      content: signedEvent.content,
+      tags: signedEvent.tags,
+      pubkey: signedEvent.pubkey,
+      created_at: signedEvent.created_at,
+      sig: signedEvent.sig
+    });
+    await this.nostrClient.publishEvent(nostrEvent);
+    return signedEvent.id;
+  }
+  /**
+   * Create and publish a NIP-17 gift wrap message for a specific address.
+   */
+  async sendGiftWrap(addressIndex, recipientPubkey, content) {
+    const entry = this.addresses.get(addressIndex);
+    if (!entry) throw new SphereError("Address not registered in mux", "NOT_INITIALIZED");
+    if (!this.nostrClient) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    const nostrRecipient = recipientPubkey.length === 66 && (recipientPubkey.startsWith("02") || recipientPubkey.startsWith("03")) ? recipientPubkey.slice(2) : recipientPubkey;
+    const giftWrap = NIP17.createGiftWrap(entry.keyManager, nostrRecipient, content);
+    const giftWrapEvent = NostrEventClass.fromJSON(giftWrap);
+    await this.nostrClient.publishEvent(giftWrapEvent);
+    const selfPubkey = entry.keyManager.getPublicKeyHex();
+    const senderNametag = entry.identity.nametag;
+    const selfWrapContent = JSON.stringify({
+      selfWrap: true,
+      originalId: giftWrap.id,
+      recipientPubkey,
+      senderNametag,
+      text: content
+    });
+    const selfGiftWrap = NIP17.createGiftWrap(entry.keyManager, selfPubkey, selfWrapContent);
+    const selfGiftWrapEvent = NostrEventClass.fromJSON(selfGiftWrap);
+    this.nostrClient.publishEvent(selfGiftWrapEvent).catch((err) => {
+      logger.debug("Mux", "Self-wrap publish failed:", err);
+    });
+    return giftWrap.id;
+  }
+  /**
+   * Publish a raw event (e.g., identity binding, broadcast).
+   */
+  async publishRawEvent(addressIndex, kind, content, tags) {
+    const entry = this.addresses.get(addressIndex);
+    if (!entry) throw new SphereError("Address not registered in mux", "NOT_INITIALIZED");
+    if (!this.nostrClient) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    const signedEvent = NostrEventClass.create(entry.keyManager, { kind, content, tags });
+    const nostrEvent = NostrEventClass.fromJSON({
+      id: signedEvent.id,
+      kind: signedEvent.kind,
+      content: signedEvent.content,
+      tags: signedEvent.tags,
+      pubkey: signedEvent.pubkey,
+      created_at: signedEvent.created_at,
+      sig: signedEvent.sig
+    });
+    await this.nostrClient.publishEvent(nostrEvent);
+    return signedEvent.id;
+  }
+  // ===========================================================================
+  // Resolve Methods (delegates to inner — these are stateless relay queries)
+  // ===========================================================================
+  /**
+   * Get the NostrClient for resolve operations.
+   * Adapters use this for resolve*, publishIdentityBinding, etc.
+   */
+  getNostrClient() {
+    return this.nostrClient;
+  }
+  /**
+   * Get keyManager for a specific address (used by adapters for resolve/binding).
+   */
+  getKeyManager(addressIndex) {
+    return this.addresses.get(addressIndex)?.keyManager ?? null;
+  }
+  /**
+   * Get identity for a specific address.
+   */
+  getIdentity(addressIndex) {
+    return this.addresses.get(addressIndex)?.identity ?? null;
+  }
+  // ===========================================================================
+  // Event timestamp persistence
+  // ===========================================================================
+  updateLastEventTimestamp(entry, createdAt) {
+    if (!this.storage) return;
+    if (createdAt <= entry.lastEventTs) return;
+    entry.lastEventTs = createdAt;
+    const storageKey = `${STORAGE_KEYS_GLOBAL.LAST_WALLET_EVENT_TS}_${entry.nostrPubkey.slice(0, 16)}`;
+    this.storage.set(storageKey, createdAt.toString()).catch((err) => {
+      logger.debug("Mux", "Failed to save last event timestamp:", err);
+    });
+  }
+  // ===========================================================================
+  // Mux-level event system
+  // ===========================================================================
+  onTransportEvent(callback) {
+    this.eventCallbacks.add(callback);
+    return () => this.eventCallbacks.delete(callback);
+  }
+  onChatReady(handler) {
+    if (this.chatEoseFired) {
+      try {
+        handler();
+      } catch {
+      }
+      return () => {
+      };
+    }
+    this.chatEoseHandlers.push(handler);
+    return () => {
+      const idx = this.chatEoseHandlers.indexOf(handler);
+      if (idx >= 0) this.chatEoseHandlers.splice(idx, 1);
+    };
+  }
+  emitEvent(event) {
+    for (const cb of this.eventCallbacks) {
+      try {
+        cb(event);
+      } catch {
+      }
+    }
+    for (const entry of this.addresses.values()) {
+      entry.adapter.emitTransportEvent(event);
+    }
+  }
+  // ===========================================================================
+  // Dedup Management
+  // ===========================================================================
+  /**
+   * Clear processed event IDs (e.g., on address change or periodic cleanup).
+   */
+  clearProcessedEvents() {
+    this.processedEventIds.clear();
+  }
+  /**
+   * Get the storage adapter (for adapters that need it).
+   */
+  getStorage() {
+    return this.storage;
+  }
+  /**
+   * Get the UUID generator.
+   */
+  getUUIDGenerator() {
+    return this.config.generateUUID;
+  }
+};
+var AddressTransportAdapter = class {
+  id;
+  name;
+  type = "p2p";
+  description;
+  mux;
+  addressIndex;
+  identity;
+  resolveDelegate;
+  // Per-address handler sets
+  messageHandlers = /* @__PURE__ */ new Set();
+  transferHandlers = /* @__PURE__ */ new Set();
+  paymentRequestHandlers = /* @__PURE__ */ new Set();
+  paymentRequestResponseHandlers = /* @__PURE__ */ new Set();
+  readReceiptHandlers = /* @__PURE__ */ new Set();
+  typingIndicatorHandlers = /* @__PURE__ */ new Set();
+  composingHandlers = /* @__PURE__ */ new Set();
+  instantSplitBundleHandlers = /* @__PURE__ */ new Set();
+  broadcastHandlers = /* @__PURE__ */ new Map();
+  eventCallbacks = /* @__PURE__ */ new Set();
+  pendingMessages = [];
+  chatEoseHandlers = [];
+  constructor(mux, addressIndex, identity, resolveDelegate) {
+    this.mux = mux;
+    this.addressIndex = addressIndex;
+    this.identity = identity;
+    this.resolveDelegate = resolveDelegate ?? null;
+    this.id = `nostr-addr-${addressIndex}`;
+    this.name = `Nostr Transport (address ${addressIndex})`;
+    this.description = `P2P messaging for address index ${addressIndex}`;
+  }
+  // ===========================================================================
+  // BaseProvider — delegates to mux
+  // ===========================================================================
+  async connect() {
+    await this.mux.connect();
+  }
+  async disconnect() {
+  }
+  isConnected() {
+    return this.mux.isConnected();
+  }
+  getStatus() {
+    return this.mux.getStatus();
+  }
+  // ===========================================================================
+  // Identity (no-op — mux manages identity via addAddress)
+  // ===========================================================================
+  async setIdentity(identity) {
+    this.identity = identity;
+    await this.mux.addAddress(this.addressIndex, identity);
+  }
+  // ===========================================================================
+  // Sending — delegates to mux with this address's keyManager
+  // ===========================================================================
+  async sendMessage(recipientPubkey, content) {
+    const senderNametag = this.identity.nametag;
+    const wrappedContent = senderNametag ? JSON.stringify({ senderNametag, text: content }) : content;
+    return this.mux.sendGiftWrap(this.addressIndex, recipientPubkey, wrappedContent);
+  }
+  async sendTokenTransfer(recipientPubkey, payload) {
+    const content = "token_transfer:" + JSON.stringify(payload);
+    const uniqueD = `token-transfer-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    return this.mux.createAndPublishEncryptedEvent(
+      this.addressIndex,
+      EVENT_KINDS.TOKEN_TRANSFER,
+      content,
+      [["p", recipientPubkey], ["d", uniqueD], ["type", "token_transfer"]]
+    );
+  }
+  async sendPaymentRequest(recipientPubkey, payload) {
+    const requestId2 = this.mux.getUUIDGenerator()();
+    const amount = typeof payload.amount === "bigint" ? payload.amount.toString() : payload.amount;
+    const requestContent = {
+      requestId: requestId2,
+      amount,
+      coinId: payload.coinId,
+      message: payload.message,
+      recipientNametag: payload.recipientNametag,
+      deadline: Date.now() + 5 * 60 * 1e3
+    };
+    const content = "payment_request:" + JSON.stringify(requestContent);
+    const tags = [
+      ["p", recipientPubkey],
+      ["type", "payment_request"],
+      ["amount", amount]
+    ];
+    if (payload.recipientNametag) {
+      tags.push(["recipient", payload.recipientNametag]);
+    }
+    return this.mux.createAndPublishEncryptedEvent(
+      this.addressIndex,
+      EVENT_KINDS.PAYMENT_REQUEST,
+      content,
+      tags
+    );
+  }
+  async sendPaymentRequestResponse(recipientPubkey, response) {
+    const content = "payment_response:" + JSON.stringify(response);
+    return this.mux.createAndPublishEncryptedEvent(
+      this.addressIndex,
+      EVENT_KINDS.PAYMENT_REQUEST_RESPONSE,
+      content,
+      [["p", recipientPubkey], ["type", "payment_response"]]
+    );
+  }
+  async sendReadReceipt(recipientPubkey, messageEventId) {
+    const content = JSON.stringify({ type: "read_receipt", messageEventId });
+    await this.mux.sendGiftWrap(this.addressIndex, recipientPubkey, content);
+  }
+  async sendTypingIndicator(recipientPubkey) {
+    const content = JSON.stringify({
+      type: "typing",
+      senderNametag: this.identity.nametag
+    });
+    await this.mux.sendGiftWrap(this.addressIndex, recipientPubkey, content);
+  }
+  async sendComposingIndicator(recipientPubkey, content) {
+    await this.mux.sendGiftWrap(this.addressIndex, recipientPubkey, content);
+  }
+  async sendInstantSplitBundle(recipientPubkey, bundle) {
+    const content = "token_transfer:" + JSON.stringify({
+      type: "instant_split",
+      ...bundle
+    });
+    const uniqueD = `instant-split-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    return this.mux.createAndPublishEncryptedEvent(
+      this.addressIndex,
+      EVENT_KINDS.TOKEN_TRANSFER,
+      content,
+      [["p", recipientPubkey], ["d", uniqueD], ["type", "instant_split"]]
+    );
+  }
+  // ===========================================================================
+  // Subscription handlers — per-address
+  // ===========================================================================
+  onMessage(handler) {
+    this.messageHandlers.add(handler);
+    if (this.pendingMessages.length > 0) {
+      const pending2 = this.pendingMessages;
+      this.pendingMessages = [];
+      for (const msg of pending2) {
+        try {
+          handler(msg);
+        } catch {
+        }
+      }
+    }
+    return () => this.messageHandlers.delete(handler);
+  }
+  onTokenTransfer(handler) {
+    this.transferHandlers.add(handler);
+    return () => this.transferHandlers.delete(handler);
+  }
+  onPaymentRequest(handler) {
+    this.paymentRequestHandlers.add(handler);
+    return () => this.paymentRequestHandlers.delete(handler);
+  }
+  onPaymentRequestResponse(handler) {
+    this.paymentRequestResponseHandlers.add(handler);
+    return () => this.paymentRequestResponseHandlers.delete(handler);
+  }
+  onReadReceipt(handler) {
+    this.readReceiptHandlers.add(handler);
+    return () => this.readReceiptHandlers.delete(handler);
+  }
+  onTypingIndicator(handler) {
+    this.typingIndicatorHandlers.add(handler);
+    return () => this.typingIndicatorHandlers.delete(handler);
+  }
+  onComposing(handler) {
+    this.composingHandlers.add(handler);
+    return () => this.composingHandlers.delete(handler);
+  }
+  onInstantSplitReceived(handler) {
+    this.instantSplitBundleHandlers.add(handler);
+    return () => this.instantSplitBundleHandlers.delete(handler);
+  }
+  subscribeToBroadcast(tags, handler) {
+    const key = tags.sort().join(":");
+    if (!this.broadcastHandlers.has(key)) {
+      this.broadcastHandlers.set(key, /* @__PURE__ */ new Set());
+    }
+    this.broadcastHandlers.get(key).add(handler);
+    return () => this.broadcastHandlers.get(key)?.delete(handler);
+  }
+  async publishBroadcast(content, tags) {
+    const eventTags = tags ? tags.map((t) => ["t", t]) : [];
+    return this.mux.publishRawEvent(this.addressIndex, 30023, content, eventTags);
+  }
+  // ===========================================================================
+  // Resolve methods — delegate to original NostrTransportProvider
+  // These are stateless relay queries, shared across all addresses
+  // ===========================================================================
+  async resolve(identifier) {
+    return this.resolveDelegate?.resolve?.(identifier) ?? null;
+  }
+  async resolveNametag(nametag) {
+    return this.resolveDelegate?.resolveNametag?.(nametag) ?? null;
+  }
+  async resolveNametagInfo(nametag) {
+    return this.resolveDelegate?.resolveNametagInfo?.(nametag) ?? null;
+  }
+  async resolveAddressInfo(address) {
+    return this.resolveDelegate?.resolveAddressInfo?.(address) ?? null;
+  }
+  async resolveTransportPubkeyInfo(transportPubkey) {
+    return this.resolveDelegate?.resolveTransportPubkeyInfo?.(transportPubkey) ?? null;
+  }
+  async discoverAddresses(transportPubkeys) {
+    return this.resolveDelegate?.discoverAddresses?.(transportPubkeys) ?? [];
+  }
+  async recoverNametag() {
+    return this.resolveDelegate?.recoverNametag?.() ?? null;
+  }
+  async publishIdentityBinding(chainPubkey, l1Address, directAddress, nametag) {
+    return this.resolveDelegate?.publishIdentityBinding?.(chainPubkey, l1Address, directAddress, nametag) ?? false;
+  }
+  // ===========================================================================
+  // Relay Management — delegates to mux
+  // ===========================================================================
+  getRelays() {
+    return this.mux.getRelays();
+  }
+  getConnectedRelays() {
+    return this.mux.getConnectedRelays();
+  }
+  async addRelay(relayUrl) {
+    return this.mux.addRelay(relayUrl);
+  }
+  async removeRelay(relayUrl) {
+    return this.mux.removeRelay(relayUrl);
+  }
+  hasRelay(relayUrl) {
+    return this.mux.hasRelay(relayUrl);
+  }
+  isRelayConnected(relayUrl) {
+    return this.mux.isRelayConnected(relayUrl);
+  }
+  setFallbackSince(sinceSeconds) {
+    this.mux.setFallbackSince(this.addressIndex, sinceSeconds);
+  }
+  async fetchPendingEvents() {
+  }
+  onChatReady(handler) {
+    return this.mux.onChatReady(handler);
+  }
+  // ===========================================================================
+  // Dispatch methods — called by MultiAddressTransportMux to route events
+  // ===========================================================================
+  dispatchMessage(message) {
+    if (this.messageHandlers.size === 0) {
+      this.pendingMessages.push(message);
+      return;
+    }
+    for (const handler of this.messageHandlers) {
+      try {
+        handler(message);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Message handler error:", e);
+      }
+    }
+  }
+  dispatchTokenTransfer(transfer) {
+    for (const handler of this.transferHandlers) {
+      try {
+        handler(transfer);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Transfer handler error:", e);
+      }
+    }
+  }
+  dispatchPaymentRequest(request) {
+    for (const handler of this.paymentRequestHandlers) {
+      try {
+        handler(request);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Payment request handler error:", e);
+      }
+    }
+  }
+  dispatchPaymentRequestResponse(response) {
+    for (const handler of this.paymentRequestResponseHandlers) {
+      try {
+        handler(response);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Payment response handler error:", e);
+      }
+    }
+  }
+  dispatchReadReceipt(receipt) {
+    for (const handler of this.readReceiptHandlers) {
+      try {
+        handler(receipt);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Read receipt handler error:", e);
+      }
+    }
+  }
+  dispatchTypingIndicator(indicator) {
+    for (const handler of this.typingIndicatorHandlers) {
+      try {
+        handler(indicator);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Typing handler error:", e);
+      }
+    }
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  dispatchComposingIndicator(indicator) {
+    for (const handler of this.composingHandlers) {
+      try {
+        handler(indicator);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Composing handler error:", e);
+      }
+    }
+  }
+  dispatchInstantSplitBundle(bundle) {
+    for (const handler of this.instantSplitBundleHandlers) {
+      try {
+        handler(bundle);
+      } catch (e) {
+        logger.debug("MuxAdapter", "Instant split handler error:", e);
+      }
+    }
+  }
+  emitTransportEvent(event) {
+    for (const cb of this.eventCallbacks) {
+      try {
+        cb(event);
+      } catch {
+      }
+    }
+  }
+};
+
 // modules/payments/L1PaymentsModule.ts
 init_errors();
 init_constants();
@@ -4911,6 +6017,15 @@ var PaymentsModule = class _PaymentsModule {
     this.unsubscribePaymentRequests = null;
     this.unsubscribePaymentRequestResponses?.();
     this.unsubscribePaymentRequestResponses = null;
+    this.stopProofPolling();
+    this.proofPollingJobs.clear();
+    this.stopResolveUnconfirmedPolling();
+    this.unsubscribeStorageEvents();
+    for (const [, resolver] of this.pendingResponseResolvers) {
+      clearTimeout(resolver.timeout);
+      resolver.reject(new Error("Address switched"));
+    }
+    this.pendingResponseResolvers.clear();
     this.tokens.clear();
     this.pendingTransfers.clear();
     this.tombstones = [];
@@ -4959,6 +6074,13 @@ var PaymentsModule = class _PaymentsModule {
         try {
           const result = await provider.load();
           if (result.success && result.data) {
+            const loadedMeta = result.data?._meta;
+            const currentL1 = this.deps.identity.l1Address;
+            const currentChain = this.deps.identity.chainPubkey;
+            if (loadedMeta?.address && currentL1 && loadedMeta.address !== currentL1 && loadedMeta.address !== currentChain) {
+              logger.warn("Payments", `Load: rejecting data from provider ${id} \u2014 address mismatch (got=${loadedMeta.address.slice(0, 20)}... expected=${currentL1.slice(0, 20)}...)`);
+              continue;
+            }
             this.loadFromStorageData(result.data);
             const txfData = result.data;
             if (txfData._history && txfData._history.length > 0) {
@@ -5040,6 +6162,11 @@ var PaymentsModule = class _PaymentsModule {
    */
   async send(request) {
     this.ensureInitialized();
+    let resolveSendTracker;
+    const sendTracker = new Promise((r) => {
+      resolveSendTracker = r;
+    });
+    this.pendingBackgroundTasks.push(sendTracker);
     const result = {
       id: crypto.randomUUID(),
       status: "pending",
@@ -5327,6 +6454,8 @@ var PaymentsModule = class _PaymentsModule {
       }
       this.deps.emitEvent("transfer:failed", result);
       throw error;
+    } finally {
+      resolveSendTracker();
     }
   }
   /**
@@ -6339,9 +7468,12 @@ var PaymentsModule = class _PaymentsModule {
    * Call this before process exit to ensure all tokens are saved.
    */
   async waitForPendingOperations() {
+    logger.debug("Payments", `waitForPendingOperations: ${this.pendingBackgroundTasks.length} pending tasks`);
     if (this.pendingBackgroundTasks.length > 0) {
+      logger.debug("Payments", "waitForPendingOperations: waiting...");
       await Promise.allSettled(this.pendingBackgroundTasks);
       this.pendingBackgroundTasks = [];
+      logger.debug("Payments", "waitForPendingOperations: all tasks completed");
     }
   }
   /**
@@ -7583,6 +8715,13 @@ var PaymentsModule = class _PaymentsModule {
         try {
           const result = await provider.sync(localData);
           if (result.success && result.merged) {
+            const mergedMeta = result.merged?._meta;
+            const currentL1 = this.deps.identity.l1Address;
+            const currentChain = this.deps.identity.chainPubkey;
+            if (mergedMeta?.address && currentL1 && mergedMeta.address !== currentL1 && mergedMeta.address !== currentChain) {
+              logger.warn("Payments", `Sync: rejecting data from provider ${providerId} \u2014 address mismatch (got=${mergedMeta.address.slice(0, 20)}... expected=${currentL1.slice(0, 20)}...)`);
+              continue;
+            }
             const savedTokens = new Map(this.tokens);
             this.loadFromStorageData(result.merged);
             let restoredCount = 0;
@@ -8594,6 +9733,12 @@ var CommunicationsModule = class {
     this.unsubscribeComposing = deps.transport.onComposing?.((indicator) => {
       this.handleComposingIndicator(indicator);
     }) ?? null;
+    if (deps.transport.onChatReady) {
+      deps.transport.onChatReady(() => {
+        const conversations = this.getConversations();
+        deps.emitEvent("communications:ready", { conversationCount: conversations.size });
+      });
+    }
   }
   /**
    * Load messages from storage.
@@ -9009,9 +10154,9 @@ init_logger();
 init_errors();
 init_constants();
 import {
-  NostrClient,
-  NostrKeyManager,
-  Filter
+  NostrClient as NostrClient2,
+  NostrKeyManager as NostrKeyManager2,
+  Filter as Filter2
 } from "@unicitylabs/nostr-js-sdk";
 
 // modules/groupchat/types.ts
@@ -9027,7 +10172,7 @@ var GroupVisibility = {
 
 // modules/groupchat/GroupChatModule.ts
 function createNip29Filter(data) {
-  return new Filter(data);
+  return new Filter2(data);
 }
 var GroupChatModule = class {
   config;
@@ -9076,7 +10221,7 @@ var GroupChatModule = class {
     }
     this.deps = deps;
     const secretKey = Buffer.from(deps.identity.privateKey, "hex");
-    this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
+    this.keyManager = NostrKeyManager2.fromPrivateKey(secretKey);
   }
   async load() {
     this.ensureInitialized();
@@ -9211,7 +10356,7 @@ var GroupChatModule = class {
     }
     this.subscriptionIds = [];
     const secretKey = Buffer.from(this.deps.identity.privateKey, "hex");
-    this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
+    this.keyManager = NostrKeyManager2.fromPrivateKey(secretKey);
     if (this.groups.size === 0) {
       await this.restoreJoinedGroups();
     } else {
@@ -9223,13 +10368,13 @@ var GroupChatModule = class {
     this.ensureInitialized();
     if (!this.keyManager) {
       const secretKey = Buffer.from(this.deps.identity.privateKey, "hex");
-      this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
+      this.keyManager = NostrKeyManager2.fromPrivateKey(secretKey);
     }
     const primaryRelay = this.config.relays[0];
     if (primaryRelay) {
       await this.checkAndClearOnRelayChange(primaryRelay);
     }
-    this.client = new NostrClient(this.keyManager);
+    this.client = new NostrClient2(this.keyManager);
     try {
       await this.client.connect(...this.config.relays);
       this.connected = true;
@@ -9240,6 +10385,7 @@ var GroupChatModule = class {
         await this.subscribeToJoinedGroups();
       }
       this.deps.emitEvent("groupchat:connection", { connected: true });
+      this.deps.emitEvent("groupchat:ready", { groupCount: this.groups.size });
     } catch (error) {
       logger.error("GroupChat", "Failed to connect to relays", error);
       this.deps.emitEvent("groupchat:connection", { connected: false });
@@ -9487,7 +10633,7 @@ var GroupChatModule = class {
     if (!myPubkey) return [];
     const groupIdsWithMembership = /* @__PURE__ */ new Set();
     await this.oneshotSubscription(
-      new Filter({ kinds: [NIP29_KINDS.GROUP_MEMBERS] }),
+      new Filter2({ kinds: [NIP29_KINDS.GROUP_MEMBERS] }),
       {
         onEvent: (event) => {
           const groupId = this.getGroupIdFromMetadataEvent(event);
@@ -9538,7 +10684,7 @@ var GroupChatModule = class {
     const memberCountsMap = /* @__PURE__ */ new Map();
     await Promise.all([
       this.oneshotSubscription(
-        new Filter({ kinds: [NIP29_KINDS.GROUP_METADATA] }),
+        new Filter2({ kinds: [NIP29_KINDS.GROUP_METADATA] }),
         {
           onEvent: (event) => {
             const group = this.parseGroupMetadata(event);
@@ -9556,7 +10702,7 @@ var GroupChatModule = class {
         }
       ),
       this.oneshotSubscription(
-        new Filter({ kinds: [NIP29_KINDS.GROUP_MEMBERS] }),
+        new Filter2({ kinds: [NIP29_KINDS.GROUP_MEMBERS] }),
         {
           onEvent: (event) => {
             const groupId = this.getGroupIdFromMetadataEvent(event);
@@ -9874,6 +11020,19 @@ var GroupChatModule = class {
   getMessages(groupId) {
     return (this.messages.get(groupId) || []).sort((a, b) => a.timestamp - b.timestamp);
   }
+  getMessagesPage(groupId, options) {
+    const limit = options?.limit ?? 20;
+    const before = options?.before ?? Infinity;
+    const groupMessages = this.messages.get(groupId) ?? [];
+    const filtered = groupMessages.filter((m) => m.timestamp < before).sort((a, b) => b.timestamp - a.timestamp);
+    const page = filtered.slice(0, limit);
+    return {
+      messages: page.reverse(),
+      // chronological order
+      hasMore: filtered.length > limit,
+      oldestTimestamp: page.length > 0 ? page[0].timestamp : null
+    };
+  }
   getMembers(groupId) {
     return (this.members.get(groupId) || []).sort((a, b) => a.joinedAt - b.joinedAt);
   }
@@ -10046,7 +11205,7 @@ var GroupChatModule = class {
     if (!this.client) return /* @__PURE__ */ new Set();
     const adminPubkeys = /* @__PURE__ */ new Set();
     return this.oneshotSubscription(
-      new Filter({ kinds: [NIP29_KINDS.GROUP_ADMINS], "#d": ["", "_"] }),
+      new Filter2({ kinds: [NIP29_KINDS.GROUP_ADMINS], "#d": ["", "_"] }),
       {
         onEvent: (event) => {
           const pTags = event.tags.filter((t) => t[0] === "p");
@@ -10068,7 +11227,7 @@ var GroupChatModule = class {
     if (!this.client) return null;
     let result = null;
     return this.oneshotSubscription(
-      new Filter({ kinds: [NIP29_KINDS.GROUP_METADATA], "#d": [groupId] }),
+      new Filter2({ kinds: [NIP29_KINDS.GROUP_METADATA], "#d": [groupId] }),
       {
         onEvent: (event) => {
           if (!result) result = this.parseGroupMetadata(event);
@@ -10105,7 +11264,7 @@ var GroupChatModule = class {
     if (!this.client) return [];
     const members = [];
     return this.oneshotSubscription(
-      new Filter({ kinds: [NIP29_KINDS.GROUP_MEMBERS], "#d": [groupId] }),
+      new Filter2({ kinds: [NIP29_KINDS.GROUP_MEMBERS], "#d": [groupId] }),
       {
         onEvent: (event) => {
           const pTags = event.tags.filter((t) => t[0] === "p");
@@ -10126,7 +11285,7 @@ var GroupChatModule = class {
     if (!this.client) return [];
     const adminPubkeys = [];
     return this.oneshotSubscription(
-      new Filter({ kinds: [NIP29_KINDS.GROUP_ADMINS], "#d": [groupId] }),
+      new Filter2({ kinds: [NIP29_KINDS.GROUP_ADMINS], "#d": [groupId] }),
       {
         onEvent: (event) => {
           const pTags = event.tags.filter((t) => t[0] === "p");
@@ -13841,11 +15000,18 @@ var Sphere = class _Sphere {
   _transport;
   _oracle;
   _priceProvider;
-  // Modules
+  // Modules (single-instance — backward compat, delegates to active address)
   _payments;
   _communications;
   _groupChat = null;
   _market = null;
+  // Per-address module instances (Phase 2: independent parallel operation)
+  _addressModules = /* @__PURE__ */ new Map();
+  _transportMux = null;
+  // Stored configs for creating per-address modules
+  _l1Config;
+  _groupChatConfig;
+  _marketConfig;
   // Events
   eventHandlers = /* @__PURE__ */ new Map();
   // Provider management
@@ -13863,6 +15029,9 @@ var Sphere = class _Sphere {
     if (tokenStorage) {
       this._tokenStorageProviders.set(tokenStorage.id, tokenStorage);
     }
+    this._l1Config = l1Config;
+    this._groupChatConfig = groupChatConfig;
+    this._marketConfig = marketConfig;
     this._payments = createPaymentsModule({ l1: l1Config });
     this._communications = createCommunicationsModule();
     this._groupChat = groupChatConfig ? createGroupChatModule(groupChatConfig) : null;
@@ -15121,7 +16290,7 @@ var Sphere = class _Sphere {
       nametags.set(0, newNametag);
     }
     const nametag = this._addressNametags.get(addressId)?.get(0);
-    this._identity = {
+    const newIdentity = {
       privateKey: addressInfo.privateKey,
       chainPubkey: addressInfo.publicKey,
       l1Address: addressInfo.address,
@@ -15129,20 +16298,53 @@ var Sphere = class _Sphere {
       ipnsName: "12D3KooW" + ipnsHash,
       nametag
     };
+    if (!this._addressModules.has(index)) {
+      logger.debug("Sphere", `switchToAddress(${index}): creating per-address modules (lazy init)`);
+      const addressTokenProviders = /* @__PURE__ */ new Map();
+      for (const [providerId, provider] of this._tokenStorageProviders.entries()) {
+        if (provider.createForAddress) {
+          const newProvider = provider.createForAddress();
+          newProvider.setIdentity(newIdentity);
+          await newProvider.initialize();
+          addressTokenProviders.set(providerId, newProvider);
+        } else {
+          logger.warn("Sphere", `Token storage provider ${providerId} does not support createForAddress, reusing shared instance`);
+          addressTokenProviders.set(providerId, provider);
+        }
+      }
+      await this.initializeAddressModules(index, newIdentity, addressTokenProviders);
+    } else {
+      const moduleSet = this._addressModules.get(index);
+      if (nametag !== moduleSet.identity.nametag) {
+        moduleSet.identity = newIdentity;
+        const addressTransport = moduleSet.transportAdapter ?? this._transport;
+        moduleSet.payments.initialize({
+          identity: newIdentity,
+          storage: this._storage,
+          tokenStorageProviders: moduleSet.tokenStorageProviders,
+          transport: addressTransport,
+          oracle: this._oracle,
+          emitEvent: this.emitEvent.bind(this),
+          chainCode: this._masterKey?.chainCode || void 0,
+          price: this._priceProvider ?? void 0
+        });
+      }
+    }
+    this._identity = newIdentity;
     this._currentAddressIndex = index;
     await this._updateCachedProxyAddress();
+    const activeModules = this._addressModules.get(index);
+    this._payments = activeModules.payments;
+    this._communications = activeModules.communications;
+    this._groupChat = activeModules.groupChat;
+    this._market = activeModules.market;
     await this._storage.set(STORAGE_KEYS_GLOBAL.CURRENT_ADDRESS_INDEX, index.toString());
     this._storage.setIdentity(this._identity);
-    await this._transport.setIdentity(this._identity);
-    logger.debug("Sphere", `switchToAddress(${index}): re-initializing ${this._tokenStorageProviders.size} token storage provider(s)`);
-    for (const [providerId, provider] of this._tokenStorageProviders.entries()) {
-      logger.debug("Sphere", `switchToAddress(${index}): shutdown provider=${providerId}`);
-      await provider.shutdown();
-      provider.setIdentity(this._identity);
-      logger.debug("Sphere", `switchToAddress(${index}): initialize provider=${providerId}`);
-      await provider.initialize();
+    if (this._transport.setFallbackSince) {
+      const fallbackTs = Math.floor(Date.now() / 1e3) - 86400;
+      this._transport.setFallbackSince(fallbackTs);
     }
-    await this.reinitializeModulesForNewAddress();
+    await this._transport.setIdentity(this._identity);
     this.emitEvent("identity:changed", {
       l1Address: this._identity.l1Address,
       directAddress: this._identity.directAddress,
@@ -15197,42 +16399,104 @@ var Sphere = class _Sphere {
     }
   }
   /**
-   * Re-initialize modules after address switch
+   * Create a new set of per-address modules for the given index.
+   * Each address gets its own PaymentsModule, CommunicationsModule, etc.
+   * Modules are fully independent — they have their own token storage,
+   * and can sync/finalize/split in background regardless of active address.
+   *
+   * @param index - HD address index
+   * @param identity - Full identity for this address
+   * @param tokenStorageProviders - Token storage providers for this address
    */
-  async reinitializeModulesForNewAddress() {
+  async initializeAddressModules(index, identity, tokenStorageProviders) {
     const emitEvent = this.emitEvent.bind(this);
-    this._payments.initialize({
-      identity: this._identity,
+    const adapter = await this.ensureTransportMux(index, identity);
+    const addressTransport = adapter ?? this._transport;
+    const payments = createPaymentsModule({ l1: this._l1Config });
+    const communications = createCommunicationsModule();
+    const groupChat = this._groupChatConfig ? createGroupChatModule(this._groupChatConfig) : null;
+    const market = this._marketConfig ? createMarketModule(this._marketConfig) : null;
+    payments.initialize({
+      identity,
       storage: this._storage,
-      tokenStorageProviders: this._tokenStorageProviders,
-      transport: this._transport,
+      tokenStorageProviders,
+      transport: addressTransport,
       oracle: this._oracle,
       emitEvent,
       chainCode: this._masterKey?.chainCode || void 0,
       price: this._priceProvider ?? void 0
     });
-    this._communications.initialize({
-      identity: this._identity,
+    communications.initialize({
+      identity,
       storage: this._storage,
-      transport: this._transport,
+      transport: addressTransport,
       emitEvent
     });
-    this._groupChat?.initialize({
-      identity: this._identity,
+    groupChat?.initialize({
+      identity,
       storage: this._storage,
       emitEvent
     });
-    this._market?.initialize({
-      identity: this._identity,
+    market?.initialize({
+      identity,
       emitEvent
     });
-    await this._payments.load();
-    await this._communications.load();
-    await this._groupChat?.load();
-    await this._market?.load();
-    this._payments.sync().catch((err) => {
-      logger.warn("Sphere", "Post-switch sync failed:", err);
+    await payments.load();
+    await communications.load();
+    await groupChat?.load();
+    await market?.load();
+    const moduleSet = {
+      index,
+      identity,
+      payments,
+      communications,
+      groupChat,
+      market,
+      transportAdapter: adapter,
+      tokenStorageProviders: new Map(tokenStorageProviders),
+      initialized: true
+    };
+    this._addressModules.set(index, moduleSet);
+    logger.debug("Sphere", `Initialized per-address modules for address ${index} (transport: ${adapter ? "mux adapter" : "primary"})`);
+    payments.sync().catch((err) => {
+      logger.warn("Sphere", `Post-init sync failed for address ${index}:`, err);
     });
+    return moduleSet;
+  }
+  /**
+   * Ensure the transport multiplexer exists and register an address.
+   * Creates the mux on first call. Returns an AddressTransportAdapter
+   * that routes events for this address independently.
+   * @returns AddressTransportAdapter or null if transport is not Nostr-based
+   */
+  async ensureTransportMux(index, identity) {
+    const transport = this._transport;
+    if (typeof transport.getWebSocketFactory !== "function" || typeof transport.getConfiguredRelays !== "function") {
+      logger.debug("Sphere", "Transport does not support mux interface, skipping");
+      return null;
+    }
+    const nostrTransport = transport;
+    if (!this._transportMux) {
+      this._transportMux = new MultiAddressTransportMux({
+        relays: nostrTransport.getConfiguredRelays(),
+        createWebSocket: nostrTransport.getWebSocketFactory(),
+        storage: nostrTransport.getStorageAdapter() ?? void 0
+      });
+      await this._transportMux.connect();
+      if (typeof nostrTransport.suppressSubscriptions === "function") {
+        nostrTransport.suppressSubscriptions();
+      }
+      logger.debug("Sphere", "Transport mux created and connected");
+    }
+    const adapter = await this._transportMux.addAddress(index, identity, this._transport);
+    return adapter;
+  }
+  /**
+   * Get per-address modules for any address index (creates lazily if needed).
+   * This allows accessing any address's modules without switching.
+   */
+  getAddressPayments(index) {
+    return this._addressModules.get(index)?.payments;
   }
   /**
    * Derive address at a specific index
@@ -16160,10 +17424,33 @@ var Sphere = class _Sphere {
   // ===========================================================================
   async destroy() {
     this.cleanupProviderEventSubscriptions();
+    for (const [idx, moduleSet] of this._addressModules.entries()) {
+      try {
+        moduleSet.payments.destroy();
+        moduleSet.communications.destroy();
+        moduleSet.groupChat?.destroy();
+        moduleSet.market?.destroy();
+        for (const provider of moduleSet.tokenStorageProviders.values()) {
+          try {
+            await provider.shutdown();
+          } catch {
+          }
+        }
+        moduleSet.tokenStorageProviders.clear();
+        logger.debug("Sphere", `Destroyed modules for address ${idx}`);
+      } catch (err) {
+        logger.warn("Sphere", `Error destroying modules for address ${idx}:`, err);
+      }
+    }
+    this._addressModules.clear();
     this._payments.destroy();
     this._communications.destroy();
     this._groupChat?.destroy();
     this._market?.destroy();
+    if (this._transportMux) {
+      await this._transportMux.disconnect();
+      this._transportMux = null;
+    }
     await this._transport.disconnect();
     await this._storage.disconnect();
     await this._oracle.disconnect();
@@ -16358,6 +17645,9 @@ var Sphere = class _Sphere {
   // ===========================================================================
   async initializeProviders() {
     this._storage.setIdentity(this._identity);
+    if (this._transport.setFallbackSince) {
+      this._transport.setFallbackSince(Math.floor(Date.now() / 1e3) - 86400);
+    }
     await this._transport.setIdentity(this._identity);
     for (const provider of this._tokenStorageProviders.values()) {
       provider.setIdentity(this._identity);
@@ -16448,11 +17738,13 @@ var Sphere = class _Sphere {
   }
   async initializeModules() {
     const emitEvent = this.emitEvent.bind(this);
+    const adapter = await this.ensureTransportMux(this._currentAddressIndex, this._identity);
+    const moduleTransport = adapter ?? this._transport;
     this._payments.initialize({
       identity: this._identity,
       storage: this._storage,
       tokenStorageProviders: this._tokenStorageProviders,
-      transport: this._transport,
+      transport: moduleTransport,
       oracle: this._oracle,
       emitEvent,
       // Pass chain code for L1 HD derivation
@@ -16463,7 +17755,7 @@ var Sphere = class _Sphere {
     this._communications.initialize({
       identity: this._identity,
       storage: this._storage,
-      transport: this._transport,
+      transport: moduleTransport,
       emitEvent
     });
     this._groupChat?.initialize({
@@ -16479,6 +17771,17 @@ var Sphere = class _Sphere {
     await this._communications.load();
     await this._groupChat?.load();
     await this._market?.load();
+    this._addressModules.set(this._currentAddressIndex, {
+      index: this._currentAddressIndex,
+      identity: this._identity,
+      payments: this._payments,
+      communications: this._communications,
+      groupChat: this._groupChat,
+      market: this._market,
+      transportAdapter: adapter,
+      tokenStorageProviders: new Map(this._tokenStorageProviders),
+      initialized: true
+    });
   }
   // ===========================================================================
   // Private: Helpers
@@ -17159,7 +18462,7 @@ import {
   encryptNametag,
   decryptNametag
 } from "@unicitylabs/nostr-js-sdk";
-import { NostrClient as NostrClient2, NostrKeyManager as NostrKeyManager2 } from "@unicitylabs/nostr-js-sdk";
+import { NostrClient as NostrClient3, NostrKeyManager as NostrKeyManager3 } from "@unicitylabs/nostr-js-sdk";
 
 // price/CoinGeckoPriceProvider.ts
 init_logger();
@@ -17431,8 +18734,8 @@ export {
   NETWORKS,
   NIP29_KINDS,
   NOSTR_EVENT_KINDS,
-  NostrClient2 as NostrClient,
-  NostrKeyManager2 as NostrKeyManager,
+  NostrClient3 as NostrClient,
+  NostrKeyManager3 as NostrKeyManager,
   PaymentsModule,
   SIGN_MESSAGE_PREFIX,
   STORAGE_KEYS,