@unicitylabs/sphere-sdk 0.6.2 → 0.6.4

package/dist/impl/nodejs/index.d.cts

@@ -1,3 +1,4 @@
+import { NostrKeyManager, Event } from '@unicitylabs/nostr-js-sdk';
 import { StateTransitionClient } from '@unicitylabs/state-transition-sdk/lib/StateTransitionClient';
 import { AggregatorClient } from '@unicitylabs/state-transition-sdk/lib/api/AggregatorClient';
 import { RootTrustBase } from '@unicitylabs/state-transition-sdk/lib/bft/RootTrustBase';
@@ -195,6 +196,16 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Set fallback 'since' timestamp for event subscriptions.
+     * Used when switching to an address that has never subscribed before.
+     * The transport uses this instead of 'now' as the initial since filter,
+     * ensuring events sent while the address was inactive are not missed.
+     * Consumed once by the next subscription setup, then cleared.
+     *
+     * @param sinceSeconds - Unix timestamp in seconds
+     */
+    setFallbackSince?(sinceSeconds: number): void;
     /**
      * Fetch pending events from transport (one-shot query).
      * Creates a temporary subscription, processes events through normal handlers,
@@ -476,6 +487,8 @@ declare class NostrTransportProvider implements TransportProvider {
     private storage;
     /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
     private lastEventTs;
+    /** Fallback 'since' timestamp for first-time address subscriptions (consumed once). */
+    private fallbackSince;
     private identity;
     private keyManager;
     private status;
@@ -493,6 +506,25 @@ declare class NostrTransportProvider implements TransportProvider {
     private broadcastHandlers;
     private eventCallbacks;
     constructor(config: NostrTransportProviderConfig);
+    /**
+     * Get the WebSocket factory (used by MultiAddressTransportMux to share the same factory).
+     */
+    getWebSocketFactory(): WebSocketFactory;
+    /**
+     * Get the configured relay URLs.
+     */
+    getConfiguredRelays(): string[];
+    /**
+     * Get the storage adapter.
+     */
+    getStorageAdapter(): TransportStorageAdapter | null;
+    /**
+     * Suppress event subscriptions — unsubscribe wallet/chat filters
+     * but keep the connection alive for resolve/identity-binding operations.
+     * Used when MultiAddressTransportMux takes over event handling.
+     */
+    suppressSubscriptions(): void;
+    private _subscriptionsSuppressed;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
@@ -526,6 +558,7 @@ declare class NostrTransportProvider implements TransportProvider {
      */
     isRelayConnected(relayUrl: string): boolean;
     setIdentity(identity: FullIdentity): Promise<void>;
+    setFallbackSince(sinceSeconds: number): void;
     /**
      * Get the Nostr-format public key (32 bytes / 64 hex chars)
      * This is the x-coordinate only, without the 02/03 prefix.
@@ -624,6 +657,12 @@ declare class NostrTransportProvider implements TransportProvider {
      */
     private stripContentPrefix;
     private ensureConnected;
+    /**
+     * Async version of ensureConnected — reconnects if the original transport
+     * lost its WebSocket while subscriptions are suppressed (mux handles events).
+     * Used by resolve methods which are always async.
+     */
+    private ensureConnectedForResolve;
     private ensureReady;
     private emitEvent;
     /**
@@ -632,6 +671,11 @@ declare class NostrTransportProvider implements TransportProvider {
      * because NIP17.createGiftWrap hardcodes kind 14 for the inner rumor.
      */
     private createCustomKindGiftWrap;
+    /**
+     * Create a NIP-17 gift wrap with a custom rumor kind.
+     * Shared between NostrTransportProvider and MultiAddressTransportMux.
+     */
+    static createCustomKindGiftWrap(keyManager: NostrKeyManager, recipientPubkeyHex: string, content: string, rumorKind: number): Event;
 }
 
 /**
@@ -1133,6 +1177,13 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Clear all data
      */
     clear?(): Promise<boolean>;
+    /**
+     * Create a new independent instance of this provider for a different address.
+     * Used by per-address module architecture — each address gets its own
+     * TokenStorageProvider instance to avoid cross-address data contamination.
+     * If not implemented, the provider cannot be used in multi-address mode.
+     */
+    createForAddress?(): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
      */
@@ -1282,6 +1333,10 @@ declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorag
     hasHistoryEntry(dedupKey: string): Promise<boolean>;
     clearHistory(): Promise<void>;
     importHistoryEntries(entries: HistoryRecord[]): Promise<number>;
+    /**
+     * Create an independent instance for a different address.
+     */
+    createForAddress(): FileTokenStorageProvider;
 }
 declare function createFileTokenStorageProvider(config: FileTokenStorageConfig | string): FileTokenStorageProvider;
 

package/dist/impl/nodejs/index.d.ts

@@ -1,3 +1,4 @@
+import { NostrKeyManager, Event } from '@unicitylabs/nostr-js-sdk';
 import { StateTransitionClient } from '@unicitylabs/state-transition-sdk/lib/StateTransitionClient';
 import { AggregatorClient } from '@unicitylabs/state-transition-sdk/lib/api/AggregatorClient';
 import { RootTrustBase } from '@unicitylabs/state-transition-sdk/lib/bft/RootTrustBase';
@@ -195,6 +196,16 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Set fallback 'since' timestamp for event subscriptions.
+     * Used when switching to an address that has never subscribed before.
+     * The transport uses this instead of 'now' as the initial since filter,
+     * ensuring events sent while the address was inactive are not missed.
+     * Consumed once by the next subscription setup, then cleared.
+     *
+     * @param sinceSeconds - Unix timestamp in seconds
+     */
+    setFallbackSince?(sinceSeconds: number): void;
     /**
      * Fetch pending events from transport (one-shot query).
      * Creates a temporary subscription, processes events through normal handlers,
@@ -476,6 +487,8 @@ declare class NostrTransportProvider implements TransportProvider {
     private storage;
     /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
     private lastEventTs;
+    /** Fallback 'since' timestamp for first-time address subscriptions (consumed once). */
+    private fallbackSince;
     private identity;
     private keyManager;
     private status;
@@ -493,6 +506,25 @@ declare class NostrTransportProvider implements TransportProvider {
     private broadcastHandlers;
     private eventCallbacks;
     constructor(config: NostrTransportProviderConfig);
+    /**
+     * Get the WebSocket factory (used by MultiAddressTransportMux to share the same factory).
+     */
+    getWebSocketFactory(): WebSocketFactory;
+    /**
+     * Get the configured relay URLs.
+     */
+    getConfiguredRelays(): string[];
+    /**
+     * Get the storage adapter.
+     */
+    getStorageAdapter(): TransportStorageAdapter | null;
+    /**
+     * Suppress event subscriptions — unsubscribe wallet/chat filters
+     * but keep the connection alive for resolve/identity-binding operations.
+     * Used when MultiAddressTransportMux takes over event handling.
+     */
+    suppressSubscriptions(): void;
+    private _subscriptionsSuppressed;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
@@ -526,6 +558,7 @@ declare class NostrTransportProvider implements TransportProvider {
      */
     isRelayConnected(relayUrl: string): boolean;
     setIdentity(identity: FullIdentity): Promise<void>;
+    setFallbackSince(sinceSeconds: number): void;
     /**
      * Get the Nostr-format public key (32 bytes / 64 hex chars)
      * This is the x-coordinate only, without the 02/03 prefix.
@@ -624,6 +657,12 @@ declare class NostrTransportProvider implements TransportProvider {
      */
     private stripContentPrefix;
     private ensureConnected;
+    /**
+     * Async version of ensureConnected — reconnects if the original transport
+     * lost its WebSocket while subscriptions are suppressed (mux handles events).
+     * Used by resolve methods which are always async.
+     */
+    private ensureConnectedForResolve;
     private ensureReady;
     private emitEvent;
     /**
@@ -632,6 +671,11 @@ declare class NostrTransportProvider implements TransportProvider {
      * because NIP17.createGiftWrap hardcodes kind 14 for the inner rumor.
      */
     private createCustomKindGiftWrap;
+    /**
+     * Create a NIP-17 gift wrap with a custom rumor kind.
+     * Shared between NostrTransportProvider and MultiAddressTransportMux.
+     */
+    static createCustomKindGiftWrap(keyManager: NostrKeyManager, recipientPubkeyHex: string, content: string, rumorKind: number): Event;
 }
 
 /**
@@ -1133,6 +1177,13 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Clear all data
      */
     clear?(): Promise<boolean>;
+    /**
+     * Create a new independent instance of this provider for a different address.
+     * Used by per-address module architecture — each address gets its own
+     * TokenStorageProvider instance to avoid cross-address data contamination.
+     * If not implemented, the provider cannot be used in multi-address mode.
+     */
+    createForAddress?(): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
      */
@@ -1282,6 +1333,10 @@ declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorag
     hasHistoryEntry(dedupKey: string): Promise<boolean>;
     clearHistory(): Promise<void>;
     importHistoryEntries(entries: HistoryRecord[]): Promise<number>;
+    /**
+     * Create an independent instance for a different address.
+     */
+    createForAddress(): FileTokenStorageProvider;
 }
 declare function createFileTokenStorageProvider(config: FileTokenStorageConfig | string): FileTokenStorageProvider;
 

