Struct BlockHeight

pub struct BlockHeight(/* private fields */);

A block’s position in the blockchain, represented as a distance from the genesis block.

BlockHeight represents the number of blocks between a specific block and the genesis block (block zero). Each block increments the height by one, forming a total ordering that defines the blockchain’s canonical sequence.

Zcash Concept Relation

In Zcash, like Bitcoin, block height is crucial for:

• Identifying when transactions were confirmed
• Determining when network upgrades activate
• Calculating confirmation counts
• Anchoring shielded transactions to specific blockchain states

Many Zcash protocol parameters are defined in terms of block heights, including upgrade activation heights and consensus rule changes.

Data Preservation

BlockHeight preserves the numeric height values from wallet data, which are essential for chronological ordering of transactions and for determining whether specific network features were active when a transaction was created.

Implementation Details

Internally, block heights are stored as unsigned 32-bit integers, which can represent blocks up to approximately 136 years into the future at Zcash’s target rate of one block every 75 seconds.

Examples

// The genesis block
let genesis = BlockHeight::from(0u32);

// Block #1,000,000
let millionth = BlockHeight::from(1_000_000u32);

// Calculate difference between blocks
let blocks_between = millionth - genesis;
assert_eq!(blocks_between, 1_000_000);

Implementations

impl BlockHeight

pub const fn from_u32(v: u32) -> BlockHeight

Creates a new BlockHeight from a u32 value.

This constructor is a const fn, which allows it to be used in constant expressions.

Examples

// Create a constant block height
const CANOPY_ACTIVATION: BlockHeight = BlockHeight::from_u32(1_046_400);

pub fn saturating_sub(self, v: u32) -> BlockHeight

Subtracts the provided value from this height, returning H0 if this would result in underflow of the wrapped u32.

This method ensures that block height calculations never underflow below the genesis block (height 0), which would be an invalid state in a blockchain.

Examples

let height = BlockHeight::from(100u32);

// Normal subtraction
let earlier = height.saturating_sub(50);
assert_eq!(u32::from(earlier), 50);

// Saturating at genesis block (0) when underflow would occur
let genesis = height.saturating_sub(200); // Would be -100, saturates to 0
assert_eq!(u32::from(genesis), 0);

Trait Implementations

impl Add<u32> for BlockHeight

Adds a block count to a height, with saturation to prevent overflow

type Output = BlockHeight

The resulting type after applying the + operator.

fn add(self, other: u32) -> Self

Performs the + operation.

impl Clone for BlockHeight

fn clone(&self) -> BlockHeight

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BlockHeight

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for BlockHeight

Displays the block height as a plain number

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&BlockHeight> for CBOR

fn from(value: &BlockHeight) -> Self

Converts to this type from the input type.

impl From<BlockHeight> for CBOR

fn from(value: BlockHeight) -> Self

Converts to this type from the input type.

impl From<BlockHeight> for Envelope

fn from(value: BlockHeight) -> Self

Converts to this type from the input type.

impl From<BlockHeight> for i64

Converts a BlockHeight to a signed i64 value

fn from(value: BlockHeight) -> i64

Converts to this type from the input type.

impl From<BlockHeight> for u32

Extracts the u32 value from a BlockHeight

fn from(value: BlockHeight) -> u32

Converts to this type from the input type.

impl From<BlockHeight> for u64

Converts a BlockHeight to a u64 value

fn from(value: BlockHeight) -> u64

Converts to this type from the input type.

impl From<u32> for BlockHeight

Creates a BlockHeight from a u32 value

fn from(value: u32) -> Self

Converts to this type from the input type.

impl Hash for BlockHeight

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for BlockHeight

Implements a total ordering between block heights

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for BlockHeight

fn eq(&self, other: &BlockHeight) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for BlockHeight

Implements a partial ordering between block heights

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub<u32> for BlockHeight

Subtracts a block count from a height, with saturation to prevent underflow

type Output = BlockHeight

The resulting type after applying the - operator.

fn sub(self, other: u32) -> Self

Performs the - operation.

impl Sub for BlockHeight

Calculates the block count between two heights, with saturation

type Output = u32

The resulting type after applying the - operator.

fn sub(self, other: BlockHeight) -> u32

Performs the - operation.

impl TryFrom<CBOR> for BlockHeight

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self>

Performs the conversion.

impl TryFrom<Envelope> for BlockHeight

type Error = Error

The type returned in the event of a conversion error.

fn try_from(envelope: Envelope) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i32> for BlockHeight

Creates a BlockHeight from a signed i32 if it’s non-negative

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: i32) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i64> for BlockHeight

Creates a BlockHeight from a signed i64 if it fits in a u32

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: i64) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u64> for BlockHeight

Creates a BlockHeight from a u64 value if it fits in a u32

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: u64) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for BlockHeight

impl Eq for BlockHeight

impl StructuralPartialEq for BlockHeight