@unicitylabs/sphere-sdk 0.1.3 → 0.1.5

package/dist/core/index.cjs

@@ -1445,6 +1445,7 @@ var L1PaymentsModule = class {
   _chainCode;
   _addresses = [];
   _wallet;
+  _transport;
   constructor(config) {
     this._config = {
       electrumUrl: config?.electrumUrl ?? "wss://fulcrum.alpha.unicity.network:50004",
@@ -1457,13 +1458,14 @@ var L1PaymentsModule = class {
     this._identity = deps.identity;
     this._chainCode = deps.chainCode;
     this._addresses = deps.addresses ?? [];
+    this._transport = deps.transport;
     this._wallet = {
       masterPrivateKey: deps.identity.privateKey,
       chainCode: deps.chainCode,
       addresses: [
         {
-          address: deps.identity.address,
-          publicKey: deps.identity.publicKey,
+          address: deps.identity.l1Address,
+          publicKey: deps.identity.chainPubkey,
           privateKey: deps.identity.privateKey,
           path: "m/0",
           index: 0
@@ -1471,7 +1473,7 @@ var L1PaymentsModule = class {
       ]
     };
     for (const addr of this._addresses) {
-      if (addr !== deps.identity.address) {
+      if (addr !== deps.identity.l1Address) {
         this._wallet.addresses.push({
           address: addr,
           path: null,
@@ -1494,18 +1496,64 @@ var L1PaymentsModule = class {
     this._addresses = [];
     this._wallet = void 0;
   }
+  /**
+   * Check if a string looks like an L1 address (alpha1... or alphat1...)
+   */
+  isL1Address(value) {
+    return value.startsWith("alpha1") || value.startsWith("alphat1");
+  }
+  /**
+   * Resolve recipient to L1 address
+   * Supports: L1 address (alpha1...), nametag (with or without @)
+   */
+  async resolveL1Address(recipient) {
+    if (recipient.startsWith("@")) {
+      const nametag = recipient.slice(1);
+      return this.resolveNametagToL1Address(nametag);
+    }
+    if (this.isL1Address(recipient)) {
+      return recipient;
+    }
+    try {
+      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.`
+      );
+    }
+  }
+  /**
+   * Resolve nametag to L1 address using transport provider
+   */
+  async resolveNametagToL1Address(nametag) {
+    if (!this._transport?.resolveNametagInfo) {
+      throw new Error("Transport provider does not support nametag resolution");
+    }
+    const info = await this._transport.resolveNametagInfo(nametag);
+    if (!info) {
+      throw new Error(`Nametag not found: ${nametag}`);
+    }
+    if (!info.l1Address) {
+      throw new Error(
+        `Nametag @${nametag} does not have L1 address information. The owner needs to update their nametag registration.`
+      );
+    }
+    return info.l1Address;
+  }
   async send(request) {
     this.ensureInitialized();
     if (!this._wallet || !this._identity) {
       return { success: false, error: "No wallet available" };
     }
     try {
+      const recipientAddress = await this.resolveL1Address(request.to);
       const amountAlpha = parseInt(request.amount, 10) / 1e8;
       const results = await sendAlpha(
         this._wallet,
-        request.to,
+        recipientAddress,
         amountAlpha,
-        this._identity.address
+        this._identity.l1Address
       );
       if (results && results.length > 0) {
         const txids = results.map((r) => r.txid);
@@ -1727,8 +1775,8 @@ var L1PaymentsModule = class {
   }
   _getWatchedAddresses() {
     const addresses = [...this._addresses];
-    if (this._identity?.address && !addresses.includes(this._identity.address)) {
-      addresses.unshift(this._identity.address);
+    if (this._identity?.l1Address && !addresses.includes(this._identity.l1Address)) {
+      addresses.unshift(this._identity.l1Address);
     }
     return addresses;
   }
@@ -2200,50 +2248,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 = {
@@ -2412,6 +2466,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,
@@ -2426,9 +2481,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;
   }
@@ -2568,23 +2620,330 @@ 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
 var import_Token4 = require("@unicitylabs/state-transition-sdk/lib/token/Token");
-var import_TokenId3 = require("@unicitylabs/state-transition-sdk/lib/token/TokenId");
 var import_CoinId3 = require("@unicitylabs/state-transition-sdk/lib/token/fungible/CoinId");
 var import_TransferCommitment2 = require("@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment");
 var import_TransferTransaction = require("@unicitylabs/state-transition-sdk/lib/transaction/TransferTransaction");
 var import_SigningService = require("@unicitylabs/state-transition-sdk/lib/sign/SigningService");
-var import_ProxyAddress = require("@unicitylabs/state-transition-sdk/lib/address/ProxyAddress");
 var import_AddressScheme = require("@unicitylabs/state-transition-sdk/lib/address/AddressScheme");
 var import_UnmaskedPredicate3 = require("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate");
 var import_TokenState3 = require("@unicitylabs/state-transition-sdk/lib/token/TokenState");
 var import_HashAlgorithm3 = require("@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 {
@@ -2605,23 +2964,25 @@ async function parseTokenInfo(tokenData) {
           }
           if (coinIdObj instanceof import_CoinId3.CoinId) {
             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
-            };
+            });
           }
         }
       }
@@ -2636,13 +2997,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
-              };
+              });
             }
           }
         }
@@ -2657,25 +3019,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
-            };
+            });
           }
         }
       }
@@ -2689,25 +3053,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
-          };
+          });
         }
       }
     }
@@ -2866,7 +3232,8 @@ var PaymentsModule = class {
       this.l1.initialize({
         identity: deps.identity,
         chainCode: deps.chainCode,
-        addresses: deps.l1Addresses
+        addresses: deps.l1Addresses,
+        transport: deps.transport
       });
     }
     this.unsubscribeTransfers = deps.transport.onTokenTransfer((transfer) => {
@@ -2888,37 +3255,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);
@@ -2926,7 +3280,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) {
@@ -3024,6 +3378,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(),
@@ -3092,20 +3448,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
@@ -3263,7 +3624,7 @@ var PaymentsModule = class {
     }
     const request = {
       id: transportRequest.id,
-      senderPubkey: transportRequest.senderPubkey,
+      senderPubkey: transportRequest.senderTransportPubkey,
       amount: transportRequest.request.amount,
       coinId: transportRequest.request.coinId,
       symbol: transportRequest.request.coinId,
@@ -3375,7 +3736,7 @@ var PaymentsModule = class {
     }
     const response = {
       id: transportResponse.id,
-      responderPubkey: transportResponse.responderPubkey,
+      responderPubkey: transportResponse.responderTransportPubkey,
       requestId: transportResponse.response.requestId,
       responseType: transportResponse.response.responseType,
       message: transportResponse.response.message,
@@ -3580,6 +3941,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(),
@@ -3835,7 +4198,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)
     );
   }
@@ -4129,6 +4492,23 @@ var PaymentsModule = class {
   // ===========================================================================
   // Private: Transfer Operations
   // ===========================================================================
+  /**
+   * Detect if a string is an L3 address (not a nametag)
+   * Returns true for: hex pubkeys (64+ chars), PROXY:, DIRECT: prefixed addresses
+   */
+  isL3Address(value) {
+    if (value.startsWith("PROXY:") || value.startsWith("DIRECT:")) {
+      return true;
+    }
+    if (value.length >= 64 && /^[0-9a-fA-F]+$/.test(value)) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Resolve recipient to Nostr pubkey for messaging
+   * Supports: nametag (with or without @), hex pubkey
+   */
   async resolveRecipient(recipient) {
     if (recipient.startsWith("@")) {
       const nametag = recipient.slice(1);
@@ -4138,7 +4518,19 @@ var PaymentsModule = class {
       }
       return pubkey;
     }
-    return recipient;
+    if (this.isL3Address(recipient)) {
+      return recipient;
+    }
+    if (this.deps?.transport.resolveNametag) {
+      const pubkey = await this.deps.transport.resolveNametag(recipient);
+      if (pubkey) {
+        this.log(`Resolved "${recipient}" as nametag to pubkey`);
+        return pubkey;
+      }
+    }
+    throw new Error(
+      `Recipient "${recipient}" is not a valid nametag or address. Use @nametag for explicit nametag or a valid hex pubkey/PROXY:/DIRECT: address.`
+    );
   }
   /**
    * Create SDK TransferCommitment for a token transfer
@@ -4170,19 +4562,74 @@ var PaymentsModule = class {
     return import_SigningService.SigningService.createFromSecret(privateKeyBytes);
   }
   /**
-   * Resolve recipient to IAddress
+   * Create DirectAddress from a public key using UnmaskedPredicateReference
+   */
+  async createDirectAddressFromPubkey(pubkeyHex) {
+    const { UnmaskedPredicateReference: UnmaskedPredicateReference3 } = await import("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
+    const { TokenType: TokenType3 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenType");
+    const UNICITY_TOKEN_TYPE_HEX3 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
+    const tokenType = new TokenType3(Buffer.from(UNICITY_TOKEN_TYPE_HEX3, "hex"));
+    const pubkeyBytes = new Uint8Array(
+      pubkeyHex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16))
+    );
+    const addressRef = await UnmaskedPredicateReference3.create(
+      tokenType,
+      "secp256k1",
+      pubkeyBytes,
+      import_HashAlgorithm3.HashAlgorithm.SHA256
+    );
+    return addressRef.toAddress();
+  }
+  /**
+   * Resolve nametag to 33-byte compressed public key using resolveNametagInfo
+   * Returns null if nametag not found or publicKey not available
+   */
+  async resolveNametagToPublicKey(nametag) {
+    if (!this.deps?.transport.resolveNametagInfo) {
+      this.log("resolveNametagInfo not available on transport");
+      return null;
+    }
+    const info = await this.deps.transport.resolveNametagInfo(nametag);
+    if (!info) {
+      this.log(`Nametag "${nametag}" not found`);
+      return null;
+    }
+    if (!info.chainPubkey) {
+      this.log(`Nametag "${nametag}" has no 33-byte chainPubkey (legacy event)`);
+      return null;
+    }
+    return info.chainPubkey;
+  }
+  /**
+   * Resolve recipient to IAddress for L3 transfers
+   * Supports: nametag (with or without @), PROXY:, DIRECT:, hex pubkey
    */
   async resolveRecipientAddress(recipient) {
+    const { AddressFactory } = await import("@unicitylabs/state-transition-sdk/lib/address/AddressFactory");
     if (recipient.startsWith("@")) {
       const nametag = recipient.slice(1);
-      const tokenId2 = await import_TokenId3.TokenId.fromNameTag(nametag);
-      return import_ProxyAddress.ProxyAddress.fromTokenId(tokenId2);
+      const publicKey2 = await this.resolveNametagToPublicKey(nametag);
+      if (publicKey2) {
+        this.log(`Resolved @${nametag} to 33-byte publicKey for DirectAddress`);
+        return this.createDirectAddressFromPubkey(publicKey2);
+      }
+      throw new Error(`Nametag "${nametag}" not found or missing publicKey`);
     }
-    const pubkeyBytes = new Uint8Array(
-      recipient.match(/.{1,2}/g).map((byte) => parseInt(byte, 16))
+    if (recipient.startsWith("PROXY:") || recipient.startsWith("DIRECT:")) {
+      return AddressFactory.createAddress(recipient);
+    }
+    if (recipient.length === 66 && /^[0-9a-fA-F]+$/.test(recipient)) {
+      this.log(`Creating DirectAddress from 33-byte compressed pubkey`);
+      return this.createDirectAddressFromPubkey(recipient);
+    }
+    const publicKey = await this.resolveNametagToPublicKey(recipient);
+    if (publicKey) {
+      this.log(`Resolved "${recipient}" as nametag to 33-byte publicKey for DirectAddress`);
+      return this.createDirectAddressFromPubkey(publicKey);
+    }
+    throw new Error(
+      `Recipient "${recipient}" is not a valid nametag or L3 address. Use @nametag for explicit nametag or a valid 33-byte hex pubkey/PROXY:/DIRECT: address.`
     );
-    const tokenId = new import_TokenId3.TokenId(pubkeyBytes.slice(0, 32));
-    return import_ProxyAddress.ProxyAddress.fromTokenId(tokenId);
   }
   async handleIncomingTransfer(transfer) {
     try {
@@ -4240,7 +4687,39 @@ var PaymentsModule = class {
             }
           }
         } else {
-          tokenData = sourceTokenInput;
+          this.log("Finalizing DIRECT address transfer for state tracking...");
+          try {
+            const signingService = await this.createSigningService();
+            const transferSalt = transferTx.data.salt;
+            const recipientPredicate = await import_UnmaskedPredicate3.UnmaskedPredicate.create(
+              sourceToken.id,
+              sourceToken.type,
+              signingService,
+              import_HashAlgorithm3.HashAlgorithm.SHA256,
+              transferSalt
+            );
+            const recipientState = new import_TokenState3.TokenState(recipientPredicate, null);
+            const stClient = this.deps.oracle.getStateTransitionClient?.();
+            const trustBase = this.deps.oracle.getTrustBase?.();
+            if (!stClient || !trustBase) {
+              this.log("Cannot finalize DIRECT transfer - missing client, using source token");
+              tokenData = sourceTokenInput;
+            } else {
+              finalizedSdkToken = await stClient.finalizeTransaction(
+                trustBase,
+                sourceToken,
+                recipientState,
+                transferTx,
+                []
+                // No nametag tokens needed for DIRECT
+              );
+              tokenData = finalizedSdkToken.toJSON();
+              this.log("DIRECT transfer finalized successfully");
+            }
+          } catch (finalizeError) {
+            this.log("DIRECT finalization failed, using source token:", finalizeError);
+            tokenData = sourceTokenInput;
+          }
         }
       } else if (payload.token) {
         tokenData = payload.token;
@@ -4259,6 +4738,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(),
@@ -4274,7 +4755,7 @@ var PaymentsModule = class {
       await this.addToken(token);
       const incomingTransfer = {
         id: transfer.id,
-        senderPubkey: transfer.senderPubkey,
+        senderPubkey: transfer.senderTransportPubkey,
         tokens: [token],
         memo: payload.memo,
         receivedAt: transfer.timestamp
@@ -4312,28 +4793,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() {
@@ -4342,11 +4827,10 @@ var PaymentsModule = class {
       tokens,
       {
         version: 1,
-        address: this.deps.identity.address,
+        address: this.deps.identity.l1Address,
         ipnsName: this.deps.identity.ipnsName ?? ""
       },
       {
-        nametag: this.nametag || void 0,
         tombstones: this.tombstones,
         archivedTokens: this.archivedTokens,
         forkedTokens: this.forkedTokens
@@ -4446,7 +4930,7 @@ var CommunicationsModule = class {
     const eventId = await this.deps.transport.sendMessage(recipientPubkey, content);
     const message = {
       id: eventId,
-      senderPubkey: this.deps.identity.publicKey,
+      senderPubkey: this.deps.identity.chainPubkey,
       senderNametag: this.deps.identity.nametag,
       recipientPubkey,
       content,
@@ -4473,7 +4957,7 @@ var CommunicationsModule = class {
   getConversations() {
     const conversations = /* @__PURE__ */ new Map();
     for (const message of this.messages.values()) {
-      const peer = message.senderPubkey === this.deps?.identity.publicKey ? message.recipientPubkey : message.senderPubkey;
+      const peer = message.senderPubkey === this.deps?.identity.chainPubkey ? message.recipientPubkey : message.senderPubkey;
       if (!conversations.has(peer)) {
         conversations.set(peer, []);
       }
@@ -4503,7 +4987,7 @@ var CommunicationsModule = class {
    */
   getUnreadCount(peerPubkey) {
     let messages = Array.from(this.messages.values()).filter(
-      (m) => !m.isRead && m.senderPubkey !== this.deps?.identity.publicKey
+      (m) => !m.isRead && m.senderPubkey !== this.deps?.identity.chainPubkey
     );
     if (peerPubkey) {
       messages = messages.filter((m) => m.senderPubkey === peerPubkey);
@@ -4528,7 +5012,7 @@ var CommunicationsModule = class {
     const eventId = await this.deps.transport.publishBroadcast?.(content, tags);
     const message = {
       id: eventId ?? crypto.randomUUID(),
-      authorPubkey: this.deps.identity.publicKey,
+      authorPubkey: this.deps.identity.chainPubkey,
       authorNametag: this.deps.identity.nametag,
       content,
       timestamp: Date.now(),
@@ -4579,11 +5063,12 @@ var CommunicationsModule = class {
   // Private: Message Handling
   // ===========================================================================
   handleIncomingMessage(msg) {
-    if (msg.senderPubkey === this.deps?.identity.publicKey) return;
+    if (msg.senderTransportPubkey === this.deps?.identity.chainPubkey) return;
     const message = {
       id: msg.id,
-      senderPubkey: msg.senderPubkey,
-      recipientPubkey: this.deps.identity.publicKey,
+      senderPubkey: msg.senderTransportPubkey,
+      senderNametag: msg.senderNametag,
+      recipientPubkey: this.deps.identity.chainPubkey,
       content: msg.content,
       timestamp: msg.timestamp,
       isRead: false
@@ -4605,7 +5090,7 @@ var CommunicationsModule = class {
   handleIncomingBroadcast(incoming) {
     const message = {
       id: incoming.id,
-      authorPubkey: incoming.authorPubkey,
+      authorPubkey: incoming.authorTransportPubkey,
       content: incoming.content,
       timestamp: incoming.timestamp,
       tags: incoming.tags
@@ -5432,6 +5917,7 @@ var import_SigningService2 = require("@unicitylabs/state-transition-sdk/lib/sign
 var import_TokenType2 = require("@unicitylabs/state-transition-sdk/lib/token/TokenType");
 var import_HashAlgorithm4 = require("@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm");
 var import_UnmaskedPredicateReference2 = require("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
+var import_nostr_js_sdk = require("@unicitylabs/nostr-js-sdk");
 var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
 async function deriveL3PredicateAddress(privateKey) {
   const secret = Buffer.from(privateKey, "hex");
@@ -5458,6 +5944,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;
@@ -5493,9 +5980,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 {
@@ -5589,6 +6076,8 @@ var Sphere = class _Sphere {
     _Sphere.instance = sphere;
     if (options.nametag) {
       await sphere.registerNametag(options.nametag);
+    } else {
+      await sphere.recoverNametagFromNostr();
     }
     return sphere;
   }
@@ -5651,6 +6140,9 @@ var Sphere = class _Sphere {
     }
     await sphere.initializeProviders();
     await sphere.initializeModules();
+    if (!options.nametag) {
+      await sphere.recoverNametagFromNostr();
+    }
     await sphere.finalizeWalletCreation();
     sphere._initialized = true;
     _Sphere.instance = sphere;
@@ -5661,20 +6153,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();
     }
@@ -5724,9 +6216,9 @@ var Sphere = class _Sphere {
   get identity() {
     if (!this._identity) return null;
     return {
-      publicKey: this._identity.publicKey,
-      address: this._identity.address,
-      predicateAddress: this._identity.predicateAddress,
+      chainPubkey: this._identity.chainPubkey,
+      l1Address: this._identity.l1Address,
+      directAddress: this._identity.directAddress,
       ipnsName: this._identity.ipnsName,
       nametag: this._identity.nametag
     };
@@ -5843,7 +6335,7 @@ var Sphere = class _Sphere {
       if (this._masterKey) {
         address0 = this.deriveAddress(0).address;
       } else if (this._identity) {
-        address0 = this._identity.address;
+        address0 = this._identity.l1Address;
       }
     } catch {
     }
@@ -5890,8 +6382,8 @@ var Sphere = class _Sphere {
       } catch {
         if (i === 0 && this._identity) {
           addresses.push({
-            address: this._identity.address,
-            publicKey: this._identity.publicKey,
+            address: this._identity.l1Address,
+            publicKey: this._identity.chainPubkey,
             path: this.getDefaultAddressPath(),
             index: 0
           });
@@ -5970,7 +6462,7 @@ var Sphere = class _Sphere {
       } catch {
         if (i === 0 && this._identity) {
           addresses.push({
-            address: this._identity.address,
+            address: this._identity.l1Address,
             path: this.getDefaultAddressPath(),
             index: 0,
             isChange: false
@@ -6274,22 +6766,47 @@ var Sphere = class _Sphere {
     return this._currentAddressIndex;
   }
   /**
-   * Get nametag for a specific address index
+   * Get primary nametag 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 Primary nametag (index 0) or undefined if not registered
    */
-  getNametagForAddress(index) {
-    const addressIndex = index ?? this._currentAddressIndex;
-    return this._addressNametags.get(addressIndex);
+  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 addressId - Address identifier (DIRECT://xxx), defaults to current address
+   * @returns Map of nametagIndex to nametag, or undefined if no nametags
+   */
+  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
@@ -6321,17 +6838,19 @@ 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,
-      publicKey: addressInfo.publicKey,
-      address: addressInfo.address,
-      predicateAddress,
+      chainPubkey: addressInfo.publicKey,
+      l1Address: addressInfo.address,
+      directAddress: predicateAddress,
       ipnsName: "12D3KooW" + ipnsHash,
       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()) {
@@ -6339,13 +6858,13 @@ var Sphere = class _Sphere {
     }
     await this.reinitializeModulesForNewAddress();
     this.emitEvent("identity:changed", {
-      address: this._identity.address,
-      predicateAddress: this._identity.predicateAddress,
-      publicKey: this._identity.publicKey,
+      l1Address: this._identity.l1Address,
+      directAddress: this._identity.directAddress,
+      chainPubkey: this._identity.chainPubkey,
       nametag: this._identity.nametag,
       addressIndex: index
     });
-    console.log(`[Sphere] Switched to address ${index}:`, this._identity.address);
+    console.log(`[Sphere] Switched to address ${index}:`, this._identity.l1Address);
   }
   /**
    * Re-initialize modules after address switch
@@ -6403,7 +6922,7 @@ var Sphere = class _Sphere {
     );
     return {
       ...info,
-      address: "alpha1" + info.address.slice(0, 38)
+      address: publicKeyToAddress(info.publicKey, "alpha")
     };
   }
   /**
@@ -6430,11 +6949,10 @@ var Sphere = class _Sphere {
       path
     );
     const publicKey = getPublicKey(derived.privateKey);
-    const addressHash = hash160(publicKey);
     return {
       privateKey: derived.privateKey,
       publicKey,
-      address: "alpha1" + addressHash.slice(0, 38),
+      address: publicKeyToAddress(publicKey, "alpha"),
       path,
       index
     };
@@ -6522,6 +7040,17 @@ var Sphere = class _Sphere {
   hasNametag() {
     return !!this._identity?.nametag;
   }
+  /**
+   * Get the PROXY address for the current nametag
+   * PROXY addresses are derived from the nametag hash and require
+   * the nametag token to claim funds sent to them
+   * @returns PROXY address string or undefined if no nametag
+   */
+  getProxyAddress() {
+    const nametag = this._identity?.nametag;
+    if (!nametag) return void 0;
+    return `PROXY:${(0, import_nostr_js_sdk.hashNametag)(nametag)}`;
+  }
   /**
    * Register a nametag for the current active address
    * Each address can have its own independent nametag
@@ -6550,14 +7079,25 @@ var Sphere = class _Sphere {
       throw new Error(`Nametag already registered for address ${this._currentAddressIndex}: @${this._identity.nametag}`);
     }
     if (this._transport.registerNametag) {
-      const success = await this._transport.registerNametag(cleanNametag, this._identity.publicKey);
+      const success = await this._transport.registerNametag(
+        cleanNametag,
+        this._identity.chainPubkey,
+        this._identity.directAddress || ""
+      );
       if (!success) {
         throw new Error("Failed to register nametag. It may already be taken.");
       }
     }
     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}...`);
@@ -6576,13 +7116,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)
@@ -6617,15 +7162,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 {
@@ -6644,7 +7198,11 @@ var Sphere = class _Sphere {
       return;
     }
     try {
-      const success = await this._transport.registerNametag(nametag, this._identity.publicKey);
+      const success = await this._transport.registerNametag(
+        nametag,
+        this._identity.chainPubkey,
+        this._identity.directAddress || ""
+      );
       if (success) {
         console.log(`[Sphere] Nametag @${nametag} synced with Nostr`);
       } else {
@@ -6654,6 +7212,47 @@ var Sphere = class _Sphere {
       console.warn(`[Sphere] Nametag sync failed:`, error);
     }
   }
+  /**
+   * Recover nametag from Nostr after wallet import
+   * Searches for encrypted nametag events authored by this wallet's pubkey
+   * and decrypts them to restore the nametag association
+   */
+  async recoverNametagFromNostr() {
+    if (this._identity?.nametag) {
+      return;
+    }
+    if (!this._transport.recoverNametag) {
+      return;
+    }
+    try {
+      const recoveredNametag = await this._transport.recoverNametag();
+      if (recoveredNametag) {
+        if (this._identity) {
+          this._identity.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,
+            this._identity.chainPubkey,
+            this._identity.directAddress || ""
+          );
+        }
+        this.emitEvent("nametag:recovered", { nametag: recoveredNametag });
+      }
+    } catch {
+    }
+  }
   /**
    * Validate nametag format
    */
@@ -6684,22 +7283,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) {
@@ -6708,16 +7307,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)
@@ -6725,20 +7324,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";
@@ -6772,65 +7371,60 @@ 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,
-        publicKey: addressInfo.publicKey,
-        address: addressInfo.address,
-        predicateAddress,
+        chainPubkey: addressInfo.publicKey,
+        l1Address: addressInfo.address,
+        directAddress: predicateAddress,
         ipnsName: "12D3KooW" + ipnsHash,
         nametag
       };
       this._storage.setIdentity(this._identity);
-      console.log(`[Sphere] Restored to address ${this._currentAddressIndex}:`, this._identity.address);
-    } else {
-      if (savedNametag && this._identity) {
-        this._identity.nametag = savedNametag;
-        if (!this._addressNametags.has(0)) {
-          this._addressNametags.set(0, savedNametag);
-        }
-        console.log("[Sphere] Restored nametag:", savedNametag);
-      } else if (this._identity) {
-        const nametag = this._addressNametags.get(0);
-        if (nametag) {
-          this._identity.nametag = nametag;
-          console.log("[Sphere] Restored nametag from map:", nametag);
-        }
+      console.log(`[Sphere] Restored to address ${this._currentAddressIndex}:`, this._identity.l1Address);
+    } 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;
       }
     }
   }
   async initializeIdentityFromMnemonic(mnemonic, derivationPath) {
-    const path = derivationPath ?? DEFAULT_DERIVATION_PATH2;
+    const basePath = derivationPath ?? DEFAULT_BASE_PATH;
+    const fullPath = `${basePath}/0/0`;
     const masterKey = identityFromMnemonicSync(mnemonic);
     const derivedKey = deriveKeyAtPath(
       masterKey.privateKey,
       masterKey.chainCode,
-      `${path}/0/0`
+      fullPath
     );
     const publicKey = getPublicKey(derivedKey.privateKey);
-    const addressHash = hash160(publicKey);
+    const address = publicKeyToAddress(publicKey, "alpha");
     const ipnsHash = sha256(publicKey, "hex").slice(0, 40);
     const predicateAddress = await deriveL3PredicateAddress(derivedKey.privateKey);
     this._identity = {
       privateKey: derivedKey.privateKey,
-      publicKey,
-      address: "alpha1" + addressHash.slice(0, 38),
-      predicateAddress,
+      chainPubkey: publicKey,
+      l1Address: address,
+      directAddress: predicateAddress,
       ipnsName: "12D3KooW" + ipnsHash
     };
     this._masterKey = masterKey;
-    console.log("[Sphere] Identity initialized from mnemonic, path:", path);
   }
   async initializeIdentityFromMasterKey(masterKey, chainCode, derivationPath) {
-    const path = derivationPath ?? DEFAULT_DERIVATION_PATH2;
+    const basePath = derivationPath ?? DEFAULT_BASE_PATH;
+    const fullPath = `${basePath}/0/0`;
     let privateKey;
     if (chainCode) {
-      const derivedKey = deriveKeyAtPath(masterKey, chainCode, `${path}/0/0`);
+      const derivedKey = deriveKeyAtPath(masterKey, chainCode, fullPath);
       privateKey = derivedKey.privateKey;
       this._masterKey = {
         privateKey: masterKey,
@@ -6841,17 +7435,16 @@ var Sphere = class _Sphere {
       this._masterKey = null;
     }
     const publicKey = getPublicKey(privateKey);
-    const addressHash = hash160(publicKey);
+    const address = publicKeyToAddress(publicKey, "alpha");
     const ipnsHash = sha256(publicKey, "hex").slice(0, 40);
     const predicateAddress = await deriveL3PredicateAddress(privateKey);
     this._identity = {
       privateKey,
-      publicKey,
-      address: "alpha1" + addressHash.slice(0, 38),
-      predicateAddress,
+      chainPubkey: publicKey,
+      l1Address: address,
+      directAddress: predicateAddress,
       ipnsName: "12D3KooW" + ipnsHash
     };
-    console.log("[Sphere] Identity initialized from master key, path:", path, "chainCode:", !!chainCode);
   }
   // ===========================================================================
   // Private: Provider & Module Initialization