breez_sdk_spark/cross_chain/

mod.rs

//! Cross-chain payment providers.
//!
//! The [`CrossChainService`] trait abstracts route discovery, quoting, and
//! sending. Each provider module (e.g. `orchestra`, `boltz`) implements it.

// Boltz is not registered as a provider (see `sdk_builder`): the service is not
// operational, and it is unclear when or whether it will be again. The modules
// stay in the tree behind the `boltz` feature so the wiring can be restored in
// one place.
#[cfg(feature = "boltz")]
#[allow(dead_code)]
pub(crate) mod boltz;
mod cached_fiat;
mod orchestra;

pub(crate) use cached_fiat::{CachedFiatService, DEFAULT_FIAT_CACHE_TTL};
pub(crate) use orchestra::{
    BreezServerOrchestraConfigResolver, DepositDestination, OrchestraQuoter, OrchestraService,
    delivery_method_from_wire, delivery_method_to_wire, parse_rfc3339_to_unix_seconds,
    to_route_limits,
};

use std::collections::HashMap;
use std::str::FromStr;
use std::sync::Arc;
use std::time::Duration;

use breez_sdk_common::fiat::FiatService;
use serde::{Deserialize, Serialize};
use spark_wallet::TransferId;

use crate::{
    ConversionInfo, CrossChainAddressDetails, PaymentDetails, error::SdkError,
    utils::conversions::extract_conversion_info,
};

/// SDK-level bounds for cross-chain slippage.
pub(crate) const MIN_CROSS_CHAIN_SLIPPAGE_BPS: u32 = 10;
pub(crate) const MAX_CROSS_CHAIN_SLIPPAGE_BPS: u32 = 500;
/// Used when neither the request nor [`crate::Config::default_slippage_bps`]
/// supplies a value.
pub(crate) const DEFAULT_CROSS_CHAIN_SLIPPAGE_BPS: u32 = 100;

/// Bounds for the target-overpay pad applied to the user's destination amount
/// on `FeesExcluded` conversion sends. `0` opts out. `500` caps at 5% (matches
/// the slippage upper bound).
pub(crate) const MIN_TARGET_OVERPAY_BPS: u32 = 0;
pub(crate) const MAX_TARGET_OVERPAY_BPS: u32 = 500;
/// Default pad applied when neither the request nor
/// [`crate::CrossChainConfig::default_target_overpay_bps`] specifies one.
/// Calibrated to the observed Orchestra delivery drift. Tune per provider
/// as real-world data accrues.
pub(crate) const DEFAULT_TARGET_OVERPAY_BPS: u32 = 15;
/// Tickers treated as $1-pegged for par-value rescaling. Adding a non-USD
/// ticker would silently misreport `fee_amount` for routes using it.
const USD_STABLE_ASSETS: &[&str] = &["USDB", "USDC", "USDT", "USDT0"];

/// Each provider's background monitor interval.
pub(crate) const MONITOR_INTERVAL: Duration = Duration::from_secs(30);

/// Serializes the conversion writes onto an inbound cross-chain receive. The
/// invoice match writes a Pending conversion when the payment is seen; the
/// provider monitor writes the Completed one and closes the receive row in
/// the same critical section. A match racing the monitor would otherwise
/// put Pending back for good.
static RECEIVE_CONVERSION_WRITES: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());

/// Links an inbound payment to the cross-chain receive whose Spark invoice it
/// fulfilled, writing a Pending conversion onto it. Returns whether it did.
/// Runs before the payment's status event so the event already carries the
/// conversion. A payment that already carries one is left alone.
pub(crate) async fn attach_receive_metadata_for_payment(
    storage: &Arc<dyn crate::Storage>,
    payment: &crate::Payment,
) -> Result<bool, SdkError> {
    if payment.payment_type != crate::PaymentType::Receive {
        return Ok(false);
    }
    let invoice = match &payment.details {
        Some(
            PaymentDetails::Spark {
                invoice_details: Some(details),
                ..
            }
            | PaymentDetails::Token {
                invoice_details: Some(details),
                ..
            },
        ) => &details.invoice,
        _ => return Ok(false),
    };

    let _serialized = RECEIVE_CONVERSION_WRITES.lock().await;
    let already_attached = storage
        .get_payment_by_id(payment.id.clone())
        .await
        .is_ok_and(|stored| extract_conversion_info(stored.details).is_some());
    if already_attached {
        return Ok(false);
    }
    let Some(conversion_info) = orchestra::link_receive_for_invoice(storage, invoice).await? else {
        return Ok(false);
    };
    storage
        .insert_payment_metadata(
            payment.id.clone(),
            crate::PaymentMetadata {
                conversion_info: Some(conversion_info),
                ..Default::default()
            },
        )
        .await?;
    Ok(true)
}

/// Attaches a cross-chain [`ConversionInfo`] to a freshly-converted
/// [`Payment`]. The payment's top-level `status` is left as-is: it reflects
/// the local Spark/Token/Lightning leg's settlement, while the cross-chain
/// pending state lives inside `conversion_info.status`.
pub(crate) fn payment_with_conversion_info(
    mut payment: crate::Payment,
    conversion_info: Option<ConversionInfo>,
) -> crate::Payment {
    payment.details = match payment.details {
        Some(PaymentDetails::Spark {
            invoice_details,
            htlc_details,
            ..
        }) => Some(PaymentDetails::Spark {
            invoice_details,
            htlc_details,
            conversion_info,
        }),
        Some(PaymentDetails::Token {
            metadata,
            tx_hash,
            tx_type,
            invoice_details,
            ..
        }) => Some(PaymentDetails::Token {
            metadata,
            tx_hash,
            tx_type,
            invoice_details,
            conversion_info,
        }),
        Some(PaymentDetails::Lightning {
            description,
            invoice,
            destination_pubkey,
            htlc_details,
            lnurl_pay_info,
            lnurl_withdraw_info,
            lnurl_receive_metadata,
            ..
        }) => Some(PaymentDetails::Lightning {
            description,
            invoice,
            destination_pubkey,
            htlc_details,
            lnurl_pay_info,
            lnurl_withdraw_info,
            lnurl_receive_metadata,
            conversion_info,
        }),
        other => other,
    };
    payment
}

/// Resolves the BTC-leg [`TransferId`] for a cross-chain send. A
/// caller-supplied `idempotency_key` from [`crate::SendPaymentRequest`]
/// wins so the top-level `get_payment_by_id(idempotency_key)` lookup in
/// `orchestrate_send` can short-circuit retries; otherwise we derive a
/// `UUIDv5` from `fallback_seed` (the provider's quote/swap id) so that
/// re-sending the same prepared shape still hits Spark's protocol-level
/// dedup. Mirrors the stable-balance per-receive convention. Token-source
/// sends ignore the return value: [`spark_wallet::transfer_tokens`] has
/// no idempotency hook.
pub(crate) fn derive_btc_leg_transfer_id(
    idempotency_key: Option<&str>,
    fallback_seed: &str,
) -> Result<TransferId, SdkError> {
    match idempotency_key {
        Some(key) => TransferId::from_str(key).map_err(SdkError::Generic),
        None => Ok(TransferId::from_name(fallback_seed)),
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum CrossChainProvider {
    Orchestra,
    /// Not operational: no routes are currently offered under this provider.
    Boltz,
}

impl std::fmt::Display for CrossChainProvider {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Orchestra => f.write_str("Orchestra"),
            Self::Boltz => f.write_str("Boltz"),
        }
    }
}

/// The asset a cross-chain route accepts on the Spark side.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum SparkAsset {
    /// Native BTC (sats).
    Bitcoin,
    /// A Spark token, identified by its bech32m `token_identifier` (e.g. `btkn1...`).
    Token { token_identifier: String },
}

/// Amount bounds a provider publishes for moving a route with one Spark-side
/// asset.
///
/// A route can enforce a tighter bound than it publishes, so an amount inside
/// these can still be rejected when the payment is prepared.
///
/// The two groups are independent, and either can be absent: a route may
/// publish a base-unit floor (a dust minimum on a sats-funded route), a USD
/// notional band, both, or neither.
///
/// `min_amount` / `max_amount` bound the asset that is paid in, so which asset
/// they are denominated in follows the direction: the Spark-side asset on a
/// send, the external asset on a receive. The USD band bounds the order's
/// value and reads the same in both directions.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CrossChainRouteLimits {
    /// Smallest amount accepted, in the base units of the asset paid in.
    pub min_amount: Option<u128>,
    /// Largest amount accepted, in the base units of the asset paid in.
    pub max_amount: Option<u128>,
    /// Smallest order value accepted, in USD cents.
    pub min_usd_cents: Option<u64>,
    /// Largest order value accepted, in USD cents.
    pub max_usd_cents: Option<u64>,
}

