spark_rust/wallet/

client.rs

//! # Spark Wallet SDK
//!
//! The central entry point for interacting with the Spark protocol, a non-custodial Bitcoin wallet
//! and payment solution. This module provides the main SDK structure that coordinates all Spark
//! functionality including:
//!
//! - Wallet initialization and authentication
//! - Creating and managing deposit addresses
//! - Transferring funds between wallets
//! - Lightning network payments
//! - On-chain transaction management
//! - Leaf (UTXO) management
//! - Fee estimation and handling
//!
//! The SDK is designed around a modular signer architecture that allows for both the provided
//! default implementation and custom signing solutions.

use super::leaf_manager::LeafManager;
use crate::signer::default_signer::DefaultSigner;
use crate::signer::traits::SparkSigner;
use crate::wallet::config::WalletConfig;
use std::sync::Arc;
use tokio::sync::MutexGuard;

/// Macro to wrap handler functions with a global lock
///
/// This macro takes a handler function call and wraps it with the handler lock acquisition.
/// It's useful for ensuring exclusive access to all leaves during handler operations.
///
/// # Usage
/// ```
/// // Inside an SDK method
/// with_handler_lock!(self, async {
///     // Your handler implementation here
///     self.some_internal_method().await?;
///     Ok(result)
/// }).await
/// ```
#[macro_export]
macro_rules! with_handler_lock {
    ($self:expr, $handler_impl:expr) => {{
        let _guard = $self.acquire_handler_lock().await;
        $handler_impl
    }};
}

/// The main interface for the Spark wallet SDK
///
/// `SparkSdk` is the primary point of interaction with the Spark protocol, providing
/// a complete set of wallet functionality for Bitcoin and Lightning operations.
/// It coordinates between the cryptographic signer, wallet configuration, and
/// leaf (UTXO) management components.
///
/// The SDK supports a pluggable signer architecture through its generic parameter,
/// allowing applications to use either the provided `DefaultSigner` or implement
/// their own custom signing solution (e.g., for hardware wallet integration).
///
/// Key functionality provided by the SDK includes:
///
/// - **Initialization:** Create and set up a new wallet instance
/// - **Deposits:** Generate deposit addresses and deposit trees
/// - **Transfers:** Send funds to other Spark users or Bitcoin addresses
/// - **Lightning:** Make and receive Lightning Network payments
/// - **Leaves:** Manage individual UTXOs within the wallet
/// - **Swaps:** Swap funds between different payment channels
/// - **Timelocks:** Manage timelock conditions for funds
/// - **Fees:** Estimate and manage transaction fees
///
/// # Examples
///
/// ```
/// use spark_rust::{
///     error::SparkSdkError,
///     signer::default_signer::DefaultSigner,
///     signer::traits::SparkSigner,
///     SparkNetwork, SparkSdk,
/// };
/// use std::sync::Arc;
///
/// async fn example() -> Result<(), SparkSdkError> {
///     // Initialize with a mnemonic phrase and network
///     let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
///     let network = SparkNetwork::Regtest;
///     
///     // Create the signer
///     let signer = Arc::new(DefaultSigner::from_mnemonic(mnemonic, network.clone()).await?);
///     
///     // Initialize the SDK
///     let sdk = SparkSdk::new(network, signer).await?;
///     
///     // Get wallet information
///     let address = sdk.get_spark_address()?;
///     println!("Spark address: {}", hex::encode(address.serialize()));
///     
///     // Use other SDK functionality...
///     
///     Ok(())
/// }
/// ```
///
/// # Security Considerations
///
/// The Spark SDK architecture implements security through several layers:
///
/// ## SDK Architecture Security
/// - Separation of concerns: The SDK delegates all key operations to the signer component
/// - Secure API communication with Spark operators using authenticated sessions
/// - Protocol-level validation of all operator responses
/// - Thread-safe access to shared resources
///
/// ## Signer Security (using DefaultSigner)
/// - BIP39 mnemonic-based key generation with proper entropy
/// - BIP32/BIP44 compliant hierarchical deterministic key derivation
/// - Secure storage of private keys with optional encryption
/// - Explicit methods for sensitive operations with clear security warnings
///
/// ## Spark Protocol Security
/// - Threshold signature schemes (FROST) requiring multiple parties to sign transactions
/// - Defense in depth through multiple security mechanisms
/// - Timelocked refund transactions as safety guarantees
/// - Verifiable cryptographic proofs for key operations
///
/// Note: This is an early version of the SDK, and future updates will further enhance
/// isolation and security properties.
#[derive(Clone)]
pub struct SparkSdk<S: SparkSigner + Send + Sync = DefaultSigner> {
    /// Wallet configuration including network settings and session information
    pub(crate) config: WalletConfig,

    /// Cryptographic signer that manages private keys and signing operations
    pub(crate) signer: Arc<S>,

    /// Manager for wallet leaves (UTXOs)
    pub(crate) leaf_manager: Arc<LeafManager>,

    /// Global lock for handler operations
    pub(crate) handler_lock: Arc<tokio::sync::Mutex<()>>,
}

impl<S: SparkSigner + Send + Sync + Clone + 'static> SparkSdk<S> {
    /// Acquires the global handler lock to ensure exclusive access to all leaves during a handler operation.
    ///
    /// This method returns a guard that will automatically release the lock when it's dropped.
    /// If the handler code panics or returns early, the lock will still be released.
    ///
    /// # Returns
    /// A MutexGuard that will release the lock when dropped
    ///
    /// # Usage
    /// ```
    /// async fn some_handler_method(&self) -> Result<(), SparkSdkError> {
    ///     // Acquire the lock at the beginning of the handler
    ///     let _guard = self.acquire_handler_lock().await;
    ///     
    ///     // Rest of handler implementation...
    ///     
    ///     // Lock is automatically released when _guard goes out of scope
    ///     Ok(())
    /// }
    /// ```
    pub(crate) async fn acquire_handler_lock(&self) -> MutexGuard<'_, ()> {
        self.handler_lock.lock().await
    }
}