khodpay_bip44/lib.rs
1//! # BIP-44: Multi-Account Hierarchy for Deterministic Wallets
2//!
3//! This crate provides a production-ready Rust implementation of [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki),
4//! which defines a logical hierarchy for deterministic wallets based on BIP-32.
5//!
6//! ## Features
7//!
8//! - **Multi-Account Support**: Manage multiple accounts per cryptocurrency
9//! - **Multi-Coin Support**: Support for Bitcoin, Ethereum, Litecoin, and more
10//! - **BIP Standards**: Support for BIP-44, BIP-49, BIP-84, and BIP-86
11//! - **Account Caching**: Efficient account derivation with caching
12//! - **Builder Pattern**: Fluent API for wallet construction
13//! - **Serialization**: Optional serde support for persistence
14//! - **Type Safety**: Strong typing for paths, chains, and coin types
15//!
16//! ## Quick Start
17//!
18//! ```rust
19//! use khodpay_bip44::{Wallet, Purpose, CoinType, Language};
20//! use khodpay_bip32::Network;
21//!
22//! // Create a wallet from a mnemonic
23//! let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
24//! let mut wallet = Wallet::from_mnemonic(
25//! mnemonic,
26//! "", // password
27//! Language::English,
28//! Network::BitcoinMainnet,
29//! )?;
30//!
31//! // Get the first Bitcoin account
32//! let account = wallet.get_account(Purpose::BIP44, CoinType::Bitcoin, 0)?;
33//!
34//! // Derive receiving addresses
35//! let addr0 = account.derive_external(0)?;
36//! let addr1 = account.derive_external(1)?;
37//!
38//! // Derive change addresses
39//! let change0 = account.derive_internal(0)?;
40//! # Ok::<(), khodpay_bip44::Error>(())
41//! ```
42//!
43//! ## BIP-44 Path Structure
44//!
45//! ```text
46//! m / purpose' / coin_type' / account' / change / address_index
47//! ```
48//!
49//! - **purpose'**: Constant set to 44' (or 49', 84', 86' for other standards)
50//! - **coin_type'**: Cryptocurrency type (0' for Bitcoin, 60' for Ethereum, etc.)
51//! - **account'**: Account index (allows multiple accounts per coin)
52//! - **change**: 0 for external (receiving), 1 for internal (change)
53//! - **address_index**: Address index within the chain
54//!
55//! ## Common Use Cases
56//!
57//! ### Creating a Multi-Coin Wallet
58//!
59//! ```rust
60//! use khodpay_bip44::{Wallet, Purpose, CoinType, Language};
61//! use khodpay_bip32::Network;
62//!
63//! let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
64//! let mut wallet = Wallet::from_english_mnemonic(mnemonic, "", Network::BitcoinMainnet)?;
65//!
66//! // Bitcoin account
67//! let btc_account = wallet.get_account(Purpose::BIP44, CoinType::Bitcoin, 0)?;
68//! let btc_addr = btc_account.derive_external(0)?;
69//!
70//! // Ethereum account
71//! let eth_account = wallet.get_account(Purpose::BIP44, CoinType::Ethereum, 0)?;
72//! let eth_addr = eth_account.derive_external(0)?;
73//! # Ok::<(), khodpay_bip44::Error>(())
74//! ```
75//!
76//! ### Using the Builder Pattern
77//!
78//! ```rust
79//! use khodpay_bip44::{WalletBuilder, Purpose, CoinType, Language};
80//! use khodpay_bip32::Network;
81//!
82//! let mut wallet = WalletBuilder::new()
83//! .mnemonic("abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about")
84//! .password("my-secure-password")
85//! .language(Language::English)
86//! .network(Network::BitcoinMainnet)
87//! .build()?;
88//!
89//! let account = wallet.get_account(Purpose::BIP44, CoinType::Bitcoin, 0)?;
90//! # Ok::<(), khodpay_bip44::Error>(())
91//! ```
92//!
93//! ### Batch Address Generation
94//!
95//! ```rust
96//! use khodpay_bip44::{Wallet, Purpose, CoinType, Chain, Language};
97//! use khodpay_bip32::Network;
98//!
99//! let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
100//! let mut wallet = Wallet::from_english_mnemonic(mnemonic, "", Network::BitcoinMainnet)?;
101//! let account = wallet.get_account(Purpose::BIP44, CoinType::Bitcoin, 0)?;
102//!
103//! // Generate 20 receiving addresses
104//! let addresses = account.derive_address_range(Chain::External, 0, 20)?;
105//! assert_eq!(addresses.len(), 20);
106//! # Ok::<(), khodpay_bip44::Error>(())
107//! ```
108//!
109//! ### Using Path Strings
110//!
111//! ```rust
112//! use khodpay_bip44::{Bip44Path, Purpose, CoinType, Chain};
113//!
114//! // Parse a BIP-44 path
115//! let path: Bip44Path = "m/44'/0'/0'/0/0".parse()?;
116//! assert_eq!(path.purpose(), Purpose::BIP44);
117//! assert_eq!(path.coin_type(), CoinType::Bitcoin);
118//! assert_eq!(path.account(), 0);
119//! assert_eq!(path.chain(), Chain::External);
120//! assert_eq!(path.address_index(), 0);
121//!
122//! // Convert back to string
123//! assert_eq!(path.to_string(), "m/44'/0'/0'/0/0");
124//! # Ok::<(), khodpay_bip44::Error>(())
125//! ```
126//!
127//! ### SegWit and Taproot
128//!
129//! ```rust
130//! use khodpay_bip44::{Wallet, Purpose, CoinType, Language};
131//! use khodpay_bip32::Network;
132//!
133//! let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
134//! let mut wallet = Wallet::from_english_mnemonic(mnemonic, "", Network::BitcoinMainnet)?;
135//!
136//! // BIP-84: Native SegWit (bc1q...)
137//! let segwit_account = wallet.get_account(Purpose::BIP84, CoinType::Bitcoin, 0)?;
138//!
139//! // BIP-86: Taproot (bc1p...)
140//! let taproot_account = wallet.get_account(Purpose::BIP86, CoinType::Bitcoin, 0)?;
141//! # Ok::<(), khodpay_bip44::Error>(())
142//! ```
143//!
144//! ## Security Considerations
145//!
146//! - **Mnemonic Storage**: Never store mnemonics in plain text. Use secure storage.
147//! - **Password Protection**: Use strong passwords for additional security (BIP-39 passphrase).
148//! - **Key Material**: Private keys should never leave secure memory.
149//! - **Gap Limit**: Follow BIP-44 gap limit (20) for address discovery.
150//!
151//! ## Supported Cryptocurrencies
152//!
153//! This crate supports all SLIP-44 registered coin types, including:
154//!
155//! - Bitcoin (BTC) - Coin type 0
156//! - Ethereum (ETH) - Coin type 60
157//! - Litecoin (LTC) - Coin type 2
158//! - Dogecoin (DOGE) - Coin type 3
159//! - And many more via [`CoinType::Custom`]
160//!
161//! ## Optional Features
162//!
163//! - `serde`: Enable serialization support for paths and metadata
164
165#![warn(missing_docs)]
166#![warn(rustdoc::broken_intra_doc_links)]
167#![deny(unsafe_code)]
168
169mod account;
170mod builder;
171mod derived;
172mod discovery;
173mod error;
174mod iterator;
175mod path;
176mod types;
177mod wallet;
178
179pub use account::{Account, AccountMetadata};
180pub use builder::WalletBuilder;
181pub use derived::DerivedAddress;
182pub use discovery::{
183 AccountDiscovery, AccountScanResult, AccountScanner, ChainScanResult, GapLimitChecker,
184 MockBlockchain, DEFAULT_GAP_LIMIT,
185};
186pub use error::Error;
187pub use iterator::AddressIterator;
188pub use path::{Bip44Path, Bip44PathBuilder};
189pub use types::{Chain, CoinType, Purpose};
190pub use wallet::Wallet;
191
192// Re-export Language from BIP39 for convenience
193pub use khodpay_bip39::Language;
194
195/// Result type alias for BIP-44 operations.
196pub type Result<T> = std::result::Result<T, Error>;