@unicitylabs/sphere-sdk 0.1.4 → 0.1.6

package/dist/core/index.js

@@ -2153,50 +2153,56 @@ var NametagMinter = class {
 };
 
 // constants.ts
-var STORAGE_PREFIX = "sphere_";
 var DEFAULT_ENCRYPTION_KEY = "sphere-default-key";
-var STORAGE_KEYS = {
+var STORAGE_KEYS_GLOBAL = {
   /** Encrypted BIP39 mnemonic */
-  MNEMONIC: `${STORAGE_PREFIX}mnemonic`,
+  MNEMONIC: "mnemonic",
   /** Encrypted master private key */
-  MASTER_KEY: `${STORAGE_PREFIX}master_key`,
+  MASTER_KEY: "master_key",
   /** BIP32 chain code */
-  CHAIN_CODE: `${STORAGE_PREFIX}chain_code`,
+  CHAIN_CODE: "chain_code",
   /** HD derivation path (full path like m/44'/0'/0'/0/0) */
-  DERIVATION_PATH: `${STORAGE_PREFIX}derivation_path`,
+  DERIVATION_PATH: "derivation_path",
   /** Base derivation path (like m/44'/0'/0' without chain/index) */
-  BASE_PATH: `${STORAGE_PREFIX}base_path`,
+  BASE_PATH: "base_path",
   /** Derivation mode: bip32, wif_hmac, legacy_hmac */
-  DERIVATION_MODE: `${STORAGE_PREFIX}derivation_mode`,
+  DERIVATION_MODE: "derivation_mode",
   /** Wallet source: mnemonic, file, unknown */
-  WALLET_SOURCE: `${STORAGE_PREFIX}wallet_source`,
+  WALLET_SOURCE: "wallet_source",
   /** Wallet existence flag */
-  WALLET_EXISTS: `${STORAGE_PREFIX}wallet_exists`,
-  /** Registered nametag (legacy - single address) */
-  NAMETAG: `${STORAGE_PREFIX}nametag`,
+  WALLET_EXISTS: "wallet_exists",
   /** Current active address index */
-  CURRENT_ADDRESS_INDEX: `${STORAGE_PREFIX}current_address_index`,
-  /** Address nametags map (JSON: { "0": "alice", "1": "bob" }) */
-  ADDRESS_NAMETAGS: `${STORAGE_PREFIX}address_nametags`,
-  /** Token data */
-  TOKENS: `${STORAGE_PREFIX}tokens`,
-  /** Pending transfers */
-  PENDING_TRANSFERS: `${STORAGE_PREFIX}pending_transfers`,
-  /** Transfer outbox */
-  OUTBOX: `${STORAGE_PREFIX}outbox`,
-  /** Conversations */
-  CONVERSATIONS: `${STORAGE_PREFIX}conversations`,
-  /** Messages */
-  MESSAGES: `${STORAGE_PREFIX}messages`,
-  /** Transaction history */
-  TRANSACTION_HISTORY: `${STORAGE_PREFIX}transaction_history`,
-  /** Archived tokens (spent token history) */
-  ARCHIVED_TOKENS: `${STORAGE_PREFIX}archived_tokens`,
-  /** Tombstones (records of deleted/spent tokens) */
-  TOMBSTONES: `${STORAGE_PREFIX}tombstones`,
-  /** Forked tokens (alternative histories) */
-  FORKED_TOKENS: `${STORAGE_PREFIX}forked_tokens`
+  CURRENT_ADDRESS_INDEX: "current_address_index",
+  /** Index of address nametags (JSON: { "0": "alice", "1": "bob" }) - for discovery */
+  ADDRESS_NAMETAGS: "address_nametags"
+};
+var STORAGE_KEYS_ADDRESS = {
+  /** Pending transfers for this address */
+  PENDING_TRANSFERS: "pending_transfers",
+  /** Transfer outbox for this address */
+  OUTBOX: "outbox",
+  /** Conversations for this address */
+  CONVERSATIONS: "conversations",
+  /** Messages for this address */
+  MESSAGES: "messages",
+  /** Transaction history for this address */
+  TRANSACTION_HISTORY: "transaction_history"
 };
+var STORAGE_KEYS = {
+  ...STORAGE_KEYS_GLOBAL,
+  ...STORAGE_KEYS_ADDRESS
+};
+function getAddressId(directAddress) {
+  let hash = directAddress;
+  if (hash.startsWith("DIRECT://")) {
+    hash = hash.slice(9);
+  } else if (hash.startsWith("DIRECT:")) {
+    hash = hash.slice(7);
+  }
+  const first = hash.slice(0, 6).toLowerCase();
+  const last = hash.slice(-6).toLowerCase();
+  return `DIRECT_${first}_${last}`;
+}
 var DEFAULT_BASE_PATH = "m/44'/0'/0'";
 var DEFAULT_DERIVATION_PATH2 = `${DEFAULT_BASE_PATH}/0/0`;
 var LIMITS = {
@@ -2365,6 +2371,7 @@ function txfToToken(tokenId, txf) {
     coinId,
     symbol: isNft ? "NFT" : "UCT",
     name: isNft ? "NFT" : "Token",
+    decimals: isNft ? 0 : 8,
     amount: totalAmount.toString(),
     status: determineTokenStatus(txf),
     createdAt: now,
@@ -2379,9 +2386,6 @@ async function buildTxfStorageData(tokens, meta, options) {
       formatVersion: "2.0"
     }
   };
-  if (options?.nametag) {
-    storageData._nametag = options.nametag;
-  }
   if (options?.tombstones && options.tombstones.length > 0) {
     storageData._tombstones = options.tombstones;
   }
@@ -2521,6 +2525,300 @@ function getCurrentStateHash(txf) {
   return void 0;
 }
 
+// registry/token-registry.testnet.json
+var token_registry_testnet_default = [
+  {
+    network: "unicity:testnet",
+    assetKind: "non-fungible",
+    name: "unicity",
+    description: "Unicity testnet token type",
+    id: "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "unicity",
+    symbol: "UCT",
+    decimals: 18,
+    description: "Unicity testnet native coin",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity_logo_32.png" }
+    ],
+    id: "455ad8720656b08e8dbd5bac1f3c73eeea5431565f6c1c3af742b1aa12d41d89"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "unicity-usd",
+    symbol: "USDU",
+    decimals: 6,
+    description: "Unicity testnet USD stablecoin",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/usdu_logo_32.png" }
+    ],
+    id: "8f0f3d7a5e7297be0ee98c63b81bcebb2740f43f616566fc290f9823a54f52d7"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "unicity-eur",
+    symbol: "EURU",
+    decimals: 6,
+    description: "Unicity testnet EUR stablecoin",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/euru_logo_32.png" }
+    ],
+    id: "5e160d5e9fdbb03b553fb9c3f6e6c30efa41fa807be39fb4f18e43776e492925"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "solana",
+    symbol: "SOL",
+    decimals: 9,
+    description: "Solana testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/sol.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/sol.png" }
+    ],
+    id: "dee5f8ce778562eec90e9c38a91296a023210ccc76ff4c29d527ac3eb64ade93"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "bitcoin",
+    symbol: "BTC",
+    decimals: 8,
+    description: "Bitcoin testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/btc.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/btc.png" }
+    ],
+    id: "86bc190fcf7b2d07c6078de93db803578760148b16d4431aa2f42a3241ff0daa"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "ethereum",
+    symbol: "ETH",
+    decimals: 18,
+    description: "Ethereum testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/eth.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/eth.png" }
+    ],
+    id: "3c2450f2fd867e7bb60c6a69d7ad0e53ce967078c201a3ecaa6074ed4c0deafb"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "alpha_test",
+    symbol: "ALPHT",
+    decimals: 8,
+    description: "ALPHA testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/alpha_coin.png" }
+    ],
+    id: "cde78ded16ef65818a51f43138031c4284e519300ab0cb60c30a8f9078080e5f"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "tether",
+    symbol: "USDT",
+    decimals: 6,
+    description: "Tether (Ethereum) testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/usdt.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/usdt.png" }
+    ],
+    id: "40d25444648418fe7efd433e147187a3a6adf049ac62bc46038bda5b960bf690"
+  },
+  {
+    network: "unicity:testnet",
+    assetKind: "fungible",
+    name: "usd-coin",
+    symbol: "USDC",
+    decimals: 6,
+    description: "USDC (Ethereum) testnet coin on Unicity",
+    icons: [
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/svg/icon/usdc.svg" },
+      { url: "https://raw.githubusercontent.com/spothq/cryptocurrency-icons/master/32/icon/usdc.png" }
+    ],
+    id: "2265121770fa6f41131dd9a6cc571e28679263d09a53eb2642e145b5b9a5b0a2"
+  }
+];
+
+// registry/TokenRegistry.ts
+var TokenRegistry = class _TokenRegistry {
+  static instance = null;
+  definitionsById;
+  definitionsBySymbol;
+  definitionsByName;
+  constructor() {
+    this.definitionsById = /* @__PURE__ */ new Map();
+    this.definitionsBySymbol = /* @__PURE__ */ new Map();
+    this.definitionsByName = /* @__PURE__ */ new Map();
+    this.loadRegistry();
+  }
+  /**
+   * Get singleton instance of TokenRegistry
+   */
+  static getInstance() {
+    if (!_TokenRegistry.instance) {
+      _TokenRegistry.instance = new _TokenRegistry();
+    }
+    return _TokenRegistry.instance;
+  }
+  /**
+   * Reset the singleton instance (useful for testing)
+   */
+  static resetInstance() {
+    _TokenRegistry.instance = null;
+  }
+  /**
+   * Load registry data from bundled JSON
+   */
+  loadRegistry() {
+    const definitions = token_registry_testnet_default;
+    for (const def of definitions) {
+      const idLower = def.id.toLowerCase();
+      this.definitionsById.set(idLower, def);
+      if (def.symbol) {
+        this.definitionsBySymbol.set(def.symbol.toUpperCase(), def);
+      }
+      this.definitionsByName.set(def.name.toLowerCase(), def);
+    }
+  }
+  // ===========================================================================
+  // Lookup Methods
+  // ===========================================================================
+  /**
+   * Get token definition by hex coin ID
+   * @param coinId - 64-character hex string
+   * @returns Token definition or undefined if not found
+   */
+  getDefinition(coinId) {
+    if (!coinId) return void 0;
+    return this.definitionsById.get(coinId.toLowerCase());
+  }
+  /**
+   * Get token definition by symbol (e.g., "UCT", "BTC")
+   * @param symbol - Token symbol (case-insensitive)
+   * @returns Token definition or undefined if not found
+   */
+  getDefinitionBySymbol(symbol) {
+    if (!symbol) return void 0;
+    return this.definitionsBySymbol.get(symbol.toUpperCase());
+  }
+  /**
+   * Get token definition by name (e.g., "bitcoin", "ethereum")
+   * @param name - Token name (case-insensitive)
+   * @returns Token definition or undefined if not found
+   */
+  getDefinitionByName(name) {
+    if (!name) return void 0;
+    return this.definitionsByName.get(name.toLowerCase());
+  }
+  /**
+   * Get token symbol for a coin ID
+   * @param coinId - 64-character hex string
+   * @returns Symbol (e.g., "UCT") or truncated ID if not found
+   */
+  getSymbol(coinId) {
+    const def = this.getDefinition(coinId);
+    if (def?.symbol) {
+      return def.symbol;
+    }
+    return coinId.slice(0, 6).toUpperCase();
+  }
+  /**
+   * Get token name for a coin ID
+   * @param coinId - 64-character hex string
+   * @returns Name (e.g., "Bitcoin") or coin ID if not found
+   */
+  getName(coinId) {
+    const def = this.getDefinition(coinId);
+    if (def?.name) {
+      return def.name.charAt(0).toUpperCase() + def.name.slice(1);
+    }
+    return coinId;
+  }
+  /**
+   * Get decimal places for a coin ID
+   * @param coinId - 64-character hex string
+   * @returns Decimals or 0 if not found
+   */
+  getDecimals(coinId) {
+    const def = this.getDefinition(coinId);
+    return def?.decimals ?? 0;
+  }
+  /**
+   * Get icon URL for a coin ID
+   * @param coinId - 64-character hex string
+   * @param preferPng - Prefer PNG format over SVG
+   * @returns Icon URL or null if not found
+   */
+  getIconUrl(coinId, preferPng = true) {
+    const def = this.getDefinition(coinId);
+    if (!def?.icons || def.icons.length === 0) {
+      return null;
+    }
+    if (preferPng) {
+      const pngIcon = def.icons.find((i) => i.url.toLowerCase().includes(".png"));
+      if (pngIcon) return pngIcon.url;
+    }
+    return def.icons[0].url;
+  }
+  /**
+   * Check if a coin ID is known in the registry
+   * @param coinId - 64-character hex string
+   * @returns true if the coin is in the registry
+   */
+  isKnown(coinId) {
+    return this.definitionsById.has(coinId.toLowerCase());
+  }
+  /**
+   * Get all token definitions
+   * @returns Array of all token definitions
+   */
+  getAllDefinitions() {
+    return Array.from(this.definitionsById.values());
+  }
+  /**
+   * Get all fungible token definitions
+   * @returns Array of fungible token definitions
+   */
+  getFungibleTokens() {
+    return this.getAllDefinitions().filter((def) => def.assetKind === "fungible");
+  }
+  /**
+   * Get all non-fungible token definitions
+   * @returns Array of non-fungible token definitions
+   */
+  getNonFungibleTokens() {
+    return this.getAllDefinitions().filter((def) => def.assetKind === "non-fungible");
+  }
+  /**
+   * Get coin ID by symbol
+   * @param symbol - Token symbol (e.g., "UCT")
+   * @returns Coin ID hex string or undefined if not found
+   */
+  getCoinIdBySymbol(symbol) {
+    const def = this.getDefinitionBySymbol(symbol);
+    return def?.id;
+  }
+  /**
+   * Get coin ID by name
+   * @param name - Token name (e.g., "bitcoin")
+   * @returns Coin ID hex string or undefined if not found
+   */
+  getCoinIdByName(name) {
+    const def = this.getDefinitionByName(name);
+    return def?.id;
+  }
+};
+
 // modules/payments/PaymentsModule.ts
 import { Token as SdkToken2 } from "@unicitylabs/state-transition-sdk/lib/token/Token";
 import { CoinId as CoinId3 } from "@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId";
