26829844658-1

Committed 02 Jun 2026 03:24PM UTC coverage: 86.038% (+0.08%) from 85.959%

Build # 26829844658-1

Build Type

Pull #7249

github

Specific Base 06b7ec

Committed by

web-flow

Commit Message

Merge e017b11f4 into b945664c8

Pull Request Pull Request #7249: feat: seamless rollovers between bond and stx-only staking positions

Coverage Stats

382 of 407 new or added lines in 3 files covered. (93.86%)

6474 existing lines in 95 files now uncovered.

194813 of 226426 relevant lines covered (86.04%)

18725269.97 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

98.44

/stackslib/src/core/mod.rs

// Copyright (C) 2013-2020 Blockstack PBC, a public benefit corporation
// Copyright (C) 2020 Stacks Open Internet Foundation
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.

#[cfg(test)]
use std::cmp::Ordering;
use std::collections::HashSet;
#[cfg(test)]
use std::str::FromStr;

use clarity::vm::costs::ExecutionCost;
use lazy_static::lazy_static;
pub use stacks_common::consts::MICROSTACKS_PER_STACKS;
use stacks_common::types::chainstate::{BlockHeaderHash, StacksBlockId};
pub use stacks_common::types::StacksEpochId;
use stacks_common::types::{EpochList as GenericEpochList, StacksEpoch as GenericStacksEpoch};
#[cfg(test)]
use stacks_common::versions::STACKS_NODE_VERSION;

pub use self::mempool::MemPoolDB;
use crate::burnchains::bitcoin::indexer::get_bitcoin_stacks_epochs;
use crate::burnchains::bitcoin::BitcoinNetworkType;
use crate::burnchains::Burnchain;
use crate::chainstate::burn::ConsensusHash;
pub mod mempool;
pub mod nonce_cache;

#[cfg(any(test, feature = "testing"))]
pub mod test_util;
#[cfg(test)]
pub mod tests;

pub type StacksEpoch = GenericStacksEpoch<ExecutionCost>;
pub type EpochList = GenericEpochList<ExecutionCost>;

// fork set identifier -- to be mixed with the consensus hash (encodes the version)
pub const SYSTEM_FORK_SET_VERSION: [u8; 4] = [23u8, 0u8, 0u8, 0u8];

// chain id
pub use stacks_common::consts::{
    CHAIN_ID_MAINNET, CHAIN_ID_TESTNET, MINING_COMMITMENT_WINDOW, NETWORK_ID_MAINNET,
    NETWORK_ID_TESTNET, PEER_NETWORK_EPOCH, PEER_VERSION_EPOCH_1_0, PEER_VERSION_EPOCH_2_0,
    PEER_VERSION_EPOCH_2_05, PEER_VERSION_EPOCH_2_1, PEER_VERSION_EPOCH_2_2,
    PEER_VERSION_EPOCH_2_3, PEER_VERSION_EPOCH_2_4, PEER_VERSION_EPOCH_2_5, PEER_VERSION_EPOCH_3_0,
    PEER_VERSION_EPOCH_3_1, PEER_VERSION_EPOCH_3_2, PEER_VERSION_EPOCH_3_3, PEER_VERSION_EPOCH_3_4,
    PEER_VERSION_EPOCH_4_0, PEER_VERSION_MAINNET, PEER_VERSION_MAINNET_MAJOR, PEER_VERSION_TESTNET,
    PEER_VERSION_TESTNET_MAJOR, STACKS_EPOCH_MAX,
};

// default port
pub const NETWORK_P2P_PORT: u16 = 6265;

// Number of previous burnchain blocks to search to find burnchain-hosted Stacks operations
pub const BURNCHAIN_TX_SEARCH_WINDOW: u8 = 6;

// This controls a miner heuristic for dropping a transaction from repeated consideration
//  in the mempool. If the transaction caused the block limit to be reached when the block
//  was previously `TX_BLOCK_LIMIT_PROPORTION_HEURISTIC`% full, the transaction will be dropped
//  from the mempool. 20% is chosen as a heuristic here to allow for large transactions to be
//  attempted, but if they cannot be included in an otherwise mostly empty block, not to consider
//  them again.
pub const TX_BLOCK_LIMIT_PROPORTION_HEURISTIC: u64 = 20;

pub const GENESIS_EPOCH: StacksEpochId = StacksEpochId::Epoch20;

/// The x-coordinate public key with no known discrete logarithm.
///
/// # Notes
///
/// This particular X-coordinate was discussed in the original taproot BIP
/// on spending rules BIP-0341[1]. Specifically, the X-coordinate is formed
/// by taking the hash of the standard uncompressed encoding of the
/// secp256k1 base point G as the X-coordinate. In that BIP the authors
/// wrote the X-coordinate that is reproduced below.
///
/// [1]: https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#constructing-and-spending-taproot-outputs
#[rustfmt::skip]
pub const NUMS_X_COORDINATE: [u8; 32] = [
    0x50, 0x92, 0x9b, 0x74, 0xc1, 0xa0, 0x49, 0x54,
    0xb7, 0x8b, 0x4b, 0x60, 0x35, 0xe9, 0x7a, 0x5e,
    0x07, 0x8a, 0x5a, 0x0f, 0x28, 0xec, 0x96, 0xd5,
    0x47, 0xbf, 0xee, 0x9a, 0xce, 0x80, 0x3a, 0xc0,
];

/// Maximum BTC fee, in satoshis, encoded into the sBTC deposit script's
/// `<deposit-data>` payload. Scaffolding constant: chosen high enough that
/// real-world bitcoin fees never exceed it. Will be replaced by a
/// protocol-determined value before mainnet activation.
pub const POX_5_SBTC_DEPOSIT_MAX_FEE_SATS: u64 = 80_000;

/// The number of blocks which will share the block bonus
///   from burn blocks that occurred without a sortition.
///   (See: https://forum.stacks.org/t/pox-consensus-and-stx-future-supply)
#[cfg(test)]
pub const INITIAL_MINING_BONUS_WINDOW: u16 = 10;
#[cfg(not(test))]
pub const INITIAL_MINING_BONUS_WINDOW: u16 = 10_000;

pub const STACKS_2_0_LAST_BLOCK_TO_PROCESS: u64 = 700_000;
pub const MAINNET_2_0_GENESIS_ROOT_HASH: &str =
    "9653c92b1ad726e2dc17862a3786f7438ab9239c16dd8e7aaba8b0b5c34b52af";