/// A Spark-side asset a route accepts, with the amount bounds that apply to it.
///
/// Bounds are per asset rather than per route: the same external endpoint can
/// carry a dust floor when moved as sats and none when moved as a token.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CrossChainAcceptedAsset {
    pub asset: SparkAsset,
    /// Unset when the provider publishes no bounds for this pairing.
    pub limits: Option<CrossChainRouteLimits>,
}

/// The rail a cross-chain payment is delivered over.
#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum DeliveryMethod {
    /// Delivered over the Spark network.
    Spark,
    /// Delivered over Lightning.
    Lightning,
    /// Delivered on-chain over Bitcoin.
    Bitcoin,
}

impl std::fmt::Display for DeliveryMethod {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Spark => f.write_str("Spark"),
            Self::Lightning => f.write_str("Lightning"),
            Self::Bitcoin => f.write_str("Bitcoin"),
        }
    }
}

/// Which side of the transfer the request `amount` sizes: what leaves the
/// payer, or what reaches the receiver.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum CrossChainFeeMode {
    /// `amount` sizes the receiving end, and fees are paid on top.
    ///
    /// Sending: `amount` is the provider invoice/deposit target, and the
    /// wallet pays `amount + source_transfer_fee_sats` in total.
    /// Receiving: `amount` is what the wallet ends up with, and the deposit
    /// the sender is asked for is sized above it to cover fees.
    FeesExcluded,
    /// `amount` sizes the paying end, and fees come out of it.
    ///
    /// Sending: `amount` is the wallet's total sats budget, and the provider
    /// leg is sized so `amount_in + source_transfer_fee_sats <= amount`.
    /// Receiving: `amount` is the deposit the sender makes, and the wallet
    /// ends up with that minus fees.
    FeesIncluded,
}

impl From<crate::FeePolicy> for CrossChainFeeMode {
    fn from(policy: crate::FeePolicy) -> Self {
        match policy {
            crate::FeePolicy::FeesExcluded => Self::FeesExcluded,
            crate::FeePolicy::FeesIncluded => Self::FeesIncluded,
        }
    }
}

/// Filter for [`CrossChainService::get_routes`] and the public
/// `get_cross_chain_routes()` API.
#[derive(Clone, Debug, Deserialize, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum CrossChainRouteFilter {
    /// Routes for sending to another chain, filtered by the parsed recipient
    /// address details.
    Send {
        address_details: CrossChainAddressDetails,
        /// Unset or `Spark` lists the routes paid from the Spark balance.
        /// `Lightning` lists the routes an external payer funds over
        /// Lightning. `Bitcoin` lists nothing.
        delivery_method: Option<DeliveryMethod>,
    },
    /// Routes for receiving from another chain, optionally filtered by the
    /// source token contract address.
    Receive {
        contract_address: Option<String>,
        /// Unset or `Spark` lists the routes that deliver to the Spark balance.
        /// `Lightning` lists the routes that pay out to a Lightning address.
        /// `Bitcoin` lists nothing.
        delivery_method: Option<DeliveryMethod>,
    },
    /// **Deprecated.** Use `Send` with the `Lightning` delivery method.
    ///
    /// Routes for a payment link that sends a stablecoin funded by Cash App
    /// over Lightning rather than the Spark wallet.
    PaymentLink {
        address_details: CrossChainAddressDetails,
    },
}

impl CrossChainRouteFilter {
    /// The equivalent filter without the deprecated `PaymentLink` variant.
    pub(crate) fn normalized(&self) -> Self {
        match self {
            Self::PaymentLink { address_details } => Self::Send {
                address_details: address_details.clone(),
                delivery_method: Some(DeliveryMethod::Lightning),
            },
            other => other.clone(),
        }
    }
}

/// A single route available for cross-chain transfers, tagged with the provider
/// that offers it. Returned by `get_cross_chain_routes()`.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CrossChainRoutePair {
    /// Which provider offers this route.
    pub provider: CrossChainProvider,
    /// External blockchain (e.g. `"base"`, `"solana"`, `"tron"`).
    pub chain: String,
    /// External chain identifier (e.g. EVM `chainId` as a decimal string).
    /// `None` for non-EVM chains that don't expose one, or when the
    /// provider doesn't surface it.
    pub chain_id: Option<String>,
    /// External asset symbol (e.g. `"USDC"`, `"USDT"`).
    pub asset: String,
    /// Token contract / mint address on the destination chain.
    pub contract_address: Option<String>,
    /// Decimal places for the destination asset.
    pub decimals: u8,
    /// Whether the route supports exact-out mode.
    pub exact_out_eligible: bool,
    /// Spark-side assets this route accepts, each with its own amount bounds.
    pub accepted_assets: Vec<CrossChainAcceptedAsset>,
    /// Rails this route can be delivered over, orthogonal to
    /// `accepted_assets` (the asset moved vs the rail moved on).
    pub delivery_methods: Vec<DeliveryMethod>,
}

impl CrossChainRoutePair {
    /// The bounds published for moving this route with `asset`, if the route
    /// accepts it at all.
    pub fn limits_for(&self, asset: &SparkAsset) -> Option<&CrossChainRouteLimits> {
        self.accepted_assets
            .iter()
            .find(|a| &a.asset == asset)
            .and_then(|a| a.limits.as_ref())
    }

    /// Whether `asset` is one of the Spark-side assets this route accepts.
    pub fn accepts_asset(&self, asset: &SparkAsset) -> bool {
        self.accepted_assets.iter().any(|a| &a.asset == asset)
    }

    /// Infers the destination address family from the route's
    /// `contract_address`. Returns `None` for native-asset routes (no
    /// contract address) or if the address format isn't recognized; callers
    /// should treat that as "skip the address-family validation".
    pub(crate) fn destination_address_family(
        &self,
    ) -> Option<breez_sdk_common::input::CrossChainAddressFamily> {
        self.contract_address
            .as_deref()
            .and_then(breez_sdk_common::input::detect_address_family)
    }
}

/// Per-provider service registry plus shared cross-chain dependencies (today:
/// the cached `FiatService`). Keeping the cache here scopes it to cross-chain
/// flows; `sdk.fiat_service` stays uncached for general fiat consumers.
#[derive(Clone)]
pub(crate) struct CrossChainContext {
    providers: HashMap<CrossChainProvider, Arc<dyn CrossChainService>>,
    fiat_service: Arc<dyn FiatService>,
    /// The Orchestra quoter, if one was set.
    orchestra_quoter: Option<Arc<OrchestraQuoter>>,
}

impl CrossChainContext {
    pub fn new(fiat_service: Arc<dyn FiatService>) -> Self {
        Self {
            providers: HashMap::new(),
            fiat_service,
            orchestra_quoter: None,
        }
    }

    pub fn insert(&mut self, key: CrossChainProvider, service: Arc<dyn CrossChainService>) {
        self.providers.insert(key, service);
    }

    pub fn set_orchestra_quoter(&mut self, quoter: Arc<OrchestraQuoter>) {
        self.orchestra_quoter = Some(quoter);
    }

    /// The Orchestra quoter, if one was set.
    pub fn orchestra_quoter(&self) -> Option<&Arc<OrchestraQuoter>> {
        self.orchestra_quoter.as_ref()
    }

    /// Fails with [`SdkError::CrossChainDisabled`] when no provider is
    /// registered, which happens only when `cross_chain_config` is unset.
    pub fn ensure_enabled(&self) -> Result<(), SdkError> {
        if self.providers.is_empty() {
            return Err(SdkError::cross_chain_disabled());
        }
        Ok(())
    }

    /// Look up a provider, returning a friendly error if missing.
    pub fn get(
        &self,
        provider: CrossChainProvider,
    ) -> Result<&Arc<dyn CrossChainService>, SdkError> {
        self.ensure_enabled()?;
        self.providers.get(&provider).ok_or_else(|| {
            SdkError::InvalidInput(format!("Cross-chain provider {provider} is not available."))
        })
    }

    pub fn values(&self) -> impl Iterator<Item = &Arc<dyn CrossChainService>> {
        self.providers.values()
    }

    /// Every provider's routes for `filter`, limited to USD-pegged assets and
    /// sorted. A provider whose listing fails is logged and left out.
    pub async fn list_routes(
        &self,
        filter: &CrossChainRouteFilter,
    ) -> Result<Vec<CrossChainRoutePair>, SdkError> {
        self.ensure_enabled()?;
        let filter = &filter.normalized();
        let mut all_routes = Vec::new();
        for svc in self.values() {
            match svc.get_routes(filter).await {
                Ok(routes) => all_routes.extend(routes),
                Err(e) => tracing::warn!("Cross-chain provider route fetch failed: {e}"),
            }
        }

        // Filter to USD-pegged destinations only.
        all_routes.retain(|r| is_usd_stable_asset(&r.asset));

        all_routes.sort_by(|a, b| {
            a.asset
                .cmp(&b.asset)
                .then_with(|| a.chain.cmp(&b.chain))
                .then_with(|| a.provider.cmp(&b.provider))
        });
        Ok(all_routes)
    }

    /// Cached fiat service shared with every cross-chain provider. Read
    /// through this on the prepare path so the TTL window is shared.
    pub fn fiat_service(&self) -> &Arc<dyn FiatService> {
        &self.fiat_service
    }
}

/// Provider-internal state produced by `prepare` and consumed by `send`.
/// Typed per provider so the send stage can resume without re-quoting and
/// without a serde round-trip. Callers should round-trip this value as-is.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum CrossChainProviderContext {
    Orchestra {
        /// Orchestra quote id, passed back on `/submit`.
        quote_id: String,
        /// Spark address Orchestra expects the deposit transfer to land on.
        deposit_address: String,
        /// Spark-side deposit amount in the route's source-asset base units.
        #[serde(default)]
        deposit_amount: u128,
    },
    Boltz {
        /// Boltz swap id.
        swap_id: String,
        /// Hold invoice to pay.
        invoice: String,
        /// Hold invoice amount in sats.
        #[serde(default)]
        invoice_amount_sats: u64,
        /// Slippage tolerance in basis points.
        max_slippage_bps: u32,
    },
}

/// Prepared cross-chain receive: the payment request to hand to the sender
/// and the receive-quote details. For a receive into this wallet, the provider
/// row is already persisted by the time this returns.
#[derive(Debug, Clone)]
pub(crate) struct CrossChainReceivePrepared {
    /// Canonical cross-chain URI the sender can paste or scan to pay.
    pub payment_request: String,
    pub info: CrossChainReceiveInfo,
    /// Provider token for reading the quote's status, when it issued one.
    pub quote_read_token: Option<String>,
}

/// Information about the cross-chain receive quote: what the sender deposits
/// and what the receiver is expected to get.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CrossChainReceiveInfo {
    /// The provider's id for this receive. The incoming payment carries the
    /// same id in its conversion info, so it can be matched to this receive.
    pub quote_id: String,
    /// Bare deposit address the sender pays to on the source chain, or the
    /// BOLT11 invoice when the sender pays over Lightning.
    pub deposit_address: String,
    /// Amount the sender must deposit, in source-asset base units
    /// (`route.decimals`, or sats over Lightning). On `FeesExcluded` this may
    /// differ from the request's `amount` because the SDK inflates the deposit
    /// to absorb provider fees. Render this value to the sender.
    pub deposit_amount: u128,
    /// Amount the receiver will see, net of provider fees, in
    /// destination-asset base units. Sats when receiving BTC, token base
    /// units when receiving a Spark token (e.g. USDB), or stablecoin base
    /// units when the receiver is on another chain. The final delivered
    /// amount may move within the slippage tolerance.
    pub expected_received_amount: u128,
    /// Symbol of the asset `expected_received_amount` is denominated in, as
    /// the provider reports it: `"BTC"` for sats, a Spark token symbol (e.g.
    /// `"USDB"`), or the stablecoin when the receiver is on another chain.
    pub destination_asset: String,
    /// Spark token identifier when the destination is a Spark token. Absent
    /// otherwise.
    pub token_identifier: Option<String>,
    /// Provider-quoted total fee for this receive, including the partner fee
    /// when one is set, in `service_fee_asset` units.
    pub service_fee_amount: u128,
    /// Ticker for `service_fee_amount`. Absent when the fee is denominated
    /// in sats.
    pub service_fee_asset: Option<String>,
    /// Decimals of `service_fee_asset`, for formatting `service_fee_amount`.
    /// Unset when the fee is in sats or the provider did not report them.
    pub service_fee_asset_decimals: Option<u32>,
    /// Quote expiry as a unix timestamp in seconds.
    pub expires_at: u64,
}

/// Data stashed on the prepared send payment so the provider can resume
/// the send stage without re-quoting.
#[derive(Debug, Clone)]
pub(crate) struct CrossChainSendPrepared {
    pub amount_in: u128,
    /// `amount_in` expressed in the cross-chain (destination) asset's base
    /// units, via the fiat rate or decimal rescale the SDK used at prepare
    /// time.
    pub asset_amount_in: u128,
    /// Amount the recipient will receive, in cross-chain asset base units.
    pub estimated_out: u128,
    /// Total user-visible fee in cross-chain asset base units. Covers provider
    /// spread, bridge/gas, and DEX slippage. On the token-conversion path it
    /// also rolls in the LN routing budget; on the direct path that budget
    /// lives separately in `source_transfer_fee_sats`. The dispatcher
    /// overrides this on the conversion path to reflect the token-side debit.
    pub fee_amount: u128,
    /// Provider service fee, including the partner fee when one is set, in
    /// `service_fee_asset` base units.
    pub service_fee_amount: u128,
    /// Asset that the service fee is denominated in. Unset means BTC sats.
    pub service_fee_asset: Option<String>,
    /// Decimals of `service_fee_asset`. Unset for sats or when unreported.
    pub service_fee_asset_decimals: Option<u32>,
    /// Sats cost to the wallet of moving `amount_in` from the wallet to the
    /// provider. For Boltz: the Lightning routing fee budget for paying the
    /// hold invoice (a budget, not a central estimate — enforced as a hard
    /// cap at send time). For Orchestra: the Spark transfer fee (0 today;
    /// non-zero in the future).
    ///
    /// Semantically distinct from `fee_amount` (provider's service fee /
    /// spread) and from destination-chain costs (baked into `estimated_out`).
    /// Denominated in sats — the field assumes a sats-denominated source leg.
    pub source_transfer_fee_sats: u64,
    /// Fee mode the prepare was called with. Needed at send time so the
    /// provider knows whether to apply FeesIncluded-style overpayment.
    pub fee_mode: CrossChainFeeMode,
    pub expires_at: String,
    pub pair: CrossChainRoutePair,
    pub recipient_address: String,
    /// The `token_identifier` on the Spark source (e.g. USDB). `None` for BTC sats.
    pub token_identifier: Option<String>,
    /// Provider-internal state carried between `prepare` and `send`.
    pub provider_context: CrossChainProviderContext,
    /// Provider token for reading the quote's status, when it issued one.
    pub quote_read_token: Option<String>,
}

/// Abstraction over cross-chain bridge/swap providers.
///
/// Each implementation owns its own client, caching, and background monitoring.
/// The SDK dispatches to the provider via this trait.
#[allow(clippy::too_many_arguments)]
#[macros::async_trait]
pub(crate) trait CrossChainService: Send + Sync {
    /// Returns the available cross-chain route pairs.
    ///
    /// The returned [`CrossChainRoutePair`] always describes the non-Spark
    /// side of the route. The [`CrossChainRouteFilter`] controls direction
    /// and optional filtering.
    async fn get_routes(
        &self,
        filter: &CrossChainRouteFilter,
    ) -> Result<Vec<CrossChainRoutePair>, SdkError>;

    /// Fetch a quote for a cross-chain send or Lightning onramp. `amount` is
    /// always in the source-leg sats/token base units. The caller converts any
    /// USD intent to sats first. `delivery_method` selects the rail the wallet
    /// dispatches over. `None` uses the provider's default
    /// ([`DeliveryMethod::Spark`] for Orchestra). `source_token_identifier`
    /// is only meaningful for a Spark source (`None` = BTC sats, `Some` = a
    /// token).
    #[allow(clippy::too_many_arguments)]
    async fn prepare_send(
        &self,
        recipient_address: &str,
        route: &CrossChainRoutePair,
        amount: u128,
        delivery_method: Option<DeliveryMethod>,
        source_token_identifier: Option<String>,
        max_slippage_bps: u32,
        fee_mode: CrossChainFeeMode,
    ) -> Result<CrossChainSendPrepared, SdkError>;

    /// Fetch a quote for a cross-chain receive.
    ///
    /// `amount` is the caller's raw ask, always:
    /// - `FeesExcluded`: net amount the receiver wants to land on the Spark
    ///   side, in `destination`'s base units (sats for BTC, token base units
    ///   for tokens). The provider inflates by `target_overpay_bps` when
    ///   sizing the deposit but drift-checks against `amount` itself, so the
    ///   overpay gives Orchestra headroom without tightening the accept
    ///   threshold beyond what the user asked for.
    /// - `FeesIncluded`: the deposit the sender will pay, in the route's
    ///   source-asset base units. The receiver lands `amount - fees`.
    ///   `target_overpay_bps` is ignored.
    ///
    /// `delivery_method` is the rail the funds arrive on:
    /// [`DeliveryMethod::Spark`] pays `recipient_address` as a Spark address,
    /// [`DeliveryMethod::Lightning`] as a Lightning address. A wallet-bound
    /// implementation receives over Spark into its own wallet and tracks the
    /// receive. `refund_address` is where the provider returns the deposit if
    /// delivery fails.
    #[allow(clippy::too_many_arguments)]
    async fn prepare_receive(
        &self,
        route: &CrossChainRoutePair,
        recipient_address: &str,
        amount: u128,
        max_slippage_bps: u32,
        // Pre-validated Spark-side destination: the SDK dispatch has
        // checked this against `route.accepted_assets` and resolved any
        // wallet-level defaults (e.g. active stable balance).
        destination: &SparkAsset,
        fee_mode: CrossChainFeeMode,
        target_overpay_bps: u32,
        delivery_method: DeliveryMethod,
        refund_address: Option<&str>,
    ) -> Result<CrossChainReceivePrepared, SdkError>;

