tweaks

Author: roberto-bayardo

storage/src/merkle/proof.rs

@@ -629,23 +629,15 @@ impl<F: Family, D: Digest> Proof<F, D> {
         }
 
         let range = start_loc..end_loc;
-        // Bagging only governs the prefix/suffix accumulator layout, which this method
-        // deliberately ignores; `range_peaks` and `fetch_nodes` are bagging-independent. Pass
-        // ForwardFold as a placeholder.
-        let bp = Blueprint::new(
-            self.leaves,
-            self.inactive_peaks,
-            Bagging::ForwardFold,
-            range,
-        )
-        .map_err(|_| ReconstructionError::InvalidSize)?;
+        let peaks = range_peaks(self.leaves, self.inactive_peaks, &range)
+            .map_err(|_| ReconstructionError::InvalidSize)?;
 
         let mut sibling_cursor = 0usize;
         let mut elements_iter = elements.iter();
-        for peak in &bp.range_peaks {
+        for peak in &peaks {
             let peak_digest = peak.reconstruct_digest(
                 hasher,
-                &bp.range,
+                &range,
                 &mut elements_iter,
                 &self.digests,
                 &mut sibling_cursor,
@@ -846,6 +838,25 @@ impl<F: Family> Subtree<F> {
     }
 }
 
+/// Return the peaks of a tree of `leaves` that overlap `range`, validating both the range and the
+/// declared `inactive_peaks` boundary.
+///
+/// The returned subtrees are bagging-independent: `Blueprint::new`'s prefix/suffix accumulator
+/// layout depends on bagging, but the per-peak partition of the proven range does not.
+///
+/// # Errors
+///
+/// See [`Blueprint::new`].
+pub(crate) fn range_peaks<F: Family>(
+    leaves: Location<F>,
+    inactive_peaks: usize,
+    range: &Range<Location<F>>,
+) -> Result<Vec<Subtree<F>>, super::Error<F>> {
+    // Bagging only affects `Blueprint`'s prefix/suffix bucketing; `range_peaks` is independent.
+    Blueprint::new(leaves, inactive_peaks, Bagging::ForwardFold, range.clone())
+        .map(|bp| bp.range_peaks)
+}
+
 /// Blueprint for a range proof, separating fold-prefix peaks from nodes that must be fetched.
 pub(crate) struct Blueprint<F: Family> {
     /// Total number of leaves in the structure this blueprint was built for.
@@ -1135,34 +1146,34 @@ where
 }
 
 /// Return the node positions needed by [`build_range_collection_proof`].
-///
-/// Bagging only governs prefix/suffix accumulator layout, which this helper does not consult; the
-/// `range_peaks` siblings it collects are bagging-independent. ForwardFold is passed as a
-/// placeholder.
 #[cfg(feature = "std")]
 pub(crate) fn range_collection_nodes<F: Family>(
     leaves: Location<F>,
     inactive_peaks: usize,
     range: Range<Location<F>>,
 ) -> Result<Vec<Position<F>>, super::Error<F>> {
-    let bp = Blueprint::new(leaves, inactive_peaks, Bagging::ForwardFold, range)?;
+    let peaks = range_peaks(leaves, inactive_peaks, &range)?;
     let mut fetch_nodes = Vec::new();
-    for peak in &bp.range_peaks {
-        peak.collect_siblings(&bp.range, &mut fetch_nodes);
+    for peak in &peaks {
+        peak.collect_siblings(&range, &mut fetch_nodes);
     }
     Ok(fetch_nodes)
 }
 
 /// Build a proof containing only the sibling digests needed to authenticate the requested range.
 ///
+/// `fetch_nodes` must be the slice returned by [`range_collection_nodes`] for the same `leaves` and
+/// `inactive_peaks`; the caller passes it in so the Blueprint traversal isn't repeated when the
+/// positions are already known (e.g., to drive concurrent fetching).
+///
 /// The resulting proof cannot reconstruct a complete generic Merkle root on its own. It is intended
 /// for wrappers that rebuild a custom root from separately supplied peak witnesses, such as current
 /// QMDB grafted proofs.
 #[cfg(feature = "std")]
 pub(crate) fn build_range_collection_proof<F, D, E>(
     leaves: Location<F>,
     inactive_peaks: usize,
-    range: Range<Location<F>>,
+    fetch_nodes: &[Position<F>],
     get_node: impl Fn(Position<F>) -> Option<D>,
     element_pruned: impl Fn(Position<F>) -> E,
 ) -> Result<Proof<F, D>, E>
@@ -1171,9 +1182,8 @@ where
     D: Digest,
     E: From<super::Error<F>>,
 {
-    let fetch_nodes = range_collection_nodes(leaves, inactive_peaks, range)?;
     let mut digests = Vec::with_capacity(fetch_nodes.len());
-    for pos in fetch_nodes {
+    for &pos in fetch_nodes {
         digests.push(get_node(pos).ok_or_else(|| element_pruned(pos))?);
     }
 

storage/src/qmdb/current/db.rs

@@ -784,7 +784,8 @@ pub(super) async fn compute_db_root<
 /// grafting height. Therefore, a single bitmap chunk may span across multiple smaller ops peaks.
 /// `grafting::grafted_root` intercepts the folding process to group these sub-grafting-height peaks,
 /// hash them together with their corresponding bitmap chunks, and then complete the final fold using
-/// the QMDB root spec. For MMR, this produces the exact same result as `hasher.root()`.
+/// the hasher's peak-bagging policy. For MMR, each complete chunk already appears as a single
+/// grafted peak, so no extra peak regrouping is needed.
 pub(super) async fn compute_grafted_root<
     F: merkle::Graftable,
     H: Hasher,

storage/src/qmdb/current/mod.rs

@@ -223,7 +223,7 @@
 //!
 //! This combines two (or three) components into a single hash:
 //!
-//! - **QMDB ops root**: The root of the operations tree computed using the QMDB root spec for
+//! - **ops root**: The root of the operations tree computed using the QMDB root spec for
 //!   the Merkle family (the inner [crate::qmdb::any] database's root). Used for state sync,
 //!   where a client downloads operations and verifies each batch against this root using QMDB
 //!   range proofs.
@@ -236,10 +236,10 @@
 //!   usually incomplete. Its digest and bit count are folded into the canonical root hash.
 //!
 //! The canonical root is returned by [Db](db::Db)`::`[root()](db::Db::root).
-//! The QMDB ops root is returned by the `sync::Database` trait's `root()` method, since the sync
+//! The ops root is returned by the `sync::Database` trait's `root()` method, since the sync
 //! engine verifies batches against the ops root, not the canonical root.
 //!
-//! For state sync, the sync engine targets the QMDB ops root and verifies each batch against it.
+//! For state sync, the sync engine targets the ops root and verifies each batch against it.
 //! After sync, the bitmap and grafted tree are reconstructed deterministically from the
 //! operations, and the canonical root is computed. [proof::OpsRootWitness] can be used to validate
 //! that a particular ops root is committed by a trusted canonical root; the sync engine does not

storage/src/qmdb/current/proof.rs

@@ -444,8 +444,9 @@ impl<F: Graftable, D: Digest> RangeProof<F, D> {
         let mut unfolded_prefix_peaks = Vec::new();
         let mut unfolded_suffix_peaks = Vec::new();
         let proof = if needs_grafted_peak_fold {
-            let mut positions =
+            let collection_positions =
                 merkle::range_collection_nodes(leaves, inactive_peaks, range.clone())?;
+            let mut positions = collection_positions.clone();
             positions.extend(layout.prefix.iter().map(|&(pos, _)| pos));
             positions.extend(layout.after.iter().map(|&(pos, _)| pos));
             positions.sort_unstable();
@@ -471,7 +472,7 @@ impl<F: Graftable, D: Digest> RangeProof<F, D> {
             let proof = merkle::build_range_collection_proof::<F, D, Error<F>>(
                 leaves,
                 inactive_peaks,
-                range.clone(),
+                &collection_positions,
                 |pos| fetched.get(&pos).copied(),
                 |pos| Error::from(merkle::Error::<F>::MissingNode(pos)),
             )?;

storage/src/qmdb/current/sync/mod.rs

@@ -3,21 +3,20 @@
 //! Contains implementation of [crate::qmdb::sync::Database] for all [Db](crate::qmdb::current::db::Db)
 //! variants (ordered/unordered, fixed/variable).
 //!
-//! The canonical root of a `current` database combines the QMDB ops root, grafted tree root, and
+//! The canonical root of a `current` database combines the ops root, grafted tree root, and
 //! optional partial chunk into a single hash (see the [Root structure](super) section in the
-//! module documentation). The sync engine operates on the **QMDB ops root**, not the canonical
-//! root: it downloads operations and verifies each batch against the QMDB ops-root spec for the
-//! Merkle family.
-//! [crate::qmdb::current::proof::OpsRootWitness] can be used by callers that need to authenticate
-//! the synced ops root against a trusted canonical root; the sync engine does not perform this
-//! check itself.
+//! module documentation). The sync engine operates on the **ops root**, not the canonical root:
+//! it downloads operations and verifies each batch against the ops root using standard merkle
+//! range proofs (identical to `any` sync). [crate::qmdb::current::proof::OpsRootWitness] can be
+//! used by callers that need to authenticate the synced ops root against a trusted canonical root;
+//! the sync engine does not perform this check itself.
 //!
 //! After all operations are synced, the bitmap and grafted tree are reconstructed
 //! deterministically from the operations. The canonical root is then computed from the
-//! QMDB ops root, the reconstructed grafted tree root, and any partial chunk.
+//! ops root, the reconstructed grafted tree root, and any partial chunk.
 //!
 //! The [Database]`::`[root()](crate::qmdb::sync::Database::root)
-//! implementation returns the **QMDB ops root** (not the canonical root) because that is what the
+//! implementation returns the **ops root** (not the canonical root) because that is what the
 //! sync engine verifies against.
 //!
 //! For pruned databases (`range.start > 0`), grafted pinned nodes for the pruned region are
@@ -52,6 +51,7 @@ use crate::{
             },
             FixedValue, VariableValue,
         },
+        bitmap::Shared,
         current::{
             db, grafting,
             ordered::{
@@ -137,17 +137,19 @@ where
     )
     .await?;
 
-    // Pre-build the activity-status bitmap with the pruned-chunk count derived from the sync
-    // range, then hand it to `any::Db::init_from_log` which becomes the sole owner. Floor
-    // division is intentional: chunks entirely below range.start are pruned. If range.start
-    // is not chunk-aligned, the partial leading chunk is reconstructed by `init_from_log`,
-    // which pads the gap between `pruned_chunks * CHUNK_SIZE_BITS` and the journal's
-    // inactivity floor with inactive (false) bits.
+    // Initialize bitmap with pruned chunks.
+    //
+    // Floor division is intentional: chunks entirely below range.start are pruned.
+    // If range.start is not chunk-aligned, the partial leading chunk is reconstructed by
+    // init_from_log, which pads the gap between `pruned_chunks * CHUNK_SIZE_BITS` and the
+    // journal's inactivity floor with inactive (false) bits.
     let pruned_chunks = (*range.start() / BitMap::<N>::CHUNK_SIZE_BITS) as usize;
     let bitmap = BitMap::<N>::new_with_pruned_chunks(pruned_chunks)
         .map_err(|_| qmdb::Error::<F>::DataCorrupted("pruned chunks overflow"))?;
-    let bitmap = Arc::new(qmdb::bitmap::Shared::<N>::new(bitmap));
+    let bitmap = Arc::new(Shared::<N>::new(bitmap));
 
+    // Build any::Db, handing it the pre-allocated bitmap. `init_from_log` populates the bitmap
+    // during replay.
     let any: AnyDb<F, E, J, I, H, U, N, S> = AnyDb::init_from_log(index, log, Some(bitmap)).await?;
 
     // Fetch grafted pinned nodes from the ops tree. For each position the grafted family
@@ -333,7 +335,7 @@ macro_rules! impl_current_sync_database {
                 true
             }
 
-            /// Returns the QMDB ops root (not the canonical root), since the sync engine verifies
+            /// Returns the ops root (not the canonical root), since the sync engine verifies
             /// batches against the ops tree.
             fn root(&self) -> Self::Digest {
                 self.any.root()
@@ -373,7 +375,7 @@ impl_current_sync_database!(
 // --- Resolver implementations ---
 //
 // The resolver for `current` databases serves ops-level proofs (not grafted proofs) from
-// the inner `any` db. The sync engine verifies each batch against the QMDB ops root.
+// the inner `any` db. The sync engine verifies each batch against the ops root.
 
 macro_rules! impl_current_resolver {
     ($db:ident, $op:ident, $val_bound:ident, $key_bound:path $(; $($where_extra:tt)+)?) => {