bitcoin_units/

block.rs

// SPDX-License-Identifier: CC0-1.0

//! Block height and interval types.
//!
//! These types are thin wrappers around `u32`, no invariants implemented or implied.
//!
//! These are general types for abstracting over block heights, they are not designed for use with
//! lock times. If you are creating lock times you should be using the
//! [`locktime::absolute::Height`] and [`locktime::relative::NumberOfBlocks`] types.
//!
//! The difference between these types and the locktime types is that these types are thin wrappers
//! whereas the locktime types contain more complex locktime specific abstractions.

use core::{fmt, ops};

#[cfg(feature = "arbitrary")]
use arbitrary::{Arbitrary, Unstructured};
#[cfg(feature = "serde")]
use serde::{Deserialize, Deserializer, Serialize, Serializer};

#[cfg(doc)]
use crate::locktime;
use crate::locktime::{absolute, relative};
use crate::parse_int::{self, PrefixedHexError, UnprefixedHexError};

#[rustfmt::skip]                // Keep public re-exports separate.
#[cfg(feature = "encoding")]
#[doc(no_inline)]
pub use self::error::BlockHeightDecoderError;
#[doc(no_inline)]
pub use self::error::TooBigForRelativeHeightError;

macro_rules! impl_u32_wrapper {
    {
        $(#[$($type_attrs:tt)*])*
        $type_vis:vis struct $newtype:ident($inner_vis:vis u32);
    } => {
        $(#[$($type_attrs)*])*
        $type_vis struct $newtype($inner_vis u32);

        impl $newtype {
            #[doc = "Constructs a new [`"]
            #[doc = stringify!($newtype)]
            #[doc = "`] from a prefixed hex string.\n\n"]
            #[doc = "# Errors\n\n"]
            #[doc = "If the input string is not a valid hex representation of a [`"]
            #[doc = stringify!($newtype)]
            #[doc = "`] or it does not include the `0x` prefix."]
            #[inline]
            pub fn from_hex(s: &str) -> Result<Self, PrefixedHexError> {
                let block_height = parse_int::hex_u32_prefixed(s)?;
                Ok(Self(block_height))
            }

            #[doc = "Constructs a new [`"]
            #[doc = stringify!($newtype)]
            #[doc = "`] from an unprefixed hex string.\n\n"]
            #[doc = "# Errors\n\n"]
            #[doc = "If the input string is not a valid hex representation of a [`"]
            #[doc = stringify!($newtype)]
            #[doc = "`] or if it includes the `0x` prefix."]
            #[inline]
            pub fn from_unprefixed_hex(s: &str) -> Result<Self, UnprefixedHexError> {
                let block_height = parse_int::hex_u32_unprefixed(s)?;
                Ok(Self(block_height))
            }
        }

        impl fmt::Display for $newtype {
            #[inline]
            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::Display::fmt(&self.0, f) }
        }

        crate::parse_int::impl_parse_str_from_int_infallible!($newtype, u32, from);

        impl From<u32> for $newtype {
            #[inline]
            fn from(inner: u32) -> Self { Self::from_u32(inner) }
        }

        impl From<$newtype> for u32 {
            #[inline]
            fn from(height: $newtype) -> Self { height.to_u32() }
        }

        #[cfg(feature = "serde")]
        impl Serialize for $newtype {
            #[inline]
            fn serialize<S>(&self, s: S) -> Result<S::Ok, S::Error>
            where
                S: Serializer,
            {
                u32::serialize(&self.to_u32(), s)
            }
        }

        #[cfg(feature = "serde")]
        impl<'de> Deserialize<'de> for $newtype {
            #[inline]
            fn deserialize<D>(d: D) -> Result<Self, D::Error>
            where
                D: Deserializer<'de>,
            {
                Ok(Self::from_u32(u32::deserialize(d)?))
            }
        }

        #[cfg(feature = "arbitrary")]
        impl<'a> Arbitrary<'a> for $newtype {
            #[inline]
            fn arbitrary(u: &mut Unstructured<'a>) -> arbitrary::Result<Self> {
                let choice = u.int_in_range(0..=3)?;
                match choice {
                    0 => Ok(Self::ZERO),
                    1 => Ok(Self::MIN),
                    2 => Ok(Self::MAX),
                    _ => Ok(Self::from_u32(u32::arbitrary(u)?)),
                }
            }
        }
    }
}

impl_u32_wrapper! {
    /// A block height. Zero denotes the genesis block.
    ///
    /// This type is not meant for constructing height based timelocks. It is a general purpose
    /// blockheight abstraction. For locktimes please see [`locktime::absolute::Height`].
    ///
    /// This is a thin wrapper around a `u32` that may take on all values of a `u32`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct BlockHeight(u32);
}

impl BlockHeight {
    /// Block height 0, the genesis block.
    pub const ZERO: Self = Self(0);

    /// The minimum block height (0), the genesis block.
    pub const MIN: Self = Self::ZERO;

    /// The maximum block height.
    pub const MAX: Self = Self(u32::MAX);

    /// Constructs a new block height from a `u32`.
    #[inline]
    pub const fn from_u32(inner: u32) -> Self { Self(inner) }

    /// Returns block height as a `u32`.
    #[inline]
    pub const fn to_u32(self) -> u32 { self.0 }

    /// Attempts to subtract two [`BlockHeight`]s, returning [`None`] if overflow occurred.
    #[inline]
    #[must_use]
    pub fn checked_sub(self, other: Self) -> Option<BlockHeightInterval> {
        self.to_u32().checked_sub(other.to_u32()).map(BlockHeightInterval)
    }

    /// Attempts to add an interval to this [`BlockHeight`], returning [`None`] if overflow
    /// occurred.
    #[inline]
    #[must_use]
    pub fn checked_add(self, other: BlockHeightInterval) -> Option<Self> {
        self.to_u32().checked_add(other.to_u32()).map(Self)
    }

    /// Saturating integer addition.
    ///
    /// Computes self + rhs, saturating at [`BlockHeight::MAX`] instead of overflowing.
    #[inline]
    #[must_use]
    pub const fn saturating_add(self, rhs: BlockHeightInterval) -> Self {
        Self::from_u32(self.to_u32().saturating_add(rhs.to_u32()))
    }

    /// Saturating integer subtraction.
    ///
    /// Computes self - rhs, saturating at [`BlockHeight::MIN`] instead of overflowing.
    #[inline]
    #[must_use]
    pub const fn saturating_sub(self, rhs: BlockHeightInterval) -> Self {
        Self::from_u32(self.to_u32().saturating_sub(rhs.to_u32()))
    }
}

crate::internal_macros::impl_fmt_traits_for_u32_wrapper!(BlockHeight);

impl From<absolute::Height> for BlockHeight {
    /// Converts a [`locktime::absolute::Height`] to a [`BlockHeight`].
    ///
    /// An absolute locktime block height has a maximum value of [`absolute::LOCK_TIME_THRESHOLD`]
    /// minus one, while [`BlockHeight`] may take the full range of `u32`.
    #[inline]
    fn from(h: absolute::Height) -> Self { Self::from_u32(h.to_u32()) }
}

impl TryFrom<BlockHeight> for absolute::Height {
    type Error = absolute::ConversionError;

    /// Converts a [`BlockHeight`] to a [`locktime::absolute::Height`].
    ///
    /// An absolute locktime block height has a maximum value of [`absolute::LOCK_TIME_THRESHOLD`]
    /// minus one, while [`BlockHeight`] may take the full range of `u32`.
    #[inline]
    fn try_from(h: BlockHeight) -> Result<Self, Self::Error> { Self::from_u32(h.to_u32()) }
}

#[cfg(feature = "encoding")]
impl encoding::Encode for BlockHeight {
    type Encoder<'e> = BlockHeightEncoder<'e>;
    #[inline]
    fn encoder(&self) -> Self::Encoder<'_> {
        BlockHeightEncoder::new(encoding::ArrayEncoder::without_length_prefix(
            self.to_u32().to_le_bytes(),
        ))
    }
}

#[cfg(feature = "encoding")]
impl encoding::Decode for BlockHeight {
    type Decoder = BlockHeightDecoder;
}

#[cfg(feature = "encoding")]
encoding::encoder_newtype_exact! {
    /// The encoder for the [`BlockHeight`] type.
    #[derive(Debug, Clone)]
    pub struct BlockHeightEncoder<'e>(encoding::ArrayEncoder<4>);
}

#[cfg(feature = "encoding")]
crate::decoder_newtype! {
    /// The decoder for the [`BlockHeight`] type.
    #[derive(Debug, Clone)]
    pub struct BlockHeightDecoder(encoding::ArrayDecoder<4>);

    /// Constructs a new [`BlockHeight`] decoder.
    pub const fn new() -> Self { Self(encoding::ArrayDecoder::new()) }

    fn end(result: Result<[u8; 4], encoding::UnexpectedEofError>) -> Result<BlockHeight, BlockHeightDecoderError> {
        let value = result.map_err(BlockHeightDecoderError)?;
        let n = u32::from_le_bytes(value);
        Ok(BlockHeight::from_u32(n))
    }
}

impl_u32_wrapper! {
    /// An unsigned block interval.
    ///
    /// Block interval is an integer type representing a difference between the heights of two blocks.
    ///
    /// This type is not meant for constructing relative height based timelocks. It is a general
    /// purpose block interval abstraction. For locktimes please see [`locktime::relative::NumberOfBlocks`].
    #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct BlockHeightInterval(u32);
}

impl BlockHeightInterval {
    /// Block interval 0.
    pub const ZERO: Self = Self(0);

    /// The minimum block interval, equivalent to [`Self::ZERO`].
    pub const MIN: Self = Self::ZERO;

    /// The maximum block interval.
    pub const MAX: Self = Self(u32::MAX);

    /// Constructs a new block interval from a `u32`.
    #[inline]
    pub const fn from_u32(inner: u32) -> Self { Self(inner) }

    /// Returns block interval as a `u32`.
    #[inline]
    pub const fn to_u32(self) -> u32 { self.0 }

    /// Attempts to subtract two [`BlockHeightInterval`]s, returning [`None`] if overflow occurred.
    #[inline]
    #[must_use]
    pub fn checked_sub(self, other: Self) -> Option<Self> {
        self.to_u32().checked_sub(other.to_u32()).map(Self)
    }

    /// Attempts to add two [`BlockHeightInterval`]s, returning [`None`] if overflow occurred.
    #[inline]
    #[must_use]
    pub fn checked_add(self, other: Self) -> Option<Self> {
        self.to_u32().checked_add(other.to_u32()).map(Self)
    }
}

crate::internal_macros::impl_fmt_traits_for_u32_wrapper!(BlockHeightInterval);

impl From<relative::NumberOfBlocks> for BlockHeightInterval {
    /// Converts a [`locktime::relative::NumberOfBlocks`] to a [`BlockHeightInterval`].
    ///
    /// A relative locktime block height has a maximum value of `u16::MAX` where as a
    /// [`BlockHeightInterval`] is a thin wrapper around a `u32`, the two types are not interchangeable.
    #[inline]
    fn from(h: relative::NumberOfBlocks) -> Self { Self::from_u32(h.to_count().into()) }
}

impl TryFrom<BlockHeightInterval> for relative::NumberOfBlocks {
    type Error = TooBigForRelativeHeightError;

    /// Converts a [`BlockHeightInterval`] to a [`locktime::relative::NumberOfBlocks`].
    ///
    /// A relative locktime block height has a maximum value of `u16::MAX` where as a
    /// [`BlockHeightInterval`] is a thin wrapper around a `u32`, the two types are not interchangeable.
    #[inline]
    fn try_from(h: BlockHeightInterval) -> Result<Self, Self::Error> {
        u16::try_from(h.to_u32())
            .map(Self::from_count)
            .map_err(|_| TooBigForRelativeHeightError(h.into()))
    }
}

impl_u32_wrapper! {
    /// The median timestamp of 11 consecutive blocks.
    ///
    /// This type is not meant for constructing time-based timelocks. It is a general purpose
    /// MTP abstraction. For locktimes please see [`locktime::absolute::MedianTimePast`].
    ///
    /// This is a thin wrapper around a `u32` that may take on all values of a `u32`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct BlockMtp(u32);
}

impl BlockMtp {
    /// Block MTP 0.
    ///
    /// Since MTP is a timestamp, 0 is before Bitcoin was invented. This const may still be useful
    /// for some use cases e.g., folding a sum of intervals.
    pub const ZERO: Self = Self(0);

    /// The minimum block MTP, equivalent to [`Self::ZERO`].
    pub const MIN: Self = Self::ZERO;

    /// The maximum block MTP.
    pub const MAX: Self = Self(u32::MAX);

    /// Constructs a new block MTP from a `u32`.
    #[inline]
    pub const fn from_u32(inner: u32) -> Self { Self(inner) }

    /// Returns block MTP as a `u32`.
    #[inline]
    pub const fn to_u32(self) -> u32 { self.0 }

    /// Constructs a [`BlockMtp`] by computing the median-time-past from the last 11 block timestamps.
    ///
    /// Because block timestamps are not monotonic, this function internally sorts them;
    /// it is therefore not important what order they appear in the array; use whatever
    /// is most convenient.
    #[inline]
    pub fn new(mut timestamps: [crate::BlockTime; 11]) -> Self {
        timestamps.sort_unstable();
        Self::from_u32(u32::from(timestamps[5]))
    }

    /// Attempts to subtract two [`BlockMtp`]s, returning [`None`] if overflow occurred.
    #[inline]
    #[must_use]
    pub fn checked_sub(self, other: Self) -> Option<BlockMtpInterval> {
        self.to_u32().checked_sub(other.to_u32()).map(BlockMtpInterval)
    }

    /// Attempts to add an interval to this [`BlockMtp`], returning [`None`] if overflow occurred.
    #[inline]
    #[must_use]
    pub fn checked_add(self, other: BlockMtpInterval) -> Option<Self> {
        self.to_u32().checked_add(other.to_u32()).map(Self)
    }
}

crate::internal_macros::impl_fmt_traits_for_u32_wrapper!(BlockMtp);

