From 953e5f930377495b2ebbe6680b7b4daa15a66123 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Thu, 13 Aug 2026 23:18:53 +0700 Subject: [PATCH 1/5] =?UTF-8?q?feat:=20branched=20indexed-axis=20proofs=20?= =?UTF-8?q?=E2=80=94=20one=20envelope=20over=20N=20sibling=20prefix=20bran?= =?UTF-8?q?ches?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A query pinning several prefix values at once (IN over a compound index's leading property) reads N sibling indexed trees whose paths differ at exactly one segment. Until now each branch needed its own full envelope, duplicating every ancestor layer N times and leaving the caller to cross-check N root hashes. The branched envelopes (IndexedAxisBranchedRangeProof / IndexedAxisBranchedPaginatedProof) share what is shared: the layers above the branching level appear once; the branching level is one multi-key Merk proof binding every branch's value tree simultaneously; each branch carries only its tail (layers below its key, its primary/other-axes attestations, its secondary proof). One root hash is reconstructed for the whole envelope. Verification composes the audited single-path building blocks: each branch tail runs through verify_deepest_layer + walk_ancestor_chain on the suffix window, the branch's value-tree root must recompose to the value_hash the multi-key proof recorded for that key (so tails cannot be swapped, duplicated, or reordered), and one shared walk chains the branching Merk's root to the GroveDB root. Prove-side reuses the existing envelope builders per branch and splits at the branching depth — no storage or hash-composition changes anywhere. Covered by indexed_axis_branched_proof_tests: range and paginated round trips against the live root hash, reordered branch keys, duplicated branch tails, echo and branch-count mismatches, and degenerate key lists. Co-Authored-By: Claude Fable 5 --- .../operations/proof/indexed_axis/branched.rs | 749 ++++++++++++++++++ .../operations/proof/indexed_axis/envelope.rs | 104 +++ .../operations/proof/indexed_axis/generate.rs | 4 +- .../src/operations/proof/indexed_axis/mod.rs | 9 +- .../operations/proof/indexed_axis/verify.rs | 12 +- .../indexed_axis_branched_proof_tests.rs | 449 +++++++++++ grovedb/src/tests/mod.rs | 1 + 7 files changed, 1317 insertions(+), 11 deletions(-) create mode 100644 grovedb/src/operations/proof/indexed_axis/branched.rs create mode 100644 grovedb/src/tests/indexed_axis_branched_proof_tests.rs diff --git a/grovedb/src/operations/proof/indexed_axis/branched.rs b/grovedb/src/operations/proof/indexed_axis/branched.rs new file mode 100644 index 000000000..f9cabdf39 --- /dev/null +++ b/grovedb/src/operations/proof/indexed_axis/branched.rs @@ -0,0 +1,749 @@ +//! Branched (multi-prefix) indexed-axis proofs: one query over N +//! sibling prefix branches, attested by a **single envelope** with a +//! single reconstructed root hash. +//! +//! ## Why this shape exists +//! +//! A compound index lays one indexed tree per prefix value: +//! `…///…/`. A query that pins several +//! prefix values at once (`prefix IN [a, b, c]`) reads N sibling +//! indexed trees whose paths differ at exactly one segment — the +//! *branching level*. Proving each branch separately duplicates every +//! layer above the branching level N times and forces the caller to +//! cross-check N root hashes. This envelope shares what is shared: +//! +//! - the layers **above** the branching level appear once +//! (`shared_layer_proofs` + `shared_ancestor_attestations`); +//! - the branching level is **one multi-key Merk proof** binding every +//! branch's value tree in the shared parent Merk simultaneously +//! (`branching_layer_proof`); +//! - each branch carries only its own tail: the layers below its +//! branch key, its primary/other-axes attestations, and its +//! secondary proof. +//! +//! ## Chain of trust +//! +//! Verification runs strictly upward, per branch first: the branch's +//! secondary proof yields its secondary root hash; the deepest tail +//! layer binds that hash (and the primary root) into the indexed-tree +//! element's recorded `value_hash`; the tail walk reconstructs the +//! branch's value-tree root. That root, composed with the branch +//! element's bytes **from the multi-key proof**, must equal the +//! `value_hash` the multi-key proof recorded for the branch's key — so +//! a branch tail cannot be swapped, duplicated, or re-ordered without +//! the composition failing. The multi-key proof's own root then seeds +//! one shared ancestor walk up to the GroveDB root hash. +//! +//! Everything here reuses the audited single-path building blocks: +//! per-branch envelopes are produced by the existing builders and +//! split at the branching level, and verification reuses +//! [`verify_deepest_layer`] and [`walk_ancestor_chain`] verbatim on +//! the tail and shared windows. + +use grovedb_costs::{ + cost_return_on_error, cost_return_on_error_no_add, CostResult, CostsExt, OperationCost, +}; +use grovedb_element::indexed::IndexAxis; +use grovedb_merk::proofs::query::{ + verify_count_offset_on_range_proof, QueryItem as MerkQueryItemForRange, +}; +use grovedb_merk::tree::axes_digest; +use grovedb_merk::{ + proofs::{query::QueryProofVerify, Query as MerkQuery}, + tree::{combine_hash, combine_hash_three, value_hash, CryptoHash}, +}; +use grovedb_path::SubtreePath; +use grovedb_query::QueryItem as MerkQueryItem; +use grovedb_storage::StorageBatch; +use grovedb_version::version::GroveVersion; + +use crate::{util::TxRef, Error, GroveDb, TransactionArg}; + +use super::verify::{ + decode_axis_entries_from_count_offset_items, decode_axis_entries_from_result_set, + reject_trailing_envelope_bytes, verify_deepest_layer, walk_ancestor_chain, +}; +use super::{ + AncestorAttestation, BranchedProofBranch, IndexedAxisBranchedPaginatedProof, + IndexedAxisBranchedPaginatedResult, IndexedAxisBranchedQueryResult, + IndexedAxisBranchedRangeProof, +}; + +/// Validate the branch-key list shared by the prove and verify entry +/// points: at least two keys (one branch is the single-path envelope's +/// job), pairwise distinct (a duplicated key is one subtree walked +/// twice — a caller error, and it would make branch alignment +/// ambiguous). +fn validate_branch_keys(branch_keys: &[Vec], err_label: &'static str) -> Result<(), Error> { + if branch_keys.len() < 2 { + return Err(Error::InvalidInput( + "branched indexed-axis proofs require at least two branch keys; use the \ + single-path envelope for one", + )); + } + let mut sorted: Vec<&Vec> = branch_keys.iter().collect(); + sorted.sort(); + if sorted.windows(2).any(|pair| pair[0] == pair[1]) { + return Err(Error::CorruptedData(format!( + "{err_label}: duplicate branch keys — each branch key names one value tree \ + and may appear once" + ))); + } + Ok(()) +} + +/// Compose an intermediate layer's recorded `value_hash` from its +/// element bytes, its child Merk's root, and its attestation — the +/// same three-way rule [`walk_ancestor_chain`] applies per layer, +/// exposed for the branching-level check where the element bytes come +/// from the multi-key proof instead of a single-key layer proof. +fn compose_intermediate( + element_bytes: &[u8], + child_root: &CryptoHash, + attestation: &AncestorAttestation, +) -> CryptoHash { + let val_h = value_hash(element_bytes).value().to_owned(); + match attestation { + AncestorAttestation::NotIndexed => combine_hash(&val_h, child_root).value().to_owned(), + AncestorAttestation::SingleSecondary(secondary_root) => { + combine_hash_three(&val_h, child_root, secondary_root) + .value() + .to_owned() + } + AncestorAttestation::MultiAxis(axes) => { + let digest = axes_digest(axes).value().to_owned(); + combine_hash_three(&val_h, child_root, &digest) + .value() + .to_owned() + } + } +} + +/// Execute the branching-level multi-key proof: one Merk proof +/// covering every branch key in the shared prefix's Merk. Returns the +/// layer's root hash plus, aligned with `branch_keys`, each key's +/// element bytes and the `value_hash` the parent Merk records for it. +fn execute_multi_key_proof( + proof_bytes: &[u8], + branch_keys: &[Vec], + err_label: &'static str, +) -> Result<(CryptoHash, Vec<(Vec, CryptoHash)>), Error> { + let mut query = MerkQuery::new(); + for key in branch_keys { + query.insert_item(MerkQueryItem::Key(key.clone())); + } + let (root_hash, result) = query + .execute_proof(proof_bytes, None, true, 0) + .unwrap() + .map_err(|e| { + Error::CorruptedData(format!( + "{err_label}: branching-level multi-key proof failed to verify: {e}" + )) + })?; + let mut per_key = Vec::with_capacity(branch_keys.len()); + for key in branch_keys { + let proved = result + .result_set + .iter() + .find(|p| &p.key == key) + .ok_or_else(|| { + Error::CorruptedData(format!( + "{err_label}: branching-level proof does not contain branch key {}", + hex::encode(key) + )) + })?; + let value = proved.value.clone().ok_or_else(|| { + Error::CorruptedData(format!( + "{err_label}: branching-level proof carries no value for branch key {}", + hex::encode(key) + )) + })?; + per_key.push((value, proved.proof)); + } + Ok((root_hash, per_key)) +} + +/// The shared upward walk of a branched envelope, after every branch's +/// tail has been verified: check each branch's composition against the +/// multi-key proof's recorded hashes, then chain the shared layers to +/// the GroveDB root. +/// +/// `branch_tail_roots[i]` is branch `i`'s reconstructed value-tree +/// root (the output of that branch's tail walk), and +/// `branch_first_attestations[i]` describes branch `i`'s value-tree +/// element. +#[allow(clippy::too_many_arguments)] +fn verify_branching_and_shared_layers( + shared_layer_proofs: &[Vec], + shared_ancestor_attestations: &[AncestorAttestation], + branching_layer_proof: &[u8], + branch_keys: &[Vec], + path_prefix: &[&[u8]], + branch_tail_roots: &[CryptoHash], + branch_first_attestations: &[&AncestorAttestation], + err_label: &'static str, +) -> Result { + if shared_layer_proofs.len() != path_prefix.len() { + return Err(Error::CorruptedData(format!( + "{err_label}: envelope has {} shared layers but the path prefix has {} segments", + shared_layer_proofs.len(), + path_prefix.len() + ))); + } + if shared_ancestor_attestations.len() != shared_layer_proofs.len() { + return Err(Error::CorruptedData(format!( + "{err_label}: envelope has {} shared attestations but {} shared layers", + shared_ancestor_attestations.len(), + shared_layer_proofs.len() + ))); + } + + let (branching_root, per_key) = + execute_multi_key_proof(branching_layer_proof, branch_keys, err_label)?; + for (branch, ((element_bytes, recorded_hash), tail_root)) in + per_key.iter().zip(branch_tail_roots.iter()).enumerate() + { + let combined = + compose_intermediate(element_bytes, tail_root, branch_first_attestations[branch]); + if combined != *recorded_hash { + return Err(Error::CorruptedData(format!( + "{err_label}: branch {branch} (key {}) chain mismatch at the branching \ + level: the branch tail reconstructs a different subtree than the \ + multi-key proof commits — a swapped, re-ordered, or foreign branch tail", + hex::encode(&branch_keys[branch]) + ))); + } + } + + // The shared walk consumes every shared layer proof: frame the + // branching-level proof as the (already-consumed) deepest layer so + // `walk_ancestor_chain`'s indexing lines up, and seed it with the + // branching Merk's root. + let mut layers: Vec> = Vec::with_capacity(shared_layer_proofs.len() + 1); + layers.extend_from_slice(shared_layer_proofs); + layers.push(Vec::new()); // placeholder for the consumed deepest slot + let mut walk_path: Vec<&[u8]> = path_prefix.to_vec(); + walk_path.push(b""); // aligned placeholder; never read by the walk + walk_ancestor_chain( + &layers, + shared_ancestor_attestations, + &walk_path, + branching_root, + err_label, + ) +} + +impl GroveDb { + /// Prove one arbitrary secondary query (the same `secondary_query` + /// and `limit` per branch) over N sibling prefix branches, as one + /// envelope. The indexed tree of branch `i` lives at + /// `path_prefix ++ [branch_keys[i]] ++ path_suffix`. + /// + /// Verified by [`GroveDb::verify_indexed_axis_query_branched`]. + #[allow(clippy::too_many_arguments)] + pub fn prove_indexed_axis_query_branched( + &self, + path_prefix: &[&[u8]], + branch_keys: &[Vec], + path_suffix: &[&[u8]], + axis: IndexAxis, + secondary_query: MerkQuery, + limit: Option, + transaction: TransactionArg, + grove_version: &GroveVersion, + ) -> CostResult, Error> { + let mut cost = OperationCost::default(); + let err_label = "indexed-axis branched range proof"; + cost_return_on_error_no_add!(cost, validate_branch_keys(branch_keys, err_label)); + if path_suffix.is_empty() { + return Err(Error::InvalidInput( + "branched indexed-axis proofs require a non-empty path suffix: the indexed \ + tree lives below the branch key", + )) + .wrap_with_cost(cost); + } + let batch = StorageBatch::new(); + let tx = TxRef::new(&self.db, transaction); + let tx_ref = tx.as_ref(); + let branching_depth = path_prefix.len(); + + let mut shared_layer_proofs: Option>> = None; + let mut shared_ancestor_attestations: Option> = None; + let mut branches = Vec::with_capacity(branch_keys.len()); + let mut requested_limit = limit; + let mut descending = false; + for key in branch_keys { + let full_path: Vec<&[u8]> = path_prefix + .iter() + .copied() + .chain(std::iter::once(key.as_slice())) + .chain(path_suffix.iter().copied()) + .collect(); + let sub_envelope = cost_return_on_error!( + &mut cost, + self.build_indexed_axis_range_proof( + SubtreePath::from(full_path.as_slice()), + axis, + secondary_query.clone(), + limit, + tx_ref, + &batch, + grove_version, + ) + ); + requested_limit = sub_envelope.requested_limit; + descending = sub_envelope.descending; + let mut layer_proofs = sub_envelope.layer_proofs; + let mut attestations = sub_envelope.ancestor_attestations; + let tail_layer_proofs = layer_proofs.split_off(branching_depth + 1); + let branch_attestations = attestations.split_off(branching_depth); + if shared_layer_proofs.is_none() { + layer_proofs.truncate(branching_depth); + shared_layer_proofs = Some(layer_proofs); + shared_ancestor_attestations = Some(attestations); + } + branches.push(BranchedProofBranch { + ancestor_attestations: branch_attestations, + tail_layer_proofs, + primary_root_hash: sub_envelope.primary_root_hash, + other_axes_root_hashes: sub_envelope.other_axes_root_hashes, + target_is_pcpsit: sub_envelope.target_is_pcpsit, + secondary_proof: sub_envelope.secondary_proof, + }); + } + + let branching_layer_proof = cost_return_on_error!( + &mut cost, + self.build_branching_layer_proof( + path_prefix, + branch_keys, + tx_ref, + &batch, + grove_version, + err_label, + ) + ); + + let envelope = IndexedAxisBranchedRangeProof { + axis_tag: axis.tag(), + shared_layer_proofs: shared_layer_proofs.unwrap_or_default(), + shared_ancestor_attestations: shared_ancestor_attestations.unwrap_or_default(), + branching_layer_proof, + branches, + requested_limit, + descending, + }; + let bytes = cost_return_on_error_no_add!( + cost, + bincode::encode_to_vec(&envelope, bincode::config::standard()).map_err(|e| { + Error::CorruptedData(format!("encoding indexed-axis branched range proof: {e}")) + }) + ); + Ok(bytes).wrap_with_cost(cost) + } + + /// Prove one offset-paginated top-k walk (the same `(k, offset, + /// descending)` per branch) over N sibling prefix branches, as one + /// envelope. + /// + /// Verified by + /// [`GroveDb::verify_indexed_axis_top_k_paginated_branched`]. + #[allow(clippy::too_many_arguments)] + pub fn prove_indexed_axis_top_k_paginated_branched( + &self, + path_prefix: &[&[u8]], + branch_keys: &[Vec], + path_suffix: &[&[u8]], + axis: IndexAxis, + k: u16, + offset: u64, + descending: bool, + transaction: TransactionArg, + grove_version: &GroveVersion, + ) -> CostResult, Error> { + let mut cost = OperationCost::default(); + let err_label = "indexed-axis branched paginated proof"; + cost_return_on_error_no_add!(cost, validate_branch_keys(branch_keys, err_label)); + if path_suffix.is_empty() { + return Err(Error::InvalidInput( + "branched indexed-axis proofs require a non-empty path suffix: the indexed \ + tree lives below the branch key", + )) + .wrap_with_cost(cost); + } + let batch = StorageBatch::new(); + let tx = TxRef::new(&self.db, transaction); + let tx_ref = tx.as_ref(); + let branching_depth = path_prefix.len(); + + let mut shared_layer_proofs: Option>> = None; + let mut shared_ancestor_attestations: Option> = None; + let mut branches = Vec::with_capacity(branch_keys.len()); + for key in branch_keys { + let full_path: Vec<&[u8]> = path_prefix + .iter() + .copied() + .chain(std::iter::once(key.as_slice())) + .chain(path_suffix.iter().copied()) + .collect(); + let sub_envelope = cost_return_on_error!( + &mut cost, + self.build_indexed_axis_paginated_proof( + SubtreePath::from(full_path.as_slice()), + axis, + k, + offset, + descending, + tx_ref, + &batch, + grove_version, + ) + ); + let mut layer_proofs = sub_envelope.layer_proofs; + let mut attestations = sub_envelope.ancestor_attestations; + let tail_layer_proofs = layer_proofs.split_off(branching_depth + 1); + let branch_attestations = attestations.split_off(branching_depth); + if shared_layer_proofs.is_none() { + layer_proofs.truncate(branching_depth); + shared_layer_proofs = Some(layer_proofs); + shared_ancestor_attestations = Some(attestations); + } + branches.push(BranchedProofBranch { + ancestor_attestations: branch_attestations, + tail_layer_proofs, + primary_root_hash: sub_envelope.primary_root_hash, + other_axes_root_hashes: sub_envelope.other_axes_root_hashes, + target_is_pcpsit: sub_envelope.target_is_pcpsit, + secondary_proof: sub_envelope.secondary_proof, + }); + } + + let branching_layer_proof = cost_return_on_error!( + &mut cost, + self.build_branching_layer_proof( + path_prefix, + branch_keys, + tx_ref, + &batch, + grove_version, + err_label, + ) + ); + + let envelope = IndexedAxisBranchedPaginatedProof { + axis_tag: axis.tag(), + shared_layer_proofs: shared_layer_proofs.unwrap_or_default(), + shared_ancestor_attestations: shared_ancestor_attestations.unwrap_or_default(), + branching_layer_proof, + branches, + requested_k: k, + requested_offset: offset, + descending, + }; + let bytes = cost_return_on_error_no_add!( + cost, + bincode::encode_to_vec(&envelope, bincode::config::standard()).map_err(|e| { + Error::CorruptedData(format!( + "encoding indexed-axis branched paginated proof: {e}" + )) + }) + ); + Ok(bytes).wrap_with_cost(cost) + } + + /// One multi-key Merk proof at the branching level: proves every + /// branch key in the Merk at `path_prefix`. + fn build_branching_layer_proof( + &self, + path_prefix: &[&[u8]], + branch_keys: &[Vec], + transaction: &crate::Transaction, + batch: &StorageBatch, + grove_version: &GroveVersion, + err_label: &'static str, + ) -> CostResult, Error> { + let mut cost = OperationCost::default(); + let parent_path: SubtreePath<&[u8]> = path_prefix.into(); + let parent_merk = cost_return_on_error!( + &mut cost, + self.open_transactional_merk_at_path( + parent_path, + transaction, + Some(batch), + grove_version, + ) + ); + let mut query = MerkQuery::new(); + for key in branch_keys { + query.insert_item(MerkQueryItem::Key(key.clone())); + } + let result = cost_return_on_error!( + &mut cost, + parent_merk + .prove(query, None, grove_version) + .map_err(|e| Error::CorruptedData(format!( + "{err_label}: prove branching-level multi-key layer: {e}" + ))) + ); + Ok(result.proof).wrap_with_cost(cost) + } + + /// Verify an [`IndexedAxisBranchedRangeProof`]: the same + /// `secondary_query` and `limit` executed over every branch, + /// reconstructing one GroveDB root hash. + #[allow(clippy::too_many_arguments)] + pub fn verify_indexed_axis_query_branched( + proof_bytes: &[u8], + path_prefix: &[&[u8]], + branch_keys: &[Vec], + path_suffix: &[&[u8]], + expected_axis: IndexAxis, + secondary_query: MerkQuery, + expected_limit: Option, + ) -> Result { + let err_label = "indexed-axis branched range proof"; + validate_branch_keys(branch_keys, err_label)?; + let config = bincode::config::standard().with_limit::<{ 16 * 1024 * 1024 }>(); + let (envelope, consumed): (IndexedAxisBranchedRangeProof, _) = + bincode::decode_from_slice(proof_bytes, config).map_err(|e| { + Error::CorruptedData(format!("decoding indexed-axis branched range proof: {e}")) + })?; + reject_trailing_envelope_bytes(consumed, proof_bytes.len(), "branched range")?; + if envelope.axis_tag != expected_axis.tag() { + return Err(Error::CorruptedData(format!( + "{err_label}: axis mismatch: expected {:?} (tag={}), envelope carries tag={}", + expected_axis, + expected_axis.tag(), + envelope.axis_tag + ))); + } + if envelope.requested_limit != expected_limit { + return Err(Error::CorruptedData(format!( + "{err_label}: limit mismatch: expected {:?}, envelope carries {:?}", + expected_limit, envelope.requested_limit + ))); + } + let expected_descending = !secondary_query.left_to_right; + if envelope.descending != expected_descending { + return Err(Error::CorruptedData(format!( + "{err_label}: direction mismatch: expected descending={expected_descending}, \ + envelope carries descending={}", + envelope.descending + ))); + } + if envelope.branches.len() != branch_keys.len() { + return Err(Error::CorruptedData(format!( + "{err_label}: envelope carries {} branches; the request resolves to {}", + envelope.branches.len(), + branch_keys.len() + ))); + } + + let left_to_right = secondary_query.left_to_right; + let mut branch_entries = Vec::with_capacity(envelope.branches.len()); + let mut branch_tail_roots = Vec::with_capacity(envelope.branches.len()); + let mut branch_first_attestations = Vec::with_capacity(envelope.branches.len()); + for (branch_index, branch) in envelope.branches.iter().enumerate() { + let (secondary_root_hash, sec_result) = secondary_query + .clone() + .execute_proof( + &branch.secondary_proof, + envelope.requested_limit, + left_to_right, + 0, + ) + .unwrap() + .map_err(|e| { + Error::CorruptedData(format!( + "{err_label}: branch {branch_index} secondary proof failed to \ + verify: {e}" + )) + })?; + let entries = + decode_axis_entries_from_result_set(expected_axis, &sec_result.result_set)?; + let tail_root = verify_branch_tail( + branch, + path_suffix, + &secondary_root_hash, + expected_axis, + err_label, + )?; + branch_entries.push(entries); + branch_tail_roots.push(tail_root); + branch_first_attestations.push(&branch.ancestor_attestations[0]); + } + + let root_hash = verify_branching_and_shared_layers( + &envelope.shared_layer_proofs, + &envelope.shared_ancestor_attestations, + &envelope.branching_layer_proof, + branch_keys, + path_prefix, + &branch_tail_roots, + &branch_first_attestations, + err_label, + )?; + Ok(IndexedAxisBranchedQueryResult { + root_hash, + branches: branch_entries, + }) + } + + /// Verify an [`IndexedAxisBranchedPaginatedProof`]: the same + /// `(k, offset, descending)` walk executed over every branch, + /// reconstructing one GroveDB root hash. Per-branch `skipped` + /// carries the same attested-skip semantics as the single-path + /// paginated verifier. + #[allow(clippy::too_many_arguments)] + pub fn verify_indexed_axis_top_k_paginated_branched( + proof_bytes: &[u8], + path_prefix: &[&[u8]], + branch_keys: &[Vec], + path_suffix: &[&[u8]], + expected_axis: IndexAxis, + expected_k: u16, + expected_offset: u64, + expected_descending: bool, + ) -> Result { + let err_label = "indexed-axis branched paginated proof"; + validate_branch_keys(branch_keys, err_label)?; + let config = bincode::config::standard().with_limit::<{ 16 * 1024 * 1024 }>(); + let (envelope, consumed): (IndexedAxisBranchedPaginatedProof, _) = + bincode::decode_from_slice(proof_bytes, config).map_err(|e| { + Error::CorruptedData(format!( + "decoding indexed-axis branched paginated proof: {e}" + )) + })?; + reject_trailing_envelope_bytes(consumed, proof_bytes.len(), "branched paginated")?; + if envelope.axis_tag != expected_axis.tag() { + return Err(Error::CorruptedData(format!( + "{err_label}: axis mismatch: expected {:?} (tag={}), envelope carries tag={}", + expected_axis, + expected_axis.tag(), + envelope.axis_tag + ))); + } + if envelope.requested_k != expected_k { + return Err(Error::CorruptedData(format!( + "{err_label}: k mismatch: expected {expected_k}, envelope carries {}", + envelope.requested_k + ))); + } + if envelope.requested_offset != expected_offset { + return Err(Error::CorruptedData(format!( + "{err_label}: offset mismatch: expected {expected_offset}, envelope carries {}", + envelope.requested_offset + ))); + } + if envelope.descending != expected_descending { + return Err(Error::CorruptedData(format!( + "{err_label}: direction mismatch: expected descending={expected_descending}, \ + envelope carries descending={}", + envelope.descending + ))); + } + if envelope.branches.len() != branch_keys.len() { + return Err(Error::CorruptedData(format!( + "{err_label}: envelope carries {} branches; the request resolves to {}", + envelope.branches.len(), + branch_keys.len() + ))); + } + + let inner_range = MerkQueryItemForRange::RangeFull(std::ops::RangeFull); + let mut branch_pages = Vec::with_capacity(envelope.branches.len()); + let mut branch_tail_roots = Vec::with_capacity(envelope.branches.len()); + let mut branch_first_attestations = Vec::with_capacity(envelope.branches.len()); + for (branch_index, branch) in envelope.branches.iter().enumerate() { + let count_offset_result = verify_count_offset_on_range_proof( + &branch.secondary_proof, + &inner_range, + envelope.requested_offset, + Some(envelope.requested_k as u64), + !envelope.descending, + ) + .unwrap() + .map_err(|e| { + Error::CorruptedData(format!( + "{err_label}: branch {branch_index} secondary count-offset proof failed \ + to verify: {e}" + )) + })?; + let entries = decode_axis_entries_from_count_offset_items( + expected_axis, + &count_offset_result.returned_items, + )?; + let tail_root = verify_branch_tail( + branch, + path_suffix, + &count_offset_result.root_hash, + expected_axis, + err_label, + )?; + branch_pages.push((count_offset_result.skipped, entries)); + branch_tail_roots.push(tail_root); + branch_first_attestations.push(&branch.ancestor_attestations[0]); + } + + let root_hash = verify_branching_and_shared_layers( + &envelope.shared_layer_proofs, + &envelope.shared_ancestor_attestations, + &envelope.branching_layer_proof, + branch_keys, + path_prefix, + &branch_tail_roots, + &branch_first_attestations, + err_label, + )?; + Ok(IndexedAxisBranchedPaginatedResult { + root_hash, + branches: branch_pages, + }) + } +} + +/// Verify one branch's tail — the deepest-layer binding of its +/// secondary root plus the walk up to (but not including) the +/// branching level — returning the branch's value-tree root hash for +/// the branching-level composition check. +fn verify_branch_tail( + branch: &BranchedProofBranch, + path_suffix: &[&[u8]], + secondary_root_hash: &CryptoHash, + axis: IndexAxis, + err_label: &'static str, +) -> Result { + if branch.tail_layer_proofs.len() != path_suffix.len() { + return Err(Error::CorruptedData(format!( + "{err_label}: branch has {} tail layers but the path suffix has {} segments", + branch.tail_layer_proofs.len(), + path_suffix.len() + ))); + } + if branch.ancestor_attestations.len() != path_suffix.len() { + return Err(Error::CorruptedData(format!( + "{err_label}: branch has {} attestations but the path suffix has {} segments \ + (one per layer from the branch's value tree down to the indexed tree's \ + parent)", + branch.ancestor_attestations.len(), + path_suffix.len() + ))); + } + let initial_root = verify_deepest_layer( + &branch.tail_layer_proofs, + path_suffix, + &branch.primary_root_hash, + secondary_root_hash, + axis, + &branch.other_axes_root_hashes, + branch.target_is_pcpsit, + err_label, + )?; + walk_ancestor_chain( + &branch.tail_layer_proofs, + &branch.ancestor_attestations[1..], + path_suffix, + initial_root, + err_label, + ) +} diff --git a/grovedb/src/operations/proof/indexed_axis/envelope.rs b/grovedb/src/operations/proof/indexed_axis/envelope.rs index 7ed405206..24b5d55bb 100644 --- a/grovedb/src/operations/proof/indexed_axis/envelope.rs +++ b/grovedb/src/operations/proof/indexed_axis/envelope.rs @@ -227,3 +227,107 @@ pub struct IndexedAxisAggregateResult { /// sum axis this is the signed sum. pub aggregate: i128, } + +/// One branch of a branched (multi-prefix) indexed-axis proof: the +/// layers *below* the branching level, plus the branch's own target +/// attestations and secondary proof. The layers above the branching +/// level — and the branching level itself — are shared across branches +/// and live once on the enclosing envelope. +#[derive(Encode, Decode, Debug, Clone)] +pub struct BranchedProofBranch { + /// Per-intermediate attestations for the branch's own layers: + /// entry 0 describes the branch's value-tree element at the + /// branching level (proved by the shared multi-key layer proof); + /// subsequent entries describe deeper intermediates. Length equals + /// `tail_layer_proofs.len()`. + pub ancestor_attestations: Vec, + /// Single-key layer proofs for the segments below the branch key, + /// top-down; the deepest proves the indexed-tree element. Length + /// equals the path-suffix length. + pub tail_layer_proofs: Vec>, + /// Same as [`IndexedAxisRangeProof::primary_root_hash`], per branch. + pub primary_root_hash: [u8; 32], + /// Same as [`IndexedAxisRangeProof::other_axes_root_hashes`]. + pub other_axes_root_hashes: Vec<(u8, [u8; 32])>, + /// Same as [`IndexedAxisRangeProof::target_is_pcpsit`]. + pub target_is_pcpsit: bool, + /// The branch's secondary proof: a Merk range proof for the range + /// shape, a `prove_count_offset_on_range` stream for the paginated + /// shape. + pub secondary_proof: Vec, +} + +/// Wire-format envelope for a **branched** range / arbitrary-query +/// proof: one query over N sibling prefix branches, attested by a +/// single envelope. The layers above the branching level appear once; +/// the branching level is one multi-key Merk proof binding every +/// branch's value tree simultaneously; each branch carries only its +/// own tail. Exactly one GroveDB root hash is reconstructed. +#[derive(Encode, Decode, Debug)] +pub struct IndexedAxisBranchedRangeProof { + /// Echoed [`IndexAxis::tag`] of the queried axis. + pub axis_tag: u8, + /// Single-key layer proofs for the shared path prefix, top-down. + /// Length equals the path-prefix length. + pub shared_layer_proofs: Vec>, + /// Attestations for the shared intermediate layers. Length equals + /// `shared_layer_proofs.len()`. + pub shared_ancestor_attestations: Vec, + /// One multi-key Merk proof at the branching level, proving every + /// echoed branch key in the shared prefix's Merk. + pub branching_layer_proof: Vec, + /// Per-branch tails, aligned with the verifier's branch-key list. + pub branches: Vec, + /// Echoed query limit, shared by every branch. + pub requested_limit: Option, + /// Echoed iteration direction, shared by every branch. + pub descending: bool, +} + +/// Wire-format envelope for a **branched** offset-paginated top-k +/// proof. Same layer structure as +/// [`IndexedAxisBranchedRangeProof`]; each branch's secondary proof is +/// a `prove_count_offset_on_range` stream. +#[derive(Encode, Decode, Debug)] +pub struct IndexedAxisBranchedPaginatedProof { + /// Echoed [`IndexAxis::tag`] of the queried axis. + pub axis_tag: u8, + /// Same as [`IndexedAxisBranchedRangeProof::shared_layer_proofs`]. + pub shared_layer_proofs: Vec>, + /// Same as + /// [`IndexedAxisBranchedRangeProof::shared_ancestor_attestations`]. + pub shared_ancestor_attestations: Vec, + /// Same as + /// [`IndexedAxisBranchedRangeProof::branching_layer_proof`]. + pub branching_layer_proof: Vec, + /// Per-branch tails, aligned with the verifier's branch-key list. + pub branches: Vec, + /// Echoed page size, shared by every branch. + pub requested_k: u16, + /// Echoed offset, shared by every branch. + pub requested_offset: u64, + /// Echoed iteration direction, shared by every branch. + pub descending: bool, +} + +/// Verified result of a branched range / arbitrary query: one root +/// hash, per-branch entries aligned with the caller's branch keys. +#[derive(Debug)] +pub struct IndexedAxisBranchedQueryResult { + /// GroveDB root hash the whole envelope reconstructs. + pub root_hash: CryptoHash, + /// Per-branch decoded entries, aligned with the caller's branch + /// keys. + pub branches: Vec, +} + +/// Verified result of a branched paginated top-k query. +#[derive(Debug)] +pub struct IndexedAxisBranchedPaginatedResult { + /// GroveDB root hash the whole envelope reconstructs. + pub root_hash: CryptoHash, + /// Per-branch `(skipped, entries)`, aligned with the caller's + /// branch keys; `skipped` carries the same attested-skip semantics + /// as [`IndexedAxisPaginatedResult::skipped`], per branch. + pub branches: Vec<(u64, AxisEntries)>, +} diff --git a/grovedb/src/operations/proof/indexed_axis/generate.rs b/grovedb/src/operations/proof/indexed_axis/generate.rs index 98b07ff91..fd51ca3f3 100644 --- a/grovedb/src/operations/proof/indexed_axis/generate.rs +++ b/grovedb/src/operations/proof/indexed_axis/generate.rs @@ -664,7 +664,7 @@ impl GroveDb { Ok(bytes).wrap_with_cost(cost) } - fn build_indexed_axis_range_proof<'db, 'b, B: AsRef<[u8]>>( + pub(super) fn build_indexed_axis_range_proof<'db, 'b, B: AsRef<[u8]>>( &'db self, path: SubtreePath<'b, B>, axis: IndexAxis, @@ -788,7 +788,7 @@ impl GroveDb { .wrap_with_cost(cost) } - fn build_indexed_axis_paginated_proof<'db, 'b, B: AsRef<[u8]>>( + pub(super) fn build_indexed_axis_paginated_proof<'db, 'b, B: AsRef<[u8]>>( &'db self, path: SubtreePath<'b, B>, axis: IndexAxis, diff --git a/grovedb/src/operations/proof/indexed_axis/mod.rs b/grovedb/src/operations/proof/indexed_axis/mod.rs index 42177527b..82e05e6e2 100644 --- a/grovedb/src/operations/proof/indexed_axis/mod.rs +++ b/grovedb/src/operations/proof/indexed_axis/mod.rs @@ -62,15 +62,18 @@ //! shape only when the range really is out of the axis's domain. mod axis_api; +mod branched; mod envelope; #[cfg(feature = "minimal")] mod generate; mod verify; pub use envelope::{ - AncestorAttestation, AxisEntries, IndexedAxisAggregateProof, IndexedAxisAggregateResult, - IndexedAxisPaginatedProof, IndexedAxisPaginatedResult, IndexedAxisQueryResult, - IndexedAxisRangeProof, + AncestorAttestation, AxisEntries, BranchedProofBranch, IndexedAxisAggregateProof, + IndexedAxisAggregateResult, IndexedAxisBranchedPaginatedProof, + IndexedAxisBranchedPaginatedResult, IndexedAxisBranchedQueryResult, + IndexedAxisBranchedRangeProof, IndexedAxisPaginatedProof, IndexedAxisPaginatedResult, + IndexedAxisQueryResult, IndexedAxisRangeProof, }; use grovedb_element::indexed::IndexAxis; diff --git a/grovedb/src/operations/proof/indexed_axis/verify.rs b/grovedb/src/operations/proof/indexed_axis/verify.rs index c6d731454..f812d4916 100644 --- a/grovedb/src/operations/proof/indexed_axis/verify.rs +++ b/grovedb/src/operations/proof/indexed_axis/verify.rs @@ -34,7 +34,7 @@ use super::{ /// Walk the verifier-side ancestor chain (depths `last_idx - 1` down to /// `0`) and return the final reconstructed root hash. Returns the /// outer GroveDB root hash on success. -fn walk_ancestor_chain( +pub(super) fn walk_ancestor_chain( layer_proofs: &[Vec], ancestor_attestations: &[AncestorAttestation], path: &[&[u8]], @@ -110,7 +110,7 @@ fn walk_ancestor_chain( /// Returns `(initial_layer_root, cidx_value_bytes)`. The /// `initial_layer_root` is then passed to `walk_ancestor_chain` as the /// starting `current_layer_root` for the ancestor walk. -fn verify_deepest_layer( +pub(super) fn verify_deepest_layer( layer_proofs: &[Vec], path: &[&[u8]], primary_root_hash: &[u8; 32], @@ -228,7 +228,7 @@ fn verify_deepest_layer( /// Verify a single-key Merk proof: returns /// `(value_bytes, layer_root_hash, parent_recorded_value_hash)`. -fn execute_single_key_proof( +pub(super) fn execute_single_key_proof( proof_bytes: &[u8], target_key: &[u8], layer_label: &'static str, @@ -509,7 +509,7 @@ fn decode_range_envelope(proof_bytes: &[u8]) -> Result Result { @@ -788,7 +788,7 @@ fn decode_axis_entries_from_result_set( } } -fn decode_axis_entries_from_count_offset_items( +pub(super) fn decode_axis_entries_from_count_offset_items( axis: IndexAxis, items: &[grovedb_merk::proofs::query::CountOffsetReturnedItem], ) -> Result { diff --git a/grovedb/src/tests/indexed_axis_branched_proof_tests.rs b/grovedb/src/tests/indexed_axis_branched_proof_tests.rs new file mode 100644 index 000000000..0ce723054 --- /dev/null +++ b/grovedb/src/tests/indexed_axis_branched_proof_tests.rs @@ -0,0 +1,449 @@ +//! End-to-end tests for the branched (multi-prefix) indexed-axis proof +//! envelopes (`prove_indexed_axis_*_branched` / +//! `verify_indexed_axis_*_branched`): one query over N sibling prefix +//! branches, one envelope, one reconstructed root hash. + +#[cfg(test)] +mod tests { + use grovedb_element::indexed::IndexAxis; + use grovedb_merk::proofs::Query as MerkQuery; + use grovedb_query::QueryItem as MerkQueryItem; + use grovedb_version::version::GroveVersion; + + use crate::{ + operations::proof::indexed_axis::{AxisEntries, IndexedAxisBranchedPaginatedProof}, + tests::{make_test_grovedb, TEST_LEAF}, + Element, GroveDb, + }; + + const REGION: &[u8] = b"region"; + const CLS: &[u8] = b"cls"; + + /// Build the branched fixture: + /// `[TEST_LEAF, "region"]` is a plain tree whose children are one + /// plain value tree per branch key, each holding a PCIT at `"cls"` + /// seeded with the given `(group key, count)` entries — the same + /// shape a compound index's prefix level takes. + fn build_branched_fixture( + db: &GroveDb, + grove_version: &GroveVersion, + branches: &[(&[u8], &[(&[u8], u64)])], + ) { + db.insert( + [TEST_LEAF].as_ref(), + REGION, + Element::empty_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create region tree"); + for (branch_key, entries) in branches { + db.insert( + [TEST_LEAF, REGION].as_ref(), + branch_key, + Element::empty_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create branch value tree"); + db.insert( + [TEST_LEAF, REGION, branch_key].as_ref(), + CLS, + Element::empty_provable_count_indexed_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create branch PCIT"); + let pcit_path: Vec<&[u8]> = vec![TEST_LEAF, REGION, branch_key, CLS]; + for (group_key, count) in *entries { + db.insert_into_count_indexed_tree( + pcit_path.as_slice(), + group_key, + Element::empty_provable_count_tree(), + None, + grove_version, + ) + .unwrap() + .expect("insert group tree"); + let mut group_path = pcit_path.clone(); + group_path.push(group_key); + for i in 0..*count { + db.insert( + group_path.as_slice(), + &i.to_be_bytes(), + Element::new_item(b"v".to_vec()), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert doc"); + } + } + } + } + + fn prefix<'a>() -> Vec<&'a [u8]> { + vec![TEST_LEAF, REGION] + } + + fn suffix<'a>() -> Vec<&'a [u8]> { + vec![CLS] + } + + fn branch_keys() -> Vec> { + vec![b"east".to_vec(), b"west".to_vec()] + } + + fn full_range_query() -> MerkQuery { + let mut q = MerkQuery::new(); + q.insert_item(MerkQueryItem::RangeFull(std::ops::RangeFull)); + q + } + + fn count_entries(entries: &AxisEntries) -> Vec<(u64, Vec)> { + match entries { + AxisEntries::Count(v) => v.clone(), + other => panic!("expected count entries, got {other:?}"), + } + } + + #[test] + fn branched_range_query_proves_and_verifies_with_one_root_hash() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture( + &db, + grove_version, + &[ + (b"east", &[(b"math", 3), (b"art", 5)]), + (b"west", &[(b"science", 2)]), + ], + ); + + let proof = db + .prove_indexed_axis_query_branched( + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + None, + grove_version, + ) + .unwrap() + .expect("branched range prove succeeds"); + + let result = GroveDb::verify_indexed_axis_query_branched( + &proof, + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + ) + .expect("branched range proof verifies"); + + assert_eq!(result.branches.len(), 2); + assert_eq!( + count_entries(&result.branches[0]), + vec![(3, b"math".to_vec()), (5, b"art".to_vec())], + "east's own groups, ascending count order" + ); + assert_eq!( + count_entries(&result.branches[1]), + vec![(2, b"science".to_vec())], + "west's own groups — no cross-branch leakage" + ); + assert_eq!( + result.root_hash, + db.root_hash(None, grove_version) + .unwrap() + .expect("root hash readable"), + "one root hash for the whole envelope, matching the live grove" + ); + } + + #[test] + fn branched_paginated_top_k_proves_and_verifies() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture( + &db, + grove_version, + &[ + (b"east", &[(b"math", 3), (b"art", 5), (b"gym", 1)]), + (b"west", &[(b"science", 2), (b"history", 7)]), + ], + ); + + let proof = db + .prove_indexed_axis_top_k_paginated_branched( + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + 2, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("branched paginated prove succeeds"); + + let result = GroveDb::verify_indexed_axis_top_k_paginated_branched( + &proof, + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + 2, + 0, + true, + ) + .expect("branched paginated proof verifies"); + + assert_eq!(result.branches.len(), 2); + let (east_skipped, east_entries) = &result.branches[0]; + assert_eq!(*east_skipped, 0); + assert_eq!( + count_entries(east_entries), + vec![(5, b"art".to_vec()), (3, b"math".to_vec())], + "east's own top 2 by count, descending" + ); + let (west_skipped, west_entries) = &result.branches[1]; + assert_eq!(*west_skipped, 0); + assert_eq!( + count_entries(west_entries), + vec![(7, b"history".to_vec()), (2, b"science".to_vec())], + "west's own top 2 by count, descending" + ); + assert_eq!( + result.root_hash, + db.root_hash(None, grove_version) + .unwrap() + .expect("root hash readable"), + ); + } + + /// The envelope binds branch tails to branch keys through the + /// multi-key proof's recorded hashes: verifying with the keys in a + /// different order than the prover's branch alignment must fail, + /// not silently relabel which prefix each page belongs to. + #[test] + fn reordered_branch_keys_do_not_verify() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture( + &db, + grove_version, + &[(b"east", &[(b"math", 3)]), (b"west", &[(b"science", 2)])], + ); + let proof = db + .prove_indexed_axis_query_branched( + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + None, + grove_version, + ) + .unwrap() + .expect("prove succeeds"); + + let reversed: Vec> = branch_keys().into_iter().rev().collect(); + assert!( + GroveDb::verify_indexed_axis_query_branched( + &proof, + &prefix(), + &reversed, + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + ) + .is_err(), + "branch tails must stay bound to their keys" + ); + } + + /// A branch tail copied over another branch's slot fails the + /// branching-level composition even though the tail is internally + /// valid — the multi-key proof commits each key's own subtree. + #[test] + fn a_duplicated_branch_tail_does_not_verify() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture( + &db, + grove_version, + &[(b"east", &[(b"math", 3)]), (b"west", &[(b"science", 2)])], + ); + let proof = db + .prove_indexed_axis_top_k_paginated_branched( + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + 1, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("prove succeeds"); + + let config = bincode::config::standard(); + let (mut envelope, _): (IndexedAxisBranchedPaginatedProof, _) = + bincode::decode_from_slice(&proof, config).expect("decode own envelope"); + let cloned = IndexedAxisBranchedPaginatedProof { + axis_tag: envelope.axis_tag, + shared_layer_proofs: std::mem::take(&mut envelope.shared_layer_proofs), + shared_ancestor_attestations: std::mem::take( + &mut envelope.shared_ancestor_attestations, + ), + branching_layer_proof: std::mem::take(&mut envelope.branching_layer_proof), + branches: { + let mut branches = std::mem::take(&mut envelope.branches); + let first = branches[0].clone(); + branches[1] = first; + branches + }, + requested_k: envelope.requested_k, + requested_offset: envelope.requested_offset, + descending: envelope.descending, + }; + let tampered = bincode::encode_to_vec(&cloned, config).expect("re-encode"); + assert!( + GroveDb::verify_indexed_axis_top_k_paginated_branched( + &tampered, + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + 1, + 0, + true, + ) + .is_err(), + "a duplicated branch tail must fail the branching-level composition" + ); + } + + /// Echo mismatches (k, direction) and a wrong branch count are all + /// rejected before any hashing happens. + #[test] + fn echo_and_branch_count_mismatches_do_not_verify() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture( + &db, + grove_version, + &[(b"east", &[(b"math", 3)]), (b"west", &[(b"science", 2)])], + ); + let proof = db + .prove_indexed_axis_top_k_paginated_branched( + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + 2, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("prove succeeds"); + + // Wrong k. + assert!(GroveDb::verify_indexed_axis_top_k_paginated_branched( + &proof, + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + 3, + 0, + true, + ) + .is_err()); + // Wrong direction. + assert!(GroveDb::verify_indexed_axis_top_k_paginated_branched( + &proof, + &prefix(), + &branch_keys(), + &suffix(), + IndexAxis::Count, + 2, + 0, + false, + ) + .is_err()); + // A third key the envelope does not carry. + let mut three = branch_keys(); + three.push(b"north".to_vec()); + assert!(GroveDb::verify_indexed_axis_top_k_paginated_branched( + &proof, + &prefix(), + &three, + &suffix(), + IndexAxis::Count, + 2, + 0, + true, + ) + .is_err()); + } + + /// Fewer than two branch keys and duplicate branch keys are + /// rejected at both ends. + #[test] + fn degenerate_branch_key_lists_are_rejected() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture(&db, grove_version, &[(b"east", &[(b"math", 3)])]); + + let single = vec![b"east".to_vec()]; + assert!(db + .prove_indexed_axis_query_branched( + &prefix(), + &single, + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + None, + grove_version, + ) + .unwrap() + .is_err()); + + let duplicated = vec![b"east".to_vec(), b"east".to_vec()]; + assert!(db + .prove_indexed_axis_query_branched( + &prefix(), + &duplicated, + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + None, + grove_version, + ) + .unwrap() + .is_err()); + } +} diff --git a/grovedb/src/tests/mod.rs b/grovedb/src/tests/mod.rs index 7f130cb0a..08a580787 100644 --- a/grovedb/src/tests/mod.rs +++ b/grovedb/src/tests/mod.rs @@ -54,6 +54,7 @@ mod estimated_costs_average_case_tests; mod estimated_costs_worst_case_tests; mod get_cost_estimator_tests; mod grove_query_result_tests; +mod indexed_axis_branched_proof_tests; mod indexed_axis_nested_and_bounds_tests; mod indexed_axis_offset_proof_tests; mod indexed_axis_proof_tests; From dd2004e4eb0643a081356c0468132026217d7d66 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 00:15:31 +0700 Subject: [PATCH 2/5] fix: compile branched proofs under verify-only builds The prove side (storage, transactions) gates behind the minimal feature exactly as the generate module does; verification stays available to verifier-only consumers. Co-Authored-By: Claude Fable 5 --- .../src/operations/proof/indexed_axis/branched.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/grovedb/src/operations/proof/indexed_axis/branched.rs b/grovedb/src/operations/proof/indexed_axis/branched.rs index f9cabdf39..5b57105f1 100644 --- a/grovedb/src/operations/proof/indexed_axis/branched.rs +++ b/grovedb/src/operations/proof/indexed_axis/branched.rs @@ -40,6 +40,7 @@ //! [`verify_deepest_layer`] and [`walk_ancestor_chain`] verbatim on //! the tail and shared windows. +#[cfg(feature = "minimal")] use grovedb_costs::{ cost_return_on_error, cost_return_on_error_no_add, CostResult, CostsExt, OperationCost, }; @@ -52,12 +53,19 @@ use grovedb_merk::{ proofs::{query::QueryProofVerify, Query as MerkQuery}, tree::{combine_hash, combine_hash_three, value_hash, CryptoHash}, }; +#[cfg(feature = "minimal")] use grovedb_path::SubtreePath; use grovedb_query::QueryItem as MerkQueryItem; +#[cfg(feature = "minimal")] use grovedb_storage::StorageBatch; +#[cfg(feature = "minimal")] use grovedb_version::version::GroveVersion; -use crate::{util::TxRef, Error, GroveDb, TransactionArg}; +#[cfg(feature = "minimal")] +use crate::util::TxRef; +#[cfg(feature = "minimal")] +use crate::TransactionArg; +use crate::{Error, GroveDb}; use super::verify::{ decode_axis_entries_from_count_offset_items, decode_axis_entries_from_result_set, @@ -233,6 +241,7 @@ fn verify_branching_and_shared_layers( ) } +#[cfg(feature = "minimal")] impl GroveDb { /// Prove one arbitrary secondary query (the same `secondary_query` /// and `limit` per branch) over N sibling prefix branches, as one @@ -487,7 +496,9 @@ impl GroveDb { ); Ok(result.proof).wrap_with_cost(cost) } +} +impl GroveDb { /// Verify an [`IndexedAxisBranchedRangeProof`]: the same /// `secondary_query` and `limit` executed over every branch, /// reconstructing one GroveDB root hash. From 1d07f587a33b8e2a131c483f0c889ce7ab585864 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 00:34:01 +0700 Subject: [PATCH 3/5] feat: authenticated-absent branches in branched indexed-axis proofs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An IN element whose prefix subtree was never created is a legal member of the union — it contributes the empty page. The branching level's exact-key Merk proof already authenticates both outcomes, so an absent branch now carries no tail (branches: Vec>) and verifies as empty with an attested skip of zero, under the same single root hash. The verifier cross-checks presence both ways: claiming a present key absent, or grafting a tail onto an absent key, both fail the branching-level alignment. Presence is decided at the branching Merk itself — deeper breakage under a present key stays an error. When every branch is absent the shared layers are built from the prefix alone so the envelope still chains to the root. Co-Authored-By: Claude Fable 5 --- .../operations/proof/indexed_axis/branched.rs | 228 ++++++++++++++---- .../operations/proof/indexed_axis/envelope.rs | 26 +- .../operations/proof/indexed_axis/generate.rs | 4 +- .../indexed_axis_branched_proof_tests.rs | 167 +++++++++++++ 4 files changed, 367 insertions(+), 58 deletions(-) diff --git a/grovedb/src/operations/proof/indexed_axis/branched.rs b/grovedb/src/operations/proof/indexed_axis/branched.rs index 5b57105f1..c4fec52e9 100644 --- a/grovedb/src/operations/proof/indexed_axis/branched.rs +++ b/grovedb/src/operations/proof/indexed_axis/branched.rs @@ -72,7 +72,7 @@ use super::verify::{ reject_trailing_envelope_bytes, verify_deepest_layer, walk_ancestor_chain, }; use super::{ - AncestorAttestation, BranchedProofBranch, IndexedAxisBranchedPaginatedProof, + AncestorAttestation, AxisEntries, BranchedProofBranch, IndexedAxisBranchedPaginatedProof, IndexedAxisBranchedPaginatedResult, IndexedAxisBranchedQueryResult, IndexedAxisBranchedRangeProof, }; @@ -130,12 +130,14 @@ fn compose_intermediate( /// Execute the branching-level multi-key proof: one Merk proof /// covering every branch key in the shared prefix's Merk. Returns the /// layer's root hash plus, aligned with `branch_keys`, each key's -/// element bytes and the `value_hash` the parent Merk records for it. +/// element bytes and recorded `value_hash` — or `None` for a key the +/// proof shows **absent** (an exact-key Merk proof authenticates both +/// outcomes). fn execute_multi_key_proof( proof_bytes: &[u8], branch_keys: &[Vec], err_label: &'static str, -) -> Result<(CryptoHash, Vec<(Vec, CryptoHash)>), Error> { +) -> Result<(CryptoHash, Vec, CryptoHash)>>), Error> { let mut query = MerkQuery::new(); for key in branch_keys { query.insert_item(MerkQueryItem::Key(key.clone())); @@ -150,23 +152,24 @@ fn execute_multi_key_proof( })?; let mut per_key = Vec::with_capacity(branch_keys.len()); for key in branch_keys { - let proved = result - .result_set - .iter() - .find(|p| &p.key == key) - .ok_or_else(|| { - Error::CorruptedData(format!( - "{err_label}: branching-level proof does not contain branch key {}", - hex::encode(key) - )) - })?; - let value = proved.value.clone().ok_or_else(|| { - Error::CorruptedData(format!( - "{err_label}: branching-level proof carries no value for branch key {}", - hex::encode(key) - )) - })?; - per_key.push((value, proved.proof)); + // An exact-key Merk proof authenticates both outcomes: a key + // missing from the result set is *proven absent* (the proof + // would not verify otherwise), which is exactly the empty + // branch of an `IN` union. + let proved = result.result_set.iter().find(|p| &p.key == key); + match proved { + None => per_key.push(None), + Some(proved) => { + let value = proved.value.clone().ok_or_else(|| { + Error::CorruptedData(format!( + "{err_label}: branching-level proof carries no value for branch \ + key {}", + hex::encode(key) + )) + })?; + per_key.push(Some((value, proved.proof))); + } + } } Ok((root_hash, per_key)) } @@ -176,10 +179,10 @@ fn execute_multi_key_proof( /// multi-key proof's recorded hashes, then chain the shared layers to /// the GroveDB root. /// -/// `branch_tail_roots[i]` is branch `i`'s reconstructed value-tree -/// root (the output of that branch's tail walk), and -/// `branch_first_attestations[i]` describes branch `i`'s value-tree -/// element. +/// `branch_tail_roots[i]` is `Some((root, attestation))` for a present +/// branch — its reconstructed value-tree root plus the attestation +/// describing its value-tree element — and `None` for a branch the +/// envelope claims absent. #[allow(clippy::too_many_arguments)] fn verify_branching_and_shared_layers( shared_layer_proofs: &[Vec], @@ -187,8 +190,7 @@ fn verify_branching_and_shared_layers( branching_layer_proof: &[u8], branch_keys: &[Vec], path_prefix: &[&[u8]], - branch_tail_roots: &[CryptoHash], - branch_first_attestations: &[&AncestorAttestation], + branch_tail_roots: &[Option<(CryptoHash, &AncestorAttestation)>], err_label: &'static str, ) -> Result { if shared_layer_proofs.len() != path_prefix.len() { @@ -208,18 +210,40 @@ fn verify_branching_and_shared_layers( let (branching_root, per_key) = execute_multi_key_proof(branching_layer_proof, branch_keys, err_label)?; - for (branch, ((element_bytes, recorded_hash), tail_root)) in - per_key.iter().zip(branch_tail_roots.iter()).enumerate() - { - let combined = - compose_intermediate(element_bytes, tail_root, branch_first_attestations[branch]); - if combined != *recorded_hash { - return Err(Error::CorruptedData(format!( - "{err_label}: branch {branch} (key {}) chain mismatch at the branching \ - level: the branch tail reconstructs a different subtree than the \ - multi-key proof commits — a swapped, re-ordered, or foreign branch tail", - hex::encode(&branch_keys[branch]) - ))); + for (branch, (proved, tail)) in per_key.iter().zip(branch_tail_roots.iter()).enumerate() { + match (proved, tail) { + // Present key, present tail: the composition binds them. + (Some((element_bytes, recorded_hash)), Some((tail_root, first_attestation))) => { + let combined = compose_intermediate(element_bytes, tail_root, first_attestation); + if combined != *recorded_hash { + return Err(Error::CorruptedData(format!( + "{err_label}: branch {branch} (key {}) chain mismatch at the \ + branching level: the branch tail reconstructs a different \ + subtree than the multi-key proof commits — a swapped, \ + re-ordered, or foreign branch tail", + hex::encode(&branch_keys[branch]) + ))); + } + } + // Absent key, no tail: the authenticated-empty branch. + (None, None) => {} + // Absence forgery, either direction: an envelope claiming a + // tail for a key the branching proof shows absent, or + // claiming absence for a key it shows present. + (Some(_), None) => { + return Err(Error::CorruptedData(format!( + "{err_label}: branch {branch} (key {}) is present in the branching \ + Merk but the envelope claims it absent", + hex::encode(&branch_keys[branch]) + ))); + } + (None, Some(_)) => { + return Err(Error::CorruptedData(format!( + "{err_label}: branch {branch} (key {}) carries a tail but the \ + branching Merk proves the key absent", + hex::encode(&branch_keys[branch]) + ))); + } } } @@ -280,8 +304,26 @@ impl GroveDb { let mut shared_ancestor_attestations: Option> = None; let mut branches = Vec::with_capacity(branch_keys.len()); let mut requested_limit = limit; - let mut descending = false; + let descending = !secondary_query.left_to_right; for key in branch_keys { + // An absent branch key contributes the empty page: the + // branching-level multi-key proof authenticates the + // absence, so no tail is built (there is no subtree to + // walk). Presence is decided at the branching Merk itself + // — deeper breakage under a *present* key stays an error. + let present = cost_return_on_error!( + &mut cost, + self.get_raw_optional( + SubtreePath::from(path_prefix), + key, + Some(tx_ref), + grove_version + ) + ); + if present.is_none() { + branches.push(None); + continue; + } let full_path: Vec<&[u8]> = path_prefix .iter() .copied() @@ -301,7 +343,6 @@ impl GroveDb { ) ); requested_limit = sub_envelope.requested_limit; - descending = sub_envelope.descending; let mut layer_proofs = sub_envelope.layer_proofs; let mut attestations = sub_envelope.ancestor_attestations; let tail_layer_proofs = layer_proofs.split_off(branching_depth + 1); @@ -311,14 +352,26 @@ impl GroveDb { shared_layer_proofs = Some(layer_proofs); shared_ancestor_attestations = Some(attestations); } - branches.push(BranchedProofBranch { + branches.push(Some(BranchedProofBranch { ancestor_attestations: branch_attestations, tail_layer_proofs, primary_root_hash: sub_envelope.primary_root_hash, other_axes_root_hashes: sub_envelope.other_axes_root_hashes, target_is_pcpsit: sub_envelope.target_is_pcpsit, secondary_proof: sub_envelope.secondary_proof, - }); + })); + } + if shared_layer_proofs.is_none() { + // Every branch was absent: build the shared layers from the + // prefix alone so the envelope still chains to the root. + // (The attestation builder wants one segment past the last + // attested element; the dummy is never read.) + let (layers, attestations) = cost_return_on_error!( + &mut cost, + self.build_shared_prefix_parts(path_prefix, tx_ref, &batch, grove_version) + ); + shared_layer_proofs = Some(layers); + shared_ancestor_attestations = Some(attestations); } let branching_layer_proof = cost_return_on_error!( @@ -389,6 +442,20 @@ impl GroveDb { let mut shared_ancestor_attestations: Option> = None; let mut branches = Vec::with_capacity(branch_keys.len()); for key in branch_keys { + // Same absence contract as the range prover above. + let present = cost_return_on_error!( + &mut cost, + self.get_raw_optional( + SubtreePath::from(path_prefix), + key, + Some(tx_ref), + grove_version + ) + ); + if present.is_none() { + branches.push(None); + continue; + } let full_path: Vec<&[u8]> = path_prefix .iter() .copied() @@ -417,14 +484,22 @@ impl GroveDb { shared_layer_proofs = Some(layer_proofs); shared_ancestor_attestations = Some(attestations); } - branches.push(BranchedProofBranch { + branches.push(Some(BranchedProofBranch { ancestor_attestations: branch_attestations, tail_layer_proofs, primary_root_hash: sub_envelope.primary_root_hash, other_axes_root_hashes: sub_envelope.other_axes_root_hashes, target_is_pcpsit: sub_envelope.target_is_pcpsit, secondary_proof: sub_envelope.secondary_proof, - }); + })); + } + if shared_layer_proofs.is_none() { + let (layers, attestations) = cost_return_on_error!( + &mut cost, + self.build_shared_prefix_parts(path_prefix, tx_ref, &batch, grove_version) + ); + shared_layer_proofs = Some(layers); + shared_ancestor_attestations = Some(attestations); } let branching_layer_proof = cost_return_on_error!( @@ -460,6 +535,46 @@ impl GroveDb { Ok(bytes).wrap_with_cost(cost) } + /// The shared layers built from the prefix alone — the all-absent + /// fallback, where no branch sub-envelope exists to split them out + /// of. The attestation builder wants one segment past the last + /// attested element; a dummy segment is appended and never read. + fn build_shared_prefix_parts( + &self, + path_prefix: &[&[u8]], + transaction: &crate::Transaction, + batch: &StorageBatch, + grove_version: &GroveVersion, + ) -> CostResult<(Vec>, Vec), Error> { + let mut cost = OperationCost::default(); + let prefix_keys: Vec> = path_prefix.iter().map(|s| s.to_vec()).collect(); + let layers = cost_return_on_error!( + &mut cost, + super::generate::build_layer_proofs( + self, + &prefix_keys, + transaction, + batch, + grove_version, + "indexed-axis branched proof (shared prefix)", + ) + ); + let mut with_dummy = prefix_keys; + with_dummy.push(Vec::new()); + let attestations = cost_return_on_error!( + &mut cost, + super::generate::build_ancestor_attestations( + self, + &with_dummy, + transaction, + batch, + grove_version, + "indexed-axis branched proof (shared prefix)", + ) + ); + Ok((layers, attestations)).wrap_with_cost(cost) + } + /// One multi-key Merk proof at the branching level: proves every /// branch key in the Merk at `path_prefix`. fn build_branching_layer_proof( @@ -553,8 +668,14 @@ impl GroveDb { let left_to_right = secondary_query.left_to_right; let mut branch_entries = Vec::with_capacity(envelope.branches.len()); let mut branch_tail_roots = Vec::with_capacity(envelope.branches.len()); - let mut branch_first_attestations = Vec::with_capacity(envelope.branches.len()); for (branch_index, branch) in envelope.branches.iter().enumerate() { + let Some(branch) = branch else { + // Claimed absent — authenticated against the branching + // proof inside the shared walk below. + branch_entries.push(AxisEntries::empty_for_axis(expected_axis)); + branch_tail_roots.push(None); + continue; + }; let (secondary_root_hash, sec_result) = secondary_query .clone() .execute_proof( @@ -580,8 +701,7 @@ impl GroveDb { err_label, )?; branch_entries.push(entries); - branch_tail_roots.push(tail_root); - branch_first_attestations.push(&branch.ancestor_attestations[0]); + branch_tail_roots.push(Some((tail_root, &branch.ancestor_attestations[0]))); } let root_hash = verify_branching_and_shared_layers( @@ -591,7 +711,6 @@ impl GroveDb { branch_keys, path_prefix, &branch_tail_roots, - &branch_first_attestations, err_label, )?; Ok(IndexedAxisBranchedQueryResult { @@ -664,8 +783,15 @@ impl GroveDb { let inner_range = MerkQueryItemForRange::RangeFull(std::ops::RangeFull); let mut branch_pages = Vec::with_capacity(envelope.branches.len()); let mut branch_tail_roots = Vec::with_capacity(envelope.branches.len()); - let mut branch_first_attestations = Vec::with_capacity(envelope.branches.len()); for (branch_index, branch) in envelope.branches.iter().enumerate() { + let Some(branch) = branch else { + // Claimed absent — an empty page with an attested skip + // of zero (there is nothing to skip in a tree that does + // not exist); authenticated in the shared walk below. + branch_pages.push((0, AxisEntries::empty_for_axis(expected_axis))); + branch_tail_roots.push(None); + continue; + }; let count_offset_result = verify_count_offset_on_range_proof( &branch.secondary_proof, &inner_range, @@ -692,8 +818,7 @@ impl GroveDb { err_label, )?; branch_pages.push((count_offset_result.skipped, entries)); - branch_tail_roots.push(tail_root); - branch_first_attestations.push(&branch.ancestor_attestations[0]); + branch_tail_roots.push(Some((tail_root, &branch.ancestor_attestations[0]))); } let root_hash = verify_branching_and_shared_layers( @@ -703,7 +828,6 @@ impl GroveDb { branch_keys, path_prefix, &branch_tail_roots, - &branch_first_attestations, err_label, )?; Ok(IndexedAxisBranchedPaginatedResult { diff --git a/grovedb/src/operations/proof/indexed_axis/envelope.rs b/grovedb/src/operations/proof/indexed_axis/envelope.rs index 24b5d55bb..3c3fb2d24 100644 --- a/grovedb/src/operations/proof/indexed_axis/envelope.rs +++ b/grovedb/src/operations/proof/indexed_axis/envelope.rs @@ -181,6 +181,16 @@ impl AxisEntries { pub fn is_empty(&self) -> bool { self.len() == 0 } + + /// The empty entry list of the given axis — what an + /// authenticated-absent branch of a branched proof verifies to. + pub fn empty_for_axis(axis: grovedb_element::indexed::IndexAxis) -> Self { + match axis { + grovedb_element::indexed::IndexAxis::Count => AxisEntries::Count(Vec::new()), + grovedb_element::indexed::IndexAxis::Sum => AxisEntries::Sum(Vec::new()), + grovedb_element::indexed::IndexAxis::Avg => AxisEntries::Avg(Vec::new()), + } + } } /// Verified result of a range / top-k / arbitrary-query proof. @@ -274,10 +284,16 @@ pub struct IndexedAxisBranchedRangeProof { /// `shared_layer_proofs.len()`. pub shared_ancestor_attestations: Vec, /// One multi-key Merk proof at the branching level, proving every - /// echoed branch key in the shared prefix's Merk. + /// echoed branch key in the shared prefix's Merk — presence for + /// branches that exist, **authenticated absence** for those that + /// don't (a Merk exact-key proof binds both outcomes). pub branching_layer_proof: Vec, /// Per-branch tails, aligned with the verifier's branch-key list. - pub branches: Vec, + /// `None` marks a branch whose key the branching-level proof shows + /// **absent**: that branch verifies as the empty page. The verifier + /// cross-checks presence both ways, so an envelope cannot claim a + /// tail for an absent key or absence for a present one. + pub branches: Vec>, /// Echoed query limit, shared by every branch. pub requested_limit: Option, /// Echoed iteration direction, shared by every branch. @@ -300,8 +316,10 @@ pub struct IndexedAxisBranchedPaginatedProof { /// Same as /// [`IndexedAxisBranchedRangeProof::branching_layer_proof`]. pub branching_layer_proof: Vec, - /// Per-branch tails, aligned with the verifier's branch-key list. - pub branches: Vec, + /// Per-branch tails, aligned with the verifier's branch-key list; + /// `None` = authenticated absence, same contract as + /// [`IndexedAxisBranchedRangeProof::branches`]. + pub branches: Vec>, /// Echoed page size, shared by every branch. pub requested_k: u16, /// Echoed offset, shared by every branch. diff --git a/grovedb/src/operations/proof/indexed_axis/generate.rs b/grovedb/src/operations/proof/indexed_axis/generate.rs index fd51ca3f3..45f8fd974 100644 --- a/grovedb/src/operations/proof/indexed_axis/generate.rs +++ b/grovedb/src/operations/proof/indexed_axis/generate.rs @@ -29,7 +29,7 @@ use super::{ /// list has length N-1 (one entry per intermediate layer). For each /// intermediate layer, open the parent merk and inspect the element /// at the depth's key to determine the chain composition. -fn build_ancestor_attestations<'db>( +pub(super) fn build_ancestor_attestations<'db>( grovedb: &'db GroveDb, path_keys: &[Vec], transaction: &'db Transaction, @@ -158,7 +158,7 @@ fn build_ancestor_attestations<'db>( /// Build single-key Merk proofs per layer, top-down. `layer_proofs[i]` /// proves the existence of `path_keys[i]` in the Merk at /// `path_keys[..i]`. -fn build_layer_proofs<'db>( +pub(super) fn build_layer_proofs<'db>( grovedb: &'db GroveDb, path_keys: &[Vec], transaction: &'db Transaction, diff --git a/grovedb/src/tests/indexed_axis_branched_proof_tests.rs b/grovedb/src/tests/indexed_axis_branched_proof_tests.rs index 0ce723054..b8771b054 100644 --- a/grovedb/src/tests/indexed_axis_branched_proof_tests.rs +++ b/grovedb/src/tests/indexed_axis_branched_proof_tests.rs @@ -446,4 +446,171 @@ mod tests { .unwrap() .is_err()); } + + /// An `IN` element whose prefix was never written contributes the + /// **empty page**, authenticated: the branching-level proof shows + /// the key absent, the envelope carries no tail for it, and the + /// present branch still proves normally under the same single root + /// hash — the union semantics the query surface advertises. + #[test] + fn an_absent_branch_key_verifies_as_the_empty_page() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture(&db, grove_version, &[(b"east", &[(b"math", 3)])]); + + let keys = vec![b"east".to_vec(), b"north".to_vec()]; + let proof = db + .prove_indexed_axis_top_k_paginated_branched( + &prefix(), + &keys, + &suffix(), + IndexAxis::Count, + 2, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("prove succeeds with an absent branch"); + + let result = GroveDb::verify_indexed_axis_top_k_paginated_branched( + &proof, + &prefix(), + &keys, + &suffix(), + IndexAxis::Count, + 2, + 0, + true, + ) + .expect("an absent branch verifies as empty"); + assert_eq!( + count_entries(&result.branches[0].1), + vec![(3, b"math".to_vec())], + "the present branch's page is intact" + ); + assert_eq!(result.branches[1].0, 0, "nothing to skip in an absent tree"); + assert!( + result.branches[1].1.is_empty(), + "the absent branch is the empty page" + ); + assert_eq!( + result.root_hash, + db.root_hash(None, grove_version) + .unwrap() + .expect("root hash readable"), + ); + + // The range shape has the same contract. + let range_proof = db + .prove_indexed_axis_query_branched( + &prefix(), + &keys, + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + None, + grove_version, + ) + .unwrap() + .expect("range prove succeeds with an absent branch"); + let range_result = GroveDb::verify_indexed_axis_query_branched( + &range_proof, + &prefix(), + &keys, + &suffix(), + IndexAxis::Count, + full_range_query(), + Some(10), + ) + .expect("range verify succeeds with an absent branch"); + assert!(range_result.branches[1].is_empty()); + } + + /// Absence forgery fails in both directions: an envelope claiming + /// absence for a key the branching proof shows present, and an + /// envelope carrying a tail for a key the proof shows absent. + #[test] + fn absence_forgeries_do_not_verify() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_fixture( + &db, + grove_version, + &[(b"east", &[(b"math", 3)]), (b"west", &[(b"science", 2)])], + ); + let config = bincode::config::standard(); + + // Direction 1: both present; claim west absent. + let both = branch_keys(); + let proof = db + .prove_indexed_axis_top_k_paginated_branched( + &prefix(), + &both, + &suffix(), + IndexAxis::Count, + 1, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("prove succeeds"); + let (mut envelope, _): (IndexedAxisBranchedPaginatedProof, _) = + bincode::decode_from_slice(&proof, config).expect("decode own envelope"); + envelope.branches[1] = None; + let tampered = bincode::encode_to_vec(&envelope, config).expect("re-encode"); + assert!( + GroveDb::verify_indexed_axis_top_k_paginated_branched( + &tampered, + &prefix(), + &both, + &suffix(), + IndexAxis::Count, + 1, + 0, + true, + ) + .is_err(), + "claiming a present branch absent must not verify" + ); + + // Direction 2: north is absent; graft east's tail onto it. + let with_absent = vec![b"east".to_vec(), b"north".to_vec()]; + let proof = db + .prove_indexed_axis_top_k_paginated_branched( + &prefix(), + &with_absent, + &suffix(), + IndexAxis::Count, + 1, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("prove succeeds"); + let (mut envelope, _): (IndexedAxisBranchedPaginatedProof, _) = + bincode::decode_from_slice(&proof, config).expect("decode own envelope"); + envelope.branches[1] = envelope.branches[0].clone(); + let tampered = bincode::encode_to_vec(&envelope, config).expect("re-encode"); + assert!( + GroveDb::verify_indexed_axis_top_k_paginated_branched( + &tampered, + &prefix(), + &with_absent, + &suffix(), + IndexAxis::Count, + 1, + 0, + true, + ) + .is_err(), + "a tail grafted onto an absent key must not verify" + ); + } } From 06985205a805d2c1106aeaae84cf2180170c8818 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 01:02:48 +0700 Subject: [PATCH 4/5] docs: book chapter for branched indexed-axis proofs Co-Authored-By: Claude Fable 5 --- docs/book/src/SUMMARY.md | 1 + docs/book/src/branched-indexed-axis-proofs.md | 192 ++++++++++++++++++ 2 files changed, 193 insertions(+) create mode 100644 docs/book/src/branched-indexed-axis-proofs.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 81bb96d01..c01d78e47 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -15,6 +15,7 @@ - [Aggregate Sum on Range Queries](aggregate-sum-on-range-queries.md) - [Count-Offset Paginated Queries](count-offset-paginated-queries.md) - [The CountIndexedTree](count-indexed-tree.md) +- [Branched Indexed-Axis Proofs](branched-indexed-axis-proofs.md) - [Batch Operations](batch-operations.md) - [Cost Tracking](cost-tracking.md) - [The MMR Tree](mmr-tree.md) diff --git a/docs/book/src/branched-indexed-axis-proofs.md b/docs/book/src/branched-indexed-axis-proofs.md new file mode 100644 index 000000000..c3c6cea8b --- /dev/null +++ b/docs/book/src/branched-indexed-axis-proofs.md @@ -0,0 +1,192 @@ +# Branched Indexed-Axis Proofs + +One query over N sibling indexed trees, one envelope, one root hash. + +## Motivation + +A compound index lays one indexed tree per *prefix value*: + +```text +…/region/ ← prefix property-name tree (a plain Merk) + "east"/cls ← indexed tree, own primary + per-axis secondaries + "west"/cls ← indexed tree, own primary + per-axis secondaries + "north"/cls ← indexed tree, own primary + per-axis secondaries +``` + +A query that pins one prefix value (`region == "east"`) reads one +indexed tree, and the single-path envelopes +(`IndexedAxisRangeProof` / `IndexedAxisPaginatedProof`) prove it. But a +query that pins *several* prefix values at once — `region IN ["east", +"west"]`, the shape Dash Platform's compound ranked indexes produce — +reads N sibling indexed trees whose paths differ at exactly one +segment: the **branching level**. + +Proving each branch with its own envelope works, but it is wasteful and +awkward in a specific, structural way: + +- every layer *above* the branching level — root, contract, document + type, the prefix property-name tree — is proved N times, byte for + byte; +- the caller receives N root hashes and must assert they are all equal + before trusting the union; +- nothing in any single envelope says the N branches belong to one + query against one state — that claim lives outside the proof system. + +The branched envelopes move that claim *inside* the proof system. + +## The shape + +Two envelope types mirror the two single-path shapes: + +- `IndexedAxisBranchedRangeProof` — one arbitrary secondary query (the + same bounds and limit) executed over every branch. +- `IndexedAxisBranchedPaginatedProof` — one offset-paginated top-k walk + (the same `k`, `offset`, direction) executed over every branch. + +Both share the same layer structure: + +| Field | What it carries | +|---|---| +| `shared_layer_proofs` | Single-key layer proofs for the path *prefix* (everything above the branching level), top-down — appearing **once**. | +| `shared_ancestor_attestations` | The per-layer chain-composition attestations for those shared layers. | +| `branching_layer_proof` | **One multi-key Merk proof** at the branching level, covering every branch key simultaneously — presence for branches that exist, authenticated absence for those that don't. | +| `branches` | `Vec>`, aligned with the caller's branch-key list. `Some` carries a branch's *tail*: its layers below the branch key, its primary-root and other-axes attestations, and its secondary proof. `None` marks an authenticated-absent branch. | +| echoes | The query parameters (`limit` / `k`, `offset`, direction), shared by every branch and re-checked by the verifier. | + +## Chain of trust + +Verification runs strictly upward, per branch first, then once for the +shared layers: + +```mermaid +graph TD + ROOT(["GroveDB root hash — reconstructed once"]) + SL["shared layers (single-key proofs + attestations)"] + BRK{{"branching Merk
ONE multi-key proof: keys + recorded value_hashes
(absence is proven for missing keys)"}} + + ROOT === SL === BRK + + subgraph EAST["branch east (Some tail)"] + EV["value tree 'east' — attestation[0]"] + ET["indexed tree — tail layer proof +
primary root + other axes"] + ES[("axis secondary — secondary proof")] + EV === ET === ES + end + subgraph NORTH["branch north (None)"] + NA["no tail — key proven absent
verifies as the empty page"] + end + + BRK === EV + BRK -.- NA + + ES -.->|"1. deepest-layer binding:
H(elem) ⊕ primary_root ⊕ secondary_root"| ET + ET -.->|"2. tail walk"| EV + EV -.->|"3. compose(elem bytes from the multi-key proof,
tail root, attestation) ≟ recorded value_hash"| BRK + BRK -.->|"4. one shared walk"| ROOT +``` + +1. **Per branch**: the secondary proof verifies on its own and yields + the branch's secondary root hash; the deepest tail layer binds that + hash (and the primary root) into the indexed-tree element's recorded + `value_hash` — the same H1-A composition every single-path envelope + uses; the tail walk reconstructs the branch's value-tree root. +2. **The branching level**: the branch's value-tree root, composed with + the element bytes *taken from the multi-key proof*, must equal the + `value_hash` the multi-key proof recorded for the branch's own key. + This is the binding step: a tail swapped between branches, + duplicated, or grafted from another state reconstructs a different + subtree root and fails here. +3. **Once**: the multi-key proof's own Merk root seeds a single + ancestor walk through the shared layers to the GroveDB root hash. + +The verifier takes the branch-key list from the *caller* (who derives +it from their own query), so an envelope carrying more, fewer, or +reordered branches fails structurally before any hashing happens. + +## Authenticated absence + +An `IN` element whose prefix subtree was never created is a legal +member of the union — it contributes the empty page, not an error. The +mechanism is the branching level's exact-key Merk proof, which +authenticates *both* outcomes: a queried key missing from the result +set is proven absent, exactly as Merk absence proofs have always +worked. + +An absent branch therefore carries no tail (`None` in `branches`), and +the verifier cross-checks presence in both directions: + +- an envelope claiming a **tail for an absent key** fails — the + multi-key proof has no recorded `value_hash` to bind it to; +- an envelope claiming **absence for a present key** fails — the + multi-key proof carries the key's element, and `None` contradicts it. + +Presence is decided at the branching Merk itself. Deeper breakage under +a *present* key — a value tree that exists but is missing the expected +indexed tree below it — remains an error, because that is corrupted +state, not an empty result. + +When every requested branch is absent, the shared layers are built from +the path prefix alone, so even the all-empty union chains to the root +hash. + +## What the caller gets + +- Range shape: `IndexedAxisBranchedQueryResult { root_hash, branches: + Vec }` — per-branch entries aligned with the caller's + branch keys, empty for absent branches. +- Paginated shape: `IndexedAxisBranchedPaginatedResult { root_hash, + branches: Vec<(skipped, AxisEntries)> }` — per-branch pages with the + same independently re-derived `skipped` semantics as the single-path + paginated verifier; an absent branch attests a skip of zero. + +Merging the branch pages into one ordered result is deliberately left +to the caller: the merged page is a deterministic function of the +verified branch pages, so no additional proof material is needed — any +entry that would precede a returned entry in the caller's merge order +is, within its own branch, preceded by fewer than `limit` entries and +therefore already in that branch's page. + +## Reuse, not new machinery + +No storage or hash-composition changes exist anywhere in this feature. +The prover reuses the single-path envelope builders per branch and +splits their output at the branching depth; the verifier reuses the +audited `verify_deepest_layer` and `walk_ancestor_chain` on the tail +and shared windows, plus one multi-key variant of the layer-proof +executor. The envelope types are new — per the proof system's rule that +new shapes get new envelope types — and everything else is composition. + +## API + +```rust,ignore +// Prove (feature = "minimal"): +db.prove_indexed_axis_query_branched( + path_prefix, branch_keys, path_suffix, + axis, secondary_query, limit, transaction, grove_version) +db.prove_indexed_axis_top_k_paginated_branched( + path_prefix, branch_keys, path_suffix, + axis, k, offset, descending, transaction, grove_version) + +// Verify (verifier-only builds included): +GroveDb::verify_indexed_axis_query_branched( + proof, path_prefix, branch_keys, path_suffix, + axis, secondary_query, limit) +GroveDb::verify_indexed_axis_top_k_paginated_branched( + proof, path_prefix, branch_keys, path_suffix, + axis, k, offset, descending) +``` + +Branch keys must be at least two (one branch is the single-path +envelope's job) and pairwise distinct; both ends enforce this. + +## Summary + +- N sibling indexed trees, differing at one path segment, proved in + **one envelope with one root hash**. +- Shared ancestor layers appear once; the branching level is one + multi-key Merk proof; each branch carries only its tail. +- Branch tails are cryptographically bound to their branch keys — no + swapping, duplicating, dropping, or grafting. +- Absent branches are authenticated as empty, so `IN` unions have real + set semantics. +- Built entirely from existing, audited proof primitives. From e5463bffddc46c15b1e427fc9e37e8899eb19492 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 01:46:14 +0700 Subject: [PATCH 5/5] feat: canonical Display for branched indexed-axis envelopes Decodes every embedded Merk proof into the same op-level notation GroveDBProof's Display uses, so a branched proof dump reads like any other GroveDB proof dump. Co-Authored-By: Claude Fable 5 --- .../operations/proof/indexed_axis/display.rs | 137 ++++++++++++++++++ .../src/operations/proof/indexed_axis/mod.rs | 1 + grovedb/src/operations/proof/mod.rs | 2 +- 3 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 grovedb/src/operations/proof/indexed_axis/display.rs diff --git a/grovedb/src/operations/proof/indexed_axis/display.rs b/grovedb/src/operations/proof/indexed_axis/display.rs new file mode 100644 index 000000000..6371d7b1f --- /dev/null +++ b/grovedb/src/operations/proof/indexed_axis/display.rs @@ -0,0 +1,137 @@ +//! Canonical op-level rendering for the branched indexed-axis +//! envelopes — the same `Merk(0: Push(...) 1: Parent ...)` notation +//! [`crate::GroveDBProof`]'s `Display` uses, so a decoded branched +//! proof reads exactly like every other GroveDB proof dump. + +use std::fmt; + +use crate::operations::proof::decode_merk_proof; + +use super::{ + BranchedProofBranch, IndexedAxisBranchedPaginatedProof, IndexedAxisBranchedRangeProof, +}; + +fn write_layers( + f: &mut fmt::Formatter<'_>, + indent: &str, + label: &str, + layers: &[Vec], +) -> fmt::Result { + writeln!(f, "{indent}{label}: [")?; + for (i, layer) in layers.iter().enumerate() { + for (line_no, line) in format!("{i}: Merk({})", decode_merk_proof(layer)?) + .lines() + .enumerate() + { + if line_no == 0 { + writeln!(f, "{indent} {line}")?; + } else { + writeln!(f, "{indent} {line}")?; + } + } + } + writeln!(f, "{indent}]") +} + +fn write_branch( + f: &mut fmt::Formatter<'_>, + indent: &str, + index: usize, + branch: &Option, +) -> fmt::Result { + match branch { + None => writeln!( + f, + "{indent}{index} => ABSENT (authenticated by branching layer)" + ), + Some(branch) => { + writeln!(f, "{indent}{index} => Branch {{")?; + let inner = format!("{indent} "); + writeln!( + f, + "{inner}ancestor_attestations: {:?}", + branch.ancestor_attestations + )?; + write_layers(f, &inner, "tail_layers", &branch.tail_layer_proofs)?; + writeln!( + f, + "{inner}primary_root_hash: HASH[{}]", + hex::encode(branch.primary_root_hash) + )?; + if !branch.other_axes_root_hashes.is_empty() { + writeln!( + f, + "{inner}other_axes_root_hashes: {:?}", + branch + .other_axes_root_hashes + .iter() + .map(|(tag, hash)| (tag, hex::encode(hash))) + .collect::>() + )?; + } + writeln!(f, "{inner}target_is_pcpsit: {}", branch.target_is_pcpsit)?; + writeln!( + f, + "{inner}secondary_proof: Merk({})", + decode_merk_proof(&branch.secondary_proof)? + )?; + writeln!(f, "{indent}}}") + } + } +} + +impl fmt::Display for IndexedAxisBranchedPaginatedProof { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + writeln!(f, "IndexedAxisBranchedPaginatedProof {{")?; + writeln!( + f, + " axis_tag: {}, k: {}, offset: {}, descending: {}", + self.axis_tag, self.requested_k, self.requested_offset, self.descending + )?; + write_layers(f, " ", "shared_layers", &self.shared_layer_proofs)?; + writeln!( + f, + " shared_ancestor_attestations: {:?}", + self.shared_ancestor_attestations + )?; + writeln!( + f, + " branching_layer: Merk({})", + decode_merk_proof(&self.branching_layer_proof)? + )?; + writeln!(f, " branches: {{")?; + for (i, branch) in self.branches.iter().enumerate() { + write_branch(f, " ", i, branch)?; + } + writeln!(f, " }}")?; + write!(f, "}}") + } +} + +impl fmt::Display for IndexedAxisBranchedRangeProof { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + writeln!(f, "IndexedAxisBranchedRangeProof {{")?; + writeln!( + f, + " axis_tag: {}, limit: {:?}, descending: {}", + self.axis_tag, self.requested_limit, self.descending + )?; + write_layers(f, " ", "shared_layers", &self.shared_layer_proofs)?; + writeln!( + f, + " shared_ancestor_attestations: {:?}", + self.shared_ancestor_attestations + )?; + writeln!( + f, + " branching_layer: Merk({})", + decode_merk_proof(&self.branching_layer_proof)? + )?; + writeln!(f, " branches: {{")?; + for (i, branch) in self.branches.iter().enumerate() { + write_branch(f, " ", i, branch)?; + } + writeln!(f, " }}")?; + write!(f, "}}") + } +} diff --git a/grovedb/src/operations/proof/indexed_axis/mod.rs b/grovedb/src/operations/proof/indexed_axis/mod.rs index 82e05e6e2..185af75f4 100644 --- a/grovedb/src/operations/proof/indexed_axis/mod.rs +++ b/grovedb/src/operations/proof/indexed_axis/mod.rs @@ -63,6 +63,7 @@ mod axis_api; mod branched; +mod display; mod envelope; #[cfg(feature = "minimal")] mod generate; diff --git a/grovedb/src/operations/proof/mod.rs b/grovedb/src/operations/proof/mod.rs index 65e708338..8d9867b70 100644 --- a/grovedb/src/operations/proof/mod.rs +++ b/grovedb/src/operations/proof/mod.rs @@ -740,7 +740,7 @@ impl fmt::Display for GroveDBProofV1 { } } -fn decode_merk_proof(proof: &[u8]) -> Result { +pub(crate) fn decode_merk_proof(proof: &[u8]) -> Result { let mut result = String::new(); let ops = MerkDecoder::new(proof);