@unicitylabs/sphere-sdk 0.5.3 → 0.5.5

package/dist/impl/nodejs/index.cjs

@@ -1096,6 +1096,18 @@ var bip39 = __toESM(require("bip39"), 1);
 var import_crypto_js = __toESM(require("crypto-js"), 1);
 var import_elliptic = __toESM(require("elliptic"), 1);
 
+// 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;
+  }
+};
+
 // core/bech32.ts
 var CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
 var GENERATOR = [996825010, 642813549, 513874426, 1027748829, 705979059];
@@ -1152,11 +1164,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);
@@ -1207,6 +1219,98 @@ function hexToBytes2(hex) {
   return Uint8Array.from(matches.map((x) => parseInt(x, 16)));
 }
 
+// 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];
+  }
+};
+
 // transport/websocket.ts
 var WebSocketReadyState = {
   CONNECTING: 0,
@@ -1349,18 +1453,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() });
         }
       });
@@ -1373,11 +1477,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();
       }
@@ -1396,7 +1500,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;
@@ -1426,14 +1530,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(),
@@ -1441,7 +1545,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(),
@@ -1466,11 +1570,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(),
@@ -1507,9 +1611,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,
@@ -1520,16 +1624,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([
@@ -1552,7 +1656,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();
   }
@@ -1573,7 +1677,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",
@@ -1587,12 +1691,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);
         }
       }
     }
@@ -1651,7 +1755,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) {
@@ -1679,7 +1783,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) {
@@ -1690,11 +1794,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);
@@ -1704,7 +1808,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",
@@ -1791,7 +1895,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);
@@ -1809,7 +1916,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]) {
@@ -1965,10 +2072,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],
@@ -1976,7 +2083,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);
@@ -1989,7 +2096,7 @@ var NostrTransportProvider = class {
             this.identity.privateKey
           );
           if (decrypted) {
-            this.log("Recovered nametag:", decrypted);
+            logger.debug("Nostr", "Recovered nametag:", decrypted);
             return decrypted;
           }
         }
@@ -1997,7 +2104,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;
   }
   /**
@@ -2013,7 +2120,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);
@@ -2032,7 +2139,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");
@@ -2050,9 +2157,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;
   }
@@ -2065,18 +2172,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;
@@ -2110,7 +2217,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
@@ -2161,14 +2268,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:
@@ -2191,7 +2298,7 @@ var NostrTransportProvider = class {
         }
       }
     } catch (error) {
-      this.log("Failed to handle event:", error);
+      logger.debug("Nostr", "Failed to handle event:", error);
     }
   }
   /**
@@ -2206,25 +2313,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,
@@ -2239,18 +2346,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,
@@ -2261,7 +2368,7 @@ var NostrTransportProvider = class {
             try {
               handler(receipt);
             } catch (e) {
-              this.log("Read receipt handler error:", e);
+              logger.debug("Nostr", "Read receipt handler error:", e);
             }
           }
         }
@@ -2281,12 +2388,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;
@@ -2294,7 +2401,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,
@@ -2304,7 +2411,7 @@ var NostrTransportProvider = class {
             try {
               handler(indicator);
             } catch (e) {
-              this.log("Typing handler error:", e);
+              logger.debug("Nostr", "Typing handler error:", e);
             }
           }
           return;
@@ -2312,7 +2419,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;
@@ -2325,7 +2432,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.
@@ -2338,20 +2445,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) {
@@ -2369,7 +2476,7 @@ var NostrTransportProvider = class {
       try {
         await handler(transfer);
       } catch (error) {
-        this.log("Transfer handler error:", error);
+        logger.debug("Nostr", "Transfer handler error:", error);
       }
     }
   }
@@ -2392,16 +2499,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) {
@@ -2420,16 +2527,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) {
@@ -2448,7 +2555,7 @@ var NostrTransportProvider = class {
           try {
             handler(broadcast);
           } catch (error) {
-            this.log("Broadcast handler error:", error);
+            logger.debug("Nostr", "Broadcast handler error:", error);
           }
         }
       }
@@ -2458,8 +2565,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,
@@ -2477,10 +2584,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(
@@ -2492,14 +2599,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();
@@ -2542,7 +2649,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);
@@ -2551,6 +2658,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, {
@@ -2580,9 +2688,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) {
@@ -2598,7 +2706,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)}`;
@@ -2607,18 +2715,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 = [
@@ -2631,7 +2739,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,
@@ -2643,19 +2751,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,
@@ -2667,13 +2775,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;
@@ -2703,7 +2811,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(),
@@ -2733,13 +2841,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) {
@@ -2747,7 +2855,7 @@ var NostrTransportProvider = class {
       try {
         callback(event);
       } catch (error) {
-        this.log("Event callback error:", error);
+        logger.debug("Nostr", "Event callback error:", error);
       }
     }
   }
@@ -2784,11 +2892,6 @@ var NostrTransportProvider = class {
     ephemeralKeys.clear();
     return giftWrap;
   }
-  log(...args) {
-    if (this.config.debug) {
-      console.log("[NostrTransportProvider]", ...args);
-    }
-  }
 };
 
 // impl/nodejs/transport/index.ts
@@ -2977,7 +3080,8 @@ var UnicityAggregatorProvider = class {
         proof: response.proof,
         timestamp: Date.now()
       };
-    } catch {
+    } catch (error) {
+      logger.warn("Aggregator", "getProof failed", error);
       return null;
     }
   }
@@ -2999,7 +3103,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();
@@ -3058,7 +3162,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,
@@ -3080,7 +3184,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;
     }
   }
@@ -3098,7 +3203,8 @@ var UnicityAggregatorProvider = class {
         roundNumber: response.state.roundNumber,
         lastUpdated: Date.now()
       };
-    } catch {
+    } catch (error) {
+      logger.warn("Aggregator", "getTokenState failed", error);
       return null;
     }
   }
@@ -3158,11 +3264,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 {
@@ -3174,7 +3280,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) {
@@ -3186,10 +3292,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;
@@ -3720,7 +3824,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),
@@ -3766,7 +3873,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);
@@ -3812,7 +3922,8 @@ var IpfsHttpClient = class {
         }
       }
       return { cid: "", content };
-    } catch {
+    } catch (err) {
+      logger.debug("IPFS-HTTP", "IPNS gateway resolution failed", err);
       return null;
     }
   }
@@ -3877,7 +3988,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),
@@ -3954,9 +4068,7 @@ var IpfsHttpClient = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-HTTP] ${message}`);
-    }
+    logger.debug("IPFS-HTTP", message);
   }
 };
 
@@ -4400,10 +4512,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);
   }
@@ -4417,9 +4531,7 @@ var IpnsSubscriptionClient = class {
   // Internal: Logging
   // ---------------------------------------------------------------------------
   log(message) {
-    if (this.debugEnabled) {
-      console.log(`[IPNS-WS] ${message}`);
-    }
+    logger.debug("IPNS-WS", message);
   }
 };
 
@@ -4608,7 +4720,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";
@@ -4772,7 +4885,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) {
@@ -5012,10 +5125,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 () => {
@@ -5069,9 +5184,7 @@ var IpfsStorageProvider = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-Storage] ${message}`);
-    }
+    logger.debug("IPFS-Storage", message);
   }
 };
 
@@ -5181,7 +5294,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) {
@@ -5220,7 +5333,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,
@@ -5230,7 +5343,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)) {
@@ -5260,12 +5373,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);
@@ -5315,7 +5428,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 {
     }
@@ -5332,8 +5445,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
@@ -5352,7 +5464,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) {
@@ -5370,7 +5482,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");
   }
 }
 
@@ -5595,14 +5707,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;
@@ -5612,7 +5722,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;
     }
   }
@@ -5859,6 +5969,11 @@ function resolveMarketConfig(config) {
 // impl/nodejs/index.ts
 function createNodeProviders(config) {
   const network = config?.network ?? "mainnet";
+  const globalDebug = config?.debug ?? false;
+  logger.configure({ debug: globalDebug });
+  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);