@unicitylabs/sphere-sdk 0.5.4 → 0.5.5

package/dist/impl/browser/index.js

@@ -1,6 +1,110 @@
 // impl/browser/index.ts
 import { Buffer as Buffer3 } from "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 */
@@ -205,7 +309,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() {
@@ -312,7 +416,7 @@ var LocalStorageProvider = class {
   }
   ensureConnected() {
     if (this.status !== "connected") {
-      throw new Error("LocalStorageProvider not connected");
+      throw new SphereError("LocalStorageProvider not connected", "STORAGE_ERROR");
     }
   }
   getStorageSafe() {
@@ -321,10 +425,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() {
@@ -385,7 +487,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(),
@@ -394,23 +496,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;
@@ -469,15 +571,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(
@@ -487,9 +589,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();
@@ -552,7 +654,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");
     }
   }
   // ===========================================================================
@@ -567,7 +669,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;
@@ -577,7 +679,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;
@@ -641,10 +743,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) {
@@ -681,31 +781,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;
@@ -726,7 +826,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",
@@ -776,7 +876,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,
@@ -784,7 +884,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",
@@ -795,7 +895,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",
@@ -805,7 +905,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);
@@ -874,21 +974,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;
     }
   }
@@ -904,7 +1005,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;
@@ -914,7 +1015,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;
@@ -1671,11 +1772,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);
@@ -1868,18 +1969,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() });
         }
       });
@@ -1892,11 +1993,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();
       }
@@ -1915,7 +2016,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;
@@ -1945,14 +2046,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(),
@@ -1960,7 +2061,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(),
@@ -1985,11 +2086,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(),
@@ -2026,9 +2127,9 @@ var NostrTransportProvider = class {
     const secretKey = Buffer2.from(identity.privateKey, "hex");
     this.keyManager = 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 NostrClient(this.keyManager, {
         autoReconnect: this.config.autoReconnect,
@@ -2039,16 +2140,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([
@@ -2071,7 +2172,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();
   }
@@ -2092,7 +2193,7 @@ var NostrTransportProvider = class {
     const selfPubkey = this.keyManager.getPublicKeyHex();
     const selfGiftWrap = 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",
@@ -2106,12 +2207,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);
         }
       }
     }
@@ -2170,7 +2271,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) {
@@ -2198,7 +2299,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) {
@@ -2209,11 +2310,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 = 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);
@@ -2223,7 +2324,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",
@@ -2310,7 +2411,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);
@@ -2328,7 +2432,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]) {
@@ -2484,10 +2588,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],
@@ -2495,7 +2599,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);
@@ -2508,7 +2612,7 @@ var NostrTransportProvider = class {
             this.identity.privateKey
           );
           if (decrypted) {
-            this.log("Recovered nametag:", decrypted);
+            logger.debug("Nostr", "Recovered nametag:", decrypted);
             return decrypted;
           }
         }
@@ -2516,7 +2620,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;
   }
   /**
@@ -2532,7 +2636,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);
@@ -2551,7 +2655,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");
@@ -2569,9 +2673,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;
   }
@@ -2584,18 +2688,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;
@@ -2629,7 +2733,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
@@ -2680,14 +2784,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 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:
@@ -2710,7 +2814,7 @@ var NostrTransportProvider = class {
         }
       }
     } catch (error) {
-      this.log("Failed to handle event:", error);
+      logger.debug("Nostr", "Failed to handle event:", error);
     }
   }
   /**
@@ -2725,25 +2829,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 = 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,
@@ -2758,18 +2862,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 (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,
@@ -2780,7 +2884,7 @@ var NostrTransportProvider = class {
             try {
               handler(receipt);
             } catch (e) {
-              this.log("Read receipt handler error:", e);
+              logger.debug("Nostr", "Read receipt handler error:", e);
             }
           }
         }
@@ -2800,12 +2904,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;
@@ -2813,7 +2917,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,
@@ -2823,7 +2927,7 @@ var NostrTransportProvider = class {
             try {
               handler(indicator);
             } catch (e) {
-              this.log("Typing handler error:", e);
+              logger.debug("Nostr", "Typing handler error:", e);
             }
           }
           return;
@@ -2831,7 +2935,7 @@ var NostrTransportProvider = class {
       } catch {
       }
       if (!isChatMessage(pm)) {
-        this.log("Skipping unknown message kind:", pm.kind);
+        logger.debug("Nostr", "Skipping unknown message kind:", pm.kind);
         return;
       }
       let content = pm.content;
@@ -2844,7 +2948,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.
@@ -2857,20 +2961,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) {
@@ -2888,7 +2992,7 @@ var NostrTransportProvider = class {
       try {
         await handler(transfer);
       } catch (error) {
-        this.log("Transfer handler error:", error);
+        logger.debug("Nostr", "Transfer handler error:", error);
       }
     }
   }
@@ -2911,16 +3015,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) {
@@ -2939,16 +3043,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) {
@@ -2967,7 +3071,7 @@ var NostrTransportProvider = class {
           try {
             handler(broadcast);
           } catch (error) {
-            this.log("Broadcast handler error:", error);
+            logger.debug("Nostr", "Broadcast handler error:", error);
           }
         }
       }
@@ -2977,8 +3081,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 = NostrEventClass.create(this.keyManager, {
       kind,
       content,
@@ -2996,10 +3100,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 NIP04.encryptHex(
@@ -3011,14 +3115,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 = NostrEventClass.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 Filter();
@@ -3061,7 +3165,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 Filter(filterObj);
@@ -3070,6 +3174,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, {
@@ -3099,9 +3204,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) {
@@ -3117,7 +3222,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)}`;
@@ -3126,18 +3231,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 Filter();
     walletFilter.kinds = [
@@ -3150,7 +3255,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,
@@ -3162,19 +3267,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 Filter();
     chatFilter.kinds = [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,
@@ -3186,13 +3291,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;
@@ -3222,7 +3327,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 NIP04.decryptHex(
       content,
       this.keyManager.getPrivateKeyHex(),
@@ -3252,13 +3357,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) {
@@ -3266,7 +3371,7 @@ var NostrTransportProvider = class {
       try {
         callback(event);
       } catch (error) {
-        this.log("Event callback error:", error);
+        logger.debug("Nostr", "Event callback error:", error);
       }
     }
   }
@@ -3303,11 +3408,6 @@ var NostrTransportProvider = class {
     ephemeralKeys.clear();
     return giftWrap;
   }
-  log(...args) {
-    if (this.config.debug) {
-      console.log("[NostrTransportProvider]", ...args);
-    }
-  }
 };
 
 // impl/browser/transport/index.ts
@@ -3491,7 +3591,8 @@ var UnicityAggregatorProvider = class {
         proof: response.proof,
         timestamp: Date.now()
       };
-    } catch {
+    } catch (error) {
+      logger.warn("Aggregator", "getProof failed", error);
       return null;
     }
   }
@@ -3513,7 +3614,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();
@@ -3572,7 +3673,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 waitInclusionProof(
       this.trustBase,
@@ -3594,7 +3695,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;
     }
   }
@@ -3612,7 +3714,8 @@ var UnicityAggregatorProvider = class {
         roundNumber: response.state.roundNumber,
         lastUpdated: Date.now()
       };
-    } catch {
+    } catch (error) {
+      logger.warn("Aggregator", "getTokenState failed", error);
       return null;
     }
   }
@@ -3672,11 +3775,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 {
@@ -3688,7 +3791,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) {
@@ -3700,10 +3803,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;
@@ -4292,7 +4393,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),
@@ -4338,7 +4442,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);
@@ -4384,7 +4491,8 @@ var IpfsHttpClient = class {
         }
       }
       return { cid: "", content };
-    } catch {
+    } catch (err) {
+      logger.debug("IPFS-HTTP", "IPNS gateway resolution failed", err);
       return null;
     }
   }
@@ -4449,7 +4557,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),
@@ -4526,9 +4637,7 @@ var IpfsHttpClient = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-HTTP] ${message}`);
-    }
+    logger.debug("IPFS-HTTP", message);
   }
 };
 
@@ -4972,10 +5081,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);
   }
@@ -4989,9 +5100,7 @@ var IpnsSubscriptionClient = class {
   // Internal: Logging
   // ---------------------------------------------------------------------------
   log(message) {
-    if (this.debugEnabled) {
-      console.log(`[IPNS-WS] ${message}`);
-    }
+    logger.debug("IPNS-WS", message);
   }
 };
 
@@ -5180,7 +5289,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";
@@ -5344,7 +5454,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) {
@@ -5584,10 +5694,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 () => {
@@ -5641,9 +5753,7 @@ var IpfsStorageProvider = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-Storage] ${message}`);
-    }
+    logger.debug("IPFS-Storage", message);
   }
 };
 
@@ -5756,7 +5866,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) {
@@ -5795,7 +5905,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,
@@ -5805,7 +5915,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)) {
@@ -5835,12 +5945,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);
@@ -5890,7 +6000,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 {
     }
@@ -5907,8 +6017,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
@@ -5927,7 +6036,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) {
@@ -5945,7 +6054,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");
   }
 }
 
@@ -6170,14 +6279,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;
@@ -6187,7 +6294,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;
     }
   }
@@ -6493,6 +6600,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);