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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +91 -0
- data/Cargo.lock +314 -0
- data/Cargo.toml +28 -0
- data/LICENSE.txt +21 -0
- data/README.md +326 -0
- data/ext/merkle_machines_native/core/CHANGELOG.md +66 -0
- data/ext/merkle_machines_native/core/Cargo.toml +20 -0
- data/ext/merkle_machines_native/core/README.md +114 -0
- data/ext/merkle_machines_native/core/src/lib.rs +16 -0
- data/ext/merkle_machines_native/core/src/refusal.rs +54 -0
- data/ext/merkle_machines_native/core/src/request.rs +60 -0
- data/ext/merkle_machines_native/core/src/schema.rs +193 -0
- data/ext/merkle_machines_native/core/src/survey/buffer.rs +61 -0
- data/ext/merkle_machines_native/core/src/survey.rs +552 -0
- data/ext/merkle_machines_native/extconf.rb +2 -0
- data/ext/merkle_machines_native/ffi/Cargo.toml +21 -0
- data/ext/merkle_machines_native/ffi/extconf.rb +14 -0
- data/ext/merkle_machines_native/ffi/src/init.rs +50 -0
- data/ext/merkle_machines_native/ffi/src/lib.rs +453 -0
- data/ext/merkle_machines_native/ffi/src/values.rs +47 -0
- data/lib/merkle_machines/survey.rb +43 -0
- data/lib/merkle_machines/values.rb +63 -0
- data/lib/merkle_machines/version.rb +5 -0
- data/lib/merkle_machines.rb +8 -0
- data/sig/merkle_machines.rbs +142 -0
- metadata +92 -0
|
@@ -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
|
+
}
|