@unicitylabs/sphere-sdk 0.2.1 → 0.2.2

package/dist/core/index.d.cts

@@ -1958,6 +1958,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 +2276,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
  */
@@ -2848,6 +2924,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 +3169,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 +3367,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

@@ -1958,6 +1958,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 +2276,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
  */
@@ -2848,6 +2924,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 +3169,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 +3367,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 };