@@ -2531,11 +2829,26 @@ import { AddressScheme } from "@unicitylabs/state-transition-sdk/lib/address/Add
 import { UnmaskedPredicate as UnmaskedPredicate3 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
 import { TokenState as TokenState3 } from "@unicitylabs/state-transition-sdk/lib/token/TokenState";
 import { HashAlgorithm as HashAlgorithm3 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
+function enrichWithRegistry(info) {
+  const registry = TokenRegistry.getInstance();
+  const def = registry.getDefinition(info.coinId);
+  if (def) {
+    return {
+      ...info,
+      symbol: def.symbol || info.symbol,
+      name: def.name.charAt(0).toUpperCase() + def.name.slice(1),
+      decimals: def.decimals ?? 0,
+      iconUrl: registry.getIconUrl(info.coinId) ?? void 0
+    };
+  }
+  return info;
+}
 async function parseTokenInfo(tokenData) {
   const defaultInfo = {
     coinId: "ALPHA",
     symbol: "ALPHA",
     name: "Alpha Token",
+    decimals: 0,
     amount: "0"
   };
   try {
@@ -2556,23 +2869,25 @@ async function parseTokenInfo(tokenData) {
           }
           if (coinIdObj instanceof CoinId3) {
             const coinIdHex = coinIdObj.toJSON();
-            return {
+            return enrichWithRegistry({
               coinId: coinIdHex,
               symbol: coinIdHex.slice(0, 8),
               name: `Token ${coinIdHex.slice(0, 8)}`,
+              decimals: 0,
               amount: String(amount ?? "0"),
               tokenId: defaultInfo.tokenId
-            };
+            });
           } else if (coinIdObj && typeof coinIdObj === "object" && "bytes" in coinIdObj) {
             const bytes = coinIdObj.bytes;
             const coinIdHex = Buffer.isBuffer(bytes) ? bytes.toString("hex") : Array.isArray(bytes) ? Buffer.from(bytes).toString("hex") : String(bytes);
-            return {
+            return enrichWithRegistry({
               coinId: coinIdHex,
               symbol: coinIdHex.slice(0, 8),
               name: `Token ${coinIdHex.slice(0, 8)}`,
+              decimals: 0,
               amount: String(amount ?? "0"),
               tokenId: defaultInfo.tokenId
-            };
+            });
           }
         }
       }
@@ -2587,13 +2902,14 @@ async function parseTokenInfo(tokenData) {
             if (Array.isArray(firstEntry) && firstEntry.length === 2) {
               const [coinIdHex, amount] = firstEntry;
               const coinIdStr = typeof coinIdHex === "string" ? coinIdHex : String(coinIdHex);
-              return {
+              return enrichWithRegistry({
                 coinId: coinIdStr,
                 symbol: coinIdStr.slice(0, 8),
                 name: `Token ${coinIdStr.slice(0, 8)}`,
+                decimals: 0,
                 amount: String(amount),
                 tokenId: defaultInfo.tokenId
-              };
+              });
             }
           }
         }
@@ -2608,25 +2924,27 @@ async function parseTokenInfo(tokenData) {
           const firstEntry = coinData[0];
           if (Array.isArray(firstEntry) && firstEntry.length === 2) {
             const [coinIdHex, amount] = firstEntry;
-            return {
+            return enrichWithRegistry({
               coinId: String(coinIdHex),
               symbol: String(coinIdHex).slice(0, 8),
               name: `Token ${String(coinIdHex).slice(0, 8)}`,
+              decimals: 0,
               amount: String(amount),
               tokenId: genesis.tokenId
-            };
+            });
           }
         } else if (typeof coinData === "object") {
           const coinEntries = Object.entries(coinData);
           if (coinEntries.length > 0) {
             const [coinId, amount] = coinEntries[0];
-            return {
+            return enrichWithRegistry({
               coinId,
               symbol: coinId.slice(0, 8),
               name: `Token ${coinId.slice(0, 8)}`,
+              decimals: 0,
               amount: String(amount),
               tokenId: genesis.tokenId
-            };
+            });
           }
         }
       }
