bsv-rs 0.8.3

BSV SDK for Rust: primitives, the script interpreter, transactions and BEEF/SPV, BRC-42 wallets, BRC-103 auth, the overlay network. Reference parity with the TypeScript SDK, native and wasm32.
Documentation
//! Proof-of-work parameters: bitcoin-sv@6504a3af `src/chainparams.cpp`
//! (`CMainParams` 1033-1160, `CTestNetParams` 1329-1428, `CRegTestParams`
//! 1456-1533) and `src/consensus/params.h:41-49`. Checkpoints, the genesis
//! hash and every other chain parameter belong to the host.

use super::{POW_LIMIT_MAIN, POW_LIMIT_REGTEST, POW_LIMIT_TEST};
use crate::primitives::U256;

/// Two weeks: `consensus.nPowTargetTimespan` on every chain
/// (src/chainparams.cpp:1050, 1346, 1474).
const TWO_WEEKS: i64 = 14 * 24 * 60 * 60;
/// Ten minutes: `consensus.nPowTargetSpacing` on every chain
/// (src/chainparams.cpp:1051, 1347, 1475).
const TEN_MINUTES: i64 = 10 * 60;

/// The consensus parameters `GetNextWorkRequired` reads, per chain.
///
/// The fields are public so a host can describe another chain starting from
/// one of the constructors; new fields may be added in a minor release.
/// ```
/// use bsv_rs::block::ChainParams;
/// let main = ChainParams::main();
/// assert_eq!(main.difficulty_adjustment_interval(), 2016);
/// assert_eq!(main.pow_limit_bits(), 0x1d00ffff);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct ChainParams {
    /// `consensus.powLimit`: the easiest target a header may carry.
    pub pow_limit: U256,
    /// `consensus.nPowTargetSpacing`, seconds.
    pub pow_target_spacing: i64,
    /// `consensus.nPowTargetTimespan`, seconds.
    pub pow_target_timespan: i64,
    /// `consensus.fPowAllowMinDifficultyBlocks`: testnet's 20-minute rule.
    pub allow_min_difficulty_blocks: bool,
    /// `consensus.fPowNoRetargeting`: regtest's constant difficulty.
    pub no_retargeting: bool,
    /// `consensus.daaHeight`: the DAA governs a header whose parent is at or
    /// above this height (src/pow.cpp:111).
    pub daa_height: u32,
}

impl ChainParams {
    /// `CMainParams` (src/chainparams.cpp:1047-1053, `daaHeight` 504031 at 1068).
    /// ```
    /// assert_eq!(bsv_rs::block::ChainParams::main().daa_height, 504_031);
    /// ```
    pub fn main() -> Self {
        Self {
            pow_limit: POW_LIMIT_MAIN,
            pow_target_spacing: TEN_MINUTES,
            pow_target_timespan: TWO_WEEKS,
            allow_min_difficulty_blocks: false,
            no_retargeting: false,
            daa_height: 504_031,
        }
    }

    /// `CTestNetParams` (src/chainparams.cpp:1343-1349, the minimum-difficulty
    /// rule on; `daaHeight` 1188697 at 1364).
    /// ```
    /// assert!(bsv_rs::block::ChainParams::test().allow_min_difficulty_blocks);
    /// ```
    pub fn test() -> Self {
        Self {
            pow_limit: POW_LIMIT_TEST,
            pow_target_spacing: TEN_MINUTES,
            pow_target_timespan: TWO_WEEKS,
            allow_min_difficulty_blocks: true,
            no_retargeting: false,
            daa_height: 1_188_697,
        }
    }

    /// `CRegTestParams` (src/chainparams.cpp:1471-1477, no retargeting;
    /// `daaHeight` 0 at 1490).
    /// ```
    /// let regtest = bsv_rs::block::ChainParams::regtest();
    /// assert!(regtest.no_retargeting);
    /// assert_eq!(regtest.pow_limit_bits(), 0x207fffff);
    /// ```
    pub fn regtest() -> Self {
        Self {
            pow_limit: POW_LIMIT_REGTEST,
            pow_target_spacing: TEN_MINUTES,
            pow_target_timespan: TWO_WEEKS,
            allow_min_difficulty_blocks: true,
            no_retargeting: true,
            daa_height: 0,
        }
    }

    /// `DifficultyAdjustmentInterval()` (src/consensus/params.h:47-49); zero
    /// for a spacing of zero, where the node divides by zero.
    /// ```
    /// assert_eq!(bsv_rs::block::ChainParams::test().difficulty_adjustment_interval(), 2016);
    /// ```
    pub fn difficulty_adjustment_interval(&self) -> i64 {
        self.pow_target_timespan
            .checked_div(self.pow_target_spacing)
            .unwrap_or(0)
    }

    /// `GetCompact(powLimit)`: the bits of a minimum-difficulty header, and
    /// `GetNextWorkRequired`'s answer for the genesis (src/pow.cpp:101-104).
    /// ```
    /// assert_eq!(bsv_rs::block::ChainParams::main().pow_limit_bits(), 0x1d00ffff);
    /// ```
    pub fn pow_limit_bits(&self) -> u32 {
        self.pow_limit.to_compact()
    }

    /// How many headers, ending at the parent, `next_work_required` may read
    /// for a header whose parent is at `prev_height`: the parent alone under
    /// regtest's rule; 147 under the DAA (the parent back to the median of
    /// three around `prev - 144`); a full interval for the legacy retarget at
    /// a boundary and for testnet's walk back; 17 for the emergency
    /// adjustment (the median time past at `prev - 6`). Never more than the
    /// chain holds.
    /// ```
    /// use bsv_rs::block::ChainParams;
    /// assert_eq!(ChainParams::main().window_depth(886_000), 147);
    /// assert_eq!(ChainParams::regtest().window_depth(886_000), 1);
    /// ```
    pub fn window_depth(&self, prev_height: u32) -> u32 {
        let depth = if self.no_retargeting {
            1
        } else if prev_height >= self.daa_height {
            147
        } else {
            let interval = self.difficulty_adjustment_interval();
            if self.allow_min_difficulty_blocks
                || (i64::from(prev_height) + 1).checked_rem(interval) == Some(0)
            {
                u32::try_from(interval).unwrap_or(u32::MAX)
            } else {
                17
            }
        };
        depth.min(prev_height.saturating_add(1))
    }
}