breez_sdk_spark/sdk/

unilateral_exit.rs

use std::collections::{HashMap, HashSet};
use std::str::FromStr;
use std::sync::Arc;

use bitcoin::{
    Address, Amount, CompressedPublicKey, OutPoint, ScriptBuf, Transaction, TxOut, Txid,
    XOnlyPublicKey,
    address::NetworkUnchecked,
    consensus::encode::{deserialize_hex, serialize_hex},
    secp256k1::PublicKey,
};

use spark_wallet::{
    AddressUtxo, ChainQuery, ChainResult, ConfirmedExitNode as WalletConfirmedExitNode, CpfpInput,
    ExitChainState as WalletExitChainState, ExitCheck, ExitCheckInput,
    ExitNodeConfirmation as WalletExitNodeConfirmation, ExitRefund as WalletExitRefund,
    ExitRefundState as WalletExitRefundState, ExitTxKind, ExitTxStatus, Observation, SpendInfo,
    TreeNode, TreeNodeId, UnilateralExitBuild, build_unilateral_exit, check_exit_chain,
    is_ephemeral_anchor_output, leaf_refund_addresses, scan_exit_chain, scan_funding,
};

use tracing::{debug, trace, warn};

use crate::{
    chain::{BitcoinChainService, Outspend},
    error::SdkError,
    models::{
        CheckUnilateralExitRequest, CheckUnilateralExitResponse, ConfirmedExitNode,
        CpfpFundingKind, CpfpInput as ModelCpfpInput, ExitChainState as ModelExitChainState,
        ExitLeafSelection, ExitNodeConfirmation, ExitRefund, ExitRefundState,
        ExitTransactionStatus, PerBranchFunding, PrepareUnilateralExitRequest,
        PrepareUnilateralExitResponse, UnilateralExitLeaf, UnilateralExitRedoReason,
        UnilateralExitRequest, UnilateralExitResponse, UnilateralExitTransaction,
        UnilateralExitTxKind, UnilateralExitVerdict,
    },
    signer::CpfpSigner,
};

use super::BreezSdk;

#[cfg_attr(feature = "uniffi", uniffi::export(async_runtime = "tokio"))]
#[allow(clippy::needless_pass_by_value)]
impl BreezSdk {
    /// Quotes a unilateral exit without any funding UTXOs: selects which leaves
    /// would exit, computes the exact fee for the given funding kind, and reports
    /// how much to fund.
    pub async fn prepare_unilateral_exit(
        &self,
        request: PrepareUnilateralExitRequest,
    ) -> Result<PrepareUnilateralExitResponse, SdkError> {
        debug!(
            fee_rate_sat_per_vbyte = request.fee_rate_sat_per_vbyte,
            funding_kind = ?request.funding_kind,
            selection = ?request.selection,
            "prepare_unilateral_exit: quoting"
        );
        let btc_network: bitcoin::Network = self.config.network.into();

        let destination = request
            .destination
            .parse::<Address<NetworkUnchecked>>()
            .map_err(|e| SdkError::InvalidInput(format!("Invalid destination address: {e}")))?
            .require_network(btc_network)
            .map_err(|e| SdkError::InvalidInput(format!("Address network mismatch: {e}")))?;
        let dest_script_len = destination.script_pubkey().len();

        let selection = wallet_selection(request.selection)?;

        let (input_weight, output_script) = funding_kind_params(&request.funding_kind)?;
        let mut context = self.spark_wallet.load_exit_context(selection).await?;

        // Ask the chain what these leaves have already done before pricing them,
        // so a leaf part-way out is quoted on the work it has left rather than on
        // a fresh exit, and is not dropped as unprofitable over work already
        // paid for. Every lookup the tree needs happens here.
        let refund_addresses = leaf_refund_addresses(
            &context.tree_nodes,
            &context.leaf_ids,
            self.config.network.into(),
        );
        let exit_chain_state = resolve_exit_chain_state(
            self.chain_service.as_ref(),
            &context.tree_nodes,
            &context.leaf_ids,
            &refund_addresses,
        )
        .await?;
        // A leaf whose exit already finished is not exited again, whether named or
        // not; `exit_chain_state` still reports it as swept or stopped.
        context.drop_finished_leaves(&exit_chain_state);

        let quote = self.spark_wallet.quote_unilateral_exit(
            &context,
            sat_per_kw_from_vbyte(request.fee_rate_sat_per_vbyte),
            input_weight,
            output_script.len(),
            output_script.minimal_non_dust().to_sat(),
            dest_script_len,
            &exit_chain_state,
        )?;
        // No selected leaves is not an error: return an empty quote.
        let recoverable_value_sat = quote
            .selected_leaves
            .iter()
            .map(|l| l.value)
            .fold(0u64, u64::saturating_add);
        let leaves = quote
            .selected_leaves
            .iter()
            .map(|l| UnilateralExitLeaf {
                leaf_id: l.id.to_string(),
                value: l.value,
            })
            .collect();
        let per_branch_funding: Vec<PerBranchFunding> = quote
            .per_branch_funding
            .into_iter()
            .map(|(id, funding_sat)| PerBranchFunding {
                leaf_id: id.to_string(),
                funding_sat,
            })
            .collect();

        debug!(
            selected_leaves = quote.selected_leaves.len(),
            recoverable_value_sat,
            total_fee_sat = quote.total_fee_sat,
            cpfp_fee_sat = quote.cpfp_fee_sat,
            fanout_fee_sat = quote.fanout_fee_sat,
            sweep_fee_sat = quote.sweep_fee_sat,
            single_utxo_funding_sat = quote.single_utxo_funding_sat,
            branches = per_branch_funding.len(),
            "prepare_unilateral_exit: quote ready"
        );

        Ok(PrepareUnilateralExitResponse {
            leaves,
            recoverable_value_sat,
            total_fee_sat: quote.total_fee_sat,
            cpfp_fee_sat: quote.cpfp_fee_sat,
            fanout_fee_sat: quote.fanout_fee_sat,
            sweep_fee_sat: quote.sweep_fee_sat,
            single_utxo_funding_sat: quote.single_utxo_funding_sat,
            per_branch_funding,
            fee_rate_sat_per_vbyte: request.fee_rate_sat_per_vbyte,
            destination: request.destination,
            exit_chain_state: exit_chain_state_model(exit_chain_state),
        })
    }

    /// Reads an exit you kept back against the chain: which of its transactions
    /// are now in a block, and whether it can still be finished as it stands.
    ///
    /// Needs neither the wallet's leaves nor a signer, so an exit can be followed
    /// from the response alone. Store the response in place of the one you passed
    /// in, and broadcast what its statuses leave to send.
    pub async fn check_unilateral_exit(
        &self,
        request: CheckUnilateralExitRequest,
    ) -> Result<CheckUnilateralExitResponse, SdkError> {
        let mut exit = request.exit;
        debug!(
            transactions = exit.transactions.len(),
            "check_unilateral_exit: reading back"
        );

        let inputs = exit
            .transactions
            .iter()
            .map(exit_check_input)
            .collect::<Result<Vec<_>, SdkError>>()?;
        let check = resolve_exit_check(self.chain_service.as_ref(), &inputs).await?;

        for tx in &mut exit.transactions {
            let txid = Txid::from_str(&tx.txid)
                .map_err(|e| SdkError::InvalidInput(format!("Invalid txid {}: {e}", tx.txid)))?;
            tx.status = status_after_check(tx.status, &check, &txid);
        }

        resolve_statuses(self.chain_service.as_ref(), &mut exit.transactions).await?;

        let all_confirmed = exit
            .transactions
            .iter()
            .all(|tx| matches!(tx.status, ExitTransactionStatus::Confirmed { .. }));
        let verdict = if check.diverged {
            UnilateralExitVerdict::Redo {
                reason: UnilateralExitRedoReason::OnChainStateDiverged,
            }
        } else if all_confirmed && !exit.transactions.is_empty() {
            UnilateralExitVerdict::Done
        } else {
            UnilateralExitVerdict::Valid
        };
        debug!(?verdict, "check_unilateral_exit: read back");

        Ok(CheckUnilateralExitResponse { exit, verdict })
    }

    /// Builds and signs a complete unilateral exit from a `prepare_unilateral_exit`
    /// quote and the actual funding UTXOs, returning the full transaction set in
    /// topological broadcast order without broadcasting. Broadcast it over time,
    /// respecting each transaction's `depends_on` and `csv_timelock_blocks`.
    ///
    /// It reads on-chain state first: an already-confirmed fan-out or CPFP node
    /// is not rebuilt, and a leaf refund already on-chain (recognized by the
    /// leaf's refund address, so any refund variant counts) is swept directly.
    /// Re-running after partial progress therefore resumes rather than restarts.
    #[allow(clippy::too_many_lines)]
    pub async fn unilateral_exit(
        &self,
        request: UnilateralExitRequest,
        signer: Arc<dyn CpfpSigner>,
    ) -> Result<UnilateralExitResponse, SdkError> {
        let UnilateralExitRequest {
            prepared,
            funding_inputs,
        } = request;
        let supplied_funding = funding_inputs.clone();
        debug!(
            leaves = prepared.leaves.len(),
            funding_inputs = funding_inputs.len(),
            fee_rate_sat_per_vbyte = prepared.fee_rate_sat_per_vbyte,
            "unilateral_exit: building"
        );
        let btc_network: bitcoin::Network = self.config.network.into();
        let chain = self.chain_service.as_ref();

        let destination = prepared
            .destination
            .parse::<Address<NetworkUnchecked>>()
            .map_err(|e| SdkError::InvalidInput(format!("Invalid destination address: {e}")))?
            .require_network(btc_network)
            .map_err(|e| SdkError::InvalidInput(format!("Address network mismatch: {e}")))?;
        let dest_script_len = destination.script_pubkey().len();

        // The build never re-selects: the quote's leaves are an explicit set.
        let leaf_ids = prepared
            .leaves
            .iter()
            .map(|l| {
                TreeNodeId::from_str(&l.leaf_id).map_err(|e| {
                    SdkError::InvalidInput(format!("Invalid leaf id {}: {e}", l.leaf_id))
                })
            })
            .collect::<Result<Vec<_>, _>>()?;
        if leaf_ids.is_empty() {
            // An empty quote builds to an empty result rather than erroring.
            debug!("unilateral_exit: quote has no leaves, returning empty result");
            return Ok(empty_exit_response());
        }

        let funding_inputs = funding_inputs
            .into_iter()
            .map(|i| i.into_funding_input(btc_network))
            .collect::<Result<Vec<_>, SdkError>>()?;
        if funding_inputs.is_empty() {
            return Err(SdkError::InvalidInput(
                "At least one funding input is required".to_string(),
            ));
        }

        // A prior run spends the funding it was given, so what the caller hands
        // back may name outputs that are gone. Follow them to what they became
        // before planning, so the plan is made over what can actually be spent.
        let funding_inputs = resolve_funding(chain, funding_inputs).await?;
        // Followed to nothing: a previous run spent all of it. That is a
        // shortfall, not a malformed request.
        if funding_inputs.is_empty() {
            return Err(SdkError::InsufficientCpfpFunds {
                required_sat: prepared.single_utxo_funding_sat,
            });
        }
        let fee_rate_sat_per_kw = sat_per_kw_from_vbyte(prepared.fee_rate_sat_per_vbyte);
        let chain_state = exit_chain_state_from_model(&prepared.exit_chain_state)?;
        let context = self
            .spark_wallet
            .load_exit_context(spark_wallet::ExitLeafSelection::Specific(leaf_ids))
            .await?;
        let prepared_exit = self.spark_wallet.prepare_unilateral_exit_plan(
            &context,
            fee_rate_sat_per_kw,
            funding_inputs,
            dest_script_len,
            &chain_state,
        )?;
        if prepared_exit.selected_leaves.is_empty() {
            debug!("unilateral_exit: plan selected no leaves, returning empty result");
            return Ok(empty_exit_response());
        }
        trace!(
            selected_leaves = prepared_exit.selected_leaves.len(),
            tree_nodes = prepared_exit.tree_nodes.len(),
            has_fan_out = prepared_exit.fan_out_psbt.is_some(),
            "unilateral_exit: plan prepared"
        );

        let leaves: Vec<UnilateralExitLeaf> = prepared_exit
            .selected_leaves
            .iter()
            .map(|l| UnilateralExitLeaf {
                leaf_id: l.id.to_string(),
                value: l.value,
            })
            .collect();

        let build = build_unilateral_exit(&prepared_exit, &chain_state, fee_rate_sat_per_kw)?;
        let recoverable_value_sat = build.recoverable_value_sat;
        let cpfp_fee_sat = build.cpfp_fee_sat;
        let fanout_fee_sat = build.fanout_fee_sat;
        let build_fee_sat = cpfp_fee_sat.saturating_add(fanout_fee_sat);
        // Captured before the loop below consumes `build.branches`.
        let sweep_status = sweep_initial_status(&build);
        debug!(
            has_fan_out = build.fan_out.is_some(),
            branches = build.branches.len(),
            refund_outputs = build.refund_outputs.len(),
            cpfp_change_inputs = build.cpfp_change_inputs.len(),
            recoverable_value_sat,
            cpfp_fee_sat,
            fanout_fee_sat,
            "unilateral_exit: build assembled, signing"
        );

        let mut transactions: Vec<UnilateralExitTransaction> = Vec::new();

        if let Some(fan_out) = build.fan_out {
            trace!(
                txid = %fan_out.txid,
                status = ?fan_out.status,
                needs_signing = fan_out.to_sign.is_some(),
                "unilateral_exit: fan-out"
            );
            let tx_hex = match fan_out.to_sign {
                Some(psbt) => sign_psbt_via(psbt, signer.as_ref()).await?,
                None => serialize_hex(&fan_out.base_tx),
            };
            transactions.push(UnilateralExitTransaction {
                kind: UnilateralExitTxKind::FanOut,
                node_id: None,
                txid: fan_out.txid.to_string(),
                tx_hex,
                cpfp_tx_hex: None,
                csv_timelock_blocks: fan_out.csv_timelock_blocks,
                depends_on: fan_out.depends_on.iter().map(ToString::to_string).collect(),
                status: initial_status(fan_out.status),
            });
        }

        for branch in build.branches {
            trace!(leaf_id = %branch.leaf_id, txs = branch.txs.len(), "unilateral_exit: branch");
            for tx in branch.txs {
                let kind = match tx.kind {
                    ExitTxKind::Node => UnilateralExitTxKind::Node,
                    ExitTxKind::Refund => UnilateralExitTxKind::Refund,
                    // The fan-out is emitted above, never inside a branch.
                    ExitTxKind::FanOut => continue,
                };
                trace!(
                    ?kind,
                    node_id = ?tx.node_id.as_ref().map(ToString::to_string),
                    txid = %tx.txid,
                    status = ?tx.status,
                    needs_cpfp_child = tx.to_sign.is_some(),
                    csv_timelock_blocks = ?tx.csv_timelock_blocks,
                    depends_on = tx.depends_on.len(),
                    "unilateral_exit: exit tx"
                );
                let cpfp_tx_hex = match tx.to_sign {
                    Some(child) => Some(sign_psbt_via(child, signer.as_ref()).await?),
                    None => None,
                };
                transactions.push(UnilateralExitTransaction {
                    kind,
                    node_id: tx.node_id.map(|id| id.to_string()),
                    txid: tx.txid.to_string(),
                    tx_hex: serialize_hex(&tx.base_tx),
                    cpfp_tx_hex,
                    csv_timelock_blocks: tx.csv_timelock_blocks,
                    depends_on: tx.depends_on.iter().map(ToString::to_string).collect(),
                    status: initial_status(tx.status),
                });
            }
        }

        // A sweep over zero inputs would error: return without one when no refund
        // is on-chain yet. A later run sweeps any refund that surfaces.
        if build.refund_outputs.is_empty() {
            resolve_statuses(chain, &mut transactions).await?;
            debug!("unilateral_exit: no refund outputs to sweep, omitting the sweep");
            return Ok(UnilateralExitResponse {
                recoverable_value_sat,
                total_fee_sat: build_fee_sat,
                cpfp_fee_sat,
                fanout_fee_sat,
                sweep_fee_sat: 0,
                leaves,
                transactions,
                funding_inputs: supplied_funding,
            });
        }

        let refund_txids: Vec<String> = build
            .refund_outputs
            .iter()
            .map(|r| r.outpoint.txid.to_string())
            .collect();
        let sweep_psbt = self
            .spark_wallet
            .create_refund_sweep_transaction(
                build.refund_outputs,
                build.cpfp_change_inputs,
                destination,
                fee_rate_sat_per_kw,
            )
            .await?;
        let sweep_fee_sat = sweep_fee(&sweep_psbt);
        let total_fee_sat = build_fee_sat.saturating_add(sweep_fee_sat);
        let sweep_txid = sweep_psbt.unsigned_tx.compute_txid();
        trace!(
            txid = %sweep_txid,
            status = ?sweep_status,
            refund_inputs = refund_txids.len(),
            "unilateral_exit: sweep"
        );
        let sweep_tx_hex = finalize_sweep(sweep_psbt, signer.as_ref()).await?;
        transactions.push(UnilateralExitTransaction {
            kind: UnilateralExitTxKind::Sweep,
            node_id: None,
            txid: sweep_txid.to_string(),
            tx_hex: sweep_tx_hex,
            cpfp_tx_hex: None,
            csv_timelock_blocks: None,
            depends_on: refund_txids,
            status: sweep_status,
        });

        resolve_statuses(chain, &mut transactions).await?;
        debug!(
            transactions = transactions.len(),
            recoverable_value_sat, total_fee_sat, sweep_fee_sat, "unilateral_exit: complete"
        );
        Ok(UnilateralExitResponse {
            recoverable_value_sat,
            total_fee_sat,
            cpfp_fee_sat,
            fanout_fee_sat,
            sweep_fee_sat,
            leaves,
            transactions,
            funding_inputs: supplied_funding,
        })
    }
}

