twenty_first/util_types/
sponge.rs

1use std::fmt::Debug;
2
3use num_traits::ConstOne;
4use num_traits::ConstZero;
5
6use crate::math::b_field_element::BFieldElement;
7
8pub const RATE: usize = 10;
9
10/// The hasher [Domain] differentiates between the modes of hashing.
11///
12/// The main purpose of declaring the domain is to prevent collisions between different types of
13/// hashing by introducing defining differences in the way the hash function's internal state
14/// (e.g. a sponge state's capacity) is initialized.
15#[derive(Debug, PartialEq, Eq)]
16pub enum Domain {
17    /// The `VariableLength` domain is used for hashing objects that potentially serialize to more
18    /// than [`RATE`] number of field elements.
19    VariableLength,
20
21    /// The `FixedLength` domain is used for hashing objects that always fit
22    /// within [RATE] number of fields elements, e.g. a pair of
23    /// [Digest](crate::prelude::Digest)s.
24    FixedLength,
25}
26
27/// A [cryptographic sponge][sponge]. Should only be based on a cryptographic permutation, e.g.,
28/// [`Tip5`][tip5].
29///
30/// [sponge]: https://keccak.team/files/CSF-0.1.pdf
31/// [tip5]: crate::prelude::Tip5
32pub trait Sponge: Clone + Debug + Default + Send + Sync {
33    const RATE: usize;
34
35    fn init() -> Self;
36
37    fn absorb(&mut self, input: [BFieldElement; RATE]);
38
39    fn squeeze(&mut self) -> [BFieldElement; RATE];
40
41    fn pad_and_absorb_all(&mut self, input: &[BFieldElement]) {
42        let (chunks, remainder) = input.as_chunks::<RATE>();
43        for &chunk in chunks {
44            self.absorb(chunk);
45        }
46
47        // Pad input with [1, 0, 0, …] – padding is at least one element.
48        // Since remainder's len is at most `RATE - 1`, the indexing is safe.
49        let mut last_chunk = const { [BFieldElement::ZERO; RATE] };
50        last_chunk[..remainder.len()].copy_from_slice(remainder);
51        last_chunk[remainder.len()] = BFieldElement::ONE;
52        self.absorb(last_chunk);
53    }
54}
55
56#[cfg(test)]
57#[cfg_attr(coverage_nightly, coverage(off))]
58mod tests {
59    use proptest::prelude::*;
60    use rand::RngExt;
61    use rand::distr::Distribution;
62    use rand::distr::StandardUniform;
63
64    use super::*;
65    use crate::math::x_field_element::EXTENSION_DEGREE;
66    use crate::prelude::BFieldCodec;
67    use crate::prelude::XFieldElement;
68    use crate::tests::proptest;
69    use crate::tests::test;
70    use crate::tip5::Digest;
71    use crate::tip5::Tip5;
72
73    fn encode_prop<T>(smallest: T, largest: T)
74    where
75        T: Eq + BFieldCodec,
76        StandardUniform: Distribution<T>,
77    {
78        let smallest_seq = smallest.encode();
79        let largest_seq = largest.encode();
80        assert_ne!(smallest_seq, largest_seq);
81        assert_eq!(smallest_seq.len(), largest_seq.len());
82
83        let mut rng = rand::rng();
84        let random_a: T = rng.random();
85        let random_b: T = rng.random();
86
87        if random_a != random_b {
88            assert_ne!(random_a.encode(), random_b.encode());
89        } else {
90            assert_eq!(random_a.encode(), random_b.encode());
91        }
92    }
93
94    #[macro_rules_attr::apply(test)]
95    fn to_sequence_test() {
96        // bool
97        encode_prop(false, true);
98
99        // u32
100        encode_prop(0u32, u32::MAX);
101
102        // u64
103        encode_prop(0u64, u64::MAX);
104
105        // BFieldElement
106        let bfe_max = BFieldElement::new(BFieldElement::MAX);
107        encode_prop(BFieldElement::ZERO, bfe_max);
108
109        // XFieldElement
110        let xfe_max = XFieldElement::new([bfe_max; EXTENSION_DEGREE]);
111        encode_prop(XFieldElement::ZERO, xfe_max);
112
113        // Digest
114        let digest_max = Digest::new([bfe_max; Digest::LEN]);
115        encode_prop(Digest::ALL_ZERO, digest_max);
116
117        // u128
118        encode_prop(0u128, u128::MAX);
119    }
120
121    #[macro_rules_attr::apply(proptest)]
122    fn sample_indices(mut tip5: Tip5) {
123        let cases = [
124            (2, 0),
125            (4, 1),
126            (8, 9),
127            (16, 10),
128            (32, 11),
129            (64, 19),
130            (128, 20),
131            (256, 21),
132            (512, 65),
133        ];
134
135        for (upper_bound, num_indices) in cases {
136            let indices = tip5.sample_indices(upper_bound, num_indices);
137            prop_assert_eq!(num_indices, indices.len());
138            prop_assert!(indices.into_iter().all(|index| index < upper_bound));
139        }
140    }
141}
twenty_first/util_types/sponge.rs

twenty_first/util_types/
sponge.rs
