breez_sdk_spark/sdk/
mod.rs

1mod api;
2mod contacts;
3mod deposits;
4pub(crate) mod exit_chain_downloader;
5mod helpers;
6mod init;
7mod lightning_address;
8mod lightning_sender;
9mod lnurl;
10mod payments;
11mod runtime;
12mod sync;
13mod sync_coordinator;
14mod unilateral_exit;
15mod unilateral_exit_backup;
16
17pub(crate) use lightning_sender::{LightningSender, PendingLightningSend};
18pub(crate) use runtime::{RuntimeEvent, SdkRuntime, runtime_from_config};
19pub(crate) use sync_coordinator::SyncCoordinator;
20
21use bitflags::bitflags;
22use breez_sdk_common::{buy::moonpay::MoonpayProvider, fiat::FiatService};
23use platform_utils::HttpClient;
24use platform_utils::tokio;
25use spark_wallet::SparkWallet;
26use std::sync::Arc;
27use tokio::sync::{Mutex, OnceCell, oneshot, watch};
28
29use crate::{
30    BitcoinChainService, LeafOptimizationConfig, Logger, Network, TokenOptimizationConfig,
31    error::SdkError, events::EventEmitter, lnurl::LnurlServerClient, logger, models::Config,
32    persist::Storage, signer::lnurl_auth::LnurlAuthSignerAdapter, stable_balance::StableBalance,
33    token_conversion::TokenConverter,
34};
35
36#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
37const BREEZ_SYNC_SERVICE_URL: &str = "https://datasync.breez.technology";
38
39#[cfg(all(target_family = "wasm", target_os = "unknown"))]
40const BREEZ_SYNC_SERVICE_URL: &str = "https://datasync.breez.technology:442";
41
42pub(crate) const CLAIM_TX_SIZE_VBYTES: u64 = 99;
43pub(crate) const SYNC_PAGING_LIMIT: u32 = 100;
44
45bitflags! {
46    #[derive(Clone, Debug, PartialEq, Eq)]
47    pub(crate) struct SyncType: u32 {
48        const Wallet = 1 << 0;
49        const WalletState = 1 << 1;
50        const Deposits = 1 << 2;
51        const LnurlMetadata = 1 << 3;
52        const Full = Self::Wallet.0.0
53            | Self::WalletState.0.0
54            | Self::Deposits.0.0
55            | Self::LnurlMetadata.0.0;
56    }
57}
58
59#[derive(Clone, Debug)]
60pub(crate) struct SyncRequest {
61    pub(crate) sync_type: SyncType,
62    #[allow(clippy::type_complexity)]
63    pub(crate) reply: Arc<Mutex<Option<oneshot::Sender<Result<(), SdkError>>>>>,
64    /// If true, bypass the "recently synced" check and sync immediately.
65    /// Use for event-driven syncs (after payments, transfers, etc.) that should happen immediately.
66    pub(crate) force: bool,
67}
68
69impl SyncRequest {
70    pub(crate) async fn reply(&self, error: Option<SdkError>) {
71        if let Some(reply) = self.reply.lock().await.take() {
72            let _ = match error {
73                Some(e) => reply.send(Err(e)),
74                None => reply.send(Ok(())),
75            };
76        }
77    }
78}
79
80/// `BreezSDK` is a wrapper around `SparkSDK` that provides a more structured API
81/// with request/response objects and comprehensive error handling.
82#[derive(Clone)]
83#[cfg_attr(feature = "uniffi", derive(uniffi::Object))]
84pub struct BreezSdk {
85    pub(crate) config: Config,
86    pub(crate) spark_wallet: Arc<SparkWallet>,
87    pub(crate) storage: Arc<dyn Storage>,
88    pub(crate) chain_service: Arc<dyn BitcoinChainService>,
89    pub(crate) fiat_service: Arc<dyn FiatService>,
90    pub(crate) lnurl_client: Arc<dyn HttpClient>,
91    pub(crate) lnurl_server_client: Option<Arc<dyn LnurlServerClient>>,
92    pub(crate) lnurl_auth_signer: Option<Arc<LnurlAuthSignerAdapter>>,
93    pub(crate) event_emitter: Arc<EventEmitter>,
94    pub(crate) shutdown_sender: watch::Sender<()>,
95    /// Wakes the exit chain downloader once an operation has changed the leaf
96    /// set. Held even when collection is off, so nothing has to branch on it.
97    pub(crate) exit_chain_trigger: exit_chain_downloader::ExitChainTrigger,
98    pub(crate) runtime: SdkRuntime,
99    /// Coordinator for coalescing duplicate sync requests
100    pub(crate) sync_coordinator: SyncCoordinator,
101    /// Serialises claim attempts on the same deposit across the sync cascade
102    /// and explicit `claim_deposit` calls.
103    pub(crate) claim_guards: deposits::ClaimGuards,
104    pub(crate) initial_synced_watcher: watch::Receiver<bool>,
105    /// Parses payment inputs over the SDK's own transports, so lightning-address
106    /// and LNURL lookups honour the proxy and ride the redirect-validating
107    /// LNURL client (their hosts are chosen by remote parties).
108    pub(crate) input_parser: Arc<SdkInputParser>,
109    pub(crate) spark_private_mode_initialized: Arc<OnceCell<()>>,
110    pub(crate) token_converter: Arc<dyn TokenConverter>,
111    pub(crate) stable_balance: Option<Arc<StableBalance>>,
112    pub(crate) buy_bitcoin_provider: Arc<MoonpayProvider>,
113    pub(crate) cross_chain_context: crate::cross_chain::CrossChainContext,
114    /// Shared helper for paying LN invoices and persisting the resulting
115    /// payment rows. Reused by cross-chain providers (e.g. Boltz) that
116    /// need to pay an LN invoice as part of a larger flow.
117    #[allow(dead_code)]
118    pub(crate) lightning_sender: Arc<LightningSender>,
119}
120
121/// The parser bound to the SDK's shared HTTP client and its DNS resolver.
122pub(crate) type SdkInputParser =
123    breez_sdk_common::input::InputParser<Arc<dyn HttpClient>, breez_sdk_common::dns::Resolver>;
124
125pub(crate) struct BreezSdkParams {
126    pub config: Config,
127    pub input_parser: Arc<SdkInputParser>,
128    pub storage: Arc<dyn Storage>,
129    pub chain_service: Arc<dyn BitcoinChainService>,
130    pub fiat_service: Arc<dyn FiatService>,
131    pub lnurl_client: Arc<dyn HttpClient>,
132    pub lnurl_server_client: Option<Arc<dyn LnurlServerClient>>,
133    pub lnurl_auth_signer: Option<Arc<LnurlAuthSignerAdapter>>,
134    pub shutdown_sender: watch::Sender<()>,
135    pub runtime: SdkRuntime,
136    pub spark_wallet: Arc<SparkWallet>,
137    pub event_emitter: Arc<EventEmitter>,
138    pub buy_bitcoin_provider: Arc<MoonpayProvider>,
139    pub token_converter: Arc<dyn TokenConverter>,
140    pub stable_balance: Option<Arc<StableBalance>>,
141    pub sync_coordinator: SyncCoordinator,
142    pub cross_chain_context: crate::cross_chain::CrossChainContext,
143    pub lightning_sender: Arc<LightningSender>,
144}
145
146#[allow(clippy::needless_pass_by_value)]
147#[cfg_attr(feature = "uniffi", uniffi::export)]
148pub fn init_logging(
149    log_dir: Option<String>,
150    app_logger: Option<Box<dyn Logger>>,
151    log_filter: Option<String>,
152) -> Result<(), SdkError> {
153    logger::init_logging(log_dir.as_deref(), app_logger, log_filter.as_deref())
154}
155
156/// Connects to the Spark network using the provided configuration and mnemonic.
157///
158/// # Arguments
159///
160/// * `request` - The connection request object
161///
162/// # Returns
163///
164/// Result containing either the initialized `BreezSdk` or an `SdkError`
165#[cfg(feature = "sqlite")]
166#[cfg_attr(feature = "uniffi", uniffi::export(async_runtime = "tokio"))]
167pub async fn connect(request: crate::ConnectRequest) -> Result<BreezSdk, SdkError> {
168    let builder = super::sdk_builder::SdkBuilder::new(request.config, request.seed)
169        .with_default_storage(request.storage_dir);
170    let sdk = builder.build().await?;
171    Ok(sdk)
172}
173
174/// Connects to the Spark network using an external signer.
175///
176/// This method allows using a custom signer implementation instead of providing
177/// a seed directly.
178///
179/// # Arguments
180///
181/// * `request` - The connection request object with external signer
182///
183/// # Returns
184///
185/// Result containing either the initialized `BreezSdk` or an `SdkError`
186#[cfg(feature = "sqlite")]
187#[cfg_attr(feature = "uniffi", uniffi::export(async_runtime = "tokio"))]
188pub async fn connect_with_signer(
189    request: crate::ConnectWithSignerRequest,
190) -> Result<BreezSdk, SdkError> {
191    let builder = super::sdk_builder::SdkBuilder::new_with_signer(
192        request.config,
193        request.breez_signer,
194        request.spark_signer,
195    )
196    .with_default_storage(request.storage_dir);
197    let sdk = builder.build().await?;
198    Ok(sdk)
199}
200
201/// Connects to the Spark network using a signing-only external signer.
202///
203/// Use this instead of [`connect_with_signer`] for a signer that can't perform
204/// the SDK's local ECIES/HMAC operations (for example a policy-restricted
205/// enclave). The SDK keeps session tokens in plaintext and disables the features
206/// that rely on ECIES/HMAC.
207///
208/// # Arguments
209///
210/// * `request` - The connection request object with a signing-only external signer
211///
212/// # Returns
213///
214/// Result containing either the initialized `BreezSdk` or an `SdkError`
215#[cfg(feature = "sqlite")]
216#[cfg_attr(feature = "uniffi", uniffi::export(async_runtime = "tokio"))]
217pub async fn connect_with_signing_only_signer(
218    request: crate::ConnectWithSigningOnlySignerRequest,
219) -> Result<BreezSdk, SdkError> {
220    let builder = super::sdk_builder::SdkBuilder::new_with_signing_only_signer(
221        request.config,
222        request.breez_signer,
223        request.spark_signer,
224    )
225    .with_default_storage(request.storage_dir);
226    let sdk = builder.build().await?;
227    Ok(sdk)
228}
229
230#[cfg_attr(feature = "uniffi", uniffi::export)]
231pub fn default_config(network: Network) -> Config {
232    let lnurl_domain = match network {
233        Network::Mainnet => Some("breez.tips".to_string()),
234        Network::Signet | Network::Regtest => None,
235    };
236    Config {
237        api_key: None,
238        network,
239        sync_interval_secs: 60, // every 1 minute
240        max_deposit_claim_fee: Some(crate::MaxFee::Rate { sat_per_vbyte: 1 }),
241        lnurl_domain,
242        prefer_spark_over_lightning: false,
243        exit_chain_auto_fetch_enabled: true,
244        external_input_parsers: None,
245        use_default_external_input_parsers: true,
246        real_time_sync_server_url: Some(BREEZ_SYNC_SERVICE_URL.to_string()),
247        private_enabled_default: true,
248        leaf_optimization_config: LeafOptimizationConfig {
249            auto_enabled: true,
250            multiplicity: 1,
251        },
252        token_optimization_config: TokenOptimizationConfig {
253            auto_enabled: true,
254            target_output_count: 5,
255            min_outputs_threshold: 50,
256        },
257        stable_balance_config: None,
258        max_concurrent_claims: 4,
259        spark_config: match network {
260            Network::Mainnet | Network::Regtest => Some(default_spark_config(network)),
261            Network::Signet => None,
262        },
263        background_tasks_enabled: true,
264        proxy: None,
265        cross_chain_config: None,
266    }
267}
268
269/// Builds a [`Config`] suitable for multi-tenant server-mode deployments.
270///
271/// This preset returns the same configuration as [`default_config`] with
272/// [`background_tasks_enabled`](Config::background_tasks_enabled) set to
273/// `false`. In server mode, the SDK is treated as a library: the host
274/// orchestrates sync, claiming, and event delivery (typically via webhooks)
275/// explicitly, so an ephemeral SDK instance stays cheap and predictable.
276///
277/// Config fields whose background services are gated off are reset to their
278/// inactive shape: `real_time_sync_server_url` and `cross_chain_config` are
279/// set to `None`, and both `leaf_optimization_config.auto_enabled` and
280/// `token_optimization_config.auto_enabled` are set to `false`. The SDK
281/// rejects builds where `background_tasks_enabled` is `false` and any of
282/// those fields is left in its active shape, so flip the flag via this
283/// helper rather than by hand.
284///
285/// Explicit operations (`sync_wallet`, `claim_deposit`,
286/// `list_unclaimed_deposits`, `refund_deposit`,
287/// `refund_pending_conversions`, etc.) continue to work and are the intended
288/// entry points in this mode.
289///
290/// Stable Balance is not supported in this mode because its conversion worker
291/// is a background service.
292///
293/// One-time setup that the SDK normally applies automatically — notably
294/// `private_enabled_default` — is NOT applied in this mode. Drive setup
295/// explicitly via `update_user_settings` (and any other relevant APIs) so
296/// ephemeral per-request SDK instances incur no implicit setup overhead.
297///
298/// `get_info` reads balance directly from the spark wallet in this mode
299/// rather than from the background-maintained storage cache, so balance
300/// reflects the latest local sync and `ensure_synced=true` is rejected with
301/// an invalid-input error
302#[cfg_attr(feature = "uniffi", uniffi::export)]
303pub fn default_server_config(network: Network) -> Config {
304    let mut config = default_config(network);
305    config.background_tasks_enabled = false;
306    config.real_time_sync_server_url = None;
307    config.leaf_optimization_config.auto_enabled = false;
308    config.token_optimization_config.auto_enabled = false;
309    config.cross_chain_config = None;
310    config
311}
312
313/// Builds the default [`SparkConfig`](crate::models::SparkConfig) for the given network.
314///
315/// Surfaced through [`default_config`] as `Config::spark_config` so callers can read the
316/// baked-in operator and SSP endpoints and selectively override individual fields (e.g. to
317/// point at a staging environment) before passing the [`Config`] to [`connect`].
318fn default_spark_config(network: Network) -> crate::models::SparkConfig {
319    use crate::models::{SparkSigningOperator, SparkSspConfig};
320
321    let wallet_config = spark_wallet::SparkWalletConfig::default_config(network.into());
322
323    let coordinator_identifier = hex::encode(
324        wallet_config
325            .operator_pool
326            .get_coordinator()
327            .identifier
328            .serialize(),
329    );
330
331    let signing_operators = wallet_config
332        .operator_pool
333        .get_all_operators()
334        .map(|op| SparkSigningOperator {
335            id: u32::try_from(op.id).expect("operator id fits in u32"),
336            identifier: hex::encode(op.identifier.serialize()),
337            address: op.address.clone(),
338            identity_public_key: hex::encode(op.identity_public_key.serialize()),
339            ca_cert_pem: op
340                .ca_cert
341                .as_ref()
342                .and_then(|b| String::from_utf8(b.clone()).ok()),
343        })
344        .collect();
345
346    let ssp = &wallet_config.service_provider_config;
347
348    crate::models::SparkConfig {
349        coordinator_identifier,
350        threshold: wallet_config.split_secret_threshold,
351        signing_operators,
352        ssp_config: SparkSspConfig {
353            base_url: ssp.base_url.clone(),
354            identity_public_key: hex::encode(ssp.identity_public_key.serialize()),
355            schema_endpoint: ssp.schema_endpoint.clone(),
356        },
357        expected_withdraw_bond_sats: wallet_config.tokens_config.expected_withdraw_bond_sats,
358        expected_withdraw_relative_block_locktime: wallet_config
359            .tokens_config
360            .expected_withdraw_relative_block_locktime,
361        max_token_transaction_inputs: None,
362    }
363}
364
365/// The two default external signers created from one mnemonic by
366/// [`default_external_signers`].
367#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
368pub struct ExternalSigners {
369    /// External signer for non-Spark SDK signing (LNURL-auth, sync, message
370    /// signing, ECIES).
371    pub breez_signer: Arc<dyn crate::signer::ExternalBreezSigner>,
372    /// External high-level Spark signer for the Spark wallet flows.
373    pub spark_signer: Arc<dyn crate::signer::ExternalSparkSigner>,
374}
375
376/// A signing-only external signer paired with the Spark signer, for wallets that
377/// connect via [`connect_with_signing_only_signer`]. The Breez half performs
378/// signing only, without the SDK's local ECIES/HMAC operations.
379#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
380pub struct SigningOnlyExternalSigners {
381    /// Signing-only external signer for non-Spark SDK signing.
382    pub breez_signer: Arc<dyn crate::signer::ExternalSigningSigner>,
383    /// External high-level Spark signer for the Spark wallet flows.
384    pub spark_signer: Arc<dyn crate::signer::ExternalSparkSigner>,
385}
386
387/// Creates the default external signers from a mnemonic.
388///
389/// This is a convenience factory method for creating the two signer halves
390/// that can be passed to `connect_with_signer` or `SdkBuilder::new_with_signer`.
391/// Key derivation matches the seed-based connect path: an SDK built either way
392/// from the same mnemonic is the same wallet.
393///
394/// # Arguments
395///
396/// * `mnemonic` - BIP39 mnemonic phrase (12 or 24 words)
397/// * `passphrase` - Optional passphrase for the mnemonic
398/// * `network` - Network to use (Mainnet, Signet, or Regtest)
399/// * `account_number` - Account number in the derivation path. Unset uses the
400///   network default: 0 on Regtest and Signet, 1 on Mainnet.
401#[cfg_attr(feature = "uniffi", uniffi::export)]
402pub fn default_external_signers(
403    mnemonic: String,
404    passphrase: Option<String>,
405    network: Network,
406    account_number: Option<u32>,
407) -> Result<ExternalSigners, SdkError> {
408    use crate::signer::{DefaultExternalSigner, DefaultExternalSparkSigner};
409
410    let breez_signer = DefaultExternalSigner::new(
411        mnemonic.clone(),
412        passphrase.clone(),
413        network,
414        account_number,
415    )?;
416    let spark_signer =
417        DefaultExternalSparkSigner::new(mnemonic, passphrase, network, account_number)?;
418
419    Ok(ExternalSigners {
420        breez_signer: Arc::new(breez_signer),
421        spark_signer: Arc::new(spark_signer),
422    })
423}
424
425/// Options for [`get_spark_status`].
426#[derive(Debug, Clone, Default)]
427#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
428pub struct GetSparkStatusRequest {
429    /// Routes the status request through a SOCKS5 proxy. Pass the same value as
430    /// [`Config::proxy`]: this call runs without an SDK instance, so it cannot
431    /// pick the setting up on its own.
432    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
433    pub proxy: Option<crate::ProxyConfig>,
434}
435
436/// Fetches the current status of Spark network services relevant to the SDK.
437///
438/// This function queries the Spark status API and returns the worst status
439/// across the Spark Operators and SSP services.
440#[cfg_attr(feature = "uniffi", uniffi::export(async_runtime = "tokio"))]
441pub async fn get_spark_status(
442    request: GetSparkStatusRequest,
443) -> Result<crate::SparkStatus, SdkError> {
444    use chrono::DateTime;
445
446    #[derive(serde::Deserialize)]
447    struct StatusApiResponse {
448        services: Vec<StatusApiService>,
449        #[serde(rename = "lastUpdated")]
450        last_updated: String,
451    }
452
453    #[derive(serde::Deserialize)]
454    struct StatusApiService {
455        name: String,
456        status: String,
457    }
458
459    fn parse_service_status(s: &str) -> crate::ServiceStatus {
460        match s {
461            "operational" => crate::ServiceStatus::Operational,
462            "degraded" => crate::ServiceStatus::Degraded,
463            "partial" => crate::ServiceStatus::Partial,
464            "major" => crate::ServiceStatus::Major,
465            _ => {
466                tracing::warn!("Unknown service status: {s}");
467                crate::ServiceStatus::Unknown
468            }
469        }
470    }
471
472    let http_client = crate::ProxyConfig::http_client(request.proxy.as_ref(), None)?;
473
474    let response = http_client
475        .get("https://spark.money/api/v1/status".to_string(), None)
476        .await
477        .map_err(|e| SdkError::NetworkError(e.to_string()))?;
478
479    let api_response: StatusApiResponse = response
480        .json()
481        .map_err(|e| SdkError::Generic(format!("Failed to parse status response: {e}")))?;
482
483    let status = api_response
484        .services
485        .iter()
486        .filter(|s| s.name == "Spark Operators" || s.name == "SSP")
487        .map(|s| parse_service_status(&s.status))
488        .max()
489        .unwrap_or(crate::ServiceStatus::Unknown);
490
491    let last_updated = DateTime::parse_from_rfc3339(&api_response.last_updated)
492        .map(|dt| dt.timestamp().cast_unsigned())
493        .map_err(|e| SdkError::Generic(format!("Failed to parse lastUpdated timestamp: {e}")))?;
494
495    Ok(crate::SparkStatus {
496        status,
497        last_updated,
498    })
499}
500
501#[cfg(test)]
502mod tests {
503    use super::*;
504
505    #[test]
506    fn default_server_config_disables_background_tasks() {
507        for network in [Network::Mainnet, Network::Regtest, Network::Signet] {
508            let cfg = default_server_config(network);
509            assert!(!cfg.background_tasks_enabled);
510            assert!(cfg.real_time_sync_server_url.is_none());
511            assert!(!cfg.leaf_optimization_config.auto_enabled);
512            assert!(!cfg.token_optimization_config.auto_enabled);
513        }
514    }
515
516    #[test]
517    fn default_config_enables_background_tasks() {
518        assert!(default_config(Network::Mainnet).background_tasks_enabled);
519        assert!(default_config(Network::Regtest).background_tasks_enabled);
520        assert!(default_config(Network::Signet).background_tasks_enabled);
521    }
522}
breez_sdk_spark/sdk/mod.rs

breez_sdk_spark/sdk/
mod.rs
