@unicitylabs/sphere-sdk 0.5.3 → 0.5.5

package/dist/impl/browser/index.cjs

@@ -61,6 +61,110 @@ __export(browser_exports, {
 module.exports = __toCommonJS(browser_exports);
 var import_buffer2 = require("buffer");
 
+// core/logger.ts
+var LOGGER_KEY = "__sphere_sdk_logger__";
+function getState() {
+  const g = globalThis;
+  if (!g[LOGGER_KEY]) {
+    g[LOGGER_KEY] = { debug: false, tags: {}, handler: null };
+  }
+  return g[LOGGER_KEY];
+}
+function isEnabled(tag) {
+  const state = getState();
+  if (tag in state.tags) return state.tags[tag];
+  return state.debug;
+}
+var logger = {
+  /**
+   * Configure the logger. Can be called multiple times (last write wins).
+   * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
+   */
+  configure(config) {
+    const state = getState();
+    if (config.debug !== void 0) state.debug = config.debug;
+    if (config.handler !== void 0) state.handler = config.handler;
+  },
+  /**
+   * Enable/disable debug logging for a specific tag.
+   * Per-tag setting overrides the global debug flag.
+   *
+   * @example
+   * ```ts
+   * logger.setTagDebug('Nostr', true);  // enable only Nostr logs
+   * logger.setTagDebug('Nostr', false); // disable Nostr logs even if global debug=true
+   * ```
+   */
+  setTagDebug(tag, enabled) {
+    getState().tags[tag] = enabled;
+  },
+  /**
+   * Clear per-tag override, falling back to global debug flag.
+   */
+  clearTagDebug(tag) {
+    delete getState().tags[tag];
+  },
+  /** Returns true if debug mode is enabled for the given tag (or globally). */
+  isDebugEnabled(tag) {
+    if (tag) return isEnabled(tag);
+    return getState().debug;
+  },
+  /**
+   * Debug-level log. Only shown when debug is enabled (globally or for this tag).
+   * Use for detailed operational information.
+   */
+  debug(tag, message, ...args) {
+    if (!isEnabled(tag)) return;
+    const state = getState();
+    if (state.handler) {
+      state.handler("debug", tag, message, ...args);
+    } else {
+      console.log(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Warning-level log. ALWAYS shown regardless of debug flag.
+   * Use for important but non-critical issues (timeouts, retries, degraded state).
+   */
+  warn(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("warn", tag, message, ...args);
+    } else {
+      console.warn(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Error-level log. ALWAYS shown regardless of debug flag.
+   * Use for critical failures that should never be silenced.
+   */
+  error(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("error", tag, message, ...args);
+    } else {
+      console.error(`[${tag}]`, message, ...args);
+    }
+  },
+  /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
+  reset() {
+    const g = globalThis;
+    delete g[LOGGER_KEY];
+  }
+};
+
+// core/errors.ts
+var SphereError = class extends Error {
+  code;
+  cause;
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "SphereError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+
 // constants.ts
 var STORAGE_KEYS_GLOBAL = {
   /** Encrypted BIP39 mnemonic */
@@ -265,7 +369,7 @@ var LocalStorageProvider = class {
       this.log("Connected to localStorage");
     } catch (error) {
       this.status = "error";
-      throw new Error(`LocalStorage not available: ${error}`);
+      throw new SphereError(`LocalStorage not available: ${error}`, "STORAGE_ERROR");
     }
   }
   async disconnect() {
@@ -372,7 +476,7 @@ var LocalStorageProvider = class {
   }
   ensureConnected() {
     if (this.status !== "connected") {
-      throw new Error("LocalStorageProvider not connected");
+      throw new SphereError("LocalStorageProvider not connected", "STORAGE_ERROR");
     }
   }
   getStorageSafe() {
@@ -381,10 +485,8 @@ var LocalStorageProvider = class {
     }
     return createInMemoryStorage();
   }
-  log(...args) {
-    if (this.config.debug) {
-      console.log("[LocalStorageProvider]", ...args);
-    }
+  log(message, ...args) {
+    logger.debug("LocalStorage", message, ...args);
   }
 };
 function createInMemoryStorage() {
@@ -445,7 +547,7 @@ var IndexedDBStorageProvider = class {
     for (let attempt = 0; attempt < 2; attempt++) {
       this.status = "connecting";
       const t0 = Date.now();
-      console.log(`[IndexedDBStorage] connect: opening db=${this.dbName}, attempt=${attempt + 1}/2`);
+      logger.debug("IndexedDB", ` connect: opening db=${this.dbName}, attempt=${attempt + 1}/2`);
       try {
         this.db = await Promise.race([
           this.openDatabase(),
@@ -454,23 +556,23 @@ var IndexedDBStorageProvider = class {
           )
         ]);
         this.status = "connected";
-        console.log(`[IndexedDBStorage] connect: connected db=${this.dbName} connId=${this.connId} (${Date.now() - t0}ms)`);
+        logger.debug("IndexedDB", ` connect: connected db=${this.dbName} connId=${this.connId} (${Date.now() - t0}ms)`);
         return;
       } catch (error) {
-        console.warn(`[IndexedDBStorage] connect: open failed db=${this.dbName} attempt=${attempt + 1} (${Date.now() - t0}ms):`, error);
+        logger.warn("IndexedDB", ` connect: open failed db=${this.dbName} attempt=${attempt + 1} (${Date.now() - t0}ms):`, error);
         if (attempt === 0) {
           this.status = "disconnected";
           await new Promise((r) => setTimeout(r, 1e3));
           continue;
         }
         this.status = "error";
-        throw new Error(`IndexedDB not available: ${error}`);
+        throw new SphereError(`IndexedDB not available: ${error}`, "STORAGE_ERROR");
       }
     }
   }
   async disconnect() {
     const cid = this.connId;
-    console.log(`[IndexedDBStorage] disconnect: db=${this.dbName} connId=${cid} wasConnected=${!!this.db}`);
+    logger.debug("IndexedDB", ` disconnect: db=${this.dbName} connId=${cid} wasConnected=${!!this.db}`);
     if (this.db) {
       this.db.close();
       this.db = null;
@@ -529,15 +631,15 @@ var IndexedDBStorageProvider = class {
     if (!prefix) {
       const t0 = Date.now();
       const prevConnId = this.connId;
-      console.log(`[IndexedDBStorage] clear: starting db=${this.dbName} connId=${prevConnId} status=${this.status} hasDb=${!!this.db}`);
+      logger.debug("IndexedDB", ` clear: starting db=${this.dbName} connId=${prevConnId} status=${this.status} hasDb=${!!this.db}`);
       try {
         if (!this.db || this.status !== "connected") {
           if (this.db) {
-            console.log(`[IndexedDBStorage] clear: closing stale handle connId=${prevConnId}`);
+            logger.debug("IndexedDB", ` clear: closing stale handle connId=${prevConnId}`);
             this.db.close();
             this.db = null;
           }
-          console.log(`[IndexedDBStorage] clear: opening fresh connection for wipe`);
+          logger.debug("IndexedDB", ` clear: opening fresh connection for wipe`);
           this.db = await Promise.race([
             this.openDatabase(),
             new Promise(
@@ -547,9 +649,9 @@ var IndexedDBStorageProvider = class {
           this.status = "connected";
         }
         await this.idbClear();
-        console.log(`[IndexedDBStorage] clear: store cleared db=${this.dbName} connId=${this.connId} (${Date.now() - t0}ms)`);
+        logger.debug("IndexedDB", ` clear: store cleared db=${this.dbName} connId=${this.connId} (${Date.now() - t0}ms)`);
       } catch (err) {
-        console.warn(`[IndexedDBStorage] clear: failed db=${this.dbName} (${Date.now() - t0}ms)`, err);
+        logger.warn("IndexedDB", ` clear: failed db=${this.dbName} (${Date.now() - t0}ms)`, err);
       } finally {
         if (this.db) {
           this.db.close();
@@ -612,7 +714,7 @@ var IndexedDBStorageProvider = class {
   }
   ensureConnected() {
     if (this.status !== "connected" || !this.db) {
-      throw new Error("IndexedDBStorageProvider not connected");
+      throw new SphereError("IndexedDBStorageProvider not connected", "STORAGE_ERROR");
     }
   }
   // ===========================================================================
@@ -627,7 +729,7 @@ var IndexedDBStorageProvider = class {
         const cid = ++connectionSeq;
         this.connId = cid;
         db.onversionchange = () => {
-          console.log(`[IndexedDBStorage] onversionchange: auto-closing db=${this.dbName} connId=${cid}`);
+          logger.debug("IndexedDB", ` onversionchange: auto-closing db=${this.dbName} connId=${cid}`);
           db.close();
           if (this.db === db) {
             this.db = null;
@@ -637,7 +739,7 @@ var IndexedDBStorageProvider = class {
         resolve(db);
       };
       request.onblocked = () => {
-        console.warn(`[IndexedDBStorage] open blocked by another connection, db=${this.dbName}`);
+        logger.warn("IndexedDB", ` open blocked by another connection, db=${this.dbName}`);
       };
       request.onupgradeneeded = (event) => {
         const db = event.target.result;
@@ -701,10 +803,8 @@ var IndexedDBStorageProvider = class {
       request.onsuccess = () => resolve();
     });
   }
-  log(...args) {
-    if (this.debug) {
-      console.log("[IndexedDBStorageProvider]", ...args);
-    }
+  log(message, ...args) {
+    logger.debug("IndexedDB", message, ...args);
   }
 };
 function createIndexedDBStorageProvider(config) {
@@ -741,31 +841,31 @@ var IndexedDBTokenStorageProvider = class {
       const addressId = getAddressId(identity.directAddress);
       this.dbName = `${this.dbNamePrefix}-${addressId}`;
     }
-    console.log(`[IndexedDBTokenStorage] setIdentity: db=${this.dbName}`);
+    logger.debug("IndexedDBToken", `setIdentity: db=${this.dbName}`);
   }
   async initialize() {
     const prevConnId = this.connId;
     const t0 = Date.now();
     try {
       if (this.db) {
-        console.log(`[IndexedDBTokenStorage] initialize: closing existing connId=${prevConnId} before re-open (db=${this.dbName})`);
+        logger.debug("IndexedDBToken", `initialize: closing existing connId=${prevConnId} before re-open (db=${this.dbName})`);
         this.db.close();
         this.db = null;
       }
-      console.log(`[IndexedDBTokenStorage] initialize: opening db=${this.dbName}`);
+      logger.debug("IndexedDBToken", `initialize: opening db=${this.dbName}`);
       this.db = await this.openDatabase();
       this.status = "connected";
-      console.log(`[IndexedDBTokenStorage] initialize: connected db=${this.dbName} connId=${this.connId} (${Date.now() - t0}ms)`);
+      logger.debug("IndexedDBToken", `initialize: connected db=${this.dbName} connId=${this.connId} (${Date.now() - t0}ms)`);
       return true;
     } catch (error) {
-      console.error(`[IndexedDBTokenStorage] initialize: failed db=${this.dbName} (${Date.now() - t0}ms):`, error);
+      logger.error("IndexedDBToken", `initialize: failed db=${this.dbName} (${Date.now() - t0}ms):`, error);
       this.status = "error";
       return false;
     }
   }
   async shutdown() {
     const cid = this.connId;
-    console.log(`[IndexedDBTokenStorage] shutdown: db=${this.dbName} connId=${cid} wasConnected=${!!this.db}`);
+    logger.debug("IndexedDBToken", `shutdown: db=${this.dbName} connId=${cid} wasConnected=${!!this.db}`);
     if (this.db) {
       this.db.close();
       this.db = null;
@@ -786,7 +886,7 @@ var IndexedDBTokenStorageProvider = class {
   }
   async load() {
     if (!this.db) {
-      console.warn(`[IndexedDBTokenStorage] load: db not initialized (db=${this.dbName})`);
+      logger.warn("IndexedDBToken", `load: db not initialized (db=${this.dbName})`);
       return {
         success: false,
         error: "Database not initialized",
@@ -836,7 +936,7 @@ var IndexedDBTokenStorageProvider = class {
         data._invalid = invalid;
       }
       const tokenKeys = Object.keys(data).filter((k) => k.startsWith("_") && !["_meta", "_tombstones", "_outbox", "_sent", "_invalid"].includes(k));
-      console.log(`[IndexedDBTokenStorage] load: db=${this.dbName}, tokens=${tokenKeys.length}`);
+      logger.debug("IndexedDBToken", `load: db=${this.dbName}, tokens=${tokenKeys.length}`);
       return {
         success: true,
         data,
@@ -844,7 +944,7 @@ var IndexedDBTokenStorageProvider = class {
         timestamp: Date.now()
       };
     } catch (error) {
-      console.error(`[IndexedDBTokenStorage] load failed: db=${this.dbName}`, error);
+      logger.error("IndexedDBToken", `load failed: db=${this.dbName}`, error);
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
@@ -855,7 +955,7 @@ var IndexedDBTokenStorageProvider = class {
   }
   async save(data) {
     if (!this.db) {
-      console.warn(`[IndexedDBTokenStorage] save: db not initialized (db=${this.dbName})`);
+      logger.warn("IndexedDBToken", `save: db not initialized (db=${this.dbName})`);
       return {
         success: false,
         error: "Database not initialized",
@@ -865,7 +965,7 @@ var IndexedDBTokenStorageProvider = class {
     try {
       const tokenKeys = Object.keys(data).filter((k) => k.startsWith("_") && !["_meta", "_tombstones", "_outbox", "_sent", "_invalid"].includes(k));
       const archivedKeys = Object.keys(data).filter((k) => k.startsWith("archived-"));
-      console.log(`[IndexedDBTokenStorage] save: db=${this.dbName}, tokens=${tokenKeys.length}, archived=${archivedKeys.length}, tombstones=${data._tombstones?.length ?? 0}`);
+      logger.debug("IndexedDBToken", `save: db=${this.dbName}, tokens=${tokenKeys.length}, archived=${archivedKeys.length}, tombstones=${data._tombstones?.length ?? 0}`);
       await this.putToStore(STORE_META, "meta", data._meta);
       if (data._tombstones) {
         await this.putToStore(STORE_META, "tombstones", data._tombstones);
@@ -934,21 +1034,22 @@ var IndexedDBTokenStorageProvider = class {
       for (const name of await this.findPrefixedDatabases()) {
         dbNames.add(name);
       }
-      console.log(`[IndexedDBTokenStorage] clear: clearing ${dbNames.size} database(s) (${[...dbNames].join(", ")})`);
+      logger.debug("IndexedDBToken", `clear: clearing ${dbNames.size} database(s) (${[...dbNames].join(", ")})`);
       const results = await Promise.allSettled(
         [...dbNames].map((name) => this.clearDatabaseStores(name))
       );
       const failed = results.filter((r) => r.status === "rejected");
       if (failed.length > 0) {
-        console.warn(
-          `[IndexedDBTokenStorage] clear: ${failed.length}/${dbNames.size} failed (${Date.now() - t0}ms)`,
+        logger.warn(
+          "IndexedDBToken",
+          `clear: ${failed.length}/${dbNames.size} failed (${Date.now() - t0}ms)`,
           failed.map((r) => r.reason)
         );
       }
-      console.log(`[IndexedDBTokenStorage] clear: done ${dbNames.size} database(s) (${Date.now() - t0}ms)`);
+      logger.debug("IndexedDBToken", `clear: done ${dbNames.size} database(s) (${Date.now() - t0}ms)`);
       return failed.length === 0;
     } catch (err) {
-      console.warn(`[IndexedDBTokenStorage] clear: failed (${Date.now() - t0}ms)`, err);
+      logger.warn("IndexedDBToken", `clear: failed (${Date.now() - t0}ms)`, err);
       return false;
     }
   }
@@ -964,7 +1065,7 @@ var IndexedDBTokenStorageProvider = class {
         const cid = ++connectionSeq2;
         this.connId = cid;
         db.onversionchange = () => {
-          console.log(`[IndexedDBTokenStorage] onversionchange: auto-closing db=${this.dbName} connId=${cid}`);
+          logger.debug("IndexedDBToken", `onversionchange: auto-closing db=${this.dbName} connId=${cid}`);
           db.close();
           if (this.db === db) {
             this.db = null;
@@ -974,7 +1075,7 @@ var IndexedDBTokenStorageProvider = class {
         resolve(db);
       };
       request.onblocked = () => {
-        console.warn(`[IndexedDBTokenStorage] open blocked by another connection, db=${this.dbName}`);
+        logger.warn("IndexedDBToken", `open blocked by another connection, db=${this.dbName}`);
       };
       request.onupgradeneeded = (event) => {
         const db = event.target.result;
@@ -1719,11 +1820,11 @@ function bech32Checksum(hrp, data) {
 }
 function encodeBech32(hrp, version, program) {
   if (version < 0 || version > 16) {
-    throw new Error("Invalid witness version");
+    throw new SphereError("Invalid witness version", "VALIDATION_ERROR");
   }
   const converted = convertBits(Array.from(program), 8, 5, true);
   if (!converted) {
-    throw new Error("Failed to convert bits");
+    throw new SphereError("Failed to convert bits", "VALIDATION_ERROR");
   }
   const data = [version].concat(converted);
   const checksum = bech32Checksum(hrp, data);
@@ -1916,18 +2017,18 @@ var NostrTransportProvider = class {
       });
       this.nostrClient.addConnectionListener({
         onConnect: (url) => {
-          this.log("NostrClient connected to relay:", url);
+          logger.debug("Nostr", "NostrClient connected to relay:", url);
           this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
         },
         onDisconnect: (url, reason) => {
-          this.log("NostrClient disconnected from relay:", url, "reason:", reason);
+          logger.debug("Nostr", "NostrClient disconnected from relay:", url, "reason:", reason);
         },
         onReconnecting: (url, attempt) => {
-          this.log("NostrClient reconnecting to relay:", url, "attempt:", attempt);
+          logger.debug("Nostr", "NostrClient reconnecting to relay:", url, "attempt:", attempt);
           this.emitEvent({ type: "transport:reconnecting", timestamp: Date.now() });
         },
         onReconnected: (url) => {
-          this.log("NostrClient reconnected to relay:", url);
+          logger.debug("Nostr", "NostrClient reconnected to relay:", url);
           this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
         }
       });
@@ -1940,11 +2041,11 @@ var NostrTransportProvider = class {
         )
       ]);
       if (!this.nostrClient.isConnected()) {
-        throw new Error("Failed to connect to any relay");
+        throw new SphereError("Failed to connect to any relay", "TRANSPORT_ERROR");
       }
       this.status = "connected";
       this.emitEvent({ type: "transport:connected", timestamp: Date.now() });
-      this.log("Connected to", this.nostrClient.getConnectedRelays().size, "relays");
+      logger.debug("Nostr", "Connected to", this.nostrClient.getConnectedRelays().size, "relays");
       if (this.identity) {
         await this.subscribeToEvents();
       }
@@ -1963,7 +2064,7 @@ var NostrTransportProvider = class {
     this.chatSubscriptionId = null;
     this.status = "disconnected";
     this.emitEvent({ type: "transport:disconnected", timestamp: Date.now() });
-    this.log("Disconnected from all relays");
+    logger.debug("Nostr", "Disconnected from all relays");
   }
   isConnected() {
     return this.status === "connected" && this.nostrClient?.isConnected() === true;
@@ -1993,14 +2094,14 @@ var NostrTransportProvider = class {
    */
   async addRelay(relayUrl) {
     if (this.config.relays.includes(relayUrl)) {
-      this.log("Relay already configured:", relayUrl);
+      logger.debug("Nostr", "Relay already configured:", relayUrl);
       return false;
     }
     this.config.relays.push(relayUrl);
     if (this.status === "connected" && this.nostrClient) {
       try {
         await this.nostrClient.connect(relayUrl);
-        this.log("Added and connected to relay:", relayUrl);
+        logger.debug("Nostr", "Added and connected to relay:", relayUrl);
         this.emitEvent({
           type: "transport:relay_added",
           timestamp: Date.now(),
@@ -2008,7 +2109,7 @@ var NostrTransportProvider = class {
         });
         return true;
       } catch (error) {
-        this.log("Failed to connect to new relay:", relayUrl, error);
+        logger.debug("Nostr", "Failed to connect to new relay:", relayUrl, error);
         this.emitEvent({
           type: "transport:relay_added",
           timestamp: Date.now(),
@@ -2033,11 +2134,11 @@ var NostrTransportProvider = class {
   async removeRelay(relayUrl) {
     const index = this.config.relays.indexOf(relayUrl);
     if (index === -1) {
-      this.log("Relay not found:", relayUrl);
+      logger.debug("Nostr", "Relay not found:", relayUrl);
       return false;
     }
     this.config.relays.splice(index, 1);
-    this.log("Removed relay from config:", relayUrl);
+    logger.debug("Nostr", "Removed relay from config:", relayUrl);
     this.emitEvent({
       type: "transport:relay_removed",
       timestamp: Date.now(),
@@ -2074,9 +2175,9 @@ var NostrTransportProvider = class {
     const secretKey = import_buffer.Buffer.from(identity.privateKey, "hex");
     this.keyManager = import_nostr_js_sdk.NostrKeyManager.fromPrivateKey(secretKey);
     const nostrPubkey = this.keyManager.getPublicKeyHex();
-    this.log("Identity set, Nostr pubkey:", nostrPubkey.slice(0, 16) + "...");
+    logger.debug("Nostr", "Identity set, Nostr pubkey:", nostrPubkey.slice(0, 16) + "...");
     if (this.nostrClient && this.status === "connected") {
-      this.log("Identity changed while connected - recreating NostrClient");
+      logger.debug("Nostr", "Identity changed while connected - recreating NostrClient");
       const oldClient = this.nostrClient;
       this.nostrClient = new import_nostr_js_sdk.NostrClient(this.keyManager, {
         autoReconnect: this.config.autoReconnect,
@@ -2087,16 +2188,16 @@ var NostrTransportProvider = class {
       });
       this.nostrClient.addConnectionListener({
         onConnect: (url) => {
-          this.log("NostrClient connected to relay:", url);
+          logger.debug("Nostr", "NostrClient connected to relay:", url);
         },
         onDisconnect: (url, reason) => {
-          this.log("NostrClient disconnected from relay:", url, "reason:", reason);
+          logger.debug("Nostr", "NostrClient disconnected from relay:", url, "reason:", reason);
         },
         onReconnecting: (url, attempt) => {
-          this.log("NostrClient reconnecting to relay:", url, "attempt:", attempt);
+          logger.debug("Nostr", "NostrClient reconnecting to relay:", url, "attempt:", attempt);
         },
         onReconnected: (url) => {
-          this.log("NostrClient reconnected to relay:", url);
+          logger.debug("Nostr", "NostrClient reconnected to relay:", url);
         }
       });
       await Promise.race([
@@ -2119,7 +2220,7 @@ var NostrTransportProvider = class {
    */
   getNostrPubkey() {
     if (!this.keyManager) {
-      throw new Error("KeyManager not initialized - call setIdentity first");
+      throw new SphereError("KeyManager not initialized - call setIdentity first", "NOT_INITIALIZED");
     }
     return this.keyManager.getPublicKeyHex();
   }
@@ -2140,7 +2241,7 @@ var NostrTransportProvider = class {
     const selfPubkey = this.keyManager.getPublicKeyHex();
     const selfGiftWrap = import_nostr_js_sdk.NIP17.createGiftWrap(this.keyManager, selfPubkey, selfWrapContent);
     this.publishEvent(selfGiftWrap).catch((err) => {
-      this.log("Self-wrap publish failed:", err);
+      logger.debug("Nostr", "Self-wrap publish failed:", err);
     });
     this.emitEvent({
       type: "message:sent",
@@ -2154,12 +2255,12 @@ var NostrTransportProvider = class {
     if (this.pendingMessages.length > 0) {
       const pending = this.pendingMessages;
       this.pendingMessages = [];
-      this.log("Flushing", pending.length, "buffered messages to new handler");
+      logger.debug("Nostr", "Flushing", pending.length, "buffered messages to new handler");
       for (const message of pending) {
         try {
           handler(message);
         } catch (error) {
-          this.log("Message handler error (buffered):", error);
+          logger.debug("Nostr", "Message handler error (buffered):", error);
         }
       }
     }
@@ -2218,7 +2319,7 @@ var NostrTransportProvider = class {
       tags
     );
     await this.publishEvent(event);
-    this.log("Sent payment request:", event.id);
+    logger.debug("Nostr", "Sent payment request:", event.id);
     return event.id;
   }
   onPaymentRequest(handler) {
@@ -2246,7 +2347,7 @@ var NostrTransportProvider = class {
       ]
     );
     await this.publishEvent(event);
-    this.log("Sent payment request response:", event.id, "type:", payload.responseType);
+    logger.debug("Nostr", "Sent payment request response:", event.id, "type:", payload.responseType);
     return event.id;
   }
   onPaymentRequestResponse(handler) {
@@ -2257,11 +2358,11 @@ var NostrTransportProvider = class {
   // Read Receipts
   // ===========================================================================
   async sendReadReceipt(recipientTransportPubkey, messageEventId) {
-    if (!this.keyManager) throw new Error("Not initialized");
+    if (!this.keyManager) throw new SphereError("Not initialized", "NOT_INITIALIZED");
     const nostrRecipient = recipientTransportPubkey.length === 66 ? recipientTransportPubkey.slice(2) : recipientTransportPubkey;
     const event = import_nostr_js_sdk.NIP17.createReadReceipt(this.keyManager, nostrRecipient, messageEventId);
     await this.publishEvent(event);
-    this.log("Sent read receipt for:", messageEventId, "to:", nostrRecipient.slice(0, 16));
+    logger.debug("Nostr", "Sent read receipt for:", messageEventId, "to:", nostrRecipient.slice(0, 16));
   }
   onReadReceipt(handler) {
     this.readReceiptHandlers.add(handler);
@@ -2271,7 +2372,7 @@ var NostrTransportProvider = class {
   // Typing Indicators
   // ===========================================================================
   async sendTypingIndicator(recipientTransportPubkey) {
-    if (!this.keyManager) throw new Error("Not initialized");
+    if (!this.keyManager) throw new SphereError("Not initialized", "NOT_INITIALIZED");
     const nostrRecipient = recipientTransportPubkey.length === 66 ? recipientTransportPubkey.slice(2) : recipientTransportPubkey;
     const content = JSON.stringify({
       type: "typing",
@@ -2358,7 +2459,10 @@ var NostrTransportProvider = class {
         limit: 1
       });
     }
-    if (events.length === 0) return null;
+    if (events.length === 0) {
+      logger.debug("Nostr", `resolveNametagInfo: no binding events found for nametag "${nametag}"`);
+      return null;
+    }
     const bindingEvent = events[0];
     try {
       const content = JSON.parse(bindingEvent.content);
@@ -2376,7 +2480,7 @@ var NostrTransportProvider = class {
           timestamp: bindingEvent.created_at * 1e3
         };
       }
-      this.log("Legacy nametag event without extended fields:", nametag);
+      logger.debug("Nostr", "Legacy nametag event without extended fields:", nametag);
       const pubkeyTag = bindingEvent.tags.find((t) => t[0] === "pubkey");
       const l1Tag = bindingEvent.tags.find((t) => t[0] === "l1");
       if (pubkeyTag?.[1] && l1Tag?.[1]) {
@@ -2532,10 +2636,10 @@ var NostrTransportProvider = class {
   async recoverNametag() {
     this.ensureReady();
     if (!this.identity || !this.keyManager) {
-      throw new Error("Identity not set");
+      throw new SphereError("Identity not set", "NOT_INITIALIZED");
     }
     const nostrPubkey = this.getNostrPubkey();
-    this.log("Searching for nametag events for pubkey:", nostrPubkey.slice(0, 16) + "...");
+    logger.debug("Nostr", "Searching for nametag events for pubkey:", nostrPubkey.slice(0, 16) + "...");
     const events = await this.queryEvents({
       kinds: [EVENT_KINDS.NAMETAG_BINDING],
       authors: [nostrPubkey],
@@ -2543,7 +2647,7 @@ var NostrTransportProvider = class {
       // Get recent events in case of updates
     });
     if (events.length === 0) {
-      this.log("No nametag events found for this pubkey");
+      logger.debug("Nostr", "No nametag events found for this pubkey");
       return null;
     }
     events.sort((a, b) => b.created_at - a.created_at);
@@ -2556,7 +2660,7 @@ var NostrTransportProvider = class {
             this.identity.privateKey
           );
           if (decrypted) {
-            this.log("Recovered nametag:", decrypted);
+            logger.debug("Nostr", "Recovered nametag:", decrypted);
             return decrypted;
           }
         }
@@ -2564,7 +2668,7 @@ var NostrTransportProvider = class {
         continue;
       }
     }
-    this.log("Could not decrypt nametag from any event");
+    logger.debug("Nostr", "Could not decrypt nametag from any event");
     return null;
   }
   /**
@@ -2580,7 +2684,7 @@ var NostrTransportProvider = class {
   async publishIdentityBinding(chainPubkey, l1Address, directAddress, nametag) {
     this.ensureReady();
     if (!this.identity) {
-      throw new Error("Identity not set");
+      throw new SphereError("Identity not set", "NOT_INITIALIZED");
     }
     const nostrPubkey = this.getNostrPubkey();
     const dTagBytes = new TextEncoder().encode("unicity:identity:" + nostrPubkey);
@@ -2599,7 +2703,7 @@ var NostrTransportProvider = class {
     if (nametag) {
       const existing = await this.resolveNametag(nametag);
       if (existing && existing !== nostrPubkey) {
-        this.log("Nametag already taken:", nametag, "- owner:", existing);
+        logger.debug("Nostr", "Nametag already taken:", nametag, "- owner:", existing);
         return false;
       }
       const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
@@ -2617,9 +2721,9 @@ var NostrTransportProvider = class {
     const event = await this.createEvent(EVENT_KINDS.NAMETAG_BINDING, content, tags);
     await this.publishEvent(event);
     if (nametag) {
-      this.log("Published identity binding with nametag:", nametag, "for pubkey:", nostrPubkey.slice(0, 16) + "...");
+      logger.debug("Nostr", "Published identity binding with nametag:", nametag, "for pubkey:", nostrPubkey.slice(0, 16) + "...");
     } else {
-      this.log("Published identity binding (no nametag) for pubkey:", nostrPubkey.slice(0, 16) + "...");
+      logger.debug("Nostr", "Published identity binding (no nametag) for pubkey:", nostrPubkey.slice(0, 16) + "...");
     }
     return true;
   }
@@ -2632,18 +2736,18 @@ var NostrTransportProvider = class {
       ["a", address]
     ]);
     await this.publishEvent(event);
-    this.log("Published nametag binding:", nametag);
+    logger.debug("Nostr", "Published nametag binding:", nametag);
   }
   async registerNametag(nametag, _publicKey, directAddress = "") {
     this.ensureReady();
     if (!this.identity) {
-      throw new Error("Identity not set");
+      throw new SphereError("Identity not set", "NOT_INITIALIZED");
     }
     const nostrPubkey = this.getNostrPubkey();
     const existing = await this.resolveNametag(nametag);
-    this.log("registerNametag:", nametag, "existing:", existing, "myPubkey:", nostrPubkey);
+    logger.debug("Nostr", "registerNametag:", nametag, "existing:", existing, "myPubkey:", nostrPubkey);
     if (existing && existing !== nostrPubkey) {
-      this.log("Nametag already taken:", nametag, "- owner:", existing);
+      logger.debug("Nostr", "Nametag already taken:", nametag, "- owner:", existing);
       return false;
     }
     const privateKeyHex = this.identity.privateKey;
@@ -2677,7 +2781,7 @@ var NostrTransportProvider = class {
     ];
     const event = await this.createEvent(EVENT_KINDS.NAMETAG_BINDING, content, tags);
     await this.publishEvent(event);
-    this.log("Registered nametag:", nametag, "for pubkey:", nostrPubkey.slice(0, 16) + "...", "l1:", l1Address.slice(0, 12) + "...");
+    logger.debug("Nostr", "Registered nametag:", nametag, "for pubkey:", nostrPubkey.slice(0, 16) + "...", "l1:", l1Address.slice(0, 12) + "...");
     return true;
   }
   // Track broadcast subscriptions
@@ -2728,14 +2832,14 @@ var NostrTransportProvider = class {
     if (event.id) {
       this.processedEventIds.add(event.id);
     }
-    this.log("Processing event kind:", event.kind, "id:", event.id?.slice(0, 12));
+    logger.debug("Nostr", "Processing event kind:", event.kind, "id:", event.id?.slice(0, 12));
     try {
       switch (event.kind) {
         case EVENT_KINDS.DIRECT_MESSAGE:
           await this.handleDirectMessage(event);
           break;
         case import_nostr_js_sdk.EventKinds.GIFT_WRAP:
-          this.log("Handling gift wrap (NIP-17 DM)");
+          logger.debug("Nostr", "Handling gift wrap (NIP-17 DM)");
           await this.handleGiftWrap(event);
           break;
         case EVENT_KINDS.TOKEN_TRANSFER:
@@ -2758,7 +2862,7 @@ var NostrTransportProvider = class {
         }
       }
     } catch (error) {
-      this.log("Failed to handle event:", error);
+      logger.debug("Nostr", "Failed to handle event:", error);
     }
   }
   /**
@@ -2773,25 +2877,25 @@ var NostrTransportProvider = class {
     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);
+      logger.debug("Nostr", "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));
+    logger.debug("Nostr", "Ignoring NIP-04 kind 4 event (DMs use NIP-17):", event.id?.slice(0, 12));
   }
   async handleGiftWrap(event) {
     if (!this.identity || !this.keyManager) {
-      this.log("handleGiftWrap: no identity/keyManager");
+      logger.debug("Nostr", "handleGiftWrap: no identity/keyManager");
       return;
     }
     try {
       const pm = import_nostr_js_sdk.NIP17.unwrap(event, this.keyManager);
-      this.log("Gift wrap unwrapped, sender:", pm.senderPubkey?.slice(0, 16), "kind:", pm.kind);
+      logger.debug("Nostr", "Gift wrap unwrapped, sender:", pm.senderPubkey?.slice(0, 16), "kind:", pm.kind);
       if (pm.senderPubkey === this.keyManager.getPublicKeyHex()) {
         try {
           const parsed = JSON.parse(pm.content);
           if (parsed?.selfWrap && parsed.recipientPubkey) {
-            this.log("Self-wrap replay for recipient:", parsed.recipientPubkey?.slice(0, 16));
+            logger.debug("Nostr", "Self-wrap replay for recipient:", parsed.recipientPubkey?.slice(0, 16));
             const message2 = {
               id: parsed.originalId || pm.eventId,
               senderTransportPubkey: pm.senderPubkey,
@@ -2806,18 +2910,18 @@ var NostrTransportProvider = class {
               try {
                 handler(message2);
               } catch (e) {
-                this.log("Self-wrap handler error:", e);
+                logger.debug("Nostr", "Self-wrap handler error:", e);
               }
             }
             return;
           }
         } catch {
         }
-        this.log("Skipping own non-self-wrap message");
+        logger.debug("Nostr", "Skipping own non-self-wrap message");
         return;
       }
       if ((0, import_nostr_js_sdk.isReadReceipt)(pm)) {
-        this.log("Read receipt from:", pm.senderPubkey?.slice(0, 16), "for:", pm.replyToEventId);
+        logger.debug("Nostr", "Read receipt from:", pm.senderPubkey?.slice(0, 16), "for:", pm.replyToEventId);
         if (pm.replyToEventId) {
           const receipt = {
             senderTransportPubkey: pm.senderPubkey,
@@ -2828,7 +2932,7 @@ var NostrTransportProvider = class {
             try {
               handler(receipt);
             } catch (e) {
-              this.log("Read receipt handler error:", e);
+              logger.debug("Nostr", "Read receipt handler error:", e);
             }
           }
         }
@@ -2848,12 +2952,12 @@ var NostrTransportProvider = class {
           senderNametag: senderNametag2,
           expiresIn
         };
-        this.log("Composing indicator from:", indicator.senderNametag || pm.senderPubkey?.slice(0, 16));
+        logger.debug("Nostr", "Composing indicator from:", indicator.senderNametag || pm.senderPubkey?.slice(0, 16));
         for (const handler of this.composingHandlers) {
           try {
             handler(indicator);
           } catch (e) {
-            this.log("Composing handler error:", e);
+            logger.debug("Nostr", "Composing handler error:", e);
           }
         }
         return;
@@ -2861,7 +2965,7 @@ var NostrTransportProvider = class {
       try {
         const parsed = JSON.parse(pm.content);
         if (parsed?.type === "typing") {
-          this.log("Typing indicator from:", pm.senderPubkey?.slice(0, 16));
+          logger.debug("Nostr", "Typing indicator from:", pm.senderPubkey?.slice(0, 16));
           const indicator = {
             senderTransportPubkey: pm.senderPubkey,
             senderNametag: parsed.senderNametag,
@@ -2871,7 +2975,7 @@ var NostrTransportProvider = class {
             try {
               handler(indicator);
             } catch (e) {
-              this.log("Typing handler error:", e);
+              logger.debug("Nostr", "Typing handler error:", e);
             }
           }
           return;
@@ -2879,7 +2983,7 @@ var NostrTransportProvider = class {
       } catch {
       }
       if (!(0, import_nostr_js_sdk.isChatMessage)(pm)) {
-        this.log("Skipping unknown message kind:", pm.kind);
+        logger.debug("Nostr", "Skipping unknown message kind:", pm.kind);
         return;
       }
       let content = pm.content;
@@ -2892,7 +2996,7 @@ var NostrTransportProvider = class {
         }
       } catch {
       }
-      this.log("DM received from:", senderNametag || pm.senderPubkey?.slice(0, 16), "content:", content?.slice(0, 50));
+      logger.debug("Nostr", "DM received from:", senderNametag || pm.senderPubkey?.slice(0, 16), "content:", content?.slice(0, 50));
       const message = {
         // Use outer gift wrap event.id so it matches the sender's stored giftWrap.id.
         // This ensures read receipts reference an ID the sender recognizes.
@@ -2905,20 +3009,20 @@ var NostrTransportProvider = class {
       };
       this.emitEvent({ type: "message:received", timestamp: Date.now() });
       if (this.messageHandlers.size === 0) {
-        this.log("No message handlers registered, buffering message for later delivery");
+        logger.debug("Nostr", "No message handlers registered, buffering message for later delivery");
         this.pendingMessages.push(message);
       } else {
-        this.log("Dispatching to", this.messageHandlers.size, "handlers");
+        logger.debug("Nostr", "Dispatching to", this.messageHandlers.size, "handlers");
         for (const handler of this.messageHandlers) {
           try {
             handler(message);
           } catch (error) {
-            this.log("Message handler error:", error);
+            logger.debug("Nostr", "Message handler error:", error);
           }
         }
       }
     } catch (err) {
-      this.log("Gift wrap decrypt failed (expected if not for us):", err?.message?.slice(0, 50));
+      logger.debug("Nostr", "Gift wrap decrypt failed (expected if not for us):", err?.message?.slice(0, 50));
     }
   }
   async handleTokenTransfer(event) {
@@ -2936,7 +3040,7 @@ var NostrTransportProvider = class {
       try {
         await handler(transfer);
       } catch (error) {
-        this.log("Transfer handler error:", error);
+        logger.debug("Nostr", "Transfer handler error:", error);
       }
     }
   }
@@ -2959,16 +3063,16 @@ var NostrTransportProvider = class {
         },
         timestamp: event.created_at * 1e3
       };
-      this.log("Received payment request:", request.id);
+      logger.debug("Nostr", "Received payment request:", request.id);
       for (const handler of this.paymentRequestHandlers) {
         try {
           handler(request);
         } catch (error) {
-          this.log("Payment request handler error:", error);
+          logger.debug("Nostr", "Payment request handler error:", error);
         }
       }
     } catch (error) {
-      this.log("Failed to handle payment request:", error);
+      logger.debug("Nostr", "Failed to handle payment request:", error);
     }
   }
   async handlePaymentRequestResponse(event) {
@@ -2987,16 +3091,16 @@ var NostrTransportProvider = class {
         },
         timestamp: event.created_at * 1e3
       };
-      this.log("Received payment request response:", response.id, "type:", responseData.responseType);
+      logger.debug("Nostr", "Received payment request response:", response.id, "type:", responseData.responseType);
       for (const handler of this.paymentRequestResponseHandlers) {
         try {
           handler(response);
         } catch (error) {
-          this.log("Payment request response handler error:", error);
+          logger.debug("Nostr", "Payment request response handler error:", error);
         }
       }
     } catch (error) {
-      this.log("Failed to handle payment request response:", error);
+      logger.debug("Nostr", "Failed to handle payment request response:", error);
     }
   }
   handleBroadcast(event) {
@@ -3015,7 +3119,7 @@ var NostrTransportProvider = class {
           try {
             handler(broadcast);
           } catch (error) {
-            this.log("Broadcast handler error:", error);
+            logger.debug("Nostr", "Broadcast handler error:", error);
           }
         }
       }
@@ -3025,8 +3129,8 @@ var NostrTransportProvider = class {
   // Private: Event Creation & Publishing
   // ===========================================================================
   async createEvent(kind, content, tags) {
-    if (!this.identity) throw new Error("Identity not set");
-    if (!this.keyManager) throw new Error("KeyManager not initialized");
+    if (!this.identity) throw new SphereError("Identity not set", "NOT_INITIALIZED");
+    if (!this.keyManager) throw new SphereError("KeyManager not initialized", "NOT_INITIALIZED");
     const signedEvent = import_nostr_js_sdk.Event.create(this.keyManager, {
       kind,
       content,
@@ -3044,10 +3148,10 @@ var NostrTransportProvider = class {
     return event;
   }
   async createEncryptedEvent(kind, content, tags) {
-    if (!this.keyManager) throw new Error("KeyManager not initialized");
+    if (!this.keyManager) throw new SphereError("KeyManager not initialized", "NOT_INITIALIZED");
     const recipientTag = tags.find((t) => t[0] === "p");
     if (!recipientTag || !recipientTag[1]) {
-      throw new Error("No recipient pubkey in tags for encryption");
+      throw new SphereError("No recipient pubkey in tags for encryption", "VALIDATION_ERROR");
     }
     const recipientPubkey = recipientTag[1];
     const encrypted = await import_nostr_js_sdk.NIP04.encryptHex(
@@ -3059,14 +3163,14 @@ var NostrTransportProvider = class {
   }
   async publishEvent(event) {
     if (!this.nostrClient) {
-      throw new Error("NostrClient not initialized");
+      throw new SphereError("NostrClient not initialized", "NOT_INITIALIZED");
     }
     const sdkEvent = import_nostr_js_sdk.Event.fromJSON(event);
     await this.nostrClient.publishEvent(sdkEvent);
   }
   async fetchPendingEvents() {
     if (!this.nostrClient?.isConnected() || !this.keyManager) {
-      throw new Error("Transport not connected");
+      throw new SphereError("Transport not connected", "TRANSPORT_ERROR");
     }
     const nostrPubkey = this.keyManager.getPublicKeyHex();
     const walletFilter = new import_nostr_js_sdk.Filter();
@@ -3109,7 +3213,7 @@ var NostrTransportProvider = class {
   }
   async queryEvents(filterObj) {
     if (!this.nostrClient || !this.nostrClient.isConnected()) {
-      throw new Error("No connected relays");
+      throw new SphereError("No connected relays", "TRANSPORT_ERROR");
     }
     const events = [];
     const filter = new import_nostr_js_sdk.Filter(filterObj);
@@ -3118,6 +3222,7 @@ var NostrTransportProvider = class {
         if (subId) {
           this.nostrClient?.unsubscribe(subId);
         }
+        logger.warn("Nostr", `queryEvents timed out after 5s, returning ${events.length} event(s)`, { kinds: filterObj.kinds, limit: filterObj.limit });
         resolve(events);
       }, 5e3);
       const subId = this.nostrClient.subscribe(filter, {
@@ -3147,9 +3252,9 @@ var NostrTransportProvider = class {
   walletSubscriptionId = null;
   chatSubscriptionId = null;
   async subscribeToEvents() {
-    this.log("subscribeToEvents called, identity:", !!this.identity, "keyManager:", !!this.keyManager, "nostrClient:", !!this.nostrClient);
+    logger.debug("Nostr", "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");
+      logger.debug("Nostr", "subscribeToEvents: skipped - no identity, keyManager, or nostrClient");
       return;
     }
     if (this.walletSubscriptionId) {
@@ -3165,7 +3270,7 @@ var NostrTransportProvider = class {
       this.mainSubscriptionId = null;
     }
     const nostrPubkey = this.keyManager.getPublicKeyHex();
-    this.log("Subscribing with Nostr pubkey:", nostrPubkey);
+    logger.debug("Nostr", "Subscribing with Nostr pubkey:", nostrPubkey);
     let since;
     if (this.storage) {
       const storageKey = `${STORAGE_KEYS_GLOBAL.LAST_WALLET_EVENT_TS}_${nostrPubkey.slice(0, 16)}`;
@@ -3174,18 +3279,18 @@ var NostrTransportProvider = class {
         if (stored) {
           since = parseInt(stored, 10);
           this.lastEventTs = since;
-          this.log("Resuming from stored event timestamp:", since);
+          logger.debug("Nostr", "Resuming from stored event timestamp:", since);
         } else {
           since = Math.floor(Date.now() / 1e3);
-          this.log("No stored timestamp, starting from now:", since);
+          logger.debug("Nostr", "No stored timestamp, starting from now:", since);
         }
       } catch (err) {
-        this.log("Failed to read last event timestamp, falling back to now:", err);
+        logger.debug("Nostr", "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");
+      logger.debug("Nostr", "No storage adapter, using 24h fallback");
     }
     const walletFilter = new import_nostr_js_sdk.Filter();
     walletFilter.kinds = [
@@ -3198,7 +3303,7 @@ var NostrTransportProvider = class {
     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));
+        logger.debug("Nostr", "Received wallet event kind:", event.kind, "id:", event.id?.slice(0, 12));
         this.handleEvent({
           id: event.id,
           kind: event.kind,
@@ -3210,19 +3315,19 @@ var NostrTransportProvider = class {
         });
       },
       onEndOfStoredEvents: () => {
-        this.log("Wallet subscription ready (EOSE)");
+        logger.debug("Nostr", "Wallet subscription ready (EOSE)");
       },
       onError: (_subId, error) => {
-        this.log("Wallet subscription error:", error);
+        logger.debug("Nostr", "Wallet subscription error:", error);
       }
     });
-    this.log("Wallet subscription created, subId:", this.walletSubscriptionId);
+    logger.debug("Nostr", "Wallet subscription created, subId:", this.walletSubscriptionId);
     const chatFilter = new import_nostr_js_sdk.Filter();
     chatFilter.kinds = [import_nostr_js_sdk.EventKinds.GIFT_WRAP];
     chatFilter["#p"] = [nostrPubkey];
     this.chatSubscriptionId = this.nostrClient.subscribe(chatFilter, {
       onEvent: (event) => {
-        this.log("Received chat event kind:", event.kind, "id:", event.id?.slice(0, 12));
+        logger.debug("Nostr", "Received chat event kind:", event.kind, "id:", event.id?.slice(0, 12));
         this.handleEvent({
           id: event.id,
           kind: event.kind,
@@ -3234,13 +3339,13 @@ var NostrTransportProvider = class {
         });
       },
       onEndOfStoredEvents: () => {
-        this.log("Chat subscription ready (EOSE)");
+        logger.debug("Nostr", "Chat subscription ready (EOSE)");
       },
       onError: (_subId, error) => {
-        this.log("Chat subscription error:", error);
+        logger.debug("Nostr", "Chat subscription error:", error);
       }
     });
-    this.log("Chat subscription created, subId:", this.chatSubscriptionId);
+    logger.debug("Nostr", "Chat subscription created, subId:", this.chatSubscriptionId);
   }
   subscribeToTags(tags) {
     if (!this.nostrClient) return;
@@ -3270,7 +3375,7 @@ var NostrTransportProvider = class {
   // Private: Encryption
   // ===========================================================================
   async decryptContent(content, senderPubkey) {
-    if (!this.keyManager) throw new Error("KeyManager not initialized");
+    if (!this.keyManager) throw new SphereError("KeyManager not initialized", "NOT_INITIALIZED");
     const decrypted = await import_nostr_js_sdk.NIP04.decryptHex(
       content,
       this.keyManager.getPrivateKeyHex(),
@@ -3300,13 +3405,13 @@ var NostrTransportProvider = class {
   // ===========================================================================
   ensureConnected() {
     if (!this.isConnected()) {
-      throw new Error("NostrTransportProvider not connected");
+      throw new SphereError("NostrTransportProvider not connected", "TRANSPORT_ERROR");
     }
   }
   ensureReady() {
     this.ensureConnected();
     if (!this.identity) {
-      throw new Error("Identity not set");
+      throw new SphereError("Identity not set", "NOT_INITIALIZED");
     }
   }
   emitEvent(event) {
@@ -3314,7 +3419,7 @@ var NostrTransportProvider = class {
       try {
         callback(event);
       } catch (error) {
-        this.log("Event callback error:", error);
+        logger.debug("Nostr", "Event callback error:", error);
       }
     }
   }
@@ -3351,11 +3456,6 @@ var NostrTransportProvider = class {
     ephemeralKeys.clear();
     return giftWrap;
   }
-  log(...args) {
-    if (this.config.debug) {
-      console.log("[NostrTransportProvider]", ...args);
-    }
-  }
 };
 
 // impl/browser/transport/index.ts
@@ -3539,7 +3639,8 @@ var UnicityAggregatorProvider = class {
         proof: response.proof,
         timestamp: Date.now()
       };
-    } catch {
+    } catch (error) {
+      logger.warn("Aggregator", "getProof failed", error);
       return null;
     }
   }
@@ -3561,7 +3662,7 @@ var UnicityAggregatorProvider = class {
       }
       await new Promise((resolve) => setTimeout(resolve, pollInterval));
     }
-    throw new Error(`Timeout waiting for proof: ${requestId}`);
+    throw new SphereError(`Timeout waiting for proof: ${requestId}`, "TIMEOUT");
   }
   async validateToken(tokenData) {
     this.ensureConnected();
@@ -3620,7 +3721,7 @@ var UnicityAggregatorProvider = class {
   async waitForProofSdk(commitment, signal) {
     this.ensureConnected();
     if (!this.trustBase) {
-      throw new Error("Trust base not initialized");
+      throw new SphereError("Trust base not initialized", "NOT_INITIALIZED");
     }
     return await (0, import_InclusionProofUtils.waitInclusionProof)(
       this.trustBase,
@@ -3642,7 +3743,8 @@ var UnicityAggregatorProvider = class {
         this.spentCache.set(stateHash, true);
       }
       return spent;
-    } catch {
+    } catch (error) {
+      logger.warn("Aggregator", "isSpent check failed, assuming unspent", error);
       return false;
     }
   }
@@ -3660,7 +3762,8 @@ var UnicityAggregatorProvider = class {
         roundNumber: response.state.roundNumber,
         lastUpdated: Date.now()
       };
-    } catch {
+    } catch (error) {
+      logger.warn("Aggregator", "getTokenState failed", error);
       return null;
     }
   }
@@ -3720,11 +3823,11 @@ var UnicityAggregatorProvider = class {
         signal: controller.signal
       });
       if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        throw new SphereError(`HTTP ${response.status}: ${response.statusText}`, "AGGREGATOR_ERROR");
       }
       const result = await response.json();
       if (result.error) {
-        throw new Error(result.error.message ?? "RPC error");
+        throw new SphereError(result.error.message ?? "RPC error", "AGGREGATOR_ERROR");
       }
       return result.result ?? {};
     } finally {
@@ -3736,7 +3839,7 @@ var UnicityAggregatorProvider = class {
   // ===========================================================================
   ensureConnected() {
     if (this.status !== "connected") {
-      throw new Error("UnicityAggregatorProvider not connected");
+      throw new SphereError("UnicityAggregatorProvider not connected", "NOT_INITIALIZED");
     }
   }
   emitEvent(event) {
@@ -3748,10 +3851,8 @@ var UnicityAggregatorProvider = class {
       }
     }
   }
-  log(...args) {
-    if (this.config.debug) {
-      console.log("[UnicityAggregatorProvider]", ...args);
-    }
+  log(message, ...args) {
+    logger.debug("Aggregator", message, ...args);
   }
 };
 var UnicityOracleProvider = UnicityAggregatorProvider;
@@ -4340,7 +4441,10 @@ var IpfsHttpClient = class {
           { headers: { Accept: "application/octet-stream" } }
         );
         if (!response.ok) {
-          const body = await response.text().catch(() => "");
+          const body = await response.text().catch((err) => {
+            logger.debug("IPFS-HTTP", "Failed to read error response body", err);
+            return "";
+          });
           throw new IpfsError(
             `Fetch failed: HTTP ${response.status}`,
             classifyHttpStatus(response.status, body),
@@ -4386,7 +4490,10 @@ var IpfsHttpClient = class {
         { method: "POST" }
       );
       if (!response.ok) {
-        const body = await response.text().catch(() => "");
+        const body = await response.text().catch((err) => {
+          logger.debug("IPFS-HTTP", "Failed to read error response body", err);
+          return "";
+        });
         const category = classifyHttpStatus(response.status, body);
         if (category === "NOT_FOUND") return null;
         throw new IpfsError(`Routing API: HTTP ${response.status}`, category, gateway);
@@ -4432,7 +4539,8 @@ var IpfsHttpClient = class {
         }
       }
       return { cid: "", content };
-    } catch {
+    } catch (err) {
+      logger.debug("IPFS-HTTP", "IPNS gateway resolution failed", err);
       return null;
     }
   }
@@ -4497,7 +4605,10 @@ var IpfsHttpClient = class {
         { method: "POST", body: formData }
       );
       if (!response.ok) {
-        const errorText = await response.text().catch(() => "");
+        const errorText = await response.text().catch((err) => {
+          logger.debug("IPFS-HTTP", "Failed to read error response body", err);
+          return "";
+        });
         throw new IpfsError(
           `IPNS publish: HTTP ${response.status}: ${errorText.slice(0, 100)}`,
           classifyHttpStatus(response.status, errorText),
@@ -4574,9 +4685,7 @@ var IpfsHttpClient = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-HTTP] ${message}`);
-    }
+    logger.debug("IPFS-HTTP", message);
   }
 };
 
@@ -5020,10 +5129,12 @@ var IpnsSubscriptionClient = class {
   startFallbackPolling() {
     if (this.fallbackPollInterval || !this.fallbackPollFn || this.destroyed) return;
     this.log(`Starting fallback polling (${this.fallbackPollIntervalMs / 1e3}s interval)`);
-    this.fallbackPollFn().catch(() => {
+    this.fallbackPollFn().catch((err) => {
+      logger.warn("IPNS-WS", "Fallback poll error:", err);
     });
     this.fallbackPollInterval = setInterval(() => {
-      this.fallbackPollFn?.().catch(() => {
+      this.fallbackPollFn?.().catch((err) => {
+        logger.warn("IPNS-WS", "Fallback poll error:", err);
       });
     }, this.fallbackPollIntervalMs);
   }
@@ -5037,9 +5148,7 @@ var IpnsSubscriptionClient = class {
   // Internal: Logging
   // ---------------------------------------------------------------------------
   log(message) {
-    if (this.debugEnabled) {
-      console.log(`[IPNS-WS] ${message}`);
-    }
+    logger.debug("IPNS-WS", message);
   }
 };
 
@@ -5228,7 +5337,8 @@ var IpfsStorageProvider = class {
         } else {
           this.log("Warning: no healthy gateways found");
         }
-      }).catch(() => {
+      }).catch((err) => {
+        logger.warn("IPFS-Storage", "Gateway health check failed (non-fatal):", err);
       });
       this.isShuttingDown = false;
       this.status = "connected";
@@ -5392,7 +5502,7 @@ var IpfsStorageProvider = class {
       };
       const result = await this._doSave(baseData);
       if (!result.success) {
-        throw new Error(result.error ?? "Save failed");
+        throw new SphereError(result.error ?? "Save failed", "STORAGE_ERROR");
       }
       this.log(`Flushed successfully: CID=${result.cid}`);
     } catch (error) {
@@ -5632,10 +5742,12 @@ var IpfsStorageProvider = class {
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
-      await this.flushQueue.enqueue(() => this.executeFlush()).catch(() => {
+      await this.flushQueue.enqueue(() => this.executeFlush()).catch((err) => {
+        logger.warn("IPFS-Storage", "Flush on shutdown failed:", err);
       });
     } else if (!this.pendingBuffer.isEmpty) {
-      await this.flushQueue.enqueue(() => this.executeFlush()).catch(() => {
+      await this.flushQueue.enqueue(() => this.executeFlush()).catch((err) => {
+        logger.warn("IPFS-Storage", "Flush on shutdown failed:", err);
       });
     } else {
       await this.flushQueue.enqueue(async () => {
@@ -5689,9 +5801,7 @@ var IpfsStorageProvider = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-Storage] ${message}`);
-    }
+    logger.debug("IPFS-Storage", message);
   }
 };
 
@@ -5804,7 +5914,7 @@ var CoinGeckoPriceProvider = class {
       const allCovered = uncachedNames.every((n) => this.fetchNames.has(n));
       if (allCovered) {
         if (this.debug) {
-          console.log(`[CoinGecko] Deduplicating request, reusing in-flight fetch`);
+          logger.debug("CoinGecko", "Deduplicating request, reusing in-flight fetch");
         }
         const fetched = await this.fetchPromise;
         for (const name of uncachedNames) {
@@ -5843,7 +5953,7 @@ var CoinGeckoPriceProvider = class {
         headers["x-cg-pro-api-key"] = this.apiKey;
       }
       if (this.debug) {
-        console.log(`[CoinGecko] Fetching prices for: ${uncachedNames.join(", ")}`);
+        logger.debug("CoinGecko", `Fetching prices for: ${uncachedNames.join(", ")}`);
       }
       const response = await fetch(url, {
         headers,
@@ -5853,7 +5963,7 @@ var CoinGeckoPriceProvider = class {
         if (response.status === 429) {
           this.extendCacheOnRateLimit(uncachedNames);
         }
-        throw new Error(`CoinGecko API error: ${response.status} ${response.statusText}`);
+        throw new SphereError(`CoinGecko API error: ${response.status} ${response.statusText}`, "NETWORK_ERROR");
       }
       const data = await response.json();
       for (const [name, values] of Object.entries(data)) {
@@ -5883,12 +5993,12 @@ var CoinGeckoPriceProvider = class {
         }
       }
       if (this.debug) {
-        console.log(`[CoinGecko] Fetched ${result.size} prices`);
+        logger.debug("CoinGecko", `Fetched ${result.size} prices`);
       }
       this.saveToStorage();
     } catch (error) {
       if (this.debug) {
-        console.warn("[CoinGecko] Fetch failed, using stale cache:", error);
+        logger.warn("CoinGecko", "Fetch failed, using stale cache:", error);
       }
       for (const name of uncachedNames) {
         const stale = this.cache.get(name);
@@ -5938,7 +6048,7 @@ var CoinGeckoPriceProvider = class {
         }
       }
       if (this.debug) {
-        console.log(`[CoinGecko] Loaded ${Object.keys(data).length} prices from persistent cache`);
+        logger.debug("CoinGecko", `Loaded ${Object.keys(data).length} prices from persistent cache`);
       }
     } catch {
     }
@@ -5955,8 +6065,7 @@ var CoinGeckoPriceProvider = class {
     Promise.all([
       this.storage.set(STORAGE_KEYS_GLOBAL.PRICE_CACHE, JSON.stringify(data)),
       this.storage.set(STORAGE_KEYS_GLOBAL.PRICE_CACHE_TS, String(Date.now()))
-    ]).catch(() => {
-    });
+    ]).catch((err) => logger.debug("Price", "Cache save failed (non-critical)", err));
   }
   // ===========================================================================
   // Rate-limit handling
@@ -5975,7 +6084,7 @@ var CoinGeckoPriceProvider = class {
       }
     }
     if (this.debug) {
-      console.warn(`[CoinGecko] Rate-limited (429), extended cache TTL by ${backoffMs / 1e3}s`);
+      logger.warn("CoinGecko", `Rate-limited (429), extended cache TTL by ${backoffMs / 1e3}s`);
     }
   }
   async getPrice(tokenName) {
@@ -5993,7 +6102,7 @@ function createPriceProvider(config) {
     case "coingecko":
       return new CoinGeckoPriceProvider(config);
     default:
-      throw new Error(`Unsupported price platform: ${String(config.platform)}`);
+      throw new SphereError(`Unsupported price platform: ${String(config.platform)}`, "INVALID_CONFIG");
   }
 }
 
@@ -6218,14 +6327,12 @@ var TokenRegistry = class _TokenRegistry {
         clearTimeout(timer);
       }
       if (!response.ok) {
-        console.warn(
-          `[TokenRegistry] Remote fetch failed: HTTP ${response.status} ${response.statusText}`
-        );
+        logger.warn("TokenRegistry", `Remote fetch failed: HTTP ${response.status} ${response.statusText}`);
         return false;
       }
       const data = await response.json();
       if (!this.isValidDefinitionsArray(data)) {
-        console.warn("[TokenRegistry] Remote data is not a valid token definitions array");
+        logger.warn("TokenRegistry", "Remote data is not a valid token definitions array");
         return false;
       }
       const definitions = data;
@@ -6235,7 +6342,7 @@ var TokenRegistry = class _TokenRegistry {
       return true;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      console.warn(`[TokenRegistry] Remote refresh failed: ${message}`);
+      logger.warn("TokenRegistry", `Remote refresh failed: ${message}`);
       return false;
     }
   }
@@ -6541,6 +6648,12 @@ function resolveTokenSyncConfig(network, config) {
 }
 function createBrowserProviders(config) {
   const network = config?.network ?? "mainnet";
+  if (config?.debug !== void 0) {
+    logger.configure({ debug: config.debug });
+  }
+  if (config?.transport?.debug) logger.setTagDebug("Nostr", true);
+  if (config?.oracle?.debug) logger.setTagDebug("Aggregator", true);
+  if (config?.price?.debug) logger.setTagDebug("Price", true);
   const transportConfig = resolveTransportConfig(network, config?.transport);
   const oracleConfig = resolveOracleConfig(network, config?.oracle);
   const l1Config = resolveL1Config(network, config?.l1);