/// The sweep's fee: total input value minus output value.
fn sweep_fee(sweep_psbt: &bitcoin::Psbt) -> u64 {
    let in_value: u64 = sweep_psbt
        .inputs
        .iter()
        .filter_map(|i| i.witness_utxo.as_ref())
        .map(|o| o.value.to_sat())
        .fold(0u64, u64::saturating_add);
    let out_value: u64 = sweep_psbt
        .unsigned_tx
        .output
        .iter()
        .map(|o| o.value.to_sat())
        .fold(0u64, u64::saturating_add);
    in_value.saturating_sub(out_value)
}

/// Converts a sat/vByte fee rate (the public API unit) to sat/kW (the exit
/// engine's unit): one vByte is 4 weight units, so 1 sat/vByte is 250 sat/kW.
fn sat_per_kw_from_vbyte(sat_per_vbyte: u64) -> u64 {
    sat_per_vbyte.saturating_mul(250)
}

/// The signed input weight and a representative output scriptPubKey for a
/// funding kind.
fn funding_kind_params(kind: &CpfpFundingKind) -> Result<(u64, ScriptBuf), SdkError> {
    // Only the scriptPubKey length matters here (it fixes output weight and
    // dust), so any valid program of the right size works.
    let witness_script = |version, program: &[u8]| -> Result<ScriptBuf, SdkError> {
        let program = bitcoin::WitnessProgram::new(version, program).map_err(|e| {
            SdkError::Generic(format!("invalid representative witness program: {e}"))
        })?;
        Ok(ScriptBuf::new_witness_program(&program))
    };
    let (weight, script) = match kind {
        CpfpFundingKind::P2wpkh => (
            spark_wallet::p2wpkh_input_weight().to_wu(),
            witness_script(bitcoin::WitnessVersion::V0, &[0u8; 20])?,
        ),
        CpfpFundingKind::P2tr => (
            spark_wallet::p2tr_key_path_input_weight().to_wu(),
            witness_script(bitcoin::WitnessVersion::V1, &[0u8; 32])?,
        ),
        CpfpFundingKind::Custom {
            script_pubkey_hex,
            signed_input_weight,
        } => {
            let script = ScriptBuf::from_hex(script_pubkey_hex).map_err(|e| {
                SdkError::InvalidInput(format!("Invalid funding script_pubkey_hex: {e}"))
            })?;
            // Only native SegWit funding is supported: the exit threads txids from
            // unsigned txs, stable only when the input's scriptSig stays empty.
            // Reject here so the quote fails before funding is gathered.
            if !script.is_witness_program() {
                return Err(SdkError::InvalidInput(
                    "Custom funding must pay to a native SegWit (witness-program) script"
                        .to_string(),
                ));
            }
            (*signed_input_weight, script)
        }
    };
    Ok((weight, script))
}

impl ModelCpfpInput {
    /// Converts into the spark-wallet funding type. Takes `network` to derive
    /// the P2WPKH/P2TR script from a pubkey.
    fn into_funding_input(self, network: bitcoin::Network) -> Result<CpfpInput, SdkError> {
        let parse_txid = |s: &str| {
            Txid::from_str(s)
                .map_err(|e| SdkError::InvalidInput(format!("Invalid funding txid: {e}")))
        };
        match self {
            ModelCpfpInput::P2wpkh {
                txid,
                vout,
                value,
                pubkey,
            } => {
                let pk = PublicKey::from_str(&pubkey)
                    .map_err(|e| SdkError::InvalidInput(format!("Invalid funding pubkey: {e}")))?;
                let script_pubkey =
                    Address::p2wpkh(&CompressedPublicKey(pk), network).script_pubkey();
                Ok(CpfpInput {
                    outpoint: OutPoint {
                        txid: parse_txid(&txid)?,
                        vout,
                    },
                    witness_utxo: TxOut {
                        value: Amount::from_sat(value),
                        script_pubkey,
                    },
                    signed_input_weight: spark_wallet::p2wpkh_input_weight().to_wu(),
                })
            }
            ModelCpfpInput::P2tr {
                txid,
                vout,
                value,
                pubkey,
            } => {
                let xonly = parse_xonly(&pubkey)?;
                let secp = bitcoin::secp256k1::Secp256k1::verification_only();
                let script_pubkey = Address::p2tr(&secp, xonly, None, network).script_pubkey();
                Ok(CpfpInput {
                    outpoint: OutPoint {
                        txid: parse_txid(&txid)?,
                        vout,
                    },
                    witness_utxo: TxOut {
                        value: Amount::from_sat(value),
                        script_pubkey,
                    },
                    signed_input_weight: spark_wallet::p2tr_key_path_input_weight().to_wu(),
                })
            }
            ModelCpfpInput::Custom {
                txid,
                vout,
                value,
                script_pubkey_hex,
                signed_input_weight,
            } => {
                let script_pubkey = ScriptBuf::from_hex(&script_pubkey_hex).map_err(|e| {
                    SdkError::InvalidInput(format!("Invalid funding scriptPubKey hex: {e}"))
                })?;
                // The exit signs/weighs funding inputs as SegWit and spends them in
                // a v3/TRUC anchor package; a legacy input breaks both. Reject it.
                if !script_pubkey.is_witness_program() {
                    return Err(SdkError::InvalidInput(
                        "Custom funding input must pay to a SegWit (witness-program) script"
                            .to_string(),
                    ));
                }
                Ok(CpfpInput {
                    outpoint: OutPoint {
                        txid: parse_txid(&txid)?,
                        vout,
                    },
                    witness_utxo: TxOut {
                        value: Amount::from_sat(value),
                        script_pubkey,
                    },
                    signed_input_weight,
                })
            }
        }
    }
}

