spark_rust/wallet/handlers/

init.rs

use std::sync::Arc;

use bitcoin::secp256k1::PublicKey;

use crate::{
    error::SparkSdkError,
    signer::traits::SparkSigner,
    wallet::{
        config::WalletConfig,
        internal_handlers::traits::{
            authenticate::AuthenticateInternalHandlers, leaves::LeavesInternalHandlers,
        },
        leaf_manager::LeafManager,
    },
    SparkNetwork, SparkSdk,
};

impl<S: SparkSigner + Send + Sync + Clone + 'static> SparkSdk<S> {
    /// Creates a new instance of the Spark SDK.
    ///
    /// This is the main entry point for interacting with the Spark protocol. It initializes the SDK with
    /// the provided network configuration, signer implementation, and optional data storage path.
    ///
    /// # Arguments
    ///
    /// * `network` - The Spark network to connect to (e.g. Regtest or Mainnet)
    /// * `signer` - Implementation of the SparkSigner trait wrapped in Arc for thread-safe access
    ///
    /// # Returns
    ///
    /// Returns a Result containing either:
    /// * The initialized SparkSdk instance
    /// * A SparkSdkError if initialization fails
    ///
    /// # Examples
    ///
    /// ```
    /// use spark_rust::{
    ///     error::SparkSdkError,
    ///     signer::default_signer::DefaultSigner,
    ///     signer::traits::SparkSigner,
    ///     SparkNetwork, SparkSdk,
    /// };
    ///
    /// async fn init_sdk() {
    ///     let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
    ///     let network = SparkNetwork::Regtest;
    ///     let signer = DefaultSigner::from_mnemonic(mnemonic, network.clone()).await.unwrap();
    ///     let sdk = SparkSdk::new(
    ///         network,
    ///         signer
    ///     ).await.unwrap();
    /// }
    /// ```
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all, fields(network = ?network)))]
    pub async fn new(network: SparkNetwork, signer: Arc<S>) -> Result<Self, SparkSdkError> {
        let config = WalletConfig::new(network).await?;
        let leaf_manager = Arc::new(LeafManager::new());
        let session = Arc::new(parking_lot::RwLock::new(Vec::new()));

        let sdk = Self {
            config,
            signer: signer.clone(),
            leaf_manager,
            session,
        };

        let sessions = sdk.authenticate().await?;

        {
            let mut write = sdk.session.write();
            *write = sessions;
        }

        let sdk_clone = sdk.clone();

        // refresh BTC leaves
        sdk_clone.sync_leaves().await?;

        // TODO: refresh tokens. This is only needed if the authn server will not refresh tokens per request.

        // TODO: set optional param to claim bg tasks in the background

        Ok(sdk)
    }

    /// Returns the Spark address of the wallet, which is the identity public key.
    ///
    /// The Spark address is derived from the identity public key of the wallet.
    /// This key is generated when the wallet is first created and remains constant throughout the
    /// wallet's lifetime.
    ///
    /// The Spark address serves several purposes:
    /// - Authenticates the wallet with Spark operators during API calls
    /// - Used in deposit address generation to prove ownership
    /// - Required for validating operator signatures
    /// - Helps prevent unauthorized access to wallet funds
    ///
    /// # Returns
    /// A byte slice containing the 33-byte compressed secp256k1 public key in SEC format.
    /// The first byte is either 0x02 or 0x03 (the parity), followed by the 32-byte X coordinate.
    ///
    /// # Examples
    /// ```
    /// # use spark_rust::{SparkSdk, SparkNetwork, signer::default_signer::DefaultSigner, signer::traits::SparkSigner};
    ///
    /// # async fn example() {
    /// let network = SparkNetwork::Regtest;
    /// let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
    /// let signer = DefaultSigner::from_mnemonic(mnemonic, network.clone()).await.unwrap();
    /// let sdk = SparkSdk::new(network, signer).await.unwrap();
    ///
    /// // Spark address is the identity public key of the user. This is derived using the derivation path (TODO: add docs)
    /// let spark_address = sdk.get_spark_address().unwrap();
    ///
    /// // Currently, a user's Spark address is their public key.
    /// assert_eq!(spark_address.serialize().len(), 33);
    /// # }
    /// ```
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub fn get_spark_address(&self) -> Result<PublicKey, SparkSdkError> {
        let account_index = 0;
        let network = self.config.spark_config.network.to_bitcoin_network();
        let pubkey = self
            .signer
            .get_identity_public_key(account_index, network)?;

        Ok(pubkey)
    }

    /// Returns the Bitcoin network that this wallet is connected to.
    ///
    /// The network determines which Spark operators the wallet communicates with and which Bitcoin network
    /// (mainnet or regtest) is used for transactions.
    ///
    /// # Network Types
    /// - [`SparkNetwork::Mainnet`] - Production Bitcoin mainnet environment
    /// - [`SparkNetwork::Regtest`] - Testing environment using Lightspark's regtest network
    ///
    /// The network is set when creating the wallet and cannot be changed after initialization.
    /// All transactions and addresses will be created for the configured network.
    ///
    /// # Returns
    /// Returns a [`SparkNetwork`] enum indicating whether this is a mainnet or regtest wallet.
    ///
    /// # Examples
    /// ```
    /// # use spark_rust::{SparkSdk, SparkNetwork, signer::default_signer::DefaultSigner, signer::traits::SparkSigner};
    /// # async fn example() {
    /// let mnemonic = "abandon ability able about above absent absorb abstract absurd abuse access accident";
    /// let network = SparkNetwork::Regtest;
    ///
    /// // Create a DefaultSigner that implements SparkSigner
    /// let signer = DefaultSigner::from_mnemonic(mnemonic, network.clone()).await.unwrap();
    /// let sdk = SparkSdk::new(network, signer).await.unwrap();
    ///
    /// assert_eq!(sdk.get_network(), SparkNetwork::Regtest);
    ///
    /// # }
    /// ```
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub fn get_network(&self) -> SparkNetwork {
        self.config.spark_config.network
    }
}