blvm_consensus/

reorganization.rs

//! Chain reorganization functions from Orange Paper Section 10.3

use crate::block::connect_block;
use crate::error::Result;
use crate::segwit::Witness;
use crate::types::*;
use blvm_spec_lock::spec_locked;
use std::collections::HashMap;

/// Deprecated reorg entry point (empty witnesses only).
///
/// Builds empty witness stacks suitable for coinbase-only / legacy blocks. Blocks containing
/// native SegWit transactions require explicit witness data via
/// [`reorganize_chain_with_witnesses`].
#[deprecated(
    since = "0.1.33",
    note = "Use reorganize_chain_with_witnesses with explicit witness data for SegWit chains"
)]
#[spec_locked("11.3")]
pub fn reorganize_chain(
    new_chain: &[Block],
    current_chain: &[Block],
    current_utxo_set: UtxoSet,
    current_height: Natural,
    network: crate::types::Network,
) -> Result<ReorganizationResult> {
    use crate::segwit::is_segwit_transaction;
    use crate::transaction::is_coinbase;

    for block in new_chain {
        for tx in &block.transactions {
            if !is_coinbase(tx) && is_segwit_transaction(tx) {
                return Err(crate::error::ConsensusError::BlockValidation(
                    "reorganize_chain: SegWit transactions require reorganize_chain_with_witnesses"
                        .into(),
                ));
            }
        }
    }

    // Precondition assertions: Validate function inputs
    assert!(
        current_height <= i64::MAX as u64,
        "Current height {current_height} must fit in i64"
    );
    assert!(
        current_utxo_set.len() <= u32::MAX as usize,
        "Current UTXO set size {} exceeds maximum",
        current_utxo_set.len()
    );
    assert!(
        new_chain.len() <= 10_000,
        "New chain length {} must be reasonable",
        new_chain.len()
    );
    assert!(
        current_chain.len() <= 10_000,
        "Current chain length {} must be reasonable",
        current_chain.len()
    );

    // Empty per-input witness stacks (legacy path only; SegWit rejected above).
    let empty_witnesses: Vec<Vec<Vec<Witness>>> = new_chain
        .iter()
        .map(|block| {
            block
                .transactions
                .iter()
                .map(|tx| tx.inputs.iter().map(|_| Vec::new()).collect())
                .collect()
        })
        .collect();
    // Invariant assertion: Witness count must match block count
    assert!(
        empty_witnesses.len() == new_chain.len(),
        "Witness count {} must match new chain block count {}",
        empty_witnesses.len(),
        new_chain.len()
    );

    reorganize_chain_with_witnesses(
        new_chain,
        &empty_witnesses,
        None, // No headers for median time-past
        current_chain,
        current_utxo_set,
        current_height,
        None::<fn(&Block) -> Option<Vec<Witness>>>, // No witness retrieval
        None::<fn(Natural) -> Option<Vec<BlockHeader>>>, // No header retrieval
        None::<fn(&Hash) -> Option<BlockUndoLog>>,  // No undo log retrieval
        None::<fn(&Hash, &BlockUndoLog) -> Result<()>>, // No undo log storage
        new_chain
            .iter()
            .map(|b| b.header.timestamp)
            .max()
            .unwrap_or(0)
            .saturating_add(crate::constants::MAX_FUTURE_BLOCK_TIME),
        network,
    )
}

