breez_sdk_spark/models/

mod.rs

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

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

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

use crate::{
    BitcoinAddressDetails, BitcoinChainService, BitcoinNetwork, Bolt11InvoiceDetails,
    ExternalInputParser, FiatCurrency, LnurlPayRequestDetails, LnurlWithdrawRequestDetails, Rate,
    SdkError, SparkInvoiceDetails, SuccessAction, SuccessActionProcessed,
    cross_chain::{CrossChainFeeMode, CrossChainProviderContext, CrossChainRoutePair},
    error::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(Debug, 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 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.
    ///
    /// Conversion operations (stable balance, ongoing sends) create internal child
    /// payments (send sats→Flashnet, receive tokens). These are identified by having
    /// `conversion_info` set in their payment details.
    pub fn is_conversion_child(&self) -> bool {
        matches!(
            &self.details,
            Some(
                PaymentDetails::Spark {
                    conversion_info: Some(_),
                    ..
                } | PaymentDetails::Token {
                    conversion_info: Some(_),
                    ..
                }
            )
        )
    }
}

/// 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 (persisted in storage)
    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,
    },
    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(Debug, 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,
}

#[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,
}

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"),
        }
    }
}

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

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,
        }
    }
}

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

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),
            _ => Err("Invalid network".to_string()),
        }
    }
}

#[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 for a static deposit claim
    // If not set then any fee is allowed
    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,

    /// 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,

    /// Configuration for cross-chain sends via Orchestra and Boltz.
    ///
    /// `Some(_)` enables cross-chain sends (sats to USDT on external chains).
    /// `None` (default) disables them entirely. Opt in by setting this to
    /// [`CrossChainConfig::default`] (or a customized value): the providers
    /// run background work (e.g. web sockets), so enabling is left to the
    /// caller. Cross-chain sends are only supported on mainnet.
    pub cross_chain_config: Option<CrossChainConfig>,
}

/// Configuration for cross-chain sends.
///
/// The presence of this struct on [`Config::cross_chain_config`] enables
/// cross-chain providers; `None` disables them.
#[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..=500`. Falls back to 100 bps (1%)
    /// when this field is `None`.
    #[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..=500`.
    /// Falls back to 15 bps when `None`.
    #[cfg_attr(feature = "uniffi", uniffi(default = None))]
    pub default_target_overpay_bps: Option<u32>,
}

/// 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. When the balance exceeds the configured threshold plus the reserved
/// amount, the SDK automatically converts the excess balance (above the reserve)
/// 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)]
#[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>,
}

/// A Spark signing operator.
#[derive(Debug, Clone)]
#[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)]
#[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.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 !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"
                )));
            }
        }

        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(),
            ));
        }

        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,
                )));
            }
            if let Some(bps) = cc.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) = cc.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(())
    }

    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
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum MaxFee {
    // Fixed fee amount in sats
    Fixed { amount: u64 },
    // Relative fee rate in satoshis per vbyte
    Rate { sat_per_vbyte: u64 },
    // Fastest network recommended fee at the time of claim, with a leeway in satoshis per vbyte
    NetworkRecommended { leeway_sat_per_vbyte: u64 },
}

impl MaxFee {
    pub(crate) async fn to_fee(&self, client: &dyn BitcoinChainService) -> Result<Fee, SdkError> {
        match self {
            MaxFee::Fixed { amount } => Ok(Fee::Fixed { amount: *amount }),
            MaxFee::Rate { sat_per_vbyte } => Ok(Fee::Rate {
                sat_per_vbyte: *sat_per_vbyte,
            }),
            MaxFee::NetworkRecommended {
                leeway_sat_per_vbyte,
            } => {
                let recommended_fees = client.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),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct DepositInfo {
    pub txid: String,
    pub vout: u32,
    pub amount_sats: u64,
    pub is_mature: bool,
    pub refund_tx: Option<String>,
    pub refund_tx_id: Option<String>,
    pub claim_error: Option<DepositClaimError>,
}

#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct ClaimDepositRequest {
    pub txid: String,
    pub vout: u32,
    #[cfg_attr(feature = "uniffi", uniffi(default=None))]
    pub max_fee: Option<MaxFee>,
}

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

#[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-to-Bitcoin via credit card, Apple Pay, etc.
    /// Uses an on-chain deposit address.
    Moonpay {
        /// Lock the purchase to a specific amount in satoshis.
        locked_amount_sat: Option<u64>,
        /// Custom redirect URL after purchase completion.
        redirect_url: Option<String>,
    },
    /// `CashApp`: Pay via the Lightning Network.
    /// Generates a bolt11 invoice for the given amount and returns a
    /// `cash.app` deep link. 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 for the Lightning invoice. Must be non-zero.
        amount_sats: u64,
    },
}

impl Default for BuyBitcoinRequest {
    fn default() -> Self {
        Self::Moonpay {
            locked_amount_sat: None,
            redirect_url: 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,
}

/// 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 intentionally deferred (eligible but held back by a
    /// safety window). The next pass will retry them.
    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,
}

impl std::fmt::Display for MaxFee {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            MaxFee::Fixed { amount } => write!(f, "Fixed: {amount}"),
            MaxFee::Rate { sat_per_vbyte } => write!(f, "Rate: {sat_per_vbyte}"),
            MaxFee::NetworkRecommended {
                leeway_sat_per_vbyte,
            } => write!(f, "NetworkRecommended: {leeway_sat_per_vbyte}"),
        }
    }
}

#[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.
    ///
    /// 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>,
}

#[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 {}

#[derive(Debug, 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>,
    },
}

#[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's own service fee/spread in its native denomination.
        service_fee_amount: u128,
        /// Asset which service fee is denominated in. Unset means BTC sats.
        service_fee_asset: Option<String>,
        /// 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 {
    pub id: String,
    pub expires_at: u64,
    pub speed_fast: SendOnchainSpeedFeeQuote,
    pub speed_medium: SendOnchainSpeedFeeQuote,
    pub speed_slow: SendOnchainSpeedFeeQuote,
}

#[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,
}

#[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..=500`. Falls back to
        /// [`Config::default_slippage_bps`] when `None`, which itself
        /// defaults to 100 bps (1%) when unset.
        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..=500`. Falls back to
        /// [`CrossChainConfig::default_target_overpay_bps`] when `None`,
        /// 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,
    },
}

#[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>,
}

#[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 },
}

#[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,
}

#[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,
}

/// 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>,
}

/// 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: 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: 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: 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,
    },
}

/// Which leaves to exit.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ExitLeafSelection {
    /// Exit every leaf whose value exceeds its own marginal exit cost (its tree
    /// and refund CPFP fees plus its sweep input). This per-leaf test does not
    /// include the shared fan-out fee, so funding many leaves from a single UTXO
    /// adds `fanout_fee_sat` on top: compare `recoverable_value_sat` with
    /// `total_fee_sat`, or fund one UTXO per branch to avoid the fan-out. Leaves
    /// that fail the per-leaf test are skipped.
    Auto,
    /// Exit exactly these leaves, regardless of profitability.
    Specific { leaf_ids: Vec<String> },
}

/// The role of a transaction in the exit path.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum UnilateralExitTxKind {
    /// Splits the caller's funding into one output per branch. Present only
    /// when the funding couldn't be matched one-to-one to branches.
    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,
}

/// Whether a transaction in the exit path is already on-chain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
pub enum ConfirmationStatus {
    /// This transaction is confirmed in a block. It needs no action.
    Confirmed,
    /// This transaction is not yet confirmed. Mempool state is not consulted.
    Unconfirmed,
    /// The on-chain status could not be determined (the chain service errored).
    /// Broadcasting may fail if a conflicting transaction already landed.
    Unverified,
}

/// One transaction in the unilateral exit path, with everything needed to
/// order and broadcast it.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct UnilateralExitTransaction {
    pub kind: UnilateralExitTxKind,
    /// The tree node this transaction belongs to. Unset for the fan-out and the
    /// 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 for the fan-out and the sweep (no anchor to bump) and for a
    /// `Confirmed` step (its CPFP is already on-chain).
    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: ConfirmationStatus,
}

/// A leaf selected for exit, with its value.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct UnilateralExitLeaf {
    pub leaf_id: String,
    /// The leaf's value in satoshis.
    pub value: u64,
}

/// Request for `prepare_unilateral_exit`, the exit quote.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct PrepareUnilateralExitRequest {
    /// Target fee rate in sat/vByte, applied to every CPFP child, the fan-out,
    /// and the sweep.
    pub fee_rate_sat_per_vbyte: u64,
    pub funding_kind: CpfpFundingKind,
    /// The Bitcoin address the swept funds are sent to.
    pub destination: String,
    pub selection: ExitLeafSelection,
}

/// How much to fund one branch of the exit to avoid a fan-out.
#[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 for this branch.
    pub funding_sat: u64,
}

/// Response from `prepare_unilateral_exit`: which leaves would exit, 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 PrepareUnilateralExitResponse {
    pub leaves: Vec<UnilateralExitLeaf>,
    /// Total value of the selected leaves, in satoshis.
    pub recoverable_value_sat: u64,
    /// Total on-chain fee when funding with a single UTXO (fanned out across
    /// branches), in satoshis. Exact for the given funding kind; nodes the
    /// operators report on-chain are assumed already paid, so a partially-exited
    /// tree quotes a lower fee than a fresh one.
    pub total_fee_sat: u64,
    /// The part of `total_fee_sat` paid for the fan-out transaction. Funding one
    /// UTXO per branch (`per_branch_funding`) avoids it. Zero for a single
    /// branch (no fan-out).
    pub fanout_fee_sat: u64,
    /// Fund a single UTXO of at least this many satoshis to exit with a fan-out.
    pub single_utxo_funding_sat: u64,
    /// To skip the fan-out, fund one UTXO per branch of at least the given
    /// amount (one entry per selected leaf).
    pub per_branch_funding: Vec<PerBranchFunding>,
    /// The fee rate this quote was computed at, in sat/vByte.
    pub fee_rate_sat_per_vbyte: u64,
    pub destination: String,
}

/// Request for `unilateral_exit`: a `prepare_unilateral_exit` quote plus the
/// funding UTXOs that pay its fees. The signer is passed separately (it is not a
/// plain data value).
#[derive(Debug, Clone)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct UnilateralExitRequest {
    /// The quote returned by `prepare_unilateral_exit`, naming the leaves to exit.
    pub prepared: PrepareUnilateralExitResponse,
    /// The funding UTXOs that pay the exit's on-chain fees, meeting the quote's
    /// `single_utxo_funding_sat` (one UTXO) or `per_branch_funding` (one per branch).
    pub funding_inputs: Vec<CpfpInput>,
}

/// Result of `unilateral_exit`: a cost summary plus the complete, signed exit
/// path.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
pub struct UnilateralExitResponse {
    /// Total value of the selected leaves, in satoshis.
    pub recoverable_value_sat: u64,
    /// The actual total on-chain fee the returned transactions pay at the
    /// requested rate, in satoshis. A resumed or partially-confirmed exit pays
    /// less because already-confirmed steps are not rebuilt.
    pub total_fee_sat: u64,
    pub leaves: Vec<UnilateralExitLeaf>,
    /// The full signed transaction set, in valid topological (broadcast) order
    /// with shared ancestors appearing once and the sweep last.
    pub transactions: Vec<UnilateralExitTransaction>,
}