/// This is the "dummy" parent to the actual first burnchain block that we process.
pub const FIRST_BURNCHAIN_CONSENSUS_HASH: ConsensusHash = ConsensusHash([0u8; 20]);

// TODO: TO BE SET BY STACKS_V1_MINER_THRESHOLD
pub const BITCOIN_MAINNET_FIRST_BLOCK_HEIGHT: u64 = 666050;
pub const BITCOIN_MAINNET_FIRST_BLOCK_TIMESTAMP: u32 = 1610643248;
pub const BITCOIN_MAINNET_FIRST_BLOCK_HASH: &str =
    "0000000000000000000ab248c8e35c574514d052a83dbc12669e19bc43df486e";
pub const BITCOIN_MAINNET_INITIAL_REWARD_START_BLOCK: u64 = 651389;
pub const BITCOIN_MAINNET_STACKS_2_05_BURN_HEIGHT: u64 = 713_000;
pub const BITCOIN_MAINNET_STACKS_21_BURN_HEIGHT: u64 = 781_551;
/// This is Epoch-2.2 activation height proposed in SIP-022
pub const BITCOIN_MAINNET_STACKS_22_BURN_HEIGHT: u64 = 787_651;
/// This is Epoch-2.3 activation height proposed in SIP-023
pub const BITCOIN_MAINNET_STACKS_23_BURN_HEIGHT: u64 = 788_240;
/// This is Epoch-2.3, now Epoch-2.4, activation height proposed in SIP-024
pub const BITCOIN_MAINNET_STACKS_24_BURN_HEIGHT: u64 = 791_551;
/// This is Epoch-2.5, activation height proposed in SIP-021
pub const BITCOIN_MAINNET_STACKS_25_BURN_HEIGHT: u64 = 840_360;
/// This is Epoch-3.0, activation height proposed in SIP-021
pub const BITCOIN_MAINNET_STACKS_30_BURN_HEIGHT: u64 = 867_867;
/// This is Epoch-3.1, activation height proposed in SIP-029
pub const BITCOIN_MAINNET_STACKS_31_BURN_HEIGHT: u64 = 875_000;
/// This is Epoch-3.2, activation height proposed in SIP-031
pub const BITCOIN_MAINNET_STACKS_32_BURN_HEIGHT: u64 = 907_740;
/// This is Epoch-3.3, activation timing proposed in SIP-033
pub const BITCOIN_MAINNET_STACKS_33_BURN_HEIGHT: u64 = 923_222;
/// This is Epoch-3.4, activation timing proposed in SIP-039
pub const BITCOIN_MAINNET_STACKS_34_BURN_HEIGHT: u64 = 943_333;
/// This is Epoch-4.0, activation timing TBD. Placeholder until scheduled.
pub const BITCOIN_MAINNET_STACKS_40_BURN_HEIGHT: u64 = 4_000_000;

/// Bitcoin mainline testnet3 activation heights.
/// TODO: No longer used since testnet3 is dead, so remove.
pub const BITCOIN_TESTNET_FIRST_BLOCK_HEIGHT: u64 = 2000000;
pub const BITCOIN_TESTNET_FIRST_BLOCK_TIMESTAMP: u32 = 1622691840;
pub const BITCOIN_TESTNET_FIRST_BLOCK_HASH: &str =
    "000000000000010dd0863ec3d7a0bae17c1957ae1de9cbcdae8e77aad33e3b8c";
pub const BITCOIN_TESTNET_STACKS_2_05_BURN_HEIGHT: u64 = 2_104_380;
pub const BITCOIN_TESTNET_STACKS_21_BURN_HEIGHT: u64 = 2_422_101;
pub const BITCOIN_TESTNET_STACKS_22_BURN_HEIGHT: u64 = 2_431_300;
pub const BITCOIN_TESTNET_STACKS_23_BURN_HEIGHT: u64 = 2_431_633;
pub const BITCOIN_TESTNET_STACKS_24_BURN_HEIGHT: u64 = 2_432_545;
pub const BITCOIN_TESTNET_STACKS_25_BURN_HEIGHT: u64 = 2_583_893;
pub const BITCOIN_TESTNET_STACKS_30_BURN_HEIGHT: u64 = 30_000_000;
pub const BITCOIN_TESTNET_STACKS_31_BURN_HEIGHT: u64 = 30_000_001;
pub const BITCOIN_TESTNET_STACKS_32_BURN_HEIGHT: u64 = 30_000_002;
pub const BITCOIN_TESTNET_STACKS_33_BURN_HEIGHT: u64 = 30_000_003;
pub const BITCOIN_TESTNET_STACKS_34_BURN_HEIGHT: u64 = 30_000_004;
pub const BITCOIN_TESTNET_STACKS_40_BURN_HEIGHT: u64 = 40_000_000;

pub const BITCOIN_REGTEST_FIRST_BLOCK_HEIGHT: u64 = 0;
pub const BITCOIN_REGTEST_FIRST_BLOCK_TIMESTAMP: u32 = 0;
pub const BITCOIN_REGTEST_FIRST_BLOCK_HASH: &str =
    "0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206";

pub const FIRST_STACKS_BLOCK_HASH: BlockHeaderHash = BlockHeaderHash([0u8; 32]);
pub const EMPTY_MICROBLOCK_PARENT_HASH: BlockHeaderHash = BlockHeaderHash([0u8; 32]);

lazy_static! {
    pub static ref FIRST_STACKS_BLOCK_ID: StacksBlockId =
        StacksBlockId::new(&FIRST_BURNCHAIN_CONSENSUS_HASH, &FIRST_STACKS_BLOCK_HASH);
}

pub const BOOT_BLOCK_HASH: BlockHeaderHash = BlockHeaderHash([0xff; 32]);
pub const BURNCHAIN_BOOT_CONSENSUS_HASH: ConsensusHash = ConsensusHash([0xff; 20]);

pub const POX_SUNSET_START: u64 = 100_000;
pub const POX_SUNSET_END: u64 = POX_SUNSET_START + 400_000;

