@unicitylabs/sphere-sdk 0.4.7 → 0.4.8

package/dist/core/index.js

@@ -14,6 +14,175 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// constants.ts
+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_ENCRYPTION_KEY, STORAGE_KEYS_GLOBAL, STORAGE_KEYS_ADDRESS, STORAGE_KEYS, DEFAULT_NOSTR_RELAYS, NIP29_KINDS, DEFAULT_AGGREGATOR_URL, DEV_AGGREGATOR_URL, TEST_AGGREGATOR_URL, DEFAULT_IPFS_GATEWAYS, DEFAULT_BASE_PATH, DEFAULT_DERIVATION_PATH, DEFAULT_ELECTRUM_URL, TEST_ELECTRUM_URL, TOKEN_REGISTRY_URL, TOKEN_REGISTRY_REFRESH_INTERVAL, TEST_NOSTR_RELAYS, DEFAULT_GROUP_RELAYS, NETWORKS;
+var init_constants = __esm({
+  "constants.ts"() {
+    "use strict";
+    DEFAULT_ENCRYPTION_KEY = "sphere-default-key";
+    STORAGE_KEYS_GLOBAL = {
+      /** Encrypted BIP39 mnemonic */
+      MNEMONIC: "mnemonic",
+      /** Encrypted master private key */
+      MASTER_KEY: "master_key",
+      /** BIP32 chain code */
+      CHAIN_CODE: "chain_code",
+      /** HD derivation path (full path like m/44'/0'/0'/0/0) */
+      DERIVATION_PATH: "derivation_path",
+      /** Base derivation path (like m/44'/0'/0' without chain/index) */
+      BASE_PATH: "base_path",
+      /** Derivation mode: bip32, wif_hmac, legacy_hmac */
+      DERIVATION_MODE: "derivation_mode",
+      /** Wallet source: mnemonic, file, unknown */
+      WALLET_SOURCE: "wallet_source",
+      /** Wallet existence flag */
+      WALLET_EXISTS: "wallet_exists",
+      /** Current active address index */
+      CURRENT_ADDRESS_INDEX: "current_address_index",
+      /** Nametag cache per address (separate from tracked addresses registry) */
+      ADDRESS_NAMETAGS: "address_nametags",
+      /** Active addresses registry (JSON: TrackedAddressesStorage) */
+      TRACKED_ADDRESSES: "tracked_addresses",
+      /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
+      LAST_WALLET_EVENT_TS: "last_wallet_event_ts",
+      /** Group chat: last used relay URL (stale data detection) — global, same relay for all addresses */
+      GROUP_CHAT_RELAY_URL: "group_chat_relay_url",
+      /** Cached token registry JSON (fetched from remote) */
+      TOKEN_REGISTRY_CACHE: "token_registry_cache",
+      /** Timestamp of last token registry cache update (ms since epoch) */
+      TOKEN_REGISTRY_CACHE_TS: "token_registry_cache_ts",
+      /** Cached price data JSON (from CoinGecko or other provider) */
+      PRICE_CACHE: "price_cache",
+      /** Timestamp of last price cache update (ms since epoch) */
+      PRICE_CACHE_TS: "price_cache_ts"
+    };
+    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",
+      /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
+      PENDING_V5_TOKENS: "pending_v5_tokens",
+      /** Group chat: joined groups for this address */
+      GROUP_CHAT_GROUPS: "group_chat_groups",
+      /** Group chat: messages for this address */
+      GROUP_CHAT_MESSAGES: "group_chat_messages",
+      /** Group chat: members for this address */
+      GROUP_CHAT_MEMBERS: "group_chat_members",
+      /** Group chat: processed event IDs for deduplication */
+      GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events"
+    };
+    STORAGE_KEYS = {
+      ...STORAGE_KEYS_GLOBAL,
+      ...STORAGE_KEYS_ADDRESS
+    };
+    DEFAULT_NOSTR_RELAYS = [
+      "wss://relay.unicity.network",
+      "wss://relay.damus.io",
+      "wss://nos.lol",
+      "wss://relay.nostr.band"
+    ];
+    NIP29_KINDS = {
+      /** Chat message sent to group */
+      CHAT_MESSAGE: 9,
+      /** Thread root message */
+      THREAD_ROOT: 11,
+      /** Thread reply message */
+      THREAD_REPLY: 12,
+      /** User join request */
+      JOIN_REQUEST: 9021,
+      /** User leave request */
+      LEAVE_REQUEST: 9022,
+      /** Admin: add/update user */
+      PUT_USER: 9e3,
+      /** Admin: remove user */
+      REMOVE_USER: 9001,
+      /** Admin: edit group metadata */
+      EDIT_METADATA: 9002,
+      /** Admin: delete event */
+      DELETE_EVENT: 9005,
+      /** Admin: create group */
+      CREATE_GROUP: 9007,
+      /** Admin: delete group */
+      DELETE_GROUP: 9008,
+      /** Admin: create invite code */
+      CREATE_INVITE: 9009,
+      /** Relay-signed group metadata */
+      GROUP_METADATA: 39e3,
+      /** Relay-signed group admins */
+      GROUP_ADMINS: 39001,
+      /** Relay-signed group members */
+      GROUP_MEMBERS: 39002,
+      /** Relay-signed group roles */
+      GROUP_ROLES: 39003
+    };
+    DEFAULT_AGGREGATOR_URL = "https://aggregator.unicity.network/rpc";
+    DEV_AGGREGATOR_URL = "https://dev-aggregator.dyndns.org/rpc";
+    TEST_AGGREGATOR_URL = "https://goggregator-test.unicity.network";
+    DEFAULT_IPFS_GATEWAYS = [
+      "https://unicity-ipfs1.dyndns.org"
+    ];
+    DEFAULT_BASE_PATH = "m/44'/0'/0'";
+    DEFAULT_DERIVATION_PATH = `${DEFAULT_BASE_PATH}/0/0`;
+    DEFAULT_ELECTRUM_URL = "wss://fulcrum.unicity.network:50004";
+    TEST_ELECTRUM_URL = "wss://fulcrum.unicity.network:50004";
+    TOKEN_REGISTRY_URL = "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
+    TOKEN_REGISTRY_REFRESH_INTERVAL = 36e5;
+    TEST_NOSTR_RELAYS = [
+      "wss://nostr-relay.testnet.unicity.network"
+    ];
+    DEFAULT_GROUP_RELAYS = [
+      "wss://sphere-relay.unicity.network"
+    ];
+    NETWORKS = {
+      mainnet: {
+        name: "Mainnet",
+        aggregatorUrl: DEFAULT_AGGREGATOR_URL,
+        nostrRelays: DEFAULT_NOSTR_RELAYS,
+        ipfsGateways: DEFAULT_IPFS_GATEWAYS,
+        electrumUrl: DEFAULT_ELECTRUM_URL,
+        groupRelays: DEFAULT_GROUP_RELAYS,
+        tokenRegistryUrl: TOKEN_REGISTRY_URL
+      },
+      testnet: {
+        name: "Testnet",
+        aggregatorUrl: TEST_AGGREGATOR_URL,
+        nostrRelays: TEST_NOSTR_RELAYS,
+        ipfsGateways: DEFAULT_IPFS_GATEWAYS,
+        electrumUrl: TEST_ELECTRUM_URL,
+        groupRelays: DEFAULT_GROUP_RELAYS,
+        tokenRegistryUrl: TOKEN_REGISTRY_URL
+      },
+      dev: {
+        name: "Development",
+        aggregatorUrl: DEV_AGGREGATOR_URL,
+        nostrRelays: TEST_NOSTR_RELAYS,
+        ipfsGateways: DEFAULT_IPFS_GATEWAYS,
+        electrumUrl: TEST_ELECTRUM_URL,
+        groupRelays: DEFAULT_GROUP_RELAYS,
+        tokenRegistryUrl: TOKEN_REGISTRY_URL
+      }
+    };
+  }
+});
+
 // core/bech32.ts
 function convertBits(data, fromBits, toBits, pad) {
   let acc = 0;
@@ -430,7 +599,8 @@ var init_network = __esm({
   "l1/network.ts"() {
     "use strict";
     init_addressToScriptHash();
-    DEFAULT_ENDPOINT = "wss://fulcrum.unicity.network:50004";
+    init_constants();
+    DEFAULT_ENDPOINT = DEFAULT_ELECTRUM_URL;
     ws = null;
     isConnected = false;
     isConnecting = false;
@@ -450,6 +620,9 @@ var init_network = __esm({
   }
 });
 
+// modules/payments/L1PaymentsModule.ts
+init_constants();
+
 // l1/index.ts
 init_bech32();
 init_addressToScriptHash();
@@ -463,7 +636,7 @@ var ec = new elliptic.ec("secp256k1");
 var CURVE_ORDER = BigInt(
   "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141"
 );
-var DEFAULT_DERIVATION_PATH = "m/44'/0'/0'";
+var DEFAULT_DERIVATION_PATH2 = "m/44'/0'/0'";
 function generateMnemonic2(strength = 128) {
   return bip39.generateMnemonic(strength);
 }
@@ -1484,7 +1657,7 @@ var L1PaymentsModule = class {
   _transport;
   constructor(config) {
     this._config = {
-      electrumUrl: config?.electrumUrl ?? "wss://fulcrum.unicity.network:50004",
+      electrumUrl: config?.electrumUrl ?? DEFAULT_ELECTRUM_URL,
       network: config?.network ?? "mainnet",
       defaultFeeRate: config?.defaultFeeRate ?? 10,
       enableVesting: config?.enableVesting ?? true
@@ -2321,168 +2494,8 @@ var NametagMinter = class {
   }
 };
 
-// constants.ts
-var DEFAULT_ENCRYPTION_KEY = "sphere-default-key";
-var STORAGE_KEYS_GLOBAL = {
-  /** Encrypted BIP39 mnemonic */
-  MNEMONIC: "mnemonic",
-  /** Encrypted master private key */
-  MASTER_KEY: "master_key",
-  /** BIP32 chain code */
-  CHAIN_CODE: "chain_code",
-  /** HD derivation path (full path like m/44'/0'/0'/0/0) */
-  DERIVATION_PATH: "derivation_path",
-  /** Base derivation path (like m/44'/0'/0' without chain/index) */
-  BASE_PATH: "base_path",
-  /** Derivation mode: bip32, wif_hmac, legacy_hmac */
-  DERIVATION_MODE: "derivation_mode",
-  /** Wallet source: mnemonic, file, unknown */
-  WALLET_SOURCE: "wallet_source",
-  /** Wallet existence flag */
-  WALLET_EXISTS: "wallet_exists",
-  /** Current active address index */
-  CURRENT_ADDRESS_INDEX: "current_address_index",
-  /** Nametag cache per address (separate from tracked addresses registry) */
-  ADDRESS_NAMETAGS: "address_nametags",
-  /** Active addresses registry (JSON: TrackedAddressesStorage) */
-  TRACKED_ADDRESSES: "tracked_addresses",
-  /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
-  LAST_WALLET_EVENT_TS: "last_wallet_event_ts",
-  /** Group chat: last used relay URL (stale data detection) — global, same relay for all addresses */
-  GROUP_CHAT_RELAY_URL: "group_chat_relay_url",
-  /** Cached token registry JSON (fetched from remote) */
-  TOKEN_REGISTRY_CACHE: "token_registry_cache",
-  /** Timestamp of last token registry cache update (ms since epoch) */
-  TOKEN_REGISTRY_CACHE_TS: "token_registry_cache_ts",
-  /** Cached price data JSON (from CoinGecko or other provider) */
-  PRICE_CACHE: "price_cache",
-  /** Timestamp of last price cache update (ms since epoch) */
-  PRICE_CACHE_TS: "price_cache_ts"
-};
-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",
-  /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
-  PENDING_V5_TOKENS: "pending_v5_tokens",
-  /** Group chat: joined groups for this address */
-  GROUP_CHAT_GROUPS: "group_chat_groups",
-  /** Group chat: messages for this address */
-  GROUP_CHAT_MESSAGES: "group_chat_messages",
-  /** Group chat: members for this address */
-  GROUP_CHAT_MEMBERS: "group_chat_members",
-  /** Group chat: processed event IDs for deduplication */
-  GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events"
-};
-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_NOSTR_RELAYS = [
-  "wss://relay.unicity.network",
-  "wss://relay.damus.io",
-  "wss://nos.lol",
-  "wss://relay.nostr.band"
-];
-var NIP29_KINDS = {
-  /** Chat message sent to group */
-  CHAT_MESSAGE: 9,
-  /** Thread root message */
-  THREAD_ROOT: 11,
-  /** Thread reply message */
-  THREAD_REPLY: 12,
-  /** User join request */
-  JOIN_REQUEST: 9021,
-  /** User leave request */
-  LEAVE_REQUEST: 9022,
-  /** Admin: add/update user */
-  PUT_USER: 9e3,
-  /** Admin: remove user */
-  REMOVE_USER: 9001,
-  /** Admin: edit group metadata */
-  EDIT_METADATA: 9002,
-  /** Admin: delete event */
-  DELETE_EVENT: 9005,
-  /** Admin: create group */
-  CREATE_GROUP: 9007,
-  /** Admin: delete group */
-  DELETE_GROUP: 9008,
-  /** Admin: create invite code */
-  CREATE_INVITE: 9009,
-  /** Relay-signed group metadata */
-  GROUP_METADATA: 39e3,
-  /** Relay-signed group admins */
-  GROUP_ADMINS: 39001,
-  /** Relay-signed group members */
-  GROUP_MEMBERS: 39002,
-  /** Relay-signed group roles */
-  GROUP_ROLES: 39003
-};
-var DEFAULT_AGGREGATOR_URL = "https://aggregator.unicity.network/rpc";
-var DEV_AGGREGATOR_URL = "https://dev-aggregator.dyndns.org/rpc";
-var TEST_AGGREGATOR_URL = "https://goggregator-test.unicity.network";
-var DEFAULT_IPFS_GATEWAYS = [
-  "https://unicity-ipfs1.dyndns.org"
-];
-var DEFAULT_BASE_PATH = "m/44'/0'/0'";
-var DEFAULT_DERIVATION_PATH2 = `${DEFAULT_BASE_PATH}/0/0`;
-var DEFAULT_ELECTRUM_URL = "wss://fulcrum.alpha.unicity.network:50004";
-var TEST_ELECTRUM_URL = "wss://fulcrum.alpha.testnet.unicity.network:50004";
-var TOKEN_REGISTRY_URL = "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
-var TOKEN_REGISTRY_REFRESH_INTERVAL = 36e5;
-var TEST_NOSTR_RELAYS = [
-  "wss://nostr-relay.testnet.unicity.network"
-];
-var DEFAULT_GROUP_RELAYS = [
-  "wss://sphere-relay.unicity.network"
-];
-var NETWORKS = {
-  mainnet: {
-    name: "Mainnet",
-    aggregatorUrl: DEFAULT_AGGREGATOR_URL,
-    nostrRelays: DEFAULT_NOSTR_RELAYS,
-    ipfsGateways: DEFAULT_IPFS_GATEWAYS,
-    electrumUrl: DEFAULT_ELECTRUM_URL,
-    groupRelays: DEFAULT_GROUP_RELAYS,
-    tokenRegistryUrl: TOKEN_REGISTRY_URL
-  },
-  testnet: {
-    name: "Testnet",
-    aggregatorUrl: TEST_AGGREGATOR_URL,
-    nostrRelays: TEST_NOSTR_RELAYS,
-    ipfsGateways: DEFAULT_IPFS_GATEWAYS,
-    electrumUrl: TEST_ELECTRUM_URL,
-    groupRelays: DEFAULT_GROUP_RELAYS,
-    tokenRegistryUrl: TOKEN_REGISTRY_URL
-  },
-  dev: {
-    name: "Development",
-    aggregatorUrl: DEV_AGGREGATOR_URL,
-    nostrRelays: TEST_NOSTR_RELAYS,
-    ipfsGateways: DEFAULT_IPFS_GATEWAYS,
-    electrumUrl: TEST_ELECTRUM_URL,
-    groupRelays: DEFAULT_GROUP_RELAYS,
-    tokenRegistryUrl: TOKEN_REGISTRY_URL
-  }
-};
+// modules/payments/PaymentsModule.ts
+init_constants();
 
 // types/txf.ts
 var ARCHIVED_PREFIX = "archived-";
@@ -2524,6 +2537,7 @@ function parseForkedKey(key) {
 }
 
 // registry/TokenRegistry.ts
+init_constants();
 var FETCH_TIMEOUT_MS = 1e4;
 var TokenRegistry = class _TokenRegistry {
   static instance = null;
@@ -7336,6 +7350,7 @@ import { HashAlgorithm as HashAlgorithm6 } from "@unicitylabs/state-transition-s
 import { UnmaskedPredicate as UnmaskedPredicate6 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicate";
 
 // modules/communications/CommunicationsModule.ts
+init_constants();
 var CommunicationsModule = class {
   config;
   deps = null;
@@ -7810,6 +7825,7 @@ function createCommunicationsModule(config) {
 }
 
 // modules/groupchat/GroupChatModule.ts
+init_constants();
 import {
   NostrClient,
   NostrKeyManager,
@@ -11659,6 +11675,9 @@ function createMarketModule(config) {
   return new MarketModule(config);
 }
 
+// core/Sphere.ts
+init_constants();
+
 // core/encryption.ts
 import CryptoJS6 from "crypto-js";
 var DEFAULT_ITERATIONS = 1e5;
@@ -11847,6 +11866,72 @@ async function scanAddressesImpl(deriveAddress, options = {}) {
   };
 }
 
+// core/discover.ts
+async function discoverAddressesImpl(deriveTransportPubkey, batchResolve, options = {}) {
+  const maxAddresses = options.maxAddresses ?? 50;
+  const gapLimit = options.gapLimit ?? 20;
+  const batchSize = options.batchSize ?? 20;
+  const { onProgress, signal } = options;
+  const discovered = /* @__PURE__ */ new Map();
+  let consecutiveEmpty = 0;
+  let scanned = 0;
+  const totalBatches = Math.ceil(maxAddresses / batchSize);
+  for (let batchStart = 0; batchStart < maxAddresses; batchStart += batchSize) {
+    if (signal?.aborted) break;
+    if (consecutiveEmpty >= gapLimit) break;
+    const batchEnd = Math.min(batchStart + batchSize, maxAddresses);
+    const batchIndices = [];
+    const pubkeyToIndex = /* @__PURE__ */ new Map();
+    const pubkeyToInfo = /* @__PURE__ */ new Map();
+    for (let i = batchStart; i < batchEnd; i++) {
+      const info = deriveTransportPubkey(i);
+      batchIndices.push(i);
+      pubkeyToIndex.set(info.transportPubkey, i);
+      pubkeyToInfo.set(info.transportPubkey, info);
+    }
+    const batchPubkeys = Array.from(pubkeyToIndex.keys());
+    onProgress?.({
+      currentBatch: Math.floor(batchStart / batchSize) + 1,
+      totalBatches,
+      discoveredCount: discovered.size,
+      currentGap: consecutiveEmpty,
+      phase: "transport"
+    });
+    const peerInfos = await batchResolve(batchPubkeys);
+    const foundInBatch = /* @__PURE__ */ new Set();
+    for (const peer of peerInfos) {
+      const index = pubkeyToIndex.get(peer.transportPubkey);
+      if (index !== void 0) {
+        foundInBatch.add(index);
+        const derived = pubkeyToInfo.get(peer.transportPubkey);
+        discovered.set(index, {
+          index,
+          l1Address: peer.l1Address || derived.l1Address,
+          directAddress: peer.directAddress || derived.directAddress,
+          chainPubkey: peer.chainPubkey || derived.chainPubkey,
+          nametag: peer.nametag,
+          l1Balance: 0,
+          source: "transport"
+        });
+      }
+    }
+    for (const idx of batchIndices) {
+      scanned++;
+      if (foundInBatch.has(idx)) {
+        consecutiveEmpty = 0;
+      } else {
+        consecutiveEmpty++;
+        if (consecutiveEmpty >= gapLimit) break;
+      }
+    }
+  }
+  return {
+    addresses: Array.from(discovered.values()).sort((a, b) => a.index - b.index),
+    scannedCount: scanned,
+    aborted: signal?.aborted ?? false
+  };
+}
+
 // core/Sphere.ts
 init_network();
 
@@ -12669,7 +12754,9 @@ var Sphere = class _Sphere {
         price: options.price,
         groupChat,
         market,
-        password: options.password
+        password: options.password,
+        discoverAddresses: options.discoverAddresses,
+        onProgress: options.onProgress
       });
       return { sphere: sphere2, created: false };
     }
@@ -12697,7 +12784,9 @@ var Sphere = class _Sphere {
       price: options.price,
       groupChat,
       market,
-      password: options.password
+      password: options.password,
+      discoverAddresses: options.discoverAddresses,
+      onProgress: options.onProgress
     });
     return { sphere, created: true, generatedMnemonic };
   }
@@ -12758,6 +12847,7 @@ var Sphere = class _Sphere {
     if (await _Sphere.exists(options.storage)) {
       throw new Error("Wallet already exists. Use Sphere.load() or Sphere.clear() first.");
     }
+    const progress = options.onProgress;
     if (!options.storage.isConnected()) {
       await options.storage.connect();
     }
@@ -12775,20 +12865,39 @@ var Sphere = class _Sphere {
       marketConfig
     );
     sphere._password = options.password ?? null;
+    progress?.({ step: "storing_keys", message: "Storing wallet keys..." });
     await sphere.storeMnemonic(options.mnemonic, options.derivationPath);
     await sphere.initializeIdentityFromMnemonic(options.mnemonic, options.derivationPath);
+    progress?.({ step: "initializing", message: "Initializing wallet..." });
     await sphere.initializeProviders();
     await sphere.initializeModules();
+    progress?.({ step: "finalizing", message: "Finalizing wallet..." });
     await sphere.finalizeWalletCreation();
     sphere._initialized = true;
     _Sphere.instance = sphere;
     await sphere.ensureAddressTracked(0);
     if (options.nametag) {
+      progress?.({ step: "registering_nametag", message: "Registering nametag..." });
       await sphere.registerNametag(options.nametag);
     } else {
+      progress?.({ step: "recovering_nametag", message: "Recovering nametag..." });
       await sphere.recoverNametagFromTransport();
+      progress?.({ step: "syncing_identity", message: "Publishing identity..." });
       await sphere.syncIdentityWithTransport();
     }
+    if (options.discoverAddresses !== false && sphere._transport.discoverAddresses) {
+      progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
+      try {
+        const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
+        const result = await sphere.discoverAddresses(discoverOpts);
+        if (result.addresses.length > 0) {
+          console.log(`[Sphere.create] Address discovery: found ${result.addresses.length} address(es)`);
+        }
+      } catch (err) {
+        console.warn("[Sphere.create] Address discovery failed (non-fatal):", err);
+      }
+    }
+    progress?.({ step: "complete", message: "Wallet created" });
     return sphere;
   }
   /**
@@ -12798,6 +12907,7 @@ var Sphere = class _Sphere {
     if (!await _Sphere.exists(options.storage)) {
       throw new Error("No wallet found. Use Sphere.create() to create a new wallet.");
     }
+    const progress = options.onProgress;
     _Sphere.configureTokenRegistry(options.storage, options.network);
     const groupChatConfig = _Sphere.resolveGroupChatConfig(options.groupChat, options.network);
     const marketConfig = _Sphere.resolveMarketConfig(options.market);
@@ -12815,13 +12925,17 @@ var Sphere = class _Sphere {
     if (!options.storage.isConnected()) {
       await options.storage.connect();
     }
+    progress?.({ step: "storing_keys", message: "Loading wallet keys..." });
     await sphere.loadIdentityFromStorage();
+    progress?.({ step: "initializing", message: "Initializing wallet..." });
     await sphere.initializeProviders();
     await sphere.initializeModules();
+    progress?.({ step: "syncing_identity", message: "Publishing identity..." });
     await sphere.syncIdentityWithTransport();
     sphere._initialized = true;
     _Sphere.instance = sphere;
     if (sphere._identity?.nametag && !sphere._payments.hasNametag()) {
+      progress?.({ step: "registering_nametag", message: "Restoring nametag token..." });
       console.log(`[Sphere] Nametag @${sphere._identity.nametag} has no token, attempting to mint...`);
       try {
         const result = await sphere.mintNametag(sphere._identity.nametag);
@@ -12834,6 +12948,19 @@ var Sphere = class _Sphere {
         console.warn(`[Sphere] Nametag token mint failed:`, err);
       }
     }
+    if (options.discoverAddresses !== false && sphere._transport.discoverAddresses && sphere._masterKey) {
+      progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
+      try {
+        const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
+        const result = await sphere.discoverAddresses(discoverOpts);
+        if (result.addresses.length > 0) {
+          console.log(`[Sphere.load] Address discovery: found ${result.addresses.length} address(es)`);
+        }
+      } catch (err) {
+        console.warn("[Sphere.load] Address discovery failed (non-fatal):", err);
+      }
+    }
+    progress?.({ step: "complete", message: "Wallet loaded" });
     return sphere;
   }
   /**
@@ -12843,9 +12970,11 @@ var Sphere = class _Sphere {
     if (!options.mnemonic && !options.masterKey) {
       throw new Error("Either mnemonic or masterKey is required");
     }
+    const progress = options.onProgress;
     console.log("[Sphere.import] Starting import...");
     const needsClear = _Sphere.instance !== null || await _Sphere.exists(options.storage);
     if (needsClear) {
+      progress?.({ step: "clearing", message: "Clearing previous wallet data..." });
       console.log("[Sphere.import] Clearing existing wallet data...");
       await _Sphere.clear({ storage: options.storage, tokenStorage: options.tokenStorage });
       console.log("[Sphere.import] Clear done");
@@ -12870,6 +12999,7 @@ var Sphere = class _Sphere {
       marketConfig
     );
     sphere._password = options.password ?? null;
+    progress?.({ step: "storing_keys", message: "Storing wallet keys..." });
     if (options.mnemonic) {
       if (!_Sphere.validateMnemonic(options.mnemonic)) {
         throw new Error("Invalid mnemonic");
@@ -12894,17 +13024,21 @@ var Sphere = class _Sphere {
         options.derivationPath
       );
     }
+    progress?.({ step: "initializing", message: "Initializing wallet..." });
     console.log("[Sphere.import] Initializing providers...");
     await sphere.initializeProviders();
     console.log("[Sphere.import] Providers initialized. Initializing modules...");
     await sphere.initializeModules();
     console.log("[Sphere.import] Modules initialized");
     if (!options.nametag) {
+      progress?.({ step: "recovering_nametag", message: "Recovering nametag..." });
       console.log("[Sphere.import] Recovering nametag from transport...");
       await sphere.recoverNametagFromTransport();
       console.log("[Sphere.import] Nametag recovery done");
+      progress?.({ step: "syncing_identity", message: "Publishing identity..." });
       await sphere.syncIdentityWithTransport();
     }
+    progress?.({ step: "finalizing", message: "Finalizing wallet..." });
     console.log("[Sphere.import] Finalizing wallet creation...");
     await sphere.finalizeWalletCreation();
     sphere._initialized = true;
@@ -12912,10 +13046,12 @@ var Sphere = class _Sphere {
     console.log("[Sphere.import] Tracking address 0...");
     await sphere.ensureAddressTracked(0);
     if (options.nametag) {
+      progress?.({ step: "registering_nametag", message: "Registering nametag..." });
       console.log("[Sphere.import] Registering nametag...");
       await sphere.registerNametag(options.nametag);
     }
     if (sphere._tokenStorageProviders.size > 0) {
+      progress?.({ step: "syncing_tokens", message: "Syncing tokens..." });
       try {
         const syncResult = await sphere._payments.sync();
         console.log(`[Sphere.import] Auto-sync: +${syncResult.added} -${syncResult.removed}`);
@@ -12923,6 +13059,19 @@ var Sphere = class _Sphere {
         console.warn("[Sphere.import] Auto-sync failed (non-fatal):", err);
       }
     }
+    if (options.discoverAddresses !== false && sphere._transport.discoverAddresses) {
+      progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
+      try {
+        const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
+        const result = await sphere.discoverAddresses(discoverOpts);
+        if (result.addresses.length > 0) {
+          console.log(`[Sphere.import] Address discovery: found ${result.addresses.length} address(es)`);
+        }
+      } catch (err) {
+        console.warn("[Sphere.import] Address discovery failed (non-fatal):", err);
+      }
+    }
+    progress?.({ step: "complete", message: "Import complete" });
     console.log("[Sphere.import] Import complete");
     return sphere;
   }
@@ -13791,6 +13940,23 @@ var Sphere = class _Sphere {
       await provider.initialize();
     }
     await this.reinitializeModulesForNewAddress();
+    this.emitEvent("identity:changed", {
+      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.l1Address);
+    this.postSwitchSync(index, newNametag).catch((err) => {
+      console.warn(`[Sphere] Post-switch sync failed for address ${index}:`, err);
+    });
+  }
+  /**
+   * Background transport sync and nametag operations after address switch.
+   * Runs after switchToAddress returns so L1/L3 queries can start immediately.
+   */
+  async postSwitchSync(index, newNametag) {
     if (!newNametag) {
       await this.syncIdentityWithTransport();
     }
@@ -13813,7 +13979,7 @@ var Sphere = class _Sphere {
         nametag: newNametag,
         addressIndex: index
       });
-    } else if (this._identity.nametag && !this._payments.hasNametag()) {
+    } else if (this._identity?.nametag && !this._payments.hasNametag()) {
       console.log(`[Sphere] Nametag @${this._identity.nametag} has no token after switch, minting...`);
       try {
         const result = await this.mintNametag(this._identity.nametag);
@@ -13826,14 +13992,6 @@ var Sphere = class _Sphere {
         console.warn(`[Sphere] Nametag token mint failed after switch:`, err);
       }
     }
-    this.emitEvent("identity:changed", {
-      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.l1Address);
   }
   /**
    * Re-initialize modules after address switch
@@ -14040,6 +14198,98 @@ var Sphere = class _Sphere {
     await this.persistTrackedAddresses();
     await this.persistAddressNametags();
   }
+  /**
+   * Discover previously used HD addresses.
+   *
+   * Primary: queries Nostr relay for identity binding events (fast, single batch query).
+   * Secondary: runs L1 balance scan to find legacy addresses with no binding event.
+   *
+   * @example
+   * ```ts
+   * const result = await sphere.discoverAddresses();
+   * console.log(`Found ${result.addresses.length} addresses`);
+   *
+   * // With auto-tracking
+   * await sphere.discoverAddresses({ autoTrack: true });
+   * ```
+   */
+  async discoverAddresses(options = {}) {
+    this.ensureReady();
+    if (!this._masterKey) {
+      throw new Error("Address discovery requires HD master key");
+    }
+    if (!this._transport.discoverAddresses) {
+      throw new Error("Transport provider does not support address discovery");
+    }
+    const includeL1Scan = options.includeL1Scan ?? true;
+    const transportResult = await discoverAddressesImpl(
+      (index) => {
+        const addrInfo = this._deriveAddressInternal(index, false);
+        return {
+          transportPubkey: addrInfo.publicKey.slice(2),
+          // x-only 32 bytes
+          chainPubkey: addrInfo.publicKey,
+          l1Address: addrInfo.address,
+          directAddress: ""
+          // not needed for discovery query
+        };
+      },
+      (pubkeys) => this._transport.discoverAddresses(pubkeys),
+      options
+    );
+    if (includeL1Scan) {
+      try {
+        const l1Result = await this.scanAddresses({
+          maxAddresses: options.maxAddresses,
+          gapLimit: options.gapLimit,
+          signal: options.signal,
+          onProgress: options.onProgress ? (p) => options.onProgress({
+            currentBatch: 0,
+            totalBatches: 0,
+            discoveredCount: p.foundCount,
+            currentGap: p.currentGap,
+            phase: "l1"
+          }) : void 0
+        });
+        for (const l1Addr of l1Result.addresses) {
+          if (l1Addr.isChange) continue;
+          const existing = transportResult.addresses.find((a) => a.index === l1Addr.index);
+          if (existing) {
+            existing.l1Balance = l1Addr.balance;
+            existing.source = "both";
+            if (!existing.nametag && l1Addr.nametag) {
+              existing.nametag = l1Addr.nametag;
+            }
+          } else {
+            const addrInfo = this._deriveAddressInternal(l1Addr.index, false);
+            transportResult.addresses.push({
+              index: l1Addr.index,
+              l1Address: l1Addr.address,
+              directAddress: "",
+              chainPubkey: addrInfo.publicKey,
+              nametag: l1Addr.nametag,
+              l1Balance: l1Addr.balance,
+              source: "l1"
+            });
+          }
+        }
+        transportResult.addresses.sort((a, b) => a.index - b.index);
+      } catch (err) {
+        console.warn("[Sphere] L1 scan failed during discovery (non-fatal):", err);
+      }
+    }
+    if (options.autoTrack && transportResult.addresses.length > 0) {
+      await this.trackScannedAddresses(
+        transportResult.addresses.map((a) => ({
+          index: a.index,
+          // Preserve existing hidden state; default to false for newly discovered
+          hidden: this._trackedAddresses.get(a.index)?.hidden ?? false,
+          nametag: a.nametag
+        }))
+      );
+    }
+    return transportResult;
+  }
   // ===========================================================================
   // Public Methods - Status
   // ===========================================================================
@@ -14611,6 +14861,17 @@ var Sphere = class _Sphere {
                 return;
               }
             }
+            const needsUpdate = !existing.directAddress || !existing.l1Address || !existing.chainPubkey || this._identity?.nametag && !existing.nametag;
+            if (needsUpdate) {
+              console.log("[Sphere] Existing binding incomplete, re-publishing with full data");
+              await this._transport.publishIdentityBinding(
+                this._identity.chainPubkey,
+                this._identity.l1Address,
+                this._identity.directAddress || "",
+                this._identity?.nametag || existing.nametag || void 0
+              );
+              return;
+            }
             console.log("[Sphere] Existing binding found, skipping re-publish");
             return;
           }
@@ -15104,6 +15365,7 @@ var CurrencyUtils = {
 init_bech32();
 
 // core/network-health.ts
+init_constants();
 var DEFAULT_TIMEOUT_MS = 5e3;
 async function checkNetworkHealth(network = "testnet", options) {
   const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -15291,7 +15553,7 @@ async function runCustomCheck(name, checkFn, timeoutMs) {
 export {
   CHARSET,
   CurrencyUtils,
-  DEFAULT_DERIVATION_PATH,
+  DEFAULT_DERIVATION_PATH2 as DEFAULT_DERIVATION_PATH,
   DEFAULT_TOKEN_DECIMALS,
   Sphere,
   base58Decode,
@@ -15314,6 +15576,7 @@ export {
   deriveChildKey,
   deriveKeyAtPath,
   deserializeEncrypted,
+  discoverAddressesImpl,
   doubleSha256,
   ec,
   encodeBech32,