@unicitylabs/sphere-sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,705 @@
1
+ import elliptic from 'elliptic';
2
+
3
+ interface Wallet {
4
+ masterPrivateKey: string;
5
+ chainCode?: string;
6
+ addresses: WalletAddress[];
7
+ createdAt?: number;
8
+ isEncrypted?: boolean;
9
+ encryptedMasterKey?: string;
10
+ childPrivateKey?: string | null;
11
+ isImportedAlphaWallet?: boolean;
12
+ masterChainCode?: string | null;
13
+ isBIP32?: boolean;
14
+ descriptorPath?: string | null;
15
+ }
16
+ interface WalletAddress {
17
+ address: string;
18
+ publicKey?: string;
19
+ privateKey?: string;
20
+ path: string | null;
21
+ index: number;
22
+ createdAt?: string;
23
+ isChange?: boolean;
24
+ }
25
+ interface StoredWallet {
26
+ key: string;
27
+ data: Wallet;
28
+ }
29
+ interface TransactionInput {
30
+ txid: string;
31
+ vout: number;
32
+ value: number;
33
+ address: string;
34
+ }
35
+ interface TransactionOutput {
36
+ value: number;
37
+ address: string;
38
+ }
39
+ interface Transaction {
40
+ input: TransactionInput;
41
+ outputs: TransactionOutput[];
42
+ fee: number;
43
+ changeAmount: number;
44
+ changeAddress: string;
45
+ }
46
+ interface TransactionPlan {
47
+ success: boolean;
48
+ transactions: Transaction[];
49
+ error?: string;
50
+ }
51
+ interface UTXO {
52
+ txid?: string;
53
+ tx_hash?: string;
54
+ vout?: number;
55
+ tx_pos?: number;
56
+ value: number;
57
+ height?: number;
58
+ address?: string;
59
+ }
60
+ interface RestoreWalletResult {
61
+ success: boolean;
62
+ wallet: Wallet;
63
+ message?: string;
64
+ error?: string;
65
+ /** Indicates that the wallet.dat file is encrypted and requires a password */
66
+ isEncryptedDat?: boolean;
67
+ }
68
+ interface ExportOptions {
69
+ password?: string;
70
+ filename?: string;
71
+ }
72
+ /**
73
+ * JSON Wallet Export Format v1.0
74
+ *
75
+ * Supports multiple wallet sources:
76
+ * - "mnemonic": Created from BIP39 mnemonic phrase (new standard)
77
+ * - "file_bip32": Imported from file with chain code (BIP32 HD wallet)
78
+ * - "file_standard": Imported from file without chain code (HMAC-based)
79
+ * - "dat_descriptor": Imported from wallet.dat descriptor wallet
80
+ * - "dat_hd": Imported from wallet.dat HD wallet
81
+ * - "dat_legacy": Imported from wallet.dat legacy wallet
82
+ */
83
+ type WalletJSONSource = "mnemonic" | "file_bip32" | "file_standard" | "dat_descriptor" | "dat_hd" | "dat_legacy";
84
+ type WalletJSONDerivationMode = "bip32" | "wif_hmac" | "legacy_hmac";
85
+ interface WalletJSONAddress {
86
+ address: string;
87
+ publicKey: string;
88
+ path: string;
89
+ index?: number;
90
+ isChange?: boolean;
91
+ }
92
+ /**
93
+ * JSON Wallet Export structure
94
+ */
95
+ interface WalletJSON {
96
+ /** Format version */
97
+ version: "1.0";
98
+ /** Generation timestamp ISO 8601 */
99
+ generated: string;
100
+ /** Security warning */
101
+ warning: string;
102
+ /** Master private key (hex, 64 chars) */
103
+ masterPrivateKey: string;
104
+ /** Master chain code for BIP32 (hex, 64 chars) - optional for HMAC wallets */
105
+ chainCode?: string;
106
+ /** BIP39 mnemonic phrase - only present if source is "mnemonic" */
107
+ mnemonic?: string;
108
+ /** Derivation mode used */
109
+ derivationMode: WalletJSONDerivationMode;
110
+ /** Source of the wallet */
111
+ source: WalletJSONSource;
112
+ /** First address for verification */
113
+ firstAddress: WalletJSONAddress;
114
+ /** Descriptor path for BIP32 wallets (e.g., "84'/0'/0'") */
115
+ descriptorPath?: string;
116
+ /** Encrypted fields (when password protected) */
117
+ encrypted?: {
118
+ /** Encrypted master private key (AES-256) */
119
+ masterPrivateKey: string;
120
+ /** Encrypted mnemonic (AES-256) - only if source is "mnemonic" */
121
+ mnemonic?: string;
122
+ /** Salt used for key derivation */
123
+ salt: string;
124
+ /** Number of PBKDF2 iterations */
125
+ iterations: number;
126
+ };
127
+ /** Additional addresses beyond first (optional) */
128
+ addresses?: WalletJSONAddress[];
129
+ }
130
+ interface WalletJSONExportOptions {
131
+ /** Password for encryption (optional) */
132
+ password?: string;
133
+ /** Include all addresses (default: only first address) */
134
+ includeAllAddresses?: boolean;
135
+ /** Number of addresses to include (if includeAllAddresses is false) */
136
+ addressCount?: number;
137
+ }
138
+ interface WalletJSONImportResult {
139
+ success: boolean;
140
+ wallet?: Wallet;
141
+ source?: WalletJSONSource;
142
+ derivationMode?: WalletJSONDerivationMode;
143
+ /** Indicates if mnemonic was found in the JSON */
144
+ hasMnemonic?: boolean;
145
+ /** The decrypted mnemonic phrase (if available) */
146
+ mnemonic?: string;
147
+ message?: string;
148
+ error?: string;
149
+ }
150
+ type VestingMode = "all" | "vested" | "unvested";
151
+ interface ClassifiedUTXO extends UTXO {
152
+ vestingStatus?: "vested" | "unvested" | "error";
153
+ coinbaseHeight?: number | null;
154
+ }
155
+ interface VestingBalances {
156
+ vested: bigint;
157
+ unvested: bigint;
158
+ all: bigint;
159
+ }
160
+ interface ClassificationResult {
161
+ isVested: boolean;
162
+ coinbaseHeight: number | null;
163
+ error?: string;
164
+ }
165
+ /**
166
+ * Parse BIP32 path components from a derivation path string
167
+ * @param path - Full path like "m/84'/1'/0'/0/5" or "m/44'/0'/0'/1/3"
168
+ * @returns { chain: number, index: number } where chain=0 is external, chain=1 is change
169
+ * Returns null if path is invalid
170
+ *
171
+ * Examples:
172
+ * "m/84'/1'/0'/0/5" -> { chain: 0, index: 5 } (external address 5)
173
+ * "m/84'/1'/0'/1/3" -> { chain: 1, index: 3 } (change address 3)
174
+ */
175
+ declare function parsePathComponents(path: string): {
176
+ chain: number;
177
+ index: number;
178
+ } | null;
179
+ /**
180
+ * Check if a BIP32 path represents a change address (chain=1)
181
+ * @param path - Full BIP32 path string
182
+ * @returns true if this is a change address path
183
+ */
184
+ declare function isChangePath(path: string): boolean;
185
+ /**
186
+ * Get display-friendly index from path (for UI display only)
187
+ * @param path - Full BIP32 path string
188
+ * @returns The address index number, or 0 if invalid
189
+ */
190
+ declare function getIndexFromPath(path: string): number;
191
+ /**
192
+ * Convert a BIP32 path to a DOM-safe ID string
193
+ * Replaces characters that are invalid in DOM IDs:
194
+ * - ' (apostrophe) -> 'h' (hardened marker)
195
+ * - / (forward slash) -> '-' (dash)
196
+ *
197
+ * @param path - Full BIP32 path like "m/84'/1'/0'/0/5"
198
+ * @returns DOM-safe ID like "m-84h-1h-0h-0-5"
199
+ *
200
+ * Examples:
201
+ * "m/84'/1'/0'/0/5" -> "m-84h-1h-0h-0-5"
202
+ * "m/44'/0'/0'/1/3" -> "m-44h-0h-0h-1-3"
203
+ */
204
+ declare function pathToDOMId(path: string): string;
205
+ /**
206
+ * Convert a DOM-safe ID back to a BIP32 path string
207
+ * Reverses the transformation done by pathToDOMId:
208
+ * - 'h' -> ' (apostrophe for hardened)
209
+ * - '-' -> / (forward slash)
210
+ *
211
+ * @param encoded - DOM-safe ID like "m-84h-1h-0h-0-5"
212
+ * @returns BIP32 path like "m/84'/1'/0'/0/5"
213
+ *
214
+ * Examples:
215
+ * "m-84h-1h-0h-0-5" -> "m/84'/1'/0'/0/5"
216
+ * "m-44h-0h-0h-1-3" -> "m/44'/0'/0'/1/3"
217
+ */
218
+ declare function domIdToPath(encoded: string): string;
219
+
220
+ /**
221
+ * Bech32 Encoding/Decoding
222
+ * BIP-173 implementation for address encoding
223
+ */
224
+ /** Bech32 character set from BIP-173 */
225
+ declare const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
226
+ /**
227
+ * Convert between bit arrays (8→5 or 5→8)
228
+ */
229
+ declare function convertBits(data: number[], fromBits: number, toBits: number, pad: boolean): number[] | null;
230
+ /**
231
+ * Encode data to bech32 address
232
+ *
233
+ * @example
234
+ * ```ts
235
+ * const address = encodeBech32('alpha', 1, pubkeyHash);
236
+ * // 'alpha1qw...'
237
+ * ```
238
+ */
239
+ declare function encodeBech32(hrp: string, version: number, program: Uint8Array): string;
240
+ /**
241
+ * Decode bech32 address
242
+ *
243
+ * @example
244
+ * ```ts
245
+ * const result = decodeBech32('alpha1qw...');
246
+ * // { hrp: 'alpha', witnessVersion: 1, data: Uint8Array }
247
+ * ```
248
+ */
249
+ declare function decodeBech32(addr: string): {
250
+ hrp: string;
251
+ witnessVersion: number;
252
+ data: Uint8Array;
253
+ } | null;
254
+ /**
255
+ * Alias for encodeBech32 (L1 SDK compatibility)
256
+ */
257
+ declare const createBech32: typeof encodeBech32;
258
+
259
+ /**
260
+ * Convert "alpha1xxxx" Bech32 → Electrum script hash
261
+ * Required for:
262
+ * - blockchain.scripthash.get_history
263
+ * - blockchain.scripthash.listunspent
264
+ */
265
+ declare function addressToScriptHash(address: string): string;
266
+
267
+ /**
268
+ * Cryptographic utilities for SDK2
269
+ *
270
+ * Provides BIP39 mnemonic and BIP32 key derivation functions.
271
+ * Platform-independent - no browser-specific APIs.
272
+ */
273
+
274
+ declare const ec: elliptic.ec;
275
+ interface DerivedKey {
276
+ privateKey: string;
277
+ chainCode: string;
278
+ }
279
+ interface KeyPair {
280
+ privateKey: string;
281
+ publicKey: string;
282
+ }
283
+ interface AddressInfo extends KeyPair {
284
+ address: string;
285
+ path: string;
286
+ index: number;
287
+ }
288
+ /**
289
+ * Derive child key using BIP32 standard
290
+ * @param parentPrivKey - Parent private key (64 hex chars)
291
+ * @param parentChainCode - Parent chain code (64 hex chars)
292
+ * @param index - Child index (>= 0x80000000 for hardened)
293
+ */
294
+ declare function deriveChildKey$1(parentPrivKey: string, parentChainCode: string, index: number): DerivedKey;
295
+ /**
296
+ * Derive key at a full BIP32/BIP44 path
297
+ * @param masterPrivKey - Master private key
298
+ * @param masterChainCode - Master chain code
299
+ * @param path - BIP44 path like "m/44'/0'/0'/0/0"
300
+ */
301
+ declare function deriveKeyAtPath$1(masterPrivKey: string, masterChainCode: string, path: string): DerivedKey;
302
+ /**
303
+ * Compute HASH160 (SHA256 -> RIPEMD160)
304
+ */
305
+ declare function hash160(data: string): string;
306
+ /**
307
+ * Alias for hash160 (L1 SDK compatibility)
308
+ */
309
+ declare const computeHash160: typeof hash160;
310
+ /**
311
+ * Convert hex string to Uint8Array for witness program
312
+ */
313
+ declare function hash160ToBytes(hash160Hex: string): Uint8Array;
314
+ /**
315
+ * Generate bech32 address from public key
316
+ * @param publicKey - Compressed public key as hex string
317
+ * @param prefix - Address prefix (default: "alpha")
318
+ * @param witnessVersion - Witness version (default: 0 for P2WPKH)
319
+ * @returns Bech32 encoded address
320
+ */
321
+ declare function publicKeyToAddress(publicKey: string, prefix?: string, witnessVersion?: number): string;
322
+ /**
323
+ * Get address info from private key
324
+ */
325
+ declare function privateKeyToAddressInfo(privateKey: string, prefix?: string): {
326
+ address: string;
327
+ publicKey: string;
328
+ };
329
+ /**
330
+ * Generate full address info from private key with index and path
331
+ * (L1 SDK compatibility)
332
+ */
333
+ declare function generateAddressInfo(privateKey: string, index: number, path: string, prefix?: string): AddressInfo;
334
+
335
+ declare function encrypt(text: string, password: string): string;
336
+ declare function decrypt(encrypted: string, password: string): string;
337
+ declare function generatePrivateKey(): string;
338
+ /**
339
+ * Encrypt wallet master key with password using PBKDF2 + AES
340
+ */
341
+ declare function encryptWallet(masterPrivateKey: string, password: string): string;
342
+ /**
343
+ * Decrypt wallet master key with password
344
+ */
345
+ declare function decryptWallet(encryptedData: string, password: string): string;
346
+ /**
347
+ * Convert hex private key to WIF format
348
+ */
349
+ declare function hexToWIF(hexKey: string): string;
350
+
351
+ /**
352
+ * Standard BIP32 child key derivation
353
+ * Re-export from core with L1 naming convention
354
+ */
355
+ declare const deriveChildKeyBIP32: typeof deriveChildKey$1;
356
+ /**
357
+ * Derive key at a full BIP44 path
358
+ * Re-export from core
359
+ */
360
+ declare const deriveKeyAtPath: typeof deriveKeyAtPath$1;
361
+ /**
362
+ * Generate master key and chain code from seed (BIP32 standard)
363
+ * Wrapper around core function with L1 return type naming
364
+ */
365
+ declare function generateMasterKeyFromSeed(seedHex: string): {
366
+ masterPrivateKey: string;
367
+ masterChainCode: string;
368
+ };
369
+ /**
370
+ * Generate HD address using standard BIP32
371
+ * Standard path: m/44'/0'/0'/0/{index} (external chain, non-hardened)
372
+ * For change addresses, use isChange = true to get m/44'/0'/0'/1/{index}
373
+ */
374
+ declare function generateHDAddressBIP32(masterPriv: string, chainCode: string, index: number, basePath?: string, isChange?: boolean): AddressInfo;
375
+ /**
376
+ * Generate address from master private key using HMAC-SHA512 derivation
377
+ * This matches exactly the original index.html implementation
378
+ * NOTE: This is NON-STANDARD derivation for legacy wallet compatibility
379
+ *
380
+ * @param masterPrivateKey - 32-byte hex private key (64 chars)
381
+ * @param index - Address index
382
+ */
383
+ declare function generateAddressFromMasterKey(masterPrivateKey: string, index: number): AddressInfo;
384
+ /**
385
+ * @deprecated Use deriveChildKeyBIP32 for new wallets
386
+ * Legacy HMAC-SHA512 derivation (non-standard)
387
+ * Kept for backward compatibility with old wallets
388
+ */
389
+ declare function deriveChildKey(masterPriv: string, chainCode: string, index: number): {
390
+ privateKey: string;
391
+ nextChainCode: string;
392
+ };
393
+ /**
394
+ * @deprecated Use generateHDAddressBIP32 for new wallets
395
+ * Legacy HD address generation (non-standard derivation)
396
+ */
397
+ declare function generateHDAddress(masterPriv: string, chainCode: string, index: number): AddressInfo;
398
+
399
+ interface BlockHeader {
400
+ height: number;
401
+ hex: string;
402
+ [key: string]: unknown;
403
+ }
404
+ declare function isWebSocketConnected(): boolean;
405
+ declare function waitForConnection(): Promise<void>;
406
+ declare function connect(endpoint?: string): Promise<void>;
407
+ declare function rpc(method: string, params?: unknown[]): Promise<unknown>;
408
+ declare function getUtxo(address: string): Promise<{
409
+ tx_hash: string | undefined;
410
+ tx_pos: number | undefined;
411
+ value: number;
412
+ height: number | undefined;
413
+ address: string;
414
+ }[]>;
415
+ declare function getBalance(address: string): Promise<number>;
416
+ declare function broadcast(rawHex: string): Promise<unknown>;
417
+ declare function subscribeBlocks(cb: (header: BlockHeader) => void): Promise<() => void>;
418
+ interface TransactionHistoryItem {
419
+ tx_hash: string;
420
+ height: number;
421
+ fee?: number;
422
+ }
423
+ interface TransactionDetail {
424
+ txid: string;
425
+ version: number;
426
+ locktime: number;
427
+ vin: Array<{
428
+ txid: string;
429
+ vout: number;
430
+ scriptSig?: {
431
+ hex: string;
432
+ };
433
+ sequence: number;
434
+ }>;
435
+ vout: Array<{
436
+ value: number;
437
+ n: number;
438
+ scriptPubKey: {
439
+ hex: string;
440
+ type: string;
441
+ addresses?: string[];
442
+ address?: string;
443
+ };
444
+ }>;
445
+ blockhash?: string;
446
+ confirmations?: number;
447
+ time?: number;
448
+ blocktime?: number;
449
+ }
450
+ declare function getTransactionHistory(address: string): Promise<TransactionHistoryItem[]>;
451
+ declare function getTransaction(txid: string): Promise<unknown>;
452
+ declare function getBlockHeader(height: number): Promise<unknown>;
453
+ declare function getCurrentBlockHeight(): Promise<number>;
454
+ declare function disconnect(): void;
455
+
456
+ /**
457
+ * Create scriptPubKey for address (P2WPKH for bech32)
458
+ * Exact copy from index.html
459
+ */
460
+ declare function createScriptPubKey(address: string): string;
461
+ /**
462
+ * Build a proper SegWit transaction
463
+ * Exact copy from index.html buildSegWitTransaction()
464
+ */
465
+ declare function buildSegWitTransaction(txPlan: {
466
+ input: {
467
+ tx_hash: string;
468
+ tx_pos: number;
469
+ value: number;
470
+ };
471
+ outputs: Array<{
472
+ value: number;
473
+ address: string;
474
+ }>;
475
+ }, keyPair: elliptic.ec.KeyPair, publicKey: string): {
476
+ hex: string;
477
+ txid: string;
478
+ };
479
+ /**
480
+ * Create and sign a transaction
481
+ * Uses the private key for the specific address being spent from
482
+ */
483
+ declare function createAndSignTransaction(wallet: Wallet, txPlan: Transaction): {
484
+ raw: string;
485
+ txid: string;
486
+ };
487
+ /**
488
+ * Collect UTXOs for required amount
489
+ * Based on index.html collectUtxosForAmount()
490
+ *
491
+ * Strategy: First try to find a single UTXO that can cover amount + fee.
492
+ * If not found, fall back to combining multiple UTXOs.
493
+ */
494
+ declare function collectUtxosForAmount(utxoList: UTXO[], amountSats: number, recipientAddress: string, senderAddress: string): TransactionPlan;
495
+ /**
496
+ * Create transaction plan from wallet
497
+ * @param wallet - The wallet
498
+ * @param toAddress - Recipient address
499
+ * @param amountAlpha - Amount in ALPHA
500
+ * @param fromAddress - Optional: specific address to send from (defaults to first address)
501
+ */
502
+ declare function createTransactionPlan(wallet: Wallet, toAddress: string, amountAlpha: number, fromAddress?: string): Promise<TransactionPlan>;
503
+ /**
504
+ * Send ALPHA to address
505
+ * @param wallet - The wallet
506
+ * @param toAddress - Recipient address
507
+ * @param amountAlpha - Amount in ALPHA
508
+ * @param fromAddress - Optional: specific address to send from
509
+ */
510
+ declare function sendAlpha(wallet: Wallet, toAddress: string, amountAlpha: number, fromAddress?: string): Promise<{
511
+ txid: string;
512
+ raw: string;
513
+ broadcastResult: unknown;
514
+ }[]>;
515
+
516
+ declare const VESTING_THRESHOLD = 280000;
517
+ declare class VestingClassifier {
518
+ private memoryCache;
519
+ private dbName;
520
+ private storeName;
521
+ private db;
522
+ /**
523
+ * Initialize IndexedDB for persistent caching
524
+ */
525
+ initDB(): Promise<void>;
526
+ /**
527
+ * Check if transaction is coinbase
528
+ */
529
+ private isCoinbaseTransaction;
530
+ /**
531
+ * Load from IndexedDB cache
532
+ */
533
+ private loadFromDB;
534
+ /**
535
+ * Save to IndexedDB cache
536
+ */
537
+ private saveToDB;
538
+ /**
539
+ * Trace a transaction to its coinbase origin
540
+ * Alpha blockchain has single-input transactions, making this a linear trace
541
+ */
542
+ traceToOrigin(txHash: string): Promise<{
543
+ coinbaseHeight: number | null;
544
+ error?: string;
545
+ }>;
546
+ /**
547
+ * Classify a single UTXO
548
+ */
549
+ classifyUtxo(utxo: UTXO): Promise<ClassificationResult>;
550
+ /**
551
+ * Classify multiple UTXOs with progress callback
552
+ */
553
+ classifyUtxos(utxos: UTXO[], onProgress?: (current: number, total: number) => void): Promise<{
554
+ vested: ClassifiedUTXO[];
555
+ unvested: ClassifiedUTXO[];
556
+ errors: Array<{
557
+ utxo: UTXO;
558
+ error: string;
559
+ }>;
560
+ }>;
561
+ /**
562
+ * Clear all caches
563
+ */
564
+ clearCaches(): void;
565
+ }
566
+ declare const vestingClassifier: VestingClassifier;
567
+
568
+ declare class VestingStateManager {
569
+ private currentMode;
570
+ private addressCache;
571
+ private classificationInProgress;
572
+ /**
573
+ * Set the current vesting mode
574
+ */
575
+ setMode(mode: VestingMode): void;
576
+ getMode(): VestingMode;
577
+ /**
578
+ * Classify all UTXOs for an address
579
+ */
580
+ classifyAddressUtxos(address: string, utxos: UTXO[], onProgress?: (current: number, total: number) => void): Promise<void>;
581
+ /**
582
+ * Get filtered UTXOs based on current vesting mode
583
+ */
584
+ getFilteredUtxos(address: string): ClassifiedUTXO[];
585
+ /**
586
+ * Get all UTXOs regardless of vesting mode (for transactions)
587
+ */
588
+ getAllUtxos(address: string): ClassifiedUTXO[];
589
+ /**
590
+ * Get balance for current vesting mode (in satoshis)
591
+ */
592
+ getBalance(address: string): bigint;
593
+ /**
594
+ * Get all balances for display
595
+ */
596
+ getAllBalances(address: string): VestingBalances;
597
+ /**
598
+ * Check if address has been classified
599
+ */
600
+ hasClassifiedData(address: string): boolean;
601
+ /**
602
+ * Check if classification is in progress
603
+ */
604
+ isClassifying(): boolean;
605
+ /**
606
+ * Clear cache for an address
607
+ */
608
+ clearAddressCache(address: string): void;
609
+ /**
610
+ * Clear all caches
611
+ */
612
+ clearAllCaches(): void;
613
+ }
614
+ declare const vestingState: VestingStateManager;
615
+
616
+ /**
617
+ * WalletAddressHelper - Path-based address lookup and mutation utilities
618
+ *
619
+ * Key principle: A BIP32 path ALWAYS derives the same address from a given master key.
620
+ * - If we try to add a different address for an existing path → FATAL ERROR
621
+ * - This indicates corruption, wrong derivation, or data integrity issue
622
+ *
623
+ * Performance: O(n) lookup is negligible for typical wallet sizes (5-100 addresses)
624
+ */
625
+
626
+ declare class WalletAddressHelper {
627
+ /**
628
+ * Find address by BIP32 derivation path
629
+ * @param wallet - The wallet to search
630
+ * @param path - Full BIP32 path like "m/84'/1'/0'/0/5"
631
+ * @returns The address if found, undefined otherwise
632
+ */
633
+ static findByPath(wallet: Wallet, path: string): WalletAddress | undefined;
634
+ /**
635
+ * Get the default address (first external/non-change address)
636
+ * This replaces `wallet.addresses[0]` pattern for safer access
637
+ *
638
+ * @param wallet - The wallet
639
+ * @returns First non-change address, or first address if all are change
640
+ */
641
+ static getDefault(wallet: Wallet): WalletAddress;
642
+ /**
643
+ * Get the default address, or undefined if wallet has no addresses
644
+ * Safe version that doesn't throw on empty wallet
645
+ */
646
+ static getDefaultOrNull(wallet: Wallet): WalletAddress | undefined;
647
+ /**
648
+ * Add new address to wallet (immutable operation)
649
+ *
650
+ * THROWS if address with same path but different address string already exists.
651
+ * This indicates a serious derivation or data corruption issue.
652
+ *
653
+ * If the same path+address already exists, returns wallet unchanged (idempotent).
654
+ *
655
+ * @param wallet - The wallet to add to
656
+ * @param newAddress - The address to add
657
+ * @returns New wallet object with address added
658
+ * @throws Error if path exists with different address (corruption indicator)
659
+ */
660
+ static add(wallet: Wallet, newAddress: WalletAddress): Wallet;
661
+ /**
662
+ * Remove address by path (immutable operation)
663
+ * @param wallet - The wallet to modify
664
+ * @param path - The path of the address to remove
665
+ * @returns New wallet object with address removed
666
+ */
667
+ static removeByPath(wallet: Wallet, path: string): Wallet;
668
+ /**
669
+ * Get all external (non-change) addresses
670
+ * @param wallet - The wallet
671
+ * @returns Array of external addresses
672
+ */
673
+ static getExternal(wallet: Wallet): WalletAddress[];
674
+ /**
675
+ * Get all change addresses
676
+ * @param wallet - The wallet
677
+ * @returns Array of change addresses
678
+ */
679
+ static getChange(wallet: Wallet): WalletAddress[];
680
+ /**
681
+ * Check if wallet has an address with the given path
682
+ * @param wallet - The wallet to check
683
+ * @param path - The path to look for
684
+ * @returns true if path exists
685
+ */
686
+ static hasPath(wallet: Wallet, path: string): boolean;
687
+ /**
688
+ * Validate wallet address array integrity
689
+ * Checks for duplicate paths which indicate data corruption
690
+ *
691
+ * @param wallet - The wallet to validate
692
+ * @throws Error if duplicate paths found
693
+ */
694
+ static validate(wallet: Wallet): void;
695
+ /**
696
+ * Sort addresses with external first, then change, each sorted by index
697
+ * Useful for display purposes
698
+ *
699
+ * @param wallet - The wallet
700
+ * @returns New wallet with sorted addresses
701
+ */
702
+ static sortAddresses(wallet: Wallet): Wallet;
703
+ }
704
+
705
+ export { type BlockHeader, CHARSET, type ClassificationResult, type ClassifiedUTXO, type ExportOptions, type RestoreWalletResult, type StoredWallet, type Transaction, type TransactionDetail, type TransactionHistoryItem, type TransactionInput, type TransactionOutput, type TransactionPlan, type UTXO, VESTING_THRESHOLD, type VestingBalances, type VestingMode, type Wallet, type WalletAddress, WalletAddressHelper, type WalletJSON, type WalletJSONAddress, type WalletJSONDerivationMode, type WalletJSONExportOptions, type WalletJSONImportResult, type WalletJSONSource, addressToScriptHash, broadcast, buildSegWitTransaction, collectUtxosForAmount, computeHash160, connect, convertBits, createAndSignTransaction, createBech32, createScriptPubKey, createTransactionPlan, decodeBech32, decrypt, decryptWallet, deriveChildKey, deriveChildKeyBIP32, deriveKeyAtPath, disconnect, domIdToPath, ec, encodeBech32, encrypt, encryptWallet, generateAddressFromMasterKey, generateAddressInfo, generateHDAddress, generateHDAddressBIP32, generateMasterKeyFromSeed, generatePrivateKey, getBalance, getBlockHeader, getCurrentBlockHeight, getIndexFromPath, getTransaction, getTransactionHistory, getUtxo, hash160, hash160ToBytes, hexToWIF, isChangePath, isWebSocketConnected, parsePathComponents, pathToDOMId, privateKeyToAddressInfo, publicKeyToAddress, rpc, sendAlpha, subscribeBlocks, vestingClassifier, vestingState, waitForConnection };