    /// Execute the send: transfer funds to the deposit address, submit to
    /// the provider, persist metadata, monitor to terminal, and return the
    /// resulting [`Payment`].
    ///
    /// `idempotency_key` is the caller-provided key from `SendPaymentRequest`.
    /// Providers should use it as the underlying Spark `TransferId` so the
    /// outbound transfer is protocol-level idempotent on retry; if `None`,
    /// the provider derives a deterministic key from its own quote/swap id
    /// (same shape as the stable-balance per-receive convention). Only the
    /// BTC-source branch benefits — token transfers have no upstream
    /// idempotency hook, and the top-level dispatcher already rejects
    /// idempotency keys for token-source sends.
    ///
    /// Each provider owns the polling-to-terminal step internally — the
    /// SDK dispatcher does not wrap this with an additional wait.
    async fn send(
        &self,
        prepared: &CrossChainSendPrepared,
        idempotency_key: Option<String>,
    ) -> Result<crate::Payment, SdkError>;
}

/// Fetches the BTC/USD rate from the Breez Server fiat feed. Errors if the
/// feed is unreachable, missing the USD entry, or returns a non-finite value.
pub(crate) async fn fetch_btc_usd_rate(fiat: &dyn FiatService) -> Result<f64, SdkError> {
    let rates = fiat
        .fetch_fiat_rates()
        .await
        .map_err(|e| SdkError::Generic(format!("Cross-chain: failed to fetch fiat rates: {e}")))?;
    let btc_usd = rates
        .iter()
        .find(|r| r.coin.eq_ignore_ascii_case("USD"))
        .map(|r| r.value)
        .ok_or_else(|| {
            SdkError::Generic("Cross-chain: BTC/USD rate not found in feed".to_string())
        })?;
    if !btc_usd.is_finite() || btc_usd <= 0.0 {
        return Err(SdkError::Generic(format!(
            "Cross-chain: invalid BTC/USD rate from feed: {btc_usd}"
        )));
    }
    Ok(btc_usd)
}

/// `sats * fiat_rate * 10^dest_decimals / 10^8`. Sub-base-unit truncation
/// is absorbed by the route's slippage tolerance.
#[allow(
    clippy::cast_precision_loss,
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss
)]
pub(crate) fn convert_sats_to_destination_amount(
    sats: u128,
    fiat_rate: f64,
    dest_decimals: u32,
) -> Result<u128, SdkError> {
    let dest_scale = 10f64.powi(i32::try_from(dest_decimals).unwrap_or(i32::MAX));
    let target = (sats as f64) * fiat_rate * dest_scale / 100_000_000f64;
    if !target.is_finite() || target < 0.0 {
        return Err(SdkError::Generic(format!(
            "Cross-chain: invalid sats→dest conversion result: {target}"
        )));
    }
    Ok(target as u128)
}

/// Converts a source-asset amount (base units at `src_decimals`) to sats
/// via `fiat_per_btc`. Assumes the source is denominated 1:1 in the same
/// fiat as the rate. Inverse of [`convert_sats_to_destination_amount`].
#[allow(
    clippy::cast_precision_loss,
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss
)]
pub(crate) fn convert_source_amount_to_sats(
    src_base_units: u128,
    src_decimals: u32,
    fiat_per_btc: f64,
) -> Result<u128, SdkError> {
    let src_scale = 10f64.powi(i32::try_from(src_decimals).unwrap_or(i32::MAX));
    let sats = (src_base_units as f64) * 100_000_000f64 / (src_scale * fiat_per_btc);
    if !sats.is_finite() || sats < 0.0 {
        return Err(SdkError::Generic(format!(
            "Cross-chain: invalid stable→sats conversion result: {sats}"
        )));
    }
    Ok(sats as u128)
}

/// Rejects a route that lists its delivery methods without `delivery_method`.
/// A hand-built route without delivery methods is accepted.
pub(crate) fn ensure_route_delivers_over(
    route: &CrossChainRoutePair,
    delivery_method: DeliveryMethod,
) -> Result<(), SdkError> {
    if !route.delivery_methods.is_empty() && !route.delivery_methods.contains(&delivery_method) {
        return Err(SdkError::InvalidInput(format!(
            "The selected route doesn't support {delivery_method}"
        )));
    }
    Ok(())
}

pub(crate) fn is_usd_stable_asset(asset: &str) -> bool {
    USD_STABLE_ASSETS
        .iter()
        .any(|a| asset.eq_ignore_ascii_case(a))
}

/// Builds the payment-request URI a sender pays to for a cross-chain
/// receive. EVM destinations get an EIP-681 URI so wallets like `MetaMask`
/// auto-fill recipient/token/chain/amount. Solana and Tron destinations
/// fall back to the bare `deposit_address` because current wallets don't
/// honor those schemes' parameters reliably (see
/// [`breez_sdk_common::input::format_cross_chain_uri`]).
pub(crate) fn build_receive_payment_request(
    deposit_address: &str,
    chain: &str,
    chain_id: Option<&str>,
    contract_address: Option<&str>,
    amount: u128,
) -> Result<String, SdkError> {
    let family =
        breez_sdk_common::input::detect_address_family(deposit_address).ok_or_else(|| {
            SdkError::Generic(format!(
                "Cross-chain provider returned unrecognised deposit address: {deposit_address}",
            ))
        })?;
    // Guard against a provider returning an address that belongs to a
    // different chain family than the route we requested.
    if !family.matches_chain(chain, contract_address) {
        return Err(SdkError::Generic(format!(
            "Cross-chain provider returned {family:?} deposit address for {chain} route"
        )));
    }
    Ok(breez_sdk_common::input::format_cross_chain_uri(
        family,
        deposit_address,
        contract_address,
        chain_id,
        amount,
    ))
}

/// Best-available fee: realized `asset_amount_in − delivered_amount` on
/// `Completed`, else the prepare-time estimate. Refunded/failed keep the
/// estimate (the realized formula would be misleading).
pub(crate) fn compute_terminal_fee_amount(
    new_status: &crate::ConversionStatus,
    asset_amount_in: Option<u128>,
    delivered_amount: Option<u128>,
    prepare_estimate: Option<u128>,
) -> Option<u128> {
    match (new_status, asset_amount_in, delivered_amount) {
        (crate::ConversionStatus::Completed, Some(a), Some(d)) => Some(a.saturating_sub(d)),
        _ => prepare_estimate,
    }
}

/// Rescales an amount between two base-unit precisions. Assumes
/// `1 source unit ≈ 1 dest unit` at face value — only valid for USD-stable
/// pairs. Errors on overflow.
pub(crate) fn rescale_decimals(
    amount: u128,
    src_decimals: u32,
    dest_decimals: u32,
) -> Result<u128, SdkError> {
    if dest_decimals >= src_decimals {
        let delta = dest_decimals.saturating_sub(src_decimals);
        let factor = 10u128
            .checked_pow(delta)
            .ok_or_else(|| SdkError::Generic("Cross-chain: decimal scale overflow".to_string()))?;
        amount
            .checked_mul(factor)
            .ok_or_else(|| SdkError::Generic("Cross-chain: decimal rescale overflow".to_string()))
    } else {
        let delta = src_decimals.saturating_sub(dest_decimals);
        let factor = 10u128
            .checked_pow(delta)
            .ok_or_else(|| SdkError::Generic("Cross-chain: decimal scale overflow".to_string()))?;
        amount.checked_div(factor).ok_or_else(|| {
            SdkError::Generic("Cross-chain: decimal rescale divisor zero".to_string())
        })
    }
}

