spark_rust/wallet/handlers/

deposit.rs

use std::collections::HashMap;

use crate::with_handler_lock;
use bitcoin::secp256k1::PublicKey;
use spark_protos::spark::{
    DepositAddressQueryResult, QueryUnusedDepositAddressesRequest, TreeNode,
};

use crate::{
    error::{NetworkError, SparkSdkError, ValidationError},
    signer::traits::SparkSigner,
    wallet::{
        internal_handlers::{
            implementations::deposit::Address,
            traits::{deposit::DepositInternalHandlers, mempool::MempoolInternalHandlers},
        },
        utils::bitcoin::serialize_bitcoin_transaction,
    },
    SparkSdk,
};

/// The response from the [`SparkSdk::generate_deposit_address`] method.
pub struct GenerateDepositAddressSdkResponse {
    /// The deposit address, as [``bitcoin::Address``]. Deposit addresses are P2TR addresses.
    pub deposit_address: bitcoin::Address,

    /// The signing public key for this deposit address, as [``bitcoin::secp256k1::PublicKey``].
    pub signing_public_key: PublicKey,

    /// The verifying public key as [``bitcoin::secp256k1::PublicKey``]. *Note:* this is an interpolated key used to verify that threshold signatures between the user and the Spark Operators are valid. This should *not* by used for signing.
    pub verifying_public_key: PublicKey,
}