/// Parses an x-only pubkey from hex, accepting both x-only (32-byte) and
/// compressed (33-byte) encodings.
fn parse_xonly(pubkey: &str) -> Result<XOnlyPublicKey, SdkError> {
    if let Ok(xonly) = XOnlyPublicKey::from_str(pubkey) {
        return Ok(xonly);
    }
    let pk = PublicKey::from_str(pubkey)
        .map_err(|e| SdkError::InvalidInput(format!("Invalid funding pubkey: {e}")))?;
    Ok(pk.x_only_public_key().0)
}

/// Reads what the chain has already done to `leaf_ids`, before any funding is
/// considered. Same loop as [`resolve_exit_check`], over the scan that needs no
/// plan.
async fn resolve_exit_chain_state(
    chain: &dyn BitcoinChainService,
    tree_nodes: &HashMap<TreeNodeId, TreeNode>,
    leaf_ids: &[TreeNodeId],
    refund_addresses: &HashMap<TreeNodeId, Address>,
) -> Result<WalletExitChainState, SdkError> {
    let mut observed: Vec<Observation> = Vec::new();
    loop {
        let scan = scan_exit_chain(tree_nodes, leaf_ids, refund_addresses, &observed);
        if scan.pending.is_empty() {
            debug!(
                nodes = scan.state.nodes.len(),
                refunds = scan.state.refunds.len(),
                observations = observed.len(),
                "resolve_exit_chain_state: what the chain has already done"
            );
            return Ok(scan.state);
        }
        // Each query is answered exactly once (a failed lookup records
        // `Unavailable`), so the loop always progresses and terminates.
        for query in scan.pending {
            let result = execute_chain_query(chain, &query).await;
            observed.push(Observation { query, result });
        }
    }
}

/// Leaf auto-resolution lives in the wallet, so a selection only has to be
/// restated in its terms.
fn wallet_selection(
    selection: ExitLeafSelection,
) -> Result<spark_wallet::ExitLeafSelection, SdkError> {
    match selection {
        ExitLeafSelection::Auto => Ok(spark_wallet::ExitLeafSelection::Auto),
        ExitLeafSelection::Specific { leaf_ids } => {
            if leaf_ids.is_empty() {
                return Err(SdkError::InvalidInput("No leaves to exit".to_string()));
            }
            Ok(spark_wallet::ExitLeafSelection::Specific(node_ids(
                &leaf_ids,
            )?))
        }
    }
}

/// Reads back the state a caller carried over from `prepare_unilateral_exit`.
fn exit_chain_state_from_model(
    state: &ModelExitChainState,
) -> Result<WalletExitChainState, SdkError> {
    Ok(WalletExitChainState {
        nodes: state
            .confirmed_nodes
            .iter()
            .map(|node| {
                Ok(WalletConfirmedExitNode {
                    block_height: node.block_height,
                    node_id: node_id(&node.node_id)?,
                    confirmed_by: match node.confirmed_by {
                        ExitNodeConfirmation::Cpfp => WalletExitNodeConfirmation::Cpfp,
                        ExitNodeConfirmation::Direct => WalletExitNodeConfirmation::Direct,
                    },
                })
            })
            .collect::<Result<_, SdkError>>()?,
        refunds: state
            .refunds
            .iter()
            .map(|refund| {
                let restored = match &refund.state {
                    ExitRefundState::OnChain {
                        tx_hex,
                        vout,
                        value_sat,
                        block_height,
                    } => WalletExitRefundState::OnChain {
                        block_height: *block_height,
                        tx: deserialize_hex(tx_hex).map_err(|e| {
                            SdkError::InvalidInput(format!("Invalid refund transaction: {e}"))
                        })?,
                        vout: *vout,
                        value: *value_sat,
                    },
                    ExitRefundState::Swept => WalletExitRefundState::Swept,
                };
                Ok(WalletExitRefund {
                    leaf_id: node_id(&refund.leaf_id)?,
                    state: restored,
                })
            })
            .collect::<Result<_, SdkError>>()?,
        stopped_leaves: node_ids(&state.stopped_leaf_ids)?,
        unverified_nodes: node_ids(&state.unverified_node_ids)?,
        unverifiable_confirmed_nodes: node_ids(&state.unverifiable_confirmed_node_ids)?,
    })
}

fn node_id(id: &str) -> Result<TreeNodeId, SdkError> {
    TreeNodeId::from_str(id).map_err(|e| SdkError::InvalidInput(format!("Invalid id {id}: {e}")))
}

fn node_ids(ids: &[String]) -> Result<Vec<TreeNodeId>, SdkError> {
    ids.iter().map(|id| node_id(id)).collect()
}

/// Restates the wallet's on-chain reading in the API's own types: ids as strings
/// and transactions as hex, so a caller can read what an exit has already done
/// rather than hand an opaque token back.
fn exit_chain_state_model(state: WalletExitChainState) -> ModelExitChainState {
    ModelExitChainState {
        confirmed_nodes: state
            .nodes
            .into_iter()
            .map(|node| ConfirmedExitNode {
                node_id: node.node_id.to_string(),
                confirmed_by: match node.confirmed_by {
                    WalletExitNodeConfirmation::Cpfp => ExitNodeConfirmation::Cpfp,
                    WalletExitNodeConfirmation::Direct => ExitNodeConfirmation::Direct,
                },
                block_height: node.block_height,
            })
            .collect(),
        refunds: state
            .refunds
            .into_iter()
            .map(|refund| ExitRefund {
                leaf_id: refund.leaf_id.to_string(),
                state: match refund.state {
                    WalletExitRefundState::OnChain {
                        tx,
                        vout,
                        value,
                        block_height,
                    } => ExitRefundState::OnChain {
                        tx_hex: serialize_hex(&tx),
                        vout,
                        value_sat: value,
                        block_height,
                    },
                    WalletExitRefundState::Swept => ExitRefundState::Swept,
                },
            })
            .collect(),
        stopped_leaf_ids: ids(state.stopped_leaves),
        unverified_node_ids: ids(state.unverified_nodes),
        unverifiable_confirmed_node_ids: ids(state.unverifiable_confirmed_nodes),
    }
}

fn ids(ids: Vec<TreeNodeId>) -> Vec<String> {
    ids.into_iter().map(|id| id.to_string()).collect()
}

/// Fills in the status of every transaction that is neither on-chain nor
/// unreadable: whether it can go out now, or what it is waiting on. Derived from
/// the whole list, so it is resolved once the list is complete rather than as
/// each entry is built.
///
/// A relative timelock counts from the height of the input being spent, so
/// maturity needs that height and the chain tip. Both are read here rather than
/// fetched again per transaction. A height that cannot be read leaves the
/// transaction waiting rather than ready, the direction that never sends a
/// transaction the mempool would reject.
async fn resolve_statuses(
    chain: &dyn BitcoinChainService,
    transactions: &mut [UnilateralExitTransaction],
) -> Result<(), SdkError> {
    let confirmed: HashSet<&str> = transactions
        .iter()
        .filter(|tx| matches!(tx.status, ExitTransactionStatus::Confirmed { .. }))
        .map(|tx| tx.txid.as_str())
        .collect();
    let met: Vec<bool> = transactions
        .iter()
        .map(|tx| {
            tx.depends_on
                .iter()
                .all(|dep| confirmed.contains(dep.as_str()))
        })
        .collect();

    // Seeded from the list, which already carries the height of everything the
    // exit walk confirmed, so the chain is only asked about inputs from outside
    // it: the ancestor a resumed exit starts from.
    let mut heights: HashMap<Txid, Option<u32>> = transactions
        .iter()
        .filter_map(|tx| match tx.status {
            ExitTransactionStatus::Confirmed {
                block_height: Some(height),
            } => Some((Txid::from_str(&tx.txid).ok()?, Some(height))),
            _ => None,
        })
        .collect();
    let mut tip: Option<u32> = None;

    let mut resolved = Vec::with_capacity(transactions.len());
    for (tx, met) in transactions.iter().zip(&met) {
        // On-chain, or its own on-chain state unknown: neither leaves anything
        // to wait for.
        if matches!(
            tx.status,
            ExitTransactionStatus::Confirmed { .. } | ExitTransactionStatus::Unverified
        ) {
            resolved.push(tx.status);
            continue;
        }
        if !met {
            resolved.push(ExitTransactionStatus::WaitingForDependencies);
            continue;
        }
        if tx.csv_timelock_blocks.is_none() {
            resolved.push(ExitTransactionStatus::Ready);
            continue;
        }
        let decoded = deserialize_hex::<Transaction>(&tx.tx_hex)
            .map_err(|e| SdkError::InvalidInput(format!("Invalid transaction: {e}")))?;
        let Some(spendable_at) = spendable_at_height(chain, &decoded, &mut heights).await else {
            resolved.push(ExitTransactionStatus::WaitingForTimelock {
                spendable_at_height: None,
            });
            continue;
        };
        if tip.is_none() {
            tip = chain.tip_height().await.ok();
        }
        // A transaction is accepted while it would be valid in the next block.
        let matured = tip.is_some_and(|tip| tip.saturating_add(1) >= spendable_at);
        resolved.push(if matured {
            ExitTransactionStatus::Ready
        } else {
            ExitTransactionStatus::WaitingForTimelock {
                spendable_at_height: Some(spendable_at),
            }
        });
    }

    for (tx, status) in transactions.iter_mut().zip(resolved) {
        tx.status = status;
    }
    Ok(())
}

/// The status of one kept transaction after a chain read.
///
/// - The chain has it in a block: `Confirmed`, at the height the read reported,
///   or at the height already held when the read settled it along the spend
///   chain instead of asking about it.
/// - The chain was asked and reported it is not in a block: reset to a
///   placeholder `resolve_statuses` replaces, discarding a confirmation a reorg
///   has undone.
/// - Anything else: left as it is. `resolve_statuses` recomputes every status
///   except `Confirmed` and `Unverified`, and neither of those may be dropped on
///   a read that did not contradict it.
fn status_after_check(
    current: ExitTransactionStatus,
    check: &ExitCheck,
    txid: &Txid,
) -> ExitTransactionStatus {
    let held_height = match current {
        ExitTransactionStatus::Confirmed { block_height } => block_height,
        _ => None,
    };
    match (check.confirmed.get(txid), current) {
        (Some(block_height), _) => ExitTransactionStatus::Confirmed {
            block_height: block_height.or(held_height),
        },
        (None, ExitTransactionStatus::Confirmed { .. }) if check.not_confirmed.contains(txid) => {
            ExitTransactionStatus::WaitingForDependencies
        }
        (None, _) => current,
    }
}

/// The first block height that can include `tx`, given the relative timelocks on
/// its inputs. `None` when an input's confirmation height cannot be established,
/// which leaves maturity unknown.
async fn spendable_at_height(
    chain: &dyn BitcoinChainService,
    tx: &Transaction,
    heights: &mut HashMap<Txid, Option<u32>>,
) -> Option<u32> {
    let mut spendable_at = None;
    for input in &tx.input {
        let blocks = match input.sequence.to_relative_lock_time() {
            Some(bitcoin::relative::LockTime::Blocks(blocks)) => u32::from(blocks.value()),
            _ => continue,
        };
        if blocks == 0 {
            continue;
        }
        let funded_by = input.previous_output.txid;
        if heights.get(&funded_by).is_none() {
            let height = match chain.get_transaction_status(funded_by.to_string()).await {
                Ok(status) if status.confirmed => status.block_height,
                _ => None,
            };
            heights.insert(funded_by, height);
        }
        let known = heights.get(&funded_by).copied().flatten();
        // One unreadable input is enough to leave the whole transaction unknown:
        // it may be the one that matures last.
        let height = known?;
        spendable_at = Some(spendable_at.unwrap_or(0).max(height.saturating_add(blocks)));
    }
    spendable_at
}

/// Decodes one kept transaction into what the check reads.
fn exit_check_input(tx: &UnilateralExitTransaction) -> Result<ExitCheckInput, SdkError> {
    let decode = |hex: &str| {
        deserialize_hex::<Transaction>(hex)
            .map_err(|e| SdkError::InvalidInput(format!("Invalid transaction: {e}")))
    };
    Ok(ExitCheckInput {
        tx: decode(&tx.tx_hex)?,
        cpfp: tx.cpfp_tx_hex.as_deref().map(decode).transpose()?,
        confirmed: matches!(tx.status, ExitTransactionStatus::Confirmed { .. }),
    })
}

/// Drives [`check_exit_chain`] to completion.
async fn resolve_exit_check(
    chain: &dyn BitcoinChainService,
    inputs: &[ExitCheckInput],
) -> Result<ExitCheck, SdkError> {
    let mut observed: Vec<Observation> = Vec::new();
    loop {
        let check = check_exit_chain(inputs, &observed);
        if check.pending.is_empty() {
            debug!(
                confirmed = check.confirmed.len(),
                diverged = check.diverged,
                observations = observed.len(),
                "resolve_exit_check: read back"
            );
            return Ok(check);
        }
        // Each query is answered exactly once (a failed lookup records
        // `Unavailable`), so the loop always progresses and terminates.
        for query in check.pending {
            let result = execute_chain_query(chain, &query).await;
            observed.push(Observation { query, result });
        }
    }
}

/// Follows the supplied funding to what it is worth now, driving
/// [`scan_funding`] to completion. The only chain reading a build does: the tree
/// was read while preparing.
async fn resolve_funding(
    chain: &dyn BitcoinChainService,
    supplied: Vec<CpfpInput>,
) -> Result<Vec<CpfpInput>, SdkError> {
    let mut observed: Vec<Observation> = Vec::new();
    loop {
        let scan = scan_funding(&supplied, &observed);
        if scan.pending.is_empty() {
            debug!(
                supplied = supplied.len(),
                resolved = scan.inputs.len(),
                "resolve_funding: what the supplied funding is worth now"
            );
            return Ok(scan.inputs);
        }
        // Each query is answered exactly once (a failed lookup records
        // `Unavailable`), so the loop always progresses and terminates.
        for query in scan.pending {
            let result = execute_chain_query(chain, &query).await;
            observed.push(Observation { query, result });
        }
    }
}

/// Performs one [`ChainQuery`], translating this crate's chain types into the
/// wallet's `bitcoin`-only [`ChainResult`]. A failed lookup becomes
/// [`ChainResult::Unavailable`] so the wallet flags the affected tx as unverified
/// rather than treating it as confirmed or absent.
async fn execute_chain_query(chain: &dyn BitcoinChainService, query: &ChainQuery) -> ChainResult {
    match query {
        ChainQuery::TxConfirmed(txid) => match chain.get_transaction_status(txid.to_string()).await
        {
            Ok(status) => ChainResult::Confirmed {
                confirmed: status.confirmed,
                block_height: status.block_height,
            },
            Err(e) => {
                warn!(%txid, error = %e, "chain lookup failed: transaction status");
                ChainResult::Unavailable
            }
        },
        ChainQuery::Outspend(outpoint) => {
            match chain
                .get_outspend(outpoint.txid.to_string(), outpoint.vout)
                .await
            {
                Ok(Outspend::Spent { txid, status, .. }) => match Txid::from_str(&txid) {
                    Ok(spender_txid) => {
                        trace!(%outpoint, spender = %spender_txid, confirmed = status.confirmed, "chain: outpoint spent");
                        ChainResult::Spend(Some(SpendInfo {
                            spender_txid,
                            confirmed: status.confirmed,
                            block_height: status.block_height,
                        }))
                    }
                    Err(e) => {
                        warn!("outspend of {outpoint} has an unparsable spender txid {txid}: {e}");
                        ChainResult::Unavailable
                    }
                },
                Ok(Outspend::Unspent) => {
                    trace!(%outpoint, "chain: outpoint unspent");
                    ChainResult::Spend(None)
                }
                Err(e) => {
                    warn!("get_outspend for {outpoint} failed: {e}");
                    ChainResult::Unavailable
                }
            }
        }
        ChainQuery::Transaction(txid) => match chain.get_transaction_hex(txid.to_string()).await {
            Ok(hex) => match deserialize_hex::<Transaction>(&hex) {
                Ok(tx) => {
                    trace!(%txid, outputs = tx.output.len(), "chain: transaction fetched");
                    ChainResult::Transaction(tx)
                }
                Err(e) => {
                    warn!("failed to decode transaction {txid}: {e}");
                    ChainResult::Unavailable
                }
            },
            Err(e) => {
                warn!("get_transaction_hex for {txid} failed: {e}");
                ChainResult::Unavailable
            }
        },
        ChainQuery::RefundAddress { leaf_id, address } => {
            match chain.get_address_txos(address.to_string()).await {
                Ok(txos) => {
                    let txos: Vec<AddressUtxo> = txos
                        .into_iter()
                        .filter_map(|u| match Txid::from_str(&u.txid) {
                            Ok(txid) => Some(AddressUtxo {
                                txid,
                                vout: u.vout,
                                value: u.value,
                                confirmed: u.status.confirmed,
                                block_height: u.status.block_height,
                            }),
                            Err(e) => {
                                warn!("skipping refund txo {} for leaf {leaf_id}: {e}", u.txid);
                                None
                            }
                        })
                        .collect();
                    trace!(
                        %leaf_id,
                        txos = txos.len(),
                        confirmed = txos.iter().filter(|u| u.confirmed).count(),
                        "chain: refund address scanned"
                    );
                    ChainResult::AddressUtxos(txos)
                }
                Err(e) => {
                    warn!("get_address_txos for leaf {leaf_id} failed: {e}");
                    ChainResult::Unavailable
                }
            }
        }
    }
}

/// The status a built transaction starts at. What an unconfirmed one is waiting
/// for takes the whole list to work out, so [`resolve_statuses`] replaces this.
fn initial_status(status: ExitTxStatus) -> ExitTransactionStatus {
    match status {
        ExitTxStatus::Confirmed { block_height } => {
            ExitTransactionStatus::Confirmed { block_height }
        }
        ExitTxStatus::Unconfirmed => ExitTransactionStatus::WaitingForDependencies,
        ExitTxStatus::Unverified => ExitTransactionStatus::Unverified,
    }
}

/// The sweep's starting status, derived from the refunds it spends. A verified
/// refund is spent-and-dropped once its sweep confirms (the exit then returns
/// with no sweep), so a freshly-returned sweep over verified refunds is never
/// yet on-chain. An unverified refund (its chain lookup failed) could already be
/// on-chain and swept without us knowing, so the sweep is `Unverified`.
fn sweep_initial_status(build: &UnilateralExitBuild) -> ExitTransactionStatus {
    let any_refund_unverified = build
        .branches
        .iter()
        .flat_map(|b| b.txs.iter())
        .any(|t| t.kind == ExitTxKind::Refund && t.status == ExitTxStatus::Unverified);
    if any_refund_unverified {
        ExitTransactionStatus::Unverified
    } else {
        ExitTransactionStatus::WaitingForDependencies
    }
}

fn empty_exit_response() -> UnilateralExitResponse {
    UnilateralExitResponse {
        recoverable_value_sat: 0,
        total_fee_sat: 0,
        cpfp_fee_sat: 0,
        fanout_fee_sat: 0,
        sweep_fee_sat: 0,
        leaves: Vec::new(),
        transactions: Vec::new(),
        funding_inputs: Vec::new(),
    }
}

/// Signs a PSBT via the external `CpfpSigner`, returning the tx as hex.
/// Ephemeral anchor inputs are finalized here (`OP_TRUE`, no signature).
async fn sign_psbt_via(
    mut psbt: bitcoin::Psbt,
    signer: &dyn CpfpSigner,
) -> Result<String, SdkError> {
    for input in &mut psbt.inputs {
        if let Some(txo) = &input.witness_utxo
            && is_ephemeral_anchor_output(txo)
        {
            input.final_script_witness = Some(bitcoin::Witness::new());
        }
    }
    let out_bytes = signer
        .sign_psbt(psbt.serialize())
        .await
        .map_err(|e| SdkError::Signer(format!("CPFP signer error: {e}")))?;
    let out_psbt = bitcoin::Psbt::deserialize(&out_bytes)
        .map_err(|e| SdkError::Generic(format!("Failed to deserialize signed PSBT: {e}")))?;
    ensure_all_inputs_finalized(&out_psbt)?;
    Ok(serialize_hex(&out_psbt.extract_tx_unchecked_fee_rate()))
}

/// Finalizes the sweep. Refund inputs are already signed by spark-wallet, so the
/// external signer is only invoked when CPFP-change inputs still need it.
async fn finalize_sweep(psbt: bitcoin::Psbt, signer: &dyn CpfpSigner) -> Result<String, SdkError> {
    let needs_signer = psbt
        .inputs
        .iter()
        .any(|input| input.final_script_witness.is_none());
    let psbt = if needs_signer {
        let out_bytes = signer
            .sign_psbt(psbt.serialize())
            .await
            .map_err(|e| SdkError::Signer(format!("Sweep signer error: {e}")))?;
        bitcoin::Psbt::deserialize(&out_bytes).map_err(|e| {
            SdkError::Generic(format!("Failed to deserialize signed sweep PSBT: {e}"))
        })?
    } else {
        psbt
    };
    ensure_all_inputs_finalized(&psbt)?;
    Ok(serialize_hex(&psbt.extract_tx_unchecked_fee_rate()))
}