impl From<absolute::MedianTimePast> for BlockMtp {
    /// Converts a [`locktime::absolute::MedianTimePast`] to a [`BlockMtp`].
    ///
    /// An absolute locktime MTP has a minimum value of [`absolute::LOCK_TIME_THRESHOLD`],
    /// while [`BlockMtp`] may take the full range of `u32`.
    #[inline]
    fn from(h: absolute::MedianTimePast) -> Self { Self::from_u32(h.to_u32()) }
}

impl TryFrom<BlockMtp> for absolute::MedianTimePast {
    type Error = absolute::ConversionError;

    /// Converts a [`BlockMtp`] to a [`locktime::absolute::MedianTimePast`].
    ///
    /// An absolute locktime MTP has a minimum value of [`absolute::LOCK_TIME_THRESHOLD`],
    /// while [`BlockMtp`] may take the full range of `u32`.
    #[inline]
    fn try_from(h: BlockMtp) -> Result<Self, Self::Error> { Self::from_u32(h.to_u32()) }
}

impl_u32_wrapper! {
    /// An unsigned difference between two [`BlockMtp`]s.
    ///
    /// This type is not meant for constructing time-based timelocks. It is a general purpose
    /// MTP abstraction. For locktimes please see [`locktime::relative::NumberOf512Seconds`].
    ///
    /// This is a thin wrapper around a `u32` that may take on all values of a `u32`.
    #[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct BlockMtpInterval(u32);
}

impl BlockMtpInterval {
    /// Block MTP interval 0.
    pub const ZERO: Self = Self(0);

    /// The minimum block MTP interval, equivalent to [`Self::ZERO`].
    pub const MIN: Self = Self::ZERO;

    /// The maximum block MTP interval.
    pub const MAX: Self = Self(u32::MAX);

    /// Constructs a new block MTP interval from a `u32`.
    #[inline]
    pub const fn from_u32(inner: u32) -> Self { Self(inner) }

    /// Returns block MTP interval as a `u32`.
    #[inline]
    pub const fn to_u32(self) -> u32 { self.0 }

    /// Converts a [`BlockMtpInterval`] to a [`locktime::relative::NumberOf512Seconds`], rounding down.
    ///
    /// Relative timelock MTP intervals have a resolution of 512 seconds, while
    /// [`BlockMtpInterval`], like all block timestamp types, has a one-second resolution.
    ///
    /// # Errors
    ///
    /// Errors if the MTP is out-of-range (in excess of 512 times `u16::MAX` seconds, or about
    /// 388 days) for a time-based relative locktime.
    #[inline]
    pub const fn to_relative_mtp_interval_floor(
        self,
    ) -> Result<relative::NumberOf512Seconds, relative::TimeOverflowError> {
        relative::NumberOf512Seconds::from_seconds_floor(self.to_u32())
    }

    /// Converts a [`BlockMtpInterval`] to a [`locktime::relative::NumberOf512Seconds`], rounding up.
    ///
    /// Relative timelock MTP intervals have a resolution of 512 seconds, while
    /// [`BlockMtpInterval`], like all block timestamp types, has a one-second resolution.
    ///
    /// # Errors
    ///
    /// Errors if the MTP is out-of-range (in excess of 512 times `u16::MAX` seconds, or about
    /// 388 days) for a time-based relative locktime.
    #[inline]
    pub const fn to_relative_mtp_interval_ceil(
        self,
    ) -> Result<relative::NumberOf512Seconds, relative::TimeOverflowError> {
        relative::NumberOf512Seconds::from_seconds_ceil(self.to_u32())
    }

    /// Attempts to subtract two [`BlockMtpInterval`]s, returning [`None`] if overflow occurred.
    #[inline]
    #[must_use]
    pub fn checked_sub(self, other: Self) -> Option<Self> {
        self.to_u32().checked_sub(other.to_u32()).map(Self)
    }

    /// Attempts to add two [`BlockMtpInterval`]s, returning [`None`] if overflow occurred.
    #[inline]
    #[must_use]
    pub fn checked_add(self, other: Self) -> Option<Self> {
        self.to_u32().checked_add(other.to_u32()).map(Self)
    }
}

crate::internal_macros::impl_fmt_traits_for_u32_wrapper!(BlockMtpInterval);

impl From<relative::NumberOf512Seconds> for BlockMtpInterval {
    /// Converts a [`locktime::relative::NumberOf512Seconds`] to a [`BlockMtpInterval`].
    ///
    /// A relative locktime MTP interval has a resolution of 512 seconds, and a maximum value
    /// of `u16::MAX` 512-second intervals. [`BlockMtpInterval`] may take the full range of
    /// `u32`.
    #[inline]
    fn from(h: relative::NumberOf512Seconds) -> Self { Self::from_u32(h.to_seconds()) }
}

