spark_rust/wallet/handlers/fees.rs
1use serde::{Deserialize, Serialize};
2
3use crate::{
4 error::SparkSdkError, signer::traits::SparkSigner,
5 wallet::internal_handlers::traits::ssp::SspInternalHandlers, SparkSdk,
6};
7
8/// Fee estimation data returned by Lightspark's Spark Service Provider. This is a generic struct that is used for Lightning, Cooperative Exit, and Leaves Swap fee estimations.
9#[derive(Debug, Serialize, Deserialize)]
10pub struct SparkFeeEstimate {
11 /// The estimated fees in sats.
12 pub fees: u64,
13}
14
15impl<S: SparkSigner + Send + Sync + Clone + 'static> SparkSdk<S> {
16 /// Estimates the fees for receiving a Lightning payment through the Spark Service Provider (SSP).
17 ///
18 /// This function calculates how much the SSP will charge for facilitating the receipt
19 /// of a Lightning payment of the specified amount. The fee is deducted from the received amount
20 /// before it is credited to your wallet.
21 ///
22 /// # Arguments
23 ///
24 /// * `amount` - The amount in satoshis you want to receive
25 ///
26 /// # Returns
27 ///
28 /// * `Ok(SparkFeeEstimate)` - Contains the estimated fees in satoshis
29 /// * `Err(SparkSdkError)` - If there was an error estimating the fees
30 ///
31 /// # Example
32 ///
33 /// ```
34 /// # use spark_rust::SparkSdk;
35 /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
36 /// // Get fee estimate for receiving 50,000 satoshis
37 /// let amount = 50_000;
38 /// let fee_estimate = sdk.get_lightning_receive_fee_estimate(amount).await?;
39 /// println!("The SSP will charge {} sats for receiving {} sats", fee_estimate.fees, amount);
40 ///
41 /// // Calculate net amount after fees
42 /// let net_amount = amount - fee_estimate.fees;
43 /// println!("You'll receive {} sats after fees", net_amount);
44 /// # Ok(())
45 /// # }
46 /// ```
47 pub async fn get_lightning_receive_fee_estimate(
48 &self,
49 amount: u64,
50 ) -> Result<SparkFeeEstimate, SparkSdkError> {
51 self.get_lightning_receive_fee_estimate_with_ssp(amount)
52 .await
53 }
54
55 /// Estimates the fees for sending a Lightning payment through the Spark Service Provider (SSP).
56 ///
57 /// This function calculates how much the SSP will charge for facilitating a Lightning payment
58 /// to the destination specified in the invoice. The fee is in addition to the invoice amount
59 /// and is paid from your wallet.
60 ///
61 /// # Arguments
62 ///
63 /// * `invoice` - The Lightning invoice you want to pay
64 ///
65 /// # Returns
66 ///
67 /// * `Ok(SparkFeeEstimate)` - Contains the estimated fees in satoshis
68 /// * `Err(SparkSdkError)` - If there was an error estimating the fees
69 ///
70 /// # Example
71 ///
72 /// ```
73 /// # use spark_rust::SparkSdk;
74 /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
75 /// // Get fee estimate for a Lightning invoice
76 /// let invoice = "lnbc1500n1p3zty3app5wkf0hagkc4egr8rl88msr4c5lp0ygt6gvzna5hdg4tpna65pzqdq0vehk7cnpwga5xzmnwvycqzpgxqyz5vqsp5v9ym7xsyf0qxqwzlmwjl3g0g9q2tg977h70hcheske9xlgfsggls9qyyssqtghx3qqpwm9zl4m398nm40wj8ryaz8v7v4rrdvczypdpy7qtc6rdrkklm9uxlkmtp3jf29yhqjw2vwmlp82y5ctft94k23cwgqd9llgy".to_string();
77 /// let fee_estimate = sdk.get_lightning_send_fee_estimate(invoice).await?;
78 /// println!("The SSP will charge {} sats for this Lightning payment", fee_estimate.fees);
79 ///
80 /// // Decide whether to proceed with payment based on fee amount
81 /// if fee_estimate.fees < 100 {
82 /// println!("Fee is acceptable, proceeding with payment");
83 /// }
84 /// # Ok(())
85 /// # }
86 /// ```
87 pub async fn get_lightning_send_fee_estimate(
88 &self,
89 invoice: String,
90 ) -> Result<SparkFeeEstimate, SparkSdkError> {
91 self.get_lightning_send_fee_estimate_with_ssp(invoice).await
92 }
93
94 /// Estimates the fees for withdrawing funds from Spark to an on-chain Bitcoin address.
95 ///
96 /// This function calculates how much the SSP will charge for facilitating the withdrawal
97 /// of specific leaves from the Spark network to an on-chain Bitcoin address. The fee is
98 /// deducted from the withdrawn amount.
99 ///
100 /// # Arguments
101 ///
102 /// * `leaf_ids` - The specific leaf IDs you want to withdraw
103 /// * `on_chain_address` - The Bitcoin address where you want to receive the funds
104 ///
105 /// # Returns
106 ///
107 /// * `Ok(SparkFeeEstimate)` - Contains the estimated fees in satoshis
108 /// * `Err(SparkSdkError)` - If there was an error estimating the fees
109 ///
110 /// # Example
111 ///
112 /// ```
113 /// # use spark_rust::SparkSdk;
114 /// # use bitcoin::Address;
115 /// # use std::str::FromStr;
116 /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
117 /// // Identify the leaves you want to withdraw
118 /// let leaf_ids = vec!["leaf_id_1".to_string(), "leaf_id_2".to_string()];
119 ///
120 /// // Specify the Bitcoin address to receive funds
121 /// let onchain_address = "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4".to_string();
122 ///
123 /// // Get fee estimate before withdrawing
124 /// let fee_estimate = sdk.get_cooperative_exit_fee_estimate(leaf_ids.clone(), onchain_address.clone()).await?;
125 /// println!("Estimated withdrawal fee: {} satoshis", fee_estimate.fees);
126 ///
127 /// // Decide whether to proceed with the withdrawal based on the fee
128 /// if fee_estimate.fees < 1000 {
129 /// // Fee is acceptable, proceed with withdrawal
130 /// let bitcoin_address = Address::from_str(&onchain_address)?;
131 /// // sdk.withdraw(&bitcoin_address, None).await?;
132 /// }
133 /// # Ok(())
134 /// # }
135 /// ```
136 pub async fn get_cooperative_exit_fee_estimate(
137 &self,
138 leaf_ids: Vec<String>,
139 on_chain_address: String,
140 ) -> Result<SparkFeeEstimate, SparkSdkError> {
141 self.get_cooperative_exit_fee_estimate_with_ssp(leaf_ids, on_chain_address)
142 .await
143 }
144
145 /// Estimates the fees for optimizing your wallet's leaf structure by swapping leaves with the SSP.
146 ///
147 /// This function calculates how much the SSP will charge for facilitating a leaves swap
148 /// operation. Leaf swaps are used to optimize your wallet's UTXO structure or to obtain
149 /// specific denominations needed for transfers.
150 ///
151 /// # Arguments
152 ///
153 /// * `total_amount_sats` - The total amount in satoshis that will be involved in the swap
154 ///
155 /// # Returns
156 ///
157 /// * `Ok(SparkFeeEstimate)` - Contains the estimated fees in satoshis
158 /// * `Err(SparkSdkError)` - If there was an error estimating the fees
159 ///
160 /// # Example
161 ///
162 /// ```
163 /// # use spark_rust::SparkSdk;
164 /// # async fn example(sdk: SparkSdk) -> Result<(), Box<dyn std::error::Error>> {
165 /// // Total amount to be swapped
166 /// let total_amount_sats = 100_000;
167 ///
168 /// // Get fee estimate before swapping leaves
169 /// let fee_estimate = sdk.get_leaves_swap_fee_estimate(total_amount_sats).await?;
170 /// println!("Estimated swap fee: {} satoshis", fee_estimate.fees);
171 ///
172 /// # Ok(())
173 /// # }
174 /// ```
175 pub async fn get_leaves_swap_fee_estimate(
176 &self,
177 total_amount_sats: u64,
178 ) -> Result<SparkFeeEstimate, SparkSdkError> {
179 self.get_leaves_swap_fee_estimate_with_ssp(total_amount_sats)
180 .await
181 }
182}