Struct DriveDocumentSumQuery 

pub struct DriveDocumentSumQuery<'a> {
    pub document_type: DocumentTypeRef<'a>,
    pub contract_id: [u8; 32],
    pub document_type_name: String,
    pub index: &'a Index,
    pub where_clauses: Vec<WhereClause>,
    pub sum_property: String,
}

Compiled sum-query object. Shared by prover and verifier — both build the same PathQuery via the path-query helpers on this struct, so the prover and the verifier can’t drift on shape. Parallels count’s DriveDocumentCountQuery.

Fields

document_type: DocumentTypeRef<'a>

The document type whose sum tree we’re querying.

contract_id: [u8; 32]

The data contract id (separated from document_type so the verifier-side construction doesn’t need the full contract).

document_type_name: String

The document type name (used to construct the index path).

index: &'a Index

The covering index. Either the index whose summable flag matches the request’s sum_property (point lookup / aggregate case), or the index whose range_summable matches (range case). The doctype-primary-key fast path stores this as a sentinel — see path_query.rs’s primary_key_sum_path_query.

where_clauses: Vec<WhereClause>

The structured where clauses.

sum_property: String

The sum target property. Validated against the index’s summable and the doctype’s documents_summable at dispatch time.

Implementations

impl<'a> DriveDocumentSumQuery<'a>

pub fn primary_key_sum_path_query( contract_id: [u8; 32], document_type_name: &str, ) -> PathQuery

Build the PathQuery for the primary-key SumTree fast path (used when documents_summable is set and the query has no where clauses).

Mirrors count’s primary_key_count_tree_path_query signature — takes the two scalar arguments (contract_id, document_type_name) that are the only fields actually used.