crate::internal_macros::impl_op_for_references! {
    // height - height = interval
    impl ops::Sub<BlockHeight> for BlockHeight {
        type Output = BlockHeightInterval;

        #[track_caller]
        fn sub(self, rhs: BlockHeight) -> Self::Output {
            let interval = self.to_u32() - rhs.to_u32();
            BlockHeightInterval::from_u32(interval)
        }
    }

    // height + interval = height
    impl ops::Add<BlockHeightInterval> for BlockHeight {
        type Output = BlockHeight;

        #[track_caller]
        fn add(self, rhs: BlockHeightInterval) -> Self::Output {
            let height = self.to_u32() + rhs.to_u32();
            BlockHeight::from_u32(height)
        }
    }

    // height - interval = height
    impl ops::Sub<BlockHeightInterval> for BlockHeight {
        type Output = BlockHeight;

        #[track_caller]
        fn sub(self, rhs: BlockHeightInterval) -> Self::Output {
            let height = self.to_u32() - rhs.to_u32();
            BlockHeight::from_u32(height)
        }
    }

    // interval + interval = interval
    impl ops::Add<BlockHeightInterval> for BlockHeightInterval {
        type Output = BlockHeightInterval;

        #[track_caller]
        fn add(self, rhs: BlockHeightInterval) -> Self::Output {
            let height = self.to_u32() + rhs.to_u32();
            BlockHeightInterval::from_u32(height)
        }
    }

    // interval - interval = interval
    impl ops::Sub<BlockHeightInterval> for BlockHeightInterval {
        type Output = BlockHeightInterval;

        #[track_caller]
        fn sub(self, rhs: BlockHeightInterval) -> Self::Output {
            let height = self.to_u32() - rhs.to_u32();
            BlockHeightInterval::from_u32(height)
        }
    }

    // height - height = interval
    impl ops::Sub<BlockMtp> for BlockMtp {
        type Output = BlockMtpInterval;

        #[track_caller]
        fn sub(self, rhs: BlockMtp) -> Self::Output {
            let interval = self.to_u32() - rhs.to_u32();
            BlockMtpInterval::from_u32(interval)
        }
    }

    // height + interval = height
    impl ops::Add<BlockMtpInterval> for BlockMtp {
        type Output = BlockMtp;

        #[track_caller]
        fn add(self, rhs: BlockMtpInterval) -> Self::Output {
            let height = self.to_u32() + rhs.to_u32();
            BlockMtp::from_u32(height)
        }
    }

    // height - interval = height
    impl ops::Sub<BlockMtpInterval> for BlockMtp {
        type Output = BlockMtp;

        #[track_caller]
        fn sub(self, rhs: BlockMtpInterval) -> Self::Output {
            let height = self.to_u32() - rhs.to_u32();
            BlockMtp::from_u32(height)
        }
    }

    // interval + interval = interval
    impl ops::Add<BlockMtpInterval> for BlockMtpInterval {
        type Output = BlockMtpInterval;

        #[track_caller]
        fn add(self, rhs: BlockMtpInterval) -> Self::Output {
            let height = self.to_u32() + rhs.to_u32();
            BlockMtpInterval::from_u32(height)
        }
    }

    // interval - interval = interval
    impl ops::Sub<BlockMtpInterval> for BlockMtpInterval {
        type Output = BlockMtpInterval;

        #[track_caller]
        fn sub(self, rhs: BlockMtpInterval) -> Self::Output {
            let height = self.to_u32() - rhs.to_u32();
            BlockMtpInterval::from_u32(height)
        }
    }
}

crate::internal_macros::impl_add_assign!(BlockHeightInterval);
crate::internal_macros::impl_sub_assign!(BlockHeightInterval);
crate::internal_macros::impl_add_assign!(BlockMtpInterval);
crate::internal_macros::impl_sub_assign!(BlockMtpInterval);

impl core::iter::Sum for BlockHeightInterval {
    #[inline]
    fn sum<I: Iterator<Item = Self>>(iter: I) -> Self {
        let sum = iter.map(Self::to_u32).sum();
        Self::from_u32(sum)
    }
}

impl<'a> core::iter::Sum<&'a Self> for BlockHeightInterval {
    #[inline]
    fn sum<I>(iter: I) -> Self
    where
        I: Iterator<Item = &'a Self>,
    {
        let sum = iter.map(|interval| interval.to_u32()).sum();
        Self::from_u32(sum)
    }
}

impl core::iter::Sum for BlockMtpInterval {
    #[inline]
    fn sum<I: Iterator<Item = Self>>(iter: I) -> Self {
        let sum = iter.map(Self::to_u32).sum();
        Self::from_u32(sum)
    }
}

