bsv_rs/
error.rs

1//! Error types for the BSV SDK.
2
3use thiserror::Error;
4
5/// Main error type for the BSV SDK.
6#[derive(Error, Debug, Clone, PartialEq, Eq)]
7pub enum Error {
8    // ===================
9    // Primitives errors
10    // ===================
11    /// Invalid key length for cryptographic operations.
12    #[error("invalid key length: expected {expected}, got {actual}")]
13    InvalidKeyLength {
14        /// The length the operation requires, in bytes.
15        expected: usize,
16        /// The length supplied, in bytes.
17        actual: usize,
18    },
19
20    /// Invalid data length for cryptographic operations.
21    #[error("invalid data length: expected {expected}, got {actual}")]
22    InvalidDataLength {
23        /// The length the operation requires, in bytes.
24        expected: usize,
25        /// The length supplied, in bytes.
26        actual: usize,
27    },
28
29    /// Invalid hex string.
30    #[error("invalid hex string: {0}")]
31    InvalidHex(String),
32
33    /// Invalid base58 string.
34    #[error("invalid base58 string: {0}")]
35    InvalidBase58(String),
36
37    /// Invalid base64 string.
38    #[error("invalid base64 string: {0}")]
39    InvalidBase64(String),
40
41    /// Cryptographic operation failed.
42    #[error("cryptographic operation failed: {0}")]
43    CryptoError(String),
44
45    /// Invalid signature.
46    #[error("invalid signature: {0}")]
47    InvalidSignature(String),
48
49    /// Invalid public key.
50    #[error("invalid public key: {0}")]
51    InvalidPublicKey(String),
52
53    /// Invalid private key.
54    #[error("invalid private key: {0}")]
55    InvalidPrivateKey(String),
56
57    /// Point at infinity (invalid for most operations).
58    #[error("point at infinity")]
59    PointAtInfinity,
60
61    /// Decryption failed.
62    #[error("decryption failed")]
63    DecryptionFailed,
64
65    /// Invalid nonce.
66    #[error("invalid nonce: {0}")]
67    InvalidNonce(String),
68
69    /// Invalid tag (for authenticated encryption).
70    #[error("invalid authentication tag")]
71    InvalidTag,
72
73    /// Invalid UTF-8 sequence.
74    #[error("invalid UTF-8 sequence: {0}")]
75    InvalidUtf8(String),
76
77    /// Reader underflow (not enough bytes to read).
78    #[error("reader underflow: need {needed} bytes, only {available} available")]
79    ReaderUnderflow {
80        /// The bytes the read asked for.
81        needed: usize,
82        /// The bytes left in the reader.
83        available: usize,
84    },
85
86    /// A varint using more bytes than its value requires. Width includes the marker.
87    #[error("non-canonical varint: {value} encoded in {width} bytes")]
88    NonCanonicalVarInt {
89        /// The encoded width in bytes, the marker included.
90        width: u8,
91        /// The value the varint carries.
92        value: u64,
93    },
94
95    /// A node CompactSize above `MAX_COMPACT_SIZE`.
96    #[error("compact size too large: {0}")]
97    CompactSizeTooLarge(u64),
98
99    /// Invalid checksum.
100    #[error("invalid checksum")]
101    InvalidChecksum,
102
103    // ===================
104    // Script errors (Phase S1+)
105    // ===================
106    /// Script parse error.
107    #[cfg(feature = "script")]
108    #[error("script parse error: {0}")]
109    ScriptParseError(String),
110
111    /// Script execution error.
112    #[cfg(feature = "script")]
113    #[error("script execution error: {0}")]
114    ScriptExecutionError(String),
115
116    /// Invalid opcode.
117    #[cfg(feature = "script")]
118    #[error("invalid opcode: 0x{0:02x}")]
119    InvalidOpcode(u8),
120
121    /// Disabled opcode.
122    #[cfg(feature = "script")]
123    #[error("disabled opcode: 0x{0:02x}")]
124    DisabledOpcode(u8),
125
126    /// Stack underflow.
127    #[cfg(feature = "script")]
128    #[error("stack underflow")]
129    StackUnderflow,
130
131    /// Stack overflow.
132    #[cfg(feature = "script")]
133    #[error("stack overflow")]
134    StackOverflow,
135
136    /// BIP-276 encoding/decoding error.
137    #[cfg(feature = "script")]
138    #[error("BIP-276 error: {0}")]
139    Bip276Error(String),
140
141    /// Invalid address.
142    #[cfg(feature = "script")]
143    #[error("invalid address: {0}")]
144    InvalidAddress(String),
145
146    /// Invalid address length.
147    #[cfg(feature = "script")]
148    #[error("invalid address length for '{0}'")]
149    InvalidAddressLength(String),
150
151    /// Unsupported address type.
152    #[cfg(feature = "script")]
153    #[error("address not supported {0}")]
154    UnsupportedAddress(String),
155
156    // ===================
157    // Transaction errors
158    // ===================
159    /// Transaction error.
160    #[cfg(feature = "transaction")]
161    #[error("transaction error: {0}")]
162    TransactionError(String),
163
164    /// MerklePath error.
165    #[cfg(feature = "transaction")]
166    #[error("merkle path error: {0}")]
167    MerklePathError(String),
168
169    /// BEEF format error.
170    #[cfg(feature = "transaction")]
171    #[error("BEEF error: {0}")]
172    BeefError(String),
173
174    /// Fee model error.
175    #[cfg(feature = "transaction")]
176    #[error("fee model error: {0}")]
177    FeeModelError(String),
178
179    // ===================
180    // Wallet errors
181    // ===================
182    /// General wallet error.
183    #[cfg(feature = "wallet")]
184    #[error("wallet error: {0}")]
185    WalletError(String),
186
187    /// Key derivation error.
188    #[cfg(feature = "wallet")]
189    #[error("key derivation error: {0}")]
190    KeyDerivationError(String),
191
192    /// Protocol validation error.
193    #[cfg(feature = "wallet")]
194    #[error("protocol validation error: {0}")]
195    ProtocolValidationError(String),
196
197    /// Invalid counterparty.
198    #[cfg(feature = "wallet")]
199    #[error("invalid counterparty: {0}")]
200    InvalidCounterparty(String),
201
202    // ===================
203    // Messages errors
204    // ===================
205    /// Message version mismatch.
206    #[cfg(feature = "messages")]
207    #[error("message version mismatch: expected {expected}, got {actual}")]
208    MessageVersionMismatch {
209        /// The version prefix this crate reads, as hex.
210        expected: String,
211        /// The version prefix the message carries, as hex.
212        actual: String,
213    },
214
215    /// General message error.
216    #[cfg(feature = "messages")]
217    #[error("message error: {0}")]
218    MessageError(String),
219
220    /// Message recipient mismatch.
221    #[cfg(feature = "messages")]
222    #[error("message recipient mismatch: expected {expected}, got {actual}")]
223    MessageRecipientMismatch {
224        /// The recipient public key the message names, compressed, as hex.
225        expected: String,
226        /// The public key of the private key supplied to read it, compressed, as hex.
227        actual: String,
228    },
229
230    // ===================
231    // Compat errors
232    // ===================
233    /// Invalid mnemonic phrase.
234    #[cfg(feature = "compat")]
235    #[error("invalid mnemonic: {0}")]
236    InvalidMnemonic(String),
237
238    /// Invalid entropy length for mnemonic generation.
239    #[cfg(feature = "compat")]
240    #[error("invalid entropy length: expected {expected}, got {actual}")]
241    InvalidEntropyLength {
242        /// The entropy lengths accepted, in bits.
243        expected: String,
244        /// The entropy length supplied, in bits.
245        actual: usize,
246    },
247
248    /// Invalid word in mnemonic phrase.
249    #[cfg(feature = "compat")]
250    #[error("invalid word in mnemonic: {0}")]
251    InvalidMnemonicWord(String),
252
253    /// Invalid extended key.
254    #[cfg(feature = "compat")]
255    #[error("invalid extended key: {0}")]
256    InvalidExtendedKey(String),
257
258    /// Cannot derive hardened child from public key.
259    #[cfg(feature = "compat")]
260    #[error("cannot derive hardened child from public key")]
261    HardenedFromPublic,
262
263    /// Invalid derivation path.
264    #[cfg(feature = "compat")]
265    #[error("invalid derivation path: {0}")]
266    InvalidDerivationPath(String),
267
268    /// ECIES decryption failed.
269    #[cfg(feature = "compat")]
270    #[error("ECIES decryption failed: {0}")]
271    EciesDecryptionFailed(String),
272
273    /// ECIES HMAC verification failed.
274    #[cfg(feature = "compat")]
275    #[error("ECIES HMAC verification failed")]
276    EciesHmacMismatch,
277
278    // ===================
279    // Auth errors
280    // ===================
281    /// General authentication error.
282    #[cfg(feature = "auth")]
283    #[error("authentication error: {0}")]
284    AuthError(String),
285
286    /// Session not found.
287    #[cfg(feature = "auth")]
288    #[error("session not found: {0}")]
289    SessionNotFound(String),
290
291    /// Certificate validation failed.
292    #[cfg(feature = "auth")]
293    #[error("certificate validation failed: {0}")]
294    CertificateValidationError(String),
295
296    /// Transport error.
297    #[cfg(feature = "auth")]
298    #[error("transport error: {0}")]
299    TransportError(String),
300
301    // ===================
302    // Overlay errors
303    // ===================
304    /// General overlay error.
305    #[cfg(feature = "overlay")]
306    #[error("overlay error: {0}")]
307    OverlayError(String),
308
309    /// No hosts found for service.
310    #[cfg(feature = "overlay")]
311    #[error("no hosts found for service: {0}")]
312    NoHostsFound(String),
313
314    /// Broadcast to overlay failed.
315    #[cfg(feature = "overlay")]
316    #[error("overlay broadcast failed: {0}")]
317    OverlayBroadcastFailed(String),
318
319    // ===================
320    // Registry errors
321    // ===================
322    /// General registry error.
323    #[cfg(feature = "registry")]
324    #[error("registry error: {0}")]
325    RegistryError(String),
326
327    /// Definition not found in registry.
328    #[cfg(feature = "registry")]
329    #[error("definition not found: {0}")]
330    DefinitionNotFound(String),
331
332    /// Invalid definition data.
333    #[cfg(feature = "registry")]
334    #[error("invalid definition data: {0}")]
335    InvalidDefinitionData(String),
336
337    // ===================
338    // KVStore errors
339    // ===================
340    /// General kvstore error.
341    #[cfg(feature = "kvstore")]
342    #[error("kvstore error: {0}")]
343    KvStoreError(String),
344
345    /// Key not found in kvstore.
346    #[cfg(feature = "kvstore")]
347    #[error("kvstore key not found: {0}")]
348    KvStoreKeyNotFound(String),
349
350    /// Corrupted kvstore state.
351    #[cfg(feature = "kvstore")]
352    #[error("corrupted kvstore state: {0}")]
353    KvStoreCorruptedState(String),
354
355    /// Empty context (protocol_id) provided to kvstore.
356    #[cfg(feature = "kvstore")]
357    #[error("context cannot be empty")]
358    KvStoreEmptyContext,
359
360    /// Invalid key provided to kvstore (empty).
361    #[cfg(feature = "kvstore")]
362    #[error("invalid key")]
363    KvStoreInvalidKey,
364
365    /// Invalid value provided to kvstore (empty).
366    #[cfg(feature = "kvstore")]
367    #[error("invalid value")]
368    KvStoreInvalidValue,
369
370    // ===================
371    // Identity errors
372    // ===================
373    /// General identity error.
374    #[cfg(feature = "identity")]
375    #[error("identity error: {0}")]
376    IdentityError(String),
377
378    /// Identity not found.
379    #[cfg(feature = "identity")]
380    #[error("identity not found: {0}")]
381    IdentityNotFound(String),
382
383    /// Contact not found.
384    #[cfg(feature = "identity")]
385    #[error("contact not found: {0}")]
386    ContactNotFound(String),
387}
388
389/// Result type alias for BSV SDK operations.
390pub type Result<T> = std::result::Result<T, Error>;
bsv_rs/error.rs

bsv_rs/
error.rs
