zebra_chain/block/
height.rs

1//! Block height.
2
3use std::ops::{Add, Sub};
4use thiserror::Error;
5use zcash_primitives::consensus::BlockHeight;
6
7use crate::{serialization::SerializationError, BoxError};
8
9#[cfg(feature = "json-conversion")]
10pub mod json_conversion;
11
12/// The length of the chain back to the genesis block.
13///
14/// Two [`Height`]s can't be added, but they can be *subtracted* to get their difference,
15/// represented as an [`HeightDiff`]. This difference can then be added to or subtracted from a
16/// [`Height`]. Note the similarity with `chrono::DateTime` and `chrono::Duration`.
17///
18/// # Invariants
19///
20/// Users should not construct block heights greater than `Height::MAX`.
21///
22/// # Consensus
23///
24/// There are multiple formats for serializing a height, so we don't implement
25/// `ZcashSerialize` or `ZcashDeserialize` for `Height`.
26#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
27#[cfg_attr(any(test, feature = "proptest-impl"), derive(Default))]
28pub struct Height(pub u32);
29
30#[derive(Error, Debug)]
31pub enum HeightError {
32    #[error("The resulting height would overflow Height::MAX.")]
33    Overflow,
34    #[error("The resulting height would underflow Height::MIN.")]
35    Underflow,
36}
37
38impl std::str::FromStr for Height {
39    type Err = SerializationError;
40    fn from_str(s: &str) -> Result<Self, Self::Err> {
41        match s.parse() {
42            Ok(h) if (Height(h) <= Height::MAX) => Ok(Height(h)),
43            Ok(_) => Err(SerializationError::Parse("Height exceeds maximum height")),
44            Err(_) => Err(SerializationError::Parse("Height(u32) integer parse error")),
45        }
46    }
47}
48
49impl Height {
50    /// The minimum [`Height`].
51    ///
52    /// Due to the underlying type, it is impossible to construct block heights
53    /// less than [`Height::MIN`].
54    ///
55    /// Style note: Sometimes, [`Height::MIN`] is less readable than
56    /// `Height(0)`. Use whichever makes sense in context.
57    pub const MIN: Height = Height(0);
58
59    /// The maximum [`Height`].
60    ///
61    /// Users should not construct block heights greater than [`Height::MAX`].
62    ///
63    /// The spec says *"Implementations MUST support block heights up to and
64    /// including 2^31 − 1"*.
65    ///
66    /// Note that `u32::MAX / 2 == 2^31 - 1 == i32::MAX`.
67    pub const MAX: Height = Height(u32::MAX / 2);
68
69    /// The maximum [`Height`] as a [`u32`], for range patterns.
70    ///
71    /// `Height::MAX.0` can't be used in match range patterns, use this
72    /// alias instead.
73    pub const MAX_AS_U32: u32 = Self::MAX.0;
74
75    /// The maximum expiration [`Height`] that is allowed in all transactions
76    /// previous to Nu5 and in non-coinbase transactions from Nu5 activation
77    /// height and above.
78    pub const MAX_EXPIRY_HEIGHT: Height = Height(499_999_999);
79
80    /// Returns the next [`Height`].
81    ///
82    /// # Panics
83    ///
84    /// - If the current height is at its maximum.
85    pub fn next(self) -> Result<Self, HeightError> {
86        (self + 1).ok_or(HeightError::Overflow)
87    }
88
89    /// Returns the previous [`Height`].
90    ///
91    /// # Panics
92    ///
93    /// - If the current height is at its minimum.
94    pub fn previous(self) -> Result<Self, HeightError> {
95        (self - 1).ok_or(HeightError::Underflow)
96    }
97
98    /// Returns `true` if the [`Height`] is at its minimum.
99    pub fn is_min(self) -> bool {
100        self == Self::MIN
101    }
102
103    /// Returns the value as a `usize`.
104    pub fn as_usize(self) -> usize {
105        self.0.try_into().expect("fits in usize")
106    }
107}
108
109impl From<Height> for BlockHeight {
110    fn from(height: Height) -> Self {
111        BlockHeight::from_u32(height.0)
112    }
113}
114
115impl TryFrom<BlockHeight> for Height {
116    type Error = &'static str;
117
118    /// Checks that the `height` is within the valid [`Height`] range.
119    fn try_from(height: BlockHeight) -> Result<Self, Self::Error> {
120        Self::try_from(u32::from(height))
121    }
122}
123
124/// A difference between two [`Height`]s, possibly negative.
125///
126/// This can represent the difference between any height values,
127/// even if they are outside the valid height range (for example, in buggy RPC code).
128pub type HeightDiff = i64;
129
130// We don't implement TryFrom<u64>, because it causes type inference issues for integer constants.
131// Instead, use 1u64.try_into_height().
132
133impl TryFrom<u32> for Height {
134    type Error = &'static str;
135
136    /// Checks that the `height` is within the valid [`Height`] range.
137    fn try_from(height: u32) -> Result<Self, Self::Error> {
138        // Check the bounds.
139        //
140        // Clippy warns that `height >= Height::MIN.0` is always true.
141        assert_eq!(Height::MIN.0, 0);
142
143        if height <= Height::MAX.0 {
144            Ok(Height(height))
145        } else {
146            Err("heights must be less than or equal to Height::MAX")
147        }
148    }
149}
150
151impl From<Height> for u32 {
152    fn from(height: Height) -> Self {
153        height.0
154    }
155}
156
157impl From<Height> for u64 {
158    fn from(height: Height) -> Self {
159        height.0.into()
160    }
161}
162
163/// Convenience trait for converting a type into a valid Zcash [`Height`].
164pub trait TryIntoHeight {
165    /// The error type returned by [`Height`] conversion failures.
166    type Error;
167
168    /// Convert `self` to a `Height`, if possible.
169    fn try_into_height(&self) -> Result<Height, Self::Error>;
170}
171
172impl TryIntoHeight for u64 {
173    type Error = BoxError;
174
175    fn try_into_height(&self) -> Result<Height, Self::Error> {
176        u32::try_from(*self)?.try_into().map_err(Into::into)
177    }
178}
179
180impl TryIntoHeight for usize {
181    type Error = BoxError;
182
183    fn try_into_height(&self) -> Result<Height, Self::Error> {
184        u32::try_from(*self)?.try_into().map_err(Into::into)
185    }
186}
187
188impl TryIntoHeight for str {
189    type Error = BoxError;
190
191    fn try_into_height(&self) -> Result<Height, Self::Error> {
192        self.parse().map_err(Into::into)
193    }
194}
195
196impl TryIntoHeight for String {
197    type Error = BoxError;
198
199    fn try_into_height(&self) -> Result<Height, Self::Error> {
200        self.as_str().try_into_height()
201    }
202}
203
204impl TryIntoHeight for i32 {
205    type Error = BoxError;
206
207    fn try_into_height(&self) -> Result<Height, Self::Error> {
208        u32::try_from(*self)?.try_into().map_err(Into::into)
209    }
210}
211
212// We don't implement Add<u32> or Sub<u32>, because they cause type inference issues for integer constants.
213
214impl Sub<Height> for Height {
215    type Output = HeightDiff;
216
217    /// Subtract two heights, returning the result, which can be negative.
218    /// Since [`HeightDiff`] is `i64` and [`Height`] is `u32`, the result is always correct.
219    fn sub(self, rhs: Height) -> Self::Output {
220        // All these conversions are exact, and the subtraction can't overflow or underflow.
221        let lhs = HeightDiff::from(self.0);
222        let rhs = HeightDiff::from(rhs.0);
223
224        lhs - rhs
225    }
226}
227
228impl Sub<HeightDiff> for Height {
229    type Output = Option<Self>;
230
231    /// Subtract a height difference from a height, returning `None` if the resulting height is
232    /// outside the valid `Height` range (this also checks the result is non-negative).
233    fn sub(self, rhs: HeightDiff) -> Option<Self> {
234        // We need to convert the height to [`i64`] so we can subtract negative [`HeightDiff`]s.
235        let lhs = HeightDiff::from(self.0);
236        let res = lhs - rhs;
237
238        // Check the bounds.
239        let res = u32::try_from(res).ok()?;
240        Height::try_from(res).ok()
241    }
242}
243
244impl Add<HeightDiff> for Height {
245    type Output = Option<Height>;
246
247    /// Add a height difference to a height, returning `None` if the resulting height is outside
248    /// the valid `Height` range (this also checks the result is non-negative).
249    fn add(self, rhs: HeightDiff) -> Option<Height> {
250        // We need to convert the height to [`i64`] so we can add negative [`HeightDiff`]s.
251        let lhs = i64::from(self.0);
252        let res = lhs + rhs;
253
254        // Check the bounds.
255        let res = u32::try_from(res).ok()?;
256        Height::try_from(res).ok()
257    }
258}
259
260#[test]
261fn operator_tests() {
262    let _init_guard = zebra_test::init();
263
264    // Elementary checks.
265    assert_eq!(Some(Height(2)), Height(1) + 1);
266    assert_eq!(None, Height::MAX + 1);
267
268    let height = Height(u32::pow(2, 31) - 2);
269    assert!(height < Height::MAX);
270
271    let max_height = (height + 1).expect("this addition should produce the max height");
272    assert!(height < max_height);
273    assert!(max_height <= Height::MAX);
274    assert_eq!(Height::MAX, max_height);
275    assert_eq!(None, max_height + 1);
276
277    // Bad heights aren't caught at compile-time or runtime, until we add or subtract
278    assert_eq!(None, Height(Height::MAX_AS_U32 + 1) + 0);
279    assert_eq!(None, Height(i32::MAX as u32) + 1);
280    assert_eq!(None, Height(u32::MAX) + 0);
281
282    // Adding negative numbers
283    assert_eq!(Some(Height(1)), Height(2) + -1);
284    assert_eq!(Some(Height(0)), Height(1) + -1);
285    assert_eq!(None, Height(0) + -1);
286    assert_eq!(Some(Height(Height::MAX_AS_U32 - 1)), Height::MAX + -1);
287
288    // Bad heights aren't caught at compile-time or runtime, until we add or subtract,
289    // and the result is invalid
290    assert_eq!(None, Height(Height::MAX_AS_U32 + 1) + 1);
291    assert_eq!(None, Height(i32::MAX as u32) + 1);
292    assert_eq!(None, Height(u32::MAX) + 1);
293
294    // Adding negative numbers
295    assert_eq!(Some(Height::MAX), Height(i32::MAX as u32 + 1) + -1);
296    assert_eq!(None, Height(u32::MAX) + -1);
297
298    assert_eq!(Some(Height(1)), Height(2) - 1);
299    assert_eq!(Some(Height(0)), Height(1) - 1);
300    assert_eq!(None, Height(0) - 1);
301    assert_eq!(Some(Height(Height::MAX_AS_U32 - 1)), Height::MAX - 1);
302
303    // Subtracting negative numbers
304    assert_eq!(Some(Height(2)), Height(1) - -1);
305    assert_eq!(Some(Height::MAX), Height(Height::MAX_AS_U32 - 1) - -1);
306    assert_eq!(None, Height::MAX - -1);
307
308    // Bad heights aren't caught at compile-time or runtime, until we add or subtract,
309    // and the result is invalid
310    assert_eq!(Some(Height::MAX), Height(i32::MAX as u32 + 1) - 1);
311    assert_eq!(None, Height(u32::MAX) - 1);
312
313    // Subtracting negative numbers
314    assert_eq!(None, Height(Height::MAX_AS_U32 + 1) - -1);
315    assert_eq!(None, Height(i32::MAX as u32) - -1);
316    assert_eq!(None, Height(u32::MAX) - -1);
317
318    assert_eq!(1, (Height(2) - Height(1)));
319    assert_eq!(0, (Height(1) - Height(1)));
320    assert_eq!(-1, Height(0) - Height(1));
321    assert_eq!(-5, Height(2) - Height(7));
322    assert_eq!(Height::MAX.0 as HeightDiff, (Height::MAX - Height(0)));
323    assert_eq!(1, (Height::MAX - Height(Height::MAX_AS_U32 - 1)));
324    assert_eq!(-1, Height(Height::MAX_AS_U32 - 1) - Height::MAX);
325    assert_eq!(-(Height::MAX_AS_U32 as HeightDiff), Height(0) - Height::MAX);
326}
zebra_chain/block/height.rs

zebra_chain/block/
height.rs