impl<S: SparkSigner + Send + Sync + Clone + 'static> SparkSdk<S> {
    /// Generates a new deposit address for receiving funds into the Spark wallet.
    ///
    /// This function handles the generation of a new deposit address by:
    /// 1. Creating a new signing keypair for the deposit address
    /// 2. Requesting a deposit address from the Spark network
    /// 3. Validating the returned address and proof of possession
    ///
    /// # Returns
    ///
    /// * `Ok(GenerateDepositAddressSdkResponse)` - Contains the validated deposit address and signing public key
    /// * `Err(SparkSdkError)` - If there was an error during address generation
    ///
    /// # Errors
    ///
    /// Returns [`SparkSdkError`] if:
    /// - Failed to generate new signing keypair
    /// - Network errors when communicating with Spark operators
    /// - Address validation fails (e.g. invalid proof of possession)
    ///
    /// # Example
    ///
    /// ```
    /// # use spark_rust::SparkSdk;
    /// # async fn example(mut sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
    /// let deposit_address = sdk.generate_deposit_address().await?;
    /// println!("New deposit address: {}", deposit_address.deposit_address);
    /// # Ok(())
    /// # }
    /// ```
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub async fn generate_deposit_address(
        &self,
    ) -> Result<GenerateDepositAddressSdkResponse, SparkSdkError> {
        with_handler_lock!(self, async {
            let identity_public_key = self.get_spark_address()?;

            let signing_public_key = self
                .signer
                .get_deposit_signing_key(self.config.spark_config.network.to_bitcoin_network())?;

            // You can do this:
            let request_data = spark_protos::spark::GenerateDepositAddressRequest {
                signing_public_key: signing_public_key.serialize().to_vec(),
                identity_public_key: identity_public_key.serialize().to_vec(),
                network: self.config.spark_config.network.marshal_proto(),
            };

            let response = self
                .config
                .spark_config
                .call_with_retry(
                    request_data,
                    |mut client, req| {
                        Box::pin(async move { client.generate_deposit_address(req).await })
                    },
                    None,
                )
                .await?;

            let address = Address::try_from_address(
                response
                    .deposit_address
                    .ok_or(SparkSdkError::from(NetworkError::InvalidResponse))?,
                self.config.spark_config.network,
            )?;

            self.validate_deposit_address(&address, &signing_public_key)
                .await?;

            Ok(GenerateDepositAddressSdkResponse {
                deposit_address: address.address,
                signing_public_key,
                verifying_public_key: address.verifying_key,
            })
        })
        .await
    }

    /// Claims a pending deposit by txid
    /// 1. Querying if the txid is a pending deposit
    /// 2. Checking the mempool for transaction
    /// 3. Finalizing the deposit by creating tree nodes
    ///
    /// # Errors
    ///
    /// Returns [`SparkSdkError`] if:
    /// - Failed to connect to Spark service
    /// - Failed to query mempool
    /// - Failed to finalize deposits
    ///
    /// # Example
    ///
    /// ```
    /// # 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;
    ///     let signer = DefaultSigner::from_mnemonic(mnemonic, network.clone()).await.unwrap();
    ///     let sdk = SparkSdk::new(network, signer).await.unwrap();
    ///
    ///     let hardcoded_txid = "edb5575e6ee96fcf175c9114e0b0d86d99d4642956edcd02e6ec7b6899e90b41";
    ///     sdk.claim_deposit(hardcoded_txid.to_string()).await.unwrap();
    /// }
    /// ```
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub async fn claim_deposit(&self, txid: String) -> Result<Vec<TreeNode>, SparkSdkError> {
        with_handler_lock!(self, async {
            // query the transaction in the mempool
            let deposit_tx = self.query_mempool_transaction_by_txid(txid).await?;

            // query unused deposit addresses from Spark
            let time_start = std::time::Instant::now();
            let identity_public_key = self.get_spark_address()?;

            let request_data = QueryUnusedDepositAddressesRequest {
                identity_public_key: identity_public_key.serialize().to_vec(),
            };

            let response = self
                .config
                .spark_config
                .call_with_retry(
                    request_data,
                    |mut client, req| {
                        Box::pin(async move { client.query_unused_deposit_addresses(req).await })
                    },
                    None,
                )
                .await?;

            let duration = time_start.elapsed();
            #[cfg(feature = "telemetry")]
            tracing::debug!(duration = ?duration, "query_unused_deposit_addresses");

            let deposit_addresses = response.deposit_addresses;
            // create a hashmap from an iterator that maps the returned Spark deposit addresses to the user's address
            let unused_deposit_addresses: HashMap<String, DepositAddressQueryResult> =
                deposit_addresses
                    .iter()
                    .map(|deposit_address| {
                        (
                            deposit_address.deposit_address.clone(),
                            deposit_address.clone(),
                        )
                    })
                    .collect();

            let mut vout: u32 = 0;
            let mut found_deposit_data: Option<DepositAddressQueryResult> = None;

            for (i, tx_output) in deposit_tx.output.iter().enumerate() {
                let parsed_script = tx_output.script_pubkey.clone();
                let script_address = bitcoin::Address::from_script(
                    &parsed_script,
                    self.config.spark_config.network.to_bitcoin_network(),
                )
                .ok()
                .map(|addr| addr.to_string())
                .ok_or_else(|| {
                    SparkSdkError::from(ValidationError::InvalidAddress {
                        address: "Invalid address".to_string(),
                    })
                })?;

                if unused_deposit_addresses.contains_key(&script_address) {
                    // Found a matching deposit address
                    vout = i as u32;
                    found_deposit_data = Some(
                        unused_deposit_addresses
                            .get(&script_address)
                            .unwrap()
                            .clone(),
                    );

                    #[cfg(feature = "telemetry")]
                    tracing::debug!(address = script_address, "Found matching deposit address");

                    break;
                }
            }

            // If no matching deposit address is found, return an error
            let deposit_data = found_deposit_data.ok_or_else(|| {
                SparkSdkError::from(ValidationError::InvalidAddress {
                    address: "Deposit address not found".to_string(),
                })
            })?;

            let nodes = self
                .finalize_deposit_internal(
                    deposit_data.user_signing_public_key.clone(),
                    deposit_data.verifying_public_key.clone(),
                    deposit_tx.clone(),
                    vout,
                )
                .await?;

            self.claim_transfers_internal().await?;

            Ok(nodes)
        })
        .await
    }

    /// Finalizes a deposit by creating a tree node and transferring it to self
    ///
    /// # Arguments
    ///
    /// * `signing_pubkey` - The public key used for signing
    /// * `deposit_tx` - The Bitcoin transaction containing the deposit
    /// * `vout` - The output index in the transaction
    ///
    /// # Errors
    ///
    /// Returns [`SparkSdkError`] if:
    /// - Failed to create tree node
    /// - Failed to transfer deposits
    ///
    /// # Returns
    ///
    /// Returns an empty vector of `TreeNode`s on success
    pub async fn finalize_deposit(
        &self,
        signing_pubkey: Vec<u8>,
        verifying_pubkey: Vec<u8>,
        deposit_tx: bitcoin::Transaction,
        vout: u32,
    ) -> Result<Vec<TreeNode>, SparkSdkError> {
        with_handler_lock!(self, async {
            self.finalize_deposit_internal(signing_pubkey, verifying_pubkey, deposit_tx, vout)
                .await
        })
        .await
    }

    async fn finalize_deposit_internal(
        &self,
        signing_pubkey: Vec<u8>,
        verifying_pubkey: Vec<u8>,
        deposit_tx: bitcoin::Transaction,
        vout: u32,
    ) -> Result<Vec<TreeNode>, SparkSdkError> {
        let time_start = std::time::Instant::now();
        let created_root = self
            .create_tree_root(
                signing_pubkey,
                verifying_pubkey,
                serialize_bitcoin_transaction(&deposit_tx)?,
                vout,
            )
            .await?;
        let duration = time_start.elapsed();

        #[cfg(feature = "telemetry")]
        tracing::debug!(duration = ?duration, "finalize_deposit");

        // Transfer the leaves to self.
        let time_start = std::time::Instant::now();
        self.transfer_deposits_to_self(
            created_root
                .nodes
                .iter()
                .map(|node| node.id.clone())
                .collect(),
        )
        .await?;

        let duration = time_start.elapsed();
        #[cfg(feature = "telemetry")]
        tracing::debug!(duration = ?duration, "transfer_deposits_to_self");

        Ok(created_root.nodes)
    }

    /// Retrieves all unused deposit addresses that have been previously generated for your wallet.
    ///
    /// This function queries the Spark network for all deposit addresses associated with your
    /// identity public key that haven't been used for deposits yet. This helps you track
    /// deposit addresses that you've created but haven't received funds on yet.
    ///
    /// # Returns
    ///
    /// * `Ok(Vec<DepositAddressQueryResult>)` - A vector of unused deposit addresses if successful
    /// * `Err(SparkSdkError)` - If there was an error querying the addresses
    ///
    /// # Example
    ///
    /// ```
    /// # use spark_rust::SparkSdk;
    /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
    /// // Query all unused deposit addresses associated with your wallet
    /// let unused_addresses = sdk.query_unused_deposit_addresses().await?;
    ///
    /// // Process each unused address
    /// for address_result in unused_addresses {
    ///     println!("Unused address: {}", address_result.deposit_address);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub async fn query_unused_deposit_addresses(
        &self,
    ) -> Result<Vec<DepositAddressQueryResult>, SparkSdkError> {
        with_handler_lock!(self, async {
            let identity_public_key = self.get_spark_address()?;

            let request = QueryUnusedDepositAddressesRequest {
                identity_public_key: identity_public_key.serialize().to_vec(),
            };
            let response = self
                .config
                .spark_config
                .call_with_retry(
                    request,
                    |mut client, req| {
                        Box::pin(async move { client.query_unused_deposit_addresses(req).await })
                    },
                    None,
                )
                .await?;

            Ok(response.deposit_addresses)
        })
        .await
    }

    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    async fn transfer_deposits_to_self(&self, leaf_ids: Vec<String>) -> Result<(), SparkSdkError> {
        self.transfer_leaf_ids_internal(leaf_ids, &self.get_spark_address()?)
            .await?;

        Ok(())
    }
}