@unicitylabs/sphere-sdk 0.2.1 → 0.2.3

package/dist/core/index.d.cts

@@ -578,7 +578,7 @@ interface PaymentRequest {
     readonly coinId: string;
     /** Optional message/memo */
     readonly message?: string;
-    /** Recipient nametag (who should pay) */
+    /** Where tokens should be sent */
     readonly recipientNametag?: string;
     /** Custom metadata */
     readonly metadata?: Record<string, unknown>;
@@ -605,7 +605,7 @@ interface IncomingPaymentRequest$1 {
     readonly symbol: string;
     /** Message from sender */
     readonly message?: string;
-    /** Who this request is for (our nametag) */
+    /** Requester's nametag (where tokens should be sent) */
     readonly recipientNametag?: string;
     /** Original request ID from sender */
     readonly requestId: string;
@@ -1094,6 +1094,8 @@ interface IncomingPaymentRequest {
     id: string;
     /** Transport-specific pubkey of sender */
     senderTransportPubkey: string;
+    /** Sender's nametag (if included in encrypted content) */
+    senderNametag?: string;
     /** Parsed request data */
     request: {
         requestId: string;
@@ -1252,6 +1254,12 @@ declare class L1PaymentsModule {
     private _transport?;
     constructor(config?: L1PaymentsModuleConfig);
     initialize(deps: L1PaymentsModuleDependencies): Promise<void>;
+    /**
+     * Ensure the Fulcrum WebSocket is connected. Called lazily before any
+     * operation that needs the network. If the singleton is already connected
+     * (e.g. by the address scanner), this is a no-op.
+     */
+    private ensureConnected;
     destroy(): void;
     /**
      * Check if a string looks like an L1 address (alpha1... or alphat1...)
@@ -1261,7 +1269,7 @@ declare class L1PaymentsModule {
      * Resolve recipient to L1 address
      * Supports: L1 address (alpha1...), nametag (with or without @)
      */
-    private resolveL1Address;
+    resolveL1Address(recipient: string): Promise<string>;
     /**
      * Resolve nametag to L1 address using transport provider
      */
@@ -1703,8 +1711,8 @@ interface PaymentsModuleConfig {
     maxRetries?: number;
     /** Enable debug logging */
     debug?: boolean;
-    /** L1 (ALPHA blockchain) configuration */
-    l1?: L1PaymentsModuleConfig;
+    /** L1 (ALPHA blockchain) configuration. Set to null to explicitly disable L1. */
+    l1?: L1PaymentsModuleConfig | null;
 }
 interface PaymentsModuleDependencies {
     identity: FullIdentity;
@@ -1958,6 +1966,11 @@ declare class PaymentsModule {
      * Remove a token by ID
      */
     removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
+    /**
+     * Delete physical token file(s) from all storage providers.
+     * Finds files by matching the SDK token ID prefix in the filename.
+     */
+    private deleteTokenFiles;
     /**
      * Get all tombstones
      */
@@ -2271,6 +2284,77 @@ declare const NETWORKS: {
 };
 type NetworkType = keyof typeof NETWORKS;
 
+/**
+ * Address Scanning — Derive HD addresses and check L1 balances via Fulcrum.
+ *
+ * Used after importing BIP32/.dat wallets to discover which addresses have funds.
+ */
+
+/** Progress callback for address scanning */
+interface ScanAddressProgress {
+    /** Number of addresses scanned so far */
+    scanned: number;
+    /** Total addresses to scan (maxAddresses * chains) */
+    total: number;
+    /** Current address being checked */
+    currentAddress: string;
+    /** Number of addresses found with balance */
+    foundCount: number;
+    /** Current gap count (consecutive empty addresses) */
+    currentGap: number;
+    /** Number of found addresses that have a nametag */
+    nametagsFoundCount: number;
+}
+/** Single scanned address result */
+interface ScannedAddressResult {
+    /** HD derivation index */
+    index: number;
+    /** L1 bech32 address (alpha1...) */
+    address: string;
+    /** Full BIP32 derivation path */
+    path: string;
+    /** L1 balance in ALPHA */
+    balance: number;
+    /** Whether this is a change address (chain 1) */
+    isChange: boolean;
+    /** Nametag associated with this address (resolved during scan) */
+    nametag?: string;
+}
+/** Options for scanning addresses */
+interface ScanAddressesOptions {
+    /** Maximum number of addresses to scan per chain (default: 50) */
+    maxAddresses?: number;
+    /** Stop after this many consecutive 0-balance addresses (default: 20) */
+    gapLimit?: number;
+    /** Also scan change addresses (chain 1) (default: true) */
+    includeChange?: boolean;
+    /** Progress callback */
+    onProgress?: (progress: ScanAddressProgress) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Resolve nametag for a found address. Return nametag string or null. */
+    resolveNametag?: (l1Address: string) => Promise<string | null>;
+}
+/** Result of scanning */
+interface ScanAddressesResult {
+    /** All addresses found with non-zero balance */
+    addresses: ScannedAddressResult[];
+    /** Total balance across all found addresses (in ALPHA) */
+    totalBalance: number;
+    /** Number of addresses actually scanned */
+    scannedCount: number;
+}
+/**
+ * Scan blockchain addresses to discover used addresses with balances.
+ * Derives addresses sequentially and checks L1 balance via Fulcrum.
+ * Uses gap limit to stop after N consecutive empty addresses.
+ *
+ * @param deriveAddress - Function to derive an address at a given index
+ * @param options - Scanning options
+ * @returns Scan results with found addresses and total balance
+ */
+declare function scanAddressesImpl(deriveAddress: (index: number, isChange: boolean) => AddressInfo, options?: ScanAddressesOptions): Promise<ScanAddressesResult>;
+
 /**
  * Legacy File Serialization Types
  */
@@ -2634,6 +2718,7 @@ declare class Sphere {
         transport: TransportProvider;
         oracle: OracleProvider;
         tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+        l1?: L1Config;
     }): Promise<{
         success: boolean;
         mnemonic?: string;
@@ -2688,6 +2773,8 @@ declare class Sphere {
         tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
         /** Optional nametag to register */
         nametag?: string;
+        /** L1 (ALPHA blockchain) configuration */
+        l1?: L1Config;
     }): Promise<{
         success: boolean;
         sphere?: Sphere;
@@ -2848,6 +2935,35 @@ declare class Sphere {
      * ```
      */
     deriveAddresses(count: number, includeChange?: boolean): AddressInfo[];
+    /**
+     * Scan blockchain addresses to discover used addresses with balances.
+     * Derives addresses sequentially and checks L1 balance via Fulcrum.
+     * Uses gap limit to stop after N consecutive empty addresses.
+     *
+     * @param options - Scanning options
+     * @returns Scan results with found addresses and total balance
+     *
+     * @example
+     * ```ts
+     * const result = await sphere.scanAddresses({
+     *   maxAddresses: 100,
+     *   gapLimit: 20,
+     *   onProgress: (p) => console.log(`Scanned ${p.scanned}/${p.total}, found ${p.foundCount}`),
+     * });
+     * console.log(`Found ${result.addresses.length} addresses, total: ${result.totalBalance} ALPHA`);
+     * ```
+     */
+    scanAddresses(options?: ScanAddressesOptions): Promise<ScanAddressesResult>;
+    /**
+     * Bulk-track scanned addresses with visibility and nametag data.
+     * Selected addresses get `hidden: false`, unselected get `hidden: true`.
+     * Performs only 2 storage writes total (tracked addresses + nametags).
+     */
+    trackScannedAddresses(entries: Array<{
+        index: number;
+        hidden: boolean;
+        nametag?: string;
+    }>): Promise<void>;
     getStatus(): {
         storage: {
             connected: boolean;
@@ -3064,6 +3180,11 @@ declare function encryptSimple(plaintext: string, password: string): string;
  * @param password - Decryption password
  */
 declare function decryptSimple(ciphertext: string, password: string): string;
+/**
+ * Decrypt data encrypted with PBKDF2-derived key (legacy JSON wallet format).
+ * Compatible with webwallet's encryptWithPassword/decryptWithPassword.
+ */
+declare function decryptWithSalt(ciphertext: string, password: string, salt: string): string | null;
 /**
  * Encrypt mnemonic phrase for storage
  * Uses simple AES encryption compatible with existing wallet format
@@ -3257,4 +3378,4 @@ declare function randomHex(byteLength: number): string;
  */
 declare function randomUUID(): string;
 
-export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, 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, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, 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, 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, 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

@@ -578,7 +578,7 @@ interface PaymentRequest {
     readonly coinId: string;
     /** Optional message/memo */
     readonly message?: string;
-    /** Recipient nametag (who should pay) */
+    /** Where tokens should be sent */
     readonly recipientNametag?: string;
     /** Custom metadata */
     readonly metadata?: Record<string, unknown>;
@@ -605,7 +605,7 @@ interface IncomingPaymentRequest$1 {
     readonly symbol: string;
     /** Message from sender */
     readonly message?: string;
-    /** Who this request is for (our nametag) */
+    /** Requester's nametag (where tokens should be sent) */
     readonly recipientNametag?: string;
     /** Original request ID from sender */
     readonly requestId: string;
@@ -1094,6 +1094,8 @@ interface IncomingPaymentRequest {
     id: string;
     /** Transport-specific pubkey of sender */
     senderTransportPubkey: string;
+    /** Sender's nametag (if included in encrypted content) */
+    senderNametag?: string;
     /** Parsed request data */
     request: {
         requestId: string;
@@ -1252,6 +1254,12 @@ declare class L1PaymentsModule {
     private _transport?;
     constructor(config?: L1PaymentsModuleConfig);
     initialize(deps: L1PaymentsModuleDependencies): Promise<void>;
+    /**
+     * Ensure the Fulcrum WebSocket is connected. Called lazily before any
+     * operation that needs the network. If the singleton is already connected
+     * (e.g. by the address scanner), this is a no-op.
+     */
+    private ensureConnected;
     destroy(): void;
     /**
      * Check if a string looks like an L1 address (alpha1... or alphat1...)
@@ -1261,7 +1269,7 @@ declare class L1PaymentsModule {
      * Resolve recipient to L1 address
      * Supports: L1 address (alpha1...), nametag (with or without @)
      */
-    private resolveL1Address;
+    resolveL1Address(recipient: string): Promise<string>;
     /**
      * Resolve nametag to L1 address using transport provider
      */
@@ -1703,8 +1711,8 @@ interface PaymentsModuleConfig {
     maxRetries?: number;
     /** Enable debug logging */
     debug?: boolean;
-    /** L1 (ALPHA blockchain) configuration */
-    l1?: L1PaymentsModuleConfig;
+    /** L1 (ALPHA blockchain) configuration. Set to null to explicitly disable L1. */
+    l1?: L1PaymentsModuleConfig | null;
 }
 interface PaymentsModuleDependencies {
     identity: FullIdentity;
@@ -1958,6 +1966,11 @@ declare class PaymentsModule {
      * Remove a token by ID
      */
     removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
+    /**
+     * Delete physical token file(s) from all storage providers.
+     * Finds files by matching the SDK token ID prefix in the filename.
+     */
+    private deleteTokenFiles;
     /**
      * Get all tombstones
      */
@@ -2271,6 +2284,77 @@ declare const NETWORKS: {
 };
 type NetworkType = keyof typeof NETWORKS;
 
+/**
+ * Address Scanning — Derive HD addresses and check L1 balances via Fulcrum.
+ *
+ * Used after importing BIP32/.dat wallets to discover which addresses have funds.
+ */
+
+/** Progress callback for address scanning */
+interface ScanAddressProgress {
+    /** Number of addresses scanned so far */
+    scanned: number;
+    /** Total addresses to scan (maxAddresses * chains) */
+    total: number;
+    /** Current address being checked */
+    currentAddress: string;
+    /** Number of addresses found with balance */
+    foundCount: number;
+    /** Current gap count (consecutive empty addresses) */
+    currentGap: number;
+    /** Number of found addresses that have a nametag */
+    nametagsFoundCount: number;
+}
+/** Single scanned address result */
+interface ScannedAddressResult {
+    /** HD derivation index */
+    index: number;
+    /** L1 bech32 address (alpha1...) */
+    address: string;
+    /** Full BIP32 derivation path */
+    path: string;
+    /** L1 balance in ALPHA */
+    balance: number;
+    /** Whether this is a change address (chain 1) */
+    isChange: boolean;
+    /** Nametag associated with this address (resolved during scan) */
+    nametag?: string;
+}
+/** Options for scanning addresses */
+interface ScanAddressesOptions {
+    /** Maximum number of addresses to scan per chain (default: 50) */
+    maxAddresses?: number;
+    /** Stop after this many consecutive 0-balance addresses (default: 20) */
+    gapLimit?: number;
+    /** Also scan change addresses (chain 1) (default: true) */
+    includeChange?: boolean;
+    /** Progress callback */
+    onProgress?: (progress: ScanAddressProgress) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Resolve nametag for a found address. Return nametag string or null. */
+    resolveNametag?: (l1Address: string) => Promise<string | null>;
+}
+/** Result of scanning */
+interface ScanAddressesResult {
+    /** All addresses found with non-zero balance */
+    addresses: ScannedAddressResult[];
+    /** Total balance across all found addresses (in ALPHA) */
+    totalBalance: number;
+    /** Number of addresses actually scanned */
+    scannedCount: number;
+}
+/**
+ * Scan blockchain addresses to discover used addresses with balances.
+ * Derives addresses sequentially and checks L1 balance via Fulcrum.
+ * Uses gap limit to stop after N consecutive empty addresses.
+ *
+ * @param deriveAddress - Function to derive an address at a given index
+ * @param options - Scanning options
+ * @returns Scan results with found addresses and total balance
+ */
+declare function scanAddressesImpl(deriveAddress: (index: number, isChange: boolean) => AddressInfo, options?: ScanAddressesOptions): Promise<ScanAddressesResult>;
+
 /**
  * Legacy File Serialization Types
  */
@@ -2634,6 +2718,7 @@ declare class Sphere {
         transport: TransportProvider;
         oracle: OracleProvider;
         tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+        l1?: L1Config;
     }): Promise<{
         success: boolean;
         mnemonic?: string;
@@ -2688,6 +2773,8 @@ declare class Sphere {
         tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
         /** Optional nametag to register */
         nametag?: string;
+        /** L1 (ALPHA blockchain) configuration */
+        l1?: L1Config;
     }): Promise<{
         success: boolean;
         sphere?: Sphere;
@@ -2848,6 +2935,35 @@ declare class Sphere {
      * ```
      */
     deriveAddresses(count: number, includeChange?: boolean): AddressInfo[];
+    /**
+     * Scan blockchain addresses to discover used addresses with balances.
+     * Derives addresses sequentially and checks L1 balance via Fulcrum.
+     * Uses gap limit to stop after N consecutive empty addresses.
+     *
+     * @param options - Scanning options
+     * @returns Scan results with found addresses and total balance
+     *
+     * @example
+     * ```ts
+     * const result = await sphere.scanAddresses({
+     *   maxAddresses: 100,
+     *   gapLimit: 20,
+     *   onProgress: (p) => console.log(`Scanned ${p.scanned}/${p.total}, found ${p.foundCount}`),
+     * });
+     * console.log(`Found ${result.addresses.length} addresses, total: ${result.totalBalance} ALPHA`);
+     * ```
+     */
+    scanAddresses(options?: ScanAddressesOptions): Promise<ScanAddressesResult>;
+    /**
+     * Bulk-track scanned addresses with visibility and nametag data.
+     * Selected addresses get `hidden: false`, unselected get `hidden: true`.
+     * Performs only 2 storage writes total (tracked addresses + nametags).
+     */
+    trackScannedAddresses(entries: Array<{
+        index: number;
+        hidden: boolean;
+        nametag?: string;
+    }>): Promise<void>;
     getStatus(): {
         storage: {
             connected: boolean;
@@ -3064,6 +3180,11 @@ declare function encryptSimple(plaintext: string, password: string): string;
  * @param password - Decryption password
  */
 declare function decryptSimple(ciphertext: string, password: string): string;
+/**
+ * Decrypt data encrypted with PBKDF2-derived key (legacy JSON wallet format).
+ * Compatible with webwallet's encryptWithPassword/decryptWithPassword.
+ */
+declare function decryptWithSalt(ciphertext: string, password: string, salt: string): string | null;
 /**
  * Encrypt mnemonic phrase for storage
  * Uses simple AES encryption compatible with existing wallet format
@@ -3257,4 +3378,4 @@ declare function randomHex(byteLength: number): string;
  */
 declare function randomUUID(): string;
 
-export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, 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, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, 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, 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, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };