bark_json/

web.rs

use bitcoin::{Amount, FeeRate, Txid};
use bitcoin::consensus::encode::serialize_hex;
use bitcoin::secp256k1::PublicKey;
use serde::{Deserialize, Serialize};

use ark::VtxoId;
use ark::lightning::PaymentHash;
use ark::offboard::OffboardRequest;
use ark::tree::signed::UnlockHash;
use ark::vtxo::VtxoPolicyKind;
use bark::round::RoundFlowKind;

#[cfg(feature = "utoipa")]
use utoipa::ToSchema;

use crate::cli::RoundStatus;


/// Query parameters for filtering wallet history by payment method.
///
/// Both fields are optional but must be supplied together: omit both to get the
/// full history, or provide both to filter by a single payment method. The pair
/// mirrors the serialized form of a payment method (its `type` tag and `value`).
#[derive(Default, Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct HistoryQuery {
	/// The payment method type tag to filter by, e.g. `ark`, `bitcoin`,
	/// `output-script`, `invoice`, `offer`, `lightning-address`, `lnurl` or
	/// `custom`. Must be provided together with `value`.
	#[serde(rename = "type")]
	pub method_type: Option<String>,
	/// The payment method value to filter by, e.g. the destination address or
	/// invoice. Must be provided together with `type`.
	pub value: Option<String>,
}

/// Query parameters for fee estimates that only require an amount.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct FeeEstimateQuery {
	/// The amount in satoshis to estimate fees for
	pub amount_sat: u64,
}

/// Query parameters for send-onchain fee estimates.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct SendOnchainFeeEstimateQuery {
	/// The amount in satoshis to send
	pub amount_sat: u64,
	/// The destination Bitcoin address
	pub address: String,
}

/// Query parameters for offboard-all fee estimates.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OffboardAllFeeEstimateQuery {
	/// The destination Bitcoin address
	pub address: String,
}

/// Request body for estimating the fee of offboarding a specific set of VTXOs.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OffboardFeeEstimateRequest {
	/// The destination Bitcoin address. The fee depends on its script type.
	pub address: String,
	/// The IDs of the VTXOs to offboard. Each is offboarded in full.
	pub vtxos: Vec<String>,
}

/// A fee estimate for an Ark wallet operation.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct FeeEstimateResponse {
	/// The total amount including fees (in satoshis)
	#[serde(rename = "gross_amount_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub gross_amount: Amount,
	/// The fee portion (in satoshis)
	#[serde(rename = "fee_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub fee: Amount,
	/// The amount excluding fees (in satoshis). For sends, this is the amount
	/// the recipient receives. For receives, this is the amount the user gets.
	#[serde(rename = "net_amount_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub net_amount: Amount,
	/// The VTXOs that would be spent for this operation
	#[cfg_attr(feature = "utoipa", schema(value_type = Vec<String>))]
	pub vtxos_spent: Vec<VtxoId>,
}

impl From<bark::FeeEstimate> for FeeEstimateResponse {
	fn from(estimate: bark::FeeEstimate) -> Self {
		FeeEstimateResponse {
			gross_amount: estimate.gross_amount,
			fee: estimate.fee,
			net_amount: estimate.net_amount,
			vtxos_spent: estimate.vtxos_spent,
		}
	}
}

/// Query parameters for emergency (unilateral) exit fee estimates.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct EmergencyExitFeeEstimateQuery {
	/// Comma-separated VTXO ids to estimate the exit for. When omitted, every spendable VTXO in
	/// the wallet is used (i.e. exit the entire wallet).
	pub vtxo_ids: Option<String>,
	/// The fee rate to price the estimate at, in sat/vB (fractions allowed). Applied to both the
	/// broadcast and claim legs. When omitted, the broadcast leg uses the current `fast` rate and
	/// the claim leg the `regular` rate.
	pub fee_rate_sat_per_vb: Option<f64>,
	/// The destination address for the claim. Only affects the claim-fee weight; when omitted a
	/// placeholder of the configured network is used.
	pub destination: Option<String>,
	/// Scales the broadcast leg to cover feerate movement and UTXO consolidation. Must be finite
	/// and non-negative; defaults to 1.2.
	pub fee_margin: Option<f64>,
}

/// A fee breakdown for unilaterally (emergency) exiting a set of VTXOs.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct EmergencyExitFeeEstimateResponse {
	/// The CPFP fees to broadcast every not-yet-confirmed exit transaction (in satoshis),
	/// including the fee margin. Paid from confirmed on-chain funds; this is the on-chain balance
	/// to fund the exit with at the chosen margin.
	#[serde(rename = "exit_broadcast_fee_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub exit_broadcast_fee: Amount,
	/// The fee for the single batched transaction that drains the matured exit outputs (in
	/// satoshis). Paid later out of the recovered value.
	#[serde(rename = "claim_fee_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub claim_fee: Amount,
	/// The sum of the broadcast and claim fees (in satoshis).
	#[serde(rename = "total_fee_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub total_fee: Amount,
	/// The fee rate the exit-broadcast leg was priced at (sat/vB), before the fee margin. Unless
	/// an explicit fee rate was supplied, the claim leg is priced separately at the chain's
	/// `regular` rate.
	pub fee_rate_sat_per_vb: f64,
	/// The number of exit transactions that still need to be broadcast and CPFP-bumped.
	pub txs_to_broadcast: usize,
	/// Whether the wallet's on-chain balance covers `exit_broadcast_fee_sat`.
	///
	/// **Deprecated**: the estimate is a funding target and no longer consults
	/// the wallet's funds. Compare `exit_broadcast_fee_sat` against the on-chain
	/// balance instead. This field is still populated from the last synced
	/// on-chain balance for backwards compatibility and will be removed in a
	/// future release.
	#[deprecated(note = "compare `exit_broadcast_fee` against the on-chain balance instead")]
	#[serde(default)]
	#[cfg_attr(feature = "utoipa", schema(required = true))]
	pub fundable: bool,
}

impl EmergencyExitFeeEstimateResponse {
	/// Builds the response from an estimate and the wallet's on-chain balance,
	/// `None` when the wallet has no on-chain wallet to fund the exit from.
	#[allow(deprecated)] // fundable kept for old clients
	pub fn new(e: bark::exit::ExitFeeEstimate, onchain_balance: Option<Amount>) -> Self {
		EmergencyExitFeeEstimateResponse {
			total_fee: e.total(),
			exit_broadcast_fee: e.exit_broadcast_fee,
			claim_fee: e.claim_fee,
			fee_rate_sat_per_vb: e.fee_rate.to_sat_per_kwu() as f64 / 250.0,
			txs_to_broadcast: e.txs_to_broadcast,
			fundable: onchain_balance.map_or(false, |b| b >= e.exit_broadcast_fee),
		}
	}
}

/// Mempool fee rates for on-chain transactions.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OnchainFeeRatesResponse {
	/// Fee rate targeting ~1 block confirmation (sat/vB)
	pub fast_sat_per_vb: u64,
	/// Fee rate targeting ~3 block confirmation (sat/vB)
	pub regular_sat_per_vb: u64,
	/// Fee rate targeting ~6 block confirmation (sat/vB)
	pub slow_sat_per_vb: u64,
}


