Skip to main content

quai_wallet/
lib.rs

1//! BIP39/BIP32 derivation, encrypted seed backups, selection and optional native storage.
2//! Bounded watch-only discovery relies on explicitly tagged node observations.
3//! No verified chain-proof recovery or complete reorg engine is implemented.
4//!
5//! Secret-owning wrappers redact diagnostics and do not implement `Clone`,
6//! `Display`, or generic serialization. Secret exports require explicit access.
7//! Zeroization is best effort; it cannot erase caller copies or guarantee that
8//! cryptographic dependencies/compiler temporaries never retain copies.
9
10#[cfg(feature = "backup")]
11pub mod account_custody;
12pub mod allocation;
13mod backup;
14#[cfg(feature = "backup")]
15mod custody_codec;
16pub mod discovery;
17#[cfg(feature = "backup")]
18pub mod full_backup;
19mod hd;
20pub mod metadata;
21#[cfg(feature = "payments")]
22pub mod payment_allocation;
23pub mod qi_addresses;
24#[cfg(feature = "backup")]
25pub mod qi_custody;
26pub mod qi_keys;
27mod selection;
28#[cfg(feature = "backup")]
29mod state;
30/// Application-chosen identity of one durable operation, shared by the native
31/// store and both custody books.
32#[cfg(feature = "backup")]
33pub use state::{ReservationId, ReservationState};
34#[cfg(all(feature = "sqlite", not(target_arch = "wasm32")))]
35pub mod storage;
36pub use selection::{
37    AggregationPolicy, CandidateCoin, CoinSelection, SelectionError, SelectionRequest, SweepMode,
38    denominate_largest, preserves_denominations, select_aggregate, select_fewest,
39    select_fewest_converting, select_sweep, select_with_fee,
40};
41mod mnemonic;
42pub mod wordlist;
43
44pub use backup::{BackupError, BackupKdf, EncryptedSeedBackup, SeedBackup};
45
46pub use hd::{
47    AccountPublic, CoinType, DerivedAddress, ExtendedKeyMetadata, ExtendedPrivateKey,
48    ExtendedPublicKey, Grinding, HdWallet, Search, SearchResult, SearchWindow, WindowStop,
49};
50pub use mnemonic::{Language, Mnemonic, MnemonicEntropy, SecretString, Seed};
51use thiserror::Error;
52
53/// Wallet errors never echo phrases, passphrases, seeds or extended private keys.
54#[derive(Clone, Debug, PartialEq, Eq, Error)]
55#[non_exhaustive]
56pub enum WalletError {
57    /// Invalid word count, word, language or checksum.
58    #[error("invalid mnemonic")]
59    InvalidMnemonic,
60    /// Entropy must contain 128–256 bits in 32-bit increments.
61    #[error("invalid mnemonic entropy length")]
62    InvalidEntropy,
63    /// Operating-system entropy was unavailable; no fallback randomness is used.
64    #[error("secure operating-system randomness unavailable")]
65    RandomnessUnavailable,
66    /// BIP32 seed length must be 16 through 64 bytes.
67    #[error("invalid BIP32 seed length")]
68    InvalidSeed,
69    /// Invalid extended-key checksum, prefix, metadata or curve point/scalar.
70    #[error("invalid extended key")]
71    InvalidExtendedKey,
72    /// Account and child indexes must be below 2^31 before hardening.
73    #[error("index must be below 2^31")]
74    InvalidIndex,
75    /// Hardened public derivation is impossible.
76    #[error("cannot derive a hardened child from an extended public key")]
77    HardenedPublicChild,
78    /// Path must be valid and absolute derivation must begin at a master node.
79    #[error("invalid derivation path or non-master starting node")]
80    InvalidPath,
81    /// Cryptographic derivation failed or the maximum depth was reached.
82    #[error("HD key derivation failed")]
83    Derivation,
84    /// Imported account xpub metadata does not match the declared origin.
85    #[error("account xpub must have depth three and the declared hardened account index")]
86    InvalidAccountOrigin,
87    /// Exact-index derivation does not select the required ledger and a known zone.
88    #[error("derived address does not match the wallet ledger or a known zone")]
89    InvalidDerivedAddress,
90    /// A search must specify 1 through 10,000,000 attempts.
91    #[error("invalid address search limit")]
92    InvalidSearchLimit,
93    /// Search stopped before deriving the next candidate.
94    #[error("address search cancelled after {attempts} attempts")]
95    Cancelled {
96        /// Number of candidates already examined.
97        attempts: u32,
98        /// Candidate index at which a later search can resume.
99        next_index: u32,
100    },
101    /// All permitted candidates were examined without a match.
102    #[error("address search exhausted after {attempts} attempts")]
103    SearchExhausted {
104        /// Number of candidates examined.
105        attempts: u32,
106        /// Next nonhardened candidate; None means the index space ended.
107        next_index: Option<u32>,
108    },
109}