spark_rust/

lib.rs

//! # Spark Wallet SDK
//!
//! A Rust implementation of the Spark protocol wallet, providing secure Bitcoin and Lightning
//! Network operations through the Spark Service Provider (SSP).
//!
//! This crate forms a complete wallet with all necessary Spark utilities, built on secure
//! cryptographic primitives from the [spark-cryptography](https://github.com/polarityorg/spark-rs/tree/main/crates/spark-cryptography) crate.
//!
//! ## Overview
//!
//! Spark is a protocol that allows secure, non-custodial Bitcoin and Lightning Network operations,
//! with all critical cryptographic operations performed client-side while leveraging Spark Service Providers
//! for efficient network operations. This implementation provides:
//!
//! - Complete Bitcoin wallet functionality
//! - Lightning Network payments (send and receive)
//! - Funds transfers between Spark users
//! - Deposit and withdrawal capabilities
//! - Comprehensive key management and signing utilities
//!
//! ## Architecture
//!
//! The Spark Wallet SDK comprises five main components:
//!
//! - **config**: Configuration settings for the Spark wallet
//! - **handlers**: User-facing APIs for wallet operations
//! - **internal_handlers**: Service handlers for signing processes and RPC communications
//! - **rpc**: Client for establishing secure connections to Spark nodes
//! - **signer**: Key management, storage, and signing capabilities
//!
//! ## Quick Start
//!
//! ```rust
//! use spark_rust::SparkSdk;
//! use spark_rust::SparkNetwork;
//! use spark_rust::signer::default_signer::DefaultSigner;
//! use std::time::Duration;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Initialize the default signer with a mnemonic phrase
//!     let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
//!     let network = SparkNetwork::Regtest;
//!     let default_signer = DefaultSigner::from_mnemonic(mnemonic, network).await?;
//!     
//!     // Create a new SDK instance
//!     let sdk = SparkSdk::new(network, default_signer).await?;
//!     
//!     // Generate a deposit address
//!     let deposit_address = sdk.generate_deposit_address().await?;
//!     println!("Deposit address: {}", deposit_address.deposit_address);
//!     
//!     // Query pending transfers
//!     let pending = sdk.query_pending_transfers().await?;
//!     println!("You have {} pending transfers", pending.len());
//!     
//!     // Claim all pending transfers
//!     sdk.claim_transfers().await?;
//!     
//!     // Get your wallet balance
//!     let balance = sdk.get_bitcoin_balance();
//!     println!("Your balance is {} satoshis", balance);
//!     
//!     Ok(())
//! }
//! ```
//!
//! ## Security Model
//!
//! Spark operates with a security model that ensures users always maintain control of their funds:
//!
//! - All critical keys are managed client-side
//! - Threshold signing with FROST ensures security with multiple participants
//! - Transactions require both user and Spark operator signatures
//! - The user always initiates the signing process
//!
//! ## Fee Structure
//!
//! Unlike traditional Bitcoin wallets, Spark uses a service fee model where:
//!
//! - Fees are charged by the Spark Service Provider (SSP) for operations they perform
//! - You don't directly pay Bitcoin mining fees (these are handled by the SSP)
//! - Fee estimation methods help you determine costs before performing operations
//!
//! Common fee operations include:
//! - Lightning payments (sending and receiving)
//! - Leaves swaps (optimizing wallet structure)
//! - Cooperative exits (withdrawing to on-chain Bitcoin)
//!
//! ## Custom Signers
//!
//! While the SDK provides a default in-memory signer implementation, advanced users can
//! implement their own signers for specialized use cases by implementing the `SparkSigner`
//! trait and its associated sub-traits.
//!
//! ```rust
//! use spark_rust::signer::traits::SparkSigner;
//! use spark_rust::SparkNetwork;
//!
//! // Example of using a custom signer (implementation details omitted)
//! #[tokio::main]
//! async fn main() {
//!     // my_custom_signer implements the SparkSigner trait
//!     let my_custom_signer = create_custom_signer().await.unwrap();
//!     let sdk = SparkSdk::new(SparkNetwork::Regtest, my_custom_signer).await.unwrap();
//!     // ...
//! }
//! # async fn create_custom_signer() -> Result<impl SparkSigner, Box<dyn std::error::Error>> { todo!() }
//! ```

use core::fmt;
use std::str::FromStr;
pub(crate) mod constants;
pub mod error;
pub(crate) mod wallet;

pub mod signer;

// pub use wallet::utils;
pub use wallet::handlers::cooperative_exit::{CompleteCoopExitInput, RequestCoopExitInput};
pub use wallet::SparkSdk;

pub(crate) mod common_types;