impl<'a> core::iter::Sum<&'a Self> for BlockMtpInterval {
    #[inline]
    fn sum<I>(iter: I) -> Self
    where
        I: Iterator<Item = &'a Self>,
    {
        let sum = iter.map(|interval| interval.to_u32()).sum();
        Self::from_u32(sum)
    }
}

/// Error types for block height and interval types.
pub mod error {
    use core::convert::Infallible;
    use core::fmt;

    #[cfg(feature = "encoding")]
    use internals::write_err;

    use crate::locktime::relative;

    /// Error returned when the block interval is too big to be used as a relative lock time.
    #[derive(Debug, Clone, PartialEq, Eq)]
    pub struct TooBigForRelativeHeightError(pub(super) u32);

    impl From<Infallible> for TooBigForRelativeHeightError {
        #[inline]
        fn from(never: Infallible) -> Self { match never {} }
    }

    impl fmt::Display for TooBigForRelativeHeightError {
        #[inline]
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
            write!(
                f,
                "block interval is too big to be used as a relative lock time: {} (max: {})",
                self.0,
                relative::NumberOfBlocks::MAX
            )
        }
    }

    #[cfg(feature = "std")]
    impl std::error::Error for TooBigForRelativeHeightError {
        #[inline]
        fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
            let Self(_) = self;
            None
        }
    }

    /// An error consensus decoding a [`BlockHeight`].
    ///
    /// [`BlockHeight`]: super::BlockHeight
    #[cfg(feature = "encoding")]
    #[derive(Debug, Clone, PartialEq, Eq)]
    pub struct BlockHeightDecoderError(pub(super) encoding::UnexpectedEofError);

    #[cfg(feature = "encoding")]
    impl From<Infallible> for BlockHeightDecoderError {
        #[inline]
        fn from(never: Infallible) -> Self { match never {} }
    }

    #[cfg(feature = "encoding")]
    impl fmt::Display for BlockHeightDecoderError {
        #[inline]
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
            write_err!(f, "block height decoder error"; self.0)
        }
    }

    #[cfg(feature = "encoding")]
    #[cfg(feature = "std")]
    impl std::error::Error for BlockHeightDecoderError {
        #[inline]
        fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { Some(&self.0) }
    }
}

#[cfg(test)]
mod tests {
    #[cfg(feature = "alloc")]
    use alloc::string::ToString;
    #[cfg(feature = "std")]
    use std::error::Error;

    #[cfg(feature = "encoding")]
    use encoding::{Decode as _, Decoder as _, UnexpectedEofError};

    use super::*;
    use crate::relative::{NumberOf512Seconds, TimeOverflowError};

    #[test]
    fn sanity_check() {
        let height: u32 = BlockHeight(100).into();
        assert_eq!(height, 100);

        let interval: u32 = BlockHeightInterval(100).into();
        assert_eq!(interval, 100);

        let interval_from_height: BlockHeightInterval =
            relative::NumberOfBlocks::from_count(10).into();
        assert_eq!(interval_from_height.to_u32(), 10u32);

        let invalid_height_greater =
            relative::NumberOfBlocks::try_from(BlockHeightInterval(u32::from(u16::MAX) + 1));
        assert!(invalid_height_greater.is_err());

        let valid_height =
            relative::NumberOfBlocks::try_from(BlockHeightInterval(u32::from(u16::MAX)));
        assert!(valid_height.is_ok());
    }

    // These tests are supposed to comprise an exhaustive list of available operations.
    #[test]
    fn all_available_ops() {
        // height - height = interval
        assert!(BlockHeight(10) - BlockHeight(7) == BlockHeightInterval(3));

        // height + interval = height
        assert!(BlockHeight(100) + BlockHeightInterval(1) == BlockHeight(101));

        // height - interval == height
        assert!(BlockHeight(100) - BlockHeightInterval(1) == BlockHeight(99));

        // interval + interval = interval
        assert!(BlockHeightInterval(1) + BlockHeightInterval(2) == BlockHeightInterval(3));

        // interval - interval = interval
        assert!(BlockHeightInterval(10) - BlockHeightInterval(7) == BlockHeightInterval(3));

        // Sum for BlockHeightInterval by reference and by value
        assert!(
            [BlockHeightInterval(1), BlockHeightInterval(2), BlockHeightInterval(3)]
                .iter()
                .sum::<BlockHeightInterval>()
                == BlockHeightInterval(6)
        );
        assert!(
            [BlockHeightInterval(4), BlockHeightInterval(5), BlockHeightInterval(6)]
                .into_iter()
                .sum::<BlockHeightInterval>()
                == BlockHeightInterval(15)
        );

        // Sum for BlockMtpInterval by reference and by value
        assert!(
            [BlockMtpInterval(1), BlockMtpInterval(2), BlockMtpInterval(3)]
                .iter()
                .sum::<BlockMtpInterval>()
                == BlockMtpInterval(6)
        );
        assert!(
            [BlockMtpInterval(4), BlockMtpInterval(5), BlockMtpInterval(6)]
                .into_iter()
                .sum::<BlockMtpInterval>()
                == BlockMtpInterval(15)
        );

        // interval += interval
        let mut int = BlockHeightInterval(1);
        int += BlockHeightInterval(2);
        assert_eq!(int, BlockHeightInterval(3));

        // interval -= interval
        let mut int = BlockHeightInterval(10);
        int -= BlockHeightInterval(7);
        assert_eq!(int, BlockHeightInterval(3));
    }

    #[test]
    fn block_height_checked() {
        let a = BlockHeight(10);
        let b = BlockHeight(5);
        assert_eq!(a.checked_sub(b), Some(BlockHeightInterval(5)));
        assert_eq!(a.checked_add(BlockHeightInterval(5)), Some(BlockHeight(15)));
        assert_eq!(a.checked_sub(BlockHeight(11)), None);
        assert_eq!(a.checked_add(BlockHeightInterval(u32::MAX - 5)), None);
    }

    #[test]
    fn block_height_interval_checked() {
        let a = BlockHeightInterval(10);
        let b = BlockHeightInterval(5);
        assert_eq!(a.checked_sub(b), Some(BlockHeightInterval(5)));
        assert_eq!(a.checked_add(b), Some(BlockHeightInterval(15)));
        assert_eq!(a.checked_sub(BlockHeightInterval(11)), None);
        assert_eq!(a.checked_add(BlockHeightInterval(u32::MAX - 5)), None);
    }

    #[test]
    fn block_mtp_interval_checked() {
        let a = BlockMtpInterval(10);
        let b = BlockMtpInterval(5);
        assert_eq!(a.checked_sub(b), Some(BlockMtpInterval(5)));
        assert_eq!(a.checked_add(b), Some(BlockMtpInterval(15)));
        assert_eq!(a.checked_sub(BlockMtpInterval(11)), None);
        assert_eq!(a.checked_add(BlockMtpInterval(u32::MAX - 5)), None);
    }

    #[test]
    fn block_mtp_checked() {
        let a = BlockMtp(10);
        let b = BlockMtp(5);
        assert_eq!(a.checked_sub(b), Some(BlockMtpInterval(5)));
        assert_eq!(a.checked_add(BlockMtpInterval(5)), Some(BlockMtp(15)));
        assert_eq!(a.checked_sub(BlockMtp(11)), None);
        assert_eq!(a.checked_add(BlockMtpInterval(u32::MAX - 5)), None);
    }

    #[test]
    fn block_mtp_interval_from_number_of_512seconds() {
        let n = NumberOf512Seconds::from_seconds_floor(0).unwrap();
        let interval = BlockMtpInterval::from(n);
        assert_eq!(interval, BlockMtpInterval(0));
        let n = NumberOf512Seconds::from_seconds_floor(1024).unwrap();
        let interval = BlockMtpInterval::from(n);
        assert_eq!(interval, BlockMtpInterval(1024));
    }

    #[test]
    fn block_mtp_interval_to_relative_mtp_floor() {
        let time = NumberOf512Seconds::from_512_second_intervals(0);
        let interval = BlockMtpInterval::from_u32(0);
        assert_eq!(interval.to_relative_mtp_interval_floor().unwrap(), time);

        let time = NumberOf512Seconds::from_512_second_intervals(1);
        let interval = BlockMtpInterval::from_u32(1023);
        assert_eq!(interval.to_relative_mtp_interval_floor().unwrap(), time); // Should floor down to 1
        assert_ne!(interval.to_relative_mtp_interval_ceil().unwrap(), time); // Should ceil up to 2

        // Check overflow limit
        let max_time = NumberOf512Seconds::from_512_second_intervals(u16::MAX);
        let max_seconds = u32::from(u16::MAX) * 512 + 511;

        let interval = BlockMtpInterval::from_u32(max_seconds);
        assert_eq!(interval.to_relative_mtp_interval_floor().unwrap(), max_time);
        let interval = BlockMtpInterval::from_u32(max_seconds + 1);
        assert_eq!(
            interval.to_relative_mtp_interval_floor().unwrap_err(),
            TimeOverflowError { seconds: max_seconds + 1 }
        );
    }

    #[test]
    fn block_mtp_interval_to_relative_mtp_ceil() {
        let time = NumberOf512Seconds::from_512_second_intervals(0);
        let interval = BlockMtpInterval::from_u32(0);
        assert_eq!(interval.to_relative_mtp_interval_ceil().unwrap(), time);

        let time = NumberOf512Seconds::from_512_second_intervals(2);
        let interval = BlockMtpInterval::from_u32(1023);
        assert_eq!(interval.to_relative_mtp_interval_ceil().unwrap(), time); // Should ceil up to 2
        assert_ne!(interval.to_relative_mtp_interval_floor().unwrap(), time); // Should floor down to 1

        // Check overflow limit
        let max_time = NumberOf512Seconds::from_512_second_intervals(u16::MAX);
        let max_seconds = u32::from(u16::MAX) * 512;

        let interval = BlockMtpInterval::from_u32(max_seconds);
        assert_eq!(interval.to_relative_mtp_interval_ceil().unwrap(), max_time);
        let interval = BlockMtpInterval::from_u32(max_seconds + 1);
        assert_eq!(
            interval.to_relative_mtp_interval_ceil().unwrap_err(),
            TimeOverflowError { seconds: max_seconds + 1 }
        );
    }

    #[test]
    #[cfg(feature = "encoding")]
    fn block_height_decoding_error() {
        let bytes = [0xff, 0xff, 0xff]; // 3 bytes is an EOF error

        let mut decoder = BlockHeightDecoder::default();
        assert!(decoder.push_bytes(&mut bytes.as_slice()).unwrap().needs_more());

        let error = decoder.end().unwrap_err();
        assert!(matches!(error, BlockHeightDecoderError(UnexpectedEofError { .. })));
    }

    // Test a impl_u32_wrapper! type serde serialisation roundtrip.
    macro_rules! serde_roundtrip_test {
        { $test_name:tt, $typ:ident } => {
            #[test]
            #[cfg(feature = "serde")]
            fn $test_name() {
                let t = $typ(1_654_321);

                let json = serde_json::to_string(&t).unwrap();
                assert_eq!(json, "1654321"); // ASCII number representation

                let roundtrip = serde_json::from_str::<$typ>(&json).unwrap();
                assert_eq!(t, roundtrip);
            }
        }
    }

    serde_roundtrip_test!(block_height_serde_round_trip, BlockHeight);
    serde_roundtrip_test!(block_height_interval_serde_round_trip, BlockHeightInterval);
    serde_roundtrip_test!(block_mtp_serde_round_trip, BlockMtp);
    serde_roundtrip_test!(block_mtp_interval_serde_round_trip, BlockMtpInterval);

    #[test]
    fn block_height_saturating_add() {
        // Normal addition
        assert_eq!(BlockHeight(100).saturating_add(BlockHeightInterval(50)), BlockHeight(150),);
        assert_eq!(BlockHeight::ZERO.saturating_add(BlockHeightInterval(1)), BlockHeight(1),);

        // Saturates at MAX instead of overflowing
        assert_eq!(BlockHeight::MAX.saturating_add(BlockHeightInterval(1)), BlockHeight::MAX,);
        assert_eq!(BlockHeight::MAX.saturating_add(BlockHeightInterval(100)), BlockHeight::MAX,);
        assert_eq!(
            BlockHeight(u32::MAX - 10).saturating_add(BlockHeightInterval(20)),
            BlockHeight::MAX,
        );

        // Adding zero
        assert_eq!(BlockHeight(500).saturating_add(BlockHeightInterval::ZERO), BlockHeight(500),);
    }

    #[test]
    fn block_height_saturating_sub() {
        // Normal subtraction
        assert_eq!(BlockHeight(100).saturating_sub(BlockHeightInterval(50)), BlockHeight(50),);
        assert_eq!(BlockHeight(100).saturating_sub(BlockHeightInterval(100)), BlockHeight(0),);

        // Saturates at MIN instead of underflowing
        assert_eq!(BlockHeight::MIN.saturating_sub(BlockHeightInterval(1)), BlockHeight::MIN,);
        assert_eq!(BlockHeight::ZERO.saturating_sub(BlockHeightInterval(100)), BlockHeight::ZERO,);
        assert_eq!(BlockHeight(10).saturating_sub(BlockHeightInterval(20)), BlockHeight::ZERO,);

        // Subtracting zero
        assert_eq!(BlockHeight(500).saturating_sub(BlockHeightInterval::ZERO), BlockHeight(500),);
    }

    #[test]
    #[cfg(feature = "alloc")]
    fn error_display_is_non_empty() {
        // TooBigForRelativeHeightError - block interval too big for relative height
        let big_interval = BlockHeightInterval::from_u32(u32::MAX);
        let e = relative::NumberOfBlocks::try_from(big_interval).unwrap_err();
        assert!(!e.to_string().is_empty());
        #[cfg(feature = "std")]
        assert!(e.source().is_none());

        #[cfg(feature = "encoding")]
        {
            // BlockHeightDecoderError
            let mut decoder = BlockHeight::decoder();
            let _ = decoder.push_bytes(&mut [0u8; 3].as_slice());
            let e = decoder.end().unwrap_err();
            assert!(!e.to_string().is_empty());
            #[cfg(feature = "std")]
            assert!(e.source().is_some());
        }
    }
}