@unicitylabs/sphere-sdk 0.5.3 → 0.5.5

package/dist/core/index.cjs

@@ -30,6 +30,125 @@ var __toESM = (mod2, isNodeMode, target) => (target = mod2 != null ? __create(__
 ));
 var __toCommonJS = (mod2) => __copyProps(__defProp({}, "__esModule", { value: true }), mod2);
 
+// 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 getAddressId(directAddress) {
   let hash = directAddress;
@@ -257,11 +376,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);
@@ -314,6 +433,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;
@@ -326,7 +446,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 = import_crypto_js.default.SHA256(import_crypto_js.default.enc.Hex.parse(scriptHex)).toString();
   return sha.match(/../g).reverse().join("");
@@ -336,6 +456,7 @@ var init_addressToScriptHash = __esm({
   "l1/addressToScriptHash.ts"() {
     "use strict";
     init_bech32();
+    init_errors();
     import_crypto_js = __toESM(require("crypto-js"), 1);
   }
 });
@@ -396,7 +517,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;
@@ -432,7 +553,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) => {
@@ -448,8 +569,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(() => {
@@ -466,7 +588,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);
   });
@@ -524,7 +646,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) => ({
@@ -576,7 +698,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;
@@ -592,7 +714,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;
   }
 }
@@ -621,6 +743,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;
@@ -651,6 +774,7 @@ __export(core_exports, {
   DEFAULT_DERIVATION_PATH: () => DEFAULT_DERIVATION_PATH2,
   DEFAULT_TOKEN_DECIMALS: () => DEFAULT_TOKEN_DECIMALS,
   Sphere: () => Sphere,
+  SphereError: () => SphereError,
   base58Decode: () => base58Decode,
   base58Encode: () => base58Encode,
   bytesToHex: () => bytesToHex2,
@@ -697,10 +821,12 @@ __export(core_exports, {
   importSphere: () => importSphere,
   initSphere: () => initSphere,
   isEncryptedData: () => isEncryptedData,
+  isSphereError: () => isSphereError,
   isValidBech32: () => isValidBech32,
   isValidNametag: () => isValidNametag,
   isValidPrivateKey: () => isValidPrivateKey,
   loadSphere: () => loadSphere,
+  logger: () => logger,
   mnemonicToEntropy: () => mnemonicToEntropy2,
   mnemonicToSeed: () => mnemonicToSeed2,
   mnemonicToSeedSync: () => mnemonicToSeedSync2,
@@ -721,7 +847,12 @@ __export(core_exports, {
 });
 module.exports = __toCommonJS(core_exports);
 
+// core/Sphere.ts
+init_logger();
+init_errors();
+
 // modules/payments/L1PaymentsModule.ts
+init_errors();
 init_constants();
 
 // l1/index.ts
@@ -733,6 +864,7 @@ var bip39 = __toESM(require("bip39"), 1);
 var import_crypto_js2 = __toESM(require("crypto-js"), 1);
 var import_elliptic = __toESM(require("elliptic"), 1);
 init_bech32();
+init_errors();
 var ec = new import_elliptic.default.ec("secp256k1");
 var CURVE_ORDER = BigInt(
   "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141"
@@ -767,7 +899,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,
@@ -795,11 +927,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 {
@@ -885,14 +1017,14 @@ function randomBytes(length) {
 }
 async function identityFromMnemonic(mnemonic, passphrase = "") {
   if (!validateMnemonic2(mnemonic)) {
-    throw new Error("Invalid mnemonic phrase");
+    throw new SphereError("Invalid mnemonic phrase", "INVALID_IDENTITY");
   }
   const seedHex = await mnemonicToSeed2(mnemonic, passphrase);
   return generateMasterKey(seedHex);
 }
 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);
@@ -940,12 +1072,19 @@ function generateAddressFromMasterKey(masterPrivateKey, index) {
 init_network();
 
 // l1/tx.ts
+init_logger();
+init_errors();
 init_network();
 init_bech32();
 var import_crypto_js5 = __toESM(require("crypto-js"), 1);
 var import_elliptic2 = __toESM(require("elliptic"), 1);
 
+// l1/vestingState.ts
+init_logger();
+init_errors();
+
 // l1/vesting.ts
+init_logger();
 init_network();
 var VESTING_THRESHOLD = 28e4;
 var currentBlockHeight = null;
@@ -1188,7 +1327,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 = () => {
@@ -1200,7 +1339,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...`);
         };
       });
     }
@@ -1218,7 +1357,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;
   }
@@ -1255,10 +1394,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 {
@@ -1335,6 +1474,7 @@ var VestingStateManager = class {
 var vestingState = new VestingStateManager();
 
 // l1/addressHelpers.ts
+init_errors();
 var WalletAddressHelper = class {
   /**
    * Find address by BIP32 derivation path
@@ -1380,16 +1520,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;
@@ -1448,9 +1589,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"
       );
     }
   }
@@ -1482,11 +1624,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;
@@ -1610,7 +1752,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");
@@ -1709,7 +1851,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;
@@ -1718,21 +1860,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) {
@@ -1799,7 +1941,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);
@@ -1854,8 +1996,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"
       );
     }
   }
@@ -1864,15 +2007,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;
@@ -2142,7 +2286,7 @@ var L1PaymentsModule = class {
   }
   ensureInitialized() {
     if (!this._initialized) {
-      throw new Error("L1PaymentsModule not initialized");
+      throw new SphereError("L1PaymentsModule not initialized", "NOT_INITIALIZED");
     }
   }
   _getWatchedAddresses() {
@@ -2164,6 +2308,7 @@ var L1PaymentsModule = class {
 };
 
 // modules/payments/TokenSplitCalculator.ts
+init_logger();
 var import_Token = require("@unicitylabs/state-transition-sdk/lib/token/Token");
 var import_CoinId = require("@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId");
 var TokenSplitCalculator = class {
@@ -2186,7 +2331,7 @@ var TokenSplitCalculator = class {
         const sdkToken = await import_Token.Token.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({
@@ -2195,14 +2340,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;
     }
@@ -2300,6 +2446,8 @@ var TokenSplitCalculator = class {
 };
 
 // modules/payments/TokenSplitExecutor.ts
+init_logger();
+init_errors();
 var import_Token2 = require("@unicitylabs/state-transition-sdk/lib/token/Token");
 var import_TokenId = require("@unicitylabs/state-transition-sdk/lib/token/TokenId");
 var import_TokenState = require("@unicitylabs/state-transition-sdk/lib/token/TokenState");
@@ -2339,7 +2487,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 import_CoinId2.CoinId(fromHex(coinIdHex));
     const seedString = `${tokenIdHex}_${splitAmount.toString()}_${remainderAmount.toString()}`;
     const recipientTokenId = new import_TokenId.TokenId(await sha2562(seedString));
@@ -2359,23 +2507,23 @@ var TokenSplitExecutor = class {
     const coinDataB = import_TokenCoinData.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 (0, import_InclusionProofUtils.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 (0, import_InclusionProofUtils.waitInclusionProof)(this.trustBase, this.client, commitment);
       const commTokenIdHex = toHex(commitment.transactionData.tokenId.bytes);
@@ -2388,7 +2536,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) => {
@@ -2396,12 +2544,12 @@ var TokenSplitExecutor = class {
       const state = new import_TokenState.TokenState(predicate, null);
       const token = await import_Token2.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 import_TransferCommitment.TransferCommitment.create(
       recipientTokenBeforeTransfer,
@@ -2413,11 +2561,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 (0, import_InclusionProofUtils.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,
@@ -2427,6 +2575,7 @@ var TokenSplitExecutor = class {
 };
 
 // modules/payments/NametagMinter.ts
+init_logger();
 var import_Token3 = require("@unicitylabs/state-transition-sdk/lib/token/Token");
 var import_TokenId2 = require("@unicitylabs/state-transition-sdk/lib/token/TokenId");
 var import_TokenType = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
@@ -2451,10 +2600,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)
@@ -2638,6 +2785,7 @@ function parseForkedKey(key) {
 }
 
 // registry/TokenRegistry.ts
+init_logger();
 init_constants();
 var FETCH_TIMEOUT_MS = 1e4;
 var TokenRegistry = class _TokenRegistry {
@@ -2859,14 +3007,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;
@@ -2876,7 +3022,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;
     }
   }
@@ -3353,7 +3499,13 @@ function getCurrentStateHash(txf) {
   return void 0;
 }
 
+// modules/payments/PaymentsModule.ts
+init_logger();
+init_errors();
+
 // modules/payments/InstantSplitExecutor.ts
+init_logger();
+init_errors();
 var import_Token4 = require("@unicitylabs/state-transition-sdk/lib/token/Token");
 var import_TokenId3 = require("@unicitylabs/state-transition-sdk/lib/token/TokenId");
 var import_TokenState3 = require("@unicitylabs/state-transition-sdk/lib/token/TokenState");
@@ -3409,7 +3561,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 import_CoinId3.CoinId(fromHex2(coinIdHex));
     const seedString = `${tokenIdHex}_${splitAmount.toString()}_${remainderAmount.toString()}_${Date.now()}`;
     const recipientTokenId = new import_TokenId3.TokenId(await sha2563(seedString));
@@ -3446,19 +3598,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 (0, import_InclusionProofUtils3.waitInclusionProof)(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);
@@ -3469,9 +3621,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,
@@ -3487,7 +3639,7 @@ var InstantSplitExecutor = class {
       recipientSalt
     );
     const mintedState = new import_TokenState3.TokenState(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();
@@ -3559,7 +3711,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),
@@ -3571,7 +3723,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 {
@@ -3585,7 +3737,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,
@@ -3634,7 +3786,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 })),
@@ -3643,14 +3795,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",
@@ -3658,12 +3810,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 (0, import_InclusionProofUtils3.waitInclusionProof)(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`
@@ -3681,38 +3833,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",
@@ -3720,7 +3872,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",
@@ -3742,7 +3894,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 })
         };
@@ -3753,6 +3905,8 @@ var InstantSplitExecutor = class {
 };
 
 // modules/payments/InstantSplitProcessor.ts
+init_logger();
+init_errors();
 var import_Token5 = require("@unicitylabs/state-transition-sdk/lib/token/Token");
 var import_TokenState4 = require("@unicitylabs/state-transition-sdk/lib/token/TokenState");
 var import_TokenType2 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
@@ -3847,27 +4001,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 import_TransferTransaction.TransferTransaction.fromJSON(burnTxJson);
-      console.log("[InstantSplitProcessor] Burn transaction validated");
+      logger.debug("InstantSplit", "Burn transaction validated");
       const mintDataJson = JSON.parse(bundle.recipientMintData);
       const mintData = await import_MintTransactionData2.MintTransactionData.fromJSON(mintDataJson);
       const mintCommitment = await import_MintCommitment2.MintCommitment.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 (0, import_InclusionProofUtils4.waitInclusionProof)(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 import_TokenType2.TokenType(fromHex3(bundle.tokenTypeHex));
       const senderMintedStateJson = JSON.parse(bundle.mintedTokenStateJson);
       const tokenJson = {
@@ -3878,17 +4032,17 @@ var InstantSplitProcessor = class {
         nametags: []
       };
       const mintedToken = await import_Token5.Token.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 import_TransferCommitment3.TransferCommitment.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 (0, import_InclusionProofUtils4.waitInclusionProof)(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 import_UnmaskedPredicate4.UnmaskedPredicate.create(
         mintData.tokenId,
@@ -3898,42 +4052,43 @@ var InstantSplitProcessor = class {
         transferSalt
       );
       const finalRecipientState = new import_TokenState4.TokenState(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 import_Token5.Token.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()];
@@ -3947,16 +4102,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,
@@ -3965,7 +4120,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,
@@ -3991,30 +4146,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 import_TransferCommitment3.TransferCommitment.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 import_MintTransactionData2.MintTransactionData.fromJSON(mintDataJson);
       const mintCommitment = await import_MintCommitment2.MintCommitment.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 import_TokenType2.TokenType(fromHex3(bundle.tokenTypeHex));
       const recipientSalt = fromHex3(bundle.recipientSaltHex);
       const recipientPredicate = await import_UnmaskedPredicate4.UnmaskedPredicate.create(
@@ -4033,19 +4188,19 @@ var InstantSplitProcessor = class {
         nametags: []
       };
       const mintedToken = await import_Token5.Token.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 import_TransferCommitment3.TransferCommitment.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 import_UnmaskedPredicate4.UnmaskedPredicate.create(
         mintData.tokenId,
@@ -4059,9 +4214,9 @@ var InstantSplitProcessor = class {
       finalTokenJson.state = finalState.toJSON();
       finalTokenJson.transactions = [transferTransaction.toJSON()];
       const finalToken = await import_Token5.Token.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,
@@ -4070,7 +4225,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,
@@ -4091,7 +4246,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 })
         };
@@ -4276,7 +4431,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;
 }
@@ -4479,11 +4634,6 @@ var PaymentsModule = class _PaymentsModule {
   }
   /** Price provider (optional) */
   priceProvider = null;
-  log(...args) {
-    if (this.moduleConfig.debug) {
-      console.log("[PaymentsModule]", ...args);
-    }
-  }
   // ===========================================================================
   // Lifecycle
   // ===========================================================================
@@ -4550,11 +4700,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) {
@@ -4563,14 +4713,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();
@@ -4586,8 +4736,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();
   }
   /**
@@ -4640,11 +4789,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());
@@ -4654,7 +4803,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) {
@@ -4672,7 +4821,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,
@@ -4700,7 +4849,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()),
@@ -4714,15 +4863,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 (0, import_InclusionProofUtils5.waitInclusionProof)(trustBase, stClient, commitment);
           const transferTx = commitment.toTransaction(inclusionProof);
@@ -4731,7 +4880,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({
@@ -4739,7 +4888,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 {
@@ -4748,7 +4897,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,
@@ -4782,7 +4931,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();
@@ -4790,7 +4939,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(
@@ -4817,8 +4966,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),
@@ -4826,7 +4976,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);
@@ -4847,11 +4997,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) {
@@ -4874,7 +5024,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();
@@ -4965,11 +5115,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());
@@ -4979,10 +5129,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",
@@ -4990,7 +5140,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);
@@ -5028,7 +5178,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();
@@ -5083,7 +5233,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();
@@ -5133,7 +5283,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) {
@@ -5142,14 +5292,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;
         }
@@ -5181,7 +5333,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({
@@ -5196,7 +5348,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;
   }
@@ -5218,11 +5370,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 = [];
@@ -5236,7 +5389,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(
@@ -5251,13 +5404,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);
@@ -5273,7 +5427,7 @@ var PaymentsModule = class _PaymentsModule {
         import_TransferCommitment4.TransferCommitment.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)
         );
       }
     }
@@ -5300,8 +5454,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();
     }
   }
@@ -5379,8 +5532,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) {
@@ -5401,11 +5553,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({
@@ -5428,10 +5580,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;
               }
             }
@@ -5539,7 +5691,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,
@@ -5547,7 +5699,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
@@ -5636,10 +5788,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 {
@@ -5694,10 +5846,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
@@ -5816,10 +5968,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)
@@ -5828,7 +5980,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 {
@@ -5839,9 +5991,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);
     }
   }
   // ===========================================================================
@@ -5865,7 +6017,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());
@@ -6012,7 +6164,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;
   }
@@ -6134,24 +6286,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++;
@@ -6159,7 +6311,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;
@@ -6175,19 +6327,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);
   }
@@ -6209,57 +6361,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 import_MintTransactionData3.MintTransactionData.fromJSON(mintDataJson);
         const mintCommitment = await import_MintCommitment3.MintCommitment.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 import_MintTransactionData3.MintTransactionData.fromJSON(mintDataJson);
         const mintCommitment = await import_MintCommitment3.MintCommitment.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 import_TransferCommitment4.TransferCommitment.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 import_TransferCommitment4.TransferCommitment.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,
@@ -6281,12 +6433,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();
@@ -6423,19 +6575,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, "");
     }
   }
@@ -6445,21 +6597,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);
     }
   }
   /**
@@ -6512,13 +6664,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;
         }
       }
@@ -6530,19 +6682,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;
@@ -6553,7 +6705,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;
   }
   /**
@@ -6583,7 +6735,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.
@@ -6606,10 +6758,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();
@@ -6666,7 +6818,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) {
@@ -6692,7 +6844,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}`);
     }
   }
   // ===========================================================================
@@ -6764,7 +6916,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
@@ -6793,7 +6945,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();
   }
   /**
@@ -6825,7 +6977,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
@@ -6905,7 +7057,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 {
@@ -6981,7 +7133,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.
@@ -7030,7 +7182,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;
           }
         }
@@ -7083,7 +7235,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
@@ -7093,7 +7245,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
@@ -7191,7 +7343,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;
@@ -7200,7 +7352,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;
@@ -7213,7 +7365,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,
@@ -7251,7 +7403,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);
           }
         });
@@ -7293,7 +7445,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);
   }
@@ -7398,8 +7550,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"
     );
   }
   /**
@@ -7470,32 +7623,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);
   }
   /**
@@ -7508,7 +7662,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(
@@ -7539,7 +7693,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);
     }
   }
   /**
@@ -7564,18 +7718,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 import_Token6.Token.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];
@@ -7595,12 +7750,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 import_TransferCommitment4.TransferCommitment.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();
@@ -7612,7 +7767,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();
@@ -7632,7 +7787,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",
@@ -7640,7 +7795,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";
@@ -7655,7 +7810,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;
@@ -7669,12 +7824,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;
       }
@@ -7691,7 +7846,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,
@@ -7699,28 +7854,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;
@@ -7728,7 +7883,7 @@ var PaymentsModule = class _PaymentsModule {
         try {
           sourceToken = await import_Token6.Token.fromJSON(sourceTokenInput);
         } catch (err) {
-          console.error("[Payments] Failed to parse sourceToken:", err);
+          logger.error("Payments", "Failed to parse sourceToken:", err);
           return;
         }
         try {
@@ -7742,16 +7897,16 @@ var PaymentsModule = class _PaymentsModule {
             const commitment = await import_TransferCommitment4.TransferCommitment.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);
@@ -7763,7 +7918,7 @@ var PaymentsModule = class _PaymentsModule {
               const commitment = await import_TransferCommitment4.TransferCommitment.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);
@@ -7771,33 +7926,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 === import_AddressScheme.AddressScheme.PROXY ? "PROXY" : "DIRECT"} finalization successful`);
+          logger.debug("Payments", `${addressScheme === import_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);
@@ -7838,12 +7993,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);
     }
   }
   // ===========================================================================
@@ -7858,15 +8013,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)}...`);
     }
   }
   // ===========================================================================
@@ -7878,20 +8033,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();
   }
@@ -7929,14 +8084,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);
@@ -7956,12 +8111,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";
@@ -7981,7 +8136,7 @@ var PaymentsModule = class _PaymentsModule {
         onProofReceived
       });
     } catch (error) {
-      this.log("submitAndPollForProof error:", error);
+      logger.debug("Payments", "submitAndPollForProof error:", error);
     }
   }
   /**
@@ -7989,7 +8144,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();
   }
   /**
@@ -7998,7 +8153,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
@@ -8011,7 +8166,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");
     }
   }
   /**
@@ -8028,7 +8183,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";
@@ -8067,12 +8222,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) {
@@ -8087,7 +8242,7 @@ var PaymentsModule = class _PaymentsModule {
   // ===========================================================================
   ensureInitialized() {
     if (!this.deps) {
-      throw new Error("PaymentsModule not initialized");
+      throw new SphereError("PaymentsModule not initialized", "NOT_INITIALIZED");
     }
   }
 };
@@ -8095,7 +8250,12 @@ function createPaymentsModule(config) {
   return new PaymentsModule(config);
 }
 
+// modules/payments/BackgroundCommitmentService.ts
+init_logger();
+init_errors();
+
 // modules/payments/TokenRecoveryService.ts
+init_logger();
 var import_TokenId4 = require("@unicitylabs/state-transition-sdk/lib/token/TokenId");
 var import_TokenState6 = require("@unicitylabs/state-transition-sdk/lib/token/TokenState");
 var import_TokenType4 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
@@ -8104,6 +8264,8 @@ var import_HashAlgorithm6 = require("@unicitylabs/state-transition-sdk/lib/hash/
 var import_UnmaskedPredicate6 = require("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate");
 
 // modules/communications/CommunicationsModule.ts
+init_logger();
+init_errors();
 init_constants();
 var CommunicationsModule = class {
   config;
@@ -8198,7 +8360,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`);
       }
     }
   }
@@ -8284,7 +8446,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);
           });
         }
       }
@@ -8484,7 +8646,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) {
@@ -8503,7 +8665,7 @@ var CommunicationsModule = class {
       try {
         handler(composing);
       } catch (error) {
-        console.error("[Communications] Composing handler error:", error);
+        logger.error("Communications", "Composing handler error:", error);
       }
     }
   }
@@ -8521,7 +8683,7 @@ var CommunicationsModule = class {
       try {
         handler(message);
       } catch (error) {
-        console.error("[Communications] Handler error:", error);
+        logger.error("Communications", "Handler error:", error);
       }
     }
   }
@@ -8562,7 +8724,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 };
     }
@@ -8570,7 +8732,7 @@ var CommunicationsModule = class {
   }
   ensureInitialized() {
     if (!this.deps) {
-      throw new Error("CommunicationsModule not initialized");
+      throw new SphereError("CommunicationsModule not initialized", "NOT_INITIALIZED");
     }
   }
 };
@@ -8580,6 +8742,8 @@ function createCommunicationsModule(config) {
 
 // modules/groupchat/GroupChatModule.ts
 var import_nostr_js_sdk2 = require("@unicitylabs/nostr-js-sdk");
+init_logger();
+init_errors();
 init_constants();
 
 // modules/groupchat/types.ts
@@ -8725,13 +8889,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;
     }
@@ -8771,7 +8937,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 = [];
@@ -8806,21 +8973,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);
   }
@@ -9055,7 +9222,8 @@ var GroupChatModule = class {
         },
         onComplete: () => {
         },
-        timeoutMs: 15e3
+        timeoutMs: 15e3,
+        timeoutLabel: "restoreJoinedGroups"
       }
     );
     if (groupIdsWithMembership.size === 0) return [];
@@ -9072,7 +9240,8 @@ var GroupChatModule = class {
             this.fetchMessages(groupId)
           ]);
         }
-      } catch {
+      } catch (error) {
+        logger.warn("GroupChat", "Failed to restore group", groupId, error);
       }
     }
     if (restoredGroups.length > 0) {
@@ -9105,7 +9274,8 @@ var GroupChatModule = class {
           },
           onComplete: () => {
           },
-          timeoutMs: 1e4
+          timeoutMs: 1e4,
+          timeoutLabel: "fetchAvailableGroups(metadata)"
         }
       ),
       this.oneshotSubscription(
@@ -9120,7 +9290,8 @@ var GroupChatModule = class {
           },
           onComplete: () => {
           },
-          timeoutMs: 1e4
+          timeoutMs: 1e4,
+          timeoutLabel: "fetchAvailableGroups(members)"
         }
       )
     ]);
@@ -9179,7 +9350,7 @@ var GroupChatModule = class {
           return true;
         }
       }
-      console.error("[GroupChat] Failed to join group", error);
+      logger.error("GroupChat", "Failed to join group", error);
       return false;
     }
   }
@@ -9209,7 +9380,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;
     }
   }
@@ -9260,10 +9431,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,
@@ -9275,7 +9444,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;
     }
   }
@@ -9302,7 +9471,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;
     }
   }
@@ -9322,7 +9491,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;
     }
   }
@@ -9372,7 +9541,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;
     }
   }
@@ -9411,7 +9580,8 @@ var GroupChatModule = class {
         this.schedulePersist();
         return fetchedMessages;
       },
-      timeoutMs: 1e4
+      timeoutMs: 1e4,
+      timeoutLabel: `fetchMessages(${groupId})`
     });
   }
   // ===========================================================================
@@ -9472,7 +9642,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;
     }
   }
@@ -9495,7 +9665,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;
     }
   }
@@ -9780,7 +9950,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;
       });
@@ -9960,7 +10130,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);
@@ -9975,12 +10146,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() {
@@ -12149,6 +12325,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;
@@ -12338,7 +12515,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) */
@@ -12364,7 +12541,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();
@@ -12372,9 +12549,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) {
@@ -12430,6 +12607,8 @@ init_constants();
 
 // core/encryption.ts
 var import_crypto_js6 = __toESM(require("crypto-js"), 1);
+init_errors();
+init_logger();
 var DEFAULT_ITERATIONS = 1e5;
 var KEY_SIZE = 256;
 var SALT_SIZE = 16;
@@ -12477,7 +12656,7 @@ function decrypt2(encryptedData, password) {
   });
   const result = decrypted.toString(import_crypto_js6.default.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;
 }
@@ -12486,7 +12665,7 @@ function decryptJson(encryptedData, password) {
   try {
     return JSON.parse(decrypted);
   } catch {
-    throw new Error("Decryption failed: invalid JSON data");
+    throw new SphereError("Decryption failed: invalid JSON data", "DECRYPTION_ERROR");
   }
 }
 function encryptSimple(plaintext, password) {
@@ -12496,7 +12675,7 @@ function decryptSimple(ciphertext, password) {
   const decrypted = import_crypto_js6.default.AES.decrypt(ciphertext, password);
   const result = decrypted.toString(import_crypto_js6.default.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;
 }
@@ -12510,7 +12689,8 @@ function decryptWithSalt(ciphertext, password, salt) {
     const decrypted = import_crypto_js6.default.AES.decrypt(ciphertext, key);
     const result = decrypted.toString(import_crypto_js6.default.enc.Utf8);
     return result || null;
-  } catch {
+  } catch (err) {
+    logger.debug("Encryption", "decryptWithSalt failed", err);
     return null;
   }
 }
@@ -12533,7 +12713,7 @@ function serializeEncrypted(data) {
 function deserializeEncrypted(serialized) {
   const parsed = JSON.parse(serialized);
   if (!isEncryptedData(parsed)) {
-    throw new Error("Invalid encrypted data format");
+    throw new SphereError("Invalid encrypted data format", "VALIDATION_ERROR");
   }
   return parsed;
 }
@@ -12542,6 +12722,7 @@ function generateRandomKey(bytes = 32) {
 }
 
 // core/scan.ts
+init_logger();
 async function scanAddressesImpl(deriveAddress, options = {}) {
   const maxAddresses = options.maxAddresses ?? 50;
   const gapLimit = options.gapLimit ?? 20;
@@ -12580,7 +12761,8 @@ async function scanAddressesImpl(deriveAddress, options = {}) {
                 nametag = tag;
                 nametagsFoundCount++;
               }
-            } catch {
+            } catch (err) {
+              logger.debug("Sphere", "Nametag resolution failed during scan", err);
             }
           }
           foundAddresses.push({
@@ -12597,7 +12779,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) {
@@ -12689,6 +12871,7 @@ init_network();
 var import_crypto_js7 = __toESM(require("crypto-js"), 1);
 
 // core/utils.ts
+init_errors();
 var SECP256K1_ORDER = BigInt("0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141");
 var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function isValidPrivateKey(hex) {
@@ -12728,7 +12911,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]);
   }
@@ -13011,6 +13194,7 @@ function parseAndDecryptWalletText(content, password) {
 
 // serialization/wallet-dat.ts
 var import_crypto_js8 = __toESM(require("crypto-js"), 1);
+init_errors();
 function uint8ArrayToWordArray(u8arr) {
   const hex = bytesToHex2(u8arr);
   return import_crypto_js8.default.enc.Hex.parse(hex);
@@ -13195,7 +13379,7 @@ async function decryptCMasterKey(cmk, password, onProgress) {
   );
   const result = import_crypto_js8.default.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;
 }
@@ -13490,6 +13674,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);
@@ -13517,8 +13702,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"
         );
       }
     }
@@ -13591,11 +13777,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()) {
@@ -13641,10 +13828,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" });
@@ -13654,8 +13841,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);
@@ -13686,16 +13874,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) {
@@ -13704,10 +13892,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" });
@@ -13717,24 +13905,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);
@@ -13752,14 +13941,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,
@@ -13767,7 +13956,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,
@@ -13775,38 +13964,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) {
@@ -13815,14 +14004,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;
   }
   /**
@@ -13848,26 +14037,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();
@@ -13876,11 +14065,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
@@ -13972,7 +14161,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);
@@ -14092,7 +14281,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 = [];
@@ -14172,7 +14361,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 = [];
@@ -14611,7 +14800,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;
@@ -14641,14 +14830,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);
@@ -14658,7 +14847,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) {
@@ -14681,12 +14870,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();
@@ -14697,9 +14886,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);
     });
   }
   /**
@@ -14713,16 +14902,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", {
@@ -14730,16 +14919,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);
       }
     }
   }
@@ -14778,7 +14967,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);
     });
   }
   /**
@@ -14812,7 +15001,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);
@@ -14842,7 +15031,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;
@@ -14909,13 +15098,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);
@@ -14966,10 +15156,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(
@@ -15025,7 +15215,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) {
@@ -15123,7 +15313,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;
@@ -15326,10 +15516,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(
@@ -15339,7 +15529,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;
@@ -15355,19 +15545,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)
@@ -15607,13 +15797,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,
@@ -15622,11 +15812,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;
         }
       }
@@ -15638,12 +15828,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);
     }
   }
   /**
@@ -15796,7 +15986,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";
@@ -15804,7 +15994,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") {
@@ -15816,7 +16006,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);
@@ -15838,7 +16028,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;
     }
@@ -16029,7 +16219,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) {
@@ -16039,7 +16229,7 @@ var Sphere = class _Sphere {
       try {
         handler(data);
       } catch (error) {
-        console.error("[Sphere] Event handler error:", error);
+        logger.error("Sphere", "Event handler error:", error);
       }
     }
   }
@@ -16076,6 +16266,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;
@@ -16084,7 +16275,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;
   }
 }
@@ -16113,6 +16305,8 @@ var CurrencyUtils = {
 
 // core/index.ts
 init_bech32();
+init_logger();
+init_errors();
 
 // core/network-health.ts
 init_constants();
@@ -16307,6 +16501,7 @@ async function runCustomCheck(name, checkFn, timeoutMs) {
   DEFAULT_DERIVATION_PATH,
   DEFAULT_TOKEN_DECIMALS,
   Sphere,
+  SphereError,
   base58Decode,
   base58Encode,
   bytesToHex,
@@ -16353,10 +16548,12 @@ async function runCustomCheck(name, checkFn, timeoutMs) {
   importSphere,
   initSphere,
   isEncryptedData,
+  isSphereError,
   isValidBech32,
   isValidNametag,
   isValidPrivateKey,
   loadSphere,
+  logger,
   mnemonicToEntropy,
   mnemonicToSeed,
   mnemonicToSeedSync,