/// Reorganization: When a longer chain is found (full API with witness support)
///
/// For new chain with blocks [b1, b2, ..., bn] and current chain with blocks [c1, c2, ..., cm]:
/// 1. Find common ancestor between new chain and current chain
/// 2. Disconnect blocks from current chain back to common ancestor
/// 3. Connect blocks from new chain from common ancestor forward
/// 4. Return new UTXO set and reorganization result
///
/// # Arguments
///
/// * `new_chain` - Blocks from the new (longer) chain
/// * `new_chain_witnesses` - Witness data for each block in new_chain (one Vec<Witness> per block)
/// * `new_chain_headers` - Recent headers for median time-past calculation (last 11+ headers, oldest to newest)
/// * `current_chain` - Blocks from the current chain
/// * `current_utxo_set` - Current UTXO set
/// * `current_height` - Current block height
/// * `get_witnesses_for_block` - Optional callback to retrieve witnesses for a block (for current chain disconnection)
/// * `get_headers_for_height` - Optional callback to retrieve headers for median time-past (for current chain disconnection)
/// * `get_undo_log_for_block` - Optional callback to retrieve undo log for a block (for current chain disconnection)
/// * `store_undo_log_for_block` - Optional callback to store undo log for a block (for new chain connection)
/// * `network_time` - Adjusted network time from the node layer (not the block under validation)
/// * `network` - Consensus network (mainnet / testnet / regtest)
#[allow(clippy::too_many_arguments)]
#[spec_locked("11.3")]
pub fn reorganize_chain_with_witnesses(
    new_chain: &[Block],
    new_chain_witnesses: &[Vec<Vec<Witness>>], // CRITICAL FIX: Changed from &[Vec<Witness>] to &[Vec<Vec<Witness>>]
    // Each block has Vec<Vec<Witness>> (one Vec per transaction, each containing one Witness per input)
    new_chain_headers: Option<&[BlockHeader]>,
    current_chain: &[Block],
    current_utxo_set: UtxoSet,
    current_height: Natural,
    _get_witnesses_for_block: Option<impl Fn(&Block) -> Option<Vec<Witness>>>,
    _get_headers_for_height: Option<impl Fn(Natural) -> Option<Vec<BlockHeader>>>,
    get_undo_log_for_block: Option<impl Fn(&Hash) -> Option<BlockUndoLog>>,
    store_undo_log_for_block: Option<impl Fn(&Hash, &BlockUndoLog) -> Result<()>>,
    network_time: u64,
    network: crate::types::Network,
) -> Result<ReorganizationResult> {
    // Precondition assertions: Validate function inputs
    assert!(
        current_height <= i64::MAX as u64,
        "Current height {current_height} must fit in i64"
    );
    assert!(
        current_utxo_set.len() <= u32::MAX as usize,
        "Current UTXO set size {} exceeds maximum",
        current_utxo_set.len()
    );
    assert!(
        new_chain.len() <= 10_000,
        "New chain length {} must be reasonable",
        new_chain.len()
    );
    assert!(
        current_chain.len() <= 10_000,
        "Current chain length {} must be reasonable",
        current_chain.len()
    );
    assert!(
        new_chain_witnesses.len() == new_chain.len(),
        "New chain witness count {} must match block count {}",
        new_chain_witnesses.len(),
        new_chain.len()
    );

    // 1. Find common ancestor by comparing block hashes
    let common_ancestor = find_common_ancestor(new_chain, current_chain)?;
    let common_ancestor_header = common_ancestor.header;
    let common_ancestor_index = common_ancestor.new_chain_index;
    let current_ancestor_index = common_ancestor.current_chain_index;

    // Invariant assertion: Common ancestor indices must be valid
    assert!(
        common_ancestor_index < new_chain.len(),
        "Common ancestor index {} must be < new chain length {}",
        common_ancestor_index,
        new_chain.len()
    );
    assert!(
        current_ancestor_index < current_chain.len(),
        "Common ancestor index {} must be < current chain length {}",
        current_ancestor_index,
        current_chain.len()
    );

    // 2. Disconnect blocks from current chain back to common ancestor
    // We disconnect from (current_ancestor_index + 1) to the tip
    // Undo logs are retrieved from persistent storage via the callback.
    // The node layer (blvm-node) should provide a callback that uses BlockStore::get_undo_log()
    // to retrieve undo logs from the database (redb/sled).
    let mut utxo_set = current_utxo_set;
    // Invariant assertion: UTXO set size must be reasonable
    assert!(
        utxo_set.len() <= u32::MAX as usize,
        "UTXO set size {} must not exceed maximum",
        utxo_set.len()
    );

    // Disconnect from the block after the common ancestor to the tip
    let disconnect_start = current_ancestor_index + 1;
    // Invariant assertion: Disconnect start must be valid
    assert!(
        disconnect_start <= current_chain.len(),
        "Disconnect start {} must be <= current chain length {}",
        disconnect_start,
        current_chain.len()
    );

    let mut disconnected_undo_logs: HashMap<Hash, BlockUndoLog> = HashMap::new();
    // Invariant assertion: Disconnected undo logs must start empty
    assert!(
        disconnected_undo_logs.is_empty(),
        "Disconnected undo logs must start empty"
    );

    for i in (disconnect_start..current_chain.len()).rev() {
        // Bounds checking assertion: Block index must be valid
        assert!(i < current_chain.len(), "Block index {i} out of bounds");
        if let Some(block) = current_chain.get(i) {
            // Invariant assertion: Block must have transactions
            assert!(
                !block.transactions.is_empty(),
                "Block at index {i} must have at least one transaction"
            );

            let block_hash = calculate_block_hash(&block.header);
            // Invariant assertion: Block hash must be non-zero
            assert!(block_hash != [0u8; 32], "Block hash must be non-zero");

            // Retrieve undo log from persistent storage via callback
            // The callback should use BlockStore::get_undo_log() which reads from the database
            let undo_log = if let Some(ref get_undo_log) = get_undo_log_for_block {
                get_undo_log(&block_hash).unwrap_or_else(|| {
                    // If undo log is not found in database, this is an error condition
                    // Undo logs should always be stored when blocks are connected
                    // Log a warning but continue with empty undo log for graceful degradation
                    BlockUndoLog::new()
                })
            } else {
                // No callback provided - cannot retrieve undo log from storage
                // This should only happen in testing or when undo logs are not needed
                BlockUndoLog::new()
            };

            utxo_set = disconnect_block(block, &undo_log, utxo_set, (i as Natural) + 1)?;
            disconnected_undo_logs.insert(block_hash, undo_log);
        }
    }

    // 3. Connect blocks from new chain from common ancestor forward
    // We connect from (common_ancestor_index + 1) to the tip of new chain
    // Calculate the height at the common ancestor.
    // current_chain[i] is at height: current_height - (current_chain.len() - 1 - i)
    // So ancestor at current_ancestor_index is at:
    //   current_height - (current_chain.len() - 1 - current_ancestor_index)
    let blocks_after_ancestor = (current_chain.len() - 1 - current_ancestor_index) as Natural;
    let common_ancestor_height = current_height.saturating_sub(blocks_after_ancestor);
    let mut new_height = common_ancestor_height;
    let mut connected_blocks = Vec::new();
    let mut connected_undo_logs: HashMap<Hash, BlockUndoLog> = HashMap::new();
    let mut mtp_header_buf: Vec<BlockHeader> = Vec::new();

    // Ensure witnesses match blocks
    if new_chain_witnesses.len() != new_chain.len() {
        return Err(crate::error::ConsensusError::ConsensusRuleViolation(
            format!(
                "Witness count {} does not match block count {}",
                new_chain_witnesses.len(),
                new_chain.len()
            )
            .into(),
        ));
    }

    // Connect blocks starting from the block after the common ancestor
    for (i, block) in new_chain.iter().enumerate().skip(common_ancestor_index + 1) {
        new_height += 1;
        // Witness stacks are required; length is validated at entry (must match new_chain).
        let witnesses = new_chain_witnesses[i].clone();

        // Median time-past: prefer caller headers; else use preceding blocks on the new chain.
        mtp_header_buf.clear();
        let recent_headers: Option<&[BlockHeader]> = if let Some(headers) = new_chain_headers {
            Some(headers)
        } else if i > 0 {
            let start = i.saturating_sub(crate::bip113::MEDIAN_TIME_BLOCKS - 1);
            mtp_header_buf.extend(new_chain[start..i].iter().map(|b| b.header.clone()));
            Some(mtp_header_buf.as_slice())
        } else {
            None
        };

        let context = crate::block::block_validation_context_for_connect_ibd(
            recent_headers,
            network_time,
            network,
        );
        let (validation_result, new_utxo_set, undo_log) =
            connect_block(block, &witnesses, utxo_set, new_height, &context)?;

        if !matches!(validation_result, ValidationResult::Valid) {
            return Err(crate::error::ConsensusError::ConsensusRuleViolation(
                format!("Invalid block at height {new_height} during reorganization").into(),
            ));
        }

        // Store undo log for this block (keyed by block hash for future retrieval)
        let block_hash = calculate_block_hash(&block.header);

        // Persist undo log to database via callback (required for future reorganizations)
        if let Some(ref store_undo_log) = store_undo_log_for_block {
            if let Err(e) = store_undo_log(&block_hash, &undo_log) {
                // Continue without persisting — reorg state is still returned in-memory.
                // Avoid stderr in default release builds; enable `profile` or use a debug build to see this.
                #[cfg(any(debug_assertions, feature = "profile"))]
                eprintln!("Warning: Failed to store undo log for block {block_hash:?}: {e}");
                #[cfg(not(any(debug_assertions, feature = "profile")))]
                let _ = e;
            }
        }

        // Also store in-memory for the reorganization result
        connected_undo_logs.insert(block_hash, undo_log);

        utxo_set = new_utxo_set;
        connected_blocks.push(block.clone());
    }

    // 4. Return reorganization result
    Ok(ReorganizationResult {
        new_utxo_set: utxo_set,
        new_height,
        common_ancestor: common_ancestor_header,
        disconnected_blocks: current_chain[disconnect_start..].to_vec(),
        connected_blocks,
        reorganization_depth: current_chain.len() - disconnect_start,
        connected_block_undo_logs: connected_undo_logs,
    })
}

