Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 20 additions & 1 deletion docs/book/src/unified-path-query.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -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
Expand Down
80 changes: 80 additions & 0 deletions grovedb/src/operations/get/run_path_query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down Expand Up @@ -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<PathQueryRun, Error> {
let axis = axis_query.axis;
let keys_only = axis_query.projection == AxisProjection::Keys;
let empty_page = |skipped: Option<u64>| {
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]],
Expand Down
117 changes: 100 additions & 17 deletions grovedb/src/operations/proof/generate.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -1776,20 +1795,84 @@ impl GroveDb {
.map(count_axis_descents)
.sum::<usize>()
}
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<u8>],
transaction: &Transaction,
grove_version: &GroveVersion,
) -> CostResult<bool, Error> {
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`.
///
Expand Down
Loading
Loading