ssz_types 0.14.1

List, vector and bitfield types for SSZ
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! Provides types with unique properties required for SSZ serialization and Merklization:
//!
//! - `FixedVector`: A heap-allocated list with a size that is fixed at compile time.
//! - `VariableList`: A heap-allocated list that cannot grow past a type-level maximum length.
//! - `BitList`: A heap-allocated bitfield that with a type-level _maximum_ length.
//! - `BitVector`: A heap-allocated bitfield that with a type-level _fixed__ length.
//!
//! These structs are required as SSZ serialization and Merklization rely upon type-level lengths
//! for padding and verification.
//!
//! Adheres to the Ethereum 2.0 [SSZ
//! specification](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/ssz/simple-serialize.md)
//! at v0.12.1.
//!
//! ## Example
//! ```
//! use ssz_types::*;
//!
//! pub struct Example {
//!     bit_vector: BitVector<typenum::U8>,
//!     bit_list: BitList<typenum::U8>,
//!     variable_list: VariableList<u64, typenum::U8>,
//!     fixed_vector: FixedVector<u64, typenum::U8>,
//! }
//!
//! let mut example = Example {
//!     bit_vector: BitVector::new(),
//!     bit_list: BitList::with_capacity(4).unwrap(),
//!     variable_list: VariableList::try_from(vec![0, 1]).unwrap(),
//!     fixed_vector: FixedVector::try_from(vec![2, 3, 4, 5, 6, 7, 8, 9]).unwrap(),
//! };
//!
//! assert_eq!(example.bit_vector.len(), 8);
//! assert_eq!(example.bit_list.len(), 4);
//! assert_eq!(&example.variable_list[..], &[0, 1]);
//! assert_eq!(&example.fixed_vector[..], &[2, 3, 4, 5, 6, 7, 8, 9]);
//!
//! ```

pub mod serde_utils;
pub mod length {
    pub use ssz::{Fixed, Variable};
}

#[macro_use]
mod fixed_vector;
mod tree_hash;
mod variable_list;

#[cfg(feature = "context_deserialize")]
mod context_deserialize;

pub use fixed_vector::FixedVector;
pub use ssz::{BitList, BitVector, Bitfield};
pub use typenum;
pub use variable_list::VariableList;

#[cfg(feature = "runtime_types")]
mod runtime_types;

#[cfg(feature = "runtime_types")]
pub use runtime_types::{RuntimeFixedVector, RuntimeVariableList};

mod list_encoded_option;

pub use list_encoded_option::ListEncodedOption;

/// Returned when an item encounters an error.
#[derive(PartialEq, Debug, Clone)]
pub enum Error {
    OutOfBounds {
        i: usize,
        len: usize,
    },
    /// A `BitList` does not have a set bit, therefore it's length is unknowable.
    MissingLengthInformation,
    /// A `BitList` has excess bits set to true.
    ExcessBits,
    /// A `BitList` has an invalid number of bytes for a given bit length.
    InvalidByteCount {
        given: usize,
        expected: usize,
    },
}

impl core::fmt::Display for Error {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            Error::OutOfBounds { i, len } => {
                write!(f, "Index out of bounds: index {}, length {}", i, len)
            }
            Error::MissingLengthInformation => {
                write!(
                    f,
                    "BitList does not have a set bit, length cannot be determined"
                )
            }
            Error::ExcessBits => {
                write!(f, "BitList has excess bits set to true")
            }
            Error::InvalidByteCount { given, expected } => {
                write!(
                    f,
                    "Invalid byte count: given {}, expected {}",
                    given, expected
                )
            }
        }
    }
}

impl core::error::Error for Error {}

/// This impl can be removed once the never type is stabilised in Rust.
///
/// It is useful for using `?` in generic code that mixes `From` and `TryFrom`, as the blanket
/// `TryFrom` impl for `From` types uses `Infallible` as the error.
///
/// See: https://doc.rust-lang.org/std/convert/trait.TryFrom.html#generic-implementations
impl From<std::convert::Infallible> for Error {
    fn from(e: std::convert::Infallible) -> Self {
        match e {}
    }
}