@unicitylabs/sphere-sdk 0.5.4 → 0.5.5

package/dist/index.js

@@ -14,6 +14,125 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// core/logger.ts
+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_KEY, logger;
+var init_logger = __esm({
+  "core/logger.ts"() {
+    "use strict";
+    LOGGER_KEY = "__sphere_sdk_logger__";
+    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
+function isSphereError(err) {
+  return err instanceof SphereError;
+}
+var SphereError;
+var init_errors = __esm({
+  "core/errors.ts"() {
+    "use strict";
+    SphereError = class extends Error {
+      code;
+      cause;
+      constructor(message, code, cause) {
+        super(message);
+        this.name = "SphereError";
+        this.code = code;
+        this.cause = cause;
+      }
+    };
+  }
+});
+
 // constants.ts
 function getAddressStorageKey(addressId, key) {
   return `${addressId}_${key}`;
@@ -294,11 +413,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);
@@ -351,6 +470,7 @@ var CHARSET, GENERATOR, createBech32;
 var init_bech32 = __esm({
   "core/bech32.ts"() {
     "use strict";
+    init_errors();
     CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
     GENERATOR = [996825010, 642813549, 513874426, 1027748829, 705979059];
     createBech32 = encodeBech32;
@@ -364,7 +484,7 @@ function bytesToHex(buf) {
 }
 function addressToScriptHash(address) {
   const decoded = decodeBech32(address);
-  if (!decoded) throw new Error("Invalid bech32 address: " + address);
+  if (!decoded) throw new SphereError("Invalid bech32 address: " + address, "VALIDATION_ERROR");
   const scriptHex = "0014" + bytesToHex(decoded.data);
   const sha = CryptoJS.SHA256(CryptoJS.enc.Hex.parse(scriptHex)).toString();
   return sha.match(/../g).reverse().join("");
@@ -373,6 +493,7 @@ var init_addressToScriptHash = __esm({
   "l1/addressToScriptHash.ts"() {
     "use strict";
     init_bech32();
+    init_errors();
   }
 });
 
@@ -432,7 +553,7 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
     try {
       ws = new WebSocket(endpoint);
     } catch (err) {
-      console.error("[L1] WebSocket constructor threw exception:", err);
+      logger.error("L1", "WebSocket constructor threw exception:", err);
       isConnecting = false;
       reject(err);
       return;
@@ -468,7 +589,7 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
         return;
       }
       if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
-        console.error("[L1] Max reconnect attempts reached. Giving up.");
+        logger.error("L1", "Max reconnect attempts reached. Giving up.");
         isConnecting = false;
         const error = new Error("Max reconnect attempts reached");
         connectionCallbacks.forEach((cb) => {
@@ -484,8 +605,9 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
       }
       const delay = Math.min(BASE_DELAY * Math.pow(2, reconnectAttempts), MAX_DELAY);
       reconnectAttempts++;
-      console.warn(
-        `[L1] WebSocket closed unexpectedly. Reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})...`
+      logger.warn(
+        "L1",
+        `WebSocket closed unexpectedly. Reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})...`
       );
       setTimeout(() => {
         connect(endpoint).then(() => {
@@ -502,7 +624,7 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
       }, delay);
     };
     ws.onerror = (err) => {
-      console.error("[L1] WebSocket error:", err);
+      logger.error("L1", "WebSocket error:", err);
     };
     ws.onmessage = (msg) => handleMessage(msg);
   });
@@ -560,7 +682,7 @@ async function getUtxo(address) {
   const scripthash = addressToScriptHash(address);
   const result = await rpc("blockchain.scripthash.listunspent", [scripthash]);
   if (!Array.isArray(result)) {
-    console.warn("listunspent returned non-array:", result);
+    logger.warn("L1", "listunspent returned non-array:", result);
     return [];
   }
   return result.map((u) => ({
@@ -612,7 +734,7 @@ async function getTransactionHistory(address) {
   const scriptHash = addressToScriptHash(address);
   const result = await rpc("blockchain.scripthash.get_history", [scriptHash]);
   if (!Array.isArray(result)) {
-    console.warn("get_history returned non-array:", result);
+    logger.warn("L1", "get_history returned non-array:", result);
     return [];
   }
   return result;
@@ -628,7 +750,7 @@ async function getCurrentBlockHeight() {
     const header = await rpc("blockchain.headers.subscribe", []);
     return header?.height || 0;
   } catch (err) {
-    console.error("Error getting current block height:", err);
+    logger.error("L1", "Error getting current block height:", err);
     return 0;
   }
 }
@@ -657,6 +779,7 @@ var DEFAULT_ENDPOINT, ws, isConnected, isConnecting, requestId, intentionalClose
 var init_network = __esm({
   "l1/network.ts"() {
     "use strict";
+    init_logger();
     init_addressToScriptHash();
     init_constants();
     DEFAULT_ENDPOINT = DEFAULT_ELECTRUM_URL;
@@ -679,7 +802,12 @@ var init_network = __esm({
   }
 });
 
+// core/Sphere.ts
+init_logger();
+init_errors();
+
 // modules/payments/L1PaymentsModule.ts
+init_errors();
 init_constants();
 
 // l1/index.ts
@@ -772,6 +900,7 @@ init_addressToScriptHash();
 
 // core/crypto.ts
 init_bech32();
+init_errors();
 import * as bip39 from "bip39";
 import CryptoJS2 from "crypto-js";
 import elliptic from "elliptic";
@@ -798,7 +927,7 @@ function generateMasterKey(seedHex) {
   const IR = I.substring(64);
   const masterKeyBigInt = BigInt("0x" + IL);
   if (masterKeyBigInt === 0n || masterKeyBigInt >= CURVE_ORDER) {
-    throw new Error("Invalid master key generated");
+    throw new SphereError("Invalid master key generated", "VALIDATION_ERROR");
   }
   return {
     privateKey: IL,
@@ -826,11 +955,11 @@ function deriveChildKey(parentPrivKey, parentChainCode, index) {
   const ilBigInt = BigInt("0x" + IL);
   const parentKeyBigInt = BigInt("0x" + parentPrivKey);
   if (ilBigInt >= CURVE_ORDER) {
-    throw new Error("Invalid key: IL >= curve order");
+    throw new SphereError("Invalid key: IL >= curve order", "VALIDATION_ERROR");
   }
   const childKeyBigInt = (ilBigInt + parentKeyBigInt) % CURVE_ORDER;
   if (childKeyBigInt === 0n) {
-    throw new Error("Invalid key: child key is zero");
+    throw new SphereError("Invalid key: child key is zero", "VALIDATION_ERROR");
   }
   const childPrivKey = childKeyBigInt.toString(16).padStart(64, "0");
   return {
@@ -916,7 +1045,7 @@ function randomBytes(length) {
 }
 function identityFromMnemonicSync(mnemonic, passphrase = "") {
   if (!validateMnemonic2(mnemonic)) {
-    throw new Error("Invalid mnemonic phrase");
+    throw new SphereError("Invalid mnemonic phrase", "INVALID_IDENTITY");
   }
   const seedHex = mnemonicToSeedSync2(mnemonic, passphrase);
   return generateMasterKey(seedHex);
@@ -1049,12 +1178,19 @@ function generateHDAddress(masterPriv, chainCode, index) {
 init_network();
 
 // l1/tx.ts
+init_logger();
+init_errors();
 init_network();
 init_bech32();
 import CryptoJS5 from "crypto-js";
 import elliptic2 from "elliptic";
 
+// l1/vestingState.ts
+init_logger();
+init_errors();
+
 // l1/vesting.ts
+init_logger();
 init_network();
 var VESTING_THRESHOLD = 28e4;
 var currentBlockHeight = null;
@@ -1297,7 +1433,7 @@ var VestingClassifier = class {
       await new Promise((resolve) => {
         const req = indexedDB.deleteDatabase(this.dbName);
         const timer = setTimeout(() => {
-          console.warn(`[VestingClassifier] destroy: deleteDatabase timed out for ${this.dbName}`);
+          logger.warn("L1", ` destroy: deleteDatabase timed out for ${this.dbName}`);
           resolve();
         }, 3e3);
         req.onsuccess = () => {
@@ -1309,7 +1445,7 @@ var VestingClassifier = class {
           resolve();
         };
         req.onblocked = () => {
-          console.warn(`[VestingClassifier] destroy: deleteDatabase blocked for ${this.dbName}, waiting...`);
+          logger.warn("L1", ` destroy: deleteDatabase blocked for ${this.dbName}, waiting...`);
         };
       });
     }
@@ -1327,7 +1463,7 @@ var VestingStateManager = class {
    */
   setMode(mode) {
     if (!["all", "vested", "unvested"].includes(mode)) {
-      throw new Error(`Invalid vesting mode: ${mode}`);
+      throw new SphereError(`Invalid vesting mode: ${mode}`, "VALIDATION_ERROR");
     }
     this.currentMode = mode;
   }
@@ -1364,10 +1500,10 @@ var VestingStateManager = class {
         }
       });
       if (result.errors.length > 0) {
-        console.warn(`Vesting classification errors: ${result.errors.length}`);
+        logger.warn("L1", `Vesting classification errors: ${result.errors.length}`);
         result.errors.slice(0, 5).forEach((err) => {
           const txHash = err.utxo.tx_hash || err.utxo.txid;
-          console.warn(`  ${txHash}: ${err.error}`);
+          logger.warn("L1", `  ${txHash}: ${err.error}`);
         });
       }
     } finally {
@@ -1444,6 +1580,7 @@ var VestingStateManager = class {
 var vestingState = new VestingStateManager();
 
 // l1/addressHelpers.ts
+init_errors();
 var WalletAddressHelper = class {
   /**
    * Find address by BIP32 derivation path
@@ -1489,16 +1626,17 @@ var WalletAddressHelper = class {
    */
   static add(wallet, newAddress) {
     if (!newAddress.path) {
-      throw new Error("Cannot add address without a path");
+      throw new SphereError("Cannot add address without a path", "INVALID_CONFIG");
     }
     const existing = this.findByPath(wallet, newAddress.path);
     if (existing) {
       if (existing.address !== newAddress.address) {
-        throw new Error(
+        throw new SphereError(
           `CRITICAL: Attempted to overwrite address for path ${newAddress.path}
 Existing: ${existing.address}
 New: ${newAddress.address}
-This indicates master key corruption or derivation logic error.`
+This indicates master key corruption or derivation logic error.`,
+          "INVALID_CONFIG"
         );
       }
       return wallet;
@@ -1557,9 +1695,10 @@ This indicates master key corruption or derivation logic error.`
     const uniquePaths = new Set(paths);
     if (paths.length !== uniquePaths.size) {
       const duplicates = paths.filter((p, i) => paths.indexOf(p) !== i);
-      throw new Error(
+      throw new SphereError(
         `CRITICAL: Wallet has duplicate paths: ${duplicates.join(", ")}
-This indicates data corruption. Please restore from backup.`
+This indicates data corruption. Please restore from backup.`,
+        "INVALID_CONFIG"
       );
     }
   }
@@ -1591,11 +1730,11 @@ var DUST = 546;
 var SAT = 1e8;
 function createScriptPubKey(address) {
   if (!address || typeof address !== "string") {
-    throw new Error("Invalid address: must be a string");
+    throw new SphereError("Invalid address: must be a string", "VALIDATION_ERROR");
   }
   const decoded = decodeBech32(address);
   if (!decoded) {
-    throw new Error("Invalid bech32 address: " + address);
+    throw new SphereError("Invalid bech32 address: " + address, "VALIDATION_ERROR");
   }
   const dataHex = Array.from(decoded.data).map((byte) => byte.toString(16).padStart(2, "0")).join("");
   return "0014" + dataHex;
@@ -1719,7 +1858,7 @@ function createAndSignTransaction(wallet, txPlan) {
     privateKeyHex = wallet.masterPrivateKey;
   }
   if (!privateKeyHex) {
-    throw new Error("No private key available for address: " + fromAddress);
+    throw new SphereError("No private key available for address: " + fromAddress, "INVALID_CONFIG");
   }
   const keyPair = ec2.keyFromPrivate(privateKeyHex, "hex");
   const publicKey = keyPair.getPublic(true, "hex");
@@ -1818,7 +1957,7 @@ function collectUtxosForAmount(utxoList, amountSats, recipientAddress, senderAdd
 }
 async function createTransactionPlan(wallet, toAddress, amountAlpha, fromAddress) {
   if (!decodeBech32(toAddress)) {
-    throw new Error("Invalid recipient address");
+    throw new SphereError("Invalid recipient address", "INVALID_RECIPIENT");
   }
   const defaultAddr = WalletAddressHelper.getDefault(wallet);
   const senderAddress = fromAddress || defaultAddr.address;
@@ -1827,21 +1966,21 @@ async function createTransactionPlan(wallet, toAddress, amountAlpha, fromAddress
   const currentMode = vestingState.getMode();
   if (vestingState.hasClassifiedData(senderAddress)) {
     utxos = vestingState.getFilteredUtxos(senderAddress);
-    console.log(`Using ${utxos.length} ${currentMode} UTXOs`);
+    logger.debug("L1", `Using ${utxos.length} ${currentMode} UTXOs`);
   } else {
     utxos = await getUtxo(senderAddress);
-    console.log(`Using ${utxos.length} UTXOs (vesting not classified yet)`);
+    logger.debug("L1", `Using ${utxos.length} UTXOs (vesting not classified yet)`);
   }
   if (!Array.isArray(utxos) || utxos.length === 0) {
     const modeText = currentMode !== "all" ? ` (${currentMode} coins)` : "";
-    throw new Error(`No UTXOs available${modeText} for address: ` + senderAddress);
+    throw new SphereError(`No UTXOs available${modeText} for address: ` + senderAddress, "INSUFFICIENT_BALANCE");
   }
   return collectUtxosForAmount(utxos, amountSats, toAddress, senderAddress);
 }
 async function sendAlpha(wallet, toAddress, amountAlpha, fromAddress) {
   const plan = await createTransactionPlan(wallet, toAddress, amountAlpha, fromAddress);
   if (!plan.success) {
-    throw new Error(plan.error || "Transaction planning failed");
+    throw new SphereError(plan.error || "Transaction planning failed", "TRANSFER_FAILED");
   }
   const results = [];
   for (const tx of plan.transactions) {
@@ -1908,7 +2047,7 @@ var L1PaymentsModule = class {
    */
   async ensureConnected() {
     if (this._disabled) {
-      throw new Error("L1 provider is disabled");
+      throw new SphereError("L1 provider is disabled", "NOT_INITIALIZED");
     }
     if (!isWebSocketConnected() && this._config.electrumUrl) {
       await connect(this._config.electrumUrl);
@@ -1963,8 +2102,9 @@ var L1PaymentsModule = class {
       const l1Address = await this.resolveNametagToL1Address(recipient);
       return l1Address;
     } catch {
-      throw new Error(
-        `Recipient "${recipient}" is not a valid nametag or L1 address. Use @nametag for explicit nametag or a valid alpha1... address.`
+      throw new SphereError(
+        `Recipient "${recipient}" is not a valid nametag or L1 address. Use @nametag for explicit nametag or a valid alpha1... address.`,
+        "INVALID_RECIPIENT"
       );
     }
   }
@@ -1973,15 +2113,16 @@ var L1PaymentsModule = class {
    */
   async resolveNametagToL1Address(nametag) {
     if (!this._transport?.resolve) {
-      throw new Error("Transport provider does not support resolution");
+      throw new SphereError("Transport provider does not support resolution", "TRANSPORT_ERROR");
     }
     const info = await this._transport.resolve(nametag);
     if (!info) {
-      throw new Error(`Nametag not found: ${nametag}`);
+      throw new SphereError(`Nametag not found: ${nametag}`, "INVALID_RECIPIENT");
     }
     if (!info.l1Address) {
-      throw new Error(
-        `Nametag @${nametag} does not have L1 address information. The owner needs to update their nametag registration.`
+      throw new SphereError(
+        `Nametag @${nametag} does not have L1 address information. The owner needs to update their nametag registration.`,
+        "INVALID_RECIPIENT"
       );
     }
     return info.l1Address;
@@ -2251,7 +2392,7 @@ var L1PaymentsModule = class {
   }
   ensureInitialized() {
     if (!this._initialized) {
-      throw new Error("L1PaymentsModule not initialized");
+      throw new SphereError("L1PaymentsModule not initialized", "NOT_INITIALIZED");
     }
   }
   _getWatchedAddresses() {
@@ -2276,6 +2417,7 @@ function createL1PaymentsModule(config) {
 }
 
 // modules/payments/TokenSplitCalculator.ts
+init_logger();
 import { Token as SdkToken } from "@unicitylabs/state-transition-sdk/lib/token/Token";
 import { CoinId } from "@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId";
 var TokenSplitCalculator = class {
@@ -2298,7 +2440,7 @@ var TokenSplitCalculator = class {
         const sdkToken = await SdkToken.fromJSON(parsed);
         const realAmount = this.getTokenBalance(sdkToken, targetCoinIdHex);
         if (realAmount <= 0n) {
-          console.warn(`[SplitCalculator] Token ${t.id} has 0 balance for coinId ${targetCoinIdHex}`);
+          logger.warn("TokenSplit", `Token ${t.id} has 0 balance for coinId ${targetCoinIdHex}`);
           continue;
         }
         candidates.push({
@@ -2307,14 +2449,15 @@ var TokenSplitCalculator = class {
           uiToken: t
         });
       } catch (e) {
-        console.warn("[SplitCalculator] Failed to parse token", t.id, e);
+        logger.warn("TokenSplit", "Failed to parse token", t.id, e);
       }
     }
     candidates.sort((a, b) => a.amount < b.amount ? -1 : 1);
     const totalAvailable = candidates.reduce((sum, t) => sum + t.amount, 0n);
     if (totalAvailable < targetAmount) {
-      console.error(
-        `[SplitCalculator] Insufficient funds. Available: ${totalAvailable}, Required: ${targetAmount}`
+      logger.error(
+        "TokenSplit",
+        `Insufficient funds. Available: ${totalAvailable}, Required: ${targetAmount}`
       );
       return null;
     }
@@ -2412,6 +2555,8 @@ var TokenSplitCalculator = class {
 };
 
 // modules/payments/TokenSplitExecutor.ts
+init_logger();
+init_errors();
 import { Token } from "@unicitylabs/state-transition-sdk/lib/token/Token";
 import { TokenId } from "@unicitylabs/state-transition-sdk/lib/token/TokenId";
 import { TokenState } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
@@ -2451,7 +2596,7 @@ var TokenSplitExecutor = class {
   }
   async executeSplit(tokenToSplit, splitAmount, remainderAmount, coinIdHex, recipientAddress) {
     const tokenIdHex = toHex(tokenToSplit.id.bytes);
-    console.log(`[TokenSplitExecutor] Splitting token ${tokenIdHex.slice(0, 8)}...`);
+    logger.debug("TokenSplit", `Splitting token ${tokenIdHex.slice(0, 8)}...`);
     const coinId = new CoinId2(fromHex(coinIdHex));
     const seedString = `${tokenIdHex}_${splitAmount.toString()}_${remainderAmount.toString()}`;
     const recipientTokenId = new TokenId(await sha2562(seedString));
@@ -2471,23 +2616,23 @@ var TokenSplitExecutor = class {
     const coinDataB = TokenCoinData.create([[coinId, remainderAmount]]);
     builder.createToken(senderTokenId, tokenToSplit.type, new Uint8Array(0), coinDataB, senderAddress, senderSalt, null);
     const split = await builder.build(tokenToSplit);
-    console.log("[TokenSplitExecutor] Step 1: Burning original token...");
+    logger.debug("TokenSplit", "Step 1: Burning original token...");
     const burnSalt = await sha2562(seedString + "_burn_salt");
     const burnCommitment = await split.createBurnCommitment(burnSalt, this.signingService);
     const burnResponse = await this.client.submitTransferCommitment(burnCommitment);
     if (burnResponse.status !== "SUCCESS" && burnResponse.status !== "REQUEST_ID_EXISTS") {
-      throw new Error(`Burn failed: ${burnResponse.status}`);
+      throw new SphereError(`Burn failed: ${burnResponse.status}`, "TRANSFER_FAILED");
     }
     const burnInclusionProof = await waitInclusionProof(this.trustBase, this.client, burnCommitment);
     const burnTransaction = burnCommitment.toTransaction(burnInclusionProof);
-    console.log("[TokenSplitExecutor] Original token burned.");
-    console.log("[TokenSplitExecutor] Step 2: Minting split tokens...");
+    logger.debug("TokenSplit", "Original token burned.");
+    logger.debug("TokenSplit", "Step 2: Minting split tokens...");
     const mintCommitments = await split.createSplitMintCommitments(this.trustBase, burnTransaction);
     const mintedTokensInfo = [];
     for (const commitment of mintCommitments) {
       const res = await this.client.submitMintCommitment(commitment);
       if (res.status !== "SUCCESS" && res.status !== "REQUEST_ID_EXISTS") {
-        throw new Error(`Mint split token failed: ${res.status}`);
+        throw new SphereError(`Mint split token failed: ${res.status}`, "TRANSFER_FAILED");
       }
       const proof = await waitInclusionProof(this.trustBase, this.client, commitment);
       const commTokenIdHex = toHex(commitment.transactionData.tokenId.bytes);
@@ -2500,7 +2645,7 @@ var TokenSplitExecutor = class {
         salt: commitment.transactionData.salt
       });
     }
-    console.log("[TokenSplitExecutor] Split tokens minted.");
+    logger.debug("TokenSplit", "Split tokens minted.");
     const recipientInfo = mintedTokensInfo.find((t) => t.isForRecipient);
     const senderInfo = mintedTokensInfo.find((t) => !t.isForRecipient);
     const createToken = async (info, label) => {
@@ -2508,12 +2653,12 @@ var TokenSplitExecutor = class {
       const state = new TokenState(predicate, null);
       const token = await Token.mint(this.trustBase, state, info.commitment.toTransaction(info.inclusionProof));
       const verification = await token.verify(this.trustBase);
-      if (!verification.isSuccessful) throw new Error(`Token verification failed: ${label}`);
+      if (!verification.isSuccessful) throw new SphereError(`Token verification failed: ${label}`, "TRANSFER_FAILED");
       return token;
     };
     const recipientTokenBeforeTransfer = await createToken(recipientInfo, "Recipient");
     const senderToken = await createToken(senderInfo, "Sender");
-    console.log("[TokenSplitExecutor] Step 3: Transferring to recipient...");
+    logger.debug("TokenSplit", "Step 3: Transferring to recipient...");
     const transferSalt = await sha2562(seedString + "_transfer_salt");
     const transferCommitment = await TransferCommitment.create(
       recipientTokenBeforeTransfer,
@@ -2525,11 +2670,11 @@ var TokenSplitExecutor = class {
     );
     const transferRes = await this.client.submitTransferCommitment(transferCommitment);
     if (transferRes.status !== "SUCCESS" && transferRes.status !== "REQUEST_ID_EXISTS") {
-      throw new Error(`Transfer failed: ${transferRes.status}`);
+      throw new SphereError(`Transfer failed: ${transferRes.status}`, "TRANSFER_FAILED");
     }
     const transferProof = await waitInclusionProof(this.trustBase, this.client, transferCommitment);
     const transferTx = transferCommitment.toTransaction(transferProof);
-    console.log("[TokenSplitExecutor] Split transfer complete!");
+    logger.debug("TokenSplit", "Split transfer complete!");
     return {
       tokenForRecipient: recipientTokenBeforeTransfer,
       tokenForSender: senderToken,
@@ -2539,6 +2684,7 @@ var TokenSplitExecutor = class {
 };
 
 // modules/payments/NametagMinter.ts
+init_logger();
 import { Token as Token2 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
 import { TokenId as TokenId2 } from "@unicitylabs/state-transition-sdk/lib/token/TokenId";
 import { TokenType } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
@@ -2563,10 +2709,8 @@ var NametagMinter = class {
     this.skipVerification = config.skipVerification ?? false;
     this.debug = config.debug ?? false;
   }
-  log(...args) {
-    if (this.debug) {
-      console.log("[NametagMinter]", ...args);
-    }
+  log(message, ...args) {
+    logger.debug("NametagMinter", message, ...args);
   }
   /**
    * Check if a nametag is available (not already minted)
@@ -2753,6 +2897,7 @@ function isValidTokenId(tokenId) {
 }
 
 // registry/TokenRegistry.ts
+init_logger();
 init_constants();
 var FETCH_TIMEOUT_MS = 1e4;
 var TokenRegistry = class _TokenRegistry {
@@ -2974,14 +3119,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;
@@ -2991,7 +3134,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;
     }
   }
@@ -3553,7 +3696,13 @@ function countCommittedTransactions(token) {
   }
 }
 
+// modules/payments/PaymentsModule.ts
+init_logger();
+init_errors();
+
 // modules/payments/InstantSplitExecutor.ts
+init_logger();
+init_errors();
 import { Token as Token3 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
 import { TokenId as TokenId3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenId";
 import { TokenState as TokenState3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
@@ -3609,7 +3758,7 @@ var InstantSplitExecutor = class {
   async buildSplitBundle(tokenToSplit, splitAmount, remainderAmount, coinIdHex, recipientAddress, options) {
     const splitGroupId = crypto.randomUUID();
     const tokenIdHex = toHex2(tokenToSplit.id.bytes);
-    console.log(`[InstantSplit] Building V5 bundle for token ${tokenIdHex.slice(0, 8)}...`);
+    logger.debug("InstantSplit", `Building V5 bundle for token ${tokenIdHex.slice(0, 8)}...`);
     const coinId = new CoinId3(fromHex2(coinIdHex));
     const seedString = `${tokenIdHex}_${splitAmount.toString()}_${remainderAmount.toString()}_${Date.now()}`;
     const recipientTokenId = new TokenId3(await sha2563(seedString));
@@ -3646,19 +3795,19 @@ var InstantSplitExecutor = class {
       null
     );
     const split = await builder.build(tokenToSplit);
-    console.log("[InstantSplit] Step 1: Creating and submitting burn...");
+    logger.debug("InstantSplit", "Step 1: Creating and submitting burn...");
     const burnSalt = await sha2563(seedString + "_burn_salt");
     const burnCommitment = await split.createBurnCommitment(burnSalt, this.signingService);
     const burnResponse = await this.client.submitTransferCommitment(burnCommitment);
     if (burnResponse.status !== "SUCCESS" && burnResponse.status !== "REQUEST_ID_EXISTS") {
-      throw new Error(`Burn submission failed: ${burnResponse.status}`);
+      throw new SphereError(`Burn submission failed: ${burnResponse.status}`, "TRANSFER_FAILED");
     }
-    console.log("[InstantSplit] Step 2: Waiting for burn proof...");
+    logger.debug("InstantSplit", "Step 2: Waiting for burn proof...");
     const burnProof = this.devMode ? await this.waitInclusionProofWithDevBypass(burnCommitment, options?.burnProofTimeoutMs) : await waitInclusionProof3(this.trustBase, this.client, burnCommitment);
     const burnTransaction = burnCommitment.toTransaction(burnProof);
-    console.log(`[InstantSplit] Burn proof received`);
+    logger.debug("InstantSplit", "Burn proof received");
     options?.onBurnCompleted?.(JSON.stringify(burnTransaction.toJSON()));
-    console.log("[InstantSplit] Step 3: Creating mint commitments...");
+    logger.debug("InstantSplit", "Step 3: Creating mint commitments...");
     const mintCommitments = await split.createSplitMintCommitments(this.trustBase, burnTransaction);
     const recipientIdHex = toHex2(recipientTokenId.bytes);
     const senderIdHex = toHex2(senderTokenId.bytes);
@@ -3669,9 +3818,9 @@ var InstantSplitExecutor = class {
       (c) => toHex2(c.transactionData.tokenId.bytes) === senderIdHex
     );
     if (!recipientMintCommitment || !senderMintCommitment) {
-      throw new Error("Failed to find expected mint commitments");
+      throw new SphereError("Failed to find expected mint commitments", "TRANSFER_FAILED");
     }
-    console.log("[InstantSplit] Step 4: Creating transfer commitment...");
+    logger.debug("InstantSplit", "Step 4: Creating transfer commitment...");
     const transferSalt = await sha2563(seedString + "_transfer_salt");
     const transferCommitment = await this.createTransferCommitmentFromMintData(
       recipientMintCommitment.transactionData,
@@ -3687,7 +3836,7 @@ var InstantSplitExecutor = class {
       recipientSalt
     );
     const mintedState = new TokenState3(mintedPredicate, null);
-    console.log("[InstantSplit] Step 5: Packaging V5 bundle...");
+    logger.debug("InstantSplit", "Step 5: Packaging V5 bundle...");
     const senderPubkey = toHex2(this.signingService.publicKey);
     let nametagTokenJson;
     const recipientAddressStr = recipientAddress.toString();
@@ -3759,7 +3908,7 @@ var InstantSplitExecutor = class {
         recipientAddress,
         options
       );
-      console.log("[InstantSplit] Sending via transport...");
+      logger.debug("InstantSplit", "Sending via transport...");
       const senderPubkey = toHex2(this.signingService.publicKey);
       const nostrEventId = await transport.sendTokenTransfer(recipientPubkey, {
         token: JSON.stringify(buildResult.bundle),
@@ -3771,7 +3920,7 @@ var InstantSplitExecutor = class {
         }
       });
       const criticalPathDuration = performance.now() - startTime;
-      console.log(`[InstantSplit] V5 complete in ${criticalPathDuration.toFixed(0)}ms`);
+      logger.debug("InstantSplit", `V5 complete in ${criticalPathDuration.toFixed(0)}ms`);
       options?.onNostrDelivered?.(nostrEventId);
       const backgroundPromise = buildResult.startBackground();
       return {
@@ -3785,7 +3934,7 @@ var InstantSplitExecutor = class {
     } catch (error) {
       const duration = performance.now() - startTime;
       const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error(`[InstantSplit] Failed after ${duration.toFixed(0)}ms:`, error);
+      logger.error("InstantSplit", `Failed after ${duration.toFixed(0)}ms:`, error);
       return {
         success: false,
         criticalPathDurationMs: duration,
@@ -3834,7 +3983,7 @@ var InstantSplitExecutor = class {
    * Then waits for sender's mint proof, reconstructs change token, and saves it.
    */
   submitBackgroundV5(senderMintCommitment, recipientMintCommitment, transferCommitment, context) {
-    console.log("[InstantSplit] Background: Starting parallel mint submission...");
+    logger.debug("InstantSplit", "Background: Starting parallel mint submission...");
     const startTime = performance.now();
     const submissions = Promise.all([
       this.client.submitMintCommitment(senderMintCommitment).then((res) => ({ type: "senderMint", status: res.status })).catch((err) => ({ type: "senderMint", status: "ERROR", error: err })),
@@ -3843,14 +3992,14 @@ var InstantSplitExecutor = class {
     ]);
     return submissions.then(async (results) => {
       const submitDuration = performance.now() - startTime;
-      console.log(`[InstantSplit] Background: Submissions complete in ${submitDuration.toFixed(0)}ms`);
+      logger.debug("InstantSplit", `Background: Submissions complete in ${submitDuration.toFixed(0)}ms`);
       context.onProgress?.({
         stage: "MINTS_SUBMITTED",
         message: `All commitments submitted in ${submitDuration.toFixed(0)}ms`
       });
       const senderMintResult = results.find((r) => r.type === "senderMint");
       if (senderMintResult?.status !== "SUCCESS" && senderMintResult?.status !== "REQUEST_ID_EXISTS") {
-        console.error("[InstantSplit] Background: Sender mint failed - cannot save change token");
+        logger.error("InstantSplit", "Background: Sender mint failed - cannot save change token");
         context.onProgress?.({
           stage: "FAILED",
           message: "Sender mint submission failed",
@@ -3858,12 +4007,12 @@ var InstantSplitExecutor = class {
         });
         return;
       }
-      console.log("[InstantSplit] Background: Waiting for sender mint proof...");
+      logger.debug("InstantSplit", "Background: Waiting for sender mint proof...");
       const proofStartTime = performance.now();
       try {
         const senderMintProof = this.devMode ? await this.waitInclusionProofWithDevBypass(senderMintCommitment) : await waitInclusionProof3(this.trustBase, this.client, senderMintCommitment);
         const proofDuration = performance.now() - proofStartTime;
-        console.log(`[InstantSplit] Background: Sender mint proof received in ${proofDuration.toFixed(0)}ms`);
+        logger.debug("InstantSplit", `Background: Sender mint proof received in ${proofDuration.toFixed(0)}ms`);
         context.onProgress?.({
           stage: "MINTS_PROVEN",
           message: `Mint proof received in ${proofDuration.toFixed(0)}ms`
@@ -3881,38 +4030,38 @@ var InstantSplitExecutor = class {
         if (!this.devMode) {
           const verification = await changeToken.verify(this.trustBase);
           if (!verification.isSuccessful) {
-            throw new Error(`Change token verification failed`);
+            throw new SphereError("Change token verification failed", "TRANSFER_FAILED");
           }
         }
-        console.log("[InstantSplit] Background: Change token created");
+        logger.debug("InstantSplit", "Background: Change token created");
         context.onProgress?.({
           stage: "CHANGE_TOKEN_SAVED",
           message: "Change token created and verified"
         });
         if (context.onChangeTokenCreated) {
           await context.onChangeTokenCreated(changeToken);
-          console.log("[InstantSplit] Background: Change token saved");
+          logger.debug("InstantSplit", "Background: Change token saved");
         }
         if (context.onStorageSync) {
           try {
             const syncSuccess = await context.onStorageSync();
-            console.log(`[InstantSplit] Background: Storage sync ${syncSuccess ? "completed" : "deferred"}`);
+            logger.debug("InstantSplit", `Background: Storage sync ${syncSuccess ? "completed" : "deferred"}`);
             context.onProgress?.({
               stage: "STORAGE_SYNCED",
               message: syncSuccess ? "Storage synchronized" : "Sync deferred"
             });
           } catch (syncError) {
-            console.warn("[InstantSplit] Background: Storage sync error:", syncError);
+            logger.warn("InstantSplit", "Background: Storage sync error:", syncError);
           }
         }
         const totalDuration = performance.now() - startTime;
-        console.log(`[InstantSplit] Background: Complete in ${totalDuration.toFixed(0)}ms`);
+        logger.debug("InstantSplit", `Background: Complete in ${totalDuration.toFixed(0)}ms`);
         context.onProgress?.({
           stage: "COMPLETED",
           message: `Background processing complete in ${totalDuration.toFixed(0)}ms`
         });
       } catch (proofError) {
-        console.error("[InstantSplit] Background: Failed to get sender mint proof:", proofError);
+        logger.error("InstantSplit", "Background: Failed to get sender mint proof:", proofError);
         context.onProgress?.({
           stage: "FAILED",
           message: "Failed to get mint proof",
@@ -3920,7 +4069,7 @@ var InstantSplitExecutor = class {
         });
       }
     }).catch((err) => {
-      console.error("[InstantSplit] Background: Submission batch failed:", err);
+      logger.error("InstantSplit", "Background: Submission batch failed:", err);
       context.onProgress?.({
         stage: "FAILED",
         message: "Background submission failed",
@@ -3942,7 +4091,7 @@ var InstantSplitExecutor = class {
           )
         ]);
       } catch {
-        console.log("[InstantSplit] Dev mode: Using mock proof");
+        logger.debug("InstantSplit", "Dev mode: Using mock proof");
         return {
           toJSON: () => ({ mock: true })
         };
@@ -3953,6 +4102,8 @@ var InstantSplitExecutor = class {
 };
 
 // modules/payments/InstantSplitProcessor.ts
+init_logger();
+init_errors();
 import { Token as Token4 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
 import { TokenState as TokenState4 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
 import { TokenType as TokenType2 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
@@ -4047,27 +4198,27 @@ var InstantSplitProcessor = class {
    * 5. Create recipient's final state and finalize token
    */
   async processV5Bundle(bundle, signingService, senderPubkey, options) {
-    console.log("[InstantSplitProcessor] Processing V5 bundle...");
+    logger.debug("InstantSplit", "Processing V5 bundle...");
     const startTime = performance.now();
     try {
       if (bundle.senderPubkey !== senderPubkey) {
-        console.warn("[InstantSplitProcessor] Sender pubkey mismatch (non-fatal)");
+        logger.warn("InstantSplit", "Sender pubkey mismatch (non-fatal)");
       }
       const burnTxJson = JSON.parse(bundle.burnTransaction);
       const _burnTransaction = await TransferTransaction.fromJSON(burnTxJson);
-      console.log("[InstantSplitProcessor] Burn transaction validated");
+      logger.debug("InstantSplit", "Burn transaction validated");
       const mintDataJson = JSON.parse(bundle.recipientMintData);
       const mintData = await MintTransactionData2.fromJSON(mintDataJson);
       const mintCommitment = await MintCommitment2.create(mintData);
-      console.log("[InstantSplitProcessor] Mint commitment recreated");
+      logger.debug("InstantSplit", "Mint commitment recreated");
       const mintResponse = await this.client.submitMintCommitment(mintCommitment);
       if (mintResponse.status !== "SUCCESS" && mintResponse.status !== "REQUEST_ID_EXISTS") {
-        throw new Error(`Mint submission failed: ${mintResponse.status}`);
+        throw new SphereError(`Mint submission failed: ${mintResponse.status}`, "TRANSFER_FAILED");
       }
-      console.log(`[InstantSplitProcessor] Mint submitted: ${mintResponse.status}`);
+      logger.debug("InstantSplit", `Mint submitted: ${mintResponse.status}`);
       const mintProof = this.devMode ? await this.waitInclusionProofWithDevBypass(mintCommitment, options?.proofTimeoutMs) : await waitInclusionProof4(this.trustBase, this.client, mintCommitment);
       const mintTransaction = mintCommitment.toTransaction(mintProof);
-      console.log("[InstantSplitProcessor] Mint proof received");
+      logger.debug("InstantSplit", "Mint proof received");
       const tokenType = new TokenType2(fromHex3(bundle.tokenTypeHex));
       const senderMintedStateJson = JSON.parse(bundle.mintedTokenStateJson);
       const tokenJson = {
@@ -4078,17 +4229,17 @@ var InstantSplitProcessor = class {
         nametags: []
       };
       const mintedToken = await Token4.fromJSON(tokenJson);
-      console.log("[InstantSplitProcessor] Minted token reconstructed from sender state");
+      logger.debug("InstantSplit", "Minted token reconstructed from sender state");
       const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
       const transferCommitment = await TransferCommitment3.fromJSON(transferCommitmentJson);
       const transferResponse = await this.client.submitTransferCommitment(transferCommitment);
       if (transferResponse.status !== "SUCCESS" && transferResponse.status !== "REQUEST_ID_EXISTS") {
-        throw new Error(`Transfer submission failed: ${transferResponse.status}`);
+        throw new SphereError(`Transfer submission failed: ${transferResponse.status}`, "TRANSFER_FAILED");
       }
-      console.log(`[InstantSplitProcessor] Transfer submitted: ${transferResponse.status}`);
+      logger.debug("InstantSplit", `Transfer submitted: ${transferResponse.status}`);
       const transferProof = this.devMode ? await this.waitInclusionProofWithDevBypass(transferCommitment, options?.proofTimeoutMs) : await waitInclusionProof4(this.trustBase, this.client, transferCommitment);
       const transferTransaction = transferCommitment.toTransaction(transferProof);
-      console.log("[InstantSplitProcessor] Transfer proof received");
+      logger.debug("InstantSplit", "Transfer proof received");
       const transferSalt = fromHex3(bundle.transferSaltHex);
       const finalRecipientPredicate = await UnmaskedPredicate4.create(
         mintData.tokenId,
@@ -4098,42 +4249,43 @@ var InstantSplitProcessor = class {
         transferSalt
       );
       const finalRecipientState = new TokenState4(finalRecipientPredicate, null);
-      console.log("[InstantSplitProcessor] Final recipient state created");
+      logger.debug("InstantSplit", "Final recipient state created");
       let nametagTokens = [];
       const recipientAddressStr = bundle.recipientAddressJson;
       if (recipientAddressStr.startsWith("PROXY://")) {
-        console.log("[InstantSplitProcessor] PROXY address detected, finding nametag token...");
+        logger.debug("InstantSplit", "PROXY address detected, finding nametag token...");
         if (bundle.nametagTokenJson) {
           try {
             const nametagToken = await Token4.fromJSON(JSON.parse(bundle.nametagTokenJson));
             const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
             const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
             if (proxy.address !== recipientAddressStr) {
-              console.warn("[InstantSplitProcessor] Nametag PROXY address mismatch, ignoring bundle token");
+              logger.warn("InstantSplit", "Nametag PROXY address mismatch, ignoring bundle token");
             } else {
               nametagTokens = [nametagToken];
-              console.log("[InstantSplitProcessor] Using nametag token from bundle (address validated)");
+              logger.debug("InstantSplit", "Using nametag token from bundle (address validated)");
             }
           } catch (err) {
-            console.warn("[InstantSplitProcessor] Failed to parse nametag token from bundle:", err);
+            logger.warn("InstantSplit", "Failed to parse nametag token from bundle:", err);
           }
         }
         if (nametagTokens.length === 0 && options?.findNametagToken) {
           const token = await options.findNametagToken(recipientAddressStr);
           if (token) {
             nametagTokens = [token];
-            console.log("[InstantSplitProcessor] Found nametag token via callback");
+            logger.debug("InstantSplit", "Found nametag token via callback");
           }
         }
         if (nametagTokens.length === 0 && !this.devMode) {
-          throw new Error(
-            `PROXY address transfer requires nametag token for verification. Address: ${recipientAddressStr}`
+          throw new SphereError(
+            `PROXY address transfer requires nametag token for verification. Address: ${recipientAddressStr}`,
+            "TRANSFER_FAILED"
           );
         }
       }
       let finalToken;
       if (this.devMode) {
-        console.log("[InstantSplitProcessor] Dev mode: finalizing without verification");
+        logger.debug("InstantSplit", "Dev mode: finalizing without verification");
         const tokenJson2 = mintedToken.toJSON();
         tokenJson2.state = finalRecipientState.toJSON();
         tokenJson2.transactions = [transferTransaction.toJSON()];
@@ -4147,16 +4299,16 @@ var InstantSplitProcessor = class {
           nametagTokens
         );
       }
-      console.log("[InstantSplitProcessor] Token finalized");
+      logger.debug("InstantSplit", "Token finalized");
       if (!this.devMode) {
         const verification = await finalToken.verify(this.trustBase);
         if (!verification.isSuccessful) {
-          throw new Error(`Token verification failed`);
+          throw new SphereError(`Token verification failed`, "TRANSFER_FAILED");
         }
-        console.log("[InstantSplitProcessor] Token verified");
+        logger.debug("InstantSplit", "Token verified");
       }
       const duration = performance.now() - startTime;
-      console.log(`[InstantSplitProcessor] V5 bundle processed in ${duration.toFixed(0)}ms`);
+      logger.debug("InstantSplit", `V5 bundle processed in ${duration.toFixed(0)}ms`);
       return {
         success: true,
         token: finalToken,
@@ -4165,7 +4317,7 @@ var InstantSplitProcessor = class {
     } catch (error) {
       const duration = performance.now() - startTime;
       const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error(`[InstantSplitProcessor] V5 processing failed:`, error);
+      logger.error("InstantSplit", "V5 processing failed:", error);
       return {
         success: false,
         error: errorMessage,
@@ -4191,30 +4343,30 @@ var InstantSplitProcessor = class {
         durationMs: 0
       };
     }
-    console.log("[InstantSplitProcessor] Processing V4 bundle (dev mode)...");
+    logger.debug("InstantSplit", "Processing V4 bundle (dev mode)...");
     const startTime = performance.now();
     try {
       const burnCommitmentJson = JSON.parse(bundle.burnCommitment);
       const burnCommitment = await TransferCommitment3.fromJSON(burnCommitmentJson);
       const burnResponse = await this.client.submitTransferCommitment(burnCommitment);
       if (burnResponse.status !== "SUCCESS" && burnResponse.status !== "REQUEST_ID_EXISTS") {
-        throw new Error(`Burn submission failed: ${burnResponse.status}`);
+        throw new SphereError(`Burn submission failed: ${burnResponse.status}`, "TRANSFER_FAILED");
       }
       await this.waitInclusionProofWithDevBypass(burnCommitment, options?.proofTimeoutMs);
-      console.log("[InstantSplitProcessor] V4: Burn proof received");
+      logger.debug("InstantSplit", "V4: Burn proof received");
       const mintDataJson = JSON.parse(bundle.recipientMintData);
       const mintData = await MintTransactionData2.fromJSON(mintDataJson);
       const mintCommitment = await MintCommitment2.create(mintData);
       const mintResponse = await this.client.submitMintCommitment(mintCommitment);
       if (mintResponse.status !== "SUCCESS" && mintResponse.status !== "REQUEST_ID_EXISTS") {
-        throw new Error(`Mint submission failed: ${mintResponse.status}`);
+        throw new SphereError(`Mint submission failed: ${mintResponse.status}`, "TRANSFER_FAILED");
       }
       const mintProof = await this.waitInclusionProofWithDevBypass(
         mintCommitment,
         options?.proofTimeoutMs
       );
       const mintTransaction = mintCommitment.toTransaction(mintProof);
-      console.log("[InstantSplitProcessor] V4: Mint proof received");
+      logger.debug("InstantSplit", "V4: Mint proof received");
       const tokenType = new TokenType2(fromHex3(bundle.tokenTypeHex));
       const recipientSalt = fromHex3(bundle.recipientSaltHex);
       const recipientPredicate = await UnmaskedPredicate4.create(
@@ -4233,19 +4385,19 @@ var InstantSplitProcessor = class {
         nametags: []
       };
       const mintedToken = await Token4.fromJSON(tokenJson);
-      console.log("[InstantSplitProcessor] V4: Minted token reconstructed");
+      logger.debug("InstantSplit", "V4: Minted token reconstructed");
       const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
       const transferCommitment = await TransferCommitment3.fromJSON(transferCommitmentJson);
       const transferResponse = await this.client.submitTransferCommitment(transferCommitment);
       if (transferResponse.status !== "SUCCESS" && transferResponse.status !== "REQUEST_ID_EXISTS") {
-        throw new Error(`Transfer submission failed: ${transferResponse.status}`);
+        throw new SphereError(`Transfer submission failed: ${transferResponse.status}`, "TRANSFER_FAILED");
       }
       const transferProof = await this.waitInclusionProofWithDevBypass(
         transferCommitment,
         options?.proofTimeoutMs
       );
       const transferTransaction = transferCommitment.toTransaction(transferProof);
-      console.log("[InstantSplitProcessor] V4: Transfer proof received");
+      logger.debug("InstantSplit", "V4: Transfer proof received");
       const transferSalt = fromHex3(bundle.transferSaltHex);
       const finalPredicate = await UnmaskedPredicate4.create(
         mintData.tokenId,
@@ -4259,9 +4411,9 @@ var InstantSplitProcessor = class {
       finalTokenJson.state = finalState.toJSON();
       finalTokenJson.transactions = [transferTransaction.toJSON()];
       const finalToken = await Token4.fromJSON(finalTokenJson);
-      console.log("[InstantSplitProcessor] V4: Token finalized");
+      logger.debug("InstantSplit", "V4: Token finalized");
       const duration = performance.now() - startTime;
-      console.log(`[InstantSplitProcessor] V4 bundle processed in ${duration.toFixed(0)}ms`);
+      logger.debug("InstantSplit", `V4 bundle processed in ${duration.toFixed(0)}ms`);
       return {
         success: true,
         token: finalToken,
@@ -4270,7 +4422,7 @@ var InstantSplitProcessor = class {
     } catch (error) {
       const duration = performance.now() - startTime;
       const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error(`[InstantSplitProcessor] V4 processing failed:`, error);
+      logger.error("InstantSplit", "V4 processing failed:", error);
       return {
         success: false,
         error: errorMessage,
@@ -4291,7 +4443,7 @@ var InstantSplitProcessor = class {
           )
         ]);
       } catch {
-        console.log("[InstantSplitProcessor] Dev mode: Using mock proof");
+        logger.debug("InstantSplit", "Dev mode: Using mock proof");
         return {
           toJSON: () => ({ mock: true })
         };
@@ -4476,7 +4628,7 @@ async function parseTokenInfo(tokenData) {
       }
     }
   } catch (error) {
-    console.warn("[Payments] Failed to parse token info:", error);
+    logger.warn("Payments", "Failed to parse token info:", error);
   }
   return defaultInfo;
 }
@@ -4679,11 +4831,6 @@ var PaymentsModule = class _PaymentsModule {
   }
   /** Price provider (optional) */
   priceProvider = null;
-  log(...args) {
-    if (this.moduleConfig.debug) {
-      console.log("[PaymentsModule]", ...args);
-    }
-  }
   // ===========================================================================
   // Lifecycle
   // ===========================================================================
@@ -4750,11 +4897,11 @@ var PaymentsModule = class _PaymentsModule {
             if (txfData._history && txfData._history.length > 0) {
               await this.importRemoteHistoryEntries(txfData._history);
             }
-            this.log(`Loaded metadata from provider ${id}`);
+            logger.debug("Payments", `Loaded metadata from provider ${id}`);
             break;
           }
         } catch (err) {
-          console.error(`[Payments] Failed to load from provider ${id}:`, err);
+          logger.error("Payments", `Failed to load from provider ${id}:`, err);
         }
       }
       for (const [id, token] of this.tokens) {
@@ -4763,14 +4910,14 @@ var PaymentsModule = class _PaymentsModule {
             const data = JSON.parse(token.sdkData);
             if (data?._placeholder) {
               this.tokens.delete(id);
-              console.log(`[Payments] Removed stale placeholder token: ${id}`);
+              logger.debug("Payments", `Removed stale placeholder token: ${id}`);
             }
           }
         } catch {
         }
       }
       const loadedTokens = Array.from(this.tokens.values()).map((t) => `${t.id.slice(0, 12)}(${t.status})`);
-      console.log(`[Payments][DEBUG] load(): from TXF providers: ${this.tokens.size} tokens [${loadedTokens.join(", ")}]`);
+      logger.debug("Payments", `load(): from TXF providers: ${this.tokens.size} tokens [${loadedTokens.join(", ")}]`);
       await this.loadPendingV5Tokens();
       await this.loadProcessedSplitGroupIds();
       await this.loadProcessedCombinedTransferIds();
@@ -4786,8 +4933,7 @@ var PaymentsModule = class _PaymentsModule {
     };
     this.loadedPromise = doLoad();
     await this.loadedPromise;
-    this.resolveUnconfirmed().catch(() => {
-    });
+    this.resolveUnconfirmed().catch((err) => logger.debug("Payments", "resolveUnconfirmed failed", err));
     this.scheduleResolveUnconfirmed();
   }
   /**
@@ -4840,11 +4986,11 @@ var PaymentsModule = class _PaymentsModule {
       const signingService = await this.createSigningService();
       const stClient = this.deps.oracle.getStateTransitionClient?.();
       if (!stClient) {
-        throw new Error("State transition client not available. Oracle provider must implement getStateTransitionClient()");
+        throw new SphereError("State transition client not available. Oracle provider must implement getStateTransitionClient()", "AGGREGATOR_ERROR");
       }
       const trustBase = this.deps.oracle.getTrustBase?.();
       if (!trustBase) {
-        throw new Error("Trust base not available. Oracle provider must implement getTrustBase()");
+        throw new SphereError("Trust base not available. Oracle provider must implement getTrustBase()", "AGGREGATOR_ERROR");
       }
       const calculator = new TokenSplitCalculator();
       const availableTokens = Array.from(this.tokens.values());
@@ -4854,7 +5000,7 @@ var PaymentsModule = class _PaymentsModule {
         request.coinId
       );
       if (!splitPlan) {
-        throw new Error("Insufficient balance");
+        throw new SphereError("Insufficient balance", "INSUFFICIENT_BALANCE");
       }
       const tokensToSend = splitPlan.tokensToTransferDirectly.map((t) => t.uiToken);
       if (splitPlan.tokenToSplit) {
@@ -4872,7 +5018,7 @@ var PaymentsModule = class _PaymentsModule {
       const transferMode = request.transferMode ?? "instant";
       if (transferMode === "conservative") {
         if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
-          this.log("Executing conservative split...");
+          logger.debug("Payments", "Executing conservative split...");
           const splitExecutor = new TokenSplitExecutor({
             stateTransitionClient: stClient,
             trustBase,
@@ -4900,7 +5046,7 @@ var PaymentsModule = class _PaymentsModule {
             sdkData: JSON.stringify(changeTokenData)
           };
           await this.addToken(changeUiToken);
-          this.log(`Conservative split: change token saved: ${changeUiToken.id}`);
+          logger.debug("Payments", `Conservative split: change token saved: ${changeUiToken.id}`);
           await this.deps.transport.sendTokenTransfer(recipientPubkey, {
             sourceToken: JSON.stringify(splitResult.tokenForRecipient.toJSON()),
             transferTx: JSON.stringify(splitResult.recipientTransferTx.toJSON()),
@@ -4914,15 +5060,15 @@ var PaymentsModule = class _PaymentsModule {
             method: "split",
             requestIdHex: splitRequestIdHex
           });
-          this.log(`Conservative split transfer completed`);
+          logger.debug("Payments", "Conservative split transfer completed");
         }
         for (const tokenWithAmount of splitPlan.tokensToTransferDirectly) {
           const token = tokenWithAmount.uiToken;
           const commitment = await this.createSdkCommitment(token, recipientAddress, signingService);
-          console.log(`[Payments] CONSERVATIVE: Sending direct token ${token.id.slice(0, 8)}... to ${recipientPubkey.slice(0, 8)}...`);
+          logger.debug("Payments", `CONSERVATIVE: Sending direct token ${token.id.slice(0, 8)}... to ${recipientPubkey.slice(0, 8)}...`);
           const submitResponse = await stClient.submitTransferCommitment(commitment);
           if (submitResponse.status !== "SUCCESS" && submitResponse.status !== "REQUEST_ID_EXISTS") {
-            throw new Error(`Transfer commitment failed: ${submitResponse.status}`);
+            throw new SphereError(`Transfer commitment failed: ${submitResponse.status}`, "TRANSFER_FAILED");
           }
           const inclusionProof = await waitInclusionProof5(trustBase, stClient, commitment);
           const transferTx = commitment.toTransaction(inclusionProof);
@@ -4931,7 +5077,7 @@ var PaymentsModule = class _PaymentsModule {
             transferTx: JSON.stringify(transferTx.toJSON()),
             memo: request.memo
           });
-          console.log(`[Payments] CONSERVATIVE: Direct token sent successfully`);
+          logger.debug("Payments", "CONSERVATIVE: Direct token sent successfully");
           const requestIdBytes = commitment.requestId;
           const requestIdHex = requestIdBytes instanceof Uint8Array ? Array.from(requestIdBytes).map((b) => b.toString(16).padStart(2, "0")).join("") : String(requestIdBytes);
           result.tokenTransfers.push({
@@ -4939,7 +5085,7 @@ var PaymentsModule = class _PaymentsModule {
             method: "direct",
             requestIdHex
           });
-          this.log(`Token ${token.id} sent via CONSERVATIVE, requestId: ${requestIdHex}`);
+          logger.debug("Payments", `Token ${token.id} sent via CONSERVATIVE, requestId: ${requestIdHex}`);
           await this.removeToken(token.id);
         }
       } else {
@@ -4948,7 +5094,7 @@ var PaymentsModule = class _PaymentsModule {
         let changeTokenPlaceholderId = null;
         let builtSplit = null;
         if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
-          this.log("Building instant split bundle...");
+          logger.debug("Payments", "Building instant split bundle...");
           const executor = new InstantSplitExecutor({
             stateTransitionClient: stClient,
             trustBase,
@@ -4982,7 +5128,7 @@ var PaymentsModule = class _PaymentsModule {
                   sdkData: JSON.stringify(changeTokenData)
                 };
                 await this.addToken(uiToken);
-                this.log(`Change token saved via background: ${uiToken.id}`);
+                logger.debug("Payments", `Change token saved via background: ${uiToken.id}`);
               },
               onStorageSync: async () => {
                 await this.save();
@@ -4990,7 +5136,7 @@ var PaymentsModule = class _PaymentsModule {
               }
             }
           );
-          this.log(`Split bundle built: splitGroupId=${builtSplit.splitGroupId}`);
+          logger.debug("Payments", `Split bundle built: splitGroupId=${builtSplit.splitGroupId}`);
         }
         const directCommitments = await Promise.all(
           splitPlan.tokensToTransferDirectly.map(
@@ -5017,8 +5163,9 @@ var PaymentsModule = class _PaymentsModule {
           senderPubkey,
           memo: request.memo
         };
-        console.log(
-          `[Payments] Sending V6 combined bundle: transfer=${result.id.slice(0, 8)}... split=${!!builtSplit} direct=${directTokenEntries.length}`
+        logger.debug(
+          "Payments",
+          `Sending V6 combined bundle: transfer=${result.id.slice(0, 8)}... split=${!!builtSplit} direct=${directTokenEntries.length}`
         );
         await this.deps.transport.sendTokenTransfer(recipientPubkey, {
           token: JSON.stringify(combinedBundle),
@@ -5026,7 +5173,7 @@ var PaymentsModule = class _PaymentsModule {
           memo: request.memo,
           sender: { transportPubkey: senderPubkey }
         });
-        console.log(`[Payments] V6 combined bundle sent successfully`);
+        logger.debug("Payments", "V6 combined bundle sent successfully");
         if (builtSplit) {
           const bgPromise = builtSplit.startBackground();
           this.pendingBackgroundTasks.push(bgPromise);
@@ -5047,11 +5194,11 @@ var PaymentsModule = class _PaymentsModule {
             sdkData: JSON.stringify({ _placeholder: true })
           };
           this.tokens.set(placeholder.id, placeholder);
-          this.log(`Placeholder change token created: ${placeholder.id} (${placeholder.amount})`);
+          logger.debug("Payments", `Placeholder change token created: ${placeholder.id} (${placeholder.amount})`);
         }
         for (const commitment of directCommitments) {
           stClient.submitTransferCommitment(commitment).catch(
-            (err) => console.error("[Payments] Background commitment submit failed:", err)
+            (err) => logger.error("Payments", "Background commitment submit failed:", err)
           );
         }
         if (splitPlan.requiresSplit && splitPlan.tokenToSplit) {
@@ -5074,7 +5221,7 @@ var PaymentsModule = class _PaymentsModule {
           });
           await this.removeToken(token.id);
         }
-        this.log(`V6 combined transfer completed`);
+        logger.debug("Payments", "V6 combined transfer completed");
       }
       result.status = "delivered";
       await this.save();
@@ -5165,11 +5312,11 @@ var PaymentsModule = class _PaymentsModule {
       const signingService = await this.createSigningService();
       const stClient = this.deps.oracle.getStateTransitionClient?.();
       if (!stClient) {
-        throw new Error("State transition client not available");
+        throw new SphereError("State transition client not available", "AGGREGATOR_ERROR");
       }
       const trustBase = this.deps.oracle.getTrustBase?.();
       if (!trustBase) {
-        throw new Error("Trust base not available");
+        throw new SphereError("Trust base not available", "AGGREGATOR_ERROR");
       }
       const calculator = new TokenSplitCalculator();
       const availableTokens = Array.from(this.tokens.values());
@@ -5179,10 +5326,10 @@ var PaymentsModule = class _PaymentsModule {
         request.coinId
       );
       if (!splitPlan) {
-        throw new Error("Insufficient balance");
+        throw new SphereError("Insufficient balance", "INSUFFICIENT_BALANCE");
       }
       if (!splitPlan.requiresSplit || !splitPlan.tokenToSplit) {
-        this.log("No split required, falling back to standard send()");
+        logger.debug("Payments", "No split required, falling back to standard send()");
         const result2 = await this.send(request);
         return {
           success: result2.status === "completed",
@@ -5190,7 +5337,7 @@ var PaymentsModule = class _PaymentsModule {
           error: result2.error
         };
       }
-      this.log(`InstantSplit: amount=${splitPlan.splitAmount}, remainder=${splitPlan.remainderAmount}`);
+      logger.debug("Payments", `InstantSplit: amount=${splitPlan.splitAmount}, remainder=${splitPlan.remainderAmount}`);
       const tokenToSplit = splitPlan.tokenToSplit.uiToken;
       tokenToSplit.status = "transferring";
       this.tokens.set(tokenToSplit.id, tokenToSplit);
@@ -5228,7 +5375,7 @@ var PaymentsModule = class _PaymentsModule {
               sdkData: JSON.stringify(changeTokenData)
             };
             await this.addToken(uiToken);
-            this.log(`Change token saved via background: ${uiToken.id}`);
+            logger.debug("Payments", `Change token saved via background: ${uiToken.id}`);
           },
           onStorageSync: async () => {
             await this.save();
@@ -5283,7 +5430,7 @@ var PaymentsModule = class _PaymentsModule {
   async saveUnconfirmedV5Token(bundle, senderPubkey, deferPersistence = false) {
     const deterministicId = `v5split_${bundle.splitGroupId}`;
     if (this.tokens.has(deterministicId) || this.processedSplitGroupIds.has(bundle.splitGroupId)) {
-      console.log(`[Payments] V5 bundle ${bundle.splitGroupId.slice(0, 12)}... already processed, skipping`);
+      logger.debug("Payments", `V5 bundle ${bundle.splitGroupId.slice(0, 12)}... already processed, skipping`);
       return null;
     }
     const registry = TokenRegistry.getInstance();
@@ -5333,7 +5480,7 @@ var PaymentsModule = class _PaymentsModule {
     const nostrTokenId = extractTokenIdFromSdkData(sdkData);
     const nostrStateHash = extractStateHashFromSdkData(sdkData);
     if (nostrTokenId && nostrStateHash && this.isStateTombstoned(nostrTokenId, nostrStateHash)) {
-      this.log(`NOSTR-FIRST: Rejecting tombstoned token ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`);
+      logger.debug("Payments", `NOSTR-FIRST: Rejecting tombstoned token ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`);
       return null;
     }
     if (nostrTokenId) {
@@ -5342,14 +5489,16 @@ var PaymentsModule = class _PaymentsModule {
         if (existingTokenId !== nostrTokenId) continue;
         const existingStateHash = extractStateHashFromSdkData(existing.sdkData);
         if (nostrStateHash && existingStateHash === nostrStateHash) {
-          console.log(
-            `[Payments] NOSTR-FIRST: Skipping duplicate token state ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`
+          logger.debug(
+            "Payments",
+            `NOSTR-FIRST: Skipping duplicate token state ${nostrTokenId.slice(0, 8)}..._${nostrStateHash.slice(0, 8)}...`
           );
           return null;
         }
         if (!skipGenesisDedup) {
-          console.log(
-            `[Payments] NOSTR-FIRST: Skipping replay of finalized token ${nostrTokenId.slice(0, 8)}...`
+          logger.debug(
+            "Payments",
+            `NOSTR-FIRST: Skipping replay of finalized token ${nostrTokenId.slice(0, 8)}...`
           );
           return null;
         }
@@ -5381,7 +5530,7 @@ var PaymentsModule = class _PaymentsModule {
         const stClient = this.deps.oracle.getStateTransitionClient?.();
         if (stClient) {
           const response = await stClient.submitTransferCommitment(commitment);
-          this.log(`NOSTR-FIRST recipient commitment submit: ${response.status}`);
+          logger.debug("Payments", `NOSTR-FIRST recipient commitment submit: ${response.status}`);
         }
       }
       this.addProofPollingJob({
@@ -5396,7 +5545,7 @@ var PaymentsModule = class _PaymentsModule {
         }
       });
     } catch (err) {
-      console.error("[Payments] Failed to parse commitment for proof polling:", err);
+      logger.error("Payments", "Failed to parse commitment for proof polling:", err);
     }
     return token;
   }
@@ -5418,11 +5567,12 @@ var PaymentsModule = class _PaymentsModule {
       await this.loadedPromise;
     }
     if (this.processedCombinedTransferIds.has(bundle.transferId)) {
-      console.log(`[Payments] V6 combined transfer ${bundle.transferId.slice(0, 12)}... already processed, skipping`);
+      logger.debug("Payments", `V6 combined transfer ${bundle.transferId.slice(0, 12)}... already processed, skipping`);
       return;
     }
-    console.log(
-      `[Payments] Processing V6 combined transfer ${bundle.transferId.slice(0, 12)}... (split=${!!bundle.splitBundle}, direct=${bundle.directTokens.length})`
+    logger.debug(
+      "Payments",
+      `Processing V6 combined transfer ${bundle.transferId.slice(0, 12)}... (split=${!!bundle.splitBundle}, direct=${bundle.directTokens.length})`
     );
     const allTokens = [];
     const tokenBreakdown = [];
@@ -5436,7 +5586,7 @@ var PaymentsModule = class _PaymentsModule {
         allTokens.push(splitToken);
         tokenBreakdown.push({ id: splitToken.id, amount: splitToken.amount, source: "split" });
       } else {
-        console.warn(`[Payments] V6: split token was deduped/failed \u2014 amount=${bundle.splitBundle.amount}`);
+        logger.warn("Payments", `V6: split token was deduped/failed \u2014 amount=${bundle.splitBundle.amount}`);
       }
     }
     const directResults = await Promise.all(
@@ -5451,13 +5601,14 @@ var PaymentsModule = class _PaymentsModule {
         tokenBreakdown.push({ id: token.id, amount: token.amount, source: "direct" });
       } else {
         const entry = bundle.directTokens[i];
-        console.warn(
-          `[Payments] V6: direct token #${i} dropped (amount=${entry.amount}, tokenId=${entry.tokenId?.slice(0, 12) ?? "N/A"})`
+        logger.warn(
+          "Payments",
+          `V6: direct token #${i} dropped (amount=${entry.amount}, tokenId=${entry.tokenId?.slice(0, 12) ?? "N/A"})`
         );
       }
     }
     if (allTokens.length === 0) {
-      console.log(`[Payments] V6 combined transfer: all tokens deduped, nothing to save`);
+      logger.debug("Payments", "V6 combined transfer: all tokens deduped, nothing to save");
       return;
     }
     this.processedCombinedTransferIds.add(bundle.transferId);
@@ -5473,7 +5624,7 @@ var PaymentsModule = class _PaymentsModule {
         TransferCommitment4.fromJSON(commitment).then(
           (c) => stClient.submitTransferCommitment(c)
         ).catch(
-          (err) => console.error("[Payments] V6 background commitment submit failed:", err)
+          (err) => logger.error("Payments", "V6 background commitment submit failed:", err)
         );
       }
     }
@@ -5500,8 +5651,7 @@ var PaymentsModule = class _PaymentsModule {
       tokenIds: tokenBreakdown
     });
     if (bundle.splitBundle) {
-      this.resolveUnconfirmed().catch(() => {
-      });
+      this.resolveUnconfirmed().catch((err) => logger.debug("Payments", "resolveUnconfirmed failed", err));
       this.scheduleResolveUnconfirmed();
     }
   }
@@ -5579,8 +5729,7 @@ var PaymentsModule = class _PaymentsModule {
         receivedAt: Date.now()
       });
       await this.save();
-      this.resolveUnconfirmed().catch(() => {
-      });
+      this.resolveUnconfirmed().catch((err) => logger.debug("Payments", "resolveUnconfirmed failed", err));
       this.scheduleResolveUnconfirmed();
       return { success: true, durationMs: 0 };
     } catch (error) {
@@ -5601,11 +5750,11 @@ var PaymentsModule = class _PaymentsModule {
       const signingService = await this.createSigningService();
       const stClient = this.deps.oracle.getStateTransitionClient?.();
       if (!stClient) {
-        throw new Error("State transition client not available");
+        throw new SphereError("State transition client not available", "AGGREGATOR_ERROR");
       }
       const trustBase = this.deps.oracle.getTrustBase?.();
       if (!trustBase) {
-        throw new Error("Trust base not available");
+        throw new SphereError("Trust base not available", "AGGREGATOR_ERROR");
       }
       const devMode = this.deps.oracle.isDevMode?.() ?? false;
       const processor = new InstantSplitProcessor({
@@ -5628,10 +5777,10 @@ var PaymentsModule = class _PaymentsModule {
                 if (proxy.address === proxyAddress) {
                   return nametagToken;
                 }
-                this.log(`Nametag PROXY address mismatch: ${proxy.address} !== ${proxyAddress}`);
+                logger.debug("Payments", `Nametag PROXY address mismatch: ${proxy.address} !== ${proxyAddress}`);
                 return null;
               } catch (err) {
-                this.log("Failed to parse nametag token:", err);
+                logger.debug("Payments", "Failed to parse nametag token:", err);
                 return null;
               }
             }
@@ -5739,7 +5888,7 @@ var PaymentsModule = class _PaymentsModule {
         status: "pending"
       };
       this.outgoingPaymentRequests.set(requestId2, outgoingRequest);
-      this.log(`Payment request sent: ${eventId}`);
+      logger.debug("Payments", `Payment request sent: ${eventId}`);
       return {
         success: true,
         requestId: requestId2,
@@ -5747,7 +5896,7 @@ var PaymentsModule = class _PaymentsModule {
       };
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error);
-      this.log(`Failed to send payment request: ${errorMsg}`);
+      logger.debug("Payments", `Failed to send payment request: ${errorMsg}`);
       return {
         success: false,
         error: errorMsg
@@ -5836,10 +5985,10 @@ var PaymentsModule = class _PaymentsModule {
   async payPaymentRequest(requestId2, memo) {
     const request = this.paymentRequests.find((r) => r.id === requestId2);
     if (!request) {
-      throw new Error(`Payment request not found: ${requestId2}`);
+      throw new SphereError(`Payment request not found: ${requestId2}`, "VALIDATION_ERROR");
     }
     if (request.status !== "pending" && request.status !== "accepted") {
-      throw new Error(`Payment request is not pending or accepted: ${request.status}`);
+      throw new SphereError(`Payment request is not pending or accepted: ${request.status}`, "VALIDATION_ERROR");
     }
     this.updatePaymentRequestStatus(requestId2, "accepted");
     try {
@@ -5894,10 +6043,10 @@ var PaymentsModule = class _PaymentsModule {
       try {
         handler(request);
       } catch (error) {
-        this.log("Payment request handler error:", error);
+        logger.debug("Payments", "Payment request handler error:", error);
       }
     }
-    this.log(`Incoming payment request: ${request.id} for ${request.amount} ${request.symbol}`);
+    logger.debug("Payments", `Incoming payment request: ${request.id} for ${request.amount} ${request.symbol}`);
   }
   // ===========================================================================
   // Public API - Outgoing Payment Requests
@@ -6016,10 +6165,10 @@ var PaymentsModule = class _PaymentsModule {
       try {
         handler(response);
       } catch (error) {
-        this.log("Payment request response handler error:", error);
+        logger.debug("Payments", "Payment request response handler error:", error);
       }
     }
-    this.log(`Received payment request response: ${response.id} type: ${response.responseType}`);
+    logger.debug("Payments", `Received payment request response: ${response.id} type: ${response.responseType}`);
   }
   /**
    * Send a response to a payment request (used internally by accept/reject/pay methods)
@@ -6028,7 +6177,7 @@ var PaymentsModule = class _PaymentsModule {
     const request = this.paymentRequests.find((r) => r.id === requestId2);
     if (!request) return;
     if (!this.deps?.transport.sendPaymentRequestResponse) {
-      this.log("Transport does not support sendPaymentRequestResponse");
+      logger.debug("Payments", "Transport does not support sendPaymentRequestResponse");
       return;
     }
     try {
@@ -6039,9 +6188,9 @@ var PaymentsModule = class _PaymentsModule {
         transferId
       };
       await this.deps.transport.sendPaymentRequestResponse(request.senderPubkey, payload);
-      this.log(`Sent payment request response: ${responseType} for ${requestId2}`);
+      logger.debug("Payments", `Sent payment request response: ${responseType} for ${requestId2}`);
     } catch (error) {
-      this.log("Failed to send payment request response:", error);
+      logger.debug("Payments", "Failed to send payment request response:", error);
     }
   }
   // ===========================================================================
@@ -6065,7 +6214,7 @@ var PaymentsModule = class _PaymentsModule {
   async receive(options, callback) {
     this.ensureInitialized();
     if (!this.deps.transport.fetchPendingEvents) {
-      throw new Error("Transport provider does not support fetchPendingEvents");
+      throw new SphereError("Transport provider does not support fetchPendingEvents", "TRANSPORT_ERROR");
     }
     const opts = options ?? {};
     const tokensBefore = new Set(this.tokens.keys());
@@ -6212,7 +6361,7 @@ var PaymentsModule = class _PaymentsModule {
         });
       }
     } catch (error) {
-      console.warn("[Payments] Failed to fetch prices, returning assets without price data:", error);
+      logger.warn("Payments", "Failed to fetch prices, returning assets without price data:", error);
     }
     return rawAssets;
   }
@@ -6334,24 +6483,24 @@ var PaymentsModule = class _PaymentsModule {
     const stClient = this.deps.oracle.getStateTransitionClient?.();
     const trustBase = this.deps.oracle.getTrustBase?.();
     if (!stClient || !trustBase) {
-      console.log(`[V5-RESOLVE] resolveUnconfirmed: EARLY EXIT \u2014 stClient=${!!stClient} trustBase=${!!trustBase}`);
+      logger.debug("Payments", `[V5-RESOLVE] resolveUnconfirmed: EARLY EXIT \u2014 stClient=${!!stClient} trustBase=${!!trustBase}`);
       return result;
     }
     const signingService = await this.createSigningService();
     const submittedCount = Array.from(this.tokens.values()).filter((t) => t.status === "submitted").length;
-    console.log(`[V5-RESOLVE] resolveUnconfirmed: ${submittedCount} submitted token(s) to process`);
+    logger.debug("Payments", `[V5-RESOLVE] resolveUnconfirmed: ${submittedCount} submitted token(s) to process`);
     for (const [tokenId, token] of this.tokens) {
       if (token.status !== "submitted") continue;
       const pending2 = this.parsePendingFinalization(token.sdkData);
       if (!pending2) {
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 16)}: no pending finalization metadata, skipping`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 16)}: no pending finalization metadata, skipping`);
         result.stillPending++;
         continue;
       }
       if (pending2.type === "v5_bundle") {
-        console.log(`[V5-RESOLVE] Processing ${tokenId.slice(0, 16)}... stage=${pending2.stage} attempt=${pending2.attemptCount}`);
+        logger.debug("Payments", `[V5-RESOLVE] Processing ${tokenId.slice(0, 16)}... stage=${pending2.stage} attempt=${pending2.attemptCount}`);
         const progress = await this.resolveV5Token(tokenId, token, pending2, stClient, trustBase, signingService);
-        console.log(`[V5-RESOLVE] Result for ${tokenId.slice(0, 16)}...: ${progress} (stage now: ${pending2.stage})`);
+        logger.debug("Payments", `[V5-RESOLVE] Result for ${tokenId.slice(0, 16)}...: ${progress} (stage now: ${pending2.stage})`);
         result.details.push({ tokenId, stage: pending2.stage, status: progress });
         if (progress === "resolved") result.resolved++;
         else if (progress === "failed") result.failed++;
@@ -6359,7 +6508,7 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
     if (result.resolved > 0 || result.failed > 0 || result.stillPending > 0) {
-      console.log(`[V5-RESOLVE] Saving: resolved=${result.resolved} failed=${result.failed} stillPending=${result.stillPending}`);
+      logger.debug("Payments", `[V5-RESOLVE] Saving: resolved=${result.resolved} failed=${result.failed} stillPending=${result.stillPending}`);
       await this.save();
     }
     return result;
@@ -6375,19 +6524,19 @@ var PaymentsModule = class _PaymentsModule {
       (t) => t.status === "submitted"
     );
     if (!hasUnconfirmed) {
-      console.log(`[V5-RESOLVE] scheduleResolveUnconfirmed: no submitted tokens, not starting timer`);
+      logger.debug("Payments", "[V5-RESOLVE] scheduleResolveUnconfirmed: no submitted tokens, not starting timer");
       return;
     }
-    console.log(`[V5-RESOLVE] scheduleResolveUnconfirmed: starting periodic retry (every ${_PaymentsModule.RESOLVE_UNCONFIRMED_INTERVAL_MS}ms)`);
+    logger.debug("Payments", `[V5-RESOLVE] scheduleResolveUnconfirmed: starting periodic retry (every ${_PaymentsModule.RESOLVE_UNCONFIRMED_INTERVAL_MS}ms)`);
     this.resolveUnconfirmedTimer = setInterval(async () => {
       try {
         const result = await this.resolveUnconfirmed();
         if (result.stillPending === 0) {
-          console.log(`[V5-RESOLVE] All tokens resolved, stopping periodic retry`);
+          logger.debug("Payments", "[V5-RESOLVE] All tokens resolved, stopping periodic retry");
           this.stopResolveUnconfirmedPolling();
         }
       } catch (err) {
-        console.log(`[V5-RESOLVE] Periodic retry error:`, err);
+        logger.debug("Payments", "[V5-RESOLVE] Periodic retry error:", err);
       }
     }, _PaymentsModule.RESOLVE_UNCONFIRMED_INTERVAL_MS);
   }
@@ -6409,57 +6558,57 @@ var PaymentsModule = class _PaymentsModule {
     pending2.lastAttemptAt = Date.now();
     try {
       if (pending2.stage === "RECEIVED") {
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: RECEIVED \u2192 submitting mint commitment...`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: RECEIVED \u2192 submitting mint commitment...`);
         const mintDataJson = JSON.parse(bundle.recipientMintData);
         const mintData = await MintTransactionData3.fromJSON(mintDataJson);
         const mintCommitment = await MintCommitment3.create(mintData);
         const mintResponse = await stClient.submitMintCommitment(mintCommitment);
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint response status=${mintResponse.status}`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint response status=${mintResponse.status}`);
         if (mintResponse.status !== "SUCCESS" && mintResponse.status !== "REQUEST_ID_EXISTS") {
-          throw new Error(`Mint submission failed: ${mintResponse.status}`);
+          throw new SphereError(`Mint submission failed: ${mintResponse.status}`, "TRANSFER_FAILED");
         }
         pending2.stage = "MINT_SUBMITTED";
         this.updatePendingFinalization(token, pending2);
       }
       if (pending2.stage === "MINT_SUBMITTED") {
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: MINT_SUBMITTED \u2192 checking mint proof...`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: MINT_SUBMITTED \u2192 checking mint proof...`);
         const mintDataJson = JSON.parse(bundle.recipientMintData);
         const mintData = await MintTransactionData3.fromJSON(mintDataJson);
         const mintCommitment = await MintCommitment3.create(mintData);
         const proof = await this.quickProofCheck(stClient, trustBase, mintCommitment);
         if (!proof) {
-          console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint proof not yet available, staying MINT_SUBMITTED`);
+          logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint proof not yet available, staying MINT_SUBMITTED`);
           this.updatePendingFinalization(token, pending2);
           return "pending";
         }
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint proof obtained!`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: mint proof obtained!`);
         pending2.mintProofJson = JSON.stringify(proof);
         pending2.stage = "MINT_PROVEN";
         this.updatePendingFinalization(token, pending2);
       }
       if (pending2.stage === "MINT_PROVEN") {
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: MINT_PROVEN \u2192 submitting transfer commitment...`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: MINT_PROVEN \u2192 submitting transfer commitment...`);
         const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
         const transferCommitment = await TransferCommitment4.fromJSON(transferCommitmentJson);
         const transferResponse = await stClient.submitTransferCommitment(transferCommitment);
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer response status=${transferResponse.status}`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer response status=${transferResponse.status}`);
         if (transferResponse.status !== "SUCCESS" && transferResponse.status !== "REQUEST_ID_EXISTS") {
-          throw new Error(`Transfer submission failed: ${transferResponse.status}`);
+          throw new SphereError(`Transfer submission failed: ${transferResponse.status}`, "TRANSFER_FAILED");
         }
         pending2.stage = "TRANSFER_SUBMITTED";
         this.updatePendingFinalization(token, pending2);
       }
       if (pending2.stage === "TRANSFER_SUBMITTED") {
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: TRANSFER_SUBMITTED \u2192 checking transfer proof...`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: TRANSFER_SUBMITTED \u2192 checking transfer proof...`);
         const transferCommitmentJson = JSON.parse(bundle.transferCommitment);
         const transferCommitment = await TransferCommitment4.fromJSON(transferCommitmentJson);
         const proof = await this.quickProofCheck(stClient, trustBase, transferCommitment);
         if (!proof) {
-          console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer proof not yet available, staying TRANSFER_SUBMITTED`);
+          logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer proof not yet available, staying TRANSFER_SUBMITTED`);
           this.updatePendingFinalization(token, pending2);
           return "pending";
         }
-        console.log(`[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer proof obtained! Finalizing...`);
+        logger.debug("Payments", `[V5-RESOLVE] ${tokenId.slice(0, 12)}: transfer proof obtained! Finalizing...`);
         const finalizedToken = await this.finalizeFromV5Bundle(bundle, pending2, signingService, stClient, trustBase);
         const confirmedToken = {
           id: token.id,
@@ -6481,12 +6630,12 @@ var PaymentsModule = class _PaymentsModule {
           tokens: [confirmedToken],
           tokenTransfers: []
         });
-        this.log(`V5 token resolved: ${tokenId.slice(0, 8)}...`);
+        logger.debug("Payments", `V5 token resolved: ${tokenId.slice(0, 8)}...`);
         return "resolved";
       }
       return "pending";
     } catch (error) {
-      console.error(`[Payments] resolveV5Token failed for ${tokenId.slice(0, 8)}:`, error);
+      logger.error("Payments", `resolveV5Token failed for ${tokenId.slice(0, 8)}:`, error);
       if (pending2.attemptCount > 50) {
         token.status = "invalid";
         token.updatedAt = Date.now();
@@ -6623,19 +6772,19 @@ var PaymentsModule = class _PaymentsModule {
     }
     if (pendingTokens.length > 0) {
       const json = JSON.stringify(pendingTokens);
-      this.log(`[V5-PERSIST] Saving ${pendingTokens.length} pending V5 token(s): ${pendingTokens.map((t) => t.id.slice(0, 16)).join(", ")} (${json.length} bytes)`);
+      logger.debug("Payments", `[V5-PERSIST] Saving ${pendingTokens.length} pending V5 token(s): ${pendingTokens.map((t) => t.id.slice(0, 16)).join(", ")} (${json.length} bytes)`);
       await this.deps.storage.set(
         STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS,
         json
       );
       const verify = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS);
       if (!verify) {
-        console.error("[Payments][V5-PERSIST] CRITICAL: KV write succeeded but read-back is empty!");
+        logger.error("Payments", "[V5-PERSIST] CRITICAL: KV write succeeded but read-back is empty!");
       } else {
-        this.log(`[V5-PERSIST] Verified: read-back ${verify.length} bytes`);
+        logger.debug("Payments", `[V5-PERSIST] Verified: read-back ${verify.length} bytes`);
       }
     } else {
-      this.log(`[V5-PERSIST] No pending V5 tokens to save (total tokens: ${this.tokens.size}), clearing KV`);
+      logger.debug("Payments", `[V5-PERSIST] No pending V5 tokens to save (total tokens: ${this.tokens.size}), clearing KV`);
       await this.deps.storage.set(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS, "");
     }
   }
@@ -6645,21 +6794,21 @@ var PaymentsModule = class _PaymentsModule {
    */
   async loadPendingV5Tokens() {
     const data = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_V5_TOKENS);
-    this.log(`[V5-PERSIST] loadPendingV5Tokens: KV data = ${data ? `${data.length} bytes` : "null/empty"}`);
+    logger.debug("Payments", `[V5-PERSIST] loadPendingV5Tokens: KV data = ${data ? `${data.length} bytes` : "null/empty"}`);
     if (!data) return;
     try {
       const pendingTokens = JSON.parse(data);
-      this.log(`[V5-PERSIST] Parsed ${pendingTokens.length} pending V5 token(s): ${pendingTokens.map((t) => t.id.slice(0, 16)).join(", ")}`);
+      logger.debug("Payments", `[V5-PERSIST] Parsed ${pendingTokens.length} pending V5 token(s): ${pendingTokens.map((t) => t.id.slice(0, 16)).join(", ")}`);
       for (const token of pendingTokens) {
         if (!this.tokens.has(token.id)) {
           this.tokens.set(token.id, token);
-          this.log(`[V5-PERSIST] Restored token ${token.id.slice(0, 16)} (status=${token.status})`);
+          logger.debug("Payments", `[V5-PERSIST] Restored token ${token.id.slice(0, 16)} (status=${token.status})`);
         } else {
-          this.log(`[V5-PERSIST] Token ${token.id.slice(0, 16)} already in map, skipping`);
+          logger.debug("Payments", `[V5-PERSIST] Token ${token.id.slice(0, 16)} already in map, skipping`);
         }
       }
     } catch (err) {
-      console.error("[Payments][V5-PERSIST] Failed to parse pending V5 tokens:", err);
+      logger.error("Payments", "[V5-PERSIST] Failed to parse pending V5 tokens:", err);
     }
   }
   /**
@@ -6712,13 +6861,13 @@ var PaymentsModule = class _PaymentsModule {
     const incomingStateHash = extractStateHashFromSdkData(token.sdkData);
     const incomingStateKey = incomingTokenId && incomingStateHash ? createTokenStateKey(incomingTokenId, incomingStateHash) : null;
     if (incomingTokenId && incomingStateHash && this.isStateTombstoned(incomingTokenId, incomingStateHash)) {
-      this.log(`Rejecting tombstoned token: ${incomingTokenId.slice(0, 8)}..._${incomingStateHash.slice(0, 8)}...`);
+      logger.debug("Payments", `Rejecting tombstoned token: ${incomingTokenId.slice(0, 8)}..._${incomingStateHash.slice(0, 8)}...`);
       return false;
     }
     if (incomingStateKey) {
       for (const [_existingId, existing] of this.tokens) {
         if (isSameTokenState(existing, token)) {
-          this.log(`Duplicate token state ignored: ${incomingTokenId?.slice(0, 8)}..._${incomingStateHash?.slice(0, 8)}...`);
+          logger.debug("Payments", `Duplicate token state ignored: ${incomingTokenId?.slice(0, 8)}..._${incomingStateHash?.slice(0, 8)}...`);
           return false;
         }
       }
@@ -6730,19 +6879,19 @@ var PaymentsModule = class _PaymentsModule {
           continue;
         }
         if (existing.status === "spent" || existing.status === "invalid") {
-          this.log(`Replacing spent/invalid token ${incomingTokenId?.slice(0, 8)}...`);
+          logger.debug("Payments", `Replacing spent/invalid token ${incomingTokenId?.slice(0, 8)}...`);
           this.tokens.delete(existingId);
           break;
         }
         if (incomingStateHash && existingStateHash && incomingStateHash !== existingStateHash) {
-          this.log(`Token ${incomingTokenId?.slice(0, 8)}... state updated: ${existingStateHash.slice(0, 8)}... -> ${incomingStateHash.slice(0, 8)}...`);
+          logger.debug("Payments", `Token ${incomingTokenId?.slice(0, 8)}... state updated: ${existingStateHash.slice(0, 8)}... -> ${incomingStateHash.slice(0, 8)}...`);
           await this.archiveToken(existing);
           this.tokens.delete(existingId);
           break;
         }
         if (!incomingStateHash || !existingStateHash) {
           if (existingId !== token.id) {
-            this.log(`Token ${incomingTokenId?.slice(0, 8)}... .id changed, replacing`);
+            logger.debug("Payments", `Token ${incomingTokenId?.slice(0, 8)}... .id changed, replacing`);
             await this.archiveToken(existing);
             this.tokens.delete(existingId);
             break;
@@ -6753,7 +6902,7 @@ var PaymentsModule = class _PaymentsModule {
     this.tokens.set(token.id, token);
     await this.archiveToken(token);
     await this.save();
-    this.log(`Added token ${token.id}, total: ${this.tokens.size}`);
+    logger.debug("Payments", `Added token ${token.id}, total: ${this.tokens.size}`);
     return true;
   }
   /**
@@ -6783,7 +6932,7 @@ var PaymentsModule = class _PaymentsModule {
     }
     await this.archiveToken(token);
     await this.save();
-    this.log(`Updated token ${token.id}`);
+    logger.debug("Payments", `Updated token ${token.id}`);
   }
   /**
    * Remove a token from the wallet.
@@ -6806,10 +6955,10 @@ var PaymentsModule = class _PaymentsModule {
       );
       if (!alreadyTombstoned) {
         this.tombstones.push(tombstone);
-        this.log(`Created tombstone for ${tombstone.tokenId.slice(0, 8)}..._${tombstone.stateHash.slice(0, 8)}...`);
+        logger.debug("Payments", `Created tombstone for ${tombstone.tokenId.slice(0, 8)}..._${tombstone.stateHash.slice(0, 8)}...`);
       }
     } else {
-      this.log(`Warning: Could not create tombstone for token ${tokenId.slice(0, 8)}... (missing tokenId or stateHash)`);
+      logger.debug("Payments", `Warning: Could not create tombstone for token ${tokenId.slice(0, 8)}... (missing tokenId or stateHash)`);
     }
     this.tokens.delete(tokenId);
     await this.save();
@@ -6866,7 +7015,7 @@ var PaymentsModule = class _PaymentsModule {
     }
     for (const token of tokensToRemove) {
       this.tokens.delete(token.id);
-      this.log(`Removed tombstoned token ${token.id.slice(0, 8)}...`);
+      logger.debug("Payments", `Removed tombstoned token ${token.id.slice(0, 8)}...`);
       removedCount++;
     }
     for (const remoteTombstone of remoteTombstones) {
@@ -6892,7 +7041,7 @@ var PaymentsModule = class _PaymentsModule {
     this.tombstones = pruneTombstonesByAge(this.tombstones, maxAge);
     if (this.tombstones.length < originalCount) {
       await this.save();
-      this.log(`Pruned tombstones from ${originalCount} to ${this.tombstones.length}`);
+      logger.debug("Payments", `Pruned tombstones from ${originalCount} to ${this.tombstones.length}`);
     }
   }
   // ===========================================================================
@@ -6964,7 +7113,7 @@ var PaymentsModule = class _PaymentsModule {
     const originalCount = this.archivedTokens.size;
     this.archivedTokens = pruneMapByCount(this.archivedTokens, maxCount);
     await this.save();
-    this.log(`Pruned archived tokens from ${originalCount} to ${this.archivedTokens.size}`);
+    logger.debug("Payments", `Pruned archived tokens from ${originalCount} to ${this.archivedTokens.size}`);
   }
   // ===========================================================================
   // Public API - Forked Tokens
@@ -6993,7 +7142,7 @@ var PaymentsModule = class _PaymentsModule {
     const key = `${tokenId}_${stateHash}`;
     if (this.forkedTokens.has(key)) return;
     this.forkedTokens.set(key, txfToken);
-    this.log(`Stored forked token ${tokenId.slice(0, 8)}... state ${stateHash.slice(0, 12)}...`);
+    logger.debug("Payments", `Stored forked token ${tokenId.slice(0, 8)}... state ${stateHash.slice(0, 12)}...`);
     await this.save();
   }
   /**
@@ -7025,7 +7174,7 @@ var PaymentsModule = class _PaymentsModule {
     const originalCount = this.forkedTokens.size;
     this.forkedTokens = pruneMapByCount(this.forkedTokens, maxCount);
     await this.save();
-    this.log(`Pruned forked tokens from ${originalCount} to ${this.forkedTokens.size}`);
+    logger.debug("Payments", `Pruned forked tokens from ${originalCount} to ${this.forkedTokens.size}`);
   }
   // ===========================================================================
   // Public API - Transaction History
@@ -7105,7 +7254,7 @@ var PaymentsModule = class _PaymentsModule {
           const imported = await provider.importHistoryEntries?.(records) ?? 0;
           if (imported > 0) {
             this._historyCache = await provider.getHistoryEntries();
-            this.log(`Migrated ${imported} history entries from KV to history store`);
+            logger.debug("Payments", `Migrated ${imported} history entries from KV to history store`);
           }
           await this.deps.storage.remove(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
         } catch {
@@ -7181,7 +7330,7 @@ var PaymentsModule = class _PaymentsModule {
       this.nametags.push(nametag);
     }
     await this.save();
-    this.log(`Nametag set: ${nametag.name}`);
+    logger.debug("Payments", `Nametag set: ${nametag.name}`);
   }
   /**
    * Get the current (first) nametag data.
@@ -7230,7 +7379,7 @@ var PaymentsModule = class _PaymentsModule {
           const parsed = parseTxfStorageData(result.data);
           if (parsed.nametags.length > 0) {
             this.nametags = parsed.nametags;
-            this.log(`Reloaded ${parsed.nametags.length} nametag(s) from storage`);
+            logger.debug("Payments", `Reloaded ${parsed.nametags.length} nametag(s) from storage`);
             return;
           }
         }
@@ -7283,7 +7432,7 @@ var PaymentsModule = class _PaymentsModule {
       const result = await minter.mintNametag(nametag, ownerAddress);
       if (result.success && result.nametagData) {
         await this.setNametag(result.nametagData);
-        this.log(`Nametag minted and saved: ${result.nametagData.name}`);
+        logger.debug("Payments", `Nametag minted and saved: ${result.nametagData.name}`);
         this.deps.emitEvent("nametag:registered", {
           nametag: result.nametagData.name,
           addressIndex: 0
@@ -7293,7 +7442,7 @@ var PaymentsModule = class _PaymentsModule {
       return result;
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error);
-      this.log("mintNametag failed:", errorMsg);
+      logger.debug("Payments", "mintNametag failed:", errorMsg);
       return {
         success: false,
         error: errorMsg
@@ -7391,7 +7540,7 @@ var PaymentsModule = class _PaymentsModule {
               restoredCount++;
             }
             if (restoredCount > 0) {
-              console.log(`[Payments] Sync: restored ${restoredCount} token(s) lost by loadFromStorageData`);
+              logger.debug("Payments", `Sync: restored ${restoredCount} token(s) lost by loadFromStorageData`);
             }
             if (this.nametags.length === 0 && savedNametags.length > 0) {
               this.nametags = savedNametags;
@@ -7400,7 +7549,7 @@ var PaymentsModule = class _PaymentsModule {
             if (txfData._history && txfData._history.length > 0) {
               const imported = await this.importRemoteHistoryEntries(txfData._history);
               if (imported > 0) {
-                this.log(`Imported ${imported} history entries from IPFS sync`);
+                logger.debug("Payments", `Imported ${imported} history entries from IPFS sync`);
               }
             }
             totalAdded += result.added;
@@ -7413,7 +7562,7 @@ var PaymentsModule = class _PaymentsModule {
             removed: result.removed
           });
         } catch (providerError) {
-          console.warn(`[PaymentsModule] Sync failed for provider ${providerId}:`, providerError);
+          logger.warn("Payments", `Sync failed for provider ${providerId}:`, providerError);
           this.deps.emitEvent("sync:provider", {
             providerId,
             success: false,
@@ -7451,7 +7600,7 @@ var PaymentsModule = class _PaymentsModule {
       if (provider.onEvent) {
         const unsub = provider.onEvent((event) => {
           if (event.type === "storage:remote-updated") {
-            this.log("Remote update detected from provider", providerId, event.data);
+            logger.debug("Payments", "Remote update detected from provider", providerId, event.data);
             this.debouncedSyncFromRemoteUpdate(providerId, event.data);
           }
         });
@@ -7493,7 +7642,7 @@ var PaymentsModule = class _PaymentsModule {
           removed: result.removed
         });
       }).catch((err) => {
-        this.log("Auto-sync from remote update failed:", err);
+        logger.debug("Payments", "Auto-sync from remote update failed:", err);
       });
     }, _PaymentsModule.SYNC_DEBOUNCE_MS);
   }
@@ -7598,8 +7747,9 @@ var PaymentsModule = class _PaymentsModule {
       }
       return recipient;
     }
-    throw new Error(
-      `Cannot resolve transport pubkey for "${recipient}". No binding event found. The recipient must publish their identity first.`
+    throw new SphereError(
+      `Cannot resolve transport pubkey for "${recipient}". No binding event found. The recipient must publish their identity first.`,
+      "INVALID_RECIPIENT"
     );
   }
   /**
@@ -7670,32 +7820,33 @@ var PaymentsModule = class _PaymentsModule {
       return AddressFactory.createAddress(recipient);
     }
     if (recipient.length === 66 && /^[0-9a-fA-F]+$/.test(recipient)) {
-      this.log(`Creating DirectAddress from 33-byte compressed pubkey`);
+      logger.debug("Payments", "Creating DirectAddress from 33-byte compressed pubkey");
       return this.createDirectAddressFromPubkey(recipient);
     }
     const info = peerInfo ?? await this.deps?.transport.resolve?.(recipient) ?? null;
     if (!info) {
-      throw new Error(
-        `Recipient "${recipient}" not found. Use @nametag, a valid PROXY:/DIRECT: address, or a 33-byte hex pubkey.`
+      throw new SphereError(
+        `Recipient "${recipient}" not found. Use @nametag, a valid PROXY:/DIRECT: address, or a 33-byte hex pubkey.`,
+        "INVALID_RECIPIENT"
       );
     }
     const nametag = recipient.startsWith("@") ? recipient.slice(1) : info.nametag || recipient;
     if (addressMode === "proxy") {
-      console.log(`[Payments] Using PROXY address for "${nametag}" (forced)`);
+      logger.debug("Payments", `Using PROXY address for "${nametag}" (forced)`);
       return ProxyAddress.fromNameTag(nametag);
     }
     if (addressMode === "direct") {
       if (!info.directAddress) {
-        throw new Error(`"${nametag}" has no DirectAddress stored. It may be a legacy registration.`);
+        throw new SphereError(`"${nametag}" has no DirectAddress stored. It may be a legacy registration.`, "INVALID_RECIPIENT");
       }
-      console.log(`[Payments] Using DirectAddress for "${nametag}" (forced): ${info.directAddress.slice(0, 30)}...`);
+      logger.debug("Payments", `Using DirectAddress for "${nametag}" (forced): ${info.directAddress.slice(0, 30)}...`);
       return AddressFactory.createAddress(info.directAddress);
     }
     if (info.directAddress) {
-      this.log(`Using DirectAddress for "${nametag}": ${info.directAddress.slice(0, 30)}...`);
+      logger.debug("Payments", `Using DirectAddress for "${nametag}": ${info.directAddress.slice(0, 30)}...`);
       return AddressFactory.createAddress(info.directAddress);
     }
-    this.log(`Using PROXY address for legacy nametag "${nametag}"`);
+    logger.debug("Payments", `Using PROXY address for legacy nametag "${nametag}"`);
     return ProxyAddress.fromNameTag(nametag);
   }
   /**
@@ -7708,7 +7859,7 @@ var PaymentsModule = class _PaymentsModule {
       const sourceTokenInput = typeof payload.sourceToken === "string" ? JSON.parse(payload.sourceToken) : payload.sourceToken;
       const commitmentInput = typeof payload.commitmentData === "string" ? JSON.parse(payload.commitmentData) : payload.commitmentData;
       if (!sourceTokenInput || !commitmentInput) {
-        console.warn("[Payments] Invalid NOSTR-FIRST transfer format");
+        logger.warn("Payments", "Invalid NOSTR-FIRST transfer format");
         return;
       }
       const token = await this.saveCommitmentOnlyToken(
@@ -7739,7 +7890,7 @@ var PaymentsModule = class _PaymentsModule {
         tokenId: nostrTokenId || token.id
       });
     } catch (error) {
-      console.error("[Payments] Failed to process NOSTR-FIRST transfer:", error);
+      logger.error("Payments", "Failed to process NOSTR-FIRST transfer:", error);
     }
   }
   /**
@@ -7764,18 +7915,19 @@ var PaymentsModule = class _PaymentsModule {
       const { ProxyAddress } = await import("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
       let proxyNametag = this.getNametag();
       if (!proxyNametag?.token) {
-        this.log("Nametag missing in memory, attempting reload from storage...");
+        logger.debug("Payments", "Nametag missing in memory, attempting reload from storage...");
         await this.reloadNametagsFromStorage();
         proxyNametag = this.getNametag();
       }
       if (!proxyNametag?.token) {
-        throw new Error("Cannot finalize PROXY transfer - no nametag token");
+        throw new SphereError("Cannot finalize PROXY transfer - no nametag token", "VALIDATION_ERROR");
       }
       const nametagToken = await SdkToken2.fromJSON(proxyNametag.token);
       const proxy = await ProxyAddress.fromTokenId(nametagToken.id);
       if (proxy.address !== recipientAddress.address) {
-        throw new Error(
-          `PROXY address mismatch: nametag resolves to ${proxy.address} but transfer targets ${recipientAddress.address}`
+        throw new SphereError(
+          `PROXY address mismatch: nametag resolves to ${proxy.address} but transfer targets ${recipientAddress.address}`,
+          "VALIDATION_ERROR"
         );
       }
       nametagTokens = [nametagToken];
@@ -7795,12 +7947,12 @@ var PaymentsModule = class _PaymentsModule {
     try {
       const token = this.tokens.get(tokenId);
       if (!token) {
-        this.log(`Token ${tokenId} not found for finalization`);
+        logger.debug("Payments", `Token ${tokenId} not found for finalization`);
         return;
       }
       const commitment = await TransferCommitment4.fromJSON(commitmentInput);
       if (!this.deps.oracle.waitForProofSdk) {
-        this.log("Cannot finalize - no waitForProofSdk");
+        logger.debug("Payments", "Cannot finalize - no waitForProofSdk");
         token.status = "confirmed";
         token.updatedAt = Date.now();
         await this.save();
@@ -7812,7 +7964,7 @@ var PaymentsModule = class _PaymentsModule {
       const stClient = this.deps.oracle.getStateTransitionClient?.();
       const trustBase = this.deps.oracle.getTrustBase?.();
       if (!stClient || !trustBase) {
-        this.log("Cannot finalize - missing state transition client or trust base");
+        logger.debug("Payments", "Cannot finalize - missing state transition client or trust base");
         token.status = "confirmed";
         token.updatedAt = Date.now();
         await this.save();
@@ -7832,7 +7984,7 @@ var PaymentsModule = class _PaymentsModule {
       };
       this.tokens.set(tokenId, finalizedToken);
       await this.save();
-      this.log(`NOSTR-FIRST: Token ${tokenId.slice(0, 8)}... finalized and confirmed`);
+      logger.debug("Payments", `NOSTR-FIRST: Token ${tokenId.slice(0, 8)}... finalized and confirmed`);
       this.deps.emitEvent("transfer:confirmed", {
         id: crypto.randomUUID(),
         status: "completed",
@@ -7840,7 +7992,7 @@ var PaymentsModule = class _PaymentsModule {
         tokenTransfers: []
       });
     } catch (error) {
-      console.error("[Payments] Failed to finalize received token:", error);
+      logger.error("Payments", "Failed to finalize received token:", error);
       const token = this.tokens.get(tokenId);
       if (token && token.status === "submitted") {
         token.status = "confirmed";
@@ -7855,7 +8007,7 @@ var PaymentsModule = class _PaymentsModule {
     }
     try {
       const payload = transfer.payload;
-      console.log("[Payments][DEBUG] handleIncomingTransfer: keys=", Object.keys(payload).join(","));
+      logger.debug("Payments", "handleIncomingTransfer: keys=", Object.keys(payload).join(","));
       let combinedBundle = null;
       if (isCombinedTransferBundleV6(payload)) {
         combinedBundle = payload;
@@ -7869,12 +8021,12 @@ var PaymentsModule = class _PaymentsModule {
         }
       }
       if (combinedBundle) {
-        this.log("Processing COMBINED_TRANSFER V6 bundle...");
+        logger.debug("Payments", "Processing COMBINED_TRANSFER V6 bundle...");
         try {
           await this.processCombinedTransferBundle(combinedBundle, transfer.senderTransportPubkey);
-          this.log("COMBINED_TRANSFER V6 processed successfully");
+          logger.debug("Payments", "COMBINED_TRANSFER V6 processed successfully");
         } catch (err) {
-          console.error("[Payments] COMBINED_TRANSFER V6 processing error:", err);
+          logger.error("Payments", "COMBINED_TRANSFER V6 processing error:", err);
         }
         return;
       }
@@ -7891,7 +8043,7 @@ var PaymentsModule = class _PaymentsModule {
         }
       }
       if (instantBundle) {
-        this.log("Processing INSTANT_SPLIT bundle...");
+        logger.debug("Payments", "Processing INSTANT_SPLIT bundle...");
         try {
           const result = await this.processInstantSplitBundle(
             instantBundle,
@@ -7899,28 +8051,28 @@ var PaymentsModule = class _PaymentsModule {
             payload.memo
           );
           if (result.success) {
-            this.log("INSTANT_SPLIT processed successfully");
+            logger.debug("Payments", "INSTANT_SPLIT processed successfully");
           } else {
-            console.warn("[Payments] INSTANT_SPLIT processing failed:", result.error);
+            logger.warn("Payments", "INSTANT_SPLIT processing failed:", result.error);
           }
         } catch (err) {
-          console.error("[Payments] INSTANT_SPLIT processing error:", err);
+          logger.error("Payments", "INSTANT_SPLIT processing error:", err);
         }
         return;
       }
       if (payload.sourceToken && payload.commitmentData && !payload.transferTx) {
-        console.log("[Payments][DEBUG] >>> NOSTR-FIRST commitment-only transfer detected");
+        logger.debug("Payments", "NOSTR-FIRST commitment-only transfer detected");
         await this.handleCommitmentOnlyTransfer(transfer, payload);
         return;
       }
       let tokenData;
       let finalizedSdkToken = null;
       if (payload.sourceToken && payload.transferTx) {
-        this.log("Processing Sphere wallet format transfer...");
+        logger.debug("Payments", "Processing Sphere wallet format transfer...");
         const sourceTokenInput = typeof payload.sourceToken === "string" ? JSON.parse(payload.sourceToken) : payload.sourceToken;
         const transferTxInput = typeof payload.transferTx === "string" ? JSON.parse(payload.transferTx) : payload.transferTx;
         if (!sourceTokenInput || !transferTxInput) {
-          console.warn("[Payments] Invalid Sphere wallet transfer format");
+          logger.warn("Payments", "Invalid Sphere wallet transfer format");
           return;
         }
         let sourceToken;
@@ -7928,7 +8080,7 @@ var PaymentsModule = class _PaymentsModule {
         try {
           sourceToken = await SdkToken2.fromJSON(sourceTokenInput);
         } catch (err) {
-          console.error("[Payments] Failed to parse sourceToken:", err);
+          logger.error("Payments", "Failed to parse sourceToken:", err);
           return;
         }
         try {
@@ -7942,16 +8094,16 @@ var PaymentsModule = class _PaymentsModule {
             const commitment = await TransferCommitment4.fromJSON(transferTxInput);
             const stClient = this.deps.oracle.getStateTransitionClient?.();
             if (!stClient) {
-              console.error("[Payments] Cannot process commitment - no state transition client");
+              logger.error("Payments", "Cannot process commitment - no state transition client");
               return;
             }
             const response = await stClient.submitTransferCommitment(commitment);
             if (response.status !== "SUCCESS" && response.status !== "REQUEST_ID_EXISTS") {
-              console.error("[Payments] Transfer commitment submission failed:", response.status);
+              logger.error("Payments", "Transfer commitment submission failed:", response.status);
               return;
             }
             if (!this.deps.oracle.waitForProofSdk) {
-              console.error("[Payments] Cannot wait for proof - missing oracle method");
+              logger.error("Payments", "Cannot wait for proof - missing oracle method");
               return;
             }
             const inclusionProof = await this.deps.oracle.waitForProofSdk(commitment);
@@ -7963,7 +8115,7 @@ var PaymentsModule = class _PaymentsModule {
               const commitment = await TransferCommitment4.fromJSON(transferTxInput);
               const stClient = this.deps.oracle.getStateTransitionClient?.();
               if (!stClient || !this.deps.oracle.waitForProofSdk) {
-                throw new Error("Cannot submit commitment - missing oracle methods");
+                throw new SphereError("Cannot submit commitment - missing oracle methods", "AGGREGATOR_ERROR");
               }
               await stClient.submitTransferCommitment(commitment);
               const inclusionProof = await this.deps.oracle.waitForProofSdk(commitment);
@@ -7971,33 +8123,33 @@ var PaymentsModule = class _PaymentsModule {
             }
           }
         } catch (err) {
-          console.error("[Payments] Failed to parse transferTx:", err);
+          logger.error("Payments", "Failed to parse transferTx:", err);
           return;
         }
         try {
           const stClient = this.deps.oracle.getStateTransitionClient?.();
           const trustBase = this.deps.oracle.getTrustBase?.();
           if (!stClient || !trustBase) {
-            console.error("[Payments] Cannot finalize - missing state transition client or trust base. Token rejected.");
+            logger.error("Payments", "Cannot finalize - missing state transition client or trust base. Token rejected.");
             return;
           }
           finalizedSdkToken = await this.finalizeTransferToken(sourceToken, transferTx, stClient, trustBase);
           tokenData = finalizedSdkToken.toJSON();
           const addressScheme = transferTx.data.recipient.scheme;
-          this.log(`${addressScheme === AddressScheme.PROXY ? "PROXY" : "DIRECT"} finalization successful`);
+          logger.debug("Payments", `${addressScheme === AddressScheme.PROXY ? "PROXY" : "DIRECT"} finalization successful`);
         } catch (finalizeError) {
-          console.error(`[Payments] Finalization FAILED - token rejected:`, finalizeError);
+          logger.error("Payments", "Finalization FAILED - token rejected:", finalizeError);
           return;
         }
       } else if (payload.token) {
         tokenData = payload.token;
       } else {
-        console.warn("[Payments] Unknown transfer payload format");
+        logger.warn("Payments", "Unknown transfer payload format");
         return;
       }
       const validation = await this.deps.oracle.validateToken(tokenData);
       if (!validation.valid) {
-        console.warn("[Payments] Received invalid token");
+        logger.warn("Payments", "Received invalid token");
         return;
       }
       const tokenInfo = await parseTokenInfo(tokenData);
@@ -8038,12 +8190,12 @@ var PaymentsModule = class _PaymentsModule {
           receivedAt: transfer.timestamp
         };
         this.deps.emitEvent("transfer:incoming", incomingTransfer);
-        this.log(`Incoming transfer processed: ${token.id}, ${token.amount} ${token.symbol}`);
+        logger.debug("Payments", `Incoming transfer processed: ${token.id}, ${token.amount} ${token.symbol}`);
       } else {
-        this.log(`Duplicate transfer ignored: ${token.id}, ${token.amount} ${token.symbol}`);
+        logger.debug("Payments", `Duplicate transfer ignored: ${token.id}, ${token.amount} ${token.symbol}`);
       }
     } catch (error) {
-      console.error("[Payments] Failed to process incoming transfer:", error);
+      logger.error("Payments", "Failed to process incoming transfer:", error);
     }
   }
   // ===========================================================================
@@ -8058,15 +8210,15 @@ var PaymentsModule = class _PaymentsModule {
     if (existingArchive) {
       if (isIncrementalUpdate(existingArchive, txf)) {
         this.archivedTokens.set(tokenId, txf);
-        this.log(`Updated archived token ${tokenId.slice(0, 8)}...`);
+        logger.debug("Payments", `Updated archived token ${tokenId.slice(0, 8)}...`);
       } else {
         const stateHash = getCurrentStateHash(txf) || "";
         await this.storeForkedToken(tokenId, stateHash, txf);
-        this.log(`Archived token ${tokenId.slice(0, 8)}... is a fork`);
+        logger.debug("Payments", `Archived token ${tokenId.slice(0, 8)}... is a fork`);
       }
     } else {
       this.archivedTokens.set(tokenId, txf);
-      this.log(`Archived token ${tokenId.slice(0, 8)}...`);
+      logger.debug("Payments", `Archived token ${tokenId.slice(0, 8)}...`);
     }
   }
   // ===========================================================================
@@ -8078,20 +8230,20 @@ var PaymentsModule = class _PaymentsModule {
       const txf = tokenToTxf(t);
       return `${t.id.slice(0, 12)}(${t.status},txf=${!!txf})`;
     });
-    console.log(`[Payments][DEBUG] save(): providers=${providers.size}, tokens=[${tokenStats.join(", ")}]`);
+    logger.debug("Payments", `save(): providers=${providers.size}, tokens=[${tokenStats.join(", ")}]`);
     if (providers.size > 0) {
       const data = await this.createStorageData();
       const dataKeys = Object.keys(data).filter((k) => k.startsWith("token-"));
-      console.log(`[Payments][DEBUG] save(): TXF keys=${dataKeys.length} (${dataKeys.join(", ")})`);
+      logger.debug("Payments", `save(): TXF keys=${dataKeys.length} (${dataKeys.join(", ")})`);
       for (const [id, provider] of providers) {
         try {
           await provider.save(data);
         } catch (err) {
-          console.error(`[Payments] Failed to save to provider ${id}:`, err);
+          logger.error("Payments", `Failed to save to provider ${id}:`, err);
         }
       }
     } else {
-      console.log("[Payments][DEBUG] save(): No token storage providers - TXF not persisted");
+      logger.debug("Payments", "save(): No token storage providers - TXF not persisted");
     }
     await this.savePendingV5Tokens();
   }
@@ -8129,14 +8281,14 @@ var PaymentsModule = class _PaymentsModule {
   }
   loadFromStorageData(data) {
     const parsed = parseTxfStorageData(data);
-    console.log(`[Payments][DEBUG] loadFromStorageData: parsed ${parsed.tokens.length} tokens, ${parsed.tombstones.length} tombstones, errors=[${parsed.validationErrors.join("; ")}]`);
+    logger.debug("Payments", `loadFromStorageData: parsed ${parsed.tokens.length} tokens, ${parsed.tombstones.length} tombstones, errors=[${parsed.validationErrors.join("; ")}]`);
     this.tombstones = parsed.tombstones;
     this.tokens.clear();
     for (const token of parsed.tokens) {
       const sdkTokenId = extractTokenIdFromSdkData(token.sdkData);
       const stateHash = extractStateHashFromSdkData(token.sdkData);
       if (sdkTokenId && stateHash && this.isStateTombstoned(sdkTokenId, stateHash)) {
-        this.log(`Skipping tombstoned token ${sdkTokenId.slice(0, 8)}... during load (exact state match)`);
+        logger.debug("Payments", `Skipping tombstoned token ${sdkTokenId.slice(0, 8)}... during load (exact state match)`);
         continue;
       }
       this.tokens.set(token.id, token);
@@ -8156,12 +8308,12 @@ var PaymentsModule = class _PaymentsModule {
     try {
       const stClient = this.deps.oracle.getStateTransitionClient?.();
       if (!stClient) {
-        this.log("Cannot submit commitment - no state transition client");
+        logger.debug("Payments", "Cannot submit commitment - no state transition client");
         return;
       }
       const response = await stClient.submitTransferCommitment(commitment);
       if (response.status !== "SUCCESS" && response.status !== "REQUEST_ID_EXISTS") {
-        this.log(`Transfer commitment submission failed: ${response.status}`);
+        logger.debug("Payments", `Transfer commitment submission failed: ${response.status}`);
         const token = this.tokens.get(tokenId);
         if (token) {
           token.status = "invalid";
@@ -8181,7 +8333,7 @@ var PaymentsModule = class _PaymentsModule {
         onProofReceived
       });
     } catch (error) {
-      this.log("submitAndPollForProof error:", error);
+      logger.debug("Payments", "submitAndPollForProof error:", error);
     }
   }
   /**
@@ -8189,7 +8341,7 @@ var PaymentsModule = class _PaymentsModule {
    */
   addProofPollingJob(job) {
     this.proofPollingJobs.set(job.tokenId, job);
-    this.log(`Added proof polling job for token ${job.tokenId.slice(0, 8)}...`);
+    logger.debug("Payments", `Added proof polling job for token ${job.tokenId.slice(0, 8)}...`);
     this.startProofPolling();
   }
   /**
@@ -8198,7 +8350,7 @@ var PaymentsModule = class _PaymentsModule {
   startProofPolling() {
     if (this.proofPollingInterval) return;
     if (this.proofPollingJobs.size === 0) return;
-    this.log("Starting proof polling...");
+    logger.debug("Payments", "Starting proof polling...");
     this.proofPollingInterval = setInterval(
       () => this.processProofPollingQueue(),
       _PaymentsModule.PROOF_POLLING_INTERVAL_MS
@@ -8211,7 +8363,7 @@ var PaymentsModule = class _PaymentsModule {
     if (this.proofPollingInterval) {
       clearInterval(this.proofPollingInterval);
       this.proofPollingInterval = null;
-      this.log("Stopped proof polling");
+      logger.debug("Payments", "Stopped proof polling");
     }
   }
   /**
@@ -8228,7 +8380,7 @@ var PaymentsModule = class _PaymentsModule {
         job.attemptCount++;
         job.lastAttemptAt = Date.now();
         if (job.attemptCount >= _PaymentsModule.PROOF_POLLING_MAX_ATTEMPTS) {
-          this.log(`Proof polling timeout for token ${tokenId.slice(0, 8)}...`);
+          logger.debug("Payments", `Proof polling timeout for token ${tokenId.slice(0, 8)}...`);
           const token2 = this.tokens.get(tokenId);
           if (token2 && token2.status === "submitted") {
             token2.status = "invalid";
@@ -8267,12 +8419,12 @@ var PaymentsModule = class _PaymentsModule {
           token.updatedAt = Date.now();
           this.tokens.set(tokenId, token);
           await this.save();
-          this.log(`Proof received for token ${tokenId.slice(0, 8)}..., status: spent`);
+          logger.debug("Payments", `Proof received for token ${tokenId.slice(0, 8)}..., status: spent`);
         }
         job.onProofReceived?.(tokenId);
         completedJobs.push(tokenId);
       } catch (error) {
-        this.log(`Proof polling attempt ${job.attemptCount} for ${tokenId.slice(0, 8)}...: ${error}`);
+        logger.debug("Payments", `Proof polling attempt ${job.attemptCount} for ${tokenId.slice(0, 8)}...: ${error}`);
       }
     }
     for (const tokenId of completedJobs) {
@@ -8287,7 +8439,7 @@ var PaymentsModule = class _PaymentsModule {
   // ===========================================================================
   ensureInitialized() {
     if (!this.deps) {
-      throw new Error("PaymentsModule not initialized");
+      throw new SphereError("PaymentsModule not initialized", "NOT_INITIALIZED");
     }
   }
 };
@@ -8295,7 +8447,12 @@ function createPaymentsModule(config) {
   return new PaymentsModule(config);
 }
 
+// modules/payments/BackgroundCommitmentService.ts
+init_logger();
+init_errors();
+
 // modules/payments/TokenRecoveryService.ts
+init_logger();
 import { TokenId as TokenId4 } from "@unicitylabs/state-transition-sdk/lib/token/TokenId";
 import { TokenState as TokenState6 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
 import { TokenType as TokenType4 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
@@ -8304,6 +8461,8 @@ import { HashAlgorithm as HashAlgorithm6 } from "@unicitylabs/state-transition-s
 import { UnmaskedPredicate as UnmaskedPredicate6 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
 
 // modules/communications/CommunicationsModule.ts
+init_logger();
+init_errors();
 init_constants();
 var CommunicationsModule = class {
   config;
@@ -8398,7 +8557,7 @@ var CommunicationsModule = class {
       }
       if (myMessages.length > 0) {
         await this.save();
-        console.log(`[Communications] Migrated ${myMessages.length} messages to per-address storage`);
+        logger.debug("Communications", `Migrated ${myMessages.length} messages to per-address storage`);
       }
     }
   }
@@ -8484,7 +8643,7 @@ var CommunicationsModule = class {
         const msg = this.messages.get(id);
         if (msg && msg.senderPubkey !== this.deps.identity.chainPubkey) {
           this.deps.transport.sendReadReceipt(msg.senderPubkey, id).catch((err) => {
-            console.warn("[Communications] Failed to send read receipt:", err);
+            logger.warn("Communications", "Failed to send read receipt:", err);
           });
         }
       }
@@ -8684,7 +8843,7 @@ var CommunicationsModule = class {
       try {
         handler(message);
       } catch (error) {
-        console.error("[Communications] Handler error:", error);
+        logger.error("Communications", "Handler error:", error);
       }
     }
     if (this.config.autoSave) {
@@ -8703,7 +8862,7 @@ var CommunicationsModule = class {
       try {
         handler(composing);
       } catch (error) {
-        console.error("[Communications] Composing handler error:", error);
+        logger.error("Communications", "Composing handler error:", error);
       }
     }
   }
@@ -8721,7 +8880,7 @@ var CommunicationsModule = class {
       try {
         handler(message);
       } catch (error) {
-        console.error("[Communications] Handler error:", error);
+        logger.error("Communications", "Handler error:", error);
       }
     }
   }
@@ -8762,7 +8921,7 @@ var CommunicationsModule = class {
       const nametag = recipient.slice(1);
       const pubkey = await this.deps.transport.resolveNametag?.(nametag);
       if (!pubkey) {
-        throw new Error(`Nametag not found: ${recipient}`);
+        throw new SphereError(`Nametag not found: ${recipient}`, "INVALID_RECIPIENT");
       }
       return { pubkey, nametag };
     }
@@ -8770,7 +8929,7 @@ var CommunicationsModule = class {
   }
   ensureInitialized() {
     if (!this.deps) {
-      throw new Error("CommunicationsModule not initialized");
+      throw new SphereError("CommunicationsModule not initialized", "NOT_INITIALIZED");
     }
   }
 };
@@ -8779,6 +8938,8 @@ function createCommunicationsModule(config) {
 }
 
 // modules/groupchat/GroupChatModule.ts
+init_logger();
+init_errors();
 init_constants();
 import {
   NostrClient,
@@ -8929,13 +9090,15 @@ var GroupChatModule = class {
       for (const subId of this.subscriptionIds) {
         try {
           this.client.unsubscribe(subId);
-        } catch {
+        } catch (err) {
+          logger.debug("GroupChat", "Failed to unsubscribe", err);
         }
       }
       this.subscriptionIds = [];
       try {
         this.client.disconnect();
-      } catch {
+      } catch (err) {
+        logger.debug("GroupChat", "Failed to disconnect", err);
       }
       this.client = null;
     }
@@ -8975,7 +9138,8 @@ var GroupChatModule = class {
     for (const subId of this.subscriptionIds) {
       try {
         this.client.unsubscribe(subId);
-      } catch {
+      } catch (err) {
+        logger.debug("GroupChat", "Failed to unsubscribe", err);
       }
     }
     this.subscriptionIds = [];
@@ -9010,21 +9174,21 @@ var GroupChatModule = class {
       }
       this.deps.emitEvent("groupchat:connection", { connected: true });
     } catch (error) {
-      console.error("[GroupChat] Failed to connect to relays", error);
+      logger.error("GroupChat", "Failed to connect to relays", error);
       this.deps.emitEvent("groupchat:connection", { connected: false });
       this.scheduleReconnect();
     }
   }
   scheduleReconnect() {
     if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
-      console.error("[GroupChat] Max reconnection attempts reached");
+      logger.error("GroupChat", "Max reconnection attempts reached");
       return;
     }
     this.reconnectAttempts++;
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       if (this.deps) {
-        this.connect().catch(console.error);
+        this.connect().catch((err) => logger.error("GroupChat", "Reconnect failed:", err));
       }
     }, this.config.reconnectDelayMs);
   }
@@ -9259,7 +9423,8 @@ var GroupChatModule = class {
         },
         onComplete: () => {
         },
-        timeoutMs: 15e3
+        timeoutMs: 15e3,
+        timeoutLabel: "restoreJoinedGroups"
       }
     );
     if (groupIdsWithMembership.size === 0) return [];
@@ -9276,7 +9441,8 @@ var GroupChatModule = class {
             this.fetchMessages(groupId)
           ]);
         }
-      } catch {
+      } catch (error) {
+        logger.warn("GroupChat", "Failed to restore group", groupId, error);
       }
     }
     if (restoredGroups.length > 0) {
@@ -9309,7 +9475,8 @@ var GroupChatModule = class {
           },
           onComplete: () => {
           },
-          timeoutMs: 1e4
+          timeoutMs: 1e4,
+          timeoutLabel: "fetchAvailableGroups(metadata)"
         }
       ),
       this.oneshotSubscription(
@@ -9324,7 +9491,8 @@ var GroupChatModule = class {
           },
           onComplete: () => {
           },
-          timeoutMs: 1e4
+          timeoutMs: 1e4,
+          timeoutLabel: "fetchAvailableGroups(members)"
         }
       )
     ]);
@@ -9383,7 +9551,7 @@ var GroupChatModule = class {
           return true;
         }
       }
-      console.error("[GroupChat] Failed to join group", error);
+      logger.error("GroupChat", "Failed to join group", error);
       return false;
     }
   }
@@ -9413,7 +9581,7 @@ var GroupChatModule = class {
         this.persistAll();
         return true;
       }
-      console.error("[GroupChat] Failed to leave group", error);
+      logger.error("GroupChat", "Failed to leave group", error);
       return false;
     }
   }
@@ -9464,10 +9632,8 @@ var GroupChatModule = class {
         kind: NIP29_KINDS.JOIN_REQUEST,
         tags: [["h", group.id]],
         content: ""
-      }).catch(() => {
-      });
-      await this.fetchAndSaveMembers(group.id).catch(() => {
-      });
+      }).catch((err) => logger.debug("GroupChat", "Background operation failed", err));
+      await this.fetchAndSaveMembers(group.id).catch((err) => logger.debug("GroupChat", "Failed to fetch members", group.id, err));
       this.saveMemberToMemory({
         pubkey: creatorPubkey,
         groupId: group.id,
@@ -9479,7 +9645,7 @@ var GroupChatModule = class {
       this.schedulePersist();
       return group;
     } catch (error) {
-      console.error("[GroupChat] Failed to create group", error);
+      logger.error("GroupChat", "Failed to create group", error);
       return null;
     }
   }
@@ -9506,7 +9672,7 @@ var GroupChatModule = class {
       }
       return false;
     } catch (error) {
-      console.error("[GroupChat] Failed to delete group", error);
+      logger.error("GroupChat", "Failed to delete group", error);
       return false;
     }
   }
@@ -9526,7 +9692,7 @@ var GroupChatModule = class {
       });
       return eventId ? inviteCode : null;
     } catch (error) {
-      console.error("[GroupChat] Failed to create invite", error);
+      logger.error("GroupChat", "Failed to create invite", error);
       return null;
     }
   }
@@ -9576,7 +9742,7 @@ var GroupChatModule = class {
       }
       return null;
     } catch (error) {
-      console.error("[GroupChat] Failed to send message", error);
+      logger.error("GroupChat", "Failed to send message", error);
       return null;
     }
   }
@@ -9615,7 +9781,8 @@ var GroupChatModule = class {
         this.schedulePersist();
         return fetchedMessages;
       },
-      timeoutMs: 1e4
+      timeoutMs: 1e4,
+      timeoutLabel: `fetchMessages(${groupId})`
     });
   }
   // ===========================================================================
@@ -9676,7 +9843,7 @@ var GroupChatModule = class {
       }
       return false;
     } catch (error) {
-      console.error("[GroupChat] Failed to kick user", error);
+      logger.error("GroupChat", "Failed to kick user", error);
       return false;
     }
   }
@@ -9699,7 +9866,7 @@ var GroupChatModule = class {
       }
       return false;
     } catch (error) {
-      console.error("[GroupChat] Failed to delete message", error);
+      logger.error("GroupChat", "Failed to delete message", error);
       return false;
     }
   }
@@ -9984,7 +10151,7 @@ var GroupChatModule = class {
     this.persistTimer = setTimeout(() => {
       this.persistTimer = null;
       this.persistPromise = this.doPersistAll().catch((err) => {
-        console.error("[GroupChat] Persistence error:", err);
+        logger.error("GroupChat", "Persistence error:", err);
       }).finally(() => {
         this.persistPromise = null;
       });
@@ -10164,7 +10331,8 @@ var GroupChatModule = class {
         if (state.subId) {
           try {
             this.client.unsubscribe(state.subId);
-          } catch {
+          } catch (err) {
+            logger.debug("GroupChat", "Failed to unsubscribe", err);
           }
           const idx = this.subscriptionIds.indexOf(state.subId);
           if (idx >= 0) this.subscriptionIds.splice(idx, 1);
@@ -10179,12 +10347,17 @@ var GroupChatModule = class {
       });
       state.subId = subId;
       this.subscriptionIds.push(subId);
-      setTimeout(finish, opts.timeoutMs ?? 5e3);
+      setTimeout(() => {
+        if (!done && opts.timeoutLabel) {
+          logger.warn("GroupChat", `${opts.timeoutLabel} timed out`);
+        }
+        finish();
+      }, opts.timeoutMs ?? 5e3);
     });
   }
   ensureInitialized() {
     if (!this.deps) {
-      throw new Error("GroupChatModule not initialized");
+      throw new SphereError("GroupChatModule not initialized", "NOT_INITIALIZED");
     }
   }
   async ensureConnected() {
@@ -12353,6 +12526,7 @@ var Pointk1 = /* @__PURE__ */ weierstrass(secp256k1_CURVE, {
 var secp256k1 = /* @__PURE__ */ ecdsa(Pointk1, sha2564);
 
 // modules/market/MarketModule.ts
+init_errors();
 var DEFAULT_MARKET_API_URL = "https://market-api.unicity.network";
 function hexToBytes3(hex) {
   const len = hex.length >> 1;
@@ -12542,7 +12716,7 @@ var MarketModule = class {
   // ---------------------------------------------------------------------------
   ensureIdentity() {
     if (!this.identity) {
-      throw new Error("MarketModule not initialized \u2014 call initialize() first");
+      throw new SphereError("MarketModule not initialized \u2014 call initialize() first", "NOT_INITIALIZED");
     }
   }
   /** Register the agent's public key with the server (idempotent) */
@@ -12568,7 +12742,7 @@ var MarketModule = class {
       data = JSON.parse(text);
     } catch {
     }
-    throw new Error(data?.error ?? `Agent registration failed: HTTP ${res.status}`);
+    throw new SphereError(data?.error ?? `Agent registration failed: HTTP ${res.status}`, "NETWORK_ERROR");
   }
   async parseResponse(res) {
     const text = await res.text();
@@ -12576,9 +12750,9 @@ var MarketModule = class {
     try {
       data = JSON.parse(text);
     } catch {
-      throw new Error(`Market API error: HTTP ${res.status} \u2014 unexpected response (not JSON)`);
+      throw new SphereError(`Market API error: HTTP ${res.status} \u2014 unexpected response (not JSON)`, "NETWORK_ERROR");
     }
-    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+    if (!res.ok) throw new SphereError(data.error ?? `HTTP ${res.status}`, "NETWORK_ERROR");
     return data;
   }
   async apiPost(path, body) {
@@ -12633,6 +12807,8 @@ function createMarketModule(config) {
 init_constants();
 
 // core/encryption.ts
+init_errors();
+init_logger();
 import CryptoJS6 from "crypto-js";
 function encryptSimple(plaintext, password) {
   return CryptoJS6.AES.encrypt(plaintext, password).toString();
@@ -12641,7 +12817,7 @@ function decryptSimple(ciphertext, password) {
   const decrypted = CryptoJS6.AES.decrypt(ciphertext, password);
   const result = decrypted.toString(CryptoJS6.enc.Utf8);
   if (!result) {
-    throw new Error("Decryption failed: invalid password or corrupted data");
+    throw new SphereError("Decryption failed: invalid password or corrupted data", "DECRYPTION_ERROR");
   }
   return result;
 }
@@ -12655,12 +12831,14 @@ function decryptWithSalt(ciphertext, password, salt) {
     const decrypted = CryptoJS6.AES.decrypt(ciphertext, key);
     const result = decrypted.toString(CryptoJS6.enc.Utf8);
     return result || null;
-  } catch {
+  } catch (err) {
+    logger.debug("Encryption", "decryptWithSalt failed", err);
     return null;
   }
 }
 
 // core/scan.ts
+init_logger();
 async function scanAddressesImpl(deriveAddress, options = {}) {
   const maxAddresses = options.maxAddresses ?? 50;
   const gapLimit = options.gapLimit ?? 20;
@@ -12699,7 +12877,8 @@ async function scanAddressesImpl(deriveAddress, options = {}) {
                 nametag = tag;
                 nametagsFoundCount++;
               }
-            } catch {
+            } catch (err) {
+              logger.debug("Sphere", "Nametag resolution failed during scan", err);
             }
           }
           foundAddresses.push({
@@ -12716,7 +12895,7 @@ async function scanAddressesImpl(deriveAddress, options = {}) {
           consecutiveEmpty++;
         }
       } catch (err) {
-        console.warn(`[scanAddresses] Error checking ${addrInfo.address}:`, err);
+        logger.warn("Sphere", `scanAddresses: Error checking ${addrInfo.address}:`, err);
         consecutiveEmpty++;
       }
       if (consecutiveEmpty >= gapLimit) {
@@ -12808,6 +12987,7 @@ init_network();
 import CryptoJS7 from "crypto-js";
 
 // core/utils.ts
+init_errors();
 var SECP256K1_ORDER = BigInt("0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141");
 var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function isValidPrivateKey(hex) {
@@ -12847,7 +13027,7 @@ function base58Decode(str) {
   for (let i = 0; i < str.length; i++) {
     const char = str[i];
     if (!(char in ALPHABET_MAP)) {
-      throw new Error("Invalid base58 character: " + char);
+      throw new SphereError("Invalid base58 character: " + char, "VALIDATION_ERROR");
     }
     num = num * BigInt(58) + BigInt(ALPHABET_MAP[char]);
   }
@@ -13129,6 +13309,7 @@ function parseAndDecryptWalletText(content, password) {
 }
 
 // serialization/wallet-dat.ts
+init_errors();
 import CryptoJS8 from "crypto-js";
 function uint8ArrayToWordArray(u8arr) {
   const hex = bytesToHex2(u8arr);
@@ -13314,7 +13495,7 @@ async function decryptCMasterKey(cmk, password, onProgress) {
   );
   const result = CryptoJS8.enc.Hex.stringify(decrypted);
   if (!result || result.length !== 64) {
-    throw new Error("Master key decryption failed - incorrect password");
+    throw new SphereError("Master key decryption failed - incorrect password", "DECRYPTION_ERROR");
   }
   return result;
 }
@@ -13609,6 +13790,7 @@ var Sphere = class _Sphere {
    * ```
    */
   static async init(options) {
+    if (options.debug) logger.configure({ debug: true });
     _Sphere.configureTokenRegistry(options.storage, options.network);
     const groupChat = _Sphere.resolveGroupChatConfig(options.groupChat, options.network);
     const market = _Sphere.resolveMarketConfig(options.market);
@@ -13636,8 +13818,9 @@ var Sphere = class _Sphere {
         mnemonic = _Sphere.generateMnemonic();
         generatedMnemonic = mnemonic;
       } else {
-        throw new Error(
-          "No wallet exists and no mnemonic provided. Provide a mnemonic or set autoGenerate: true."
+        throw new SphereError(
+          "No wallet exists and no mnemonic provided. Provide a mnemonic or set autoGenerate: true.",
+          "INVALID_CONFIG"
         );
       }
     }
@@ -13710,11 +13893,12 @@ var Sphere = class _Sphere {
    * Create new wallet with mnemonic
    */
   static async create(options) {
+    if (options.debug) logger.configure({ debug: true });
     if (!options.mnemonic || !_Sphere.validateMnemonic(options.mnemonic)) {
-      throw new Error("Invalid mnemonic");
+      throw new SphereError("Invalid mnemonic", "INVALID_IDENTITY");
     }
     if (await _Sphere.exists(options.storage)) {
-      throw new Error("Wallet already exists. Use Sphere.load() or Sphere.clear() first.");
+      throw new SphereError("Wallet already exists. Use Sphere.load() or Sphere.clear() first.", "ALREADY_INITIALIZED");
     }
     const progress = options.onProgress;
     if (!options.storage.isConnected()) {
@@ -13760,10 +13944,10 @@ var Sphere = class _Sphere {
         const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
         const result = await sphere.discoverAddresses(discoverOpts);
         if (result.addresses.length > 0) {
-          console.log(`[Sphere.create] Address discovery: found ${result.addresses.length} address(es)`);
+          logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
         }
       } catch (err) {
-        console.warn("[Sphere.create] Address discovery failed (non-fatal):", err);
+        logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
       }
     }
     progress?.({ step: "complete", message: "Wallet created" });
@@ -13773,8 +13957,9 @@ var Sphere = class _Sphere {
    * Load existing wallet from storage
    */
   static async load(options) {
+    if (options.debug) logger.configure({ debug: true });
     if (!await _Sphere.exists(options.storage)) {
-      throw new Error("No wallet found. Use Sphere.create() to create a new wallet.");
+      throw new SphereError("No wallet found. Use Sphere.create() to create a new wallet.", "NOT_INITIALIZED");
     }
     const progress = options.onProgress;
     _Sphere.configureTokenRegistry(options.storage, options.network);
@@ -13805,16 +13990,16 @@ var Sphere = class _Sphere {
     _Sphere.instance = sphere;
     if (sphere._identity?.nametag && !sphere._payments.hasNametag()) {
       progress?.({ step: "registering_nametag", message: "Restoring nametag token..." });
-      console.log(`[Sphere] Nametag @${sphere._identity.nametag} has no token, attempting to mint...`);
+      logger.debug("Sphere", `Nametag @${sphere._identity.nametag} has no token, attempting to mint...`);
       try {
         const result = await sphere.mintNametag(sphere._identity.nametag);
         if (result.success) {
-          console.log(`[Sphere] Nametag token minted successfully on load`);
+          logger.debug("Sphere", `Nametag token minted successfully on load`);
         } else {
-          console.warn(`[Sphere] Could not mint nametag token: ${result.error}`);
+          logger.warn("Sphere", `Could not mint nametag token: ${result.error}`);
         }
       } catch (err) {
-        console.warn(`[Sphere] Nametag token mint failed:`, err);
+        logger.warn("Sphere", `Nametag token mint failed:`, err);
       }
     }
     if (options.discoverAddresses !== false && sphere._transport.discoverAddresses && sphere._masterKey) {
@@ -13823,10 +14008,10 @@ var Sphere = class _Sphere {
         const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
         const result = await sphere.discoverAddresses(discoverOpts);
         if (result.addresses.length > 0) {
-          console.log(`[Sphere.load] Address discovery: found ${result.addresses.length} address(es)`);
+          logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
         }
       } catch (err) {
-        console.warn("[Sphere.load] Address discovery failed (non-fatal):", err);
+        logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
       }
     }
     progress?.({ step: "complete", message: "Wallet loaded" });
@@ -13836,24 +14021,25 @@ var Sphere = class _Sphere {
    * Import wallet from mnemonic or master key
    */
   static async import(options) {
+    if (options.debug) logger.configure({ debug: true });
     if (!options.mnemonic && !options.masterKey) {
-      throw new Error("Either mnemonic or masterKey is required");
+      throw new SphereError("Either mnemonic or masterKey is required", "INVALID_CONFIG");
     }
     const progress = options.onProgress;
-    console.log("[Sphere.import] Starting import...");
+    logger.debug("Sphere", "Starting import...");
     const needsClear = _Sphere.instance !== null || await _Sphere.exists(options.storage);
     if (needsClear) {
       progress?.({ step: "clearing", message: "Clearing previous wallet data..." });
-      console.log("[Sphere.import] Clearing existing wallet data...");
+      logger.debug("Sphere", "Clearing existing wallet data...");
       await _Sphere.clear({ storage: options.storage, tokenStorage: options.tokenStorage });
-      console.log("[Sphere.import] Clear done");
+      logger.debug("Sphere", "Clear done");
     } else {
-      console.log("[Sphere.import] No existing wallet \u2014 skipping clear");
+      logger.debug("Sphere", "No existing wallet \u2014 skipping clear");
     }
     if (!options.storage.isConnected()) {
-      console.log("[Sphere.import] Reconnecting storage...");
+      logger.debug("Sphere", "Reconnecting storage...");
       await options.storage.connect();
-      console.log("[Sphere.import] Storage reconnected");
+      logger.debug("Sphere", "Storage reconnected");
     }
     const groupChatConfig = _Sphere.resolveGroupChatConfig(options.groupChat);
     const marketConfig = _Sphere.resolveMarketConfig(options.market);
@@ -13871,14 +14057,14 @@ var Sphere = class _Sphere {
     progress?.({ step: "storing_keys", message: "Storing wallet keys..." });
     if (options.mnemonic) {
       if (!_Sphere.validateMnemonic(options.mnemonic)) {
-        throw new Error("Invalid mnemonic");
+        throw new SphereError("Invalid mnemonic", "INVALID_IDENTITY");
       }
-      console.log("[Sphere.import] Storing mnemonic...");
+      logger.debug("Sphere", "Storing mnemonic...");
       await sphere.storeMnemonic(options.mnemonic, options.derivationPath, options.basePath);
-      console.log("[Sphere.import] Initializing identity from mnemonic...");
+      logger.debug("Sphere", "Initializing identity from mnemonic...");
       await sphere.initializeIdentityFromMnemonic(options.mnemonic, options.derivationPath);
     } else if (options.masterKey) {
-      console.log("[Sphere.import] Storing master key...");
+      logger.debug("Sphere", "Storing master key...");
       await sphere.storeMasterKey(
         options.masterKey,
         options.chainCode,
@@ -13886,7 +14072,7 @@ var Sphere = class _Sphere {
         options.basePath,
         options.derivationMode
       );
-      console.log("[Sphere.import] Initializing identity from master key...");
+      logger.debug("Sphere", "Initializing identity from master key...");
       await sphere.initializeIdentityFromMasterKey(
         options.masterKey,
         options.chainCode,
@@ -13894,38 +14080,38 @@ var Sphere = class _Sphere {
       );
     }
     progress?.({ step: "initializing", message: "Initializing wallet..." });
-    console.log("[Sphere.import] Initializing providers...");
+    logger.debug("Sphere", "Initializing providers...");
     await sphere.initializeProviders();
-    console.log("[Sphere.import] Providers initialized. Initializing modules...");
+    logger.debug("Sphere", "Providers initialized. Initializing modules...");
     await sphere.initializeModules();
-    console.log("[Sphere.import] Modules initialized");
+    logger.debug("Sphere", "Modules initialized");
     if (!options.nametag) {
       progress?.({ step: "recovering_nametag", message: "Recovering nametag..." });
-      console.log("[Sphere.import] Recovering nametag from transport...");
+      logger.debug("Sphere", "Recovering nametag from transport...");
       await sphere.recoverNametagFromTransport();
-      console.log("[Sphere.import] Nametag recovery done");
+      logger.debug("Sphere", "Nametag recovery done");
       progress?.({ step: "syncing_identity", message: "Publishing identity..." });
       await sphere.syncIdentityWithTransport();
     }
     progress?.({ step: "finalizing", message: "Finalizing wallet..." });
-    console.log("[Sphere.import] Finalizing wallet creation...");
+    logger.debug("Sphere", "Finalizing wallet creation...");
     await sphere.finalizeWalletCreation();
     sphere._initialized = true;
     _Sphere.instance = sphere;
-    console.log("[Sphere.import] Tracking address 0...");
+    logger.debug("Sphere", "Tracking address 0...");
     await sphere.ensureAddressTracked(0);
     if (options.nametag) {
       progress?.({ step: "registering_nametag", message: "Registering nametag..." });
-      console.log("[Sphere.import] Registering nametag...");
+      logger.debug("Sphere", "Registering nametag...");
       await sphere.registerNametag(options.nametag);
     }
     if (sphere._tokenStorageProviders.size > 0) {
       progress?.({ step: "syncing_tokens", message: "Syncing tokens..." });
       try {
         const syncResult = await sphere._payments.sync();
-        console.log(`[Sphere.import] Auto-sync: +${syncResult.added} -${syncResult.removed}`);
+        logger.debug("Sphere", `Auto-sync: +${syncResult.added} -${syncResult.removed}`);
       } catch (err) {
-        console.warn("[Sphere.import] Auto-sync failed (non-fatal):", err);
+        logger.warn("Sphere", "Auto-sync failed (non-fatal):", err);
       }
     }
     if (options.discoverAddresses !== false && sphere._transport.discoverAddresses) {
@@ -13934,14 +14120,14 @@ var Sphere = class _Sphere {
         const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
         const result = await sphere.discoverAddresses(discoverOpts);
         if (result.addresses.length > 0) {
-          console.log(`[Sphere.import] Address discovery: found ${result.addresses.length} address(es)`);
+          logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
         }
       } catch (err) {
-        console.warn("[Sphere.import] Address discovery failed (non-fatal):", err);
+        logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
       }
     }
     progress?.({ step: "complete", message: "Import complete" });
-    console.log("[Sphere.import] Import complete");
+    logger.debug("Sphere", "Import complete");
     return sphere;
   }
   /**
@@ -13967,26 +14153,26 @@ var Sphere = class _Sphere {
     const storage = "get" in storageOrOptions ? storageOrOptions : storageOrOptions.storage;
     const tokenStorage = "get" in storageOrOptions ? void 0 : storageOrOptions.tokenStorage;
     if (_Sphere.instance) {
-      console.log("[Sphere.clear] Destroying Sphere instance...");
+      logger.debug("Sphere", "Destroying Sphere instance...");
       await _Sphere.instance.destroy();
-      console.log("[Sphere.clear] Sphere instance destroyed");
+      logger.debug("Sphere", "Sphere instance destroyed");
     }
-    console.log("[Sphere.clear] Clearing L1 vesting cache...");
+    logger.debug("Sphere", "Clearing L1 vesting cache...");
     await vestingClassifier.destroy();
-    console.log("[Sphere.clear] Yielding 50ms for IDB transaction settlement...");
+    logger.debug("Sphere", "Yielding 50ms for IDB transaction settlement...");
     await new Promise((r) => setTimeout(r, 50));
     if (tokenStorage?.clear) {
-      console.log("[Sphere.clear] Clearing token storage...");
+      logger.debug("Sphere", "Clearing token storage...");
       try {
         await tokenStorage.clear();
-        console.log("[Sphere.clear] Token storage cleared");
+        logger.debug("Sphere", "Token storage cleared");
       } catch (err) {
-        console.warn("[Sphere.clear] Token storage clear failed:", err);
+        logger.warn("Sphere", "Token storage clear failed:", err);
       }
     } else {
-      console.log("[Sphere.clear] No token storage provider to clear");
+      logger.debug("Sphere", "No token storage provider to clear");
     }
-    console.log("[Sphere.clear] Clearing KV storage...");
+    logger.debug("Sphere", "Clearing KV storage...");
     if (!storage.isConnected()) {
       try {
         await storage.connect();
@@ -13995,11 +14181,11 @@ var Sphere = class _Sphere {
     }
     if (storage.isConnected()) {
       await storage.clear();
-      console.log("[Sphere.clear] KV storage cleared");
+      logger.debug("Sphere", "KV storage cleared");
     } else {
-      console.log("[Sphere.clear] KV storage not connected, skipping");
+      logger.debug("Sphere", "KV storage not connected, skipping");
     }
-    console.log("[Sphere.clear] Done");
+    logger.debug("Sphere", "Done");
   }
   /**
    * Get current instance
@@ -14091,7 +14277,7 @@ var Sphere = class _Sphere {
    */
   async addTokenStorageProvider(provider) {
     if (this._tokenStorageProviders.has(provider.id)) {
-      throw new Error(`Token storage provider '${provider.id}' already exists`);
+      throw new SphereError(`Token storage provider '${provider.id}' already exists`, "INVALID_CONFIG");
     }
     if (this._identity) {
       provider.setIdentity(this._identity);
@@ -14211,7 +14397,7 @@ var Sphere = class _Sphere {
   exportToJSON(options = {}) {
     this.ensureReady();
     if (!this._masterKey && !this._identity) {
-      throw new Error("Wallet not initialized");
+      throw new SphereError("Wallet not initialized", "NOT_INITIALIZED");
     }
     const addressCount = options.addressCount || 1;
     const addresses = [];
@@ -14291,7 +14477,7 @@ var Sphere = class _Sphere {
   exportToTxt(options = {}) {
     this.ensureReady();
     if (!this._masterKey && !this._identity) {
-      throw new Error("Wallet not initialized");
+      throw new SphereError("Wallet not initialized", "NOT_INITIALIZED");
     }
     const addressCount = options.addressCount || 1;
     const addresses = [];
@@ -14730,7 +14916,7 @@ var Sphere = class _Sphere {
     this.ensureReady();
     const entry = this._trackedAddresses.get(index);
     if (!entry) {
-      throw new Error(`Address at index ${index} is not tracked. Switch to it first.`);
+      throw new SphereError(`Address at index ${index} is not tracked. Switch to it first.`, "INVALID_CONFIG");
     }
     if (entry.hidden === hidden) return;
     entry.hidden = hidden;
@@ -14760,14 +14946,14 @@ var Sphere = class _Sphere {
   async switchToAddress(index, options) {
     this.ensureReady();
     if (!this._masterKey) {
-      throw new Error("HD derivation requires master key with chain code. Cannot switch addresses.");
+      throw new SphereError("HD derivation requires master key with chain code. Cannot switch addresses.", "INVALID_CONFIG");
     }
     if (index < 0) {
-      throw new Error("Address index must be non-negative");
+      throw new SphereError("Address index must be non-negative", "INVALID_CONFIG");
     }
     const newNametag = options?.nametag ? this.cleanNametag(options.nametag) : void 0;
     if (newNametag && !isValidNametag(newNametag)) {
-      throw new Error("Invalid nametag format. Use lowercase alphanumeric, underscore, or hyphen (3-20 chars), or a valid phone number.");
+      throw new SphereError("Invalid nametag format. Use lowercase alphanumeric, underscore, or hyphen (3-20 chars), or a valid phone number.", "VALIDATION_ERROR");
     }
     const addressInfo = this.deriveAddress(index, false);
     const ipnsHash = sha256(addressInfo.publicKey, "hex").slice(0, 40);
@@ -14777,7 +14963,7 @@ var Sphere = class _Sphere {
     if (newNametag) {
       const existing = await this._transport.resolveNametag?.(newNametag);
       if (existing) {
-        throw new Error(`Nametag @${newNametag} is already taken`);
+        throw new SphereError(`Nametag @${newNametag} is already taken`, "VALIDATION_ERROR");
       }
       let nametags = this._addressNametags.get(addressId);
       if (!nametags) {
@@ -14800,12 +14986,12 @@ var Sphere = class _Sphere {
     await this._storage.set(STORAGE_KEYS_GLOBAL.CURRENT_ADDRESS_INDEX, index.toString());
     this._storage.setIdentity(this._identity);
     await this._transport.setIdentity(this._identity);
-    console.log(`[Sphere] switchToAddress(${index}): re-initializing ${this._tokenStorageProviders.size} token storage provider(s)`);
+    logger.debug("Sphere", `switchToAddress(${index}): re-initializing ${this._tokenStorageProviders.size} token storage provider(s)`);
     for (const [providerId, provider] of this._tokenStorageProviders.entries()) {
-      console.log(`[Sphere] switchToAddress(${index}): shutdown provider=${providerId}`);
+      logger.debug("Sphere", `switchToAddress(${index}): shutdown provider=${providerId}`);
       await provider.shutdown();
       provider.setIdentity(this._identity);
-      console.log(`[Sphere] switchToAddress(${index}): initialize provider=${providerId}`);
+      logger.debug("Sphere", `switchToAddress(${index}): initialize provider=${providerId}`);
       await provider.initialize();
     }
     await this.reinitializeModulesForNewAddress();
@@ -14816,9 +15002,9 @@ var Sphere = class _Sphere {
       nametag: this._identity.nametag,
       addressIndex: index
     });
-    console.log(`[Sphere] Switched to address ${index}:`, this._identity.l1Address);
+    logger.debug("Sphere", `Switched to address ${index}:`, this._identity.l1Address);
     this.postSwitchSync(index, newNametag).catch((err) => {
-      console.warn(`[Sphere] Post-switch sync failed for address ${index}:`, err);
+      logger.warn("Sphere", `Post-switch sync failed for address ${index}:`, err);
     });
   }
   /**
@@ -14832,16 +15018,16 @@ var Sphere = class _Sphere {
     if (newNametag) {
       await this.persistAddressNametags();
       if (!this._payments.hasNametag()) {
-        console.log(`[Sphere] Minting nametag token for @${newNametag}...`);
+        logger.debug("Sphere", `Minting nametag token for @${newNametag}...`);
         try {
           const result = await this.mintNametag(newNametag);
           if (result.success) {
-            console.log(`[Sphere] Nametag token minted successfully`);
+            logger.debug("Sphere", `Nametag token minted successfully`);
           } else {
-            console.warn(`[Sphere] Could not mint nametag token: ${result.error}`);
+            logger.warn("Sphere", `Could not mint nametag token: ${result.error}`);
           }
         } catch (err) {
-          console.warn(`[Sphere] Nametag token mint failed:`, err);
+          logger.warn("Sphere", `Nametag token mint failed:`, err);
         }
       }
       this.emitEvent("nametag:registered", {
@@ -14849,16 +15035,16 @@ var Sphere = class _Sphere {
         addressIndex: index
       });
     } else if (this._identity?.nametag && !this._payments.hasNametag()) {
-      console.log(`[Sphere] Nametag @${this._identity.nametag} has no token after switch, minting...`);
+      logger.debug("Sphere", `Nametag @${this._identity.nametag} has no token after switch, minting...`);
       try {
         const result = await this.mintNametag(this._identity.nametag);
         if (result.success) {
-          console.log(`[Sphere] Nametag token minted successfully after switch`);
+          logger.debug("Sphere", `Nametag token minted successfully after switch`);
         } else {
-          console.warn(`[Sphere] Could not mint nametag token after switch: ${result.error}`);
+          logger.warn("Sphere", `Could not mint nametag token after switch: ${result.error}`);
         }
       } catch (err) {
-        console.warn(`[Sphere] Nametag token mint failed after switch:`, err);
+        logger.warn("Sphere", `Nametag token mint failed after switch:`, err);
       }
     }
   }
@@ -14897,7 +15083,7 @@ var Sphere = class _Sphere {
     await this._groupChat?.load();
     await this._market?.load();
     this._payments.sync().catch((err) => {
-      console.warn("[Sphere] Post-switch sync failed:", err);
+      logger.warn("Sphere", "Post-switch sync failed:", err);
     });
   }
   /**
@@ -14931,7 +15117,7 @@ var Sphere = class _Sphere {
    */
   _deriveAddressInternal(index, isChange = false) {
     if (!this._masterKey) {
-      throw new Error("HD derivation requires master key with chain code");
+      throw new SphereError("HD derivation requires master key with chain code", "INVALID_CONFIG");
     }
     if (this._derivationMode === "wif_hmac") {
       return generateAddressFromMasterKey(this._masterKey.privateKey, index);
@@ -14961,7 +15147,7 @@ var Sphere = class _Sphere {
   deriveAddressAtPath(path) {
     this.ensureReady();
     if (!this._masterKey) {
-      throw new Error("HD derivation requires master key with chain code");
+      throw new SphereError("HD derivation requires master key with chain code", "INVALID_CONFIG");
     }
     const match = path.match(/\/(\d+)$/);
     const index = match ? parseInt(match[1], 10) : 0;
@@ -15028,13 +15214,14 @@ var Sphere = class _Sphere {
   async scanAddresses(options = {}) {
     this.ensureReady();
     if (!this._masterKey) {
-      throw new Error("Address scanning requires HD master key");
+      throw new SphereError("Address scanning requires HD master key", "INVALID_CONFIG");
     }
     const resolveNametag = options.resolveNametag ?? (this._transport.resolveAddressInfo ? async (l1Address) => {
       try {
         const info = await this._transport.resolveAddressInfo(l1Address);
         return info?.nametag ?? null;
-      } catch {
+      } catch (err) {
+        logger.debug("Sphere", "Nametag resolution failed during scan", err);
         return null;
       }
     } : void 0);
@@ -15085,10 +15272,10 @@ var Sphere = class _Sphere {
   async discoverAddresses(options = {}) {
     this.ensureReady();
     if (!this._masterKey) {
-      throw new Error("Address discovery requires HD master key");
+      throw new SphereError("Address discovery requires HD master key", "INVALID_CONFIG");
     }
     if (!this._transport.discoverAddresses) {
-      throw new Error("Transport provider does not support address discovery");
+      throw new SphereError("Transport provider does not support address discovery", "INVALID_CONFIG");
     }
     const includeL1Scan = options.includeL1Scan ?? true;
     const transportResult = await discoverAddressesImpl(
@@ -15144,7 +15331,7 @@ var Sphere = class _Sphere {
         }
         transportResult.addresses.sort((a, b) => a.index - b.index);
       } catch (err) {
-        console.warn("[Sphere] L1 scan failed during discovery (non-fatal):", err);
+        logger.warn("Sphere", "L1 scan failed during discovery (non-fatal):", err);
       }
     }
     if (options.autoTrack && transportResult.addresses.length > 0) {
@@ -15242,7 +15429,7 @@ var Sphere = class _Sphere {
    */
   async disableProvider(providerId) {
     if (providerId === this._storage.id) {
-      throw new Error("Cannot disable the main storage provider");
+      throw new SphereError("Cannot disable the main storage provider", "INVALID_CONFIG");
     }
     const provider = this.findProviderById(providerId);
     if (!provider) return false;
@@ -15445,10 +15632,10 @@ var Sphere = class _Sphere {
     this.ensureReady();
     const cleanNametag = this.cleanNametag(nametag);
     if (!isValidNametag(cleanNametag)) {
-      throw new Error("Invalid nametag format. Use lowercase alphanumeric, underscore, or hyphen (3-20 chars), or a valid phone number.");
+      throw new SphereError("Invalid nametag format. Use lowercase alphanumeric, underscore, or hyphen (3-20 chars), or a valid phone number.", "VALIDATION_ERROR");
     }
     if (this._identity?.nametag) {
-      throw new Error(`Nametag already registered for address ${this._currentAddressIndex}: @${this._identity.nametag}`);
+      throw new SphereError(`Nametag already registered for address ${this._currentAddressIndex}: @${this._identity.nametag}`, "ALREADY_INITIALIZED");
     }
     if (this._transport.publishIdentityBinding) {
       const success = await this._transport.publishIdentityBinding(
@@ -15458,7 +15645,7 @@ var Sphere = class _Sphere {
         cleanNametag
       );
       if (!success) {
-        throw new Error("Failed to register nametag. It may already be taken.");
+        throw new SphereError("Failed to register nametag. It may already be taken.", "VALIDATION_ERROR");
       }
     }
     this._identity.nametag = cleanNametag;
@@ -15474,19 +15661,19 @@ var Sphere = class _Sphere {
     }
     await this.persistAddressNametags();
     if (!this._payments.hasNametag()) {
-      console.log(`[Sphere] Minting nametag token for @${cleanNametag}...`);
+      logger.debug("Sphere", `Minting nametag token for @${cleanNametag}...`);
       const result = await this.mintNametag(cleanNametag);
       if (!result.success) {
-        console.warn(`[Sphere] Failed to mint nametag token: ${result.error}`);
+        logger.warn("Sphere", `Failed to mint nametag token: ${result.error}`);
       } else {
-        console.log(`[Sphere] Nametag token minted successfully`);
+        logger.debug("Sphere", `Nametag token minted successfully`);
       }
     }
     this.emitEvent("nametag:registered", {
       nametag: cleanNametag,
       addressIndex: this._currentAddressIndex
     });
-    console.log(`[Sphere] Nametag registered for address ${this._currentAddressIndex}:`, cleanNametag);
+    logger.debug("Sphere", `Nametag registered for address ${this._currentAddressIndex}:`, cleanNametag);
   }
   /**
    * Persist tracked addresses to storage (only minimal fields via StorageProvider)
@@ -15726,13 +15913,13 @@ var Sphere = class _Sphere {
                   this._identity.directAddress || "",
                   recoveredNametag
                 );
-                console.log(`[Sphere] Migrated legacy binding with nametag @${recoveredNametag}`);
+                logger.debug("Sphere", `Migrated legacy binding with nametag @${recoveredNametag}`);
                 return;
               }
             }
             const needsUpdate = !existing.directAddress || !existing.l1Address || !existing.chainPubkey || this._identity?.nametag && !existing.nametag;
             if (needsUpdate) {
-              console.log("[Sphere] Existing binding incomplete, re-publishing with full data");
+              logger.debug("Sphere", "Existing binding incomplete, re-publishing with full data");
               await this._transport.publishIdentityBinding(
                 this._identity.chainPubkey,
                 this._identity.l1Address,
@@ -15741,11 +15928,11 @@ var Sphere = class _Sphere {
               );
               return;
             }
-            console.log("[Sphere] Existing binding found, skipping re-publish");
+            logger.debug("Sphere", "Existing binding found, skipping re-publish");
             return;
           }
         } catch (e) {
-          console.warn("[Sphere] resolve() failed, skipping publish to avoid overwrite", e);
+          logger.warn("Sphere", "resolve() failed, skipping publish to avoid overwrite", e);
           return;
         }
       }
@@ -15757,12 +15944,12 @@ var Sphere = class _Sphere {
         nametag || void 0
       );
       if (success) {
-        console.log(`[Sphere] Identity binding published${nametag ? ` with nametag @${nametag}` : ""}`);
+        logger.debug("Sphere", `Identity binding published${nametag ? ` with nametag @${nametag}` : ""}`);
       } else if (nametag) {
-        console.warn(`[Sphere] Nametag @${nametag} is taken by another pubkey`);
+        logger.warn("Sphere", `Nametag @${nametag} is taken by another pubkey`);
       }
     } catch (error) {
-      console.warn(`[Sphere] Identity binding sync failed:`, error);
+      logger.warn("Sphere", `Identity binding sync failed:`, error);
     }
   }
   /**
@@ -15915,7 +16102,7 @@ var Sphere = class _Sphere {
     if (encryptedMnemonic) {
       const mnemonic = this.decrypt(encryptedMnemonic);
       if (!mnemonic) {
-        throw new Error("Failed to decrypt mnemonic");
+        throw new SphereError("Failed to decrypt mnemonic", "STORAGE_ERROR");
       }
       this._mnemonic = mnemonic;
       this._source = "mnemonic";
@@ -15923,7 +16110,7 @@ var Sphere = class _Sphere {
     } else if (encryptedMasterKey) {
       const masterKey = this.decrypt(encryptedMasterKey);
       if (!masterKey) {
-        throw new Error("Failed to decrypt master key");
+        throw new SphereError("Failed to decrypt master key", "STORAGE_ERROR");
       }
       this._mnemonic = null;
       if (this._source === "unknown") {
@@ -15935,7 +16122,7 @@ var Sphere = class _Sphere {
         derivationPath ?? void 0
       );
     } else {
-      throw new Error("No wallet data found in storage");
+      throw new SphereError("No wallet data found in storage", "NOT_INITIALIZED");
     }
     if (this._identity) {
       this._storage.setIdentity(this._identity);
@@ -15957,7 +16144,7 @@ var Sphere = class _Sphere {
         nametag
       };
       this._storage.setIdentity(this._identity);
-      console.log(`[Sphere] Restored to address ${this._currentAddressIndex}:`, this._identity.l1Address);
+      logger.debug("Sphere", `Restored to address ${this._currentAddressIndex}:`, this._identity.l1Address);
     } else if (this._identity && nametag) {
       this._identity.nametag = nametag;
     }
@@ -16148,7 +16335,7 @@ var Sphere = class _Sphere {
   // ===========================================================================
   ensureReady() {
     if (!this._initialized) {
-      throw new Error("Sphere not initialized");
+      throw new SphereError("Sphere not initialized", "NOT_INITIALIZED");
     }
   }
   emitEvent(type, data) {
@@ -16158,7 +16345,7 @@ var Sphere = class _Sphere {
       try {
         handler(data);
       } catch (error) {
-        console.error("[Sphere] Event handler error:", error);
+        logger.error("Sphere", "Event handler error:", error);
       }
     }
   }
@@ -16195,6 +16382,7 @@ var getSphere = Sphere.getInstance.bind(Sphere);
 var sphereExists = Sphere.exists.bind(Sphere);
 
 // core/currency.ts
+init_logger();
 var DEFAULT_TOKEN_DECIMALS = 18;
 function toSmallestUnit(amount, decimals = DEFAULT_TOKEN_DECIMALS) {
   if (!amount) return 0n;
@@ -16203,7 +16391,8 @@ function toSmallestUnit(amount, decimals = DEFAULT_TOKEN_DECIMALS) {
     const [integer, fraction = ""] = str.split(".");
     const paddedFraction = fraction.padEnd(decimals, "0").slice(0, decimals);
     return BigInt(integer + paddedFraction);
-  } catch {
+  } catch (err) {
+    logger.debug("Currency", "toSmallestUnit conversion failed", err);
     return 0n;
   }
 }
@@ -16227,6 +16416,8 @@ function formatAmount(amount, options = {}) {
 
 // core/index.ts
 init_bech32();
+init_logger();
+init_errors();
 
 // core/network-health.ts
 init_constants();
@@ -16418,6 +16609,9 @@ async function runCustomCheck(name, checkFn, timeoutMs) {
 // index.ts
 init_constants();
 
+// types/index.ts
+init_errors();
+
 // types/payment-session.ts
 function createPaymentSession(params) {
   const now = Date.now();
@@ -16477,22 +16671,11 @@ function createPaymentSessionError(code, message, recoverable = false, details)
   };
 }
 
-// types/index.ts
-var SphereError = class extends Error {
-  code;
-  cause;
-  constructor(message, code, cause) {
-    super(message);
-    this.name = "SphereError";
-    this.code = code;
-    this.cause = cause;
-  }
-};
-
 // index.ts
 init_constants();
 
 // validation/token-validator.ts
+init_logger();
 var TokenValidator = class {
   aggregatorClient = null;
   trustBase = null;
@@ -16617,7 +16800,7 @@ var TokenValidator = class {
           };
         }
       } catch (err) {
-        console.warn("SDK verification skipped:", err instanceof Error ? err.message : err);
+        logger.warn("Validation", "SDK verification skipped:", err instanceof Error ? err.message : err);
       }
     }
     return { isValid: true };
@@ -16662,7 +16845,7 @@ var TokenValidator = class {
       });
       return isSpent;
     } catch (err) {
-      console.warn("Error checking token state:", err);
+      logger.warn("Validation", "Error checking token state:", err);
       return false;
     }
   }
@@ -16825,6 +17008,8 @@ import {
 } from "@unicitylabs/nostr-js-sdk";
 
 // price/CoinGeckoPriceProvider.ts
+init_logger();
+init_errors();
 init_constants();
 var CoinGeckoPriceProvider = class {
   platform = "coingecko";
@@ -16876,7 +17061,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) {
@@ -16915,7 +17100,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,
@@ -16925,7 +17110,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)) {
@@ -16955,12 +17140,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);
@@ -17010,7 +17195,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 {
     }
@@ -17027,8 +17212,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
@@ -17047,7 +17231,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) {
@@ -17060,12 +17244,13 @@ var CoinGeckoPriceProvider = class {
 };
 
 // price/index.ts
+init_errors();
 function createPriceProvider(config) {
   switch (config.platform) {
     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");
   }
 }
 export {
@@ -17174,6 +17359,7 @@ export {
   isPaymentSessionTimedOut,
   isPhoneNumber2 as isPhoneNumber,
   isSQLiteDatabase,
+  isSphereError,
   isTextWalletEncrypted,
   isTokenKey,
   isValidBech32,
@@ -17184,6 +17370,7 @@ export {
   isWalletTextFormat,
   keyFromTokenId,
   loadSphere,
+  logger,
   mnemonicToSeedSync2 as mnemonicToSeedSync,
   normalizeNametag3 as normalizeNametag,
   normalizeSdkTokenToStorage,