pub fn point_lookup_sum_path_query( &self, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Instance-method form of Self::point_lookup_sum_path_query_static — uses self.index (already resolved by the picker) rather than re-picking from the document type. Mirrors count’s point_lookup_count_path_query shape.

pub fn aggregate_sum_path_query( &self, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Instance-method form: builds the AggregateSumOnRange path query against self.index (resolved upstream by the find_range_summable_index_for_where_clauses picker). The terminator’s range clause is required; prefix properties must use ==.

pub fn aggregate_count_and_sum_path_query( &self, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Instance-method form: builds the combined PCPS AggregateCountAndSumOnRange path query against self.index. Requires the index to declare BOTH rangeCountable: true AND rangeSummable: true.

pub fn distinct_sum_path_query( &self, limit: Option<u16>, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Build the grovedb PathQuery for a per-distinct-key range-sum proof / no-proof walk against this query’s rangeSummable index. Sum analog of count’s distinct_count_path_query — the path-query shape is structurally identical (range on the terminator + outer Keys per In value on a prefix prop, if any). The only difference is at proof-emission time: the terminator’s value tree is a SumTree (vs CountTree on the count side), so grovedb emits KVSum ops instead of KVCount. The path-query bytes the prover and verifier reconstruct are the same on both sides.

left_to_right flips both the outer Query (when there’s an In on prefix) and the subquery direction so the iteration walks (in_key, terminator_key) tuples in the requested order — descending on left_to_right = false walks the In dimension lex-descending too, not just the inner range.

Errors:

• No range where-clause / multiple range where-clauses
• Multiple In clauses on prefix props
• Non-Equal-non-In operator on a prefix prop
• Missing prefix clause

pub fn carrier_aggregate_sum_path_query( &self, limit: Option<u16>, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Build the grovedb PathQuery for a carrier AggregateSumOnRange proof — one outer Key per In value (or one outer QueryItem per outer-range match), each terminating in an ASOR boundary walk over the per-branch range subtree. Returns one (in_key, i64) pair per resolved In branch via [grovedb::GroveDb::query_aggregate_sum_per_key] (no-proof) and [grovedb::GroveDb::verify_aggregate_sum_query_per_key] (verify), once those primitives ship.

Required where-clause shape (validated upstream by [crate::query::drive_document_sum_query::drive_dispatcher::detect_sum_mode] routing to [DocumentSumMode::RangeAggregateCarrierProof]):

• Exactly one In clause on the In-property
• Exactly one range clause on the terminator property of a rangeSummable: true index whose first property is the In-property
• Any prefix properties between In and range must use == (mirror of Self::aggregate_sum_path_query’s non-In prefix rule)

Path-query structure (mirror of count’s analog — [crate::query::drive_document_count_query::path_query::DriveDocumentCountQuery::carrier_aggregate_count_path_query]):

• Outer path stops one level above the In-bearing property subtree’s children (@/doc_prefix/0x01/doctype/<In-prop>).
• Outer Query: Key(in_value_0), Key(in_value_1), … in lex-asc serialized order (grovedb’s multi-key walker invariant — required for prove/verify byte-parity).
• subquery_path: the terminator property name (and any trailing == clause names between In and range, in index order).
• subquery: Query::new_aggregate_sum_on_range(range_item).

Both the executor and the verifier consume the PathQuery this builder produces. Grovedb PR #670 (head e98bab5f) landed carrier-AggregateSumOnRange support (Query::validate_carrier_aggregate_sum_on_range and GroveDb::verify_aggregate_sum_query_per_key), so the builder’s output flows directly through prove_query and the verifier on both sides.

Errors:

• No range where-clause / multiple range where-clauses → InvalidWhereClauseComponents
• No In where-clause → InvalidWhereClauseComponents
• In on a non-prefix property → InvalidWhereClauseComponents
• Prefix property between In and range uses non-Equal → InvalidWhereClauseComponents

pub fn carrier_aggregate_count_and_sum_path_query( &self, limit: Option<u16>, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Combined PCPS (ProvableCountProvableSumTree) carrier variant: outer In or outer range, inner range carrying both per-bucket count AND per-bucket sum via grovedb’s AggregateCountAndSumOnRange primitive. The terminator property’s value tree must be PCPS (the index must declare BOTH rangeCountable: true AND rangeSummable: true).

PCPS-only — ProvableSumTree / ProvableCountTree / ProvableCountSumTree (the per-axis or root-only sum variants) reject the query item at the prover. Returns one (outer_key, u64 count, i64 sum) triple per resolved In branch. Verified client-side via GroveDb::verify_aggregate_count_and_sum_query_per_key (grovedb develop (PR #670 merged; head e98bab5f as of this PR)).

Same outer/subquery topology as Self::carrier_aggregate_sum_path_query — the only difference is the inner aggregation primitive (Query::new_aggregate_count_and_sum_on_range vs. Query::new_aggregate_sum_on_range) and the additional PCPS gate.

impl<'a> DriveDocumentSumQuery<'a>

pub fn point_lookup_sum_path_query_static( contract: &DataContract, document_type: DocumentTypeRef<'_>, sum_property: &str, where_clauses: &[WhereClause], platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Static wrapper for the bench / verifier-side rebuild. Calls the instance method via a temporary DriveDocumentSumQuery built from the picked covering index.

pub fn aggregate_sum_path_query_static( contract: &DataContract, document_type: DocumentTypeRef<'_>, sum_property: &str, where_clauses: &[WhereClause], platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Static wrapper for the bench / verifier-side rebuild — picks the covering range-summable index and delegates to the instance method.

pub fn carrier_aggregate_sum_path_query_static( contract: &DataContract, document_type: DocumentTypeRef<'_>, sum_property: &str, where_clauses: &[WhereClause], limit: Option<u16>, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Static wrapper for the bench / verifier-side rebuild — picks the covering range-summable index and delegates to the carrier instance method. Mirror of count’s analog [crate::query::drive_document_count_query::path_query::DriveDocumentCountQuery::carrier_aggregate_count_path_query]’s implicit static surface via the executor. Used by the SDK verifier-side rebuild via GroveDb::verify_aggregate_sum_query_per_key (grovedb PR #670 head e98bab5f).

impl DriveDocumentSumQuery<'_>

pub fn execute_no_proof( &self, drive: &Drive, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<SumEntry>, Error>

Executes the sum query without generating a proof.

Returns the total sum as a single SumEntry with empty key (the unified-sum Total shape).

Mirror of count’s execute_no_proof — runs through the same Self::point_lookup_sum_path_query builder the prove path uses, then runs grove.query to fetch the matched SumTree elements and sums their sum_value_or_default().

pub fn execute_point_lookup_sum_with_proof( &self, drive: &Drive, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<u8>, Error>

Generates a grovedb proof of the SumTree elements covering a fully-covered Equal/In sum query against a summable: "<x>" index. Mirrors count’s execute_point_lookup_count_with_proof.

impl DriveDocumentSumQuery<'_>

pub fn execute_range_sum_no_proof( &self, drive: &Drive, options: &RangeSumOptions, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<SumEntry>, Error>

Range-aware sum walk against a rangeSummable: true index.

Mirror of count’s execute_range_count_no_proof. Routing:

• Flat summed (no In, distinct=false): single query_aggregate_sum call against the merk-level AggregateSumOnRange primitive. O(log n).
• Compound summed (In on prefix, distinct=false): per-In fan-out — one query_aggregate_sum call per matched In branch, summed in Rust.
• Distinct mode (distinct=true): walks the unified distinct_sum_path_query and emits one entry per matched (in_key, key) pair. (Currently stubbed pending the distinct-builder port.)

pub fn execute_aggregate_sum_with_proof( &self, drive: &Drive, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<u8>, Error>

Generates a grovedb AggregateSumOnRange proof for a range-sum query against a rangeSummable index. Returned proof bytes verify via GroveDb::verify_aggregate_sum_query yielding (root_hash, i64 sum).

pub fn execute_distinct_sum_with_proof( &self, drive: &Drive, limit: u16, left_to_right: bool, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<u8>, Error>

Per-distinct-key range-sum proof against this query’s rangeSummable index. Mirror of count’s execute_distinct_count_with_proof. Currently routes through distinct_sum_path_query which is stubbed (pending the ~280-line port from count); calls before that lands surface Unsupported cleanly.

pub fn execute_aggregate_count_and_sum_with_proof( &self, drive: &Drive, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<u8>, Error>

Generates a grovedb leaf-PCPS AggregateCountAndSumOnRange proof for a combined count + sum range query against an index that declares BOTH rangeCountable: true AND rangeSummable: true. Returned proof bytes verify via GroveDb::verify_aggregate_count_and_sum_query yielding (root_hash, u64 count, i64 sum) — the load-bearing primitive for the [average-index-examples chapter] (../../../../book/src/drive/average-index-examples.md)’s Query 5 (“Class Trend”). PCPS-only: the terminator’s value tree MUST be a ProvableCountProvableSumTree; lighter (CountSumTree / ProvableCountSumTree / ProvableSumTree) terminators are rejected at the grovedb merk-gate.

Leaf analog of Self::execute_carrier_aggregate_count_and_sum_with_proof: same primitive, no outer In fan-out — single (count, sum) per proof rather than per-In-key (count, sum) triples.

pub fn execute_carrier_aggregate_sum_with_proof( &self, drive: &Drive, limit: Option<u16>, left_to_right: bool, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<u8>, Error>

Generates a grovedb carrier AggregateSumOnRange proof for In + range queries with group_by = [in_field] (and the RangeAggregateCarrierProof mode in general). Sum analog of count’s crate::query::drive_document_count_query::DriveDocumentCountQuery::execute_carrier_aggregate_count_with_proof.

Builds the carrier PathQuery via Self::carrier_aggregate_sum_path_query and asks grovedb for a proof. The proof commits one aggregate sum per resolved In branch; verified client-side via GroveDb::verify_aggregate_sum_query_per_key (grovedb PR #670 head e98bab5f), which returns (RootHash, Vec<(Vec<u8>, i64)>).

left_to_right and limit are byte-load-bearing — they are part of the PathQuery bytes the verifier rebuilds. See count’s analog for the rationale.

pub fn execute_carrier_aggregate_count_and_sum_with_proof( &self, drive: &Drive, limit: Option<u16>, left_to_right: bool, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<Vec<u8>, Error>

Combined PCPS carrier proof: AggregateCountAndSumOnRange-on-carrier. Sum-and-count analog of Self::execute_carrier_aggregate_sum_with_proof. Requires the chosen index to declare BOTH rangeCountable: true AND rangeSummable: true so the terminator’s value tree is a ProvableCountProvableSumTree.

Returns proof bytes the verifier maps to Vec<(Vec<u8>, u64, i64)> via GroveDb::verify_aggregate_count_and_sum_query_per_key (grovedb PR #670 head e98bab5f) — one (in_key, count, sum) triple per resolved In branch.

impl DriveDocumentSumQuery<'_>

pub fn verify_aggregate_sum_proof( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, i64), Error>

Verifies a grovedb AggregateSumOnRange proof (grovedb PR #670) and returns (root_hash, i64 sum). Counterpart to the prover-side Self::execute_aggregate_sum_with_proof. Calls GroveDb::verify_aggregate_sum_query.

Tree-type restriction: the chosen index must declare rangeSummable: true so the terminator’s value tree is at least a ProvableSumTree; the grovedb merk gate rejects lighter sum-bearing variants on the aggregate primitive. Same path-query byte-equality contract as every other paired prover/verifier in this surface — both sides share Self::aggregate_sum_path_query.

impl DriveDocumentSumQuery<'_>

pub fn verify_carrier_aggregate_sum_proof( &self, proof: &[u8], limit: Option<u16>, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<(Vec<u8>, i64)>), Error>

Verifies a carrier AggregateSumOnRange proof and returns (root_hash, per_key_sums) — one (in_key, i64) pair per resolved In branch. Order depends on left_to_right: true returns serialized lex-ascending, false returns serialized lex-descending.

Sum-side analog of count’s crate::query::DriveDocumentCountQuery::verify_carrier_aggregate_count_proof. Counterpart to the prover-side execute_carrier_aggregate_sum_with_proof: rebuilds the same PathQuery via carrier_aggregate_sum_path_query and calls [grovedb::GroveDb::verify_aggregate_sum_query_per_key] (once the grovedb sister PR exposes it). The caller is responsible for combining the returned root_hash with the surrounding tenderdash signature — see rs-drive-proof-verifier’s wrapper for the canonical composition.

Arguments

• proof — raw grovedb proof bytes.
• limit — per-branch carrier walk cap; must match the prover’s SizedQuery::limit.
• left_to_right — proof-shaping bit. Must match the value the prover passed to Self::execute_carrier_aggregate_sum_with_proof. Mismatch produces different PathQuery bytes and the tenderdash root check fails.
• platform_version — selects the method version.

impl DriveDocumentSumQuery<'_>

pub fn verify_carrier_aggregate_count_and_sum_proof( &self, proof: &[u8], limit: Option<u16>, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<(Vec<u8>, u64, i64)>), Error>

Verifies a combined PCPS carrier proof (AggregateCountAndSumOnRange on a carrier subquery) and returns (root_hash, per_key_count_sums) — one (in_key, u64 count, i64 sum) triple per resolved In branch.

Combined-axis analog of Self::verify_carrier_aggregate_sum_proof. Requires the covering index to declare BOTH rangeCountable: true AND rangeSummable: true so the terminator’s value tree is a ProvableCountProvableSumTree. Counterpart to the prover-side execute_carrier_aggregate_count_and_sum_with_proof. Calls GroveDb::verify_aggregate_count_and_sum_query_per_key (grovedb develop (PR #670 merged; head e98bab5f as of this PR)).

impl DriveDocumentSumQuery<'_>

pub fn verify_aggregate_count_and_sum_proof( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, u64, i64), Error>

Verifies a leaf-PCPS AggregateCountAndSumOnRange proof and returns (root_hash, count, sum) — the verified (count, sum) pair extracted from one merk traversal of the PCPS terminator. Counterpart to the prover-side execute_aggregate_count_and_sum_with_proof. Calls GroveDb::verify_aggregate_count_and_sum_query (grovedb PR #670 head e98bab5f).

The client computes avg = sum as f64 / count as f64 (or preferred precision) to recover the verified average — the proof commits both metrics from the same in-range set, so there’s no way for the server to splice a count from one set with a sum from another. This is the load-bearing primitive for the [average-index-examples chapter] (../../../../book/src/drive/average-index-examples.md)’s Query 5.

Tree-type restriction: the chosen index must declare BOTH rangeCountable: true AND rangeSummable: true so the terminator’s value tree is a ProvableCountProvableSumTree (PCPS). Lighter sum-bearing or count-bearing variants reject the combined primitive at the merk gate.

impl DriveDocumentSumQuery<'_>

pub fn verify_primary_key_sum_tree_proof( proof: &[u8], contract_id: [u8; 32], document_type_name: &str, platform_version: &PlatformVersion, ) -> Result<(RootHash, i64), Error>

Verifies a grovedb proof of the document type’s primary-key SumTree element and returns the unfiltered total sum. Sum analog of count’s verify_primary_key_count_tree_proof.

Used by the prove path’s documentsSummable: "<prop>" fast path — when the where clauses are empty and the document type has a matching documents_summable, the executor proves the primary-key SumTree element directly via Self::primary_key_sum_path_query (a single-key verify_query shape), avoiding the per-index covering walk.

Returns 0 when the element is absent (the proof’s element stream is empty or carries None). At contract apply time the SumTree element is created unconditionally for documents_summable doctypes, so absence here means “no documents inserted yet”, not a misconfiguration.

impl DriveDocumentSumQuery<'_>

pub fn verify_primary_key_count_sum_tree_proof( proof: &[u8], contract_id: [u8; 32], document_type_name: &str, platform_version: &PlatformVersion, ) -> Result<(RootHash, u64, i64), Error>

Verifies a grovedb proof of the document type’s primary-key CountSumTree (or ProvableCountSumTree / ProvableCountProvableSumTree) element and returns the unfiltered (count, sum) pair. Average-aggregate analog of Self::verify_primary_key_sum_tree_proof / count’s verify_primary_key_count_tree_proof.

Used by the prove path’s AVG fast path — when the where clauses are empty and the document type has both documentsCountable: true and documentsSummable: "<prop>" (which implies the primary key tree is one of the count-sum-bearing variants), the executor proves the primary-key element directly via Self::primary_key_sum_path_query — same single-key shape as the SumTree fast path, just decoded as a combined (count, sum) instead of i64 alone.

Returns (0, 0) when the element is absent.

impl DriveDocumentSumQuery<'_>

pub fn verify_point_lookup_sum_proof( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<SumEntry>), Error>

Verifies a grovedb point-lookup sum proof and returns the per-branch entries. Sum analog of count’s verify_point_lookup_count_proof.

Single-terminator shape, kept in sync with Self::point_lookup_sum_path_query: the insertion side stores every summable: "<prop>" index’s terminator value tree as a SumTree (with sibling continuations NonCounted-wrapped so they don’t pollute the parent’s sum), so proofs target the value tree directly via Key(serialized_value) and sum_value_or_default() on the verified element is the per-branch sum.

Entry shape

One entry per present queried key. Today’s path query does not set absence_proofs_for_non_existing_searched_keys: true, so absent In values are silently omitted from the elements stream. Callers that need to distinguish “verified with sum N” from “queried but absent” diff their request’s In array against the returned entries by key.

The Option<i64> field’s None variant is reserved for a future variant that flips absence_proofs_for_non_existing_searched_keys; the current path query won’t produce it.

impl DriveDocumentSumQuery<'_>

pub fn verify_distinct_sum_proof( &self, proof: &[u8], limit: u16, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<SumEntry>), Error>

Verifies a regular grovedb range proof against a rangeSummable: true index’s terminator SumTrees and returns the per-(in_key, terminator_key) sums. Sum analog of count’s verify_distinct_count_proof.

Used by the prove path’s [DocumentSumMode::RangeDistinctProof] (GroupByRange / GroupByCompound + range + prove). Rebuilds the same PathQuery the prover used via Self::distinct_sum_path_query (including limit and left_to_right — both are encoded into the path query bytes) and walks the verified (path, key, Option<Element>) triples to extract sum_value_or_default() from each terminator SumTree.

Cross-fork aggregation is intentionally NOT done here — callers reduce by key client-side if they want a flat histogram. See SumEntry’s sibling crate::query::SplitCountEntry for the no-merge rationale (identical contract on the sum side).

impl DriveDocumentSumQuery<'_>

pub fn verify_point_lookup_count_and_sum_proof( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<AverageEntry>), Error>

Verifies a grovedb point-lookup proof against an index whose terminator value tree is a count-sum-bearing variant (CountSumTree / ProvableCountSumTree / ProvableCountProvableSumTree) and returns per-branch (count, sum) entries. AVG analog of Self::verify_point_lookup_sum_proof.

Walks the verified (path, key, Option<Element>) triples emitted by Self::point_lookup_sum_path_query and extracts count_sum_value_or_default() from each present terminator element — (count, sum) come from the same merk hash so there’s no way for the server to splice a count from one branch with a sum from another.

Today’s path query does not set absence_proofs_for_non_existing_searched_keys: true, so absent In values are silently omitted from the result. Callers that need to distinguish “verified with (c, s)” from “queried but absent” diff their In array against the returned entries by key.

impl DriveDocumentSumQuery<'_>

pub fn verify_distinct_count_and_sum_proof( &self, proof: &[u8], limit: u16, left_to_right: bool, platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<AverageEntry>), Error>

Verifies a per-distinct-key range-AVG proof against an index whose terminator value trees are count-sum-bearing variants (the chosen index opts into BOTH rangeCountable: true AND rangeSummable: true, i.e. a rangeAverageable: true index). Average analog of Self::verify_distinct_sum_proof / count’s verify_distinct_count_proof.

Rebuilds the same PathQuery the prover used via Self::distinct_sum_path_query (the count + sum sides share the same path-query shape — the difference is at proof-emission time which merk ops are emitted) and walks the verified (path, key, Option<Element>) triples to extract count_sum_value_or_default() from each present terminator element.

Trait Implementations

impl<'a> Clone for DriveDocumentSumQuery<'a>

fn clone(&self) -> DriveDocumentSumQuery<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for DriveDocumentSumQuery<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.