package/dist/impl/nodejs/index.js

@@ -319,7 +319,7 @@ import * as path2 from "path";
 var META_FILE = "_meta.json";
 var TOMBSTONES_FILE = "_tombstones.json";
 var HISTORY_FILE = "_history.json";
-var FileTokenStorageProvider = class {
+var FileTokenStorageProvider = class _FileTokenStorageProvider {
   id = "file-token-storage";
   name = "File Token Storage";
   type = "local";
@@ -546,6 +546,12 @@ var FileTokenStorageProvider = class {
     }
     return imported;
   }
+  /**
+   * Create an independent instance for a different address.
+   */
+  createForAddress() {
+    return new _FileTokenStorageProvider({ tokensDir: this.baseTokensDir });
+  }
 };
 function createFileTokenStorageProvider(config) {
   return new FileTokenStorageProvider(config);
@@ -1072,7 +1078,7 @@ function defaultUUIDGenerator() {
 var COMPOSING_INDICATOR_KIND = 25050;
 var TIMESTAMP_RANDOMIZATION = 2 * 24 * 60 * 60;
 var EVENT_KINDS = NOSTR_EVENT_KINDS;
-var NostrTransportProvider = class {
+var NostrTransportProvider = class _NostrTransportProvider {
   id = "nostr";
   name = "Nostr Transport";
   type = "p2p";
@@ -1081,6 +1087,8 @@ var NostrTransportProvider = class {
   storage = null;
   /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
   lastEventTs = 0;
+  /** Fallback 'since' timestamp for first-time address subscriptions (consumed once). */
+  fallbackSince = null;
   identity = null;
   keyManager = null;
   status = "disconnected";
@@ -1113,6 +1121,48 @@ var NostrTransportProvider = class {
     };
     this.storage = config.storage ?? null;
   }
+  /**
+   * Get the WebSocket factory (used by MultiAddressTransportMux to share the same factory).
+   */
+  getWebSocketFactory() {
+    return this.config.createWebSocket;
+  }
+  /**
+   * Get the configured relay URLs.
+   */
+  getConfiguredRelays() {
+    return [...this.config.relays];
+  }
+  /**
+   * Get the storage adapter.
+   */
+  getStorageAdapter() {
+    return this.storage;
+  }
+  /**
+   * Suppress event subscriptions — unsubscribe wallet/chat filters
+   * but keep the connection alive for resolve/identity-binding operations.
+   * Used when MultiAddressTransportMux takes over event handling.
+   */
+  suppressSubscriptions() {
+    if (!this.nostrClient) return;
+    if (this.walletSubscriptionId) {
+      this.nostrClient.unsubscribe(this.walletSubscriptionId);
+      this.walletSubscriptionId = null;
+    }
+    if (this.chatSubscriptionId) {
+      this.nostrClient.unsubscribe(this.chatSubscriptionId);
+      this.chatSubscriptionId = null;
+    }
+    if (this.mainSubscriptionId) {
+      this.nostrClient.unsubscribe(this.mainSubscriptionId);
+      this.mainSubscriptionId = null;
+    }
+    this._subscriptionsSuppressed = true;
+    logger.debug("Nostr", "Subscriptions suppressed \u2014 mux handles event routing");
+  }
+  // Flag to prevent re-subscription after suppressSubscriptions()
+  _subscriptionsSuppressed = false;
   // ===========================================================================
   // BaseProvider Implementation
   // ===========================================================================
@@ -1291,6 +1341,8 @@ var NostrTransportProvider = class {
   // ===========================================================================
   async setIdentity(identity) {
     this.identity = identity;
+    this.processedEventIds.clear();
+    this.lastEventTs = 0;
     const secretKey = Buffer2.from(identity.privateKey, "hex");
     this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
     const nostrPubkey = this.keyManager.getPublicKeyHex();
@@ -1333,6 +1385,9 @@ var NostrTransportProvider = class {
       await this.subscribeToEvents();
     }
   }
+  setFallbackSince(sinceSeconds) {
+    this.fallbackSince = sinceSeconds;
+  }
   /**
    * Get the Nostr-format public key (32 bytes / 64 hex chars)
    * This is the x-coordinate only, without the 02/03 prefix.
@@ -1554,11 +1609,11 @@ var NostrTransportProvider = class {
     return this.resolveNametagInfo(identifier);
   }
   async resolveNametag(nametag) {
-    this.ensureConnected();
+    await this.ensureConnectedForResolve();
     return this.nostrClient.queryPubkeyByNametag(nametag);
   }
   async resolveNametagInfo(nametag) {
-    this.ensureConnected();
+    await this.ensureConnectedForResolve();
     const binding = await this.nostrClient.queryBindingByNametag(nametag);
     if (!binding) {
       logger.debug("Nostr", `resolveNametagInfo: no binding events found for Unicity ID "${nametag}"`);
@@ -1571,7 +1626,7 @@ var NostrTransportProvider = class {
    * Performs reverse lookup via nostr-js-sdk with first-seen-wins anti-hijacking.
    */
   async resolveAddressInfo(address) {
-    this.ensureConnected();
+    await this.ensureConnectedForResolve();
     const binding = await this.nostrClient.queryBindingByAddress(address);
     if (!binding) return null;
     return this.bindingInfoToPeerInfo(binding);
@@ -1606,7 +1661,7 @@ var NostrTransportProvider = class {
    * Queries binding events authored by the given pubkey.
    */
   async resolveTransportPubkeyInfo(transportPubkey) {
-    this.ensureConnected();
+    await this.ensureConnectedForResolve();
     const events = await this.queryEvents({
       kinds: [EVENT_KINDS.NAMETAG_BINDING],
       authors: [transportPubkey],
@@ -1641,7 +1696,7 @@ var NostrTransportProvider = class {
    * Used for HD address discovery — single relay query with multi-author filter.
    */
   async discoverAddresses(transportPubkeys) {
-    this.ensureConnected();
+    await this.ensureConnectedForResolve();
     if (transportPubkeys.length === 0) return [];
     const events = await this.queryEvents({
       kinds: [EVENT_KINDS.NAMETAG_BINDING],
@@ -1680,7 +1735,10 @@ var NostrTransportProvider = class {
    * @returns Decrypted nametag or null if none found
    */
   async recoverNametag() {
-    this.ensureReady();
+    await this.ensureConnectedForResolve();
+    if (!this.identity) {
+      throw new SphereError("Identity not set", "NOT_INITIALIZED");
+    }
     if (!this.identity || !this.keyManager) {
       throw new SphereError("Identity not set", "NOT_INITIALIZED");
     }
@@ -2240,6 +2298,10 @@ var NostrTransportProvider = class {
   chatEoseFired = false;
   async subscribeToEvents() {
     logger.debug("Nostr", "subscribeToEvents called, identity:", !!this.identity, "keyManager:", !!this.keyManager, "nostrClient:", !!this.nostrClient);
+    if (this._subscriptionsSuppressed) {
+      logger.debug("Nostr", "subscribeToEvents: suppressed \u2014 mux handles event routing");
+      return;
+    }
     if (!this.identity || !this.keyManager || !this.nostrClient) {
       logger.debug("Nostr", "subscribeToEvents: skipped - no identity, keyManager, or nostrClient");
       return;
@@ -2266,7 +2328,13 @@ var NostrTransportProvider = class {
         if (stored) {
           since = parseInt(stored, 10);
           this.lastEventTs = since;
+          this.fallbackSince = null;
           logger.debug("Nostr", "Resuming from stored event timestamp:", since);
+        } else if (this.fallbackSince !== null) {
+          since = this.fallbackSince;
+          this.lastEventTs = since;
+          this.fallbackSince = null;
+          logger.debug("Nostr", "Using fallback since timestamp:", since);
         } else {
           since = Math.floor(Date.now() / 1e3);
           logger.debug("Nostr", "No stored timestamp, starting from now:", since);
@@ -2274,6 +2342,7 @@ var NostrTransportProvider = class {
       } catch (err) {
         logger.debug("Nostr", "Failed to read last event timestamp, falling back to now:", err);
         since = Math.floor(Date.now() / 1e3);
+        this.fallbackSince = null;
       }
     } else {
       since = Math.floor(Date.now() / 1e3) - 86400;
@@ -2405,6 +2474,31 @@ var NostrTransportProvider = class {
       throw new SphereError("NostrTransportProvider not connected", "TRANSPORT_ERROR");
     }
   }
+  /**
+   * Async version of ensureConnected — reconnects if the original transport
+   * lost its WebSocket while subscriptions are suppressed (mux handles events).
+   * Used by resolve methods which are always async.
+   */
+  async ensureConnectedForResolve() {
+    if (this.isConnected()) return;
+    if (this._subscriptionsSuppressed && this.nostrClient) {
+      logger.debug("Nostr", "Suppressed transport disconnected \u2014 reconnecting for resolve");
+      try {
+        await Promise.race([
+          this.nostrClient.connect(...this.config.relays),
+          new Promise(
+            (_, reject) => setTimeout(() => reject(new Error("reconnect timeout")), 5e3)
+          )
+        ]);
+        if (this.nostrClient.isConnected()) {
+          this.status = "connected";
+          return;
+        }
+      } catch {
+      }
+    }
+    throw new SphereError("NostrTransportProvider not connected", "TRANSPORT_ERROR");
+  }
   ensureReady() {
     this.ensureConnected();
     if (!this.identity) {
@@ -2426,16 +2520,23 @@ var NostrTransportProvider = class {
    * because NIP17.createGiftWrap hardcodes kind 14 for the inner rumor.
    */
   createCustomKindGiftWrap(recipientPubkeyHex, content, rumorKind) {
-    const senderPubkey = this.keyManager.getPublicKeyHex();
+    return _NostrTransportProvider.createCustomKindGiftWrap(this.keyManager, recipientPubkeyHex, content, rumorKind);
+  }
+  /**
+   * Create a NIP-17 gift wrap with a custom rumor kind.
+   * Shared between NostrTransportProvider and MultiAddressTransportMux.
+   */
+  static createCustomKindGiftWrap(keyManager, recipientPubkeyHex, content, rumorKind) {
+    const senderPubkey = keyManager.getPublicKeyHex();
     const now = Math.floor(Date.now() / 1e3);
     const rumorTags = [["p", recipientPubkeyHex]];
     const rumorSerialized = JSON.stringify([0, senderPubkey, now, rumorKind, rumorTags, content]);
     const rumorId = bytesToHex(sha256(new TextEncoder().encode(rumorSerialized)));
     const rumor = { id: rumorId, pubkey: senderPubkey, created_at: now, kind: rumorKind, tags: rumorTags, content };
     const recipientPubkeyBytes = hexToBytes(recipientPubkeyHex);
-    const encryptedRumor = NIP44.encrypt(JSON.stringify(rumor), this.keyManager.getPrivateKey(), recipientPubkeyBytes);
+    const encryptedRumor = NIP44.encrypt(JSON.stringify(rumor), keyManager.getPrivateKey(), recipientPubkeyBytes);
     const sealTimestamp = now + Math.floor(Math.random() * 2 * TIMESTAMP_RANDOMIZATION) - TIMESTAMP_RANDOMIZATION;
-    const seal = NostrEventClass.create(this.keyManager, {
+    const seal = NostrEventClass.create(keyManager, {
       kind: EventKinds.SEAL,
       tags: [],
       content: encryptedRumor,
@@ -4241,11 +4342,17 @@ var AsyncSerialQueue = class {
 var WriteBuffer = class {
   /** Full TXF data from save() calls — latest wins */
   txfData = null;
+  /** IPNS context captured at save() time — ensures flush writes to the correct
+   *  IPNS record even if identity changes between save() and flush(). */
+  capturedIpnsKeyPair = null;
+  capturedIpnsName = null;
   get isEmpty() {
     return this.txfData === null;
   }
   clear() {
     this.txfData = null;
+    this.capturedIpnsKeyPair = null;
+    this.capturedIpnsName = null;
   }
   /**
    * Merge another buffer's contents into this one (for rollback).
@@ -4254,12 +4361,14 @@ var WriteBuffer = class {
   mergeFrom(other) {
     if (other.txfData && !this.txfData) {
       this.txfData = other.txfData;
+      this.capturedIpnsKeyPair = other.capturedIpnsKeyPair;
+      this.capturedIpnsName = other.capturedIpnsName;
     }
   }
 };
 
 // impl/shared/ipfs/ipfs-storage-provider.ts
-var IpfsStorageProvider = class {
+var IpfsStorageProvider = class _IpfsStorageProvider {
   id = "ipfs";
   name = "IPFS Storage";
   type = "p2p";
@@ -4304,7 +4413,12 @@ var IpfsStorageProvider = class {
   flushDebounceMs;
   /** Set to true during shutdown to prevent new flushes */
   isShuttingDown = false;
+  /** Stored config for createForAddress() cloning */
+  _config;
+  _statePersistenceCtor;
   constructor(config, statePersistence) {
+    this._config = config;
+    this._statePersistenceCtor = statePersistence;
     const gateways = config?.gateways ?? getIpfsGatewayUrls();
     this.debug = config?.debug ?? false;
     this.ipnsLifetimeMs = config?.ipnsLifetimeMs ?? 99 * 365 * 24 * 60 * 60 * 1e3;
@@ -4424,6 +4538,7 @@ var IpfsStorageProvider = class {
   }
   async shutdown() {
     this.isShuttingDown = true;
+    logger.debug("IPFS-Storage", `shutdown: ipnsName=${this.ipnsName?.slice(0, 20)}..., pendingEmpty=${this.pendingBuffer.isEmpty}, capturedIpns=${this.pendingBuffer.capturedIpnsName?.slice(0, 20) ?? "none"}`);
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
@@ -4456,6 +4571,8 @@ var IpfsStorageProvider = class {
       return { success: false, error: "Not initialized", timestamp: Date.now() };
     }
     this.pendingBuffer.txfData = data;
+    this.pendingBuffer.capturedIpnsKeyPair = this.ipnsKeyPair;
+    this.pendingBuffer.capturedIpnsName = this.ipnsName;
     this.scheduleFlush();
     return { success: true, timestamp: Date.now() };
   }
@@ -4466,8 +4583,12 @@ var IpfsStorageProvider = class {
    * Perform the actual upload + IPNS publish synchronously.
    * Called by executeFlush() and sync() — never by public save().
    */
-  async _doSave(data) {
-    if (!this.ipnsKeyPair || !this.ipnsName) {
+  async _doSave(data, overrideIpns) {
+    const ipnsKeyPair = overrideIpns?.keyPair ?? this.ipnsKeyPair;
+    const ipnsName = overrideIpns?.name ?? this.ipnsName;
+    const metaAddr = data?._meta?.address;
+    logger.debug("IPFS-Storage", `_doSave: ipnsName=${ipnsName?.slice(0, 20)}..., override=${!!overrideIpns}, meta.address=${metaAddr?.slice(0, 20) ?? "none"}`);
+    if (!ipnsKeyPair || !ipnsName) {
       return { success: false, error: "Not initialized", timestamp: Date.now() };
     }
     this.emitEvent({ type: "storage:saving", timestamp: Date.now() });
@@ -4476,7 +4597,7 @@ var IpfsStorageProvider = class {
       const metaUpdate = {
         ...data._meta,
         version: this.dataVersion,
-        ipnsName: this.ipnsName,
+        ipnsName,
         updatedAt: Date.now()
       };
       if (this.remoteCid) {
@@ -4488,13 +4609,13 @@ var IpfsStorageProvider = class {
       const baseSeq = this.ipnsSequenceNumber > this.lastKnownRemoteSequence ? this.ipnsSequenceNumber : this.lastKnownRemoteSequence;
       const newSeq = baseSeq + 1n;
       const marshalledRecord = await createSignedRecord(
-        this.ipnsKeyPair,
+        ipnsKeyPair,
         cid,
         newSeq,
         this.ipnsLifetimeMs
       );
       const publishResult = await this.httpClient.publishIpns(
-        this.ipnsName,
+        ipnsName,
         marshalledRecord
       );
       if (!publishResult.success) {
@@ -4509,14 +4630,14 @@ var IpfsStorageProvider = class {
       this.ipnsSequenceNumber = newSeq;
       this.lastCid = cid;
       this.remoteCid = cid;
-      this.cache.setIpnsRecord(this.ipnsName, {
+      this.cache.setIpnsRecord(ipnsName, {
         cid,
         sequence: newSeq,
         gateway: "local"
       });
       this.cache.setContent(cid, updatedData);
-      this.cache.markIpnsFresh(this.ipnsName);
-      await this.statePersistence.save(this.ipnsName, {
+      this.cache.markIpnsFresh(ipnsName);
+      await this.statePersistence.save(ipnsName, {
         sequenceNumber: newSeq.toString(),
         lastCid: cid,
         version: this.dataVersion
@@ -4568,7 +4689,8 @@ var IpfsStorageProvider = class {
       const baseData = active.txfData ?? {
         _meta: { version: 0, address: this.identity?.directAddress ?? "", formatVersion: "2.0", updatedAt: 0 }
       };
-      const result = await this._doSave(baseData);
+      const overrideIpns = active.capturedIpnsKeyPair && active.capturedIpnsName ? { keyPair: active.capturedIpnsKeyPair, name: active.capturedIpnsName } : void 0;
+      const result = await this._doSave(baseData, overrideIpns);
       if (!result.success) {
         throw new SphereError(result.error ?? "Save failed", "STORAGE_ERROR");
       }
@@ -4871,6 +4993,13 @@ var IpfsStorageProvider = class {
   log(message) {
     logger.debug("IPFS-Storage", message);
   }
+  /**
+   * Create an independent instance for a different address.
+   * Shares the same gateway/timeout config but has fresh IPNS state.
+   */
+  createForAddress() {
+    return new _IpfsStorageProvider(this._config, this._statePersistenceCtor);
+  }
 };
 
 // impl/nodejs/ipfs/nodejs-ipfs-state-persistence.ts