breez_sdk_spark/token_conversion/
mod.rs

1mod error;
2mod flashnet;
3mod middleware;
4mod models;
5
6pub use error::ConversionError;
7pub(crate) use flashnet::FlashnetTokenConverter;
8pub(crate) use middleware::TokenConversionMiddleware;
9pub use models::*;
10
11use spark_wallet::TransferId;
12use tokio::sync::broadcast;
13
14/// Trait for conversion implementations.
15///
16/// This trait abstracts the conversion mechanics, allowing different
17/// implementations (e.g., Flashnet) to be used interchangeably.
18/// Business logic for when/how much to convert is handled by `StableBalance`.
19#[macros::async_trait]
20pub(crate) trait TokenConverter: Send + Sync {
21    /// Execute a conversion swap.
22    ///
23    /// # Arguments
24    /// * `options` - The conversion options including type and slippage
25    /// * `purpose` - The purpose of the conversion
26    /// * `token_identifier` - Optional token identifier for `FromBitcoin` conversions
27    /// * `amount` - Either the minimum output amount or exact input amount
28    /// * `transfer_id` - Optional transfer ID for idempotency
29    async fn convert(
30        &self,
31        options: &ConversionOptions,
32        purpose: &ConversionPurpose,
33        token_identifier: Option<&String>,
34        amount: ConversionAmount,
35        transfer_id: Option<TransferId>,
36    ) -> Result<TokenConversionResponse, ConversionError>;
37
38    /// Validate a conversion and return the estimated conversion.
39    ///
40    /// Called during `prepare_send_payment` to calculate the conversion fee,
41    /// and during auto-conversion to estimate the token output.
42    ///
43    /// # Arguments
44    /// * `options` - The conversion options to validate
45    /// * `token_identifier` - Optional token identifier for `FromBitcoin` conversions
46    /// * `amount` - Either the minimum output amount or exact input amount
47    ///
48    /// # Returns
49    /// The estimated conversion including amount and fee, or None if options is None.
50    /// `estimate.amount_in` is the input amount, `estimate.amount_out` is the estimated output.
51    async fn validate(
52        &self,
53        options: Option<&ConversionOptions>,
54        token_identifier: Option<&String>,
55        amount: ConversionAmount,
56    ) -> Result<Option<ConversionEstimate>, ConversionError>;
57
58    /// Fetch conversion limits for a given conversion type.
59    ///
60    /// # Arguments
61    /// * `request` - The request containing conversion type and optional token identifier
62    async fn fetch_limits(
63        &self,
64        request: &FetchConversionLimitsRequest,
65    ) -> Result<FetchConversionLimitsResponse, ConversionError>;
66
67    /// Process any conversions whose pending refunds need to be issued.
68    ///
69    /// Iterates over payments marked as needing a refund and attempts to
70    /// refund each one. Surfaced through `BreezSdk::refund_pending_conversions`
71    /// so partners can drive this explicitly — required in server mode (where
72    /// no periodic refunder runs) and available in client mode as a way to
73    /// force an immediate refund pass instead of waiting for the next tick.
74    async fn refund_pending(&self) -> Result<(), ConversionError>;
75
76    /// Optional signal that wakes the client-mode periodic refunder.
77    fn subscribe_refund_requests(&self) -> Option<broadcast::Receiver<()>> {
78        None
79    }
80}
breez_sdk_spark/token_conversion/mod.rs

breez_sdk_spark/token_conversion/
mod.rs