@@ -2640,25 +2958,27 @@ async function parseTokenInfo(tokenData) {
         const firstEntry = coinData[0];
         if (Array.isArray(firstEntry) && firstEntry.length === 2) {
           const [coinIdHex, amount] = firstEntry;
-          return {
+          return enrichWithRegistry({
             coinId: String(coinIdHex),
             symbol: String(coinIdHex).slice(0, 8),
             name: `Token ${String(coinIdHex).slice(0, 8)}`,
+            decimals: 0,
             amount: String(amount),
             tokenId: defaultInfo.tokenId
-          };
+          });
         }
       } else if (typeof coinData === "object") {
         const coinEntries = Object.entries(coinData);
         if (coinEntries.length > 0) {
           const [coinId, amount] = coinEntries[0];
-          return {
+          return enrichWithRegistry({
             coinId,
             symbol: coinId.slice(0, 8),
             name: `Token ${coinId.slice(0, 8)}`,
+            decimals: 0,
             amount: String(amount),
             tokenId: defaultInfo.tokenId
-          };
+          });
         }
       }
     }
@@ -2840,37 +3160,24 @@ var PaymentsModule = class {
    */
   async load() {
     this.ensureInitialized();
-    const data = await this.deps.storage.get(STORAGE_KEYS.TOKENS);
-    if (data) {
+    const providers = this.getTokenStorageProviders();
+    for (const [id, provider] of providers) {
       try {
-        const parsed = JSON.parse(data);
-        const tokens = parsed.tokens || [];
-        this.tokens.clear();
-        for (const token of tokens) {
-          this.tokens.set(token.id, token);
-        }
-        if (Array.isArray(parsed.tombstones)) {
-          this.tombstones = parsed.tombstones.filter(
-            (t) => typeof t === "object" && t !== null && typeof t.tokenId === "string" && typeof t.stateHash === "string"
-          );
-        }
-        if (parsed.archivedTokens && typeof parsed.archivedTokens === "object") {
-          this.archivedTokens = new Map(Object.entries(parsed.archivedTokens));
-        }
-        if (parsed.forkedTokens && typeof parsed.forkedTokens === "object") {
-          this.forkedTokens = new Map(Object.entries(parsed.forkedTokens));
-        }
-        if (parsed.nametag) {
-          this.nametag = parsed.nametag;
+        const result = await provider.load();
+        if (result.success && result.data) {
+          this.loadFromStorageData(result.data);
+          this.log(`Loaded from provider ${id}: ${this.tokens.size} tokens`);
+          break;
         }
-        this.log(`Loaded ${this.tokens.size} tokens, ${this.tombstones.length} tombstones, ${this.archivedTokens.size} archived`);
       } catch (err) {
-        console.error("[Payments] Failed to parse stored data:", err);
+        console.error(`[Payments] Failed to load from provider ${id}:`, err);
       }
     }
-    await this.loadTokensFromFileStorage();
+    if (this.tokens.size === 0) {
+      await this.loadTokensFromFileStorage();
+    }
     await this.loadNametagFromFileStorage();
-    const historyData = await this.deps.storage.get(STORAGE_KEYS.TRANSACTION_HISTORY);
+    const historyData = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
     if (historyData) {
       try {
         this.transactionHistory = JSON.parse(historyData);
@@ -2878,7 +3185,7 @@ var PaymentsModule = class {
         this.transactionHistory = [];
       }
     }
-    const pending2 = await this.deps.storage.get(STORAGE_KEYS.PENDING_TRANSFERS);
+    const pending2 = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
     if (pending2) {
       const transfers = JSON.parse(pending2);
       for (const transfer of transfers) {
@@ -2976,6 +3283,8 @@ var PaymentsModule = class {
           coinId: request.coinId,
           symbol: this.getCoinSymbol(request.coinId),
           name: this.getCoinName(request.coinId),
+          decimals: this.getCoinDecimals(request.coinId),
+          iconUrl: this.getCoinIconUrl(request.coinId),
           amount: splitPlan.remainderAmount.toString(),
           status: "confirmed",
           createdAt: Date.now(),
@@ -3044,20 +3353,25 @@ var PaymentsModule = class {
    * Get coin symbol from coinId
    */
   getCoinSymbol(coinId) {
-    const symbols = {
-      "UCT": "UCT"
-      // Add more as needed
-    };
-    return symbols[coinId] || coinId.slice(0, 6).toUpperCase();
+    return TokenRegistry.getInstance().getSymbol(coinId);
   }
   /**
    * Get coin name from coinId
    */
   getCoinName(coinId) {
-    const names = {
-      "UCT": "Unicity Token"
-    };
-    return names[coinId] || coinId;
+    return TokenRegistry.getInstance().getName(coinId);
+  }
+  /**
+   * Get coin decimals from coinId
+   */
+  getCoinDecimals(coinId) {
+    return TokenRegistry.getInstance().getDecimals(coinId);
+  }
+  /**
+   * Get coin icon URL from coinId
+   */
+  getCoinIconUrl(coinId) {
+    return TokenRegistry.getInstance().getIconUrl(coinId) ?? void 0;
   }
   // ===========================================================================
   // Public API - Payment Requests
@@ -3532,6 +3846,8 @@ var PaymentsModule = class {
               coinId: tokenInfo.coinId,
               symbol: tokenInfo.symbol,
               name: tokenInfo.name,
+              decimals: tokenInfo.decimals,
+              iconUrl: tokenInfo.iconUrl,
               amount: tokenInfo.amount,
               status: "confirmed",
               createdAt: data.receivedAt || Date.now(),
@@ -3787,7 +4103,7 @@ var PaymentsModule = class {
     };
     this.transactionHistory.push(historyEntry);
     await this.deps.storage.set(
-      STORAGE_KEYS.TRANSACTION_HISTORY,
+      STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY,
       JSON.stringify(this.transactionHistory)
     );
   }
@@ -4327,6 +4643,8 @@ var PaymentsModule = class {
         coinId: tokenInfo.coinId,
         symbol: tokenInfo.symbol,
         name: tokenInfo.name,
+        decimals: tokenInfo.decimals,
+        iconUrl: tokenInfo.iconUrl,
         amount: tokenInfo.amount,
         status: "confirmed",
         createdAt: Date.now(),
@@ -4380,28 +4698,32 @@ var PaymentsModule = class {
   // Private: Storage
   // ===========================================================================
   async save() {
-    const tokens = Array.from(this.tokens.values());
-    const data = {
-      tokens,
-      tombstones: this.tombstones.length > 0 ? this.tombstones : void 0,
-      archivedTokens: this.archivedTokens.size > 0 ? Object.fromEntries(this.archivedTokens) : void 0,
-      forkedTokens: this.forkedTokens.size > 0 ? Object.fromEntries(this.forkedTokens) : void 0,
-      nametag: this.nametag || void 0
-    };
-    await this.deps.storage.set(STORAGE_KEYS.TOKENS, JSON.stringify(data));
+    const providers = this.getTokenStorageProviders();
+    if (providers.size === 0) {
+      this.log("No token storage providers - tokens not persisted");
+      return;
+    }
+    const data = await this.createStorageData();
+    for (const [id, provider] of providers) {
+      try {
+        await provider.save(data);
+      } catch (err) {
+        console.error(`[Payments] Failed to save to provider ${id}:`, err);
+      }
+    }
   }
   async saveToOutbox(transfer, recipient) {
     const outbox = await this.loadOutbox();
     outbox.push({ transfer, recipient, createdAt: Date.now() });
-    await this.deps.storage.set(STORAGE_KEYS.OUTBOX, JSON.stringify(outbox));
+    await this.deps.storage.set(STORAGE_KEYS_ADDRESS.OUTBOX, JSON.stringify(outbox));
   }
   async removeFromOutbox(transferId) {
     const outbox = await this.loadOutbox();
     const filtered = outbox.filter((e) => e.transfer.id !== transferId);
-    await this.deps.storage.set(STORAGE_KEYS.OUTBOX, JSON.stringify(filtered));
+    await this.deps.storage.set(STORAGE_KEYS_ADDRESS.OUTBOX, JSON.stringify(filtered));
   }
   async loadOutbox() {
-    const data = await this.deps.storage.get(STORAGE_KEYS.OUTBOX);
+    const data = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.OUTBOX);
     return data ? JSON.parse(data) : [];
   }
   async createStorageData() {
@@ -4414,7 +4736,6 @@ var PaymentsModule = class {
         ipnsName: this.deps.identity.ipnsName ?? ""
       },
       {
-        nametag: this.nametag || void 0,
         tombstones: this.tombstones,
         archivedTokens: this.archivedTokens,
         forkedTokens: this.forkedTokens
@@ -5528,6 +5849,7 @@ var Sphere = class _Sphere {
   _derivationMode = "bip32";
   _basePath = DEFAULT_BASE_PATH;
   _currentAddressIndex = 0;
+  /** Map of addressId -> (nametagIndex -> nametag). Supports multiple nametags per address (e.g., from Nostr recovery) */
   _addressNametags = /* @__PURE__ */ new Map();
   // Providers
   _storage;
@@ -5563,9 +5885,9 @@ var Sphere = class _Sphere {
       if (!storage.isConnected()) {
         await storage.connect();
       }
-      const mnemonic = await storage.get(STORAGE_KEYS.MNEMONIC);
+      const mnemonic = await storage.get(STORAGE_KEYS_GLOBAL.MNEMONIC);
       if (mnemonic) return true;
-      const masterKey = await storage.get(STORAGE_KEYS.MASTER_KEY);
+      const masterKey = await storage.get(STORAGE_KEYS_GLOBAL.MASTER_KEY);
       if (masterKey) return true;
       return false;
     } catch {
@@ -5736,20 +6058,20 @@ var Sphere = class _Sphere {
   }
   /**
    * Clear wallet data from storage
+   * Note: Token data is cleared via TokenStorageProvider, not here
    */
   static async clear(storage) {
-    await storage.remove(STORAGE_KEYS.MNEMONIC);
-    await storage.remove(STORAGE_KEYS.MASTER_KEY);
-    await storage.remove(STORAGE_KEYS.CHAIN_CODE);
-    await storage.remove(STORAGE_KEYS.DERIVATION_PATH);
-    await storage.remove(STORAGE_KEYS.BASE_PATH);
-    await storage.remove(STORAGE_KEYS.DERIVATION_MODE);
-    await storage.remove(STORAGE_KEYS.WALLET_SOURCE);
-    await storage.remove(STORAGE_KEYS.WALLET_EXISTS);
-    await storage.remove(STORAGE_KEYS.NAMETAG);
-    await storage.remove(STORAGE_KEYS.TOKENS);
-    await storage.remove(STORAGE_KEYS.PENDING_TRANSFERS);
-    await storage.remove(STORAGE_KEYS.OUTBOX);
+    await storage.remove(STORAGE_KEYS_GLOBAL.MNEMONIC);
+    await storage.remove(STORAGE_KEYS_GLOBAL.MASTER_KEY);
+    await storage.remove(STORAGE_KEYS_GLOBAL.CHAIN_CODE);
+    await storage.remove(STORAGE_KEYS_GLOBAL.DERIVATION_PATH);
+    await storage.remove(STORAGE_KEYS_GLOBAL.BASE_PATH);
+    await storage.remove(STORAGE_KEYS_GLOBAL.DERIVATION_MODE);
+    await storage.remove(STORAGE_KEYS_GLOBAL.WALLET_SOURCE);
+    await storage.remove(STORAGE_KEYS_GLOBAL.WALLET_EXISTS);
+    await storage.remove(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS);
+    await storage.remove(STORAGE_KEYS_ADDRESS.PENDING_TRANSFERS);
+    await storage.remove(STORAGE_KEYS_ADDRESS.OUTBOX);
     if (_Sphere.instance) {
       await _Sphere.instance.destroy();
     }
@@ -6349,22 +6671,47 @@ var Sphere = class _Sphere {
     return this._currentAddressIndex;
   }
   /**
-   * Get nametag for a specific address index
+   * Get primary nametag for a specific address
+   *
+   * @param addressId - Address identifier (DIRECT://xxx), defaults to current address
+   * @returns Primary nametag (index 0) or undefined if not registered
+   */
+  getNametagForAddress(addressId) {
+    const id = addressId ?? this.getCurrentAddressId();
+    if (!id) return void 0;
+    const nametagsMap = this._addressNametags.get(id);
+    return nametagsMap?.get(0);
+  }
+  /**
+   * Get all nametags for a specific address
    *
-   * @param index - Address index (default: current address)
-   * @returns Nametag or undefined if not registered
+   * @param addressId - Address identifier (DIRECT://xxx), defaults to current address
+   * @returns Map of nametagIndex to nametag, or undefined if no nametags
    */
-  getNametagForAddress(index) {
-    const addressIndex = index ?? this._currentAddressIndex;
-    return this._addressNametags.get(addressIndex);
+  getNametagsForAddress(addressId) {
+    const id = addressId ?? this.getCurrentAddressId();
+    if (!id) return void 0;
+    const nametagsMap = this._addressNametags.get(id);
+    return nametagsMap ? new Map(nametagsMap) : void 0;
   }
   /**
    * Get all registered address nametags
    *
-   * @returns Map of address index to nametag
+   * @returns Map of addressId to (nametagIndex -> nametag)
    */
   getAllAddressNametags() {
-    return new Map(this._addressNametags);
+    const result = /* @__PURE__ */ new Map();
+    this._addressNametags.forEach((nametagsMap, addressId) => {
+      result.set(addressId, new Map(nametagsMap));
+    });
+    return result;
+  }
+  /**
+   * Get current address identifier (DIRECT://xxx format)
+   */
+  getCurrentAddressId() {
+    if (!this._identity?.directAddress) return void 0;
+    return getAddressId(this._identity.directAddress);
   }
   /**
    * Switch to a different address by index
@@ -6396,7 +6743,9 @@ var Sphere = class _Sphere {
     const addressInfo = this.deriveAddress(index, false);
     const ipnsHash = sha256(addressInfo.publicKey, "hex").slice(0, 40);
     const predicateAddress = await deriveL3PredicateAddress(addressInfo.privateKey);
-    const nametag = this._addressNametags.get(index);
+    const addressId = getAddressId(predicateAddress);
+    const nametagsMap = this._addressNametags.get(addressId);
+    const nametag = nametagsMap?.get(0);
     this._identity = {
       privateKey: addressInfo.privateKey,
       chainPubkey: addressInfo.publicKey,
@@ -6406,7 +6755,7 @@ var Sphere = class _Sphere {
       nametag
     };
     this._currentAddressIndex = index;
-    await this._storage.set(STORAGE_KEYS.CURRENT_ADDRESS_INDEX, index.toString());
+    await this._storage.set(STORAGE_KEYS_GLOBAL.CURRENT_ADDRESS_INDEX, index.toString());
     this._storage.setIdentity(this._identity);
     this._transport.setIdentity(this._identity);
     for (const provider of this._tokenStorageProviders.values()) {
@@ -6645,8 +6994,15 @@ var Sphere = class _Sphere {
       }
     }
     this._identity.nametag = cleanNametag;
-    this._addressNametags.set(this._currentAddressIndex, cleanNametag);
-    await this._storage.set(STORAGE_KEYS.NAMETAG, cleanNametag);
+    const addressId = this.getCurrentAddressId();
+    if (addressId) {
+      let nametagsMap = this._addressNametags.get(addressId);
+      if (!nametagsMap) {
+        nametagsMap = /* @__PURE__ */ new Map();
+        this._addressNametags.set(addressId, nametagsMap);
+      }
+      nametagsMap.set(0, cleanNametag);
+    }
     await this.persistAddressNametags();
     if (!this._payments.hasNametag()) {
       console.log(`[Sphere] Minting nametag token for @${cleanNametag}...`);
@@ -6665,13 +7021,18 @@ var Sphere = class _Sphere {
   }
   /**
    * Persist address nametags to storage
+   * Format: { "DIRECT://abc...xyz": { "0": "alice", "1": "alice2" }, ... }
    */
   async persistAddressNametags() {
-    const nametagsObj = {};
-    this._addressNametags.forEach((nametag, index) => {
-      nametagsObj[index.toString()] = nametag;
+    const result = {};
+    this._addressNametags.forEach((nametagsMap, addressId) => {
+      const innerObj = {};
+      nametagsMap.forEach((nametag, index) => {
+        innerObj[index.toString()] = nametag;
+      });
+      result[addressId] = innerObj;
     });
-    await this._storage.set(STORAGE_KEYS.ADDRESS_NAMETAGS, JSON.stringify(nametagsObj));
+    await this._storage.set(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS, JSON.stringify(result));
   }
   /**
    * Mint a nametag token on-chain (like Sphere wallet and lottery)
@@ -6706,15 +7067,24 @@ var Sphere = class _Sphere {
   }
   /**
    * Load address nametags from storage
+   * Supports new format: { "DIRECT://abc...xyz": { "0": "alice" } }
+   * And legacy format: { "0": "alice" } (migrates to new format on save)
    */
   async loadAddressNametags() {
     try {
-      const saved = await this._storage.get(STORAGE_KEYS.ADDRESS_NAMETAGS);
+      const saved = await this._storage.get(STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS);
       if (saved) {
-        const nametagsObj = JSON.parse(saved);
+        const parsed = JSON.parse(saved);
         this._addressNametags.clear();
-        for (const [indexStr, nametag] of Object.entries(nametagsObj)) {
-          this._addressNametags.set(parseInt(indexStr, 10), nametag);
+        for (const [key, value] of Object.entries(parsed)) {
+          if (typeof value === "object" && value !== null) {
+            const nametagsMap = /* @__PURE__ */ new Map();
+            for (const [indexStr, nametag] of Object.entries(value)) {
+              nametagsMap.set(parseInt(indexStr, 10), nametag);
+            }
+            this._addressNametags.set(key, nametagsMap);
+          } else if (typeof value === "string") {
+          }
         }
       }
     } catch {
@@ -6765,8 +7135,17 @@ var Sphere = class _Sphere {
         if (this._identity) {
           this._identity.nametag = recoveredNametag;
         }
-        this._addressNametags.set(this._currentAddressIndex, recoveredNametag);
-        await this._storage.set(STORAGE_KEYS.NAMETAG, recoveredNametag);
+        const addressId = this.getCurrentAddressId();
+        if (addressId) {
+          let nametagsMap = this._addressNametags.get(addressId);
+          if (!nametagsMap) {
+            nametagsMap = /* @__PURE__ */ new Map();
+            this._addressNametags.set(addressId, nametagsMap);
+          }
+          const nextIndex = nametagsMap.size;
+          nametagsMap.set(nextIndex, recoveredNametag);
+        }
+        await this.persistAddressNametags();
         if (this._transport.registerNametag) {
           await this._transport.registerNametag(
             recoveredNametag,
@@ -6809,22 +7188,22 @@ var Sphere = class _Sphere {
   // ===========================================================================
   async storeMnemonic(mnemonic, derivationPath, basePath) {
     const encrypted = this.encrypt(mnemonic);
-    await this._storage.set(STORAGE_KEYS.MNEMONIC, encrypted);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.MNEMONIC, encrypted);
     this._mnemonic = mnemonic;
     this._source = "mnemonic";
     this._derivationMode = "bip32";
     if (derivationPath) {
-      await this._storage.set(STORAGE_KEYS.DERIVATION_PATH, derivationPath);
+      await this._storage.set(STORAGE_KEYS_GLOBAL.DERIVATION_PATH, derivationPath);
     }
     const effectiveBasePath = basePath ?? DEFAULT_BASE_PATH;
     this._basePath = effectiveBasePath;
-    await this._storage.set(STORAGE_KEYS.BASE_PATH, effectiveBasePath);
-    await this._storage.set(STORAGE_KEYS.DERIVATION_MODE, this._derivationMode);
-    await this._storage.set(STORAGE_KEYS.WALLET_SOURCE, this._source);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.BASE_PATH, effectiveBasePath);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.DERIVATION_MODE, this._derivationMode);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.WALLET_SOURCE, this._source);
   }
   async storeMasterKey(masterKey, chainCode, derivationPath, basePath, derivationMode) {
     const encrypted = this.encrypt(masterKey);
-    await this._storage.set(STORAGE_KEYS.MASTER_KEY, encrypted);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.MASTER_KEY, encrypted);
     this._source = "file";
     this._mnemonic = null;
     if (derivationMode) {
@@ -6833,16 +7212,16 @@ var Sphere = class _Sphere {
       this._derivationMode = chainCode ? "bip32" : "wif_hmac";
     }
     if (chainCode) {
-      await this._storage.set(STORAGE_KEYS.CHAIN_CODE, chainCode);
+      await this._storage.set(STORAGE_KEYS_GLOBAL.CHAIN_CODE, chainCode);
     }
     if (derivationPath) {
-      await this._storage.set(STORAGE_KEYS.DERIVATION_PATH, derivationPath);
+      await this._storage.set(STORAGE_KEYS_GLOBAL.DERIVATION_PATH, derivationPath);
     }
     const effectiveBasePath = basePath ?? DEFAULT_BASE_PATH;
     this._basePath = effectiveBasePath;
-    await this._storage.set(STORAGE_KEYS.BASE_PATH, effectiveBasePath);
-    await this._storage.set(STORAGE_KEYS.DERIVATION_MODE, this._derivationMode);
-    await this._storage.set(STORAGE_KEYS.WALLET_SOURCE, this._source);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.BASE_PATH, effectiveBasePath);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.DERIVATION_MODE, this._derivationMode);
+    await this._storage.set(STORAGE_KEYS_GLOBAL.WALLET_SOURCE, this._source);
   }
   /**
    * Mark wallet as fully created (after successful initialization)
@@ -6850,20 +7229,20 @@ var Sphere = class _Sphere {
    * marked as existing after all initialization steps succeed.
    */
   async finalizeWalletCreation() {
-    await this._storage.set(STORAGE_KEYS.WALLET_EXISTS, "true");
+    await this._storage.set(STORAGE_KEYS_GLOBAL.WALLET_EXISTS, "true");
   }
   // ===========================================================================
   // Private: Identity Initialization
   // ===========================================================================
   async loadIdentityFromStorage() {
-    const encryptedMnemonic = await this._storage.get(STORAGE_KEYS.MNEMONIC);
-    const encryptedMasterKey = await this._storage.get(STORAGE_KEYS.MASTER_KEY);
-    const chainCode = await this._storage.get(STORAGE_KEYS.CHAIN_CODE);
-    const derivationPath = await this._storage.get(STORAGE_KEYS.DERIVATION_PATH);
-    const savedBasePath = await this._storage.get(STORAGE_KEYS.BASE_PATH);
-    const savedDerivationMode = await this._storage.get(STORAGE_KEYS.DERIVATION_MODE);
-    const savedSource = await this._storage.get(STORAGE_KEYS.WALLET_SOURCE);
-    const savedAddressIndex = await this._storage.get(STORAGE_KEYS.CURRENT_ADDRESS_INDEX);
+    const encryptedMnemonic = await this._storage.get(STORAGE_KEYS_GLOBAL.MNEMONIC);
+    const encryptedMasterKey = await this._storage.get(STORAGE_KEYS_GLOBAL.MASTER_KEY);
+    const chainCode = await this._storage.get(STORAGE_KEYS_GLOBAL.CHAIN_CODE);
+    const derivationPath = await this._storage.get(STORAGE_KEYS_GLOBAL.DERIVATION_PATH);
+    const savedBasePath = await this._storage.get(STORAGE_KEYS_GLOBAL.BASE_PATH);
+    const savedDerivationMode = await this._storage.get(STORAGE_KEYS_GLOBAL.DERIVATION_MODE);
+    const savedSource = await this._storage.get(STORAGE_KEYS_GLOBAL.WALLET_SOURCE);
+    const savedAddressIndex = await this._storage.get(STORAGE_KEYS_GLOBAL.CURRENT_ADDRESS_INDEX);
     this._basePath = savedBasePath ?? DEFAULT_BASE_PATH;
     this._derivationMode = savedDerivationMode ?? "bip32";
     this._source = savedSource ?? "unknown";
@@ -6897,12 +7276,13 @@ var Sphere = class _Sphere {
       this._storage.setIdentity(this._identity);
     }
     await this.loadAddressNametags();
-    const savedNametag = await this._storage.get(STORAGE_KEYS.NAMETAG);
     if (this._currentAddressIndex > 0 && this._masterKey) {
       const addressInfo = this.deriveAddress(this._currentAddressIndex, false);
       const ipnsHash = sha256(addressInfo.publicKey, "hex").slice(0, 40);
       const predicateAddress = await deriveL3PredicateAddress(addressInfo.privateKey);
-      const nametag = this._addressNametags.get(this._currentAddressIndex);
+      const addressId = getAddressId(predicateAddress);
+      const nametagsMap = this._addressNametags.get(addressId);
+      const nametag = nametagsMap?.get(0);
       this._identity = {
         privateKey: addressInfo.privateKey,
         chainPubkey: addressInfo.publicKey,
@@ -6913,25 +7293,12 @@ var Sphere = class _Sphere {
       };
       this._storage.setIdentity(this._identity);
       console.log(`[Sphere] Restored to address ${this._currentAddressIndex}:`, this._identity.l1Address);
-    } else {
-      if (savedNametag && this._identity) {
-        let nametag = savedNametag;
-        if (savedNametag.startsWith("{")) {
-          try {
-            const parsed = JSON.parse(savedNametag);
-            nametag = parsed["0"] || parsed[0] || Object.values(parsed)[0];
-          } catch {
-          }
-        }
+    } else if (this._identity) {
+      const addressId = this.getCurrentAddressId();
+      const nametagsMap = addressId ? this._addressNametags.get(addressId) : void 0;
+      const nametag = nametagsMap?.get(0);
+      if (nametag) {
         this._identity.nametag = nametag;
-        if (!this._addressNametags.has(0)) {
-          this._addressNametags.set(0, nametag);
-        }
-      } else if (this._identity) {
-        const nametag = this._addressNametags.get(0);
-        if (nametag) {
-          this._identity.nametag = nametag;
-        }
       }
     }
   }