/// Inverse of [`convert_sats_to_destination_amount`]: returns the sats whose
/// fiat-equivalent matches the given USD-stable `destination_amount`.
/// Errors on a non-positive `fiat_rate`.
#[allow(
    clippy::cast_precision_loss,
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss
)]
pub(crate) fn convert_destination_amount_to_sats(
    destination_amount: u128,
    fiat_rate: f64,
    dest_decimals: u32,
) -> Result<u128, SdkError> {
    if !fiat_rate.is_finite() || fiat_rate <= 0.0 {
        return Err(SdkError::Generic(format!(
            "Cross-chain: invalid BTC/USD rate for inversion: {fiat_rate}"
        )));
    }
    let dest_scale = 10f64.powi(i32::try_from(dest_decimals).unwrap_or(i32::MAX));
    let sats = (destination_amount as f64) * 100_000_000f64 / (fiat_rate * dest_scale);
    if !sats.is_finite() || sats < 0.0 {
        return Err(SdkError::Generic(format!(
            "Cross-chain: invalid dest→sats conversion result: {sats}"
        )));
    }
    Ok(sats as u128)
}

/// Resolves the target-overpay bps to apply on `FeesExcluded` cross-chain
/// preparations (send and receive). Same precedence as slippage:
/// caller-supplied value (bounds-checked here), then the config default, then
/// the built-in default. Config defaults are validated at SDK startup in
/// `Config::validate`.
pub(crate) fn resolve_target_overpay_bps(
    requested: Option<u32>,
    config_default: Option<u32>,
) -> Result<u32, SdkError> {
    if let Some(bps) = requested
        && !(MIN_TARGET_OVERPAY_BPS..=MAX_TARGET_OVERPAY_BPS).contains(&bps)
    {
        return Err(SdkError::InvalidInput(format!(
            "target_overpay_bps {bps} must be in \
             {MIN_TARGET_OVERPAY_BPS} to {MAX_TARGET_OVERPAY_BPS}",
        )));
    }
    Ok(requested
        .or(config_default)
        .unwrap_or(DEFAULT_TARGET_OVERPAY_BPS))
}

/// Inflates a target amount by `overpay_bps` so the realized delivery lands at
/// or above target despite provider slippage. `overpay_bps == 0` is identity.
/// Used on both directions: send pads the destination target, receive pads
/// the source-asset deposit.
pub(crate) fn inflate_target_amount(amount: u128, overpay_bps: u32) -> u128 {
    if overpay_bps == 0 {
        return amount;
    }
    amount.saturating_add(amount.saturating_mul(u128::from(overpay_bps)) / 10_000)
}

#[cfg(test)]
mod tests {
    use super::*;
    use macros::test_all;

    #[cfg(feature = "browser-tests")]
    wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);

    struct NoFiat;

    #[macros::async_trait]
    impl FiatService for NoFiat {
        async fn fetch_fiat_currencies(
            &self,
        ) -> Result<
            Vec<breez_sdk_common::fiat::FiatCurrency>,
            breez_sdk_common::error::ServiceConnectivityError,
        > {
            Ok(Vec::new())
        }

        async fn fetch_fiat_rates(
            &self,
        ) -> Result<
            Vec<breez_sdk_common::fiat::Rate>,
            breez_sdk_common::error::ServiceConnectivityError,
        > {
            Ok(Vec::new())
        }
    }

    struct StubProvider;

    #[macros::async_trait]
    impl CrossChainService for StubProvider {
        async fn get_routes(
            &self,
            _filter: &CrossChainRouteFilter,
        ) -> Result<Vec<CrossChainRoutePair>, SdkError> {
            unimplemented!()
        }

        async fn prepare_send(
            &self,
            _recipient_address: &str,
            _route: &CrossChainRoutePair,
            _amount: u128,
            _delivery_method: Option<DeliveryMethod>,
            _source_token_identifier: Option<String>,
            _max_slippage_bps: u32,
            _fee_mode: CrossChainFeeMode,
        ) -> Result<CrossChainSendPrepared, SdkError> {
            unimplemented!()
        }

        async fn prepare_receive(
            &self,
            _route: &CrossChainRoutePair,
            _recipient_address: &str,
            _amount: u128,
            _max_slippage_bps: u32,
            _destination: &SparkAsset,
            _fee_mode: CrossChainFeeMode,
            _target_overpay_bps: u32,
            _delivery_method: DeliveryMethod,
            _refund_address: Option<&str>,
        ) -> Result<CrossChainReceivePrepared, SdkError> {
            unimplemented!()
        }

        async fn send(
            &self,
            _prepared: &CrossChainSendPrepared,
            _idempotency_key: Option<String>,
        ) -> Result<crate::Payment, SdkError> {
            unimplemented!()
        }
    }

    fn evm_address_details() -> crate::CrossChainAddressDetails {
        crate::CrossChainAddressDetails {
            address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e".to_string(),
            address_family: crate::CrossChainAddressFamily::Evm,
            contract_address: None,
            chain_id: None,
            amount: None,
        }
    }

    #[test_all]
    fn empty_context_reports_cross_chain_disabled() {
        let context = CrossChainContext::new(Arc::new(NoFiat));
        assert!(matches!(
            context.ensure_enabled(),
            Err(SdkError::CrossChainDisabled { .. })
        ));
        assert!(matches!(
            context.get(CrossChainProvider::Orchestra),
            Err(SdkError::CrossChainDisabled { .. })
        ));
    }

    #[test_all]
    fn enabled_context_reports_missing_provider() {
        let mut context = CrossChainContext::new(Arc::new(NoFiat));
        context.insert(CrossChainProvider::Orchestra, Arc::new(StubProvider));
        assert!(context.ensure_enabled().is_ok());
        assert!(context.get(CrossChainProvider::Orchestra).is_ok());
        assert!(matches!(
            context.get(CrossChainProvider::Boltz),
            Err(SdkError::InvalidInput(_))
        ));
    }

    #[test_all]
    fn route_filter_normalizes_payment_link_to_lightning_send() {
        let filter = CrossChainRouteFilter::PaymentLink {
            address_details: evm_address_details(),
        };
        let CrossChainRouteFilter::Send {
            address_details,
            delivery_method,
        } = filter.normalized()
        else {
            panic!("expected a send filter");
        };
        assert_eq!(address_details.address, evm_address_details().address);
        assert_eq!(delivery_method, Some(DeliveryMethod::Lightning));
    }

    #[test_all]
    fn ensure_route_delivers_over_checks_listed_methods() {
        let route = |delivery_methods: Vec<DeliveryMethod>| CrossChainRoutePair {
            provider: CrossChainProvider::Orchestra,
            chain: "base".to_string(),
            chain_id: None,
            asset: "USDC".to_string(),
            contract_address: None,
            decimals: 6,
            exact_out_eligible: false,
            accepted_assets: Vec::new(),
            delivery_methods,
        };
        let spark = route(vec![DeliveryMethod::Spark]);
        let lightning = route(vec![DeliveryMethod::Lightning]);
        let unlisted = route(Vec::new());

        assert!(ensure_route_delivers_over(&spark, DeliveryMethod::Spark).is_ok());
        assert!(matches!(
            ensure_route_delivers_over(&lightning, DeliveryMethod::Spark),
            Err(SdkError::InvalidInput(_))
        ));
        assert!(ensure_route_delivers_over(&lightning, DeliveryMethod::Lightning).is_ok());
        assert!(ensure_route_delivers_over(&unlisted, DeliveryMethod::Spark).is_ok());
    }

    #[test_all]
    fn delivery_method_display_is_human_readable() {
        assert_eq!(DeliveryMethod::Spark.to_string(), "Spark");
        assert_eq!(DeliveryMethod::Lightning.to_string(), "Lightning");
        assert_eq!(DeliveryMethod::Bitcoin.to_string(), "Bitcoin");
    }

    #[test_all]
    fn derive_btc_leg_transfer_id_uses_caller_key() {
        // A v4 UUID is a valid TransferId — using one here checks that the
        // caller-supplied key wins outright.
        let key = "00000000-0000-4000-8000-000000000001";
        let id = derive_btc_leg_transfer_id(Some(key), "ignored-seed").unwrap();
        assert_eq!(id.to_string(), key);
    }

    #[test_all]
    fn derive_btc_leg_transfer_id_deterministic_from_seed() {
        let a = derive_btc_leg_transfer_id(None, "cross_chain:orchestra:quote-1").unwrap();
        let b = derive_btc_leg_transfer_id(None, "cross_chain:orchestra:quote-1").unwrap();
        assert_eq!(
            a, b,
            "same seed must produce the same TransferId across calls"
        );
    }

    #[test_all]
    fn derive_btc_leg_transfer_id_distinct_seeds_yield_distinct_ids() {
        let a = derive_btc_leg_transfer_id(None, "cross_chain:orchestra:quote-1").unwrap();
        let b = derive_btc_leg_transfer_id(None, "cross_chain:orchestra:quote-2").unwrap();
        assert_ne!(a, b);
    }

    #[test_all]
    fn derive_btc_leg_transfer_id_orchestra_and_boltz_seeds_collide_only_on_id() {
        // The provider tag in the seed prevents an Orchestra `quote-1` and a
        // hypothetical Boltz `quote-1` from colliding on the same TransferId.
        let orchestra = derive_btc_leg_transfer_id(None, "cross_chain:orchestra:abc").unwrap();
        let boltz = derive_btc_leg_transfer_id(None, "cross_chain:boltz:abc").unwrap();
        assert_ne!(orchestra, boltz);
    }

    #[test_all]
    fn derive_btc_leg_transfer_id_rejects_invalid_caller_key() {
        let err = derive_btc_leg_transfer_id(Some("not-a-uuid"), "fallback").unwrap_err();
        assert!(matches!(err, SdkError::Generic(_)));
    }

    #[test_all]
    fn convert_sats_to_destination_amount_round_trip_inverts_to_sats() {
        // 10_000 sats at $60_000/BTC → $6.00 = 6_000_000 USDC base units.
        let dest = convert_sats_to_destination_amount(10_000, 60_000.0, 6).unwrap();
        assert_eq!(dest, 6_000_000);
        // Inverse must recover the source sats.
        let sats = convert_destination_amount_to_sats(dest, 60_000.0, 6).unwrap();
        assert_eq!(sats, 10_000);
    }

    #[test_all]
    fn convert_destination_amount_to_sats_typical_stable() {
        // 1 USDC ($1.00 = 1_000_000 base units) at $60_000/BTC → 1666 sats (floor).
        let sats = convert_destination_amount_to_sats(1_000_000, 60_000.0, 6).unwrap();
        assert_eq!(sats, 1_666);
    }

    #[test_all]
    fn convert_destination_amount_to_sats_zero_passes_through() {
        let sats = convert_destination_amount_to_sats(0, 60_000.0, 6).unwrap();
        assert_eq!(sats, 0);
    }

    #[test_all]
    fn convert_destination_amount_to_sats_rejects_non_positive_rate() {
        let err = convert_destination_amount_to_sats(1_000_000, 0.0, 6).unwrap_err();
        assert!(matches!(err, SdkError::Generic(ref m) if m.contains("invalid BTC/USD rate")));
        let err = convert_destination_amount_to_sats(1_000_000, f64::NAN, 6).unwrap_err();
        assert!(matches!(err, SdkError::Generic(_)));
    }

    #[test_all]
    fn rescale_decimals_scales_down_when_dest_decimals_lower() {
        assert_eq!(rescale_decimals(100_000_000, 8, 6).unwrap(), 1_000_000);
    }

    #[test_all]
    fn rescale_decimals_same_decimals_is_identity() {
        assert_eq!(rescale_decimals(123_456_789, 6, 6).unwrap(), 123_456_789);
    }

    #[test_all]
    fn rescale_decimals_scales_up_when_dest_decimals_higher() {
        assert_eq!(rescale_decimals(1_000_000, 6, 8).unwrap(), 100_000_000);
    }

    #[test_all]
    fn rescale_decimals_zero_passes_through() {
        assert_eq!(rescale_decimals(0, 8, 6).unwrap(), 0);
        assert_eq!(rescale_decimals(0, 6, 8).unwrap(), 0);
    }

    #[test_all]
    fn is_usd_stable_asset_recognizes_known_stables() {
        for ticker in ["USDB", "USDC", "USDT", "USDT0", "usdb", "uSdC"] {
            assert!(is_usd_stable_asset(ticker), "{ticker} should be stable");
        }
    }

    #[test_all]
    fn is_usd_stable_asset_rejects_btc_and_unknown() {
        for ticker in ["BTC", "ETH", "DAI", "", "USD"] {
            assert!(
                !is_usd_stable_asset(ticker),
                "{ticker} should not be a recognized USD-stable"
            );
        }
    }

    // ---- compute_terminal_fee_amount ----

    #[test_all]
    fn compute_terminal_fee_overwrites_estimate_on_completed() {
        let realized = compute_terminal_fee_amount(
            &crate::ConversionStatus::Completed,
            Some(1_020_434), // asset_amount_in
            Some(997_498),   // delivered_amount
            Some(20_434),    // prepare-time estimate
        );
        assert_eq!(realized, Some(22_936), "= asset_amount_in − delivered");
    }

    #[test_all]
    fn compute_terminal_fee_keeps_estimate_on_refunded() {
        // Refunded payments don't have a realized fee semantic; the estimate
        // is the best we can show (and the realized formula would produce
        // garbage because delivered_amount is 0/None on a refund).
        let realized = compute_terminal_fee_amount(
            &crate::ConversionStatus::Refunded,
            Some(1_020_434),
            None,
            Some(20_434),
        );
        assert_eq!(realized, Some(20_434));
    }

    #[test_all]
    fn compute_terminal_fee_keeps_estimate_on_failed() {
        let realized = compute_terminal_fee_amount(
            &crate::ConversionStatus::Failed,
            Some(1_020_434),
            None,
            Some(20_434),
        );
        assert_eq!(realized, Some(20_434));
    }

    #[test_all]
    fn compute_terminal_fee_keeps_estimate_when_asset_amount_in_missing() {
        // Pre-upgrade rows have no asset_amount_in; realized fee can't be
        // computed, so the stored estimate stays as-is.
        let realized = compute_terminal_fee_amount(
            &crate::ConversionStatus::Completed,
            None, // asset_amount_in missing
            Some(997_498),
            Some(20_434),
        );
        assert_eq!(realized, Some(20_434));
    }

    #[test_all]
    fn compute_terminal_fee_keeps_estimate_when_delivered_amount_missing() {
        // Should never happen on Completed per the contract, but defend
        // against the edge anyway.
        let realized = compute_terminal_fee_amount(
            &crate::ConversionStatus::Completed,
            Some(1_020_434),
            None, // delivered_amount missing
            Some(20_434),
        );
        assert_eq!(realized, Some(20_434));
    }

    #[test_all]
    fn compute_terminal_fee_saturating_sub_on_over_delivery() {
        // Rare but possible: provider over-delivers vs source.
        let realized = compute_terminal_fee_amount(
            &crate::ConversionStatus::Completed,
            Some(1_000_000),
            Some(1_005_000),
            Some(0),
        );
        assert_eq!(
            realized,
            Some(0),
            "saturating_sub must clamp at 0, not underflow"
        );
    }

    /// Regression: `CrossChainProviderContext::Boltz.invoice_amount_sats` must
    /// be the source of truth for the LN-leg amount, distinct from
    /// `CrossChainSendPrepared::amount_in` (which can carry a user-facing display
    /// value such as token base units after the dispatcher's conversion-path
    /// override). Conflating the two persisted USDB base units into the
    /// `invoice_amount_sats` field of `ConversionInfo::Boltz`, showing a
    /// ~$1,200,000-sat "from" amount for a ~$1 send. This test asserts the
    /// two fields are independently representable + survive a serde
    /// round-trip with their distinct values.
    #[test_all]
    fn boltz_provider_context_invoice_amount_sats_is_independent_of_amount_in() {
        let ctx = CrossChainProviderContext::Boltz {
            swap_id: "swap_1".to_string(),
            invoice: "lnbc19090n1pexample".to_string(),
            invoice_amount_sats: 1_909,
            max_slippage_bps: 100,
        };
        let json = serde_json::to_string(&ctx).unwrap();
        let decoded: CrossChainProviderContext = serde_json::from_str(&json).unwrap();
        let CrossChainProviderContext::Boltz {
            invoice_amount_sats,
            ..
        } = &decoded
        else {
            panic!("expected Boltz variant");
        };
        assert_eq!(*invoice_amount_sats, 1_909);
        assert!(
            *invoice_amount_sats != 1_222_703,
            "the LN invoice sats must never be conflated with a user-facing display value (e.g. USDB base units)"
        );
    }

    /// Pre-bug-fix persisted contexts lack `invoice_amount_sats`. Serde must
    /// default the missing field to 0 rather than failing to deserialize — the
    /// downstream send-time error becomes obvious instead of corrupting the
    /// stored Payment.
    #[test_all]
    fn boltz_provider_context_legacy_row_without_invoice_amount_sats_defaults_to_zero() {
        let legacy = r#"{
            "Boltz": {
                "swap_id": "swap_legacy",
                "invoice": "lnbc19090n1p",
                "max_slippage_bps": 100
            }
        }"#;
        let decoded: CrossChainProviderContext = serde_json::from_str(legacy).unwrap();
        let CrossChainProviderContext::Boltz {
            invoice_amount_sats,
            ..
        } = &decoded
        else {
            panic!("expected Boltz variant");
        };
        assert_eq!(*invoice_amount_sats, 0);
    }

    /// Same invariant for Orchestra: `deposit_amount` is the source of truth
    /// for the deposit transfer size and is distinct from
    /// `CrossChainSendPrepared::amount_in`.
    #[test_all]
    fn orchestra_provider_context_deposit_amount_is_independent_of_amount_in() {
        let ctx = CrossChainProviderContext::Orchestra {
            quote_id: "q_1".to_string(),
            deposit_address: "spark1...".to_string(),
            deposit_amount: 1_020_434,
        };
        let json = serde_json::to_string(&ctx).unwrap();
        let decoded: CrossChainProviderContext = serde_json::from_str(&json).unwrap();
        let CrossChainProviderContext::Orchestra { deposit_amount, .. } = &decoded else {
            panic!("expected Orchestra variant");
        };
        assert_eq!(*deposit_amount, 1_020_434);
    }

    fn boltz_info(swap_id: &str) -> ConversionInfo {
        ConversionInfo::Boltz {
            swap_id: swap_id.to_string(),
            invoice: "lnbc1".to_string(),
            invoice_amount_sats: 1_000,
            bridge_ref: None,
            max_slippage_bps: 100,
            quote_degraded: false,
            chain: "polygon".to_string(),
            chain_id: None,
            asset: "USDC".to_string(),
            recipient_address: "0xabc".to_string(),
            estimated_out: 1_000_000,
            delivered_amount: None,
            status: crate::ConversionStatus::Pending,
            asset_amount_in: None,
            fee_amount: None,
            service_fee_amount: None,
            service_fee_asset: None,
            asset_decimals: 6,
            asset_contract: None,
        }
    }

    #[test_all]
    fn payment_with_conversion_info_injects_into_lightning_details() {
        let payment = crate::Payment {
            id: "p1".to_string(),
            payment_type: crate::PaymentType::Send,
            status: crate::PaymentStatus::Pending,
            amount: 1_000,
            fees: 0,
            timestamp: 100,
            method: crate::PaymentMethod::Lightning,
            details: Some(PaymentDetails::Lightning {
                description: Some("desc".to_string()),
                invoice: "lnbc1".to_string(),
                destination_pubkey: "02aa".to_string(),
                htlc_details: crate::SparkHtlcDetails {
                    payment_hash: "hash1".to_string(),
                    preimage: None,
                    expiry_time: 0,
                    status: crate::SparkHtlcStatus::PreimageShared,
                },
                lnurl_pay_info: None,
                lnurl_withdraw_info: None,
                lnurl_receive_metadata: None,
                conversion_info: None,
            }),
            conversion_details: None,
        };

        let out = payment_with_conversion_info(payment, Some(boltz_info("swap1")));

        assert_eq!(out.status, crate::PaymentStatus::Pending);
        let Some(PaymentDetails::Lightning {
            invoice,
            description,
            conversion_info,
            ..
        }) = out.details
        else {
            panic!("expected Lightning details");
        };
        // Sibling fields survive the rebuild.
        assert_eq!(invoice, "lnbc1");
        assert_eq!(description.as_deref(), Some("desc"));
        assert!(matches!(
            conversion_info,
            Some(ConversionInfo::Boltz { ref swap_id, .. }) if swap_id == "swap1"
        ));
    }

    #[test_all]
    fn payment_with_conversion_info_passes_through_variants_without_a_slot() {
        let payment = crate::Payment {
            id: "p1".to_string(),
            payment_type: crate::PaymentType::Send,
            status: crate::PaymentStatus::Completed,
            amount: 1_000,
            fees: 0,
            timestamp: 100,
            method: crate::PaymentMethod::Withdraw,
            details: Some(PaymentDetails::Withdraw {
                tx_id: "tx1".to_string(),
                vout: 0,
                destination_address: "bcrt1p_destination".to_string(),
            }),
            conversion_details: None,
        };

        let out = payment_with_conversion_info(payment, Some(boltz_info("swap1")));

        assert!(matches!(
            out.details,
            Some(PaymentDetails::Withdraw { tx_id, .. }) if tx_id == "tx1"
        ));
    }

    // ---- resolve_target_overpay_bps ----

    #[test_all]
    fn resolve_target_overpay_uses_request_when_in_range() {
        assert_eq!(resolve_target_overpay_bps(Some(50), Some(75)).unwrap(), 50);
    }

    #[test_all]
    fn resolve_target_overpay_falls_back_to_config_default() {
        assert_eq!(resolve_target_overpay_bps(None, Some(75)).unwrap(), 75);
    }

    #[test_all]
    fn resolve_target_overpay_falls_back_to_built_in_default() {
        assert_eq!(
            resolve_target_overpay_bps(None, None).unwrap(),
            DEFAULT_TARGET_OVERPAY_BPS
        );
    }

    #[test_all]
    fn resolve_target_overpay_request_zero_opts_out() {
        assert_eq!(resolve_target_overpay_bps(Some(0), Some(50)).unwrap(), 0);
    }

    #[test_all]
    fn resolve_target_overpay_rejects_out_of_range_request() {
        let too_high = MAX_TARGET_OVERPAY_BPS + 1;
        assert!(matches!(
            resolve_target_overpay_bps(Some(too_high), None),
            Err(SdkError::InvalidInput(_))
        ));
    }

    // ---- inflate_target_amount ----

    #[test_all]
    fn inflate_target_amount_zero_bps_is_identity() {
        assert_eq!(inflate_target_amount(1_000_000, 0), 1_000_000);
    }

    #[test_all]
    fn inflate_target_amount_applies_bps_pad() {
        // 25 bps on 1_000_000 → 2_500 pad.
        assert_eq!(inflate_target_amount(1_000_000, 25), 1_002_500);
    }

    #[test_all]
    fn inflate_target_amount_truncates_sub_unit_pad() {
        // 25 bps on 100 → 0.25 pad, truncates to 0.
        assert_eq!(inflate_target_amount(100, 25), 100);
    }

    // ---- convert_source_amount_to_sats ----

    #[test_all]
    fn convert_stable_to_sats_at_par_6dp() {
        // BTC/USD = 100_000, 1 USD = 1000 sats. 1_000_000 (6dp) = $1 = 1000 sats.
        assert_eq!(
            convert_source_amount_to_sats(1_000_000, 6, 100_000.0).unwrap(),
            1000
        );
    }

    #[test_all]
    fn convert_stable_to_sats_at_a_different_rate() {
        // BTC/USD = 50_000, $1 = 2000 sats.
        assert_eq!(
            convert_source_amount_to_sats(1_000_000, 6, 50_000.0).unwrap(),
            2000
        );
    }

    #[test_all]
    fn convert_stable_to_sats_matches_across_decimals_at_same_usd_value() {
        // $1 at 6dp and at 18dp must produce the same sats.
        let sats_6 = convert_source_amount_to_sats(1_000_000, 6, 100_000.0).unwrap();
        let sats_18 =
            convert_source_amount_to_sats(1_000_000_000_000_000_000, 18, 100_000.0).unwrap();
        assert_eq!(sats_6, sats_18);
        assert_eq!(sats_6, 1000);
    }

    #[test_all]
    fn convert_stable_to_sats_zero_input_is_zero() {
        assert_eq!(convert_source_amount_to_sats(0, 6, 100_000.0).unwrap(), 0);
    }

    #[test_all]
    fn convert_stable_to_sats_rejects_nan_rate() {
        // Infinity is intentionally allowed (produces 0 sats, a finite result);
        // NaN is the pathological input we guard against.
        assert!(matches!(
            convert_source_amount_to_sats(1_000_000, 6, f64::NAN),
            Err(SdkError::Generic(_))
        ));
    }

    #[test_all]
    fn convert_stable_to_sats_rejects_negative_rate() {
        assert!(matches!(
            convert_source_amount_to_sats(1_000_000, 6, -100_000.0),
            Err(SdkError::Generic(_))
        ));
    }

    // ---- build_receive_payment_request ----

    /// EVM destinations produce an EIP-681 URI (with `chain_id` and token
    /// contract when present) so wallets like `MetaMask` auto-fill.
    #[test_all]
    fn build_receive_payment_request_evm_emits_eip_681_uri() {
        let uri = build_receive_payment_request(
            "0x00Df20df75800ca8f40080505a7a802331C1321c",
            "arbitrum",
            Some("42161"),
            Some("0xaf88d065e77c8cC2239327C5EDb3A432268e5831"),
            1_000_000,
        )
        .unwrap();
        assert!(uri.starts_with("ethereum:"), "got {uri}");
        assert!(uri.contains("42161"), "chain_id must appear: {uri}");
        assert!(
            uri.contains("0xaf88d065e77c8cC2239327C5EDb3A432268e5831"),
            "token contract must appear: {uri}"
        );
        assert!(uri.contains("1000000"), "amount must appear: {uri}");
    }

    /// Solana falls back to the bare deposit address: current wallets don't
    /// honor solana: URI parameters reliably.
    #[test_all]
    fn build_receive_payment_request_solana_returns_bare_address() {
        let addr = "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM";
        let out = build_receive_payment_request(addr, "solana", None, None, 1_000_000).unwrap();
        assert_eq!(out, addr);
    }

    /// Tron falls back to the bare deposit address for the same reason.
    #[test_all]
    fn build_receive_payment_request_tron_returns_bare_address() {
        let addr = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t";
        let out = build_receive_payment_request(addr, "tron", None, None, 1_000_000).unwrap();
        assert_eq!(out, addr);
    }

    /// An unrecognized address surfaces a Generic error rather than silently
    /// returning something usable.
    #[test_all]
    fn build_receive_payment_request_rejects_unrecognized_address() {
        let err =
            build_receive_payment_request("not-an-address", "arbitrum", None, None, 1_000_000)
                .unwrap_err();
        assert!(matches!(err, SdkError::Generic(_)));
    }

    /// An EVM-looking deposit address for a Solana route must be rejected:
    /// a provider that miswires chains cannot silently redirect funds by
    /// returning an EVM address where a Solana address was expected.
    #[test_all]
    fn build_receive_payment_request_rejects_family_chain_mismatch() {
        let evm_addr = "0x00Df20df75800ca8f40080505a7a802331C1321c";
        let err =
            build_receive_payment_request(evm_addr, "solana", None, None, 1_000_000).unwrap_err();
        match err {
            SdkError::Generic(msg) => {
                assert!(
                    msg.contains("Evm") && msg.contains("solana"),
                    "unexpected message: {msg}"
                );
            }
            other => panic!("expected Generic mismatch error, got {other:?}"),
        }

        let solana_addr = "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM";
        assert!(
            build_receive_payment_request(solana_addr, "tron", None, None, 1_000_000).is_err(),
            "solana address must not be accepted for tron route",
        );
    }

    #[cfg(feature = "sqlite")]
    mod receive_matching {
        use super::*;
        use crate::{
            PaymentDetails, PaymentMethod, PaymentStatus, PaymentType, SparkInvoicePaymentDetails,
            TokenMetadata, TokenTransactionType,
        };

        fn sqlite_storage() -> Arc<dyn crate::Storage> {
            let mut dir = std::env::temp_dir();
            dir.push(format!(
                "breez-xchain-receive-match-{}",
                uuid::Uuid::new_v4()
            ));
            std::fs::create_dir_all(&dir).unwrap();
            Arc::new(crate::SqliteStorage::new(&dir).unwrap())
        }

        async fn storage_with_open_receive(invoice: &str) -> Arc<dyn crate::Storage> {
            let storage = sqlite_storage();
            let data = orchestra::storage_adapter::OrchestraSwapData {
                quote_id: "q_match".to_string(),
                order_id: None,
                read_token: None,
                quote_read_token: None,
                recipient_address: "sp1rcv".to_string(),
                spark_invoice: Some(invoice.to_string()),
                paid: false,
                source_chain: "arbitrum".to_string(),
                source_asset: "USDC".to_string(),
                source_chain_id: Some("42161".to_string()),
                source_contract_address: Some("0xUSDC".to_string()),
                source_decimals: 6,
                destination_chain: "spark".to_string(),
                destination_asset: "BTC".to_string(),
                destination_decimals: 8,
                token_identifier: None,
                amount_in: "1000000".to_string(),
                expected_amount_out: "1146".to_string(),
                fee_amount: Some("10000".to_string()),
                fee_asset: Some("USDC".to_string()),
                fee_asset_decimals: Some(6),
                expires_at: 1_700_000_120,
            };
            orchestra::storage_adapter::OrchestraStorageAdapter::new(Arc::clone(&storage))
                .upsert(&data)
                .await
                .unwrap();
            storage
        }

        fn invoice_details(invoice: &str) -> SparkInvoicePaymentDetails {
            SparkInvoicePaymentDetails {
                description: None,
                invoice: invoice.to_string(),
            }
        }

        fn payment(payment_type: PaymentType, details: PaymentDetails) -> crate::Payment {
            crate::Payment {
                id: "p1".to_string(),
                payment_type,
                status: PaymentStatus::Completed,
                amount: 1146,
                fees: 0,
                timestamp: 100,
                method: PaymentMethod::Spark,
                details: Some(details),
                conversion_details: None,
            }
        }

        fn spark_details(invoice: Option<&str>) -> PaymentDetails {
            PaymentDetails::Spark {
                invoice_details: invoice.map(invoice_details),
                htlc_details: None,
                conversion_info: None,
            }
        }

        fn token_details(invoice: &str) -> PaymentDetails {
            PaymentDetails::Token {
                metadata: TokenMetadata {
                    identifier: "btkn1usdb".to_string(),
                    issuer_public_key: "02aa".to_string(),
                    name: "Bitcoin USD".to_string(),
                    ticker: "USDB".to_string(),
                    decimals: 6,
                    max_supply: 0,
                    is_freezable: true,
                },
                tx_hash: "abcd".to_string(),
                tx_type: TokenTransactionType::Transfer,
                invoice_details: Some(invoice_details(invoice)),
                conversion_info: None,
            }
        }

        async fn stored_conversion_status(
            storage: &Arc<dyn crate::Storage>,
            payment_id: &str,
        ) -> Option<crate::ConversionStatus> {
            let stored = storage
                .get_payment_by_id(payment_id.to_string())
                .await
                .unwrap();
            match extract_conversion_info(stored.details) {
                Some(ConversionInfo::Orchestra { status, .. }) => Some(status),
                _ => None,
            }
        }

        #[tokio::test]
        async fn spark_receive_fulfilling_an_open_invoice_gets_pending_conversion_info() {
            let storage = storage_with_open_receive("spark1inv").await;
            let payment = payment(PaymentType::Receive, spark_details(Some("spark1inv")));
            storage.apply_payment_update(payment.clone()).await.unwrap();

            let attached = attach_receive_metadata_for_payment(&storage, &payment)
                .await
                .unwrap();

            assert!(attached);
            assert_eq!(
                stored_conversion_status(&storage, &payment.id).await,
                Some(crate::ConversionStatus::Pending)
            );
        }

        #[tokio::test]
        async fn token_receive_fulfilling_an_open_invoice_gets_pending_conversion_info() {
            let storage = storage_with_open_receive("spark1inv").await;
            let payment = payment(PaymentType::Receive, token_details("spark1inv"));
            storage.apply_payment_update(payment.clone()).await.unwrap();

            let attached = attach_receive_metadata_for_payment(&storage, &payment)
                .await
                .unwrap();

            assert!(attached);
            assert_eq!(
                stored_conversion_status(&storage, &payment.id).await,
                Some(crate::ConversionStatus::Pending)
            );
        }

        #[tokio::test]
        async fn a_payment_already_carrying_a_conversion_is_left_alone() {
            let storage = storage_with_open_receive("spark1inv").await;
            let payment = payment(PaymentType::Receive, spark_details(Some("spark1inv")));
            storage.apply_payment_update(payment.clone()).await.unwrap();
            let mut completed = orchestra_receive_info_placeholder();
            if let ConversionInfo::Orchestra { status, .. } = &mut completed {
                *status = crate::ConversionStatus::Completed;
            }
            storage
                .insert_payment_metadata(
                    payment.id.clone(),
                    crate::PaymentMetadata {
                        conversion_info: Some(completed),
                        ..Default::default()
                    },
                )
                .await
                .unwrap();

            let attached = attach_receive_metadata_for_payment(&storage, &payment)
                .await
                .unwrap();

            assert!(!attached);
            assert_eq!(
                stored_conversion_status(&storage, &payment.id).await,
                Some(crate::ConversionStatus::Completed)
            );
        }

        #[tokio::test]
        async fn other_payments_get_nothing() {
            let storage = storage_with_open_receive("spark1inv").await;

            for payment in [
                payment(PaymentType::Receive, spark_details(Some("spark1other"))),
                payment(PaymentType::Receive, spark_details(None)),
                payment(PaymentType::Send, spark_details(Some("spark1inv"))),
            ] {
                let attached = attach_receive_metadata_for_payment(&storage, &payment)
                    .await
                    .unwrap();
                assert!(!attached, "{payment:?}");
            }
        }

        fn orchestra_receive_info_placeholder() -> ConversionInfo {
            ConversionInfo::Orchestra {
                order_id: "ord".to_string(),
                quote_id: "q_match".to_string(),
                read_token: None,
                chain: "arbitrum".to_string(),
                chain_id: Some("42161".to_string()),
                asset: "USDC".to_string(),
                recipient_address: "sp1rcv".to_string(),
                asset_amount_in: Some(1_000_000),
                estimated_out: 1146,
                delivered_amount: Some(1146),
                external_tx_hash: Some("0xdeposit".to_string()),
                status: crate::ConversionStatus::Pending,
                fee_amount: Some(10_000),
                service_fee_amount: Some(10_000),
                service_fee_asset: Some("USDC".to_string()),
                service_fee_asset_decimals: Some(6),
                asset_decimals: 6,
                asset_contract: Some("0xUSDC".to_string()),
            }
        }
    }
}