breez_sdk_spark/models/

mod.rs

pub(crate) mod adaptors;
pub mod payment_observer;
pub use payment_observer::*;
pub mod token_allowance;
pub use token_allowance::*;

// Re-export public conversion types from the conversion module
pub use crate::token_conversion::{
    AmountAdjustmentReason, ConversionEstimate, ConversionInfo, ConversionOptions,
    ConversionPurpose, ConversionStatus, ConversionType, FetchConversionLimitsRequest,
    FetchConversionLimitsResponse, SwapDegradation,
};

use core::fmt;
use lnurl_models::RecoverLnurlPayResponse;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use spark_wallet::bech32m_decode_token_id;
use std::{
    collections::{HashMap, HashSet},
    fmt::Display,
    str::FromStr,
};

use crate::{
    BitcoinAddressDetails, BitcoinNetwork, Bolt11InvoiceDetails, ExternalInputParser, FiatCurrency,
    LnurlPayRequestDetails, LnurlWithdrawRequestDetails, Rate, SdkError, SparkInvoiceDetails,
    SuccessAction, SuccessActionProcessed,
    chain::FeeMarket,
    cross_chain::{CrossChainFeeMode, CrossChainProviderContext, CrossChainRoutePair},
    error::{CooperativeRecoveryError, DepositClaimError},
};

/// A list of external input parsers that are used by default.
/// To opt-out, set `use_default_external_input_parsers` in [Config] to false.
pub const DEFAULT_EXTERNAL_INPUT_PARSERS: &[(&str, &str, &str)] = &[
    (
        "picknpay",
        "(.*)(za.co.electrum.picknpay)(.*)",
        "https://cryptoqr.net/.well-known/lnurlp/<input>",
    ),
    (
        "bootleggers",
        r"(.*)(wigroup\.co|yoyogroup\.co)(.*)",
        "https://cryptoqr.net/.well-known/lnurlw/<input>",
    ),
];

/// Represents the seed for wallet generation, either as a mnemonic phrase with an optional
/// passphrase or as raw entropy bytes.
#[derive(Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum Seed {
    /// A BIP-39 mnemonic phrase with an optional passphrase.
    Mnemonic {
        /// The mnemonic phrase. 12 or 24 words.
        mnemonic: String,
        /// An optional passphrase for the mnemonic.
        passphrase: Option<String>,
    },
    /// Raw entropy bytes.
    Entropy(Vec<u8>),
}

impl fmt::Debug for Seed {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Seed::Mnemonic { passphrase, .. } => f
                .debug_struct("Mnemonic")
                .field("mnemonic", &"<redacted>")
                .field("passphrase", &passphrase.as_ref().map(|_| "<redacted>"))
                .finish(),
            Seed::Entropy(_) => f.debug_tuple("Entropy").field(&"<redacted>").finish(),
        }
    }
}

impl Seed {
    pub fn to_bytes(&self) -> Result<Vec<u8>, SdkError> {
        match self {
            Seed::Mnemonic {
                mnemonic,
                passphrase,
            } => {
                let mnemonic = bip39::Mnemonic::parse(mnemonic)
                    .map_err(|e| SdkError::Generic(e.to_string()))?;

                Ok(mnemonic
                    .to_seed(passphrase.as_deref().unwrap_or(""))
                    .to_vec())
            }
            Seed::Entropy(entropy) => Ok(entropy.clone()),
        }
    }
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ConnectRequest {
    pub config: Config,
    pub seed: Seed,
    pub storage_dir: String,
}

/// Request object for connecting to the Spark network using an external signer.
///
/// This allows using a custom signer implementation instead of providing a seed directly.
#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ConnectWithSignerRequest {
    pub config: Config,
    /// External signer for non-Spark SDK signing (LNURL-auth, sync, message
    /// signing, ECIES).
    pub breez_signer: std::sync::Arc<dyn crate::signer::ExternalBreezSigner>,
    /// External high-level Spark signer for the Spark wallet flows.
    pub spark_signer: std::sync::Arc<dyn crate::signer::ExternalSparkSigner>,
    pub storage_dir: String,
}

/// Request object for connecting to the Spark network using a signing-only
/// external signer.
///
/// Use this instead of [`ConnectWithSignerRequest`] for a signer that can't
/// perform the SDK's local ECIES/HMAC operations (for example a
/// policy-restricted enclave). The SDK keeps session tokens in plaintext and
/// disables the features that rely on ECIES/HMAC.
#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ConnectWithSigningOnlySignerRequest {
    pub config: Config,
    /// Signing-only external signer for non-Spark SDK signing.
    pub breez_signer: std::sync::Arc<dyn crate::signer::ExternalSigningSigner>,
    /// External high-level Spark signer for the Spark wallet flows.
    pub spark_signer: std::sync::Arc<dyn crate::signer::ExternalSparkSigner>,
    pub storage_dir: String,
}

/// The type of payment
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PaymentType {
    /// Payment sent from this wallet
    Send,
    /// Payment received to this wallet
    Receive,
}

impl fmt::Display for PaymentType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PaymentType::Send => write!(f, "send"),
            PaymentType::Receive => write!(f, "receive"),
        }
    }
}

impl FromStr for PaymentType {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(match s.to_lowercase().as_str() {
            "receive" => PaymentType::Receive,
            "send" => PaymentType::Send,
            _ => return Err(format!("invalid payment type '{s}'")),
        })
    }
}

/// The status of a payment
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PaymentStatus {
    /// Payment is completed successfully
    Completed,
    /// Payment is in progress
    Pending,
    /// Payment has failed
    Failed,
}

impl PaymentStatus {
    /// Returns true if the payment status is final (either Completed or Failed)
    pub fn is_final(&self) -> bool {
        matches!(self, PaymentStatus::Completed | PaymentStatus::Failed)
    }
}

impl fmt::Display for PaymentStatus {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PaymentStatus::Completed => write!(f, "completed"),
            PaymentStatus::Pending => write!(f, "pending"),
            PaymentStatus::Failed => write!(f, "failed"),
        }
    }
}

impl FromStr for PaymentStatus {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(match s.to_lowercase().as_str() {
            "completed" => PaymentStatus::Completed,
            "pending" => PaymentStatus::Pending,
            "failed" => PaymentStatus::Failed,
            _ => return Err(format!("Invalid payment status '{s}'")),
        })
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PaymentMethod {
    Lightning,
    Spark,
    Token,
    Deposit,
    Withdraw,
    Unknown,
}

impl Display for PaymentMethod {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            PaymentMethod::Lightning => write!(f, "lightning"),
            PaymentMethod::Spark => write!(f, "spark"),
            PaymentMethod::Token => write!(f, "token"),
            PaymentMethod::Deposit => write!(f, "deposit"),
            PaymentMethod::Withdraw => write!(f, "withdraw"),
            PaymentMethod::Unknown => write!(f, "unknown"),
        }
    }
}

impl FromStr for PaymentMethod {
    type Err = ();

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "lightning" => Ok(PaymentMethod::Lightning),
            "spark" => Ok(PaymentMethod::Spark),
            "token" => Ok(PaymentMethod::Token),
            "deposit" => Ok(PaymentMethod::Deposit),
            "withdraw" => Ok(PaymentMethod::Withdraw),
            "unknown" => Ok(PaymentMethod::Unknown),
            _ => Err(()),
        }
    }
}

/// Represents a payment (sent or received)
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct Payment {
    /// Unique identifier for the payment
    pub id: String,
    /// Type of payment (send or receive)
    pub payment_type: PaymentType,
    /// Status of the payment
    pub status: PaymentStatus,
    /// Amount in satoshis or token base units
    pub amount: u128,
    /// Fee paid in satoshis or token base units
    pub fees: u128,
    /// Timestamp of when the payment was created
    pub timestamp: u64,
    /// Method of payment. Sometimes the payment details is empty so this field
    /// is used to determine the payment method.
    pub method: PaymentMethod,
    /// Details of the payment
    pub details: Option<PaymentDetails>,
    /// If set, this payment involved a conversion before the payment
    pub conversion_details: Option<ConversionDetails>,
}

impl Payment {
    /// Returns `true` if this payment is a child of a conversion operation.
    ///
    /// An AMM conversion (stable balance, convert-on-send) settles as its own
    /// payments: sats out to the pool, tokens back in. Those legs are internal
    /// plumbing, so they carry [`ConversionInfo::Amm`]. A cross-chain
    /// conversion has no such legs: it annotates the payment the user made or
    /// received, which is never a child.
    pub fn is_conversion_child(&self) -> bool {
        matches!(
            &self.details,
            Some(
                PaymentDetails::Spark {
                    conversion_info: Some(ConversionInfo::Amm { .. }),
                    ..
                } | PaymentDetails::Token {
                    conversion_info: Some(ConversionInfo::Amm { .. }),
                    ..
                }
            )
        )
    }
}

/// Outlines the steps involved in one or more conversions on a payment.
///
/// Built progressively: `status` is available immediately from payment metadata,
/// while `conversions` are enriched later from child payments and conversion info.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ConversionDetails {
    /// Overall status of the conversion. On a send, it follows the cross-chain
    /// step until that step finishes.
    pub status: ConversionStatus,
    /// Ordered list of conversion steps. For sends: [AMM, cross-chain].
    /// For receives: [cross-chain, AMM]. Rebuilt on retrieval, not persisted.
    #[serde(default)]
    pub conversions: Vec<Conversion>,
}

/// The provider that performed a conversion.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ConversionProvider {
    /// AMM (Flashnet pool) conversion between token and BTC on Spark
    Amm,
    /// Orchestra cross-chain conversion
    Orchestra,
    /// Boltz reverse-swap cross-chain conversion
    Boltz,
}

/// The chain or network that a [`ConversionSide`] lives on.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ConversionChain {
    /// Spark layer-2 network.
    Spark,
    /// Bitcoin Lightning Network.
    Lightning,
    /// An external chain reached via a cross-chain provider.
    External {
        /// Human-readable chain name (e.g. `"base"`, `"solana"`, `"arbitrum"`).
        name: String,
        /// Stable chain identifier (e.g. EVM `chainId` as a decimal string,
        /// or a chain-native identifier). `None` when the provider does not
        /// expose one for this route.
        chain_id: Option<String>,
    },
}

/// The asset on a [`ConversionSide`] — groups the ticker, stable identifier,
/// and decimals that always travel together.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ConversionAsset {
    /// Ticker (e.g. `"BTC"`, `"USDB"`, `"USDC"`, `"USDT"`). Tickers alone
    /// are ambiguous across chains — pair with [`Self::identifier`] for a
    /// hard match.
    pub ticker: String,
    /// Stable identifier: a Spark token identifier for Spark tokens, or a
    /// contract/mint address for cross-chain assets. `None` for BTC/sats.
    pub identifier: Option<String>,
    /// Number of decimals for the asset.
    /// `0` for BTC/sats sides (amount is already in the smallest unit,
    /// so no scaling is needed); non-zero for token assets (e.g. `6` for
    /// USDC/USDT/USDB).
    pub decimals: u32,
}

/// One side (source or destination) of a conversion.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ConversionSide {
    /// The chain or network for this side.
    pub chain: ConversionChain,
    /// The asset being converted on this side.
    pub asset: ConversionAsset,
    /// Amount in base units (satoshis or token base units)
    pub amount: u128,
    /// Fee in the same base units
    pub fee: u128,
}

/// A single conversion in a payment's conversion chain.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct Conversion {
    /// The provider that performed this conversion
    pub provider: ConversionProvider,
    /// Status of this specific conversion step
    pub status: ConversionStatus,
    /// Source side of the conversion
    pub from: ConversionSide,
    /// Destination side of the conversion
    pub to: ConversionSide,
    /// Reason the conversion amount was adjusted, if applicable (AMM only)
    #[serde(default)]
    pub amount_adjustment: Option<AmountAdjustmentReason>,
}

#[cfg(feature = "uniffi")]
uniffi::custom_type!(u128, String, {
    remote,
    try_lift: |val| val.parse::<u128>().map_err(uniffi::deps::anyhow::Error::msg),
    lower: |obj| obj.to_string(),
});

// TODO: fix large enum variant lint - may be done by boxing lnurl_pay_info but that requires
//  some changes to the wasm bindgen macro
#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PaymentDetails {
    Spark {
        /// The invoice details if the payment fulfilled a spark invoice
        invoice_details: Option<SparkInvoicePaymentDetails>,
        /// The HTLC transfer details if the payment fulfilled an HTLC transfer
        htlc_details: Option<SparkHtlcDetails>,
        /// The information for a conversion
        conversion_info: Option<ConversionInfo>,
    },
    Token {
        metadata: TokenMetadata,
        tx_hash: String,
        tx_type: TokenTransactionType,
        /// The invoice details if the payment fulfilled a spark invoice
        invoice_details: Option<SparkInvoicePaymentDetails>,
        /// The information for a conversion
        conversion_info: Option<ConversionInfo>,
    },
    Lightning {
        /// Represents the invoice description
        description: Option<String>,
        /// Represents the Bolt11/Bolt12 invoice associated with a payment
        /// In the case of a Send payment, this is the invoice paid by the user
        /// In the case of a Receive payment, this is the invoice paid to the user
        invoice: String,

        /// The invoice destination/payee pubkey
        destination_pubkey: String,

        /// The HTLC transfer details
        htlc_details: SparkHtlcDetails,

        /// Lnurl payment information if this was an lnurl payment.
        lnurl_pay_info: Option<LnurlPayInfo>,

        /// Lnurl withdrawal information if this was an lnurl payment.
        lnurl_withdraw_info: Option<LnurlWithdrawInfo>,

        /// Lnurl receive information if this was a received lnurl payment.
        lnurl_receive_metadata: Option<LnurlReceiveMetadata>,

        /// The information for a conversion — populated when this Lightning
        /// payment is the source leg of a cross-chain conversion (e.g. a
        /// Boltz reverse swap paying a hold invoice).
        conversion_info: Option<ConversionInfo>,
    },
    Withdraw {
        tx_id: String,
        /// The index of the withdrawal transaction's output that pays the
        /// destination address.
        vout: u32,
        destination_address: String,
    },
    Deposit {
        tx_id: String,
        vout: u32,
    },
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum TokenTransactionType {
    Transfer,
    Mint,
    Burn,
}

impl fmt::Display for TokenTransactionType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TokenTransactionType::Transfer => write!(f, "transfer"),
            TokenTransactionType::Mint => write!(f, "mint"),
            TokenTransactionType::Burn => write!(f, "burn"),
        }
    }
}

impl FromStr for TokenTransactionType {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "transfer" => Ok(TokenTransactionType::Transfer),
            "mint" => Ok(TokenTransactionType::Mint),
            "burn" => Ok(TokenTransactionType::Burn),
            _ => Err(format!("Invalid token transaction type '{s}'")),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SparkInvoicePaymentDetails {
    /// Represents the spark invoice description
    pub description: Option<String>,
    /// The raw spark invoice string
    pub invoice: String,
}

#[derive(Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SparkHtlcDetails {
    /// The payment hash of the HTLC
    pub payment_hash: String,
    /// The preimage of the HTLC. Empty until receiver has released it.
    pub preimage: Option<String>,
    /// The expiry time of the HTLC as a unix timestamp in seconds
    pub expiry_time: u64,
    /// The HTLC status
    pub status: SparkHtlcStatus,
}

impl fmt::Debug for SparkHtlcDetails {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SparkHtlcDetails")
            .field("payment_hash", &self.payment_hash)
            .field("preimage", &self.preimage.as_ref().map(|_| "<redacted>"))
            .field("expiry_time", &self.expiry_time)
            .field("status", &self.status)
            .finish()
    }
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum SparkHtlcStatus {
    /// The HTLC is waiting for the preimage to be shared by the receiver
    WaitingForPreimage,
    /// The HTLC preimage has been shared and the transfer can be or has been claimed by the receiver
    PreimageShared,
    /// The HTLC has been returned to the sender due to expiry
    Returned,
}

impl fmt::Display for SparkHtlcStatus {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SparkHtlcStatus::WaitingForPreimage => write!(f, "WaitingForPreimage"),
            SparkHtlcStatus::PreimageShared => write!(f, "PreimageShared"),
            SparkHtlcStatus::Returned => write!(f, "Returned"),
        }
    }
}

impl FromStr for SparkHtlcStatus {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "WaitingForPreimage" => Ok(SparkHtlcStatus::WaitingForPreimage),
            "PreimageShared" => Ok(SparkHtlcStatus::PreimageShared),
            "Returned" => Ok(SparkHtlcStatus::Returned),
            _ => Err("Invalid Spark HTLC status".to_string()),
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum Network {
    Mainnet,
    Regtest,
    Signet,
}

impl std::fmt::Display for Network {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Network::Mainnet => write!(f, "Mainnet"),
            Network::Regtest => write!(f, "Regtest"),
            Network::Signet => write!(f, "Signet"),
        }
    }
}

impl From<Network> for BitcoinNetwork {
    fn from(network: Network) -> Self {
        match network {
            Network::Mainnet => BitcoinNetwork::Bitcoin,
            Network::Regtest => BitcoinNetwork::Regtest,
            Network::Signet => BitcoinNetwork::Signet,
        }
    }
}

impl From<Network> for breez_sdk_common::network::BitcoinNetwork {
    fn from(network: Network) -> Self {
        match network {
            Network::Mainnet => breez_sdk_common::network::BitcoinNetwork::Bitcoin,
            Network::Regtest => breez_sdk_common::network::BitcoinNetwork::Regtest,
            Network::Signet => breez_sdk_common::network::BitcoinNetwork::Signet,
        }
    }
}

impl From<Network> for bitcoin::Network {
    fn from(network: Network) -> Self {
        match network {
            Network::Mainnet => bitcoin::Network::Bitcoin,
            Network::Regtest => bitcoin::Network::Regtest,
            Network::Signet => bitcoin::Network::Signet,
        }
    }
}

impl FromStr for Network {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "mainnet" => Ok(Network::Mainnet),
            "regtest" => Ok(Network::Regtest),
            "signet" => Ok(Network::Signet),
            _ => Err("Invalid network".to_string()),
        }
    }
}

/// A SOCKS5 proxy carrying the connections the SDK opens.
///
/// Hostnames are resolved by the proxy rather than locally, so a DNS query
/// never discloses which host is being reached. A connection that cannot be
/// established through the proxy fails: the SDK never falls back to a direct
/// one.
///
/// Not supported on WASM, where the browser owns connection setup and exposes
/// no proxy control. In Node, route the SDK by installing a proxy dispatcher
/// on the global `fetch` instead.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ProxyConfig {
    /// Proxy host. An IP address, or a name resolvable locally: reaching the
    /// proxy is the one lookup that cannot itself go through the proxy.
    pub host: String,
    pub port: u16,
    /// Username for SOCKS5 username/password authentication. Authentication is
    /// only offered when both this and `password` are set.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub username: Option<String>,
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub password: Option<String>,
}

impl From<&ProxyConfig> for platform_utils::ProxyConfig {
    fn from(config: &ProxyConfig) -> Self {
        Self {
            host: config.host.clone(),
            port: config.port,
            username: config.username.clone(),
            password: config.password.clone(),
        }
    }
}

impl ProxyConfig {
    /// A validated HTTP client honouring `proxy`, for the components built
    /// outside the SDK's shared context. Everything inside it takes the
    /// context's pooled client instead and never sees a proxy.
    pub(crate) fn http_client(
        proxy: Option<&Self>,
        user_agent: Option<&str>,
    ) -> Result<std::sync::Arc<dyn platform_utils::HttpClient>, SdkError> {
        if let Some(proxy) = proxy {
            proxy.validate()?;
        }
        platform_utils::create_http_client_with_proxy(
            user_agent,
            proxy.map(platform_utils::ProxyConfig::from).as_ref(),
        )
        .map_err(|e| SdkError::InvalidInput(format!("Failed to build proxied HTTP client: {e}")))
    }

    /// Rejects a proxy the SDK cannot honour end to end. Accepting one it can
    /// only partly apply would leave some traffic going direct, which is worse
    /// than refusing outright.
    pub(crate) fn validate(&self) -> Result<(), SdkError> {
        if cfg!(all(target_family = "wasm", target_os = "unknown")) {
            return Err(SdkError::InvalidInput(
                "A SOCKS5 proxy is not supported on WASM: the browser owns connection setup and \
                 exposes no proxy control. In Node, install a proxy dispatcher on the global \
                 fetch instead."
                    .to_string(),
            ));
        }
        if self.host.is_empty() {
            return Err(SdkError::InvalidInput(
                "Proxy host must not be empty".to_string(),
            ));
        }
        if self.port == 0 {
            return Err(SdkError::InvalidInput(
                "Proxy port must not be 0".to_string(),
            ));
        }
        if self.username.is_some() != self.password.is_some() {
            return Err(SdkError::InvalidInput(
                "Proxy username and password must be set together".to_string(),
            ));
        }
        // The host ends up in a URL authority, so it has to survive being put
        // there unchanged. Parsing is not enough on its own: a host carrying
        // `@` parses, but as userinfo, which silently turns part of it into a
        // username and moves the address. Checked here rather than at client
        // build time so the error names the config that caused it.
        let address = platform_utils::ProxyConfig::from(self).address();
        let intact = url::Url::parse(&format!("socks5h://{address}")).is_ok_and(|url| {
            url.username().is_empty()
                && url.password().is_none()
                && url.port() == Some(self.port)
                && url.path().is_empty()
                && url.query().is_none()
                && url.fragment().is_none()
        });
        if !intact {
            return Err(SdkError::InvalidInput(format!(
                "Proxy host '{}' cannot be used in a proxy URL",
                self.host
            )));
        }
        Ok(())
    }
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[allow(clippy::struct_excessive_bools)]
pub struct Config {
    pub api_key: Option<String>,
    pub network: Network,
    pub sync_interval_secs: u32,

    /// The maximum fee that can be paid to claim an on-chain deposit. It also caps
    /// the provider's spread for crediting a deposit before it matures, so raising
    /// it is what allows deposits to be claimed early. Unset disables claiming
    /// rather than allowing any fee.
    pub max_deposit_claim_fee: Option<MaxFee>,

    /// The domain used for receiving through lnurl-pay and lightning address.
    pub lnurl_domain: Option<String>,

    /// When this is set to `true` we will prefer to use spark payments over
    /// lightning when sending and receiving. This has the benefit of lower fees
    /// but is at the cost of privacy.
    pub prefer_spark_over_lightning: bool,

    /// Whether the data needed to exit a payment unilaterally, without the Spark
    /// operators, is collected automatically as funds arrive. Collection runs in
    /// the background, after an operation rather than during it. A leaf the
    /// operators cannot complete stays un-exitable until a later attempt
    /// succeeds.
    ///
    /// Turn it off when collecting behind every operation costs more than it is
    /// worth, on a busy wallet holding many leaves. `sync_wallet` collects
    /// regardless of this flag, and waits for the pass before returning, so an
    /// explicit sync on a cadence of your choosing is how the data is kept
    /// current with the automatic collection off.
    ///
    /// Only that automatic collection is governed, so this has no effect at all
    /// where none runs: with `background_tasks_enabled` off there is no
    /// background collector, and every sync is an explicit one.
    ///
    /// Default value is true.
    pub exit_chain_auto_fetch_enabled: bool,

    /// Whether the SDK pre-signs the transactions that protect funds on chain at
    /// a range of fees, so the protection holds when on-chain fees are high.
    ///
    /// Unset turns it on. It is not supported with a remote signer, such as
    /// Turnkey: unset keeps it off there, and true fails to connect.
    pub watchtower_fee_ladder_enabled: Option<bool>,

    /// A set of external input parsers that are used by [`BreezSdk::parse`](crate::sdk::BreezSdk::parse) when the input
    /// is not recognized. See [`ExternalInputParser`] for more details on how to configure
    /// external parsing.
    pub external_input_parsers: Option<Vec<ExternalInputParser>>,
    /// The SDK includes some default external input parsers
    /// ([`DEFAULT_EXTERNAL_INPUT_PARSERS`]).
    /// Set this to false in order to prevent their use.
    pub use_default_external_input_parsers: bool,

    /// Url to use for the real-time sync server. Defaults to the Breez real-time sync server.
    pub real_time_sync_server_url: Option<String>,

    /// Whether the Spark private mode is enabled by default.
    ///
    /// If set to true, the Spark private mode will be enabled on the first
    /// initialization of the SDK. If set to false, no changes will be made
    /// to the Spark private mode.
    ///
    /// This default is only auto-applied when `background_tasks_enabled` is
    /// `true`. When `background_tasks_enabled` is `false`, the SDK does not
    /// touch the Spark private mode on startup; call `update_user_settings`
    /// with `spark_private_mode_enabled` set as needed on a one-time setup
    /// pass.
    pub private_enabled_default: bool,

    /// Configuration for leaf optimization.
    ///
    /// Leaf optimization controls the denominations of leaves that are held in the wallet.
    /// Fewer, bigger leaves allow for more funds to be exited unilaterally.
    /// More leaves allow payments to be made without needing a swap, reducing payment latency.
    pub leaf_optimization_config: LeafOptimizationConfig,

    /// Configuration for token-output optimization.
    ///
    /// Token-output optimization controls automatic consolidation of a token's
    /// available outputs. Keeping the output set small reduces transaction size,
    /// while keeping enough distinct outputs preserves concurrency for parallel
    /// sends.
    pub token_optimization_config: TokenOptimizationConfig,

    /// Configuration for automatic conversion of Bitcoin to stable tokens.
    ///
    /// When set, received sats will be automatically converted to the specified token
    /// once the balance exceeds the threshold.
    pub stable_balance_config: Option<StableBalanceConfig>,

    /// Maximum number of concurrent transfer claims.
    ///
    /// Default is 4. Increase for server environments with high incoming payment volume.
    pub max_concurrent_claims: u32,

    /// Optional custom Spark environment configuration.
    ///
    /// When set, overrides the default Spark operator pool, service provider,
    /// threshold, and token settings. Use this to connect to alternative Spark
    /// deployments (e.g. dev/staging environments).
    pub spark_config: Option<SparkConfig>,

    /// Master switch for per-instance background services.
    ///
    /// When `true` (default), the SDK runs its standard background work:
    /// periodic sync, lightning-address recovery, private-mode initialization,
    /// the leaf and token-output optimizers, the Spark server-event
    /// subscription, and the real-time sync client (when
    /// `real_time_sync_server_url` is set).
    ///
    /// When `false`, **no background service is started**, regardless of any
    /// other setting on this config. This is intended for multi-tenant server
    /// deployments where the host application orchestrates sync and claims
    /// explicitly and receives events via webhooks. Use
    /// `default_server_config` to get this preset.
    ///
    /// Explicit operations (`sync_wallet`, `claim_deposit`,
    /// `list_unclaimed_deposits`, `refund_deposit`,
    /// `refund_pending_conversions`, leaf/token optimization, etc.) work
    /// regardless of this flag.
    ///
    /// When `false`, the SDK rejects builds where fields whose backing
    /// service is gated off are still in their active shape:
    /// `stable_balance_config` must be `None`, `real_time_sync_server_url`
    /// must be `None`, and `optimization_config.auto_enabled` must be `false`.
    /// `default_server_config` already sets these compatible values.
    pub background_tasks_enabled: bool,

    /// Routes the connections the SDK opens through a SOCKS5 proxy.
    ///
    /// Covers HTTP and gRPC alike, and resolves hostnames at the proxy so no
    /// DNS query leaks the destination. `None` (default) connects directly.
    ///
    /// When an [`SdkContext`](crate::SdkContext) is supplied to the builder,
    /// its proxy must match this one: the context owns the shared clients, so
    /// a disagreement would mean part of the traffic bypassed the proxy.
    pub proxy: Option<ProxyConfig>,

    /// Enables cross-chain payments: sending and receiving USDC/USDT on other
    /// chains. Set it to a default `CrossChainConfig`, or one with your own
    /// defaults, to turn the feature on. Unset (the default) leaves it off, and
    /// the cross-chain calls fail with a `CrossChainDisabled` error.
    ///
    /// Off by default because the providers run background work such as web
    /// sockets. Only supported on mainnet.
    pub cross_chain_config: Option<CrossChainConfig>,
}

/// Configuration for cross-chain payments. Setting it on the config turns the
/// feature on.
#[derive(Debug, Clone, Default)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CrossChainConfig {
    /// Default maximum slippage in basis points used when
    /// [`PaymentRequest::CrossChain::max_slippage_bps`] is not set on the
    /// prepare request. Must be in 10 to 500. Falls back to 100 bps (1%)
    /// when this field is unset.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub default_slippage_bps: Option<u32>,
    /// Default target-overpay pad in basis points applied to the user's
    /// destination amount on `FeesExcluded` conversion sends. Bumps the
    /// target upward before quoting so the recipient lands at or above the
    /// requested amount despite provider slippage. Must be in 0 to 500.
    /// Falls back to 15 bps when unset.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub default_target_overpay_bps: Option<u32>,
}

impl CrossChainConfig {
    pub(crate) fn validate(&self) -> Result<(), SdkError> {
        if let Some(bps) = self.default_slippage_bps
            && !(crate::cross_chain::MIN_CROSS_CHAIN_SLIPPAGE_BPS
                ..=crate::cross_chain::MAX_CROSS_CHAIN_SLIPPAGE_BPS)
                .contains(&bps)
        {
            return Err(SdkError::InvalidInput(format!(
                "Default cross-chain slippage must be between {} and {} basis points, but got {bps}.",
                crate::cross_chain::MIN_CROSS_CHAIN_SLIPPAGE_BPS,
                crate::cross_chain::MAX_CROSS_CHAIN_SLIPPAGE_BPS,
            )));
        }
        if let Some(bps) = self.default_target_overpay_bps
            && !(crate::cross_chain::MIN_TARGET_OVERPAY_BPS
                ..=crate::cross_chain::MAX_TARGET_OVERPAY_BPS)
                .contains(&bps)
        {
            return Err(SdkError::InvalidInput(format!(
                "Default cross-chain target-overpay must be between {} and {} basis points, but got {bps}.",
                crate::cross_chain::MIN_TARGET_OVERPAY_BPS,
                crate::cross_chain::MAX_TARGET_OVERPAY_BPS,
            )));
        }
        Ok(())
    }
}

/// Configuration for leaf optimization.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LeafOptimizationConfig {
    /// Whether automatic leaf optimization is enabled.
    ///
    /// If set to true, the SDK will automatically optimize the leaf set when it changes.
    /// Otherwise, the manual optimization API must be used to optimize the leaf set.
    ///
    /// Default value is true.
    pub auto_enabled: bool,
    /// The desired multiplicity for the leaf set.
    ///
    /// Setting this to 0 will optimize for maximizing unilateral exit.
    /// Higher values will optimize for minimizing transfer swaps, with higher values
    /// being more aggressive and allowing better TPS rates.
    ///
    /// For end-user wallets, values of 1-5 are recommended. Values above 5 are
    /// intended for high-throughput server environments and are not recommended
    /// for end-user wallets due to significantly higher unilateral exit costs.
    ///
    /// Default value is 1.
    pub multiplicity: u8,
}

/// Configuration for token-output optimization.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct TokenOptimizationConfig {
    /// Whether automatic token-output consolidation is enabled.
    ///
    /// If set to true, the SDK will periodically consolidate a token's outputs
    /// once their count exceeds [`Self::min_outputs_threshold`]. Otherwise, no
    /// automatic consolidation is performed.
    ///
    /// Default value is true.
    pub auto_enabled: bool,
    /// Number of token outputs to produce when token-output auto-consolidation
    /// fires.
    ///
    /// Instead of collapsing a token's outputs into a single output (which
    /// serializes subsequent payments), the SDK splits the consolidated balance
    /// across this many outputs of roughly equal value. Higher values preserve
    /// concurrency for parallel sends at the cost of a slightly larger output
    /// set.
    ///
    /// Must be >= 1 and strictly less than [`Self::min_outputs_threshold`].
    ///
    /// Default value is 5.
    pub target_output_count: u32,
    /// Output count that triggers per-token auto-consolidation.
    ///
    /// Auto-consolidation triggers for a token when its available output count
    /// strictly exceeds this threshold.
    ///
    /// Must be greater than 1.
    ///
    /// Default value is 50.
    pub min_outputs_threshold: u32,
}

/// A stable token that can be used for automatic balance conversion.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct StableBalanceToken {
    /// Integrator-defined display label for the token, e.g. "USD".
    ///
    /// This is a short, human-readable name set by the integrator for display purposes.
    /// It is **not** a canonical Spark token ticker — it has no protocol-level meaning.
    /// Labels must be unique within the [`StableBalanceConfig::tokens`] list.
    pub label: String,

    /// The full token identifier string used for conversions.
    pub token_identifier: String,
}

/// Configuration for automatic conversion of Bitcoin to stable tokens.
///
/// When configured, the SDK automatically monitors the Bitcoin balance after each
/// wallet sync. Once the balance reaches the configured threshold, the SDK converts
/// the whole Bitcoin balance to the active stable token.
///
/// When the balance is held in a stable token, Bitcoin payments can still be sent.
/// The SDK automatically detects when there's not enough Bitcoin balance to cover a
/// payment and auto-populates the token-to-Bitcoin conversion options to facilitate
/// the payment.
///
/// The active token can be changed at runtime via [`UpdateUserSettingsRequest`].
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct StableBalanceConfig {
    /// Available tokens that can be used for stable balance.
    pub tokens: Vec<StableBalanceToken>,

    /// The label of the token to activate by default.
    ///
    /// If `None`, stable balance starts deactivated. The user can activate it
    /// at runtime via [`UpdateUserSettingsRequest`]. If a user setting is cached
    /// locally, it takes precedence over this default.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub default_active_label: Option<String>,

    /// The minimum sats balance that triggers auto-conversion.
    ///
    /// If not provided, uses the minimum from conversion limits.
    /// If provided but less than the conversion limit minimum, the limit minimum is used.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub threshold_sats: Option<u64>,

    /// Maximum slippage in basis points (1/100 of a percent).
    ///
    /// Defaults to 10 bps (0.1%) if not set.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub max_slippage_bps: Option<u32>,
}

/// Specifies how to update the active stable balance token.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum StableBalanceActiveLabel {
    /// Activate stable balance with the given label.
    Set { label: String },
    /// Deactivate stable balance.
    Unset,
}

/// Configuration for a custom Spark environment.
///
/// When set on [`Config`], overrides the default Spark operator pool,
/// service provider, threshold, and token settings. This allows connecting
/// to alternative Spark deployments (e.g. dev/staging environments).
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SparkConfig {
    /// Hex-encoded identifier of the coordinator operator.
    pub coordinator_identifier: String,
    /// The FROST signing threshold (e.g. 2 of 3).
    pub threshold: u32,
    /// The set of signing operators.
    pub signing_operators: Vec<SparkSigningOperator>,
    /// Service provider (SSP) configuration.
    pub ssp_config: SparkSspConfig,
    /// Expected bond amount in sats for token withdrawals.
    pub expected_withdraw_bond_sats: u64,
    /// Expected relative block locktime for token withdrawals.
    pub expected_withdraw_relative_block_locktime: u64,
    /// Cap on the inputs a single token transaction may spend. A send needing
    /// more first consolidates the wallet's token outputs. Unset uses the SDK
    /// default (500).
    pub max_token_transaction_inputs: Option<u32>,
}

impl From<&SparkConfig> for spark_wallet::SparkDeployment {
    fn from(config: &SparkConfig) -> Self {
        Self {
            coordinator_identifier: config.coordinator_identifier.clone(),
            threshold: config.threshold,
            signing_operators: config
                .signing_operators
                .iter()
                .map(|operator| spark_wallet::SparkDeploymentOperator {
                    id: operator.id,
                    identifier: operator.identifier.clone(),
                    address: operator.address.clone(),
                    identity_public_key: operator.identity_public_key.clone(),
                    ca_cert_pem: operator.ca_cert_pem.clone(),
                })
                .collect(),
            ssp_config: spark_wallet::SparkDeploymentSsp {
                base_url: config.ssp_config.base_url.clone(),
                identity_public_key: config.ssp_config.identity_public_key.clone(),
                schema_endpoint: config.ssp_config.schema_endpoint.clone(),
            },
            expected_withdraw_bond_sats: config.expected_withdraw_bond_sats,
            expected_withdraw_relative_block_locktime: config
                .expected_withdraw_relative_block_locktime,
            max_token_transaction_inputs: config.max_token_transaction_inputs,
        }
    }
}

/// A Spark signing operator.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SparkSigningOperator {
    /// Sequential operator ID (0-indexed).
    pub id: u32,
    /// Hex-encoded 32-byte FROST identifier.
    pub identifier: String,
    /// gRPC address of the operator (e.g. `https://0.spark.lightspark.com`).
    pub address: String,
    /// Hex-encoded compressed public key of the operator.
    pub identity_public_key: String,
    /// Optional PEM-encoded CA certificate for TLS verification.
    /// When set, the SDK uses this CA to verify the operator's TLS certificate
    /// instead of the system/default roots. Useful for local development with
    /// self-signed certificates.
    pub ca_cert_pem: Option<String>,
}

/// Configuration for the Spark Service Provider (SSP).
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SparkSspConfig {
    /// Base URL of the SSP GraphQL API.
    pub base_url: String,
    /// Hex-encoded compressed public key of the SSP.
    pub identity_public_key: String,
    /// Optional GraphQL schema endpoint path (e.g. "graphql/spark/rc").
    /// Defaults to the hardcoded schema endpoint if not set.
    pub schema_endpoint: Option<String>,
}

impl Config {
    /// Validates the configuration.
    ///
    /// Returns an error if any configuration values are invalid.
    pub fn validate(&self) -> Result<(), SdkError> {
        if self.network == Network::Signet && self.spark_config.is_none() {
            return Err(SdkError::InvalidInput(
                "Signet requires an explicit spark_config with signing operators and an SSP"
                    .to_string(),
            ));
        }
        if self.max_concurrent_claims == 0 {
            return Err(SdkError::InvalidInput(
                "max_concurrent_claims must be greater than 0".to_string(),
            ));
        }

        if let Some(sb) = &self.stable_balance_config {
            if sb.tokens.is_empty() {
                return Err(SdkError::InvalidInput(
                    "tokens must not be empty".to_string(),
                ));
            }

            let mut seen_labels = HashSet::new();
            let mut seen_identifiers = HashSet::new();
            for token in &sb.tokens {
                if token.label.is_empty() {
                    return Err(SdkError::InvalidInput(
                        "token label must not be empty".to_string(),
                    ));
                }
                if token.token_identifier.is_empty() {
                    return Err(SdkError::InvalidInput(
                        "token_identifier must not be empty".to_string(),
                    ));
                }
                if bech32m_decode_token_id(&token.token_identifier, Some(self.network.into()))
                    .is_err()
                {
                    return Err(SdkError::InvalidInput(format!(
                        "token_identifier must be a bech32m token identifier for this network: {}",
                        token.token_identifier
                    )));
                }
                if !seen_labels.insert(&token.label) {
                    return Err(SdkError::InvalidInput(format!(
                        "tokens contains duplicate label: {}",
                        token.label
                    )));
                }
                if !seen_identifiers.insert(&token.token_identifier) {
                    return Err(SdkError::InvalidInput(format!(
                        "tokens contains duplicate token_identifier: {}",
                        token.token_identifier
                    )));
                }
            }

            if let Some(bps) = sb.max_slippage_bps
                && bps > 10000
            {
                return Err(SdkError::InvalidInput(
                    "max_slippage_bps must be <= 10000".to_string(),
                ));
            }

            if let Some(default_label) = &sb.default_active_label
                && !seen_labels.contains(default_label)
            {
                return Err(SdkError::InvalidInput(format!(
                    "default_active_label '{default_label}' not found in tokens list"
                )));
            }
        }

        self.validate_token_optimization()?;
        self.proxy.as_ref().map_or(Ok(()), ProxyConfig::validate)?;

        if let Some(cc) = &self.cross_chain_config {
            if self.network != Network::Mainnet {
                return Err(SdkError::InvalidInput(format!(
                    "Cross-chain sends are only available on Mainnet, not on {}.",
                    self.network,
                )));
            }
            cc.validate()?;
        }

        Ok(())
    }

    fn validate_token_optimization(&self) -> Result<(), SdkError> {
        let token_opt = &self.token_optimization_config;
        if token_opt.min_outputs_threshold <= 1 {
            return Err(SdkError::InvalidInput(
                "token optimization minimum outputs threshold must be greater than 1".to_string(),
            ));
        }
        if token_opt.target_output_count < 1 {
            return Err(SdkError::InvalidInput(
                "token optimization target output count must be at least 1".to_string(),
            ));
        }
        if token_opt.target_output_count >= token_opt.min_outputs_threshold {
            return Err(SdkError::InvalidInput(
                "token optimization target output count must be less than the minimum outputs threshold".to_string(),
            ));
        }
        Ok(())
    }

    pub(crate) fn get_all_external_input_parsers(&self) -> Vec<ExternalInputParser> {
        let mut external_input_parsers = Vec::new();
        if self.use_default_external_input_parsers {
            let default_parsers = DEFAULT_EXTERNAL_INPUT_PARSERS
                .iter()
                .map(|(id, regex, url)| ExternalInputParser {
                    provider_id: (*id).to_string(),
                    input_regex: (*regex).to_string(),
                    parser_url: (*url).to_string(),
                })
                .collect::<Vec<_>>();
            external_input_parsers.extend(default_parsers);
        }
        external_input_parsers.extend(self.external_input_parsers.clone().unwrap_or_default());

        external_input_parsers
    }
}

/// The most a deposit claim may cost: an on-chain part plus an optional share
/// of the deposit amount.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(from = "StoredMaxFee", into = "StoredMaxFee")]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct MaxFee {
    pub onchain: MaxOnchainFee,
    /// A share of the deposit amount added on top of the on-chain part, in parts
    /// per million (100 ppm is 0.01%), to allow for a provider fee that grows
    /// with the deposit. It applies to every claim, early ones included. Unset
    /// adds nothing.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub proportional_ppm: Option<u32>,
}

/// The on-chain part of a [`MaxFee`].
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum MaxOnchainFee {
    /// A fixed amount in sats.
    Fixed { amount: u64 },
    /// A fee rate in sats per vbyte.
    Rate { sat_per_vbyte: u64 },
    /// The fastest recommended fee rate at the time of the claim plus a leeway in
    /// sats per vbyte.
    NetworkRecommended { leeway_sat_per_vbyte: u64 },
}

/// How a [`MaxFee`] is persisted: one variant per on-chain kind, each carrying the
/// proportional part. Ceilings stored before the split are in this shape, so
/// keeping it lets them load as they are.
#[derive(Serialize, Deserialize)]
enum StoredMaxFee {
    Fixed {
        amount: u64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        proportional_ppm: Option<u32>,
    },
    Rate {
        sat_per_vbyte: u64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        proportional_ppm: Option<u32>,
    },
    NetworkRecommended {
        leeway_sat_per_vbyte: u64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        proportional_ppm: Option<u32>,
    },
}

impl From<StoredMaxFee> for MaxFee {
    fn from(stored: StoredMaxFee) -> Self {
        let (onchain, proportional_ppm) = match stored {
            StoredMaxFee::Fixed {
                amount,
                proportional_ppm,
            } => (MaxOnchainFee::Fixed { amount }, proportional_ppm),
            StoredMaxFee::Rate {
                sat_per_vbyte,
                proportional_ppm,
            } => (MaxOnchainFee::Rate { sat_per_vbyte }, proportional_ppm),
            StoredMaxFee::NetworkRecommended {
                leeway_sat_per_vbyte,
                proportional_ppm,
            } => (
                MaxOnchainFee::NetworkRecommended {
                    leeway_sat_per_vbyte,
                },
                proportional_ppm,
            ),
        };
        MaxFee {
            onchain,
            proportional_ppm,
        }
    }
}

impl From<MaxFee> for StoredMaxFee {
    fn from(max_fee: MaxFee) -> Self {
        let proportional_ppm = max_fee.proportional_ppm;
        match max_fee.onchain {
            MaxOnchainFee::Fixed { amount } => StoredMaxFee::Fixed {
                amount,
                proportional_ppm,
            },
            MaxOnchainFee::Rate { sat_per_vbyte } => StoredMaxFee::Rate {
                sat_per_vbyte,
                proportional_ppm,
            },
            MaxOnchainFee::NetworkRecommended {
                leeway_sat_per_vbyte,
            } => StoredMaxFee::NetworkRecommended {
                leeway_sat_per_vbyte,
                proportional_ppm,
            },
        }
    }
}

impl MaxFee {
    /// The share of the deposit amount allowed on top of the on-chain part, in
    /// parts per million.
    pub(crate) fn proportional_ppm(&self) -> u32 {
        self.proportional_ppm.unwrap_or(0)
    }

    /// The on-chain part of the ceiling, priced at the current fee market.
    pub(crate) async fn to_fee(&self, fee_market: &FeeMarket<'_>) -> Result<Fee, SdkError> {
        match &self.onchain {
            MaxOnchainFee::Fixed { amount } => Ok(Fee::Fixed { amount: *amount }),
            MaxOnchainFee::Rate { sat_per_vbyte } => Ok(Fee::Rate {
                sat_per_vbyte: *sat_per_vbyte,
            }),
            MaxOnchainFee::NetworkRecommended {
                leeway_sat_per_vbyte,
            } => {
                let recommended_fees = fee_market.recommended_fees().await?;
                let max_fee_rate = recommended_fees
                    .fastest_fee
                    .saturating_add(*leeway_sat_per_vbyte);
                Ok(Fee::Rate {
                    sat_per_vbyte: max_fee_rate,
                })
            }
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum Fee {
    // Fixed fee amount in sats
    Fixed { amount: u64 },
    // Relative fee rate in satoshis per vbyte
    Rate { sat_per_vbyte: u64 },
}

impl Fee {
    pub fn to_sats(&self, vbytes: u64) -> u64 {
        match self {
            Fee::Fixed { amount } => *amount,
            Fee::Rate { sat_per_vbyte } => sat_per_vbyte.saturating_mul(vbytes),
        }
    }
}

/// State of an instant claim attempt on a deposit.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum InstantClaimStatus {
    /// The early claim was declined and the deposit falls through to the claim at
    /// maturity. `max_fee_sats` is the ceiling that declined it, unset when the
    /// decline was for a reason no ceiling will fix. `confirmations` is the depth
    /// it was declined at.
    Declined {
        max_fee_sats: Option<u64>,
        #[serde(default)]
        confirmations: u32,
    },
    /// An instant claim was submitted and is settling. Carries the SSP claim id.
    Submitted { claim_id: String },
    /// A claim has taken the deposit: either its credit arrived here, or the
    /// provider reports the deposit as already claimed. It stays listed until
    /// the provider spends the output, so treat it as settled rather than as
    /// awaiting action.
    Claimed,
}

/// State of the deposit refund broadcast.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum RefundState {
    /// The refund is signed and stored but has not been seen on the network.
    /// `last_error` carries the reason the most recent broadcast was refused,
    /// unset while none has been refused. A refund whose fee is under the
    /// network's current minimum stays here until it is re-created at a higher
    /// fee.
    BroadcastPending { last_error: Option<String> },
    /// The refund has been accepted by the network and is waiting to confirm.
    Broadcast,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct DepositInfo {
    /// Transaction id of the on-chain output the deposit came from.
    pub txid: String,
    /// Index of that output within its transaction.
    pub vout: u32,
    /// Deposit value in satoshis.
    pub amount_sats: u64,
    /// Whether the deposit has enough confirmations to be claimed.
    pub is_mature: bool,
    /// Raw refund transaction, once one has been created.
    pub refund_tx: Option<String>,
    /// Transaction id of the refund, once one has been created.
    pub refund_tx_id: Option<String>,
    /// How far the refund has got towards the network. Unset when no refund has
    /// been created, and on refunds created before this field existed.
    pub refund_state: Option<RefundState>,
    /// Why the last claim attempt failed. Unset while none has failed.
    pub claim_error: Option<DepositClaimError>,
    /// Unset when no instant claim has been attempted.
    pub instant_claim_status: Option<InstantClaimStatus>,
    /// The fee ceiling standing for this deposit alone. It caps what may be paid
    /// to claim the deposit ahead of maturity. The claim at maturity runs under
    /// whichever is larger, this or the configured max deposit claim fee, so a
    /// ceiling set below that one does not hold the deposit back from it. Unset
    /// means the configured ceiling applies to both.
    pub max_claim_fee: Option<MaxFee>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ClaimDepositRequest {
    pub txid: String,
    pub vout: u32,
    /// Caps what the claim may cost, and is recorded on the deposit so later
    /// automatic attempts are held to it too.
    ///
    /// Raising it above the quoted spread is what lets a deposit be claimed ahead
    /// of maturity without further input. Lowering it below the spread keeps the
    /// deposit from being claimed early, and does not hold back its claim at
    /// maturity: that one runs under whichever is larger, this or the configured
    /// max deposit claim fee.
    ///
    /// Unset claims under the configured max deposit claim fee and clears any
    /// ceiling previously recorded on the deposit.
    ///
    /// The ceiling is recorded before the claim is attempted, so it stands even
    /// when the attempt is then declined for exceeding it.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub max_fee: Option<MaxFee>,
}

/// Why a claim was deferred rather than made.
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ClaimDeferredReason {
    /// Claiming ahead of maturity costs more than the fee ceiling allows. Unlike a
    /// depth that has not arrived, this does not clear on its own: the deposit is
    /// claimed at maturity unless the ceiling is raised.
    ///
    /// `required_fee_sats` is what the early claim would have cost, so a caller can
    /// offer it at that price rather than quoting again.
    MaxFeeExceeded {
        /// What the provider asked to credit the deposit early.
        required_fee_sats: u64,
        /// The ceiling it was held to.
        max_fee_sats: u64,
    },
    /// The provider offers no early claim at the deposit's current depth, either
    /// because it is too shallow for any plan or because none was offered for it.
    /// Depth is the usual cause, and it resolves itself: the next confirmation may
    /// well bring an early claim within reach.
    NoEarlyClaimAvailable,
    /// The provider refused the early claim or could not be reached, so nothing was
    /// submitted. Unlike a depth that has not arrived, waiting for a confirmation
    /// does not address this, and the deposit is claimed at maturity unless a later
    /// call succeeds. `message` is what the provider or the transport reported.
    ProviderDeclined { message: String },
}

/// What became of a claim.
#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ClaimDepositOutcome {
    /// Claimed at maturity and settled, carrying the payment it produced.
    Settled { payment: Payment },
    /// Claimed ahead of maturity and submitted. The transfer settles
    /// asynchronously, so no payment is returned yet: watch for it via events or
    /// `list_payments`.
    Submitted,
    /// Nothing was claimed yet, and no further call is needed: any fee ceiling this
    /// one asked for stands on the deposit, and the SDK keeps claiming it on its
    /// own. An early claim is attempted again as the deposit gains confirmations,
    /// so one declined for being too shallow is often claimed early a block or two
    /// later. Failing that, the deposit is claimed at maturity.
    ///
    /// An ordinary outcome rather than a failure. `reason` says which of the two to
    /// expect: a depth that has not arrived yet, or a cost the ceiling will not
    /// cover.
    Deferred { reason: ClaimDeferredReason },
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ClaimDepositResponse {
    /// What the call did. Which outcome occurs follows from the deposit's maturity
    /// and the fee ceiling, not from anything the caller asks for, so handle all
    /// three on every claim.
    pub outcome: ClaimDepositOutcome,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct FetchClaimDepositQuoteRequest {
    pub txid: String,
    pub vout: u32,
}

/// What one way of claiming a deposit costs.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ClaimDepositQuote {
    /// The depth this becomes claimable at, as a total confirmation count on the
    /// deposit tx and not a number still to wait. A deposit already at or past
    /// this depth can be claimed.
    pub confirmations_required: u32,
    /// What reaches the balance.
    pub credit_amount_sats: u64,
    /// The deposit value less the credit.
    pub fee_sats: u64,
    /// The most this claim may cost for this deposit, in sats, under the max claim
    /// fee that applies to it. The SDK claims automatically when `fee_sats` is
    /// within it. Unset when automatic claiming is off.
    pub max_fee_sats: Option<u64>,
    /// The provider would not quote this yet, so the fee is derived from current
    /// on-chain fees and the real one may differ.
    pub is_estimate: bool,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct FetchClaimDepositQuoteResponse {
    pub amount_sats: u64,
    /// Confirmations the deposit has now, 0 while unconfirmed.
    pub confirmations: u32,
    /// Claiming ahead of maturity, for a spread. Absent when the provider offers
    /// no such option for this deposit, and when claiming early would not actually
    /// be earlier: a deposit that has already matured, or a plan crediting no
    /// sooner than maturity would, is only ever the more expensive way to wait.
    ///
    /// Also absent when the provider could not be reached for a quote, which is not
    /// distinguished here from having nothing to offer: both mean there is no early
    /// claim to show right now, and the one worth retrying is the transient one.
    ///
    /// Priced regardless of the max claim fee, so it can be offered: its
    /// `fee_sats` within its `max_fee_sats` means the SDK claims it on its own.
    /// Claiming it by hand needs a max fee of at least its `fee_sats`.
    pub instant: Option<ClaimDepositQuote>,
    /// Claiming once the deposit matures.
    pub mature: ClaimDepositQuote,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RefundDepositRequest {
    pub txid: String,
    pub vout: u32,
    pub destination_address: String,
    pub fee: Fee,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RefundDepositResponse {
    pub tx_id: String,
    pub tx_hex: String,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ListUnclaimedDepositsRequest {}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ListUnclaimedDepositsResponse {
    pub deposits: Vec<DepositInfo>,
}

/// The available providers for buying Bitcoin
/// Request to buy Bitcoin using an external provider.
///
/// Each variant carries only the parameters relevant to that provider.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum BuyBitcoinRequest {
    /// `MoonPay`: Fiat purchase via credit card, Apple Pay, etc.
    Moonpay {
        /// How `MoonPay` delivers the purchase. Defaults to Bitcoin with no
        /// amount.
        delivery: Option<MoonpayDelivery>,
        /// Custom redirect URL after purchase completion.
        redirect_url: Option<String>,
    },
    /// `CashApp`: Pay via the Lightning Network.
    /// Returns a `cash.app` deep link to a bolt11 invoice. A conversion
    /// provider delivers the payment to the wallet over Spark, and the payer
    /// pays its fee on top of the amount. Only available on mainnet.
    ///
    /// The amount is required. With an amountless invoice, Cash App only
    /// lets the payer fund from their existing Cash App BTC balance. With
    /// a fixed-amount invoice, Cash App opens up funding via fiat balance
    /// and debit card.
    CashApp {
        /// Amount in satoshis the wallet receives. Must be non-zero.
        amount_sats: u64,
    },
}

impl Default for BuyBitcoinRequest {
    fn default() -> Self {
        Self::Moonpay {
            delivery: None,
            redirect_url: None,
        }
    }
}

/// How a `MoonPay` purchase is delivered.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum MoonpayDelivery {
    /// Bitcoin to an on-chain deposit address.
    Bitcoin {
        /// Amount in satoshis to prefill the checkout with.
        amount_sat: Option<u64>,
    },
    /// USDC on Solana, converted on arrival into the active stable balance
    /// token if set, otherwise Bitcoin. Requires `cross_chain_config`.
    CrossChain {
        /// USD amount to prefill the checkout with, in 6-decimal base units
        /// (`1_000_000` is $1).
        amount: u128,
        /// Whether the conversion fee is added on top of `amount`
        /// (`FeesExcluded`, the default) or deducted from it (`FeesIncluded`).
        fee_mode: Option<crate::cross_chain::CrossChainFeeMode>,
    },
}

impl Default for MoonpayDelivery {
    fn default() -> Self {
        Self::Bitcoin { amount_sat: None }
    }
}

/// Response containing a URL to complete the Bitcoin purchase
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BuyBitcoinResponse {
    /// The URL to open in a browser to complete the purchase
    pub url: String,
    /// The conversion quote, populated for cross-chain delivery and for
    /// `CashApp`, whose purchase is delivered through a conversion provider.
    pub cross_chain_info: Option<crate::cross_chain::CrossChainReceiveInfo>,
}

/// Response from refunding pending conversions.
#[derive(Debug, Clone, Serialize, Default)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RefundPendingConversionsResponse {
    /// Conversions successfully refunded this pass.
    pub refunded: u32,
    /// Conversions not clawed back this pass: held back by a safety window, or
    /// found to have executed after all. Only the former are retried.
    pub skipped: u32,
    /// Conversions whose clawback did not complete this pass (rejected or
    /// errored; funds not returned). The next pass will retry them.
    pub failed: u32,
}

/// **Deprecated.** Use `CreateBridgeRequest` with the bridging client's
/// `bridge_from_cash_app`.
///
/// Request for a payment link that sends USDC/USDT to an external-chain
/// recipient, funded by Cash App over Lightning.
///
/// The user pays the returned URL, and the cross-chain provider delivers the
/// stablecoin to `address`. No funds move through the Spark wallet. Only
/// available on mainnet.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PreparePaymentLinkRequest {
    /// Recipient address on the destination chain (e.g. an EVM `0x...` address).
    pub address: String,
    /// The destination route from calling `get_cross_chain_routes()` with the
    /// `CrossChainRouteFilter::PaymentLink` filter. Selects the destination chain
    /// + asset (e.g. USDC on Base).
    pub route: CrossChainRoutePair,
    /// Amount in the destination asset's base units, per the route's
    /// `decimals`. These routes deliver USD-pegged stablecoins, so at parity
    /// this is the USD value: `1_000_000` is 1 USDC (6 decimals), about $1.
    ///
    /// With the default fee policy the recipient receives this net amount.
    /// With `FeesIncluded` it is the amount the payer deposits.
    pub amount: u128,
    /// Whether fees are added on top of `amount` (`FeesExcluded`, the default)
    /// or deducted from it (`FeesIncluded`).
    pub fee_policy: Option<FeePolicy>,
    /// Maximum slippage tolerance in basis points. Falls back to the SDK
    /// default when unset.
    pub max_slippage_bps: Option<u32>,
}

/// **Deprecated.** Use `CreateBridgeResponse`, from the bridging client's
/// `bridge_from_cash_app`.
///
/// Response to a [`PreparePaymentLinkRequest`]. Mirrors `BuyBitcoinResponse`
/// (a payable `url`) plus the quote so the caller can display the expected
/// delivery and fees.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PreparePaymentLinkResponse {
    /// The URL to open in a browser; paying it delivers the stablecoin.
    pub url: String,
    /// Sats the payer deposits through the fiat rail.
    pub amount_sats: u64,
    /// Estimated amount delivered to the recipient, in `asset` base units.
    pub estimated_out: u128,
    /// The destination stablecoin symbol (e.g. `USDC`). `estimated_out` is
    /// denominated in it.
    pub asset: String,
    /// Provider service fee, including the partner fee when one is set, in
    /// `service_fee_asset` base units.
    pub service_fee_amount: u128,
    /// Denomination of `service_fee_amount`. `None` means sats: Boltz
    /// denominates its fee in sats, Orchestra in the stablecoin.
    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>,
    /// RFC3339 timestamp after which the quote is no longer valid.
    pub expires_at: String,
}

/// **Deprecated.** Use `CreateBridgeRequest` with the bridging client's
/// `bridge_from_cash_app`.
///
/// Request to bridge from Cash App to USDC/USDT on an external chain.
///
/// The payer pays the returned URL in Cash App over Lightning, and the
/// cross-chain provider delivers the stablecoin to `address`. No funds move
/// through the Spark wallet. Only available on mainnet.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BridgeFromCashAppRequest {
    /// Recipient address on the destination chain (e.g. an EVM `0x...` address).
    pub address: String,
    /// The destination route from calling `get_cross_chain_routes()` with the
    /// `CrossChainRouteFilter::Send` filter and its `delivery_method` set to
    /// `Lightning`. Selects the destination chain + asset (e.g. USDC on Base).
    pub route: CrossChainRoutePair,
    /// Amount in the destination asset's base units, per the route's
    /// `decimals`. These routes deliver USD-pegged stablecoins, so at parity
    /// this is the USD value: `1_000_000` is 1 USDC (6 decimals), about $1.
    ///
    /// With the default fee policy the recipient receives this net amount.
    /// With `FeesIncluded` it is the amount the payer deposits.
    pub amount: u128,
    /// Whether fees are added on top of `amount` (`FeesExcluded`, the default)
    /// or deducted from it (`FeesIncluded`).
    pub fee_policy: Option<FeePolicy>,
    /// Maximum slippage tolerance in basis points. Falls back to the SDK
    /// default when unset.
    pub max_slippage_bps: Option<u32>,
}

/// **Deprecated.** Use `CreateBridgeResponse`, from the bridging client's
/// `bridge_from_cash_app`.
///
/// Response to a [`BridgeFromCashAppRequest`]: the URL to pay plus the quote,
/// so the caller can display the expected delivery and fees.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BridgeFromCashAppResponse {
    /// The `cash.app` URL to open. Paying it delivers the stablecoin.
    pub url: String,
    /// Sats the payer deposits through Cash App.
    pub amount_sats: u64,
    /// Estimated amount delivered to the recipient, in `asset` base units.
    pub estimated_out: u128,
    /// The destination stablecoin symbol (e.g. `USDC`). `estimated_out` is
    /// denominated in it.
    pub asset: String,
    /// Provider service fee, including the partner fee when one is set, in
    /// `service_fee_asset` base units.
    pub service_fee_amount: u128,
    /// Denomination of `service_fee_amount`. Unset means 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,
}

impl From<PreparePaymentLinkRequest> for BridgeFromCashAppRequest {
    fn from(request: PreparePaymentLinkRequest) -> Self {
        BridgeFromCashAppRequest {
            address: request.address,
            route: request.route,
            amount: request.amount,
            fee_policy: request.fee_policy,
            max_slippage_bps: request.max_slippage_bps,
        }
    }
}

impl From<BridgeFromCashAppResponse> for PreparePaymentLinkResponse {
    fn from(response: BridgeFromCashAppResponse) -> Self {
        PreparePaymentLinkResponse {
            url: response.url,
            amount_sats: response.amount_sats,
            estimated_out: response.estimated_out,
            asset: response.asset,
            service_fee_amount: response.service_fee_amount,
            service_fee_asset: response.service_fee_asset,
            service_fee_asset_decimals: response.service_fee_asset_decimals,
            expires_at: i64::try_from(response.expires_at)
                .ok()
                .and_then(|secs| chrono::DateTime::from_timestamp(secs, 0))
                .map_or_else(
                    || response.expires_at.to_string(),
                    |dt| dt.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
                ),
        }
    }
}

/// **Deprecated.** Use `CreateBridgeRequest` with the bridging client's
/// `bridge_to_cash_app`.
///
/// Request to bridge USDC/USDT from an external chain to a Cash App user.
///
/// The payer deposits the stablecoin to the returned address, and the
/// cross-chain provider pays the recipient in Bitcoin over Lightning. No funds
/// move through the Spark wallet. Only available on mainnet.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BridgeToCashAppRequest {
    /// The Cash App user, as a username (`alice` or `$alice`) or a Cash App
    /// Lightning address (`alice@cash.app`).
    pub recipient: String,
    /// The source route from calling `get_cross_chain_routes()` with the
    /// `CrossChainRouteFilter::Receive` filter and its `delivery_method` set to
    /// `Lightning`. Selects the source chain + asset (e.g. USDC on Base).
    pub route: CrossChainRoutePair,
    /// Amount in the source asset's base units, per the route's `decimals`.
    /// These routes carry USD-pegged stablecoins, so at parity this is the USD
    /// value: `1_000_000` is 1 USDC (6 decimals), about $1.
    ///
    /// With the default fee policy the recipient receives about this value in
    /// Bitcoin. With `FeesIncluded` it is the amount the payer deposits.
    pub amount: u128,
    /// Whether fees are added on top of `amount` (`FeesExcluded`, the default)
    /// or deducted from it (`FeesIncluded`).
    pub fee_policy: Option<FeePolicy>,
    /// The payer's address on the source chain. The deposit is refunded here
    /// if the recipient can't be paid.
    pub refund_address: String,
    /// Maximum slippage tolerance in basis points. Falls back to the SDK
    /// default when unset.
    pub max_slippage_bps: Option<u32>,
}

/// **Deprecated.** Use `CreateBridgeResponse`, from the bridging client's
/// `bridge_to_cash_app`.
///
/// Response to a [`BridgeToCashAppRequest`].
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BridgeToCashAppResponse {
    /// What the payer pays: an EIP-681 URI on EVM chains, otherwise the bare
    /// deposit address.
    pub payment_request: String,
    /// The deposit and the expected delivery. `expected_received_amount` is
    /// in sats.
    pub info: crate::cross_chain::CrossChainReceiveInfo,
}

impl std::fmt::Display for MaxFee {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match &self.onchain {
            MaxOnchainFee::Fixed { amount } => write!(f, "Fixed: {amount}")?,
            MaxOnchainFee::Rate { sat_per_vbyte } => write!(f, "Rate: {sat_per_vbyte}")?,
            MaxOnchainFee::NetworkRecommended {
                leeway_sat_per_vbyte,
            } => write!(f, "NetworkRecommended: {leeway_sat_per_vbyte}")?,
        }
        match self.proportional_ppm() {
            0 => Ok(()),
            ppm => write!(f, " + {ppm} ppm"),
        }
    }
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct Credentials {
    pub username: String,
    pub password: String,
}

/// Request to get the balance of the wallet
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct GetInfoRequest {
    /// When `Some(true)`, and `background_tasks_enabled` is `true`, the call
    /// waits for the initial Full sync to complete before returning. The sync
    /// can fail to reach the network: `last_sync_error` in the response says
    /// whether it did.
    ///
    /// When `background_tasks_enabled` is `false`, setting this to `Some(true)`
    /// is rejected with an invalid-input error. There is no background sync to
    /// wait on; call `sync_wallet` explicitly first if you need fresh state.
    pub ensure_synced: Option<bool>,
}

/// Response containing the balance of the wallet
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct GetInfoResponse {
    /// The identity public key of the wallet as a hex string
    pub identity_pubkey: String,
    /// The balance in satoshis
    pub balance_sats: u64,
    /// The balances of the tokens in the wallet keyed by the token identifier
    pub token_balances: HashMap<String, TokenBalance>,
    /// Funds that left `balance_sats` and wait to be recovered on-chain with
    /// `recover_funds`. The SDK on this device takes them out of this total
    /// once it has seen their recovery in a block, at the next sync at the
    /// latest. It looks for that in `prepare_recover_funds`, `recover_funds`
    /// and `check_recover_funds`, and during syncs at most once per leaf. The
    /// total includes funds too small to be worth recovering at the fee rate
    /// you choose.
    pub recoverable_funds_sats: u64,
    /// Why the latest sync could not refresh the balances, which may then be
    /// out of date. Unset once a sync succeeds. It is not persisted, so it is
    /// also unset after each `connect` until the first sync ends.
    pub last_sync_error: Option<SyncError>,
    /// When a sync last refreshed the balances, in seconds since the Unix
    /// epoch. Unset until a sync succeeds with this storage.
    pub last_synced_at: Option<u64>,
}

/// Why a sync could not refresh the balances. Each message is for logs, not
/// for display.
#[derive(Debug, Clone, PartialEq, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum SyncError {
    /// The network could not be reached, or is temporarily too busy to answer.
    Network { message: String },
    /// Any other failure.
    Generic { message: String },
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct TokenBalance {
    pub balance: u128,
    pub token_metadata: TokenMetadata,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct TokenMetadata {
    pub identifier: String,
    /// Hex representation of the issuer public key
    pub issuer_public_key: String,
    pub name: String,
    pub ticker: String,
    /// Number of decimals the token uses
    pub decimals: u32,
    pub max_supply: u128,
    pub is_freezable: bool,
}

/// Request to sync the wallet with the Spark network
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SyncWalletRequest {}

/// Response from synchronizing the wallet
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SyncWalletResponse {
    /// Why the sync could not refresh the balances, which may then be out of
    /// date. Unset when it succeeded.
    pub last_sync_error: Option<SyncError>,
    /// When a sync last refreshed the balances, in seconds since the Unix
    /// epoch. Unset until a sync succeeds with this storage.
    pub last_synced_at: Option<u64>,
}

#[derive(Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ReceivePaymentMethod {
    SparkAddress,
    SparkInvoice {
        /// Amount to receive. Denominated in sats if token identifier is empty, otherwise in the token base units
        amount: Option<u128>,
        /// The presence of this field indicates that the payment is for a token
        /// If empty, it is a Bitcoin payment
        token_identifier: Option<String>,
        /// The expiry time of the invoice as a unix timestamp in seconds
        expiry_time: Option<u64>,
        /// A description to embed in the invoice.
        description: Option<String>,
        /// If set, the invoice may only be fulfilled by a payer with this public key
        sender_public_key: Option<String>,
    },
    BitcoinAddress {
        /// If true, rotate to a new deposit address. Previous ones remain valid.
        /// If false or absent, return the existing address (creating one if none
        /// exists yet).
        new_address: Option<bool>,
    },
    Bolt11Invoice {
        description: String,
        amount_sats: Option<u64>,
        /// The expiry of the invoice as a duration in seconds
        expiry_secs: Option<u32>,
        /// If set, creates a HODL invoice with this payment hash (hex-encoded).
        /// The payer's HTLC will be held until the preimage is provided via
        /// `claim_htlc_payment` or the HTLC expires.
        payment_hash: Option<String>,
        /// Spark identity public key that will receive the payment.
        /// If absent, the connected wallet's identity public key is used.
        receiver_identity_public_key: Option<String>,
        /// If set, creates an invoice for the hash of this preimage (hex-encoded)
        /// instead of one the SDK generates. The SSP settles the payment without
        /// the receiver, and the payer learns the preimage. Use a random value
        /// below the secp256k1 group order, and a new one for each invoice. The
        /// invoice never includes a Spark address. Set at most one of this and
        /// `payment_hash`.
        preimage: Option<String>,
    },
    CrossChain {
        /// The selected cross-chain route in the receive direction.
        route: crate::cross_chain::CrossChainRoutePair,
        /// The amount, in the source asset's base units (`route.decimals`).
        /// USD-stable sources are at parity, so `1 USD = 10^route.decimals`
        /// (e.g. `1_000_000` for 6-decimal USDC/USDT, `10^18` for 18-decimal
        /// BSC USDC).
        ///
        /// - `FeesExcluded` (default): what the receiver ends up with, sized
        ///   as if `amount` source units were converted to the Spark-side
        ///   destination at parity (USDB) or the live BTC/USD rate (Bitcoin).
        /// - `FeesIncluded`: what the sender deposits. The receiver ends up
        ///   with that amount minus provider fees.
        amount: u128,
        /// Spark-side asset the receiver wants delivered. When absent, the
        /// SDK auto-selects: the wallet's active stable-balance token if
        /// the route supports it, otherwise Bitcoin (sats). When set, the
        /// value must appear in the route's `accepted_assets`.
        destination: Option<crate::cross_chain::SparkAsset>,
        /// How `amount` should be interpreted. When absent, defaults to
        /// `FeesExcluded`.
        fee_mode: Option<crate::cross_chain::CrossChainFeeMode>,
        /// Maximum slippage in basis points. When absent, the SDK default
        /// (100 bps) is used.
        max_slippage_bps: Option<u32>,
        /// Per-request override for the overpay buffer applied to the
        /// sender's deposit when `fee_mode == FeesExcluded`. Range 0 to 500.
        /// When absent, falls back to `CrossChainConfig::default_target_overpay_bps`
        /// then the built-in default (15 bps). Ignored when `fee_mode`
        /// is `FeesIncluded`.
        target_overpay_bps: Option<u32>,
    },
}

impl fmt::Debug for ReceivePaymentMethod {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ReceivePaymentMethod::SparkAddress => f.write_str("SparkAddress"),
            ReceivePaymentMethod::SparkInvoice {
                amount,
                token_identifier,
                expiry_time,
                description,
                sender_public_key,
            } => f
                .debug_struct("SparkInvoice")
                .field("amount", amount)
                .field("token_identifier", token_identifier)
                .field("expiry_time", expiry_time)
                .field("description", description)
                .field("sender_public_key", sender_public_key)
                .finish(),
            ReceivePaymentMethod::BitcoinAddress { new_address } => f
                .debug_struct("BitcoinAddress")
                .field("new_address", new_address)
                .finish(),
            ReceivePaymentMethod::Bolt11Invoice {
                description,
                amount_sats,
                expiry_secs,
                payment_hash,
                receiver_identity_public_key,
                preimage,
            } => f
                .debug_struct("Bolt11Invoice")
                .field("description", description)
                .field("amount_sats", amount_sats)
                .field("expiry_secs", expiry_secs)
                .field("payment_hash", payment_hash)
                .field("receiver_identity_public_key", receiver_identity_public_key)
                .field("preimage", &preimage.as_ref().map(|_| "<redacted>"))
                .finish(),
            ReceivePaymentMethod::CrossChain {
                route,
                amount,
                destination,
                fee_mode,
                max_slippage_bps,
                target_overpay_bps,
            } => f
                .debug_struct("CrossChain")
                .field("route", route)
                .field("amount", amount)
                .field("destination", destination)
                .field("fee_mode", fee_mode)
                .field("max_slippage_bps", max_slippage_bps)
                .field("target_overpay_bps", target_overpay_bps)
                .finish(),
        }
    }
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum SendPaymentMethod {
    BitcoinAddress {
        address: BitcoinAddressDetails,
        fee_quote: SendOnchainFeeQuote,
    },
    Bolt11Invoice {
        invoice_details: Bolt11InvoiceDetails,
        spark_transfer_fee_sats: Option<u64>,
        lightning_fee_sats: u64,
    }, // should be replaced with the parsed invoice
    SparkAddress {
        address: String,
        /// Fee to pay for the transaction
        /// Denominated in sats if token identifier is empty, otherwise in the token base units
        fee: u128,
        /// The presence of this field indicates that the payment is for a token
        /// If empty, it is a Bitcoin payment
        token_identifier: Option<String>,
    },
    SparkInvoice {
        spark_invoice_details: SparkInvoiceDetails,
        /// Fee to pay for the transaction
        /// Denominated in sats if token identifier is empty, otherwise in the token base units
        fee: u128,
        /// The presence of this field indicates that the payment is for a token
        /// If empty, it is a Bitcoin payment
        token_identifier: Option<String>,
    },
    /// A cross-chain send via a bridge/swap provider.
    CrossChainAddress {
        /// The route selected for this cross-chain send (includes provider, chain, asset).
        route: CrossChainRoutePair,
        /// Raw destination address (e.g. `0xabc...`).
        recipient_address: String,
        /// Amount routed to the provider, in the route's source-asset units
        /// (Boltz invoice sats; Orchestra deposit sats/token). On the
        /// token-conversion path (both `FeesIncluded` and `FeesExcluded`)
        /// the dispatcher overrides this with the wallet-side token debit
        /// when the source token and destination asset form a USD-stable pair.
        amount_in: u128,
        /// `amount_in` expressed in the cross-chain (destination) asset's
        /// base units, via the same rate the SDK used at prepare time.
        asset_amount_in: u128,
        /// Estimated recipient amount in cross-chain asset base units.
        estimated_out: u128,
        /// Prepare-time total user-visible fee in cross-chain asset base units.
        /// Covers provider spread + bridge/gas + 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`.
        fee_amount: u128,
        /// Provider service fee, including the partner fee when one is set, in
        /// `service_fee_asset` base units.
        service_fee_amount: u128,
        /// Asset which service fee is denominated in. Unset means BTC sats.
        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.
        service_fee_asset_decimals: Option<u32>,
        /// Sats budget for moving the amount in from the wallet to the provider.
        source_transfer_fee_sats: u64,
        /// Fee mode the prepare ran under; the send stage matches.
        fee_mode: CrossChainFeeMode,
        /// ISO8601 timestamp after which the quote is no longer valid.
        expires_at: String,
        /// Provider-internal state, produced when preparing and consumed
        /// when sending.
        provider_context: CrossChainProviderContext,
    },
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SendOnchainFeeQuote {
    /// Identifies the quote to the provider when the payment is sent. Empty on
    /// an estimate, which no provider has issued.
    pub id: String,
    /// When the quote stops being honoured, as a Unix timestamp in seconds.
    /// Zero on an estimate.
    pub expires_at: u64,
    pub speed_fast: SendOnchainSpeedFeeQuote,
    pub speed_medium: SendOnchainSpeedFeeQuote,
    pub speed_slow: SendOnchainSpeedFeeQuote,
    /// Set when the wallet holds no bitcoin and a token conversion will fund the
    /// send, because the provider will not quote without funds to price against.
    /// The estimate is an upper bound: the payment quotes for real once the
    /// conversion lands, and fails rather than spending more than this.
    pub is_estimate: bool,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SendOnchainSpeedFeeQuote {
    pub user_fee_sat: u64,
    pub l1_broadcast_fee_sat: u64,
}

impl SendOnchainSpeedFeeQuote {
    pub fn total_fee_sat(&self) -> u64 {
        self.user_fee_sat.saturating_add(self.l1_broadcast_fee_sat)
    }
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ReceivePaymentRequest {
    pub payment_method: ReceivePaymentMethod,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ReceivePaymentResponse {
    pub payment_request: String,
    /// Fee to pay to receive the payment
    /// Denominated in sats or token base units
    pub fee: u128,
    /// Optional information populated only for cross-chain receives.
    pub cross_chain_info: Option<crate::cross_chain::CrossChainReceiveInfo>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareLnurlPayRequest {
    /// The amount to send. Denominated in satoshis, or in token base units
    /// when `token_identifier` is set.
    pub amount: u128,
    pub pay_request: LnurlPayRequestDetails,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub comment: Option<String>,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub validate_success_action_url: Option<bool>,
    /// The token identifier when sending a token amount with conversion.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub token_identifier: Option<String>,
    /// If provided, the payment will include a token conversion step before sending the payment
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub conversion_options: Option<ConversionOptions>,
    /// How fees are handled. See [`FeePolicy`]. Defaults to `FeesExcluded`.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub fee_policy: Option<FeePolicy>,
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareLnurlPayResponse {
    /// The amount for the payment, always denominated in sats, even when a
    /// `token_identifier` and conversion are present.
    /// When a conversion is present, the token input amount is available in
    /// `conversion_estimate.amount_in`.
    pub amount_sats: u64,
    pub comment: Option<String>,
    pub pay_request: LnurlPayRequestDetails,
    /// The fee in satoshis. For `FeesIncluded` operations, this represents the total fee
    /// (including potential overpayment).
    pub fee_sats: u64,
    pub invoice_details: Bolt11InvoiceDetails,
    pub success_action: Option<SuccessAction>,
    /// When set, the payment will include a token conversion step before sending the payment
    pub conversion_estimate: Option<ConversionEstimate>,
    /// The fee policy actually applied. May differ from the request — e.g.,
    /// LNURL sends with `token_identifier` set + conversion are always
    /// `FeesIncluded` (explicit `FeesExcluded` is rejected).
    pub fee_policy: FeePolicy,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlPayRequest {
    pub prepare_response: PrepareLnurlPayResponse,
    /// If set, providing the same idempotency key for multiple requests will ensure that only one
    /// payment is made. If an idempotency key is re-used, the same payment will be returned.
    /// The idempotency key must be a valid UUID.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub idempotency_key: Option<String>,
}

#[derive(Debug, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlPayResponse {
    pub payment: Payment,
    pub success_action: Option<SuccessActionProcessed>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BuildUnsignedLnurlPayPackageRequest {
    pub prepare_response: PrepareLnurlPayResponse,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PublishSignedLnurlPayPackageRequest {
    pub signed_package: SignedTransferPackage,
}

#[allow(clippy::large_enum_variant)]
#[derive(Debug)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PublishSignedLnurlPayResponse {
    SwapCompleted,
    PaymentSent { response: LnurlPayResponse },
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlWithdrawRequest {
    /// The amount to withdraw in satoshis
    /// Must be within the min and max withdrawable limits
    pub amount_sats: u64,
    pub withdraw_request: LnurlWithdrawRequestDetails,
    /// If set, the function will return the payment if it is still pending after this
    /// number of seconds. If unset, the function will return immediately after
    /// initiating the LNURL withdraw.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub completion_timeout_secs: Option<u32>,
}

#[derive(Debug, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlWithdrawResponse {
    /// The Lightning invoice generated for the LNURL withdraw
    pub payment_request: String,
    pub payment: Option<Payment>,
}

/// Represents the payment LNURL info
#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlPayInfo {
    pub ln_address: Option<String>,
    pub comment: Option<String>,
    pub domain: Option<String>,
    pub metadata: Option<String>,
    pub processed_success_action: Option<SuccessActionProcessed>,
    pub raw_success_action: Option<SuccessAction>,
}

/// Represents the withdraw LNURL info
#[derive(Clone, Debug, Deserialize, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlWithdrawInfo {
    pub withdraw_url: String,
}

impl LnurlPayInfo {
    pub fn extract_description(&self) -> Option<String> {
        let Some(metadata) = &self.metadata else {
            return None;
        };

        let Ok(metadata) = serde_json::from_str::<Vec<Vec<Value>>>(metadata) else {
            return None;
        };

        for arr in metadata {
            if arr.len() != 2 {
                continue;
            }
            if let (Some(key), Some(value)) = (arr[0].as_str(), arr[1].as_str())
                && key == "text/plain"
            {
                return Some(value.to_string());
            }
        }

        None
    }
}

/// Specifies how fees are handled in a payment.
///
/// "Fees" are the wallet's sender-paid fees (Lightning routing, on-chain,
/// Spark transfer). They do not include provider spreads or destination-chain
/// costs on cross-chain routes; those are reported separately via
/// `estimated_out` on the prepare response and are not deterministic.
/// `FeePolicy` only controls the wallet's spend accounting.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum FeePolicy {
    /// Fees are added on top of `amount`. Wallet's total spend is
    /// `amount + fees`. For direct sat sends, the recipient receives exactly
    /// `amount`. Default.
    #[default]
    FeesExcluded,
    /// Fees are deducted from `amount`. Wallet's total spend is `amount`.
    /// Use this to drain a balance — pass `amount = balance` and the wallet
    /// spends exactly that.
    FeesIncluded,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum OnchainConfirmationSpeed {
    Fast,
    Medium,
    Slow,
}

/// The payment destination. Either a raw string (bolt11, spark address, BIP-21,
/// cross-chain URI, etc.) that is parsed internally, or a structured
/// cross-chain destination with explicit chain + asset selection.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PaymentRequest {
    /// Unparsed user input string (bolt11, spark address, BIP-21, cross-chain URI, etc.)
    Input { input: String },
    /// Cross-chain send with a selected route from `get_cross_chain_routes()`.
    /// Amount comes from `PrepareSendPaymentRequest.amount`, not here.
    CrossChain {
        address: String,
        route: CrossChainRoutePair,
        /// Maximum slippage tolerance in basis points (1/100 of a percent)
        /// for the cross-chain quote. Must be in 10 to 500. Falls back to
        /// [`Config::default_slippage_bps`] when unset, which itself
        /// defaults to 100 bps (1%).
        max_slippage_bps: Option<u32>,
        /// Target-overpay pad in basis points applied on `FeesExcluded`
        /// conversion sends. Inflates the destination target before quoting
        /// so the recipient lands at or above the user's requested amount
        /// despite provider slippage. Must be in 0 to 500. Falls back to
        /// [`CrossChainConfig::default_target_overpay_bps`] when unset,
        /// which itself defaults to 15 bps.
        target_overpay_bps: Option<u32>,
    },
}

#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum UnsignedTransferPackage {
    Swap {
        prepare_transfer: crate::signer::ExternalPrepareTransferRequest,
        target_amounts: Vec<u64>,
        amount_sat: u64,
        fee_sat: u64,
    },
    Transfer {
        prepare_transfer: crate::signer::ExternalPrepareTransferRequest,
        amount_sat: u64,
        fee_sat: u64,
        target: TransferTarget,
    },
    Token {
        prepare_token_transaction: crate::signer::ExternalPrepareTokenTransactionRequest,
        token_context: Vec<u8>,
        token_identifier: String,
        amount: u128,
        fee: u128,
        /// When set, this package re-shapes the wallet's token outputs instead of
        /// sending a payment. Publishing it returns `SwapCompleted`: rebuild the
        /// original send from the same prepare response and submit again.
        is_swap: bool,
    },
    /// One token transaction paying several recipients. Publishing it returns
    /// `PaymentsSent` with one payment per recipient.
    TokenBatch {
        prepare_token_transaction: crate::signer::ExternalPrepareTokenTransactionRequest,
        token_context: Vec<u8>,
        /// What the batch debits, per token. A batch spanning tokens has no
        /// single amount to report.
        totals: Vec<BatchTotal>,
        /// When set, this package re-shapes the wallet's token outputs instead of
        /// sending a payment. Publishing it returns `SwapCompleted`: rebuild the
        /// original send from the same prepare response and submit again.
        is_swap: bool,
    },
    /// A pull from a token allowance, signed through its `prepare_token_transaction` like a Token package.
    TokenPull {
        prepare_token_transaction: crate::signer::ExternalPrepareTokenTransactionRequest,
        pull_context: Vec<u8>,
        payer_address: String,
        token_identifier: String,
        receivers: Vec<PullReceiver>,
        amount: u128,
        /// When the pull stops being publishable, in Unix seconds.
        expiry_time: u64,
    },
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum TransferTarget {
    Spark {
        address: String,
        spark_invoice: Option<String>,
    },
    Lightning {
        bolt11: String,
        lnurl_pay: Option<LnurlPayContext>,
        fee_policy: FeePolicy,
        completion_timeout_secs: Option<u32>,
    },
    CoopExit {
        address: String,
        fee_quote: SendOnchainFeeQuote,
        confirmation_speed: OnchainConfirmationSpeed,
    },
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlPayContext {
    pub pay_request: LnurlPayRequestDetails,
    pub comment: Option<String>,
    pub success_action: Option<SuccessAction>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SignedTransferPackage {
    pub unsigned: UnsignedTransferPackage,
    pub signature: TransferSignature,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum TransferSignature {
    Transfer {
        signed: crate::signer::ExternalPreparedTransfer,
    },
    Token {
        signed: crate::signer::ExternalPreparedTokenTransaction,
    },
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum BuildTransferPackageOptions {
    BitcoinAddress {
        confirmation_speed: OnchainConfirmationSpeed,
    },
    Bolt11Invoice {
        prefer_spark: bool,

        /// If set, publishing the package waits up to this many seconds for the
        /// payment to complete before returning it while still pending. If unset,
        /// publishing returns immediately after initiating the payment.
        completion_timeout_secs: Option<u32>,
    },
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BuildUnsignedTransferPackageRequest {
    pub prepare_response: PrepareSendPaymentResponse,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub options: Option<BuildTransferPackageOptions>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareSendPaymentRequest {
    pub payment_request: PaymentRequest,
    /// The amount to send.
    /// Optional for payment requests with embedded amounts (e.g., Spark/Bolt11 invoices with amounts).
    /// Required for Spark addresses, Bitcoin addresses, and amountless invoices.
    /// Denominated in satoshis for Bitcoin payments, or token base units for token payments.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub amount: Option<u128>,
    /// Optional token identifier for token payments.
    /// Absence indicates that the payment is a Bitcoin payment.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub token_identifier: Option<String>,
    /// If provided, the payment will include a conversion step before sending the payment
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub conversion_options: Option<ConversionOptions>,
    /// How fees are handled. See [`FeePolicy`]. Defaults to `FeesExcluded`.
    ///
    /// Ignored on cross-chain AMM-conversion sends (whether the conversion was
    /// explicitly requested or auto-injected by stable balance) — fees come
    /// out of the converted sats. Bolt11 and Bitcoin AMM-conversion sends
    /// still respect this field by sizing the conversion to cover fees. The
    /// prepare response's `fee_policy` reflects what was actually applied.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub fee_policy: Option<FeePolicy>,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareSendPaymentResponse {
    pub payment_method: SendPaymentMethod,
    /// The amount to be sent, denominated in satoshis for Bitcoin payments
    /// (including token-to-Bitcoin conversions), or token base units for token payments.
    /// When a conversion is present, the input amount is in
    /// `conversion_estimate.amount_in`.
    pub amount: u128,
    /// Optional token identifier for token payments.
    /// Absence indicates that the payment is a Bitcoin payment.
    pub token_identifier: Option<String>,
    /// When set, the payment will include a conversion step before sending the payment
    pub conversion_estimate: Option<ConversionEstimate>,
    /// The fee policy actually applied. May differ from the request — e.g.,
    /// cross-chain AMM-conversion sends are always `FeesIncluded`.
    pub fee_policy: FeePolicy,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum SendPaymentOptions {
    BitcoinAddress {
        /// Confirmation speed for the on-chain transaction.
        confirmation_speed: OnchainConfirmationSpeed,
    },
    Bolt11Invoice {
        prefer_spark: bool,

        /// If set, the function will return the payment if it is still pending after this
        /// number of seconds. If unset, the function will return immediately after initiating the payment.
        completion_timeout_secs: Option<u32>,
    },
    SparkAddress {
        /// Can only be provided for Bitcoin payments. If set, a Spark HTLC transfer will be created.
        /// The receiver will need to provide the preimage to claim it.
        htlc_options: Option<SparkHtlcOptions>,
    },
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SparkHtlcOptions {
    /// The payment hash of the HTLC. The receiver will need to provide the associated preimage to claim it.
    pub payment_hash: String,
    /// The duration of the HTLC in seconds.
    /// After this time, the HTLC will be returned.
    pub expiry_duration_secs: u64,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SendPaymentRequest {
    pub prepare_response: PrepareSendPaymentResponse,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub options: Option<SendPaymentOptions>,
    /// The optional idempotency key for all Spark based transfers (excludes token payments
    /// and cross-chain sends).
    /// If set, providing the same idempotency key for multiple requests will ensure that only one
    /// payment is made. If an idempotency key is re-used, the same payment will be returned.
    /// The idempotency key must be a valid UUID.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub idempotency_key: Option<String>,
}

/// A single payee in a batch send.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BatchRecipient {
    /// Spark address or Spark invoice identifying the payee.
    pub payment_request: String,
    /// Amount to send, in the base units of the asset being sent. Required
    /// unless `payment_request` is an invoice that carries its own amount.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub amount: Option<u128>,
    /// Token to send. Unset means sats, which a batch cannot send yet, so a
    /// plain address needs this set. An invoice that names a token does not.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub token_identifier: Option<String>,
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareSendBatchRequest {
    /// The payees, all paid by one transaction. They may span several tokens,
    /// and may mix Spark addresses with Spark invoices. Once a Spark invoice is
    /// among them, every recipient must be paid in the same token.
    pub recipients: Vec<BatchRecipient>,
}

/// Where a batch recipient is paid, once prepare has decoded its payment request.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum BatchDestination {
    SparkAddress {
        address: String,
    },
    SparkInvoice {
        invoice_details: SparkInvoiceDetails,
    },
}

/// A recipient after prepare has resolved the asset and amount it is owed.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ResolvedBatchRecipient {
    pub destination: BatchDestination,
    /// Amount in the base units of the asset this recipient is paid in.
    pub amount: u128,
    /// The token this recipient is paid in. Unset means sats, which a batch
    /// cannot send yet.
    pub token_identifier: Option<String>,
}

/// What a batch debits for one asset.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BatchTotal {
    /// The token debited. Unset means sats, which a batch cannot send yet.
    pub token_identifier: Option<String>,
    /// Amount in the asset's base units.
    pub amount: u128,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareSendBatchResponse {
    /// The payees in the order they were requested, which is the order their
    /// payments come back in.
    pub recipients: Vec<ResolvedBatchRecipient>,
    /// What the batch debits, one entry per distinct asset.
    pub totals: Vec<BatchTotal>,
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SendBatchRequest {
    pub prepare_response: PrepareSendBatchResponse,
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SendBatchResponse {
    /// One payment per recipient, in recipient order, all sharing a transaction
    /// hash.
    pub payments: Vec<Payment>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct BuildUnsignedBatchPackageRequest {
    pub prepare_response: PrepareSendBatchResponse,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PublishSignedTransferPackageRequest {
    pub signed_package: SignedTransferPackage,
}

#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PublishSignedTransferPackageResponse {
    SwapCompleted,
    PaymentSent {
        payment: Payment,
    },
    /// Returned for a batch package: one payment per recipient, in recipient
    /// order.
    PaymentsSent {
        payments: Vec<Payment>,
    },
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SendPaymentResponse {
    pub payment: Payment,
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum PaymentDetailsFilter {
    Spark {
        /// Filter specific Spark HTLC statuses
        htlc_status: Option<Vec<SparkHtlcStatus>>,
        /// Filter conversion payments with refund information
        conversion_refund_needed: Option<bool>,
    },
    Token {
        /// Filter conversion payments with refund information
        conversion_refund_needed: Option<bool>,
        /// Filter by transaction hash
        tx_hash: Option<String>,
        /// Filter by transaction type
        tx_type: Option<TokenTransactionType>,
    },
    Lightning {
        /// Filter specific Spark HTLC statuses
        htlc_status: Option<Vec<SparkHtlcStatus>>,
    },
}

/// Request to list payments with optional filters and pagination
#[derive(Debug, Clone, Default)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ListPaymentsRequest {
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub type_filter: Option<Vec<PaymentType>>,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub status_filter: Option<Vec<PaymentStatus>>,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub asset_filter: Option<AssetFilter>,
    /// Only include payments matching at least one of these payment details filters
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub payment_details_filter: Option<Vec<PaymentDetailsFilter>>,
    /// Only include payments created after this timestamp (inclusive)
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub from_timestamp: Option<u64>,
    /// Only include payments created before this timestamp (exclusive)
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub to_timestamp: Option<u64>,
    /// Number of records to skip
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub offset: Option<u32>,
    /// Maximum number of records to return
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub limit: Option<u32>,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub sort_ascending: Option<bool>,
}

/// A field of [`ListPaymentsRequest`] when listing payments filtered by asset
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum AssetFilter {
    Bitcoin,
    Token {
        /// Optional token identifier to filter by
        token_identifier: Option<String>,
    },
}

impl FromStr for AssetFilter {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(match s.to_lowercase().as_str() {
            "bitcoin" => AssetFilter::Bitcoin,
            "token" => AssetFilter::Token {
                token_identifier: None,
            },
            str if str.starts_with("token:") => AssetFilter::Token {
                token_identifier: Some(
                    str.split_once(':')
                        .ok_or(format!("Invalid asset filter '{s}'"))?
                        .1
                        .to_string(),
                ),
            },
            _ => return Err(format!("Invalid asset filter '{s}'")),
        })
    }
}

/// Response from listing payments
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ListPaymentsResponse {
    /// The list of payments
    pub payments: Vec<Payment>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct GetPaymentRequest {
    pub payment_id: String,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct GetPaymentResponse {
    pub payment: Payment,
}

#[cfg_attr(feature = "uniffi", uniffi::export(callback_interface))]
pub trait Logger: Send + Sync {
    fn log(&self, l: LogEntry);
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LogEntry {
    pub line: String,
    pub level: String,
    /// Identity public key of the SDK instance that emitted the line, telling
    /// apart the logs of several instances in one process. Unset for lines not
    /// emitted by an instance.
    pub instance_id: Option<String>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CheckLightningAddressRequest {
    pub username: String,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RegisterLightningAddressRequest {
    pub username: String,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub description: Option<String>,
}

/// Authorization from the current owner granting a specific new owner the
/// right to take over a username. Produced by
/// [`BreezSdk::authorize_lightning_address_transfer`] and handed to the new
/// owner, who passes it to [`BreezSdk::claim_lightning_address_transfer`]. It
/// fully describes the transfer, so the new owner needs nothing else to claim.
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TransferAuthorization {
    /// The username being handed over.
    pub username: String,
    /// The current owner's public key.
    pub pubkey: String,
    /// The current owner's signature authorizing the transfer.
    pub signature: String,
    /// The lightning-address domain the authorization is for, taken from the
    /// address being handed over. The signed message names this domain, so an
    /// authorization made for one server does not verify at another.
    pub domain: String,
    /// When the authorization was produced, in seconds since the Unix epoch.
    /// Covered by the signature, and valid for 10 minutes: the transferee has
    /// to claim within that window or the current owner authorizes again.
    pub timestamp: u64,
}

/// Request for [`BreezSdk::authorize_lightning_address_transfer`]. Called by
/// the *current owner* to authorize handing their registered username over to
/// `transferee_pubkey`.
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuthorizeTransferRequest {
    /// The new owner's identity public key.
    pub transferee_pubkey: String,
}

/// Request for [`BreezSdk::claim_lightning_address_transfer`]. Called by the
/// *new owner* to complete the takeover using the authorization produced by
/// the current owner.
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ClaimTransferRequest {
    /// Authorization produced by the current owner via
    /// [`BreezSdk::authorize_lightning_address_transfer`].
    pub authorization: TransferAuthorization,
    /// Description for the address. Defaults to `"Pay to {username}@{domain}"`.
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub description: Option<String>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct LnurlInfo {
    pub url: String,
    pub bech32: String,
}

impl LnurlInfo {
    pub fn new(url: String) -> Self {
        let bech32 =
            breez_sdk_common::lnurl::encode_lnurl_to_bech32(&url).unwrap_or_else(|_| url.clone());
        Self { url, bech32 }
    }
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct LightningAddressInfo {
    pub description: String,
    pub lightning_address: String,
    pub lnurl: LnurlInfo,
    pub username: String,
}

impl From<RecoverLnurlPayResponse> for LightningAddressInfo {
    fn from(resp: RecoverLnurlPayResponse) -> Self {
        Self {
            description: resp.description,
            lightning_address: resp.lightning_address,
            lnurl: LnurlInfo::new(resp.lnurl),
            username: resp.username,
        }
    }
}

/// Response from listing fiat currencies
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ListFiatCurrenciesResponse {
    /// The list of fiat currencies
    pub currencies: Vec<FiatCurrency>,
}

/// Response from listing fiat rates
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ListFiatRatesResponse {
    /// The list of fiat rates
    pub rates: Vec<Rate>,
}

/// The operational status of a Spark service.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ServiceStatus {
    /// Service is fully operational.
    Operational,
    /// Service is experiencing degraded performance.
    Degraded,
    /// Service is partially unavailable.
    Partial,
    /// Service status is unknown.
    Unknown,
    /// Service is experiencing a major outage.
    Major,
}

/// The status of the Spark network services relevant to the SDK.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SparkStatus {
    /// The worst status across all relevant services.
    pub status: ServiceStatus,
    /// The last time the status was updated, as a unix timestamp in seconds.
    pub last_updated: u64,
}

pub(crate) enum WaitForPaymentIdentifier {
    PaymentId(String),
    LightningReceive { invoice: String, ssp_id: String },
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct GetTokensMetadataRequest {
    pub token_identifiers: Vec<String>,
}

#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct GetTokensMetadataResponse {
    pub tokens_metadata: Vec<TokenMetadata>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SignMessageRequest {
    pub message: String,
    /// If true, the signature will be encoded in compact format instead of DER format
    pub compact: bool,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SignMessageResponse {
    pub pubkey: String,
    /// The DER or compact hex encoded signature
    pub signature: String,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CheckMessageRequest {
    /// The message that was signed
    pub message: String,
    /// The public key that signed the message
    pub pubkey: String,
    /// The DER or compact hex encoded signature
    pub signature: String,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CheckMessageResponse {
    pub is_valid: bool,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
#[derive(Debug, Clone, Serialize)]
pub struct UserSettings {
    pub spark_private_mode_enabled: bool,

    /// The label of the currently active stable balance token, or `None` if deactivated.
    pub stable_balance_active_label: Option<String>,

    /// The hex encoded public key designated as this wallet's master identity
    /// key, or `None` if none is designated.
    pub spark_master_identity_public_key: Option<String>,
}

/// Specifies how to update the wallet's Spark master identity public key.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum SparkMasterIdentityPublicKey {
    /// Designate the holder of this public key as the wallet's master
    /// identity, replacing any previously designated key. Must be hex encoded
    /// in the 33-byte compressed form.
    Set { public_key: String },
    /// Remove the designated master identity, leaving the owner as the only
    /// party able to read the wallet under private mode.
    Unset,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct UpdateUserSettingsRequest {
    pub spark_private_mode_enabled: Option<bool>,

    /// Update the active stable balance token. `None` means no change.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub stable_balance_active_label: Option<StableBalanceActiveLabel>,

    /// Designate or remove the wallet's master identity, a second public key
    /// the Spark operators accept as a reader of this wallet's balance and
    /// history while `spark_private_mode_enabled` is set. The master identity
    /// can only read: payments still require the owner's keys. `None` means no
    /// change.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub spark_master_identity_public_key: Option<SparkMasterIdentityPublicKey>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ClaimHtlcPaymentRequest {
    pub preimage: String,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ClaimHtlcPaymentResponse {
    pub payment: Payment,
}

#[derive(Debug, Clone, Deserialize, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct LnurlReceiveMetadata {
    pub nostr_zap_request: Option<String>,
    pub nostr_zap_receipt: Option<String>,
    pub sender_comment: Option<String>,
    /// The Lightning address the payment was received on. Unset for some payments received
    /// before the LNURL server recorded addresses.
    pub lightning_address: Option<String>,
}

/// Mode of a manually-triggered optimization run.
#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum OptimizationMode {
    /// Run until no further optimization is productive.
    #[default]
    Full,
    /// Execute a single round and return so the caller can drive progress.
    SingleRound,
}

/// Request for [`BreezSdk::optimize_leaves`]. Defaults to
/// [`OptimizationMode::Full`].
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct OptimizeLeavesRequest {
    /// Controls how much work the call performs before returning.
    pub mode: OptimizationMode,
}

/// Response from a [`BreezSdk::optimize_leaves`] call.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct OptimizeLeavesResponse {
    /// The outcome of the optimization run.
    pub outcome: OptimizationOutcome,
}

/// Outcome of a [`BreezSdk::optimize_leaves`] call.
///
/// `rounds_executed` on `Completed` refers to rounds run by *this call*.
/// The SDK holds no cross-call state — callers driving a `SingleRound`
/// loop maintain their own cumulative counter if they need one.
///
/// A `Completed { rounds_executed: 0 }` outcome means the wallet was
/// already optimal at call time (no swap was needed).
///
/// **`SingleRound` loop pattern**: terminate on anything that isn't
/// `InProgress`. `Completed` covers both the final swap of a productive
/// run and the "already optimal" no-op case (the latter as
/// `rounds_executed: 0`).
///
/// ```ignore
/// loop {
///     let request = OptimizeLeavesRequest { mode: OptimizationMode::SingleRound };
///     match sdk.optimize_leaves(request).await?.outcome {
///         OptimizationOutcome::InProgress => continue,
///         OptimizationOutcome::Completed { .. } => break,
///     }
/// }
/// ```
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum OptimizationOutcome {
    /// All planned optimization work was executed in this call.
    /// Returned by `Full` runs on success, and by `SingleRound` runs
    /// whose swap was the final one needed (the planner produced a
    /// single-swap plan with a convergence guarantee).
    /// `rounds_executed == 0` means the wallet was already optimal —
    /// no work was performed.
    Completed { rounds_executed: u32 },
    /// `SingleRound` only: a round ran but the planner could not
    /// guarantee it was the last. The caller should invoke
    /// `optimize_leaves` again.
    InProgress,
}

/// A contact entry containing a name and payment identifier.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct Contact {
    pub id: String,
    pub name: String,
    /// A Lightning address (user@domain).
    pub payment_identifier: String,
    pub created_at: u64,
    pub updated_at: u64,
}

/// Request to add a new contact.
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct AddContactRequest {
    pub name: String,
    /// A Lightning address (user@domain).
    pub payment_identifier: String,
}

/// Request to update an existing contact.
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct UpdateContactRequest {
    pub id: String,
    pub name: String,
    /// A Lightning address (user@domain).
    pub payment_identifier: String,
}

/// Request to list contacts with optional pagination.
#[derive(Debug, Clone, Default)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ListContactsRequest {
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub offset: Option<u32>,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub limit: Option<u32>,
}

/// The type of event that triggers a webhook notification.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[allow(clippy::enum_variant_names)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum WebhookEventType {
    /// Triggered when a Lightning receive operation completes.
    LightningReceiveFinished,
    /// Triggered when a Lightning send operation completes.
    LightningSendFinished,
    /// Triggered when a cooperative exit completes.
    CoopExitFinished,
    /// Triggered when a static deposit completes.
    StaticDepositFinished,
    /// An event type not yet recognized by this version of the SDK.
    Unknown(String),
}

/// A registered webhook entry.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct Webhook {
    /// Unique identifier for this webhook.
    pub id: String,
    /// The URL that receives webhook notifications.
    pub url: String,
    /// The event types this webhook is subscribed to.
    pub event_types: Vec<WebhookEventType>,
}

/// Request to register a new webhook.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RegisterWebhookRequest {
    /// The URL that will receive webhook notifications.
    pub url: String,
    /// A secret used for HMAC-SHA256 signature verification of webhook payloads.
    pub secret: String,
    /// The event types to subscribe to.
    pub event_types: Vec<WebhookEventType>,
}

/// Response from registering a webhook.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RegisterWebhookResponse {
    /// The unique identifier of the newly registered webhook.
    pub webhook_id: String,
}

/// Request to unregister an existing webhook.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct UnregisterWebhookRequest {
    /// The unique identifier of the webhook to unregister.
    pub webhook_id: String,
}

// ===========================================================================
// Unilateral exit
// ===========================================================================

/// A funding UTXO that pays the on-chain fees of a unilateral exit.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum CpfpInput {
    /// A P2WPKH (native segwit v0) UTXO controlled by `pubkey` (33-byte
    /// compressed, hex).
    P2wpkh {
        txid: String,
        vout: u32,
        value_sats: u64,
        pubkey: String,
    },
    /// A P2TR (taproot, key-path) UTXO. `pubkey` (x-only or compressed, hex) is
    /// the **internal** (untweaked, BIP86 key-path) public key whose secret signs
    /// the input, not the tweaked on-chain output key. The SDK applies the BIP86
    /// taproot tweak itself to derive the funding scriptPubKey, so passing the
    /// already-tweaked output key here produces a scriptPubKey that does not match
    /// the UTXO and the built transaction is rejected at broadcast.
    P2tr {
        txid: String,
        vout: u32,
        value_sats: u64,
        pubkey: String,
    },
    /// Any witness-program script, signed via a custom `CpfpSigner`. Legacy
    /// (non-SegWit) scripts are rejected. `signed_input_weight` (weight units)
    /// is an upper bound on the input's signed weight, so the fee stays exact,
    /// or slightly conservative if the real signature is shorter.
    Custom {
        txid: String,
        vout: u32,
        value_sats: u64,
        script_pubkey_hex: String,
        signed_input_weight: u64,
    },
}

/// The kind of UTXO that will fund an exit's fees.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum CpfpFundingKind {
    /// Fees paid from P2WPKH (native segwit v0) UTXOs.
    P2wpkh,
    /// Fees paid from P2TR (taproot, key-path) UTXOs.
    P2tr,
    /// Fees paid from a custom witness-program script (legacy scripts are
    /// rejected). `script_pubkey_hex` (the funding scriptPubKey) sizes the
    /// fan-out output and dust; `signed_input_weight` (weight units) is an upper
    /// bound on the input's signed weight, so the quote stays exact or slightly
    /// conservative.
    Custom {
        script_pubkey_hex: String,
        signed_input_weight: u64,
    },
}

/// How funding UTXOs pay a unilateral exit's CPFP children.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum CpfpFundingStrategy {
    /// One UTXO per branch. Each child after the first spends the change of the
    /// one before it, so a child's inputs depend on the fee rate of every child
    /// above it.
    #[default]
    PerBranch,
    /// One UTXO per fee-bumped transaction. No child spends another's output,
    /// so each can be signed at any fee rate without knowing the others. Each
    /// child's change stays on the funding script rather than being swept.
    PerNode,
}

/// Which leaves to recover. `All` and `RecoverableOnly` take a leaf only when
/// what is left of its funds exceeds what recovering it costs. That cost leaves
/// out the shared fan-out fee, which you also pay when you fund several
/// `funding.per_branch` entries from one UTXO: compare `recoverable_value_sats`
/// with `total_fee_sats`, or fund one UTXO per entry to avoid the fan-out.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ExitLeafSelection {
    /// Every leaf, including the ones still in the balance. Only for when the
    /// operators are unreachable or refuse to serve the wallet. Its cooperative
    /// leaves still need the operators.
    All,
    /// The leaves that left the balance and whose recovery has not confirmed.
    RecoverableOnly,
    /// Exactly these leaves, whether or not they are worth it. A leaf whose
    /// recovery finished is left out, and so is a cooperative leaf too small to
    /// pay its fee, or one whose funds were not found.
    Specific { leaf_ids: Vec<String> },
}

/// Where a transaction of a recovery stands: on-chain, ready to send, or
/// waiting for something.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ExitTransactionStatus {
    /// Confirmed in a block, at `block_height` where the chain service reported
    /// one. It needs no action.
    ///
    /// A relative `csv_timelock_blocks` counts from the height of the
    /// transaction it spends, so this is what tells you when a child of this one
    /// can go out, without fetching it again.
    Confirmed { block_height: Option<u32> },
    /// Not on-chain, and nothing is holding it back. Broadcast it, with its
    /// `cpfp_tx_hex` where it has one.
    Ready,
    /// A transaction in `depends_on` has yet to confirm. A relative timelock
    /// only starts counting once it does.
    WaitingForDependencies,
    /// Every input is confirmed, but a relative timelock has yet to mature.
    /// `spendable_at_height` is the first block that can include this
    /// transaction, and is unset when the height it counts from could not be
    /// read from the chain.
    WaitingForTimelock { spendable_at_height: Option<u32> },
    /// The on-chain status could not be determined (the chain service errored),
    /// which also leaves what it is waiting for unknown. A cooperative recovery
    /// has this status when the SDK did not see the output it spends in a
    /// block, or could not check whether an earlier recovery spent that
    /// output. Broadcasting may fail if a conflicting transaction already
    /// landed.
    Unverified,
}

/// How much one funding UTXO must hold to avoid a fan-out: for a branch of the
/// exit, or under `CpfpFundingStrategy::PerNode` for one transaction of it.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PerBranchFunding {
    /// The leaf whose branch this funds.
    pub leaf_id: String,
    /// Fund a UTXO of at least this many satoshis.
    pub funding_sats: u64,
}

/// What the chain has already done to an exit's leaves, as
/// `prepare_recover_funds` found it. `recover_funds` builds only the steps it
/// does not cover.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ExitChainState {
    /// Nodes whose transaction is on-chain.
    pub confirmed_nodes: Vec<ConfirmedExitNode>,
    /// Leaves whose refund reached the chain.
    pub refunds: Vec<ExitRefund>,
    /// Leaves whose lineage was taken on-chain by a transaction the exit cannot
    /// continue from. Nothing further can be driven for them.
    pub stopped_leaf_ids: Vec<String>,
    /// Nodes a chain lookup could not read, so their state is unknown rather
    /// than absent. Transactions depending on them come back
    /// `ExitTransactionStatus::Unverified`.
    pub unverified_node_ids: Vec<String>,
    /// Nodes taken to be on-chain on the operators' word, the chain itself being
    /// unreadable. Their spend is invisible, so anything built over them risks
    /// double-spending an output that is already gone.
    pub unverifiable_confirmed_node_ids: Vec<String>,
}

/// A node of the exit tree that is already on-chain.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ConfirmedExitNode {
    pub node_id: String,
    pub confirmed_by: ExitNodeConfirmation,
    /// The block it is in, where that is known. Unset for a node put in a block
    /// by a descendant's confirmation rather than read directly.
    pub block_height: Option<u32>,
}

/// Which of a node's two pre-signed spends took it on-chain.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ExitNodeConfirmation {
    /// The CPFP transaction, whose fee a child paid.
    Cpfp,
    /// The direct transaction, which pays its own fee. A leaf that went out this
    /// way is refunded by its direct refund transaction.
    Direct,
}

/// A leaf's refund as the chain shows it.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ExitRefund {
    pub leaf_id: String,
    pub state: ExitRefundState,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ExitRefundState {
    /// On-chain with its output still there, which is what the sweep pulls from.
    /// A sweep sitting unconfirmed in the mempool leaves the refund here, so
    /// that sweep is rebuilt rather than dropped.
    OnChain {
        tx_hex: String,
        vout: u32,
        value_sats: u64,
        block_height: Option<u32>,
    },
    /// Spent by a confirmed transaction: the sweep landed.
    Swept,
}

/// Result of `export_unilateral_exit_state`: a self-contained copy of the
/// wallet's exit state, ready to be stored outside the wallet.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ExportUnilateralExitStateResponse {
    /// The serialized exit state, to be handed back to
    /// `import_unilateral_exit_state` unmodified.
    pub exit_state: String,
}

/// Request for `import_unilateral_exit_state`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ImportUnilateralExitStateRequest {
    /// An exit state as returned by `export_unilateral_exit_state`.
    pub exit_state: String,
}

/// Result of `import_unilateral_exit_state`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ImportUnilateralExitStateResponse {
    /// Leaves merged into the wallet's exit state, whether or not their exit
    /// data was taken with them.
    pub imported_leaves: u32,
    /// Leaves left out because the exit state does not record this wallet as
    /// their owner.
    pub skipped_foreign_leaves: u32,
    /// Leaves left out because their exit data disagrees with what the wallet
    /// already holds, so none of it could be trusted. The wallet is left without
    /// these leaves.
    pub skipped_conflicting_leaves: u32,
    /// Leaves the wallet holds whose imported exit data was left out: it is
    /// incomplete, the wallet's own copy can already back an exit, or the leaf
    /// was named more than once. The leaf itself is in the wallet either way.
    pub skipped_chains: u32,
}

// ===========================================================================
// Recover funds
// ===========================================================================

/// Request for `prepare_recover_funds`, which returns the recovery quote.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareRecoverFundsRequest {
    /// Target fee rate in sat/vByte, applied to every transaction the recovery
    /// builds. Below the network's relay minimum, zero included, nodes do not
    /// relay the transactions: they have to reach a miner another way.
    pub fee_rate_sat_per_vbyte: u64,
    /// The kind of UTXO that will fund a unilateral exit. Needed when a
    /// transaction of a unilateral exit in the quote has a CPFP child.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub funding_kind: Option<CpfpFundingKind>,
    /// How the funding UTXOs pay a unilateral exit's CPFP children. Unset funds
    /// one UTXO per branch.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub funding_strategy: Option<CpfpFundingStrategy>,
    /// The Bitcoin address the recovered funds are sent to.
    pub destination: String,
    pub selection: ExitLeafSelection,
}

/// Response from `prepare_recover_funds`: which leaves would be recovered and
/// how, the exact fee at the requested rate, and how much to fund.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareRecoverFundsResponse {
    pub leaves: Vec<RecoverFundsLeaf>,
    /// The leaves the selection covers that are not in `leaves`, each with the
    /// reason. A leaf whose recovery already finished is not listed.
    pub skipped: Vec<SkippedLeaf>,
    /// Total value of the selected leaves, in satoshis.
    pub recoverable_value_sats: u64,
    /// `cooperative_fee_sats + cpfp_fee_sats + fanout_fee_sats +
    /// refund_fee_sats + sweep_fee_sats`.
    pub total_fee_sats: u64,
    /// Paid from the cooperative leaves' own value. Each leaf has two fees: the
    /// one of the transaction the operators broadcast to move it on-chain, which
    /// is already paid, and the one of its recovery transaction.
    pub cooperative_fee_sats: u64,
    /// Paid by the CPFP children, from your funding UTXOs.
    pub cpfp_fee_sats: u64,
    /// Paid by the fan-out, from your funding UTXO. Funding one UTXO per
    /// `funding.per_branch` entry avoids it.
    pub fanout_fee_sats: u64,
    /// Paid from the unilateral leaves' own value before the sweep: each leaf's
    /// value less what its refund passes to the sweep. The output of a direct
    /// transaction, the Spark operators' version of a leaf's transaction, is its
    /// input less its fee, and a refund received with a watchtower fee ladder
    /// pays its own fee. For a refund that is not on-chain yet, the SDK counts
    /// the refund it expects: the operators can broadcast one with another fee.
    pub refund_fee_sats: u64,
    /// Paid by the final sweep, off the value it moves.
    pub sweep_fee_sats: u64,
    /// What to fund the unilateral exit with. Unset when nothing needs funding:
    /// no transaction of the recovery has a CPFP child.
    pub funding: Option<RecoveryFunding>,
    pub fee_rate_sat_per_vbyte: u64,
    pub destination: String,
    /// What the chain has already done to the unilateral leaves, read while
    /// preparing.
    pub exit_chain_state: ExitChainState,
}

/// How much to fund a unilateral exit with.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RecoveryFunding {
    /// Fund a single UTXO of at least this many satoshis, which a fan-out
    /// splits over the `per_branch` entries.
    pub single_utxo_sats: u64,
    /// To skip the fan-out, fund one UTXO per entry of at least its amount, in
    /// any order. An entry is a branch, or under `CpfpFundingStrategy::PerNode`
    /// one transaction of a branch, so a leaf can have several.
    pub per_branch: Vec<PerBranchFunding>,
    /// The strategy the amounts were computed for, which `recover_funds` builds
    /// with.
    #[serde(default)]
    pub strategy: CpfpFundingStrategy,
}

/// A leaf the selection covers that `prepare_recover_funds` leaves out of the
/// quote.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct SkippedLeaf {
    pub leaf_id: String,
    pub value_sats: u64,
    pub reason: SkippedLeafReason,
}

/// Why `prepare_recover_funds` leaves a leaf out of the quote.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum SkippedLeafReason {
    /// At the quote's fee rate, recovering the leaf costs at least what is left
    /// of its funds: `value_sats`, less the fee of each direct transaction in its
    /// exit and the fee the operators paid out of the leaf when they broadcast
    /// its refund. A low enough fee rate brings the leaf back into the quote.
    FeeExceedsValue,
    /// The SDK read the chain and found no output holding the leaf's funds.
    FundsNotFound,
    /// The SDK could not look up where the leaf's funds are. It looks again the
    /// next time you prepare.
    Unverified,
    /// The SDK needs data from the Spark operators to find the leaf's funds,
    /// and could not reach them or they were too busy. It tries again the next
    /// time you prepare.
    OperatorsUnavailable,
    /// No recovery can be built for the leaf as it stands. `message` says why.
    NotRecoverable { message: String },
}

/// A leaf selected for recovery.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RecoverFundsLeaf {
    pub leaf_id: String,
    pub value_sats: u64,
    pub method: RecoveryMethod,
}

/// How a leaf's funds are recovered.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum RecoveryMethod {
    /// One transaction the operators co-sign, paid from the leaf's value. No
    /// funding, no timelock.
    Cooperative,
    /// The leaf's own pre-signed transactions, fee-bumped from funding you
    /// supply, with timelock waits.
    Unilateral,
}

/// Request for `recover_funds`: a `prepare_recover_funds` quote plus the
/// funding UTXOs that pay its fees.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RecoverFundsRequest {
    pub prepared: PrepareRecoverFundsResponse,
    /// UTXOs that meet the quote's `funding`: one of at least `single_utxo_sats`,
    /// or one per `per_branch` entry. Not needed when the quote has no `funding`.
    #[cfg_attr(feature = "uniffi", uniffi(default = []))]
    pub funding_inputs: Vec<CpfpInput>,
}

/// Result of `recover_funds`: every signed transaction of the recovery, and its
/// totals. The totals mean what they do on the quote, for the leaves in
/// `leaves`: the ones in `failed` add nothing to them.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RecoverFundsResponse {
    pub recoverable_value_sats: u64,
    pub total_fee_sats: u64,
    pub cooperative_fee_sats: u64,
    pub cpfp_fee_sats: u64,
    pub fanout_fee_sats: u64,
    pub refund_fee_sats: u64,
    pub sweep_fee_sats: u64,
    pub leaves: Vec<RecoverFundsLeaf>,
    /// Cooperative leaves whose recovery could not be produced, and why. No
    /// transaction depends on them.
    pub failed: Vec<CooperativeRecoveryFailure>,
    /// Every transaction, cooperative ones included, in broadcast order.
    pub transactions: Vec<RecoveryTransaction>,
    /// The funding UTXOs this recovery was built from, as you supplied them.
    /// Hand them back when you build it again and they are followed to whatever
    /// they have since become.
    pub funding_inputs: Vec<CpfpInput>,
    pub fee_rate_sat_per_vbyte: u64,
    pub destination: String,
}

/// A cooperative recovery that could not be produced.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CooperativeRecoveryFailure {
    pub leaf_id: String,
    /// The output the recovery would have spent: the on-chain output where the
    /// SDK found the leaf's funds, or the one it assumed to hold them.
    pub output_txid: String,
    pub output_vout: u32,
    pub error: CooperativeRecoveryError,
}

/// One transaction of a recovery, with everything needed to order and
/// broadcast it.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct RecoveryTransaction {
    pub kind: RecoveryTxKind,
    /// The tree node it belongs to (the leaf, for `Cooperative`). Unset for
    /// `FanOut` and `Sweep`.
    pub node_id: Option<String>,
    pub txid: String,
    pub tx_hex: String,
    /// The signed CPFP child to broadcast alongside `tx_hex` as a package. Unset
    /// when there is no anchor to bump, and for a `Confirmed` step.
    pub cpfp_tx_hex: Option<String>,
    /// Relative CSV timelock, in blocks, that must mature on the spent input
    /// before this transaction can confirm. Unset when there is no timelock.
    pub csv_timelock_blocks: Option<u32>,
    /// Txids of other entries in this list that must be confirmed before this
    /// one can be broadcast.
    pub depends_on: Vec<String>,
    pub status: ExitTransactionStatus,
}

/// The role of a transaction in a recovery.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum RecoveryTxKind {
    /// Spends the on-chain output holding a leaf's funds, co-signed by the
    /// operators. Pays its fee from the leaf's value: no CPFP child, no
    /// dependencies, no timelock.
    Cooperative,
    /// Splits the caller's funding into one output per `funding.per_branch`
    /// entry: per branch, or under `CpfpFundingStrategy::PerNode` per
    /// transaction. Present only when the funding couldn't be matched
    /// one-to-one to the entries.
    FanOut,
    /// A tree node transaction (root, intermediate, or leaf node).
    Node,
    /// A leaf's refund transaction.
    Refund,
    /// The final transaction sweeping all refund outputs to the destination.
    Sweep,
}

/// Request for `check_recover_funds`: the recovery you kept from a previous
/// `recover_funds`, as you last stored it.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CheckRecoverFundsRequest {
    pub recovery: RecoverFundsResponse,
}

/// Result of `check_recover_funds`: the same recovery, read back against the
/// chain.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct CheckRecoverFundsResponse {
    /// Store it in place of the one you passed in.
    pub recovery: RecoverFundsResponse,
    pub verdict: RecoveryVerdict,
}

/// What to do with a recovery that has been read back against the chain.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum RecoveryVerdict {
    /// The recovery can still be finished as it stands. Broadcast the `Ready`
    /// transactions.
    Valid,
    /// Every transaction is confirmed. The leaves in `failed` are not part of
    /// the recovery.
    Done,
    /// The recovery cannot be finished as it stands. Prepare and recover again.
    Redo { reason: RecoveryRedoReason },
}

/// Why a recovery has to be built again.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum RecoveryRedoReason {
    /// The chain no longer matches the recovery: something that is not one of
    /// its own transactions took an outpoint it still needs. A different
    /// refund, a fee bump from elsewhere, or funding spent on something else
    /// all land here.
    OnChainStateDiverged,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{ConversionStatus, PaymentMethod};
    use macros::test_all;

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

    #[test_all]
    fn seed_debug_redacts_secrets() {
        let mnemonic = Seed::Mnemonic {
            mnemonic: "abandon ability able".to_string(),
            passphrase: Some("hunter2".to_string()),
        };
        let rendered = format!("{mnemonic:?}");
        assert!(!rendered.contains("abandon"), "{rendered}");
        assert!(!rendered.contains("hunter2"), "{rendered}");

        let entropy = format!("{:?}", Seed::Entropy(vec![0xab; 16]));
        assert!(!entropy.contains("171"), "{entropy}");
    }

    #[test_all]
    fn debug_fmt_redacts_the_preimage_of_a_bolt11_receive() {
        let preimage = "ab".repeat(32);
        let method = ReceivePaymentMethod::Bolt11Invoice {
            description: "test".to_string(),
            amount_sats: Some(1_000),
            expiry_secs: None,
            payment_hash: None,
            receiver_identity_public_key: None,
            preimage: Some(preimage.clone()),
        };

        let written = format!("{method:?}");

        assert!(
            written.contains(r#"preimage: Some("<redacted>")"#),
            "{written}"
        );
        assert!(!written.contains(&preimage), "{written}");
    }

    #[test_all]
    fn payment_link_types_map_to_bridge_from_cash_app() {
        let route = crate::CrossChainRoutePair {
            provider: crate::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: Vec::new(),
        };
        let request: BridgeFromCashAppRequest = PreparePaymentLinkRequest {
            address: "0xabc".to_string(),
            route: route.clone(),
            amount: 1_000_000,
            fee_policy: Some(FeePolicy::FeesIncluded),
            max_slippage_bps: Some(50),
        }
        .into();
        assert_eq!(request.address, "0xabc");
        assert_eq!(request.route, route);
        assert_eq!(request.amount, 1_000_000);
        assert_eq!(request.fee_policy, Some(FeePolicy::FeesIncluded));
        assert_eq!(request.max_slippage_bps, Some(50));

        let response: PreparePaymentLinkResponse = BridgeFromCashAppResponse {
            url: "https://cash.app/launch/lightning/lnbc1".to_string(),
            amount_sats: 1_500,
            estimated_out: 990_000,
            asset: "USDC".to_string(),
            service_fee_amount: 10_000,
            service_fee_asset: Some("USDC".to_string()),
            service_fee_asset_decimals: Some(6),
            expires_at: 1_791_374_400,
        }
        .into();
        assert_eq!(response.url, "https://cash.app/launch/lightning/lnbc1");
        assert_eq!(response.amount_sats, 1_500);
        assert_eq!(response.estimated_out, 990_000);
        assert_eq!(response.asset, "USDC");
        assert_eq!(response.service_fee_amount, 10_000);
        assert_eq!(response.service_fee_asset.as_deref(), Some("USDC"));
        assert_eq!(response.service_fee_asset_decimals, Some(6));
        assert_eq!(response.expires_at, "2026-10-07T12:00:00Z");
    }

    fn spark_payment(conversion_info: Option<ConversionInfo>) -> Payment {
        Payment {
            id: "pmt".to_string(),
            payment_type: PaymentType::Receive,
            status: PaymentStatus::Completed,
            amount: 1_000,
            fees: 0,
            timestamp: 0,
            method: PaymentMethod::Spark,
            details: Some(PaymentDetails::Spark {
                invoice_details: None,
                htlc_details: None,
                conversion_info,
            }),
            conversion_details: None,
        }
    }

    fn amm_info() -> ConversionInfo {
        ConversionInfo::Amm {
            pool_id: "pool".to_string(),
            conversion_id: "conv".to_string(),
            status: ConversionStatus::Completed,
            fee: None,
            purpose: None,
            amount_adjustment: None,
            degradation: None,
        }
    }

    fn orchestra_info() -> ConversionInfo {
        ConversionInfo::Orchestra {
            order_id: "ord".to_string(),
            quote_id: "q".to_string(),
            read_token: None,
            chain: "base".to_string(),
            chain_id: Some("8453".to_string()),
            asset: "USDC".to_string(),
            recipient_address: "sp1rcv".to_string(),
            asset_amount_in: Some(1_000_000),
            estimated_out: 990_000,
            delivered_amount: Some(990_000),
            external_tx_hash: None,
            status: ConversionStatus::Completed,
            fee_amount: Some(10_000),
            service_fee_amount: None,
            service_fee_asset: None,
            service_fee_asset_decimals: None,
            asset_decimals: 6,
            asset_contract: None,
        }
    }

    #[test_all]
    fn only_amm_legs_are_conversion_children() {
        // The AMM settles a conversion as its own payments, and those are the
        // ones the event middleware keeps to itself.
        assert!(spark_payment(Some(amm_info())).is_conversion_child());

        // A cross-chain conversion annotates the payment the user made or
        // received. Treating it as a child would swallow its events, which on
        // receive is the only signal the funds arrived.
        assert!(!spark_payment(Some(orchestra_info())).is_conversion_child());

        assert!(!spark_payment(None).is_conversion_child());
    }

    #[test_all]
    fn claim_error_stored_with_a_fee_and_rate_still_loads() {
        let stored = r#"{"MaxDepositClaimFeeExceeded":{"tx":"tx","vout":1,
            "max_fee":{"Rate":{"sat_per_vbyte":2}},"required_fee_sats":500,
            "required_fee_rate_sat_per_vbyte":6}}"#;
        let error: crate::DepositClaimError = serde_json::from_str(stored).unwrap();
        assert_eq!(
            error,
            crate::DepositClaimError::MaxDepositClaimFeeExceeded {
                tx: "tx".to_string(),
                vout: 1,
                max_fee_sats: None,
                required_fee_sats: 500,
            }
        );
    }

    #[test_all]
    fn max_fee_stored_without_a_proportional_part_still_loads() {
        for (stored, onchain) in [
            (
                r#"{"Fixed":{"amount":500}}"#,
                MaxOnchainFee::Fixed { amount: 500 },
            ),
            (
                r#"{"Rate":{"sat_per_vbyte":12}}"#,
                MaxOnchainFee::Rate { sat_per_vbyte: 12 },
            ),
            (
                r#"{"NetworkRecommended":{"leeway_sat_per_vbyte":3}}"#,
                MaxOnchainFee::NetworkRecommended {
                    leeway_sat_per_vbyte: 3,
                },
            ),
        ] {
            let max_fee: MaxFee = serde_json::from_str(stored).unwrap();
            assert_eq!(
                max_fee,
                MaxFee {
                    onchain,
                    proportional_ppm: None,
                }
            );
        }
    }

    #[test_all]
    fn max_fee_is_stored_in_its_flat_shape() {
        let max_fee = MaxFee {
            onchain: MaxOnchainFee::Fixed { amount: 500 },
            proportional_ppm: Some(1_000),
        };
        let stored = serde_json::to_string(&max_fee).unwrap();
        assert_eq!(
            stored,
            r#"{"Fixed":{"amount":500,"proportional_ppm":1000}}"#
        );
        assert_eq!(serde_json::from_str::<MaxFee>(&stored).unwrap(), max_fee);
        let without_ppm = MaxFee {
            onchain: MaxOnchainFee::Rate { sat_per_vbyte: 2 },
            proportional_ppm: None,
        };
        assert_eq!(
            serde_json::to_string(&without_ppm).unwrap(),
            r#"{"Rate":{"sat_per_vbyte":2}}"#
        );
    }

    #[test_all]
    fn recovery_funding_without_a_strategy_reads_as_per_branch() {
        // A quote is held while its funding is gathered, so one stored before the
        // field existed still has to read back, as the funding it always was.
        let stored =
            r#"{"single_utxo_sats":5000,"per_branch":[{"leaf_id":"a","funding_sats":5000}]}"#;
        let funding: RecoveryFunding = serde_json::from_str(stored).unwrap();
        assert_eq!(funding.strategy, CpfpFundingStrategy::PerBranch);

        let per_node = RecoveryFunding {
            strategy: CpfpFundingStrategy::PerNode,
            ..funding
        };
        let round_trip: RecoveryFunding =
            serde_json::from_str(&serde_json::to_string(&per_node).unwrap()).unwrap();
        assert_eq!(round_trip.strategy, CpfpFundingStrategy::PerNode);
    }
}