@unicitylabs/sphere-sdk 0.4.6 → 0.4.8

package/dist/core/index.d.cts

@@ -984,6 +984,14 @@ interface TransportProvider extends BaseProvider {
      * @returns PeerInfo or null if no binding found
      */
     resolveTransportPubkeyInfo?(transportPubkey: string): Promise<PeerInfo | null>;
+    /**
+     * Batch-resolve multiple transport pubkeys to peer info.
+     * Used for HD address discovery: derives transport pubkeys for indices 0..N
+     * and queries binding events in a single batch.
+     * @param transportPubkeys - Array of transport-specific pubkeys to look up
+     * @returns Array of PeerInfo for pubkeys that have binding events (may be shorter than input)
+     */
+    discoverAddresses?(transportPubkeys: string[]): Promise<PeerInfo[]>;
     /**
      * Recover nametag for current identity by decrypting stored encrypted nametag
      * Used after wallet import to recover associated nametag
@@ -2800,6 +2808,12 @@ declare class GroupChatModule {
     onMessage(handler: (message: GroupMessageData) => void): () => void;
     getRelayUrls(): string[];
     getMyPublicKey(): string | null;
+    /**
+     * Returns the latest message timestamp (in Nostr seconds) across the given groups,
+     * or 0 if no messages exist.  Used to set `since` on subscriptions so the relay
+     * only sends events we don't already have.
+     */
+    private getLatestMessageTimestamp;
     private fetchRelayAdmins;
     private doFetchRelayAdmins;
     private fetchGroupMetadataInternal;
@@ -2987,7 +3001,7 @@ declare const NETWORKS: {
         readonly aggregatorUrl: "https://aggregator.unicity.network/rpc";
         readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
-        readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
+        readonly electrumUrl: "wss://fulcrum.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
@@ -2996,7 +3010,7 @@ declare const NETWORKS: {
         readonly aggregatorUrl: "https://goggregator-test.unicity.network";
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
-        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly electrumUrl: "wss://fulcrum.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
@@ -3005,7 +3019,7 @@ declare const NETWORKS: {
         readonly aggregatorUrl: "https://dev-aggregator.dyndns.org/rpc";
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
-        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly electrumUrl: "wss://fulcrum.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
@@ -3083,6 +3097,88 @@ interface ScanAddressesResult {
  */
 declare function scanAddressesImpl(deriveAddress: (index: number, isChange: boolean) => AddressInfo, options?: ScanAddressesOptions): Promise<ScanAddressesResult>;
 
+/**
+ * HD Address Discovery — discover previously used addresses via transport binding events.
+ *
+ * Derives transport pubkeys for HD indices and batch-queries the relay.
+ * Complements L1 scan (scan.ts) by finding L3-only addresses.
+ */
+
+/** Progress callback for address discovery */
+interface DiscoverAddressProgress {
+    /** Current batch being queried */
+    currentBatch: number;
+    /** Total batches planned */
+    totalBatches: number;
+    /** Number of addresses discovered so far */
+    discoveredCount: number;
+    /** Current gap count (consecutive empty indices) */
+    currentGap: number;
+    /** Phase: 'transport' or 'l1' */
+    phase: 'transport' | 'l1';
+}
+/** Single discovered address result */
+interface DiscoveredAddress {
+    /** HD derivation index */
+    index: number;
+    /** L1 bech32 address (alpha1...) */
+    l1Address: string;
+    /** L3 DIRECT address */
+    directAddress: string;
+    /** 33-byte compressed chain pubkey */
+    chainPubkey: string;
+    /** Nametag (from binding event) */
+    nametag?: string;
+    /** L1 balance in ALPHA (0 if only discovered via transport) */
+    l1Balance: number;
+    /** Discovery source */
+    source: 'transport' | 'l1' | 'both';
+}
+/** Options for address discovery */
+interface DiscoverAddressesOptions {
+    /** Max HD indices to probe (default: 50) */
+    maxAddresses?: number;
+    /** Stop after N consecutive empty indices (default: 20) */
+    gapLimit?: number;
+    /** Batch size for transport queries (default: 20) */
+    batchSize?: number;
+    /** Also run L1 balance scan (default: true) */
+    includeL1Scan?: boolean;
+    /** Progress callback */
+    onProgress?: (progress: DiscoverAddressProgress) => void;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Auto-track discovered addresses (default: true) */
+    autoTrack?: boolean;
+}
+/** Result of address discovery */
+interface DiscoverAddressesResult {
+    /** All discovered addresses */
+    addresses: DiscoveredAddress[];
+    /** Total indices scanned */
+    scannedCount: number;
+    /** Whether scan was aborted */
+    aborted: boolean;
+}
+/** Info derived for a single HD index */
+interface DerivedAddressInfo {
+    transportPubkey: string;
+    chainPubkey: string;
+    l1Address: string;
+    directAddress: string;
+}
+/**
+ * Discover used HD addresses via transport binding events.
+ *
+ * Derives transport pubkeys in batches, queries the relay, and uses
+ * gap limit to determine when to stop.
+ *
+ * @param deriveTransportPubkey - function(index) → address info with transportPubkey
+ * @param batchResolve - function(transportPubkeys[]) → PeerInfo[]
+ * @param options - Discovery options
+ */
+declare function discoverAddressesImpl(deriveTransportPubkey: (index: number) => DerivedAddressInfo, batchResolve: (transportPubkeys: string[]) => Promise<PeerInfo[]>, options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
+
 /**
  * Legacy File Serialization Types
  */
@@ -3095,6 +3191,17 @@ type DecryptionProgressCallback = (iteration: number, total: number) => Promise<
 
 declare function isValidNametag(nametag: string): boolean;
 
+/** Steps reported by the onProgress callback during wallet init/create/load/import */
+type InitProgressStep = 'clearing' | 'storing_keys' | 'initializing' | 'recovering_nametag' | 'registering_nametag' | 'syncing_identity' | 'syncing_tokens' | 'discovering_addresses' | 'finalizing' | 'complete';
+/** Progress info passed to onProgress callback */
+interface InitProgress {
+    /** Current step identifier */
+    readonly step: InitProgressStep;
+    /** Human-readable description of what's happening */
+    readonly message: string;
+}
+/** Callback for tracking wallet initialization progress */
+type InitProgressCallback = (progress: InitProgress) => void;
 /** Options for creating a new wallet */
 interface SphereCreateOptions {
     /** BIP39 mnemonic (12 or 24 words) */
@@ -3127,6 +3234,15 @@ interface SphereCreateOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses after creation.
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** Options for loading existing wallet */
 interface SphereLoadOptions {
@@ -3154,6 +3270,15 @@ interface SphereLoadOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to decrypt the wallet. Must match the password used during creation. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses on load.
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** Options for importing a wallet */
 interface SphereImportOptions {
@@ -3189,6 +3314,15 @@ interface SphereImportOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses after import.
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** L1 (ALPHA blockchain) configuration */
 interface L1Config {
@@ -3238,6 +3372,16 @@ interface SphereInitOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt/decrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses when creating from mnemonic.
+     * Only applies when wallet is newly created (not on load of existing wallet).
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** Result of init operation */
 interface SphereInitResult {
@@ -3509,14 +3653,9 @@ declare class Sphere {
      * });
      * ```
      */
-    static importFromJSON(options: {
+    static importFromJSON(options: Omit<SphereImportOptions, 'mnemonic' | 'masterKey' | 'chainCode' | 'derivationPath' | 'basePath' | 'derivationMode'> & {
         jsonContent: string;
         password?: string;
-        storage: StorageProvider;
-        transport: TransportProvider;
-        oracle: OracleProvider;
-        tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
-        l1?: L1Config;
     }): Promise<{
         success: boolean;
         mnemonic?: string;
@@ -3552,7 +3691,7 @@ declare class Sphere {
      * });
      * ```
      */
-    static importFromLegacyFile(options: {
+    static importFromLegacyFile(options: Omit<SphereImportOptions, 'mnemonic' | 'masterKey' | 'chainCode' | 'derivationPath' | 'basePath' | 'derivationMode'> & {
         /** File content - Uint8Array for .dat, string for .txt */
         fileContent: string | Uint8Array;
         /** File name (used for type detection) */
@@ -3561,18 +3700,6 @@ declare class Sphere {
         password?: string;
         /** Progress callback for long decryption operations */
         onDecryptProgress?: DecryptionProgressCallback;
-        /** Storage provider instance */
-        storage: StorageProvider;
-        /** Transport provider instance */
-        transport: TransportProvider;
-        /** Oracle provider instance */
-        oracle: OracleProvider;
-        /** Optional token storage provider */
-        tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
-        /** Optional nametag to register */
-        nametag?: string;
-        /** L1 (ALPHA blockchain) configuration */
-        l1?: L1Config;
     }): Promise<{
         success: boolean;
         sphere?: Sphere;
@@ -3673,6 +3800,11 @@ declare class Sphere {
     switchToAddress(index: number, options?: {
         nametag?: string;
     }): Promise<void>;
+    /**
+     * Background transport sync and nametag operations after address switch.
+     * Runs after switchToAddress returns so L1/L3 queries can start immediately.
+     */
+    private postSwitchSync;
     /**
      * Re-initialize modules after address switch
      */
@@ -3762,6 +3894,22 @@ declare class Sphere {
         hidden: boolean;
         nametag?: string;
     }>): Promise<void>;
+    /**
+     * 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 });
+     * ```
+     */
+    discoverAddresses(options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
     /**
      * Get aggregated status of all providers, grouped by role.
      *
@@ -4313,4 +4461,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };

package/dist/core/index.d.ts

@@ -984,6 +984,14 @@ interface TransportProvider extends BaseProvider {
      * @returns PeerInfo or null if no binding found
      */
     resolveTransportPubkeyInfo?(transportPubkey: string): Promise<PeerInfo | null>;
+    /**
+     * Batch-resolve multiple transport pubkeys to peer info.
+     * Used for HD address discovery: derives transport pubkeys for indices 0..N
+     * and queries binding events in a single batch.
+     * @param transportPubkeys - Array of transport-specific pubkeys to look up
+     * @returns Array of PeerInfo for pubkeys that have binding events (may be shorter than input)
+     */
+    discoverAddresses?(transportPubkeys: string[]): Promise<PeerInfo[]>;
     /**
      * Recover nametag for current identity by decrypting stored encrypted nametag
      * Used after wallet import to recover associated nametag
@@ -2800,6 +2808,12 @@ declare class GroupChatModule {
     onMessage(handler: (message: GroupMessageData) => void): () => void;
     getRelayUrls(): string[];
     getMyPublicKey(): string | null;
+    /**
+     * Returns the latest message timestamp (in Nostr seconds) across the given groups,
+     * or 0 if no messages exist.  Used to set `since` on subscriptions so the relay
+     * only sends events we don't already have.
+     */
+    private getLatestMessageTimestamp;
     private fetchRelayAdmins;
     private doFetchRelayAdmins;
     private fetchGroupMetadataInternal;
@@ -2987,7 +3001,7 @@ declare const NETWORKS: {
         readonly aggregatorUrl: "https://aggregator.unicity.network/rpc";
         readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
-        readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
+        readonly electrumUrl: "wss://fulcrum.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
@@ -2996,7 +3010,7 @@ declare const NETWORKS: {
         readonly aggregatorUrl: "https://goggregator-test.unicity.network";
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
-        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly electrumUrl: "wss://fulcrum.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
@@ -3005,7 +3019,7 @@ declare const NETWORKS: {
         readonly aggregatorUrl: "https://dev-aggregator.dyndns.org/rpc";
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
-        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly electrumUrl: "wss://fulcrum.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
@@ -3083,6 +3097,88 @@ interface ScanAddressesResult {
  */
 declare function scanAddressesImpl(deriveAddress: (index: number, isChange: boolean) => AddressInfo, options?: ScanAddressesOptions): Promise<ScanAddressesResult>;
 
+/**
+ * HD Address Discovery — discover previously used addresses via transport binding events.
+ *
+ * Derives transport pubkeys for HD indices and batch-queries the relay.
+ * Complements L1 scan (scan.ts) by finding L3-only addresses.
+ */
+
+/** Progress callback for address discovery */
+interface DiscoverAddressProgress {
+    /** Current batch being queried */
+    currentBatch: number;
+    /** Total batches planned */
+    totalBatches: number;
+    /** Number of addresses discovered so far */
+    discoveredCount: number;
+    /** Current gap count (consecutive empty indices) */
+    currentGap: number;
+    /** Phase: 'transport' or 'l1' */
+    phase: 'transport' | 'l1';
+}
+/** Single discovered address result */
+interface DiscoveredAddress {
+    /** HD derivation index */
+    index: number;
+    /** L1 bech32 address (alpha1...) */
+    l1Address: string;
+    /** L3 DIRECT address */
+    directAddress: string;
+    /** 33-byte compressed chain pubkey */
+    chainPubkey: string;
+    /** Nametag (from binding event) */
+    nametag?: string;
+    /** L1 balance in ALPHA (0 if only discovered via transport) */
+    l1Balance: number;
+    /** Discovery source */
+    source: 'transport' | 'l1' | 'both';
+}
+/** Options for address discovery */
+interface DiscoverAddressesOptions {
+    /** Max HD indices to probe (default: 50) */
+    maxAddresses?: number;
+    /** Stop after N consecutive empty indices (default: 20) */
+    gapLimit?: number;
+    /** Batch size for transport queries (default: 20) */
+    batchSize?: number;
+    /** Also run L1 balance scan (default: true) */
+    includeL1Scan?: boolean;
+    /** Progress callback */
+    onProgress?: (progress: DiscoverAddressProgress) => void;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Auto-track discovered addresses (default: true) */
+    autoTrack?: boolean;
+}
+/** Result of address discovery */
+interface DiscoverAddressesResult {
+    /** All discovered addresses */
+    addresses: DiscoveredAddress[];
+    /** Total indices scanned */
+    scannedCount: number;
+    /** Whether scan was aborted */
+    aborted: boolean;
+}
+/** Info derived for a single HD index */
+interface DerivedAddressInfo {
+    transportPubkey: string;
+    chainPubkey: string;
+    l1Address: string;
+    directAddress: string;
+}
+/**
+ * Discover used HD addresses via transport binding events.
+ *
+ * Derives transport pubkeys in batches, queries the relay, and uses
+ * gap limit to determine when to stop.
+ *
+ * @param deriveTransportPubkey - function(index) → address info with transportPubkey
+ * @param batchResolve - function(transportPubkeys[]) → PeerInfo[]
+ * @param options - Discovery options
+ */
+declare function discoverAddressesImpl(deriveTransportPubkey: (index: number) => DerivedAddressInfo, batchResolve: (transportPubkeys: string[]) => Promise<PeerInfo[]>, options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
+
 /**
  * Legacy File Serialization Types
  */
@@ -3095,6 +3191,17 @@ type DecryptionProgressCallback = (iteration: number, total: number) => Promise<
 
 declare function isValidNametag(nametag: string): boolean;
 
+/** Steps reported by the onProgress callback during wallet init/create/load/import */
+type InitProgressStep = 'clearing' | 'storing_keys' | 'initializing' | 'recovering_nametag' | 'registering_nametag' | 'syncing_identity' | 'syncing_tokens' | 'discovering_addresses' | 'finalizing' | 'complete';
+/** Progress info passed to onProgress callback */
+interface InitProgress {
+    /** Current step identifier */
+    readonly step: InitProgressStep;
+    /** Human-readable description of what's happening */
+    readonly message: string;
+}
+/** Callback for tracking wallet initialization progress */
+type InitProgressCallback = (progress: InitProgress) => void;
 /** Options for creating a new wallet */
 interface SphereCreateOptions {
     /** BIP39 mnemonic (12 or 24 words) */
@@ -3127,6 +3234,15 @@ interface SphereCreateOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses after creation.
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** Options for loading existing wallet */
 interface SphereLoadOptions {
@@ -3154,6 +3270,15 @@ interface SphereLoadOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to decrypt the wallet. Must match the password used during creation. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses on load.
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** Options for importing a wallet */
 interface SphereImportOptions {
@@ -3189,6 +3314,15 @@ interface SphereImportOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses after import.
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** L1 (ALPHA blockchain) configuration */
 interface L1Config {
@@ -3238,6 +3372,16 @@ interface SphereInitOptions {
     market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt/decrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /**
+     * Auto-discover previously used HD addresses when creating from mnemonic.
+     * Only applies when wallet is newly created (not on load of existing wallet).
+     * - true: discover with defaults (Nostr + L1 scan, autoTrack: true)
+     * - DiscoverAddressesOptions: custom config
+     * - false/undefined: no auto-discovery (default)
+     */
+    discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Optional callback to report initialization progress steps */
+    onProgress?: InitProgressCallback;
 }
 /** Result of init operation */
 interface SphereInitResult {
@@ -3509,14 +3653,9 @@ declare class Sphere {
      * });
      * ```
      */
-    static importFromJSON(options: {
+    static importFromJSON(options: Omit<SphereImportOptions, 'mnemonic' | 'masterKey' | 'chainCode' | 'derivationPath' | 'basePath' | 'derivationMode'> & {
         jsonContent: string;
         password?: string;
-        storage: StorageProvider;
-        transport: TransportProvider;
-        oracle: OracleProvider;
-        tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
-        l1?: L1Config;
     }): Promise<{
         success: boolean;
         mnemonic?: string;
@@ -3552,7 +3691,7 @@ declare class Sphere {
      * });
      * ```
      */
-    static importFromLegacyFile(options: {
+    static importFromLegacyFile(options: Omit<SphereImportOptions, 'mnemonic' | 'masterKey' | 'chainCode' | 'derivationPath' | 'basePath' | 'derivationMode'> & {
         /** File content - Uint8Array for .dat, string for .txt */
         fileContent: string | Uint8Array;
         /** File name (used for type detection) */
@@ -3561,18 +3700,6 @@ declare class Sphere {
         password?: string;
         /** Progress callback for long decryption operations */
         onDecryptProgress?: DecryptionProgressCallback;
-        /** Storage provider instance */
-        storage: StorageProvider;
-        /** Transport provider instance */
-        transport: TransportProvider;
-        /** Oracle provider instance */
-        oracle: OracleProvider;
-        /** Optional token storage provider */
-        tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
-        /** Optional nametag to register */
-        nametag?: string;
-        /** L1 (ALPHA blockchain) configuration */
-        l1?: L1Config;
     }): Promise<{
         success: boolean;
         sphere?: Sphere;
@@ -3673,6 +3800,11 @@ declare class Sphere {
     switchToAddress(index: number, options?: {
         nametag?: string;
     }): Promise<void>;
+    /**
+     * Background transport sync and nametag operations after address switch.
+     * Runs after switchToAddress returns so L1/L3 queries can start immediately.
+     */
+    private postSwitchSync;
     /**
      * Re-initialize modules after address switch
      */
@@ -3762,6 +3894,22 @@ declare class Sphere {
         hidden: boolean;
         nametag?: string;
     }>): Promise<void>;
+    /**
+     * 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 });
+     * ```
+     */
+    discoverAddresses(options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
     /**
      * Get aggregated status of all providers, grouped by role.
      *
@@ -4313,4 +4461,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };