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
151/// Convenience trait for converting a type into a valid Zcash [`Height`].
152pub trait TryIntoHeight {
153    /// The error type returned by [`Height`] conversion failures.
154    type Error;
155
156    /// Convert `self` to a `Height`, if possible.
157    fn try_into_height(&self) -> Result<Height, Self::Error>;
158}
159
160impl TryIntoHeight for u64 {
161    type Error = BoxError;
162
163    fn try_into_height(&self) -> Result<Height, Self::Error> {
164        u32::try_from(*self)?.try_into().map_err(Into::into)
165    }
166}
167
168impl TryIntoHeight for usize {
169    type Error = BoxError;
170
171    fn try_into_height(&self) -> Result<Height, Self::Error> {
172        u32::try_from(*self)?.try_into().map_err(Into::into)
173    }
174}
175
176impl TryIntoHeight for str {
177    type Error = BoxError;
178
179    fn try_into_height(&self) -> Result<Height, Self::Error> {
180        self.parse().map_err(Into::into)
181    }
182}
183
184impl TryIntoHeight for String {
185    type Error = BoxError;
186
187    fn try_into_height(&self) -> Result<Height, Self::Error> {
188        self.as_str().try_into_height()
189    }
190}
191
192impl TryIntoHeight for i32 {
193    type Error = BoxError;
194
195    fn try_into_height(&self) -> Result<Height, Self::Error> {
196        u32::try_from(*self)?.try_into().map_err(Into::into)
197    }
198}
199
200// We don't implement Add<u32> or Sub<u32>, because they cause type inference issues for integer constants.
201
202impl Sub<Height> for Height {
203    type Output = HeightDiff;
204
205    /// Subtract two heights, returning the result, which can be negative.
206    /// Since [`HeightDiff`] is `i64` and [`Height`] is `u32`, the result is always correct.
207    fn sub(self, rhs: Height) -> Self::Output {
208        // All these conversions are exact, and the subtraction can't overflow or underflow.
209        let lhs = HeightDiff::from(self.0);
210        let rhs = HeightDiff::from(rhs.0);
211
212        lhs - rhs
213    }
214}
215
216impl Sub<HeightDiff> for Height {
217    type Output = Option<Self>;
218
219    /// Subtract a height difference from a height, returning `None` if the resulting height is
220    /// outside the valid `Height` range (this also checks the result is non-negative).
221    fn sub(self, rhs: HeightDiff) -> Option<Self> {
222        // We need to convert the height to [`i64`] so we can subtract negative [`HeightDiff`]s.
223        let lhs = HeightDiff::from(self.0);
224        let res = lhs - rhs;
225
226        // Check the bounds.
227        let res = u32::try_from(res).ok()?;
228        Height::try_from(res).ok()
229    }
230}
231
232impl Add<HeightDiff> for Height {
233    type Output = Option<Height>;
234
235    /// Add a height difference to a height, returning `None` if the resulting height is outside
236    /// the valid `Height` range (this also checks the result is non-negative).
237    fn add(self, rhs: HeightDiff) -> Option<Height> {
238        // We need to convert the height to [`i64`] so we can add negative [`HeightDiff`]s.
239        let lhs = i64::from(self.0);
240        let res = lhs + rhs;
241
242        // Check the bounds.
243        let res = u32::try_from(res).ok()?;
244        Height::try_from(res).ok()
245    }
246}
247
248#[test]
249fn operator_tests() {
250    let _init_guard = zebra_test::init();
251
252    // Elementary checks.
253    assert_eq!(Some(Height(2)), Height(1) + 1);
254    assert_eq!(None, Height::MAX + 1);
255
256    let height = Height(u32::pow(2, 31) - 2);
257    assert!(height < Height::MAX);
258
259    let max_height = (height + 1).expect("this addition should produce the max height");
260    assert!(height < max_height);
261    assert!(max_height <= Height::MAX);
262    assert_eq!(Height::MAX, max_height);
263    assert_eq!(None, max_height + 1);
264
265    // Bad heights aren't caught at compile-time or runtime, until we add or subtract
266    assert_eq!(None, Height(Height::MAX_AS_U32 + 1) + 0);
267    assert_eq!(None, Height(i32::MAX as u32) + 1);
268    assert_eq!(None, Height(u32::MAX) + 0);
269
270    // Adding negative numbers
271    assert_eq!(Some(Height(1)), Height(2) + -1);
272    assert_eq!(Some(Height(0)), Height(1) + -1);
273    assert_eq!(None, Height(0) + -1);
274    assert_eq!(Some(Height(Height::MAX_AS_U32 - 1)), Height::MAX + -1);
275
276    // Bad heights aren't caught at compile-time or runtime, until we add or subtract,
277    // and the result is invalid
278    assert_eq!(None, Height(Height::MAX_AS_U32 + 1) + 1);
279    assert_eq!(None, Height(i32::MAX as u32) + 1);
280    assert_eq!(None, Height(u32::MAX) + 1);
281
282    // Adding negative numbers
283    assert_eq!(Some(Height::MAX), Height(i32::MAX as u32 + 1) + -1);
284    assert_eq!(None, Height(u32::MAX) + -1);
285
286    assert_eq!(Some(Height(1)), Height(2) - 1);
287    assert_eq!(Some(Height(0)), Height(1) - 1);
288    assert_eq!(None, Height(0) - 1);
289    assert_eq!(Some(Height(Height::MAX_AS_U32 - 1)), Height::MAX - 1);
290
291    // Subtracting negative numbers
292    assert_eq!(Some(Height(2)), Height(1) - -1);
293    assert_eq!(Some(Height::MAX), Height(Height::MAX_AS_U32 - 1) - -1);
294    assert_eq!(None, Height::MAX - -1);
295
296    // Bad heights aren't caught at compile-time or runtime, until we add or subtract,
297    // and the result is invalid
298    assert_eq!(Some(Height::MAX), Height(i32::MAX as u32 + 1) - 1);
299    assert_eq!(None, Height(u32::MAX) - 1);
300
301    // Subtracting negative numbers
302    assert_eq!(None, Height(Height::MAX_AS_U32 + 1) - -1);
303    assert_eq!(None, Height(i32::MAX as u32) - -1);
304    assert_eq!(None, Height(u32::MAX) - -1);
305
306    assert_eq!(1, (Height(2) - Height(1)));
307    assert_eq!(0, (Height(1) - Height(1)));
308    assert_eq!(-1, Height(0) - Height(1));
309    assert_eq!(-5, Height(2) - Height(7));
310    assert_eq!(Height::MAX.0 as HeightDiff, (Height::MAX - Height(0)));
311    assert_eq!(1, (Height::MAX - Height(Height::MAX_AS_U32 - 1)));
312    assert_eq!(-1, Height(Height::MAX_AS_U32 - 1) - Height::MAX);
313    assert_eq!(-(Height::MAX_AS_U32 as HeightDiff), Height(0) - Height::MAX);
314}
zebra_chain/block/height.rs

zebra_chain/block/
height.rs