#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct TipResponse {
	pub tip_height: u32,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct MailboxSyncResponse {
	/// The mailbox checkpoint (tip) the wallet has consumed up to after
	/// the sync. Monotonically non-decreasing across successful syncs.
	pub checkpoint: u64,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct CreateWalletRequest {
	/// The Ark server to use for the wallet.
	/// Optional when a config.toml already exists in the datadir or when
	/// the network has a default Ark server (mainnet and signet).
	pub ark_server: Option<String>,
	/// An access token for a private Ark server.
	///
	/// **Deprecated**: access tokens are no longer enforced by the server;
	/// this field will be removed in a future release.
	#[deprecated(
		since = "0.2.4",
		note = "access tokens are not enforced by the server; this field will be removed",
	)]
	pub ark_server_access_token: Option<String>,
	/// The chain source to use for the wallet.
	/// Optional when a config.toml already exists in the datadir or when
	/// the network has a default chain source (mainnet, signet and
	/// mutinynet).
	pub chain_source: Option<ChainSourceConfig>,
	/// The optional mnemonic to use for the wallet
	pub mnemonic: Option<String>,
	/// The network to use for the wallet
	pub network: BarkNetwork,
	/// An optional birthday height to start syncing the wallet from
	pub birthday_height: Option<u32>,
	/// How many consecutive unused key indices a VTXO key scan may cross before
	/// it concludes the wallet doesn't own a recovered/imported VTXO.
	#[serde(default)]
	#[cfg_attr(feature = "utoipa", schema(maximum = 100_000))]
	pub gap_limit: Option<u32>,
	/// Proceed even if the datadir contains unexpected files
	#[serde(default)]
	pub force: bool,
}

/// Networks bark can be used on
#[derive(Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub enum BarkNetwork {
	/// Bitcoin's mainnet
	Mainnet,
	/// The official Bitcoin Core signet
	Signet,
	/// Mutinynet
	Mutinynet,
	/// Any regtest network
	Regtest,
}

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub enum ChainSourceConfig {
	/// Use a bitcoind RPC server
	Bitcoind {
		bitcoind: String,
		bitcoind_auth: BitcoindAuth,
	},
	/// Use an Esplora HTTP server
	Esplora {
		url: String,
	},
}

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub enum BitcoindAuth {
	/// Use a cookie file for authentication
	Cookie {
		cookie: String,
	},
	/// Use a username and password for authentication
	UserPass {
		user: String,
		pass: String,
	},
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct CreateWalletResponse {
	pub fingerprint: String,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ConnectedResponse {
	/// Whether the wallet is currently connected to its Ark server
	pub connected: bool,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct MnemonicResponse {
	/// The BIP-39 mnemonic phrase backing the wallet.
	pub mnemonic: String,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ArkAddressResponse {
	#[cfg_attr(feature = "utoipa", schema(value_type = String))]
	pub address: String,
}

/// Request to build a BIP 321 unified payment URI.
///
/// An Ark address is always included. A BOLT11 invoice is only included when
/// `amount_sat` is given (an amount is required to create one). An on-chain
/// address is included only when `onchain` is `true`.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct Bip321UriRequest {
	/// Optional amount (in satoshis) to request. When set, it is embedded in
	/// the URI and used to create the BOLT11 invoice. Any server-configured
	/// [LightningReceiveFees](crate::cli::fees::LightningReceiveFees) are
	/// deducted from the amount the client ultimately receives over Lightning.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub amount_sat: Option<u64>,
	/// Whether to include a fresh on-chain address as a payment destination.
	/// Defaults to `false`.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub onchain: Option<bool>,
	/// Optional label describing the payment, recorded in the URI's `label`.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub label: Option<String>,
	/// Optional message describing the payment, recorded in the URI's `message`.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub message: Option<String>,
}

/// Query parameters for building a BIP 321 URI.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct Bip321UriQuery {
	/// Whether to upper-case the returned `bip321` URI so QR encoders can use
	/// the compact alphanumeric mode. Defaults to `false`.
	/// Requesting an upper-case URI fails when it carries case-sensitive data
	/// (a label or message with lowercase characters, or base58 address) that
	/// cannot be upper-cased.
	pub uppercase: Option<bool>,
}

/// A BIP 321 unified payment URI together with its individual destinations.
///
/// The `bip321` field is the combined `bitcoin:` URI; the other fields expose
/// each generated destination separately for convenience. A field is `null`
/// when that destination was not requested or could not be produced.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct Bip321UriResponse {
	/// The generated Ark address, if any.
	#[serde(skip_serializing_if = "Option::is_none")]
	pub ark: Option<String>,
	/// The generated BOLT11 invoice, included only when an amount was given.
	#[serde(skip_serializing_if = "Option::is_none")]
	pub bolt11: Option<String>,
	/// The generated on-chain address, included only when `onchain` was set.
	#[serde(skip_serializing_if = "Option::is_none")]
	pub onchain: Option<String>,
	/// The combined BIP 321 `bitcoin:` URI.
	pub bip321: String,
}

/// Response for the encoded-VTXO endpoint.
///
/// Wraps the hex-encoded VTXO in a named field so clients can easily
/// extract it.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct EncodedVtxoResponse {
	/// Hex-encoded serialized VTXO.
	pub encoded: crate::primitives::EncodedVtxo,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct VtxosQuery {
	/// Return all VTXOs regardless of their state (including spent ones)
	pub all: Option<bool>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct RefreshRequest {
	/// List of VTXO IDs to refresh. The sum of the VTXOs being refreshed must be
	/// >= [P2TR_DUST](bitcoin_ext::P2TR_DUST). Keep in mind that fees set out in
	/// [RefreshFees](crate::cli::fees::RefreshFees) will be deducted from the newly created VTXO, this
	/// value must also be >= [P2TR_DUST](bitcoin_ext::P2TR_DUST).
	pub vtxos: Vec<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct DelegatedRefreshRequest {
	/// List of VTXO IDs to refresh. The sum of the VTXOs being refreshed must be
	/// >= [P2TR_DUST](bitcoin_ext::P2TR_DUST). Keep in mind that fees set out in
	/// [RefreshFees](crate::cli::fees::RefreshFees) will be deducted from the newly created VTXO, this
	/// value must also be >= [P2TR_DUST](bitcoin_ext::P2TR_DUST).
	pub vtxos: Vec<String>,
	/// Optional block height to schedule the refresh at. When set, the refresh fee is priced at
	/// that height and the server includes the participation in the first round once the chain
	/// tip reaches it; when omitted, the participation is eligible for the next round.
	pub height: Option<u32>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct BoardRequest {
	/// An amount of onchain funds to board (in satoshis). For a board operation to be successful,
	/// this value, with any server-configured [BoardFees](crate::cli::fees::BoardFees) deducted, must be
	/// >= [P2TR_DUST](bitcoin_ext::P2TR_DUST).
	pub amount_sat: u64,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct SendRequest {
	/// The destination can be an Ark address, a BOLT11-invoice, LNURL or a lightning address
	pub destination: String,
	/// The amount to send (in satoshis). Optional for bolt11 invoices. Depending on the
	/// `destination`, the wallet must contain this amount plus any fees configured by the server in
	/// [FeeSchedule](crate::cli::fees::FeeSchedule).
	pub amount_sat: Option<u64>,
	/// An optional comment, only supported when paying to lightning addresses
	pub comment: Option<String>,
	/// For lightning destinations, how many seconds the Ark server should keep
	/// trying to pay, capped to the server's maximum. The server picks its
	/// default when empty.
	#[serde(default)]
	pub retry_for_secs: Option<u64>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct SendResponse {
	/// Success message
	pub message: String,
	/// The payment hash, when the destination resolved to a lightning
	/// payment. Can be used to poll the payment status.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	#[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
	pub payment_hash: Option<PaymentHash>,
}

/// Request to sign an arbitrary message with one of the wallet's keys
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct SignMessageRequest {
	/// The message to sign
	pub message: String,
	/// The Ark address to sign the message with
	pub address: String,
}

/// Request to verify a signed message
///
/// Exactly one of `pubkey` and `address` must be set.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct VerifyMessageRequest {
	/// The message that was signed
	pub message: String,
	/// The BIP-340 Schnorr signature over the message digest
	/// `SHA256("bark/message" || message)`, in hex
	pub signature: String,
	/// The public key to verify the signature against
	pub pubkey: Option<String>,
	/// The Ark address whose user public key to verify the signature against
	pub address: Option<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct SendOnchainRequest {
	/// The destination Bitcoin address
	pub destination: String,
	/// The amount (in satoshis) to be received by `destination` onchain. Must be
	/// >= [P2TR_DUST](bitcoin_ext::P2TR_DUST). Server-configured fees laid out in
	/// [OffboardFees](crate::cli::fees::OffboardFees) will be added on top of this amount.
	pub amount_sat: u64,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OffboardVtxosRequest {
	/// Optional Bitcoin address to send to. If not provided, uses the onchain wallet's address
	pub address: Option<String>,
	/// List of VTXO IDs to offboard. The sum of the VTXOs being refreshed must be
	/// >= [P2TR_DUST](bitcoin_ext::P2TR_DUST) after the server-configured
	/// [OffboardFees](crate::cli::fees::OffboardFees) are deducted.
	pub vtxos: Vec<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OffboardAllRequest {
	/// Optional Bitcoin address to send to. If not provided, uses the onchain wallet's address
	pub address: Option<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ImportVtxoRequest {
	/// Hex-encoded VTXOs to import
	pub vtxos: Vec<String>,
	/// How many consecutive unused key indices to scan for each VTXO's user
	/// pubkey. Overrides the wallet's configured gap limit.
	#[serde(default)]
	#[cfg_attr(feature = "utoipa", schema(maximum = 100_000))]
	pub gap_limit: Option<u32>,
	/// Import as spendable without asking the server for each VTXO's state.
	///
	/// Use it when you already know it's spendable or when the server can't be reached,
	/// as it can leave the wallet in an inconsistent state.
	#[serde(default)]
	pub skip_status_check: bool,
	/// Keep the VTXOs that import successfully even when another one in the
	/// request fails. The response lists the VTXOs that were kept.
	///
	/// Without it, a single failure discards the whole request.
	#[serde(default)]
	pub allow_partial: bool,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct LightningInvoiceRequest {
	/// The amount to create invoice for (in satoshis). This is the amount the payee will pay but
	/// the final amount received by the client will have any server-configured
	/// [LightningReceiveFees](crate::cli::fees::LightningReceiveFees) deducted.
	pub amount_sat: u64,
	/// Optional description embedded in the invoice as its memo.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub description: Option<String>,
	/// Optional lightning receive token for authentication of the claim, if
	/// the server requires one and there are no existing spendable VTXOs to
	/// prove ownership of.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub token: Option<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct LightningInvoiceForAddressRequest {
	/// The amount to create invoice for (in satoshis).
	pub amount_sat: u64,
	/// Ark address that will receive the claimed VTXO.
	pub address: String,
	/// Optional description embedded in the invoice as its memo.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	pub description: Option<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct LightningPayRequest {
	/// The invoice, offer, or lightning address to pay
	pub destination: String,
	/// The amount to send (in satoshis). Optional for bolt11 invoices with amount. This must be
	/// higher than the minimum fee laid out in server-configured
	/// [LightningSendFees](crate::cli::fees::LightningSendFees). The wallet must also contain enough
	/// funds to cover the amount plus any fees.
	pub amount_sat: Option<u64>,
	/// An optional comment, only supported when paying to lightning addresses
	pub comment: Option<String>,
	/// How many seconds the Ark server should keep trying to pay, capped to
	/// the server's maximum. The server picks its default when empty.
	#[serde(default)]
	pub retry_for_secs: Option<u64>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct LightningPayResponse {
	/// Success message
	pub message: String,
	/// The payment hash of the lightning payment. Can be used to poll the
	/// payment status.
	#[serde(default, skip_serializing_if = "Option::is_none")]
	#[cfg_attr(feature = "utoipa", schema(value_type = Option<String>))]
	pub payment_hash: Option<PaymentHash>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OnchainSendRequest {
	/// The destination Bitcoin address
	pub destination: String,
	/// The amount to send (in satoshis)
	pub amount_sat: u64,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OnchainSendManyRequest {
	/// List of destinations in format "address:amount"
	pub destinations: Vec<String>,
	/// Sends the transaction immediately instead of waiting
	pub immediate: Option<bool>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OnchainDrainRequest {
	/// The destination Bitcoin address
	pub destination: String,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitStatusRequest {
	/// Whether to include the detailed history of the exit process
	pub history: Option<bool>,
	/// Whether to include the exit transactions and their CPFP children
	pub transactions: Option<bool>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitStartRequest {
	/// The ID of VTXOs to unilaterally exit
	pub vtxos: Vec<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitStartResponse {
	pub message: String,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitProgressRequest {
	/// Wait until the exit is completed
	pub wait: Option<bool>,
	/// Sets the desired fee-rate in sats/kvB to use broadcasting exit transactions
	pub fee_rate: Option<u64>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitClaimAllRequest {
	/// The destination Bitcoin address
	pub destination: String,
	/// Sets the desired fee-rate in sats/kvB to use broadcasting exit transactions
	pub fee_rate: Option<u64>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitClaimVtxosRequest {
	/// The destination Bitcoin address
	pub destination: String,
	/// The ID of an exited VTXO to be claimed
	pub vtxos: Vec<String>,
	/// Sets the desired fee-rate in sats/kvB to use broadcasting exit transactions
	pub fee_rate: Option<u64>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitClaimResponse {
	pub message: String,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct ExitCancelResponse {
	pub message: String,
}


#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct VtxoRequestInfo {
	#[serde(rename = "amount_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub amount: Amount,
	#[cfg_attr(feature = "utoipa", schema(value_type = String))]
	pub policy_type: VtxoPolicyKind,
	#[cfg_attr(feature = "utoipa", schema(value_type = String))]
	pub user_pubkey: PublicKey,
}

impl<'a> From<&'a ark::VtxoRequest> for VtxoRequestInfo {
	fn from(v: &'a ark::VtxoRequest) -> Self {
		Self {
			amount: v.amount,
			policy_type: v.policy.policy_type(),
			user_pubkey: v.policy.user_pubkey(),
		}
	}
}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Deserialize, Serialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct OffboardRequestInfo {
	/// hexadecimal representation of the output script
	pub script_pubkey_hex: String,
	/// opcode representation of the output script
	pub script_pubkey_asm: String,
	/// The target amount in sats.
	#[serde(rename = "net_amount_sat", with = "bitcoin::amount::serde::as_sat")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub net_amount: Amount,
	/// Determines whether fees should be added onto the given amount or deducted from it.
	pub deduct_fees_from_gross_amount: bool,
	/// What fee rate was used when calculating the fee for the offboard.
	#[serde(rename = "fee_rate_kwu")]
	#[cfg_attr(feature = "utoipa", schema(value_type = u64))]
	pub fee_rate: FeeRate,
}

impl<'a> From<&'a OffboardRequest> for OffboardRequestInfo {
	fn from(v: &'a OffboardRequest) -> Self {
		Self {
			script_pubkey_hex: v.script_pubkey.to_hex_string(),
			script_pubkey_asm: v.script_pubkey.to_asm_string(),
			net_amount: v.net_amount,
			deduct_fees_from_gross_amount: v.deduct_fees_from_gross_amount,
			fee_rate: v.fee_rate,
		}
	}
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct RoundParticipationInfo {
	#[cfg_attr(feature = "utoipa", schema(value_type = Vec<String>))]
	pub inputs: Vec<VtxoId>,
	pub outputs: Vec<VtxoRequestInfo>,
}

impl<'a> From<&'a bark::round::RoundParticipation> for RoundParticipationInfo {
	fn from(v: &'a bark::round::RoundParticipation) -> Self {
		Self {
			inputs: v.inputs.iter().map(|v| v.id()).collect(),
			outputs: v.outputs.iter().map(Into::into).collect(),
		}
	}
}

/// Lifecycle phase of a round participation.
#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
#[serde(rename_all = "kebab-case")]
pub enum RoundFlowState {
	/// Delegated participation waiting for its round.
	DelegatedPending,
	/// Interactive participation waiting for its round.
	Pending,
	/// The interactive part is being played out with the server.
	Ongoing,
	/// The round finished and its funding tx is waiting for confirmations.
	AwaitingConfirmations,
	/// The participation failed.
	Failed,
	/// The user canceled the participation.
	Canceled,
}

impl From<RoundFlowKind> for RoundFlowState {
	fn from(kind: RoundFlowKind) -> Self {
		match kind {
			RoundFlowKind::DelegatedPending => Self::DelegatedPending,
			RoundFlowKind::Pending => Self::Pending,
			RoundFlowKind::Ongoing => Self::Ongoing,
			RoundFlowKind::AwaitingConfirmations => Self::AwaitingConfirmations,
			RoundFlowKind::Failed => Self::Failed,
			RoundFlowKind::Canceled => Self::Canceled,
		}
	}
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct PendingRoundInfo {
	/// Unique identifier for the round
	pub id: u32,
	/// the current status of the round
	pub status: RoundStatus,
	/// Lifecycle phase of the participation
	pub state: RoundFlowState,
	/// the round participation details
	pub participation: RoundParticipationInfo,
	#[cfg_attr(feature = "utoipa", schema(value_type = String, nullable = true))]
	pub unlock_hash: Option<UnlockHash>,
	/// The block height a delegated participation is scheduled for, if any
	#[serde(default)]
	pub scheduled_height: Option<u32>,
	/// The round transaction id, if already assigned
	#[cfg_attr(feature = "utoipa", schema(value_type = String, nullable = true))]
	pub funding_txid: Option<Txid>,
	pub funding_tx_hex: Option<String>,
}

impl PendingRoundInfo {
	pub fn new<G>(
		state: &bark::persist::models::StoredRoundState<G>,
		sync_result: anyhow::Result<bark::round::RoundStatus>,
	) -> Self {
		let funding_tx = state.state().funding_tx();
		Self {
			id: state.id().0,
			status: match sync_result {
				Ok(status) => status.into(),
				Err(e) => RoundStatus::SyncError {
					error: format!("{:#}", e),
				},
			},
			state: state.state().flow_kind().into(),
			participation: state.state().participation().into(),
			unlock_hash: state.state().unlock_hash(),
			scheduled_height: state.state().scheduled_height().map(Into::into),
			funding_txid: funding_tx.map(|t| t.compute_txid()),
			funding_tx_hex: funding_tx.map(|t| serialize_hex(t)),
		}
	}

	/// Like [PendingRoundInfo::new], but without contacting the server: the
	/// status is derived from the stored state alone.
	pub fn from_state<G>(state: &bark::persist::models::StoredRoundState<G>) -> Self {
		let status = match state.state().flow_kind() {
			RoundFlowKind::AwaitingConfirmations => {
				bark::round::RoundStatus::Unconfirmed {
					funding_txid: state.state().funding_tx()
						.expect("finished rounds have a funding tx")
						.compute_txid(),
				}
			},
			RoundFlowKind::Canceled => bark::round::RoundStatus::Canceled,
			RoundFlowKind::DelegatedPending
				| RoundFlowKind::Pending
				| RoundFlowKind::Ongoing
				| RoundFlowKind::Failed
			=> bark::round::RoundStatus::Pending,
		};
		Self::new(state, Ok(status))
	}
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct WalletExistsResponse {
	pub fingerprint: Option<String>,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct WalletDeleteRequest {
	pub dangerous: bool,
	pub fingerprint: String,
}

#[derive(Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(ToSchema))]
pub struct WalletDeleteResponse {
	pub deleted: bool,
	pub fingerprint: Option<String>,
	pub message: String,
}