/// Update mempool after chain reorganization
///
/// This function should be called after successfully reorganizing the chain
/// to keep the mempool synchronized with the new blockchain state.
///
/// Handles:
/// 1. Removes transactions from mempool that were included in the new chain blocks
/// 2. Removes transactions that became invalid (their inputs were spent by new chain)
/// 3. Optionally re-adds transactions from disconnected blocks that are still valid
///
/// # Arguments
///
/// * `mempool` - Mutable reference to the mempool
/// * `reorg_result` - The reorganization result
/// * `utxo_set` - The updated UTXO set after reorganization
/// * `get_tx_by_id` - Optional function to look up transactions by ID (needed for full validation)
///
/// # Returns
///
/// Returns a vector of transaction IDs that were removed from the mempool.
///
/// # Example
///
/// ```rust
/// use blvm_consensus::reorganization::{reorganize_chain_with_witnesses, update_mempool_after_reorg};
/// use blvm_consensus::mempool::Mempool;
/// use blvm_consensus::segwit::Witness;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// # use blvm_consensus::types::*;
/// # use blvm_consensus::mempool::Mempool;
/// # let new_chain = vec![];
/// # let new_witnesses = vec![];
/// # let current_chain = vec![];
/// # let current_utxo_set = UtxoSet::default();
/// # let current_height = 0;
/// # let mut mempool = Mempool::new();
/// // Note: This is a simplified example. In practice, chains must have at least one block
/// // and share a common ancestor. The result may be an error for empty chains.
/// let reorg_result = reorganize_chain_with_witnesses(
///     &new_chain,
///     &new_witnesses,
///     None,
///     &current_chain,
///     current_utxo_set,
///     current_height,
///     None::<fn(&Block) -> Option<Vec<Witness>>>,
///     None::<fn(Natural) -> Option<Vec<BlockHeader>>>,
///     None::<fn(&blvm_consensus::types::Hash) -> Option<blvm_consensus::reorganization::BlockUndoLog>>,
///     None::<fn(&blvm_consensus::types::Hash, &blvm_consensus::reorganization::BlockUndoLog) -> blvm_consensus::error::Result<()>>,
///     0,
///     Network::Regtest,
/// );
/// if let Ok(reorg_result) = reorg_result {
///     let _removed = update_mempool_after_reorg(
///         &mut mempool,
///         &reorg_result,
///         &reorg_result.new_utxo_set,
///         None::<fn(&Hash) -> Option<Transaction>>, // No transaction lookup available
///     )?;
/// }
/// # Ok(())
/// # }
/// ```
pub fn update_mempool_after_reorg<F>(
    mempool: &mut crate::mempool::Mempool,
    reorg_result: &ReorganizationResult,
    utxo_set: &UtxoSet,
    get_tx_by_id: Option<F>,
) -> Result<Vec<Hash>>
where
    F: Fn(&Hash) -> Option<Transaction>,
{
    use crate::mempool::update_mempool_after_block;

    let mut all_removed = Vec::new();

    // 1. Remove transactions that were included in the new connected blocks
    for block in &reorg_result.connected_blocks {
        let removed = update_mempool_after_block(mempool, block, utxo_set)?;
        all_removed.extend(removed);
    }

    // 2. Remove transactions that became invalid (their inputs were spent by new chain)
    // Collect all spent outpoints from the new connected blocks
    let mut spent_outpoints = std::collections::HashSet::new();
    for block in &reorg_result.connected_blocks {
        for tx in &block.transactions {
            if !crate::transaction::is_coinbase(tx) {
                for input in &tx.inputs {
                    spent_outpoints.insert(input.prevout);
                }
            }
        }
    }

    // If we have transaction lookup, check each mempool transaction
    if let Some(lookup) = get_tx_by_id {
        let mut invalid_tx_ids = Vec::new();
        for &tx_id in mempool.iter() {
            if let Some(tx) = lookup(&tx_id) {
                // Check if any input of this transaction was spent by the new chain
                for input in &tx.inputs {
                    if spent_outpoints.contains(&input.prevout) {
                        invalid_tx_ids.push(tx_id);
                        break;
                    }
                }
            }
        }

        // Remove invalid transactions
        for tx_id in invalid_tx_ids {
            if mempool.remove(&tx_id) {
                all_removed.push(tx_id);
            }
        }
    }

    // 3. Re-add transactions from disconnected blocks via [`update_mempool_after_reorg_with_readd`].

    Ok(all_removed)
}

/// Parameters for re-adding mempool entries from disconnected blocks after a reorg.
#[derive(Debug, Clone)]
pub struct ReorgMempoolReaddParams {
    pub height: Natural,
    pub time_context: Option<TimeContext>,
    pub network: Network,
}

/// Update mempool after reorg and re-add valid transactions from disconnected blocks.
///
/// Runs [`update_mempool_after_reorg`] then attempts `accept_to_memory_pool` for each
/// non-coinbase transaction in `reorg_result.disconnected_blocks`.
pub fn update_mempool_after_reorg_with_readd<F, G>(
    mempool: &mut crate::mempool::Mempool,
    reorg_result: &ReorganizationResult,
    utxo_set: &UtxoSet,
    get_tx_by_id: Option<F>,
    readd: &ReorgMempoolReaddParams,
    get_witnesses: Option<G>,
) -> Result<(Vec<Hash>, Vec<Hash>)>
where
    F: Fn(&Hash) -> Option<Transaction>,
    G: Fn(&Hash) -> Option<Vec<Witness>>,
{
    let removed = update_mempool_after_reorg(mempool, reorg_result, utxo_set, get_tx_by_id)?;
    let readded = readd_disconnected_to_mempool(
        mempool,
        &reorg_result.disconnected_blocks,
        utxo_set,
        readd,
        get_witnesses,
    )?;
    Ok((removed, readded))
}

