spark_rust/wallet/handlers/

lightning.rs

use lightning_invoice::Bolt11Invoice;
use rand::rngs::OsRng;
use spark_cryptography::derivation_path::SparkKeyType;
use spark_protos::spark::StorePreimageShareRequest;
use std::{collections::HashMap, str::FromStr};
use uuid::Uuid;

use crate::{
    error::{IoError, NetworkError, SparkSdkError, ValidationError},
    signer::traits::SparkSigner,
    wallet::internal_handlers::traits::{
        leaves::LeavesInternalHandlers,
        lightning::LightningInternalHandlers,
        ssp::SspInternalHandlers,
        transfer::{LeafKeyTweak, TransferInternalHandlers},
    },
    with_handler_lock, SparkSdk,
};

impl<S: SparkSigner + Send + Sync + Clone + 'static> SparkSdk<S> {
    /// Pays a Lightning Network invoice using the Spark Service Provider (SSP) as an intermediary.
    ///
    /// Unlike traditional Lightning wallets, Spark doesn't directly connect to the Lightning Network.
    /// Instead, it uses a cooperative approach where:
    ///
    /// 1. You provide your leaves (UTXOs) to the SSP
    /// 2. The SSP makes the Lightning payment on your behalf
    /// 3. The transaction is secured using cryptographic techniques
    ///
    /// This method handles the entire process including:
    /// - Parsing and validating the Lightning invoice
    /// - Selecting appropriate leaves to cover the invoice amount
    /// - Executing a secure swap with the SSP
    /// - Finalizing the payment through the Lightning Network
    ///
    /// # Arguments
    ///
    /// * `invoice` - A BOLT11 Lightning invoice string that you want to pay
    ///
    /// # Returns
    ///
    /// * `Ok(String)` - The payment ID if successful, which can be used to track the payment status
    /// * `Err(SparkSdkError)` - If there was an error during the payment process
    ///
    /// # Example
    ///
    /// ```
    /// # use spark_rust::SparkSdk;
    /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
    /// // Lightning invoice to pay
    /// let invoice = "lnbc1500n1p3zty3app5wkf0hagkc4egr8rl88msr4c5lp0ygt6gvzna5hdg4tpna65pzqdq0vehk7cnpwga5xzmnwvycqzpgxqyz5vqsp5v9ym7xsyf0qxqwzlmwjl3g0g9q2tg977h70hcheske9xlgfsggls9qyyssqtghx3qqpwm9zl4m398nm40wj8ryaz8v7v4rrdvczypdpy7qtc6rdrkklm9uxlkmtp3jf29yhqjw2vwmlp82y5ctft94k23cwgqd9llgy".to_string();
    ///
    /// // Pay the invoice
    /// let payment_id = sdk.pay_lightning_invoice(&invoice).await?;
    /// println!("Lightning payment initiated with ID: {}", payment_id);
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Note
    ///
    /// The payment incurs a service fee charged by the SSP. You can estimate this fee before
    /// initiating the payment using the `get_lightning_send_fee_estimate` method.
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub async fn pay_lightning_invoice(&self, invoice: &String) -> Result<Uuid, SparkSdkError> {
        with_handler_lock!(self, async {
        let invoice = Bolt11Invoice::from_str(invoice)
            .map_err(|err| SparkSdkError::from(IoError::Bolt11InvoiceDecoding(err.to_string())))?;

        // get the invoice amount in sats, then validate the amount
        let amount_sats = get_invoice_amount_sats(&invoice)?;
        if amount_sats == 0 {
            return Err(SparkSdkError::from(ValidationError::InvalidInput {
                field: "Amount must be greater than 0".to_string(),
            }));
        }

        // get the payment hash from the invoice
        let payment_hash = invoice.payment_hash();

        // refresh timelock nodes
        self.refresh_timelock_nodes(None).await?;

        // select leaves
        let leaf_selection_response = self.prepare_leaves_for_amount(amount_sats).await?;

        let unlocking_id = leaf_selection_response.unlocking_id.clone().unwrap();
        let leaves = leaf_selection_response.leaves;

        // prepare leaf tweaks
        let network = self.get_network();
        let mut leaf_tweaks = Vec::with_capacity(leaves.len());
        for leaf in &leaves {
            let tree_node = leaf.get_tree_node()?;
            let keypair = self.signer.derive_spark_key(
                leaf.get_id().clone(),
                0,
                SparkKeyType::BaseSigning,
                network.to_bitcoin_network(),
            )?;
            let old_signing_private_key = keypair.secret_key();

            let new_signing_public_key = self.signer.new_ephemeral_keypair()?;

            let leaf_tweak = LeafKeyTweak {
                leaf: tree_node,
                old_signing_private_key,
                new_signing_public_key,
            };
            leaf_tweaks.push(leaf_tweak);
        }

        let swap_response = self
            .swap_nodes_for_preimage(
                leaf_tweaks.clone(),
                &self.config.spark_config.ssp_identity_public_key,
                payment_hash,
                &invoice,
                amount_sats,
                0, // TODO: this must use the estimated fee.
                false,
            )
            .await?;

        #[cfg(feature = "telemetry")]
        tracing::trace!(swap_response = ?swap_response, "swap_nodes_for_preimage");

        let transfer = swap_response
            .transfer
            .ok_or(SparkSdkError::from(ValidationError::InvalidInput {
                field: "Swap response did not contain a transfer".to_string(),
            }))?
            .try_into()?;

        // start the transfer
        let transfer = self
            .send_transfer_tweak_key(&transfer, &leaf_tweaks, &HashMap::new())
            .await?;
        #[cfg(feature = "telemetry")]
        tracing::trace!(
            transfer_id = transfer.id.to_string(),
            "send_transfer_tweak_key"
        );

        // request Lightning send with the SSP
        let lightning_send_response = self
            .request_lightning_send_with_ssp(invoice.to_string(), payment_hash.to_string())
            .await?;
        #[cfg(feature = "telemetry")]
        tracing::trace!(lightning_send_response = ?lightning_send_response, "request_lightning_send_with_ssp");

        // delete the leaves after the transfer
        let leaf_ids_to_remove: Vec<String> = leaves.iter().map(|l| l.get_id().clone()).collect();
        self.leaf_manager
            .unlock_leaves(unlocking_id.clone(), &leaf_ids_to_remove, true)?;
        #[cfg(feature = "telemetry")]
        tracing::trace!(unlocking_id = ?unlocking_id, leaf_ids_to_remove = ?leaf_ids_to_remove, "unlock_leaves");

        Ok(transfer.id)
        })
        .await
    }

    /// Creates a Lightning Network invoice that others can pay to you.
    ///
    /// This function generates a BOLT11 Lightning invoice and distributes the payment preimage
    /// using a threshold secret sharing scheme among Spark operators. When someone pays this
    /// invoice via Lightning, the funds will be received by the SSP and then transferred to
    /// your Spark wallet.
    ///
    /// The process involves:
    /// 1. Generating a secure payment preimage and hash
    /// 2. Creating the invoice through the SSP
    /// 3. Distributing preimage shares to Spark operators using threshold secret sharing
    /// 4. Returning the formatted BOLT11 invoice
    ///
    /// # Arguments
    ///
    /// * `amount_sats` - The amount in satoshis that you want to receive
    /// * `memo` - Optional description/memo for the invoice
    /// * `expiry_seconds` - Optional expiry time in seconds (defaults to 30 days if not specified)
    ///
    /// # Returns
    ///
    /// * `Ok(Bolt11Invoice)` - The generated Lightning invoice if successful
    /// * `Err(SparkSdkError)` - If there was an error during invoice creation
    ///
    /// # Example
    ///
    /// ```
    /// # use spark_rust::SparkSdk;
    /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
    /// // Create an invoice for 50,000 satoshis
    /// let amount_sats = 50_000;
    /// let memo = Some("Payment for services".to_string());
    /// let expiry = Some(3600 * 24); // 24 hours
    ///
    /// // Generate the Lightning invoice
    /// let invoice = sdk.create_lightning_invoice(amount_sats, memo, expiry).await?;
    ///
    /// // Get the invoice string to share with the payer
    /// let invoice_string = invoice.to_string();
    /// println!("Lightning Invoice: {}", invoice_string);
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Note
    ///
    /// Receiving Lightning payments incurs a service fee charged by the SSP. You can estimate
    /// this fee before creating an invoice using the `get_lightning_receive_fee_estimate` method.
    #[cfg_attr(feature = "telemetry", tracing::instrument(skip_all))]
    pub async fn create_lightning_invoice(
        &self,
        amount_sats: u64,
        memo: Option<String>,
        expiry_seconds: Option<i32>,
    ) -> Result<Bolt11Invoice, SparkSdkError> {
        // default expiry to 30 days
        let expiry_seconds = expiry_seconds.unwrap_or(60 * 60 * 24 * 30);

        // generate the preimage
        // hash the preimage to get the payment hash
        let preimage_sk = bitcoin::secp256k1::SecretKey::new(&mut OsRng);
        let preimage_bytes = preimage_sk.secret_bytes();
        let payment_hash = sha256::digest(&preimage_bytes);
        let payment_hash_bytes = hex::decode(&payment_hash)
            .map_err(|err| SparkSdkError::from(IoError::Decoding(err)))?;

        // create the invoice by making a request to the SSP
        // TODO: we'll need to use fees
        let (invoice, _fees) = self
            .create_invoice_with_ssp(
                amount_sats,
                payment_hash,
                expiry_seconds,
                memo,
                self.config.spark_config.network,
            )
            .await?;

        // distribute the preimage shares to the operators
        // TODO: parallelize this
        let t = self.config.spark_config.threshold as usize;
        let n = self.config.spark_config.operator_pool.operators.len();
        let shares = self.signer.split_with_verifiable_secret_sharing(
            preimage_sk.secret_bytes().to_vec(),
            t,
            n,
        )?;

        let signing_operators = self.config.spark_config.operator_pool.operators.clone();
        let identity_pubkey = self.get_spark_address()?;

        let futures = signing_operators.iter().map(|operator| {
            let operator_id = operator.id;
            let share = &shares[operator_id as usize];
            let payment_hash = payment_hash_bytes.clone();
            let invoice_str = invoice.clone();
            let threshold = self.config.spark_config.threshold;
            let config = self.config.clone();

            async move {
                let request_data = StorePreimageShareRequest {
                    payment_hash,
                    preimage_share: Some(share.marshal_proto()),
                    threshold,
                    invoice_string: invoice_str,
                    user_identity_public_key: identity_pubkey.serialize().to_vec(),
                };

                config
                    .spark_config
                    .call_with_retry(
                        request_data,
                        |mut client, req| {
                            Box::pin(async move { client.store_preimage_share(req).await })
                        },
                        Some(operator_id),
                    )
                    .await
                    .map_err(|e| tonic::Status::internal(format!("RPC error: {}", e)))?;

                Ok(())
            }
        });

        futures::future::try_join_all(futures)
            .await
            .map_err(|e| SparkSdkError::from(NetworkError::Status(e)))?;

        Bolt11Invoice::from_str(&invoice).map_err(|err| {
            SparkSdkError::from(ValidationError::InvalidBolt11Invoice(err.to_string()))
        })
    }
}

fn get_invoice_amount_sats(invoice: &Bolt11Invoice) -> Result<u64, SparkSdkError> {
    let invoice_amount_msats = invoice
        .amount_milli_satoshis()
        .ok_or(SparkSdkError::Validation(
            ValidationError::InvalidBolt11Invoice(invoice.to_string()),
        ))?;

    Ok(invoice_amount_msats / 1000)
}