@unicitylabs/sphere-sdk 0.2.3 → 0.2.5

package/dist/impl/browser/ipfs.js

@@ -1,59 +1,63 @@
-// constants.ts
-var STORAGE_KEYS_GLOBAL = {
-  /** Encrypted BIP39 mnemonic */
-  MNEMONIC: "mnemonic",
-  /** Encrypted master private key */
-  MASTER_KEY: "master_key",
-  /** BIP32 chain code */
-  CHAIN_CODE: "chain_code",
-  /** HD derivation path (full path like m/44'/0'/0'/0/0) */
-  DERIVATION_PATH: "derivation_path",
-  /** Base derivation path (like m/44'/0'/0' without chain/index) */
-  BASE_PATH: "base_path",
-  /** Derivation mode: bip32, wif_hmac, legacy_hmac */
-  DERIVATION_MODE: "derivation_mode",
-  /** Wallet source: mnemonic, file, unknown */
-  WALLET_SOURCE: "wallet_source",
-  /** Wallet existence flag */
-  WALLET_EXISTS: "wallet_exists",
-  /** Current active address index */
-  CURRENT_ADDRESS_INDEX: "current_address_index",
-  /** Nametag cache per address (separate from tracked addresses registry) */
-  ADDRESS_NAMETAGS: "address_nametags",
-  /** Active addresses registry (JSON: TrackedAddressesStorage) */
-  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 */
-  PENDING_TRANSFERS: "pending_transfers",
-  /** Transfer outbox for this address */
-  OUTBOX: "outbox",
-  /** Conversations for this address */
-  CONVERSATIONS: "conversations",
-  /** Messages for this address */
-  MESSAGES: "messages",
-  /** Transaction history for this address */
-  TRANSACTION_HISTORY: "transaction_history"
+// 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";
+  }
 };
-var STORAGE_KEYS = {
-  ...STORAGE_KEYS_GLOBAL,
-  ...STORAGE_KEYS_ADDRESS
+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";
+    }
+  }
+  if (status >= 500) {
+    return "GATEWAY_ERROR";
+  }
+  if (status >= 400) {
+    return "GATEWAY_ERROR";
+  }
+  return "GATEWAY_ERROR";
+}
+
+// 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);
+  }
 };
-var DEFAULT_IPFS_GATEWAYS = [
-  "https://ipfs.unicity.network",
-  "https://dweb.link",
-  "https://ipfs.io"
-];
-var DEFAULT_IPFS_BOOTSTRAP_PEERS = [
-  "/dns4/unicity-ipfs2.dyndns.org/tcp/4001/p2p/12D3KooWLNi5NDPPHbrfJakAQqwBqymYTTwMQXQKEWuCrJNDdmfh",
-  "/dns4/unicity-ipfs3.dyndns.org/tcp/4001/p2p/12D3KooWQ4aujVE4ShLjdusNZBdffq3TbzrwT2DuWZY9H1Gxhwn6",
-  "/dns4/unicity-ipfs4.dyndns.org/tcp/4001/p2p/12D3KooWJ1ByPfUzUrpYvgxKU8NZrR8i6PU1tUgMEbQX9Hh2DEn1",
-  "/dns4/unicity-ipfs5.dyndns.org/tcp/4001/p2p/12D3KooWB1MdZZGHN5B8TvWXntbycfe7Cjcz7n6eZ9eykZadvmDv"
-];
-var DEFAULT_BASE_PATH = "m/44'/0'/0'";
-var DEFAULT_DERIVATION_PATH = `${DEFAULT_BASE_PATH}/0/0`;
 
 // node_modules/@noble/hashes/utils.js
 function isBytes(a) {
@@ -491,583 +495,1941 @@ var sha256 = /* @__PURE__ */ createHasher(
   /* @__PURE__ */ oidNist(1)
 );
 
-// impl/browser/storage/IpfsStorageProvider.ts
-var heliaModule = null;
-var heliaJsonModule = null;
-var libp2pBootstrapModule = null;
+// core/crypto.ts
+import * as bip39 from "bip39";
+import CryptoJS from "crypto-js";
+import elliptic from "elliptic";
+var ec = new elliptic.ec("secp256k1");
+var CURVE_ORDER = BigInt(
+  "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141"
+);
+function hexToBytes(hex) {
+  const matches = hex.match(/../g);
+  if (!matches) {
+    return new Uint8Array(0);
+  }
+  return Uint8Array.from(matches.map((x) => parseInt(x, 16)));
+}
+
+// impl/shared/ipfs/ipns-key-derivation.ts
+var IPNS_HKDF_INFO = "ipfs-storage-ed25519-v1";
 var libp2pCryptoModule = null;
 var libp2pPeerIdModule = null;
-var multiformatsCidModule = null;
-async function loadHeliaModules() {
-  if (!heliaModule) {
-    [
-      heliaModule,
-      heliaJsonModule,
-      libp2pBootstrapModule,
-      libp2pCryptoModule,
-      libp2pPeerIdModule,
-      multiformatsCidModule
-    ] = await Promise.all([
-      import("helia"),
-      import("@helia/json"),
-      import("@libp2p/bootstrap"),
+async function loadLibp2pModules() {
+  if (!libp2pCryptoModule) {
+    [libp2pCryptoModule, libp2pPeerIdModule] = await Promise.all([
       import("@libp2p/crypto/keys"),
-      import("@libp2p/peer-id"),
-      import("multiformats/cid")
+      import("@libp2p/peer-id")
     ]);
   }
   return {
-    createHelia: heliaModule.createHelia,
-    json: heliaJsonModule.json,
-    bootstrap: libp2pBootstrapModule.bootstrap,
     generateKeyPairFromSeed: libp2pCryptoModule.generateKeyPairFromSeed,
-    peerIdFromPrivateKey: libp2pPeerIdModule.peerIdFromPrivateKey,
-    CID: multiformatsCidModule.CID
+    peerIdFromPrivateKey: libp2pPeerIdModule.peerIdFromPrivateKey
   };
 }
-var HKDF_INFO = new TextEncoder().encode("ipfs-storage-key");
-var IpfsStorageProvider = class {
-  id = "ipfs";
-  name = "IPFS Storage";
-  type = "p2p";
-  description = "Decentralized storage via IPFS/IPNS";
-  config;
-  identity = null;
-  status = "disconnected";
-  ipnsName = null;
-  lastCid = null;
-  eventCallbacks = /* @__PURE__ */ new Set();
-  // Helia instance for browser-based IPFS
-  helia = null;
-  heliaJson = null;
-  ipnsKeyPair = null;
-  /** Get the last published CID */
-  getLastCid() {
-    return this.lastCid;
-  }
-  // Local cache for faster loads
-  localCache = null;
-  cacheTimestamp = 0;
-  constructor(config) {
-    this.config = {
-      gateways: config?.gateways ?? [...DEFAULT_IPFS_GATEWAYS],
-      bootstrapPeers: config?.bootstrapPeers ?? [...DEFAULT_IPFS_BOOTSTRAP_PEERS],
-      enableIpns: config?.enableIpns ?? true,
-      ipnsTimeout: config?.ipnsTimeout ?? 3e4,
-      fetchTimeout: config?.fetchTimeout ?? 15e3,
-      debug: config?.debug ?? false
+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 {
+    keyPair,
+    ipnsName: peerId.toString()
+  };
+}
+
+// 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
     };
   }
-  // ===========================================================================
-  // BaseProvider Implementation
-  // ===========================================================================
-  async connect() {
-    if (this.status === "connected") return;
-    this.status = "connecting";
+  return ipnsModule;
+}
+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 {
-      await this.testGatewayConnectivity();
-      await this.initializeHelia();
-      this.status = "connected";
-      this.log("Connected to IPFS gateways and Helia initialized");
-    } catch (error) {
-      this.status = "error";
-      throw new Error(`IPFS connection failed: ${error}`);
+      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 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/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;
   }
   /**
-   * Initialize Helia browser IPFS node
+   * Get cached IPNS record ignoring TTL (for known-fresh optimization).
    */
-  async initializeHelia() {
-    if (this.helia) return;
-    try {
-      this.log("Initializing Helia with bootstrap peers...");
-      const { createHelia, json, bootstrap } = await loadHeliaModules();
-      this.helia = await createHelia({
-        libp2p: {
-          peerDiscovery: [
-            bootstrap({ list: this.config.bootstrapPeers })
-          ],
-          connectionManager: {
-            maxConnections: 10
-          }
-        }
-      });
-      this.heliaJson = json(this.helia);
-      const peerId = this.helia.libp2p.peerId.toString();
-      this.log("Helia initialized, browser peer ID:", peerId.slice(0, 20) + "...");
-      setTimeout(() => {
-        const connections = this.helia?.libp2p.getConnections() || [];
-        this.log(`Active Helia connections: ${connections.length}`);
-      }, 3e3);
-    } catch (error) {
-      this.log("Helia initialization failed (will use HTTP only):", error);
-    }
+  getIpnsRecordIgnoreTtl(ipnsName) {
+    const entry = this.ipnsRecords.get(ipnsName);
+    return entry?.data ?? null;
   }
-  async disconnect() {
-    if (this.helia) {
-      try {
-        await this.helia.stop();
-      } catch (error) {
-        this.log("Error stopping Helia:", error);
-      }
-      this.helia = null;
-      this.heliaJson = null;
-    }
-    this.status = "disconnected";
-    this.localCache = null;
-    this.ipnsKeyPair = null;
-    this.log("Disconnected from IPFS");
+  setIpnsRecord(ipnsName, result) {
+    this.ipnsRecords.set(ipnsName, {
+      data: result,
+      timestamp: Date.now()
+    });
   }
-  isConnected() {
-    return this.status === "connected";
+  invalidateIpns(ipnsName) {
+    this.ipnsRecords.delete(ipnsName);
   }
-  getStatus() {
-    return this.status;
+  // ---------------------------------------------------------------------------
+  // Content Cache (infinite TTL - content is immutable by CID)
+  // ---------------------------------------------------------------------------
+  getContent(cid) {
+    const entry = this.content.get(cid);
+    return entry?.data ?? null;
   }
-  // ===========================================================================
-  // TokenStorageProvider Implementation
-  // ===========================================================================
-  async setIdentity(identity) {
-    this.identity = identity;
-    try {
-      const { generateKeyPairFromSeed, peerIdFromPrivateKey } = await loadHeliaModules();
-      const walletSecret = this.hexToBytes(identity.privateKey);
-      const derivedKey = hkdf(sha256, walletSecret, void 0, HKDF_INFO, 32);
-      this.ipnsKeyPair = await generateKeyPairFromSeed("Ed25519", derivedKey);
-      const peerId = peerIdFromPrivateKey(this.ipnsKeyPair);
-      this.ipnsName = peerId.toString();
-      this.log("Identity set, IPNS name:", this.ipnsName);
-    } catch {
-      this.ipnsName = identity.ipnsName ?? this.deriveIpnsNameSimple(identity.privateKey);
-      this.log("Identity set with fallback IPNS name:", this.ipnsName);
-    }
+  setContent(cid, data) {
+    this.content.set(cid, {
+      data,
+      timestamp: Date.now()
+    });
   }
-  async initialize() {
-    if (!this.identity) {
-      throw new Error("Identity must be set before initialization");
+  // ---------------------------------------------------------------------------
+  // 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;
     }
-    try {
-      await this.connect();
-      return true;
-    } catch {
+    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;
   }
-  async shutdown() {
-    await this.disconnect();
+  // ---------------------------------------------------------------------------
+  // Cache Management
+  // ---------------------------------------------------------------------------
+  clear() {
+    this.ipnsRecords.clear();
+    this.content.clear();
+    this.gatewayFailures.clear();
+    this.knownFreshTimestamps.clear();
   }
-  async save(data) {
-    this.ensureReady();
-    this.emitEvent({ type: "storage:saving", timestamp: Date.now() });
+};
+
+// 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 dataToSave = {
-        ...data,
-        _meta: {
-          ...data._meta,
-          updatedAt: Date.now(),
-          ipnsName: this.ipnsName ?? void 0
-        }
-      };
-      const cid = await this.publishToGateways(dataToSave);
-      if (this.config.enableIpns && this.ipnsName) {
-        await this.publishIpns(cid);
+      const response = await this.fetchWithTimeout(
+        `${gateway}/api/v0/version`,
+        this.connectivityTimeoutMs,
+        { method: "POST" }
+      );
+      if (!response.ok) {
+        return { gateway, healthy: false, error: `HTTP ${response.status}` };
       }
-      this.localCache = dataToSave;
-      this.cacheTimestamp = Date.now();
-      this.lastCid = cid;
-      this.emitEvent({ type: "storage:saved", timestamp: Date.now(), data: { cid } });
       return {
-        success: true,
-        cid,
-        timestamp: Date.now()
+        gateway,
+        healthy: true,
+        responseTimeMs: Date.now() - start
       };
     } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      this.emitEvent({ type: "storage:error", timestamp: Date.now(), error: errorMsg });
       return {
-        success: false,
-        error: errorMsg,
-        timestamp: Date.now()
+        gateway,
+        healthy: false,
+        error: error instanceof Error ? error.message : String(error)
       };
     }
   }
-  async load(identifier) {
-    this.ensureReady();
-    this.emitEvent({ type: "storage:loading", timestamp: Date.now() });
-    try {
-      const cacheAge = Date.now() - this.cacheTimestamp;
-      if (this.localCache && cacheAge < 6e4) {
-        this.log("Returning cached data");
-        return {
-          success: true,
-          data: this.localCache,
-          source: "cache",
-          timestamp: Date.now()
-        };
+  /**
+   * 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;
       }
-      let cid = identifier ?? null;
-      if (!cid && this.config.enableIpns && this.ipnsName) {
-        cid = await this.resolveIpns(this.ipnsName);
+    });
+    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"
+        );
       }
-      if (!cid) {
-        return {
-          success: true,
-          data: void 0,
-          source: "remote",
-          timestamp: Date.now()
-        };
+      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;
       }
-      const data = await this.fetchFromGateways(cid);
-      this.localCache = data;
-      this.cacheTimestamp = Date.now();
-      this.lastCid = cid;
-      this.emitEvent({ type: "storage:loaded", timestamp: Date.now() });
-      return {
-        success: true,
-        data,
-        source: "remote",
-        timestamp: Date.now()
-      };
+    });
+    try {
+      return await Promise.any(promises);
     } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      this.emitEvent({ type: "storage:error", timestamp: Date.now(), error: errorMsg });
-      if (this.localCache) {
-        return {
-          success: true,
-          data: this.localCache,
-          source: "cache",
-          timestamp: Date.now()
-        };
+      if (error instanceof AggregateError) {
+        throw new IpfsError(
+          `Fetch failed on all gateways for CID=${cid}`,
+          "NETWORK_ERROR"
+        );
       }
-      return {
-        success: false,
-        error: errorMsg,
-        source: "remote",
-        timestamp: Date.now()
-      };
+      throw error;
     }
   }
-  async sync(localData) {
-    this.ensureReady();
-    this.emitEvent({ type: "sync:started", timestamp: Date.now() });
+  // ---------------------------------------------------------------------------
+  // 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 remoteResult = await this.load();
-      const remoteData = remoteResult.data;
-      if (!remoteData) {
-        await this.save(localData);
-        this.emitEvent({ type: "sync:completed", timestamp: Date.now() });
-        return {
-          success: true,
-          merged: localData,
-          added: 0,
-          removed: 0,
-          conflicts: 0
-        };
+      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 mergeResult = this.mergeData(localData, remoteData);
-      await this.save(mergeResult.merged);
-      this.emitEvent({ type: "sync:completed", timestamp: Date.now() });
+      const text = await response.text();
+      const parsed = await parseRoutingApiResponse(text);
+      if (!parsed) return null;
+      this.cache.recordGatewaySuccess(gateway);
       return {
-        success: true,
-        merged: mergeResult.merged,
-        added: mergeResult.added,
-        removed: mergeResult.removed,
-        conflicts: mergeResult.conflicts
+        cid: parsed.cid,
+        sequence: parsed.sequence,
+        gateway,
+        recordData: parsed.recordData
       };
     } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      this.emitEvent({ type: "sync:error", timestamp: Date.now(), error: errorMsg });
-      return {
-        success: false,
-        added: 0,
-        removed: 0,
-        conflicts: 0,
-        error: errorMsg
-      };
+      if (error instanceof IpfsError) throw error;
+      const category = classifyFetchError(error);
+      if (category !== "NOT_FOUND") {
+        this.cache.recordGatewayFailure(gateway);
+      }
+      return null;
     }
   }
-  async exists() {
-    if (!this.ipnsName) return false;
+  /**
+   * 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 cid = await this.resolveIpns(this.ipnsName);
-      return cid !== null;
+      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 false;
-    }
-  }
-  async clear() {
-    const emptyData = {
-      _meta: {
-        version: 0,
-        address: this.identity?.l1Address ?? "",
-        formatVersion: "2.0",
-        updatedAt: Date.now()
-      },
-      _tombstones: []
-    };
-    const result = await this.save(emptyData);
-    return result.success;
-  }
-  onEvent(callback) {
-    this.eventCallbacks.add(callback);
-    return () => this.eventCallbacks.delete(callback);
-  }
-  // ===========================================================================
-  // Private: IPFS Operations
-  // ===========================================================================
-  async testGatewayConnectivity() {
-    const gateway = this.config.gateways[0];
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 5e3);
-    try {
-      const response = await fetch(`${gateway}/api/v0/version`, {
-        method: "POST",
-        signal: controller.signal
-      });
-      if (!response.ok) throw new Error("Gateway not responding");
-    } finally {
-      clearTimeout(timeout);
+      return null;
     }
   }
-  async publishToGateways(data) {
-    const content = JSON.stringify(data);
-    const blob = new Blob([content], { type: "application/json" });
-    const promises = [];
-    for (const gateway of this.config.gateways) {
-      promises.push(this.publishToGateway(gateway, blob));
+  /**
+   * 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 };
     }
-    if (this.heliaJson) {
-      promises.push(this.publishToHelia(data));
+    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;
+      }
     }
-    try {
-      const cid = await Promise.any(promises);
-      this.log("Published to IPFS, CID:", cid);
-      return cid;
-    } catch {
-      throw new Error("All publish attempts failed");
+    if (best) {
+      this.cache.setIpnsRecord(ipnsName, best);
     }
+    return {
+      best,
+      allResults: results,
+      respondedCount,
+      totalGateways: targets.length
+    };
   }
+  // ---------------------------------------------------------------------------
+  // IPNS Publishing
+  // ---------------------------------------------------------------------------
   /**
-   * Publish data via Helia (browser DHT)
+   * Publish IPNS record to a single gateway via routing API.
    */
-  async publishToHelia(data) {
-    if (!this.heliaJson) {
-      throw new Error("Helia not initialized");
-    }
-    const cid = await this.heliaJson.add(data);
-    this.log("Published via Helia, CID:", cid.toString());
-    return cid.toString();
-  }
-  async publishToGateway(gateway, blob) {
-    const formData = new FormData();
-    formData.append("file", blob);
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.config.fetchTimeout);
+  async publishIpnsViaRoutingApi(gateway, ipnsName, marshalledRecord, timeoutMs = DEFAULT_PUBLISH_TIMEOUT_MS) {
     try {
-      const response = await fetch(`${gateway}/api/v0/add?pin=true`, {
-        method: "POST",
-        body: formData,
-        signal: controller.signal
-      });
+      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) {
-        throw new Error(`Gateway ${gateway} returned ${response.status}`);
+        const errorText = await response.text().catch(() => "");
+        throw new IpfsError(
+          `IPNS publish: HTTP ${response.status}: ${errorText.slice(0, 100)}`,
+          classifyHttpStatus(response.status, errorText),
+          gateway
+        );
       }
-      const result = await response.json();
-      return result.Hash;
-    } finally {
-      clearTimeout(timeout);
+      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;
     }
   }
-  async publishIpns(cid) {
-    if (!this.identity) return;
-    const promises = this.config.gateways.map(
-      (gateway) => this.publishIpnsToGateway(gateway, cid).catch(() => null)
+  /**
+   * 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))
     );
-    await Promise.allSettled(promises);
-    this.log("Published IPNS:", this.ipnsName, "->", cid);
+    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
+    };
   }
-  async publishIpnsToGateway(gateway, cid) {
+  // ---------------------------------------------------------------------------
+  // 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 timeout = setTimeout(() => controller.abort(), this.config.ipnsTimeout);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      const response = await fetch(
-        `${gateway}/api/v0/name/publish?arg=${cid}&key=${this.ipnsName}`,
-        {
-          method: "POST",
-          signal: controller.signal
+      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());
+}
+
+// transport/websocket.ts
+var WebSocketReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3
+};
+
+// 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();
+          }
         }
-      );
-      if (!response.ok) {
-        throw new Error(`IPNS publish failed: ${response.status}`);
       }
-    } finally {
-      clearTimeout(timeout);
+    };
+  }
+  /**
+   * 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("*");
+        }
+      }
+    };
   }
-  async resolveIpns(name) {
-    for (const gateway of this.config.gateways) {
-      try {
-        return await this.resolveIpnsFromGateway(gateway, name);
-      } catch {
-        continue;
+  /**
+   * 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");
     }
-    return null;
   }
-  async resolveIpnsFromGateway(gateway, name) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.config.fetchTimeout);
+  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);
+      }
+    }
+  }
+};
+
+// constants.ts
+var STORAGE_KEYS_GLOBAL = {
+  /** Encrypted BIP39 mnemonic */
+  MNEMONIC: "mnemonic",
+  /** Encrypted master private key */
+  MASTER_KEY: "master_key",
+  /** BIP32 chain code */
+  CHAIN_CODE: "chain_code",
+  /** HD derivation path (full path like m/44'/0'/0'/0/0) */
+  DERIVATION_PATH: "derivation_path",
+  /** Base derivation path (like m/44'/0'/0' without chain/index) */
+  BASE_PATH: "base_path",
+  /** Derivation mode: bip32, wif_hmac, legacy_hmac */
+  DERIVATION_MODE: "derivation_mode",
+  /** Wallet source: mnemonic, file, unknown */
+  WALLET_SOURCE: "wallet_source",
+  /** Wallet existence flag */
+  WALLET_EXISTS: "wallet_exists",
+  /** Current active address index */
+  CURRENT_ADDRESS_INDEX: "current_address_index",
+  /** Nametag cache per address (separate from tracked addresses registry) */
+  ADDRESS_NAMETAGS: "address_nametags",
+  /** Active addresses registry (JSON: TrackedAddressesStorage) */
+  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 */
+  PENDING_TRANSFERS: "pending_transfers",
+  /** Transfer outbox for this address */
+  OUTBOX: "outbox",
+  /** Conversations for this address */
+  CONVERSATIONS: "conversations",
+  /** Messages for this address */
+  MESSAGES: "messages",
+  /** Transaction history for this address */
+  TRANSACTION_HISTORY: "transaction_history",
+  /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
+  PENDING_V5_TOKENS: "pending_v5_tokens"
+};
+var STORAGE_KEYS = {
+  ...STORAGE_KEYS_GLOBAL,
+  ...STORAGE_KEYS_ADDRESS
+};
+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`;
+
+// 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 response = await fetch(`${gateway}/api/v0/name/resolve?arg=${name}`, {
-        method: "POST",
-        signal: controller.signal
+      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(() => {
       });
-      if (!response.ok) {
-        throw new Error(`IPNS resolve failed: ${response.status}`);
+      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)");
+        }
       }
-      const result = await response.json();
-      return result.Path.replace("/ipfs/", "");
-    } finally {
-      clearTimeout(timeout);
+    });
+    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() };
   }
-  async fetchFromGateways(cid) {
-    const promises = [];
-    for (const gateway of this.config.gateways) {
-      promises.push(this.fetchFromGateway(gateway, cid));
+  // ---------------------------------------------------------------------------
+  // 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() };
     }
-    if (this.heliaJson) {
-      promises.push(this.fetchFromHelia(cid));
+    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() };
     }
-    return Promise.any(promises);
+  }
+  // ---------------------------------------------------------------------------
+  // 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);
   }
   /**
-   * Fetch content via Helia (browser DHT)
+   * Execute a flush of the pending buffer to IPFS.
+   * Runs inside AsyncSerialQueue for concurrency safety.
    */
-  async fetchFromHelia(cidString) {
-    if (!this.heliaJson) {
-      throw new Error("Helia not initialized");
+  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;
     }
-    const { CID } = await loadHeliaModules();
-    const cid = CID.parse(cidString);
-    const data = await this.heliaJson.get(cid);
-    this.log("Fetched via Helia, CID:", cidString);
-    return data;
   }
-  async fetchFromGateway(gateway, cid) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.config.fetchTimeout);
+  // ---------------------------------------------------------------------------
+  // 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 {
-      const response = await fetch(`${gateway}/ipfs/${cid}`, {
-        signal: controller.signal
+      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() }
       });
-      if (!response.ok) {
-        throw new Error(`Fetch failed: ${response.status}`);
+      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() };
+          }
+        }
       }
-      return response.json();
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-  // ===========================================================================
-  // Private: Merge Logic
-  // ===========================================================================
-  mergeData(local, remote) {
-    const localVersion = local._meta?.version ?? 0;
-    const remoteVersion = remote._meta?.version ?? 0;
-    const baseMeta = remoteVersion > localVersion ? remote._meta : local._meta;
-    const tombstones = /* @__PURE__ */ new Map();
-    for (const t of local._tombstones ?? []) {
-      tombstones.set(t.tokenId, t);
-    }
-    for (const t of remote._tombstones ?? []) {
-      const existing = tombstones.get(t.tokenId);
-      if (!existing || t.timestamp > existing.timestamp) {
-        tombstones.set(t.tokenId, t);
+      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 merged = {
+    const emptyData = {
       _meta: {
-        ...baseMeta,
-        version: Math.max(localVersion, remoteVersion) + 1,
+        version: 0,
+        address: this.identity?.directAddress ?? "",
+        ipnsName: this.ipnsName,
+        formatVersion: "2.0",
         updatedAt: Date.now()
-      },
-      _tombstones: Array.from(tombstones.values())
-    };
-    let added = 0;
-    let conflicts = 0;
-    const processedKeys = /* @__PURE__ */ new Set();
-    for (const key of Object.keys(local)) {
-      if (!key.startsWith("_") || key === "_meta" || key === "_tombstones") continue;
-      processedKeys.add(key);
-      const tokenId = key.slice(1);
-      if (tombstones.has(tokenId)) continue;
-      const localToken = local[key];
-      const remoteToken = remote[key];
-      if (remoteToken) {
-        conflicts++;
-        merged[key] = localToken;
-      } else {
-        merged[key] = localToken;
       }
+    };
+    const result = await this._doSave(emptyData);
+    if (result.success) {
+      this.cache.clear();
+      this.tokenBuffer.clear();
+      this.deletedTokenIds.clear();
+      await this.statePersistence.clear(this.ipnsName);
     }
-    for (const key of Object.keys(remote)) {
-      if (!key.startsWith("_") || key === "_meta" || key === "_tombstones") continue;
-      if (processedKeys.has(key)) continue;
-      const tokenId = key.slice(1);
-      if (tombstones.has(tokenId)) continue;
-      merged[key] = remote[key];
-      added++;
-    }
-    return { merged, added, removed: 0, conflicts };
+    return result.success;
   }
-  // ===========================================================================
-  // Private: Helpers
-  // ===========================================================================
-  ensureReady() {
-    if (this.status !== "connected") {
-      throw new Error("IpfsStorageProvider not connected");
-    }
-    if (!this.identity) {
-      throw new Error("Identity not set");
+  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
+  // ---------------------------------------------------------------------------
   /**
-   * Simple IPNS name derivation (fallback when libp2p is unavailable)
+   * Derive WebSocket URL from the first configured gateway.
+   * Converts https://host → wss://host/ws/ipns
    */
-  deriveIpnsNameSimple(privateKey) {
-    return `12D3KooW${privateKey.slice(0, 40)}`;
+  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`;
   }
   /**
-   * Convert hex string to Uint8Array
+   * Poll for remote IPNS changes (fallback when WS is unavailable).
+   * Compares remote sequence number with last known and emits event if changed.
    */
-  hexToBytes(hex) {
-    const bytes = new Uint8Array(hex.length / 2);
-    for (let i = 0; i < bytes.length; i++) {
-      bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+  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 {
     }
-    return bytes;
   }
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
   emitEvent(event) {
     for (const callback of this.eventCallbacks) {
       try {
         callback(event);
-      } catch (error) {
-        console.error("[IpfsStorageProvider] Event callback error:", error);
+      } 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/browser/ipfs/browser-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 BrowserIpfsStatePersistence = class {
+  async load(ipnsName) {
+    try {
+      const seq = localStorage.getItem(seqKey(ipnsName));
+      if (!seq) return null;
+      return {
+        sequenceNumber: seq,
+        lastCid: localStorage.getItem(cidKey(ipnsName)),
+        version: parseInt(localStorage.getItem(verKey(ipnsName)) ?? "0", 10)
+      };
+    } catch {
+      return null;
+    }
+  }
+  async save(ipnsName, state) {
+    try {
+      localStorage.setItem(seqKey(ipnsName), state.sequenceNumber);
+      if (state.lastCid) {
+        localStorage.setItem(cidKey(ipnsName), state.lastCid);
+      } else {
+        localStorage.removeItem(cidKey(ipnsName));
       }
+      localStorage.setItem(verKey(ipnsName), String(state.version));
+    } catch {
     }
   }
-  log(...args) {
-    if (this.config.debug) {
-      console.log("[IpfsStorageProvider]", ...args);
+  async clear(ipnsName) {
+    try {
+      localStorage.removeItem(seqKey(ipnsName));
+      localStorage.removeItem(cidKey(ipnsName));
+      localStorage.removeItem(verKey(ipnsName));
+    } catch {
     }
   }
 };
-function createIpfsStorageProvider(config) {
-  return new IpfsStorageProvider(config);
+
+// impl/browser/ipfs/index.ts
+function createBrowserWebSocket(url) {
+  return new WebSocket(url);
+}
+function createBrowserIpfsStorageProvider(config) {
+  return new IpfsStorageProvider(
+    { ...config, createWebSocket: config?.createWebSocket ?? createBrowserWebSocket },
+    new BrowserIpfsStatePersistence()
+  );
 }
+var createIpfsStorageProvider = createBrowserIpfsStorageProvider;
 export {
+  BrowserIpfsStatePersistence,
   IpfsStorageProvider,
+  createBrowserIpfsStorageProvider,
   createIpfsStorageProvider
 };
 /*! Bundled license information: