merkle_machines 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,193 @@
1
+ //! Tree shape, node addresses and leaf ranges.
2
+
3
+ /// Largest supported number of children per node.
4
+ pub const MAX_FANOUT: u8 = 64;
5
+
6
+ /// Half-open range of leaf indices, `start..end`, never backwards.
7
+ ///
8
+ /// `LeafRange::default()` is the empty range `0..0`, a placeholder for
9
+ /// pre-filling an output buffer; a survey never emits an empty range.
10
+ #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
11
+ pub struct LeafRange {
12
+ // Crate-visible so the survey's sorted buffer can join ranges in place;
13
+ // it only ever widens a range, so `start <= end` holds.
14
+ pub(crate) start: u64,
15
+ pub(crate) end: u64,
16
+ }
17
+
18
+ impl LeafRange {
19
+ /// The leaves `start..end`, e.g. rebuilt after crossing a wire.
20
+ ///
21
+ /// `None` when `start > end`: no range runs backwards.
22
+ #[must_use]
23
+ pub const fn new(start: u64, end: u64) -> Option<Self> {
24
+ if start > end {
25
+ return None;
26
+ }
27
+ Some(Self { start, end })
28
+ }
29
+
30
+ /// First leaf in the range.
31
+ #[must_use]
32
+ pub const fn start(&self) -> u64 {
33
+ self.start
34
+ }
35
+
36
+ /// One past the last leaf in the range.
37
+ #[must_use]
38
+ pub const fn end(&self) -> u64 {
39
+ self.end
40
+ }
41
+
42
+ /// Number of leaves covered.
43
+ #[must_use]
44
+ pub const fn len(&self) -> u64 {
45
+ // Every constructor keeps `start <= end`, so this cannot wrap.
46
+ self.end - self.start
47
+ }
48
+
49
+ /// `true` when the range covers no leaf.
50
+ #[must_use]
51
+ pub const fn is_empty(&self) -> bool {
52
+ self.end == self.start
53
+ }
54
+ }
55
+
56
+ /// Address of a tree node: `level` 0 is the root, `index` counts left to right
57
+ /// within the level.
58
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
59
+ pub struct Node {
60
+ /// Distance from the root.
61
+ pub level: u8,
62
+ /// Position within the level.
63
+ pub index: u64,
64
+ }
65
+
66
+ impl Node {
67
+ /// The root of every tree.
68
+ pub const ROOT: Self = Self { level: 0, index: 0 };
69
+ }
70
+
71
+ /// First field on which two schemas disagree.
72
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
73
+ pub enum Mismatch {
74
+ /// Different number of children per node.
75
+ Fanout,
76
+ /// Different number of levels below the root.
77
+ Depth,
78
+ /// Different key-to-leaf partitioning.
79
+ Partitioning,
80
+ /// Different digest algorithm or encoding.
81
+ Digest,
82
+ }
83
+
84
+ /// Shape and identity of a fixed-depth digest tree.
85
+ ///
86
+ /// `partitioning` and `digest` are opaque identifiers chosen by the caller for
87
+ /// the key-to-leaf mapping and for the digest algorithm. Two trees can be
88
+ /// compared only when all four fields are equal.
89
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
90
+ pub struct Schema {
91
+ fanout: u8,
92
+ depth: u8,
93
+ partitioning: u64,
94
+ digest: u64,
95
+ }
96
+
97
+ impl Schema {
98
+ /// A schema with `fanout` children per node and `depth` levels below the
99
+ /// root. `None` when `fanout` is outside `2..=MAX_FANOUT` or the leaf count
100
+ /// `fanout^depth` does not fit in a `u64`.
101
+ #[must_use]
102
+ pub const fn new(fanout: u8, depth: u8, partitioning: u64, digest: u64) -> Option<Self> {
103
+ if fanout < 2 || fanout > MAX_FANOUT {
104
+ return None;
105
+ }
106
+ if (fanout as u64).checked_pow(depth as u32).is_none() {
107
+ return None;
108
+ }
109
+ Some(Self {
110
+ fanout,
111
+ depth,
112
+ partitioning,
113
+ digest,
114
+ })
115
+ }
116
+
117
+ /// Children per node.
118
+ #[must_use]
119
+ pub const fn fanout(&self) -> u8 {
120
+ self.fanout
121
+ }
122
+
123
+ /// Levels below the root; leaves live at this level.
124
+ #[must_use]
125
+ pub const fn depth(&self) -> u8 {
126
+ self.depth
127
+ }
128
+
129
+ /// Caller-defined identifier of the key-to-leaf mapping.
130
+ #[must_use]
131
+ pub const fn partitioning(&self) -> u64 {
132
+ self.partitioning
133
+ }
134
+
135
+ /// Caller-defined identifier of the digest algorithm.
136
+ #[must_use]
137
+ pub const fn digest(&self) -> u64 {
138
+ self.digest
139
+ }
140
+
141
+ /// Total number of leaves.
142
+ #[must_use]
143
+ pub const fn leaves(&self) -> u64 {
144
+ self.width(self.depth)
145
+ }
146
+
147
+ /// Number of nodes at `level`, saturating past the leaf level.
148
+ #[must_use]
149
+ pub const fn width(&self, level: u8) -> u64 {
150
+ let level = if level > self.depth {
151
+ self.depth
152
+ } else {
153
+ level
154
+ };
155
+ (self.fanout as u64).pow(level as u32)
156
+ }
157
+
158
+ /// Leaves below `node`, or `None` when the node is not part of the tree.
159
+ #[must_use]
160
+ pub const fn span(&self, node: Node) -> Option<LeafRange> {
161
+ if node.level > self.depth || node.index >= self.width(node.level) {
162
+ return None;
163
+ }
164
+ // `node.level <= depth` and `node.index < fanout^level`, so `(index +
165
+ // 1) * fanout^(depth - level) <= fanout^depth`, which `new` proved
166
+ // fits a `u64`: nothing here can wrap.
167
+ let each = self.width(self.depth - node.level);
168
+ Some(LeafRange {
169
+ start: node.index * each,
170
+ end: (node.index + 1) * each,
171
+ })
172
+ }
173
+
174
+ /// `Ok` when `other` describes a tree comparable with this one.
175
+ ///
176
+ /// # Errors
177
+ /// The first field on which the schemas differ.
178
+ pub const fn compatible(&self, other: &Self) -> Result<(), Mismatch> {
179
+ if self.fanout != other.fanout {
180
+ return Err(Mismatch::Fanout);
181
+ }
182
+ if self.depth != other.depth {
183
+ return Err(Mismatch::Depth);
184
+ }
185
+ if self.partitioning != other.partitioning {
186
+ return Err(Mismatch::Partitioning);
187
+ }
188
+ if self.digest != other.digest {
189
+ return Err(Mismatch::Digest);
190
+ }
191
+ Ok(())
192
+ }
193
+ }
@@ -0,0 +1,61 @@
1
+ //! The survey's sorted leaf-range buffer.
2
+
3
+ use super::Survey;
4
+ use crate::schema::LeafRange;
5
+
6
+ impl<const P: usize, const O: usize> Survey<P, O> {
7
+ /// Insert a run of leaves into the sorted buffer, joining touching ranges.
8
+ ///
9
+ /// `false` when it does not fit: the buffer is full and nothing changed.
10
+ /// Every cell touched lies in the live prefix, or (inserting) in
11
+ /// `at..=buffered` with `buffered < O`.
12
+ pub(super) fn buffer(&mut self, start: u64, end: u64) -> bool {
13
+ let Some(live) = self.out.get_mut(..self.buffered) else {
14
+ debug_assert!(false, "buffered never exceeds O");
15
+ return false;
16
+ };
17
+ let at = live
18
+ .iter()
19
+ .position(|r| r.start > start)
20
+ .unwrap_or(live.len());
21
+ // `at <= live.len()`, so the split always succeeds.
22
+ let Some((before, after)) = live.split_at_mut_checked(at) else {
23
+ debug_assert!(false, "the insertion point lies within the live prefix");
24
+ return false;
25
+ };
26
+ let left = before.last_mut().filter(|r| r.end == start);
27
+ let right = after.first_mut().filter(|r| r.start == end);
28
+ match (left, right) {
29
+ (Some(left), Some(right)) => {
30
+ left.end = right.end;
31
+ // `right` is `live[at]`, so `at + 1 <= live.len()` and
32
+ // `buffered >= 1`.
33
+ live.copy_within(at + 1.., at);
34
+ self.buffered -= 1;
35
+ }
36
+ (Some(left), None) => left.end = end,
37
+ (None, Some(right)) => right.start = start,
38
+ (None, None) => {
39
+ if self.buffered == O {
40
+ return false;
41
+ }
42
+ // `at <= buffered < O`: the window is in bounds and nonempty.
43
+ // Rotating moves the unused cell at `buffered` to the front,
44
+ // shifting `at..buffered` up by one, then the run takes it.
45
+ let Some(window) = self.out.get_mut(at..=self.buffered) else {
46
+ debug_assert!(false, "buffered stays below O here");
47
+ return false;
48
+ };
49
+ window.rotate_right(1);
50
+ let Some(first) = window.first_mut() else {
51
+ debug_assert!(false, "the window holds at least one cell");
52
+ return false;
53
+ };
54
+ *first = LeafRange { start, end };
55
+ // `buffered < O`, so this cannot overflow.
56
+ self.buffered += 1;
57
+ }
58
+ }
59
+ true
60
+ }
61
+ }