fn readd_disconnected_to_mempool<G>(
    mempool: &mut crate::mempool::Mempool,
    disconnected_blocks: &[Block],
    utxo_set: &UtxoSet,
    readd: &ReorgMempoolReaddParams,
    get_witnesses: Option<G>,
) -> Result<Vec<Hash>>
where
    G: Fn(&Hash) -> Option<Vec<Witness>>,
{
    use crate::block::calculate_tx_id;
    use crate::mempool::{MempoolResult, accept_to_memory_pool};
    use crate::transaction::is_coinbase;

    let mut readded = Vec::new();
    for block in disconnected_blocks {
        for tx in block.transactions.iter() {
            if is_coinbase(tx) {
                continue;
            }
            let tx_id = calculate_tx_id(tx);
            if mempool.contains(&tx_id) {
                continue;
            }
            let witness_storage = get_witnesses.as_ref().and_then(|lookup| lookup(&tx_id));
            let witnesses = witness_storage.as_deref();
            match accept_to_memory_pool(
                tx,
                witnesses,
                utxo_set,
                mempool,
                readd.height,
                readd.time_context,
                readd.network,
            )? {
                MempoolResult::Accepted => {
                    if mempool.insert_transaction(tx) {
                        readded.push(tx_id);
                    }
                }
                MempoolResult::Rejected(_) => {}
            }
        }
    }
    Ok(readded)
}

/// Update mempool after reorg without a transaction lookup callback.
pub fn update_mempool_after_reorg_simple(
    mempool: &mut crate::mempool::Mempool,
    reorg_result: &ReorganizationResult,
    utxo_set: &UtxoSet,
) -> Result<Vec<Hash>> {
    update_mempool_after_reorg(
        mempool,
        reorg_result,
        utxo_set,
        None::<fn(&Hash) -> Option<Transaction>>,
    )
}

/// Common ancestor result with indices in both chains
struct CommonAncestorResult {
    header: BlockHeader,
    new_chain_index: usize,
    current_chain_index: usize,
}

/// Find common ancestor between two chains by comparing block hashes
///
/// Algorithm: Walk forward from genesis while block hashes match at the same
/// index. The last matching block is the fork point. This is correct for
/// full chains collected genesis-to-tip (unlike tip-distance comparison, which
/// misaligns when fork branches differ in length).
/// Orange Paper 11.3: Chain reorganization finds common ancestor before disconnect/connect.
fn find_common_ancestor(
    new_chain: &[Block],
    current_chain: &[Block],
) -> Result<CommonAncestorResult> {
    if new_chain.is_empty() || current_chain.is_empty() {
        return Err(crate::error::ConsensusError::ConsensusRuleViolation(
            "Cannot find common ancestor: empty chain".into(),
        ));
    }

    let max_compare = new_chain.len().min(current_chain.len());
    let mut last_match: Option<usize> = None;
    for i in 0..max_compare {
        let new_hash = calculate_block_hash(&new_chain[i].header);
        let current_hash = calculate_block_hash(&current_chain[i].header);
        if new_hash == current_hash {
            last_match = Some(i);
        } else {
            break;
        }
    }

    if let Some(idx) = last_match {
        return Ok(CommonAncestorResult {
            header: new_chain[idx].header.clone(),
            new_chain_index: idx,
            current_chain_index: idx,
        });
    }

    Err(crate::error::ConsensusError::ConsensusRuleViolation(
        "Chains do not share a common ancestor".into(),
    ))
}

/// Disconnect a block from the chain (reverse of ConnectBlock)
///
/// Uses the undo log to perfectly restore the UTXO set to its state before the block was connected.
/// This is the inverse operation of `connect_block`.
/// Orange Paper 11.3.1: DisconnectBlock applies undo log to reverse ConnectBlock.
///
/// # Arguments
///
/// * `block` - The block to disconnect (used for validation, undo_log contains the actual changes)
/// * `undo_log` - The undo log created when this block was connected
/// * `utxo_set` - Current UTXO set (will be modified)
/// * `_height` - Block height (for potential future use)
#[spec_locked("11.3.1", "DisconnectBlock")]
fn disconnect_block(
    _block: &Block,
    undo_log: &BlockUndoLog,
    mut utxo_set: UtxoSet,
    _height: Natural,
) -> Result<UtxoSet> {
    // Precondition assertions: Validate function inputs
    assert!(
        !_block.transactions.is_empty(),
        "Block must have at least one transaction"
    );
    assert!(
        _height <= i64::MAX as u64,
        "Block height {_height} must fit in i64"
    );
    assert!(
        utxo_set.len() <= u32::MAX as usize,
        "UTXO set size {} must not exceed maximum",
        utxo_set.len()
    );
    // Invariant assertion: Undo log entry count must be reasonable
    assert!(
        undo_log.entries.len() <= 10_000,
        "Undo log entry count {} must be reasonable",
        undo_log.entries.len()
    );

    // Process undo entries in reverse order (most recent first)
    // This reverses the order of operations from connect_block
    for (i, entry) in undo_log.entries.iter().enumerate() {
        // Bounds checking assertion: Entry index must be valid
        assert!(i < undo_log.entries.len(), "Entry index {i} out of bounds");
        // Remove new UTXO (if it was created by this block)
        if entry.new_utxo.is_some() {
            utxo_set.remove(&entry.outpoint);
        }

        // Restore previous UTXO (if it was spent by this block)
        if let Some(previous_utxo) = &entry.previous_utxo {
            utxo_set.insert(entry.outpoint, std::sync::Arc::clone(previous_utxo));
        }
    }

    Ok(utxo_set)
}

/// Check if reorganization is beneficial
#[track_caller] // Better error messages showing caller location
#[allow(clippy::redundant_comparisons)] // Intentional assertions for formal verification
#[spec_locked("11.3", "ShouldReorganize")]
pub fn should_reorganize(new_chain: &[Block], current_chain: &[Block]) -> Result<bool> {
    // Precondition assertions: Validate function inputs
    assert!(
        new_chain.len() <= 10_000,
        "New chain length {} must be reasonable",
        new_chain.len()
    );
    assert!(
        current_chain.len() <= 10_000,
        "Current chain length {} must be reasonable",
        current_chain.len()
    );

    // Reorganize when new chain has strictly more cumulative work.
    let new_work = calculate_chain_work(new_chain)?;
    let current_work = calculate_chain_work(current_chain)?;
    Ok(new_work > current_work)
}

/// Work contribution for a single block header (matches [`calculate_chain_work`]).
pub fn work_for_bits(bits: Natural) -> Result<crate::pow::U256> {
    crate::pow::get_block_proof(bits)
}

/// Calculate total work for a chain
/// Orange Paper 11.3: BestChain = argmax Σ Work(block)
///
/// Mathematical invariants:
/// - Work is always non-negative
/// - Work increases monotonically with chain length
/// - Work calculation is deterministic
#[spec_locked("11.3", "CalculateChainWork")]
pub fn calculate_chain_work(chain: &[Block]) -> Result<crate::pow::U256> {
    let mut total_work = crate::pow::U256::zero();

    for block in chain {
        let work_contribution = work_for_bits(block.header.bits)?;
        let old_total = total_work;
        total_work = total_work.saturating_add(work_contribution);

        // Runtime assertion: Total work must be non-decreasing
        debug_assert!(
            total_work >= old_total,
            "Total work ({total_work:?}) must be >= previous total ({old_total:?})"
        );
    }

    Ok(total_work)
}