pub const POX_PREPARE_WINDOW_LENGTH: u32 = 100;
pub const POX_REWARD_CYCLE_LENGTH: u32 = 2100;
/// The maximum amount that PoX rewards can be scaled by.
///  That is, if participation is very low, rewards are:
///      POX_MAXIMAL_SCALING x (rewards with 100% participation)
///  Set a 4x, this implies the lower bound of participation for scaling
///   is 25%
pub const POX_MAXIMAL_SCALING: u128 = 4;
/// This is the amount that PoX threshold adjustments are stepped by.
pub const POX_THRESHOLD_STEPS_USTX: u128 = 10_000 * (MICROSTACKS_PER_STACKS as u128);

pub const POX_MAX_NUM_CYCLES: u8 = 12;

// These values are taken from the corresponding variables in `pox-tesnet.clar`.
pub const POX_TESTNET_STACKING_THRESHOLD_25: u128 = 8000;
pub const POX_TESTNET_CYCLE_LENGTH: u128 = 1050;

pub const POX_V1_MAINNET_EARLY_UNLOCK_HEIGHT: u32 =
    (BITCOIN_MAINNET_STACKS_21_BURN_HEIGHT as u32) + 1;
pub const POX_V1_TESTNET_EARLY_UNLOCK_HEIGHT: u32 =
    (BITCOIN_TESTNET_STACKS_21_BURN_HEIGHT as u32) + 1;

pub const POX_V2_MAINNET_EARLY_UNLOCK_HEIGHT: u32 =
    (BITCOIN_MAINNET_STACKS_22_BURN_HEIGHT as u32) + 1;
pub const POX_V2_TESTNET_EARLY_UNLOCK_HEIGHT: u32 =
    (BITCOIN_TESTNET_STACKS_22_BURN_HEIGHT as u32) + 1;

pub const POX_V3_MAINNET_EARLY_UNLOCK_HEIGHT: u32 =
    (BITCOIN_MAINNET_STACKS_25_BURN_HEIGHT as u32) + 1;
pub const POX_V3_TESTNET_EARLY_UNLOCK_HEIGHT: u32 =
    (BITCOIN_TESTNET_STACKS_25_BURN_HEIGHT as u32) + 1;

// The threshold of weighted votes on a block to approve it in Nakamoto.
// This is out of 10, so 7 means "70%".
pub const NAKAMOTO_SIGNER_BLOCK_APPROVAL_THRESHOLD: u64 = 7;

// Stacks 1.0 did not allow smart contracts so all limits are 0.
pub const BLOCK_LIMIT_MAINNET_10: ExecutionCost = ExecutionCost {
    write_length: 0,
    write_count: 0,
    read_length: 0,
    read_count: 0,
    runtime: 0,
};

// Block limit in Stacks 2.0.
pub const BLOCK_LIMIT_MAINNET_20: ExecutionCost = ExecutionCost {
    write_length: 15_000_000, // roughly 15 mb
    write_count: 7_750,
    read_length: 100_000_000,
    read_count: 7_750,
    runtime: 5_000_000_000,
};

// Block limit in Stacks 2.05.
pub const BLOCK_LIMIT_MAINNET_205: ExecutionCost = ExecutionCost {
    write_length: 15_000_000,
    write_count: 15_000,
    read_length: 100_000_000,
    read_count: 15_000,
    runtime: 5_000_000_000,
};

// Block limit in Stacks 2.1
pub const BLOCK_LIMIT_MAINNET_21: ExecutionCost = ExecutionCost {
    write_length: 15_000_000,
    write_count: 15_000,
    read_length: 100_000_000,
    read_count: 15_000,
    runtime: 5_000_000_000,
};

// Block limit for the testnet in Stacks 2.0.
pub const HELIUM_BLOCK_LIMIT_20: ExecutionCost = ExecutionCost {
    write_length: 150_000_000,
    write_count: 50_000,
    read_length: 1_000_000_000,
    read_count: 50_000,
    // allow much more runtime in helium blocks than mainnet
    runtime: 100_000_000_000,
};

pub const FAULT_DISABLE_MICROBLOCKS_COST_CHECK: &str = "MICROBLOCKS_DISABLE_COST_CHECK";
pub const FAULT_DISABLE_MICROBLOCKS_BYTES_CHECK: &str = "MICROBLOCKS_DISABLE_BYTES_CHECK";

pub fn check_fault_injection(fault_name: &str) -> bool {
    use std::env;

    // only activates if we're testing
    if env::var("BITCOIND_TEST") != Ok("1".to_string()) {
        return false;
    }

    env::var(fault_name) == Ok("1".to_string())
}

lazy_static! {
    pub static ref STACKS_EPOCHS_MAINNET: EpochList = EpochList::new(&[
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch10,
            start_height: 0,
            end_height: BITCOIN_MAINNET_FIRST_BLOCK_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_10,
            network_epoch: PEER_VERSION_EPOCH_1_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch20,
            start_height: BITCOIN_MAINNET_FIRST_BLOCK_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_2_05_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_20,
            network_epoch: PEER_VERSION_EPOCH_2_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch2_05,
            start_height: BITCOIN_MAINNET_STACKS_2_05_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_21_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_205,
            network_epoch: PEER_VERSION_EPOCH_2_05
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch21,
            start_height: BITCOIN_MAINNET_STACKS_21_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_22_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_1
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch22,
            start_height: BITCOIN_MAINNET_STACKS_22_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_23_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_2
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch23,
            start_height: BITCOIN_MAINNET_STACKS_23_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_24_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_3
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch24,
            start_height: BITCOIN_MAINNET_STACKS_24_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_25_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_4
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch25,
            start_height: BITCOIN_MAINNET_STACKS_25_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_30_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_5
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch30,
            start_height: BITCOIN_MAINNET_STACKS_30_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_31_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch31,
            start_height: BITCOIN_MAINNET_STACKS_31_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_32_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_1
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch32,
            start_height: BITCOIN_MAINNET_STACKS_32_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_33_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_2
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch33,
            start_height: BITCOIN_MAINNET_STACKS_33_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_34_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_3
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch34,
            start_height: BITCOIN_MAINNET_STACKS_34_BURN_HEIGHT,
            end_height: BITCOIN_MAINNET_STACKS_40_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_4
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch40,
            start_height: BITCOIN_MAINNET_STACKS_40_BURN_HEIGHT,
            end_height: STACKS_EPOCH_MAX,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_4_0
        },
    ]);
}

lazy_static! {
    pub static ref STACKS_EPOCHS_TESTNET: EpochList = EpochList::new(&[
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch10,
            start_height: 0,
            end_height: BITCOIN_TESTNET_FIRST_BLOCK_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_10,
            network_epoch: PEER_VERSION_EPOCH_1_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch20,
            start_height: BITCOIN_TESTNET_FIRST_BLOCK_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_2_05_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_20,
            network_epoch: PEER_VERSION_EPOCH_2_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch2_05,
            start_height: BITCOIN_TESTNET_STACKS_2_05_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_21_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_205,
            network_epoch: PEER_VERSION_EPOCH_2_05
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch21,
            start_height: BITCOIN_TESTNET_STACKS_21_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_22_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_1
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch22,
            start_height: BITCOIN_TESTNET_STACKS_22_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_23_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_2
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch23,
            start_height: BITCOIN_TESTNET_STACKS_23_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_24_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_3
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch24,
            start_height: BITCOIN_TESTNET_STACKS_24_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_25_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_4
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch25,
            start_height: BITCOIN_TESTNET_STACKS_25_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_30_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_5
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch30,
            start_height: BITCOIN_TESTNET_STACKS_30_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_31_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch31,
            start_height: BITCOIN_TESTNET_STACKS_31_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_32_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_1
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch32,
            start_height: BITCOIN_TESTNET_STACKS_32_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_33_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_2
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch33,
            start_height: BITCOIN_TESTNET_STACKS_33_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_34_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_3
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch34,
            start_height: BITCOIN_TESTNET_STACKS_34_BURN_HEIGHT,
            end_height: BITCOIN_TESTNET_STACKS_40_BURN_HEIGHT,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_4
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch40,
            start_height: BITCOIN_TESTNET_STACKS_40_BURN_HEIGHT,
            end_height: STACKS_EPOCH_MAX,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_4_0
        },
    ]);
}

lazy_static! {
    pub static ref STACKS_EPOCHS_REGTEST: EpochList = EpochList::new(&[
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch10,
            start_height: 0,
            end_height: 0,
            block_limit: BLOCK_LIMIT_MAINNET_10,
            network_epoch: PEER_VERSION_EPOCH_1_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch20,
            start_height: 0,
            end_height: 1000,
            block_limit: HELIUM_BLOCK_LIMIT_20,
            network_epoch: PEER_VERSION_EPOCH_2_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch2_05,
            start_height: 1000,
            end_height: 2000,
            block_limit: HELIUM_BLOCK_LIMIT_20,
            network_epoch: PEER_VERSION_EPOCH_2_05
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch21,
            start_height: 2000,
            end_height: 3000,
            block_limit: HELIUM_BLOCK_LIMIT_20,
            network_epoch: PEER_VERSION_EPOCH_2_1
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch22,
            start_height: 3000,
            end_height: 4000,
            block_limit: HELIUM_BLOCK_LIMIT_20,
            network_epoch: PEER_VERSION_EPOCH_2_2
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch23,
            start_height: 4000,
            end_height: 5000,
            block_limit: HELIUM_BLOCK_LIMIT_20,
            network_epoch: PEER_VERSION_EPOCH_2_3
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch24,
            start_height: 5000,
            end_height: 6000,
            block_limit: HELIUM_BLOCK_LIMIT_20,
            network_epoch: PEER_VERSION_EPOCH_2_4
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch25,
            start_height: 6000,
            end_height: 7001,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_2_5
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch30,
            start_height: 7001,
            end_height: 8001,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_0
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch31,
            start_height: 8001,
            end_height: 9001,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_1
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch32,
            start_height: 9001,
            end_height: 10001,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_2
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch33,
            start_height: 10001,
            end_height: 11001,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_3
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch34,
            start_height: 11001,
            end_height: 12001,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_3_4
        },
        StacksEpoch {
            epoch_id: StacksEpochId::Epoch40,
            start_height: 12001,
            end_height: STACKS_EPOCH_MAX,
            block_limit: BLOCK_LIMIT_MAINNET_21,
            network_epoch: PEER_VERSION_EPOCH_4_0
        },
    ]);
}

/// Stacks 2.05 epoch marker.  All block-commits in 2.05 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_2_05_MARKER: u8 = 0x05;

/// Stacks 2.1 epoch marker.  All block-commits in 2.1 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_2_1_MARKER: u8 = 0x06;

/// Stacks 2.2 epoch marker.  All block-commits in 2.2 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_2_2_MARKER: u8 = 0x07;

/// Stacks 2.3 epoch marker.  All block-commits in 2.3 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_2_3_MARKER: u8 = 0x08;

/// Stacks 2.4 epoch marker.  All block-commits in 2.4 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_2_4_MARKER: u8 = 0x09;

/// Stacks 2.5 epoch marker.  All block-commits in 2.5 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_2_5_MARKER: u8 = 0x0a;

/// Stacks 3.0 epoch marker.  All block-commits in 3.0 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_3_0_MARKER: u8 = 0x0b;

/// Stacks 3.1 epoch marker.  All block-commits in 3.1 must have a memo bitfield with this value
/// *or greater*.
/// NOTE: it has to be 0x0d because a prior release of 3.1 with 0x0c before activation had a
/// consensus bug. This forces miners with this buggy release off the network if they are still
/// running it prior to 3.1 activation.
pub static STACKS_EPOCH_3_1_MARKER: u8 = 0x0d;

/// Stacks 3.2 epoch marker.  All block-commits in 3.2 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_3_2_MARKER: u8 = 0x0e;

/// Stacks 3.3 epoch marker.  All block-commits in 3.3 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_3_3_MARKER: u8 = 0x0f;

/// Stacks 3.4 epoch marker.  All block-commits in 3.4 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_3_4_MARKER: u8 = 0x10;

/// Stacks 4.0 epoch marker.  All block-commits in 4.0 must have a memo bitfield with this value
/// *or greater*.
pub static STACKS_EPOCH_4_0_MARKER: u8 = 0x11;

/// Latest Stacks epoch marker. Automatically uses the marker for the highest supported epoch.
pub static STACKS_EPOCH_LATEST_MARKER: u8 =
    marker_for_epoch(StacksEpochId::latest()).expect("Latest epoch should always have a marker");

