miden-crypto/src/merkle/store/mod.rs
src/merkle/store/mod.rsRaw
1use super::{
2 mmr::Mmr, BTreeMap, EmptySubtreeRoots, InnerNodeInfo, KvMap, MerkleError, MerklePath,
3 MerklePathSet, MerkleTree, NodeIndex, RecordingMap, RootPath, Rpo256, RpoDigest, SimpleSmt,
4 TieredSmt, ValuePath, Vec,
5};
6use crate::utils::{ByteReader, ByteWriter, Deserializable, DeserializationError, Serializable};
7use core::borrow::Borrow;
8
9#[cfg(test)]
10mod tests;
11
12// MERKLE STORE
13// ================================================================================================
14
15/// A default [MerkleStore] which uses a simple [BTreeMap] as the backing storage.
16pub type DefaultMerkleStore = MerkleStore<BTreeMap<RpoDigest, Node>>;
17
18/// A [MerkleStore] with recording capabilities which uses [RecordingMap] as the backing storage.
19pub type RecordingMerkleStore = MerkleStore<RecordingMap<RpoDigest, Node>>;
20
21#[derive(Debug, Default, Copy, Clone, Eq, PartialEq)]
22pub struct Node {
23 left: RpoDigest,
24 right: RpoDigest,
25}
26
27/// An in-memory data store for Merkelized data.
28///
29/// This is a in memory data store for Merkle trees, this store allows all the nodes of multiple
30/// trees to live as long as necessary and without duplication, this allows the implementation of
31/// space efficient persistent data structures.
32///
33/// Example usage:
34///
35/// ```rust
36/// # use miden_crypto::{ZERO, Felt, Word};
37/// # use miden_crypto::merkle::{NodeIndex, MerkleStore, MerkleTree};
38/// # use miden_crypto::hash::rpo::Rpo256;
39/// # const fn int_to_node(value: u64) -> Word {
40/// # [Felt::new(value), ZERO, ZERO, ZERO]
41/// # }
42/// # let A = int_to_node(1);
43/// # let B = int_to_node(2);
44/// # let C = int_to_node(3);
45/// # let D = int_to_node(4);
46/// # let E = int_to_node(5);
47/// # let F = int_to_node(6);
48/// # let G = int_to_node(7);
49/// # let H0 = int_to_node(8);
50/// # let H1 = int_to_node(9);
51/// # let T0 = MerkleTree::new([A, B, C, D, E, F, G, H0].to_vec()).expect("even number of leaves provided");
52/// # let T1 = MerkleTree::new([A, B, C, D, E, F, G, H1].to_vec()).expect("even number of leaves provided");
53/// # let ROOT0 = T0.root();
54/// # let ROOT1 = T1.root();
55/// let mut store: MerkleStore = MerkleStore::new();
56///
57/// // the store is initialized with the SMT empty nodes
58/// assert_eq!(store.num_internal_nodes(), 255);
59///
60/// let tree1 = MerkleTree::new(vec![A, B, C, D, E, F, G, H0]).unwrap();
61/// let tree2 = MerkleTree::new(vec![A, B, C, D, E, F, G, H1]).unwrap();
62///
63/// // populates the store with two merkle trees, common nodes are shared
64/// store.extend(tree1.inner_nodes());
65/// store.extend(tree2.inner_nodes());
66///
67/// // every leaf except the last are the same
68/// for i in 0..7 {
69/// let idx0 = NodeIndex::new(3, i).unwrap();
70/// let d0 = store.get_node(ROOT0, idx0).unwrap();
71/// let idx1 = NodeIndex::new(3, i).unwrap();
72/// let d1 = store.get_node(ROOT1, idx1).unwrap();
73/// assert_eq!(d0, d1, "Both trees have the same leaf at pos {i}");
74/// }
75///
76/// // The leafs A-B-C-D are the same for both trees, so are their 2 immediate parents
77/// for i in 0..4 {
78/// let idx0 = NodeIndex::new(3, i).unwrap();
79/// let d0 = store.get_path(ROOT0, idx0).unwrap();
80/// let idx1 = NodeIndex::new(3, i).unwrap();
81/// let d1 = store.get_path(ROOT1, idx1).unwrap();
82/// assert_eq!(d0.path[0..2], d1.path[0..2], "Both sub-trees are equal up to two levels");
83/// }
84///
85/// // Common internal nodes are shared, the two added trees have a total of 30, but the store has
86/// // only 10 new entries, corresponding to the 10 unique internal nodes of these trees.
87/// assert_eq!(store.num_internal_nodes() - 255, 10);
88/// ```
89#[derive(Debug, Clone, Eq, PartialEq)]
90pub struct MerkleStore<T: KvMap<RpoDigest, Node> = BTreeMap<RpoDigest, Node>> {
91 nodes: T,
92}
93
94impl<T: KvMap<RpoDigest, Node>> Default for MerkleStore<T> {
95 fn default() -> Self {
96 Self::new()
97 }
98}
99
100impl<T: KvMap<RpoDigest, Node>> MerkleStore<T> {
101 // CONSTRUCTORS
102 // --------------------------------------------------------------------------------------------
103
104 /// Creates an empty `MerkleStore` instance.
105 pub fn new() -> MerkleStore<T> {
106 // pre-populate the store with the empty hashes
107 let nodes = empty_hashes().into_iter().collect();
108 MerkleStore { nodes }
109 }
110
111 // PUBLIC ACCESSORS
112 // --------------------------------------------------------------------------------------------
113
114 /// Return a count of the non-leaf nodes in the store.
115 pub fn num_internal_nodes(&self) -> usize {
116 self.nodes.len()
117 }
118
119 /// Returns the node at `index` rooted on the tree `root`.
120 ///
121 /// # Errors
122 /// This method can return the following errors:
123 /// - `RootNotInStore` if the `root` is not present in the store.
124 /// - `NodeNotInStore` if a node needed to traverse from `root` to `index` is not present in
125 /// the store.
126 pub fn get_node(&self, root: RpoDigest, index: NodeIndex) -> Result<RpoDigest, MerkleError> {
127 let mut hash = root;
128
129 // corner case: check the root is in the store when called with index `NodeIndex::root()`
130 self.nodes.get(&hash).ok_or(MerkleError::RootNotInStore(hash))?;
131
132 for i in (0..index.depth()).rev() {
133 let node = self.nodes.get(&hash).ok_or(MerkleError::NodeNotInStore(hash, index))?;
134
135 let bit = (index.value() >> i) & 1;
136 hash = if bit == 0 { node.left } else { node.right }
137 }
138
139 Ok(hash)
140 }
141
142 /// Returns the node at the specified `index` and its opening to the `root`.
143 ///
144 /// The path starts at the sibling of the target leaf.
145 ///
146 /// # Errors
147 /// This method can return the following errors:
148 /// - `RootNotInStore` if the `root` is not present in the store.
149 /// - `NodeNotInStore` if a node needed to traverse from `root` to `index` is not present in
150 /// the store.
151 pub fn get_path(&self, root: RpoDigest, index: NodeIndex) -> Result<ValuePath, MerkleError> {
152 let mut hash = root;
153 let mut path = Vec::with_capacity(index.depth().into());
154
155 // corner case: check the root is in the store when called with index `NodeIndex::root()`
156 self.nodes.get(&hash).ok_or(MerkleError::RootNotInStore(hash))?;
157
158 for i in (0..index.depth()).rev() {
159 let node = self.nodes.get(&hash).ok_or(MerkleError::NodeNotInStore(hash, index))?;
160
161 let bit = (index.value() >> i) & 1;
162 hash = if bit == 0 {
163 path.push(node.right);
164 node.left
165 } else {
166 path.push(node.left);
167 node.right
168 }
169 }
170
171 // the path is computed from root to leaf, so it must be reversed
172 path.reverse();
173
174 Ok(ValuePath {
175 value: hash,
176 path: MerklePath::new(path),
177 })
178 }
179
180 /// Reconstructs a path from the root until a leaf or empty node and returns its depth.
181 ///
182 /// The `tree_depth` parameter defines up to which depth the tree will be traversed, starting
183 /// from `root`. The maximum value the argument accepts is [u64::BITS].
184 ///
185 /// The traversed path from leaf to root will start at the least significant bit of `index`,
186 /// and will be executed for `tree_depth` bits.
187 ///
188 /// # Errors
189 /// Will return an error if:
190 /// - The provided root is not found.
191 /// - The path from the root continues to a depth greater than `tree_depth`.
192 /// - The provided `tree_depth` is greater than `64.
193 /// - The provided `index` is not valid for a depth equivalent to `tree_depth`. For more
194 /// information, check [NodeIndex::new].
195 pub fn get_leaf_depth(
196 &self,
197 root: RpoDigest,
198 tree_depth: u8,
199 index: u64,
200 ) -> Result<u8, MerkleError> {
201 // validate depth and index
202 if tree_depth > 64 {
203 return Err(MerkleError::DepthTooBig(tree_depth as u64));
204 }
205 NodeIndex::new(tree_depth, index)?;
206
207 // it's not illegal to have a maximum depth of `0`; we should just return the root in that
208 // case. this check will simplify the implementation as we could overflow bits for depth
209 // `0`.
210 if tree_depth == 0 {
211 return Ok(0);
212 }
213
214 // check if the root exists, providing the proper error report if it doesn't
215 let empty = EmptySubtreeRoots::empty_hashes(tree_depth);
216 let mut hash = root;
217 if !self.nodes.contains_key(&hash) {
218 return Err(MerkleError::RootNotInStore(hash));
219 }
220
221 // we traverse from root to leaf, so the path is reversed
222 let mut path = (index << (64 - tree_depth)).reverse_bits();
223
224 // iterate every depth and reconstruct the path from root to leaf
225 for depth in 0..tree_depth {
226 // we short-circuit if an empty node has been found
227 if hash == empty[depth as usize] {
228 return Ok(depth);
229 }
230
231 // fetch the children pair, mapped by its parent hash
232 let children = match self.nodes.get(&hash) {
233 Some(node) => node,
234 None => return Ok(depth),
235 };
236
237 // traverse down
238 hash = if path & 1 == 0 { children.left } else { children.right };
239 path >>= 1;
240 }
241
242 // at max depth assert it doesn't have sub-trees
243 if self.nodes.contains_key(&hash) {
244 return Err(MerkleError::DepthTooBig(tree_depth as u64 + 1));
245 }
246
247 // depleted bits; return max depth
248 Ok(tree_depth)
249 }
250
251 // DATA EXTRACTORS
252 // --------------------------------------------------------------------------------------------
253
254 /// Returns a subset of this Merkle store such that the returned Merkle store contains all
255 /// nodes which are descendants of the specified roots.
256 ///
257 /// The roots for which no descendants exist in this Merkle store are ignored.
258 pub fn subset<I, R>(&self, roots: I) -> MerkleStore<T>
259 where
260 I: Iterator<Item = R>,
261 R: Borrow<RpoDigest>,
262 {
263 let mut store = MerkleStore::new();
264 for root in roots {
265 let root = *root.borrow();
266 store.clone_tree_from(root, self);
267 }
268 store
269 }
270
271 /// Iterator over the inner nodes of the [MerkleStore].
272 pub fn inner_nodes(&self) -> impl Iterator<Item = InnerNodeInfo> + '_ {
273 self.nodes.iter().map(|(r, n)| InnerNodeInfo {
274 value: *r,
275 left: n.left,
276 right: n.right,
277 })
278 }
279
280 // STATE MUTATORS
281 // --------------------------------------------------------------------------------------------
282
283 /// Adds all the nodes of a Merkle path represented by `path`, opening to `node`. Returns the
284 /// new root.
285 ///
286 /// This will compute the sibling elements determined by the Merkle `path` and `node`, and
287 /// include all the nodes into the store.
288 pub fn add_merkle_path(
289 &mut self,
290 index: u64,
291 node: RpoDigest,
292 path: MerklePath,
293 ) -> Result<RpoDigest, MerkleError> {
294 let root = path.inner_nodes(index, node)?.fold(RpoDigest::default(), |_, node| {
295 let value: RpoDigest = node.value;
296 let left: RpoDigest = node.left;
297 let right: RpoDigest = node.right;
298
299 debug_assert_eq!(Rpo256::merge(&[left, right]), value);
300 self.nodes.insert(value, Node { left, right });
301
302 node.value
303 });
304 Ok(root)
305 }
306
307 /// Adds all the nodes of multiple Merkle paths into the store.
308 ///
309 /// This will compute the sibling elements for each Merkle `path` and include all the nodes
310 /// into the store.
311 ///
312 /// For further reference, check [MerkleStore::add_merkle_path].
313 pub fn add_merkle_paths<I>(&mut self, paths: I) -> Result<(), MerkleError>
314 where
315 I: IntoIterator<Item = (u64, RpoDigest, MerklePath)>,
316 {
317 for (index_value, node, path) in paths.into_iter() {
318 self.add_merkle_path(index_value, node, path)?;
319 }
320 Ok(())
321 }
322
323 /// Appends the provided [MerklePathSet] into the store.
324 ///
325 /// For further reference, check [MerkleStore::add_merkle_path].
326 pub fn add_merkle_path_set(
327 &mut self,
328 path_set: &MerklePathSet,
329 ) -> Result<RpoDigest, MerkleError> {
330 let root = path_set.root();
331 for (index, path) in path_set.to_paths() {
332 self.add_merkle_path(index, path.value, path.path)?;
333 }
334 Ok(root)
335 }
336
337 /// Sets a node to `value`.
338 ///
339 /// # Errors
340 /// This method can return the following errors:
341 /// - `RootNotInStore` if the `root` is not present in the store.
342 /// - `NodeNotInStore` if a node needed to traverse from `root` to `index` is not present in
343 /// the store.
344 pub fn set_node(
345 &mut self,
346 mut root: RpoDigest,
347 index: NodeIndex,
348 value: RpoDigest,
349 ) -> Result<RootPath, MerkleError> {
350 let node = value;
351 let ValuePath { value, path } = self.get_path(root, index)?;
352
353 // performs the update only if the node value differs from the opening
354 if node != value {
355 root = self.add_merkle_path(index.value(), node, path.clone())?;
356 }
357
358 Ok(RootPath { root, path })
359 }
360
361 /// Merges two elements and adds the resulting node into the store.
362 ///
363 /// Merges arbitrary values. They may be leafs, nodes, or a mixture of both.
364 pub fn merge_roots(
365 &mut self,
366 left_root: RpoDigest,
367 right_root: RpoDigest,
368 ) -> Result<RpoDigest, MerkleError> {
369 let parent = Rpo256::merge(&[left_root, right_root]);
370 self.nodes.insert(
371 parent,
372 Node {
373 left: left_root,
374 right: right_root,
375 },
376 );
377
378 Ok(parent)
379 }
380
381 // DESTRUCTURING
382 // --------------------------------------------------------------------------------------------
383
384 /// Returns the inner storage of this MerkleStore while consuming `self`.
385 pub fn into_inner(self) -> T {
386 self.nodes
387 }
388
389 // HELPER METHODS
390 // --------------------------------------------------------------------------------------------
391
392 /// Recursively clones a tree with the specified root from the specified source into self.
393 ///
394 /// If the source store does not contain a tree with the specified root, this is a noop.
395 fn clone_tree_from(&mut self, root: RpoDigest, source: &Self) {
396 // process the node only if it is in the source
397 if let Some(node) = source.nodes.get(&root) {
398 // if the node has already been inserted, no need to process it further as all of its
399 // descendants should be already cloned from the source store
400 if self.nodes.insert(root, *node).is_none() {
401 self.clone_tree_from(node.left, source);
402 self.clone_tree_from(node.right, source);
403 }
404 }
405 }
406}
407
408// CONVERSIONS
409// ================================================================================================
410
411impl<T: KvMap<RpoDigest, Node>> From<&MerkleTree> for MerkleStore<T> {
412 fn from(value: &MerkleTree) -> Self {
413 let nodes = combine_nodes_with_empty_hashes(value.inner_nodes()).collect();
414 Self { nodes }
415 }
416}
417
418impl<T: KvMap<RpoDigest, Node>> From<&SimpleSmt> for MerkleStore<T> {
419 fn from(value: &SimpleSmt) -> Self {
420 let nodes = combine_nodes_with_empty_hashes(value.inner_nodes()).collect();
421 Self { nodes }
422 }
423}
424
425impl<T: KvMap<RpoDigest, Node>> From<&Mmr> for MerkleStore<T> {
426 fn from(value: &Mmr) -> Self {
427 let nodes = combine_nodes_with_empty_hashes(value.inner_nodes()).collect();
428 Self { nodes }
429 }
430}
431
432impl<T: KvMap<RpoDigest, Node>> From<&TieredSmt> for MerkleStore<T> {
433 fn from(value: &TieredSmt) -> Self {
434 let nodes = combine_nodes_with_empty_hashes(value.inner_nodes()).collect();
435 Self { nodes }
436 }
437}
438
439impl<T: KvMap<RpoDigest, Node>> From<T> for MerkleStore<T> {
440 fn from(values: T) -> Self {
441 let nodes = values.into_iter().chain(empty_hashes().into_iter()).collect();
442 Self { nodes }
443 }
444}
445
446impl<T: KvMap<RpoDigest, Node>> FromIterator<InnerNodeInfo> for MerkleStore<T> {
447 fn from_iter<I: IntoIterator<Item = InnerNodeInfo>>(iter: I) -> Self {
448 let nodes = combine_nodes_with_empty_hashes(iter.into_iter()).collect();
449 Self { nodes }
450 }
451}
452
453impl<T: KvMap<RpoDigest, Node>> FromIterator<(RpoDigest, Node)> for MerkleStore<T> {
454 fn from_iter<I: IntoIterator<Item = (RpoDigest, Node)>>(iter: I) -> Self {
455 let nodes = iter.into_iter().chain(empty_hashes().into_iter()).collect();
456 Self { nodes }
457 }
458}
459
460// ITERATORS
461// ================================================================================================
462
463impl<T: KvMap<RpoDigest, Node>> Extend<InnerNodeInfo> for MerkleStore<T> {
464 fn extend<I: IntoIterator<Item = InnerNodeInfo>>(&mut self, iter: I) {
465 self.nodes.extend(iter.into_iter().map(|info| {
466 (
467 info.value,
468 Node {
469 left: info.left,
470 right: info.right,
471 },
472 )
473 }));
474 }
475}
476
477// SERIALIZATION
478// ================================================================================================
479
480impl Serializable for Node {
481 fn write_into<W: ByteWriter>(&self, target: &mut W) {
482 self.left.write_into(target);
483 self.right.write_into(target);
484 }
485}
486
487impl Deserializable for Node {
488 fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
489 let left = RpoDigest::read_from(source)?;
490 let right = RpoDigest::read_from(source)?;
491 Ok(Node { left, right })
492 }
493}
494
495impl<T: KvMap<RpoDigest, Node>> Serializable for MerkleStore<T> {
496 fn write_into<W: ByteWriter>(&self, target: &mut W) {
497 target.write_u64(self.nodes.len() as u64);
498
499 for (k, v) in self.nodes.iter() {
500 k.write_into(target);
501 v.write_into(target);
502 }
503 }
504}
505
506impl<T: KvMap<RpoDigest, Node>> Deserializable for MerkleStore<T> {
507 fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
508 let len = source.read_u64()?;
509 let mut nodes: Vec<(RpoDigest, Node)> = Vec::with_capacity(len as usize);
510
511 for _ in 0..len {
512 let key = RpoDigest::read_from(source)?;
513 let value = Node::read_from(source)?;
514 nodes.push((key, value));
515 }
516
517 Ok(nodes.into_iter().collect())
518 }
519}
520
521// HELPER FUNCTIONS
522// ================================================================================================
523
524/// Creates empty hashes for all the subtrees of a tree with a max depth of 255.
525fn empty_hashes() -> impl IntoIterator<Item = (RpoDigest, Node)> {
526 let subtrees = EmptySubtreeRoots::empty_hashes(255);
527 subtrees.iter().rev().copied().zip(subtrees.iter().rev().skip(1).copied()).map(
528 |(child, parent)| {
529 (
530 parent,
531 Node {
532 left: child,
533 right: child,
534 },
535 )
536 },
537 )
538}
539
540/// Consumes an iterator of [InnerNodeInfo] and returns an iterator of `(value, node)` tuples
541/// which includes the nodes associate with roots of empty subtrees up to a depth of 255.
542fn combine_nodes_with_empty_hashes(
543 nodes: impl IntoIterator<Item = InnerNodeInfo>,
544) -> impl Iterator<Item = (RpoDigest, Node)> {
545 nodes
546 .into_iter()
547 .map(|info| {
548 (
549 info.value,
550 Node {
551 left: info.left,
552 right: info.right,
553 },
554 )
555 })
556 .chain(empty_hashes().into_iter())
557}