spark_rust/

error.rs

//! # Error handling for the Spark Wallet SDK
//!
//! This module defines the error types used throughout the Spark Wallet SDK.
//! The error system uses a hierarchical structure, with the top-level `SparkSdkError`
//! enum wrapping various subcategory errors.
//!
//! ## Error Structure
//!
//! The error structure follows a domain-driven design:
//!
//! ```text
//! SparkSdkError
//! ├── NetworkError - Network communication and RPC issues
//! ├── WalletError - Wallet operations and leaf management
//! ├── CryptoError - Cryptographic and signing operations
//! ├── ValidationError - Input validation and verification
//! ├── TransactionError - Bitcoin transaction handling
//! ├── IoError - Input/output and serialization
//! ├── InternalError - SDK initialization and internal processing
//! └── General - General errors with a string message
//! ```
//!
//! ## Error Handling
//!
//! Most functions in the SDK return `Result<T, SparkSdkError>`, allowing you to handle
//! errors with standard Rust error handling patterns:
//!
//! ```rust
//! use spark_rust::SparkSdk;
//! use spark_rust::SparkNetwork;
//! use spark_rust::error::SparkSdkError;
//! use spark_rust::signer::default_signer::DefaultSigner;
//!
//! async fn example() -> Result<(), SparkSdkError> {
//!     let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
//!     let signer = DefaultSigner::from_mnemonic(mnemonic, SparkNetwork::Regtest).await?;
//!     let sdk = SparkSdk::new(SparkNetwork::Regtest, signer).await?;
//!     
//!     // When you need to handle specific error categories
//!     match sdk.generate_deposit_address().await {
//!         Ok(address) => println!("Deposit address: {}", address.deposit_address),
//!         Err(SparkSdkError::Network(e)) => println!("Network error: {}", e),
//!         Err(SparkSdkError::Validation(e)) => println!("Validation error: {}", e),
//!         Err(e) => println!("Other error: {}", e),
//!     }
//!     
//!     Ok(())
//! }
//! ```
//!
//! ## Error Conversion
//!
//! The error system implements `From` traits for common error types, allowing
//! automatic conversion using the `?` operator:
//!
//! - `String` and `&str` convert to `SparkSdkError::General`
//! - `tonic::transport::Error` converts to `SparkSdkError::Network`
//! - `secp256k1::Error` converts to `SparkSdkError::Crypto`
//!
//! This makes error propagation and handling more ergonomic throughout the SDK.

use bitcoin::secp256k1;
use lightning_invoice::ParseOrSemanticError;
use std::io;
use thiserror::Error;
use tonic::codegen::http::uri::InvalidUri;

// Re-export all errors from subcategories defined below
pub use self::crypto::CryptoError;
pub use self::internal::InternalError;
pub use self::io_error::IoError;
pub use self::network::NetworkError;
pub use self::transaction::TransactionError;
pub use self::validation::ValidationError;
pub use self::wallet::WalletError;

/// Main error type for the Spark Wallet SDK.
///
/// This enum wraps all subcategory errors and provides a uniform error
/// interface for SDK functions. Most SDK methods return `Result<T, SparkSdkError>`.
///
/// When handling errors, you can either match on the specific error type:
///
/// ```rust
/// # use spark_rust::error::SparkSdkError;
/// # fn example(error: SparkSdkError) {
/// match error {
///     SparkSdkError::Network(network_error) => {
///         // Handle network-specific errors
///         println!("Network error: {}", network_error);
///     },
///     SparkSdkError::Wallet(wallet_error) => {
///         // Handle wallet-specific errors
///         println!("Wallet error: {}", wallet_error);
///     },
///     // Other error categories...
///     _ => println!("Other error: {}", error),
/// }
/// # }
/// ```
///
/// Or simply use the error's `Display` implementation for general handling:
///
/// ```rust
/// # use spark_rust::error::SparkSdkError;
/// # fn example(error: SparkSdkError) {
/// println!("Error occurred: {}", error);
/// # }
/// ```
#[derive(Debug, Error)]
pub enum SparkSdkError {
    /// Network communication errors, including RPC calls and HTTP requests.
    #[error(transparent)]
    Network(#[from] NetworkError),

    /// Wallet operation errors, including leaf management and funds handling.
    #[error(transparent)]
    Wallet(#[from] WalletError),

    /// Cryptographic operation errors, including signing and key management.
    #[error(transparent)]
    Crypto(#[from] CryptoError),

    /// Input validation errors, parameter checking, and verification issues.
    #[error(transparent)]
    Validation(#[from] ValidationError),

    /// Bitcoin transaction errors, including creation and processing issues.
    #[error(transparent)]
    Transaction(#[from] TransactionError),

    /// Input/output errors, including serialization and file operations.
    #[error(transparent)]
    Io(#[from] IoError),

    /// SDK internal errors, typically for initialization or processing problems.
    #[error(transparent)]
    Internal(#[from] InternalError),

    /// General errors with a string message for cases that don't fit other categories.
    #[error("General error: {0}")]
    General(String),
}

/// Network-related errors for RPC, HTTP, and other communication issues.
pub mod network {
    use super::*;

    /// Errors related to network communication, including RPC calls and HTTP requests.
    #[derive(Debug, Error)]
    pub enum NetworkError {
        /// gRPC transport layer errors.
        #[error("Transport error: {0}")]
        Transport(#[from] tonic::transport::Error),

        /// HTTP client errors from reqwest.
        #[error("HTTP error: {0}")]
        Http(#[from] reqwest::Error),

        /// gRPC status errors.
        #[error("Status error: {0}")]
        Status(#[from] tonic::Status),

        /// Invalid URI format errors.
        #[error("Invalid URI: {0}")]
        InvalidUri(#[from] InvalidUri),

        /// Invalid URL format with optional details.
        #[error("Invalid URL: {url}")]
        InvalidUrl {
            url: String,
            details: Option<String>,
        },

        /// RPC connection failures with endpoint information.
        #[error("RPC connection error with endpoint: {uri}")]
        RpcConnection {
            uri: String,
            details: Option<String>,
        },

        /// Bitcoin RPC specific errors.
        #[error("Bitcoin RPC error: {0}")]
        BitcoinRpc(String),

        /// Invalid GraphQL operation format.
        #[error("Invalid GraphQL operation: {0}")]
        InvalidGraphQLOperation(String),

        /// GraphQL query errors.
        #[error("GraphQL error with query: {0}")]
        GraphQL(String),

        /// GraphQL request failures with status code.
        #[error("GraphQL request failed: {status_code}")]
        GraphQLRequestFailed { status_code: u16 },

        /// Faucet request failures with status code.
        #[error("Faucet request failed with status: {status_code}")]
        FaucetRequestFailed { status_code: u16 },

        /// Invalid responses from the server that can't be parsed.
        #[error("Invalid response from server")]
        InvalidResponse,
    }
}

/// Wallet-related errors for leaf management and funds handling.
pub mod wallet {
    use super::*;

    /// Errors related to wallet operations, leaf management, and funds handling.
    #[derive(Debug, Error)]
    pub enum WalletError {
        /// No leaves (UTXOs) found in the wallet.
        #[error("No leaves found for wallet")]
        NoLeavesFound,

        /// No leaf with the exact amount requested.
        #[error("No leaf with exact amount")]
        NoLeafWithExactAmount,

        /// Insufficient funds during leaf selection.
        #[error("Leaf selection failed: insufficient funds")]
        LeafSelectionInsufficientFunds,

        /// No suitable leaves available for the requested operation.
        #[error("Leaf selection failed: no suitable leaves available")]
        LeafSelectionNoSuitableLeaves,

        /// Leaf not found with the specified ID.
        #[error("Leaf not found with id: {0}")]
        LeafNotFound(String),

        /// Leaf was used for an operation but not found afterward.
        #[error("Leaf is used for operation but not found after. Leaf ID: {leaf_id}")]
        LeafNotFoundAfterOperation { leaf_id: String },

        /// Leaf is not of Bitcoin type.
        #[error("Leaf is not Bitcoin type: {leaf_id}")]
        LeafIsNotBitcoin { leaf_id: String },

        /// Leaf already exists in the wallet.
        #[error("Leaf already exists in wallet: {leaf_id}")]
        LeafAlreadyExistsInWallet { leaf_id: String },

        /// Leaf is not available for use (e.g., locked or in use).
        #[error("Leaf not available for use: {leaf_id}")]
        LeafNotAvailableForUse { leaf_id: String },

        /// Leaf is not using the expected lock.
        #[error("Leaf not using expected lock. Expected: {expected}, Found: {actual}")]
        LeafNotUsingExpectedLock { expected: String, actual: String },

        /// Leaf not found in the wallet.
        #[error("Leaf not found in wallet: {leaf_id}")]
        LeafNotFoundInWallet { leaf_id: String },

        /// Invalid account specified.
        #[error("Invalid account: {account_id}")]
        InvalidAccount { account_id: String },

        /// Cooperative exit failed.
        #[error("Cooperative exit failed: {reason}")]
        CooperativeExit { reason: String },

        /// Leaf has no parent.
        #[error("Leaf has no parent: {leaf_id}")]
        LeafHasNoParent { leaf_id: String },

        /// Leaf parent not found.
        #[error("Leaf parent not found: {leaf_id}")]
        LeafParentNotFound { leaf_id: String },

        /// Post refresh node signature length mismatch.
        #[error("Post refresh node signature length mismatch")]
        PostRefreshNodeSignatureLengthMismatch,
    }
}

/// Cryptographic operation errors for signing and key management.
pub mod crypto {
    use super::*;

    /// Errors related to cryptographic operations, including signing and key management.
    #[derive(Debug, Error)]
    pub enum CryptoError {
        /// Secp256k1 cryptographic errors.
        #[error("Signature error: {0}")]
        Secp256k1(#[from] secp256k1::Error),

        /// FROST threshold signing failures.
        #[error("FROST signing failed with job id: {job_id}")]
        FrostSigning { job_id: String },

        /// FROST signature aggregation failures.
        #[error("FROST aggregation failed")]
        FrostAggregation,

        /// Invalid hash value.
        #[error("Invalid hash: {hash}")]
        InvalidHash { hash: String },

        /// Decryption failures.
        #[error("Decryption failed")]
        Decryption,

        /// Secret key not found for a public key.
        #[error("Secret key not found for public key: {public_key}")]
        SecretKeyNotFound { public_key: String },

        /// Missing keyshare information for threshold signing.
        #[error("Missing keyshare information")]
        MissingKeyshareInfo,

        /// FROST signature not found with the specified job ID.
        #[error("Could not find FROST signature with job id: {job_id}")]
        FrostSignatureNotFound { job_id: String },

        /// Invalid key type for the operation.
        #[error("Invalid key type: {key_type}")]
        InvalidKeyType { key_type: String },

        /// Invalid seed for key derivation.
        #[error("Invalid seed")]
        InvalidSeed,

        /// Child key derivation failures.
        #[error("Child key derivation failed with path: {derivation_path}")]
        ChildKeyDerivationError { derivation_path: String },

        /// Missing root node signature shares.
        #[error("Missing root node signature shares")]
        MissingRootNodeSignatureShares,

        /// Invalid cryptographic input for operations.
        #[error("Invalid crypto input: {field}")]
        InvalidInput { field: String },
    }
}

/// Validation errors for input checking and verification.
pub mod validation {
    use super::*;

    /// Errors related to input validation, parameter checking, and verification.
    #[derive(Debug, Error)]
    pub enum ValidationError {
        /// Invalid configuration parameter.
        #[error("Invalid configuration: {parameter}")]
        Config { parameter: String },

        /// Invalid input field value.
        #[error("Invalid input: {field}")]
        InvalidInput { field: String },

        /// Invalid function argument.
        #[error("Invalid argument: {argument}")]
        InvalidArgument { argument: String },

        /// Invalid Bitcoin address format.
        #[error("Invalid address: {address}")]
        InvalidAddress { address: String },

        /// Deposit address validation failures.
        #[error("Deposit address validation failed: {address}")]
        DepositAddressValidationFailed { address: String },

        /// Deposit transaction not found in the Bitcoin network.
        #[error("Deposit transaction not found in network: {txid}")]
        DepositTransactionNotFoundInNetwork { txid: String },

        /// Invalid keyshare configuration.
        #[error("Invalid keyshare config with id: {config_id}")]
        InvalidKeyshareConfig { config_id: String },

        /// Invalid sequence number.
        #[error("Invalid sequence number: {sequence}")]
        InvalidSequence { sequence: u64 },

        /// Invalid UUID format.
        #[error("Invalid UUID: {0}")]
        InvalidUuid(#[from] uuid::Error),

        /// Invalid BOLT11 lightning invoice format.
        #[error("Invalid Bolt11 invoice: {0}")]
        InvalidBolt11Invoice(String),

        /// Transfer claim did not update balance (integration tests only).
        #[cfg(feature = "integration-tests")]
        #[error("Transfer claim did not update balance")]
        TransferClaimDidNotUpdateBalance,
    }
}

/// Transaction errors for Bitcoin transaction handling.
pub mod transaction {
    use super::*;

    /// Errors related to Bitcoin transaction creation, signing, and processing.
    #[derive(Debug, Error)]
    pub enum TransactionError {
        /// Transfer operation failures.
        #[error("Transfer failed: {reason}")]
        Transfer { reason: String },

        /// Invalid Bitcoin transaction format.
        #[error("Invalid bitcoin transaction: {0}")]
        InvalidBitcoinTransaction(String),

        /// Invalid deposit transaction format.
        #[error("Invalid deposit transaction: {0}")]
        InvalidDepositTx(String),
    }
}

/// IO errors for serialization and file operations.
pub mod io_error {

    use super::*;

    /// Errors related to input/output, serialization, and file operations.
    #[derive(Debug, Error)]
    pub enum IoError {
        /// Standard IO errors.
        #[error("IO error: {0}")]
        Io(#[from] io::Error),

        /// JSON serialization/deserialization errors.
        #[error("JSON serialization error: {0}")]
        SerdeJson(#[from] serde_json::Error),

        /// Hex decoding errors.
        #[error("Hex decoding error: {0}")]
        Decoding(#[from] hex::FromHexError),

        /// BOLT11 invoice decoding errors.
        #[error("Bolt11 invoice decoding error: {0}")]
        Bolt11InvoiceDecoding(String),
    }
}

/// Internal errors for SDK initialization and processing.
pub mod internal {
    use super::*;

    /// Errors related to SDK initialization and internal processing.
    #[derive(Debug, Error)]
    pub enum InternalError {
        /// Initialization failures for SDK components.
        #[error("Initialization failed: {component}")]
        Initialization { component: String },

        /// Tree creation failures.
        #[error("Tree creation failed: {reason}")]
        TreeCreation { reason: String },

        /// Test database query errors (for testing only).
        #[error("Test database query error: {query}")]
        TestDatabaseQuery { query: String },

        /// Async task failures.
        #[error("Async task failed: {task}")]
        AsyncTask { task: String },
    }
}

// Implement From traits for common conversions
impl From<String> for SparkSdkError {
    /// Converts a String to a SparkSdkError::General.
    ///
    /// This allows passing a string directly as an error:
    /// ```rust
    /// # use spark_rust::error::SparkSdkError;
    /// # fn example() -> Result<(), SparkSdkError> {
    /// if something_is_wrong() {
    ///     return Err("Something went wrong".to_string().into());
    /// }
    /// # Ok(())
    /// # }
    /// # fn something_is_wrong() -> bool { false }
    /// ```
    fn from(s: String) -> Self {
        Self::General(s)
    }
}

impl From<&str> for SparkSdkError {
    /// Converts a string slice to a SparkSdkError::General.
    ///
    /// This allows passing a string literal directly as an error:
    /// ```rust
    /// # use spark_rust::error::SparkSdkError;
    /// # fn example() -> Result<(), SparkSdkError> {
    /// if something_is_wrong() {
    ///     return Err("Something went wrong".into());
    /// }
    /// # Ok(())
    /// # }
    /// # fn something_is_wrong() -> bool { false }
    /// ```
    fn from(s: &str) -> Self {
        Self::General(s.to_string())
    }
}

// Add direct conversion from tonic transport errors
impl From<tonic::transport::Error> for SparkSdkError {
    /// Converts a tonic transport error to a SparkSdkError::Network.
    fn from(err: tonic::transport::Error) -> Self {
        Self::Network(NetworkError::Transport(err))
    }
}

// Add direct conversion from secp256k1 errors
impl From<secp256k1::Error> for SparkSdkError {
    /// Converts a secp256k1 error to a SparkSdkError::Crypto.
    fn from(err: secp256k1::Error) -> Self {
        Self::Crypto(CryptoError::Secp256k1(err))
    }
}

// Add manual conversion from ParseOrSemanticError
impl From<ParseOrSemanticError> for IoError {
    /// Converts a BOLT11 invoice parsing error to an IoError.
    fn from(err: ParseOrSemanticError) -> Self {
        Self::Bolt11InvoiceDecoding(err.to_string())
    }
}