pub const fn marker_for_epoch(epoch_id: StacksEpochId) -> Option<u8> {
    match epoch_id {
        StacksEpochId::Epoch10 => None,
        StacksEpochId::Epoch20 => None,
        StacksEpochId::Epoch2_05 => Some(STACKS_EPOCH_2_05_MARKER),
        StacksEpochId::Epoch21 => Some(STACKS_EPOCH_2_1_MARKER),
        StacksEpochId::Epoch22 => Some(STACKS_EPOCH_2_2_MARKER),
        StacksEpochId::Epoch23 => Some(STACKS_EPOCH_2_3_MARKER),
        StacksEpochId::Epoch24 => Some(STACKS_EPOCH_2_4_MARKER),
        StacksEpochId::Epoch25 => Some(STACKS_EPOCH_2_5_MARKER),
        StacksEpochId::Epoch30 => Some(STACKS_EPOCH_3_0_MARKER),
        StacksEpochId::Epoch31 => Some(STACKS_EPOCH_3_1_MARKER),
        StacksEpochId::Epoch32 => Some(STACKS_EPOCH_3_2_MARKER),
        StacksEpochId::Epoch33 => Some(STACKS_EPOCH_3_3_MARKER),
        StacksEpochId::Epoch34 => Some(STACKS_EPOCH_3_4_MARKER),
        StacksEpochId::Epoch40 => Some(STACKS_EPOCH_4_0_MARKER),
    }
}

// Pick the release epoch whose `network_epoch` must match `PEER_NETWORK_EPOCH`.
// `latest()` may be one-ahead in test/testing builds, so this check intentionally
// anchors to the release latest epoch instead.
fn peer_network_epoch_check_epoch_id() -> StacksEpochId {
    assert!(
        StacksEpochId::RELEASE_LATEST_EPOCH <= StacksEpochId::latest(),
        "FATAL: RELEASE_LATEST_EPOCH cannot be greater than latest()"
    );
    StacksEpochId::RELEASE_LATEST_EPOCH
}

#[test]
fn test_ord_for_stacks_epoch() {
    let epochs = &*STACKS_EPOCHS_MAINNET;
    assert_eq!(
        epochs[StacksEpochId::Epoch10].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Less
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch20].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Less
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch10].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Less
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch10].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Equal
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch20].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Equal
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch2_05].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Equal
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch21].cmp(&epochs[StacksEpochId::Epoch21]),
        Ordering::Equal
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch22].cmp(&epochs[StacksEpochId::Epoch22]),
        Ordering::Equal
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch2_05].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch2_05].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch20].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch21].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch21].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch21].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch22].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch22].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch22].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch22].cmp(&epochs[StacksEpochId::Epoch21]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch23].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch23].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch23].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch23].cmp(&epochs[StacksEpochId::Epoch21]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch23].cmp(&epochs[StacksEpochId::Epoch22]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch24].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch24].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch24].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch24].cmp(&epochs[StacksEpochId::Epoch21]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch24].cmp(&epochs[StacksEpochId::Epoch22]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch24].cmp(&epochs[StacksEpochId::Epoch23]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch25].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch25].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch25].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch25].cmp(&epochs[StacksEpochId::Epoch21]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch25].cmp(&epochs[StacksEpochId::Epoch22]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch25].cmp(&epochs[StacksEpochId::Epoch23]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch25].cmp(&epochs[StacksEpochId::Epoch24]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch21]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch22]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch23]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch24]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch30].cmp(&epochs[StacksEpochId::Epoch25]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch10]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch20]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch2_05]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch21]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch22]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch23]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch24]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch25]),
        Ordering::Greater
    );
    assert_eq!(
        epochs[StacksEpochId::Epoch31].cmp(&epochs[StacksEpochId::Epoch30]),
        Ordering::Greater
    );
}

#[test]
fn test_ord_for_stacks_epoch_id() {
    assert_eq!(
        StacksEpochId::Epoch10.cmp(&StacksEpochId::Epoch20),
        Ordering::Less
    );
    assert_eq!(
        StacksEpochId::Epoch20.cmp(&StacksEpochId::Epoch2_05),
        Ordering::Less
    );
    assert_eq!(
        StacksEpochId::Epoch10.cmp(&StacksEpochId::Epoch2_05),
        Ordering::Less
    );
    assert_eq!(
        StacksEpochId::Epoch10.cmp(&StacksEpochId::Epoch10),
        Ordering::Equal
    );
    assert_eq!(
        StacksEpochId::Epoch20.cmp(&StacksEpochId::Epoch20),
        Ordering::Equal
    );
    assert_eq!(
        StacksEpochId::Epoch2_05.cmp(&StacksEpochId::Epoch2_05),
        Ordering::Equal
    );
    assert_eq!(
        StacksEpochId::Epoch2_05.cmp(&StacksEpochId::Epoch20),
        Ordering::Greater
    );
    assert_eq!(
        StacksEpochId::Epoch2_05.cmp(&StacksEpochId::Epoch10),
        Ordering::Greater
    );
    assert_eq!(
        StacksEpochId::Epoch20.cmp(&StacksEpochId::Epoch10),
        Ordering::Greater
    );
}

#[cfg(test)]
fn release_epoch_from_stacks_node_version() -> StacksEpochId {
    let mut parts = STACKS_NODE_VERSION.split('.');
    let major = parts
        .next()
        .expect("FATAL: STACKS_NODE_VERSION must include major version");
    let minor = parts
        .next()
        .expect("FATAL: STACKS_NODE_VERSION must include minor version");
    let release_epoch_str = format!("{major}.{minor}");
    StacksEpochId::from_str(&release_epoch_str).unwrap_or_else(|_| {
        panic!(
            "FATAL: STACKS_NODE_VERSION major.minor '{release_epoch_str}' must map to a StacksEpochId"
        )
    })
}

#[test]
fn test_release_epoch_matches_versions_and_peer_epoch() {
    let release_epoch_from_version = release_epoch_from_stacks_node_version();
    assert_eq!(
        release_epoch_from_version,
        StacksEpochId::RELEASE_LATEST_EPOCH,
        "versions.toml stacks_node_version major.minor must match RELEASE_LATEST_EPOCH"
    );
    assert_eq!(
        u32::from(StacksEpochId::network_epoch(
            StacksEpochId::RELEASE_LATEST_EPOCH
        )),
        PEER_NETWORK_EPOCH,
        "PEER_NETWORK_EPOCH must match RELEASE_LATEST_EPOCH's network_epoch"
    );
}

#[test]
fn test_peer_network_epoch_matches_static_epoch_tables() {
    let check_epoch_id = peer_network_epoch_check_epoch_id();
    for (network_name, epochs) in [
        ("mainnet", &*STACKS_EPOCHS_MAINNET),
        ("testnet", &*STACKS_EPOCHS_TESTNET),
        ("regtest", &*STACKS_EPOCHS_REGTEST),
    ] {
        let check_epoch = epochs.get(check_epoch_id).unwrap_or_else(|| {
            panic!("FATAL: {network_name} epoch table is missing check epoch {check_epoch_id:?}")
        });
        assert_eq!(
            u32::from(check_epoch.network_epoch),
            PEER_NETWORK_EPOCH,
            "stacks-blockchain static network epoch should match {network_name} epoch {check_epoch_id:?}"
        );
    }
}

#[test]
#[should_panic(expected = "stacks-blockchain static network epoch should match")]
fn test_validate_epochs_rejects_stale_peer_network_epoch() {
    let check_epoch_id = peer_network_epoch_check_epoch_id();
    let mut bad_epochs = (*STACKS_EPOCHS_MAINNET).clone();
    bad_epochs[check_epoch_id].network_epoch = (PEER_NETWORK_EPOCH + 1) as u8;
    let _ = StacksEpoch::validate_epochs(&bad_epochs);
}

pub trait StacksEpochExtension {
    /// Build an epoch list spanning `Epoch10..=last_epoch` with the standard
    /// test cadence: Epoch10 covers `[0, first_burnchain_height)`, each
    /// subsequent epoch occupies 4 blocks, and `last_epoch` ends at
    /// `STACKS_EPOCH_MAX`.
    #[cfg(test)]
    fn unit_test_up_to(first_burnchain_height: u64, last_epoch: StacksEpochId) -> EpochList;
    /// Build an epoch list where `target_epoch` is the only active epoch.
    /// Pre-Epoch25 epochs are disabled (zero-width at height 0); Epoch25
    /// spans `[0, first_burnchain_height)` as the transition point; Nakamoto
    /// epochs before `target_epoch` are zero-width at `first_burnchain_height`;
    /// `target_epoch` spans `[first_burnchain_height, STACKS_EPOCH_MAX)`.
    /// Requires `target_epoch >= Epoch30`.
    #[cfg(test)]
    fn unit_test_epoch_only(first_burnchain_height: u64, target_epoch: StacksEpochId) -> EpochList;
    /// Build a pre-Nakamoto fixture with custom transition heights for the
    /// pre-2.1 epochs. Spans Epoch10..=Epoch21 with all `block_limit`s set to
    /// `ExecutionCost::max_value()` (so cost limits are out of the way).
    /// Each parameter is the `start_height` of the named epoch (which equals
    /// the `end_height` of the preceding one).
    fn unit_test_2_1_with_heights(
        epoch_2_0_start: u64,
        epoch_2_05_start: u64,
        epoch_2_1_start: u64,
    ) -> EpochList;
    fn validate_epochs(epochs: &[StacksEpoch]) -> EpochList;
    /// This method gets the epoch vector.
    ///
    /// Choose according to:
    /// 1) Use the custom epochs defined on the underlying `BitcoinIndexerConfig`, if they exist.
    /// 2) Use hard-coded static values, otherwise.
    ///
    /// It is an error (panic) to set custom epochs if running on `Mainnet`.
    ///
    fn get_epochs(
        bitcoin_network: BitcoinNetworkType,
        configured_epochs: Option<&EpochList>,
    ) -> EpochList;
    /// Validates that Epoch 3.0 activation (if present) satisfies all required safety
    /// invariants for Nakamoto transition, using the provided burnchain configuration.
    fn validate_nakamoto_transition_schedule(epochs: &[StacksEpoch], burnchain: &Burnchain);
}

impl StacksEpochExtension for StacksEpoch {
    fn get_epochs(
        bitcoin_network: BitcoinNetworkType,
        configured_epochs: Option<&EpochList>,
    ) -> EpochList {
        match configured_epochs {
            Some(epochs) => {
                assert!(bitcoin_network != BitcoinNetworkType::Mainnet);
                epochs.clone()
            }
            None => get_bitcoin_stacks_epochs(bitcoin_network),
        }
    }

    #[cfg(test)]
    fn unit_test_up_to(first_burnchain_height: u64, last_epoch: StacksEpochId) -> EpochList {
        info!(
            "StacksEpoch unit_test_up_to last_epoch={last_epoch} first_burn_height={first_burnchain_height}"
        );

        // Block limits used by the test epoch fixtures.
        let block_limit_for = |epoch_id: StacksEpochId| -> ExecutionCost {
            match epoch_id {
                StacksEpochId::Epoch10 | StacksEpochId::Epoch20 => ExecutionCost::max_value(),
                StacksEpochId::Epoch2_05 => ExecutionCost {
                    write_length: 205205,
                    write_count: 205205,
                    read_length: 205205,
                    read_count: 205205,
                    runtime: 205205,
                },
                _ => ExecutionCost {
                    write_length: 210210,
                    write_count: 210210,
                    read_length: 210210,
                    read_count: 210210,
                    runtime: 210210,
                },
            }
        };

        let mut epochs = Vec::new();
        let mut start_height = 0u64;
        for epoch_id in StacksEpochId::ALL.iter() {
            let end_height = if *epoch_id == last_epoch {
                STACKS_EPOCH_MAX
            } else if *epoch_id == StacksEpochId::Epoch10 {
                first_burnchain_height
            } else {
                start_height + 4
            };
            epochs.push(StacksEpoch {
                epoch_id: *epoch_id,
                start_height,
                end_height,
                block_limit: block_limit_for(*epoch_id),
                network_epoch: StacksEpochId::network_epoch(*epoch_id),
            });
            if *epoch_id == last_epoch {
                break;
            }
            start_height = end_height;
        }
        EpochList::new(&epochs)
    }

    #[cfg(test)]
    fn unit_test_epoch_only(first_burnchain_height: u64, target_epoch: StacksEpochId) -> EpochList {
        info!(
            "StacksEpoch unit_test_epoch_only target={target_epoch} first_burn_height={first_burnchain_height}"
        );
        assert!(
            target_epoch >= StacksEpochId::Epoch30,
            "unit_test_epoch_only requires a Nakamoto-era target (Epoch30+), got {target_epoch}"
        );

        // Height layout, iterating through StacksEpochId::ALL:
        //  - Pre-Epoch25 epochs sit in a dead zone at height 0 (start == end == 0).
        //  - Epoch25 spans [0, first_burnchain_height), the transition point.
        //  - Nakamoto epochs before `target_epoch` are zero-width at
        //    `first_burnchain_height`.
        //  - `target_epoch` spans [first_burnchain_height, STACKS_EPOCH_MAX).
        //
        // Each epoch's `start_height` is the previous epoch's `end_height`,
        // which falls out of that layout for free.
        let mut epochs = Vec::new();
        let mut start_height = 0u64;
        for epoch_id in StacksEpochId::ALL.iter() {
            let end_height = if *epoch_id == target_epoch {
                STACKS_EPOCH_MAX
            } else if *epoch_id < StacksEpochId::Epoch25 {
                0
            } else {
                first_burnchain_height
            };
            let block_limit = if *epoch_id < StacksEpochId::Epoch25 {
                ExecutionCost::max_value()
            } else {
                BLOCK_LIMIT_MAINNET_21
            };
            epochs.push(StacksEpoch {
                epoch_id: *epoch_id,
                start_height,
                end_height,
                block_limit,
                network_epoch: StacksEpochId::network_epoch(*epoch_id),
            });
            if *epoch_id == target_epoch {
                break;
            }
            start_height = end_height;
        }
        EpochList::new(&epochs)
    }

    fn unit_test_2_1_with_heights(
        epoch_2_0_start: u64,
        epoch_2_05_start: u64,
        epoch_2_1_start: u64,
    ) -> EpochList {
        let make = |epoch_id, start_height, end_height| StacksEpoch {
            epoch_id,
            start_height,
            end_height,
            block_limit: ExecutionCost::max_value(),
            network_epoch: StacksEpochId::network_epoch(epoch_id),
        };
        EpochList::new(&[
            make(StacksEpochId::Epoch10, 0, epoch_2_0_start),
            make(StacksEpochId::Epoch20, epoch_2_0_start, epoch_2_05_start),
            make(StacksEpochId::Epoch2_05, epoch_2_05_start, epoch_2_1_start),
            make(StacksEpochId::Epoch21, epoch_2_1_start, STACKS_EPOCH_MAX),
        ])
    }

    /// Verify that a list of epochs is well-formed, and if so, return the list of epochs.
    /// Epochs must proceed in order, and must represent contiguous block ranges.
    /// Panic if the list is not well-formed.
    fn validate_epochs(epochs_ref: &[StacksEpoch]) -> EpochList {
        // sanity check -- epochs must all be contiguous, each epoch must be unique,
        // and the range of epochs should span the whole non-negative i64 space.
        let mut epochs = epochs_ref.to_vec();
        let mut seen_epochs = HashSet::new();
        epochs.sort();

        let latest_epoch = StacksEpochId::latest();
        let max_epoch = epochs_ref
            .iter()
            .max()
            .expect("FATAL: expect at least one epoch");

        let check_epoch_id = peer_network_epoch_check_epoch_id();
        assert_peer_network_epoch(epochs_ref, max_epoch, check_epoch_id);

        let latest_epoch_idx = StacksEpochId::ALL
            .iter()
            .position(|epoch_id| *epoch_id == latest_epoch)
            .expect("FATAL: latest epoch id missing from StacksEpochId::ALL");
        let max_epoch_idx = StacksEpochId::ALL
            .iter()
            .position(|epoch_id| *epoch_id == max_epoch.epoch_id)
            .expect("FATAL: max epoch id missing from StacksEpochId::ALL");

        // Allow epochs up to one version ahead of latest() for development purposes
        assert!(max_epoch_idx <= latest_epoch_idx.saturating_add(1),
            "StacksEpochId::latest() should be greater than or equal to any epoch defined in the node (except for development epochs)"
        );

        let mut epoch_end_height = 0;
        for epoch in epochs.iter() {
            assert!(
                epoch.start_height <= epoch.end_height,
                "{} > {} for {:?}",
                epoch.start_height,
                epoch.end_height,
                &epoch.epoch_id
            );

            if epoch_end_height == 0 {
                // first ever epoch must be defined for all of the prior chain history
                assert_eq!(epoch.start_height, 0);
                epoch_end_height = epoch.end_height;
            } else {
                assert_eq!(epoch_end_height, epoch.start_height);
                epoch_end_height = epoch.end_height;
            }
            if seen_epochs.contains(&epoch.epoch_id) {
                panic!("BUG: duplicate epoch");
            }

            seen_epochs.insert(epoch.epoch_id);
        }

        assert_eq!(epoch_end_height, STACKS_EPOCH_MAX);

        EpochList::new(&epochs)
    }