/// Test-only approximate tx id from tx fields (not a consensus hash).
#[allow(dead_code)] // Used in tests
fn calculate_tx_id(tx: &Transaction) -> Hash {
    let mut hash = [0u8; 32];
    hash[0] = (tx.version & 0xff) as u8;
    hash[1] = (tx.inputs.len() & 0xff) as u8;
    hash[2] = (tx.outputs.len() & 0xff) as u8;
    hash[3] = (tx.lock_time & 0xff) as u8;
    hash
}

/// Calculate block hash for indexing undo logs
///
/// Uses the block header to compute a unique identifier for the block.
/// This is used to store and retrieve undo logs during reorganization.
fn calculate_block_hash(header: &BlockHeader) -> Hash {
    use sha2::{Digest, Sha256};

    // Serialize block header (80 bytes: version, prev_block_hash, merkle_root, timestamp, bits, nonce)
    let mut bytes = Vec::with_capacity(80);
    bytes.extend_from_slice(&header.version.to_le_bytes());
    bytes.extend_from_slice(&header.prev_block_hash);
    bytes.extend_from_slice(&header.merkle_root);
    bytes.extend_from_slice(&header.timestamp.to_le_bytes());
    bytes.extend_from_slice(&header.bits.to_le_bytes());
    bytes.extend_from_slice(&header.nonce.to_le_bytes());

    // Double SHA256 (Bitcoin standard)
    let first_hash = Sha256::digest(&bytes);
    let second_hash = Sha256::digest(first_hash);

    let mut hash = [0u8; 32];
    hash.copy_from_slice(&second_hash);
    hash
}

// ============================================================================
// TYPES
// ============================================================================

mod undo_entry_serde {
    use crate::types::UTXO;
    use serde::{Deserialize, Deserializer, Serialize, Serializer};
    use std::sync::Arc;

    pub fn serialize<S>(opt: &Option<Arc<UTXO>>, s: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        opt.as_ref().map(|a| a.as_ref()).serialize(s)
    }

    pub fn deserialize<'de, D>(d: D) -> Result<Option<Arc<UTXO>>, D::Error>
    where
        D: Deserializer<'de>,
    {
        Option::<UTXO>::deserialize(d).map(|opt| opt.map(Arc::new))
    }
}

/// Undo log entry for a single UTXO change
///
/// Records the state of a UTXO before and after a transaction is applied.
/// This allows perfect reversal of UTXO set changes during block disconnection.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct UndoEntry {
    /// The outpoint that was changed
    pub outpoint: OutPoint,
    /// The UTXO that existed before (None if it was created by this transaction)
    #[serde(with = "undo_entry_serde")]
    pub previous_utxo: Option<std::sync::Arc<UTXO>>,
    /// The UTXO that exists after (None if it was spent by this transaction)
    #[serde(with = "undo_entry_serde")]
    pub new_utxo: Option<std::sync::Arc<UTXO>>,
}

/// Undo log for a single block
///
/// Contains all UTXO changes made by a block, allowing perfect reversal
/// of the block's effects on the UTXO set.
///
/// Entries are stored in reverse order (most recent first) to allow
/// efficient undo by iterating forward.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct BlockUndoLog {
    /// Entries in reverse order (most recent first)
    /// This allows efficient undo: iterate forward and restore previous_utxo, remove new_utxo
    pub entries: Vec<UndoEntry>,
}

impl BlockUndoLog {
    /// Create an empty undo log
    pub fn new() -> Self {
        Self {
            entries: Vec::new(),
        }
    }

    /// Add an undo entry to the log
    pub fn push(&mut self, entry: UndoEntry) {
        self.entries.push(entry);
    }

    /// Check if the undo log is empty
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}

impl Default for BlockUndoLog {
    fn default() -> Self {
        Self::new()
    }
}

/// Result of chain reorganization
#[derive(Debug, Clone)]
pub struct ReorganizationResult {
    pub new_utxo_set: UtxoSet,
    pub new_height: Natural,
    pub common_ancestor: BlockHeader,
    pub disconnected_blocks: Vec<Block>,
    pub connected_blocks: Vec<Block>,
    pub reorganization_depth: usize,
    /// Undo logs for connected blocks (keyed by block hash)
    /// These can be used for future disconnections
    pub connected_block_undo_logs: HashMap<Hash, BlockUndoLog>,
}

// ============================================================================
// FORMAL VERIFICATION
// ============================================================================

/// Mathematical Specification for Chain Selection:
/// ∀ chains C₁, C₂: work(C₁) > work(C₂) ⇒ select(C₁)
///
/// Invariants:
/// - Selected chain has maximum cumulative work
/// - Work calculation is deterministic
/// - Empty chains are rejected
/// - Chain work is always non-negative

#[cfg(test)]
mod property_tests {
    use super::*;
    use proptest::prelude::*;

    /// Helper to get chain length range based on coverage mode
    fn chain_len_range() -> std::ops::Range<usize> {
        if std::env::var("CARGO_TARPAULIN").is_ok() || std::env::var("TARPAULIN").is_ok() {
            1..3 // Reduced range under coverage
        } else {
            1..5
        }
    }

    /// Helper to get chain length range for deterministic test
    fn chain_len_range_det() -> std::ops::Range<usize> {
        if std::env::var("CARGO_TARPAULIN").is_ok() || std::env::var("TARPAULIN").is_ok() {
            0..3 // Reduced range under coverage
        } else {
            0..10
        }
    }

    /// Random compact-encoded header bits (same domain as `expand_target` tests).
    fn arb_block() -> impl Strategy<Value = Block> {
        (0x00000000u64..0x1d00ffffu64).prop_map(|bits| Block {
            header: BlockHeader {
                version: 1,
                prev_block_hash: [0u8; 32],
                merkle_root: [0u8; 32],
                timestamp: 0,
                bits,
                nonce: 0,
            },
            transactions: Box::new([]),
        })
    }

    /// Property test: should_reorganize selects chain with maximum work
    proptest! {
        #[test]
        fn prop_should_reorganize_max_work(
            new_chain in proptest::collection::vec(arb_block(), chain_len_range()),
            current_chain in proptest::collection::vec(arb_block(), chain_len_range())
        ) {
            // Calculate work for both chains - handle errors from invalid blocks
            let new_work = calculate_chain_work(&new_chain);
            let current_work = calculate_chain_work(&current_chain);

            // Only test if both chains have valid work calculations
            if let (Ok(new_w), Ok(current_w)) = (new_work, current_work) {
                // Call should_reorganize
                let should_reorg = should_reorganize(&new_chain, &current_chain).unwrap_or(false);

                // should_reorganize: reorganize iff new chain has more cumulative work
                if new_w > current_w {
                    prop_assert!(should_reorg, "Must reorganize when new chain has more work");
                } else {
                    prop_assert!(!should_reorg, "Must not reorganize when new chain has less or equal work");
                }
            }
            // If either chain has invalid blocks, skip the test (acceptable)
        }
    }

    /// Property test: calculate_chain_work is deterministic
    proptest! {
        #[test]
        fn prop_calculate_chain_work_deterministic(
            chain in proptest::collection::vec(arb_block(), chain_len_range_det())
        ) {
            // Calculate work twice - handle errors from invalid blocks
            let work1 = calculate_chain_work(&chain);
            let work2 = calculate_chain_work(&chain);

            // Deterministic property: both should succeed or both should fail
            match (work1, work2) {
                (Ok(w1), Ok(w2)) => {
                    prop_assert_eq!(w1, w2, "Chain work calculation must be deterministic");
                },
                (Err(_), Err(_)) => {
                    // Both failed - this is acceptable for invalid blocks
                },
                _ => {
                    prop_assert!(false, "Chain work calculation must be deterministic (both succeed or both fail)");
                }
            }
        }
    }

    /// Property test: expand_target handles various difficulty values
    proptest! {
        #[test]
        fn prop_expand_target_valid_range(
            bits in 0x00000000u64..0x1d00ffffu64
        ) {
            let result = crate::pow::expand_target(bits);

            match result {
                Ok(target) => {
                    let _ = target;
                },
                Err(_) => {
                    // Some invalid targets may fail, which is acceptable
                }
            }
        }
    }

    /// Property test: should_reorganize with equal length chains compares work
    proptest! {
        #[test]
        fn prop_should_reorganize_equal_length(
            chain1 in proptest::collection::vec(arb_block(), 1..3),
            chain2 in proptest::collection::vec(arb_block(), 1..3)
        ) {
            // Ensure equal length
            let len = chain1.len().min(chain2.len());
            let chain1 = &chain1[..len];
            let chain2 = &chain2[..len];

            let work1 = calculate_chain_work(chain1);
            let work2 = calculate_chain_work(chain2);

            // Only test if both chains have valid work calculations
            if let (Ok(w1), Ok(w2)) = (work1, work2) {
                let should_reorg = should_reorganize(chain1, chain2).unwrap_or(false);

                // For equal length chains, reorganize iff chain1 has more work
                if w1 > w2 {
                    prop_assert!(should_reorg, "Must reorganize when first chain has more work");
                } else {
                    prop_assert!(!should_reorg, "Must not reorganize when first chain has less or equal work");
                }
            }
            // If either chain has invalid blocks, skip the test (acceptable)
        }
    }
}

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

    fn witnesses_for_chain(chain: &[Block]) -> Vec<Vec<Vec<Witness>>> {
        chain
            .iter()
            .map(|block| {
                block
                    .transactions
                    .iter()
                    .map(|tx| tx.inputs.iter().map(|_| Vec::new()).collect())
                    .collect()
            })
            .collect()
    }

    fn reorg_network_time(chain: &[Block]) -> u64 {
        chain
            .iter()
            .map(|b| b.header.timestamp)
            .max()
            .unwrap_or(0)
            .saturating_add(crate::constants::MAX_FUTURE_BLOCK_TIME)
    }

    fn reorganize_chain_test(
        new_chain: &[Block],
        current_chain: &[Block],
        utxo_set: UtxoSet,
        current_height: Natural,
    ) -> Result<ReorganizationResult> {
        reorganize_chain_with_witnesses(
            new_chain,
            &witnesses_for_chain(new_chain),
            None,
            current_chain,
            utxo_set,
            current_height,
            None::<fn(&Block) -> Option<Vec<Witness>>>,
            None::<fn(Natural) -> Option<Vec<BlockHeader>>>,
            None::<fn(&Hash) -> Option<BlockUndoLog>>,
            None::<fn(&Hash, &BlockUndoLog) -> Result<()>>,
            reorg_network_time(new_chain),
            crate::types::Network::Regtest,
        )
    }

    #[test]
    fn test_should_reorganize_more_cumulative_work() {
        let new_chain = vec![create_test_block(), create_test_block()];
        let current_chain = vec![create_test_block()];

        assert!(should_reorganize(&new_chain, &current_chain).unwrap());
    }

    #[test]
    fn test_should_reorganize_same_length_more_work() {
        let mut new_chain = vec![create_test_block()];
        let mut current_chain = vec![create_test_block()];

        // Same-length fork: harder chain (smaller target) has more cumulative work.
        new_chain[0].header.bits = 0x0300ffff;
        current_chain[0].header.bits = 0x0400ffff;

        assert!(should_reorganize(&new_chain, &current_chain).unwrap());
    }

    #[test]
    fn test_should_not_reorganize_less_work() {
        let new_chain = vec![create_test_block()];
        let current_chain = vec![create_test_block(), create_test_block()];

        assert!(!should_reorganize(&new_chain, &current_chain).unwrap());
    }

    #[test]
    fn test_find_common_ancestor() {
        let new_chain = vec![create_test_block()];
        let current_chain = vec![create_test_block()];

        let ancestor = find_common_ancestor(&new_chain, &current_chain).unwrap();
        assert_eq!(ancestor.header.version, 4);
        assert_eq!(ancestor.new_chain_index, 0);
        assert_eq!(ancestor.current_chain_index, 0);
    }

    #[test]
    fn test_find_common_ancestor_shared_prefix_unequal_length() {
        let b0 = create_test_block_at_height(0);
        let b1 = create_test_block_at_height(1);
        let b2 = create_test_block_at_height(2);
        let b3 = create_test_block_at_height(3);

        let new_chain = vec![b0.clone(), b1.clone(), b2, b3];
        let current_chain = vec![b0, b1];

        let ancestor = find_common_ancestor(&new_chain, &current_chain).unwrap();
        assert_eq!(ancestor.new_chain_index, 1);
        assert_eq!(ancestor.current_chain_index, 1);
    }

    #[test]
    fn test_find_common_ancestor_empty_chain() {
        let new_chain = vec![];
        let current_chain = vec![create_test_block()];

        let result = find_common_ancestor(&new_chain, &current_chain);
        assert!(result.is_err());
    }

    #[test]
    fn test_calculate_chain_work() {
        let mut block = create_test_block();
        // Use a bits value with exponent <= 18 so the target fits in u128
        block.header.bits = 0x0300ffff;
        let chain = vec![block];
        let work = calculate_chain_work(&chain).unwrap();
        assert!(work > crate::pow::U256::zero());
    }

    #[test]
    fn test_reorganize_chain() {
        // current_chain = [ancestor] (tip at height 1)
        // new_chain = [ancestor, new_block] (longer chain, should win)
        let ancestor = create_test_block_at_height(0);
        let mut new_block = create_test_block_at_height(1);
        new_block.header.nonce = 42; // Different block than ancestor
        // Recalculate merkle root (nonce doesn't affect it, but prev_block_hash irrelevant for connect_block)

        let new_chain = vec![ancestor.clone(), new_block];
        let current_chain = vec![ancestor];
        let utxo_set = UtxoSet::default();

        // current_height = 1 (tip of current_chain at height 1)
        let result = reorganize_chain_test(&new_chain, &current_chain, utxo_set, 1);
        match result {
            Ok(reorg_result) => {
                // Ancestor is at height 1 (current_height - 0 blocks after it = 1)
                // One new block connected at height 2
                assert_eq!(reorg_result.new_height, 2);
                assert_eq!(reorg_result.connected_blocks.len(), 1);
                assert_eq!(reorg_result.connected_block_undo_logs.len(), 1);
            }
            Err(_) => {
                // Acceptable: validation may fail for simplified test blocks
            }
        }
    }

    #[test]
    fn test_reorganize_chain_deep_reorg() {
        // Create blocks with unique hashes by varying nonce
        let mut block1 = create_test_block();
        block1.header.nonce = 1;
        let mut block2 = create_test_block();
        block2.header.nonce = 2;
        let mut block3 = create_test_block();
        block3.header.nonce = 3;
        let new_chain = vec![block1, block2, block3];

        let mut current_block1 = create_test_block();
        current_block1.header.nonce = 10;
        let mut current_block2 = create_test_block();
        current_block2.header.nonce = 11;
        let current_chain = vec![current_block1, current_block2];
        let utxo_set = UtxoSet::default();

        let result = reorganize_chain_test(&new_chain, &current_chain, utxo_set, 2);
        match result {
            Ok(reorg_result) => {
                assert_eq!(reorg_result.connected_blocks.len(), 3);
                assert_eq!(reorg_result.reorganization_depth, 2);
                // Verify undo logs are stored for all connected blocks
                assert_eq!(reorg_result.connected_block_undo_logs.len(), 3);
            }
            Err(_) => {
                // Expected failure due to simplified validation
            }
        }
    }

    #[test]
    fn test_undo_log_storage_and_retrieval() {
        use crate::block::connect_block;
        use crate::segwit::Witness;

        let block = create_test_block_at_height(1);
        let mut utxo_set = UtxoSet::default();

        // Add some UTXOs that will be spent
        let tx_id = calculate_tx_id(&block.transactions[0]);
        let outpoint = OutPoint {
            hash: tx_id,
            index: 0,
        };
        let utxo = UTXO {
            value: 5_000_000_000,
            script_pubkey: vec![0x51].into(),
            height: 1,
            is_coinbase: false,
        };
        utxo_set.insert(outpoint, std::sync::Arc::new(utxo.clone()));

        // Connect block and get undo log
        let witnesses: Vec<Vec<Witness>> = block
            .transactions
            .iter()
            .map(|tx| tx.inputs.iter().map(|_| Vec::new()).collect())
            .collect();
        let ctx = crate::block::BlockValidationContext::for_network(crate::types::Network::Regtest);
        let (result, new_utxo_set, undo_log) =
            connect_block(&block, &witnesses, utxo_set.clone(), 1, &ctx).unwrap();

        assert!(matches!(result, crate::types::ValidationResult::Valid));

        // Verify undo log contains entries
        assert!(
            !undo_log.entries.is_empty(),
            "Undo log should contain entries"
        );

        // Calculate block hash
        let block_hash = calculate_block_hash(&block.header);

        // Store undo log in a map (simulating persistent storage)
        let mut undo_log_storage: HashMap<Hash, BlockUndoLog> = HashMap::new();
        undo_log_storage.insert(block_hash, undo_log.clone());

        // Retrieve undo log
        let retrieved_undo_log = undo_log_storage.get(&block_hash);
        assert!(
            retrieved_undo_log.is_some(),
            "Should be able to retrieve undo log"
        );
        assert_eq!(
            retrieved_undo_log.unwrap().entries.len(),
            undo_log.entries.len()
        );

        // Disconnect block using retrieved undo log
        let disconnected_utxo_set = disconnect_block(&block, &undo_log, new_utxo_set, 1).unwrap();

        // Verify UTXO was restored
        assert!(
            disconnected_utxo_set.contains_key(&outpoint),
            "Disconnected UTXO set should contain restored UTXO"
        );
    }

    #[test]
    fn test_reorganize_with_undo_log_callback() {
        use crate::block::connect_block;
        use crate::segwit::Witness;

        // Create a block at height 1 and connect it to get undo log
        let block = create_test_block_at_height(1);
        let utxo_set = UtxoSet::default();
        let witnesses: Vec<Vec<Witness>> = block
            .transactions
            .iter()
            .map(|tx| tx.inputs.iter().map(|_| Vec::new()).collect())
            .collect();

        let ctx = crate::block::BlockValidationContext::for_network(crate::types::Network::Regtest);
        let (result, connected_utxo_set, undo_log) =
            connect_block(&block, &witnesses, utxo_set.clone(), 1, &ctx).unwrap();

        if !matches!(result, crate::types::ValidationResult::Valid) {
            eprintln!("Block validation failed: {result:?}");
        }
        assert!(matches!(result, crate::types::ValidationResult::Valid));

        // Store undo log
        let block_hash = calculate_block_hash(&block.header);
        let mut undo_log_storage: HashMap<Hash, BlockUndoLog> = HashMap::new();
        undo_log_storage.insert(block_hash, undo_log);

        // Create callback to retrieve undo log
        let get_undo_log =
            |hash: &Hash| -> Option<BlockUndoLog> { undo_log_storage.get(hash).cloned() };

        // Reorganize with undo log callback
        // new_chain shares the same ancestor block, plus a new block at height 2
        let mut new_block = create_test_block_at_height(2);
        new_block.header.nonce = 42; // Differentiate from ancestor
        let new_chain = vec![block.clone(), new_block];
        let current_chain = vec![block];
        let empty_witnesses: Vec<Vec<Vec<Witness>>> = new_chain
            .iter()
            .map(|b| {
                b.transactions
                    .iter()
                    .map(|tx| tx.inputs.iter().map(|_| Vec::new()).collect())
                    .collect()
            })
            .collect();

        let reorg_result = reorganize_chain_with_witnesses(
            &new_chain,
            &empty_witnesses,
            None,
            &current_chain,
            connected_utxo_set,
            1,
            None::<fn(&Block) -> Option<Vec<Witness>>>,
            None::<fn(Natural) -> Option<Vec<BlockHeader>>>,
            Some(get_undo_log),
            None::<fn(&Hash, &BlockUndoLog) -> Result<()>>, // No storage in test
            2_000_000_000,
            crate::types::Network::Regtest,
        );

        // Reorganization should succeed (or fail gracefully)
        match reorg_result {
            Ok(result) => {
                // Verify undo logs are stored for new blocks
                assert!(!result.connected_block_undo_logs.is_empty());
            }
            Err(_) => {
                // Expected failure due to simplified validation
            }
        }
    }

    #[test]
    fn test_reorganize_chain_empty_new_chain() {
        let new_chain = vec![];
        let current_chain = vec![create_test_block()];
        let utxo_set = UtxoSet::default();

        let result = reorganize_chain_test(&new_chain, &current_chain, utxo_set, 1);
        assert!(result.is_err());
    }

    #[test]
    fn test_reorganize_chain_empty_current_chain() {
        let new_chain = vec![create_test_block()];
        let current_chain = vec![];
        let utxo_set = UtxoSet::default();

        let result = reorganize_chain_test(&new_chain, &current_chain, utxo_set, 0);
        assert!(result.is_err());
    }

    #[test]
    fn test_disconnect_block() {
        let block = create_test_block();
        let mut utxo_set = UtxoSet::default();

        // Add some UTXOs that will be removed
        let tx_id = calculate_tx_id(&block.transactions[0]);
        let outpoint = OutPoint {
            hash: tx_id,
            index: 0,
        };
        let utxo = UTXO {
            value: 50_000_000_000,
            script_pubkey: vec![0x51].into(),
            height: 1,
            is_coinbase: false,
        };
        utxo_set.insert(outpoint, std::sync::Arc::new(utxo));

        // Create an empty undo log for testing (simplified)
        let empty_undo_log = BlockUndoLog::new();
        let result = disconnect_block(&block, &empty_undo_log, utxo_set, 1);
        assert!(result.is_ok());
    }

    #[test]
    fn test_calculate_chain_work_empty_chain() {
        let chain = vec![];
        let work = calculate_chain_work(&chain).unwrap();
        assert_eq!(work, crate::pow::U256::zero());
    }

    #[test]
    fn test_calculate_chain_work_multiple_blocks() {
        let mut chain = vec![create_test_block(), create_test_block()];
        // Use bits values with exponent <= 18 so targets fit in u128
        chain[0].header.bits = 0x0300ffff;
        chain[1].header.bits = 0x0400ffff;

        let work = calculate_chain_work(&chain).unwrap();
        assert!(work > crate::pow::U256::zero());
    }

    #[test]
    fn test_expand_target_edge_cases() {
        // Zero mantissa with valid exponent
        let result = crate::pow::expand_target(0x03000000);
        assert!(result.is_ok());
        assert!(result.unwrap().is_zero());

        // Test maximum valid target in low-exponent range
        let result = crate::pow::expand_target(0x03ffffff);
        assert!(result.is_ok());

        // Exponent outside pow::expand_target range (3..=32)
        let result = crate::pow::expand_target(0x2100ffff);
        assert!(result.is_err());
    }

    #[test]
    fn test_calculate_tx_id_different_transactions() {
        let tx1 = Transaction {
            version: 1,
            inputs: vec![].into(),
            outputs: vec![].into(),
            lock_time: 0,
        };

        let tx2 = Transaction {
            version: 2,
            inputs: vec![].into(),
            outputs: vec![].into(),
            lock_time: 0,
        };

        let id1 = calculate_tx_id(&tx1);
        let id2 = calculate_tx_id(&tx2);

        assert_ne!(id1, id2);
    }

    /// Encode a block height into a BIP34-compliant coinbase scriptSig prefix.
    /// Follows Bitcoin's CScriptNum serialization:
    /// - Height 0: OP_0 (0x00)
    /// - Height 1+: push N bytes of little-endian height (with sign-bit padding)
    fn encode_bip34_height(height: u64) -> Vec<u8> {
        if height == 0 {
            // CScriptNum(0) serializes to empty vec, CScript << empty = OP_0
            return vec![0x00, 0xff]; // OP_0 + padding to meet 2-byte minimum
        }
        let mut height_bytes = Vec::new();
        let mut n = height;
        while n > 0 {
            height_bytes.push((n & 0xff) as u8);
            n >>= 8;
        }
        // If high bit is set, add 0x00 for positive sign
        if height_bytes.last().is_some_and(|&b| b & 0x80 != 0) {
            height_bytes.push(0x00);
        }
        let mut script_sig = Vec::with_capacity(1 + height_bytes.len() + 1);
        script_sig.push(height_bytes.len() as u8); // direct push length
        script_sig.extend_from_slice(&height_bytes);
        // Pad to at least 2 bytes (coinbase scriptSig minimum)
        if script_sig.len() < 2 {
            script_sig.push(0xff);
        }
        script_sig
    }

    /// Create a test block with BIP34-compliant coinbase encoding for the given height.
    fn create_test_block_at_height(height: u64) -> Block {
        use crate::mining::calculate_merkle_root;

        let script_sig = encode_bip34_height(height);
        let coinbase_tx = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [0; 32],
                    index: 0xffffffff,
                },
                script_sig,
                sequence: 0xffffffff,
            }]
            .into(),
            outputs: vec![TransactionOutput {
                value: 5_000_000_000,
                script_pubkey: vec![0x51],
            }]
            .into(),
            lock_time: 0,
        };

        let merkle_root =
            calculate_merkle_root(&[coinbase_tx.clone()]).expect("Failed to calculate merkle root");

        Block {
            header: BlockHeader {
                version: 4,
                prev_block_hash: [0; 32],
                merkle_root,
                timestamp: 1231006505,
                bits: 0x0300ffff, // Valid compact target for chain-work tests
                nonce: 0,
            },
            transactions: vec![coinbase_tx].into_boxed_slice(),
        }
    }

    /// Create a test block at height 0 (backward-compatible default).
    fn create_test_block() -> Block {
        create_test_block_at_height(0)
    }
}