spark_rust/wallet/handlers/

cooperative_exit.rs

use crate::with_handler_lock;
use crate::{
    constants::spark::{DEFAULT_COOPERATIVE_EXIT_EXPIRY, DEFAULT_WITHDRAWAL_AMOUNT},
    error::{IoError, SparkSdkError, ValidationError},
    signer::traits::{derivation_path::SparkKeyType, SparkSigner},
    wallet::{
        internal_handlers::traits::{
            cooperative_exit::CooperativeExitInternalHandlers,
            leaves::LeavesInternalHandlers,
            ssp::SspInternalHandlers,
            transfer::{LeafKeyTweak, TransferInternalHandlers},
        },
        leaf_manager::SparkNodeStatus,
        utils::transaction::create_connector_refund_tx,
    },
    SparkSdk,
};
use bitcoin::{secp256k1::PublicKey, Address, OutPoint, Transaction, Txid};
use serde::{Deserialize, Serialize};
use uuid::Uuid;

// An opaque ID representing a cooperative exit request.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct CoopExitRequestId(pub String);

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct CoopExitResponse {
    pub request_id: CoopExitRequestId,
    pub exit_txid: Txid,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub enum CoopExitStatus {
    Pending,
    Completed,
}

/// Input for requesting a cooperative exit
pub struct RequestCoopExitInput {
    /// The leaf external IDs to exit
    pub leaf_external_ids: Uuid,
    /// The withdrawal address
    pub withdrawal_address: Address,
}

/// Input for completing a cooperative exit
#[derive(Serialize, Deserialize)]
pub struct CompleteCoopExitInput {
    /// The user outbound transfer external ID
    pub user_outbound_transfer_external_id: String,
    /// The cooperative exit request ID
    pub coop_exit_request_id: CoopExitRequestId,
}

/// Cooperative exit request response
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct CoopExitRequest {
    /// The ID of the request
    pub id: CoopExitRequestId,
    /// The raw connector transaction. Only present if the request is pending.
    pub raw_connector_transaction: Option<Transaction>,
    /// The status of the request
    pub status: CoopExitStatus,
    /// The timestamp of the request
    pub created_at: u64,
    /// The timestamp of the last update
    pub updated_at: u64,
}

/// Represents a signing nonce with binding and hiding keys
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SigningNonce {
    /// The binding key
    pub binding: Vec<u8>,
    /// The hiding key
    pub hiding: Vec<u8>,
}

/// Represents a signing commitment with binding and hiding public keys
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SigningCommitment {
    /// The binding public key
    pub binding: Vec<u8>,
    /// The hiding public key
    pub hiding: Vec<u8>,
}

/// CoopExitService implementation for Rust
/// This is a 1-to-1 port of the TypeScript CoopExitService class
impl<S: SparkSigner + Send + Sync + Clone + 'static> SparkSdk<S> {
    /// Initiates a withdrawal to move funds from the Spark network to an on-chain Bitcoin address.
    ///
    /// This function allows you to exit the Spark network by withdrawing funds back to the Bitcoin
    /// blockchain through a cooperative process with the Spark Service Provider (SSP). The SSP
    /// facilitates the on-chain transaction and charges a service fee for this operation.
    ///
    /// # Arguments
    ///
    /// * `onchain_address` - The Bitcoin address where the funds should be sent
    /// * `target_amount_sats` - Optional amount in satoshis to withdraw. If not specified,
    ///                        attempts to withdraw all available funds in your wallet
    ///
    /// # Returns
    ///
    /// * `Ok(CoopExitResponse)` - Contains the cooperative exit request ID and exit transaction ID
    /// * `Err(SparkSdkError)` - If the withdrawal request failed
    ///
    /// # Example
    ///
    /// ```
    /// # use spark_rust::SparkSdk;
    /// # use bitcoin::Address;
    /// # use std::str::FromStr;
    /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
    /// // Create a Bitcoin address to receive the funds
    /// let address = Address::from_str("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4")?;
    ///
    /// // Withdraw all available funds
    /// let response = sdk.withdraw(&address, None).await?;
    /// println!("Withdrawal initiated with request ID: {:?}", response.request_id);
    /// println!("Exit transaction ID: {}", response.exit_txid);
    ///
    /// // Or withdraw a specific amount (e.g., 50,000 satoshis)
    /// // let response = sdk.withdraw(&address, Some(50_000)).await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Note
    ///
    /// Withdrawals incur a service fee charged by the SSP. You can estimate this fee before
    /// initiating a withdrawal using the `get_cooperative_exit_fee_estimate` method.
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub async fn withdraw(
        &self,
        onchain_address: &Address,
        target_amount_sats: Option<u64>,
    ) -> Result<CoopExitResponse, SparkSdkError> {
        // Then perform the cooperative exit
        with_handler_lock!(self, async {
            self.cooperative_exit(onchain_address, target_amount_sats)
                .await
        })
        .await
    }

    /// Performs a cooperative exit operation.
    ///
    /// This method allows a user to exit the Spark network cooperatively with the connector.
    /// It signs refund transactions for the leaves being exited and sends them to the connector.
    ///
    /// # Arguments
    ///
    /// * `onchain_address` - The Bitcoin address to withdraw funds to
    /// * `target_amount_sats` - Optional target amount in satoshis to withdraw
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The ID of the completed cooperative exit request
    /// * `Err(SparkSdkError)` - If there was an error during the cooperative exit process
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    async fn cooperative_exit(
        &self,
        onchain_address: &Address,
        target_amount_sats: Option<u64>,
    ) -> Result<CoopExitResponse, SparkSdkError> {
        if let Some(amount) = target_amount_sats {
            if amount < DEFAULT_WITHDRAWAL_AMOUNT {
                return Err(SparkSdkError::from(ValidationError::InvalidInput {
                    field: "Target amount is less than the minimum withdrawal amount".to_string(),
                }));
            }
        } else {
            let leaves = self
                .leaf_manager
                .get_available_bitcoin_leaves(None, SparkNodeStatus::Available);

            let amount = leaves
                .iter()
                .map(|leaf| leaf.get_tree_node().unwrap().value)
                .sum::<u64>();

            if amount < DEFAULT_WITHDRAWAL_AMOUNT {
                return Err(SparkSdkError::from(ValidationError::InvalidInput {
                    field: "Target amount is less than the minimum withdrawal amount".to_string(),
                }));
            }
        }

        let leaves_to_send = match target_amount_sats {
            Some(amount) => {
                // Get leaves for the target amount
                self.prepare_leaves_for_amount(amount).await?.leaves
            }
            None => {
                // Get all available BTC leaves
                self.leaf_manager
                    .get_available_bitcoin_leaves(None, SparkNodeStatus::CooperativeExit)
            }
        };

        // return early if no leaves found
        if leaves_to_send.is_empty() {
            return Err(SparkSdkError::from(ValidationError::InvalidInput {
                field: "No available leaves found".to_string(),
            }));
        }

        // generate leaf key tweaks
        let mut leaf_key_tweaks = Vec::new();
        let network = self.config.spark_config.network.to_bitcoin_network();
        for leaf in &leaves_to_send {
            // generate signing public key from leaf ID
            let old_signing_private_key = self.signer.expose_leaf_secret_key_for_transfer(
                leaf.get_id().clone(),
                SparkKeyType::BaseSigning,
                0,
                network,
            )?;
            // generate new signing public key
            let new_signing_public_key = self.signer.new_ephemeral_keypair()?;

            leaf_key_tweaks.push(LeafKeyTweak {
                leaf: leaf.get_tree_node()?,
                old_signing_private_key,
                new_signing_public_key,
            });
        }

        // initiate the coop exit with SSP
        let leaf_ids = leaves_to_send
            .iter()
            .map(|leaf| leaf.get_id().clone())
            .collect();

        let initiate_response = self
            .initiate_cooperative_exit_with_ssp(leaf_ids, onchain_address)
            .await?;

        // TODO: make a function
        let connector_txid = initiate_response.connector_tx.compute_txid();
        let coop_exit_txid = initiate_response.connector_tx.input[0].previous_output.txid;

        // extract connector outputs
        let mut connector_outputs = Vec::new();
        // Only include outputs up to the second-to-last one (len - 1)
        // This is because the last output is typically the change output
        let output_count = initiate_response.connector_tx.output.len();
        for i in 0..output_count.saturating_sub(1) {
            connector_outputs.push(OutPoint {
                txid: connector_txid,
                vout: i as u32,
            });
        }

        // get connector refund signatures
        let coop_exit_txid_bytes = hex::decode(coop_exit_txid.to_string())
            .map_err(|err| SparkSdkError::from(IoError::Decoding(err)))?;

        let expiry = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_secs()
            + DEFAULT_COOPERATIVE_EXIT_EXPIRY;
        let (transfer, _) = self
            .get_connector_refund_signatures(
                &leaf_key_tweaks,
                &coop_exit_txid_bytes,
                &connector_outputs,
                &self.config.spark_config.ssp_identity_public_key,
                expiry,
            )
            .await?;

        // complete the cooperative exit using the internal handler
        let complete_response = match self
            .complete_cooperative_exit_with_ssp(transfer.id.clone(), initiate_response.request_id)
            .await
        {
            Ok(response) => CoopExitResponse {
                request_id: response,
                exit_txid: coop_exit_txid,
            },
            Err(status) => {
                // If the request fails, cancel the transfer and propagate the error
                if let Err(cancel_err) = self.cancel_send_transfer(transfer.id.clone()).await {
                    // Log the cancellation error but return the original error
                    #[cfg(feature = "telemetry")]
                    tracing::error!(
                        "Failed to cancel transfer after complete_cooperative_exit error: {}",
                        cancel_err
                    );
                }
                return Err(status);
            }
        };

        Ok(complete_response)
    }

    /// Creates a connector refund transaction.
    ///
    /// This method is equivalent to the TypeScript `createConnectorRefundTransaction` method.
    /// It creates a refund transaction for a connector output.
    ///
    /// # Arguments
    ///
    /// * `sequence` - The sequence number for the transaction
    /// * `node_outpoint` - The outpoint of the node transaction
    /// * `connector_output` - The connector output
    /// * `amount_sats` - The amount in satoshis
    /// * `receiver_pubkey` - The receiver public key
    ///
    /// # Returns
    ///
    /// The created refund transaction
    pub fn create_connector_refund_transaction(
        &self,
        sequence: u32,
        node_outpoint: OutPoint,
        connector_output: OutPoint,
        amount_sats: u64,
        receiver_pubkey: &PublicKey,
    ) -> Transaction {
        // Use the utility function from the codebase
        create_connector_refund_tx(
            sequence,
            node_outpoint,
            connector_output,
            amount_sats,
            receiver_pubkey,
            self.config.spark_config.network.to_bitcoin_network(),
        )
    }
}