    /// Validates that Epoch 3.0 activation (if present) satisfies all required safety
    /// invariants for Nakamoto transition, using the provided burnchain configuration.
    ///
    /// This function is only relevant when **Nakamoto epochs** (Epoch 3.0+) exist in the
    /// epoch list. If no post Epoch 2.5 is defined, the function returns early with no checks.
    ///
    /// ### Required Invariants for Safe Epoch 3.0 Activation
    ///
    /// 1. **Epoch 2.5 must exist** and start **before** the prepare phase of the reward
    ///    cycle immediately preceding Epoch 3.0.
    /// 2. **Epoch 2.5 must end exactly at the start of Epoch 3.0** — they are contiguous.
    /// 3. **Epoch 2.5 and Epoch 3.0 must be in different reward cycles**
    /// 4. **Epoch 3.0 must start during a reward phase**, not in a prepare phase.
    /// 5. **Epoch 3.0 must not start at a reward cycle boundary** (i.e., block height
    ///    modulo `reward_cycle_length` must not be 0 or 1).
    /// 6. **Epoch 3.0 must activate at or after reward cycle 2** (cycle 0 and 1 are
    ///    reserved for early network bootstrapping).
    ///
    /// # Parameters
    ///
    /// - `epochs`: List of defined Stacks epochs.
    /// - `burnchain`: Burnchain configuration, providing PoX reward cycle parameters
    ///   (`reward_cycle_length`, `prepare_length`) and height-to-cycle utilities.
    ///
    /// # Panics
    ///
    /// This function panics if any of the invariants fail.
    /// These panics are intended to catch **misconfigured networks** at startup
    fn validate_nakamoto_transition_schedule(epochs: &[StacksEpoch], burnchain: &Burnchain) {
        // Early return if no Nakamoto epochs are defined
        if epochs
            .iter()
            .all(|epoch| epoch.epoch_id < StacksEpochId::Epoch30)
        {
            return;
        }
        let epoch_3_0 = epochs
            .iter()
            .find(|e| e.epoch_id == StacksEpochId::Epoch30)
            .expect("FATAL: Cannot activate Epoch 3.0 without specifying its activation height");
        let epoch_2_5 = epochs
            .iter()
            .find(|e| e.epoch_id == StacksEpochId::Epoch25)
            .expect("FATAL: Epoch 2.5 not found");
        let epoch_3_0_start = epoch_3_0.start_height;
        let epoch_2_5_start = epoch_2_5.start_height;
        let epoch_2_5_end = epoch_2_5.end_height;

        let reward_cycle_length = u64::from(burnchain.pox_constants.reward_cycle_length);
        let prepare_length = u64::from(burnchain.pox_constants.prepare_length);

        assert!(
            !burnchain.is_in_prepare_phase(epoch_3_0_start),
            "FATAL: Epoch 3.0 must start *during* a reward phase, not prepare phase. \
            Activation height: {epoch_3_0_start}, PoX Parameters: {:?}",
            burnchain.pox_constants
        );

        let activation_reward_cycle = burnchain
            .block_height_to_reward_cycle(epoch_3_0_start)
            .expect("FATAL: Epoch 3.0 cannot start before the first burnchain block");
        assert!(
            activation_reward_cycle >= 2,
            "FATAL: Epoch 3.0 must start at or after reward cycle 2. \
            Activation height: {epoch_3_0_start}, cycle: {activation_reward_cycle}, \
            PoX Parameters: {:?}",
            burnchain.pox_constants
        );

        let epoch_2_5_reward_cycle = epoch_2_5_start / reward_cycle_length;
        let epoch_3_0_reward_cycle = epoch_3_0_start / reward_cycle_length;
        // Start of prepare phase in the cycle before Epoch 3.0
        let prior_cycle = epoch_3_0_reward_cycle.saturating_sub(1);
        let epoch_3_0_prepare_phase_start =
            prior_cycle * reward_cycle_length + (reward_cycle_length - prepare_length);
        assert!(
            epoch_2_5_start < epoch_3_0_prepare_phase_start,
            "FATAL: Epoch 2.5 must start before the prepare phase of the cycle prior to Epoch 3.0. \
            Epoch 2.5 start: {epoch_2_5_start}, \
            Epoch 3.0 prior cycle prepare phase start: {epoch_3_0_prepare_phase_start}, \
            PoX Parameters: {:?}",
            burnchain.pox_constants
        );

        assert_eq!(
            epoch_2_5_end, epoch_3_0_start,
            "FATAL: Epoch 2.5 end must equal Epoch 3.0 start. \
            End: {epoch_2_5_end}, Start: {epoch_3_0_start}"
        );

        assert_ne!(
            epoch_2_5_reward_cycle, epoch_3_0_reward_cycle,
            "FATAL: Epoch 2.5 and Epoch 3.0 must not be in the same reward cycle. \
            Epoch 2.5 cycle: {epoch_2_5_reward_cycle}, \
            Epoch 3.0 cycle: {epoch_3_0_reward_cycle}, \
            PoX Parameters: {:?}",
            burnchain.pox_constants
        );

        // Epoch 2.5 has some confusing boundary logic for calculating the reward set hence why
        // the boundary is viewed as both 0 and 1.
        assert!(
            epoch_3_0_start % reward_cycle_length > 1,
            "FATAL: Epoch 3.0 must not start at a reward cycle boundary (offset 0 or 1). \
            Activation height: {epoch_3_0_start}, \
            offset: {}, PoX Parameters: {:?}",
            epoch_3_0_start % reward_cycle_length,
            burnchain.pox_constants
        );
    }
}

// Test/testing variant:
// - Allows older epoch markers (`<= PEER_NETWORK_EPOCH`) to cover back-compat fixtures
//   (e.g. the historical 3.3 release that advertised 3.2).
// - Allows partial epoch lists used by unit tests that intentionally stop before
//   `RELEASE_LATEST_EPOCH`.
#[cfg(any(test, feature = "testing"))]
fn assert_peer_network_epoch(
    epochs_ref: &[StacksEpoch],
    max_epoch: &StacksEpoch,
    check_epoch_id: StacksEpochId,
) {
    if epochs_ref
        .iter()
        .find(|epoch| epoch.epoch_id == check_epoch_id)
        .is_none()
    {
        // Some test-only epoch lists intentionally end before the release latest epoch.
        assert!(
            max_epoch.network_epoch as u32 <= PEER_NETWORK_EPOCH,
            "stacks-blockchain static network epoch should be greater than or equal to the max epoch's"
        );
    } else {
        let check_epoch = epochs_ref
            .iter()
            .find(|epoch| epoch.epoch_id == check_epoch_id)
            .expect("FATAL: check epoch must exist");
        assert!(
            u32::from(check_epoch.network_epoch) <= PEER_NETWORK_EPOCH,
            "stacks-blockchain static network epoch should match {:?}'s network_epoch",
            check_epoch_id
        );
    }
}

// Runtime variant:
// - Enforces strict equality between `PEER_NETWORK_EPOCH` and the release epoch marker.
// - Requires the release epoch to be present in the configured epoch list.
#[cfg(not(any(test, feature = "testing")))]
fn assert_peer_network_epoch(
    epochs_ref: &[StacksEpoch],
    _max_epoch: &StacksEpoch,
    check_epoch_id: StacksEpochId,
) {
    let check_epoch = epochs_ref
        .iter()
        .find(|epoch| epoch.epoch_id == check_epoch_id)
        .unwrap_or_else(|| {
            panic!(
                "FATAL: no {:?} defined in epoch list, cannot validate PEER_NETWORK_EPOCH",
                check_epoch_id
            )
        });
    assert_eq!(
        u32::from(check_epoch.network_epoch),
        PEER_NETWORK_EPOCH,
        "stacks-blockchain static network epoch should match {:?}'s network_epoch",
        check_epoch_id
    );
}

stacks-network / stacks-core / 26829844658-1

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous