From 4d12666f00c1f0129398a36587c0604d93a47db6 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Tue, 15 Sep 2026 05:15:41 +0700 Subject: [PATCH] fix: answer a single-path axis read over an absent path with the empty result A single-path axis read (`PathQuery::new_axis*`) whose path did not exist failed on every surface: the trusted reader with a storage error, and the prover with an explicit refusal ("a single-path axis read must produce exactly one axis descent"), so the verifier never saw such a proof. Key selection and the branched axis shape already answer an absent path with an authenticated empty result; the single-path axis read was the one provable shape that could not, which made a ranking over a window nothing had been written to yet (a fresh time-range bucket, a prefix value nobody has used) unanswerable rather than empty. Absence was always provable here. The generic walk emits the layers that authenticate it: the parent of the missing segment proves the key absent through its single-key Merk proof, an empty ancestor is bound to NULL_HASH, every present non-empty tree on the path must carry its lower layer, and a present axis position must be an indexed tree with an axis layer. So zero axis layers in a verified walk can only mean the path does not exist, or (surfaced as a row) that a non-tree element blocks it. Now: - the verifier reads zero axis layers as the traversal's empty answer: no entries and `skipped: Some(0)` for a ranked page (the population is zero), no entries and `None` for a bounded walk, `0` for a value-range aggregate; a present non-tree row on the path is rejected; - the prover settles the same question against its own snapshot before handing the proof out: an absent path yields the proof, a present path that does not lead to an indexed tree is still refused; - the trusted reader probes the path the way the branched arm already does and returns the same empty answer for an absent path; - `RankOfKey`, which has no empty answer, fails over an absent path on every surface exactly as it does for a key absent from a present tree. `AxisKeys::empty_for_axis` is new, mirroring `AxisEntries::empty_for_axis`. Tests: absent last segment, absent intermediate segment and an empty-tree ancestor round-trip empty through the reader, the prover and the verifier for ranked, bounded and both aggregate folds, with rank-of-key refused; an absence proof covers exactly its Merk gap (a key inside the gap verifies absent, a key past a hashed-out subtree does not, and the present tree next to it does not); stripping a present indexed tree's axis layer, populated or empty, is still rejected rather than read as absence; a present non-indexed target and a path through an item are still refused by prover and reader. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 13 + docs/book/src/unified-path-query.md | 21 +- grovedb/src/operations/get/run_path_query.rs | 80 ++++ grovedb/src/operations/proof/generate.rs | 117 +++++- .../src/operations/proof/verify_path_query.rs | 110 +++++- grovedb/src/query_result_type.rs | 9 + grovedb/src/tests/axis_descent_proof_tests.rs | 351 +++++++++++++++++- 7 files changed, 666 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d61090029..87b14c1d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed +- Single-path axis reads (`PathQuery::new_axis*`) over a path that does not + exist — a missing segment, or an empty tree above one — now answer with the + traversal's empty result (no entries and `skipped: Some(0)` for a ranked + page, `None` for a bounded walk, `0` for a value-range aggregate) on + `run_path_query`, `prove_query` and `verify_path_query` alike, matching + key selection and the branched axis shape. Previously the trusted read + failed with a storage error and the prover refused to generate ("must + produce exactly one axis descent"), so a ranking over a window nothing had + been written to yet was unanswerable. A path that is present but does not + lead to an indexed tree is still refused, and `RankOfKey` still fails over + an absent path. `AxisKeys::empty_for_axis` is new. (#965) + ## [6.0.1] - 2026-09-13 GroveDB 6.0.1 is the 6.0 release to depend on. It supersedes 6.0.0, which is diff --git a/docs/book/src/unified-path-query.md b/docs/book/src/unified-path-query.md index 8ebd283f4..f1c16d308 100644 --- a/docs/book/src/unified-path-query.md +++ b/docs/book/src/unified-path-query.md @@ -199,7 +199,15 @@ merged union. Branched reads mirror the proof's absence semantics: a branch key — or any suffix segment under it — that does not exist yields `None` for -that branch rather than failing the whole read. +that branch rather than failing the whole read. A single-path axis read +over a path that does not exist — a missing segment, or an empty tree +above one — likewise answers with the traversal's empty result: no +entries and `skipped: Some(0)` for a ranked page (the population is +zero), no entries and `None` for a bounded walk, `0` for a value-range +aggregate. The trusted read and the proof agree on it; only `RankOfKey`, +which has no empty answer, fails as it does for a key absent from a +present tree. A path that exists but does not lead to an indexed tree +carrying the axis is still an error on both sides. ## One verify entry point: `verify_path_query` @@ -265,6 +273,17 @@ while omitting its axis layer is rejected — hiding entries behind fake absence fails closed — and an axis-read position with a missing lower layer is a hard error, never a silent absence. +A single-path read whose walk verifies with **zero** axis layers is the +absent-path case, and the layers that were emitted are what +authenticate it: every present non-empty tree on the path had to carry +its lower layer, an empty ancestor is bound to `NULL_HASH`, and the +parent of the missing segment proves that key absent through its +single-key Merk proof. The verifier then returns the traversal's empty +answer (a present non-tree element on the path, which the walk surfaces +as a row, is rejected instead). The prover settles the same question +against its own snapshot before handing the proof out, and refuses when +the path is present but does not lead to an indexed tree. + ### Sum-budget windows (`ProofBytes::SumBudgetWindow`) A sum-budget proof is an ordinary Merk proof over exactly the window of diff --git a/grovedb/src/operations/get/run_path_query.rs b/grovedb/src/operations/get/run_path_query.rs index 83e808da1..f6e90ae41 100644 --- a/grovedb/src/operations/get/run_path_query.rs +++ b/grovedb/src/operations/get/run_path_query.rs @@ -224,11 +224,42 @@ impl GroveDb { } }, PathQueryShape::AxisRead { axis } => { + // Mirror the proof's absence semantics (and the branched + // arm's per-branch probe): a queried path that does not + // exist — a missing segment, or an empty tree above one + // — answers with the traversal's empty result rather + // than a storage error, exactly what the prover hands + // out and the verifier accepts for that state. The probe + // is one raw read per segment; the axis primitives then + // run only over a path known to exist, so the remaining + // errors are about the element's kind, never its + // absence. let path_refs: Vec<&[u8]> = path_query .path .iter() .map(|segment| segment.as_slice()) .collect(); + let mut resolved: Vec<&[u8]> = Vec::with_capacity(path_refs.len()); + for segment in &path_refs { + let present = cost_return_on_error!( + &mut cost, + self.get_raw_optional( + SubtreePath::from(resolved.as_slice()), + segment, + transaction, + grove_version, + ) + ); + match present { + None => return Self::absent_axis_run(axis).wrap_with_cost(cost), + // A present non-tree element part-way down: the + // path is not absent, it is the wrong kind, and + // the primitive below reports that — the same + // verdict the prover reaches. + Some(element) if !element.is_any_tree() => break, + Some(_) => resolved.push(segment), + } + } self.run_axis_read(path_refs.as_slice(), axis, transaction, grove_version) .add_cost(cost) } @@ -358,9 +389,58 @@ impl GroveDb { } } + /// The empty answer of a single-path axis read over a path that does + /// not exist, per traversal: no entries and a zero skip for a ranked + /// page (the population is zero), no entries and no skip for a + /// bounded walk, a zero aggregate for a value-range aggregate. A + /// rank-of-key read has no empty answer — the key has no rank in a + /// tree that does not exist — and fails as it does for a key absent + /// from a present tree. The same mapping the verifier applies to a + /// proof with zero axis layers. + fn absent_axis_run( + axis_query: &grovedb_merk::proofs::query::AxisQuery, + ) -> Result { + let axis = axis_query.axis; + let keys_only = axis_query.projection == AxisProjection::Keys; + let empty_page = |skipped: Option| { + if keys_only { + PathQueryRun::AxisKeys { + keys: AxisKeys::empty_for_axis(axis), + skipped, + } + } else { + PathQueryRun::AxisEntries { + entries: AxisEntries::empty_for_axis(axis), + skipped, + } + } + }; + match &axis_query.traversal { + AxisTraversal::RankedPage { .. } => Ok(empty_page(Some(0))), + AxisTraversal::Bounded { .. } => Ok(empty_page(None)), + AxisTraversal::RankOfKey { .. } => Err(Error::PathKeyNotFound( + "indexed-axis rank: the queried path does not exist, so the key has no rank" + .to_string(), + )), + AxisTraversal::AggregateOverValueRange { fold, .. } => match (axis, fold) { + (IndexAxis::Count | IndexAxis::Sum, AggregateFold::Population) => Ok( + PathQueryRun::AxisAggregate(AxisAggregateValue::Population(0)), + ), + (IndexAxis::Count | IndexAxis::Sum, AggregateFold::Total) => { + Ok(PathQueryRun::AxisAggregate(AxisAggregateValue::Total(0))) + } + // classify rejects value-range aggregates on the Avg axis. + (IndexAxis::Avg, _) => Err(Error::CorruptedCodeExecution( + "value-range aggregate on the Avg axis survived classification", + )), + }, + } + } + /// Single-path axis read: route one validated /// [`AxisQuery`](grovedb_merk::proofs::query::AxisQuery) to the /// indexed-tree primitive that serves its `(axis, traversal)` pair. + /// The caller has established that `path` exists. fn run_axis_read( &self, path: &[&[u8]], diff --git a/grovedb/src/operations/proof/generate.rs b/grovedb/src/operations/proof/generate.rs index a83155734..e8d706b11 100644 --- a/grovedb/src/operations/proof/generate.rs +++ b/grovedb/src/operations/proof/generate.rs @@ -11,11 +11,16 @@ use grovedb_costs::{ use grovedb_dense_fixed_sized_merkle_tree::DenseTreeProof; use grovedb_merk::{ element::ElementExt, - proofs::{encode_into, query::QueryItem, Node, Op}, + proofs::{ + encode_into, + query::{AxisTraversal, QueryItem}, + Node, Op, + }, tree::{combine_hash, value_hash, NULL_HASH}, Merk, ProofWithoutEncodingResult, TreeFeatureType, }; use grovedb_merkle_mountain_range::MmrTreeProof; +use grovedb_path::SubtreePath; use grovedb_storage::{Storage, StorageContext}; use grovedb_version::{ check_grovedb_v0_or_v1_with_cost, check_grovedb_v0_with_cost, version::GroveVersion, @@ -1754,18 +1759,32 @@ 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. + // descent at the queried path — or, when that path does not + // exist, the empty answer for its traversal. The generic walk + // produces no descent in two states that must not be confused: + // + // * the path is ABSENT (a segment is missing, or an empty tree + // sits above one). The layers the walk did emit authenticate + // that — the parent of the missing segment proves its key + // absent through the single-key Merk proof, an empty + // ancestor is bound to `NULL_HASH` — and the verifier reads + // zero axis layers as the empty answer. "Nothing ranked at + // this path yet" is a legitimate answer, so the proof is + // handed out; + // * the path is PRESENT but names something other than an + // indexed tree carrying that axis. No proof can answer an + // axis read there, so generation fails rather than handing + // out a proof the verifier can only reject. + // + // Told apart against the same snapshot the proof was built + // from. A rank-of-key read has no empty answer (the key has no + // rank in a tree that does not exist), so it fails over an + // absent path exactly as the trusted read does. // // 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!(validated.shape(), PathQueryShape::AxisRead { .. }) { + if let PathQueryShape::AxisRead { axis } = validated.shape() { fn count_axis_descents(layer: &LayerProof) -> usize { usize::from(matches!( layer.merk_proof, @@ -1776,20 +1795,84 @@ impl GroveDb { .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); + match count_axis_descents(&root_layer) { + 1 => {} + 0 => { + let path_present = cost_return_on_error!( + &mut cost, + self.path_is_present( + &path_query.path, + &snapshot_transaction, + grove_version + ) + ); + if path_present { + return Err(Error::InvalidPath( + "a single-path axis read must produce exactly one axis descent \ + at the queried path, but the walk produced 0 — the path is \ + present but does not lead to an indexed tree carrying that axis" + .to_string(), + )) + .wrap_with_cost(cost); + } + if matches!(axis.traversal, AxisTraversal::RankOfKey { .. }) { + return Err(Error::PathKeyNotFound( + "indexed-axis rank: the queried path does not exist, so the key \ + has no rank" + .to_string(), + )) + .wrap_with_cost(cost); + } + } + descents => { + 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}" + ))) + .wrap_with_cost(cost); + } } } Ok(GroveDBProof::V1(GroveDBProofV1 { root_layer })).wrap_with_cost(cost) } + /// Whether `path` leads to a present element, read under + /// `transaction`. `false` as soon as a segment is missing — + /// including below an empty tree, whose (empty) Merk holds no key — + /// which is exactly the state whose absence the generic proof walk + /// authenticates. A present non-tree element part-way down the path + /// counts as present: nothing can be absent below it, and the walk + /// surfaces it as a row the verifier refuses rather than reads as + /// absence. Mirrors the trusted reader's chain probe, so the + /// prover's "absent path" and the reader's agree. + fn path_is_present( + &self, + path: &[Vec], + transaction: &Transaction, + grove_version: &GroveVersion, + ) -> CostResult { + let mut cost = OperationCost::default(); + let mut resolved: Vec<&[u8]> = Vec::with_capacity(path.len()); + for segment in path { + let present = cost_return_on_error!( + &mut cost, + self.get_raw_optional( + SubtreePath::from(resolved.as_slice()), + segment, + Some(transaction), + grove_version, + ) + ); + match present { + None => return Ok(false).wrap_with_cost(cost), + Some(element) if !element.is_any_tree() => return Ok(true).wrap_with_cost(cost), + Some(_) => resolved.push(segment.as_slice()), + } + } + Ok(true).wrap_with_cost(cost) + } + /// Compute the 32-byte secondary attestation that an indexed-tree element /// commits to as the third input of its parent's `combine_hash_three`. /// diff --git a/grovedb/src/operations/proof/verify_path_query.rs b/grovedb/src/operations/proof/verify_path_query.rs index 9e85b3abb..8c120f2f1 100644 --- a/grovedb/src/operations/proof/verify_path_query.rs +++ b/grovedb/src/operations/proof/verify_path_query.rs @@ -16,7 +16,10 @@ //! Key-selection and aggregate shapes route to the existing verifiers //! unchanged. -use grovedb_merk::{proofs::query::AxisTraversal, CryptoHash}; +use grovedb_merk::{ + proofs::query::{AxisQuery, AxisTraversal}, + CryptoHash, +}; use grovedb_version::version::GroveVersion; use crate::{ @@ -240,19 +243,31 @@ impl GroveDb { } }, PathQueryShape::AxisRead { axis } => { - let (root_hash, _, outcomes) = + let (root_hash, trios, outcomes) = Self::verify_axis_shape_walk(proof, &validated, grove_version)?; - let [outcome]: [AxisWalkOutcome; 1] = - outcomes.try_into().map_err(|outcomes: Vec<_>| { - Error::InvalidProof( + let outcome = match <[AxisWalkOutcome; 1]>::try_from(outcomes) { + Ok([outcome]) => outcome, + // No axis layer at all: the walk authenticated that + // the queried path does not exist, and the answer + // is the traversal's empty one. See + // `absent_axis_path_into_verified` for why zero + // layers can mean nothing else. + Err(outcomes) if outcomes.is_empty() => { + return Self::absent_axis_path_into_verified( + root_hash, axis, &trios, path_query, + ); + } + Err(outcomes) => { + return Err(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(), @@ -436,6 +451,87 @@ impl GroveDb { Self::verify_proof_v1_with_axis_outcomes(&proof_v1, validated.query(), grove_version) } + /// The answer of a single-path axis read whose walk verified with + /// **no** axis layer: the queried path does not exist, and the + /// traversal's empty answer is what the proof authenticates. + /// + /// Zero layers can mean nothing else. The walk fails closed on every + /// other way of reaching the end without an axis layer: a present + /// non-empty tree on the path must carry its lower layer, the + /// axis-read position itself must be an indexed tree with an axis + /// layer (a non-indexed element or a missing layer is a hard error, + /// never a silent absence), and a present-but-empty ancestor is + /// bound to `NULL_HASH` so a populated tree cannot be rewritten as + /// empty to hide the descent. What remains is a path segment the + /// parent's single-key Merk proof authenticated as absent — or an + /// empty ancestor below which nothing can exist — and that is the + /// prover's "absent path" too (`GroveDb::path_is_present` decides + /// it against the proof's own snapshot before the proof is handed + /// out). The one state the walk reports instead of refusing — a + /// present non-tree element somewhere on the path, surfaced as a + /// result row — is rejected here: an axis read has no meaning + /// under an item, and the prover refuses to generate it. + /// + /// Only entry-listing and aggregate traversals have an empty answer. + /// A rank-of-key read does not (the key has no rank in a tree that + /// does not exist), so it is rejected exactly as the prover and the + /// trusted read refuse it. + fn absent_axis_path_into_verified( + root_hash: CryptoHash, + axis: &AxisQuery, + trios: &[PathKeyOptionalElementTrio], + path_query: &PathQuery, + ) -> Result { + let on_the_queried_path = |trio_path: &[Vec], trio_key: &[u8]| { + trio_path.len() < path_query.path.len() + && path_query.path[..trio_path.len()] == *trio_path + && path_query.path[trio_path.len()] == *trio_key + }; + if let Some((trio_path, trio_key, _)) = + trios.iter().find(|(trio_path, trio_key, element)| { + element.is_some() && on_the_queried_path(trio_path, trio_key) + }) + { + return Err(Error::InvalidProof( + path_query.clone(), + format!( + "the queried path runs through a present non-tree element at {}/{}; an \ + axis read has no meaning there, so the path is not absent and the \ + proof cannot answer the query", + trio_path + .iter() + .map(hex::encode) + .collect::>() + .join("/"), + hex::encode(trio_key), + ), + )); + } + match &axis.traversal { + AxisTraversal::RankedPage { .. } => Ok(VerifiedPathQuery::AxisEntries { + root_hash, + entries: AxisEntries::empty_for_axis(axis.axis), + skipped: Some(0), + }), + AxisTraversal::Bounded { .. } => Ok(VerifiedPathQuery::AxisEntries { + root_hash, + entries: AxisEntries::empty_for_axis(axis.axis), + skipped: None, + }), + AxisTraversal::AggregateOverValueRange { .. } => Ok(VerifiedPathQuery::AxisAggregate { + root_hash, + value: 0, + }), + AxisTraversal::RankOfKey { .. } => Err(Error::InvalidProof( + path_query.clone(), + "a rank-of-key axis read has no answer over an absent path: the key has no \ + rank in a tree that does not exist, and the prover refuses to generate such \ + a proof" + .to_string(), + )), + } + } + /// Map a single-path axis outcome into the public result, checking /// the outcome family matches the traversal. fn outcome_into_verified( diff --git a/grovedb/src/query_result_type.rs b/grovedb/src/query_result_type.rs index ef872fa23..4ca9fdd06 100644 --- a/grovedb/src/query_result_type.rs +++ b/grovedb/src/query_result_type.rs @@ -80,6 +80,15 @@ pub enum AxisKeys { } impl AxisKeys { + /// An empty pair 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 => AxisKeys::Count(Vec::new()), + grovedb_element::indexed::IndexAxis::Sum => AxisKeys::Sum(Vec::new()), + grovedb_element::indexed::IndexAxis::Avg => AxisKeys::Avg(Vec::new()), + } + } + /// Number of pairs. pub fn len(&self) -> usize { match self { diff --git a/grovedb/src/tests/axis_descent_proof_tests.rs b/grovedb/src/tests/axis_descent_proof_tests.rs index 8080b4664..db108c817 100644 --- a/grovedb/src/tests/axis_descent_proof_tests.rs +++ b/grovedb/src/tests/axis_descent_proof_tests.rs @@ -1345,29 +1345,41 @@ mod tests { // ----------------------------------------------------------------- #[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. + fn a_single_path_axis_read_over_a_present_non_indexed_target_fails_generation() { + // The generic walk produces no axis descent when the queried + // path leads to something other than 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. (An ABSENT path is different: it + // has an empty answer, see + // `a_single_path_axis_read_over_an_absent_path_answers_empty_everywhere`.) let grove_version = GroveVersion::latest(); let db = make_test_grovedb(grove_version); build_psit(&db, grove_version, PSIT_ENTRIES); + db.insert( + [TEST_LEAF].as_ref(), + b"item", + Element::new_item(b"v".to_vec()), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert item"); // 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()], + // ...and a path that runs through an item. + let through_item = PathQuery::new_axis_top_k( + vec![TEST_LEAF.to_vec(), b"item".to_vec(), b"psit".to_vec()], IndexAxis::Sum, 2, 0, true, ); - for pq in [plain_target, missing_target] { + for pq in [plain_target, through_item] { match db.prove_query(&pq, None, grove_version).unwrap() { Err(Error::InvalidPath(message)) => assert!( message.contains("exactly one axis descent"), @@ -1375,6 +1387,325 @@ mod tests { ), other => panic!("an axis read with no indexed target must be refused: {other:?}"), } + // The trusted read agrees: a present non-indexed target is an + // error, not an empty page. + assert!( + db.run_path_query( + &pq, + true, + true, + true, + crate::query_result_type::QueryResultType::QueryKeyElementPairResultType, + None, + grove_version, + ) + .unwrap() + .is_err(), + "the trusted read must refuse an axis read over a present non-indexed target" + ); + } + } + + /// A single-path axis read over a path that does not exist — a + /// missing last segment, a missing intermediate segment, or an + /// empty tree above the would-be target — is a question with an + /// answer: nothing is ranked there. The trusted read returns the + /// traversal's empty result, the prover hands out a proof whose + /// layers authenticate the absence, and the verifier reconstructs + /// the live root hash from it. The one traversal without an empty + /// answer, rank-of-key, fails on both sides exactly as it does for + /// a key absent from a present tree. + #[test] + fn a_single_path_axis_read_over_an_absent_path_answers_empty_everywhere() { + use crate::operations::get::{AxisAggregateValue, PathQueryRun}; + use crate::query_result_type::QueryResultType; + + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + db.insert( + [TEST_LEAF].as_ref(), + b"hollow", + Element::empty_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert empty tree"); + let live_root = root_hash(&db, grove_version); + + let read = |pq: &PathQuery| { + db.run_path_query( + pq, + true, + true, + true, + QueryResultType::QueryKeyElementPairResultType, + None, + grove_version, + ) + .unwrap() + }; + + let absent_paths: [(&str, Vec>); 3] = [ + ( + "missing last segment", + vec![TEST_LEAF.to_vec(), b"ghost".to_vec()], + ), + ( + "missing intermediate segment", + vec![TEST_LEAF.to_vec(), b"ghost".to_vec(), b"psit".to_vec()], + ), + ( + "empty ancestor", + vec![TEST_LEAF.to_vec(), b"hollow".to_vec(), b"psit".to_vec()], + ), + ]; + for (label, path) in absent_paths { + // Ranked page: no entries, and a ZERO skip — the population is + // zero, so the requested offset of 1 could not be skipped. + let page = PathQuery::new_axis_top_k(path.clone(), IndexAxis::Sum, 3, 1, true); + match read(&page).expect(label) { + PathQueryRun::AxisEntries { entries, skipped } => { + assert!(entries.is_empty(), "{label}: read entries"); + assert_eq!(skipped, Some(0), "{label}: read skip"); + } + other => panic!("{label}: expected AxisEntries, got {other:?}"), + } + let keys_only = PathQuery::new_axis( + path.clone(), + AxisQuery::top_k(IndexAxis::Sum, 3, 1, true).keys_only(), + ); + match read(&keys_only).expect(label) { + PathQueryRun::AxisKeys { keys, skipped } => { + assert!(keys.is_empty(), "{label}: read keys"); + assert_eq!(skipped, Some(0), "{label}: keys-only read skip"); + } + other => panic!("{label}: expected AxisKeys, got {other:?}"), + } + let proof = prove(&db, &page, grove_version); + match GroveDb::verify_path_query(&proof, &page, grove_version) + .unwrap_or_else(|e| panic!("{label}: absent-path page proof verifies: {e}")) + { + VerifiedPathQuery::AxisEntries { + root_hash, + entries, + skipped, + } => { + assert_eq!(root_hash, live_root, "{label}: page root"); + assert!(entries.is_empty(), "{label}: verified entries"); + assert_eq!(skipped, Some(0), "{label}: verified skip"); + } + other => panic!("{label}: expected AxisEntries, got {other:?}"), + } + + // Bounded: no entries, no skip. + let bounded = + PathQuery::new_axis_bounded(path.clone(), IndexAxis::Sum, -100, 100, 5, false); + match read(&bounded).expect(label) { + PathQueryRun::AxisEntries { entries, skipped } => { + assert!(entries.is_empty(), "{label}: bounded read entries"); + assert_eq!(skipped, None, "{label}: bounded read skip"); + } + other => panic!("{label}: expected AxisEntries, got {other:?}"), + } + let proof = prove(&db, &bounded, grove_version); + match GroveDb::verify_path_query(&proof, &bounded, grove_version) + .unwrap_or_else(|e| panic!("{label}: absent-path bounded proof verifies: {e}")) + { + VerifiedPathQuery::AxisEntries { + root_hash, + entries, + skipped, + } => { + assert_eq!(root_hash, live_root, "{label}: bounded root"); + assert!(entries.is_empty(), "{label}: verified bounded entries"); + assert_eq!(skipped, None, "{label}: verified bounded skip"); + } + other => panic!("{label}: expected AxisEntries, got {other:?}"), + } + + // Value-range aggregates: zero, under either fold. + for (fold, expected) in [ + (AggregateFold::Total, AxisAggregateValue::Total(0)), + (AggregateFold::Population, AxisAggregateValue::Population(0)), + ] { + let aggregate = PathQuery::new_axis_aggregate_over_value_range( + path.clone(), + IndexAxis::Sum, + -100, + 100, + fold, + ); + match read(&aggregate).expect(label) { + PathQueryRun::AxisAggregate(value) => { + assert_eq!(value, expected, "{label}: {fold:?} read"); + } + other => panic!("{label}: expected AxisAggregate, got {other:?}"), + } + let proof = prove(&db, &aggregate, grove_version); + match GroveDb::verify_path_query(&proof, &aggregate, grove_version) + .unwrap_or_else(|e| panic!("{label}: absent-path {fold:?} proof verifies: {e}")) + { + VerifiedPathQuery::AxisAggregate { root_hash, value } => { + assert_eq!(root_hash, live_root, "{label}: {fold:?} root"); + assert_eq!(value, 0, "{label}: verified {fold:?}"); + } + other => panic!("{label}: expected AxisAggregate, got {other:?}"), + } + } + + // Rank of key: no empty answer, so both sides fail — with the + // same error a key absent from a present tree gets. + let rank = PathQuery::new_axis_rank_of_key( + path.clone(), + IndexAxis::Sum, + b"alice".to_vec(), + true, + ); + assert!( + matches!(read(&rank), Err(Error::PathKeyNotFound(_))), + "{label}: rank-of-key read over an absent path must fail as key-not-found" + ); + assert!( + matches!( + db.prove_query(&rank, None, grove_version).unwrap(), + Err(Error::PathKeyNotFound(_)) + ), + "{label}: rank-of-key proof over an absent path must be refused" + ); + } + } + + /// An absent-path proof authenticates absence the way any Merk + /// absence proof does: the parent layer proves the GAP the missing + /// segment falls into, so the same bytes also verify another key in + /// that gap absent (which it truly is) — and verify nothing outside + /// it: neither a key past the gap nor the present indexed tree next + /// to it. + #[test] + fn an_absent_path_proof_covers_only_its_own_gap() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + // Enough siblings that a single-key proof no longer carries the + // whole tree: far subtrees are hashed out, so a key in one of + // them is NOT covered. (Over a tiny tree the proof includes every + // node and honestly proves every absent key.) + for i in 0..64u8 { + db.insert( + [TEST_LEAF].as_ref(), + format!("k{i:02}").as_bytes(), + Element::new_item(vec![i]), + None, + None, + grove_version, + ) + .unwrap() + .expect("insert filler item"); + } + + let ghost = PathQuery::new_axis_top_k( + vec![TEST_LEAF.to_vec(), b"ghost".to_vec()], + IndexAxis::Sum, + 2, + 0, + true, + ); + let proof = prove(&db, &ghost, grove_version); + GroveDb::verify_path_query(&proof, &ghost, grove_version) + .expect("the absent-path proof verifies for its own query"); + + // `ghosu` sits in the same gap as `ghost` — the proof genuinely + // covers it, so it verifies absent too. + let same_gap = PathQuery::new_axis_top_k( + vec![TEST_LEAF.to_vec(), b"ghosu".to_vec()], + IndexAxis::Sum, + 2, + 0, + true, + ); + match GroveDb::verify_path_query(&proof, &same_gap, grove_version) + .expect("a key inside the proven gap is proven absent by the same bytes") + { + VerifiedPathQuery::AxisEntries { entries, .. } => assert!(entries.is_empty()), + other => panic!("expected AxisEntries, got {other:?}"), + } + + // `zzz` lies past `psit`, outside the proven gap. + let past_the_gap = PathQuery::new_axis_top_k( + vec![TEST_LEAF.to_vec(), b"zzz".to_vec()], + IndexAxis::Sum, + 2, + 0, + true, + ); + GroveDb::verify_path_query(&proof, &past_the_gap, grove_version) + .expect_err("an absence proof for `ghost` must not verify a key outside its gap"); + + let present = PathQuery::new_axis_top_k(psit_path(), IndexAxis::Sum, 2, 0, true); + GroveDb::verify_path_query(&proof, &present, grove_version) + .expect_err("an absence proof must not verify the present tree's ranking as empty"); + } + + /// Accepting zero axis layers as absence must not open a way to hide + /// a present tree: stripping the axis layer of a present indexed + /// tree — populated or empty — from an honest single-path proof is + /// rejected, never read as an empty page. + #[test] + fn stripping_a_single_path_axis_layer_is_rejected_not_read_as_absence() { + let grove_version = GroveVersion::latest(); + let db = make_test_grovedb(grove_version); + build_psit(&db, grove_version, PSIT_ENTRIES); + db.insert( + [TEST_LEAF].as_ref(), + b"vacant", + Element::empty_provable_sum_indexed_tree(), + None, + None, + grove_version, + ) + .unwrap() + .expect("create empty PSIT"); + + 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)) + } + let config = bincode::config::standard().with_big_endian(); + for (label, key) in [ + ("populated", b"psit".as_slice()), + ("empty", b"vacant".as_slice()), + ] { + let pq = PathQuery::new_axis_top_k( + vec![TEST_LEAF.to_vec(), key.to_vec()], + IndexAxis::Sum, + 2, + 0, + true, + ); + let proof = prove(&db, &pq, grove_version); + GroveDb::verify_path_query(&proof, &pq, grove_version) + .unwrap_or_else(|e| panic!("{label}: honest proof verifies: {e}")); + + 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"); + }; + assert!( + strip_key(&mut v1.root_layer, key), + "{label}: axis layer stripped" + ); + let tampered = bincode::encode_to_vec(&decoded, config).expect("re-encode"); + GroveDb::verify_path_query(&tampered, &pq, grove_version) + .expect_err("hiding a present indexed tree behind fake absence must be rejected"); } }