@unicitylabs/sphere-sdk 0.2.2 → 0.2.5

package/dist/impl/nodejs/index.js

@@ -25,7 +25,9 @@ var STORAGE_KEYS_GLOBAL = {
   /** Nametag cache per address (separate from tracked addresses registry) */
   ADDRESS_NAMETAGS: "address_nametags",
   /** Active addresses registry (JSON: TrackedAddressesStorage) */
-  TRACKED_ADDRESSES: "tracked_addresses"
+  TRACKED_ADDRESSES: "tracked_addresses",
+  /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
+  LAST_WALLET_EVENT_TS: "last_wallet_event_ts"
 };
 var STORAGE_KEYS_ADDRESS = {
   /** Pending transfers for this address */
@@ -37,7 +39,9 @@ var STORAGE_KEYS_ADDRESS = {
   /** Messages for this address */
   MESSAGES: "messages",
   /** Transaction history for this address */
-  TRANSACTION_HISTORY: "transaction_history"
+  TRANSACTION_HISTORY: "transaction_history",
+  /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
+  PENDING_V5_TOKENS: "pending_v5_tokens"
 };
 var STORAGE_KEYS = {
   ...STORAGE_KEYS_GLOBAL,
@@ -84,6 +88,19 @@ var DEFAULT_IPFS_GATEWAYS = [
   "https://dweb.link",
   "https://ipfs.io"
 ];
+var UNICITY_IPFS_NODES = [
+  {
+    host: "unicity-ipfs1.dyndns.org",
+    peerId: "12D3KooWDKJqEMAhH4nsSSiKtK1VLcas5coUqSPZAfbWbZpxtL4u",
+    httpPort: 9080,
+    httpsPort: 443
+  }
+];
+function getIpfsGatewayUrls(isSecure) {
+  return UNICITY_IPFS_NODES.map(
+    (node) => isSecure !== false ? `https://${node.host}` : `http://${node.host}:${node.httpPort}`
+  );
+}
 var DEFAULT_BASE_PATH = "m/44'/0'/0'";
 var DEFAULT_DERIVATION_PATH = `${DEFAULT_BASE_PATH}/0/0`;
 var DEFAULT_ELECTRUM_URL = "wss://fulcrum.alpha.unicity.network:50004";
@@ -1023,8 +1040,21 @@ function publicKeyToAddress(publicKey, prefix = "alpha", witnessVersion = 0) {
   const programBytes = hash160ToBytes(pubKeyHash);
   return encodeBech32(prefix, witnessVersion, programBytes);
 }
+function hexToBytes(hex) {
+  const matches = hex.match(/../g);
+  if (!matches) {
+    return new Uint8Array(0);
+  }
+  return Uint8Array.from(matches.map((x) => parseInt(x, 16)));
+}
 
 // transport/websocket.ts
+var WebSocketReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3
+};
 function defaultUUIDGenerator() {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
     return crypto.randomUUID();
@@ -1101,6 +1131,9 @@ var NostrTransportProvider = class {
   type = "p2p";
   description = "P2P messaging via Nostr protocol";
   config;
+  storage = null;
+  /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
+  lastEventTs = 0;
   identity = null;
   keyManager = null;
   status = "disconnected";
@@ -1109,6 +1142,7 @@ var NostrTransportProvider = class {
   nostrClient = null;
   mainSubscriptionId = null;
   // Event handlers
+  processedEventIds = /* @__PURE__ */ new Set();
   messageHandlers = /* @__PURE__ */ new Set();
   transferHandlers = /* @__PURE__ */ new Set();
   paymentRequestHandlers = /* @__PURE__ */ new Set();
@@ -1126,6 +1160,7 @@ var NostrTransportProvider = class {
       createWebSocket: config.createWebSocket,
       generateUUID: config.generateUUID ?? defaultUUIDGenerator
     };
+    this.storage = config.storage ?? null;
   }
   // ===========================================================================
   // BaseProvider Implementation
@@ -1164,7 +1199,14 @@ var NostrTransportProvider = class {
           this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
         }
       });
-      await this.nostrClient.connect(...this.config.relays);
+      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 Error("Failed to connect to any relay");
       }
@@ -1172,7 +1214,7 @@ var NostrTransportProvider = class {
       this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
       this.log("Connected to", this.nostrClient.getConnectedRelays().size, "relays");
       if (this.identity) {
-        this.subscribeToEvents();
+        await this.subscribeToEvents();
       }
     } catch (error) {
       this.status = "error";
@@ -1325,11 +1367,18 @@ var NostrTransportProvider = class {
           this.log("NostrClient reconnected to relay:", url);
         }
       });
-      await this.nostrClient.connect(...this.config.relays);
-      this.subscribeToEvents();
+      await Promise.race([
+        this.nostrClient.connect(...this.config.relays),
+        new Promise(
+          (_, reject) => setTimeout(() => reject(new Error(
+            `Transport reconnection timed out after ${this.config.timeout}ms`
+          )), this.config.timeout)
+        )
+      ]);
+      await this.subscribeToEvents();
       oldClient.disconnect();
     } else if (this.isConnected()) {
-      this.subscribeToEvents();
+      await this.subscribeToEvents();
     }
   }
   /**
@@ -1834,6 +1883,12 @@ var NostrTransportProvider = class {
   // Private: Message Handling
   // ===========================================================================
   async handleEvent(event) {
+    if (event.id && this.processedEventIds.has(event.id)) {
+      return;
+    }
+    if (event.id) {
+      this.processedEventIds.add(event.id);
+    }
     this.log("Processing event kind:", event.kind, "id:", event.id?.slice(0, 12));
     try {
       switch (event.kind) {
@@ -1857,10 +1912,31 @@ var NostrTransportProvider = class {
           this.handleBroadcast(event);
           break;
       }
+      if (event.created_at && this.storage && this.keyManager) {
+        const kind = event.kind;
+        if (kind === EVENT_KINDS.DIRECT_MESSAGE || kind === EVENT_KINDS.TOKEN_TRANSFER || kind === EVENT_KINDS.PAYMENT_REQUEST || kind === EVENT_KINDS.PAYMENT_REQUEST_RESPONSE) {
+          this.updateLastEventTimestamp(event.created_at);
+        }
+      }
     } catch (error) {
       this.log("Failed to handle event:", error);
     }
   }
+  /**
+   * Save the max event timestamp to storage (fire-and-forget, no await needed by caller).
+   * Uses in-memory `lastEventTs` to avoid read-before-write race conditions
+   * when multiple events arrive in quick succession.
+   */
+  updateLastEventTimestamp(createdAt) {
+    if (!this.storage || !this.keyManager) return;
+    if (createdAt <= this.lastEventTs) return;
+    this.lastEventTs = createdAt;
+    const pubkey = this.keyManager.getPublicKeyHex();
+    const storageKey = `${STORAGE_KEYS_GLOBAL.LAST_WALLET_EVENT_TS}_${pubkey.slice(0, 16)}`;
+    this.storage.set(storageKey, createdAt.toString()).catch((err) => {
+      this.log("Failed to save last event timestamp:", err);
+    });
+  }
   async handleDirectMessage(event) {
     this.log("Ignoring NIP-04 kind 4 event (DMs use NIP-17):", event.id?.slice(0, 12));
   }
