spark_rust/wallet/handlers/

deposit.rs

use std::collections::HashMap;

use bitcoin::secp256k1::PublicKey;
use spark_protos::spark::{
    DepositAddressQueryResult, GenerateDepositAddressRequest, QueryUnusedDepositAddressesRequest,
    TreeNode,
};
use tonic::Request;

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> {
        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())?;

        let mut spark_client = self.config.spark_config.get_spark_connection(None).await?;
        let mut request = tonic::Request::new(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(),
        });
        self.add_authorization_header_to_request(&mut request, None);

        let response = spark_client
            .generate_deposit_address(request)
            .await
            .map_err(|status| SparkSdkError::from(NetworkError::Status(status)))?;

        let response = response.into_inner();
        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,
        })
    }

    /// 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> {
        // 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 mut spark_client = self.config.spark_config.get_spark_connection(None).await?;
        let identity_public_key = self.get_spark_address();
        let mut request = Request::new(QueryUnusedDepositAddressesRequest {
            identity_public_key: identity_public_key?.serialize().to_vec(),
        });
        self.add_authorization_header_to_request(&mut request, None);
        let response_outer = spark_client
            .query_unused_deposit_addresses(request)
            .await
            .map_err(|status| SparkSdkError::from(NetworkError::Status(status)))?;
        let deposit_addresses = response_outer.into_inner().deposit_addresses;

        let duration = time_start.elapsed();
        #[cfg(feature = "telemetry")]
        tracing::debug!(duration = ?duration, "query_unused_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(
                deposit_data.user_signing_public_key.clone(),
                deposit_data.verifying_public_key.clone(),
                deposit_tx.clone(),
                vout,
            )
            .await?;

        self.claim_transfers().await?;

        Ok(nodes)
    }

    /// 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> {
        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)
    }

    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub async fn query_unused_deposit_addresses(
        &self,
    ) -> Result<Vec<DepositAddressQueryResult>, SparkSdkError> {
        let identity_public_key = self.get_spark_address()?;
        let mut spark_client = self.config.spark_config.get_spark_connection(None).await?;
        let mut request = Request::new(QueryUnusedDepositAddressesRequest {
            identity_public_key: identity_public_key.serialize().to_vec(),
        });
        self.add_authorization_header_to_request(&mut request, None);
        let response = spark_client
            .query_unused_deposit_addresses(request)
            .await
            .map_err(|status| SparkSdkError::from(NetworkError::Status(status)))?;

        let response = response.into_inner();
        Ok(response.deposit_addresses)
    }

    #[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(leaf_ids, &self.get_spark_address()?)
            .await?;

        Ok(())
    }
}