/// Rejects a PSBT with any input the signer left unfinalized (neither a witness
/// nor a scriptSig), so a missing signature fails here instead of at broadcast.
fn ensure_all_inputs_finalized(psbt: &bitcoin::Psbt) -> Result<(), SdkError> {
    if let Some(index) = psbt
        .inputs
        .iter()
        .position(|input| input.final_script_witness.is_none() && input.final_script_sig.is_none())
    {
        return Err(SdkError::Signer(format!(
            "PSBT input {index} was not signed"
        )));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::SignerError;
    use bitcoin::hashes::Hash;
    use spark_wallet::{ExitBranch, ExitTx};

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

    fn refund_tx(status: ExitTxStatus) -> ExitTx {
        ExitTx {
            kind: ExitTxKind::Refund,
            node_id: None,
            txid: Txid::from_byte_array([3; 32]),
            base_tx: Transaction {
                version: bitcoin::transaction::Version::TWO,
                lock_time: bitcoin::absolute::LockTime::ZERO,
                input: vec![],
                output: vec![],
            },
            to_sign: None,
            csv_timelock_blocks: None,
            depends_on: vec![],
            status,
        }
    }

    fn build_with_refund(status: ExitTxStatus) -> UnilateralExitBuild {
        UnilateralExitBuild {
            fan_out: None,
            branches: vec![ExitBranch {
                leaf_id: TreeNodeId::from_str("leaf").unwrap(),
                txs: vec![refund_tx(status)],
            }],
            refund_outputs: vec![],
            cpfp_change_inputs: vec![],
            recoverable_value_sat: 0,
            cpfp_fee_sat: 0,
            fanout_fee_sat: 0,
        }
    }

    #[test]
    fn a_sweep_over_verified_refunds_starts_out_waiting_on_them() {
        assert_eq!(
            sweep_initial_status(&build_with_refund(ExitTxStatus::Unconfirmed)),
            ExitTransactionStatus::WaitingForDependencies
        );
    }

    #[test]
    fn a_sweep_over_an_unverified_refund_is_unverified() {
        assert_eq!(
            sweep_initial_status(&build_with_refund(ExitTxStatus::Unverified)),
            ExitTransactionStatus::Unverified
        );
    }

    fn unsigned_two_input_psbt() -> bitcoin::Psbt {
        let tx = Transaction {
            version: bitcoin::transaction::Version::TWO,
            lock_time: bitcoin::absolute::LockTime::ZERO,
            input: vec![
                bitcoin::TxIn {
                    previous_output: OutPoint {
                        txid: Txid::from_byte_array([1; 32]),
                        vout: 0,
                    },
                    ..Default::default()
                },
                bitcoin::TxIn {
                    previous_output: OutPoint {
                        txid: Txid::from_byte_array([2; 32]),
                        vout: 0,
                    },
                    ..Default::default()
                },
            ],
            output: vec![TxOut {
                value: Amount::from_sat(1_000),
                script_pubkey: ScriptBuf::new(),
            }],
        };
        let mut psbt = bitcoin::Psbt::from_unsigned_tx(tx).unwrap();
        for input in &mut psbt.inputs {
            input.witness_utxo = Some(TxOut {
                value: Amount::from_sat(2_000),
                script_pubkey: ScriptBuf::new(),
            });
        }
        psbt
    }

    fn finalize_input(input: &mut bitcoin::psbt::Input) {
        let mut witness = bitcoin::Witness::new();
        witness.push([0x01u8]);
        input.final_script_witness = Some(witness);
    }

    /// A `CpfpSigner` that finalizes only the first `finalize` inputs.
    struct PartialSigner {
        finalize: usize,
    }

    #[macros::async_trait]
    impl CpfpSigner for PartialSigner {
        async fn sign_psbt(&self, psbt_bytes: Vec<u8>) -> Result<Vec<u8>, SignerError> {
            let mut psbt = bitcoin::Psbt::deserialize(&psbt_bytes).unwrap();
            for input in psbt.inputs.iter_mut().take(self.finalize) {
                finalize_input(input);
            }
            Ok(psbt.serialize())
        }
    }

    #[test]
    fn ensure_all_inputs_finalized_rejects_unsigned() {
        assert!(ensure_all_inputs_finalized(&unsigned_two_input_psbt()).is_err());
    }

    #[test]
    fn ensure_all_inputs_finalized_accepts_finalized() {
        let mut psbt = unsigned_two_input_psbt();
        psbt.inputs.iter_mut().for_each(finalize_input);
        assert!(ensure_all_inputs_finalized(&psbt).is_ok());
    }

    #[macros::async_test_all]
    async fn sign_psbt_via_errors_when_an_input_is_left_unsigned() {
        let result = sign_psbt_via(unsigned_two_input_psbt(), &PartialSigner { finalize: 1 }).await;
        assert!(matches!(result, Err(SdkError::Signer(_))));
    }

    #[macros::async_test_all]
    async fn sign_psbt_via_succeeds_when_every_input_is_signed() {
        let result = sign_psbt_via(unsigned_two_input_psbt(), &PartialSigner { finalize: 2 }).await;
        assert!(result.is_ok());
    }

    /// A chain that knows one transaction's height and one tip, and refuses
    /// everything else, so a test says exactly what the resolver was told.
    struct StubChain {
        tip: Option<u32>,
        heights: HashMap<String, u32>,
    }

    #[macros::async_trait]
    impl BitcoinChainService for StubChain {
        async fn get_address_utxos(
            &self,
            _address: String,
        ) -> Result<Vec<crate::chain::Utxo>, crate::chain::ChainServiceError> {
            unreachable!()
        }
        async fn get_address_txos(
            &self,
            _address: String,
        ) -> Result<Vec<crate::chain::Utxo>, crate::chain::ChainServiceError> {
            unreachable!()
        }
        async fn get_transaction_status(
            &self,
            txid: String,
        ) -> Result<crate::chain::TxStatus, crate::chain::ChainServiceError> {
            match self.heights.get(&txid) {
                Some(height) => Ok(crate::chain::TxStatus {
                    confirmed: true,
                    block_height: Some(*height),
                    block_time: None,
                }),
                None => Err(crate::chain::ChainServiceError::Generic("unknown".into())),
            }
        }
        async fn tip_height(&self) -> Result<u32, crate::chain::ChainServiceError> {
            self.tip
                .ok_or_else(|| crate::chain::ChainServiceError::Generic("no tip".into()))
        }
        async fn get_transaction_hex(
            &self,
            _txid: String,
        ) -> Result<String, crate::chain::ChainServiceError> {
            unreachable!()
        }
        async fn get_outspend(
            &self,
            _txid: String,
            _vout: u32,
        ) -> Result<Outspend, crate::chain::ChainServiceError> {
            unreachable!()
        }
        async fn broadcast_transaction(
            &self,
            _tx: String,
        ) -> Result<(), crate::chain::ChainServiceError> {
            unreachable!()
        }
        async fn recommended_fees(
            &self,
        ) -> Result<crate::chain::RecommendedFees, crate::chain::ChainServiceError> {
            unreachable!()
        }
    }

    /// A transaction spending `parent` under a relative timelock of `csv` blocks.
    fn timelocked_tx(parent: Txid, csv: u32) -> Transaction {
        Transaction {
            version: bitcoin::transaction::Version::TWO,
            lock_time: bitcoin::absolute::LockTime::ZERO,
            input: vec![bitcoin::TxIn {
                previous_output: OutPoint {
                    txid: parent,
                    vout: 0,
                },
                sequence: bitcoin::Sequence::from_height(u16::try_from(csv).unwrap()),
                ..Default::default()
            }],
            output: vec![TxOut {
                value: Amount::from_sat(1_000),
                script_pubkey: ScriptBuf::new(),
            }],
        }
    }

    fn model_tx(
        tx: &Transaction,
        csv: Option<u32>,
        depends_on: Vec<String>,
        status: ExitTransactionStatus,
    ) -> UnilateralExitTransaction {
        UnilateralExitTransaction {
            kind: UnilateralExitTxKind::Node,
            node_id: None,
            txid: tx.compute_txid().to_string(),
            tx_hex: serialize_hex(tx),
            cpfp_tx_hex: None,
            csv_timelock_blocks: csv,
            depends_on,
            status,
        }
    }

    fn check_of(
        confirmed: &[(Txid, Option<u32>)],
        not_confirmed: &[Txid],
    ) -> spark_wallet::ExitCheck {
        spark_wallet::ExitCheck {
            confirmed: confirmed.iter().copied().collect(),
            diverged: false,
            not_confirmed: not_confirmed.iter().copied().collect(),
            pending: Vec::new(),
        }
    }

    /// The check settles an ancestor along the spend chain without asking, so it
    /// reports no height for it. Overwriting with that loses the height the
    /// caller is holding, which is what a child's timelock counts from.
    #[macros::async_test_all]
    async fn a_settled_ancestor_keeps_the_height_the_caller_already_had() {
        let txid = Txid::from_byte_array([4; 32]);
        let held = ExitTransactionStatus::Confirmed {
            block_height: Some(880_000),
        };

        assert_eq!(
            status_after_check(held, &check_of(&[(txid, None)], &[]), &txid),
            held,
            "a height-less confirmation does not erase the one held"
        );
        assert_eq!(
            status_after_check(held, &check_of(&[(txid, Some(880_004))], &[]), &txid),
            ExitTransactionStatus::Confirmed {
                block_height: Some(880_004)
            },
            "a height the chain did report wins"
        );
    }

    /// A transaction the chain reports as not in a block loses its stored
    /// `Confirmed`, so a reorg cannot leave the exit reporting `Done` over a
    /// transaction that is no longer there. A failed lookup leaves it alone.
    #[macros::async_test_all]
    async fn a_confirmation_the_chain_contradicts_is_dropped() {
        let txid = Txid::from_byte_array([5; 32]);
        let held = ExitTransactionStatus::Confirmed {
            block_height: Some(880_000),
        };

        assert_eq!(
            status_after_check(held, &check_of(&[], &[txid]), &txid),
            ExitTransactionStatus::WaitingForDependencies,
            "re-derived, so resolve_statuses works out where it really stands"
        );
        assert_eq!(
            status_after_check(held, &check_of(&[], &[]), &txid),
            held,
            "no answer either way leaves the caller's record alone"
        );
    }

    /// `Unverified` says the chain could not be read while the exit was built, so
    /// the SDK cannot tell whether an earlier fee-bumping child already spent the
    /// funding this transaction would use. A check reads only the kept exit, never
    /// the funding, so it can promote the status on finding the transaction in a
    /// block, but must not clear it on failing to.
    #[macros::async_test_all]
    async fn a_check_promotes_an_unverified_transaction_but_never_clears_it() {
        let txid = Txid::from_byte_array([6; 32]);

        assert_eq!(
            status_after_check(
                ExitTransactionStatus::Unverified,
                &check_of(&[], &[]),
                &txid
            ),
            ExitTransactionStatus::Unverified,
            "not found is not evidence that broadcasting it is safe"
        );
        assert_eq!(
            status_after_check(
                ExitTransactionStatus::Unverified,
                &check_of(&[(txid, Some(880_000))], &[]),
                &txid,
            ),
            ExitTransactionStatus::Confirmed {
                block_height: Some(880_000)
            },
            "found in a block settles it outright"
        );
    }

    /// `resolve_statuses` recomputes everything except `Confirmed` and
    /// `Unverified`, so a check that learned nothing about a transaction can leave
    /// its status alone and still have it come out up to date.
    #[macros::async_test_all]
    async fn a_check_that_learned_nothing_leaves_a_recomputable_status_alone() {
        let txid = Txid::from_byte_array([7; 32]);
        for status in [
            ExitTransactionStatus::Ready,
            ExitTransactionStatus::WaitingForDependencies,
            ExitTransactionStatus::WaitingForTimelock {
                spendable_at_height: Some(880_010),
            },
        ] {
            assert_eq!(
                status_after_check(status, &check_of(&[], &[]), &txid),
                status
            );
        }
    }

    /// A parent at height 100 with a 6 block timelock is spendable from block
    /// 106, so a tip of 105 is enough: the child would be valid in block 106.
    #[macros::async_test_all]
    async fn a_matured_timelock_is_ready_one_block_early() {
        let parent = model_tx(
            &timelocked_tx(Txid::from_byte_array([9; 32]), 0),
            None,
            vec![],
            ExitTransactionStatus::Confirmed {
                block_height: Some(100),
            },
        );
        let parent_txid = Txid::from_str(&parent.txid).unwrap();
        let child = model_tx(
            &timelocked_tx(parent_txid, 6),
            Some(6),
            vec![parent.txid.clone()],
            ExitTransactionStatus::WaitingForDependencies,
        );
        let chain = StubChain {
            tip: Some(105),
            heights: HashMap::new(),
        };

        let mut txs = vec![parent, child];
        resolve_statuses(&chain, &mut txs).await.unwrap();

        assert_eq!(txs[1].status, ExitTransactionStatus::Ready);
    }

    #[macros::async_test_all]
    async fn an_unmatured_timelock_reports_the_block_it_waits_for() {
        let parent = model_tx(
            &timelocked_tx(Txid::from_byte_array([9; 32]), 0),
            None,
            vec![],
            ExitTransactionStatus::Confirmed {
                block_height: Some(100),
            },
        );
        let parent_txid = Txid::from_str(&parent.txid).unwrap();
        let child = model_tx(
            &timelocked_tx(parent_txid, 6),
            Some(6),
            vec![parent.txid.clone()],
            ExitTransactionStatus::WaitingForDependencies,
        );
        let chain = StubChain {
            tip: Some(104),
            heights: HashMap::new(),
        };

        let mut txs = vec![parent, child];
        resolve_statuses(&chain, &mut txs).await.unwrap();

        assert_eq!(
            txs[1].status,
            ExitTransactionStatus::WaitingForTimelock {
                spendable_at_height: Some(106)
            }
        );
    }

    /// An unconfirmed parent holds the child at its dependencies: the timelock
    /// has no height to count from yet.
    #[macros::async_test_all]
    async fn an_unconfirmed_dependency_outranks_the_timelock() {
        let parent = model_tx(
            &timelocked_tx(Txid::from_byte_array([9; 32]), 0),
            None,
            vec![],
            ExitTransactionStatus::WaitingForDependencies,
        );
        let parent_txid = Txid::from_str(&parent.txid).unwrap();
        let child = model_tx(
            &timelocked_tx(parent_txid, 6),
            Some(6),
            vec![parent.txid.clone()],
            ExitTransactionStatus::WaitingForDependencies,
        );
        let chain = StubChain {
            tip: Some(999),
            heights: HashMap::new(),
        };

        let mut txs = vec![parent, child];
        resolve_statuses(&chain, &mut txs).await.unwrap();

        assert_eq!(txs[1].status, ExitTransactionStatus::WaitingForDependencies);
    }

    /// The exit a resume builds starts below the node it resumes from, so the
    /// height its first timelock counts from is not in the list. It comes from
    /// the chain instead.
    #[macros::async_test_all]
    async fn a_height_outside_the_list_is_read_from_the_chain() {
        let ancestor = Txid::from_byte_array([7; 32]);
        let tx = timelocked_tx(ancestor, 10);
        let chain = StubChain {
            tip: Some(1_000),
            heights: HashMap::from([(ancestor.to_string(), 500)]),
        };

        let mut txs = vec![model_tx(
            &tx,
            Some(10),
            vec![],
            ExitTransactionStatus::WaitingForDependencies,
        )];
        resolve_statuses(&chain, &mut txs).await.unwrap();

        assert_eq!(txs[0].status, ExitTransactionStatus::Ready);
    }

    /// An unreadable chain leaves the transaction waiting rather than ready:
    /// the direction that never sends what the mempool would reject.
    #[macros::async_test_all]
    async fn an_unreadable_height_leaves_the_timelock_unknown() {
        let tx = timelocked_tx(Txid::from_byte_array([7; 32]), 10);
        let chain = StubChain {
            tip: Some(1_000),
            heights: HashMap::new(),
        };

        let mut txs = vec![model_tx(
            &tx,
            Some(10),
            vec![],
            ExitTransactionStatus::WaitingForDependencies,
        )];
        resolve_statuses(&chain, &mut txs).await.unwrap();

        assert_eq!(
            txs[0].status,
            ExitTransactionStatus::WaitingForTimelock {
                spendable_at_height: None
            }
        );
    }
}