@@ -1925,7 +2001,7 @@ var NostrTransportProvider = class {
     this.emitEvent({ type: "transfer:received", timestamp: Date.now() });
     for (const handler of this.transferHandlers) {
       try {
-        handler(transfer);
+        await handler(transfer);
       } catch (error) {
         this.log("Transfer handler error:", error);
       }
@@ -1939,6 +2015,7 @@ var NostrTransportProvider = class {
       const request = {
         id: event.id,
         senderTransportPubkey: event.pubkey,
+        senderNametag: requestData.recipientNametag,
         request: {
           requestId: requestData.requestId,
           amount: requestData.amount,
@@ -2054,6 +2131,49 @@ var NostrTransportProvider = class {
     const sdkEvent = NostrEventClass.fromJSON(event);
     await this.nostrClient.publishEvent(sdkEvent);
   }
+  async fetchPendingEvents() {
+    if (!this.nostrClient?.isConnected() || !this.keyManager) {
+      throw new Error("Transport not connected");
+    }
+    const nostrPubkey = this.keyManager.getPublicKeyHex();
+    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"] = [nostrPubkey];
+    walletFilter.since = Math.floor(Date.now() / 1e3) - 86400;
+    const events = [];
+    await new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        if (subId) this.nostrClient?.unsubscribe(subId);
+        resolve();
+      }, 5e3);
+      const subId = this.nostrClient.subscribe(walletFilter, {
+        onEvent: (event) => {
+          events.push({
+            id: event.id,
+            kind: event.kind,
+            content: event.content,
+            tags: event.tags,
+            pubkey: event.pubkey,
+            created_at: event.created_at,
+            sig: event.sig
+          });
+        },
+        onEndOfStoredEvents: () => {
+          clearTimeout(timeout);
+          this.nostrClient?.unsubscribe(subId);
+          resolve();
+        }
+      });
+    });
+    for (const event of events) {
+      await this.handleEvent(event);
+    }
+  }
   async queryEvents(filterObj) {
     if (!this.nostrClient || !this.nostrClient.isConnected()) {
       throw new Error("No connected relays");
@@ -2093,7 +2213,7 @@ var NostrTransportProvider = class {
   // Track subscription IDs for cleanup
   walletSubscriptionId = null;
   chatSubscriptionId = null;
-  subscribeToEvents() {
+  async subscribeToEvents() {
     this.log("subscribeToEvents called, identity:", !!this.identity, "keyManager:", !!this.keyManager, "nostrClient:", !!this.nostrClient);
     if (!this.identity || !this.keyManager || !this.nostrClient) {
       this.log("subscribeToEvents: skipped - no identity, keyManager, or nostrClient");
@@ -2113,6 +2233,27 @@ var NostrTransportProvider = class {
     }
     const nostrPubkey = this.keyManager.getPublicKeyHex();
     this.log("Subscribing with Nostr pubkey:", nostrPubkey);
+    let since;
+    if (this.storage) {
+      const storageKey = `${STORAGE_KEYS_GLOBAL.LAST_WALLET_EVENT_TS}_${nostrPubkey.slice(0, 16)}`;
+      try {
+        const stored = await this.storage.get(storageKey);
+        if (stored) {
+          since = parseInt(stored, 10);
+          this.lastEventTs = since;
+          this.log("Resuming from stored event timestamp:", since);
+        } else {
+          since = Math.floor(Date.now() / 1e3);
+          this.log("No stored timestamp, starting from now:", since);
+        }
+      } catch (err) {
+        this.log("Failed to read last event timestamp, falling back to now:", err);
+        since = Math.floor(Date.now() / 1e3);
+      }
+    } else {
+      since = Math.floor(Date.now() / 1e3) - 86400;
+      this.log("No storage adapter, using 24h fallback");
+    }
     const walletFilter = new Filter();
     walletFilter.kinds = [
       EVENT_KINDS.DIRECT_MESSAGE,
@@ -2121,7 +2262,7 @@ var NostrTransportProvider = class {
       EVENT_KINDS.PAYMENT_REQUEST_RESPONSE
     ];
     walletFilter["#p"] = [nostrPubkey];
-    walletFilter.since = Math.floor(Date.now() / 1e3) - 86400;
+    walletFilter.since = since;
     this.walletSubscriptionId = this.nostrClient.subscribe(walletFilter, {
       onEvent: (event) => {
         this.log("Received wallet event kind:", event.kind, "id:", event.id?.slice(0, 12));
@@ -2742,186 +2883,2093 @@ function createUnicityAggregatorProvider(config) {
 }
 var createUnicityOracleProvider = createUnicityAggregatorProvider;
 
-// price/CoinGeckoPriceProvider.ts
-var CoinGeckoPriceProvider = class {
-  platform = "coingecko";
-  cache = /* @__PURE__ */ new Map();
-  apiKey;
-  cacheTtlMs;
-  timeout;
-  debug;
-  baseUrl;
-  constructor(config) {
-    this.apiKey = config?.apiKey;
-    this.cacheTtlMs = config?.cacheTtlMs ?? 6e4;
-    this.timeout = config?.timeout ?? 1e4;
-    this.debug = config?.debug ?? false;
-    this.baseUrl = config?.baseUrl ?? (this.apiKey ? "https://pro-api.coingecko.com/api/v3" : "https://api.coingecko.com/api/v3");
+// impl/shared/ipfs/ipfs-error-types.ts
+var IpfsError = class extends Error {
+  category;
+  gateway;
+  cause;
+  constructor(message, category, gateway, cause) {
+    super(message);
+    this.name = "IpfsError";
+    this.category = category;
+    this.gateway = gateway;
+    this.cause = cause;
+  }
+  /** Whether this error should trigger the circuit breaker */
+  get shouldTriggerCircuitBreaker() {
+    return this.category !== "NOT_FOUND" && this.category !== "SEQUENCE_DOWNGRADE";
   }
-  async getPrices(tokenNames) {
-    if (tokenNames.length === 0) {
-      return /* @__PURE__ */ new Map();
-    }
-    const now = Date.now();
-    const result = /* @__PURE__ */ new Map();
-    const uncachedNames = [];
-    for (const name of tokenNames) {
-      const cached = this.cache.get(name);
-      if (cached && cached.expiresAt > now) {
-        if (cached.price !== null) {
-          result.set(name, cached.price);
-        }
-      } else {
-        uncachedNames.push(name);
-      }
-    }
-    if (uncachedNames.length === 0) {
-      return result;
-    }
-    try {
-      const ids = uncachedNames.join(",");
-      const url = `${this.baseUrl}/simple/price?ids=${encodeURIComponent(ids)}&vs_currencies=usd,eur&include_24hr_change=true`;
-      const headers = { Accept: "application/json" };
-      if (this.apiKey) {
-        headers["x-cg-pro-api-key"] = this.apiKey;
-      }
-      if (this.debug) {
-        console.log(`[CoinGecko] Fetching prices for: ${uncachedNames.join(", ")}`);
-      }
-      const response = await fetch(url, {
-        headers,
-        signal: AbortSignal.timeout(this.timeout)
-      });
-      if (!response.ok) {
-        throw new Error(`CoinGecko API error: ${response.status} ${response.statusText}`);
-      }
-      const data = await response.json();
-      for (const [name, values] of Object.entries(data)) {
-        if (values && typeof values === "object") {
-          const price = {
-            tokenName: name,
-            priceUsd: values.usd ?? 0,
-            priceEur: values.eur,
-            change24h: values.usd_24h_change,
-            timestamp: now
-          };
-          this.cache.set(name, { price, expiresAt: now + this.cacheTtlMs });
-          result.set(name, price);
-        }
-      }
-      for (const name of uncachedNames) {
-        if (!result.has(name)) {
-          this.cache.set(name, { price: null, expiresAt: now + this.cacheTtlMs });
-        }
-      }
-      if (this.debug) {
-        console.log(`[CoinGecko] Fetched ${result.size} prices`);
-      }
-    } catch (error) {
-      if (this.debug) {
-        console.warn("[CoinGecko] Fetch failed, using stale cache:", error);
-      }
-      for (const name of uncachedNames) {
-        const stale = this.cache.get(name);
-        if (stale?.price) {
-          result.set(name, stale.price);
-        }
-      }
+};
+function classifyFetchError(error) {
+  if (error instanceof DOMException && error.name === "AbortError") {
+    return "TIMEOUT";
+  }
+  if (error instanceof TypeError) {
+    return "NETWORK_ERROR";
+  }
+  if (error instanceof Error && error.name === "TimeoutError") {
+    return "TIMEOUT";
+  }
+  return "NETWORK_ERROR";
+}
+function classifyHttpStatus(status, responseBody) {
+  if (status === 404) {
+    return "NOT_FOUND";
+  }
+  if (status === 500 && responseBody) {
+    if (/routing:\s*not\s*found/i.test(responseBody)) {
+      return "NOT_FOUND";
     }
-    return result;
   }
-  async getPrice(tokenName) {
-    const prices = await this.getPrices([tokenName]);
-    return prices.get(tokenName) ?? null;
+  if (status >= 500) {
+    return "GATEWAY_ERROR";
   }
-  clearCache() {
-    this.cache.clear();
+  if (status >= 400) {
+    return "GATEWAY_ERROR";
   }
-};
+  return "GATEWAY_ERROR";
+}
 
-// price/index.ts
-function createPriceProvider(config) {
-  switch (config.platform) {
-    case "coingecko":
-      return new CoinGeckoPriceProvider(config);
-    default:
-      throw new Error(`Unsupported price platform: ${String(config.platform)}`);
+// impl/shared/ipfs/ipfs-state-persistence.ts
+var InMemoryIpfsStatePersistence = class {
+  states = /* @__PURE__ */ new Map();
+  async load(ipnsName) {
+    return this.states.get(ipnsName) ?? null;
   }
-}
+  async save(ipnsName, state) {
+    this.states.set(ipnsName, { ...state });
+  }
+  async clear(ipnsName) {
+    this.states.delete(ipnsName);
+  }
+};
 
-// impl/shared/resolvers.ts
-function getNetworkConfig(network = "mainnet") {
-  return NETWORKS[network];
-}
-function resolveTransportConfig(network, config) {
-  const networkConfig = getNetworkConfig(network);
-  let relays;
-  if (config?.relays) {
-    relays = config.relays;
-  } else {
-    relays = [...networkConfig.nostrRelays];
-    if (config?.additionalRelays) {
-      relays = [...relays, ...config.additionalRelays];
-    }
+// impl/shared/ipfs/ipns-key-derivation.ts
+var IPNS_HKDF_INFO = "ipfs-storage-ed25519-v1";
+var libp2pCryptoModule = null;
+var libp2pPeerIdModule = null;
+async function loadLibp2pModules() {
+  if (!libp2pCryptoModule) {
+    [libp2pCryptoModule, libp2pPeerIdModule] = await Promise.all([
+      import("@libp2p/crypto/keys"),
+      import("@libp2p/peer-id")
+    ]);
   }
   return {
-    relays,
-    timeout: config?.timeout,
-    autoReconnect: config?.autoReconnect,
-    debug: config?.debug,
-    // Browser-specific
-    reconnectDelay: config?.reconnectDelay,
-    maxReconnectAttempts: config?.maxReconnectAttempts
+    generateKeyPairFromSeed: libp2pCryptoModule.generateKeyPairFromSeed,
+    peerIdFromPrivateKey: libp2pPeerIdModule.peerIdFromPrivateKey
   };
 }
-function resolveOracleConfig(network, config) {
-  const networkConfig = getNetworkConfig(network);
+function deriveEd25519KeyMaterial(privateKeyHex, info = IPNS_HKDF_INFO) {
+  const walletSecret = hexToBytes(privateKeyHex);
+  const infoBytes = new TextEncoder().encode(info);
+  return hkdf(sha256, walletSecret, void 0, infoBytes, 32);
+}
+async function deriveIpnsIdentity(privateKeyHex) {
+  const { generateKeyPairFromSeed, peerIdFromPrivateKey } = await loadLibp2pModules();
+  const derivedKey = deriveEd25519KeyMaterial(privateKeyHex);
+  const keyPair = await generateKeyPairFromSeed("Ed25519", derivedKey);
+  const peerId = peerIdFromPrivateKey(keyPair);
   return {
-    url: config?.url ?? networkConfig.aggregatorUrl,
-    apiKey: config?.apiKey ?? DEFAULT_AGGREGATOR_API_KEY,
-    timeout: config?.timeout,
-    skipVerification: config?.skipVerification,
-    debug: config?.debug,
-    // Node.js-specific
-    trustBasePath: config?.trustBasePath
+    keyPair,
+    ipnsName: peerId.toString()
   };
 }
-function resolveL1Config(network, config) {
-  if (config === void 0) {
-    return void 0;
+
+// impl/shared/ipfs/ipns-record-manager.ts
+var DEFAULT_LIFETIME_MS = 99 * 365 * 24 * 60 * 60 * 1e3;
+var ipnsModule = null;
+async function loadIpnsModule() {
+  if (!ipnsModule) {
+    const mod = await import("ipns");
+    ipnsModule = {
+      createIPNSRecord: mod.createIPNSRecord,
+      marshalIPNSRecord: mod.marshalIPNSRecord,
+      unmarshalIPNSRecord: mod.unmarshalIPNSRecord
+    };
   }
-  const networkConfig = getNetworkConfig(network);
-  return {
-    electrumUrl: config.electrumUrl ?? networkConfig.electrumUrl,
-    defaultFeeRate: config.defaultFeeRate,
-    enableVesting: config.enableVesting
-  };
+  return ipnsModule;
 }
-function resolvePriceConfig(config) {
-  if (config === void 0) {
-    return void 0;
+async function createSignedRecord(keyPair, cid, sequenceNumber, lifetimeMs = DEFAULT_LIFETIME_MS) {
+  const { createIPNSRecord, marshalIPNSRecord } = await loadIpnsModule();
+  const record = await createIPNSRecord(
+    keyPair,
+    `/ipfs/${cid}`,
+    sequenceNumber,
+    lifetimeMs
+  );
+  return marshalIPNSRecord(record);
+}
+async function parseRoutingApiResponse(responseText) {
+  const { unmarshalIPNSRecord } = await loadIpnsModule();
+  const lines = responseText.trim().split("\n");
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const obj = JSON.parse(line);
+      if (obj.Extra) {
+        const recordData = base64ToUint8Array(obj.Extra);
+        const record = unmarshalIPNSRecord(recordData);
+        const valueBytes = typeof record.value === "string" ? new TextEncoder().encode(record.value) : record.value;
+        const valueStr = new TextDecoder().decode(valueBytes);
+        const cidMatch = valueStr.match(/\/ipfs\/([a-zA-Z0-9]+)/);
+        if (cidMatch) {
+          return {
+            cid: cidMatch[1],
+            sequence: record.sequence,
+            recordData
+          };
+        }
+      }
+    } catch {
+      continue;
+    }
   }
-  return {
-    platform: config.platform ?? "coingecko",
-    apiKey: config.apiKey,
-    baseUrl: config.baseUrl,
-    cacheTtlMs: config.cacheTtlMs,
-    timeout: config.timeout,
-    debug: config.debug
-  };
+  return null;
+}
+function base64ToUint8Array(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
 }
 
-// impl/nodejs/index.ts
-function createNodeProviders(config) {
-  const network = config?.network ?? "mainnet";
-  const transportConfig = resolveTransportConfig(network, config?.transport);
-  const oracleConfig = resolveOracleConfig(network, config?.oracle);
-  const l1Config = resolveL1Config(network, config?.l1);
-  const priceConfig = resolvePriceConfig(config?.price);
-  return {
-    storage: createFileStorageProvider({
-      dataDir: config?.dataDir ?? "./sphere-data"
-    }),
+// impl/shared/ipfs/ipfs-cache.ts
+var DEFAULT_IPNS_TTL_MS = 6e4;
+var DEFAULT_FAILURE_COOLDOWN_MS = 6e4;
+var DEFAULT_FAILURE_THRESHOLD = 3;
+var DEFAULT_KNOWN_FRESH_WINDOW_MS = 3e4;
+var IpfsCache = class {
+  ipnsRecords = /* @__PURE__ */ new Map();
+  content = /* @__PURE__ */ new Map();
+  gatewayFailures = /* @__PURE__ */ new Map();
+  knownFreshTimestamps = /* @__PURE__ */ new Map();
+  ipnsTtlMs;
+  failureCooldownMs;
+  failureThreshold;
+  knownFreshWindowMs;
+  constructor(config) {
+    this.ipnsTtlMs = config?.ipnsTtlMs ?? DEFAULT_IPNS_TTL_MS;
+    this.failureCooldownMs = config?.failureCooldownMs ?? DEFAULT_FAILURE_COOLDOWN_MS;
+    this.failureThreshold = config?.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+    this.knownFreshWindowMs = config?.knownFreshWindowMs ?? DEFAULT_KNOWN_FRESH_WINDOW_MS;
+  }
+  // ---------------------------------------------------------------------------
+  // IPNS Record Cache (60s TTL)
+  // ---------------------------------------------------------------------------
+  getIpnsRecord(ipnsName) {
+    const entry = this.ipnsRecords.get(ipnsName);
+    if (!entry) return null;
+    if (Date.now() - entry.timestamp > this.ipnsTtlMs) {
+      this.ipnsRecords.delete(ipnsName);
+      return null;
+    }
+    return entry.data;
+  }
+  /**
+   * Get cached IPNS record ignoring TTL (for known-fresh optimization).
+   */
+  getIpnsRecordIgnoreTtl(ipnsName) {
+    const entry = this.ipnsRecords.get(ipnsName);
+    return entry?.data ?? null;
+  }
+  setIpnsRecord(ipnsName, result) {
+    this.ipnsRecords.set(ipnsName, {
+      data: result,
+      timestamp: Date.now()
+    });
+  }
+  invalidateIpns(ipnsName) {
+    this.ipnsRecords.delete(ipnsName);
+  }
+  // ---------------------------------------------------------------------------
+  // Content Cache (infinite TTL - content is immutable by CID)
+  // ---------------------------------------------------------------------------
+  getContent(cid) {
+    const entry = this.content.get(cid);
+    return entry?.data ?? null;
+  }
+  setContent(cid, data) {
+    this.content.set(cid, {
+      data,
+      timestamp: Date.now()
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Gateway Failure Tracking (Circuit Breaker)
+  // ---------------------------------------------------------------------------
+  /**
+   * Record a gateway failure. After threshold consecutive failures,
+   * the gateway enters cooldown and is considered unhealthy.
+   */
+  recordGatewayFailure(gateway) {
+    const existing = this.gatewayFailures.get(gateway);
+    this.gatewayFailures.set(gateway, {
+      count: (existing?.count ?? 0) + 1,
+      lastFailure: Date.now()
+    });
+  }
+  /** Reset failure count for a gateway (on successful request) */
+  recordGatewaySuccess(gateway) {
+    this.gatewayFailures.delete(gateway);
+  }
+  /**
+   * Check if a gateway is currently in circuit breaker cooldown.
+   * A gateway is considered unhealthy if it has had >= threshold
+   * consecutive failures and the cooldown period hasn't elapsed.
+   */
+  isGatewayInCooldown(gateway) {
+    const failure = this.gatewayFailures.get(gateway);
+    if (!failure) return false;
+    if (failure.count < this.failureThreshold) return false;
+    const elapsed = Date.now() - failure.lastFailure;
+    if (elapsed >= this.failureCooldownMs) {
+      this.gatewayFailures.delete(gateway);
+      return false;
+    }
+    return true;
+  }
+  // ---------------------------------------------------------------------------
+  // Known-Fresh Flag (FAST mode optimization)
+  // ---------------------------------------------------------------------------
+  /**
+   * Mark IPNS cache as "known-fresh" (after local publish or push notification).
+   * Within the fresh window, we can skip network resolution.
+   */
+  markIpnsFresh(ipnsName) {
+    this.knownFreshTimestamps.set(ipnsName, Date.now());
+  }
+  /**
+   * Check if the cache is known-fresh (within the fresh window).
+   */
+  isIpnsKnownFresh(ipnsName) {
+    const timestamp = this.knownFreshTimestamps.get(ipnsName);
+    if (!timestamp) return false;
+    if (Date.now() - timestamp > this.knownFreshWindowMs) {
+      this.knownFreshTimestamps.delete(ipnsName);
+      return false;
+    }
+    return true;
+  }
+  // ---------------------------------------------------------------------------
+  // Cache Management
+  // ---------------------------------------------------------------------------
+  clear() {
+    this.ipnsRecords.clear();
+    this.content.clear();
+    this.gatewayFailures.clear();
+    this.knownFreshTimestamps.clear();
+  }
+};
+
+// impl/shared/ipfs/ipfs-http-client.ts
+var DEFAULT_CONNECTIVITY_TIMEOUT_MS = 5e3;
+var DEFAULT_FETCH_TIMEOUT_MS = 15e3;
+var DEFAULT_RESOLVE_TIMEOUT_MS = 1e4;
+var DEFAULT_PUBLISH_TIMEOUT_MS = 3e4;
+var DEFAULT_GATEWAY_PATH_TIMEOUT_MS = 3e3;
+var DEFAULT_ROUTING_API_TIMEOUT_MS = 2e3;
+var IpfsHttpClient = class {
+  gateways;
+  fetchTimeoutMs;
+  resolveTimeoutMs;
+  publishTimeoutMs;
+  connectivityTimeoutMs;
+  debug;
+  cache;
+  constructor(config, cache) {
+    this.gateways = config.gateways;
+    this.fetchTimeoutMs = config.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    this.resolveTimeoutMs = config.resolveTimeoutMs ?? DEFAULT_RESOLVE_TIMEOUT_MS;
+    this.publishTimeoutMs = config.publishTimeoutMs ?? DEFAULT_PUBLISH_TIMEOUT_MS;
+    this.connectivityTimeoutMs = config.connectivityTimeoutMs ?? DEFAULT_CONNECTIVITY_TIMEOUT_MS;
+    this.debug = config.debug ?? false;
+    this.cache = cache;
+  }
+  // ---------------------------------------------------------------------------
+  // Public Accessors
+  // ---------------------------------------------------------------------------
+  /**
+   * Get configured gateway URLs.
+   */
+  getGateways() {
+    return [...this.gateways];
+  }
+  // ---------------------------------------------------------------------------
+  // Gateway Health
+  // ---------------------------------------------------------------------------
+  /**
+   * Test connectivity to a single gateway.
+   */
+  async testConnectivity(gateway) {
+    const start = Date.now();
+    try {
+      const response = await this.fetchWithTimeout(
+        `${gateway}/api/v0/version`,
+        this.connectivityTimeoutMs,
+        { method: "POST" }
+      );
+      if (!response.ok) {
+        return { gateway, healthy: false, error: `HTTP ${response.status}` };
+      }
+      return {
+        gateway,
+        healthy: true,
+        responseTimeMs: Date.now() - start
+      };
+    } catch (error) {
+      return {
+        gateway,
+        healthy: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  /**
+   * Find healthy gateways from the configured list.
+   */
+  async findHealthyGateways() {
+    const results = await Promise.allSettled(
+      this.gateways.map((gw) => this.testConnectivity(gw))
+    );
+    return results.filter((r) => r.status === "fulfilled" && r.value.healthy).map((r) => r.value.gateway);
+  }
+  /**
+   * Get gateways that are not in circuit breaker cooldown.
+   */
+  getAvailableGateways() {
+    return this.gateways.filter((gw) => !this.cache.isGatewayInCooldown(gw));
+  }
+  // ---------------------------------------------------------------------------
+  // Content Upload
+  // ---------------------------------------------------------------------------
+  /**
+   * Upload JSON content to IPFS.
+   * Tries all gateways in parallel, returns first success.
+   */
+  async upload(data, gateways) {
+    const targets = gateways ?? this.getAvailableGateways();
+    if (targets.length === 0) {
+      throw new IpfsError("No gateways available for upload", "NETWORK_ERROR");
+    }
+    const jsonBytes = new TextEncoder().encode(JSON.stringify(data));
+    const promises = targets.map(async (gateway) => {
+      try {
+        const formData = new FormData();
+        formData.append("file", new Blob([jsonBytes], { type: "application/json" }), "data.json");
+        const response = await this.fetchWithTimeout(
+          `${gateway}/api/v0/add?pin=true&cid-version=1`,
+          this.publishTimeoutMs,
+          { method: "POST", body: formData }
+        );
+        if (!response.ok) {
+          throw new IpfsError(
+            `Upload failed: HTTP ${response.status}`,
+            classifyHttpStatus(response.status),
+            gateway
+          );
+        }
+        const result = await response.json();
+        this.cache.recordGatewaySuccess(gateway);
+        this.log(`Uploaded to ${gateway}: CID=${result.Hash}`);
+        return { cid: result.Hash, gateway };
+      } catch (error) {
+        if (error instanceof IpfsError && error.shouldTriggerCircuitBreaker) {
+          this.cache.recordGatewayFailure(gateway);
+        }
+        throw error;
+      }
+    });
+    try {
+      const result = await Promise.any(promises);
+      return { cid: result.cid };
+    } catch (error) {
+      if (error instanceof AggregateError) {
+        throw new IpfsError(
+          `Upload failed on all gateways: ${error.errors.map((e) => e.message).join("; ")}`,
+          "NETWORK_ERROR"
+        );
+      }
+      throw error;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Content Fetch
+  // ---------------------------------------------------------------------------
+  /**
+   * Fetch content by CID from IPFS gateways.
+   * Checks content cache first. Races all gateways for fastest response.
+   */
+  async fetchContent(cid, gateways) {
+    const cached = this.cache.getContent(cid);
+    if (cached) {
+      this.log(`Content cache hit for CID=${cid}`);
+      return cached;
+    }
+    const targets = gateways ?? this.getAvailableGateways();
+    if (targets.length === 0) {
+      throw new IpfsError("No gateways available for fetch", "NETWORK_ERROR");
+    }
+    const promises = targets.map(async (gateway) => {
+      try {
+        const response = await this.fetchWithTimeout(
+          `${gateway}/ipfs/${cid}`,
+          this.fetchTimeoutMs,
+          { headers: { Accept: "application/octet-stream" } }
+        );
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          throw new IpfsError(
+            `Fetch failed: HTTP ${response.status}`,
+            classifyHttpStatus(response.status, body),
+            gateway
+          );
+        }
+        const data = await response.json();
+        this.cache.recordGatewaySuccess(gateway);
+        this.cache.setContent(cid, data);
+        this.log(`Fetched from ${gateway}: CID=${cid}`);
+        return data;
+      } catch (error) {
+        if (error instanceof IpfsError && error.shouldTriggerCircuitBreaker) {
+          this.cache.recordGatewayFailure(gateway);
+        }
+        throw error;
+      }
+    });
+    try {
+      return await Promise.any(promises);
+    } catch (error) {
+      if (error instanceof AggregateError) {
+        throw new IpfsError(
+          `Fetch failed on all gateways for CID=${cid}`,
+          "NETWORK_ERROR"
+        );
+      }
+      throw error;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // IPNS Resolution
+  // ---------------------------------------------------------------------------
+  /**
+   * Resolve IPNS via Routing API (returns record with sequence number).
+   * POST /api/v0/routing/get?arg=/ipns/{name}
+   */
+  async resolveIpnsViaRoutingApi(gateway, ipnsName, timeoutMs = DEFAULT_ROUTING_API_TIMEOUT_MS) {
+    try {
+      const response = await this.fetchWithTimeout(
+        `${gateway}/api/v0/routing/get?arg=/ipns/${ipnsName}`,
+        timeoutMs,
+        { method: "POST" }
+      );
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        const category = classifyHttpStatus(response.status, body);
+        if (category === "NOT_FOUND") return null;
+        throw new IpfsError(`Routing API: HTTP ${response.status}`, category, gateway);
+      }
+      const text = await response.text();
+      const parsed = await parseRoutingApiResponse(text);
+      if (!parsed) return null;
+      this.cache.recordGatewaySuccess(gateway);
+      return {
+        cid: parsed.cid,
+        sequence: parsed.sequence,
+        gateway,
+        recordData: parsed.recordData
+      };
+    } catch (error) {
+      if (error instanceof IpfsError) throw error;
+      const category = classifyFetchError(error);
+      if (category !== "NOT_FOUND") {
+        this.cache.recordGatewayFailure(gateway);
+      }
+      return null;
+    }
+  }
+  /**
+   * Resolve IPNS via gateway path (simpler, no sequence number).
+   * GET /ipns/{name}?format=dag-json
+   */
+  async resolveIpnsViaGatewayPath(gateway, ipnsName, timeoutMs = DEFAULT_GATEWAY_PATH_TIMEOUT_MS) {
+    try {
+      const response = await this.fetchWithTimeout(
+        `${gateway}/ipns/${ipnsName}`,
+        timeoutMs,
+        { headers: { Accept: "application/json" } }
+      );
+      if (!response.ok) return null;
+      const content = await response.json();
+      const cidHeader = response.headers.get("X-Ipfs-Path");
+      if (cidHeader) {
+        const match = cidHeader.match(/\/ipfs\/([a-zA-Z0-9]+)/);
+        if (match) {
+          this.cache.recordGatewaySuccess(gateway);
+          return { cid: match[1], content };
+        }
+      }
+      return { cid: "", content };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Progressive IPNS resolution across all gateways.
+   * Queries all gateways in parallel, returns highest sequence number.
+   */
+  async resolveIpns(ipnsName, gateways) {
+    const targets = gateways ?? this.getAvailableGateways();
+    if (targets.length === 0) {
+      return { best: null, allResults: [], respondedCount: 0, totalGateways: 0 };
+    }
+    const results = [];
+    let respondedCount = 0;
+    const promises = targets.map(async (gateway) => {
+      const result = await this.resolveIpnsViaRoutingApi(
+        gateway,
+        ipnsName,
+        this.resolveTimeoutMs
+      );
+      if (result) results.push(result);
+      respondedCount++;
+      return result;
+    });
+    await Promise.race([
+      Promise.allSettled(promises),
+      new Promise((resolve) => setTimeout(resolve, this.resolveTimeoutMs + 1e3))
+    ]);
+    let best = null;
+    for (const result of results) {
+      if (!best || result.sequence > best.sequence) {
+        best = result;
+      }
+    }
+    if (best) {
+      this.cache.setIpnsRecord(ipnsName, best);
+    }
+    return {
+      best,
+      allResults: results,
+      respondedCount,
+      totalGateways: targets.length
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // IPNS Publishing
+  // ---------------------------------------------------------------------------
+  /**
+   * Publish IPNS record to a single gateway via routing API.
+   */
+  async publishIpnsViaRoutingApi(gateway, ipnsName, marshalledRecord, timeoutMs = DEFAULT_PUBLISH_TIMEOUT_MS) {
+    try {
+      const formData = new FormData();
+      formData.append(
+        "file",
+        new Blob([new Uint8Array(marshalledRecord)]),
+        "record"
+      );
+      const response = await this.fetchWithTimeout(
+        `${gateway}/api/v0/routing/put?arg=/ipns/${ipnsName}&allow-offline=true`,
+        timeoutMs,
+        { method: "POST", body: formData }
+      );
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        throw new IpfsError(
+          `IPNS publish: HTTP ${response.status}: ${errorText.slice(0, 100)}`,
+          classifyHttpStatus(response.status, errorText),
+          gateway
+        );
+      }
+      this.cache.recordGatewaySuccess(gateway);
+      this.log(`IPNS published to ${gateway}: ${ipnsName}`);
+      return true;
+    } catch (error) {
+      if (error instanceof IpfsError && error.shouldTriggerCircuitBreaker) {
+        this.cache.recordGatewayFailure(gateway);
+      }
+      this.log(`IPNS publish to ${gateway} failed: ${error}`);
+      return false;
+    }
+  }
+  /**
+   * Publish IPNS record to all gateways in parallel.
+   */
+  async publishIpns(ipnsName, marshalledRecord, gateways) {
+    const targets = gateways ?? this.getAvailableGateways();
+    if (targets.length === 0) {
+      return { success: false, error: "No gateways available" };
+    }
+    const results = await Promise.allSettled(
+      targets.map((gw) => this.publishIpnsViaRoutingApi(gw, ipnsName, marshalledRecord, this.publishTimeoutMs))
+    );
+    const successfulGateways = [];
+    results.forEach((result, index) => {
+      if (result.status === "fulfilled" && result.value) {
+        successfulGateways.push(targets[index]);
+      }
+    });
+    return {
+      success: successfulGateways.length > 0,
+      ipnsName,
+      successfulGateways,
+      error: successfulGateways.length === 0 ? "All gateways failed" : void 0
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // IPNS Verification
+  // ---------------------------------------------------------------------------
+  /**
+   * Verify IPNS record persistence after publishing.
+   * Retries resolution to confirm the record was accepted.
+   */
+  async verifyIpnsRecord(ipnsName, expectedSeq, expectedCid, retries = 3, delayMs = 1e3) {
+    for (let i = 0; i < retries; i++) {
+      if (i > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+      const { best } = await this.resolveIpns(ipnsName);
+      if (best && best.sequence >= expectedSeq && best.cid === expectedCid) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+  async fetchWithTimeout(url, timeoutMs, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  log(message) {
+    if (this.debug) {
+      console.log(`[IPFS-HTTP] ${message}`);
+    }
+  }
+};
+
+// impl/shared/ipfs/txf-merge.ts
+function mergeTxfData(local, remote) {
+  let added = 0;
+  let removed = 0;
+  let conflicts = 0;
+  const localVersion = local._meta?.version ?? 0;
+  const remoteVersion = remote._meta?.version ?? 0;
+  const baseMeta = localVersion >= remoteVersion ? local._meta : remote._meta;
+  const mergedMeta = {
+    ...baseMeta,
+    version: Math.max(localVersion, remoteVersion) + 1,
+    updatedAt: Date.now()
+  };
+  const mergedTombstones = mergeTombstones(
+    local._tombstones ?? [],
+    remote._tombstones ?? []
+  );
+  const tombstoneKeys = new Set(
+    mergedTombstones.map((t) => `${t.tokenId}:${t.stateHash}`)
+  );
+  const localTokenKeys = getTokenKeys(local);
+  const remoteTokenKeys = getTokenKeys(remote);
+  const allTokenKeys = /* @__PURE__ */ new Set([...localTokenKeys, ...remoteTokenKeys]);
+  const mergedTokens = {};
+  for (const key of allTokenKeys) {
+    const tokenId = key.startsWith("_") ? key.slice(1) : key;
+    const localToken = local[key];
+    const remoteToken = remote[key];
+    if (isTokenTombstoned(tokenId, localToken, remoteToken, tombstoneKeys)) {
+      if (localTokenKeys.has(key)) removed++;
+      continue;
+    }
+    if (localToken && !remoteToken) {
+      mergedTokens[key] = localToken;
+    } else if (!localToken && remoteToken) {
+      mergedTokens[key] = remoteToken;
+      added++;
+    } else if (localToken && remoteToken) {
+      mergedTokens[key] = localToken;
+      conflicts++;
+    }
+  }
+  const mergedOutbox = mergeArrayById(
+    local._outbox ?? [],
+    remote._outbox ?? [],
+    "id"
+  );
+  const mergedSent = mergeArrayById(
+    local._sent ?? [],
+    remote._sent ?? [],
+    "tokenId"
+  );
+  const mergedInvalid = mergeArrayById(
+    local._invalid ?? [],
+    remote._invalid ?? [],
+    "tokenId"
+  );
+  const merged = {
+    _meta: mergedMeta,
+    _tombstones: mergedTombstones.length > 0 ? mergedTombstones : void 0,
+    _outbox: mergedOutbox.length > 0 ? mergedOutbox : void 0,
+    _sent: mergedSent.length > 0 ? mergedSent : void 0,
+    _invalid: mergedInvalid.length > 0 ? mergedInvalid : void 0,
+    ...mergedTokens
+  };
+  return { merged, added, removed, conflicts };
+}
+function mergeTombstones(local, remote) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const tombstone of [...local, ...remote]) {
+    const key = `${tombstone.tokenId}:${tombstone.stateHash}`;
+    const existing = merged.get(key);
+    if (!existing || tombstone.timestamp > existing.timestamp) {
+      merged.set(key, tombstone);
+    }
+  }
+  return Array.from(merged.values());
+}
+function getTokenKeys(data) {
+  const reservedKeys = /* @__PURE__ */ new Set([
+    "_meta",
+    "_tombstones",
+    "_outbox",
+    "_sent",
+    "_invalid",
+    "_nametag",
+    "_mintOutbox",
+    "_invalidatedNametags",
+    "_integrity"
+  ]);
+  const keys = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(data)) {
+    if (reservedKeys.has(key)) continue;
+    if (key.startsWith("archived-") || key.startsWith("_forked_") || key.startsWith("nametag-")) continue;
+    keys.add(key);
+  }
+  return keys;
+}
+function isTokenTombstoned(tokenId, localToken, remoteToken, tombstoneKeys) {
+  for (const key of tombstoneKeys) {
+    if (key.startsWith(`${tokenId}:`)) {
+      return true;
+    }
+  }
+  void localToken;
+  void remoteToken;
+  return false;
+}
+function mergeArrayById(local, remote, idField) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of local) {
+    const id = item[idField];
+    if (id !== void 0) {
+      seen.set(id, item);
+    }
+  }
+  for (const item of remote) {
+    const id = item[idField];
+    if (id !== void 0 && !seen.has(id)) {
+      seen.set(id, item);
+    }
+  }
+  return Array.from(seen.values());
+}
+
+// impl/shared/ipfs/ipns-subscription-client.ts
+var IpnsSubscriptionClient = class {
+  ws = null;
+  subscriptions = /* @__PURE__ */ new Map();
+  reconnectTimeout = null;
+  pingInterval = null;
+  fallbackPollInterval = null;
+  wsUrl;
+  createWebSocket;
+  pingIntervalMs;
+  initialReconnectDelayMs;
+  maxReconnectDelayMs;
+  debugEnabled;
+  reconnectAttempts = 0;
+  isConnecting = false;
+  connectionOpenedAt = 0;
+  destroyed = false;
+  /** Minimum stable connection time before resetting backoff (30 seconds) */
+  minStableConnectionMs = 3e4;
+  fallbackPollFn = null;
+  fallbackPollIntervalMs = 0;
+  constructor(config) {
+    this.wsUrl = config.wsUrl;
+    this.createWebSocket = config.createWebSocket;
+    this.pingIntervalMs = config.pingIntervalMs ?? 3e4;
+    this.initialReconnectDelayMs = config.reconnectDelayMs ?? 5e3;
+    this.maxReconnectDelayMs = config.maxReconnectDelayMs ?? 6e4;
+    this.debugEnabled = config.debug ?? false;
+  }
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+  /**
+   * Subscribe to IPNS updates for a specific name.
+   * Automatically connects the WebSocket if not already connected.
+   * If WebSocket is connecting, the name will be subscribed once connected.
+   */
+  subscribe(ipnsName, callback) {
+    if (!ipnsName || typeof ipnsName !== "string") {
+      this.log("Invalid IPNS name for subscription");
+      return () => {
+      };
+    }
+    const isNewSubscription = !this.subscriptions.has(ipnsName);
+    if (isNewSubscription) {
+      this.subscriptions.set(ipnsName, /* @__PURE__ */ new Set());
+    }
+    this.subscriptions.get(ipnsName).add(callback);
+    if (isNewSubscription && this.ws?.readyState === WebSocketReadyState.OPEN) {
+      this.sendSubscribe([ipnsName]);
+    }
+    if (!this.ws || this.ws.readyState !== WebSocketReadyState.OPEN) {
+      this.connect();
+    }
+    return () => {
+      const callbacks = this.subscriptions.get(ipnsName);
+      if (callbacks) {
+        callbacks.delete(callback);
+        if (callbacks.size === 0) {
+          this.subscriptions.delete(ipnsName);
+          if (this.ws?.readyState === WebSocketReadyState.OPEN) {
+            this.sendUnsubscribe([ipnsName]);
+          }
+          if (this.subscriptions.size === 0) {
+            this.disconnect();
+          }
+        }
+      }
+    };
+  }
+  /**
+   * Register a convenience update callback for all subscriptions.
+   * Returns an unsubscribe function.
+   */
+  onUpdate(callback) {
+    if (!this.subscriptions.has("*")) {
+      this.subscriptions.set("*", /* @__PURE__ */ new Set());
+    }
+    this.subscriptions.get("*").add(callback);
+    return () => {
+      const callbacks = this.subscriptions.get("*");
+      if (callbacks) {
+        callbacks.delete(callback);
+        if (callbacks.size === 0) {
+          this.subscriptions.delete("*");
+        }
+      }
+    };
+  }
+  /**
+   * Set a fallback poll function to use when WebSocket is disconnected.
+   * The poll function will be called at the specified interval while WS is down.
+   */
+  setFallbackPoll(fn, intervalMs) {
+    this.fallbackPollFn = fn;
+    this.fallbackPollIntervalMs = intervalMs;
+    if (!this.isConnected()) {
+      this.startFallbackPolling();
+    }
+  }
+  /**
+   * Connect to the WebSocket server.
+   */
+  connect() {
+    if (this.destroyed) return;
+    if (this.ws?.readyState === WebSocketReadyState.OPEN || this.isConnecting) {
+      return;
+    }
+    this.isConnecting = true;
+    try {
+      this.log(`Connecting to ${this.wsUrl}...`);
+      this.ws = this.createWebSocket(this.wsUrl);
+      this.ws.onopen = () => {
+        this.log("WebSocket connected");
+        this.isConnecting = false;
+        this.connectionOpenedAt = Date.now();
+        const names = Array.from(this.subscriptions.keys()).filter((n) => n !== "*");
+        if (names.length > 0) {
+          this.sendSubscribe(names);
+        }
+        this.startPingInterval();
+        this.stopFallbackPolling();
+      };
+      this.ws.onmessage = (event) => {
+        this.handleMessage(event.data);
+      };
+      this.ws.onclose = () => {
+        const connectionDuration = this.connectionOpenedAt > 0 ? Date.now() - this.connectionOpenedAt : 0;
+        const wasStable = connectionDuration >= this.minStableConnectionMs;
+        this.log(`WebSocket closed (duration: ${Math.round(connectionDuration / 1e3)}s)`);
+        this.isConnecting = false;
+        this.connectionOpenedAt = 0;
+        this.stopPingInterval();
+        if (wasStable) {
+          this.reconnectAttempts = 0;
+        }
+        this.startFallbackPolling();
+        this.scheduleReconnect();
+      };
+      this.ws.onerror = () => {
+        this.log("WebSocket error");
+        this.isConnecting = false;
+      };
+    } catch (e) {
+      this.log(`Failed to connect: ${e}`);
+      this.isConnecting = false;
+      this.startFallbackPolling();
+      this.scheduleReconnect();
+    }
+  }
+  /**
+   * Disconnect from the WebSocket server and clean up.
+   */
+  disconnect() {
+    this.destroyed = true;
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.stopPingInterval();
+    this.stopFallbackPolling();
+    if (this.ws) {
+      this.ws.onopen = null;
+      this.ws.onclose = null;
+      this.ws.onerror = null;
+      this.ws.onmessage = null;
+      this.ws.close();
+      this.ws = null;
+    }
+    this.isConnecting = false;
+    this.reconnectAttempts = 0;
+  }
+  /**
+   * Check if connected to the WebSocket server.
+   */
+  isConnected() {
+    return this.ws?.readyState === WebSocketReadyState.OPEN;
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: Message Handling
+  // ---------------------------------------------------------------------------
+  handleMessage(data) {
+    try {
+      const message = JSON.parse(data);
+      switch (message.type) {
+        case "update":
+          if (message.name && message.sequence !== void 0) {
+            this.notifySubscribers({
+              type: "update",
+              name: message.name,
+              sequence: message.sequence,
+              cid: message.cid ?? "",
+              timestamp: message.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+            });
+          }
+          break;
+        case "subscribed":
+          this.log(`Subscribed to ${message.names?.length || 0} names`);
+          break;
+        case "unsubscribed":
+          this.log(`Unsubscribed from ${message.names?.length || 0} names`);
+          break;
+        case "pong":
+          break;
+        case "error":
+          this.log(`Server error: ${message.message}`);
+          break;
+        default:
+          break;
+      }
+    } catch {
+      this.log("Failed to parse message");
+    }
+  }
+  notifySubscribers(update) {
+    const callbacks = this.subscriptions.get(update.name);
+    if (callbacks) {
+      this.log(`Update: ${update.name.slice(0, 16)}... seq=${update.sequence}`);
+      for (const callback of callbacks) {
+        try {
+          callback(update);
+        } catch {
+        }
+      }
+    }
+    const globalCallbacks = this.subscriptions.get("*");
+    if (globalCallbacks) {
+      for (const callback of globalCallbacks) {
+        try {
+          callback(update);
+        } catch {
+        }
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: WebSocket Send
+  // ---------------------------------------------------------------------------
+  sendSubscribe(names) {
+    if (this.ws?.readyState === WebSocketReadyState.OPEN) {
+      this.ws.send(JSON.stringify({ action: "subscribe", names }));
+    }
+  }
+  sendUnsubscribe(names) {
+    if (this.ws?.readyState === WebSocketReadyState.OPEN) {
+      this.ws.send(JSON.stringify({ action: "unsubscribe", names }));
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: Reconnection
+  // ---------------------------------------------------------------------------
+  /**
+   * Schedule reconnection with exponential backoff.
+   * Sequence: 5s, 10s, 20s, 40s, 60s (capped)
+   */
+  scheduleReconnect() {
+    if (this.destroyed || this.reconnectTimeout) return;
+    const realSubscriptions = Array.from(this.subscriptions.keys()).filter((n) => n !== "*");
+    if (realSubscriptions.length === 0) return;
+    this.reconnectAttempts++;
+    const delay = Math.min(
+      this.initialReconnectDelayMs * Math.pow(2, this.reconnectAttempts - 1),
+      this.maxReconnectDelayMs
+    );
+    this.log(`Reconnecting in ${(delay / 1e3).toFixed(1)}s (attempt ${this.reconnectAttempts})...`);
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null;
+      this.connect();
+    }, delay);
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: Keepalive
+  // ---------------------------------------------------------------------------
+  startPingInterval() {
+    this.stopPingInterval();
+    this.pingInterval = setInterval(() => {
+      if (this.ws?.readyState === WebSocketReadyState.OPEN) {
+        this.ws.send(JSON.stringify({ action: "ping" }));
+      }
+    }, this.pingIntervalMs);
+  }
+  stopPingInterval() {
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = null;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: Fallback Polling
+  // ---------------------------------------------------------------------------
+  startFallbackPolling() {
+    if (this.fallbackPollInterval || !this.fallbackPollFn || this.destroyed) return;
+    this.log(`Starting fallback polling (${this.fallbackPollIntervalMs / 1e3}s interval)`);
+    this.fallbackPollFn().catch(() => {
+    });
+    this.fallbackPollInterval = setInterval(() => {
+      this.fallbackPollFn?.().catch(() => {
+      });
+    }, this.fallbackPollIntervalMs);
+  }
+  stopFallbackPolling() {
+    if (this.fallbackPollInterval) {
+      clearInterval(this.fallbackPollInterval);
+      this.fallbackPollInterval = null;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: Logging
+  // ---------------------------------------------------------------------------
+  log(message) {
+    if (this.debugEnabled) {
+      console.log(`[IPNS-WS] ${message}`);
+    }
+  }
+};
+
+// impl/shared/ipfs/write-behind-buffer.ts
+var AsyncSerialQueue = class {
+  tail = Promise.resolve();
+  /** Enqueue an async operation. Returns when it completes. */
+  enqueue(fn) {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    this.tail = this.tail.then(
+      () => fn().then(resolve, reject),
+      () => fn().then(resolve, reject)
+    );
+    return promise;
+  }
+};
+var WriteBuffer = class {
+  /** Full TXF data from save() calls — latest wins */
+  txfData = null;
+  /** Individual token mutations: key -> { op: 'save'|'delete', data? } */
+  tokenMutations = /* @__PURE__ */ new Map();
+  get isEmpty() {
+    return this.txfData === null && this.tokenMutations.size === 0;
+  }
+  clear() {
+    this.txfData = null;
+    this.tokenMutations.clear();
+  }
+  /**
+   * Merge another buffer's contents into this one (for rollback).
+   * Existing (newer) mutations in `this` take precedence over `other`.
+   */
+  mergeFrom(other) {
+    if (other.txfData && !this.txfData) {
+      this.txfData = other.txfData;
+    }
+    for (const [id, mutation] of other.tokenMutations) {
+      if (!this.tokenMutations.has(id)) {
+        this.tokenMutations.set(id, mutation);
+      }
+    }
+  }
+};
+
+// impl/shared/ipfs/ipfs-storage-provider.ts
+var IpfsStorageProvider = class {
+  id = "ipfs";
+  name = "IPFS Storage";
+  type = "p2p";
+  status = "disconnected";
+  identity = null;
+  ipnsKeyPair = null;
+  ipnsName = null;
+  ipnsSequenceNumber = 0n;
+  lastCid = null;
+  lastKnownRemoteSequence = 0n;
+  dataVersion = 0;
+  /**
+   * The CID currently stored on the sidecar for this IPNS name.
+   * Used as `_meta.lastCid` in the next save to satisfy chain validation.
+   * - null for bootstrap (first-ever save)
+   * - set after every successful save() or load()
+   */
+  remoteCid = null;
+  cache;
+  httpClient;
+  statePersistence;
+  eventCallbacks = /* @__PURE__ */ new Set();
+  debug;
+  ipnsLifetimeMs;
+  /** WebSocket factory for push subscriptions */
+  createWebSocket;
+  /** Override WS URL */
+  wsUrl;
+  /** Fallback poll interval (default: 90000) */
+  fallbackPollIntervalMs;
+  /** IPNS subscription client for push notifications */
+  subscriptionClient = null;
+  /** Unsubscribe function from subscription client */
+  subscriptionUnsubscribe = null;
+  /** In-memory buffer for individual token save/delete calls */
+  tokenBuffer = /* @__PURE__ */ new Map();
+  deletedTokenIds = /* @__PURE__ */ new Set();
+  /** Write-behind buffer: serializes flush / sync / shutdown */
+  flushQueue = new AsyncSerialQueue();
+  /** Pending mutations not yet flushed to IPFS */
+  pendingBuffer = new WriteBuffer();
+  /** Debounce timer for background flush */
+  flushTimer = null;
+  /** Debounce interval in ms */
+  flushDebounceMs;
+  /** Set to true during shutdown to prevent new flushes */
+  isShuttingDown = false;
+  constructor(config, statePersistence) {
+    const gateways = config?.gateways ?? getIpfsGatewayUrls();
+    this.debug = config?.debug ?? false;
+    this.ipnsLifetimeMs = config?.ipnsLifetimeMs ?? 99 * 365 * 24 * 60 * 60 * 1e3;
+    this.flushDebounceMs = config?.flushDebounceMs ?? 2e3;
+    this.cache = new IpfsCache({
+      ipnsTtlMs: config?.ipnsCacheTtlMs,
+      failureCooldownMs: config?.circuitBreakerCooldownMs,
+      failureThreshold: config?.circuitBreakerThreshold,
+      knownFreshWindowMs: config?.knownFreshWindowMs
+    });
+    this.httpClient = new IpfsHttpClient({
+      gateways,
+      fetchTimeoutMs: config?.fetchTimeoutMs,
+      resolveTimeoutMs: config?.resolveTimeoutMs,
+      publishTimeoutMs: config?.publishTimeoutMs,
+      connectivityTimeoutMs: config?.connectivityTimeoutMs,
+      debug: this.debug
+    }, this.cache);
+    this.statePersistence = statePersistence ?? new InMemoryIpfsStatePersistence();
+    this.createWebSocket = config?.createWebSocket;
+    this.wsUrl = config?.wsUrl;
+    this.fallbackPollIntervalMs = config?.fallbackPollIntervalMs ?? 9e4;
+  }
+  // ---------------------------------------------------------------------------
+  // BaseProvider interface
+  // ---------------------------------------------------------------------------
+  async connect() {
+    await this.initialize();
+  }
+  async disconnect() {
+    await this.shutdown();
+  }
+  isConnected() {
+    return this.status === "connected";
+  }
+  getStatus() {
+    return this.status;
+  }
+  // ---------------------------------------------------------------------------
+  // Identity & Initialization
+  // ---------------------------------------------------------------------------
+  setIdentity(identity) {
+    this.identity = identity;
+  }
+  async initialize() {
+    if (!this.identity) {
+      this.log("Cannot initialize: no identity set");
+      return false;
+    }
+    this.status = "connecting";
+    this.emitEvent({ type: "storage:loading", timestamp: Date.now() });
+    try {
+      const { keyPair, ipnsName } = await deriveIpnsIdentity(this.identity.privateKey);
+      this.ipnsKeyPair = keyPair;
+      this.ipnsName = ipnsName;
+      this.log(`IPNS name derived: ${ipnsName}`);
+      const persisted = await this.statePersistence.load(ipnsName);
+      if (persisted) {
+        this.ipnsSequenceNumber = BigInt(persisted.sequenceNumber);
+        this.lastCid = persisted.lastCid;
+        this.remoteCid = persisted.lastCid;
+        this.dataVersion = persisted.version;
+        this.log(`Loaded persisted state: seq=${this.ipnsSequenceNumber}, cid=${this.lastCid}`);
+      }
+      if (this.createWebSocket) {
+        try {
+          const wsUrlFinal = this.wsUrl ?? this.deriveWsUrl();
+          if (wsUrlFinal) {
+            this.subscriptionClient = new IpnsSubscriptionClient({
+              wsUrl: wsUrlFinal,
+              createWebSocket: this.createWebSocket,
+              debug: this.debug
+            });
+            this.subscriptionUnsubscribe = this.subscriptionClient.subscribe(
+              ipnsName,
+              (update) => {
+                this.log(`Push update: seq=${update.sequence}, cid=${update.cid}`);
+                this.emitEvent({
+                  type: "storage:remote-updated",
+                  timestamp: Date.now(),
+                  data: { name: update.name, sequence: update.sequence, cid: update.cid }
+                });
+              }
+            );
+            this.subscriptionClient.setFallbackPoll(
+              () => this.pollForRemoteChanges(),
+              this.fallbackPollIntervalMs
+            );
+            this.subscriptionClient.connect();
+          }
+        } catch (wsError) {
+          this.log(`Failed to set up IPNS subscription: ${wsError}`);
+        }
+      }
+      this.httpClient.findHealthyGateways().then((healthy) => {
+        if (healthy.length > 0) {
+          this.log(`${healthy.length} healthy gateway(s) found`);
+        } else {
+          this.log("Warning: no healthy gateways found");
+        }
+      }).catch(() => {
+      });
+      this.isShuttingDown = false;
+      this.status = "connected";
+      this.emitEvent({ type: "storage:loaded", timestamp: Date.now() });
+      return true;
+    } catch (error) {
+      this.status = "error";
+      this.emitEvent({
+        type: "storage:error",
+        timestamp: Date.now(),
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return false;
+    }
+  }
+  async shutdown() {
+    this.isShuttingDown = true;
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flushQueue.enqueue(async () => {
+      if (!this.pendingBuffer.isEmpty) {
+        try {
+          await this.executeFlush();
+        } catch {
+          this.log("Final flush on shutdown failed (data may be lost)");
+        }
+      }
+    });
+    if (this.subscriptionUnsubscribe) {
+      this.subscriptionUnsubscribe();
+      this.subscriptionUnsubscribe = null;
+    }
+    if (this.subscriptionClient) {
+      this.subscriptionClient.disconnect();
+      this.subscriptionClient = null;
+    }
+    this.cache.clear();
+    this.status = "disconnected";
+  }
+  // ---------------------------------------------------------------------------
+  // Save (non-blocking — buffers data for async flush)
+  // ---------------------------------------------------------------------------
+  async save(data) {
+    if (!this.ipnsKeyPair || !this.ipnsName) {
+      return { success: false, error: "Not initialized", timestamp: Date.now() };
+    }
+    this.pendingBuffer.txfData = data;
+    this.scheduleFlush();
+    return { success: true, timestamp: Date.now() };
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: Blocking save (used by sync and executeFlush)
+  // ---------------------------------------------------------------------------
+  /**
+   * Perform the actual upload + IPNS publish synchronously.
+   * Called by executeFlush() and sync() — never by public save().
+   */
+  async _doSave(data) {
+    if (!this.ipnsKeyPair || !this.ipnsName) {
+      return { success: false, error: "Not initialized", timestamp: Date.now() };
+    }
+    this.emitEvent({ type: "storage:saving", timestamp: Date.now() });
+    try {
+      this.dataVersion++;
+      const metaUpdate = {
+        ...data._meta,
+        version: this.dataVersion,
+        ipnsName: this.ipnsName,
+        updatedAt: Date.now()
+      };
+      if (this.remoteCid) {
+        metaUpdate.lastCid = this.remoteCid;
+      }
+      const updatedData = { ...data, _meta: metaUpdate };
+      for (const [tokenId, tokenData] of this.tokenBuffer) {
+        if (!this.deletedTokenIds.has(tokenId)) {
+          updatedData[tokenId] = tokenData;
+        }
+      }
+      for (const tokenId of this.deletedTokenIds) {
+        delete updatedData[tokenId];
+      }
+      const { cid } = await this.httpClient.upload(updatedData);
+      this.log(`Content uploaded: CID=${cid}`);
+      const baseSeq = this.ipnsSequenceNumber > this.lastKnownRemoteSequence ? this.ipnsSequenceNumber : this.lastKnownRemoteSequence;
+      const newSeq = baseSeq + 1n;
+      const marshalledRecord = await createSignedRecord(
+        this.ipnsKeyPair,
+        cid,
+        newSeq,
+        this.ipnsLifetimeMs
+      );
+      const publishResult = await this.httpClient.publishIpns(
+        this.ipnsName,
+        marshalledRecord
+      );
+      if (!publishResult.success) {
+        this.dataVersion--;
+        this.log(`IPNS publish failed: ${publishResult.error}`);
+        return {
+          success: false,
+          error: publishResult.error ?? "IPNS publish failed",
+          timestamp: Date.now()
+        };
+      }
+      this.ipnsSequenceNumber = newSeq;
+      this.lastCid = cid;
+      this.remoteCid = cid;
+      this.cache.setIpnsRecord(this.ipnsName, {
+        cid,
+        sequence: newSeq,
+        gateway: "local"
+      });
+      this.cache.setContent(cid, updatedData);
+      this.cache.markIpnsFresh(this.ipnsName);
+      await this.statePersistence.save(this.ipnsName, {
+        sequenceNumber: newSeq.toString(),
+        lastCid: cid,
+        version: this.dataVersion
+      });
+      this.deletedTokenIds.clear();
+      this.emitEvent({
+        type: "storage:saved",
+        timestamp: Date.now(),
+        data: { cid, sequence: newSeq.toString() }
+      });
+      this.log(`Saved: CID=${cid}, seq=${newSeq}`);
+      return { success: true, cid, timestamp: Date.now() };
+    } catch (error) {
+      this.dataVersion--;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.emitEvent({
+        type: "storage:error",
+        timestamp: Date.now(),
+        error: errorMessage
+      });
+      return { success: false, error: errorMessage, timestamp: Date.now() };
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Write-behind buffer: scheduling and flushing
+  // ---------------------------------------------------------------------------
+  /**
+   * Schedule a debounced background flush.
+   * Resets the timer on each call so rapid mutations coalesce.
+   */
+  scheduleFlush() {
+    if (this.isShuttingDown) return;
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flushQueue.enqueue(() => this.executeFlush()).catch((err) => {
+        this.log(`Background flush failed: ${err}`);
+      });
+    }, this.flushDebounceMs);
+  }
+  /**
+   * Execute a flush of the pending buffer to IPFS.
+   * Runs inside AsyncSerialQueue for concurrency safety.
+   */
+  async executeFlush() {
+    if (this.pendingBuffer.isEmpty) return;
+    const active = this.pendingBuffer;
+    this.pendingBuffer = new WriteBuffer();
+    try {
+      const baseData = active.txfData ?? {
+        _meta: { version: 0, address: this.identity?.directAddress ?? "", formatVersion: "2.0", updatedAt: 0 }
+      };
+      const result = await this._doSave(baseData);
+      if (!result.success) {
+        throw new Error(result.error ?? "Save failed");
+      }
+      this.log(`Flushed successfully: CID=${result.cid}`);
+    } catch (error) {
+      this.pendingBuffer.mergeFrom(active);
+      const msg = error instanceof Error ? error.message : String(error);
+      this.log(`Flush failed (will retry): ${msg}`);
+      this.scheduleFlush();
+      throw error;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Load
+  // ---------------------------------------------------------------------------
+  async load(identifier) {
+    if (!this.ipnsName && !identifier) {
+      return { success: false, error: "Not initialized", source: "local", timestamp: Date.now() };
+    }
+    this.emitEvent({ type: "storage:loading", timestamp: Date.now() });
+    try {
+      if (identifier) {
+        const data2 = await this.httpClient.fetchContent(identifier);
+        return { success: true, data: data2, source: "remote", timestamp: Date.now() };
+      }
+      const ipnsName = this.ipnsName;
+      if (this.cache.isIpnsKnownFresh(ipnsName)) {
+        const cached = this.cache.getIpnsRecordIgnoreTtl(ipnsName);
+        if (cached) {
+          const content = this.cache.getContent(cached.cid);
+          if (content) {
+            this.log("Using known-fresh cached data");
+            return { success: true, data: content, source: "cache", timestamp: Date.now() };
+          }
+        }
+      }
+      const cachedRecord = this.cache.getIpnsRecord(ipnsName);
+      if (cachedRecord) {
+        const content = this.cache.getContent(cachedRecord.cid);
+        if (content) {
+          this.log("IPNS cache hit");
+          return { success: true, data: content, source: "cache", timestamp: Date.now() };
+        }
+        try {
+          const data2 = await this.httpClient.fetchContent(cachedRecord.cid);
+          return { success: true, data: data2, source: "remote", timestamp: Date.now() };
+        } catch {
+        }
+      }
+      const { best } = await this.httpClient.resolveIpns(ipnsName);
+      if (!best) {
+        this.log("IPNS record not found (new wallet?)");
+        return { success: false, error: "IPNS record not found", source: "remote", timestamp: Date.now() };
+      }
+      if (best.sequence > this.lastKnownRemoteSequence) {
+        this.lastKnownRemoteSequence = best.sequence;
+      }
+      this.remoteCid = best.cid;
+      const data = await this.httpClient.fetchContent(best.cid);
+      const remoteVersion = data?._meta?.version;
+      if (typeof remoteVersion === "number" && remoteVersion > this.dataVersion) {
+        this.dataVersion = remoteVersion;
+      }
+      this.populateTokenBuffer(data);
+      this.emitEvent({
+        type: "storage:loaded",
+        timestamp: Date.now(),
+        data: { cid: best.cid, sequence: best.sequence.toString() }
+      });
+      return { success: true, data, source: "remote", timestamp: Date.now() };
+    } catch (error) {
+      if (this.ipnsName) {
+        const cached = this.cache.getIpnsRecordIgnoreTtl(this.ipnsName);
+        if (cached) {
+          const content = this.cache.getContent(cached.cid);
+          if (content) {
+            this.log("Network error, returning stale cache");
+            return { success: true, data: content, source: "cache", timestamp: Date.now() };
+          }
+        }
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.emitEvent({
+        type: "storage:error",
+        timestamp: Date.now(),
+        error: errorMessage
+      });
+      return { success: false, error: errorMessage, source: "remote", timestamp: Date.now() };
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Sync (enters serial queue to avoid concurrent IPNS conflicts)
+  // ---------------------------------------------------------------------------
+  async sync(localData) {
+    return this.flushQueue.enqueue(async () => {
+      if (this.flushTimer) {
+        clearTimeout(this.flushTimer);
+        this.flushTimer = null;
+      }
+      this.emitEvent({ type: "sync:started", timestamp: Date.now() });
+      try {
+        this.pendingBuffer.clear();
+        const remoteResult = await this.load();
+        if (!remoteResult.success || !remoteResult.data) {
+          this.log("No remote data found, uploading local data");
+          const saveResult2 = await this._doSave(localData);
+          this.emitEvent({ type: "sync:completed", timestamp: Date.now() });
+          return {
+            success: saveResult2.success,
+            merged: this.enrichWithTokenBuffer(localData),
+            added: 0,
+            removed: 0,
+            conflicts: 0,
+            error: saveResult2.error
+          };
+        }
+        const remoteData = remoteResult.data;
+        const localVersion = localData._meta?.version ?? 0;
+        const remoteVersion = remoteData._meta?.version ?? 0;
+        if (localVersion === remoteVersion && this.lastCid) {
+          this.log("Data is in sync (same version)");
+          this.emitEvent({ type: "sync:completed", timestamp: Date.now() });
+          return {
+            success: true,
+            merged: this.enrichWithTokenBuffer(localData),
+            added: 0,
+            removed: 0,
+            conflicts: 0
+          };
+        }
+        this.log(`Merging: local v${localVersion} <-> remote v${remoteVersion}`);
+        const { merged, added, removed, conflicts } = mergeTxfData(localData, remoteData);
+        if (conflicts > 0) {
+          this.emitEvent({
+            type: "sync:conflict",
+            timestamp: Date.now(),
+            data: { conflicts }
+          });
+        }
+        const saveResult = await this._doSave(merged);
+        this.emitEvent({
+          type: "sync:completed",
+          timestamp: Date.now(),
+          data: { added, removed, conflicts }
+        });
+        return {
+          success: saveResult.success,
+          merged: this.enrichWithTokenBuffer(merged),
+          added,
+          removed,
+          conflicts,
+          error: saveResult.error
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.emitEvent({
+          type: "sync:error",
+          timestamp: Date.now(),
+          error: errorMessage
+        });
+        return {
+          success: false,
+          added: 0,
+          removed: 0,
+          conflicts: 0,
+          error: errorMessage
+        };
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Private Helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Enrich TXF data with individually-buffered tokens before returning to caller.
+   * PaymentsModule.createStorageData() passes empty tokens (they're stored via
+   * saveToken()), but loadFromStorageData() needs them in the merged result.
+   */
+  enrichWithTokenBuffer(data) {
+    if (this.tokenBuffer.size === 0) return data;
+    const enriched = { ...data };
+    for (const [tokenId, tokenData] of this.tokenBuffer) {
+      if (!this.deletedTokenIds.has(tokenId)) {
+        enriched[tokenId] = tokenData;
+      }
+    }
+    return enriched;
+  }
+  // ---------------------------------------------------------------------------
+  // Optional Methods
+  // ---------------------------------------------------------------------------
+  async exists() {
+    if (!this.ipnsName) return false;
+    const cached = this.cache.getIpnsRecord(this.ipnsName);
+    if (cached) return true;
+    const { best } = await this.httpClient.resolveIpns(this.ipnsName);
+    return best !== null;
+  }
+  async clear() {
+    if (!this.ipnsKeyPair || !this.ipnsName) return false;
+    this.pendingBuffer.clear();
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    const emptyData = {
+      _meta: {
+        version: 0,
+        address: this.identity?.directAddress ?? "",
+        ipnsName: this.ipnsName,
+        formatVersion: "2.0",
+        updatedAt: Date.now()
+      }
+    };
+    const result = await this._doSave(emptyData);
+    if (result.success) {
+      this.cache.clear();
+      this.tokenBuffer.clear();
+      this.deletedTokenIds.clear();
+      await this.statePersistence.clear(this.ipnsName);
+    }
+    return result.success;
+  }
+  onEvent(callback) {
+    this.eventCallbacks.add(callback);
+    return () => {
+      this.eventCallbacks.delete(callback);
+    };
+  }
+  async saveToken(tokenId, tokenData) {
+    this.pendingBuffer.tokenMutations.set(tokenId, { op: "save", data: tokenData });
+    this.tokenBuffer.set(tokenId, tokenData);
+    this.deletedTokenIds.delete(tokenId);
+    this.scheduleFlush();
+  }
+  async getToken(tokenId) {
+    if (this.deletedTokenIds.has(tokenId)) return null;
+    return this.tokenBuffer.get(tokenId) ?? null;
+  }
+  async listTokenIds() {
+    return Array.from(this.tokenBuffer.keys()).filter(
+      (id) => !this.deletedTokenIds.has(id)
+    );
+  }
+  async deleteToken(tokenId) {
+    this.pendingBuffer.tokenMutations.set(tokenId, { op: "delete" });
+    this.tokenBuffer.delete(tokenId);
+    this.deletedTokenIds.add(tokenId);
+    this.scheduleFlush();
+  }
+  // ---------------------------------------------------------------------------
+  // Public Accessors
+  // ---------------------------------------------------------------------------
+  getIpnsName() {
+    return this.ipnsName;
+  }
+  getLastCid() {
+    return this.lastCid;
+  }
+  getSequenceNumber() {
+    return this.ipnsSequenceNumber;
+  }
+  getDataVersion() {
+    return this.dataVersion;
+  }
+  getRemoteCid() {
+    return this.remoteCid;
+  }
+  // ---------------------------------------------------------------------------
+  // Testing helper: wait for pending flush to complete
+  // ---------------------------------------------------------------------------
+  /**
+   * Wait for the pending flush timer to fire and the flush operation to
+   * complete. Useful in tests to await background writes.
+   * Returns immediately if no flush is pending.
+   */
+  async waitForFlush() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+      await this.flushQueue.enqueue(() => this.executeFlush()).catch(() => {
+      });
+    } else if (!this.pendingBuffer.isEmpty) {
+      await this.flushQueue.enqueue(() => this.executeFlush()).catch(() => {
+      });
+    } else {
+      await this.flushQueue.enqueue(async () => {
+      });
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal: Push Subscription Helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Derive WebSocket URL from the first configured gateway.
+   * Converts https://host → wss://host/ws/ipns
+   */
+  deriveWsUrl() {
+    const gateways = this.httpClient.getGateways();
+    if (gateways.length === 0) return null;
+    const gateway = gateways[0];
+    const wsProtocol = gateway.startsWith("https://") ? "wss://" : "ws://";
+    const host = gateway.replace(/^https?:\/\//, "");
+    return `${wsProtocol}${host}/ws/ipns`;
+  }
+  /**
+   * Poll for remote IPNS changes (fallback when WS is unavailable).
+   * Compares remote sequence number with last known and emits event if changed.
+   */
+  async pollForRemoteChanges() {
+    if (!this.ipnsName) return;
+    try {
+      const { best } = await this.httpClient.resolveIpns(this.ipnsName);
+      if (best && best.sequence > this.lastKnownRemoteSequence) {
+        this.log(`Poll detected remote change: seq=${best.sequence} (was ${this.lastKnownRemoteSequence})`);
+        this.lastKnownRemoteSequence = best.sequence;
+        this.emitEvent({
+          type: "storage:remote-updated",
+          timestamp: Date.now(),
+          data: { name: this.ipnsName, sequence: Number(best.sequence), cid: best.cid }
+        });
+      }
+    } catch {
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+  emitEvent(event) {
+    for (const callback of this.eventCallbacks) {
+      try {
+        callback(event);
+      } catch {
+      }
+    }
+  }
+  log(message) {
+    if (this.debug) {
+      console.log(`[IPFS-Storage] ${message}`);
+    }
+  }
+  META_KEYS = /* @__PURE__ */ new Set([
+    "_meta",
+    "_tombstones",
+    "_outbox",
+    "_sent",
+    "_invalid",
+    "_nametag",
+    "_mintOutbox",
+    "_invalidatedNametags",
+    "_integrity"
+  ]);
+  populateTokenBuffer(data) {
+    this.tokenBuffer.clear();
+    this.deletedTokenIds.clear();
+    for (const key of Object.keys(data)) {
+      if (!this.META_KEYS.has(key)) {
+        this.tokenBuffer.set(key, data[key]);
+      }
+    }
+  }
+};
+
+// impl/nodejs/ipfs/nodejs-ipfs-state-persistence.ts
+var KEY_PREFIX = "sphere_ipfs_";
+function seqKey(ipnsName) {
+  return `${KEY_PREFIX}seq_${ipnsName}`;
+}
+function cidKey(ipnsName) {
+  return `${KEY_PREFIX}cid_${ipnsName}`;
+}
+function verKey(ipnsName) {
+  return `${KEY_PREFIX}ver_${ipnsName}`;
+}
+var NodejsIpfsStatePersistence = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  async load(ipnsName) {
+    try {
+      const seq = await this.storage.get(seqKey(ipnsName));
+      if (!seq) return null;
+      const cid = await this.storage.get(cidKey(ipnsName));
+      const ver = await this.storage.get(verKey(ipnsName));
+      return {
+        sequenceNumber: seq,
+        lastCid: cid,
+        version: parseInt(ver ?? "0", 10)
+      };
+    } catch {
+      return null;
+    }
+  }
+  async save(ipnsName, state) {
+    await this.storage.set(seqKey(ipnsName), state.sequenceNumber);
+    if (state.lastCid) {
+      await this.storage.set(cidKey(ipnsName), state.lastCid);
+    } else {
+      await this.storage.remove(cidKey(ipnsName));
+    }
+    await this.storage.set(verKey(ipnsName), String(state.version));
+  }
+  async clear(ipnsName) {
+    await this.storage.remove(seqKey(ipnsName));
+    await this.storage.remove(cidKey(ipnsName));
+    await this.storage.remove(verKey(ipnsName));
+  }
+};
+
+// impl/nodejs/ipfs/index.ts
+function createNodeIpfsStorageProvider(config, storageProvider) {
+  const persistence = storageProvider ? new NodejsIpfsStatePersistence(storageProvider) : void 0;
+  return new IpfsStorageProvider(
+    { ...config, createWebSocket: config?.createWebSocket ?? createNodeWebSocketFactory() },
+    persistence
+  );
+}
+
+// price/CoinGeckoPriceProvider.ts
+var CoinGeckoPriceProvider = class {
+  platform = "coingecko";
+  cache = /* @__PURE__ */ new Map();
+  apiKey;
+  cacheTtlMs;
+  timeout;
+  debug;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config?.apiKey;
+    this.cacheTtlMs = config?.cacheTtlMs ?? 6e4;
+    this.timeout = config?.timeout ?? 1e4;
+    this.debug = config?.debug ?? false;
+    this.baseUrl = config?.baseUrl ?? (this.apiKey ? "https://pro-api.coingecko.com/api/v3" : "https://api.coingecko.com/api/v3");
+  }
+  async getPrices(tokenNames) {
+    if (tokenNames.length === 0) {
+      return /* @__PURE__ */ new Map();
+    }
+    const now = Date.now();
+    const result = /* @__PURE__ */ new Map();
+    const uncachedNames = [];
+    for (const name of tokenNames) {
+      const cached = this.cache.get(name);
+      if (cached && cached.expiresAt > now) {
+        if (cached.price !== null) {
+          result.set(name, cached.price);
+        }
+      } else {
+        uncachedNames.push(name);
+      }
+    }
+    if (uncachedNames.length === 0) {
+      return result;
+    }
+    try {
+      const ids = uncachedNames.join(",");
+      const url = `${this.baseUrl}/simple/price?ids=${encodeURIComponent(ids)}&vs_currencies=usd,eur&include_24hr_change=true`;
+      const headers = { Accept: "application/json" };
+      if (this.apiKey) {
+        headers["x-cg-pro-api-key"] = this.apiKey;
+      }
+      if (this.debug) {
+        console.log(`[CoinGecko] Fetching prices for: ${uncachedNames.join(", ")}`);
+      }
+      const response = await fetch(url, {
+        headers,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+      if (!response.ok) {
+        throw new Error(`CoinGecko API error: ${response.status} ${response.statusText}`);
+      }
+      const data = await response.json();
+      for (const [name, values] of Object.entries(data)) {
+        if (values && typeof values === "object") {
+          const price = {
+            tokenName: name,
+            priceUsd: values.usd ?? 0,
+            priceEur: values.eur,
+            change24h: values.usd_24h_change,
+            timestamp: now
+          };
+          this.cache.set(name, { price, expiresAt: now + this.cacheTtlMs });
+          result.set(name, price);
+        }
+      }
+      for (const name of uncachedNames) {
+        if (!result.has(name)) {
+          this.cache.set(name, { price: null, expiresAt: now + this.cacheTtlMs });
+        }
+      }
+      if (this.debug) {
+        console.log(`[CoinGecko] Fetched ${result.size} prices`);
+      }
+    } catch (error) {
+      if (this.debug) {
+        console.warn("[CoinGecko] Fetch failed, using stale cache:", error);
+      }
+      for (const name of uncachedNames) {
+        const stale = this.cache.get(name);
+        if (stale?.price) {
+          result.set(name, stale.price);
+        }
+      }
+    }
+    return result;
+  }
+  async getPrice(tokenName) {
+    const prices = await this.getPrices([tokenName]);
+    return prices.get(tokenName) ?? null;
+  }
+  clearCache() {
+    this.cache.clear();
+  }
+};
+
+// price/index.ts
+function createPriceProvider(config) {
+  switch (config.platform) {
+    case "coingecko":
+      return new CoinGeckoPriceProvider(config);
+    default:
+      throw new Error(`Unsupported price platform: ${String(config.platform)}`);
+  }
+}
+
+// impl/shared/resolvers.ts
+function getNetworkConfig(network = "mainnet") {
+  return NETWORKS[network];
+}
+function resolveTransportConfig(network, config) {
+  const networkConfig = getNetworkConfig(network);
+  let relays;
+  if (config?.relays) {
+    relays = config.relays;
+  } else {
+    relays = [...networkConfig.nostrRelays];
+    if (config?.additionalRelays) {
+      relays = [...relays, ...config.additionalRelays];
+    }
+  }
+  return {
+    relays,
+    timeout: config?.timeout,
+    autoReconnect: config?.autoReconnect,
+    debug: config?.debug,
+    // Browser-specific
+    reconnectDelay: config?.reconnectDelay,
+    maxReconnectAttempts: config?.maxReconnectAttempts
+  };
+}
+function resolveOracleConfig(network, config) {
+  const networkConfig = getNetworkConfig(network);
+  return {
+    url: config?.url ?? networkConfig.aggregatorUrl,
+    apiKey: config?.apiKey ?? DEFAULT_AGGREGATOR_API_KEY,
+    timeout: config?.timeout,
+    skipVerification: config?.skipVerification,
+    debug: config?.debug,
+    // Node.js-specific
+    trustBasePath: config?.trustBasePath
+  };
+}
+function resolveL1Config(network, config) {
+  if (config === void 0) {
+    return void 0;
+  }
+  const networkConfig = getNetworkConfig(network);
+  return {
+    electrumUrl: config.electrumUrl ?? networkConfig.electrumUrl,
+    defaultFeeRate: config.defaultFeeRate,
+    enableVesting: config.enableVesting
+  };
+}
+function resolvePriceConfig(config) {
+  if (config === void 0) {
+    return void 0;
+  }
+  return {
+    platform: config.platform ?? "coingecko",
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+    cacheTtlMs: config.cacheTtlMs,
+    timeout: config.timeout,
+    debug: config.debug
+  };
+}
+
+// impl/nodejs/index.ts
+function createNodeProviders(config) {
+  const network = config?.network ?? "mainnet";
+  const transportConfig = resolveTransportConfig(network, config?.transport);
+  const oracleConfig = resolveOracleConfig(network, config?.oracle);
+  const l1Config = resolveL1Config(network, config?.l1);
+  const priceConfig = resolvePriceConfig(config?.price);
+  const storage = createFileStorageProvider({
+    dataDir: config?.dataDir ?? "./sphere-data"
+  });
+  const ipfsSync = config?.tokenSync?.ipfs;
+  const ipfsTokenStorage = ipfsSync?.enabled ? createNodeIpfsStorageProvider(ipfsSync.config, storage) : void 0;
+  return {
+    storage,
     tokenStorage: createFileTokenStorageProvider({
       tokensDir: config?.tokensDir ?? "./sphere-tokens"
     }),
@@ -2929,7 +4977,8 @@ function createNodeProviders(config) {
       relays: transportConfig.relays,
       timeout: transportConfig.timeout,
       autoReconnect: transportConfig.autoReconnect,
-      debug: transportConfig.debug
+      debug: transportConfig.debug,
+      storage
     }),
     oracle: createUnicityAggregatorProvider({
       url: oracleConfig.url,
@@ -2941,7 +4990,8 @@ function createNodeProviders(config) {
       network
     }),
     l1: l1Config,
-    price: priceConfig ? createPriceProvider(priceConfig) : void 0
+    price: priceConfig ? createPriceProvider(priceConfig) : void 0,
+    ipfsTokenStorage
   };
 }
 export {