From 4cd44baac5cdf6a50537cea70e65abbcbb7357fd Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 05:13:41 +0700 Subject: [PATCH 1/4] feat: axis-ordered reads embedded in the GroveDBProof V1 envelope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The full-integration step: a PathQuery whose query node carries ReadMode::Axis now proves and verifies through the general V1 proof walk, via a new appended ProofBytes::IndexedTreeAxisDescent variant whose payload carries a proof over the queried per-axis SECONDARY in place of the primary descent. Trust model. The payload echoes no traversal parameters (the V1 envelope's query-as-input philosophy — the verifier resolves the axis, bounds, direction, and caps from the query it independently holds, via the new PathQuery::axis_read_at_path, the same resolver the prover uses, so the two sides cannot disagree about which layers are axis reads). The verifier RECOMPUTES the secondary-root attestation from the carried secondary proof — never accepting 32 raw bytes — then rebuilds the third combine_hash_three input (the recomputed root for PCIT/PSIT; the axes digest over carried other-axes roots plus the recomputed queried-axis root for PCPSIT, family-checked against axis-relabel forgery) and requires the parent-committed value_hash to match. The one echo is the RankOfKey rank, needed to drive the count-offset verification walk; the count commitments attest it and the yielded entry must be the queried key. Branched axis reads fall out of the ordinary walk: branch keys are Key items at the branching layer (one multi-key merk proof, absence proven natively), each present branch descends the shared suffix to its own axis-descent terminal, and the verifier rejects a proof that shows a branch key present while omitting its axis layer — hiding entries behind fake absence fails closed. Surface: prove_query serves axis shapes (V1 envelope only, GROVE_V4's new proof.axis_descent_in_v1_envelope slot on both sides — V0 refusal follows the ACOR template); the new verify_path_query is the unified verify entry returning a typed VerifiedPathQuery for every provable shape (key selection, all six aggregate forms, axis entries/rank/ aggregate, branched with authenticated absence); the verify_query family stays key-selection-only. Sum-budget shapes still have no proof form. The rank computation and attestation-binding cores are factored from the standalone envelope machinery and shared, not duplicated. Tests: round trips for every traversal (top-k, paginated, bounded, rank both directions, range aggregate) incl. PCPSIT multi-axis digest reconstruction and branched absence; equality cross-checks against both the trusted reads and the standalone envelopes with matching root hashes; forgery rejections (forged primary root, relabeled axis tag, tampered secondary bytes, smuggled other-axes list, lying rank echo, stripped present branch); V3-refuses/V4-serves gates on both sides and V0-envelope rejection. Full suite, clippy, verify-only build green. Co-Authored-By: Claude Fable 5 --- .../src/version/grovedb_versions.rs | 24 + grovedb-version/src/version/v1.rs | 1 + grovedb-version/src/version/v2.rs | 1 + grovedb-version/src/version/v3.rs | 1 + grovedb-version/src/version/v4.rs | 9 + grovedb/src/operations/proof/generate.rs | 139 +++- .../operations/proof/indexed_axis/envelope.rs | 11 + .../operations/proof/indexed_axis/generate.rs | 242 +++++++ .../src/operations/proof/indexed_axis/mod.rs | 2 +- .../operations/proof/indexed_axis/verify.rs | 78 ++- grovedb/src/operations/proof/mod.rs | 113 ++++ grovedb/src/operations/proof/verify.rs | 394 ++++++++++- .../src/operations/proof/verify_path_query.rs | 423 ++++++++++++ grovedb/src/query/axis_lowering.rs | 117 ++++ grovedb/src/query/mod.rs | 86 ++- grovedb/src/query/shape.rs | 5 +- grovedb/src/tests/axis_descent_proof_tests.rs | 623 ++++++++++++++++++ grovedb/src/tests/mod.rs | 1 + grovedb/src/tests/proof_depth_limit_tests.rs | 4 + grovedb/src/tests/read_mode_gate_tests.rs | 21 +- 20 files changed, 2253 insertions(+), 42 deletions(-) create mode 100644 grovedb/src/operations/proof/verify_path_query.rs create mode 100644 grovedb/src/query/axis_lowering.rs create mode 100644 grovedb/src/tests/axis_descent_proof_tests.rs diff --git a/grovedb-version/src/version/grovedb_versions.rs b/grovedb-version/src/version/grovedb_versions.rs index 877aeb355..88d6ae356 100644 --- a/grovedb-version/src/version/grovedb_versions.rs +++ b/grovedb-version/src/version/grovedb_versions.rs @@ -191,6 +191,30 @@ pub struct GroveDBOperationsProofVersions { /// non-empty **Merk** trees have required the child hash since V3 and /// stay bound at every version. pub terminal_non_merk_tree_child_hash: FeatureVersion, + /// Whether the V1 proof envelope carries **axis-ordered descents** + /// into indexed trees (`ProofBytes::IndexedTreeAxisDescent`), + /// serving `PathQuery`s whose query node holds `ReadMode::Axis`. + /// + /// - `0` (V1..V3): the prover refuses axis-shaped queries with + /// `NotSupported` and the verifier rejects any proof/query pair + /// involving one. These versions also reject the version-2 + /// `Query` wire encoding outright, so the slot's `0` value is the + /// in-process mirror of that fail-closed decode. + /// - `1` (V4+): the prover emits the axis-descent layer — a proof + /// over the queried per-axis **secondary** in place of the primary + /// descent — and the verifier accepts it, recomputing the + /// secondary-root attestation from the carried secondary proof + /// (never trusting 32 raw bytes) before performing the same + /// `combine_hash_three` parent binding as the other indexed + /// shapes. + /// + /// Gated because it adds an acceptance rule to the live V1 + /// envelope: an upgraded verifier accepts proof shapes a released + /// one rejects. Prover and verifier read the same slot, so there is + /// no version at which they disagree about whether the shape + /// exists. Indexed trees themselves cannot exist in pre-V4 + /// production data, so `0` never rejects anything real. + pub axis_descent_in_v1_envelope: FeatureVersion, } #[derive(Clone, Debug, Default)] diff --git a/grovedb-version/src/version/v1.rs b/grovedb-version/src/version/v1.rs index 6a1cf6bb3..0577ee368 100644 --- a/grovedb-version/src/version/v1.rs +++ b/grovedb-version/src/version/v1.rs @@ -168,6 +168,7 @@ pub const GROVE_V1: GroveVersion = GroveVersion { verify_query_with_chained_path_queries: 0, verify_query_get_parent_tree_info_with_options: 0, terminal_non_merk_tree_child_hash: 0, + axis_descent_in_v1_envelope: 0, }, average_case: GroveDBOperationsAverageCaseVersions { add_average_case_get_merk_at_path: 0, diff --git a/grovedb-version/src/version/v2.rs b/grovedb-version/src/version/v2.rs index 63072919a..664de0b89 100644 --- a/grovedb-version/src/version/v2.rs +++ b/grovedb-version/src/version/v2.rs @@ -168,6 +168,7 @@ pub const GROVE_V2: GroveVersion = GroveVersion { verify_query_with_chained_path_queries: 0, verify_query_get_parent_tree_info_with_options: 0, terminal_non_merk_tree_child_hash: 0, + axis_descent_in_v1_envelope: 0, }, average_case: GroveDBOperationsAverageCaseVersions { add_average_case_get_merk_at_path: 0, diff --git a/grovedb-version/src/version/v3.rs b/grovedb-version/src/version/v3.rs index 96f0aa18d..a935c1e52 100644 --- a/grovedb-version/src/version/v3.rs +++ b/grovedb-version/src/version/v3.rs @@ -172,6 +172,7 @@ pub const GROVE_V3: GroveVersion = GroveVersion { verify_query_with_chained_path_queries: 0, verify_query_get_parent_tree_info_with_options: 0, terminal_non_merk_tree_child_hash: 0, + axis_descent_in_v1_envelope: 0, }, average_case: GroveDBOperationsAverageCaseVersions { add_average_case_get_merk_at_path: 0, diff --git a/grovedb-version/src/version/v4.rs b/grovedb-version/src/version/v4.rs index fc22418d0..1e7caf985 100644 --- a/grovedb-version/src/version/v4.rs +++ b/grovedb-version/src/version/v4.rs @@ -32,6 +32,14 @@ //! flips a rejected/accepted outcome and because deriving the state root //! costs the prover extra storage reads and hash calls. //! +//! - `proof.axis_descent_in_v1_envelope: 1` — the V1 proof envelope carries +//! axis-ordered descents into indexed trees +//! (`ProofBytes::IndexedTreeAxisDescent`): a proof over the queried +//! per-axis secondary in place of the primary descent, with the +//! secondary-root attestation recomputed by the verifier rather than +//! supplied raw. V1..V3 refuse the shape on both sides. Gated because it +//! adds an acceptance rule to the live V1 envelope. +//! //! - `path_query_methods.unified_read_mode: 1` — `PathQuery` read modes //! (axis-ordered and sum-budget reads carried in `Query::read_mode`) are //! served by the unified dispatch (`run_path_query`, and the unified @@ -230,6 +238,7 @@ pub const GROVE_V4: GroveVersion = GroveVersion { verify_query_with_chained_path_queries: 0, verify_query_get_parent_tree_info_with_options: 0, terminal_non_merk_tree_child_hash: 1, // bind terminal non-Merk tree element bytes to the parent value_hash + axis_descent_in_v1_envelope: 1, // axis-ordered descents in the V1 envelope (ReadMode::Axis) }, average_case: GroveDBOperationsAverageCaseVersions { add_average_case_get_merk_at_path: 0, diff --git a/grovedb/src/operations/proof/generate.rs b/grovedb/src/operations/proof/generate.rs index 90bd8ae2a..edf838381 100644 --- a/grovedb/src/operations/proof/generate.rs +++ b/grovedb/src/operations/proof/generate.rs @@ -109,12 +109,35 @@ impl GroveDb { prove_options: Option, grove_version: &GroveVersion, ) -> CostResult { - // Read-mode gate: axis / sum-budget reads are not served by this - // prover. Fail closed rather than misreading such a query as key - // selection and returning a proof about the wrong thing. - if let Err(e) = path_query.reject_unserved_read_mode() { - return Err(e).wrap_with_cost(OperationCost::default()); - } + // Read-mode dispatch. Axis shapes are served by the V1 envelope + // — validated here (classify runs the full shape grammar) and + // gated below once `prove_version` is known. Sum-budget shapes + // have no proof form yet. Anything malformed fails closed + // rather than being misread as key selection. + let is_axis_shape = if path_query.query.query.has_read_mode_anywhere() { + match path_query.classify() { + Ok(crate::PathQueryShape::AxisRead { .. }) + | Ok(crate::PathQueryShape::BranchedAxisRead { .. }) => true, + Ok(crate::PathQueryShape::SumBudget { .. }) => { + return Err(Error::NotSupported( + "sum-budget path queries have no proof form yet; prove the underlying \ + items with a key-selection query and fold client-side, or use the \ + trusted read (run_path_query)" + .to_string(), + )) + .wrap_with_cost(OperationCost::default()); + } + Ok(_) => { + return Err(Error::CorruptedCodeExecution( + "a read-mode-bearing query classified as a non-read-mode shape", + )) + .wrap_with_cost(OperationCost::default()); + } + Err(e) => return Err(e).wrap_with_cost(OperationCost::default()), + } + } else { + false + }; // Aggregate-count gate: validate at entry so malformed ACOR // queries (invalid inner range, ACOR-hidden-in-subquery, etc.) are // rejected up front instead of being skipped when the recursive @@ -161,6 +184,35 @@ impl GroveDb { // refusing the combination here keeps callers from accidentally // emitting a V0 ACOR proof that the verifier would (correctly) // reject. + // Axis shapes are V1-envelope-only, and a V4 capability: refuse + // the V0 envelope (same contract as the aggregate gates below) + // and pre-V4 versions up front, mirroring the verifier's + // envelope gate so both sides agree at every version. + if is_axis_shape { + if prove_version == 0 { + return Err(Error::NotSupported( + "axis-ordered path queries require V1 proof envelopes; upgrade the grove \ + version producing the proof" + .to_string(), + )) + .wrap_with_cost(OperationCost::default()); + } + if grove_version + .grovedb_versions + .operations + .proof + .axis_descent_in_v1_envelope + != 1 + { + return Err(Error::NotSupported( + "axis-ordered descents in the V1 proof envelope are not emitted at this \ + grove version" + .to_string(), + )) + .wrap_with_cost(OperationCost::default()); + } + } + if is_acor_query && prove_version == 0 { return Err(Error::NotSupported( "AggregateCountOnRange proofs require V1 proof envelopes; upgrade the grove \ @@ -1958,6 +2010,81 @@ impl GroveDb { lower_layers.insert(key.clone(), layer_proof); } + // Axis-ordered read of an indexed tree: the + // query node governing this element carries + // ReadMode::Axis, so instead of descending the + // primary the layer carries an axis-descent + // payload — a proof over the queried per-axis + // secondary. Matched before the primary-descent + // arms below so an axis read can never be + // silently served as a primary descent; matches + // empty primaries too (the payload commits + // NULL_HASH roots naturally). + Ok(Element::ProvableCountIndexedTree(..)) + | Ok(Element::ProvableSumIndexedTree(..)) + | Ok(Element::ProvableCountProvableSumIndexedTree(..)) + if !done_with_results && { + let mut lower_path = path.clone(); + lower_path.push(key.as_slice()); + path_query.axis_read_at_path(&lower_path).is_some() + } => + { + let mut lower_path = path.clone(); + lower_path.push(key.as_slice()); + let Some(axis_query) = path_query.axis_read_at_path(&lower_path) + else { + return Err(Error::CorruptedCodeExecution( + "axis read vanished between the match guard and the arm", + )) + .wrap_with_cost(cost); + }; + + // The axis descent is a GROVE_V4 envelope + // capability; older versions refuse to emit + // it, mirroring the verifier-side gate. + if grove_version + .grovedb_versions + .operations + .proof + .axis_descent_in_v1_envelope + != 1 + { + return Err(Error::NotSupported( + "axis-ordered descents in the V1 proof envelope are \ + not emitted at this grove version" + .to_string(), + )) + .wrap_with_cost(cost); + } + + let payload_batch = grovedb_storage::StorageBatch::new(); + let lower_subtree_path: grovedb_path::SubtreePath<&[u8]> = + lower_path.as_slice().into(); + let payload = cost_return_on_error!( + &mut cost, + self.build_axis_descent_payload( + lower_subtree_path, + axis_query, + &tx, + &payload_batch, + grove_version, + ) + ); + let payload_bytes = + cost_return_on_error_no_add!(cost, payload.encode_canonical()); + lower_layers.insert( + key.clone(), + LayerProof { + merk_proof: + crate::operations::proof::ProofBytes::IndexedTreeAxisDescent( + payload_bytes, + ), + lower_layers: Default::default(), + }, + ); + has_a_result_at_level |= true; + } + // Subquery into CountIndexedTree: descend into // the primary like a regular tree, then wrap // the resulting Merk proof bytes with a 32-byte diff --git a/grovedb/src/operations/proof/indexed_axis/envelope.rs b/grovedb/src/operations/proof/indexed_axis/envelope.rs index 7ed405206..051024314 100644 --- a/grovedb/src/operations/proof/indexed_axis/envelope.rs +++ b/grovedb/src/operations/proof/indexed_axis/envelope.rs @@ -178,6 +178,17 @@ impl AxisEntries { } /// Whether the result list is empty. + /// The first entry's original (primary) key, if any — the yielded + /// item of a `k = 1` page, used by rank verification. + pub fn first_original_key(&self) -> Option<&[u8]> { + match self { + AxisEntries::Count(entries) => entries.first().map(|(_, key)| key.as_slice()), + AxisEntries::Sum(entries) => entries.first().map(|(_, key)| key.as_slice()), + AxisEntries::Avg(entries) => entries.first().map(|(_, key)| key.as_slice()), + } + } + + /// Whether there are no entries. pub fn is_empty(&self) -> bool { self.len() == 0 } diff --git a/grovedb/src/operations/proof/indexed_axis/generate.rs b/grovedb/src/operations/proof/indexed_axis/generate.rs index d71dd4adb..81329e368 100644 --- a/grovedb/src/operations/proof/indexed_axis/generate.rs +++ b/grovedb/src/operations/proof/indexed_axis/generate.rs @@ -24,6 +24,7 @@ use super::{ aggregate_range_out_of_domain, AncestorAttestation, IndexedAxisAggregateProof, IndexedAxisPaginatedProof, IndexedAxisRangeProof, }; +use crate::operations::proof::AxisDescentProof; /// Build the per-ancestor attestation list for a path of length N: the /// list has length N-1 (one entry per intermediate layer). For each @@ -1160,6 +1161,247 @@ impl GroveDb { }) .wrap_with_cost(cost) } + + /// Build the [`AxisDescentProof`] payload for an axis-ordered read + /// of the indexed tree at `path` — the embedded (V1-envelope) form + /// of an axis proof. Unlike the standalone envelope builders above, + /// no path-walk layers or ancestor attestations are collected here: + /// in the V1 envelope those are ordinary layers of the general + /// proof walk, and this payload covers only the indexed element's + /// own axis read. + /// + /// The traversal is taken from the query and NOT echoed into the + /// payload (the V1 envelope's query-as-input philosophy); the one + /// exception is `RankOfKey`, whose computed rank must travel so the + /// verifier can drive the count-offset verification walk — the + /// count commitments then attest it. + pub(crate) fn build_axis_descent_payload<'db, 'b, B: AsRef<[u8]>>( + &'db self, + path: SubtreePath<'b, B>, + axis_query: &grovedb_query::AxisQuery, + transaction: &'db Transaction, + batch: &'db StorageBatch, + grove_version: &GroveVersion, + ) -> CostResult { + use grovedb_query::AxisTraversal; + + let mut cost = OperationCost::default(); + let axis = axis_query.axis; + + let path_keys: Vec> = path.to_vec(); + if path_keys.is_empty() { + return Err(Error::InvalidPath( + "cannot build an axis descent at the root path".to_string(), + )) + .wrap_with_cost(cost); + } + + // Per-axis validation + secondary root key + non-queried axes. + let (secondary_root_key, other_axes_root_hashes, target_is_pcpsit) = cost_return_on_error!( + &mut cost, + read_queried_axis_info_with_path_keys( + self, + &path_keys, + axis, + transaction, + batch, + grove_version, + "axis descent", + ) + ); + + // Primary root hash (an empty primary commits NULL_HASH + // naturally). + let primary_merk = cost_return_on_error!( + &mut cost, + self.open_transactional_merk_at_path( + path.clone(), + transaction, + Some(batch), + grove_version + ) + ); + if !primary_merk.tree_type.is_indexed_primary() { + return Err(Error::InvalidPath( + "axis descent requires the path's last segment to be an indexed-tree element" + .to_string(), + )) + .wrap_with_cost(cost); + } + let (primary_root_hash, _, _) = cost_return_on_error!( + &mut cost, + primary_merk + .root_hash_key_and_aggregate_data() + .map_err(|e| Error::CorruptedData(format!("axis descent: primary root hash: {e}"))) + ); + + // Rank first (it opens its own merks), so the secondary borrow + // below doesn't overlap. + let rank = match &axis_query.traversal { + AxisTraversal::RankOfKey { key } => Some(cost_return_on_error!( + &mut cost, + self.compute_indexed_axis_rank_of_key( + path.clone(), + axis, + key, + axis_query.descending, + Some(transaction), + grove_version, + ) + )), + _ => None, + }; + + // The secondary proof for the query's traversal. + let secondary_merk = cost_return_on_error!( + &mut cost, + self.open_indexed_secondary_at_path( + path, + axis, + secondary_root_key, + transaction, + Some(batch), + grove_version, + ) + ); + let secondary_proof = match &axis_query.traversal { + AxisTraversal::TopK { k, offset } => { + cost_return_on_error_no_add!( + cost, + build_paginated_secondary_proof( + &secondary_merk, + *offset, + *k, + axis_query.descending, + axis, + grove_version, + &mut cost, + ) + ) + } + AxisTraversal::RankOfKey { .. } => { + // rank computed above; the rank proof IS the paginated + // proof at (offset = rank, k = 1). + let rank_offset = rank.expect("set above for RankOfKey"); + cost_return_on_error_no_add!( + cost, + build_paginated_secondary_proof( + &secondary_merk, + rank_offset, + 1, + axis_query.descending, + axis, + grove_version, + &mut cost, + ) + ) + } + AxisTraversal::Bounded { limit, .. } => { + let secondary_query = cost_return_on_error_no_add!( + cost, + crate::query::axis_lowering::axis_bounded_merk_query(axis_query) + ); + let sec_result = cost_return_on_error!( + &mut cost, + secondary_merk + .prove(secondary_query, Some(*limit), grove_version) + .map_err(|e| Error::CorruptedData(format!( + "axis descent: secondary range proof: {e}" + ))) + ); + sec_result.proof + } + AxisTraversal::RangeAggregate { lo, hi } => match axis { + IndexAxis::Count => { + // classify() rejects wholly-out-of-domain ranges, so + // clamping cannot collapse onto a boundary key here. + let lo_count = (*lo).clamp(0, u64::MAX as i128) as u64; + let hi_count = (*hi).clamp(0, u64::MAX as i128) as u64; + cost_return_on_error_no_add!( + cost, + build_count_aggregate_secondary_proof( + &secondary_merk, + lo_count, + hi_count, + grove_version, + &mut cost, + ) + ) + } + IndexAxis::Sum => { + let lo_sum = (*lo).clamp(i64::MIN as i128, i64::MAX as i128) as i64; + let hi_sum = (*hi).clamp(i64::MIN as i128, i64::MAX as i128) as i64; + cost_return_on_error_no_add!( + cost, + build_sum_aggregate_secondary_proof( + &secondary_merk, + lo_sum, + hi_sum, + grove_version, + &mut cost, + ) + ) + } + IndexAxis::Avg => { + return Err(Error::NotSupported( + "axis descent: range aggregates are not defined for the Avg axis" + .to_string(), + )) + .wrap_with_cost(cost); + } + }, + }; + + Ok(AxisDescentProof { + axis_tag: axis.tag(), + target_is_pcpsit, + other_axes_root_hashes, + primary_root_hash, + rank, + secondary_proof, + }) + .wrap_with_cost(cost) + } +} + +/// The count-offset paginated secondary proof shared by the `TopK` and +/// `RankOfKey` embedded traversals — the same shape step 4 of +/// `build_indexed_axis_paginated_proof` emits. +fn build_paginated_secondary_proof<'db, S>( + secondary_merk: &grovedb_merk::Merk, + offset: u64, + k: u16, + descending: bool, + axis: IndexAxis, + grove_version: &GroveVersion, + cost: &mut OperationCost, +) -> Result, Error> +where + S: grovedb_storage::StorageContext<'db>, +{ + if !secondary_merk.tree_type.is_count_bearing() { + return Err(Error::NotSupported(format!( + "axis descent: the {axis:?} axis secondary ({:?}) does not carry a provable count \ + aggregate, so offset pagination cannot be attested", + secondary_merk.tree_type + ))); + } + let inner_range = MerkQueryItemForRange::RangeFull(std::ops::RangeFull); + let prove_result = secondary_merk + .prove_count_offset_on_range( + &inner_range, + offset, + Some(k as u64), + !descending, + grove_version, + ) + .unwrap_add_cost(cost) + .map_err(|e| { + Error::CorruptedData(format!("axis descent: secondary count-offset proof: {e}")) + })?; + let mut serialized = Vec::with_capacity(128); + encode_into(prove_result.ops.iter(), &mut serialized); + Ok(serialized) } fn build_count_aggregate_secondary_proof<'db, S>( diff --git a/grovedb/src/operations/proof/indexed_axis/mod.rs b/grovedb/src/operations/proof/indexed_axis/mod.rs index 42177527b..7508c14f7 100644 --- a/grovedb/src/operations/proof/indexed_axis/mod.rs +++ b/grovedb/src/operations/proof/indexed_axis/mod.rs @@ -65,7 +65,7 @@ mod axis_api; mod envelope; #[cfg(feature = "minimal")] mod generate; -mod verify; +pub(crate) mod verify; pub use envelope::{ AncestorAttestation, AxisEntries, IndexedAxisAggregateProof, IndexedAxisAggregateResult, diff --git a/grovedb/src/operations/proof/indexed_axis/verify.rs b/grovedb/src/operations/proof/indexed_axis/verify.rs index c6d731454..d7aadaa6c 100644 --- a/grovedb/src/operations/proof/indexed_axis/verify.rs +++ b/grovedb/src/operations/proof/indexed_axis/verify.rs @@ -126,6 +126,48 @@ fn verify_deepest_layer( execute_single_key_proof(&layer_proofs[last_idx], cidx_key, err_label)?; let actual_value_hash = value_hash(&cidx_value_bytes).value().to_owned(); + let queried_axis_digest = recompute_axis_binding_digest( + &cidx_value_bytes, + axis, + secondary_root_hash, + other_axes_root_hashes, + target_is_pcpsit, + err_label, + )?; + + let combined = combine_hash_three(&actual_value_hash, primary_root_hash, &queried_axis_digest) + .value() + .to_owned(); + if combined != cidx_value_hash_recorded { + return Err(Error::CorruptedData(format!( + "{err_label}: deepest-layer chain mismatch — parent recorded value_hash {} but \ + combine_hash_three(H(value), primary_root, axis_digest) is {}", + hex::encode(cidx_value_hash_recorded), + hex::encode(combined) + ))); + } + Ok(layer_root) +} + +/// The attestation-binding core shared by the standalone envelopes and +/// the embedded V1 axis descent: check the proved element's family +/// against the requested axis, then recompute the third +/// `combine_hash_three` input — the queried secondary's (recomputed) +/// root hash for PCIT / PSIT, or the `axes_digest` over +/// `other_axes_root_hashes` + the queried axis's recomputed root for +/// PCPSIT. +/// +/// The caller performs the `combine_hash_three(H(value), primary_root, +/// returned_digest)` comparison against whatever parent-committed hash +/// its envelope carries. +pub(crate) fn recompute_axis_binding_digest( + element_value_bytes: &[u8], + axis: IndexAxis, + secondary_root_hash: &[u8; 32], + other_axes_root_hashes: &[(u8, [u8; 32])], + target_is_pcpsit: bool, + err_label: &'static str, +) -> Result { // Bind the proved element's family to the requested axis. // // Without this, the H1-A chain check below passes for a *relabeled* @@ -146,13 +188,14 @@ fn verify_deepest_layer( // digest and fails the chain check below), so the family check is // all that is additionally required. { - let proved_family = grovedb_element::ElementType::from_serialized_value(&cidx_value_bytes) - .map_err(|e| { - Error::CorruptedData(format!( - "{err_label}: cannot determine element type of proved value: {e}" - )) - })? - .base(); + let proved_family = + grovedb_element::ElementType::from_serialized_value(element_value_bytes) + .map_err(|e| { + Error::CorruptedData(format!( + "{err_label}: cannot determine element type of proved value: {e}" + )) + })? + .base(); let expected_family = if target_is_pcpsit { grovedb_element::ElementType::ProvableCountProvableSumIndexedTree } else { @@ -212,18 +255,7 @@ fn verify_deepest_layer( *secondary_root_hash }; - let combined = combine_hash_three(&actual_value_hash, primary_root_hash, &queried_axis_digest) - .value() - .to_owned(); - if combined != cidx_value_hash_recorded { - return Err(Error::CorruptedData(format!( - "{err_label}: deepest-layer chain mismatch — parent recorded value_hash {} but \ - combine_hash_three(H(value), primary_root, axis_digest) is {}", - hex::encode(cidx_value_hash_recorded), - hex::encode(combined) - ))); - } - Ok(layer_root) + Ok(queried_axis_digest) } /// Verify a single-key Merk proof: returns @@ -729,7 +761,7 @@ fn verify_indexed_axis_aggregate_inner( }) } -fn decode_axis_entries_from_result_set( +pub(crate) fn decode_axis_entries_from_result_set( axis: IndexAxis, result_set: &[grovedb_merk::proofs::query::ProvedKeyOptionalValue], ) -> Result { @@ -788,7 +820,7 @@ fn decode_axis_entries_from_result_set( } } -fn decode_axis_entries_from_count_offset_items( +pub(crate) fn decode_axis_entries_from_count_offset_items( axis: IndexAxis, items: &[grovedb_merk::proofs::query::CountOffsetReturnedItem], ) -> Result { @@ -844,7 +876,7 @@ fn decode_axis_entries_from_count_offset_items( } } -fn count_aggregate_inner_range(lo: i128, hi: i128) -> MerkQueryItemForRange { +pub(crate) fn count_aggregate_inner_range(lo: i128, hi: i128) -> MerkQueryItemForRange { // Out-of-domain (hi < 0 OR lo > u64::MAX): emit the canonical // empty-range shape (`u64::MAX..u64::MAX`) the prover commits via // `build_empty_count_aggregate_proof`. This must match exactly or @@ -872,7 +904,7 @@ fn count_aggregate_inner_range(lo: i128, hi: i128) -> MerkQueryItemForRange { } } -fn sum_aggregate_inner_range(lo: i128, hi: i128) -> MerkQueryItemForRange { +pub(crate) fn sum_aggregate_inner_range(lo: i128, hi: i128) -> MerkQueryItemForRange { // Out-of-domain (hi < i64::MIN OR lo > i64::MAX): emit the canonical // empty-range shape the prover commits via // `build_empty_sum_aggregate_proof` (`encode(i64::MAX)..encode(i64::MAX)`). diff --git a/grovedb/src/operations/proof/mod.rs b/grovedb/src/operations/proof/mod.rs index 65e708338..4722e7ad8 100644 --- a/grovedb/src/operations/proof/mod.rs +++ b/grovedb/src/operations/proof/mod.rs @@ -24,6 +24,13 @@ pub mod indexed_axis; /// Utility functions for proof display and conversion. pub mod util; mod verify; +/// The unified verify entry point (`verify_path_query`), serving every +/// provable `PathQuery` shape. Verify-reachable for light clients. +#[cfg(any(feature = "minimal", feature = "verify"))] +mod verify_path_query; + +#[cfg(any(feature = "minimal", feature = "verify"))] +pub use verify_path_query::VerifiedPathQuery; use std::{collections::BTreeMap, fmt}; @@ -269,6 +276,92 @@ pub enum ProofBytes { /// only ever emitted for indexed trees, which no released version can /// store. IndexedTreeTerminal(Vec), + /// Axis-ordered descent into an indexed tree: instead of descending + /// the primary (the [`ProofBytes::CountIndexedTree`] shape), the + /// layer carries a proof over the queried per-axis **secondary** — + /// the [`AxisDescentProof`] payload, encoded with the same + /// big-endian canonical config as the envelope itself. + /// + /// Emitted only when the query node governing this layer carries + /// `ReadMode::Axis` (see `PathQuery::axis_read_at_path`); gated on + /// `proof.axis_descent_in_v1_envelope` (GROVE_V4+). The verifier + /// **recomputes** the secondary-root attestation from the payload's + /// secondary proof rather than accepting 32 raw bytes, then + /// performs the same `combine_hash_three` parent binding as the + /// other indexed shapes. + /// + /// Appended after [`ProofBytes::IndexedTreeTerminal`] so every + /// existing variant keeps its discriminant. + IndexedTreeAxisDescent(Vec), +} + +/// Payload of [`ProofBytes::IndexedTreeAxisDescent`]: everything the +/// verifier needs to check an axis-ordered read of one indexed tree, +/// *given* the query (which carries the axis, traversal, direction, and +/// bounds — none of those are echoed here, matching the envelope's +/// query-as-input philosophy). +/// +/// Trust model per field: +/// - `secondary_proof` is verified cryptographically; the queried +/// axis's secondary root hash is **recomputed** from it. +/// - `primary_root_hash` and `other_axes_root_hashes` are +/// prover-supplied but bound: they enter `combine_hash_three(H(value), +/// primary_root, attestation)` (with `attestation` the recomputed +/// secondary root for PCIT/PSIT, or the axes digest over +/// `other_axes_root_hashes` + the recomputed queried-axis root for +/// PCPSIT), which must equal the parent-committed `value_hash` — any +/// forgery fails that comparison. +/// - `rank` is present iff the traversal is `RankOfKey`: the verifier +/// needs the claimed rank to drive the count-offset verification +/// walk, whose counted commitments then attest it (a wrong claim +/// fails verification), and the single yielded entry must be the +/// queried key. +#[derive(Debug, Clone, PartialEq, Encode, Decode)] +pub struct AxisDescentProof { + /// Tag byte of the queried axis; must equal the query's axis. + pub axis_tag: u8, + /// Whether the target element is a PCPSIT (multi-axis TLV) rather + /// than a single-secondary PCIT / PSIT. + pub target_is_pcpsit: bool, + /// PCPSIT only: `(tag, secondary_root_hash)` for every axis the + /// element carries *except* the queried one. Must be empty for + /// PCIT / PSIT. + pub other_axes_root_hashes: Vec<(u8, [u8; 32])>, + /// Root hash of the indexed tree's primary Merk at proof time. + pub primary_root_hash: [u8; 32], + /// `RankOfKey` traversals only: the prover-computed rank. + pub rank: Option, + /// The secondary-Merk proof for the query's traversal: a + /// count-offset paginated proof for `TopK` / `RankOfKey`, a plain + /// Merk range proof for `Bounded`, an aggregate-on-range proof for + /// `RangeAggregate`. + pub secondary_proof: Vec, +} + +impl AxisDescentProof { + /// Encode with the same big-endian config as the surrounding + /// envelope. + pub fn encode_canonical(&self) -> Result, Error> { + let config = bincode::config::standard().with_big_endian(); + bincode::encode_to_vec(self, config) + .map_err(|e| Error::CorruptedData(format!("unable to encode axis descent: {e}"))) + } + + /// Decode with trailing-byte rejection and a payload size cap. + pub fn decode_canonical(bytes: &[u8]) -> Result { + let config = bincode::config::standard() + .with_big_endian() + .with_limit::<{ 16 * 1024 * 1024 }>(); + let (decoded, consumed): (Self, usize) = bincode::decode_from_slice(bytes, config) + .map_err(|e| Error::CorruptedData(format!("unable to decode axis descent: {e}")))?; + if consumed != bytes.len() { + return Err(Error::CorruptedData(format!( + "axis descent payload has {} trailing bytes", + bytes.len() - consumed + ))); + } + Ok(decoded) + } } /// A single layer of a v1 GroveDB proof supporting multiple tree types. @@ -707,6 +800,26 @@ impl fmt::Display for ProofBytes { write!(f, "IndexedTreeTerminal()", bytes.len()) } } + ProofBytes::IndexedTreeAxisDescent(bytes) => { + match AxisDescentProof::decode_canonical(bytes) { + Ok(payload) => write!( + f, + "IndexedTreeAxisDescent(axis_tag={}, pcpsit={}, other_axes={}, \ + primary_root={}, rank={:?}, secondary_proof={} bytes)", + payload.axis_tag, + payload.target_is_pcpsit, + payload.other_axes_root_hashes.len(), + hex::encode(payload.primary_root_hash), + payload.rank, + payload.secondary_proof.len(), + ), + Err(_) => write!( + f, + "IndexedTreeAxisDescent()", + bytes.len() + ), + } + } } } } diff --git a/grovedb/src/operations/proof/verify.rs b/grovedb/src/operations/proof/verify.rs index 5987acf4d..b173bdfab 100644 --- a/grovedb/src/operations/proof/verify.rs +++ b/grovedb/src/operations/proof/verify.rs @@ -21,15 +21,45 @@ use crate::operations::proof::util::{ }; use crate::{ operations::proof::{ + indexed_axis::AxisEntries, util::{ProvedPathKeyOptionalValue, ProvedPathKeyValues}, - GroveDBProof, GroveDBProofV0, GroveDBProofV1, LayerProof, MerkOnlyLayerProof, ProofBytes, - ProveOptions, + AxisDescentProof, GroveDBProof, GroveDBProofV0, GroveDBProofV1, LayerProof, + MerkOnlyLayerProof, ProofBytes, ProveOptions, }, query::{GroveTrunkQueryResult, PathTrunkChunkQuery}, query_result_type::PathKeyOptionalElementTrio, Element, Error, GroveDb, PathQuery, }; +/// One axis-ordered layer verified during a V1 walk: the full path to +/// the indexed tree whose axis was read, plus the traversal's verified +/// answer. Collected into a side channel because axis entries are +/// `(aggregate_value, original_key)` pairs, not elements — they do not +/// belong in the trio result set. +#[derive(Debug)] +pub(crate) struct AxisWalkOutcome { + /// Full path (from the GroveDB root) of the indexed tree. + pub(crate) path: Vec>, + /// The traversal's verified answer. + pub(crate) result: AxisWalkResult, +} + +/// The verified answer of one axis-ordered layer, by traversal family. +#[derive(Debug)] +pub(crate) enum AxisWalkResult { + /// `TopK` / `Bounded`: the entries in walk order. `skipped` is the + /// count-commitment-attested skip for paginated traversals, `None` + /// for bounded ones (which do not skip). + Entries { + entries: AxisEntries, + skipped: Option, + }, + /// `RankOfKey`: the attested 0-based rank of the queried key. + Rank { rank: u64 }, + /// `RangeAggregate`: the attested aggregate over the value range. + Aggregate { value: i128 }, +} + impl GroveDb { /// Verifies a proof against a path query with the given options, returning /// the root hash and deserialized results. @@ -370,6 +400,10 @@ impl GroveDb { let mut result = Vec::new(); let mut limit = query.query.limit; let mut last_tree_feature_type = None; + // This entry point serves key-selection queries only (read-mode + // queries are gated out before reaching it), so axis outcomes + // cannot occur; the collector exists to satisfy the walk. + let mut axis_outcomes = Vec::new(); let root_hash = Self::verify_layer_proof_v1( Self::merk_bytes_of_layer(&proof.root_layer, query)?, &proof.root_layer.lower_layers, @@ -378,6 +412,7 @@ impl GroveDb { &mut limit, &[], &mut result, + &mut axis_outcomes, &mut last_tree_feature_type, &options, 0, @@ -408,6 +443,53 @@ impl GroveDb { Ok((root_hash, last_tree_feature_type, result)) } + /// Run the V1 walk for a read-mode (axis-shaped) query, returning + /// the reconstructed root hash, the trio result set (which for axis + /// shapes carries only absence records and any incidental + /// key-selection rows), and the collected axis outcomes. + /// + /// This is the one V1 entry that does NOT gate read-mode queries + /// out — `verify_path_query` is its only caller and applies the + /// shape grammar (`classify`) plus the envelope gate first. + pub(crate) fn verify_proof_v1_with_axis_outcomes( + proof: &GroveDBProofV1, + query: &PathQuery, + grove_version: &GroveVersion, + ) -> Result< + ( + CryptoHash, + Vec, + Vec, + ), + Error, + > { + let prove_options = ProveOptions::default(); + let options = VerifyOptions { + absence_proofs_for_non_existing_searched_keys: false, + verify_proof_succinctness: true, + include_empty_trees_in_result: false, + }; + let mut result = Vec::new(); + let mut limit = query.query.limit; + let mut last_tree_feature_type = None; + let mut axis_outcomes = Vec::new(); + let root_hash = Self::verify_layer_proof_v1( + Self::merk_bytes_of_layer(&proof.root_layer, query)?, + &proof.root_layer.lower_layers, + &prove_options, + query, + &mut limit, + &[], + &mut result, + &mut axis_outcomes, + &mut last_tree_feature_type, + &options, + 0, + grove_version, + )?; + Ok((root_hash, result, axis_outcomes)) + } + fn verify_proof_v1_raw_internal( proof: &GroveDBProofV1, query: &PathQuery, @@ -419,6 +501,8 @@ impl GroveDb { let mut result = Vec::new(); let mut limit = query.query.limit; let mut last_tree_feature_type = None; + // Key-selection-only entry point; see verify_proof_v1_internal. + let mut axis_outcomes = Vec::new(); let root_hash = Self::verify_layer_proof_v1( Self::merk_bytes_of_layer(&proof.root_layer, query)?, &proof.root_layer.lower_layers, @@ -427,6 +511,7 @@ impl GroveDb { &mut limit, &[], &mut result, + &mut axis_outcomes, &mut last_tree_feature_type, &options, 0, @@ -677,13 +762,291 @@ impl GroveDb { | ProofBytes::DenseTree(_) | ProofBytes::CommitmentTree(_) | ProofBytes::CountIndexedTree(_) - | ProofBytes::IndexedTreeTerminal(_) => Err(Error::InvalidProof( + | ProofBytes::IndexedTreeTerminal(_) + | ProofBytes::IndexedTreeAxisDescent(_) => Err(Error::InvalidProof( query.clone(), "Expected Merk proof at this layer, got non-Merk proof type".to_string(), )), } } + /// Verify one axis-ordered descent layer: the embedded + /// (V1-envelope) counterpart of the standalone indexed-axis + /// envelopes. + /// + /// Trust chain, strictly downward: + /// 1. The secondary proof is verified for the query's traversal, + /// yielding the entries/aggregate AND the secondary's + /// reconstructed root hash — the attestation is **recomputed**, + /// never accepted as raw bytes. + /// 2. The proved element's family is checked against the queried + /// axis, and the third `combine_hash_three` input is derived + /// (recomputed secondary root for PCIT/PSIT; `axes_digest` over + /// the payload's other-axes list plus the recomputed root for + /// PCPSIT). Forged `primary_root_hash` / `other_axes` fail the + /// binding below because they are part of its preimage. + /// 3. `combine_hash_three(H(value), primary_root, digest)` must + /// equal the parent-committed `value_hash` the surrounding walk + /// already verified. + /// + /// On success the traversal's verified answer is pushed into + /// `axis_outcomes` keyed by the indexed tree's full path. + #[allow(clippy::too_many_arguments)] + fn verify_axis_descent_layer( + lower_layer: &LayerProof, + axis_query: &grovedb_merk::proofs::query::AxisQuery, + element_value_bytes: &[u8], + parent_committed_hash: &CryptoHash, + path: &[&[u8]], + axis_outcomes: &mut Vec, + query: &PathQuery, + grove_version: &GroveVersion, + ) -> Result<(), Error> { + use grovedb_merk::proofs::query::{ + verify_aggregate_count_on_range_proof, verify_aggregate_sum_on_range_proof, + verify_count_offset_on_range_proof, AxisTraversal, QueryItem as MerkQueryItemForRange, + }; + + use crate::operations::proof::indexed_axis::verify::{ + count_aggregate_inner_range, decode_axis_entries_from_count_offset_items, + decode_axis_entries_from_result_set, recompute_axis_binding_digest, + sum_aggregate_inner_range, + }; + + // Envelope gate: the axis descent is a V4 acceptance rule. + if grove_version + .grovedb_versions + .operations + .proof + .axis_descent_in_v1_envelope + != 1 + { + return Err(Error::NotSupported( + "axis-ordered descents in the V1 proof envelope are not accepted at this \ + grove version" + .to_string(), + )); + } + + let ProofBytes::IndexedTreeAxisDescent(payload_bytes) = &lower_layer.merk_proof else { + return Err(Error::InvalidProof( + query.clone(), + "the query node at this indexed tree is an axis read; its lower layer must \ + carry ProofBytes::IndexedTreeAxisDescent" + .to_string(), + )); + }; + if !lower_layer.lower_layers.is_empty() { + return Err(Error::InvalidProof( + query.clone(), + "an axis descent is terminal and must not carry further lower layers".to_string(), + )); + } + let payload = AxisDescentProof::decode_canonical(payload_bytes)?; + let axis = axis_query.axis; + if payload.axis_tag != axis.tag() { + return Err(Error::InvalidProof( + query.clone(), + format!( + "axis descent payload claims axis tag {} but the query reads axis {:?}", + payload.axis_tag, axis + ), + )); + } + if payload.rank.is_some() + && !matches!(axis_query.traversal, AxisTraversal::RankOfKey { .. }) + { + return Err(Error::InvalidProof( + query.clone(), + "axis descent payload carries a rank but the traversal is not RankOfKey" + .to_string(), + )); + } + + // 1. Verify the secondary proof for the query's traversal, + // recomputing the secondary root hash. + let (secondary_root_hash, walk_result) = match &axis_query.traversal { + AxisTraversal::TopK { k, offset } => { + let inner_range = MerkQueryItemForRange::RangeFull(std::ops::RangeFull); + let res = verify_count_offset_on_range_proof( + &payload.secondary_proof, + &inner_range, + *offset, + Some(*k as u64), + !axis_query.descending, + ) + .unwrap() + .map_err(|e| { + Error::InvalidProof( + query.clone(), + format!("axis descent: secondary count-offset proof failed: {e}"), + ) + })?; + let entries = + decode_axis_entries_from_count_offset_items(axis, &res.returned_items)?; + ( + res.root_hash, + AxisWalkResult::Entries { + entries, + skipped: Some(res.skipped), + }, + ) + } + AxisTraversal::RankOfKey { key } => { + let Some(rank) = payload.rank else { + return Err(Error::InvalidProof( + query.clone(), + "axis descent for a rank-of-key traversal must carry the rank".to_string(), + )); + }; + let inner_range = MerkQueryItemForRange::RangeFull(std::ops::RangeFull); + let res = verify_count_offset_on_range_proof( + &payload.secondary_proof, + &inner_range, + rank, + Some(1), + !axis_query.descending, + ) + .unwrap() + .map_err(|e| { + Error::InvalidProof( + query.clone(), + format!("axis descent: rank count-offset proof failed: {e}"), + ) + })?; + // The count commitments attest the skip; the claimed + // rank must be fully realized (not merely "walk ran + // out"), and the single yielded entry must be the + // queried key. + if res.skipped != rank { + return Err(Error::InvalidProof( + query.clone(), + format!( + "axis descent: claimed rank {rank} but the count commitments \ + attest {} skipped entries", + res.skipped + ), + )); + } + let entries = + decode_axis_entries_from_count_offset_items(axis, &res.returned_items)?; + let yielded_key = entries.first_original_key().map(|k| k.to_vec()); + if yielded_key.as_deref() != Some(key.as_slice()) { + return Err(Error::InvalidProof( + query.clone(), + format!( + "axis descent: the entry at rank {rank} is {:?}, not the queried \ + key {}", + yielded_key.map(hex::encode), + hex::encode(key), + ), + )); + } + (res.root_hash, AxisWalkResult::Rank { rank }) + } + AxisTraversal::Bounded { limit, .. } => { + let secondary_query = + crate::query::axis_lowering::axis_bounded_merk_query(axis_query)?; + let left_to_right = secondary_query.left_to_right; + let (root, res) = secondary_query + .execute_proof(&payload.secondary_proof, Some(*limit), left_to_right, 0) + .unwrap() + .map_err(|e| { + Error::InvalidProof( + query.clone(), + format!("axis descent: secondary range proof failed: {e}"), + ) + })?; + let entries = decode_axis_entries_from_result_set(axis, &res.result_set)?; + ( + root, + AxisWalkResult::Entries { + entries, + skipped: None, + }, + ) + } + AxisTraversal::RangeAggregate { lo, hi } => match axis { + grovedb_merk::proofs::query::IndexAxis::Count => { + let inner_range = count_aggregate_inner_range(*lo, *hi); + let (root, count) = verify_aggregate_count_on_range_proof( + &payload.secondary_proof, + &inner_range, + ) + .unwrap() + .map_err(|e| { + Error::InvalidProof( + query.clone(), + format!("axis descent: aggregate-count proof failed: {e}"), + ) + })?; + ( + root, + AxisWalkResult::Aggregate { + value: count as i128, + }, + ) + } + grovedb_merk::proofs::query::IndexAxis::Sum => { + let inner_range = sum_aggregate_inner_range(*lo, *hi); + let (root, sum) = + verify_aggregate_sum_on_range_proof(&payload.secondary_proof, &inner_range) + .unwrap() + .map_err(|e| { + Error::InvalidProof( + query.clone(), + format!("axis descent: aggregate-sum proof failed: {e}"), + ) + })?; + (root, AxisWalkResult::Aggregate { value: sum as i128 }) + } + grovedb_merk::proofs::query::IndexAxis::Avg => { + return Err(Error::InvalidProof( + query.clone(), + "axis descent: range aggregates are not defined for the Avg axis" + .to_string(), + )); + } + }, + }; + + // 2. Family check + third-input digest, with the RECOMPUTED + // secondary root. + let digest = recompute_axis_binding_digest( + element_value_bytes, + axis, + &secondary_root_hash, + &payload.other_axes_root_hashes, + payload.target_is_pcpsit, + "axis descent", + )?; + + // 3. Parent binding. + let combined = combine_hash_three( + value_hash(element_value_bytes).value(), + &payload.primary_root_hash, + &digest, + ) + .value() + .to_owned(); + if parent_committed_hash != &combined { + return Err(Error::InvalidProof( + query.clone(), + format!( + "axis descent binding mismatch: parent committed {}, recomputed {}", + hex::encode(parent_committed_hash), + hex::encode(combined), + ), + )); + } + + axis_outcomes.push(AxisWalkOutcome { + path: path.iter().map(|segment| segment.to_vec()).collect(), + result: walk_result, + }); + Ok(()) + } + /// Derive a Merk layer's root hash without reporting any of its rows. /// /// Used when a subset verification stops at a tree ELEMENT that the proof @@ -732,6 +1095,7 @@ impl GroveDb { limit_left: &mut Option, current_path: &[&[u8]], result: &mut Vec, + axis_outcomes: &mut Vec, last_parent_tree_type: &mut Option, options: &VerifyOptions, current_depth: usize, @@ -850,6 +1214,25 @@ impl GroveDb { | Element::ProvableCountProvableSumIndexedTree(..) => { path.push(key); *last_parent_tree_type = element.tree_feature_type(); + // Axis-ordered descent: the query node + // governing this indexed tree carries + // ReadMode::Axis, so the lower layer must be + // an axis-descent payload — a proof over the + // queried per-axis secondary — never a + // primary descent or a terminal attestation. + if let Some(axis_query) = query.axis_read_at_path(&path) { + Self::verify_axis_descent_layer( + lower_layer, + axis_query, + value_bytes, + hash, + &path, + axis_outcomes, + query, + grove_version, + )?; + continue; + } if query.query_items_at_path(&path, grove_version)?.is_none() { // The indexed tree is itself a result and // nothing is queried below it. The element @@ -1007,6 +1390,7 @@ impl GroveDb { limit_left, &path, result, + axis_outcomes, last_parent_tree_type, options, current_depth + 1, @@ -1143,6 +1527,7 @@ impl GroveDb { limit_left, &path, result, + axis_outcomes, last_parent_tree_type, options, current_depth + 1, @@ -1199,7 +1584,8 @@ impl GroveDb { )? } ProofBytes::CountIndexedTree(_) - | ProofBytes::IndexedTreeTerminal(_) => { + | ProofBytes::IndexedTreeTerminal(_) + | ProofBytes::IndexedTreeAxisDescent(_) => { // Indexed-tree envelopes are // dispatched in the dedicated // arm above; reaching this point diff --git a/grovedb/src/operations/proof/verify_path_query.rs b/grovedb/src/operations/proof/verify_path_query.rs new file mode 100644 index 000000000..6ed62388e --- /dev/null +++ b/grovedb/src/operations/proof/verify_path_query.rs @@ -0,0 +1,423 @@ +//! The unified verify entry point: one function that verifies a proof +//! for every provable [`PathQuery`] shape. +//! +//! [`GroveDb::verify_path_query`] classifies the query once +//! ([`PathQuery::classify`]) and routes it to the verifier that serves +//! that shape, returning a [`VerifiedPathQuery`] whose variant mirrors +//! the shape — the proved counterpart of `run_path_query`. +//! +//! Axis shapes verify **GroveDBProof V1** envelopes carrying +//! [`ProofBytes::IndexedTreeAxisDescent`](crate::operations::proof::ProofBytes) +//! layers, gated on `proof.axis_descent_in_v1_envelope` (GROVE_V4+). +//! Key-selection and aggregate shapes route to the existing verifiers +//! unchanged. Sum-budget shapes have no proof form yet. + +use grovedb_merk::{proofs::query::AxisTraversal, CryptoHash}; +use grovedb_version::version::GroveVersion; + +use crate::{ + operations::proof::{ + decode_grovedb_proof_canonical, + indexed_axis::AxisEntries, + verify::{AxisWalkOutcome, AxisWalkResult}, + GroveDBProof, + }, + query::{AggregateKind, PathQueryShape}, + query_result_type::PathKeyOptionalElementTrio, + Error, GroveDb, PathQuery, +}; + +/// The verified answer to any provable [`PathQuery`] shape — one +/// variant per shape family. Every variant carries the reconstructed +/// GroveDB root hash; compare it against the root you trust — +/// verification alone proves internal consistency, not that the proof +/// is about the state you meant. +#[derive(Debug)] +pub enum VerifiedPathQuery { + /// Key-selection shapes: the regular trio result set. + Elements { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// The proved `(path, key, element)` rows. + elements: Vec, + }, + /// Leaf `AggregateCountOnRange`. + AggregateCount { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// The proved count. + count: u64, + }, + /// Leaf `AggregateSumOnRange`. + AggregateSum { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// The proved signed sum. + sum: i64, + }, + /// Leaf `AggregateCountAndSumOnRange`. + AggregateCountAndSum { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// The proved count. + count: u64, + /// The proved signed sum. + sum: i64, + }, + /// Carrier aggregates: one value per matched outer key. + AggregatePerKey { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// Per outer key: the proved `(count, sum)` — count-only + /// carriers report `sum = None`, sum-only carriers report + /// `count = None`. + per_key: Vec<(Vec, Option, Option)>, + }, + /// Single-path axis read (`TopK` / `Bounded`): the proved entries. + AxisEntries { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// The proved entries, in walk order. + entries: AxisEntries, + /// Count-commitment-attested skip for paginated traversals; + /// `None` for bounded ones. + skipped: Option, + }, + /// Branched axis read: per branch key, in query order, the proved + /// entries — or `None` for a branch key whose absence the + /// branching-level Merk proof authenticates. + BranchedAxisEntries { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// `(branch_key, entries)` per branch, `None` = proven absent. + branches: Vec<(Vec, Option)>, + }, + /// `RankOfKey`: the attested 0-based rank of the queried key in the + /// directional walk. + AxisRank { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// The attested rank. + rank: u64, + }, + /// `RangeAggregate`: the attested aggregate over the value range. + AxisAggregate { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// The attested aggregate: a count (`>= 0`) for the count axis, + /// a signed sum for the sum axis. + value: i128, + }, +} + +impl VerifiedPathQuery { + /// The reconstructed GroveDB root hash, whichever shape this is. + pub fn root_hash(&self) -> &CryptoHash { + match self { + VerifiedPathQuery::Elements { root_hash, .. } + | VerifiedPathQuery::AggregateCount { root_hash, .. } + | VerifiedPathQuery::AggregateSum { root_hash, .. } + | VerifiedPathQuery::AggregateCountAndSum { root_hash, .. } + | VerifiedPathQuery::AggregatePerKey { root_hash, .. } + | VerifiedPathQuery::AxisEntries { root_hash, .. } + | VerifiedPathQuery::BranchedAxisEntries { root_hash, .. } + | VerifiedPathQuery::AxisRank { root_hash, .. } + | VerifiedPathQuery::AxisAggregate { root_hash, .. } => root_hash, + } + } +} + +impl GroveDb { + /// Verify `proof` against `path_query`, whatever shape the query + /// is, returning the shape's typed verified answer. The unified + /// counterpart of the per-shape `verify_*` entry points and the + /// proved counterpart of `run_path_query`. + pub fn verify_path_query( + proof: &[u8], + path_query: &PathQuery, + grove_version: &GroveVersion, + ) -> Result { + match path_query.classify()? { + PathQueryShape::KeySelection | PathQueryShape::CountOffsetPaginated { .. } => { + let (root_hash, elements) = Self::verify_query(proof, path_query, grove_version)?; + Ok(VerifiedPathQuery::Elements { + root_hash, + elements, + }) + } + PathQueryShape::AggregateLeaf { kind, .. } => match kind { + AggregateKind::Count => { + let (root_hash, count) = + Self::verify_aggregate_count_query(proof, path_query, grove_version)?; + Ok(VerifiedPathQuery::AggregateCount { root_hash, count }) + } + AggregateKind::Sum => { + let (root_hash, sum) = + Self::verify_aggregate_sum_query(proof, path_query, grove_version)?; + Ok(VerifiedPathQuery::AggregateSum { root_hash, sum }) + } + AggregateKind::CountAndSum => { + let (root_hash, count, sum) = Self::verify_aggregate_count_and_sum_query( + proof, + path_query, + grove_version, + )?; + Ok(VerifiedPathQuery::AggregateCountAndSum { + root_hash, + count, + sum, + }) + } + }, + PathQueryShape::AggregateCarrier { kind, .. } => match kind { + AggregateKind::Count => { + let (root_hash, per_key) = Self::verify_aggregate_count_query_per_key( + proof, + path_query, + grove_version, + )?; + Ok(VerifiedPathQuery::AggregatePerKey { + root_hash, + per_key: per_key + .into_iter() + .map(|(key, count)| (key, Some(count), None)) + .collect(), + }) + } + AggregateKind::Sum => { + let (root_hash, per_key) = + Self::verify_aggregate_sum_query_per_key(proof, path_query, grove_version)?; + Ok(VerifiedPathQuery::AggregatePerKey { + root_hash, + per_key: per_key + .into_iter() + .map(|(key, sum)| (key, None, Some(sum))) + .collect(), + }) + } + AggregateKind::CountAndSum => { + let (root_hash, per_key) = Self::verify_aggregate_count_and_sum_query_per_key( + proof, + path_query, + grove_version, + )?; + Ok(VerifiedPathQuery::AggregatePerKey { + root_hash, + per_key: per_key + .into_iter() + .map(|(key, count, sum)| (key, Some(count), Some(sum))) + .collect(), + }) + } + }, + PathQueryShape::AxisRead { axis } => { + let (root_hash, _, outcomes) = + Self::verify_axis_shape_walk(proof, path_query, grove_version)?; + let [outcome]: [AxisWalkOutcome; 1] = + outcomes.try_into().map_err(|outcomes: Vec<_>| { + Error::InvalidProof( + path_query.clone(), + format!( + "a single-path axis read must verify exactly one axis layer, \ + got {}", + outcomes.len() + ), + ) + })?; + if outcome.path != path_query.path { + return Err(Error::InvalidProof( + path_query.clone(), + "the verified axis layer is not at the queried path".to_string(), + )); + } + Self::outcome_into_verified(root_hash, outcome.result, &axis.traversal, path_query) + } + PathQueryShape::BranchedAxisRead { + branch_items, + suffix, + axis, + } => { + let (root_hash, trios, outcomes) = + Self::verify_axis_shape_walk(proof, path_query, grove_version)?; + + // Index outcomes by their branch key (the segment right + // after the branching prefix). + let prefix_len = path_query.path.len(); + let mut by_branch_key: std::collections::BTreeMap, AxisWalkResult> = + std::collections::BTreeMap::new(); + for outcome in outcomes { + let expected_len = prefix_len + 1 + suffix.len(); + if outcome.path.len() != expected_len + || outcome.path[..prefix_len] + .iter() + .zip(&path_query.path) + .any(|(a, b)| a != b) + || outcome.path[prefix_len + 1..] + .iter() + .zip(suffix) + .any(|(a, b)| a != b) + { + return Err(Error::InvalidProof( + path_query.clone(), + "a verified axis layer sits outside the branched query's \ + prefix/branch/suffix structure" + .to_string(), + )); + } + let branch_key = outcome.path[prefix_len].clone(); + if by_branch_key.insert(branch_key, outcome.result).is_some() { + return Err(Error::InvalidProof( + path_query.clone(), + "duplicate axis layers for one branch key".to_string(), + )); + } + } + + // Present-element trios anywhere under a branch key that + // produced no outcome would mean the prover proved the + // branch present but omitted its axis layer — hiding + // entries behind a fake absence. Reject. + let mut branches = Vec::with_capacity(branch_items.len()); + for item in branch_items { + let grovedb_merk::proofs::query::query_item::QueryItem::Key(branch_key) = item + else { + return Err(Error::CorruptedCodeExecution( + "branched axis read classified with a non-Key branch item", + )); + }; + match by_branch_key.remove(branch_key) { + Some(AxisWalkResult::Entries { entries, .. }) => { + branches.push((branch_key.clone(), Some(entries))); + } + Some(_) => { + return Err(Error::InvalidProof( + path_query.clone(), + "branched axis reads verify entry-listing traversals only" + .to_string(), + )); + } + None => { + // No axis layer for this branch: the + // branching-level Merk proof must have + // authenticated the key's ABSENCE — any + // present-element trio for it means a hidden + // branch. + let present = trios.iter().any(|(trio_path, trio_key, element)| { + trio_path == &path_query.path + && trio_key == branch_key + && element.is_some() + }); + if present { + return Err(Error::InvalidProof( + path_query.clone(), + format!( + "branch key {} is proven present but its axis layer \ + is missing from the proof", + hex::encode(branch_key), + ), + )); + } + branches.push((branch_key.clone(), None)); + } + } + } + if !by_branch_key.is_empty() { + return Err(Error::InvalidProof( + path_query.clone(), + "the proof carries axis layers for branch keys the query does not name" + .to_string(), + )); + } + // The branched grammar admits only entry-listing + // traversals downstream; reject aggregates/ranks here + // for symmetry with the prover. + if matches!( + axis.traversal, + AxisTraversal::RankOfKey { .. } | AxisTraversal::RangeAggregate { .. } + ) { + return Err(Error::NotSupported( + "branched axis reads serve entry-listing traversals (TopK / Bounded) \ + only" + .to_string(), + )); + } + Ok(VerifiedPathQuery::BranchedAxisEntries { + root_hash, + branches, + }) + } + PathQueryShape::SumBudget { .. } => Err(Error::NotSupported( + "sum-budget path queries have no proof form yet; use the trusted read \ + (run_path_query)" + .to_string(), + )), + } + } + + /// Decode + envelope-gate + walk for the axis shapes. + fn verify_axis_shape_walk( + proof: &[u8], + path_query: &PathQuery, + grove_version: &GroveVersion, + ) -> Result< + ( + CryptoHash, + Vec, + Vec, + ), + Error, + > { + if grove_version + .grovedb_versions + .operations + .proof + .axis_descent_in_v1_envelope + != 1 + { + return Err(Error::NotSupported( + "axis-ordered descents in the V1 proof envelope are not accepted at this \ + grove version" + .to_string(), + )); + } + let decoded = decode_grovedb_proof_canonical(proof)?; + match decoded { + GroveDBProof::V0(_) => Err(Error::NotSupported( + "axis-ordered path queries require V1 proof envelopes".to_string(), + )), + GroveDBProof::V1(proof_v1) => { + Self::verify_proof_v1_with_axis_outcomes(&proof_v1, path_query, grove_version) + } + } + } + + /// Map a single-path axis outcome into the public result, checking + /// the outcome family matches the traversal. + fn outcome_into_verified( + root_hash: CryptoHash, + result: AxisWalkResult, + traversal: &AxisTraversal, + path_query: &PathQuery, + ) -> Result { + match (result, traversal) { + ( + AxisWalkResult::Entries { entries, skipped }, + AxisTraversal::TopK { .. } | AxisTraversal::Bounded { .. }, + ) => Ok(VerifiedPathQuery::AxisEntries { + root_hash, + entries, + skipped, + }), + (AxisWalkResult::Rank { rank }, AxisTraversal::RankOfKey { .. }) => { + Ok(VerifiedPathQuery::AxisRank { root_hash, rank }) + } + (AxisWalkResult::Aggregate { value }, AxisTraversal::RangeAggregate { .. }) => { + Ok(VerifiedPathQuery::AxisAggregate { root_hash, value }) + } + _ => Err(Error::InvalidProof( + path_query.clone(), + "the verified axis outcome does not match the query's traversal".to_string(), + )), + } + } +} diff --git a/grovedb/src/query/axis_lowering.rs b/grovedb/src/query/axis_lowering.rs new file mode 100644 index 000000000..3942c1e63 --- /dev/null +++ b/grovedb/src/query/axis_lowering.rs @@ -0,0 +1,117 @@ +//! Lowering an [`AxisQuery`]'s bounded traversal into the secondary's +//! own Merk query. +//! +//! This is prover/verifier agreement material: both sides build the +//! range from the query through *this* function, so they cannot drift +//! on which secondary entries a proof is about. The secondary's keys +//! are `sort_key ‖ original_key`, so an inclusive bound on the +//! aggregate becomes a byte range that brackets every key-suffix at the +//! boundary sort key: inclusive at `lo`, exclusive at the *successor* +//! of `hi`. When `hi` is already the axis maximum there is no +//! successor, and the range is open-ended instead. +//! +//! Compiled under both `minimal` (prover) and `verify` (light-client +//! verifier). + +use grovedb_element::indexed::{ + encode_avg_sort_key, encode_count_sort_key, encode_sum_sort_key, IndexAxis, +}; +use grovedb_merk::proofs::{ + query::{query_item::QueryItem as MerkQueryItem, AxisQuery, AxisTraversal}, + Query as MerkQuery, +}; + +use crate::Error; + +/// Lower a [`AxisTraversal::Bounded`] traversal into the secondary's +/// Merk query. Errors on any other traversal (top-k and rank are served +/// by the count-offset paginated primitives; range aggregates by the +/// aggregate-on-range primitives) and on a query that fails +/// [`AxisQuery::validate`]. +pub(crate) fn axis_bounded_merk_query(axis_query: &AxisQuery) -> Result { + let AxisTraversal::Bounded { lo, hi, .. } = axis_query.traversal else { + return Err(Error::InvalidQuery( + "only a bounded traversal lowers to a secondary Merk query", + )); + }; + axis_query + .validate() + .map_err(crate::query::shape::read_mode_validation_error)?; + + let (lo_bytes, hi_exclusive) = match axis_query.axis { + IndexAxis::Count => { + let lo = lo.clamp(0, u64::MAX as i128) as u64; + let hi = hi.clamp(0, u64::MAX as i128) as u64; + ( + encode_count_sort_key(lo).to_vec(), + hi.checked_add(1) + .map(|next| encode_count_sort_key(next).to_vec()), + ) + } + IndexAxis::Sum => { + let lo = lo.clamp(i64::MIN as i128, i64::MAX as i128) as i64; + let hi = hi.clamp(i64::MIN as i128, i64::MAX as i128) as i64; + ( + encode_sum_sort_key(lo).to_vec(), + hi.checked_add(1) + .map(|next| encode_sum_sort_key(next).to_vec()), + ) + } + IndexAxis::Avg => ( + encode_avg_sort_key(lo).to_vec(), + hi.checked_add(1) + .map(|next| encode_avg_sort_key(next).to_vec()), + ), + }; + + let mut query = MerkQuery::new(); + match hi_exclusive { + Some(hi_bytes) => query.insert_item(MerkQueryItem::Range(lo_bytes..hi_bytes)), + None => query.insert_item(MerkQueryItem::RangeFrom(lo_bytes..)), + } + query.left_to_right = !axis_query.descending; + Ok(query) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn bounded_lowering_brackets_the_boundary_sort_keys() { + let q = axis_bounded_merk_query(&AxisQuery::bounded(IndexAxis::Count, 3, 7, 10, false)) + .expect("bounded lowers"); + assert!(q.left_to_right); + match &q.items[0] { + MerkQueryItem::Range(range) => { + assert_eq!(range.start, encode_count_sort_key(3).to_vec()); + // Exclusive at the successor of hi: covers every + // original-key suffix at hi itself. + assert_eq!(range.end, encode_count_sort_key(8).to_vec()); + } + other => panic!("expected Range, got {other:?}"), + } + } + + #[test] + fn bounded_lowering_at_axis_max_is_open_ended() { + let q = axis_bounded_merk_query(&AxisQuery::bounded( + IndexAxis::Sum, + 0, + i64::MAX as i128, + 1, + true, + )) + .expect("bounded at max lowers"); + assert!(!q.left_to_right); + assert!(matches!(&q.items[0], MerkQueryItem::RangeFrom(_))); + } + + #[test] + fn non_bounded_traversals_do_not_lower() { + assert!(axis_bounded_merk_query(&AxisQuery::top_k(IndexAxis::Count, 1, 0, true)).is_err()); + assert!( + axis_bounded_merk_query(&AxisQuery::range_aggregate(IndexAxis::Sum, 0, 1)).is_err() + ); + } +} diff --git a/grovedb/src/query/mod.rs b/grovedb/src/query/mod.rs index c5cd816aa..ccb044368 100644 --- a/grovedb/src/query/mod.rs +++ b/grovedb/src/query/mod.rs @@ -1,11 +1,12 @@ //! Queries pub mod aggregate_sum_path_query; +pub(crate) mod axis_lowering; mod grove_branch_query_result; mod grove_trunk_query_result; mod path_branch_chunk_query; mod path_trunk_chunk_query; -mod shape; +pub(crate) mod shape; use std::{ borrow::{Cow, Cow::Borrowed}, @@ -1206,6 +1207,89 @@ impl PathQuery { }) } + /// Returns the axis read governing the subtree at `path`, if the + /// query node resolved at exactly that path carries + /// [`ReadMode::Axis`]. `path` is a full path from the GroveDB root + /// (the same convention as [`Self::query_items_at_path`]). + /// + /// This is how the proof walk — prover and verifier alike — learns + /// that a layer is an axis-ordered read of an indexed tree rather + /// than a key-selecting descent into its primary. Both sides + /// resolve from the same query through this one function, so they + /// cannot disagree about which layers are axis reads. + /// + /// Positions *inside* a subquery branch's `subquery_path` resolve + /// to `None` (a read mode lives on a query node, never mid-path), + /// as do paths that diverge from the query entirely. + pub fn axis_read_at_path(&self, path: &[&[u8]]) -> Option<&AxisQuery> { + /// Resolve the query NODE at exactly `path` below `query`, + /// following conditional and default subquery branches the same + /// way `query_items_at_path`'s resolver does — but returning + /// the node itself rather than its per-layer view, and `None` + /// for mid-`subquery_path` positions. + fn resolve_node_at_path<'b>(query: &'b Query, path: &[&[u8]]) -> Option<&'b Query> { + if path.is_empty() { + return Some(query); + } + let key = path[0]; + let rest = &path[1..]; + + if let Some(conditional_branches) = &query.conditional_subquery_branches { + for (query_item, subquery_branch) in conditional_branches { + if query_item.contains(key) { + return resolve_branch_at_path(subquery_branch, rest); + } + } + } + resolve_branch_at_path(&query.default_subquery_branch, rest) + } + + fn resolve_branch_at_path<'b>( + branch: &'b SubqueryBranch, + rest: &[&[u8]], + ) -> Option<&'b Query> { + match &branch.subquery_path { + Some(subquery_path) => { + if rest.len() < subquery_path.len() { + // Mid-subquery_path: no query node here. + return None; + } + if !rest + .iter() + .take(subquery_path.len()) + .zip(subquery_path) + .all(|(a, b)| *a == b.as_slice()) + { + return None; + } + let after = &rest[subquery_path.len()..]; + branch + .subquery + .as_deref() + .and_then(|subquery| resolve_node_at_path(subquery, after)) + } + None => branch + .subquery + .as_deref() + .and_then(|subquery| resolve_node_at_path(subquery, rest)), + } + } + + let self_path_len = self.path.len(); + if path.len() < self_path_len { + // Above the query root: nothing can carry a read mode. + return None; + } + if !self.path.iter().zip(path).all(|(a, b)| a.as_slice() == *b) { + return None; + } + let node = resolve_node_at_path(&self.query.query, &path[self_path_len..])?; + match &node.read_mode { + Some(ReadMode::Axis(axis_query)) => Some(axis_query), + _ => None, + } + } + /// Returns the query items applicable at the given path, if any. pub fn query_items_at_path( &self, diff --git a/grovedb/src/query/shape.rs b/grovedb/src/query/shape.rs index 711ada6d2..86e0ed1a5 100644 --- a/grovedb/src/query/shape.rs +++ b/grovedb/src/query/shape.rs @@ -421,8 +421,9 @@ fn has_conditional_branches(query: &grovedb_merk::proofs::Query) -> bool { /// Projects the vocabulary crate's validation error (always /// `InvalidOperation(&'static str)`) into this crate's `InvalidQuery`, -/// preserving the message. -fn read_mode_validation_error(e: grovedb_query::error::Error) -> Error { +/// preserving the message. Shared with the axis-bounds lowering, which +/// runs the same validation on the prover/verifier side. +pub(crate) fn read_mode_validation_error(e: grovedb_query::error::Error) -> Error { match e { grovedb_query::error::Error::InvalidOperation(msg) => Error::InvalidQuery(msg), _ => Error::InvalidQuery("read-mode validation failed"), diff --git a/grovedb/src/tests/axis_descent_proof_tests.rs b/grovedb/src/tests/axis_descent_proof_tests.rs new file mode 100644 index 000000000..89077ff43 --- /dev/null +++ b/grovedb/src/tests/axis_descent_proof_tests.rs @@ -0,0 +1,623 @@ +//! End-to-end tests for axis-ordered reads embedded in the GroveDBProof +//! V1 envelope (`ProofBytes::IndexedTreeAxisDescent`): round trips for +//! every traversal, cross-checks against the standalone envelopes and +//! the trusted reads, absence-authenticated branched reads, forgery +//! rejections, and the GROVE_V4 gates. + +#[cfg(test)] +mod tests { + use grovedb_merk::proofs::query::{AxisQuery, IndexAxis}; + use grovedb_version::version::{GroveVersion, GROVE_VERSIONS}; + + use crate::{ + operations::proof::{ + indexed_axis::AxisEntries, AxisDescentProof, GroveDBProof, LayerProof, ProofBytes, + VerifiedPathQuery, + }, + tests::{make_test_grovedb, TEST_LEAF}, + Element, Error, GroveDb, PathQuery, + }; + + // ----------------------------------------------------------------- + // Fixtures (same shapes as the standalone-envelope suites) + // ----------------------------------------------------------------- + + const PSIT_ENTRIES: &[(&[u8], i64)] = &[ + (b"alice", 40), + (b"bob", -10), + (b"carol", 25), + (b"dave", 40), + (b"erin", 5), + ]; + + fn build_psit(db: &GroveDb, grove_version: &GroveVersion, entries: &[(&[u8], i64)]) { + db.insert( + [TEST_LEAF].as_ref(), + b"psit", + Element::empty_provable_sum_indexed_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create PSIT"); + for (k, s) in entries { + db.insert_into_provable_sum_indexed_tree( + [TEST_LEAF, b"psit"].as_ref(), + k, + Element::new_sum_item(*s), + None, + grove_version, + ) + .unwrap() + .expect("insert PSIT entry"); + } + } + + fn build_pcpsit(db: &GroveDb, grove_version: &GroveVersion, entries: &[(&[u8], i64)]) { + // All three axes so the queried-axis digest reconstruction + // exercises other_axes_root_hashes. + let axes: Vec<(u8, Option>)> = vec![(0, None), (1, None), (2, None)]; + let elem = + Element::empty_provable_count_provable_sum_indexed_tree(axes).expect("axes canonical"); + db.insert( + [TEST_LEAF].as_ref(), + b"pcpsit", + elem, + None, + None, + grove_version, + ) + .unwrap() + .expect("create PCPSIT"); + for (k, sum) in entries { + db.insert_into_provable_count_provable_sum_indexed_tree( + [TEST_LEAF, b"pcpsit"].as_ref(), + k, + Element::new_item_with_sum_item(b"v".to_vec(), *sum), + None, + grove_version, + ) + .unwrap() + .expect("insert PCPSIT entry"); + } + } + + fn build_branched_psits( + db: &GroveDb, + grove_version: &GroveVersion, + branches: &[(&[u8], &[(&[u8], i64)])], + ) { + for (branch, entries) in branches { + db.insert( + [TEST_LEAF].as_ref(), + branch, + Element::empty_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create branch tree"); + db.insert( + [TEST_LEAF, branch].as_ref(), + b"scores", + Element::empty_provable_sum_indexed_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create branch PSIT"); + for (k, s) in *entries { + db.insert_into_provable_sum_indexed_tree( + [TEST_LEAF, branch, b"scores".as_slice()].as_ref(), + k, + Element::new_sum_item(*s), + None, + grove_version, + ) + .unwrap() + .expect("insert branch PSIT entry"); + } + } + } + + fn psit_path() -> Vec> { + vec![TEST_LEAF.to_vec(), b"psit".to_vec()] + } + + fn root_hash(db: &GroveDb, grove_version: &GroveVersion) -> [u8; 32] { + db.root_hash(None, grove_version).unwrap().expect("root") + } + + fn prove(db: &GroveDb, path_query: &PathQuery, grove_version: &GroveVersion) -> Vec { + db.prove_query(path_query, None, grove_version) + .unwrap() + .expect("prove axis path query") + } + + fn entries_as_sum(entries: &AxisEntries) -> &[(i64, Vec)] { + match entries { + AxisEntries::Sum(entries) => entries, + other => panic!("expected sum entries, got {other:?}"), + } + } + + // ----------------------------------------------------------------- + // Round trips + // ----------------------------------------------------------------- + + #[test] + fn top_k_round_trip_matches_reads_and_standalone_envelope() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + + let path_query = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 3, 0, true); + let proof = prove(&db, &path_query, grove_version); + + let verified = GroveDb::verify_path_query(&proof, &path_query, grove_version) + .expect("embedded top-k proof must verify"); + let VerifiedPathQuery::AxisEntries { + root_hash: verified_root, + entries, + skipped, + } = verified + else { + panic!("expected AxisEntries"); + }; + assert_eq!(verified_root, root_hash(&db, grove_version)); + assert_eq!(skipped, Some(0)); + + // Equal to the trusted read... + let direct = db + .indexed_sum_top_k_paginated( + [TEST_LEAF, b"psit"].as_ref(), + 3, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("direct read"); + assert_eq!(entries_as_sum(&entries), direct.as_slice()); + + // ...and to the standalone envelope over the same state. + let standalone_bytes = db + .prove_indexed_sum_top_k([TEST_LEAF, b"psit"].as_ref(), 3, true, None, grove_version) + .unwrap() + .expect("standalone prove"); + let standalone = + GroveDb::verify_indexed_sum_top_k(&standalone_bytes, &[TEST_LEAF, b"psit"], 3, true) + .expect("standalone verify"); + assert_eq!(standalone.root_hash, verified_root); + assert_eq!( + entries_as_sum(&standalone.entries), + entries_as_sum(&entries) + ); + } + + #[test] + fn paginated_bounded_rank_and_aggregate_round_trips() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + let root = root_hash(&db, grove_version); + + // Paginated top-k: skip 2, take 2, descending. + let pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 2, 2, true); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("paginated verifies") + { + VerifiedPathQuery::AxisEntries { + root_hash, + entries, + skipped, + } => { + assert_eq!(root_hash, root); + assert_eq!(skipped, Some(2)); + let direct = db + .indexed_sum_top_k_paginated( + [TEST_LEAF, b"psit"].as_ref(), + 2, + 2, + true, + None, + grove_version, + ) + .unwrap() + .expect("direct"); + assert_eq!(entries_as_sum(&entries), direct.as_slice()); + } + other => panic!("expected AxisEntries, got {other:?}"), + } + + // Bounded: sums in [0, 40] ascending, capped. + let pq = PathQuery::new_axis_bounded(psit_path(), IndexAxis::Sum, 0, 40, 10, false); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("bounded verifies") + { + VerifiedPathQuery::AxisEntries { + root_hash, + entries, + skipped, + } => { + assert_eq!(root_hash, root); + assert_eq!(skipped, None); + let direct = db + .indexed_sum_range( + [TEST_LEAF, b"psit"].as_ref(), + 0, + 40, + false, + 10, + None, + grove_version, + ) + .unwrap() + .expect("direct"); + assert_eq!(entries_as_sum(&entries), direct.as_slice()); + } + other => panic!("expected AxisEntries, got {other:?}"), + } + + // Rank of key, both directions, cross-checked against the + // standalone rank prover. + for descending in [true, false] { + let pq = PathQuery::new_axis_rank_of_key( + psit_path(), + IndexAxis::Sum, + b"carol".to_vec(), + descending, + ); + let (_, expected_rank) = db + .prove_indexed_axis_rank_of_key( + [TEST_LEAF, b"psit"].as_ref(), + IndexAxis::Sum, + b"carol", + descending, + None, + grove_version, + ) + .unwrap() + .expect("standalone rank"); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("rank verifies") + { + VerifiedPathQuery::AxisRank { root_hash, rank } => { + assert_eq!(root_hash, root); + assert_eq!(rank, expected_rank, "descending={descending}"); + } + other => panic!("expected AxisRank, got {other:?}"), + } + } + + // Range aggregate over the sum axis. + let pq = PathQuery::new_axis_range_aggregate(psit_path(), IndexAxis::Sum, 0, 40); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("aggregate verifies") + { + VerifiedPathQuery::AxisAggregate { root_hash, value } => { + assert_eq!(root_hash, root); + let direct = db + .indexed_sum_range_aggregate( + [TEST_LEAF, b"psit"].as_ref(), + 0, + 40, + None, + grove_version, + ) + .unwrap() + .expect("direct"); + assert_eq!(value, direct as i128); + } + other => panic!("expected AxisAggregate, got {other:?}"), + } + } + + #[test] + fn pcpsit_multi_axis_round_trip_exercises_axes_digest() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pcpsit(&db, grove_version, PSIT_ENTRIES); + let root = root_hash(&db, grove_version); + + // Query the SUM axis of a three-axis PCPSIT: the verifier must + // rebuild the axes digest from the two other axes' carried + // roots plus the RECOMPUTED sum-secondary root. + let path = vec![TEST_LEAF.to_vec(), b"pcpsit".to_vec()]; + let pq = PathQuery::new_axis_top_k(path, IndexAxis::Sum, 2, 0, true); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("PCPSIT axis proof verifies") + { + VerifiedPathQuery::AxisEntries { + root_hash, entries, .. + } => { + assert_eq!(root_hash, root); + let direct = db + .indexed_sum_top_k_paginated( + [TEST_LEAF, b"pcpsit"].as_ref(), + 2, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("direct"); + assert_eq!(entries_as_sum(&entries), direct.as_slice()); + } + other => panic!("expected AxisEntries, got {other:?}"), + } + } + + #[test] + fn branched_round_trip_authenticates_absence() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_psits( + &db, + grove_version, + &[ + (b"alice", &[(b"m1", 10), (b"m2", 30)]), + (b"carol", &[(b"m1", 7)]), + ], + ); + let root = root_hash(&db, grove_version); + + let pq = PathQuery::new_branched_axis( + vec![TEST_LEAF.to_vec()], + vec![b"alice".to_vec(), b"bob".to_vec(), b"carol".to_vec()], + vec![b"scores".to_vec()], + AxisQuery::top_k(IndexAxis::Sum, 2, 0, true), + ); + let proof = prove(&db, &pq, grove_version); + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("branched proof verifies") + { + VerifiedPathQuery::BranchedAxisEntries { + root_hash, + branches, + } => { + assert_eq!(root_hash, root); + assert_eq!(branches.len(), 3); + for (branch_key, entries) in &branches { + match branch_key.as_slice() { + b"bob" => assert!(entries.is_none(), "bob is proven absent"), + present => { + let direct = db + .indexed_sum_top_k_paginated( + [TEST_LEAF, present, b"scores".as_slice()].as_ref(), + 2, + 0, + true, + None, + grove_version, + ) + .unwrap() + .expect("direct"); + assert_eq!( + entries_as_sum(entries.as_ref().expect("present")), + direct.as_slice() + ); + } + } + } + } + other => panic!("expected BranchedAxisEntries, got {other:?}"), + } + } + + // ----------------------------------------------------------------- + // Forgeries + // ----------------------------------------------------------------- + + /// Decode → mutate the terminal axis-descent payload → re-encode. + fn tamper_axis_payload(proof: &[u8], mutate: impl FnOnce(&mut AxisDescentProof)) -> Vec { + let config = bincode::config::standard().with_big_endian(); + let (mut decoded, _): (GroveDBProof, usize) = + bincode::decode_from_slice(proof, config).expect("decode envelope"); + let GroveDBProof::V1(ref mut v1) = decoded else { + panic!("expected V1 envelope"); + }; + fn find_descent(layer: &mut LayerProof) -> Option<&mut LayerProof> { + if matches!(layer.merk_proof, ProofBytes::IndexedTreeAxisDescent(_)) { + return Some(layer); + } + layer.lower_layers.values_mut().find_map(find_descent) + } + let descent = find_descent(&mut v1.root_layer).expect("envelope has an axis descent"); + let ProofBytes::IndexedTreeAxisDescent(bytes) = &descent.merk_proof else { + unreachable!(); + }; + let mut payload = AxisDescentProof::decode_canonical(bytes).expect("decode payload"); + mutate(&mut payload); + descent.merk_proof = + ProofBytes::IndexedTreeAxisDescent(payload.encode_canonical().expect("re-encode")); + bincode::encode_to_vec(&decoded, config).expect("re-encode envelope") + } + + #[test] + fn forged_payload_fields_are_rejected() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + let pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 3, 0, true); + let proof = prove(&db, &pq, grove_version); + + // Sanity: untampered verifies. + GroveDb::verify_path_query(&proof, &pq, grove_version).expect("untampered verifies"); + + // Forged primary root: part of the combine_hash_three preimage. + let tampered = tamper_axis_payload(&proof, |payload| { + payload.primary_root_hash[0] ^= 0xff; + }); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("forged primary root must fail the parent binding"); + + // Relabeled axis tag: must not survive. + let tampered = tamper_axis_payload(&proof, |payload| { + payload.axis_tag = IndexAxis::Count.tag(); + }); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("relabeled axis tag must be rejected"); + + // Tampered secondary proof bytes: the recomputed secondary root + // changes, so the binding fails even though the bytes decode. + let tampered = tamper_axis_payload(&proof, |payload| { + let len = payload.secondary_proof.len(); + payload.secondary_proof[len / 2] ^= 0x01; + }); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("tampered secondary proof must be rejected"); + + // Smuggled other-axes list on a single-secondary target. + let tampered = tamper_axis_payload(&proof, |payload| { + payload.other_axes_root_hashes.push((0, [7u8; 32])); + }); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("other-axes on a PCIT/PSIT target must be rejected"); + } + + #[test] + fn lying_about_the_rank_is_rejected() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + let pq = + PathQuery::new_axis_rank_of_key(psit_path(), IndexAxis::Sum, b"carol".to_vec(), true); + let proof = prove(&db, &pq, grove_version); + GroveDb::verify_path_query(&proof, &pq, grove_version).expect("honest rank verifies"); + + // Claiming a different rank: the count commitments in the + // carried secondary proof attest the true skip, so a lying echo + // cannot verify. + let tampered = tamper_axis_payload(&proof, |payload| { + payload.rank = Some(payload.rank.expect("rank present") + 1); + }); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("a lying rank echo must be rejected"); + } + + #[test] + fn hiding_a_present_branch_is_rejected() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_psits( + &db, + grove_version, + &[(b"alice", &[(b"m1", 10)]), (b"carol", &[(b"m1", 7)])], + ); + let pq = PathQuery::new_branched_axis( + vec![TEST_LEAF.to_vec()], + vec![b"alice".to_vec(), b"carol".to_vec()], + vec![b"scores".to_vec()], + AxisQuery::top_k(IndexAxis::Sum, 1, 0, true), + ); + let proof = prove(&db, &pq, grove_version); + GroveDb::verify_path_query(&proof, &pq, grove_version).expect("honest branched verifies"); + + // Strip carol's whole branch descent: the branching layer still + // proves carol PRESENT, so the verifier must reject rather than + // reporting her branch as absent. + let config = bincode::config::standard().with_big_endian(); + let (mut decoded, _): (GroveDBProof, usize) = + bincode::decode_from_slice(&proof, config).expect("decode envelope"); + let GroveDBProof::V1(ref mut v1) = decoded else { + panic!("expected V1 envelope"); + }; + fn strip_key(layer: &mut LayerProof, key: &[u8]) -> bool { + if layer.lower_layers.remove(key).is_some() { + return true; + } + layer + .lower_layers + .values_mut() + .any(|lower| strip_key(lower, key)) + } + assert!( + strip_key(&mut v1.root_layer, b"carol".as_slice()), + "fixture must contain carol's branch layer" + ); + let tampered = bincode::encode_to_vec(&decoded, config).expect("re-encode"); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("hiding a present branch must be rejected"); + } + + // ----------------------------------------------------------------- + // Gates + // ----------------------------------------------------------------- + + #[test] + fn axis_descents_are_gated_to_grove_v4_on_both_sides() { + let v3 = &GROVE_VERSIONS[2]; + assert_eq!(v3.protocol_version, 3); + let v4 = GroveVersion::latest(); + + let db = make_test_grovedb(v4); + build_psit(&db, v4, PSIT_ENTRIES); + let pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 2, 0, true); + + // V3 prover refuses. + match db.prove_query(&pq, None, v3).unwrap() { + Err(Error::NotSupported(_)) => {} + other => panic!("V3 prover must refuse axis shapes, got {other:?}"), + } + + // V3 verifier rejects a genuine V4 proof. + let proof = prove(&db, &pq, v4); + match GroveDb::verify_path_query(&proof, &pq, v3) { + Err(Error::NotSupported(_)) => {} + other => panic!("V3 verifier must reject axis shapes, got {other:?}"), + } + + // A V0 envelope (grove v1 prover, plain query) fed to an + // axis-shaped verification is rejected as the wrong envelope. + let v1 = &GROVE_VERSIONS[0]; + let plain = PathQuery::new_single_key(vec![TEST_LEAF.to_vec()], b"psit".to_vec()); + let v0_proof = db + .prove_query(&plain, None, v1) + .unwrap() + .expect("V0 proof for a plain query"); + match GroveDb::verify_path_query(&v0_proof, &pq, v4) { + Err(Error::NotSupported(_)) | Err(Error::InvalidProof(..)) => {} + other => panic!("V0 envelope + axis query must be rejected, got {other:?}"), + } + } + + #[test] + fn verify_path_query_serves_key_selection_too() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + db.insert( + [TEST_LEAF].as_ref(), + b"item", + Element::new_item(b"v".to_vec()), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert item"); + let pq = PathQuery::new_single_key(vec![TEST_LEAF.to_vec()], b"item".to_vec()); + let proof = prove(&db, &pq, grove_version); + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("key selection verifies through the unified entry") + { + VerifiedPathQuery::Elements { + root_hash, + elements, + } => { + assert_eq!(root_hash, root_hash_of(&db, grove_version)); + assert_eq!(elements.len(), 1); + } + other => panic!("expected Elements, got {other:?}"), + } + } + + fn root_hash_of(db: &GroveDb, grove_version: &GroveVersion) -> [u8; 32] { + db.root_hash(None, grove_version).unwrap().expect("root") + } +} diff --git a/grovedb/src/tests/mod.rs b/grovedb/src/tests/mod.rs index 99271cf18..0333cfbf7 100644 --- a/grovedb/src/tests/mod.rs +++ b/grovedb/src/tests/mod.rs @@ -36,6 +36,7 @@ mod coverage_round7_tests; // and `provable_count_provable_sum_indexed_tree_tests`; the generic-write // rejection cases it uniquely held are ported to // `generic_writes_against_pcit_primary_are_rejected`. +mod axis_descent_proof_tests; mod count_offset_paginated_tests; mod count_sum_tree_tests; mod count_tree_tests; diff --git a/grovedb/src/tests/proof_depth_limit_tests.rs b/grovedb/src/tests/proof_depth_limit_tests.rs index 24ffc6731..9d81b1a77 100644 --- a/grovedb/src/tests/proof_depth_limit_tests.rs +++ b/grovedb/src/tests/proof_depth_limit_tests.rs @@ -319,6 +319,7 @@ mod tests { let mut limit: Option = Some(100); let mut last_tree_type = None; let mut result: Vec = Vec::new(); + let mut axis_outcomes = Vec::new(); let err = GroveDb::verify_layer_proof_v1( match &dummy_proof.merk_proof { @@ -331,6 +332,7 @@ mod tests { &mut limit, &[], &mut result, + &mut axis_outcomes, &mut last_tree_type, &verify_options, MAX_PROOF_DEPTH + 1, @@ -715,6 +717,7 @@ mod tests { let mut limit: Option = Some(100); let mut last_tree_type = None; let mut result: Vec = Vec::new(); + let mut axis_outcomes = Vec::new(); let err = GroveDb::verify_layer_proof_v1( match &dummy_proof.merk_proof { @@ -727,6 +730,7 @@ mod tests { &mut limit, &[b"deep"], &mut result, + &mut axis_outcomes, &mut last_tree_type, &verify_options, MAX_PROOF_DEPTH, diff --git a/grovedb/src/tests/read_mode_gate_tests.rs b/grovedb/src/tests/read_mode_gate_tests.rs index 98a4a6d9c..dddc0eb85 100644 --- a/grovedb/src/tests/read_mode_gate_tests.rs +++ b/grovedb/src/tests/read_mode_gate_tests.rs @@ -76,15 +76,26 @@ fn query_raw_rejects_read_mode_queries() { } #[test] -fn prove_query_rejects_read_mode_queries() { - let grove_version = GroveVersion::latest(); +fn prove_query_gates_read_mode_queries() { let db = make_empty_grovedb(); - for path_query in all_read_mode_queries() { + + // Axis shapes are served from GROVE_V4 (round-trip coverage lives + // in axis_descent_proof_tests); below V4 the prover refuses them. + let v3 = &grovedb_version::version::GROVE_VERSIONS[2]; + assert_eq!(v3.protocol_version, 3); + for path_query in [axis_path_query(), branched_axis_path_query()] { assert_not_supported( - db.prove_query(&path_query, None, grove_version).unwrap(), - "prove_query", + db.prove_query(&path_query, None, v3).unwrap(), + "prove_query (axis, V3)", ); } + + // Sum-budget shapes have no proof form at any version yet. + assert_not_supported( + db.prove_query(&sum_budget_path_query(), None, GroveVersion::latest()) + .unwrap(), + "prove_query (sum budget)", + ); } #[test] From f680b088399df304955182cacc5f8c310eb11359 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 08:10:08 +0700 Subject: [PATCH 2/4] fix: close the branched absence forgery and the empty-secondary gap (security audit) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three findings from the adversarial audit of the axis-descent integration, all fixed with regression tests: 1. Branched absence forgery (Medium). The axis-read check lived inside the lower-layer lookup, so a prover could STRIP an axis-descent layer whose indexed tree exists but is empty — is_non_empty_tree() is false for it, so no guard fired — and the verifier endorsed a false 'proven absent' slot under the genuine root hash. The check is now hoisted above the lookup: at an axis-read position the layer MUST exist (a missing one is a hard InvalidProof), and an existing empty indexed tree now reports Some(empty entries), matching the honest prover and the trusted read. The branched absence guard in verify_path_query also widens to reject any present trio under the branch subtree, and the trusted branched read resolves the full suffix chain so read and proof agree on None for every absence level. 2. Bounded traversal vs empty secondary (Medium). Merk::prove refuses empty trees, so a Bounded axis proof over a freshly created indexed tree hard-errored while every other traversal — and the trusted read — handled it. Both sides now use the same empty convention as the count-offset and aggregate-on-range shapes: empty proof bytes resolve to a NULL_HASH secondary root, which the parent binding only accepts when the element genuinely commits an empty secondary. 3. Duplicate branch keys (Low). classify() now rejects a branched axis read naming the same branch key twice — a valid proof could otherwise yield contradictory (Some, None) rows for one key. Also documents why the Bounded secondary executes with the lenient proof version (only keys are consumed, and they are bound into the recomputed root); the audit confirmed this is not exploitable today. Co-Authored-By: Claude Fable 5 --- grovedb/src/operations/get/run_path_query.rs | 51 +++--- .../operations/proof/indexed_axis/envelope.rs | 9 + .../operations/proof/indexed_axis/generate.rs | 39 +++-- grovedb/src/operations/proof/verify.rs | 134 ++++++++++----- .../src/operations/proof/verify_path_query.rs | 41 ++--- grovedb/src/query/mod.rs | 2 +- grovedb/src/query/shape.rs | 16 ++ grovedb/src/tests/axis_descent_proof_tests.rs | 160 ++++++++++++++++++ 8 files changed, 358 insertions(+), 94 deletions(-) diff --git a/grovedb/src/operations/get/run_path_query.rs b/grovedb/src/operations/get/run_path_query.rs index fd898d24c..c87d2816c 100644 --- a/grovedb/src/operations/get/run_path_query.rs +++ b/grovedb/src/operations/get/run_path_query.rs @@ -240,28 +240,41 @@ impl GroveDb { )) .wrap_with_cost(cost); }; - // Mirror the branched proof's absence slots: a branch - // key missing at the branching level yields None - // rather than an error, so partially-populated - // branch sets read the same way they prove. - let present = cost_return_on_error!( - &mut cost, - self.get_raw_optional( - SubtreePath::from(prefix_refs.as_slice()), - branch_key, - transaction, - grove_version, - ) - ); - if present.is_none() { + // Mirror the branched proof's absence slots: a + // branch key — or any suffix segment under it — + // missing yields None rather than an error, so + // partially-populated branch sets read exactly the + // way they prove (the proof authenticates the + // absence at whichever level the chain breaks). + // + // Seeded from the hoisted `prefix_refs`: the prefix + // is built once, and only the per-branch descent + // pushes onto its own copy. + let mut resolved: Vec<&[u8]> = prefix_refs.clone(); + let mut chain_broken = false; + for segment in std::iter::once(branch_key.as_slice()) + .chain(suffix.iter().map(|segment| segment.as_slice())) + { + let present = cost_return_on_error!( + &mut cost, + self.get_raw_optional( + SubtreePath::from(resolved.as_slice()), + segment, + transaction, + grove_version, + ) + ); + if present.is_none() { + chain_broken = true; + break; + } + resolved.push(segment); + } + if chain_broken { branches.push((branch_key.clone(), None)); continue; } - let mut full_path: Vec<&[u8]> = - Vec::with_capacity(path_query.path.len() + 1 + suffix.len()); - full_path.extend(path_query.path.iter().map(|segment| segment.as_slice())); - full_path.push(branch_key.as_slice()); - full_path.extend(suffix.iter().map(|segment| segment.as_slice())); + let full_path = resolved; let run = cost_return_on_error!( &mut cost, self.run_axis_read(full_path.as_slice(), axis, transaction, grove_version) diff --git a/grovedb/src/operations/proof/indexed_axis/envelope.rs b/grovedb/src/operations/proof/indexed_axis/envelope.rs index 051024314..1205e85c0 100644 --- a/grovedb/src/operations/proof/indexed_axis/envelope.rs +++ b/grovedb/src/operations/proof/indexed_axis/envelope.rs @@ -178,6 +178,15 @@ impl AxisEntries { } /// Whether the result list is empty. + /// An empty entry list of the right variant for `axis`. + 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()), + } + } + /// The first entry's original (primary) key, if any — the yielded /// item of a `k = 1` page, used by rank verification. pub fn first_original_key(&self) -> Option<&[u8]> { diff --git a/grovedb/src/operations/proof/indexed_axis/generate.rs b/grovedb/src/operations/proof/indexed_axis/generate.rs index 81329e368..ff08ea4a4 100644 --- a/grovedb/src/operations/proof/indexed_axis/generate.rs +++ b/grovedb/src/operations/proof/indexed_axis/generate.rs @@ -1265,7 +1265,7 @@ impl GroveDb { ) ); let secondary_proof = match &axis_query.traversal { - AxisTraversal::TopK { k, offset } => { + AxisTraversal::RankedPage { k, offset } => { cost_return_on_error_no_add!( cost, build_paginated_secondary_proof( @@ -1297,19 +1297,30 @@ impl GroveDb { ) } AxisTraversal::Bounded { limit, .. } => { - let secondary_query = cost_return_on_error_no_add!( - cost, - crate::query::axis_lowering::axis_bounded_merk_query(axis_query) - ); - let sec_result = cost_return_on_error!( - &mut cost, - secondary_merk - .prove(secondary_query, Some(*limit), grove_version) - .map_err(|e| Error::CorruptedData(format!( - "axis descent: secondary range proof: {e}" - ))) - ); - sec_result.proof + // An empty secondary cannot carry a Merk range proof + // (`Merk::prove` refuses empty trees), so — mirroring + // the count-offset and aggregate-on-range empty + // conventions — the payload carries EMPTY proof bytes, + // which the verifier resolves to a NULL_HASH secondary + // root. The parent binding then only passes if the + // element genuinely commits an empty secondary. + if cost_return_on_error!(&mut cost, secondary_merk.is_empty_tree().map(Ok)) { + Vec::new() + } else { + let secondary_query = cost_return_on_error_no_add!( + cost, + crate::query::axis_lowering::axis_bounded_merk_query(axis_query) + ); + let sec_result = cost_return_on_error!( + &mut cost, + secondary_merk + .prove(secondary_query, Some(*limit), grove_version) + .map_err(|e| Error::CorruptedData(format!( + "axis descent: secondary range proof: {e}" + ))) + ); + sec_result.proof + } } AxisTraversal::RangeAggregate { lo, hi } => match axis { IndexAxis::Count => { diff --git a/grovedb/src/operations/proof/verify.rs b/grovedb/src/operations/proof/verify.rs index b173bdfab..c99a63423 100644 --- a/grovedb/src/operations/proof/verify.rs +++ b/grovedb/src/operations/proof/verify.rs @@ -866,7 +866,7 @@ impl GroveDb { // 1. Verify the secondary proof for the query's traversal, // recomputing the secondary root hash. let (secondary_root_hash, walk_result) = match &axis_query.traversal { - AxisTraversal::TopK { k, offset } => { + AxisTraversal::RankedPage { k, offset } => { let inner_range = MerkQueryItemForRange::RangeFull(std::ops::RangeFull); let res = verify_count_offset_on_range_proof( &payload.secondary_proof, @@ -945,26 +945,51 @@ impl GroveDb { (res.root_hash, AxisWalkResult::Rank { rank }) } AxisTraversal::Bounded { limit, .. } => { - let secondary_query = - crate::query::axis_lowering::axis_bounded_merk_query(axis_query)?; - let left_to_right = secondary_query.left_to_right; - let (root, res) = secondary_query - .execute_proof(&payload.secondary_proof, Some(*limit), left_to_right, 0) - .unwrap() - .map_err(|e| { - Error::InvalidProof( - query.clone(), - format!("axis descent: secondary range proof failed: {e}"), - ) - })?; - let entries = decode_axis_entries_from_result_set(axis, &res.result_set)?; - ( - root, - AxisWalkResult::Entries { - entries, - skipped: None, - }, - ) + if payload.secondary_proof.is_empty() { + // Empty-secondary convention (mirrors the + // count-offset and aggregate-on-range verifiers): + // empty proof bytes resolve to a NULL_HASH secondary + // root and no entries. Sound because the binding + // below only passes when the element genuinely + // commits an empty secondary — claiming emptiness + // for a populated one needs a Blake3 second + // preimage. + ( + NULL_HASH, + AxisWalkResult::Entries { + entries: AxisEntries::empty_for_axis(axis), + skipped: None, + }, + ) + } else { + let secondary_query = + crate::query::axis_lowering::axis_bounded_merk_query(axis_query)?; + let left_to_right = secondary_query.left_to_right; + // proof_version 0 (lenient) matches the standalone + // envelope's choice and is safe HERE because the + // axis decoders consume only `proved.key` — bound + // into the recomputed secondary root — never + // `proved.value`. If a future change starts reading + // secondary VALUES, it must move to + // PROOF_VERSION_LATEST first. + let (root, res) = secondary_query + .execute_proof(&payload.secondary_proof, Some(*limit), left_to_right, 0) + .unwrap() + .map_err(|e| { + Error::InvalidProof( + query.clone(), + format!("axis descent: secondary range proof failed: {e}"), + ) + })?; + let entries = decode_axis_entries_from_result_set(axis, &res.result_set)?; + ( + root, + AxisWalkResult::Entries { + entries, + skipped: None, + }, + ) + } } AxisTraversal::RangeAggregate { lo, hi } => match axis { grovedb_merk::proofs::query::IndexAxis::Count => { @@ -1192,6 +1217,50 @@ impl GroveDb { verified_keys.insert(key.clone()); + // Axis-ordered read: resolved BEFORE the lower-layer + // lookup, so that a prover cannot omit the + // axis-descent layer to fabricate an absence. If the + // query node governing this indexed tree carries + // ReadMode::Axis, the layer MUST exist and MUST be an + // axis descent — a missing layer is a hard error, not + // a silent skip (which the branched shape would + // endorse as a `None`, i.e. proven-absent, slot). + // + // This also makes an empty indexed tree report an + // empty axis result (verify_axis_descent_layer proves + // it against a NULL-hash secondary), matching the + // honest prover and the trusted read rather than + // reporting the branch absent. + if element.is_indexed_tree() { + let mut axis_path = current_path.to_vec(); + axis_path.push(key); + if let Some(axis_query) = query.axis_read_at_path(&axis_path) { + let Some(lower_layer) = lower_layers.get(key) else { + return Err(Error::InvalidProof( + query.clone(), + format!( + "V1 axis read at key {} has no axis-descent lower \ + layer; the element cannot be reported as absent", + hex::encode(key), + ), + )); + }; + path.push(key); + *last_parent_tree_type = element.tree_feature_type(); + Self::verify_axis_descent_layer( + lower_layer, + axis_query, + value_bytes, + hash, + &path, + axis_outcomes, + query, + grove_version, + )?; + continue; + } + } + if let Some(lower_layer) = lower_layers.get(key) { // MmrTree/BulkAppendTree have root_key=None (no child Merk data), // so they match on (..) rather than (Some(_), ..) @@ -1212,27 +1281,12 @@ impl GroveDb { Element::ProvableCountIndexedTree(..) | Element::ProvableSumIndexedTree(..) | Element::ProvableCountProvableSumIndexedTree(..) => { + // An axis-read indexed tree was already + // handled (and `continue`d) above, before + // this lower-layer lookup, so here the + // query descends the primary as usual. path.push(key); *last_parent_tree_type = element.tree_feature_type(); - // Axis-ordered descent: the query node - // governing this indexed tree carries - // ReadMode::Axis, so the lower layer must be - // an axis-descent payload — a proof over the - // queried per-axis secondary — never a - // primary descent or a terminal attestation. - if let Some(axis_query) = query.axis_read_at_path(&path) { - Self::verify_axis_descent_layer( - lower_layer, - axis_query, - value_bytes, - hash, - &path, - axis_outcomes, - query, - grove_version, - )?; - continue; - } if query.query_items_at_path(&path, grove_version)?.is_none() { // The indexed tree is itself a result and // nothing is queried below it. The element diff --git a/grovedb/src/operations/proof/verify_path_query.rs b/grovedb/src/operations/proof/verify_path_query.rs index 6ed62388e..72bd72f0b 100644 --- a/grovedb/src/operations/proof/verify_path_query.rs +++ b/grovedb/src/operations/proof/verify_path_query.rs @@ -299,13 +299,22 @@ impl GroveDb { None => { // No axis layer for this branch: the // branching-level Merk proof must have - // authenticated the key's ABSENCE — any - // present-element trio for it means a hidden - // branch. + // authenticated the key's ABSENCE. Any + // present-element trio for the branch key + // itself — or anywhere under its subtree — + // means the proof shows the branch present + // while withholding its axis layer, i.e. a + // hidden branch dressed up as absence. let present = trios.iter().any(|(trio_path, trio_key, element)| { - trio_path == &path_query.path - && trio_key == branch_key - && element.is_some() + if element.is_none() { + return false; + } + // The branch key at the branching level… + (trio_path == &path_query.path && trio_key == branch_key) + // …or anything below prefix/branch_key. + || (trio_path.len() > path_query.path.len() + && trio_path[..path_query.path.len()] == path_query.path + && trio_path[path_query.path.len()] == *branch_key) }); if present { return Err(Error::InvalidProof( @@ -328,19 +337,11 @@ impl GroveDb { .to_string(), )); } - // The branched grammar admits only entry-listing - // traversals downstream; reject aggregates/ranks here - // for symmetry with the prover. - if matches!( - axis.traversal, - AxisTraversal::RankOfKey { .. } | AxisTraversal::RangeAggregate { .. } - ) { - return Err(Error::NotSupported( - "branched axis reads serve entry-listing traversals (TopK / Bounded) \ - only" - .to_string(), - )); - } + // A non-entry-listing branched traversal never reaches + // here: `classify` rejects it as `InvalidQuery` before + // this function runs, which is where the rule belongs — + // the trusted reader gets the identical rejection. + let _ = axis; Ok(VerifiedPathQuery::BranchedAxisEntries { root_hash, branches, @@ -402,7 +403,7 @@ impl GroveDb { match (result, traversal) { ( AxisWalkResult::Entries { entries, skipped }, - AxisTraversal::TopK { .. } | AxisTraversal::Bounded { .. }, + AxisTraversal::RankedPage { .. } | AxisTraversal::Bounded { .. }, ) => Ok(VerifiedPathQuery::AxisEntries { root_hash, entries, diff --git a/grovedb/src/query/mod.rs b/grovedb/src/query/mod.rs index ccb044368..f1e40e116 100644 --- a/grovedb/src/query/mod.rs +++ b/grovedb/src/query/mod.rs @@ -1284,7 +1284,7 @@ impl PathQuery { return None; } let node = resolve_node_at_path(&self.query.query, &path[self_path_len..])?; - match &node.read_mode { + match node.read_mode.as_deref() { Some(ReadMode::Axis(axis_query)) => Some(axis_query), _ => None, } diff --git a/grovedb/src/query/shape.rs b/grovedb/src/query/shape.rs index 86e0ed1a5..3cf0b9aec 100644 --- a/grovedb/src/query/shape.rs +++ b/grovedb/src/query/shape.rs @@ -340,6 +340,22 @@ impl PathQuery { (at least one)", )); } + // Duplicate branch keys would produce contradictory + // per-branch rows (one Some, one None) from a single + // valid proof; reject them for reader, prover, and + // verifier at once. + { + let mut seen = std::collections::BTreeSet::new(); + for item in &query.items { + if let QueryItem::Key(branch_key) = item + && !seen.insert(branch_key.as_slice()) + { + return Err(Error::InvalidQuery( + "a branched axis read may not name the same branch key twice", + )); + } + } + } let branch = &query.default_subquery_branch; let Some(suffix) = branch.subquery_path.as_deref() else { return Err(Error::InvalidQuery( diff --git a/grovedb/src/tests/axis_descent_proof_tests.rs b/grovedb/src/tests/axis_descent_proof_tests.rs index 89077ff43..3e0192f3d 100644 --- a/grovedb/src/tests/axis_descent_proof_tests.rs +++ b/grovedb/src/tests/axis_descent_proof_tests.rs @@ -546,6 +546,166 @@ mod tests { .expect_err("hiding a present branch must be rejected"); } + #[test] + fn hiding_a_present_but_empty_branch_is_rejected() { + // Audit finding: a branch whose indexed tree exists but is EMPTY + // fails `is_non_empty_tree`, so before the axis check was hoisted + // above the lower-layer lookup, stripping its axis layer slipped + // every guard and the verifier endorsed a false `None` + // ("proven absent") slot under the genuine root hash. + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_branched_psits( + &db, + grove_version, + &[ + (b"alice", &[] as &[(&[u8], i64)]), // created, NO entries + (b"carol", &[(b"m1", 7)]), + ], + ); + let pq = PathQuery::new_branched_axis( + vec![TEST_LEAF.to_vec()], + vec![b"alice".to_vec(), b"carol".to_vec()], + vec![b"scores".to_vec()], + AxisQuery::top_k(IndexAxis::Sum, 1, 0, true), + ); + let proof = prove(&db, &pq, grove_version); + + // Honest verification reports alice PRESENT with empty entries, + // never absent. + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("honest empty-branch proof verifies") + { + VerifiedPathQuery::BranchedAxisEntries { branches, .. } => { + let alice = branches + .iter() + .find(|(key, _)| key == b"alice") + .expect("alice slot"); + assert!( + matches!(&alice.1, Some(entries) if entries.is_empty()), + "an existing empty indexed tree must report Some(empty), got {:?}", + alice.1 + ); + } + other => panic!("expected BranchedAxisEntries, got {other:?}"), + } + + // Stripping alice's axis layer must be rejected, not endorsed as + // absence. + let config = bincode::config::standard().with_big_endian(); + let (mut decoded, _): (GroveDBProof, usize) = + bincode::decode_from_slice(&proof, config).expect("decode envelope"); + let GroveDBProof::V1(ref mut v1) = decoded else { + panic!("expected V1 envelope"); + }; + fn strip_key(layer: &mut LayerProof, key: &[u8]) -> bool { + if layer.lower_layers.remove(key).is_some() { + return true; + } + layer + .lower_layers + .values_mut() + .any(|lower| strip_key(lower, key)) + } + assert!(strip_key(&mut v1.root_layer, b"scores".as_slice())); + let tampered = bincode::encode_to_vec(&decoded, config).expect("re-encode"); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("hiding a present-but-empty branch must be rejected"); + } + + #[test] + fn empty_indexed_tree_round_trips_for_every_traversal() { + // Audit finding: the Bounded traversal hard-errored on an empty + // secondary (Merk::prove refuses empty trees) while every other + // traversal — and the trusted read — handled it. All four must + // round-trip against a freshly created, never-populated indexed + // tree. + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, &[]); + let root = root_hash(&db, grove_version); + + // Bounded (the previously-broken one). + let pq = PathQuery::new_axis_bounded(psit_path(), IndexAxis::Sum, 0, 100, 5, true); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("bounded over an empty secondary verifies") + { + VerifiedPathQuery::AxisEntries { + root_hash, entries, .. + } => { + assert_eq!(root_hash, root); + assert!(entries.is_empty()); + } + other => panic!("expected AxisEntries, got {other:?}"), + } + + // TopK. + let pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 3, 0, true); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("top-k over an empty secondary verifies") + { + VerifiedPathQuery::AxisEntries { + root_hash, entries, .. + } => { + assert_eq!(root_hash, root); + assert!(entries.is_empty()); + } + other => panic!("expected AxisEntries, got {other:?}"), + } + + // RangeAggregate. + let pq = PathQuery::new_axis_range_aggregate(psit_path(), IndexAxis::Sum, 0, 100); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("range aggregate over an empty secondary verifies") + { + VerifiedPathQuery::AxisAggregate { root_hash, value } => { + assert_eq!(root_hash, root); + assert_eq!(value, 0); + } + other => panic!("expected AxisAggregate, got {other:?}"), + } + + // RankOfKey errors cleanly (the key cannot exist in an empty + // tree) rather than producing a bogus proof. + let pq = + PathQuery::new_axis_rank_of_key(psit_path(), IndexAxis::Sum, b"ghost".to_vec(), true); + db.prove_query(&pq, None, grove_version) + .unwrap() + .expect_err("rank of a key in an empty indexed tree must error"); + } + + #[test] + fn duplicate_branch_keys_are_rejected_at_classification() { + // Audit finding: duplicate branch keys would produce + // contradictory per-branch rows (one Some, one None) from a + // single valid proof. The constructor dedups via `insert_key`, + // so hand-build the malformed query the way a hostile or buggy + // caller could. + use grovedb_merk::proofs::{ + query::{query_item::QueryItem, ReadMode}, + Query, + }; + let mut terminal = Query::new(); + terminal.read_mode = Some(Box::new(ReadMode::Axis(AxisQuery::top_k( + IndexAxis::Sum, + 1, + 0, + true, + )))); + let mut branching = Query::new(); + branching.items.push(QueryItem::Key(b"alice".to_vec())); + branching.items.push(QueryItem::Key(b"alice".to_vec())); + branching.set_subquery_path(vec![b"scores".to_vec()]); + branching.set_subquery(terminal); + let pq = PathQuery::new_unsized(vec![TEST_LEAF.to_vec()], branching); + match pq.classify() { + Err(Error::InvalidQuery(message)) => { + assert!(message.contains("same branch key"), "got: {message}") + } + other => panic!("duplicate branch keys must be rejected, got {other:?}"), + } + } + // ----------------------------------------------------------------- // Gates // ----------------------------------------------------------------- From eaa9f459c5c53cc293f2e32eb20ac508eae2c61a Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 17:40:48 +0700 Subject: [PATCH 3/4] fix: close two axis-read gaps found in review; expand coverage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 — a branch whose axis terminal is a present NON-indexed element was reported as proven-absent. The verifier resolved `axis_read_at_path` only after filtering on `element.is_indexed_tree()`, so an ordinary tree at the terminal fell through to the normal descent, which yields no trio for it; the branched arm then saw neither an axis layer nor a present element and endorsed `None` under a genuine root hash — while the trusted read rejects the same state as unindexed. The axis read is now resolved from the query FIRST: any key the query governs as an axis read must hold an indexed tree, or it is a hard InvalidProof. P2 — a single-path axis read whose target is missing or non-indexed produced no axis descent, and the prover returned Ok with an ordinary layer; only the verifier caught it, as "must verify exactly one axis layer, got 0". Generation now fails instead. Branched reads are excluded: an absent branch key legitimately produces no descent, and the branching-level Merk proof is what authenticates its absence. Coverage: verify_path_query.rs 48% -> 77%, and the new-code gaps in verify.rs / indexed_axis / envelope / axis_lowering closed alongside. Nine differential tests route every non-axis shape (three aggregate leaves, three aggregate carriers, key selection, count-offset pagination, the unproved sum-budget shape) through the unified entry and assert equality with the dedicated verifier it delegates to. On the axis side: count- and avg-axis round trips (each traversal fans out per axis on both sides), bounded-over-empty on all three axes, structural layer forgeries (non-axis bytes, smuggled lower layers, stray/dropped rank echoes), rank-proof replay for another key, canonical payload decoding, and axis-read path resolution. Co-Authored-By: Claude Opus 5 --- grovedb/src/operations/proof/generate.rs | 37 ++ grovedb/src/operations/proof/verify.rs | 103 +-- grovedb/src/tests/axis_descent_proof_tests.rs | 620 ++++++++++++++++++ grovedb/src/tests/mod.rs | 1 + .../tests/verify_path_query_shape_tests.rs | 478 ++++++++++++++ 5 files changed, 1199 insertions(+), 40 deletions(-) create mode 100644 grovedb/src/tests/verify_path_query_shape_tests.rs diff --git a/grovedb/src/operations/proof/generate.rs b/grovedb/src/operations/proof/generate.rs index edf838381..daecc88f0 100644 --- a/grovedb/src/operations/proof/generate.rs +++ b/grovedb/src/operations/proof/generate.rs @@ -1407,6 +1407,43 @@ impl GroveDb { ) ); + // A single-path axis read has exactly one answer — the axis + // descent at the queried path. The generic walk cannot produce + // one when the target is missing or is not an indexed tree; it + // returns `Ok` with an ordinary (or empty) layer instead, and + // the verifier then rejects the result as "must verify exactly + // one axis layer, got 0". Fail generation here instead, so the + // prover never hands out a proof that cannot answer the query + // it was asked. + // + // Branched axis reads are deliberately excluded: an absent + // branch key legitimately produces no descent, and its absence + // is what the branching-level Merk proof authenticates. + if matches!( + path_query.classify(), + Ok(crate::PathQueryShape::AxisRead { .. }) + ) { + fn count_axis_descents(layer: &LayerProof) -> usize { + usize::from(matches!( + layer.merk_proof, + ProofBytes::IndexedTreeAxisDescent(_) + )) + layer + .lower_layers + .values() + .map(count_axis_descents) + .sum::() + } + let descents = count_axis_descents(&root_layer); + if descents != 1 { + return Err(Error::InvalidPath(format!( + "a single-path axis read must produce exactly one axis descent at the \ + queried path, but the walk produced {descents} — the path does not \ + name an indexed tree carrying that axis" + ))) + .wrap_with_cost(cost); + } + } + Ok(GroveDBProof::V1(GroveDBProofV1 { root_layer })).wrap_with_cost(cost) } diff --git a/grovedb/src/operations/proof/verify.rs b/grovedb/src/operations/proof/verify.rs index c99a63423..5dab15177 100644 --- a/grovedb/src/operations/proof/verify.rs +++ b/grovedb/src/operations/proof/verify.rs @@ -1217,48 +1217,71 @@ impl GroveDb { verified_keys.insert(key.clone()); - // Axis-ordered read: resolved BEFORE the lower-layer - // lookup, so that a prover cannot omit the - // axis-descent layer to fabricate an absence. If the - // query node governing this indexed tree carries - // ReadMode::Axis, the layer MUST exist and MUST be an - // axis descent — a missing layer is a hard error, not - // a silent skip (which the branched shape would - // endorse as a `None`, i.e. proven-absent, slot). + // Axis-ordered read: resolved from the QUERY first — + // before the element type is consulted and before + // the lower-layer lookup — so that neither a + // wrong-typed element nor a missing layer can + // fabricate an absence. If the query node governing + // this key carries ReadMode::Axis then this key is + // an axis read, and the only proof that answers it + // is an axis descent over an indexed tree: // - // This also makes an empty indexed tree report an - // empty axis result (verify_axis_descent_layer proves - // it against a NULL-hash secondary), matching the - // honest prover and the trusted read rather than - // reporting the branch absent. - if element.is_indexed_tree() { - let mut axis_path = current_path.to_vec(); - axis_path.push(key); - if let Some(axis_query) = query.axis_read_at_path(&axis_path) { - let Some(lower_layer) = lower_layers.get(key) else { - return Err(Error::InvalidProof( - query.clone(), - format!( - "V1 axis read at key {} has no axis-descent lower \ - layer; the element cannot be reported as absent", - hex::encode(key), - ), - )); - }; - path.push(key); - *last_parent_tree_type = element.tree_feature_type(); - Self::verify_axis_descent_layer( - lower_layer, - axis_query, - value_bytes, - hash, - &path, - axis_outcomes, - query, - grove_version, - )?; - continue; + // * a non-indexed element here is a hard error. It + // used to fall through to the ordinary descent, + // which yields no trio for a present normal tree + // — so the branched shape saw neither an axis + // layer nor a present element and endorsed the + // branch as `None`, i.e. proven absent, while the + // trusted read rejects the same state as + // unindexed. + // * a missing layer is a hard error, not a silent + // skip (which the branched shape would likewise + // endorse as a proven-absent slot). + // + // An empty indexed tree still reports an EMPTY axis + // result (verify_axis_descent_layer proves it against + // a NULL-hash secondary), matching the honest prover + // and the trusted read rather than reporting the + // branch absent. + let mut axis_path = current_path.to_vec(); + axis_path.push(key); + if let Some(axis_query) = query.axis_read_at_path(&axis_path) { + if !element.is_indexed_tree() { + return Err(Error::InvalidProof( + query.clone(), + format!( + "V1 axis read at key {} resolves to a non-indexed \ + element ({}); an axis-ordered read has no meaning \ + there, so the proof cannot answer this query — and \ + the key must not be reported as absent", + hex::encode(key), + element.type_str(), + ), + )); } + let Some(lower_layer) = lower_layers.get(key) else { + return Err(Error::InvalidProof( + query.clone(), + format!( + "V1 axis read at key {} has no axis-descent lower \ + layer; the element cannot be reported as absent", + hex::encode(key), + ), + )); + }; + path.push(key); + *last_parent_tree_type = element.tree_feature_type(); + Self::verify_axis_descent_layer( + lower_layer, + axis_query, + value_bytes, + hash, + &path, + axis_outcomes, + query, + grove_version, + )?; + continue; } if let Some(lower_layer) = lower_layers.get(key) { diff --git a/grovedb/src/tests/axis_descent_proof_tests.rs b/grovedb/src/tests/axis_descent_proof_tests.rs index 3e0192f3d..4c77b2f82 100644 --- a/grovedb/src/tests/axis_descent_proof_tests.rs +++ b/grovedb/src/tests/axis_descent_proof_tests.rs @@ -780,4 +780,624 @@ mod tests { fn root_hash_of(db: &GroveDb, grove_version: &GroveVersion) -> [u8; 32] { db.root_hash(None, grove_version).unwrap().expect("root") } + + // ----------------------------------------------------------------- + // The other two axes through the embedded envelope + // + // Every traversal fans out per axis on BOTH sides — the prover picks + // a secondary-proof builder per axis, the verifier picks a decoder — + // so a sum-only suite leaves two thirds of each fan-out unexecuted. + // ----------------------------------------------------------------- + + /// Build a PCIT at `[TEST_LEAF, b"pcit"]` whose entries carry the + /// given counts. Counts are DERIVED: each child is a provable count + /// tree populated with `c` items. + fn build_pcit(db: &GroveDb, grove_version: &GroveVersion, entries: &[(&[u8], u64)]) { + db.insert( + [TEST_LEAF].as_ref(), + b"pcit", + Element::empty_provable_count_indexed_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create PCIT"); + for (key, count) in entries { + db.insert_into_count_indexed_tree( + [TEST_LEAF, b"pcit"].as_ref(), + key, + Element::empty_provable_count_tree(), + None, + grove_version, + ) + .unwrap() + .expect("insert PCIT child"); + for i in 0..*count { + db.insert( + [TEST_LEAF, b"pcit", key].as_ref(), + &i.to_be_bytes(), + Element::new_item(b"v".to_vec()), + None, + None, + grove_version, + ) + .unwrap() + .expect("populate PCIT child"); + } + } + } + + fn pcit_path() -> Vec> { + vec![TEST_LEAF.to_vec(), b"pcit".to_vec()] + } + + #[test] + fn count_axis_traversals_round_trip() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pcit( + &db, + grove_version, + &[(b"alpha", 3), (b"beta", 1), (b"gamma", 5)], + ); + let root = root_hash(&db, grove_version); + let path = [TEST_LEAF, b"pcit"]; + + // Range aggregate on the COUNT axis: a different prover builder + // and a different verifier decoder from the sum axis. + let pq = PathQuery::new_axis_range_aggregate(pcit_path(), IndexAxis::Count, 2, 10); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("count range aggregate verifies") + { + VerifiedPathQuery::AxisAggregate { root_hash, value } => { + assert_eq!(root_hash, root); + let direct = db + .indexed_count_range_aggregate(path.as_ref(), 2, 10, None, grove_version) + .unwrap() + .expect("direct count range aggregate"); + assert_eq!(value, direct as i128); + // A count-axis range aggregate counts the ENTRIES whose + // count value lands in `[lo, hi]` — alpha (3) and gamma + // (5) — not the sum of those counts. beta (1) is below + // the range. + assert_eq!(value, 2); + } + other => panic!("expected AxisAggregate, got {other:?}"), + } + + // Paginated page and rank on the count axis: the paginated + // decoder and `first_original_key` both fan out per axis. + let pq = PathQuery::new_axis_top_k(pcit_path(), IndexAxis::Count, 2, 0, true); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("count top-k verifies") + { + VerifiedPathQuery::AxisEntries { entries, .. } => { + let direct = db + .indexed_count_top_k_paginated(path.as_ref(), 2, 0, true, None, grove_version) + .unwrap() + .expect("direct count top-k"); + assert_eq!(entries, AxisEntries::Count(direct)); + } + other => panic!("expected AxisEntries, got {other:?}"), + } + + let pq = + PathQuery::new_axis_rank_of_key(pcit_path(), IndexAxis::Count, b"alpha".to_vec(), true); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("count rank verifies") + { + // gamma (5) outranks alpha (3) descending. + VerifiedPathQuery::AxisRank { rank, .. } => assert_eq!(rank, 1), + other => panic!("expected AxisRank, got {other:?}"), + } + } + + #[test] + fn avg_axis_traversals_round_trip() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pcpsit(&db, grove_version, PSIT_ENTRIES); + let pcpsit_path = vec![TEST_LEAF.to_vec(), b"pcpsit".to_vec()]; + let path = [TEST_LEAF, b"pcpsit"]; + + // Bounded over the whole i128 domain (the avg axis is unclamped). + let pq = PathQuery::new_axis_bounded( + pcpsit_path.clone(), + IndexAxis::Avg, + i128::MIN, + i128::MAX, + 10, + false, + ); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("avg bounded verifies") + { + VerifiedPathQuery::AxisEntries { entries, .. } => { + let direct = db + .indexed_avg_range( + path.as_ref(), + i128::MIN, + i128::MAX, + false, + 10, + None, + grove_version, + ) + .unwrap() + .expect("direct avg range"); + assert_eq!(entries, AxisEntries::Avg(direct)); + } + other => panic!("expected AxisEntries, got {other:?}"), + } + + // Rank on the avg axis: `first_original_key` must read the Avg + // variant, not fall through to another axis's tuple shape. + let pq = + PathQuery::new_axis_rank_of_key(pcpsit_path, IndexAxis::Avg, b"alice".to_vec(), true); + let verified = + GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("avg rank verifies"); + let VerifiedPathQuery::AxisRank { rank, .. } = verified else { + panic!("expected AxisRank, got {verified:?}"); + }; + // Cross-check against the standalone envelope over the same + // state: two wire paths, one answer. + let (standalone_bytes, standalone_rank) = db + .prove_indexed_axis_rank_of_key( + path.as_ref(), + IndexAxis::Avg, + b"alice", + true, + None, + grove_version, + ) + .unwrap() + .expect("standalone avg rank prove"); + GroveDb::verify_indexed_axis_rank_of_key( + &standalone_bytes, + &path, + IndexAxis::Avg, + b"alice", + standalone_rank, + true, + ) + .expect("standalone avg rank verify"); + assert_eq!(rank, standalone_rank); + } + + #[test] + fn bounded_over_an_empty_secondary_round_trips_on_every_axis() { + // The empty-secondary convention resolves to `NULL_HASH` plus an + // axis-typed empty entry list — one constructor per axis. + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pcit(&db, grove_version, &[]); + build_pcpsit(&db, grove_version, &[]); + let pcpsit_path = vec![TEST_LEAF.to_vec(), b"pcpsit".to_vec()]; + + for (path, axis, expected) in [ + ( + pcit_path(), + IndexAxis::Count, + AxisEntries::Count(Vec::new()), + ), + ( + pcpsit_path.clone(), + IndexAxis::Sum, + AxisEntries::Sum(Vec::new()), + ), + (pcpsit_path, IndexAxis::Avg, AxisEntries::Avg(Vec::new())), + ] { + let pq = PathQuery::new_axis_bounded(path, axis, 0, 100, 5, true); + match GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("bounded over an empty secondary verifies") + { + VerifiedPathQuery::AxisEntries { entries, .. } => { + assert_eq!(entries, expected, "axis {axis:?}") + } + other => panic!("expected AxisEntries for {axis:?}, got {other:?}"), + } + } + } + + // ----------------------------------------------------------------- + // Structural forgeries of the axis layer itself + // ----------------------------------------------------------------- + + /// Decode → mutate the terminal axis-descent LAYER → re-encode. + fn tamper_axis_layer(proof: &[u8], mutate: impl FnOnce(&mut LayerProof)) -> Vec { + let config = bincode::config::standard().with_big_endian(); + let (mut decoded, _): (GroveDBProof, usize) = + bincode::decode_from_slice(proof, config).expect("decode envelope"); + let GroveDBProof::V1(ref mut v1) = decoded else { + panic!("expected V1 envelope"); + }; + fn find_descent(layer: &mut LayerProof) -> Option<&mut LayerProof> { + if matches!(layer.merk_proof, ProofBytes::IndexedTreeAxisDescent(_)) { + return Some(layer); + } + layer.lower_layers.values_mut().find_map(find_descent) + } + mutate(find_descent(&mut v1.root_layer).expect("envelope has an axis descent")); + bincode::encode_to_vec(&decoded, config).expect("re-encode envelope") + } + + #[test] + fn a_malformed_axis_layer_is_rejected() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + let pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 3, 0, true); + let proof = prove(&db, &pq, grove_version); + GroveDb::verify_path_query(&proof, &pq, grove_version).expect("untampered verifies"); + + // A plain merk proof where the query says "axis read": the + // verifier must not fall back to a key-selecting descent into + // the primary, which would answer a different question under + // the same root hash. + let swapped = tamper_axis_layer(&proof, |layer| { + layer.merk_proof = ProofBytes::Merk(Vec::new()); + }); + match GroveDb::verify_path_query(&swapped, &pq, grove_version) { + Err(Error::InvalidProof(_, message)) => { + assert!(message.contains("IndexedTreeAxisDescent"), "got: {message}") + } + other => panic!("a non-axis layer under an axis query must be rejected: {other:?}"), + } + + // An axis descent is terminal; smuggling lower layers under it + // must not be silently ignored. + let with_lower = tamper_axis_layer(&proof, |layer| { + layer + .lower_layers + .insert(b"smuggled".to_vec(), layer.clone()); + }); + match GroveDb::verify_path_query(&with_lower, &pq, grove_version) { + Err(Error::InvalidProof(_, message)) => { + assert!(message.contains("terminal"), "got: {message}") + } + other => panic!("lower layers under an axis descent must be rejected: {other:?}"), + } + + // A rank echo on a traversal that has no rank: the field only + // exists for RankOfKey, so carrying it elsewhere is malformed. + let stray_rank = tamper_axis_payload(&proof, |payload| payload.rank = Some(0)); + match GroveDb::verify_path_query(&stray_rank, &pq, grove_version) { + Err(Error::InvalidProof(_, message)) => { + assert!(message.contains("not RankOfKey"), "got: {message}") + } + other => panic!("a stray rank echo must be rejected: {other:?}"), + } + } + + #[test] + fn a_rank_proof_cannot_be_stripped_or_replayed_for_another_key() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + let pq = + PathQuery::new_axis_rank_of_key(psit_path(), IndexAxis::Sum, b"carol".to_vec(), true); + let proof = prove(&db, &pq, grove_version); + GroveDb::verify_path_query(&proof, &pq, grove_version).expect("honest rank verifies"); + + // Dropping the rank: a RankOfKey traversal has nothing to + // attest without it. + let no_rank = tamper_axis_payload(&proof, |payload| payload.rank = None); + match GroveDb::verify_path_query(&no_rank, &pq, grove_version) { + Err(Error::InvalidProof(_, message)) => { + assert!(message.contains("must carry the rank"), "got: {message}") + } + other => panic!("a rank proof without a rank must be rejected: {other:?}"), + } + + // Replaying carol's rank proof as an answer about erin: the + // count commitments still attest the skip honestly, so the + // entry AT that rank is carol — not the key that was asked + // about. The verifier must catch the substitution. + let other_key = + PathQuery::new_axis_rank_of_key(psit_path(), IndexAxis::Sum, b"erin".to_vec(), true); + match GroveDb::verify_path_query(&proof, &other_key, grove_version) { + Err(Error::InvalidProof(_, message)) => { + assert!(message.contains("not the queried key"), "got: {message}") + } + other => panic!("a replayed rank proof must be rejected: {other:?}"), + } + + // Overstating the rank past the end of the walk: the count + // commitments attest fewer skipped entries than claimed. + let overstated = tamper_axis_payload(&proof, |payload| payload.rank = Some(99)); + match GroveDb::verify_path_query(&overstated, &pq, grove_version) { + Err(Error::InvalidProof(_, message)) => assert!( + message.contains("attest") || message.contains("count-offset proof failed"), + "got: {message}" + ), + other => panic!("an overstated rank must be rejected: {other:?}"), + } + } + + #[test] + fn axis_descent_bytes_never_satisfy_a_key_selection_query() { + // The axis-descent variant is meaningful only where the query + // says "axis read". Reaching the ordinary layer verifier with + // it — e.g. by feeding an axis proof to a plain query over the + // same path — must hard-error rather than being treated as an + // empty or opaque merk proof. + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + let axis_pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 3, 0, true); + let axis_proof = prove(&db, &axis_pq, grove_version); + + let mut plain = grovedb_merk::proofs::Query::new(); + plain.insert_all(); + let mut outer = grovedb_merk::proofs::Query::new(); + outer.insert_key(b"psit".to_vec()); + outer.set_subquery(plain); + let plain_pq = PathQuery::new_unsized(vec![TEST_LEAF.to_vec()], outer); + + match GroveDb::verify_query(&axis_proof, &plain_pq, grove_version) { + Err(Error::InvalidProof(..)) | Err(Error::NotSupported(_)) => {} + other => panic!("axis-descent bytes must not satisfy a key selection: {other:?}"), + } + } + + #[test] + fn axis_descent_payload_decoding_is_canonical() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + let pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 3, 0, true); + let proof = prove(&db, &pq, grove_version); + + // Pull the honest payload bytes out of the envelope. + let config = bincode::config::standard().with_big_endian(); + let (decoded, _): (GroveDBProof, usize) = + bincode::decode_from_slice(&proof, config).expect("decode envelope"); + let GroveDBProof::V1(v1) = decoded else { + panic!("expected V1 envelope"); + }; + fn find_descent(layer: &LayerProof) -> Option<&Vec> { + if let ProofBytes::IndexedTreeAxisDescent(bytes) = &layer.merk_proof { + return Some(bytes); + } + layer.lower_layers.values().find_map(find_descent) + } + let bytes = find_descent(&v1.root_layer).expect("axis descent present"); + AxisDescentProof::decode_canonical(bytes).expect("honest payload decodes"); + + // Trailing bytes are a distinct encoding of the same payload — + // canonical decoding rejects them rather than ignoring them. + let mut padded = bytes.clone(); + padded.push(0); + match AxisDescentProof::decode_canonical(&padded) { + Err(Error::CorruptedData(message)) => { + assert!(message.contains("trailing"), "got: {message}") + } + other => panic!("trailing bytes must be rejected, got {other:?}"), + } + + // Garbage does not decode at all. + AxisDescentProof::decode_canonical(&[0xff, 0xff, 0xff, 0xff]) + .expect_err("garbage must not decode"); + + // The Display impl degrades to a byte count for payloads it + // cannot decode, rather than panicking inside a debug print. + let rendered = format!("{}", ProofBytes::IndexedTreeAxisDescent(vec![0xff; 3])); + assert!(rendered.contains('3'), "got: {rendered}"); + } + + // ----------------------------------------------------------------- + // Prover-side refusals + // ----------------------------------------------------------------- + + #[test] + fn a_single_path_axis_read_without_a_target_fails_generation() { + // Review finding (P2): the generic walk produces no axis descent + // when the queried path is missing or is not an indexed tree, + // and used to return `Ok` with an ordinary layer — a proof the + // verifier could only reject as "got 0 axis layers". The prover + // must refuse to emit it instead. + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + + // A present element that is an ordinary tree... + let plain_target = + PathQuery::new_axis_top_k(vec![TEST_LEAF.to_vec()], IndexAxis::Sum, 2, 0, true); + // ...and a path that names nothing at all. + let missing_target = PathQuery::new_axis_top_k( + vec![TEST_LEAF.to_vec(), b"ghost".to_vec()], + IndexAxis::Sum, + 2, + 0, + true, + ); + + for pq in [plain_target, missing_target] { + match db.prove_query(&pq, None, grove_version).unwrap() { + Err(Error::InvalidPath(message)) => assert!( + message.contains("exactly one axis descent"), + "got: {message}" + ), + other => panic!("an axis read with no indexed target must be refused: {other:?}"), + } + } + } + + #[test] + fn a_branch_whose_axis_terminal_is_not_indexed_is_never_reported_absent() { + // Review finding (P1): the verifier resolved the axis read only + // AFTER filtering on `is_indexed_tree`, so a present ORDINARY + // tree at a branch's axis terminal fell through to the normal + // descent — which yields no trio for it. The branched arm then + // saw neither an axis layer nor a present element and endorsed + // the branch as `None`, i.e. proven absent, under a genuine root + // hash, while the trusted read rejects the same state outright. + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + // carol is indexed as usual; alice's `scores` is an ordinary + // tree, so her axis terminal has no secondary index at all. + build_branched_psits(&db, grove_version, &[(b"carol", &[(b"m1", 7)])]); + db.insert( + [TEST_LEAF].as_ref(), + b"alice", + Element::empty_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create alice branch"); + db.insert( + [TEST_LEAF, b"alice"].as_ref(), + b"scores", + Element::empty_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create alice's UNindexed scores tree"); + + let pq = PathQuery::new_branched_axis( + vec![TEST_LEAF.to_vec()], + vec![b"alice".to_vec(), b"carol".to_vec()], + vec![b"scores".to_vec()], + AxisQuery::top_k(IndexAxis::Sum, 1, 0, true), + ); + + // The trusted read refuses the same state, so a verified answer + // of "alice is absent" would be a proof/read disagreement. + db.run_path_query( + &pq, + true, + true, + true, + crate::query_result_type::QueryResultType::QueryKeyElementPairResultType, + None, + grove_version, + ) + .unwrap() + .expect_err("the trusted read rejects an unindexed axis terminal"); + + // Whatever the prover emits, verification must not endorse + // alice as proven-absent. + match db.prove_query(&pq, None, grove_version).unwrap() { + Err(_) => {} + Ok(proof) => match GroveDb::verify_path_query(&proof, &pq, grove_version) { + Err(Error::InvalidProof(_, message)) => { + assert!(message.contains("non-indexed"), "got: {message}") + } + other => panic!( + "an unindexed axis terminal must never verify as an absent branch: \ + {other:?}" + ), + }, + } + } + + #[test] + fn the_v0_envelope_and_malformed_read_modes_are_refused_at_the_prover() { + let v1 = &GROVE_VERSIONS[0]; + assert_eq!(v1.protocol_version, 1, "GROVE_VERSIONS[0] must be V1"); + let v4 = GroveVersion::latest(); + let db = make_test_grovedb(v4); + build_psit(&db, v4, PSIT_ENTRIES); + + // Grove v1 emits V0 envelopes, which have no axis-descent + // variant at all — refuse before touching the tree. + let pq = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 2, 0, true); + match db.prove_query(&pq, None, v1).unwrap() { + Err(Error::NotSupported(message)) => { + assert!(message.contains("V1 proof envelopes"), "got: {message}") + } + other => panic!("the V0 envelope must refuse axis shapes: {other:?}"), + } + + // A read-mode query that does not classify at all fails closed + // at the prover instead of being misread as key selection. + use grovedb_merk::proofs::{query::ReadMode, Query as MerkQuery}; + let mut malformed = MerkQuery::new(); + malformed.read_mode = Some(Box::new(ReadMode::Axis(AxisQuery::top_k( + IndexAxis::Sum, + 1, + 0, + true, + )))); + // Items alongside an axis read: the axis grammar forbids it. + malformed.insert_key(b"alice".to_vec()); + let pq = PathQuery::new_unsized(psit_path(), malformed); + match db.prove_query(&pq, None, v4).unwrap() { + Err(Error::InvalidQuery(_)) => {} + other => panic!("a malformed read-mode query must fail closed: {other:?}"), + } + } + + // ----------------------------------------------------------------- + // Read-mode resolution — the one function both sides use to decide + // which layers are axis reads + // ----------------------------------------------------------------- + + #[test] + fn axis_read_resolution_agrees_on_every_position() { + use grovedb_merk::proofs::{ + query::{query_item::QueryItem, ReadMode}, + Query as MerkQuery, + }; + let mut terminal = MerkQuery::new(); + terminal.read_mode = Some(Box::new(ReadMode::Axis(AxisQuery::top_k( + IndexAxis::Sum, + 1, + 0, + true, + )))); + // A conditional branch for `alice` and a default branch for the + // rest, both reaching the terminal through a two-segment + // subquery path. + let mut branching = MerkQuery::new(); + branching.insert_key(b"alice".to_vec()); + branching.insert_key(b"bob".to_vec()); + branching.set_subquery_path(vec![b"scores".to_vec(), b"y2026".to_vec()]); + branching.set_subquery(terminal.clone()); + branching.add_conditional_subquery( + QueryItem::Key(b"alice".to_vec()), + Some(vec![b"scores".to_vec(), b"y2026".to_vec()]), + Some(terminal), + ); + let pq = PathQuery::new_unsized(vec![TEST_LEAF.to_vec()], branching); + + let p = + |segments: &[&[u8]]| -> Option { pq.axis_read_at_path(segments).map(|_| true) }; + + // The terminal node, reached through the conditional branch... + assert_eq!( + p(&[TEST_LEAF, b"alice", b"scores", b"y2026"]), + Some(true), + "conditional branch must resolve to the axis terminal" + ); + // ...and through the default one. + assert_eq!( + p(&[TEST_LEAF, b"bob", b"scores", b"y2026"]), + Some(true), + "default branch must resolve to the axis terminal" + ); + // Above the query root: nothing can carry a read mode. + assert_eq!(p(&[]), None); + // Diverging from the query's own path. + assert_eq!(p(&[b"elsewhere", b"alice", b"scores", b"y2026"]), None); + // Mid-subquery_path: a read mode lives on a query node, never + // between two path segments. + assert_eq!(p(&[TEST_LEAF, b"bob", b"scores"]), None); + // The subquery path exists but diverges at its last segment. + assert_eq!(p(&[TEST_LEAF, b"bob", b"scores", b"y2025"]), None); + // Past the terminal: the axis descent has nothing below it. + assert_eq!( + p(&[TEST_LEAF, b"bob", b"scores", b"y2026", b"deeper"]), + None + ); + // The branching level itself is a key selection, not an axis + // read. + assert_eq!(p(&[TEST_LEAF]), None); + } } diff --git a/grovedb/src/tests/mod.rs b/grovedb/src/tests/mod.rs index 0333cfbf7..756c04561 100644 --- a/grovedb/src/tests/mod.rs +++ b/grovedb/src/tests/mod.rs @@ -96,6 +96,7 @@ mod trunk_proof_tests; mod v1_cidx_descent_tests; mod v1_proof_tests; mod verify_grovedb_indexed_tests; +mod verify_path_query_shape_tests; mod visualize_tests; use std::{ diff --git a/grovedb/src/tests/verify_path_query_shape_tests.rs b/grovedb/src/tests/verify_path_query_shape_tests.rs new file mode 100644 index 000000000..730552e35 --- /dev/null +++ b/grovedb/src/tests/verify_path_query_shape_tests.rs @@ -0,0 +1,478 @@ +//! Differential tests for the non-axis arms of +//! [`GroveDb::verify_path_query`], the unified verification dispatch: +//! for every shape it routes, the unified answer must equal the answer +//! of the dedicated `verify_*` entry point it delegates to, over the +//! same proof. The axis arms live in `axis_descent_proof_tests`. + +#[cfg(test)] +mod tests { + use grovedb_merk::proofs::{query::query_item::QueryItem, Query}; + use grovedb_version::version::GroveVersion; + + use crate::{ + operations::proof::VerifiedPathQuery, + tests::{make_test_grovedb, TEST_LEAF}, + Element, Error, GroveDb, PathQuery, SizedQuery, + }; + + // ----------------------------------------------------------------- + // Fixtures + // ----------------------------------------------------------------- + + /// A provable count tree at `[TEST_LEAF, name]` holding `keys` + /// plain items. + fn build_pct(db: &GroveDb, name: &[u8], keys: &[&[u8]], grove_version: &GroveVersion) { + db.insert( + [TEST_LEAF].as_ref(), + name, + Element::empty_provable_count_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create provable count tree"); + for key in keys { + db.insert( + [TEST_LEAF, name].as_ref(), + key, + Element::new_item(b"v".to_vec()), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert counted item"); + } + } + + /// A provable sum tree at `[TEST_LEAF, name]` holding `entries`. + fn build_pst( + db: &GroveDb, + name: &[u8], + entries: &[(&[u8], i64)], + grove_version: &GroveVersion, + ) { + db.insert( + [TEST_LEAF].as_ref(), + name, + Element::empty_provable_sum_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create provable sum tree"); + for (key, sum) in entries { + db.insert( + [TEST_LEAF, name].as_ref(), + key, + Element::new_sum_item(*sum), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert sum item"); + } + } + + /// A provable count + provable sum tree at `[TEST_LEAF, name]`. + fn build_pcps( + db: &GroveDb, + name: &[u8], + entries: &[(&[u8], i64)], + grove_version: &GroveVersion, + ) { + db.insert( + [TEST_LEAF].as_ref(), + name, + Element::empty_provable_count_provable_sum_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create PCPS tree"); + for (key, sum) in entries { + db.insert( + [TEST_LEAF, name].as_ref(), + key, + Element::new_sum_item(*sum), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert PCPS sum item"); + } + } + + fn full_range() -> QueryItem { + QueryItem::Range(b"a".to_vec()..b"z".to_vec()) + } + + fn prove(db: &GroveDb, path_query: &PathQuery, grove_version: &GroveVersion) -> Vec { + db.prove_query(path_query, None, grove_version) + .unwrap() + .expect("prove path query") + } + + // ----------------------------------------------------------------- + // Aggregate leaves: one aggregate over one range in one tree + // ----------------------------------------------------------------- + + #[test] + fn aggregate_leaf_count_verifies_through_the_unified_entry() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pct(&db, b"pct", &[b"a", b"b", b"c"], grove_version); + + let pq = PathQuery::new_aggregate_count_on_range( + vec![TEST_LEAF.to_vec(), b"pct".to_vec()], + full_range(), + ); + let proof = prove(&db, &pq, grove_version); + + let (dedicated_root, dedicated_count) = + GroveDb::verify_aggregate_count_query(&proof, &pq, grove_version) + .expect("dedicated count verify"); + match GroveDb::verify_path_query(&proof, &pq, grove_version).expect("unified count verify") + { + VerifiedPathQuery::AggregateCount { root_hash, count } => { + assert_eq!(root_hash, dedicated_root); + assert_eq!(count, dedicated_count); + assert_eq!(count, 3); + } + other => panic!("expected AggregateCount, got {other:?}"), + } + } + + #[test] + fn aggregate_leaf_sum_verifies_through_the_unified_entry() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pst( + &db, + b"pst", + &[(b"a", 5), (b"b", -2), (b"c", 11)], + grove_version, + ); + + let pq = PathQuery::new_aggregate_sum_on_range( + vec![TEST_LEAF.to_vec(), b"pst".to_vec()], + full_range(), + ); + let proof = prove(&db, &pq, grove_version); + + let (dedicated_root, dedicated_sum) = + GroveDb::verify_aggregate_sum_query(&proof, &pq, grove_version) + .expect("dedicated sum verify"); + match GroveDb::verify_path_query(&proof, &pq, grove_version).expect("unified sum verify") { + VerifiedPathQuery::AggregateSum { root_hash, sum } => { + assert_eq!(root_hash, dedicated_root); + assert_eq!(sum, dedicated_sum); + assert_eq!(sum, 14); + } + other => panic!("expected AggregateSum, got {other:?}"), + } + } + + #[test] + fn aggregate_leaf_count_and_sum_verifies_through_the_unified_entry() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pcps(&db, b"pcps", &[(b"a", 7), (b"b", 3)], grove_version); + + let pq = PathQuery::new_aggregate_count_and_sum_on_range( + vec![TEST_LEAF.to_vec(), b"pcps".to_vec()], + full_range(), + ); + let proof = prove(&db, &pq, grove_version); + + let (dedicated_root, dedicated_count, dedicated_sum) = + GroveDb::verify_aggregate_count_and_sum_query(&proof, &pq, grove_version) + .expect("dedicated combined verify"); + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("unified combined verify") + { + VerifiedPathQuery::AggregateCountAndSum { + root_hash, + count, + sum, + } => { + assert_eq!(root_hash, dedicated_root); + assert_eq!((count, sum), (dedicated_count, dedicated_sum)); + assert_eq!((count, sum), (2, 10)); + } + other => panic!("expected AggregateCountAndSum, got {other:?}"), + } + } + + // ----------------------------------------------------------------- + // Aggregate carriers: one aggregate per matched outer key + // ----------------------------------------------------------------- + + /// Outer keys at `TEST_LEAF`, each an aggregate leaf underneath. + fn carrier_path_query(outer_keys: &[&[u8]], subquery: Query) -> PathQuery { + let mut carrier = Query::new(); + for key in outer_keys { + carrier.insert_key(key.to_vec()); + } + carrier.set_subquery(subquery); + PathQuery::new_unsized(vec![TEST_LEAF.to_vec()], carrier) + } + + #[test] + fn aggregate_carrier_count_verifies_through_the_unified_entry() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pct(&db, b"one", &[b"a", b"b"], grove_version); + build_pct(&db, b"two", &[b"a", b"b", b"c"], grove_version); + + let pq = carrier_path_query( + &[b"one", b"two"], + Query::new_aggregate_count_on_range(full_range()), + ); + let proof = prove(&db, &pq, grove_version); + + let (dedicated_root, dedicated) = + GroveDb::verify_aggregate_count_query_per_key(&proof, &pq, grove_version) + .expect("dedicated per-key count verify"); + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("unified per-key count verify") + { + VerifiedPathQuery::AggregatePerKey { root_hash, per_key } => { + assert_eq!(root_hash, dedicated_root); + // The carrier arm widens `(key, count)` into + // `(key, Some(count), None)` — sums are not proved here. + assert_eq!( + per_key, + dedicated + .into_iter() + .map(|(key, count)| (key, Some(count), None)) + .collect::>() + ); + assert_eq!( + per_key, + vec![ + (b"one".to_vec(), Some(2), None), + (b"two".to_vec(), Some(3), None), + ] + ); + } + other => panic!("expected AggregatePerKey, got {other:?}"), + } + } + + #[test] + fn aggregate_carrier_sum_verifies_through_the_unified_entry() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pst(&db, b"one", &[(b"a", 5), (b"b", -2)], grove_version); + build_pst(&db, b"two", &[(b"a", 11)], grove_version); + + let pq = carrier_path_query( + &[b"one", b"two"], + Query::new_aggregate_sum_on_range(full_range()), + ); + let proof = prove(&db, &pq, grove_version); + + let (dedicated_root, dedicated) = + GroveDb::verify_aggregate_sum_query_per_key(&proof, &pq, grove_version) + .expect("dedicated per-key sum verify"); + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("unified per-key sum verify") + { + VerifiedPathQuery::AggregatePerKey { root_hash, per_key } => { + assert_eq!(root_hash, dedicated_root); + // Sum carriers report `count = None`. + assert_eq!( + per_key, + dedicated + .into_iter() + .map(|(key, sum)| (key, None, Some(sum))) + .collect::>() + ); + assert_eq!( + per_key, + vec![ + (b"one".to_vec(), None, Some(3)), + (b"two".to_vec(), None, Some(11)), + ] + ); + } + other => panic!("expected AggregatePerKey, got {other:?}"), + } + } + + #[test] + fn aggregate_carrier_count_and_sum_verifies_through_the_unified_entry() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pcps(&db, b"one", &[(b"a", 7), (b"b", 3)], grove_version); + build_pcps(&db, b"two", &[(b"a", -4)], grove_version); + + let pq = carrier_path_query( + &[b"one", b"two"], + Query::new_aggregate_count_and_sum_on_range(full_range()), + ); + let proof = prove(&db, &pq, grove_version); + + let (dedicated_root, dedicated) = + GroveDb::verify_aggregate_count_and_sum_query_per_key(&proof, &pq, grove_version) + .expect("dedicated per-key combined verify"); + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("unified per-key combined verify") + { + VerifiedPathQuery::AggregatePerKey { root_hash, per_key } => { + assert_eq!(root_hash, dedicated_root); + assert_eq!( + per_key, + dedicated + .into_iter() + .map(|(key, count, sum)| (key, Some(count), Some(sum))) + .collect::>() + ); + assert_eq!( + per_key, + vec![ + (b"one".to_vec(), Some(2), Some(10)), + (b"two".to_vec(), Some(1), Some(-4)), + ] + ); + } + other => panic!("expected AggregatePerKey, got {other:?}"), + } + } + + // ----------------------------------------------------------------- + // Key selection, count-offset pagination, and the unproved shape + // ----------------------------------------------------------------- + + #[test] + fn count_offset_paginated_verifies_through_the_unified_entry() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pct(&db, b"pct", &[b"a", b"b", b"c", b"d"], grove_version); + + // A non-zero offset over a single range item is the count-offset + // paginated shape — a distinct classification from plain key + // selection, sharing the unified `Elements` arm. + let pq = PathQuery::new( + vec![TEST_LEAF.to_vec(), b"pct".to_vec()], + SizedQuery::new( + Query::new_single_query_item(QueryItem::RangeFull(..)), + Some(2), + Some(1), + ), + ); + let proof = prove(&db, &pq, grove_version); + + let (dedicated_root, dedicated) = + GroveDb::verify_query(&proof, &pq, grove_version).expect("dedicated verify"); + match GroveDb::verify_path_query(&proof, &pq, grove_version) + .expect("unified paginated verify") + { + VerifiedPathQuery::Elements { + root_hash, + elements, + } => { + assert_eq!(root_hash, dedicated_root); + assert_eq!(elements, dedicated); + assert_eq!(elements.len(), 2); + } + other => panic!("expected Elements, got {other:?}"), + } + } + + #[test] + fn sum_budget_path_queries_have_no_proof_form_yet() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pst(&db, b"pst", &[(b"a", 5), (b"b", 7)], grove_version); + + let pq = PathQuery::new_sum_budget( + vec![TEST_LEAF.to_vec(), b"pst".to_vec()], + vec![QueryItem::RangeFull(..)], + true, + 10, + None, + ); + + // The prover refuses by name... + match db.prove_query(&pq, None, grove_version).unwrap() { + Err(Error::NotSupported(message)) => { + assert!(message.contains("sum-budget"), "got: {message}") + } + other => panic!("sum-budget proving must be refused, got {other:?}"), + } + + // ...and so does the verifier, pointing at the trusted read + // rather than verifying the shape as key selection. + match GroveDb::verify_path_query(&[], &pq, grove_version) { + Err(Error::NotSupported(message)) => { + assert!(message.contains("run_path_query"), "got: {message}") + } + other => panic!("sum-budget verification must be refused, got {other:?}"), + } + } + + #[test] + fn root_hash_is_exposed_for_every_verified_shape() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_pct(&db, b"pct", &[b"a", b"b"], grove_version); + build_pst(&db, b"pst", &[(b"a", 5)], grove_version); + build_pcps(&db, b"pcps", &[(b"a", 7)], grove_version); + + let expected = db.root_hash(None, grove_version).unwrap().expect("root"); + + let mut verified = Vec::new(); + // Elements. + let pq = PathQuery::new_single_key(vec![TEST_LEAF.to_vec()], b"pct".to_vec()); + verified.push( + GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("key selection"), + ); + // Three aggregate leaves. + let pq = PathQuery::new_aggregate_count_on_range( + vec![TEST_LEAF.to_vec(), b"pct".to_vec()], + full_range(), + ); + verified.push( + GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("count leaf"), + ); + let pq = PathQuery::new_aggregate_sum_on_range( + vec![TEST_LEAF.to_vec(), b"pst".to_vec()], + full_range(), + ); + verified.push( + GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("sum leaf"), + ); + let pq = PathQuery::new_aggregate_count_and_sum_on_range( + vec![TEST_LEAF.to_vec(), b"pcps".to_vec()], + full_range(), + ); + verified.push( + GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("combined leaf"), + ); + // A carrier. + let pq = carrier_path_query(&[b"pct"], Query::new_aggregate_count_on_range(full_range())); + verified.push( + GroveDb::verify_path_query(&prove(&db, &pq, grove_version), &pq, grove_version) + .expect("count carrier"), + ); + + for shape in &verified { + assert_eq!( + shape.root_hash(), + &expected, + "every shape must expose the same reconstructed root: {shape:?}" + ); + } + } +} From 817148ad5a2625dbd91b4f7ea3b095b2514c35ed Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Fri, 14 Aug 2026 17:45:36 +0700 Subject: [PATCH 4/4] docs: state the per-axis meaning of RangeAggregate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The count axis is the one that reads wrong. "Aggregate over the entries in [lo, hi]" invites "total of their counts", but a count secondary aggregates by counting nodes, so the answer is the bucket POPULATION: over counts [3, 1, 5], the band [2, 10] answers 2, not 8. The sum axis does total its values, so the two axes genuinely differ and no single name covers both — the semantics have to be stated, per axis, wherever a caller meets the number. Stated at the three points where one does: the traversal variant, the `new_axis_range_aggregate` constructor, and the verified `AxisAggregate.value`. The `lo`/`hi` field docs now say they bound the entry's own axis value, not the aggregate being returned. Also fixes a book paragraph that filed `indexed_count_range_aggregate` under "Lookup of count for a key" and described it as a single primary-node read — that is a different operation entirely; the range aggregate walks the secondary. Co-Authored-By: Claude Opus 5 --- docs/book/src/count-indexed-tree.md | 18 ++++++--- grovedb-query/src/axis_query.rs | 38 +++++++++++++++---- .../src/operations/proof/verify_path_query.rs | 12 ++++-- grovedb/src/query/mod.rs | 13 +++++-- 4 files changed, 62 insertions(+), 19 deletions(-) diff --git a/docs/book/src/count-indexed-tree.md b/docs/book/src/count-indexed-tree.md index c9314a438..339660950 100644 --- a/docs/book/src/count-indexed-tree.md +++ b/docs/book/src/count-indexed-tree.md @@ -542,11 +542,19 @@ which is what `indexed_count_top_k(path, k, descending = true, ..)` produces. Ascending traversal is also supported for "smallest counts first" / "items with the lowest counts in [a, b]" patterns. -### Lookup of count for a key - -`indexed_count_range_aggregate(path, lo, hi, ..)` returns the count without returning the -value. It can be answered by reading the primary node's feature type -(which carries `count_value`). No secondary lookup needed; one Merk read. +### How many entries fall in a count band + +`indexed_count_range_aggregate(path, lo, hi, ..)` answers **how many +entries have a `count_value` in `[lo, hi]`** — a bucket population, in +which each matching entry contributes 1. It is *not* the total of those +entries' counts: over counts `[3, 1, 5]`, the band `[2, 10]` selects the +`3` and the `5` and answers `2`, not `8`. If you want the total, use +`indexed_count_range(path, lo, hi, ..)` to list the selected entries +with their counts and sum them caller-side. + +The walk folds each fully-contained subtree's stored aggregate in one +step and descends only along the two range boundaries, so the cost is +`O(log n)` with no term in the number of matching entries. ### Subqueries diff --git a/grovedb-query/src/axis_query.rs b/grovedb-query/src/axis_query.rs index 24401970a..fd043465d 100644 --- a/grovedb-query/src/axis_query.rs +++ b/grovedb-query/src/axis_query.rs @@ -177,21 +177,43 @@ pub enum AxisTraversal { /// The original (primary) key whose rank is requested. key: Vec, }, - /// A single aggregate over every entry whose aggregate value lies in - /// the inclusive `[lo, hi]` range. Count and Sum axes only — the - /// Avg axis has no meaningful sum-of-averages. + /// `[lo, hi]` selects the entries; the axis's own secondary + /// aggregate over exactly those entries is the answer. Count and + /// Sum axes only — the Avg axis has no meaningful + /// average-of-averages. + /// + /// **The aggregation differs per axis, and the count axis is the + /// one that reads wrong.** Each secondary aggregates the way its + /// own tree type does, so: + /// + /// * **Sum axis** — the answer is the TOTAL of the selected + /// entries' sums. `RangeAggregate { lo: 0, hi: 100 }` over sums + /// `[40, -10, 25]` selects `40` and `25` and answers `65`. + /// * **Count axis** — the answer is HOW MANY entries were + /// selected, each contributing 1. It is a bucket population, NOT + /// the total of their counts. `RangeAggregate { lo: 2, hi: 10 }` + /// over counts `[3, 1, 5]` selects the `3` and the `5` and + /// answers **2**, not 8. + /// + /// Reach for the count axis here to ask "how many entries fall in + /// this band?". There is no traversal that totals the counts in a + /// band — [`Self::Bounded`] lists the selected entries with their + /// values, and the caller sums them. /// /// **Cost** — `O(log n)` in every case. The walk classifies each /// subtree as fully Contained, Disjoint, or Partial and folds a /// Contained subtree's stored aggregate in one step, descending /// only along the two range boundaries. **No term in the number of - /// matched entries** — summing a million in-range entries costs - /// what summing one costs, which is what makes this preferable to - /// [`Self::Bounded`] whenever only the total is wanted. + /// matched entries** — aggregating a million in-range entries costs + /// what aggregating one costs, which is what makes this preferable + /// to [`Self::Bounded`] whenever only the total is wanted. RangeAggregate { - /// Inclusive lower bound on the aggregate. + /// Inclusive lower bound on the entry's own axis VALUE (its + /// count on the count axis, its sum on the sum axis) — not on + /// the aggregate this traversal returns. lo: i128, - /// Inclusive upper bound on the aggregate. + /// Inclusive upper bound on the entry's own axis value. See + /// [`Self::RangeAggregate::lo`]. hi: i128, }, } diff --git a/grovedb/src/operations/proof/verify_path_query.rs b/grovedb/src/operations/proof/verify_path_query.rs index 72bd72f0b..a080771d3 100644 --- a/grovedb/src/operations/proof/verify_path_query.rs +++ b/grovedb/src/operations/proof/verify_path_query.rs @@ -100,12 +100,18 @@ pub enum VerifiedPathQuery { /// The attested rank. rank: u64, }, - /// `RangeAggregate`: the attested aggregate over the value range. + /// `RangeAggregate`: the attested aggregate over the entries the + /// value range selected. AxisAggregate { /// Reconstructed GroveDB root hash. root_hash: CryptoHash, - /// The attested aggregate: a count (`>= 0`) for the count axis, - /// a signed sum for the sum axis. + /// The attested aggregate, whose meaning follows the queried + /// axis: on the **sum** axis the signed TOTAL of the selected + /// entries' sums; on the **count** axis HOW MANY entries the + /// range selected (`>= 0`, each entry contributing 1) — a + /// bucket population, not the total of their counts. The query + /// names the axis, so the caller already knows which reading + /// applies. value: i128, }, } diff --git a/grovedb/src/query/mod.rs b/grovedb/src/query/mod.rs index f1e40e116..6e4a78398 100644 --- a/grovedb/src/query/mod.rs +++ b/grovedb/src/query/mod.rs @@ -619,9 +619,16 @@ impl PathQuery { ) } - /// A single aggregate over every entry of the indexed tree at - /// `path` whose `axis` value is in the inclusive `[lo, hi]`. - /// Count and Sum axes only. + /// `[lo, hi]` selects the entries of the indexed tree at `path` by + /// their own `axis` value; the answer is that axis's aggregate over + /// exactly those entries. Count and Sum axes only. + /// + /// The two axes aggregate differently — on the **sum** axis the + /// answer is the total of the selected sums, on the **count** axis + /// it is how many entries were selected (a bucket population), not + /// the total of their counts. See + /// [`AxisTraversal::RangeAggregate`](grovedb_query::AxisTraversal::RangeAggregate) + /// for worked examples of both. pub fn new_axis_range_aggregate( path: Vec>, axis: IndexAxis,