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-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/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/generate.rs b/grovedb/src/operations/proof/generate.rs index 90bd8ae2a..daecc88f0 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 \ @@ -1355,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) } @@ -1958,6 +2047,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..1205e85c0 100644 --- a/grovedb/src/operations/proof/indexed_axis/envelope.rs +++ b/grovedb/src/operations/proof/indexed_axis/envelope.rs @@ -178,6 +178,26 @@ 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]> { + 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..ff08ea4a4 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,258 @@ 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::RankedPage { 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, .. } => { + // 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 => { + // 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..5dab15177 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,316 @@ 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::RankedPage { 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, .. } => { + 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 => { + 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 +1120,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, @@ -828,6 +1217,73 @@ impl GroveDb { verified_keys.insert(key.clone()); + // 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: + // + // * 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) { // MmrTree/BulkAppendTree have root_key=None (no child Merk data), // so they match on (..) rather than (Some(_), ..) @@ -848,6 +1304,10 @@ 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(); if query.query_items_at_path(&path, grove_version)?.is_none() { @@ -1007,6 +1467,7 @@ impl GroveDb { limit_left, &path, result, + axis_outcomes, last_parent_tree_type, options, current_depth + 1, @@ -1143,6 +1604,7 @@ impl GroveDb { limit_left, &path, result, + axis_outcomes, last_parent_tree_type, options, current_depth + 1, @@ -1199,7 +1661,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..a080771d3 --- /dev/null +++ b/grovedb/src/operations/proof/verify_path_query.rs @@ -0,0 +1,430 @@ +//! 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 entries the + /// value range selected. + AxisAggregate { + /// Reconstructed GroveDB root hash. + root_hash: CryptoHash, + /// 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, + }, +} + +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 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)| { + 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( + 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(), + )); + } + // 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, + }) + } + 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::RankedPage { .. } | 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..6e4a78398 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}, @@ -618,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, @@ -1206,6 +1214,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.as_deref() { + 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..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( @@ -421,8 +437,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..4c77b2f82 --- /dev/null +++ b/grovedb/src/tests/axis_descent_proof_tests.rs @@ -0,0 +1,1403 @@ +//! 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"); + } + + #[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 + // ----------------------------------------------------------------- + + #[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") + } + + // ----------------------------------------------------------------- + // 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 99271cf18..756c04561 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; @@ -95,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/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] 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:?}" + ); + } + } +}