From 8fa9ad5b48cbcc6736f2fa26a83d05066708e7ab Mon Sep 17 00:00:00 2001 From: Qyriad Date: Fri, 8 Nov 2024 12:53:28 -0700 Subject: [PATCH] improve docs for build_subtree() --- src/merkle/smt/full/mod.rs | 13 +++++++++++++ src/merkle/smt/mod.rs | 16 +++++++++------- 2 files changed, 22 insertions(+), 7 deletions(-) diff --git a/src/merkle/smt/full/mod.rs b/src/merkle/smt/full/mod.rs index 34a677c..9c08f26 100644 --- a/src/merkle/smt/full/mod.rs +++ b/src/merkle/smt/full/mod.rs @@ -238,6 +238,19 @@ impl Smt { } } + /// Builds Merkle nodes from a bottom layer of "leaves" -- represented by a horizontal index and + /// the hash of the leaf at that index. `leaves` *must* be sorted by horizontal index, and + /// `leaves` must not contain more than one depth-8 subtree's worth of leaves. + /// + /// This function will then calculate the inner nodes above each leaf for 8 layers, as well as + /// the "leaves" for the next 8-deep subtree, so this function can effectively be chained into + /// itself. + /// + /// # Panics + /// With debug assertions on, this function panics under invalid inputs: if `leaves` contains + /// more entries than can fit in a depth-8 subtree, if `leaves` contains leaves belonging to + /// different depth-8 subtrees, if `bottom_depth` is lower in the tree than the specified + /// maximum depth (`DEPTH`), or if `leaves` is not sorted. pub fn build_subtree( leaves: Vec, bottom_depth: u8, diff --git a/src/merkle/smt/mod.rs b/src/merkle/smt/mod.rs index 22b6d53..196fd92 100644 --- a/src/merkle/smt/mod.rs +++ b/src/merkle/smt/mod.rs @@ -406,17 +406,19 @@ pub(crate) trait SparseMerkleTree { accumulator } - /// Builds Merkle nodes from a bottom layer of tuples of horizontal indices and their hashes, - /// sorted by their position. + /// Builds Merkle nodes from a bottom layer of "leaves" -- represented by a horizontal index and + /// the hash of the leaf at that index. `leaves` *must* be sorted by horizontal index, and + /// `leaves` must not contain more than one depth-8 subtree's worth of leaves. /// - /// The leaves are 'conceptual' leaves, simply being entities at the bottom of some subtree, not - /// [`Self::Leaf`]. + /// This function will then calculate the inner nodes above each leaf for 8 layers, as well as + /// the "leaves" for the next 8-deep subtree, so this function can effectively be chained into + /// itself. /// /// # Panics /// With debug assertions on, this function panics under invalid inputs: if `leaves` contains - /// more entries than can fit in a depth-8 subtree (more than 256), if `bottom_depth` is - /// lower in the tree than the specified maximum depth (`DEPTH`), or if `leaves` is not sorted. - // FIXME: more complete docstring. + /// more entries than can fit in a depth-8 subtree, if `leaves` contains leaves belonging to + /// different depth-8 subtrees, if `bottom_depth` is lower in the tree than the specified + /// maximum depth (`DEPTH`), or if `leaves` is not sorted. fn build_subtree( mut leaves: Vec, bottom_depth: u8,