breez_sdk_spark/sdk/bridging/
models.rs

1use serde::{Deserialize, Serialize};
2
3use crate::{
4    CrossChainConfig, CrossChainProvider, CrossChainReceiveInfo, CrossChainRouteLimits, FeePolicy,
5    ProxyConfig,
6};
7
8/// Settings for a [`BridgingClient`](super::BridgingClient) built with
9/// [`new_bridging_client`](super::new_bridging_client).
10#[derive(Debug, Clone)]
11#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
12pub struct BridgingConfig {
13    /// Breez API key.
14    pub api_key: String,
15    /// Routes the client's connections through a SOCKS5 proxy.
16    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
17    pub proxy: Option<ProxyConfig>,
18    /// Default slippage and overpay. Unset uses the built-in defaults.
19    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
20    pub cross_chain_config: Option<CrossChainConfig>,
21}
22
23#[derive(Debug, Clone)]
24#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
25pub struct GetBridgeRoutesRequest {
26    /// Who to pay: a Spark address, a Lightning address (a Cash App
27    /// `$cashtag` included), or an EVM/Solana/Tron address or URI.
28    pub recipient: String,
29}
30
31#[derive(Debug, Clone, Serialize)]
32#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
33pub struct GetBridgeRoutesResponse {
34    /// The routes that can pay the recipient. Empty when none can.
35    pub routes: Vec<BridgeRoutePair>,
36}
37
38/// A way to pay a recipient: what the payer pays, and what the recipient
39/// receives.
40#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
41#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
42pub struct BridgeRoutePair {
43    pub provider: CrossChainProvider,
44    /// What the payer pays.
45    pub source: BridgeRoutePairSide,
46    /// What the recipient receives.
47    pub destination: BridgeRoutePairSide,
48    /// Bounds on what the payer pays, in `source` base units. Unset when the
49    /// provider publishes none.
50    pub limits: Option<CrossChainRouteLimits>,
51}
52
53/// One side of a [`BridgeRoutePair`].
54#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
55#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
56pub struct BridgeRoutePairSide {
57    /// `"spark"`, `"lightning"`, or another chain, e.g. `"base"` or `"tron"`.
58    pub chain: String,
59    /// EVM `chainId` as a decimal string. Unset on chains without one.
60    pub chain_id: Option<String>,
61    /// Asset symbol, e.g. `"USDC"`, `"USDT"`, `"BTC"` or `"USDB"`.
62    pub asset: String,
63    /// Token contract or mint address, or the token identifier on Spark.
64    /// Unset for Bitcoin.
65    pub contract_address: Option<String>,
66    pub decimals: u8,
67}
68
69#[derive(Debug, Clone)]
70#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
71pub struct CreateBridgeRequest {
72    /// Who to pay, as given to [`BridgingClient::get_routes`](super::BridgingClient::get_routes).
73    pub recipient: String,
74    /// A route from [`BridgingClient::get_routes`](super::BridgingClient::get_routes)
75    /// for this recipient.
76    pub route: BridgeRoutePair,
77    /// Amount in stablecoin base units: the destination asset when the
78    /// recipient is paid in a stablecoin, the source asset otherwise, per that
79    /// side's `decimals`. At parity this is the USD value: `1_000_000` is 1
80    /// USDC at 6 decimals.
81    pub amount: u128,
82    /// The payer's address on the source chain, where the deposit is refunded
83    /// if the recipient can't be paid. Required to pay a Lightning address,
84    /// and recommended whenever the payer pays from another chain: without
85    /// one the provider has no address to refund to. Ignored when the payer
86    /// pays over Lightning.
87    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
88    pub refund_address: Option<String>,
89    /// Whether fees are added on top of `amount` (`FeesExcluded`, the default)
90    /// or deducted from it (`FeesIncluded`).
91    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
92    pub fee_policy: Option<FeePolicy>,
93    /// Maximum slippage tolerance in basis points. Unset uses the configured
94    /// default.
95    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
96    pub max_slippage_bps: Option<u32>,
97}
98
99#[derive(Debug, Clone, Serialize)]
100#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
101pub struct CreateBridgeResponse {
102    /// Identifies the bridge for [`BridgingClient::get_bridge_status`](super::BridgingClient::get_bridge_status).
103    /// Store it to look up the status later.
104    pub bridge_id: String,
105    /// Pass it to
106    /// [`BridgingClient::get_bridge_status`](super::BridgingClient::get_bridge_status).
107    pub status_token: Option<String>,
108    /// What the payer pays: an EIP-681 URI on EVM chains, a BOLT11 invoice or a
109    /// Cash App link over Lightning, otherwise the bare deposit address.
110    pub payment_request: String,
111    /// The deposit and the expected delivery.
112    pub info: CrossChainReceiveInfo,
113}
114
115#[derive(Debug, Clone)]
116#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
117pub struct GetBridgeStatusRequest {
118    pub bridge_id: String,
119    /// The bridge's status token, if any.
120    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
121    pub status_token: Option<String>,
122}
123
124/// Where a bridge is in its lifecycle.
125#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
126#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
127pub enum BridgeStatus {
128    /// The bridge was created, and the payer hasn't paid yet. An unpaid bridge
129    /// stays `Created` after its `expires_at`. A late deposit on another chain
130    /// may still be accepted at a new price.
131    Created,
132    /// The provider is processing the payment, from confirming the deposit to
133    /// paying the recipient. `provider_status` gives the stage.
134    Pending,
135    /// The recipient can't be paid, and the payment is being refunded.
136    Refunding,
137    /// The recipient was paid.
138    Completed,
139    /// The payment was refunded to the payer's refund address.
140    Refunded,
141    /// The bridge failed. `error_code` gives the reason.
142    Failed,
143    /// The provider's order expired without a payment.
144    Expired,
145}
146
147#[derive(Debug, Clone, Serialize)]
148#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
149pub struct GetBridgeStatusResponse {
150    pub status: BridgeStatus,
151    /// The provider's own status, e.g. `"bridging"` or `"awaiting_approval"`,
152    /// for display and support. Unset before the payment arrives.
153    pub provider_status: Option<String>,
154    /// The provider's order id, once the payment arrived.
155    pub order_id: Option<String>,
156    /// The amount the payer paid, in the source asset's base units.
157    pub amount_in: Option<u128>,
158    /// The amount the recipient received, in the destination asset's base
159    /// units. Set once completed.
160    pub amount_out: Option<u128>,
161    /// The payer's transaction on the source chain.
162    pub deposit_tx_hash: Option<String>,
163    /// The transaction that paid the recipient, or the Spark transfer when the
164    /// recipient is on Spark. Set once completed.
165    pub delivery_tx_hash: Option<String>,
166    /// The transaction that refunded the payer.
167    pub refund_tx_hash: Option<String>,
168    /// The provider's error code when the bridge failed.
169    pub error_code: Option<String>,
170}
breez_sdk_spark/sdk/bridging/models.rs

breez_sdk_spark/sdk/bridging/
models.rs