#[cfg(any(test, feature = "integration-tests"))]
pub mod spark_test_utils;

pub mod rpc;

/// Spark Network. This is the network of the Spark Operators that the user chooses to connect to.
///
/// - `Mainnet` is the Bitcoin network, and all operations involve real money.
/// - `Regtest` is Lightspark's Regtest network for testing purposes.
#[derive(Debug, Copy, PartialEq, Eq, PartialOrd, Ord, Clone, Hash)]
#[non_exhaustive]
pub enum SparkNetwork {
    /// Mainnet Bitcoin network. Use this for real transactions with actual value.
    Mainnet,

    /// Lightspark's Regtest network for testing and development.
    /// No real value is transferred when using this network.
    Regtest,
}

impl SparkNetwork {
    /// Converts a Spark network to its corresponding Bitcoin network.
    ///
    /// # Returns
    /// The equivalent Bitcoin network type from the `bitcoin` crate:
    /// - `SparkNetwork::Mainnet` returns `bitcoin::Network::Bitcoin`
    /// - `SparkNetwork::Regtest` returns `bitcoin::Network::Regtest`
    pub fn to_bitcoin_network(&self) -> ::bitcoin::Network {
        match self {
            SparkNetwork::Mainnet => ::bitcoin::Network::Bitcoin,
            SparkNetwork::Regtest => ::bitcoin::Network::Regtest,
        }
    }

    /// Marshals the network type to its protocol buffer representation. For most use cases, you don't need to use this method.
    ///
    /// # Returns
    /// An integer representing the network in the protocol buffer format.
    pub fn marshal_proto(&self) -> i32 {
        match self {
            SparkNetwork::Mainnet => spark_protos::spark::Network::Mainnet as i32,
            SparkNetwork::Regtest => spark_protos::spark::Network::Regtest as i32,
        }
    }
}

impl FromStr for SparkNetwork {
    type Err = String;

    /// Creates a `SparkNetwork` from a string representation.
    ///
    /// The string comparison is case-insensitive, so both "mainnet" and "Mainnet"
    /// will return `SparkNetwork::Mainnet`.
    ///
    /// # Arguments
    /// * `s` - A string slice representing the network ("mainnet" or "regtest")
    ///
    /// # Returns
    /// * `Ok(SparkNetwork)` if the string matches a known network
    /// * `Err(String)` with an error message if the string does not match
    ///
    /// # Examples
    /// ```
    /// use std::str::FromStr;
    /// use spark_rust::SparkNetwork;
    ///
    /// let mainnet = SparkNetwork::from_str("mainnet").unwrap();
    /// assert_eq!(mainnet, SparkNetwork::Mainnet);
    ///
    /// let regtest = SparkNetwork::from_str("Regtest").unwrap();
    /// assert_eq!(regtest, SparkNetwork::Regtest);
    ///
    /// let err = SparkNetwork::from_str("testnet");
    /// assert!(err.is_err());
    /// ```
    fn from_str(s: &str) -> Result<Self, String> {
        match s.to_lowercase().as_str() {
            "mainnet" => Ok(SparkNetwork::Mainnet),
            "regtest" => Ok(SparkNetwork::Regtest),
            _ => Err(format!("Invalid network: {}", s)),
        }
    }
}

impl fmt::Display for SparkNetwork {
    /// Formats the network as a lowercase string.
    ///
    /// # Returns
    /// - `"mainnet"` for `SparkNetwork::Mainnet`
    /// - `"regtest"` for `SparkNetwork::Regtest`
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SparkNetwork::Mainnet => write!(f, "mainnet"),
            SparkNetwork::Regtest => write!(f, "regtest"),
        }
    }
}

#[cfg(test)]
mod tests {
    use std::str::FromStr as _;

    use crate::SparkNetwork;

    #[test]
    fn test_spark_network_display() {
        let network = SparkNetwork::Mainnet;
        assert_eq!(network.to_string(), "mainnet");

        let network = SparkNetwork::Regtest;
        assert_eq!(network.to_string(), "regtest");
    }

    #[test]
    fn test_spark_network_from_str() {
        let network = SparkNetwork::from_str("mainnet").unwrap();
        assert_eq!(network, SparkNetwork::Mainnet);
        let network = SparkNetwork::from_str("Mainnet").unwrap();
        assert_eq!(network, SparkNetwork::Mainnet);

        let network = SparkNetwork::from_str("regtest").unwrap();
        assert_eq!(network, SparkNetwork::Regtest);
        let network = SparkNetwork::from_str("Regtest").unwrap();
        assert_eq!(network, SparkNetwork::Regtest);

        let network = SparkNetwork::from_str("testnet");
        assert!(network.is_err());
    }
}