From 5aa5d4a4b2910bdd7a909e48916cca08e56b41f2 Mon Sep 17 00:00:00 2001 From: Ivan Shumkov Date: Thu, 5 Nov 2026 15:40:42 +0700 Subject: [PATCH 1/4] refactor(drive): plan proved counts, sums and averages from the request alone Move what a proved aggregate decides from its request alone into one request-only plan per surface, available under `verify` as well as `server`, so the SDK's verifier and its check before sending can make the plan the server proves by: - `CountProofPlan` + `DriveDocumentCountQuery::proof_plan`: the primary-key count-tree route or the covering index, and the limit and walk direction the path query carries. - `SumProofPlan` (one type for sums and averages) + `DriveDocumentSumQuery::proof_plan` (routed by `DocumentSumMode`) and `DriveDocumentSumQuery::average_proof_plan` (routed by `AverageMode` and whether a range constrains the request, as the average server routes). - `refuse_several_window_selections`: the one window-cardinality rule, replacing the inline copies in the documents index pick, the ranked dispatcher and the having dispatcher. The count dispatcher's four proof executors become one `execute_document_count_proof`; the sum dispatcher's four and the average prove path become one `execute_document_sum_proof`. They prove what the plan names and no longer pick an index. Server output is unchanged: each plan calls the same pickers with the same arguments, refuses with the same variants and texts, and keeps each mode's order (limit before index for count and sum, index before limit for average, primary-key route first). No protocol or method version changes; none of the edited functions is versioned. Evidence: - window_selection_cardinality_tests pins the three server refusals of two windows byte for byte through the server entry points; written and run green before the extraction, green after. - A temporary A/B probe ran 4,800 proved count/sum/average requests (12 where-shapes x 4 modes x 5 limits x 2 directions x 5 selects, at protocol 14 and latest) on a populated Drive against origin/v5.1-dev and this change: the reports (proof-byte hashes and error Debug) are identical. - rs-drive lib: 4,356 passed. Co-Authored-By: Claude Opus 5.5 --- .../tests/range_countable_index_e2e_tests.rs | 4 +- .../drive_dispatcher.rs | 325 +++--------------- .../query/drive_document_average_query/mod.rs | 12 +- .../proof_plan.rs | 199 +++++++++++ .../drive_dispatcher.rs | 160 ++------- .../executors/mod.rs | 34 +- .../executors/point_lookup_proof.rs | 96 ------ .../executors/proof.rs | 96 ++++++ .../range_aggregate_carrier_proof.rs | 94 ----- .../executors/range_distinct_proof.rs | 73 ---- .../executors/range_proof.rs | 54 --- .../query/drive_document_count_query/mod.rs | 7 + .../drive_document_count_query/path_query.rs | 2 +- .../drive_document_count_query/proof_plan.rs | 183 ++++++++++ .../query/drive_document_count_query/tests.rs | 4 +- .../drive_dispatcher.rs | 22 +- .../drive_dispatcher.rs | 19 +- .../drive_dispatcher.rs | 150 ++------ .../drive_document_sum_query/executors/mod.rs | 12 +- .../executors/point_lookup_proof.rs | 86 ----- .../executors/proof.rs | 117 +++++++ .../range_aggregate_carrier_proof.rs | 86 ----- .../executors/range_distinct_proof.rs | 66 ---- .../executors/range_proof.rs | 57 --- .../src/query/drive_document_sum_query/mod.rs | 15 +- .../drive_document_sum_query/proof_plan.rs | 226 ++++++++++++ packages/rs-drive/src/query/mod.rs | 49 ++- .../window_selection_cardinality_tests.rs | 192 +++++++++++ 28 files changed, 1221 insertions(+), 1219 deletions(-) create mode 100644 packages/rs-drive/src/query/drive_document_average_query/proof_plan.rs delete mode 100644 packages/rs-drive/src/query/drive_document_count_query/executors/point_lookup_proof.rs create mode 100644 packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs delete mode 100644 packages/rs-drive/src/query/drive_document_count_query/executors/range_aggregate_carrier_proof.rs delete mode 100644 packages/rs-drive/src/query/drive_document_count_query/executors/range_distinct_proof.rs delete mode 100644 packages/rs-drive/src/query/drive_document_count_query/executors/range_proof.rs create mode 100644 packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs delete mode 100644 packages/rs-drive/src/query/drive_document_sum_query/executors/point_lookup_proof.rs create mode 100644 packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs delete mode 100644 packages/rs-drive/src/query/drive_document_sum_query/executors/range_aggregate_carrier_proof.rs delete mode 100644 packages/rs-drive/src/query/drive_document_sum_query/executors/range_distinct_proof.rs delete mode 100644 packages/rs-drive/src/query/drive_document_sum_query/executors/range_proof.rs create mode 100644 packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs create mode 100644 packages/rs-drive/src/query/window_selection_cardinality_tests.rs diff --git a/packages/rs-drive/src/drive/contract/insert/insert_contract/v0/tests/range_countable_index_e2e_tests.rs b/packages/rs-drive/src/drive/contract/insert/insert_contract/v0/tests/range_countable_index_e2e_tests.rs index 82dd88d113f..1ba23185c86 100644 --- a/packages/rs-drive/src/drive/contract/insert/insert_contract/v0/tests/range_countable_index_e2e_tests.rs +++ b/packages/rs-drive/src/drive/contract/insert/insert_contract/v0/tests/range_countable_index_e2e_tests.rs @@ -3312,7 +3312,7 @@ fn distinct_count_proof_returns_per_lot_counts_for_lots_greater_than_b() { /// ascending order: `c, d, e, f, g`. /// /// Pins two things at once: (1) the limit is plumbed end-to-end -/// through `execute_document_count_range_distinct_proof` → +/// through `execute_document_count_proof` → /// `execute_distinct_count_with_proof` → /// `distinct_count_path_query`, and (2) the prover and verifier /// build the *exact same* `PathQuery` with that limit so the @@ -3466,7 +3466,7 @@ fn distinct_count_proof_honors_request_limit() { /// in-range). With `LIMIT = 5` and descending iteration the /// proof should cover `z, y, x, w, v` — pinning that: /// (1) `left_to_right = false` propagates end-to-end through -/// `execute_document_count_range_distinct_proof` → +/// `execute_document_count_proof` → /// `execute_distinct_count_with_proof` → /// `distinct_count_path_query`; /// (2) the prover and verifier agree on the descending path diff --git a/packages/rs-drive/src/query/drive_document_average_query/drive_dispatcher.rs b/packages/rs-drive/src/query/drive_document_average_query/drive_dispatcher.rs index 5d3a044024d..e18a9f040bc 100644 --- a/packages/rs-drive/src/query/drive_document_average_query/drive_dispatcher.rs +++ b/packages/rs-drive/src/query/drive_document_average_query/drive_dispatcher.rs @@ -10,9 +10,10 @@ //! docstring for the routing / atomicity contract. //! - **Prove path** → dispatched to //! [`Drive::execute_document_average_prove`] (defined below), which -//! routes to one of the PCPS / direct-read prove executors based on -//! `(mode, where_clauses)`. The prove path's per-shape rules are -//! unchanged. +//! plans the proof from `(mode, where_clauses)` with +//! [`DriveDocumentSumQuery::average_proof_plan`] — the plan the +//! client's verifier makes too — and proves it with one of the PCPS / +//! direct-read primitives. //! //! ## Joint dispatch //! @@ -25,10 +26,10 @@ //! `(where_clauses × mode)` → executor decision has a single source //! of truth shared with the count and sum surfaces. //! -//! ## Prove path shapes (unchanged) +//! ## Prove path shapes //! //! The prove-path routing table at -//! [`Self::execute_document_average_prove`] picks one of: +//! [`DriveDocumentSumQuery::average_proof_plan`] picks one of: //! - empty-where + `documentsCountable + documentsSummable` //! doctype → primary-key count-sum tree direct read //! - range AVG on a `rangeAverageable` index → PCPS @@ -46,22 +47,17 @@ //! `verify_*_count_and_sum_proof` helpers in `drive-proof-verifier`. use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; use crate::error::Error; use crate::query::drive_document_average_query::{ AverageMode, DocumentAverageRequest, DocumentAverageResponse, }; -use crate::query::drive_document_sum_query::index_picker::{ - find_range_summable_index_with_counts_for_where_clauses, - find_summable_index_with_counts_for_where_clauses, -}; -use crate::query::drive_document_sum_query::{is_range_operator, DriveDocumentSumQuery}; +use crate::query::drive_document_sum_query::DriveDocumentSumQuery; use crate::query::{ key_array_element_clauses, validate_and_canonicalize_where_clauses, validate_resolved_time_range_clause_shapes, }; use dpp::data_contract::accessors::v0::DataContractV0Getters; -use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; +use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; use dpp::version::PlatformVersion; use grovedb::TransactionArg; @@ -117,9 +113,10 @@ impl Drive { /// Prove path of [`Self::execute_document_average_request`]. /// - /// Routes the `(where_clauses × mode)` pair to one of the - /// available PCPS / direct-read prove executors and returns - /// proof bytes the client verifies with the matching + /// Plans the proof of the `(where_clauses × mode)` pair with + /// [`DriveDocumentSumQuery::average_proof_plan`], the plan the + /// client's verifier makes too, and returns proof bytes the + /// client verifies with the matching /// `verify_*_count_and_sum_proof` helper. /// /// Supported prove shapes: @@ -155,277 +152,39 @@ impl Drive { ) -> Result { let contract_id = request.contract.id().to_buffer(); let document_type_name = request.document_type.name().to_string(); - let has_range = request - .where_clauses - .iter() - .any(|wc| is_range_operator(wc.operator)); - let order_by_ascending = request - .order_clauses - .first() - .map(|c| c.ascending) - .unwrap_or(true); - - // Empty-where AVG fast path: prove the primary-key - // count-sum-bearing element directly when the doctype - // declares both `documents_countable: true` (implied by - // having a CountSumTree primary key) and a matching - // `documents_summable`. The verifier extracts `(count, - // sum)` from one element. - if matches!(request.mode, AverageMode::Aggregate) - && request.where_clauses.is_empty() - && request.document_type.documents_countable() - && request - .document_type - .documents_summable() - .map(|p| p == request.sum_property) - .unwrap_or(false) - { - let path_query = - DriveDocumentSumQuery::primary_key_sum_path_query(contract_id, &document_type_name); - let proof = self - .grove - .get_proved_path_query( - &path_query, - None, - transaction, - &platform_version.drive.grove_version, - ) - .unwrap() - .map_err(|e| Error::GroveDB(Box::new(e)))?; - return Ok(DocumentAverageResponse::Proof(proof)); - } - - // Range AVG: pick a PCPS-eligible index (range_countable - // AND range_summable) covering the where clauses. Sum's range - // picker restricted to `range_countable` indexes. - if has_range - && matches!( - request.mode, - AverageMode::Aggregate | AverageMode::GroupByIn - ) - { - let index = find_range_summable_index_with_counts_for_where_clauses( - request.document_type.indexes(), - &request.where_clauses, - &request.sum_property, - &request.resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "prove AVG requires an index that declares BOTH `rangeCountable: \ - true` AND `rangeSummable: true` (a `rangeAverageable: true` \ - index is the shorthand) whose last property matches the range \ - field and whose summable property matches the request's \ - `sum_property`" - .to_string(), - )) - })?; - let sum_query = DriveDocumentSumQuery { - document_type: request.document_type, - contract_id, - document_type_name, - index, - where_clauses: request.where_clauses.clone(), - sum_property: request.sum_property.clone(), - }; - - let proof = match request.mode { - AverageMode::Aggregate => sum_query.execute_aggregate_count_and_sum_with_proof( - self, - transaction, - platform_version, - )?, - AverageMode::GroupByIn => { - // Carrier-PCPS: one (count, sum) per In branch. - // Validate-don't-clamp limit policy on the prove - // path — `SizedQuery::limit` is bytes-of-proof - // material; silent clamping would byte-differ the - // SDK's reconstruction and break verification. - // Same contract as sum's `RangeAggregateCarrierProof` - // arm. `None` stays `None` (unbounded outer walk). - let limit_u16 = request - .limit - .map(|l| { - if l > request.drive_config.max_query_limit as u32 { - return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( - "limit {} exceeds max_query_limit {} on the prove + \ - carrier-aggregate path (GROUP BY In + range, AVG); \ - reduce the requested limit or use prove = false", - l, request.drive_config.max_query_limit - )))); - } - u16::try_from(l).map_err(|_| { - Error::Query(QuerySyntaxError::Unsupported(format!( - "limit {} exceeds u16::MAX for carrier-aggregate \ - count+sum (AVG) proof", - l - ))) - }) - }) - .transpose()?; - sum_query.execute_carrier_aggregate_count_and_sum_with_proof( - self, - limit_u16, - order_by_ascending, - transaction, - platform_version, - )? - } - _ => unreachable!("outer matches! gate filters out non-Aggregate/GroupByIn"), - }; - return Ok(DocumentAverageResponse::Proof(proof)); - } - - // Distinct AVG (GroupByRange / GroupByCompound + range) — - // per-distinct-key (count, sum) proof against a PCPS- - // eligible index (rangeCountable + rangeSummable, i.e. a - // `rangeAverageable: true` index). The prover uses sum's - // `execute_distinct_sum_with_proof` against a path query - // whose terminators are `ProvableCountProvableSumTree`; the - // verifier extracts `count_sum_value_or_default()` from - // each emitted element. - if has_range - && matches!( - request.mode, - AverageMode::GroupByRange | AverageMode::GroupByCompound - ) - { - let index = find_range_summable_index_with_counts_for_where_clauses( - request.document_type.indexes(), - &request.where_clauses, - &request.sum_property, - &request.resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "prove distinct AVG requires an index that declares BOTH \ - `rangeCountable: true` AND `rangeSummable: true` (a \ - `rangeAverageable: true` index is the shorthand) whose last \ - property matches the range field and whose summable property \ - matches the request's `sum_property`" - .to_string(), - )) - })?; - // Validate-don't-clamp limit policy on the prove path — - // see sum's `RangeDistinctProof` arm for the full - // rationale. Limit fallback uses - // [`crate::config::DEFAULT_QUERY_LIMIT`] (compile-time - // constant) so the SDK's reconstruction lands on the same - // `SizedQuery::limit` value; `max_query_limit` still - // gates as a DoS ceiling. - let effective_limit = request - .limit - .unwrap_or(crate::config::DEFAULT_QUERY_LIMIT as u32); - if effective_limit > request.drive_config.max_query_limit as u32 { - return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( - "limit {} exceeds max_query_limit {} on the prove + distinct-walk \ - path (GROUP BY a range field, AVG); reduce the requested limit \ - or use prove = false", - effective_limit, request.drive_config.max_query_limit - )))); - } - let limit_u16 = u16::try_from(effective_limit).map_err(|_| { - Error::Query(QuerySyntaxError::Unsupported(format!( - "limit {} exceeds u16::MAX for distinct AVG proof", - effective_limit - ))) - })?; - let sum_query = DriveDocumentSumQuery { - document_type: request.document_type, - contract_id, - document_type_name, - index, - where_clauses: request.where_clauses.clone(), - sum_property: request.sum_property.clone(), - }; - let proof = sum_query.execute_distinct_sum_with_proof( - self, - limit_u16, - order_by_ascending, - transaction, - platform_version, - )?; - return Ok(DocumentAverageResponse::Proof(proof)); - } - - // Point-lookup AVG: Equal/In on a count+sum index (whose - // `summable.is_some()` AND `countable.is_countable()`) OR - // doctype-level documentsSummable + documentsCountable for - // the empty-where case (handled by the fast path above — - // this arm handles the non-empty-where Equal/In shape). - // - // Accepts both `Aggregate` (caller wants one aggregate row - // collapsed across all matched In branches — folded - // client-side by `DocumentAverage`) and `GroupByIn` (caller - // wants per-In-branch entries — `DocumentSplitAverages` - // shape). The grovedb-side proof is identical: one walk - // through the point-lookup `subquery` per In key emits one - // count-sum-bearing element per branch. - // - // Mirrors the sum router's resolved-mode table - // (`mode_detection/v0/mod.rs`) which maps both - // `(SumMode::Aggregate, !range, _, true)` and - // `(SumMode::GroupByIn, !range, _, true)` to - // `DocumentSumMode::PointLookupProof`. Before adding - // `GroupByIn` here the SDK could ask drive for a no-range - // GroupByIn AVG proof, drive would 500 with `Unsupported`, - // and the SDK's `verify_point_lookup_count_and_sum_proof` - // arm (gated on the same resolved mode) would never get - // proof bytes to verify. - if !has_range - && matches!( - request.mode, - AverageMode::Aggregate | AverageMode::GroupByIn - ) - { - let index = find_summable_index_with_counts_for_where_clauses( - request.document_type.indexes(), - &request.where_clauses, - &request.sum_property, - &request.resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "prove point-lookup AVG requires an index that declares BOTH \ - `summable: \"\"` AND a countable terminator (`countable: \ - \"countable\"` or `\"countableAllowingOffset\"`) whose properties \ - exactly match the where clause fields" - .to_string(), - )) - })?; - let sum_query = DriveDocumentSumQuery { - document_type: request.document_type, - contract_id, - document_type_name, - index, - where_clauses: request.where_clauses.clone(), - sum_property: request.sum_property.clone(), - }; - let proof = sum_query.execute_point_lookup_sum_with_proof( - self, - transaction, - platform_version, - )?; - return Ok(DocumentAverageResponse::Proof(proof)); - } - - // Unreachable in practice — the matches!() gates above - // cover every (mode × has_range) combination today. Kept as - // a typed error in case a future AverageMode variant lands - // without a corresponding prove arm. - Err(Error::Query(QuerySyntaxError::Unsupported(format!( - "execute_document_average_request prove=true: the (mode = {:?}, has_range \ - = {}) combination is not yet supported on the prove path. \ - This is likely a new AverageMode variant that hasn't been wired \ - into the prove dispatcher.", - request.mode, has_range, - )))) + // The request-only plan the SDK's verifier makes too: the + // primary-key route or the covering index, and the limit and walk + // direction the path query carries (see `SumProofPlan`). The carrier + // and distinct walks follow sum's validate-don't-clamp limit policy. + let plan = DriveDocumentSumQuery::average_proof_plan( + &request.document_type, + &request.where_clauses, + &request.resolved_time_ranges, + &request.sum_property, + request.mode, + &request.order_clauses, + request.limit, + Some(request.drive_config.max_query_limit), + )?; + let proof = self.execute_document_sum_proof( + contract_id, + request.document_type, + document_type_name, + request.where_clauses, + request.sum_property, + plan, + true, + transaction, + platform_version, + )?; + Ok(DocumentAverageResponse::Proof(proof)) } } #[cfg(all(test, feature = "server"))] mod tests { use super::*; + use crate::query::drive_document_sum_query::index_picker::find_range_summable_index_with_counts_for_where_clauses; use crate::query::ResolvedTimeRange; // ── Dispatcher limit-policy regression tests ─────────────────── @@ -433,8 +192,8 @@ mod tests { // AVG-side analogs of count's // `test_range_distinct_proof_uses_compile_time_default_query_limit_not_operator_config` // and the sum-side tests in `drive_document_sum_query/tests.rs`'s - // `limit_policy_regression` module. The AVG dispatcher's - // `RangeDistinctProof` arm mirrors the same validate-don't-clamp + // `limit_policy_regression` module. The AVG proof plan's + // distinct walk mirrors the same validate-don't-clamp // policy on the prove path; these tests pin that the dispatcher // uses [`crate::config::DEFAULT_QUERY_LIMIT`] (compile-time // constant) rather than the operator-tunable @@ -445,7 +204,7 @@ mod tests { // The AVG distinct path internally calls // `execute_distinct_sum_with_proof` (the same primitive sum's // RangeDistinctProof uses — see `drive_document_average_query/ - // drive_dispatcher.rs::execute_document_average_prove`); the + // proof_plan.rs::average_proof_plan`); the // distinction is the index requirement (`rangeCountable + // rangeSummable`, i.e. PCPS / `rangeAverageable`) and the // verifier helper (`verify_aggregate_count_and_sum_query`). diff --git a/packages/rs-drive/src/query/drive_document_average_query/mod.rs b/packages/rs-drive/src/query/drive_document_average_query/mod.rs index bbd069070e9..02014bc68f6 100644 --- a/packages/rs-drive/src/query/drive_document_average_query/mod.rs +++ b/packages/rs-drive/src/query/drive_document_average_query/mod.rs @@ -28,6 +28,9 @@ #[cfg(feature = "server")] pub mod drive_dispatcher; +// The request-only plan of a proved average, shared by the server's +// dispatcher and the SDK's verifier. +pub mod proof_plan; #[cfg(feature = "server")] use crate::query::{OrderClause, ResolvedTimeRange, WhereClause}; @@ -146,11 +149,10 @@ pub struct DocumentAverageRequest<'a> { /// rather than clamped, so a tuned operator default or an /// over-max request can't byte-differ the /// `SizedQuery::limit` the SDK reconstructs for merk-root - /// verification. See the - /// [`drive_dispatcher`]'s `RangeDistinctProof` / - /// `RangeAggregateCarrierProof` arms for the - /// validate-don't-clamp policy, mirrored from count's - /// prove-path arms. + /// verification. See + /// [`DriveDocumentSumQuery::average_proof_plan`](crate::query::drive_document_sum_query::DriveDocumentSumQuery::average_proof_plan) + /// for the validate-don't-clamp policy, mirrored from count's + /// proof plan. pub limit: Option, /// Whether to return a `Proof(Vec)` instead of materializing /// the (count, sum) pairs server-side. diff --git a/packages/rs-drive/src/query/drive_document_average_query/proof_plan.rs b/packages/rs-drive/src/query/drive_document_average_query/proof_plan.rs new file mode 100644 index 00000000000..f55323250c6 --- /dev/null +++ b/packages/rs-drive/src/query/drive_document_average_query/proof_plan.rs @@ -0,0 +1,199 @@ +//! The request-only half of a proved average: which proof answers the +//! request, what that proof reads, and the limit and walk direction its +//! path query carries. +//! +//! An average reads the trees a sum reads, through the same path queries, +//! so it is planned as a [`SumProofPlan`]; its range and carrier proofs read +//! each element's count beside its sum. It is planned apart from a sum +//! because the server routes it by its [`AverageMode`] and whether a range +//! clause constrains it, not by sum's resolved mode, with its own refusals. +//! The server's average dispatcher proves what the plan names, and the SDK's +//! verifier rebuilds the path query from the same plan; a client refuses +//! before sending what the plan refuses, in the server's words. The planner +//! reads no version table, so every protocol version that serves a proved +//! average plans the same proof for the same request. + +use super::AverageMode; +use crate::config::DEFAULT_QUERY_LIMIT; +use crate::error::query::QuerySyntaxError; +use crate::error::Error; +use crate::query::drive_document_sum_query::index_picker::{ + find_range_summable_index_with_counts_for_where_clauses, + find_summable_index_with_counts_for_where_clauses, +}; +use crate::query::drive_document_sum_query::{ + is_range_operator, DriveDocumentSumQuery, SumProofPlan, +}; +use crate::query::{OrderClause, ResolvedTimeRange, WhereClause}; +use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; +use dpp::data_contract::document_type::DocumentTypeRef; + +impl DriveDocumentSumQuery<'_> { + /// The [`SumProofPlan`] of a proved average of `sum_property` over + /// `document_type`: each proof reads an element's count beside its sum. + /// + /// A range picks an index that is both range-countable and + /// range-summable (one `rangeAverageable: true` declares both), no range + /// an index that sums the property and counts its terminator. The + /// arguments are [`DriveDocumentSumQuery::proof_plan`]'s, except that + /// `mode` is the request's SQL-shape [`AverageMode`] and that an average + /// picks its index *before* it checks the limit against + /// `max_query_limit`: a request with both problems is refused for the + /// index. + #[allow(clippy::too_many_arguments)] + pub fn average_proof_plan<'a>( + document_type: &'a DocumentTypeRef<'_>, + where_clauses: &[WhereClause], + resolved_time_ranges: &[ResolvedTimeRange], + sum_property: &str, + mode: AverageMode, + order_clauses: &[OrderClause], + limit: Option, + max_query_limit: Option, + ) -> Result, Error> { + let has_range = where_clauses + .iter() + .any(|wc| is_range_operator(wc.operator)); + let left_to_right = order_clauses.first().map(|c| c.ascending).unwrap_or(true); + + // An unfiltered average over a type that counts its documents and + // sums them by the requested property proves the primary-key + // count-sum-bearing element directly. + if matches!(mode, AverageMode::Aggregate) + && where_clauses.is_empty() + && document_type.documents_countable() + && document_type + .documents_summable() + .map(|p| p == sum_property) + .unwrap_or(false) + { + return Ok(SumProofPlan::PrimaryKeySumTree); + } + + match (mode, has_range) { + (AverageMode::Aggregate | AverageMode::GroupByIn, true) => { + let index = find_range_summable_index_with_counts_for_where_clauses( + document_type.indexes(), + where_clauses, + sum_property, + resolved_time_ranges, + ) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "prove AVG requires an index that declares BOTH `rangeCountable: \ + true` AND `rangeSummable: true` (a `rangeAverageable: true` \ + index is the shorthand) whose last property matches the range \ + field and whose summable property matches the request's \ + `sum_property`" + .to_string(), + )) + })?; + if matches!(mode, AverageMode::Aggregate) { + return Ok(SumProofPlan::Range(index)); + } + // Carrier: one (count, sum) per `In` branch. Validate-don't- + // clamp, as for sum's carrier; an unset limit stays unset. + let limit = limit + .map(|l| { + if let Some(max_query_limit) = max_query_limit { + if l > max_query_limit as u32 { + return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( + "limit {} exceeds max_query_limit {} on the prove + \ + carrier-aggregate path (GROUP BY In + range, AVG); \ + reduce the requested limit or use prove = false", + l, max_query_limit + )))); + } + } + u16::try_from(l).map_err(|_| { + Error::Query(QuerySyntaxError::Unsupported(format!( + "limit {} exceeds u16::MAX for carrier-aggregate \ + count+sum (AVG) proof", + l + ))) + }) + }) + .transpose()?; + Ok(SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + }) + } + (AverageMode::GroupByRange | AverageMode::GroupByCompound, true) => { + let index = find_range_summable_index_with_counts_for_where_clauses( + document_type.indexes(), + where_clauses, + sum_property, + resolved_time_ranges, + ) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "prove distinct AVG requires an index that declares BOTH \ + `rangeCountable: true` AND `rangeSummable: true` (a \ + `rangeAverageable: true` index is the shorthand) whose last \ + property matches the range field and whose summable property \ + matches the request's `sum_property`" + .to_string(), + )) + })?; + // Validate-don't-clamp, as for sum's distinct walk; an unset + // limit falls back to the compile-time `DEFAULT_QUERY_LIMIT`. + let effective_limit = limit.unwrap_or(DEFAULT_QUERY_LIMIT as u32); + if let Some(max_query_limit) = max_query_limit { + if effective_limit > max_query_limit as u32 { + return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( + "limit {} exceeds max_query_limit {} on the prove + distinct-walk \ + path (GROUP BY a range field, AVG); reduce the requested limit \ + or use prove = false", + effective_limit, max_query_limit + )))); + } + } + let limit = u16::try_from(effective_limit).map_err(|_| { + Error::Query(QuerySyntaxError::Unsupported(format!( + "limit {} exceeds u16::MAX for distinct AVG proof", + effective_limit + ))) + })?; + Ok(SumProofPlan::RangeDistinct { + index, + limit, + left_to_right, + }) + } + // Equal / `In`, no range: one count-sum-bearing element per matched + // branch, collapsed into one aggregate by `DocumentAverage` or kept + // per branch by `DocumentSplitAverages` (the same proof either way). + (AverageMode::Aggregate | AverageMode::GroupByIn, false) => { + find_summable_index_with_counts_for_where_clauses( + document_type.indexes(), + where_clauses, + sum_property, + resolved_time_ranges, + ) + .map(SumProofPlan::PointLookup) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "prove point-lookup AVG requires an index that declares BOTH \ + `summable: \"\"` AND a countable terminator (`countable: \ + \"countable\"` or `\"countableAllowingOffset\"`) whose properties \ + exactly match the where clause fields" + .to_string(), + )) + }) + } + // A grouped walk with no range to walk: routing never sends one, so + // only a direct Drive caller reaches this. + (AverageMode::GroupByRange | AverageMode::GroupByCompound, false) => { + Err(Error::Query(QuerySyntaxError::Unsupported(format!( + "execute_document_average_request prove=true: the (mode = {:?}, has_range \ + = {}) combination is not yet supported on the prove path. \ + This is likely a new AverageMode variant that hasn't been wired \ + into the prove dispatcher.", + mode, has_range, + )))) + } + } + } +} diff --git a/packages/rs-drive/src/query/drive_document_count_query/drive_dispatcher.rs b/packages/rs-drive/src/query/drive_document_count_query/drive_dispatcher.rs index 996a5778c10..6a852b16ebb 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/drive_dispatcher.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/drive_dispatcher.rs @@ -252,8 +252,11 @@ impl Drive { /// Owns the whole pipeline: /// 1. [`DriveDocumentCountQuery::detect_mode`] classifies the /// query shape from the where clauses + flags. - /// 2. The matching `Drive::execute_document_count_*` per-mode - /// method picks an index and runs the executor. + /// 2. A no-proof mode's `Drive::execute_document_count_*` method + /// picks an index and runs the executor; a proof mode's + /// [`DriveDocumentCountQuery::proof_plan`] picks the primary-key + /// route or the index, and `execute_document_count_proof` + /// proves it. /// 3. The result is wrapped in [`DocumentCountResponse`] — /// `Counts(...)` for no-proof modes, `Proof(...)` for proof /// modes. @@ -406,137 +409,46 @@ impl Drive { Ok(DocumentCountResponse::Entries(entries)) } } - DocumentCountMode::RangeProof => Ok(DocumentCountResponse::Proof( - self.execute_document_count_range_proof( - contract_id, - request.document_type, - document_type_name, - where_clauses, - &resolved_time_ranges, - transaction, - platform_version, - )?, - )), - DocumentCountMode::RangeDistinctProof => { - // Validate-don't-clamp limit policy on the prove - // path: client-side proof reconstruction needs the - // exact same limit value the server applied to the - // path query (so the merk-root recomputation - // matches). Silent clamping would invisibly break - // verification on any request with `limit > - // max_query_limit`. + DocumentCountMode::RangeProof + | DocumentCountMode::RangeDistinctProof + | DocumentCountMode::PointLookupProof + | DocumentCountMode::RangeAggregateCarrierProof => { + // The request-only plan the SDK's verifier makes too: the + // primary-key route or the covering index, and the limit + // the path query carries (see `CountProofPlan`). // - // **Limit fallback uses `crate::config::DEFAULT_QUERY_LIMIT` - // (the compile-time constant), NOT - // `drive_config.default_query_limit` (the - // operator-tunable runtime value).** The SDK verifier - // can't know an operator's tuned config, so any - // operator who tuned `default_query_limit` away from - // `DEFAULT_QUERY_LIMIT` would produce proofs whose - // `SizedQuery::limit` byte-differs from the - // verifier's reconstruction — silent verify failure - // on a consensus-adjacent path. Anchoring the - // fallback to the shared compile-time constant - // removes that operator-tunable degree of freedom - // from proof bytes entirely; the runtime - // `default_query_limit` continues to govern no-proof - // dispatch paths where there's no verifier to match. - // `max_query_limit` still gates the request as a - // DoS-protection knob (proofs never cross the - // operator-set ceiling, but the ceiling itself doesn't - // affect proof bytes — it only decides whether the - // request gets served). - let effective_limit = request - .limit - .unwrap_or(crate::config::DEFAULT_QUERY_LIMIT as u32); - if effective_limit > request.drive_config.max_query_limit as u32 { - return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( - "limit {} exceeds max_query_limit {} on the prove + \ - distinct-walk path (GROUP BY a range field); reduce the \ - requested limit or use prove = false", - effective_limit, request.drive_config.max_query_limit - )))); - } - let limit_u16 = effective_limit as u16; - // Default to ascending if the request didn't specify - // — matches the no-proof default. The verifier reads - // the same field to reconstruct the matching path - // query (see SDK's `FromProof` impl - // for `DocumentSplitCounts`); both sides MUST land - // on the same `left_to_right` value or the merk-root - // recomputation fails. - let left_to_right = order_by_ascending; - Ok(DocumentCountResponse::Proof( - self.execute_document_count_range_distinct_proof( - contract_id, - request.document_type, - document_type_name, - where_clauses, - &resolved_time_ranges, - limit_u16, - left_to_right, - transaction, - platform_version, - )?, - )) - } - DocumentCountMode::PointLookupProof => Ok(DocumentCountResponse::Proof( - self.execute_document_count_point_lookup_proof( - contract_id, - request.document_type, - document_type_name, - where_clauses, - &resolved_time_ranges, - transaction, - platform_version, - )?, - )), - DocumentCountMode::RangeAggregateCarrierProof => { - // Validate-don't-clamp limit policy on the prove path - // (same rationale as `RangeDistinctProof` above): the - // verifier reconstructs the SizedQuery's `limit` byte- - // identically, so silent clamping would invisibly - // break verification. - // - // Two shape-dependent rules apply here: - // - // - **In-outer carrier (G7):** the caller's `|In|` - // already bounds the result. `SizedQuery::limit` - // stays `None`; if the caller passed a non-`None` - // `limit`, reject — there's no use case for a sub- - // `|In|` limit on this path, and accepting it would - // silently change which In-branches appear in the - // proof. - // - // - **Range-outer carrier (G8):** the platform - // enforces a max outer-walk cap of - // [`super::MAX_CARRIER_AGGREGATE_OUTER_RANGE_LIMIT`] - // on how many outer-range matches the carrier walks. - // Caller may pass a smaller `limit` to truncate the - // walk further; passing a larger one is rejected. - // If the caller passes `None`, the platform default - // (the cap itself) is used. - let effective_limit = DriveDocumentCountQuery::carrier_aggregate_count_limit( + // Validate-don't-clamp limit policy on the prove path: + // client-side proof reconstruction needs the exact limit + // the server applied to the path query, so a limit above + // `max_query_limit` is refused rather than clamped. The + // distinct walk's unset limit falls back to the compile-time + // `DEFAULT_QUERY_LIMIT`, never the operator-tunable + // `default_query_limit` a verifier cannot know; + // `max_query_limit` only decides whether the request is + // served, never the proof bytes. A carrier's limit follows + // `DriveDocumentCountQuery::carrier_aggregate_count_limit`: + // none for an `In` outer, which its values bound, and at + // most `MAX_CARRIER_AGGREGATE_OUTER_RANGE_LIMIT` for a range + // outer. The distinct and carrier walks run in the first + // `order_by` clause's direction, ascending by default, carried + // byte for byte through `Query::left_to_right` so the verifier + // rebuilds the same `PathQuery`. + let plan = DriveDocumentCountQuery::proof_plan( + &request.document_type, &where_clauses, + &resolved_time_ranges, + mode, + &order_clauses, request.limit, + Some(request.drive_config.max_query_limit), )?; - // Outer-walk direction: ascending by default (the - // grovedb invariant for serialized-key carriers), or - // descending when the caller's `order_by` first - // clause is `desc`. Carried byte-identically through - // `Query::left_to_right` so the verifier rebuilds the - // exact same `PathQuery` — same load-bearing pattern - // as the `RangeDistinctProof` arm above. - let left_to_right = order_by_ascending; Ok(DocumentCountResponse::Proof( - self.execute_document_count_range_aggregate_carrier_proof( + self.execute_document_count_proof( contract_id, request.document_type, document_type_name, where_clauses, - &resolved_time_ranges, - effective_limit, - left_to_right, + plan, transaction, platform_version, )?, diff --git a/packages/rs-drive/src/query/drive_document_count_query/executors/mod.rs b/packages/rs-drive/src/query/drive_document_count_query/executors/mod.rs index 4a524b9a1b0..97a4e4196f7 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/executors/mod.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/executors/mod.rs @@ -1,33 +1,27 @@ -//! Per-mode count-query executors on `impl Drive`. One file per -//! [`super::DocumentCountMode`] variant — the dispatcher -//! ([`super::drive_dispatcher`]) calls into the right one based -//! on the detected mode. +//! Count-query executors on `impl Drive`. One file per no-proof +//! [`super::DocumentCountMode`] variant, and one for every proof mode: +//! the dispatcher ([`super::drive_dispatcher`]) calls into the right one +//! based on the detected mode. //! -//! Each executor: +//! Each no-proof executor: //! //! 1. Picks the right covering index for its mode (returns //! `Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty)` //! if no index covers the where clauses). //! 2. Builds the appropriate `DriveDocumentCountQuery`. -//! 3. Runs the matching method on it (`execute_no_proof`, -//! `execute_range_count_no_proof`, -//! `execute_aggregate_count_with_proof`, -//! `execute_distinct_count_with_proof`, or -//! `execute_point_lookup_count_with_proof`). -//! 4. Returns `Vec` (no-proof modes) or -//! `Vec` proof bytes (proof modes). +//! 3. Runs the matching method on it (`execute_no_proof` or +//! `execute_range_count_no_proof`) and returns +//! `Vec`. //! -//! Splitting along mode boundaries — one file per mode — keeps -//! each executor's index-picking + clause-handling logic local -//! and lets the dispatcher's match arms stay one line each. No -//! re-exports are needed: each file adds methods directly to +//! The proof executor ([`proof`]) instead proves what the request's +//! [`super::CountProofPlan`] reads, the plan the SDK's verifier rebuilds +//! the path query from, and returns the `Vec` proof bytes. +//! +//! No re-exports are needed: each file adds methods directly to //! `impl Drive`, so callers (the dispatcher) just see them on //! the `Drive` type. pub mod per_in_value; -pub mod point_lookup_proof; -pub mod range_aggregate_carrier_proof; -pub mod range_distinct_proof; +pub mod proof; pub mod range_no_proof; -pub mod range_proof; pub mod total; diff --git a/packages/rs-drive/src/query/drive_document_count_query/executors/point_lookup_proof.rs b/packages/rs-drive/src/query/drive_document_count_query/executors/point_lookup_proof.rs deleted file mode 100644 index 81ba6770996..00000000000 --- a/packages/rs-drive/src/query/drive_document_count_query/executors/point_lookup_proof.rs +++ /dev/null @@ -1,96 +0,0 @@ -//! Point-lookup count proof executor for -//! [`super::super::DocumentCountMode::PointLookupProof`] -//! dispatch — `prove = true` count queries with no range clause -//! (Equal/`In` against a `countable: true` index, OR the -//! `documents_countable: true` fast path on empty where). - -use super::super::super::conditions::WhereClause; -use super::super::DriveDocumentCountQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Point-lookup count proof against a `countable: true` - /// index for `prove = true` Equal/`In` count queries, OR — - /// when the where clauses are empty and the document type - /// has `documents_countable: true` — a proof of the type's - /// primary-key CountTree (one merk path proof, O(log n) - /// bytes). - /// - /// In both cases the SDK-side verifier extracts each verified - /// CountTree element's `count_value` directly, no document - /// materialization. - /// - /// Mirrors the no-proof `Total` / `PerInValue` modes' - /// rejection contract: if no `countable: true` index exactly - /// covers the where clauses (and the documents_countable - /// fast path doesn't apply), rejects with - /// `WhereClauseOnNonIndexedProperty`. Same contract on both - /// prove and no-proof paths — no silent fallback. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_count_point_lookup_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters; - - // Fast path: unfiltered prove count on a - // `documents_countable: true` document type proves the - // primary-key CountTree element directly. Same path-query - // shape as the index-based case, just rooted at - // `[..., doctype]` instead of inside an index. - if where_clauses.is_empty() && document_type.documents_countable() { - let path_query = DriveDocumentCountQuery::primary_key_count_tree_path_query( - contract_id, - &document_type_name, - ); - let proof = self - .grove - .get_proved_path_query( - &path_query, - None, - transaction, - &platform_version.drive.grove_version, - ) - .unwrap() - .map_err(|e| Error::GroveDB(Box::new(e)))?; - return Ok(proof); - } - - let index = DriveDocumentCountQuery::find_countable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "prove count requires a `countable: true` (or summableOffCountIndex) index whose properties \ - exactly match the where clause fields, a `rangeCountable: true` \ - index they cover up to its last property, or `documentsCountable: \ - true` on the document type for unfiltered total counts — same \ - requirement as the no-proof path" - .to_string(), - )) - })?; - let count_query = DriveDocumentCountQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - }; - count_query.execute_point_lookup_count_with_proof(self, transaction, platform_version) - } -} diff --git a/packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs b/packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs new file mode 100644 index 00000000000..1437e19e9c6 --- /dev/null +++ b/packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs @@ -0,0 +1,96 @@ +//! Proof executor for every proved count mode +//! ([`super::super::DocumentCountMode::PointLookupProof`], `RangeProof`, +//! `RangeDistinctProof` and `RangeAggregateCarrierProof`): it proves what the +//! request's [`CountProofPlan`] reads. The SDK's verifier rebuilds the path +//! query from the same plan. + +use super::super::super::conditions::WhereClause; +use super::super::{CountProofPlan, DriveDocumentCountQuery}; +use crate::drive::Drive; +use crate::error::Error; +use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; +use dpp::data_contract::document_type::DocumentTypeRef; +use dpp::version::PlatformVersion; +use grovedb::TransactionArg; + +impl Drive { + /// Proof of what `plan` reads: + /// + /// - the primary-key count tree: one merk path proof, O(log n) bytes; + /// - a point lookup: the matched branches' count trees, whose + /// `count_value` the verifier extracts with no document + /// materialization; + /// - a range: grovedb's `AggregateCountOnRange`, one `u64`; + /// - a distinct range: one `KVCount` per distinct in-range value, at most + /// the plan's limit of them; + /// - a carrier: one aggregate per outer `In` value or outer-range match + /// (grovedb's carrier-subquery composition). + /// + #[allow(clippy::too_many_arguments)] + pub(crate) fn execute_document_count_proof( + &self, + contract_id: [u8; 32], + document_type: DocumentTypeRef, + document_type_name: String, + where_clauses: Vec, + plan: CountProofPlan, + transaction: TransactionArg, + platform_version: &PlatformVersion, + ) -> Result, Error> { + // The index-reading arms each move the query parts into the query + // they prove. + let count_query = |index| DriveDocumentCountQuery { + document_type, + contract_id, + document_type_name, + index, + where_clauses, + }; + match plan { + CountProofPlan::PrimaryKeyCountTree => { + let path_query = DriveDocumentCountQuery::primary_key_count_tree_path_query( + contract_id, + document_type.name(), + ); + self.grove + .get_proved_path_query( + &path_query, + None, + transaction, + &platform_version.drive.grove_version, + ) + .unwrap() + .map_err(|e| Error::GroveDB(Box::new(e))) + } + CountProofPlan::PointLookup(index) => count_query(index) + .execute_point_lookup_count_with_proof(self, transaction, platform_version), + CountProofPlan::Range(index) => count_query(index).execute_aggregate_count_with_proof( + self, + transaction, + platform_version, + ), + CountProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => count_query(index).execute_distinct_count_with_proof( + self, + limit, + left_to_right, + transaction, + platform_version, + ), + CountProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => count_query(index).execute_carrier_aggregate_count_with_proof( + self, + limit, + left_to_right, + transaction, + platform_version, + ), + } + } +} diff --git a/packages/rs-drive/src/query/drive_document_count_query/executors/range_aggregate_carrier_proof.rs b/packages/rs-drive/src/query/drive_document_count_query/executors/range_aggregate_carrier_proof.rs deleted file mode 100644 index 7371d51efdc..00000000000 --- a/packages/rs-drive/src/query/drive_document_count_query/executors/range_aggregate_carrier_proof.rs +++ /dev/null @@ -1,94 +0,0 @@ -//! Carrier-ACOR proof executor for -//! [`super::super::DocumentCountMode::RangeAggregateCarrierProof`] -//! dispatch — `prove = true` count queries where the caller asks -//! for one aggregate per outer-key branch via -//! `group_by = [outer_field]`. The outer dimension is either: -//! -//! - An `In` clause on the index's first property (G7 shape — -//! `brand IN[...] AND color > floor`). One Key per In value. -//! - A range clause on the index's first property (G8 shape — -//! `brand > X AND color > floor`, optional `limit`). Single -//! QueryItem bounding the outer walk; `SizedQuery::limit` caps -//! how many outer matches the carrier walks before stopping. -//! -//! Uses grovedb's carrier-subquery composition introduced in -//! [PR #663](https://github.com/dashpay/grovedb/pull/663) and -//! extended in [PR #664](https://github.com/dashpay/grovedb/pull/664) -//! (the latter relaxed the `SizedQuery::limit` rejection for -//! carriers, which is what unblocks the G8 outer-range shape with -//! a useful upper bound). Returns proof bytes that the client -//! verifies via -//! [`grovedb::GroveDb::verify_aggregate_count_query_per_key`], -//! producing `Vec<(outer_key, u64)>` — same per-key aggregate -//! semantics as the no-proof per-In fan-out, just verifiable. - -use super::super::super::conditions::WhereClause; -use super::super::DriveDocumentCountQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Carrier-ACOR proof for `(In OR outer Range) + inner range` - /// with `group_by = [outer_field]`. Returns proof bytes that - /// the client verifies via - /// [`grovedb::GroveDb::verify_aggregate_count_query_per_key`]. - /// - /// `limit` caps the outer walk for the Range-outer (G8) shape; - /// for the In-outer (G7) shape the `|In|` array already bounds - /// the result and `limit` is typically `None`. - /// - /// Sibling executors (`range_distinct_proof`, `range_no_proof`, - /// `per_in_value`) use the same `#[allow]` here — the 8-arg - /// boundary (contract id, doc type, doc type name, where clauses, - /// limit, transaction, platform version) is the established - /// executor signature; refactoring it into a struct would just - /// move the same fields one indirection away. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_count_range_aggregate_carrier_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - limit: Option, - left_to_right: bool, - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - let index = DriveDocumentCountQuery::find_range_countable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "carrier-aggregate count requires a `range_countable: true` (or \ - summableOffCountIndex) index whose first \ - property carries the outer In or range clause and whose last property \ - carries the inner ACOR range clause" - .to_string(), - )) - })?; - let count_query = DriveDocumentCountQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - }; - count_query.execute_carrier_aggregate_count_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ) - } -} diff --git a/packages/rs-drive/src/query/drive_document_count_query/executors/range_distinct_proof.rs b/packages/rs-drive/src/query/drive_document_count_query/executors/range_distinct_proof.rs deleted file mode 100644 index 9ea27c0adc9..00000000000 --- a/packages/rs-drive/src/query/drive_document_count_query/executors/range_distinct_proof.rs +++ /dev/null @@ -1,73 +0,0 @@ -//! Distinct-range-count proof executor for -//! [`super::super::DocumentCountMode::RangeDistinctProof`] -//! dispatch — `prove = true` count queries with a range clause -//! and non-empty `group_by`. Emits per-distinct-value `KVCount` -//! ops the client verifies via -//! [`drive_proof_verifier::verify_distinct_count_proof`]. - -use super::super::super::conditions::WhereClause; -use super::super::DriveDocumentCountQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Distinct-counts-with-proof companion to - /// [`Self::execute_document_count_range_proof`]. Returns - /// proof bytes that the client verifies via - /// [`drive_proof_verifier::verify_distinct_count_proof`], - /// yielding a `BTreeMap, u64>` keyed by serialized - /// property value. - /// - /// `limit` caps the number of distinct in-range values the - /// proof covers — the dispatcher pre-validates - /// `limit ≤ max_query_limit` so client-side proof - /// reconstruction can use the exact same value without - /// divergence. The SDK reads it back off the request when - /// building the verifier's `PathQuery`. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_count_range_distinct_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - limit: u16, - left_to_right: bool, - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - let index = DriveDocumentCountQuery::find_range_countable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "range count requires a `range_countable: true` (or summableOffCountIndex) index whose last \ - property matches the range field" - .to_string(), - )) - })?; - let count_query = DriveDocumentCountQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - }; - count_query.execute_distinct_count_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ) - } -} diff --git a/packages/rs-drive/src/query/drive_document_count_query/executors/range_proof.rs b/packages/rs-drive/src/query/drive_document_count_query/executors/range_proof.rs deleted file mode 100644 index e70541313da..00000000000 --- a/packages/rs-drive/src/query/drive_document_count_query/executors/range_proof.rs +++ /dev/null @@ -1,54 +0,0 @@ -//! Range-count proof executor for -//! [`super::super::DocumentCountMode::RangeProof`] dispatch — -//! `prove = true` count queries with a range clause and empty -//! `group_by`. Uses grovedb's `AggregateCountOnRange` primitive -//! to emit a single u64 verified out of the proof. - -use super::super::super::conditions::WhereClause; -use super::super::DriveDocumentCountQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Range-count proof via grovedb's `AggregateCountOnRange`. - /// Returns proof bytes that the client verifies via - /// `GroveDb::verify_aggregate_count_query`. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_count_range_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - let index = DriveDocumentCountQuery::find_range_countable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "range count requires a `range_countable: true` (or summableOffCountIndex) index whose last \ - property matches the range field" - .to_string(), - )) - })?; - let count_query = DriveDocumentCountQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - }; - count_query.execute_aggregate_count_with_proof(self, transaction, platform_version) - } -} diff --git a/packages/rs-drive/src/query/drive_document_count_query/mod.rs b/packages/rs-drive/src/query/drive_document_count_query/mod.rs index 28ccd7dedd5..02b6d8a667a 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/mod.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/mod.rs @@ -7,6 +7,9 @@ //! - [`path_query`] — the load-bearing prover/verifier-agreement //! path-query builders (`aggregate_count_path_query`, //! `distinct_count_path_query`, `range_clause_to_query_item`). +//! - [`proof_plan`] — [`CountProofPlan`]: what a proved count reads and +//! the limit its path query carries, decided from the request alone by +//! the server's dispatcher and the SDK's verifier alike. //! - [`execute_point_lookup`] — Equal/In point-lookup execution //! (`execute_no_proof`, `execute_with_proof`). //! - [`execute_range_count`] — range-mode execution + `RangeCountOptions`. @@ -39,6 +42,10 @@ pub mod mode_detection; // match. pub mod index_picker; pub mod path_query; +// The request-only plan of a proved count, shared by the server's dispatcher +// and the SDK's verifier. +pub mod proof_plan; +pub use proof_plan::CountProofPlan; // Server-side execution paths. #[cfg(feature = "server")] diff --git a/packages/rs-drive/src/query/drive_document_count_query/path_query.rs b/packages/rs-drive/src/query/drive_document_count_query/path_query.rs index 2f556ba5d99..3d6fd632e1a 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/path_query.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/path_query.rs @@ -1223,7 +1223,7 @@ impl DriveDocumentCountQuery<'_> { /// count, no index walk needed. /// /// Shared between the server-side prove path - /// ([`Drive::execute_document_count_point_lookup_proof`]'s + /// (`Drive::execute_document_count_proof`'s primary-key /// documents_countable fast path) and the client-side verify path /// ([`Self::verify_primary_key_count_tree_proof`]). Both sides /// produce the exact same `PathQuery` for merk-root recomputation. diff --git a/packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs b/packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs new file mode 100644 index 00000000000..fff42587445 --- /dev/null +++ b/packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs @@ -0,0 +1,183 @@ +//! The request-only half of a proved count: which proof answers the +//! request, what that proof reads, and the limit and walk direction its +//! path query carries. +//! +//! The server's dispatcher proves what the plan names, and the SDK's +//! verifier rebuilds the path query from the same plan, so the two cannot +//! read one request differently; a client refuses before sending what the +//! plan refuses, in the server's words. + +use super::{DocumentCountMode, DriveDocumentCountQuery, QuerySyntaxError}; +use crate::config::DEFAULT_QUERY_LIMIT; +use crate::error::drive::DriveError; +use crate::error::Error; +use crate::query::{OrderClause, ResolvedTimeRange, WhereClause}; +use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; +use dpp::data_contract::document_type::{DocumentTypeRef, Index}; + +/// What a proved count reads, decided from its request alone. +#[derive(Debug, Clone, Copy, PartialEq)] +pub enum CountProofPlan<'a> { + /// An unfiltered count of a `documentsCountable` document type: the + /// type's primary-key count tree. + PrimaryKeyCountTree, + /// `Equal` / `In` clauses on a countable index: one count tree per + /// matched branch. + PointLookup(&'a Index), + /// A range on a range-countable index, ungrouped: one aggregate over the + /// range. + Range(&'a Index), + /// A range grouped by its values: one count per distinct value, walking + /// at most `limit` of them. + RangeDistinct { + /// The range-countable index the walk reads. + index: &'a Index, + /// The `SizedQuery` limit of the walk. + limit: u16, + /// The walk's direction, `Query::left_to_right`. + left_to_right: bool, + }, + /// A range grouped by an outer `In` or range: one aggregate per outer + /// key. + RangeAggregateCarrier { + /// The range-countable index the carrier reads. + index: &'a Index, + /// The `SizedQuery` limit of the outer walk; `None` for an `In` + /// outer, whose values bound it. + limit: Option, + /// The outer walk's direction, `Query::left_to_right`. + left_to_right: bool, + }, +} + +impl DriveDocumentCountQuery<'_> { + /// The [`CountProofPlan`] of a proved count over `document_type`. + /// + /// `where_clauses` are the request's clauses as the dispatcher reads them + /// (typed array elements keyed, canonicalized), `resolved_time_ranges` + /// their window provenance, and `mode` the proof mode + /// [`Self::detect_mode_versioned`] resolved them to. `order_clauses` and + /// `limit` are the request's, `limit` `None` when unset; a distinct or + /// carrier walk runs in the first order clause's direction, ascending + /// by default. + /// + /// `max_query_limit` is the node's configured cap on a distinct walk's + /// limit, checked before the index is picked. A client, which cannot + /// know a node's configuration, passes `None`; the node refuses a limit + /// above its own cap. + /// + /// The plan reads no version table, so every protocol version that serves + /// a proved count plans the same proof for the same request. + pub fn proof_plan<'a>( + document_type: &'a DocumentTypeRef<'_>, + where_clauses: &[WhereClause], + resolved_time_ranges: &[ResolvedTimeRange], + mode: DocumentCountMode, + order_clauses: &[OrderClause], + limit: Option, + max_query_limit: Option, + ) -> Result, Error> { + let left_to_right = order_clauses.first().map(|c| c.ascending).unwrap_or(true); + let range_index = || { + Self::find_range_countable_index_for_where_clauses( + document_type.indexes(), + where_clauses, + resolved_time_ranges, + ) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "range count requires a `range_countable: true` (or summableOffCountIndex) index whose last \ + property matches the range field" + .to_string(), + )) + }) + }; + match mode { + DocumentCountMode::RangeProof => Ok(CountProofPlan::Range(range_index()?)), + DocumentCountMode::RangeDistinctProof => { + // Validate-don't-clamp: the verifier rebuilds the walk's + // `SizedQuery::limit` byte for byte, so an over-cap limit is + // refused rather than clamped. An unset limit falls back to + // the compile-time `DEFAULT_QUERY_LIMIT`, never the + // operator-tunable `default_query_limit`, which a verifier + // cannot know. + let effective_limit = limit.unwrap_or(DEFAULT_QUERY_LIMIT as u32); + if let Some(max_query_limit) = max_query_limit { + if effective_limit > max_query_limit as u32 { + return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( + "limit {} exceeds max_query_limit {} on the prove + \ + distinct-walk path (GROUP BY a range field); reduce the \ + requested limit or use prove = false", + effective_limit, max_query_limit + )))); + } + } + // Within a node's `u16` cap this always converts. + let limit = u16::try_from(effective_limit).map_err(|_| { + Error::Query(QuerySyntaxError::InvalidLimit(format!( + "limit {effective_limit} exceeds u16::MAX; the prove-distinct path \ + query cannot represent it" + ))) + })?; + Ok(CountProofPlan::RangeDistinct { + index: range_index()?, + limit, + left_to_right, + }) + } + DocumentCountMode::PointLookupProof => { + // An unfiltered count of a `documents_countable` type proves the + // primary-key count tree directly, no index involved. + if where_clauses.is_empty() && document_type.documents_countable() { + return Ok(CountProofPlan::PrimaryKeyCountTree); + } + Self::find_countable_index_for_where_clauses( + document_type.indexes(), + where_clauses, + resolved_time_ranges, + ) + .map(CountProofPlan::PointLookup) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "prove count requires a `countable: true` (or summableOffCountIndex) index whose properties \ + exactly match the where clause fields, a `rangeCountable: true` \ + index they cover up to its last property, or `documentsCountable: \ + true` on the document type for unfiltered total counts — same \ + requirement as the no-proof path" + .to_string(), + )) + }) + } + DocumentCountMode::RangeAggregateCarrierProof => { + let limit = Self::carrier_aggregate_count_limit(where_clauses, limit)?; + let index = Self::find_range_countable_index_for_where_clauses( + document_type.indexes(), + where_clauses, + resolved_time_ranges, + ) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "carrier-aggregate count requires a `range_countable: true` (or \ + summableOffCountIndex) index whose first \ + property carries the outer In or range clause and whose last property \ + carries the inner ACOR range clause" + .to_string(), + )) + })?; + Ok(CountProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + }) + } + DocumentCountMode::Total + | DocumentCountMode::PerInValue + | DocumentCountMode::RangeNoProof => { + Err(Error::Drive(DriveError::CorruptedCodeExecution( + "a count proof plan is made only for a proof mode; mode detection with \ + prove = true never returns a no-proof mode", + ))) + } + } + } +} diff --git a/packages/rs-drive/src/query/drive_document_count_query/tests.rs b/packages/rs-drive/src/query/drive_document_count_query/tests.rs index 5f1a2176aba..c6926906cb1 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/tests.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/tests.rs @@ -1464,8 +1464,8 @@ fn test_count_request_with_duplicate_equality_clauses_is_rejected() { /// the reconstructed path query bytes differ and `verify_query` /// returns an error. /// -/// Without the fix in `drive_dispatcher.rs`'s `RangeDistinctProof` -/// arm this test fails. The "fix" is the one-line change from +/// Without the compile-time fallback in the count proof plan's +/// `RangeDistinctProof` arm this test fails. The "fix" is the one-line change from /// `request.drive_config.default_query_limit` to /// `crate::config::DEFAULT_QUERY_LIMIT` on the prove path — see /// the comment in that arm for the symmetric reasoning. diff --git a/packages/rs-drive/src/query/drive_document_having_query/drive_dispatcher.rs b/packages/rs-drive/src/query/drive_document_having_query/drive_dispatcher.rs index b8ce938adc9..39d01201a85 100644 --- a/packages/rs-drive/src/query/drive_document_having_query/drive_dispatcher.rs +++ b/packages/rs-drive/src/query/drive_document_having_query/drive_dispatcher.rs @@ -5,11 +5,13 @@ use super::super::drive_document_ranked_query::{RankedEntry, RankedPaginationInputs}; use super::mode_detection::detect_having_mode; use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; use crate::error::Error; use crate::query::having::HavingClause; use crate::query::projection::SelectProjection; -use crate::query::{key_array_element_clauses, OrderClause, ResolvedTimeRange, WhereClause}; +use crate::query::{ + key_array_element_clauses, refuse_several_window_selections, OrderClause, ResolvedTimeRange, + WhereClause, +}; use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; use dpp::data_contract::document_type::DocumentTypeRef; @@ -117,22 +119,14 @@ impl Drive { transaction: TransactionArg, platform_version: &PlatformVersion, ) -> Result { - // A transform's source must be its index's first property, so no - // single index can serve two resolved buckets; rejected before - // routing, mirroring the ranked dispatcher. A single resolution is - // consumed by index selection (the picker's admissibility rule + // No single index can serve two resolved buckets; rejected before + // routing, as the ranked dispatcher rejects them. A single resolution + // is consumed by index selection (the picker's admissibility rule // routes it to exactly the grid it was resolved against, and keeps // raw requests off bucketed indexes) — the resolved bucket-start // equality pins the bucketed first level like any other leading // property. - if request.resolved_time_ranges.len() > 1 { - return Err(Error::Query(QuerySyntaxError::Unsupported(format!( - "at most one window selection (IN_TIME_RANGE or IN_INTEGER_RANGE) is \ - supported per having-range query; this one resolves {:?}, and no single \ - index can bucket more than one field", - request.resolved_time_ranges - )))); - } + refuse_several_window_selections(request.resolved_time_ranges, "having-range query")?; // A typed array's elements are keyed first: one pinned element // (`contains`) at most, since rankings under several are not merged // per document (see [`key_array_element_clauses`]). diff --git a/packages/rs-drive/src/query/drive_document_ranked_query/drive_dispatcher.rs b/packages/rs-drive/src/query/drive_document_ranked_query/drive_dispatcher.rs index c1688eea9b9..be6ce612982 100644 --- a/packages/rs-drive/src/query/drive_document_ranked_query/drive_dispatcher.rs +++ b/packages/rs-drive/src/query/drive_document_ranked_query/drive_dispatcher.rs @@ -17,12 +17,13 @@ use super::mode_detection::detect_ranked_mode; use super::{RankedPage, RankedPaginationInputs}; use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; use crate::error::Error; use crate::query::having::HavingClause; use crate::query::projection::SelectProjection; use crate::query::ResolvedTimeRange; -use crate::query::{key_array_element_clauses, OrderClause, WhereClause}; +use crate::query::{ + key_array_element_clauses, refuse_several_window_selections, OrderClause, WhereClause, +}; use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; use dpp::data_contract::document_type::DocumentTypeRef; @@ -146,17 +147,9 @@ impl Drive { transaction: TransactionArg, platform_version: &PlatformVersion, ) -> Result { - // A transform's source must be its index's first property, so no - // single index can serve two resolved buckets; rejected before - // routing, mirroring `DriveDocumentQuery::select_best_index`. - if request.resolved_time_ranges.len() > 1 { - return Err(Error::Query(QuerySyntaxError::Unsupported(format!( - "at most one window selection (IN_TIME_RANGE or IN_INTEGER_RANGE) is \ - supported per ranked query; this one resolves {:?}, and no single index can \ - bucket more than one field", - request.resolved_time_ranges - )))); - } + // No single index can serve two resolved buckets; rejected before + // routing, as `DriveDocumentQuery::select_best_index` rejects them. + refuse_several_window_selections(request.resolved_time_ranges, "ranked query")?; // A typed array's elements are keyed first: one pinned element // (`contains`) at most, since rankings under several are not merged diff --git a/packages/rs-drive/src/query/drive_document_sum_query/drive_dispatcher.rs b/packages/rs-drive/src/query/drive_document_sum_query/drive_dispatcher.rs index 529a45f848a..063d289258e 100644 --- a/packages/rs-drive/src/query/drive_document_sum_query/drive_dispatcher.rs +++ b/packages/rs-drive/src/query/drive_document_sum_query/drive_dispatcher.rs @@ -16,8 +16,8 @@ use crate::error::query::QuerySyntaxError; use crate::error::Error; use crate::query::drive_document_count_query::drive_dispatcher as count_dispatcher; use crate::query::drive_document_sum_query::{ - DocumentSumMode, DocumentSumRequest, DocumentSumResponse, RangeSumOptions, RangeSumWalkMode, - SumMode, + DocumentSumMode, DocumentSumRequest, DocumentSumResponse, DriveDocumentSumQuery, + RangeSumOptions, RangeSumWalkMode, SumMode, }; use crate::query::{ key_array_element_clauses, validate_and_canonicalize_where_clauses, @@ -167,128 +167,46 @@ impl Drive { Ok(DocumentSumResponse::Entries(entries)) } } - DocumentSumMode::RangeProof => Ok(DocumentSumResponse::Proof( - self.execute_document_sum_range_proof( - contract_id, - request.document_type, - document_type_name, - where_clauses, - &resolved_time_ranges, - sum_property, - transaction, - platform_version, - )?, - )), - DocumentSumMode::RangeDistinctProof => { - // Validate-don't-clamp limit policy on the prove path: - // client-side proof reconstruction needs the EXACT - // limit value the server applied to the path query - // (the SDK rebuilds the same `SizedQuery::limit` for - // merk-root recomputation). Silent clamping or a - // tuned `default_query_limit` would byte-differ the - // reconstructed path query and break verification. + DocumentSumMode::RangeProof + | DocumentSumMode::RangeDistinctProof + | DocumentSumMode::PointLookupProof + | DocumentSumMode::RangeAggregateCarrierProof => { + // The request-only plan the SDK's verifier makes too: the + // primary-key route or the covering index, and the limit the + // path query carries (see `SumProofPlan`). // - // Limit fallback uses [`crate::config::DEFAULT_QUERY_LIMIT`] - // (compile-time constant), NOT - // `drive_config.default_query_limit` (operator-tunable - // runtime value). `max_query_limit` still gates the - // request as a DoS-protection knob — proofs never - // cross the operator-set ceiling, but the ceiling - // itself doesn't shape proof bytes; it only decides - // whether the request gets served. - // - // Mirrors count's policy at - // `drive_document_count_query::drive_dispatcher` - // `DocumentCountMode::RangeDistinctProof`. - let effective_limit = request - .limit - .unwrap_or(crate::config::DEFAULT_QUERY_LIMIT as u32); - if effective_limit > request.drive_config.max_query_limit as u32 { - return Err(Error::Query( - crate::error::query::QuerySyntaxError::InvalidLimit(format!( - "limit {} exceeds max_query_limit {} on the prove + \ - distinct-walk path (GROUP BY a range field, SUM); \ - reduce the requested limit or use prove = false", - effective_limit, request.drive_config.max_query_limit - )), - )); - } - let limit_u16 = u16::try_from(effective_limit).map_err(|_| { - Error::Query(crate::error::query::QuerySyntaxError::Unsupported(format!( - "limit {} exceeds u16::MAX for range-distinct sum proof", - effective_limit - ))) - })?; - Ok(DocumentSumResponse::Proof( - self.execute_document_sum_range_distinct_proof( - contract_id, - request.document_type, - document_type_name, - where_clauses, - &resolved_time_ranges, - sum_property, - limit_u16, - order_by_ascending, - transaction, - platform_version, - )?, - )) - } - DocumentSumMode::PointLookupProof => Ok(DocumentSumResponse::Proof( - self.execute_document_sum_point_lookup_proof( - contract_id, - request.document_type, - document_type_name, - where_clauses, + // Validate-don't-clamp limit policy on the prove path: + // client-side proof reconstruction needs the EXACT limit the + // server applied to the path query (the SDK rebuilds the same + // `SizedQuery::limit` for merk-root recomputation), so a limit + // above `max_query_limit` is refused rather than clamped. The + // distinct walk's unset limit falls back to the compile-time + // `DEFAULT_QUERY_LIMIT`, NOT the operator-tunable + // `default_query_limit`; the carrier's stays unset (an + // unbounded outer walk). `max_query_limit` still gates the + // request as a DoS-protection knob, but never shapes proof + // bytes. The distinct and carrier walks run in the first + // `order_by` clause's direction, ascending by default. + // Mirrors count's prove-path policy. + let plan = DriveDocumentSumQuery::proof_plan( + &request.document_type, + &where_clauses, &resolved_time_ranges, - sum_property, - transaction, - platform_version, - )?, - )), - DocumentSumMode::RangeAggregateCarrierProof => { - // Validate-don't-clamp limit policy on the prove path - // — same contract as RangeDistinctProof above. The - // carrier proof's outer-walk cap is `SizedQuery::limit` - // bytes-of-proof material; a silent clamp would - // byte-differ the SDK's reconstruction and break - // verification. Unlike the distinct arm, the carrier - // arm passes `Option` (None = unbounded outer - // walk), so the request's `None` stays `None` instead - // of falling back to a default. - let limit_u16 = request - .limit - .map(|l| { - if l > request.drive_config.max_query_limit as u32 { - return Err(Error::Query( - crate::error::query::QuerySyntaxError::InvalidLimit(format!( - "limit {} exceeds max_query_limit {} on the prove + \ - carrier-aggregate path (GROUP BY In + range, SUM); \ - reduce the requested limit or use prove = false", - l, request.drive_config.max_query_limit - )), - )); - } - u16::try_from(l).map_err(|_| { - Error::Query(crate::error::query::QuerySyntaxError::Unsupported( - format!( - "limit {} exceeds u16::MAX for carrier-aggregate sum proof", - l - ), - )) - }) - }) - .transpose()?; + &sum_property, + resolved_mode, + &request.order_clauses, + request.limit, + Some(request.drive_config.max_query_limit), + )?; Ok(DocumentSumResponse::Proof( - self.execute_document_sum_range_aggregate_carrier_proof( + self.execute_document_sum_proof( contract_id, request.document_type, document_type_name, where_clauses, - &resolved_time_ranges, sum_property, - limit_u16, - order_by_ascending, + plan, + false, transaction, platform_version, )?, diff --git a/packages/rs-drive/src/query/drive_document_sum_query/executors/mod.rs b/packages/rs-drive/src/query/drive_document_sum_query/executors/mod.rs index cd7450b7e55..f65ade83a2f 100644 --- a/packages/rs-drive/src/query/drive_document_sum_query/executors/mod.rs +++ b/packages/rs-drive/src/query/drive_document_sum_query/executors/mod.rs @@ -1,11 +1,9 @@ -//! Per-`DocumentSumMode` executor modules. Each module owns a single -//! executor function and the helpers it needs. Mirrors count's -//! `executors/` layout — file names parallel byte-for-byte. +//! Sum-query executor modules. One per no-proof `DocumentSumMode`, each +//! owning a single executor function and the helpers it needs, and one +//! ([`proof`]) for every proof mode and every proved average. Mirrors +//! count's `executors/` layout — file names parallel byte-for-byte. pub mod per_in_value; -pub mod point_lookup_proof; -pub mod range_aggregate_carrier_proof; -pub mod range_distinct_proof; +pub mod proof; pub mod range_no_proof; -pub mod range_proof; pub mod total; diff --git a/packages/rs-drive/src/query/drive_document_sum_query/executors/point_lookup_proof.rs b/packages/rs-drive/src/query/drive_document_sum_query/executors/point_lookup_proof.rs deleted file mode 100644 index a473fc657d1..00000000000 --- a/packages/rs-drive/src/query/drive_document_sum_query/executors/point_lookup_proof.rs +++ /dev/null @@ -1,86 +0,0 @@ -//! Point-lookup prove executor for sum queries. -//! Mirror of count's `executors/point_lookup_proof.rs`. - -use super::super::index_picker::find_summable_index_for_where_clauses; -use super::super::DriveDocumentSumQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use crate::query::WhereClause; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Point-lookup sum proof against a `summable: ""` index for - /// `prove = true` Equal/`In` sum queries, OR — when the where - /// clauses are empty and the document type has - /// `documents_summable: Some(matching_property)` — a proof of the - /// type's primary-key SumTree. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_sum_point_lookup_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - sum_property: String, - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters; - - // Fast path: unfiltered prove sum on a `documents_summable: - // Some(matching_property)` document type proves the - // primary-key SumTree element directly. - if where_clauses.is_empty() - && document_type - .documents_summable() - .map(|p| p == sum_property) - .unwrap_or(false) - { - let path_query = - DriveDocumentSumQuery::primary_key_sum_path_query(contract_id, &document_type_name); - let proof = self - .grove - .get_proved_path_query( - &path_query, - None, - transaction, - &platform_version.drive.grove_version, - ) - .unwrap() - .map_err(|e| Error::GroveDB(Box::new(e)))?; - return Ok(proof); - } - - let index = find_summable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - &sum_property, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "prove sum requires a `summable: \"\"` index whose properties \ - exactly match the where clause fields and whose summed property \ - matches the request's `sum_property`, or `documentsSummable: \ - \"\"` on the document type for unfiltered total sums — same \ - requirement as the no-proof path" - .to_string(), - )) - })?; - let sum_query = DriveDocumentSumQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - sum_property, - }; - sum_query.execute_point_lookup_sum_with_proof(self, transaction, platform_version) - } -} diff --git a/packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs b/packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs new file mode 100644 index 00000000000..fb2a6b46225 --- /dev/null +++ b/packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs @@ -0,0 +1,117 @@ +//! Proof executor for every proved sum mode +//! ([`super::super::DocumentSumMode::PointLookupProof`], `RangeProof`, +//! `RangeDistinctProof` and `RangeAggregateCarrierProof`) and every proved +//! average: it proves what the request's [`SumProofPlan`] reads. The SDK's +//! verifiers rebuild the path query from the same plan. + +use super::super::{DriveDocumentSumQuery, SumProofPlan}; +use crate::drive::Drive; +use crate::error::Error; +use crate::query::WhereClause; +use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; +use dpp::data_contract::document_type::DocumentTypeRef; +use dpp::version::PlatformVersion; +use grovedb::TransactionArg; + +impl Drive { + /// Proof of what `plan` reads: + /// + /// - the primary-key sum tree: one merk path proof; + /// - a point lookup: the matched branches' sum-bearing elements; + /// - a range: grovedb's `AggregateSumOnRange`, or with `with_counts` + /// its `AggregateCountAndSumOnRange` over a PCPS + /// (`ProvableCountProvableSumTree`) index; + /// - a distinct range: one element per distinct in-range value, at most + /// the plan's limit of them; + /// - a carrier: one aggregate per outer `In` value or outer-range match, + /// with `with_counts` a `(count, sum)` pair each. + /// + /// `with_counts` is whether the request is an average, whose range and + /// carrier proofs read each element's count beside its sum; its point + /// lookups and distinct walks read the count-sum-bearing elements the + /// index's terminators already hold. + #[allow(clippy::too_many_arguments)] + pub(crate) fn execute_document_sum_proof( + &self, + contract_id: [u8; 32], + document_type: DocumentTypeRef, + document_type_name: String, + where_clauses: Vec, + sum_property: String, + plan: SumProofPlan, + with_counts: bool, + transaction: TransactionArg, + platform_version: &PlatformVersion, + ) -> Result, Error> { + // The index-reading arms each move the query parts into the query + // they prove. + let sum_query = |index| DriveDocumentSumQuery { + document_type, + contract_id, + document_type_name, + index, + where_clauses, + sum_property, + }; + match plan { + SumProofPlan::PrimaryKeySumTree => { + let path_query = DriveDocumentSumQuery::primary_key_sum_path_query( + contract_id, + document_type.name(), + ); + self.grove + .get_proved_path_query( + &path_query, + None, + transaction, + &platform_version.drive.grove_version, + ) + .unwrap() + .map_err(|e| Error::GroveDB(Box::new(e))) + } + SumProofPlan::PointLookup(index) => sum_query(index) + .execute_point_lookup_sum_with_proof(self, transaction, platform_version), + SumProofPlan::Range(index) if with_counts => sum_query(index) + .execute_aggregate_count_and_sum_with_proof(self, transaction, platform_version), + SumProofPlan::Range(index) => sum_query(index).execute_aggregate_sum_with_proof( + self, + transaction, + platform_version, + ), + SumProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => sum_query(index).execute_distinct_sum_with_proof( + self, + limit, + left_to_right, + transaction, + platform_version, + ), + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } if with_counts => sum_query(index) + .execute_carrier_aggregate_count_and_sum_with_proof( + self, + limit, + left_to_right, + transaction, + platform_version, + ), + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => sum_query(index).execute_carrier_aggregate_sum_with_proof( + self, + limit, + left_to_right, + transaction, + platform_version, + ), + } + } +} diff --git a/packages/rs-drive/src/query/drive_document_sum_query/executors/range_aggregate_carrier_proof.rs b/packages/rs-drive/src/query/drive_document_sum_query/executors/range_aggregate_carrier_proof.rs deleted file mode 100644 index d72978ad5f2..00000000000 --- a/packages/rs-drive/src/query/drive_document_sum_query/executors/range_aggregate_carrier_proof.rs +++ /dev/null @@ -1,86 +0,0 @@ -//! Carrier-aggregate sum prove executor. Mirror of count's -//! [`crate::query::drive_document_count_query::executors::range_aggregate_carrier_proof`]. -//! -//! Routes a `(In OR outer Range) + inner range` sum request with -//! `group_by = [outer_field]` to the carrier `PathQuery` builder -//! ([`super::super::DriveDocumentSumQuery::carrier_aggregate_sum_path_query`]) -//! and asks grovedb for a proof. The client verifies via -//! [`grovedb::GroveDb::verify_aggregate_sum_query_per_key`] (grovedb -//! PR #670 head `e98bab5f`), producing `Vec<(outer_key, i64)>` — same -//! per-key aggregate semantics as the no-proof per-In fan-out, just -//! verifiable. - -use super::super::index_picker::find_range_summable_index_for_where_clauses; -use super::super::DriveDocumentSumQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use crate::query::WhereClause; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Carrier-aggregate sum proof for `(In OR outer Range) + inner - /// range` with `group_by = [outer_field]`. Returns proof bytes - /// that the client verifies via - /// [`grovedb::GroveDb::verify_aggregate_sum_query_per_key`]. - /// - /// `limit` caps the outer walk for the Range-outer shape; for - /// the In-outer shape the `|In|` array already bounds the result - /// and `limit` is typically `None`. - /// - /// Sibling executors (`range_distinct_proof`, `range_no_proof`, - /// `per_in_value`) use the same `#[allow]` here — the 9-arg - /// boundary (contract id, doc type, doc type name, where clauses, - /// sum_property, limit, left_to_right, transaction, platform - /// version) is the established executor signature; refactoring it - /// into a struct would just move the same fields one indirection - /// away. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_sum_range_aggregate_carrier_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - sum_property: String, - limit: Option, - left_to_right: bool, - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - let index = find_range_summable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - &sum_property, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "carrier-aggregate sum requires a `rangeSummable: true` index whose first \ - property carries the outer In or range clause and whose last property \ - carries the inner ASOR range clause" - .to_string(), - )) - })?; - let sum_query = DriveDocumentSumQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - sum_property, - }; - sum_query.execute_carrier_aggregate_sum_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ) - } -} diff --git a/packages/rs-drive/src/query/drive_document_sum_query/executors/range_distinct_proof.rs b/packages/rs-drive/src/query/drive_document_sum_query/executors/range_distinct_proof.rs deleted file mode 100644 index f0410e85658..00000000000 --- a/packages/rs-drive/src/query/drive_document_sum_query/executors/range_distinct_proof.rs +++ /dev/null @@ -1,66 +0,0 @@ -//! Per-distinct-key range-sum prove executor. -//! Mirror of count's `executors/range_distinct_proof.rs`. Returns -//! one `SumEntry` per distinct in-range value via `KVSum` ops. - -use super::super::index_picker::find_range_summable_index_for_where_clauses; -use super::super::DriveDocumentSumQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use crate::query::WhereClause; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Distinct-sums-with-proof companion to - /// [`Self::execute_document_sum_range_proof`]. Returns proof bytes - /// the client verifies via the per-distinct-sum verifier - /// (pending), yielding `BTreeMap, i64>` per distinct - /// value. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_sum_range_distinct_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - sum_property: String, - limit: u16, - left_to_right: bool, - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - let index = find_range_summable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - &sum_property, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "range sum requires a `rangeSummable: true` index whose last \ - property matches the range field" - .to_string(), - )) - })?; - let sum_query = DriveDocumentSumQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - sum_property, - }; - sum_query.execute_distinct_sum_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ) - } -} diff --git a/packages/rs-drive/src/query/drive_document_sum_query/executors/range_proof.rs b/packages/rs-drive/src/query/drive_document_sum_query/executors/range_proof.rs deleted file mode 100644 index 9907f03ddd4..00000000000 --- a/packages/rs-drive/src/query/drive_document_sum_query/executors/range_proof.rs +++ /dev/null @@ -1,57 +0,0 @@ -//! Range-sum prove executor. -//! Mirror of count's `executors/range_proof.rs`. Builds an -//! `AggregateSumOnRange` path query (grovedb PR 670) and returns proof -//! bytes verifiable via `GroveDb::verify_aggregate_sum_query`. - -use super::super::index_picker::find_range_summable_index_for_where_clauses; -use super::super::DriveDocumentSumQuery; -use crate::drive::Drive; -use crate::error::query::QuerySyntaxError; -use crate::error::Error; -use crate::query::ResolvedTimeRange; -use crate::query::WhereClause; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; -use dpp::data_contract::document_type::DocumentTypeRef; -use dpp::version::PlatformVersion; -use grovedb::TransactionArg; - -impl Drive { - /// Range-sum proof via grovedb's `AggregateSumOnRange` primitive - /// (PR 670). Returns proof bytes verified via - /// `GroveDb::verify_aggregate_sum_query`. - #[allow(clippy::too_many_arguments)] - pub(crate) fn execute_document_sum_range_proof( - &self, - contract_id: [u8; 32], - document_type: DocumentTypeRef, - document_type_name: String, - where_clauses: Vec, - resolved_time_ranges: &[ResolvedTimeRange], - sum_property: String, - transaction: TransactionArg, - platform_version: &PlatformVersion, - ) -> Result, Error> { - let index = find_range_summable_index_for_where_clauses( - document_type.indexes(), - &where_clauses, - &sum_property, - resolved_time_ranges, - ) - .ok_or_else(|| { - Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( - "range sum requires a `rangeSummable: true` index whose last \ - property matches the range field" - .to_string(), - )) - })?; - let sum_query = DriveDocumentSumQuery { - document_type, - contract_id, - document_type_name, - index, - where_clauses, - sum_property, - }; - sum_query.execute_aggregate_sum_with_proof(self, transaction, platform_version) - } -} diff --git a/packages/rs-drive/src/query/drive_document_sum_query/mod.rs b/packages/rs-drive/src/query/drive_document_sum_query/mod.rs index 50a544cbdde..23c410c6015 100644 --- a/packages/rs-drive/src/query/drive_document_sum_query/mod.rs +++ b/packages/rs-drive/src/query/drive_document_sum_query/mod.rs @@ -41,6 +41,13 @@ pub mod mode_detection; #[cfg(any(feature = "server", feature = "verify"))] pub mod path_query; +// The request-only plan of a proved sum or average, shared by the server's +// dispatchers and the SDK's verifiers. +#[cfg(any(feature = "server", feature = "verify"))] +pub mod proof_plan; +#[cfg(any(feature = "server", feature = "verify"))] +pub use proof_plan::SumProofPlan; + #[cfg(feature = "server")] pub mod execute_point_lookup; @@ -213,11 +220,9 @@ pub struct DocumentSumRequest<'a> { /// rather than clamped, so a tuned operator default or an /// over-max request can't byte-differ the /// `SizedQuery::limit` the SDK reconstructs for merk-root - /// verification. See the - /// [`drive_dispatcher`]'s `RangeDistinctProof` / - /// `RangeAggregateCarrierProof` arms for the - /// validate-don't-clamp policy, mirrored from count's - /// prove-path arms. + /// verification. See [`DriveDocumentSumQuery::proof_plan`] + /// for the validate-don't-clamp policy, mirrored from count's + /// proof plan. pub limit: Option, /// Whether to return a `Proof(Vec)` instead of materializing /// the aggregate/entries server-side. diff --git a/packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs b/packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs new file mode 100644 index 00000000000..a1dfd856788 --- /dev/null +++ b/packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs @@ -0,0 +1,226 @@ +//! The request-only half of a proved sum or average: which proof answers +//! the request, what that proof reads, and the limit and walk direction its +//! path query carries. +//! +//! A sum and an average read the same trees through the same path queries; +//! an average's range and carrier proofs read each element's count beside +//! its sum. They share [`SumProofPlan`], and each surface keeps its own +//! planner, since the server routes a sum by its resolved +//! [`DocumentSumMode`] and an average by its mode and whether a range +//! constrains it, each with its own refusals: this module plans a sum, and +//! [`crate::query::drive_document_average_query::proof_plan`] an average. +//! The server's dispatchers +//! prove what the plan names, and the SDK's verifiers rebuild the path query +//! from the same plan, so the two cannot read one request differently; a +//! client refuses before sending what the plan refuses, in the server's +//! words. The planners read no version table, so every protocol version +//! that serves a proved sum or average plans the same proof for the same +//! request. + +use super::index_picker::{ + find_range_summable_index_for_where_clauses, find_summable_index_for_where_clauses, +}; +use super::{DocumentSumMode, DriveDocumentSumQuery}; +use crate::config::DEFAULT_QUERY_LIMIT; +use crate::error::drive::DriveError; +use crate::error::query::QuerySyntaxError; +use crate::error::Error; +use crate::query::{OrderClause, ResolvedTimeRange, WhereClause}; +use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; +use dpp::data_contract::document_type::{DocumentTypeRef, Index}; + +/// What a proved sum or average reads, decided from its request alone. +#[derive(Debug, Clone, Copy, PartialEq)] +pub enum SumProofPlan<'a> { + /// An unfiltered total over a type summed by the requested property (for + /// an average, also `documentsCountable`): the type's primary-key sum + /// tree. + PrimaryKeySumTree, + /// `Equal` / `In` clauses on a summable index: one sum-bearing element + /// per matched branch. + PointLookup(&'a Index), + /// A range on a range-summable index, ungrouped: one aggregate over the + /// range. + Range(&'a Index), + /// A range grouped by its values: one entry per distinct value, walking + /// at most `limit` of them. + RangeDistinct { + /// The range-summable index the walk reads. + index: &'a Index, + /// The `SizedQuery` limit of the walk. + limit: u16, + /// The walk's direction, `Query::left_to_right`. + left_to_right: bool, + }, + /// A range grouped by an outer `In` or range: one aggregate per outer + /// key. + RangeAggregateCarrier { + /// The range-summable index the carrier reads. + index: &'a Index, + /// The `SizedQuery` limit of the outer walk; `None` leaves it + /// unbounded. + limit: Option, + /// The outer walk's direction, `Query::left_to_right`. + left_to_right: bool, + }, +} + +impl DriveDocumentSumQuery<'_> { + /// The [`SumProofPlan`] of a proved sum of `sum_property` over + /// `document_type`. + /// + /// `where_clauses` are the request's clauses as the dispatcher reads them + /// (typed array elements keyed, canonicalized), `resolved_time_ranges` + /// their window provenance, and `mode` the proof mode + /// [`detect_sum_mode_from_inputs`](super::mode_detection::detect_sum_mode_from_inputs) + /// resolved them to. `order_clauses` and `limit` are the request's, + /// `limit` `None` when unset; a distinct or carrier walk runs in the + /// first order clause's direction, ascending by default. + /// + /// `max_query_limit` is the node's configured cap on a proved walk's + /// limit, checked before the index is picked. A client, which cannot + /// know a node's configuration, passes `None`; the node refuses a limit + /// above its own cap. + #[allow(clippy::too_many_arguments)] + pub fn proof_plan<'a>( + document_type: &'a DocumentTypeRef<'_>, + where_clauses: &[WhereClause], + resolved_time_ranges: &[ResolvedTimeRange], + sum_property: &str, + mode: DocumentSumMode, + order_clauses: &[OrderClause], + limit: Option, + max_query_limit: Option, + ) -> Result, Error> { + let left_to_right = order_clauses.first().map(|c| c.ascending).unwrap_or(true); + let range_index = || { + find_range_summable_index_for_where_clauses( + document_type.indexes(), + where_clauses, + sum_property, + resolved_time_ranges, + ) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "range sum requires a `rangeSummable: true` index whose last \ + property matches the range field" + .to_string(), + )) + }) + }; + match mode { + DocumentSumMode::RangeProof => Ok(SumProofPlan::Range(range_index()?)), + DocumentSumMode::RangeDistinctProof => { + // Validate-don't-clamp: the verifier rebuilds the walk's + // `SizedQuery::limit` byte for byte, so an over-cap limit is + // refused rather than clamped. An unset limit falls back to + // the compile-time `DEFAULT_QUERY_LIMIT`, never the + // operator-tunable `default_query_limit`, which a verifier + // cannot know. + let effective_limit = limit.unwrap_or(DEFAULT_QUERY_LIMIT as u32); + if let Some(max_query_limit) = max_query_limit { + if effective_limit > max_query_limit as u32 { + return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( + "limit {} exceeds max_query_limit {} on the prove + \ + distinct-walk path (GROUP BY a range field, SUM); \ + reduce the requested limit or use prove = false", + effective_limit, max_query_limit + )))); + } + } + let limit = u16::try_from(effective_limit).map_err(|_| { + Error::Query(QuerySyntaxError::Unsupported(format!( + "limit {} exceeds u16::MAX for range-distinct sum proof", + effective_limit + ))) + })?; + Ok(SumProofPlan::RangeDistinct { + index: range_index()?, + limit, + left_to_right, + }) + } + DocumentSumMode::PointLookupProof => { + // An unfiltered sum over a type summed by the requested + // property proves the primary-key sum tree directly. + if where_clauses.is_empty() + && document_type + .documents_summable() + .map(|p| p == sum_property) + .unwrap_or(false) + { + return Ok(SumProofPlan::PrimaryKeySumTree); + } + find_summable_index_for_where_clauses( + document_type.indexes(), + where_clauses, + sum_property, + resolved_time_ranges, + ) + .map(SumProofPlan::PointLookup) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "prove sum requires a `summable: \"\"` index whose properties \ + exactly match the where clause fields and whose summed property \ + matches the request's `sum_property`, or `documentsSummable: \ + \"\"` on the document type for unfiltered total sums — same \ + requirement as the no-proof path" + .to_string(), + )) + }) + } + DocumentSumMode::RangeAggregateCarrierProof => { + // Validate-don't-clamp, as for the distinct walk; an unset + // limit stays unset (an unbounded outer walk) rather than + // falling back to a default. + let limit = limit + .map(|l| { + if let Some(max_query_limit) = max_query_limit { + if l > max_query_limit as u32 { + return Err(Error::Query(QuerySyntaxError::InvalidLimit(format!( + "limit {} exceeds max_query_limit {} on the prove + \ + carrier-aggregate path (GROUP BY In + range, SUM); \ + reduce the requested limit or use prove = false", + l, max_query_limit + )))); + } + } + u16::try_from(l).map_err(|_| { + Error::Query(QuerySyntaxError::Unsupported(format!( + "limit {} exceeds u16::MAX for carrier-aggregate sum proof", + l + ))) + }) + }) + .transpose()?; + let index = find_range_summable_index_for_where_clauses( + document_type.indexes(), + where_clauses, + sum_property, + resolved_time_ranges, + ) + .ok_or_else(|| { + Error::Query(QuerySyntaxError::WhereClauseOnNonIndexedProperty( + "carrier-aggregate sum requires a `rangeSummable: true` index whose first \ + property carries the outer In or range clause and whose last property \ + carries the inner ASOR range clause" + .to_string(), + )) + })?; + Ok(SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + }) + } + DocumentSumMode::Total + | DocumentSumMode::PerInValue + | DocumentSumMode::RangeNoProof => { + Err(Error::Drive(DriveError::CorruptedCodeExecution( + "a sum proof plan is made only for a proof mode; mode detection with \ + prove = true never returns a no-proof mode", + ))) + } + } + } +} diff --git a/packages/rs-drive/src/query/mod.rs b/packages/rs-drive/src/query/mod.rs index 2ef3ba79a39..b4dcd6a83e4 100644 --- a/packages/rs-drive/src/query/mod.rs +++ b/packages/rs-drive/src/query/mod.rs @@ -35,7 +35,7 @@ pub use { // (`DocumentCountMode`). Available under either `server` // (executor input) or `verify` (proof-decode input). drive_document_count_query::{ - CountMode, DocumentCountMode, DriveDocumentCountQuery, SplitCountEntry, + CountMode, CountProofPlan, DocumentCountMode, DriveDocumentCountQuery, SplitCountEntry, }, // Having-range verifier-shareable types — same split as ranked: // `DocumentHavingMode` + `AxisRangeBounds` to re-run the same @@ -59,7 +59,7 @@ pub use { // entry type the verifier returns, `SumMode` / `DriveDocumentSumQuery` // are shape inputs the verifier needs to rebuild the path query. // Parallels the count-side exports above. - drive_document_sum_query::{DriveDocumentSumQuery, SumEntry, SumMode}, + drive_document_sum_query::{DriveDocumentSumQuery, SumEntry, SumMode, SumProofPlan}, grovedb::{PathQuery, Query, QueryItem, SizedQuery}, having::{ HavingAggregate, HavingAggregateFunction, HavingClause, HavingOperator, HavingRightOperand, @@ -1700,6 +1700,32 @@ pub fn refuse_a_range_total_through_a_ranked_index( Ok(()) } +/// Refuses more than one window selection: a transform's source must be its +/// index's first property, so one index buckets exactly one field and no +/// index serves two resolved windows. Serving such a query would need a join +/// across two bucketed indexes, which the engine has no shape for. +/// `query_kind` names the query in the refusal ("query", "ranked query", +/// "having-range query"). +/// +/// The documents index pick, the ranked dispatcher and the having dispatcher +/// call it before they route a request, and a client calls it before sending +/// one, so all of them refuse two windows by one rule in one text, which +/// differs only by the query kind it names. +#[cfg(any(feature = "server", feature = "verify"))] +pub fn refuse_several_window_selections( + resolved_time_ranges: &[ResolvedTimeRange], + query_kind: &'static str, +) -> Result<(), Error> { + if resolved_time_ranges.len() > 1 { + return Err(Error::Query(QuerySyntaxError::Unsupported(format!( + "at most one window selection (IN_TIME_RANGE or IN_INTEGER_RANGE) is supported \ + per {query_kind}; this one resolves {resolved_time_ranges:?}, and no single \ + index can bucket more than one field" + )))); + } + Ok(()) +} + /// Rejects a query whose resolution provenance and clause shapes disagree: /// every field in `resolved_time_ranges` must appear in the where /// clauses as exactly one `Equal` clause — the only shape @@ -3410,19 +3436,9 @@ impl<'a> DriveDocumentQuery<'a> { &self, platform_version: &PlatformVersion, ) -> Result, Error> { - // A transform's source must be its index's first property, so one - // index buckets exactly one field and no index can carry two resolved - // equalities. Serving such a query would need a join across two - // bucketed indexes, which the engine has no shape for. This runs - // before any routing so the multiple-`In` path cannot bypass it. - if self.resolved_time_ranges.len() > 1 { - return Err(Error::Query(QuerySyntaxError::Unsupported(format!( - "at most one window selection (IN_TIME_RANGE or IN_INTEGER_RANGE) is \ - supported per query; this one resolves {:?}, and no single index can bucket \ - more than one field", - self.resolved_time_ranges - )))); - } + // No index can carry two resolved equalities. This runs before any + // routing so the multiple-`In` path cannot bypass it. + refuse_several_window_selections(&self.resolved_time_ranges, "query")?; // One shared source-shape guard for every selection route — see its // doc for the contract. Running it before routing keeps the single- @@ -4147,6 +4163,9 @@ impl<'a> From<&DriveDocumentQuery<'a>> for BTreeMap { #[cfg(all(test, feature = "server"))] pub(crate) mod unsigned_index_key_order_tests; +#[cfg(all(test, feature = "server"))] +mod window_selection_cardinality_tests; + #[cfg(feature = "server")] #[cfg(test)] mod tests { diff --git a/packages/rs-drive/src/query/window_selection_cardinality_tests.rs b/packages/rs-drive/src/query/window_selection_cardinality_tests.rs new file mode 100644 index 00000000000..a4479a00501 --- /dev/null +++ b/packages/rs-drive/src/query/window_selection_cardinality_tests.rs @@ -0,0 +1,192 @@ +//! The refusal of a request carrying two window selections, as each server path that refuses +//! it words it. A transform's source is its index's first property, so an index buckets one +//! field and no index serves two windows; the documents query, the ranked dispatcher and the +//! having dispatcher refuse such a request before routing it, and a client refuses it before +//! sending in the same words. These texts reach callers, so they are pinned byte for byte. + +use crate::drive::Drive; +use crate::error::query::QuerySyntaxError; +use crate::error::Error; +use crate::query::having::{ + HavingAggregate, HavingAggregateFunction, HavingClause, HavingOperator, HavingRightOperand, +}; +use crate::query::projection::SelectProjection; +use crate::query::{ + refuse_several_window_selections, resolve_integer_range_bucket_clause, + resolve_time_range_bucket_clause, DocumentHavingRequest, DocumentRankedRequest, + DriveDocumentQuery, OrderClause, ResolvedTimeRange, TimeRangeSelector, +}; +use crate::util::test_helpers::setup::setup_drive_with_initial_state_structure; +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::DataContractFactory; +use dpp::platform_value::{platform_value, Identifier, Value}; +use dpp::prelude::DataContract; +use dpp::version::PlatformVersion; + +/// A `listing` whose `price` is bucketed in windows of 100 and whose `$createdAt` in daily +/// windows, each under its own index, so a window on each field resolves. +fn windowed_contract() -> DataContract { + let schemas = platform_value!({"listing": { + "type": "object", + "properties": { + "price": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 0}, + "category": {"type": "string", "minLength": 1, "maxLength": 63, "position": 1} + }, + "required": ["price", "category", "$createdAt"], + "indices": [ + {"name": "byPriceBand", + "properties": [{"price": "asc"}, {"category": "asc"}], + "integerRange": {"on": "price", "range": 100u64, "step": 100u64}, + "countable": "countable"}, + {"name": "byDay", + "properties": [{"$createdAt": "asc"}, {"category": "asc"}], + "timeRange": {"on": "$createdAt", "range": 86400, "step": 86400}, + "countable": "countable"} + ], + "additionalProperties": false + }}); + DataContractFactory::new(PlatformVersion::latest().protocol_version) + .expect("factory") + .create_with_value_config(Identifier::from([203u8; 32]), 0, schemas, None, None) + .expect("the listing contract is well-formed") + .data_contract_owned() +} + +/// One resolved window on `price` and one on `$createdAt`. +fn two_windows(contract: &DataContract) -> Vec { + let document_type = contract + .document_type_for_name("listing") + .expect("the contract has this document type"); + let (_, price) = + resolve_integer_range_bucket_clause("price", &Value::U64(200), None, document_type) + .expect("a price window resolves"); + let (_, created_at) = resolve_time_range_bucket_clause( + "$createdAt", + TimeRangeSelector::Newest, + None, + document_type, + 1_700_000_000_000, + ) + .expect("a day window resolves"); + vec![price, created_at] +} + +/// The text a server path refuses two windows with, `query_kind` naming the query. +fn expected_refusal(query_kind: &str, resolved: &[ResolvedTimeRange]) -> String { + format!( + "at most one window selection (IN_TIME_RANGE or IN_INTEGER_RANGE) is supported per \ + {query_kind}; this one resolves {resolved:?}, and no single index can bucket more \ + than one field" + ) +} + +fn assert_refused_in(result: Result<(), Error>, query_kind: &str, resolved: &[ResolvedTimeRange]) { + match result { + Err(Error::Query(QuerySyntaxError::Unsupported(text))) => { + assert_eq!(text, expected_refusal(query_kind, resolved)) + } + other => panic!("expected the two-window refusal per {query_kind}, got {other:?}"), + } +} + +#[test] +fn should_refuse_two_windows_on_a_documents_query_before_picking_an_index() { + let platform_version = PlatformVersion::latest(); + let contract = windowed_contract(); + let resolved = two_windows(&contract); + let mut query = DriveDocumentQuery::all_items_query( + &contract, + contract + .document_type_for_name("listing") + .expect("the contract has this document type"), + None, + ); + query.resolved_time_ranges = resolved.clone(); + assert_refused_in( + query.find_best_index(platform_version).map(drop), + "query", + &resolved, + ); +} + +#[test] +fn should_refuse_two_windows_on_a_ranked_or_having_request_before_routing_it() { + let platform_version = PlatformVersion::latest(); + let drive: Drive = setup_drive_with_initial_state_structure(Some(platform_version)); + let contract = windowed_contract(); + let resolved = two_windows(&contract); + let document_type = contract + .document_type_for_name("listing") + .expect("the contract has this document type"); + let group_by = vec!["category".to_string()]; + let order_by = vec![OrderClause { + field: "$count".to_string(), + ascending: false, + }]; + + let ranked = drive.execute_document_ranked_request( + DocumentRankedRequest { + contract: &contract, + document_type, + group_by: &group_by, + select: SelectProjection::count_star(), + having: &[], + order_by: &order_by, + where_clauses: &[], + limit: Some(5), + offset: None, + has_start_at: false, + prove: true, + resolved_time_ranges: &resolved, + }, + None, + platform_version, + ); + assert_refused_in(ranked.map(drop), "ranked query", &resolved); + + let having = [HavingClause { + aggregate: HavingAggregate { + function: HavingAggregateFunction::Count, + field: String::new(), + }, + operator: HavingOperator::GreaterThan, + right: HavingRightOperand::Value(Value::U64(1)), + }]; + let having = drive.execute_document_having_request( + DocumentHavingRequest { + contract: &contract, + document_type, + group_by: &group_by, + select: SelectProjection::count_star(), + having: &having, + order_by: &[], + where_clauses: &[], + resolved_time_ranges: &resolved, + limit: Some(5), + offset: None, + has_start_at: false, + prove: true, + }, + None, + platform_version, + ); + assert_refused_in(having.map(drop), "having-range query", &resolved); +} + +/// Each server path refuses through the one helper; its words for each query kind are the ones +/// the paths above refuse with. +#[test] +fn should_word_the_refusal_of_two_windows_by_the_query_kind() { + let contract = windowed_contract(); + let resolved = two_windows(&contract); + for query_kind in ["query", "ranked query", "having-range query"] { + assert_refused_in( + refuse_several_window_selections(&resolved, query_kind), + query_kind, + &resolved, + ); + } + refuse_several_window_selections(&resolved[..1], "query") + .expect("one window is served by the index that buckets it"); + refuse_several_window_selections(&[], "query").expect("a request without windows"); +} From 4ce431b8988a6f9c2836a5d15db424b2d54e5cf1 Mon Sep 17 00:00:00 2001 From: Ivan Shumkov Date: Thu, 5 Nov 2026 15:40:54 +0700 Subject: [PATCH 2/4] refactor(sdk): check document requests with Drive's own request-only planning before sending MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The SDK's check before sending (`FromProof::check_request`) for document requests now runs the request-only half of the request's own verifier, which is Drive code the node runs too: - Documents: drive-proof-verifier's `FromProof for Documents` gains `check_request`, Drive's `construct_path_query(None, ..)` — the lowering the verifier runs on every page, cursor pages included. The check and the verifier build their Drive query through one `drive_query_with_provenance`, so neither drops the windows' resolution provenance. - Count, sum, average: the check and the verifier both take Drive's `CountProofPlan` / `SumProofPlan`, and the verifiers pick their primitive by the plan. The average verifier now routes as the average server does; the duplicated `resolve_sum_mode` is gone. - Two windows are refused through Drive's `refuse_several_window_selections`. A request no node serves (no covering index, two windows) now fails before sending with `InvalidRequest` instead of `INVALID_ARGUMENT` after a round trip. Test would have caught this in CI: ✖ before fix, ✔ after — - should_refuse_a_documents_select_no_index_covers_before_sending (price window + $createdAt equality): ✖ "Document must refuse … got Ok(())" - should_refuse_an_aggregate_no_index_serves_before_sending (SUM/AVG(price) on a countable-only type, COUNT on a type that counts nothing): ✖ "DocumentSum must refuse … got Ok(())" - should_refuse_windows_on_two_fields_before_sending (Drive's words): ✖ "… this one resolves 2, and …" - drive-abci index_coverage::should_refuse_before_sending_exactly_the_ requests_no_index_serves: ✖ "shape 0 (Documents): the check before sending says Ok(())" while the node refused every uncovered shape. The provenance guard (should_send_a_documents_select_pinned_to_a_window_ its_index_buckets) passes before and after, and fails when the shared builder drops the provenance. Fixture migrations, each a test querying something no node serves: the aggregate views now use types that count and sum; the windowed listing sums a `quantity`; the typed-array post has a summing index; rs-sdk's count mocks use a countable mock type; the protocol-gate `contains` fixture is a typed array, and the mock-not-gating test uses a composite page. Co-Authored-By: Claude Opus 5.5 --- .../src/documents/average_proof_helpers.rs | 415 +++++------- .../src/documents/check_request_tests.rs | 615 ++++++++++++++++-- .../src/documents/count_proof_helpers.rs | 354 ++++------ .../src/documents/document_query.rs | 68 +- .../src/documents/sum_proof_helpers.rs | 359 +++++----- .../tests/query_request_errors.rs | 2 + .../query_request_errors/index_coverage.rs | 296 +++++++++ packages/rs-drive-proof-verifier/src/proof.rs | 30 + .../rs-sdk/src/sdk/protocol_gate_tests.rs | 50 +- packages/rs-sdk/tests/fetch/common.rs | 51 ++ packages/rs-sdk/tests/fetch/document_count.rs | 18 +- 11 files changed, 1489 insertions(+), 769 deletions(-) create mode 100644 packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs diff --git a/packages/dash-platform-queries/src/documents/average_proof_helpers.rs b/packages/dash-platform-queries/src/documents/average_proof_helpers.rs index 675500fda37..f1da6aa9a6d 100644 --- a/packages/dash-platform-queries/src/documents/average_proof_helpers.rs +++ b/packages/dash-platform-queries/src/documents/average_proof_helpers.rs @@ -7,38 +7,32 @@ //! [`DocumentAverage`] sums into a single `(count, sum)` pair, //! [`DocumentSplitAverages`] passes the entries through. //! -//! Routing is driven by drive's resolved [`DocumentSumMode`] (via -//! [`detect_sum_mode_from_inputs`]) — same as the SUM helper. -//! AVG and SUM share the same routing table because their grovedb -//! primitives differ only in which element type is extracted -//! (`KVCountSum` for AVG vs `KVSum` for SUM); the dispatch -//! decisions are otherwise identical, which is why drive's -//! `drive_dispatcher` translates `AverageMode` → `(CountMode, -//! SumMode)` 1:1 before invoking the per-mode executor. +//! Routing is driven by drive's [`SumProofPlan`] for an average (via +//! [`DriveDocumentSumQuery::average_proof_plan`], the plan the +//! server's average dispatcher proves by). AVG and SUM share the plan +//! type because their grovedb primitives differ only in which element +//! type is extracted (`KVCountSum` for AVG vs `KVSum` for SUM), but an +//! average is planned by its own [`AverageMode`] and whether a range +//! constrains it, exactly as the server plans it. //! //! [`DocumentAverage`]: drive_proof_verifier::DocumentAverage //! [`DocumentSplitAverages`]: drive_proof_verifier::DocumentSplitAverages use crate::documents::array_element_clauses::{ - aggregate_request_where_clauses, aggregate_where_clauses, + aggregate_request_where_clauses, aggregate_where_clauses, document_type_named, }; use crate::documents::document_query::normalize_time_range_clauses_with_metadata_time; use crate::documents::document_query::DocumentQuery; +use crate::documents::sum_proof_helpers::resolve_sum_mode; use dapi_grpc::platform::v0::{GetDocumentsResponse, Proof, ResponseMetadata}; use dapi_grpc::platform::VersionedGrpcResponse; use dash_context_provider::ContextProvider; +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::DocumentTypeRef; use dpp::version::PlatformVersion; -use dpp::{ - data_contract::accessors::v0::DataContractV0Getters, - data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}, -}; -use drive::query::drive_document_sum_query::index_picker::{ - find_range_summable_index_with_counts_for_where_clauses, - find_summable_index_with_counts_for_where_clauses, -}; -use drive::query::drive_document_sum_query::mode_detection::detect_sum_mode_from_inputs; -use drive::query::drive_document_sum_query::{DocumentSumMode, DriveDocumentSumQuery, SumMode}; -use drive::query::{SelectFunction, WhereOperator}; +use drive::query::drive_document_average_query::AverageMode; +use drive::query::drive_document_sum_query::{DriveDocumentSumQuery, SumMode, SumProofPlan}; +use drive::query::{OrderClause, ResolvedTimeRange, SelectFunction, WhereClause}; use drive_proof_verifier::{ verify_aggregate_count_and_sum_proof, verify_carrier_aggregate_count_and_sum_proof, verify_distinct_count_and_sum_proof, verify_point_lookup_count_and_sum_proof, @@ -73,7 +67,9 @@ pub(super) fn assert_select_is_avg( /// The refusals [`verify_average_query`] makes from the request alone, made /// before it is sent, for the reasons /// [`check_count_request`](super::count_proof_helpers::check_count_request) -/// gives. +/// gives. The last check is the verifier's proof plan +/// ([`average_proof_plan`]), which the node plans its proof by too, so an +/// average no index serves is refused here in the node's words. pub(super) fn check_average_request( request: &DocumentQuery, folds_entries: bool, @@ -81,43 +77,96 @@ pub(super) fn check_average_request( ) -> Result<(), drive_proof_verifier::Error> { request.ensure_no_sub_queries()?; assert_select_is_avg(request)?; - let (resolved, _) = request.resolved_for_checking()?; + let (resolved, resolved_time_ranges) = request.resolved_for_checking()?; let request = &resolved; let where_clauses = aggregate_request_where_clauses(request, folds_entries, platform_version)?; - resolve_sum_mode(&request.group_by, &where_clauses)?; - request.ensure_no_having() + let average_mode = resolve_average_mode(&request.group_by, &where_clauses)?; + request.ensure_no_having()?; + let document_type = document_type_named(&request.data_contract, &request.document_type_name)?; + average_proof_plan( + &document_type, + &where_clauses, + &resolved_time_ranges, + &request.select.field, + average_mode, + &request.order_by_clauses, + request.limit, + ) + .map(drop) +} + +/// The SQL-shape [`AverageMode`] of an average request: the [`SumMode`] a sum +/// over the same `(group_by, where_clauses)` resolves to +/// ([`resolve_sum_mode`]), mapped 1:1 as drive-abci maps it. +fn resolve_average_mode( + group_by: &[String], + where_clauses: &[WhereClause], +) -> Result { + Ok(match resolve_sum_mode(group_by, where_clauses)? { + SumMode::Aggregate => AverageMode::Aggregate, + SumMode::GroupByIn => AverageMode::GroupByIn, + SumMode::GroupByRange => AverageMode::GroupByRange, + SumMode::GroupByCompound => AverageMode::GroupByCompound, + }) +} + +/// The proof plan a node makes for a proved average of `sum_property`, made +/// from the request alone ([`DriveDocumentSumQuery::average_proof_plan`]): the +/// primary-key route or the covering index, and the limit the path query +/// carries. A client cannot know a node's `max_query_limit`, so it leaves that +/// check to the node. +/// +/// `order_clauses` and `limit` are the request's, `limit` `0` when unset. +fn average_proof_plan<'a>( + document_type: &'a DocumentTypeRef<'_>, + where_clauses: &[WhereClause], + resolved_time_ranges: &[ResolvedTimeRange], + sum_property: &str, + average_mode: AverageMode, + order_clauses: &[OrderClause], + limit: u32, +) -> Result, drive_proof_verifier::Error> { + DriveDocumentSumQuery::average_proof_plan( + document_type, + where_clauses, + resolved_time_ranges, + sum_property, + average_mode, + order_clauses, + (limit != 0).then_some(limit), + None, + ) + .map_err(|e| drive_proof_verifier::Error::RequestError { + error: format!("no answer to this average can be verified: {e}"), + }) } /// Verify an AVG-shape proof and return per-branch `AverageEntry`s. /// -/// Picks the verifier primitive by **drive's resolved -/// [`DocumentSumMode`]** (AVG reuses SUM's resolved-mode space — -/// see module docstring) rather than a clause-shape heuristic, so -/// the SDK's routing matches the server's exactly. +/// Picks the verifier primitive by **Drive's [`SumProofPlan`] for an +/// average**, the plan the server's average dispatcher proved by, +/// rather than a clause-shape heuristic, so the SDK's routing matches +/// the server's exactly. /// -/// **Routing**: build a [`SumMode`] from `(group_by, +/// **Routing**: build an [`AverageMode`] from `(group_by, /// where_clauses)` matching the abci handler's `validate_and_route` -/// logic, then call [`detect_sum_mode_from_inputs`] with -/// `prove = true` to get the resolved [`DocumentSumMode`]. Branch -/// by the resolved mode: +/// logic, then take Drive's plan ([`average_proof_plan`]). Branch by +/// the plan: /// -/// - [`DocumentSumMode::PointLookupProof`] (no range, with or -/// without `In`) → [`verify_point_lookup_count_and_sum_proof`]. -/// Special-case: doctype-level `documentsCountable + -/// documentsSummable` + empty where → -/// [`verify_primary_key_count_sum_tree_proof`]. -/// - [`DocumentSumMode::RangeProof`] (range, no In, no distinct) → +/// - [`SumProofPlan::PrimaryKeySumTree`] (empty where on a doctype +/// that declares `documentsCountable` and sums by the averaged +/// property) → [`verify_primary_key_count_sum_tree_proof`]. +/// - [`SumProofPlan::PointLookup`] (no range, with or without `In`) +/// → [`verify_point_lookup_count_and_sum_proof`]. +/// - [`SumProofPlan::Range`] (range, ungrouped) → /// [`verify_aggregate_count_and_sum_proof`] → single empty-key /// entry. -/// - [`DocumentSumMode::RangeDistinctProof`] (range + distinct walk -/// via `GroupByRange` / `GroupByCompound`) → +/// - [`SumProofPlan::RangeDistinct`] (range + distinct walk via +/// `GroupByRange` / `GroupByCompound`) → /// [`verify_distinct_count_and_sum_proof`]. -/// - [`DocumentSumMode::RangeAggregateCarrierProof`] (`In + range + +/// - [`SumProofPlan::RangeAggregateCarrier`] (`In + range + /// group_by = [in_field]` on the prove path) → /// [`verify_carrier_aggregate_count_and_sum_proof`]. -/// - `Total` / `PerInValue` / `RangeNoProof` are no-proof modes -/// that should be unreachable here (`prove = true`); reject as -/// `RequestError` if they bubble through. /// /// `folds_entries` is whether the caller adds the verified entries up into one /// total ([`aggregate_where_clauses`]). @@ -169,245 +218,89 @@ pub(super) fn verify_average_query( platform_version, )?; - // Resolve the SQL-shape `SumMode` the request implies — AVG - // shares the routing table with SUM (see module docstring), so - // we use the same SumMode resolver. The shape is mechanically - // identical to `AverageMode` (Aggregate / GroupByIn / - // GroupByRange / GroupByCompound). - let sum_mode = resolve_sum_mode(&request.group_by, &request.where_clauses)?; - - let resolved_mode = - detect_sum_mode_from_inputs(&request.where_clauses, sum_mode, true, platform_version) - .map_err(|e| drive_proof_verifier::Error::RequestError { - error: format!("avg-mode detection failed (via sum-mode router): {e}"), - })?; - - // Empty-where AVG fast path: primary-key count-sum-bearing - // element direct read. Doctype must declare BOTH - // `documentsCountable` AND a matching `documentsSummable`. - if matches!(resolved_mode, DocumentSumMode::PointLookupProof) - && request.where_clauses.is_empty() - && document_type.documents_countable() - && document_type - .documents_summable() - .map(|p| p == sum_property) - .unwrap_or(false) - { - let (count, sum) = verify_primary_key_count_sum_tree_proof( - contract_id, - &request.document_type_name, - proof, - mtd, - platform_version, - provider, - )?; - return Ok(( - Some(single_empty_key_entry(count, sum)), - mtd.clone(), - proof.clone(), - )); - } + // Resolve the SQL-shape `AverageMode` the request implies — the + // same decision tree as `validate_and_route` in the abci handler, + // which maps it 1:1 from the count / sum mode. + let average_mode = resolve_average_mode(&request.group_by, &request.where_clauses)?; - // Pick the index the prover would have picked. Range modes need - // an index that's BOTH `range_summable: true` AND - // `range_countable: true` (i.e. PCPS) — that's the surface a - // `rangeAverageable: true` index resolves to. Everything else - // uses a summable + countable terminator. - let needs_range_index = matches!( - resolved_mode, - DocumentSumMode::RangeProof - | DocumentSumMode::RangeDistinctProof - | DocumentSumMode::RangeAggregateCarrierProof - ); - let index = if needs_range_index { - find_range_summable_index_with_counts_for_where_clauses( - document_type.indexes(), - &request.where_clauses, - &sum_property, - &resolved_time_ranges, - ) - .ok_or_else(|| drive_proof_verifier::Error::RequestError { - error: "prove range AVG requires an index that declares BOTH `rangeCountable: \ - true` AND `rangeSummable: true` (a `rangeAverageable: true` \ - index is the shorthand) whose last property matches the range \ - field and whose summable property matches the request's \ - select `field`" - .to_string(), - })? - } else { - find_summable_index_with_counts_for_where_clauses( - document_type.indexes(), - &request.where_clauses, - &sum_property, - &resolved_time_ranges, - ) - .ok_or_else(|| drive_proof_verifier::Error::RequestError { - error: "prove AVG requires an index that declares BOTH `summable: \ - \"\"` AND a countable terminator (`countable: \ - \"countable\"` or `\"countableAllowingOffset\"`) whose properties \ - exactly match the where clause fields" - .to_string(), - })? - }; - let sum_query = DriveDocumentSumQuery { + // Drive's plan, the one the prover made from the same request: the + // primary-key route or covering index, and the limit the path query + // carries. + let plan = average_proof_plan( + &document_type, + &request.where_clauses, + &resolved_time_ranges, + &sum_property, + average_mode, + &request.order_by_clauses, + request.limit, + )?; + let sum_query = |index| DriveDocumentSumQuery { document_type, contract_id, document_type_name: request.document_type_name.clone(), index, where_clauses: request.where_clauses.clone(), - sum_property, + sum_property: sum_property.clone(), }; - match resolved_mode { - DocumentSumMode::PointLookupProof => { - let entries = verify_point_lookup_count_and_sum_proof( - &sum_query, + let entries = match plan { + SumProofPlan::PrimaryKeySumTree => { + let (count, sum) = verify_primary_key_count_sum_tree_proof( + contract_id, + &request.document_type_name, proof, mtd, platform_version, provider, )?; - Ok((Some(entries), mtd.clone(), proof.clone())) + single_empty_key_entry(count, sum) } - DocumentSumMode::RangeProof => { + SumProofPlan::PointLookup(index) => verify_point_lookup_count_and_sum_proof( + &sum_query(index), + proof, + mtd, + platform_version, + provider, + )?, + SumProofPlan::Range(index) => { let (count, sum) = verify_aggregate_count_and_sum_proof( - &sum_query, + &sum_query(index), proof, mtd, platform_version, provider, )?; - Ok(( - Some(single_empty_key_entry(count, sum)), - mtd.clone(), - proof.clone(), - )) + single_empty_key_entry(count, sum) } - DocumentSumMode::RangeDistinctProof => { - let limit_u16 = if request.limit == 0 { - drive::config::DEFAULT_QUERY_LIMIT - } else { - u16::try_from(request.limit).map_err(|_| { - drive_proof_verifier::Error::RequestError { - error: format!( - "limit {} exceeds u16::MAX for distinct AVG proof", - request.limit - ), - } - })? - }; - let left_to_right = request - .order_by_clauses - .first() - .map(|c| c.ascending) - .unwrap_or(true); - let entries = verify_distinct_count_and_sum_proof( - &sum_query, - proof, - mtd, - limit_u16, - left_to_right, - platform_version, - provider, - )?; - Ok((Some(entries), mtd.clone(), proof.clone())) - } - DocumentSumMode::RangeAggregateCarrierProof => { - let limit_u16 = if request.limit == 0 { - None - } else { - Some(u16::try_from(request.limit).map_err(|_| { - drive_proof_verifier::Error::RequestError { - error: format!( - "limit {} exceeds u16::MAX for carrier-aggregate AVG proof", - request.limit - ), - } - })?) - }; - let left_to_right = request - .order_by_clauses - .first() - .map(|c| c.ascending) - .unwrap_or(true); - let entries = verify_carrier_aggregate_count_and_sum_proof( - &sum_query, - proof, - mtd, - limit_u16, - left_to_right, - platform_version, - provider, - )?; - Ok((Some(entries), mtd.clone(), proof.clone())) - } - DocumentSumMode::Total | DocumentSumMode::PerInValue | DocumentSumMode::RangeNoProof => { - Err(drive_proof_verifier::Error::RequestError { - error: format!( - "internal: detect_sum_mode_from_inputs returned no-proof mode {resolved_mode:?} \ - for prove=true (AVG path) — the routing table is internally inconsistent. \ - Please report this as a drive bug." - ), - }) - } - } -} - -/// Build the SQL-shape [`SumMode`] from `(group_by, where_clauses)`. -/// Identical resolver to [`super::sum_proof_helpers::resolve_sum_mode`] -/// — AVG and SUM share the same SQL surface (their `AverageMode` / -/// `SumMode` enums have the same shape and the same routing -/// decisions). Duplicated here to keep the SDK helper self-contained -/// (so users can disable the sum surface without breaking AVG). -fn resolve_sum_mode( - group_by: &[String], - where_clauses: &[drive::query::WhereClause], -) -> Result { - let is_in_field = |field: &str| { - where_clauses - .iter() - .any(|wc| wc.operator == WhereOperator::In && wc.field == field) - }; - let is_range_field = |field: &str| { - where_clauses.iter().any(|wc| { - drive::query::drive_document_sum_query::is_range_operator(wc.operator) - && wc.field == field - }) - }; - let unsupported = |feature: String| drive_proof_verifier::Error::RequestError { - error: format!("{feature} (see issue #3655 for the v1 wire surface follow-ups)"), + SumProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => verify_distinct_count_and_sum_proof( + &sum_query(index), + proof, + mtd, + limit, + left_to_right, + platform_version, + provider, + )?, + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => verify_carrier_aggregate_count_and_sum_proof( + &sum_query(index), + proof, + mtd, + limit, + left_to_right, + platform_version, + provider, + )?, }; - match group_by { - [] => Ok(SumMode::Aggregate), - [field] => { - if is_in_field(field) { - Ok(SumMode::GroupByIn) - } else if is_range_field(field) { - Ok(SumMode::GroupByRange) - } else { - Err(drive_proof_verifier::Error::RequestError { - error: format!( - "GROUP BY on field '{field}' which is not constrained by an `In` \ - or range where clause is not yet implemented (see issue #3655)" - ), - }) - } - } - [first, second] => { - if is_in_field(first) && is_range_field(second) { - Ok(SumMode::GroupByCompound) - } else { - Err(unsupported( - "two-field GROUP BY outside the `(In, range)` compound shape \ - is not yet implemented" - .to_string(), - )) - } - } - _ => Err(unsupported( - "GROUP BY with more than two fields is not yet implemented".to_string(), - )), - } + Ok((Some(entries), mtd.clone(), proof.clone())) } /// Wrap a single `(count, sum)` from a per-key-less aggregate diff --git a/packages/dash-platform-queries/src/documents/check_request_tests.rs b/packages/dash-platform-queries/src/documents/check_request_tests.rs index f4cda7aca6e..733ba175415 100644 --- a/packages/dash-platform-queries/src/documents/check_request_tests.rs +++ b/packages/dash-platform-queries/src/documents/check_request_tests.rs @@ -10,12 +10,14 @@ use crate::documents::composite_document_query::CompositeSubQuery; use crate::documents::document_query::{DocumentQuery, RankingDirection}; +use dapi_grpc::platform::v0::get_documents_request::get_documents_request_v0::Start; use dapi_grpc::platform::v0::get_documents_response::{ self, get_documents_response_v0, GetDocumentsResponseV0, }; use dapi_grpc::platform::v0::{GetDocumentsResponse, Proof, ResponseMetadata}; use dash_context_provider::{ContextProvider, ContextProviderError}; use dpp::dashcore::Network; +use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::data_contract::{DataContract, DataContractFactory, TokenConfiguration}; use dpp::document::Document; use dpp::platform_value::{platform_value, Identifier, Value}; @@ -23,7 +25,8 @@ use dpp::prelude::CoreBlockHeight; use dpp::tests::fixtures::get_data_contract_fixture; use dpp::version::PlatformVersion; use drive::query::{ - HavingAggregate, HavingAggregateFunction, HavingClause, HavingOperator, HavingRightOperand, + resolve_integer_range_bucket_clause, resolve_time_range_bucket_clause, HavingAggregate, + HavingAggregateFunction, HavingClause, HavingOperator, HavingRightOperand, OrderClause, SelectFunction, SelectProjection, TimeRangeSelector, WhereClause, WhereOperator, }; use drive_proof_verifier::types::Documents; @@ -42,11 +45,9 @@ fn check>( T::check_request(query, PlatformVersion::latest()) } -/// The count, sum and average views check shapes only, so the fixture's -/// document type serves them; whether an index covers the query is the server's -/// call, and the server refuses a query no index covers. The ranked and -/// having-range views also check that an index serves the query, so their -/// queries use [`ranked_contract`]. +/// A contract whose `niceDocument` has no index: a documents select over it reads the +/// primary-key tree, and a count, sum or average over it is served by nothing, so the views of +/// those use [`ranked_contract`]. fn contract() -> Arc { Arc::new( get_data_contract_fixture(None, 0, PlatformVersion::latest().protocol_version) @@ -59,10 +60,14 @@ fn query() -> DocumentQuery { } /// A `review` whose indexes rank restaurants by their average grade and hashtags by how many -/// reviews carry them, so ranked and having-range queries over it are served. +/// reviews carry them, so ranked and having-range queries over it are served. Its documents are +/// counted and summed by grade, and its restaurant index sums and counts grades, so counts, sums +/// and averages over it, in total or per restaurant, are served too. fn ranked_contract() -> Arc { let schemas = platform_value!({"review": { "type": "object", + "documentsCountable": true, + "documentsSummable": "grade", "properties": { "restaurantId": {"type": "string", "minLength": 1, "maxLength": 59, "position": 0}, "grade": {"type": "integer", "minimum": 0, "maximum": 100, "position": 1}, @@ -149,12 +154,12 @@ fn plain_views() -> Vec<(&'static str, Check, DocumentQuery)> { ( "DocumentCount", check::, - query().with_select(SelectProjection::count_star()), + reviews().with_select(SelectProjection::count_star()), ), ( "DocumentSplitCounts", check::, - query() + reviews() .with_select(SelectProjection::count_star()) .with_where(restaurants_in()) .with_group_by("restaurantId"), @@ -162,12 +167,12 @@ fn plain_views() -> Vec<(&'static str, Check, DocumentQuery)> { ( "DocumentSum", check::, - query().with_select(SelectProjection::sum("grade")), + reviews().with_select(SelectProjection::sum("grade")), ), ( "DocumentSplitSums", check::, - query() + reviews() .with_select(SelectProjection::sum("grade")) .with_where(restaurants_in()) .with_group_by("restaurantId"), @@ -175,12 +180,12 @@ fn plain_views() -> Vec<(&'static str, Check, DocumentQuery)> { ( "DocumentAverage", check::, - query().with_select(SelectProjection::avg("grade")), + reviews().with_select(SelectProjection::avg("grade")), ), ( "DocumentSplitAverages", check::, - query() + reviews() .with_select(SelectProjection::avg("grade")) .with_where(restaurants_in()) .with_group_by("restaurantId"), @@ -241,24 +246,41 @@ fn should_refuse_a_view_of_a_query_that_selects_something_else() { let count = SelectProjection::count_star(); let sum = SelectProjection::sum("grade"); let avg = SelectProjection::avg("grade"); - let views: [(&str, Check, &SelectProjection); 8] = [ - ("Document", check::, &documents), - ("Documents", check::, &documents), - ("DocumentCount", check::, &count), - ("DocumentSplitCounts", check::, &count), - ("DocumentSum", check::, &sum), - ("DocumentSplitSums", check::, &sum), - ("DocumentAverage", check::, &avg), + let documents_words = "require the documents projection"; + let count_words = "require `SelectProjection::count_star()`"; + let sum_words = "require `SelectProjection::sum("; + let avg_words = "require `SelectProjection::avg("; + let views: [(&str, Check, &SelectProjection, &str); 8] = [ + ("Document", check::, &documents, documents_words), + ("Documents", check::, &documents, documents_words), + ("DocumentCount", check::, &count, count_words), + ( + "DocumentSplitCounts", + check::, + &count, + count_words, + ), + ("DocumentSum", check::, &sum, sum_words), + ( + "DocumentSplitSums", + check::, + &sum, + sum_words, + ), + ("DocumentAverage", check::, &avg, avg_words), ( "DocumentSplitAverages", check::, &avg, + avg_words, ), ]; - for (view, check, own) in views { + // Over a type that serves every one of these selects, so the refusal is the view's own. + for (view, check, own, words) in views { for select in [&documents, &count, &sum, &avg] { if select != own { - refusal(view, check, &query().with_select(select.clone())); + let error = refusal(view, check, &reviews().with_select(select.clone())); + assert!(error.contains(words), "{view} {select:?}: {error}"); } } } @@ -667,7 +689,8 @@ fn should_keep_a_window_that_does_not_resolve_at_the_answers_block_time_a_reques ); } -/// A `post` whose `hashtags` is a typed array of strings. +/// A `post` whose `hashtags` is a typed array of strings, with an index that counts posts and +/// sums their `grade` per hashtag. fn post_contract() -> Arc { let schemas = platform_value!({"post": { "type": "object", @@ -677,13 +700,17 @@ fn post_contract() -> Arc { "maxItems": 10, "items": {"type": "string", "minLength": 1, "maxLength": 61}, "position": 0 - } + }, + "grade": {"type": "integer", "minimum": 0, "maximum": 100, "position": 1} }, - "required": ["$createdAt"], + "required": ["grade", "$createdAt"], "indices": [ {"name": "byHashtagTime", "properties": [{"hashtags": "asc"}, {"$createdAt": "asc"}], - "countable": "countable"} + "countable": "countable"}, + {"name": "byHashtag", + "properties": [{"hashtags": "asc"}], + "averageable": "grade"} ], "additionalProperties": false }}); @@ -795,24 +822,26 @@ fn should_leave_a_documents_projection_field_to_the_encoder_and_the_server() { } /// A `listing` whose `price` is bucketed in windows of 100 and whose `$createdAt` is bucketed -/// in daily windows, each under a countable index, so window selections on it resolve. +/// in daily windows, each under an index that counts listings and sums their `quantity`, so +/// window selections on it resolve. Nothing sums `price`. fn windowed_contract() -> Arc { let schemas = platform_value!({"listing": { "type": "object", "properties": { "price": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 0}, - "category": {"type": "string", "minLength": 1, "maxLength": 63, "position": 1} + "category": {"type": "string", "minLength": 1, "maxLength": 63, "position": 1}, + "quantity": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 2} }, - "required": ["price", "category", "$createdAt"], + "required": ["price", "category", "quantity", "$createdAt"], "indices": [ {"name": "byPriceBand", "properties": [{"price": "asc"}, {"category": "asc"}], "integerRange": {"on": "price", "range": 100u64, "step": 100u64}, - "countable": "countable"}, + "averageable": "quantity"}, {"name": "byDay", "properties": [{"$createdAt": "asc"}, {"category": "asc"}], "timeRange": {"on": "$createdAt", "range": 86400, "step": 86400}, - "countable": "countable"} + "averageable": "quantity"} ], "additionalProperties": false }}); @@ -885,7 +914,7 @@ fn should_refuse_a_documents_select_whose_window_every_verifier_refuses_before_s /// An index buckets one field, so no index serves windows on two fields, even when each /// window resolves: every node refuses such a query, and so does every verifier's index pick. -/// It is refused before sending. +/// It is refused before sending, in Drive's own words. #[test] fn should_refuse_windows_on_two_fields_before_sending() { let two_windows = listings() @@ -913,15 +942,428 @@ fn should_refuse_windows_on_two_fields_before_sending() { SelectProjection::avg("price"), ), ]; + // The windows as a check resolves them: time-range selections first, at the block time it + // checks at. + let document_type = windowed_contract(); + let document_type = document_type + .document_type_for_name("listing") + .expect("the contract has this document type"); + let (_, created_at) = resolve_time_range_bucket_clause( + "$createdAt", + TimeRangeSelector::Newest, + None, + document_type, + 1_700_000_000_000, + ) + .expect("a day window resolves"); + let (_, price) = + resolve_integer_range_bucket_clause("price", &Value::U64(200), None, document_type) + .expect("a price window resolves"); + // Drive's words for a query, naming both windows, as the node refuses a documents query. + let drives_words = format!( + "at most one window selection (IN_TIME_RANGE or IN_INTEGER_RANGE) is supported per \ + query; this one resolves {:?}, and no single index can bucket more than one field", + [created_at, price] + ); for (view, check, select) in views { let error = refusal(view, check, &two_windows.clone().with_select(select)); + assert!(error.contains(&drives_words), "{view}: {error}"); + } + for (view, check, query) in [ + ( + "DocumentRankedEntries", + check:: as Check, + windowed_ranked(), + ), + ( + "DocumentHavingEntries", + check::, + windowed_having(), + ), + ] { + let error = refusal( + view, + check, + &query + .with_integer_range("price", Value::U64(200)) + .with_time_range("$createdAt", TimeRangeSelector::Newest), + ); + assert!(error.contains(&drives_words), "{view}: {error}"); + } +} + +/// `SELECT COUNT(*) FROM listing GROUP BY category ORDER BY COUNT(*) DESC LIMIT 5`. +fn windowed_ranked() -> DocumentQuery { + listings() + .with_select(SelectProjection::count_star()) + .with_group_by("category") + .order_by_selected_aggregate(RankingDirection::Descending) + .with_limit(5) +} + +/// `SELECT COUNT(*) FROM listing GROUP BY category HAVING COUNT(*) > 1 LIMIT 5`. +fn windowed_having() -> DocumentQuery { + listings() + .with_select(SelectProjection::count_star()) + .with_group_by("category") + .with_having(vec![HavingClause { + aggregate: HavingAggregate { + function: HavingAggregateFunction::Count, + field: String::new(), + }, + operator: HavingOperator::GreaterThan, + right: HavingRightOperand::Value(Value::U64(1)), + }]) + .with_limit(5) +} + +/// The equality on `$createdAt` a caller writes, as opposed to one a window resolves to. +fn created_at_equal() -> WhereClause { + WhereClause { + field: "$createdAt".to_string(), + operator: WhereOperator::Equal, + value: Value::U64(1_700_000_000_000), + } +} + +/// A documents select is rebuilt by its verifier into Drive's path query, from the request +/// alone, before the proof is read; that path query reads one index. A query no index covers, +/// here a window on `price` beside an equality on `$createdAt`, is refused by every node and by +/// every verifier for every answer, so it is refused before sending. +#[test] +fn should_refuse_a_documents_select_no_index_covers_before_sending() { + let uncovered = listings() + .with_integer_range("price", Value::U64(200)) + .with_where(created_at_equal()); + let views: [(&str, Check); 2] = [ + ("Document", check::), + ("Documents", check::), + ]; + for (view, check) in views { + let error = refusal(view, check, &uncovered); + assert!( + error.contains("no answer to this documents query can be verified"), + "{view}: {error}" + ); + } +} + +/// A window's resolved equality reads as an ordinary equality, and no index may bind a raw +/// value to the bucket keys of the index that buckets the field. The check hands the +/// resolution's provenance to the index pick, as the verifier does, so a windowed query every +/// node serves is sent; a check that dropped it would refuse these. +#[test] +fn should_send_a_documents_select_pinned_to_a_window_its_index_buckets() { + let category_equal = WhereClause { + field: "category".to_string(), + operator: WhereOperator::Equal, + value: Value::Text("tools".to_string()), + }; + let views: [(&str, Check); 2] = [ + ("Document", check::), + ("Documents", check::), + ]; + for (view, check) in views { + for window in [ + listings().with_integer_range("price", Value::U64(200)), + listings() + .with_integer_range("price", Value::U64(200)) + .with_where(category_equal.clone()), + listings().with_time_range("$createdAt", TimeRangeSelector::Newest), + ] { + assert!( + check(&window).is_ok(), + "{view} {window:?}: {:?}", + check(&window) + ); + } + // The same equality written by the caller binds to no index, which is what the + // provenance changes. + let raw_price = listings().with_where(WhereClause { + field: "price".to_string(), + operator: WhereOperator::Equal, + value: Value::U64(200), + }); + let error = refusal(view, check, &raw_price); + assert!( + error.contains("no answer to this documents query can be verified"), + "{view}: {error}" + ); + } +} + +/// The verifier rebuilds a cursor page's path query without the cursor document, too, to read +/// its walk direction, so the check's lowering without a cursor document refuses nothing a +/// cursor page is served for, and refuses a cursor where the verifier does. +#[test] +fn should_send_a_documents_select_with_a_cursor() { + let with_cursor = |query: DocumentQuery| DocumentQuery { + start: Some(Start::StartAfter([1u8; 32].to_vec())), + ..query + }; + let by_restaurant = || { + reviews() + .with_where(restaurants_in()) + .with_order_by(OrderClause { + field: "restaurantId".to_string(), + ascending: true, + }) + .with_limit(10) + }; + type VersionedCheck = fn(&DocumentQuery, &PlatformVersion) -> Result<(), Error>; + let views: [(&str, VersionedCheck); 2] = [ + ( + "Document", + >::check_request, + ), + ( + "Documents", + >::check_request, + ), + ]; + let v13 = PlatformVersion::get(13).expect("protocol version 13"); + for (view, check) in views { + // The primary-key and single-index routes, at the oldest version still on a network and + // at the latest. + for version in [v13, PlatformVersion::latest()] { + for query in [query().with_limit(10), by_restaurant()] { + let query = with_cursor(query); + assert!( + check(&query, version).is_ok(), + "{view} at {}: {:?}", + version.protocol_version, + check(&query, version) + ); + } + } + // A bucketed index, which the latest version serves with a cursor. + let windowed = with_cursor( + listings() + .with_integer_range("price", Value::U64(200)) + .with_limit(10), + ); + assert!( + check(&windowed, PlatformVersion::latest()).is_ok(), + "{view}: {:?}", + check(&windowed, PlatformVersion::latest()) + ); + // Two `In`s on a compound index are served without a cursor; the multiple-`In` route has + // no cursor position, so the lowering, which reads the cursor, refuses one. + assert!( + check(&two_ins(), PlatformVersion::latest()).is_ok(), + "{view}: {:?}", + check(&two_ins(), PlatformVersion::latest()) + ); + let error = match check(&with_cursor(two_ins()), PlatformVersion::latest()) { + Err(Error::RequestError { error }) => error, + other => panic!("{view} must refuse a cursor over two `In`s, got {other:?}"), + }; + assert!( + error.contains("not supported with multiple in clauses"), + "{view}: {error}" + ); + // An indexOnly position has no document id a cursor can address, so the lowering, which + // reads the cursor, refuses it as the verifier does. + let error = match check( + &with_cursor(index_only_entries().with_limit(10)), + PlatformVersion::latest(), + ) { + Err(Error::RequestError { error }) => error, + other => panic!("{view} must refuse an indexOnly cursor, got {other:?}"), + }; assert!( - error.contains("at most one window selection"), + error.contains("cannot address an indexOnly"), "{view}: {error}" ); } } +/// A `shirt` with a compound index on `color` and `size`, queried with an `In` on each, in +/// index order. +fn two_ins() -> DocumentQuery { + let schemas = platform_value!({"shirt": { + "type": "object", + "properties": { + "color": {"type": "string", "minLength": 1, "maxLength": 31, "position": 0}, + "size": {"type": "string", "minLength": 1, "maxLength": 7, "position": 1} + }, + "required": ["color", "size"], + "indices": [ + {"name": "byColorSize", "properties": [{"color": "asc"}, {"size": "asc"}]} + ], + "additionalProperties": false + }}); + let contract = DataContractFactory::new(PlatformVersion::latest().protocol_version) + .expect("factory") + .create_with_value_config(Identifier::new([13u8; 32]), 0, schemas, None, None) + .expect("the shirt contract is well-formed") + .data_contract_owned(); + DocumentQuery::new(Arc::new(contract), "shirt") + .expect("the contract has this document type") + .with_where(WhereClause { + field: "color".to_string(), + operator: WhereOperator::In, + value: platform_value!(["red", "blue"]), + }) + .with_where(WhereClause { + field: "size".to_string(), + operator: WhereOperator::In, + value: platform_value!(["s", "m"]), + }) + .with_order_by(OrderClause { + field: "color".to_string(), + ascending: true, + }) + .with_order_by(OrderClause { + field: "size".to_string(), + ascending: true, + }) + .with_limit(10) +} + +/// An indexOnly `entry`: its documents exist only as positions of its index. +fn index_only_entries() -> DocumentQuery { + let schemas = platform_value!({"entry": { + "type": "object", + "indexOnly": true, + "documentsMutable": false, + "indices": [ + {"name": "byNormalizedName", + "properties": [{"normalizedName": "asc"}, {"name": "asc"}], + "terminal": "$ownerId"} + ], + "properties": { + "name": {"type": "string", "maxLength": 32, "position": 0}, + "normalizedName": {"type": "string", "maxLength": 32, "position": 1} + }, + "required": ["name", "normalizedName"], + "additionalProperties": false + }}); + let contract = DataContractFactory::new(PlatformVersion::latest().protocol_version) + .expect("factory") + .create_with_value_config(Identifier::new([14u8; 32]), 0, schemas, None, None) + .expect("the entry contract is well-formed") + .data_contract_owned(); + DocumentQuery::new(Arc::new(contract), "entry") + .expect("the contract has this document type") + .with_where(WhereClause { + field: "normalizedName".to_string(), + operator: WhereOperator::Equal, + value: Value::Text("alice".to_string()), + }) +} + +/// A count, sum or average proof reads a tree that an index or the document type keeps, picked +/// from the request alone by the node and again by the verifier. A sum or an average of a +/// property no index sums, or a count over a type that counts nothing, is refused by every node +/// and every verifier, so it is refused before sending. +#[test] +fn should_refuse_an_aggregate_no_index_serves_before_sending() { + let categories_in = WhereClause { + field: "category".to_string(), + operator: WhereOperator::In, + value: platform_value!(["tools", "toys"]), + }; + let names_in = WhereClause { + field: "name".to_string(), + operator: WhereOperator::In, + value: platform_value!(["a", "b"]), + }; + let split = |query: DocumentQuery, clause: &WhereClause, field: &str| { + query.with_where(clause.clone()).with_group_by(field) + }; + let cases: Vec<(&str, Check, DocumentQuery, &str)> = vec![ + ( + "DocumentSum", + check::, + listings().with_select(SelectProjection::sum("price")), + "no answer to this sum can be verified", + ), + ( + "DocumentSplitSums", + check::, + split( + listings().with_select(SelectProjection::sum("price")), + &categories_in, + "category", + ), + "no answer to this sum can be verified", + ), + ( + "DocumentAverage", + check::, + listings().with_select(SelectProjection::avg("price")), + "no answer to this average can be verified", + ), + ( + "DocumentSplitAverages", + check::, + split( + listings().with_select(SelectProjection::avg("price")), + &categories_in, + "category", + ), + "no answer to this average can be verified", + ), + ( + "DocumentCount", + check::, + query().with_select(SelectProjection::count_star()), + "no answer to this count can be verified", + ), + ( + "DocumentSplitCounts", + check::, + split( + query().with_select(SelectProjection::count_star()), + &names_in, + "name", + ), + "no answer to this count can be verified", + ), + ]; + for (view, check, query, words) in cases { + let error = refusal(view, check, &query); + assert!(error.contains(words), "{view} {query:?}: {error}"); + assert!( + error.contains("index"), + "{view}: refused for the index it lacks: {error}" + ); + } +} + +/// The verifier rebuilds a distinct walk's limit byte for byte and leaves the cap on it to the +/// node's configuration, which a client cannot know: a limit any node may serve is sent, and +/// one no path query can carry is refused. +#[test] +fn should_send_a_distinct_walk_limit_only_a_path_query_can_carry() { + let distinct = |limit: u32| { + reviews() + .with_select(SelectProjection::count_star()) + .with_where(WhereClause { + field: "hashtag".to_string(), + operator: WhereOperator::GreaterThan, + value: Value::Text("a".to_string()), + }) + .with_group_by("hashtag") + .with_limit(limit) + }; + for limit in [1, 500, u16::MAX as u32] { + let query = distinct(limit); + assert!( + check::(&query).is_ok(), + "limit {limit}: {:?}", + check::(&query) + ); + } + let error = refusal( + "DocumentSplitCounts", + check::, + &distinct(u16::MAX as u32 + 1), + ); + assert!(error.contains("exceeds u16::MAX"), "{error}"); +} + /// A query whose contract lacks its document type is refused by the verifier for every answer, /// in the same words, when it carries a window to resolve. #[test] @@ -997,8 +1439,8 @@ fn should_refuse_a_having_clause_in_an_aggregate_view_before_sending() { ), ]; for (view, check, select) in views { - let ungrouped = query().with_select(select.clone()); - let grouped_by_in = query() + let ungrouped = reviews().with_select(select.clone()); + let grouped_by_in = reviews() .with_select(select) .with_where(restaurants_in()) .with_group_by("restaurantId"); @@ -1011,6 +1453,24 @@ fn should_refuse_a_having_clause_in_an_aggregate_view_before_sending() { let error = refusal(view, check, &aggregate.with_having(having.clone())); assert!(error.contains("DocumentHavingEntries"), "{view}: {error}"); } + // The `having` clause is named even when no index serves the aggregate: it is checked + // before the proof plan, whose refusal would only say that. + let unserved = query() + .with_select(select_of(view)) + .with_having(having.clone()); + let error = refusal(view, check, &unserved); + assert!(error.contains("DocumentHavingEntries"), "{view}: {error}"); + } +} + +/// The select each aggregate view is verified from. +fn select_of(view: &str) -> SelectProjection { + if view.contains("Count") { + SelectProjection::count_star() + } else if view.contains("Sum") { + SelectProjection::sum("grade") + } else { + SelectProjection::avg("grade") } } @@ -1079,12 +1539,12 @@ fn should_refuse_an_in_or_range_beside_a_window_on_the_same_field_before_sending ( "DocumentSum", check::, - SelectProjection::sum("price"), + SelectProjection::sum("quantity"), ), ( "DocumentAverage", check::, - SelectProjection::avg("price"), + SelectProjection::avg("quantity"), ), ]; for (window, field) in windows { @@ -1101,9 +1561,19 @@ fn should_refuse_an_in_or_range_beside_a_window_on_the_same_field_before_sending "{view} {field} {operator:?}: {error}" ); } + // The window with the rest of its index pinned is served by the index. + let served = window + .clone() + .with_where(WhereClause { + field: "category".to_string(), + operator: WhereOperator::Equal, + value: Value::Text("tools".to_string()), + }) + .with_select(select.clone()); assert!( - check(&window.clone().with_select(select.clone())).is_ok(), - "{view} {field}: the window alone is sent" + check(&served).is_ok(), + "{view} {field}: the window is sent: {:?}", + check(&served) ); } } @@ -1442,6 +1912,69 @@ fn should_refuse_before_sending_only_what_the_verifier_refuses_at_any_block_time .with_time_range("$createdAt", TimeRangeSelector::Newest), ), ]; + // An aggregate no index serves is refused before sending, as the verifier's proof plan + // refuses it; its siblings an index serves are sent. Each is pinned both ways here, so a + // check that skipped the plan cannot pass by sending the refused ones. + let aggregates: [(&str, Check, Verifies, DocumentQuery, bool); 5] = [ + ( + "DocumentSum", + check::, + verifier_refuses::, + listings().with_select(SelectProjection::sum("price")), + true, + ), + ( + "DocumentAverage", + check::, + verifier_refuses::, + listings().with_select(SelectProjection::avg("price")), + true, + ), + ( + "DocumentCount", + check::, + verifier_refuses::, + query().with_select(SelectProjection::count_star()), + true, + ), + ( + "DocumentSum", + check::, + verifier_refuses::, + listings() + .with_select(SelectProjection::sum("quantity")) + .with_integer_range("price", Value::U64(200)) + .with_where(WhereClause { + field: "category".to_string(), + operator: WhereOperator::Equal, + value: Value::Text("tools".to_string()), + }), + false, + ), + ( + "DocumentAverage", + check::, + verifier_refuses::, + reviews().with_select(SelectProjection::avg("grade")), + false, + ), + ]; + for (view, check, _, query, refused_before_sending) in &aggregates { + assert_eq!( + check(query).is_err(), + *refused_before_sending, + "{view} {query:?}: {:?}", + check(query) + ); + } + let shapes = shapes + .into_iter() + .chain( + aggregates + .into_iter() + .map(|(view, check, verifies, query, _)| (view, check, verifies, query)), + ) + .collect::>(); let (mut refused, mut accepted_by_both) = (0, 0); for (view, check, verifier_refuses, query) in &shapes { if check(query).is_ok() { @@ -1463,7 +1996,7 @@ fn should_refuse_before_sending_only_what_the_verifier_refuses_at_any_block_time } } assert!( - refused >= 3 && accepted_by_both >= 2, + refused >= 6 && accepted_by_both >= 4, "{refused} refused, {accepted_by_both} accepted by both" ); } diff --git a/packages/dash-platform-queries/src/documents/count_proof_helpers.rs b/packages/dash-platform-queries/src/documents/count_proof_helpers.rs index 1fe58cc7f6a..c38501bd851 100644 --- a/packages/dash-platform-queries/src/documents/count_proof_helpers.rs +++ b/packages/dash-platform-queries/src/documents/count_proof_helpers.rs @@ -14,20 +14,19 @@ //! [`DocumentSplitCounts`]: drive_proof_verifier::DocumentSplitCounts use crate::documents::array_element_clauses::{ - aggregate_request_where_clauses, aggregate_where_clauses, + aggregate_request_where_clauses, aggregate_where_clauses, document_type_named, }; use crate::documents::document_query::normalize_time_range_clauses_with_metadata_time; use crate::documents::document_query::DocumentQuery; use dapi_grpc::platform::v0::{GetDocumentsResponse, Proof, ResponseMetadata}; use dapi_grpc::platform::VersionedGrpcResponse; use dash_context_provider::ContextProvider; +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::DocumentTypeRef; use dpp::version::PlatformVersion; -use dpp::{ - data_contract::accessors::v0::DataContractV0Getters, - data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}, -}; use drive::query::{ - CountMode, DocumentCountMode, DriveDocumentCountQuery, SelectFunction, WhereOperator, + CountMode, CountProofPlan, DriveDocumentCountQuery, OrderClause, ResolvedTimeRange, + SelectFunction, WhereClause, WhereOperator, }; use drive_proof_verifier::{ verify_aggregate_count_proof, verify_carrier_aggregate_count_proof, @@ -79,6 +78,9 @@ pub(super) fn assert_select_is_count( /// /// Pending window selections are resolved first, as the verifier resolves them /// ([`DocumentQuery::resolved_for_checking`]), so the checks read the clauses the verifier reads. +/// The last check is the verifier's proof plan ([`count_proof_plan`]): the primary-key route or +/// the covering index, and the limit, which the node plans its proof by too, so a count no index +/// serves is refused here in the node's words. pub(super) fn check_count_request( request: &DocumentQuery, folds_entries: bool, @@ -86,80 +88,98 @@ pub(super) fn check_count_request( ) -> Result<(), drive_proof_verifier::Error> { request.ensure_no_sub_queries()?; assert_select_is_count(request)?; - let (resolved, _) = request.resolved_for_checking()?; + let (resolved, resolved_time_ranges) = request.resolved_for_checking()?; let request = &resolved; let where_clauses = aggregate_request_where_clauses(request, folds_entries, platform_version)?; - resolve_count_mode(&request.group_by, &where_clauses)?; - request.ensure_no_having() + let count_mode = resolve_count_mode(&request.group_by, &where_clauses)?; + request.ensure_no_having()?; + let document_type = document_type_named(&request.data_contract, &request.document_type_name)?; + count_proof_plan( + &document_type, + &where_clauses, + &resolved_time_ranges, + count_mode, + &request.order_by_clauses, + request.limit, + platform_version, + ) + .map(drop) } -/// Translate the SDK's `u32`-with-`0`-sentinel limit into the -/// `u16` the proof verifier wants to rebuild the prover's path -/// query. +/// The proof plan a node makes for a proved count, made from the request alone +/// ([`DriveDocumentCountQuery::proof_plan`]): Drive resolves the SQL-shape +/// `count_mode` into its proof mode +/// ([`DriveDocumentCountQuery::detect_mode_versioned`]), then picks the +/// primary-key route or the covering index and the limit the path query +/// carries. A client cannot know a node's `max_query_limit`, so it leaves that +/// check to the node. /// -/// `0` falls back to [`drive::config::DEFAULT_QUERY_LIMIT`] — the -/// same compile-time constant the server's prove-distinct -/// dispatcher reads (NOT the operator-tunable -/// `drive_config.default_query_limit`, which the SDK can't see). -/// With both sides anchored to the shared constant the path-query -/// bytes match byte-for-byte across operators, so merk-root -/// recomputation succeeds regardless of any operator's tuning. -/// -/// Non-zero values must fit in `u16` since the wire's -/// `optional uint32` is wider than the verifier's path-query -/// representation. We `try_from` rather than truncate so a caller -/// passing `limit > u16::MAX` fails loudly at the SDK boundary -/// rather than silently producing a mismatched path query. -fn limit_to_u16_or_default(limit: u32) -> Result { - if limit == 0 { - return Ok(drive::config::DEFAULT_QUERY_LIMIT); - } - u16::try_from(limit).map_err(|_| drive_proof_verifier::Error::RequestError { - error: format!( - "limit {} exceeds u16::MAX; the prove-distinct path query cannot represent it", - limit - ), +/// `order_clauses` and `limit` are the request's, `limit` `0` when unset. +pub(super) fn count_proof_plan<'a>( + document_type: &'a DocumentTypeRef<'_>, + where_clauses: &[WhereClause], + resolved_time_ranges: &[ResolvedTimeRange], + count_mode: CountMode, + order_clauses: &[OrderClause], + limit: u32, + platform_version: &PlatformVersion, +) -> Result, drive_proof_verifier::Error> { + let mode = DriveDocumentCountQuery::detect_mode_versioned( + where_clauses, + count_mode, + true, + platform_version, + ) + .map_err(|e| drive_proof_verifier::Error::RequestError { + error: format!("count-mode detection failed: {e}"), + })?; + DriveDocumentCountQuery::proof_plan( + document_type, + where_clauses, + resolved_time_ranges, + mode, + order_clauses, + (limit != 0).then_some(limit), + None, + ) + .map_err(|e| drive_proof_verifier::Error::RequestError { + error: format!("no answer to this count can be verified: {e}"), }) } /// Verify a count-shape proof and return per-branch entries. /// /// Single source of truth for the count-proof dispatch. Picks -/// the verifier primitive by **drive's resolved -/// [`DocumentCountMode`]** rather than a clause-shape heuristic, -/// so the SDK's routing decision matches the server's exactly. -/// Mismatch here was previously possible — e.g. `group_by = -/// [in_field]` with a co-present range clause on the prove path -/// produces a carrier-aggregate proof server-side but the old +/// the verifier primitive by **Drive's [`CountProofPlan`]**, the +/// plan the server proved by, rather than a clause-shape heuristic, +/// so the SDK's routing matches the server's exactly. Mismatch here +/// was previously possible — e.g. `group_by = [in_field]` with a +/// co-present range clause on the prove path produces a +/// carrier-aggregate proof server-side but the old /// `has_range && !group_by.is_empty()` heuristic routed it to /// `verify_distinct_count_proof` (different primitive ⇒ /// verification fails). /// /// **Routing**: build a [`CountMode`] from `(group_by, /// where_clauses)` matching the abci handler's -/// `validate_and_route` logic, then call -/// [`DriveDocumentCountQuery::detect_mode`] with `prove = true` -/// to get the resolved [`DocumentCountMode`]. Branch by the -/// resolved mode: +/// `validate_and_route` logic, then take Drive's plan +/// ([`count_proof_plan`]). Branch by the plan: /// -/// - [`DocumentCountMode::PointLookupProof`] (no range, with or -/// without `In`) → `verify_point_lookup_count_proof`. -/// Special-case: `documents_countable: true` doctype + empty -/// where → `verify_primary_key_count_tree_proof`. -/// - [`DocumentCountMode::RangeProof`] (range, no In, no -/// distinct) → `verify_aggregate_count_proof` → single -/// empty-key entry. -/// - [`DocumentCountMode::RangeDistinctProof`] (range + distinct -/// walk via `GroupByRange` / `GroupByCompound`) → +/// - [`CountProofPlan::PrimaryKeyCountTree`] (empty where on a +/// `documents_countable: true` doctype) → +/// `verify_primary_key_count_tree_proof`. +/// - [`CountProofPlan::PointLookup`] (no range, with or without +/// `In`) → `verify_point_lookup_count_proof`. +/// - [`CountProofPlan::Range`] (range, no In, no distinct) → +/// `verify_aggregate_count_proof` → single empty-key entry. +/// - [`CountProofPlan::RangeDistinct`] (range + distinct walk via +/// `GroupByRange` / `GroupByCompound`) → /// `verify_distinct_count_proof`. -/// - [`DocumentCountMode::RangeAggregateCarrierProof`] (`In + -/// range + group_by=[in_field]` on the prove path; grovedb #663 -/// carrier primitive) → `verify_carrier_aggregate_count_proof`. -/// - `Total` / `PerInValue` / `RangeNoProof` are no-proof modes -/// and would be unreachable here (`prove=true`); reject as -/// `Internal` if they ever bubble through. +/// - [`CountProofPlan::RangeAggregateCarrier`] (`In + range + +/// group_by=[in_field]` on the prove path; grovedb #663 carrier +/// primitive) → `verify_carrier_aggregate_count_proof`. /// -/// Wrapping aggregate primitives (`RangeProof`, primary-key +/// Wrapping aggregate primitives (`Range`, primary-key /// CountTree) as single empty-key entries is the only shape /// massage this helper does — the underlying primitives /// genuinely emit `u64`s, and consumers ([`DocumentCount`] sums, @@ -225,170 +245,83 @@ pub(super) fn verify_count_query( // unrelated `select` projection check. let count_mode = resolve_count_mode(&request.group_by, &request.where_clauses)?; - // Translate the SQL-shape mode + where-clause shape into the - // resolved `DocumentCountMode` the prover would dispatch on. - // Driver-side detect_mode is the single source of truth — the - // SDK calling it directly is what keeps the verifier in sync - // with whatever new prove-mode lands next. - let resolved_mode = DriveDocumentCountQuery::detect_mode_versioned( + // Drive's plan, the one the prover made from the same request: the + // proof mode, the primary-key route or covering index, and the limit + // the path query carries. A plan the verifier made apart from the + // prover's would build a different path query. + let plan = count_proof_plan( + &document_type, &request.where_clauses, + &resolved_time_ranges, count_mode, - true, + &request.order_by_clauses, + request.limit, platform_version, - ) - .map_err(|e| drive_proof_verifier::Error::RequestError { - error: format!("count-mode detection failed: {e}"), - })?; - - // Special-case: empty where-clauses on a `documents_countable` - // doctype proves the primary-key CountTree element directly, - // skipping the per-index covering walk. This lives outside - // `detect_mode`'s output because the contract-level - // `documents_countable` flag isn't part of mode detection; - // pre-empt it here before falling through to PointLookupProof. - if matches!(resolved_mode, DocumentCountMode::PointLookupProof) - && request.where_clauses.is_empty() - && document_type.documents_countable() - { - let contract_id = request.data_contract.id().to_buffer(); - let count = verify_primary_key_count_tree_proof( - contract_id, - &request.document_type_name, - proof, - mtd, - platform_version, - provider, - )?; - return Ok(( - Some(single_empty_key_entry(count)), - mtd.clone(), - proof.clone(), - )); - } - - // Pick the index the prover would have picked. Range modes - // need a `range_countable: true` index; everything else uses - // the regular `countable: true` resolver. Mismatch here would - // produce a path-query different from the prover's, so the - // index lookup matches drive's `range_count_path_query` / - // `point_lookup_count_path_query` dispatch. - let needs_range_index = matches!( - resolved_mode, - DocumentCountMode::RangeProof - | DocumentCountMode::RangeDistinctProof - | DocumentCountMode::RangeAggregateCarrierProof - ); - let index = if needs_range_index { - DriveDocumentCountQuery::find_range_countable_index_for_where_clauses( - document_type.indexes(), - &request.where_clauses, - &resolved_time_ranges, - ) - .ok_or_else(|| drive_proof_verifier::Error::RequestError { - error: "range count requires a `range_countable: true` (or summableOffCountIndex) index whose last \ - property matches the range field" - .to_string(), - })? - } else { - DriveDocumentCountQuery::find_countable_index_for_where_clauses( - document_type.indexes(), - &request.where_clauses, - &resolved_time_ranges, - ) - .ok_or_else(|| drive_proof_verifier::Error::RequestError { - error: "prove count requires a `countable: true` (or summableOffCountIndex) index whose properties \ - exactly match the where clause fields, or `documentsCountable: \ - true` on the document type for unfiltered total counts" - .to_string(), - })? - }; - let count_query = DriveDocumentCountQuery { + )?; + let contract_id = request.data_contract.id().to_buffer(); + let count_query = |index| DriveDocumentCountQuery { document_type, - contract_id: request.data_contract.id().to_buffer(), + contract_id, document_type_name: request.document_type_name.clone(), index, where_clauses: request.where_clauses.clone(), }; - match resolved_mode { - DocumentCountMode::PointLookupProof => { - let entries = verify_point_lookup_count_proof( - &count_query, - proof, - mtd, - platform_version, - provider, - )?; - Ok((Some(entries), mtd.clone(), proof.clone())) - } - DocumentCountMode::RangeProof => { - let count = - verify_aggregate_count_proof(&count_query, proof, mtd, platform_version, provider)?; - Ok(( - Some(single_empty_key_entry(count)), - mtd.clone(), - proof.clone(), - )) - } - DocumentCountMode::RangeDistinctProof => { - let limit_u16 = limit_to_u16_or_default(request.limit)?; - let left_to_right = request - .order_by_clauses - .first() - .map(|c| c.ascending) - .unwrap_or(true); - let entries = verify_distinct_count_proof( - &count_query, - proof, - mtd, - limit_u16, - left_to_right, - platform_version, - provider, - )?; - Ok((Some(entries), mtd.clone(), proof.clone())) - } - DocumentCountMode::RangeAggregateCarrierProof => { - // Carrier-ACOR (grovedb #663) — one verified `u64` per - // present In branch. The limit comes from the same - // function the server's dispatcher uses (`0` is the - // unset sentinel), so a range-outer request without a - // limit walks the platform default on both sides and the - // path-query bytes match the server's exactly. - let limit_u16 = DriveDocumentCountQuery::carrier_aggregate_count_limit( - &request.where_clauses, - (request.limit != 0).then_some(request.limit), - )?; - let left_to_right = request - .order_by_clauses - .first() - .map(|c| c.ascending) - .unwrap_or(true); - let entries = verify_carrier_aggregate_count_proof( - &count_query, + let entries = match plan { + CountProofPlan::PrimaryKeyCountTree => { + single_empty_key_entry(verify_primary_key_count_tree_proof( + contract_id, + &request.document_type_name, proof, mtd, - limit_u16, - left_to_right, platform_version, provider, - )?; - Ok((Some(entries), mtd.clone(), proof.clone())) + )?) } - // The three no-proof modes are unreachable under `prove = - // true`. `detect_mode` would only return them when called - // with `prove = false`. If we ever see one here it means - // drive's detect_mode contract changed unexpectedly; - // surface a clear internal error rather than crash. - DocumentCountMode::Total - | DocumentCountMode::PerInValue - | DocumentCountMode::RangeNoProof => Err(drive_proof_verifier::Error::RequestError { - error: format!( - "unexpected no-proof DocumentCountMode {resolved_mode:?} returned for a \ - prove=true request — drive's detect_mode contract may have changed" - ), - }), - } + CountProofPlan::PointLookup(index) => verify_point_lookup_count_proof( + &count_query(index), + proof, + mtd, + platform_version, + provider, + )?, + CountProofPlan::Range(index) => single_empty_key_entry(verify_aggregate_count_proof( + &count_query(index), + proof, + mtd, + platform_version, + provider, + )?), + CountProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => verify_distinct_count_proof( + &count_query(index), + proof, + mtd, + limit, + left_to_right, + platform_version, + provider, + )?, + // Carrier-ACOR (grovedb #663) — one verified `u64` per present In + // branch. + CountProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => verify_carrier_aggregate_count_proof( + &count_query(index), + proof, + mtd, + limit, + left_to_right, + platform_version, + provider, + )?, + }; + Ok((Some(entries), mtd.clone(), proof.clone())) } /// Build the SQL-shape [`CountMode`] from `(group_by, @@ -493,6 +426,7 @@ mod tests { get_documents_response_v1, GetDocumentsResponseV1, Version as ResponseVersion, }; use dash_context_provider::ContextProviderError; + use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; use dpp::data_contract::{DataContractFactory, TokenConfiguration}; use dpp::platform_value::platform_value; use dpp::prelude::{CoreBlockHeight, DataContract, Identifier}; diff --git a/packages/dash-platform-queries/src/documents/document_query.rs b/packages/dash-platform-queries/src/documents/document_query.rs index 53da152b92e..4bd5f65e2e0 100644 --- a/packages/dash-platform-queries/src/documents/document_query.rs +++ b/packages/dash-platform-queries/src/documents/document_query.rs @@ -40,11 +40,12 @@ use drive::config::DEFAULT_QUERY_LIMIT; use drive::error::Error as DriveError; use drive::query::drive_document_ranked_query::mode_detection::ranked_order_key; use drive::query::{ - resolve_integer_range_bucket_clause, resolve_time_range_bucket_clause, - validate_resolved_time_range_clause_shapes, DriveDocumentQuery, HavingAggregate, - HavingAggregateFunction, HavingClause, HavingOperator, HavingRightOperand, - IntegerRangeGridSpec, InternalClauses, OrderClause, ResolvedTimeRange, SelectFunction, - SelectProjection, TimeRangeGridSpec, TimeRangeSelector, WhereClause, WhereOperator, + refuse_several_window_selections, resolve_integer_range_bucket_clause, + resolve_time_range_bucket_clause, validate_resolved_time_range_clause_shapes, + DriveDocumentQuery, HavingAggregate, HavingAggregateFunction, HavingClause, HavingOperator, + HavingRightOperand, IntegerRangeGridSpec, InternalClauses, OrderClause, ResolvedTimeRange, + SelectFunction, SelectProjection, TimeRangeGridSpec, TimeRangeSelector, WhereClause, + WhereOperator, }; use drive_proof_verifier::{types::Documents, FromProof}; @@ -655,10 +656,13 @@ impl FromProof for drive_proof_verifier::types::Documents { /// refuses it. A projection field on the documents select is left alone: the server /// refuses it on the V1 wire, and the V0 encoder drops it, so the documents served verify. /// The window selections are resolved as the verifier resolves them, which refuses one that - /// does not resolve, or an `In` or range clause beside it on the field it buckets. + /// does not resolve, or an `In` or range clause beside it on the field it buckets. The + /// resolved query is then handed to the verifier's own check, which builds Drive's path query + /// from it as the verifier does before reading the proof, so a query no index serves is + /// refused too. fn check_request( request: &Self::Request, - _platform_version: &PlatformVersion, + platform_version: &PlatformVersion, ) -> Result<(), drive_proof_verifier::Error> { request.ensure_no_sub_queries()?; if request.select.function != SelectFunction::Documents { @@ -689,10 +693,12 @@ impl FromProof for drive_proof_verifier::types::Documents { }); } // The verifier rebuilds the resolved query as Drive's before it reads the proof. - let (resolved, _) = request.resolved_for_checking()?; - DriveDocumentQuery::try_from(&resolved) - .map(drop) - .map_err(unconvertible_documents_query) + let (resolved, resolved_time_ranges) = request.resolved_for_checking()?; + let drive_query = drive_query_with_provenance(&resolved, resolved_time_ranges)?; + >::check_request( + &drive_query, + platform_version, + ) } fn maybe_from_proof_with_metadata<'a, I: Into, O: Into>( @@ -733,13 +739,7 @@ impl FromProof for drive_proof_verifier::types::Documents { normalize_time_range_clauses_with_metadata_time(&mut request, time_ms)?; } - let mut drive_query: DriveDocumentQuery = (&request) - .try_into() - .map_err(unconvertible_documents_query)?; - // The conversion cannot recover which equalities came from resolution, - // so the provenance is carried across here; index selection reads it - // to pin the query to the index that buckets the field. - drive_query.resolved_time_ranges = resolved_time_ranges; + let drive_query = drive_query_with_provenance(&request, resolved_time_ranges)?; >::maybe_from_proof_with_metadata( drive_query, @@ -751,6 +751,21 @@ impl FromProof for drive_proof_verifier::types::Documents { } } +/// Drive's query for `resolved`, a documents select whose window selections are already +/// resolved, carrying the resolution provenance `resolved_time_ranges`. The conversion cannot +/// recover which equalities came from resolution, so the provenance is carried across here; +/// index selection reads it to pin the query to the index that buckets the field. The check +/// before sending and the verifier both build their query here, so neither can drop it. +fn drive_query_with_provenance( + resolved: &DocumentQuery, + resolved_time_ranges: Vec, +) -> Result, drive_proof_verifier::Error> { + let mut drive_query = + DriveDocumentQuery::try_from(resolved).map_err(unconvertible_documents_query)?; + drive_query.resolved_time_ranges = resolved_time_ranges; + Ok(drive_query) +} + /// Resolve a request's pending time-range (`IN_TIME_RANGE`) selections into /// concrete bucket-equality clauses on `request.where_clauses`, using the /// **quorum-signed** response metadata block time — the same authoritative @@ -866,16 +881,13 @@ impl DocumentQuery { .map_err(|e| drive_proof_verifier::Error::RequestError { error: format!("invalid window selection query shape: {}", e), })?; - if resolved_time_ranges.len() > 1 { - return Err(drive_proof_verifier::Error::RequestError { - error: format!( - "at most one window selection (IN_TIME_RANGE or IN_INTEGER_RANGE) is \ - supported per query; this one resolves {}, and no single index can \ - bucket more than one field", - resolved_time_ranges.len() - ), - }); - } + // Drive's rule, in Drive's words: the only clear refusal of two windows the aggregate, + // ranked and having checks get, which would otherwise only find no index to serve them. + refuse_several_window_selections(&resolved_time_ranges, "query").map_err(|e| { + drive_proof_verifier::Error::RequestError { + error: e.to_string(), + } + })?; Ok((query, resolved_time_ranges)) } } diff --git a/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs b/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs index 5ea776a0825..923759108ac 100644 --- a/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs +++ b/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs @@ -7,9 +7,10 @@ //! the entries into a single `i64`, [`DocumentSplitSums`] passes //! them through. //! -//! Routing is driven by drive's resolved [`DocumentSumMode`] (via -//! [`detect_sum_mode_from_inputs`]) rather than ad-hoc clause-shape -//! heuristics — same approach as count. Without that, `group_by = +//! Routing is driven by drive's [`SumProofPlan`] (via +//! [`DriveDocumentSumQuery::proof_plan`], the plan the server proves +//! by) rather than ad-hoc clause-shape heuristics — same approach as +//! count. Without that, `group_by = //! [in_field]` with a co-present range clause could be silently //! answered with an aggregate-shape proof while the server emitted //! a carrier-shape proof, producing verification failures (or worse, @@ -27,19 +28,15 @@ use crate::documents::document_query::DocumentQuery; use dapi_grpc::platform::v0::{GetDocumentsResponse, Proof, ResponseMetadata}; use dapi_grpc::platform::VersionedGrpcResponse; use dash_context_provider::ContextProvider; +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::accessors::DocumentTypeV2Getters; +use dpp::data_contract::document_type::DocumentTypeRef; use dpp::version::PlatformVersion; -use dpp::{ - data_contract::accessors::v0::DataContractV0Getters, - data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}, -}; -use drive::query::drive_document_sum_query::index_picker::{ - find_range_summable_index_for_where_clauses, find_summable_index_for_where_clauses, -}; use drive::query::drive_document_sum_query::mode_detection::{ check_sum_property_against_document_type, detect_sum_mode_from_inputs, }; -use drive::query::drive_document_sum_query::{DocumentSumMode, DriveDocumentSumQuery, SumMode}; -use drive::query::{SelectFunction, WhereOperator}; +use drive::query::drive_document_sum_query::{DriveDocumentSumQuery, SumMode, SumProofPlan}; +use drive::query::{OrderClause, ResolvedTimeRange, SelectFunction, WhereClause, WhereOperator}; use drive_proof_verifier::{ verify_aggregate_sum_proof, verify_carrier_aggregate_sum_proof, verify_distinct_sum_proof, verify_point_lookup_sum_proof, verify_primary_key_sum_tree_proof, SumEntry, @@ -74,6 +71,9 @@ pub(super) fn assert_select_is_sum( /// It also refuses a sum of another property than the one the document type /// sums its documents by. Every node refuses that request with an internal /// error, which the SDK would retry on every other node and ban each one for. +/// The last check is the verifier's proof plan ([`sum_proof_plan`]), which the +/// node plans its proof by too, so a sum no index serves is refused here in the +/// node's words. pub(super) fn check_sum_request( request: &DocumentQuery, folds_entries: bool, @@ -94,41 +94,87 @@ pub(super) fn check_sum_request( ), }, )?; - let (resolved, _) = request.resolved_for_checking()?; + let (resolved, resolved_time_ranges) = request.resolved_for_checking()?; let request = &resolved; let where_clauses = aggregate_request_where_clauses(request, folds_entries, platform_version)?; - resolve_sum_mode(&request.group_by, &where_clauses)?; - request.ensure_no_having() + let sum_mode = resolve_sum_mode(&request.group_by, &where_clauses)?; + request.ensure_no_having()?; + sum_proof_plan( + &document_type, + &where_clauses, + &resolved_time_ranges, + &request.select.field, + sum_mode, + &request.order_by_clauses, + request.limit, + platform_version, + ) + .map(drop) +} + +/// The proof plan a node makes for a proved sum of `sum_property`, made from +/// the request alone ([`DriveDocumentSumQuery::proof_plan`]): Drive resolves the +/// SQL-shape `sum_mode` into its proof mode ([`detect_sum_mode_from_inputs`]), +/// then picks the primary-key route or the covering index and the limit the +/// path query carries. A client cannot know a node's `max_query_limit`, so it +/// leaves that check to the node. +/// +/// `order_clauses` and `limit` are the request's, `limit` `0` when unset. +#[allow(clippy::too_many_arguments)] +fn sum_proof_plan<'a>( + document_type: &'a DocumentTypeRef<'_>, + where_clauses: &[WhereClause], + resolved_time_ranges: &[ResolvedTimeRange], + sum_property: &str, + sum_mode: SumMode, + order_clauses: &[OrderClause], + limit: u32, + platform_version: &PlatformVersion, +) -> Result, drive_proof_verifier::Error> { + let mode = detect_sum_mode_from_inputs(where_clauses, sum_mode, true, platform_version) + .map_err(|e| drive_proof_verifier::Error::RequestError { + error: format!("sum-mode detection failed: {e}"), + })?; + DriveDocumentSumQuery::proof_plan( + document_type, + where_clauses, + resolved_time_ranges, + sum_property, + mode, + order_clauses, + (limit != 0).then_some(limit), + None, + ) + .map_err(|e| drive_proof_verifier::Error::RequestError { + error: format!("no answer to this sum can be verified: {e}"), + }) } /// Verify a SUM-shape proof and return per-branch `SumEntry`s. /// -/// Picks the verifier primitive by **drive's resolved -/// [`DocumentSumMode`]** rather than a clause-shape heuristic, so -/// the SDK's routing matches the server's exactly. Mirrors count's +/// Picks the verifier primitive by **Drive's [`SumProofPlan`]**, the +/// plan the server proved by, rather than a clause-shape heuristic, +/// so the SDK's routing matches the server's exactly. Mirrors count's /// [`super::count_proof_helpers::verify_count_query`] approach. /// /// **Routing**: build a [`SumMode`] from `(group_by, /// where_clauses)` matching the abci handler's `validate_and_route` -/// logic, then call [`detect_sum_mode_from_inputs`] with -/// `prove = true` to get the resolved [`DocumentSumMode`]. Branch -/// by the resolved mode: +/// logic, then take Drive's plan ([`sum_proof_plan`]). Branch by the +/// plan: /// -/// - [`DocumentSumMode::PointLookupProof`] (no range, with or -/// without `In`) → [`verify_point_lookup_sum_proof`]. -/// Special-case: doctype-level `documentsSummable` + empty where -/// → [`verify_primary_key_sum_tree_proof`]. -/// - [`DocumentSumMode::RangeProof`] (range, no In, no distinct) → +/// - [`SumProofPlan::PrimaryKeySumTree`] (empty where on a doctype +/// whose `documentsSummable` is the summed property) → +/// [`verify_primary_key_sum_tree_proof`]. +/// - [`SumProofPlan::PointLookup`] (no range, with or without `In`) +/// → [`verify_point_lookup_sum_proof`]. +/// - [`SumProofPlan::Range`] (range, no In, no distinct) → /// [`verify_aggregate_sum_proof`] → single empty-key entry. -/// - [`DocumentSumMode::RangeDistinctProof`] (range + distinct walk -/// via `GroupByRange` / `GroupByCompound`) → +/// - [`SumProofPlan::RangeDistinct`] (range + distinct walk via +/// `GroupByRange` / `GroupByCompound`) → /// [`verify_distinct_sum_proof`]. -/// - [`DocumentSumMode::RangeAggregateCarrierProof`] (`In + range + +/// - [`SumProofPlan::RangeAggregateCarrier`] (`In + range + /// group_by = [in_field]` on the prove path) → /// [`verify_carrier_aggregate_sum_proof`]. -/// - `Total` / `PerInValue` / `RangeNoProof` are no-proof modes -/// that should be unreachable here (`prove = true`); reject as -/// `RequestError` if they bubble through. /// /// `folds_entries` is whether the caller adds the verified entries up into one /// total ([`aggregate_where_clauses`]). @@ -186,196 +232,83 @@ pub(super) fn verify_sum_query( // depend on rs-drive-abci. let sum_mode = resolve_sum_mode(&request.group_by, &request.where_clauses)?; - // Translate the SQL-shape mode + where-clause shape into the - // resolved `DocumentSumMode` the prover dispatched on. Driver- - // side detect_sum_mode_from_inputs is the single source of - // truth — the SDK calling it directly keeps the verifier in - // sync with whatever new prove-mode lands next. - let resolved_mode = - detect_sum_mode_from_inputs(&request.where_clauses, sum_mode, true, platform_version) - .map_err(|e| drive_proof_verifier::Error::RequestError { - error: format!("sum-mode detection failed: {e}"), - })?; - - // Empty-where SUM fast path: primary-key SumTree element direct - // read. Lives outside `detect_sum_mode`'s output because the - // contract-level `documents_summable` flag isn't part of mode - // detection; pre-empt before falling through to PointLookupProof. - if matches!(resolved_mode, DocumentSumMode::PointLookupProof) - && request.where_clauses.is_empty() - && document_type - .documents_summable() - .map(|p| p == sum_property) - .unwrap_or(false) - { - let sum = verify_primary_key_sum_tree_proof( - contract_id, - &request.document_type_name, - proof, - mtd, - platform_version, - provider, - )?; - return Ok(( - Some(single_empty_key_entry(sum)), - mtd.clone(), - proof.clone(), - )); - } - - // Pick the index the prover would have picked. Range modes - // need a `range_summable: true` index; everything else uses - // the regular `summable: ""` resolver. Mismatch here - // would produce a path-query different from the prover's, so - // the index lookup matches drive's dispatch. - let needs_range_index = matches!( - resolved_mode, - DocumentSumMode::RangeProof - | DocumentSumMode::RangeDistinctProof - | DocumentSumMode::RangeAggregateCarrierProof - ); - let index = if needs_range_index { - find_range_summable_index_for_where_clauses( - document_type.indexes(), - &request.where_clauses, - &sum_property, - &resolved_time_ranges, - ) - .ok_or_else(|| drive_proof_verifier::Error::RequestError { - error: "prove range SUM requires a `rangeSummable: true` index whose last \ - property matches the range field and whose summable property \ - matches the request's select `field`" - .to_string(), - })? - } else { - find_summable_index_for_where_clauses( - document_type.indexes(), - &request.where_clauses, - &sum_property, - &resolved_time_ranges, - ) - .ok_or_else(|| drive_proof_verifier::Error::RequestError { - error: "prove SUM requires a `summable: \"\"` index whose properties \ - exactly match the where clause fields and whose summed property \ - matches the request's select `field`, or `documentsSummable: \ - \"\"` on the document type for unfiltered total sums" - .to_string(), - })? - }; - let sum_query = DriveDocumentSumQuery { + // Drive's plan, the one the prover made from the same request: the + // proof mode, the primary-key route or covering index, and the limit + // the path query carries. On the prove path the server refuses an + // over-max limit with a typed `InvalidLimit` before producing proof + // bytes, so the SDK never sees a clamped value to un-clamp. + let plan = sum_proof_plan( + &document_type, + &request.where_clauses, + &resolved_time_ranges, + &sum_property, + sum_mode, + &request.order_by_clauses, + request.limit, + platform_version, + )?; + let sum_query = |index| DriveDocumentSumQuery { document_type, contract_id, document_type_name: request.document_type_name.clone(), index, where_clauses: request.where_clauses.clone(), - sum_property, + sum_property: sum_property.clone(), }; - match resolved_mode { - DocumentSumMode::PointLookupProof => { - let entries = - verify_point_lookup_sum_proof(&sum_query, proof, mtd, platform_version, provider)?; - Ok((Some(entries), mtd.clone(), proof.clone())) - } - DocumentSumMode::RangeProof => { - let sum = - verify_aggregate_sum_proof(&sum_query, proof, mtd, platform_version, provider)?; - Ok(( - Some(single_empty_key_entry(sum)), - mtd.clone(), - proof.clone(), - )) - } - DocumentSumMode::RangeDistinctProof => { - // Limit handling on the prove path: - // - Fallback uses [`drive::config::DEFAULT_QUERY_LIMIT`] - // (compile-time constant), matching the server's - // `DocumentSumMode::RangeDistinctProof` arm in - // `drive_document_sum_query/drive_dispatcher.rs`. - // Both sides MUST anchor to the same compile-time - // value — operator-tunable - // `drive_config.default_query_limit` is intentionally - // NOT used here so a tuned operator default can't - // byte-differ the reconstructed `SizedQuery::limit` - // from the prover's. - // - Raw caller limit propagates unchanged on the prove - // path — the server rejects over-max - // (`max_query_limit`) requests with a typed - // `InvalidLimit` error before producing proof bytes, - // so the SDK never sees a clamped value to - // un-clamp. - let limit_u16 = if request.limit == 0 { - drive::config::DEFAULT_QUERY_LIMIT - } else { - u16::try_from(request.limit).map_err(|_| { - drive_proof_verifier::Error::RequestError { - error: format!( - "limit {} exceeds u16::MAX for distinct SUM proof", - request.limit - ), - } - })? - }; - let left_to_right = request - .order_by_clauses - .first() - .map(|c| c.ascending) - .unwrap_or(true); - let entries = verify_distinct_sum_proof( - &sum_query, + let entries = match plan { + SumProofPlan::PrimaryKeySumTree => { + single_empty_key_entry(verify_primary_key_sum_tree_proof( + contract_id, + &request.document_type_name, proof, mtd, - limit_u16, - left_to_right, platform_version, provider, - )?; - Ok((Some(entries), mtd.clone(), proof.clone())) + )?) } - DocumentSumMode::RangeAggregateCarrierProof => { - let limit_u16 = if request.limit == 0 { - None - } else { - Some(u16::try_from(request.limit).map_err(|_| { - drive_proof_verifier::Error::RequestError { - error: format!( - "limit {} exceeds u16::MAX for carrier-aggregate SUM proof", - request.limit - ), - } - })?) - }; - let left_to_right = request - .order_by_clauses - .first() - .map(|c| c.ascending) - .unwrap_or(true); - let entries = verify_carrier_aggregate_sum_proof( - &sum_query, - proof, - mtd, - limit_u16, - left_to_right, - platform_version, - provider, - )?; - Ok((Some(entries), mtd.clone(), proof.clone())) - } - // `Total` / `PerInValue` / `RangeNoProof` are no-proof modes - // that detect_sum_mode_from_inputs returns only for - // `prove = false`. We pass `prove = true`, so reaching here - // would indicate a drive routing-table bug rather than a - // user error — surface it clearly. - DocumentSumMode::Total | DocumentSumMode::PerInValue | DocumentSumMode::RangeNoProof => { - Err(drive_proof_verifier::Error::RequestError { - error: format!( - "internal: detect_sum_mode_from_inputs returned no-proof mode {resolved_mode:?} \ - for prove=true — the routing table is internally inconsistent. \ - Please report this as a drive bug." - ), - }) - } - } + SumProofPlan::PointLookup(index) => verify_point_lookup_sum_proof( + &sum_query(index), + proof, + mtd, + platform_version, + provider, + )?, + SumProofPlan::Range(index) => single_empty_key_entry(verify_aggregate_sum_proof( + &sum_query(index), + proof, + mtd, + platform_version, + provider, + )?), + SumProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => verify_distinct_sum_proof( + &sum_query(index), + proof, + mtd, + limit, + left_to_right, + platform_version, + provider, + )?, + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => verify_carrier_aggregate_sum_proof( + &sum_query(index), + proof, + mtd, + limit, + left_to_right, + platform_version, + provider, + )?, + }; + Ok((Some(entries), mtd.clone(), proof.clone())) } /// Build the SQL-shape [`SumMode`] from `(group_by, where_clauses)`. @@ -383,8 +316,10 @@ pub(super) fn verify_sum_query( /// same SQL surface, same routing decision shape (`SumMode` is /// structurally identical to `CountMode`). Keeping the two /// resolvers in lock-step means a future SQL extension only has -/// to land once in count + once in sum. -fn resolve_sum_mode( +/// to land once in count + once in sum. The average helpers resolve +/// their mode with it too, since an average routes over the same SQL +/// surface. +pub(super) fn resolve_sum_mode( group_by: &[String], where_clauses: &[drive::query::WhereClause], ) -> Result { diff --git a/packages/rs-drive-abci/tests/query_request_errors.rs b/packages/rs-drive-abci/tests/query_request_errors.rs index 6b5b1766aae..42f1a3f0feb 100644 --- a/packages/rs-drive-abci/tests/query_request_errors.rs +++ b/packages/rs-drive-abci/tests/query_request_errors.rs @@ -86,6 +86,8 @@ mod composite_caps; mod document_features; #[path = "query_request_errors/features_not_active.rs"] mod features_not_active; +#[path = "query_request_errors/index_coverage.rs"] +mod index_coverage; #[path = "query_request_errors/offset_controls.rs"] mod offset_controls; #[path = "query_request_errors/offsets.rs"] diff --git a/packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs b/packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs new file mode 100644 index 00000000000..aaa5c0963eb --- /dev/null +++ b/packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs @@ -0,0 +1,296 @@ +//! Document requests no index serves. A node answers one with a query error, so the SDK +//! refuses it before sending, by running the request-only half of the request's own verifier: +//! the documents path query, or the count, sum or average proof plan, which the node builds +//! its answer from too. The node and the check must agree on every shape below: a request the +//! check refuses is one no node answers, and one the check sends is one the node serves. + +use super::*; +use dash_platform_queries::documents::document_query::DocumentQuery; +use dpp::data_contract::DataContractFactory; +use dpp::platform_value::{platform_value, Value}; +use dpp::version::TryFromPlatformVersioned; +use drive::query::{SelectProjection, TimeRangeSelector, WhereClause, WhereOperator}; +use drive_proof_verifier::types::Documents; +use drive_proof_verifier::{ + DocumentAverage, DocumentCount, DocumentSplitAverages, DocumentSplitCounts, DocumentSplitSums, + DocumentSum, FromProof, +}; + +type Check = fn(&DocumentQuery, &PlatformVersion) -> Result<(), drive_proof_verifier::Error>; + +// The SDK's error type is large; the check returns it as the view's check does. +#[allow(clippy::result_large_err)] +fn check>( + query: &DocumentQuery, + version: &PlatformVersion, +) -> Result<(), drive_proof_verifier::Error> { + T::check_request(query, version) +} + +fn contract(id: u8, schemas: Value, version: &PlatformVersion) -> Arc { + Arc::new( + DataContractFactory::new(version.protocol_version) + .expect("factory") + .create_with_value_config(Identifier::new([id; 32]), 0, schemas, None, None) + .expect("the contract is well-formed") + .data_contract_owned(), + ) +} + +/// A `listing` whose `price` is bucketed in windows of 100 and whose `$createdAt` in daily +/// windows, each under an index that counts listings and sums their `quantity`; nothing sums +/// `price`. +fn listings(version: &PlatformVersion) -> Arc { + contract( + 31, + platform_value!({"listing": { + "type": "object", + "properties": { + "price": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 0}, + "category": {"type": "string", "minLength": 1, "maxLength": 63, "position": 1}, + "quantity": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 2} + }, + "required": ["price", "category", "quantity", "$createdAt"], + "indices": [ + {"name": "byPriceBand", + "properties": [{"price": "asc"}, {"category": "asc"}], + "integerRange": {"on": "price", "range": 100u64, "step": 100u64}, + "averageable": "quantity"}, + {"name": "byDay", + "properties": [{"$createdAt": "asc"}, {"category": "asc"}], + "timeRange": {"on": "$createdAt", "range": 86400, "step": 86400}, + "averageable": "quantity"} + ], + "additionalProperties": false + }}), + version, + ) +} + +/// A `review` whose index sums and counts `grade` per restaurant, and a `note` that counts and +/// sums nothing. +fn reviews(version: &PlatformVersion) -> Arc { + contract( + 32, + platform_value!({ + "review": { + "type": "object", + "properties": { + "restaurantId": {"type": "string", "minLength": 1, "maxLength": 59, "position": 0}, + "grade": {"type": "integer", "minimum": 0, "maximum": 100, "position": 1} + }, + "required": ["restaurantId", "grade"], + "indices": [ + {"name": "byRestaurant", + "properties": [{"restaurantId": "asc"}], + "averageable": "grade"} + ], + "additionalProperties": false + }, + "note": { + "type": "object", + "properties": { + "name": {"type": "string", "minLength": 1, "maxLength": 59, "position": 0} + }, + "required": ["name"], + "additionalProperties": false + } + }), + version, + ) +} + +fn equal(field: &str, value: Value) -> WhereClause { + WhereClause { + field: field.to_string(), + operator: WhereOperator::Equal, + value, + } +} + +fn any_of(field: &str, values: Value) -> WhereClause { + WhereClause { + field: field.to_string(), + operator: WhereOperator::In, + value: values, + } +} + +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn should_refuse_before_sending_exactly_the_requests_no_index_serves() { + // Windows ride protocol version 14, which testnet runs, and the latest version. + let mut versions = vec![ + PlatformVersion::get(14).expect("protocol version 14"), + PlatformVersion::latest(), + ]; + versions.dedup_by_key(|version| version.protocol_version); + for version in versions { + agree_at(version).await; + } +} + +async fn agree_at(version: &'static PlatformVersion) { + let fixture = QueryFixture::new_with_version(version); + let listings = listings(version); + let reviews = reviews(version); + for contract in [&listings, &reviews] { + fixture + .platform + .drive + .apply_contract(contract, BlockInfo::default(), true, None, None, version) + .expect("store the contract"); + } + let (mut client, server) = fixture.client(); + let listing = || DocumentQuery::new(Arc::clone(&listings), "listing").expect("listing"); + let review = || DocumentQuery::new(Arc::clone(&reviews), "review").expect("review"); + let note = || DocumentQuery::new(Arc::clone(&reviews), "note").expect("note"); + let price_window = || listing().with_integer_range("price", Value::U64(200)); + let restaurants_in = || any_of("restaurantId", platform_value!(["a", "b"])); + let categories_in = || any_of("category", platform_value!(["tools", "toys"])); + + // (what it is, the view's check, the request, whether an index serves it) + let shapes: Vec<(&str, Check, DocumentQuery, bool)> = vec![ + // No index covers a price window beside an equality on `$createdAt`. + ( + "documents: price window + $createdAt equality", + check::, + price_window().with_where(equal("$createdAt", Value::U64(1_700_000_000_000))), + false, + ), + ( + "documents: price window", + check::, + price_window(), + true, + ), + ( + "documents: price window + category", + check::, + price_window().with_where(equal("category", Value::Text("tools".to_string()))), + true, + ), + // No index serves two windows. + ( + "documents: two windows", + check::, + price_window().with_time_range( + "$createdAt", + TimeRangeSelector::ByStart { + start_ms: 1_700_006_400_000, + }, + ), + false, + ), + // Nothing sums `price`. + ( + "sum(price)", + check::, + listing().with_select(SelectProjection::sum("price")), + false, + ), + ( + "sum(price) per category", + check::, + listing() + .with_select(SelectProjection::sum("price")) + .with_where(categories_in()) + .with_group_by("category"), + false, + ), + ( + "avg(price)", + check::, + listing().with_select(SelectProjection::avg("price")), + false, + ), + ( + "avg(price) per category", + check::, + listing() + .with_select(SelectProjection::avg("price")) + .with_where(categories_in()) + .with_group_by("category"), + false, + ), + ( + "sum(grade) of restaurants", + check::, + review() + .with_select(SelectProjection::sum("grade")) + .with_where(restaurants_in()), + true, + ), + ( + "avg(grade) per restaurant", + check::, + review() + .with_select(SelectProjection::avg("grade")) + .with_where(restaurants_in()) + .with_group_by("restaurantId"), + true, + ), + ( + "sum(quantity) in a price window + category", + check::, + price_window() + .with_select(SelectProjection::sum("quantity")) + .with_where(equal("category", Value::Text("tools".to_string()))), + true, + ), + // A `note` counts nothing. + ( + "count of notes", + check::, + note().with_select(SelectProjection::count_star()), + false, + ), + ( + "count of notes per name", + check::, + note() + .with_select(SelectProjection::count_star()) + .with_where(any_of("name", platform_value!(["a", "b"]))) + .with_group_by("name"), + false, + ), + ( + "count in a price window + category", + check::, + price_window() + .with_select(SelectProjection::count_star()) + .with_where(equal("category", Value::Text("tools".to_string()))), + true, + ), + ( + "count in a price window per category", + check::, + price_window() + .with_select(SelectProjection::count_star()) + .with_where(categories_in()) + .with_group_by("category"), + true, + ), + ]; + let protocol_version = version.protocol_version; + for (shape, check, query, served) in shapes { + let request = + wire::GetDocumentsRequest::try_from_platform_versioned(query.clone(), version) + .expect("the query encodes"); + let answer = client.get_documents(request).await.map(drop); + let checked = check(&query, version); + assert_eq!( + (answer.is_ok(), checked.is_ok()), + (served, served), + "protocol {protocol_version}, {shape}: the node answers {answer:?}, the check \ + before sending says {checked:?}" + ); + if !served { + assert_eq!( + code(answer), + Code::InvalidArgument, + "protocol {protocol_version}, {shape}: a query error" + ); + } + } + server.abort(); +} diff --git a/packages/rs-drive-proof-verifier/src/proof.rs b/packages/rs-drive-proof-verifier/src/proof.rs index 6b69adafd91..0b62e60393d 100644 --- a/packages/rs-drive-proof-verifier/src/proof.rs +++ b/packages/rs-drive-proof-verifier/src/proof.rs @@ -1950,6 +1950,36 @@ where type Request = Q; type Response = platform::GetDocumentsResponse; + /// The verifier rebuilds Drive's path query from the request alone before it reads the + /// proof: the where-clause shape, the route (by id, through an index, indexOnly) and the + /// index it reads. It does so without the cursor document on every page, so a request whose + /// path query cannot be built that way, such as one no index covers, can never verify; every + /// node refuses it too. The path query is built at `platform_version`, the version the + /// request is encoded with: a shape only a later version serves carries a protocol feature, + /// and the SDK's protocol gate encodes such a request at the network's version before this + /// check runs, so the check never refuses what that later version serves. + fn check_request( + request: &Self::Request, + platform_version: &PlatformVersion, + ) -> Result<(), Error> + where + Self: Sized, + { + let request: DriveDocumentQuery<'dq> = + request + .clone() + .try_into() + .map_err(|e: Q::Error| Error::RequestError { + error: e.to_string(), + })?; + request + .construct_path_query(None, platform_version) + .map(drop) + .map_err(|e| Error::RequestError { + error: format!("no answer to this documents query can be verified: {e}"), + }) + } + fn maybe_from_proof_with_metadata<'a, I: Into, O: Into>( request: I, response: O, diff --git a/packages/rs-sdk/src/sdk/protocol_gate_tests.rs b/packages/rs-sdk/src/sdk/protocol_gate_tests.rs index 09246968eec..0dfa5b2b1a5 100644 --- a/packages/rs-sdk/src/sdk/protocol_gate_tests.rs +++ b/packages/rs-sdk/src/sdk/protocol_gate_tests.rs @@ -1542,13 +1542,42 @@ fn assert_refused_for( } } -/// A `domain` query that reads the elements of `records.identity`. +/// A `post` contract whose `hashtags` is a typed array of strings, indexed by element. +fn posts() -> Arc { + let schemas = dpp::platform_value::platform_value!({"post": { + "type": "object", + "properties": { + "hashtags": { + "type": "array", + "maxItems": 10, + "items": {"type": "string", "minLength": 1, "maxLength": 61}, + "position": 0 + } + }, + "indices": [ + {"name": "byHashtag", "properties": [{"hashtags": "asc"}]} + ], + "additionalProperties": false + }}); + Arc::new( + dpp::data_contract::DataContractFactory::new(PlatformVersion::latest().protocol_version) + .unwrap() + .create_with_value_config(Identifier::new([9; 32]), 0, schemas, None, None) + .unwrap() + .data_contract_owned(), + ) +} + +/// A `post` query that reads the elements of `hashtags`, which the type's index serves. fn contains_query() -> DocumentQuery { - plain_query().with_where(DriveWhereClause { - field: "records.identity".to_string(), - operator: WhereOperator::Contains, - value: dpp::platform_value::Value::Identifier([1; 32]), - }) + DocumentQuery::new(posts(), "post") + .unwrap() + .with_limit(10) + .with_where(DriveWhereClause { + field: "hashtags".to_string(), + operator: WhereOperator::Contains, + value: dpp::platform_value::Value::Text("dash".to_string()), + }) } /// A `tip` contract whose documents are summed by `amount`. @@ -1812,7 +1841,10 @@ fn should_refuse_a_document_query_that_does_not_state_its_requirement() { } /// A mock SDK does not enforce the gate: it sends a query that uses a protocol 14 feature -/// whatever version it starts at, as a test registered it. +/// whatever version it starts at, as a test registered it. The check before sending still runs +/// at the version the query is encoded with, so the feature here is a composite page, which a +/// check at 13 reads by its shape alone; a typed array's elements, by contrast, are read only +/// from 14, so a check at 13 refuses a `contains` as its verifier at 13 would. #[tokio::test] async fn should_send_protocol_14_document_queries_from_a_mock_that_does_not_enforce_the_gate() { let mut sdk = SdkBuilder::new_mock() @@ -1820,10 +1852,10 @@ async fn should_send_protocol_14_document_queries_from_a_mock_that_does_not_enfo .build() .unwrap(); sdk.mock() - .expect_fetch_many(contains_query(), None::) + .expect_fetch(composite_query(), None::) .await .expect("a mock at 13 encodes the query"); - Document::fetch_many(&sdk, contains_query()) + CompositeDocuments::fetch(&sdk, composite_query()) .await .expect("a mock sends what a test registered"); } diff --git a/packages/rs-sdk/tests/fetch/common.rs b/packages/rs-sdk/tests/fetch/common.rs index b5c96332a3d..e0776c88c73 100644 --- a/packages/rs-sdk/tests/fetch/common.rs +++ b/packages/rs-sdk/tests/fetch/common.rs @@ -73,6 +73,57 @@ pub fn mock_document_type() -> dpp::data_contract::document_type::DocumentType { .expect("expected to create a document type") } +/// A mock document type whose documents are counted ([`mock_document_type`] counts nothing): +/// the type counts its documents, and its index on `a` counts them per value and over a range +/// of values, so every count a mock test fetches is one a node serves and the SDK verifies. +pub fn mock_countable_document_type() -> dpp::data_contract::document_type::DocumentType { + use dpp::{ + data_contract::document_type::DocumentType, platform_value::platform_value, + version::PlatformVersion, + }; + + let platform_version = PlatformVersion::latest(); + + let schema = platform_value!({ + "type": "object", + "documentsCountable": true, + "properties": { + "a": { + "type": "string", + "maxLength": 10, + "position": 0 + } + }, + "indices": [ + { + "name": "byA", + "properties": [{"a": "asc"}], + "countable": "countable", + "rangeCountable": true + } + ], + "additionalProperties": false, + }); + + let config = + DataContractConfig::default_for_version(platform_version).expect("create a default config"); + + DocumentType::try_from_schema( + Identifier::random(), + 1, + config.version(), + "document_type_name", + schema, + None, + &BTreeMap::new(), + &config, + true, + &mut vec![], + platform_version, + ) + .expect("expected to create a document type") +} + /// Create a mock data contract for testing of mock API pub fn mock_data_contract( document_type: Option<&dpp::data_contract::document_type::DocumentType>, diff --git a/packages/rs-sdk/tests/fetch/document_count.rs b/packages/rs-sdk/tests/fetch/document_count.rs index 02012630300..8d1cf4a1b27 100644 --- a/packages/rs-sdk/tests/fetch/document_count.rs +++ b/packages/rs-sdk/tests/fetch/document_count.rs @@ -36,7 +36,9 @@ use std::sync::Arc; -use super::common::{bootstrap_mock_sdk_to_latest, mock_data_contract, mock_document_type}; +use super::common::{ + bootstrap_mock_sdk_to_latest, mock_countable_document_type, mock_data_contract, +}; use dash_sdk::{ platform::{documents::document_query::DocumentQuery, Fetch}, Sdk, SdkBuilder, @@ -64,7 +66,7 @@ async fn count_capable_mock_sdk() -> Sdk { async fn test_mock_fetch_document_count_returns_expected() { let mut sdk = count_capable_mock_sdk().await; - let document_type = mock_document_type(); + let document_type = mock_countable_document_type(); let data_contract = mock_data_contract(Some(&document_type)); let query = DocumentQuery::new(Arc::new(data_contract), document_type.name()) .expect("build DocumentQuery") @@ -90,7 +92,7 @@ async fn test_mock_fetch_document_count_returns_expected() { async fn test_mock_fetch_document_count_zero() { let mut sdk = count_capable_mock_sdk().await; - let document_type = mock_document_type(); + let document_type = mock_countable_document_type(); let data_contract = mock_data_contract(Some(&document_type)); let query = DocumentQuery::new(Arc::new(data_contract), document_type.name()) .expect("build DocumentQuery") @@ -115,7 +117,7 @@ async fn test_mock_fetch_document_count_zero() { async fn test_mock_fetch_document_count_not_found() { let mut sdk = count_capable_mock_sdk().await; - let document_type = mock_document_type(); + let document_type = mock_countable_document_type(); let data_contract = mock_data_contract(Some(&document_type)); let query = DocumentQuery::new(Arc::new(data_contract), document_type.name()) .expect("build DocumentQuery") @@ -145,7 +147,7 @@ async fn test_mock_fetch_document_count_not_found() { async fn test_mock_fetch_document_split_counts_with_in_clause() { let mut sdk = count_capable_mock_sdk().await; - let document_type = mock_document_type(); + let document_type = mock_countable_document_type(); let data_contract = mock_data_contract(Some(&document_type)); let query = DocumentQuery::new(Arc::new(data_contract), document_type.name()) .expect("build DocumentQuery") @@ -197,7 +199,7 @@ async fn test_mock_fetch_document_split_counts_with_in_clause() { async fn test_mock_fetch_document_split_counts_with_distinct_range() { let mut sdk = count_capable_mock_sdk().await; - let document_type = mock_document_type(); + let document_type = mock_countable_document_type(); let data_contract = mock_data_contract(Some(&document_type)); let query = DocumentQuery::new(Arc::new(data_contract), document_type.name()) .expect("build DocumentQuery") @@ -255,7 +257,7 @@ async fn test_mock_fetch_document_split_counts_with_distinct_range() { async fn test_mock_fetch_document_count_with_distinct_range_sums_entries() { let mut sdk = count_capable_mock_sdk().await; - let document_type = mock_document_type(); + let document_type = mock_countable_document_type(); let data_contract = mock_data_contract(Some(&document_type)); let query = DocumentQuery::new(Arc::new(data_contract), document_type.name()) .expect("build DocumentQuery") @@ -297,7 +299,7 @@ async fn test_mock_fetch_document_count_with_distinct_range_sums_entries() { async fn test_mock_fetch_document_split_counts_preserves_none_for_absent_in_values() { let mut sdk = count_capable_mock_sdk().await; - let document_type = mock_document_type(); + let document_type = mock_countable_document_type(); let data_contract = mock_data_contract(Some(&document_type)); let query = DocumentQuery::new(Arc::new(data_contract), document_type.name()) .expect("build DocumentQuery") From 75c7248b22304a89ac6b8d6ed2096e98b33e5ffc Mon Sep 17 00:00:00 2001 From: Ivan Shumkov Date: Thu, 5 Nov 2026 17:06:26 +0700 Subject: [PATCH 3/4] fix(sdk): refuse composite sub-queries in the generic documents check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `FromProof for Documents::check_request` built the page's path query but did not look at the sub-queries a `DriveDocumentQuery` can carry, which its verifier refuses at once (`ensure_no_sub_queries`). The check now calls the same Drive guard first, made public for it, so a direct caller of the generic impl is refused before sending what the verifier refuses. `DocumentQuery`'s own check already refused sub-queries, so the SDK's fetch path is unchanged. Test would have caught this in CI: ✖ before fix (should_refuse_sub_queries_before_sending_a_documents_page: "a page with sub-queries must be refused, got Ok(())"), ✔ after. Co-Authored-By: Claude Opus 5.5 --- packages/rs-drive-proof-verifier/src/proof.rs | 59 ++++++++++++++++++- packages/rs-drive/src/query/mod.rs | 2 +- 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/packages/rs-drive-proof-verifier/src/proof.rs b/packages/rs-drive-proof-verifier/src/proof.rs index 0b62e60393d..748d95a805a 100644 --- a/packages/rs-drive-proof-verifier/src/proof.rs +++ b/packages/rs-drive-proof-verifier/src/proof.rs @@ -1950,7 +1950,8 @@ where type Request = Q; type Response = platform::GetDocumentsResponse; - /// The verifier rebuilds Drive's path query from the request alone before it reads the + /// The verifier refuses a query carrying composite sub-queries, which it would otherwise + /// ignore, and rebuilds Drive's path query from the request alone before it reads the /// proof: the where-clause shape, the route (by id, through an index, indexOnly) and the /// index it reads. It does so without the cursor document on every page, so a request whose /// path query cannot be built that way, such as one no index covers, can never verify; every @@ -1972,6 +1973,11 @@ where .map_err(|e: Q::Error| Error::RequestError { error: e.to_string(), })?; + request + .ensure_no_sub_queries("verify_proof") + .map_err(|e| Error::RequestError { + error: format!("no answer to this documents query can be verified: {e}"), + })?; request .construct_path_query(None, platform_version) .map(drop) @@ -3173,6 +3179,57 @@ mod tests { use super::*; use platform_serialization::PLATFORM_BINCODE_CONFIG; + /// A plain documents page cannot verify the sub-queries a composite request carries: its + /// verifier refuses them rather than report them verified, so its check refuses them before + /// sending, and sends the page alone. + #[test] + fn should_refuse_sub_queries_before_sending_a_documents_page() { + use dpp::data_contract::accessors::v0::DataContractV0Getters; + use drive::query::{DriveSubQuery, SubQueryKind}; + + let platform_version = PlatformVersion::latest(); + let contract = dpp::tests::fixtures::get_data_contract_fixture( + None, + 0, + platform_version.protocol_version, + ) + .data_contract_owned(); + let document_type = contract + .document_type_for_name("niceDocument") + .expect("the fixture has this document type"); + let mut page = DriveDocumentQuery { + contract: &contract, + document_type, + internal_clauses: Default::default(), + offset: None, + limit: Some(10), + order_by: Default::default(), + start_at: None, + start_at_included: false, + block_time_ms: None, + resolved_time_ranges: vec![], + sub_queries: vec![], + }; + >::check_request(&page, platform_version) + .expect("a plain page is sent"); + + page.sub_queries.push(DriveSubQuery { + contract: &contract, + document_type, + kind: SubQueryKind::Documents, + where_clauses: vec![], + order_by: vec![], + limit: Some(10), + binding: None, + }); + match >::check_request(&page, platform_version) { + Err(Error::RequestError { error }) => { + assert!(error.contains("sub-queries"), "{error}") + } + other => panic!("a page with sub-queries must be refused, got {other:?}"), + } + } + #[test] fn try_u32_to_u16_succeeds_for_valid_values() { assert_eq!(try_u32_to_u16(0).unwrap(), 0u16); diff --git a/packages/rs-drive/src/query/mod.rs b/packages/rs-drive/src/query/mod.rs index b4dcd6a83e4..6ca8eac8394 100644 --- a/packages/rs-drive/src/query/mod.rs +++ b/packages/rs-drive/src/query/mod.rs @@ -1973,7 +1973,7 @@ impl<'a> DriveDocumentQuery<'a> { /// (page-only) surface, which would otherwise silently ignore them — /// on the verify side that would mean reporting the composition /// verified when only the page was. - pub(crate) fn ensure_no_sub_queries(&self, surface: &str) -> Result<(), Error> { + pub fn ensure_no_sub_queries(&self, surface: &str) -> Result<(), Error> { if self.sub_queries.is_empty() { return Ok(()); } From 9fb36ecc60638d960bf6e5878b7d458b2c719920 Mon Sep 17 00:00:00 2001 From: Ivan Shumkov Date: Thu, 5 Nov 2026 17:39:17 +0700 Subject: [PATCH 4/4] refactor(sdk): share the aggregate path-query lowering and the request routing with Drive MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two request-only steps the node runs before it answers a count, sum or average now live once in Drive, and the SDK's check before sending and verifier run them too: - Plan -> path query. `CountProofPlan::path_query` and `SumProofPlan::path_query(.., with_counts, ..)` name the builder each proof mode proves its index through (with a `summableOffCountIndex` index's range proofs read through its sums). The proof executors prove what they return; the SDK builds it from the same plan before sending and before verifying, so a request whose path query cannot be built — e.g. an ungrouped average over a range under several `In` prefixes — is refused locally in the node's words. - Routing. drive-abci's versioned `compute_aggregate_mode_and_check_limit` (v0/v1/v2 and its dispatcher) moves to `drive::query::aggregate_routing` under `verify`. drive-abci calls it through `route_aggregate`, which reports `Error::Query` as `QueryError::Query` and anything else as `QueryError::Drive`, as before. The SDK's count, sum and average views route through it instead of their own `resolve_{count,sum}_mode`, which brings the routing's `limit` contract and its ranked/having routing to the check: e.g. an ungrouped COUNT(*) with a limit is refused before sending. Element clauses are keyed by the routed mode, as the server keys them. `From` for `SumMode`/`AverageMode` replaces the inline 1:1 mappings. Server output is unchanged: the moved routing code and its texts are identical, and the lowering calls the builders the per-mode methods called. Evidence: the temporary A/B probe (4,800 proved count/sum/avg requests at protocol 14 and latest, origin/v5.1-dev vs this tree) reports identical proofs and refusals; the new proof_plan_equivalence_tests pin the dispatcher's answer (proof or refusal) to the per-mode `execute_*_with_proof` methods' for every request of a matrix that reaches all five plans of count, sum and average (an equivalence guard, not a red-to-green test); rs-drive lib 4,358 and drive-abci lib 4,118 passed. Test would have caught this in CI: ✖ before fix, ✔ after — - should_refuse_a_limit_the_routed_mode_cannot_honor_before_sending: ✖ "DocumentCount must refuse … got Ok(())" - should_refuse_an_aggregate_whose_path_query_cannot_be_built_before_sending: ✖ "DocumentAverage must refuse … got Ok(())" - should_refuse_an_aggregate_view_of_a_ranked_or_having_query (now names DocumentRankedEntries): ✖ "GROUP BY on field 'restaurantId' which is not constrained by an `In` or range where clause …" - drive-abci index_coverage agreement test: ✖ "avg(amount) of sales in a price range under several categories: the node answers Err(InvalidArgument … prefix properties must use `==` (no `in`))", the check sent it. Co-Authored-By: Claude Opus 5.5 --- .../src/documents/aggregate_routing.rs | 48 ++ .../src/documents/array_element_clauses.rs | 33 +- .../src/documents/average_proof_helpers.rs | 105 ++-- .../src/documents/check_request_tests.rs | 160 ++++- .../src/documents/count_proof_helpers.rs | 159 ++--- .../src/documents/document_query.rs | 17 +- .../src/documents/mod.rs | 1 + .../src/documents/sum_proof_helpers.rs | 147 ++--- .../document_query/v1/dispatch/average.rs | 7 +- .../query/document_query/v1/dispatch/sum.rs | 7 +- .../src/query/document_query/v1/mod.rs | 1 - .../src/query/document_query/v1/routing.rs | 42 +- .../query_request_errors/index_coverage.rs | 76 ++- .../src/query/aggregate_routing}/mod.rs | 45 +- .../src/query/aggregate_routing}/v0/mod.rs | 30 +- .../src/query/aggregate_routing}/v1/mod.rs | 35 +- .../src/query/aggregate_routing}/v2/mod.rs | 8 +- .../query/drive_document_average_query/mod.rs | 15 + .../execute_point_lookup.rs | 4 +- .../executors/proof.rs | 77 +-- .../drive_document_count_query/proof_plan.rs | 85 +++ .../executors/proof.rs | 94 +-- .../src/query/drive_document_sum_query/mod.rs | 15 +- .../drive_document_sum_query/proof_plan.rs | 80 +++ packages/rs-drive/src/query/mod.rs | 9 + .../src/query/proof_plan_equivalence_tests.rs | 586 ++++++++++++++++++ .../drive_abci_query_versions/mod.rs | 4 +- 27 files changed, 1386 insertions(+), 504 deletions(-) create mode 100644 packages/dash-platform-queries/src/documents/aggregate_routing.rs rename packages/{rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit => rs-drive/src/query/aggregate_routing}/mod.rs (80%) rename packages/{rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit => rs-drive/src/query/aggregate_routing}/v0/mod.rs (77%) rename packages/{rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit => rs-drive/src/query/aggregate_routing}/v1/mod.rs (80%) rename packages/{rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit => rs-drive/src/query/aggregate_routing}/v2/mod.rs (94%) create mode 100644 packages/rs-drive/src/query/proof_plan_equivalence_tests.rs diff --git a/packages/dash-platform-queries/src/documents/aggregate_routing.rs b/packages/dash-platform-queries/src/documents/aggregate_routing.rs new file mode 100644 index 00000000000..dabda2519fb --- /dev/null +++ b/packages/dash-platform-queries/src/documents/aggregate_routing.rs @@ -0,0 +1,48 @@ +//! The grouped mode a count, sum or average request is answered in, decided +//! by Drive's routing of the request +//! ([`compute_aggregate_mode_and_check_limit`]), the routing every node runs +//! before it executes one, at the protocol version the request is encoded +//! for. + +use crate::documents::document_query::{having_page_refusal, DocumentQuery}; +use dpp::version::PlatformVersion; +use drive::query::aggregate_routing::{compute_aggregate_mode_and_check_limit, AggregateRouting}; +use drive::query::CountMode; + +/// The grouped mode a node answers `request` in, a `function_name` +/// (`"COUNT"`, `"SUM"` or `"AVG"`) select with its pending windows resolved. +/// +/// The routing refuses what every node refuses — a grouping no `In` or +/// range constrains, a `limit` the mode cannot honor — in the node's words. +/// A request it routes to the ranked or having-range surface is answered +/// with a page a count, sum or average view cannot verify, so it is refused +/// in favour of the view that verifies it. +pub(super) fn grouped_mode( + request: &DocumentQuery, + function_name: &str, + platform_version: &PlatformVersion, +) -> Result { + let routing = compute_aggregate_mode_and_check_limit( + &request.select, + &request.group_by, + &request.where_clauses, + &request.order_by_clauses, + (request.limit != 0).then_some(request.limit), + &request.having, + function_name, + platform_version, + ) + .map_err(|e| drive_proof_verifier::Error::RequestError { + error: format!("no node answers this {function_name} request: {e}"), + })?; + match routing { + AggregateRouting::Grouped(mode) => Ok(mode), + AggregateRouting::Ranked => Err(drive_proof_verifier::Error::RequestError { + error: format!( + "a grouped {function_name} ordered by itself is answered as a ranked page, which \ + a count, sum or average view cannot verify; fetch it as DocumentRankedEntries" + ), + }), + AggregateRouting::HavingRange => Err(having_page_refusal()), + } +} diff --git a/packages/dash-platform-queries/src/documents/array_element_clauses.rs b/packages/dash-platform-queries/src/documents/array_element_clauses.rs index 7a556097145..141e9fee359 100644 --- a/packages/dash-platform-queries/src/documents/array_element_clauses.rs +++ b/packages/dash-platform-queries/src/documents/array_element_clauses.rs @@ -9,7 +9,8 @@ use dpp::data_contract::document_type::DocumentTypeRef; use dpp::data_contract::DataContract; use dpp::version::PlatformVersion; use drive::query::{ - key_array_element_clauses, validate_and_canonicalize_where_clauses, WhereClause, WhereOperator, + key_array_element_clauses, validate_and_canonicalize_where_clauses, CountMode, WhereClause, + WhereOperator, }; /// `where_clauses`, read against the document type `document_type_name` of @@ -39,18 +40,20 @@ pub fn key_element_clauses( ) } -/// [`aggregate_where_clauses`] of `request` before it is sent. Callers pass the -/// request with its pending window selections resolved, as the verifier resolves -/// them (`DocumentQuery::resolved_for_checking`), so whatever this refuses the +/// [`aggregate_where_clauses`] of `request` before it is sent, a request the +/// routing answers in `mode`. Callers pass the request with its pending window +/// selections resolved, as the verifier resolves them +/// (`DocumentQuery::resolved_for_checking`), so whatever this refuses the /// verifier refuses too. pub(super) fn aggregate_request_where_clauses( request: &DocumentQuery, + mode: CountMode, folds_entries: bool, platform_version: &PlatformVersion, ) -> Result, drive_proof_verifier::Error> { aggregate_where_clauses( document_type_named(&request.data_contract, &request.document_type_name)?, - &request.group_by, + mode, request.where_clauses.clone(), folds_entries, platform_version, @@ -69,8 +72,10 @@ pub(super) fn document_type_named<'a>( } /// Whether a request grouped by `group_by` is grouped by one field that an -/// `In` or a `containsAny` constrains: the shape drive-abci routes as -/// `GroupByIn` (its `is_in_field`), which the SDK cannot call. +/// `In` or a `containsAny` constrains: the shape Drive's routing answers as +/// `CountMode::GroupByIn` from protocol version 14 +/// (`drive::query::aggregate_routing`), which the count, sum and average +/// views route through themselves. pub fn grouped_by_in_field(group_by: &[String], where_clauses: &[WhereClause]) -> bool { match group_by { [field] => where_clauses.iter().any(|clause| { @@ -91,18 +96,20 @@ pub fn grouped_by_in_field(group_by: &[String], where_clauses: &[WhereClause]) - /// detection, and the verifier's must run over the same shape or a valid /// proof is refused. /// -/// `folds_entries` is whether the caller adds the verified entries up into -/// one total (`DocumentCount`, `DocumentSum`, `DocumentAverage`): several -/// elements are then refused even grouped by the array, since the total -/// would count a document once per element it holds. +/// `mode` is the grouped mode the routing answers the request in: several +/// elements are read only grouped by the `In` field (`CountMode::GroupByIn`), +/// as the server keys them. `folds_entries` is whether the caller adds the +/// verified entries up into one total (`DocumentCount`, `DocumentSum`, +/// `DocumentAverage`): several elements are then refused even grouped by the +/// array, since the total would count a document once per element it holds. pub(super) fn aggregate_where_clauses( document_type: DocumentTypeRef, - group_by: &[String], + mode: CountMode, where_clauses: Vec, folds_entries: bool, platform_version: &PlatformVersion, ) -> Result, drive_proof_verifier::Error> { - let grouped_by_in = !folds_entries && grouped_by_in_field(group_by, &where_clauses); + let grouped_by_in = !folds_entries && matches!(mode, CountMode::GroupByIn); let keyed = key_clauses_of( document_type, where_clauses, diff --git a/packages/dash-platform-queries/src/documents/average_proof_helpers.rs b/packages/dash-platform-queries/src/documents/average_proof_helpers.rs index f1da6aa9a6d..fbc82460894 100644 --- a/packages/dash-platform-queries/src/documents/average_proof_helpers.rs +++ b/packages/dash-platform-queries/src/documents/average_proof_helpers.rs @@ -18,12 +18,12 @@ //! [`DocumentAverage`]: drive_proof_verifier::DocumentAverage //! [`DocumentSplitAverages`]: drive_proof_verifier::DocumentSplitAverages +use crate::documents::aggregate_routing::grouped_mode; use crate::documents::array_element_clauses::{ aggregate_request_where_clauses, aggregate_where_clauses, document_type_named, }; use crate::documents::document_query::normalize_time_range_clauses_with_metadata_time; use crate::documents::document_query::DocumentQuery; -use crate::documents::sum_proof_helpers::resolve_sum_mode; use dapi_grpc::platform::v0::{GetDocumentsResponse, Proof, ResponseMetadata}; use dapi_grpc::platform::VersionedGrpcResponse; use dash_context_provider::ContextProvider; @@ -31,8 +31,8 @@ use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::data_contract::document_type::DocumentTypeRef; use dpp::version::PlatformVersion; use drive::query::drive_document_average_query::AverageMode; -use drive::query::drive_document_sum_query::{DriveDocumentSumQuery, SumMode, SumProofPlan}; -use drive::query::{OrderClause, ResolvedTimeRange, SelectFunction, WhereClause}; +use drive::query::drive_document_sum_query::{DriveDocumentSumQuery, SumProofPlan}; +use drive::query::{ResolvedTimeRange, SelectFunction, WhereClause}; use drive_proof_verifier::{ verify_aggregate_count_and_sum_proof, verify_carrier_aggregate_count_and_sum_proof, verify_distinct_count_and_sum_proof, verify_point_lookup_count_and_sum_proof, @@ -79,66 +79,66 @@ pub(super) fn check_average_request( assert_select_is_avg(request)?; let (resolved, resolved_time_ranges) = request.resolved_for_checking()?; let request = &resolved; - let where_clauses = aggregate_request_where_clauses(request, folds_entries, platform_version)?; - let average_mode = resolve_average_mode(&request.group_by, &where_clauses)?; request.ensure_no_having()?; + let mode = grouped_mode(request, "AVG", platform_version)?; + let where_clauses = + aggregate_request_where_clauses(request, mode, folds_entries, platform_version)?; let document_type = document_type_named(&request.data_contract, &request.document_type_name)?; average_proof_plan( + request, &document_type, &where_clauses, &resolved_time_ranges, - &request.select.field, - average_mode, - &request.order_by_clauses, - request.limit, + AverageMode::from(mode), + platform_version, ) .map(drop) } -/// The SQL-shape [`AverageMode`] of an average request: the [`SumMode`] a sum -/// over the same `(group_by, where_clauses)` resolves to -/// ([`resolve_sum_mode`]), mapped 1:1 as drive-abci maps it. -fn resolve_average_mode( - group_by: &[String], - where_clauses: &[WhereClause], -) -> Result { - Ok(match resolve_sum_mode(group_by, where_clauses)? { - SumMode::Aggregate => AverageMode::Aggregate, - SumMode::GroupByIn => AverageMode::GroupByIn, - SumMode::GroupByRange => AverageMode::GroupByRange, - SumMode::GroupByCompound => AverageMode::GroupByCompound, - }) -} - -/// The proof plan a node makes for a proved average of `sum_property`, made -/// from the request alone ([`DriveDocumentSumQuery::average_proof_plan`]): the -/// primary-key route or the covering index, and the limit the path query -/// carries. A client cannot know a node's `max_query_limit`, so it leaves that -/// check to the node. +/// The proof plan a node makes for a proved average of `request`'s select +/// field, made from the request alone and lowered to the path query its proof +/// answers: the primary-key route or the covering index and the limit and walk +/// direction ([`DriveDocumentSumQuery::average_proof_plan`]), and the path +/// query ([`SumProofPlan::path_query`]), which the check before sending +/// discards and the verifier's Drive call rebuilds from the plan. A client +/// cannot know a node's `max_query_limit`, so it leaves that check to the +/// node. /// -/// `order_clauses` and `limit` are the request's, `limit` `0` when unset. +/// `where_clauses` are the request's as the server reads them +/// ([`aggregate_where_clauses`]). fn average_proof_plan<'a>( + request: &DocumentQuery, document_type: &'a DocumentTypeRef<'_>, where_clauses: &[WhereClause], resolved_time_ranges: &[ResolvedTimeRange], - sum_property: &str, average_mode: AverageMode, - order_clauses: &[OrderClause], - limit: u32, + platform_version: &PlatformVersion, ) -> Result, drive_proof_verifier::Error> { - DriveDocumentSumQuery::average_proof_plan( + let unverifiable = |e| drive_proof_verifier::Error::RequestError { + error: format!("no answer to this average can be verified: {e}"), + }; + let plan = DriveDocumentSumQuery::average_proof_plan( document_type, where_clauses, resolved_time_ranges, - sum_property, + &request.select.field, average_mode, - order_clauses, - (limit != 0).then_some(limit), + &request.order_by_clauses, + (request.limit != 0).then_some(request.limit), None, ) - .map_err(|e| drive_proof_verifier::Error::RequestError { - error: format!("no answer to this average can be verified: {e}"), - }) + .map_err(unverifiable)?; + plan.path_query( + request.data_contract.id().to_buffer(), + *document_type, + request.document_type_name.clone(), + where_clauses.to_vec(), + request.select.field.clone(), + true, + platform_version, + ) + .map_err(unverifiable)?; + Ok(plan) } /// Verify an AVG-shape proof and return per-branch `AverageEntry`s. @@ -148,10 +148,9 @@ fn average_proof_plan<'a>( /// rather than a clause-shape heuristic, so the SDK's routing matches /// the server's exactly. /// -/// **Routing**: build an [`AverageMode`] from `(group_by, -/// where_clauses)` matching the abci handler's `validate_and_route` -/// logic, then take Drive's plan ([`average_proof_plan`]). Branch by -/// the plan: +/// **Routing**: route the request to an [`AverageMode`] with the +/// node's own routing ([`grouped_mode`]), then take Drive's plan +/// ([`average_proof_plan`]). Branch by the plan: /// /// - [`SumProofPlan::PrimaryKeySumTree`] (empty where on a doctype /// that declares `documentsCountable` and sums by the averaged @@ -210,30 +209,28 @@ pub(super) fn verify_average_query( request.document_type_name, e ), })?; + // The grouped mode the node's routing answers the request in, read over + // the clauses as the routing reads them: windows resolved, elements not + // yet keyed. + let mode = grouped_mode(&request, "AVG", platform_version)?; request.where_clauses = aggregate_where_clauses( document_type, - &request.group_by, + mode, std::mem::take(&mut request.where_clauses), folds_entries, platform_version, )?; - // Resolve the SQL-shape `AverageMode` the request implies — the - // same decision tree as `validate_and_route` in the abci handler, - // which maps it 1:1 from the count / sum mode. - let average_mode = resolve_average_mode(&request.group_by, &request.where_clauses)?; - // Drive's plan, the one the prover made from the same request: the // primary-key route or covering index, and the limit the path query // carries. let plan = average_proof_plan( + &request, &document_type, &request.where_clauses, &resolved_time_ranges, - &sum_property, - average_mode, - &request.order_by_clauses, - request.limit, + AverageMode::from(mode), + platform_version, )?; let sum_query = |index| DriveDocumentSumQuery { document_type, diff --git a/packages/dash-platform-queries/src/documents/check_request_tests.rs b/packages/dash-platform-queries/src/documents/check_request_tests.rs index 733ba175415..8661ae02a7f 100644 --- a/packages/dash-platform-queries/src/documents/check_request_tests.rs +++ b/packages/dash-platform-queries/src/documents/check_request_tests.rs @@ -418,10 +418,9 @@ fn should_refuse_a_having_view_without_a_having_clause() { /// From protocol version 14 a grouped aggregate ordered by its aggregate is /// served as a ranked answer, and one with a `having` clause as a having-range -/// answer. Neither is a grouped total a count, sum or average view verifies, -/// and its verifier refuses the request outright: a node serves a ranked or -/// having-range request only when no `In` or range constrains its group, since -/// the where clauses pin the properties before the grouped one. +/// answer. Neither is a grouped total a count, sum or average view verifies, so +/// the view routes the request as every node routes it and refuses it before +/// sending, naming the view that verifies it. #[test] fn should_refuse_an_aggregate_view_of_a_ranked_or_having_query() { let views: [(&str, Check, SelectProjection); 6] = [ @@ -462,12 +461,12 @@ fn should_refuse_an_aggregate_view_of_a_ranked_or_having_query() { .with_group_by("restaurantId") .order_by_selected_aggregate(RankingDirection::Descending) .with_limit(5); - for query in [ranked, having().with_select(select)] { + for (query, verified_by) in [ + (ranked, "DocumentRankedEntries"), + (having().with_select(select), "DocumentHavingEntries"), + ] { let error = refusal(view, check, &query); - assert!( - error.contains("not constrained by an `In` or range"), - "{view}: {error}" - ); + assert!(error.contains(verified_by), "{view}: {error}"); } } } @@ -1332,6 +1331,149 @@ fn should_refuse_an_aggregate_no_index_serves_before_sending() { } } +/// A `sale` whose index on `category` then `price` counts and sums `amount` over price ranges. +fn sales() -> DocumentQuery { + let schemas = platform_value!({"sale": { + "type": "object", + "properties": { + "category": {"type": "string", "minLength": 1, "maxLength": 59, "position": 0}, + "price": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 1}, + "amount": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 2} + }, + "required": ["category", "price", "amount"], + "indices": [ + {"name": "byCategoryPrice", + "properties": [{"category": "asc"}, {"price": "asc"}], + "averageable": "amount", + "rangeAverageable": true} + ], + "additionalProperties": false + }}); + let contract = DataContractFactory::new(PlatformVersion::latest().protocol_version) + .expect("factory") + .create_with_value_config(Identifier::new([15u8; 32]), 0, schemas, None, None) + .expect("the sale contract is well-formed") + .data_contract_owned(); + DocumentQuery::new(Arc::new(contract), "sale").expect("the contract has this document type") +} + +/// A count, sum or average proof answers the path query its plan lowers to, which the node +/// builds from the request alone before it proves anything. A request whose path query cannot +/// be built — an ungrouped average over a range under several `In` prefixes, which the range +/// total reads through one prefix only — is refused by every node and every verifier, so it is +/// refused before sending; the same average under one prefix is sent. +#[test] +fn should_refuse_an_aggregate_whose_path_query_cannot_be_built_before_sending() { + let price_above_zero = WhereClause { + field: "price".to_string(), + operator: WhereOperator::GreaterThan, + value: Value::U64(0), + }; + let average = || sales().with_select(SelectProjection::avg("amount")); + let under_several = average() + .with_where(WhereClause { + field: "category".to_string(), + operator: WhereOperator::In, + value: platform_value!(["tools", "toys"]), + }) + .with_where(price_above_zero.clone()); + let error = refusal("DocumentAverage", check::, &under_several); + assert!( + error.contains("no answer to this average can be verified") + && error.contains("prefix properties must use `==`"), + "{error}" + ); + let under_one = average() + .with_where(WhereClause { + field: "category".to_string(), + operator: WhereOperator::Equal, + value: Value::Text("tools".to_string()), + }) + .with_where(price_above_zero); + assert!( + check::(&under_one).is_ok(), + "{:?}", + check::(&under_one) + ); +} + +/// A node routes every count, sum and average before executing it, and refuses a `limit` the +/// routed mode cannot honor: a total is one row, and a grouping by an `In` field is bounded by +/// the `In` array. The view routes the request the same way and refuses it before sending, in +/// the node's words; a limit on a distinct walk, which a node honors, is sent. +#[test] +fn should_refuse_a_limit_the_routed_mode_cannot_honor_before_sending() { + let total = |select: SelectProjection| reviews().with_select(select).with_limit(1); + let per_restaurant = |select: SelectProjection| { + reviews() + .with_select(select) + .with_where(restaurants_in()) + .with_group_by("restaurantId") + .with_limit(1) + }; + let total_words = "is not valid for SELECT"; + let cases: Vec<(&str, Check, DocumentQuery)> = vec![ + ( + "DocumentCount", + check::, + total(SelectProjection::count_star()), + ), + ( + "DocumentSum", + check::, + total(SelectProjection::sum("grade")), + ), + ( + "DocumentAverage", + check::, + total(SelectProjection::avg("grade")), + ), + ( + "DocumentSplitCounts", + check::, + per_restaurant(SelectProjection::count_star()), + ), + ( + "DocumentSplitSums", + check::, + per_restaurant(SelectProjection::sum("grade")), + ), + ( + "DocumentSplitAverages", + check::, + per_restaurant(SelectProjection::avg("grade")), + ), + ]; + for (view, check, query) in cases { + let error = refusal(view, check, &query); + assert!( + error.contains("`limit`") && error.contains(total_words), + "{view}: {error}" + ); + let mut without_limit = query; + without_limit.limit = 0; + assert!( + check(&without_limit).is_ok(), + "{view}: {:?}", + check(&without_limit) + ); + } + let distinct_with_limit = reviews() + .with_select(SelectProjection::count_star()) + .with_where(WhereClause { + field: "hashtag".to_string(), + operator: WhereOperator::GreaterThan, + value: Value::Text("a".to_string()), + }) + .with_group_by("hashtag") + .with_limit(5); + assert!( + check::(&distinct_with_limit).is_ok(), + "{:?}", + check::(&distinct_with_limit) + ); +} + /// The verifier rebuilds a distinct walk's limit byte for byte and leaves the cap on it to the /// node's configuration, which a client cannot know: a limit any node may serve is sent, and /// one no path query can carry is refused. diff --git a/packages/dash-platform-queries/src/documents/count_proof_helpers.rs b/packages/dash-platform-queries/src/documents/count_proof_helpers.rs index c38501bd851..d037f70f982 100644 --- a/packages/dash-platform-queries/src/documents/count_proof_helpers.rs +++ b/packages/dash-platform-queries/src/documents/count_proof_helpers.rs @@ -13,6 +13,7 @@ //! [`DocumentCount`]: drive_proof_verifier::DocumentCount //! [`DocumentSplitCounts`]: drive_proof_verifier::DocumentSplitCounts +use crate::documents::aggregate_routing::grouped_mode; use crate::documents::array_element_clauses::{ aggregate_request_where_clauses, aggregate_where_clauses, document_type_named, }; @@ -25,8 +26,8 @@ use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::data_contract::document_type::DocumentTypeRef; use dpp::version::PlatformVersion; use drive::query::{ - CountMode, CountProofPlan, DriveDocumentCountQuery, OrderClause, ResolvedTimeRange, - SelectFunction, WhereClause, WhereOperator, + CountMode, CountProofPlan, DriveDocumentCountQuery, ResolvedTimeRange, SelectFunction, + WhereClause, }; use drive_proof_verifier::{ verify_aggregate_count_proof, verify_carrier_aggregate_count_proof, @@ -68,19 +69,14 @@ pub(super) fn assert_select_is_count( /// The refusals [`verify_count_query`] makes from the request alone, made /// before it is sent ([`drive_proof_verifier::FromProof::check_request`]). /// -/// A grouped request is verified only when an `In` or a range constrains its -/// group ([`resolve_count_mode`]), yet some requests without one are served. -/// From protocol version 14 a grouped request ordered by its count, or with a -/// `having` clause, is served as a ranked or having-range answer, and a node -/// serves one only when nothing constrains its group: its where clauses may -/// only pin the index properties before the grouped one. Older nodes refuse -/// those shapes, so refusing them here is right at every protocol version. -/// /// Pending window selections are resolved first, as the verifier resolves them /// ([`DocumentQuery::resolved_for_checking`]), so the checks read the clauses the verifier reads. -/// The last check is the verifier's proof plan ([`count_proof_plan`]): the primary-key route or -/// the covering index, and the limit, which the node plans its proof by too, so a count no index -/// serves is refused here in the node's words. +/// The request is then routed as every node routes it ([`grouped_mode`]): a grouping no `In` or +/// range constrains, or a `limit` its mode cannot honor, is refused in the node's words, and a +/// request the node answers as a ranked or having-range page is refused in favour of the view +/// that verifies it. The last check is the verifier's proof plan, lowered to its path query +/// ([`count_proof_plan`]), which the node proves by too, so a count no index serves, or whose +/// path query cannot be built, is refused here in the node's words. pub(super) fn check_count_request( request: &DocumentQuery, folds_entries: bool, @@ -90,38 +86,40 @@ pub(super) fn check_count_request( assert_select_is_count(request)?; let (resolved, resolved_time_ranges) = request.resolved_for_checking()?; let request = &resolved; - let where_clauses = aggregate_request_where_clauses(request, folds_entries, platform_version)?; - let count_mode = resolve_count_mode(&request.group_by, &where_clauses)?; request.ensure_no_having()?; + let count_mode = grouped_mode(request, "COUNT", platform_version)?; + let where_clauses = + aggregate_request_where_clauses(request, count_mode, folds_entries, platform_version)?; let document_type = document_type_named(&request.data_contract, &request.document_type_name)?; count_proof_plan( + request, &document_type, &where_clauses, &resolved_time_ranges, count_mode, - &request.order_by_clauses, - request.limit, platform_version, ) .map(drop) } -/// The proof plan a node makes for a proved count, made from the request alone -/// ([`DriveDocumentCountQuery::proof_plan`]): Drive resolves the SQL-shape -/// `count_mode` into its proof mode -/// ([`DriveDocumentCountQuery::detect_mode_versioned`]), then picks the -/// primary-key route or the covering index and the limit the path query -/// carries. A client cannot know a node's `max_query_limit`, so it leaves that -/// check to the node. +/// The proof plan a node makes for a proved count of `request`, made from the +/// request alone and lowered to the path query its proof answers. Drive +/// resolves the SQL-shape `count_mode` into its proof mode +/// ([`DriveDocumentCountQuery::detect_mode_versioned`]), picks the +/// primary-key route or the covering index and the limit and walk direction +/// ([`DriveDocumentCountQuery::proof_plan`]), and builds the path query +/// ([`CountProofPlan::path_query`]), which the check before sending discards +/// and the verifier's Drive call rebuilds from the plan. A client cannot know +/// a node's `max_query_limit`, so it leaves that check to the node. /// -/// `order_clauses` and `limit` are the request's, `limit` `0` when unset. +/// `where_clauses` are the request's as the server reads them +/// ([`aggregate_where_clauses`]). pub(super) fn count_proof_plan<'a>( + request: &DocumentQuery, document_type: &'a DocumentTypeRef<'_>, where_clauses: &[WhereClause], resolved_time_ranges: &[ResolvedTimeRange], count_mode: CountMode, - order_clauses: &[OrderClause], - limit: u32, platform_version: &PlatformVersion, ) -> Result, drive_proof_verifier::Error> { let mode = DriveDocumentCountQuery::detect_mode_versioned( @@ -133,18 +131,28 @@ pub(super) fn count_proof_plan<'a>( .map_err(|e| drive_proof_verifier::Error::RequestError { error: format!("count-mode detection failed: {e}"), })?; - DriveDocumentCountQuery::proof_plan( + let unverifiable = |e| drive_proof_verifier::Error::RequestError { + error: format!("no answer to this count can be verified: {e}"), + }; + let plan = DriveDocumentCountQuery::proof_plan( document_type, where_clauses, resolved_time_ranges, mode, - order_clauses, - (limit != 0).then_some(limit), + &request.order_by_clauses, + (request.limit != 0).then_some(request.limit), None, ) - .map_err(|e| drive_proof_verifier::Error::RequestError { - error: format!("no answer to this count can be verified: {e}"), - }) + .map_err(unverifiable)?; + plan.path_query( + request.data_contract.id().to_buffer(), + *document_type, + request.document_type_name.clone(), + where_clauses.to_vec(), + platform_version, + ) + .map_err(unverifiable)?; + Ok(plan) } /// Verify a count-shape proof and return per-branch entries. @@ -160,9 +168,8 @@ pub(super) fn count_proof_plan<'a>( /// `verify_distinct_count_proof` (different primitive ⇒ /// verification fails). /// -/// **Routing**: build a [`CountMode`] from `(group_by, -/// where_clauses)` matching the abci handler's -/// `validate_and_route` logic, then take Drive's plan +/// **Routing**: route the request to a [`CountMode`] with the +/// node's own routing ([`grouped_mode`]), then take Drive's plan /// ([`count_proof_plan`]). Branch by the plan: /// /// - [`CountProofPlan::PrimaryKeyCountTree`] (empty where on a @@ -229,33 +236,28 @@ pub(super) fn verify_count_query( request.document_type_name, e ), })?; + // The grouped mode the node's routing answers the request in, read over + // the clauses as the routing reads them: windows resolved, elements not + // yet keyed. + let count_mode = grouped_mode(&request, "COUNT", platform_version)?; request.where_clauses = aggregate_where_clauses( document_type, - &request.group_by, + count_mode, std::mem::take(&mut request.where_clauses), folds_entries, platform_version, )?; - // Resolve the SQL-shape `CountMode` the request implies. Same - // decision tree as `validate_and_route` in the abci handler — - // single source of truth would be nicer but the SDK can't - // depend on rs-drive-abci, and drive doesn't expose this - // helper because `validate_and_route` also folds in the - // unrelated `select` projection check. - let count_mode = resolve_count_mode(&request.group_by, &request.where_clauses)?; - // Drive's plan, the one the prover made from the same request: the // proof mode, the primary-key route or covering index, and the limit // the path query carries. A plan the verifier made apart from the // prover's would build a different path query. let plan = count_proof_plan( + &request, &document_type, &request.where_clauses, &resolved_time_ranges, count_mode, - &request.order_by_clauses, - request.limit, platform_version, )?; let contract_id = request.data_contract.id().to_buffer(); @@ -324,67 +326,6 @@ pub(super) fn verify_count_query( Ok((Some(entries), mtd.clone(), proof.clone())) } -/// Build the SQL-shape [`CountMode`] from `(group_by, -/// where_clauses)`. Mirrors the abci handler's -/// `validate_and_route` logic so the SDK side picks the same -/// mode the server would have routed to, which keeps -/// [`DriveDocumentCountQuery::detect_mode`]'s output (and the -/// proof-verification primitive) in sync end-to-end. -/// -/// Match-any semantics on the field lookups (`is_in_field` / -/// `is_range_field`) — clause ordering on the wire must not -/// affect routing, same fix as the abci handler's round-3 -/// regression. -fn resolve_count_mode( - group_by: &[String], - where_clauses: &[drive::query::WhereClause], -) -> Result { - let is_in_field = |field: &str| { - where_clauses - .iter() - .any(|wc| wc.operator == WhereOperator::In && wc.field == field) - }; - let is_range_field = |field: &str| { - where_clauses - .iter() - .any(|wc| DriveDocumentCountQuery::is_range_operator(wc.operator) && wc.field == field) - }; - let unsupported = |feature: String| drive_proof_verifier::Error::RequestError { - error: format!("{feature} (see issue #3655 for the v1 wire surface follow-ups)"), - }; - match group_by { - [] => Ok(CountMode::Aggregate), - [field] => { - if is_in_field(field) { - Ok(CountMode::GroupByIn) - } else if is_range_field(field) { - Ok(CountMode::GroupByRange) - } else { - Err(drive_proof_verifier::Error::RequestError { - error: format!( - "GROUP BY on field '{field}' which is not constrained by an `In` \ - or range where clause is not yet implemented (see issue #3655)" - ), - }) - } - } - [first, second] => { - if is_in_field(first) && is_range_field(second) { - Ok(CountMode::GroupByCompound) - } else { - Err(unsupported( - "two-field GROUP BY outside the `(In, range)` compound shape \ - is not yet implemented" - .to_string(), - )) - } - } - _ => Err(unsupported( - "GROUP BY with more than two fields is not yet implemented".to_string(), - )), - } -} - /// Wrap a single `u64` from an aggregate proof primitive /// (`AggregateCountOnRange` or `verify_primary_key_count_tree_proof`) /// as a one-element `Vec` so callers see a @@ -430,7 +371,7 @@ mod tests { use dpp::data_contract::{DataContractFactory, TokenConfiguration}; use dpp::platform_value::platform_value; use dpp::prelude::{CoreBlockHeight, DataContract, Identifier}; - use drive::query::{SelectProjection, TimeRangeSelector, WhereClause}; + use drive::query::{SelectProjection, TimeRangeSelector, WhereClause, WhereOperator}; use std::sync::Arc; const DOCUMENT_TYPE: &str = "post"; diff --git a/packages/dash-platform-queries/src/documents/document_query.rs b/packages/dash-platform-queries/src/documents/document_query.rs index 4bd5f65e2e0..4d24d4e38f3 100644 --- a/packages/dash-platform-queries/src/documents/document_query.rs +++ b/packages/dash-platform-queries/src/documents/document_query.rs @@ -273,12 +273,7 @@ impl DocumentQuery { /// the having view verifies, and every node refuses one without a grouping. pub(super) fn ensure_no_having(&self) -> Result<(), drive_proof_verifier::Error> { if !self.having.is_empty() { - return Err(drive_proof_verifier::Error::RequestError { - error: "a having clause is answered as a having-range page, which a count, sum \ - or average view cannot verify; fetch a grouped query with one as \ - DocumentHavingEntries" - .to_string(), - }); + return Err(having_page_refusal()); } Ok(()) } @@ -751,6 +746,16 @@ impl FromProof for drive_proof_verifier::types::Documents { } } +/// The refusal of a `having` clause in a count, sum or average view. +pub(super) fn having_page_refusal() -> drive_proof_verifier::Error { + drive_proof_verifier::Error::RequestError { + error: "a having clause is answered as a having-range page, which a count, sum or \ + average view cannot verify; fetch a grouped query with one as \ + DocumentHavingEntries" + .to_string(), + } +} + /// Drive's query for `resolved`, a documents select whose window selections are already /// resolved, carrying the resolution provenance `resolved_time_ranges`. The conversion cannot /// recover which equalities came from resolution, so the provenance is carried across here; diff --git a/packages/dash-platform-queries/src/documents/mod.rs b/packages/dash-platform-queries/src/documents/mod.rs index 560799913ec..a761c41cd83 100644 --- a/packages/dash-platform-queries/src/documents/mod.rs +++ b/packages/dash-platform-queries/src/documents/mod.rs @@ -1,3 +1,4 @@ +pub(crate) mod aggregate_routing; pub mod array_element_clauses; pub(crate) mod average_proof_helpers; pub mod chained_document_query; diff --git a/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs b/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs index 923759108ac..6516c2bfcad 100644 --- a/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs +++ b/packages/dash-platform-queries/src/documents/sum_proof_helpers.rs @@ -20,6 +20,7 @@ //! [`DocumentSum`]: drive_proof_verifier::DocumentSum //! [`DocumentSplitSums`]: drive_proof_verifier::DocumentSplitSums +use crate::documents::aggregate_routing::grouped_mode; use crate::documents::array_element_clauses::{ aggregate_request_where_clauses, aggregate_where_clauses, document_type_named, }; @@ -36,7 +37,7 @@ use drive::query::drive_document_sum_query::mode_detection::{ check_sum_property_against_document_type, detect_sum_mode_from_inputs, }; use drive::query::drive_document_sum_query::{DriveDocumentSumQuery, SumMode, SumProofPlan}; -use drive::query::{OrderClause, ResolvedTimeRange, SelectFunction, WhereClause, WhereOperator}; +use drive::query::{ResolvedTimeRange, SelectFunction, WhereClause}; use drive_proof_verifier::{ verify_aggregate_sum_proof, verify_carrier_aggregate_sum_proof, verify_distinct_sum_proof, verify_point_lookup_sum_proof, verify_primary_key_sum_tree_proof, SumEntry, @@ -96,58 +97,70 @@ pub(super) fn check_sum_request( )?; let (resolved, resolved_time_ranges) = request.resolved_for_checking()?; let request = &resolved; - let where_clauses = aggregate_request_where_clauses(request, folds_entries, platform_version)?; - let sum_mode = resolve_sum_mode(&request.group_by, &where_clauses)?; request.ensure_no_having()?; + let mode = grouped_mode(request, "SUM", platform_version)?; + let where_clauses = + aggregate_request_where_clauses(request, mode, folds_entries, platform_version)?; sum_proof_plan( + request, &document_type, &where_clauses, &resolved_time_ranges, - &request.select.field, - sum_mode, - &request.order_by_clauses, - request.limit, + SumMode::from(mode), platform_version, ) .map(drop) } -/// The proof plan a node makes for a proved sum of `sum_property`, made from -/// the request alone ([`DriveDocumentSumQuery::proof_plan`]): Drive resolves the -/// SQL-shape `sum_mode` into its proof mode ([`detect_sum_mode_from_inputs`]), -/// then picks the primary-key route or the covering index and the limit the -/// path query carries. A client cannot know a node's `max_query_limit`, so it -/// leaves that check to the node. +/// The proof plan a node makes for a proved sum of `request`'s select field, +/// made from the request alone and lowered to the path query its proof +/// answers. Drive resolves the SQL-shape `sum_mode` into its proof mode +/// ([`detect_sum_mode_from_inputs`]), picks the primary-key route or the +/// covering index and the limit and walk direction +/// ([`DriveDocumentSumQuery::proof_plan`]), and builds the path query +/// ([`SumProofPlan::path_query`]), which the check before sending discards +/// and the verifier's Drive call rebuilds from the plan. A client cannot know +/// a node's `max_query_limit`, so it leaves that check to the node. /// -/// `order_clauses` and `limit` are the request's, `limit` `0` when unset. -#[allow(clippy::too_many_arguments)] +/// `where_clauses` are the request's as the server reads them +/// ([`aggregate_where_clauses`]). fn sum_proof_plan<'a>( + request: &DocumentQuery, document_type: &'a DocumentTypeRef<'_>, where_clauses: &[WhereClause], resolved_time_ranges: &[ResolvedTimeRange], - sum_property: &str, sum_mode: SumMode, - order_clauses: &[OrderClause], - limit: u32, platform_version: &PlatformVersion, ) -> Result, drive_proof_verifier::Error> { let mode = detect_sum_mode_from_inputs(where_clauses, sum_mode, true, platform_version) .map_err(|e| drive_proof_verifier::Error::RequestError { error: format!("sum-mode detection failed: {e}"), })?; - DriveDocumentSumQuery::proof_plan( + let unverifiable = |e| drive_proof_verifier::Error::RequestError { + error: format!("no answer to this sum can be verified: {e}"), + }; + let plan = DriveDocumentSumQuery::proof_plan( document_type, where_clauses, resolved_time_ranges, - sum_property, + &request.select.field, mode, - order_clauses, - (limit != 0).then_some(limit), + &request.order_by_clauses, + (request.limit != 0).then_some(request.limit), None, ) - .map_err(|e| drive_proof_verifier::Error::RequestError { - error: format!("no answer to this sum can be verified: {e}"), - }) + .map_err(unverifiable)?; + plan.path_query( + request.data_contract.id().to_buffer(), + *document_type, + request.document_type_name.clone(), + where_clauses.to_vec(), + request.select.field.clone(), + false, + platform_version, + ) + .map_err(unverifiable)?; + Ok(plan) } /// Verify a SUM-shape proof and return per-branch `SumEntry`s. @@ -157,10 +170,9 @@ fn sum_proof_plan<'a>( /// so the SDK's routing matches the server's exactly. Mirrors count's /// [`super::count_proof_helpers::verify_count_query`] approach. /// -/// **Routing**: build a [`SumMode`] from `(group_by, -/// where_clauses)` matching the abci handler's `validate_and_route` -/// logic, then take Drive's plan ([`sum_proof_plan`]). Branch by the -/// plan: +/// **Routing**: route the request to a [`SumMode`] with the node's +/// own routing ([`grouped_mode`]), then take Drive's plan +/// ([`sum_proof_plan`]). Branch by the plan: /// /// - [`SumProofPlan::PrimaryKeySumTree`] (empty where on a doctype /// whose `documentsSummable` is the summed property) → @@ -218,33 +230,29 @@ pub(super) fn verify_sum_query( request.document_type_name, e ), })?; + // The grouped mode the node's routing answers the request in, read over + // the clauses as the routing reads them: windows resolved, elements not + // yet keyed. + let mode = grouped_mode(&request, "SUM", platform_version)?; request.where_clauses = aggregate_where_clauses( document_type, - &request.group_by, + mode, std::mem::take(&mut request.where_clauses), folds_entries, platform_version, )?; - // Resolve the SQL-shape `SumMode` the request implies. Same - // decision tree as `validate_and_route` in the abci handler — - // single source of truth would be nicer but the SDK can't - // depend on rs-drive-abci. - let sum_mode = resolve_sum_mode(&request.group_by, &request.where_clauses)?; - // Drive's plan, the one the prover made from the same request: the // proof mode, the primary-key route or covering index, and the limit // the path query carries. On the prove path the server refuses an // over-max limit with a typed `InvalidLimit` before producing proof // bytes, so the SDK never sees a clamped value to un-clamp. let plan = sum_proof_plan( + &request, &document_type, &request.where_clauses, &resolved_time_ranges, - &sum_property, - sum_mode, - &request.order_by_clauses, - request.limit, + SumMode::from(mode), platform_version, )?; let sum_query = |index| DriveDocumentSumQuery { @@ -311,65 +319,6 @@ pub(super) fn verify_sum_query( Ok((Some(entries), mtd.clone(), proof.clone())) } -/// Build the SQL-shape [`SumMode`] from `(group_by, where_clauses)`. -/// Mirrors [`super::count_proof_helpers::resolve_count_mode`] — -/// same SQL surface, same routing decision shape (`SumMode` is -/// structurally identical to `CountMode`). Keeping the two -/// resolvers in lock-step means a future SQL extension only has -/// to land once in count + once in sum. The average helpers resolve -/// their mode with it too, since an average routes over the same SQL -/// surface. -pub(super) fn resolve_sum_mode( - group_by: &[String], - where_clauses: &[drive::query::WhereClause], -) -> Result { - let is_in_field = |field: &str| { - where_clauses - .iter() - .any(|wc| wc.operator == WhereOperator::In && wc.field == field) - }; - let is_range_field = |field: &str| { - where_clauses.iter().any(|wc| { - drive::query::drive_document_sum_query::is_range_operator(wc.operator) - && wc.field == field - }) - }; - let unsupported = |feature: String| drive_proof_verifier::Error::RequestError { - error: format!("{feature} (see issue #3655 for the v1 wire surface follow-ups)"), - }; - match group_by { - [] => Ok(SumMode::Aggregate), - [field] => { - if is_in_field(field) { - Ok(SumMode::GroupByIn) - } else if is_range_field(field) { - Ok(SumMode::GroupByRange) - } else { - Err(drive_proof_verifier::Error::RequestError { - error: format!( - "GROUP BY on field '{field}' which is not constrained by an `In` \ - or range where clause is not yet implemented (see issue #3655)" - ), - }) - } - } - [first, second] => { - if is_in_field(first) && is_range_field(second) { - Ok(SumMode::GroupByCompound) - } else { - Err(unsupported( - "two-field GROUP BY outside the `(In, range)` compound shape \ - is not yet implemented" - .to_string(), - )) - } - } - _ => Err(unsupported( - "GROUP BY with more than two fields is not yet implemented".to_string(), - )), - } -} - /// Wrap a single `i64` from an aggregate primitive (range-aggregate /// or primary-key direct read) as a one-element `Vec` so /// call sites see a uniform shape. diff --git a/packages/rs-drive-abci/src/query/document_query/v1/dispatch/average.rs b/packages/rs-drive-abci/src/query/document_query/v1/dispatch/average.rs index f868ac9bc8a..a2a45197d78 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/dispatch/average.rs +++ b/packages/rs-drive-abci/src/query/document_query/v1/dispatch/average.rs @@ -83,12 +83,7 @@ impl Platform { )))); // `AverageMode` mirrors `CountMode` 1:1 — map across. - let avg_mode = match mode { - CountMode::Aggregate => AverageMode::Aggregate, - CountMode::GroupByIn => AverageMode::GroupByIn, - CountMode::GroupByRange => AverageMode::GroupByRange, - CountMode::GroupByCompound => AverageMode::GroupByCompound, - }; + let avg_mode = AverageMode::from(mode); let drive_request = DocumentAverageRequest { contract: contract_ref, diff --git a/packages/rs-drive-abci/src/query/document_query/v1/dispatch/sum.rs b/packages/rs-drive-abci/src/query/document_query/v1/dispatch/sum.rs index b5fc7a064d1..049e82b127c 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/dispatch/sum.rs +++ b/packages/rs-drive-abci/src/query/document_query/v1/dispatch/sum.rs @@ -83,12 +83,7 @@ impl Platform { // `SumMode` mirrors `CountMode` 1:1 — same four variants // computed via the same `compute_aggregate_mode_and_check_limit` // helper. Map across the isomorphism. - let sum_mode = match mode { - CountMode::Aggregate => SumMode::Aggregate, - CountMode::GroupByIn => SumMode::GroupByIn, - CountMode::GroupByRange => SumMode::GroupByRange, - CountMode::GroupByCompound => SumMode::GroupByCompound, - }; + let sum_mode = SumMode::from(mode); let drive_request = DocumentSumRequest { contract: contract_ref, diff --git a/packages/rs-drive-abci/src/query/document_query/v1/mod.rs b/packages/rs-drive-abci/src/query/document_query/v1/mod.rs index 6b56b26170c..53f6ae099f4 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/mod.rs +++ b/packages/rs-drive-abci/src/query/document_query/v1/mod.rs @@ -26,7 +26,6 @@ //! message-level docstring on `GetDocumentsRequestV1` in //! `platform.proto` for the full supported / rejected shape table. -mod compute_aggregate_mode_and_check_limit; mod conversions; mod dispatch; mod routing; diff --git a/packages/rs-drive-abci/src/query/document_query/v1/routing.rs b/packages/rs-drive-abci/src/query/document_query/v1/routing.rs index a5b8426fe29..de22b47a2e3 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/routing.rs +++ b/packages/rs-drive-abci/src/query/document_query/v1/routing.rs @@ -5,13 +5,11 @@ //! the routing *rules* version through the //! `compute_aggregate_mode_and_check_limit` table it calls into. -use super::compute_aggregate_mode_and_check_limit::{ - compute_aggregate_mode_and_check_limit, AggregateRouting, -}; use super::{not_yet_implemented, RoutingDecision}; use crate::error::query::QueryError; use dpp::version::PlatformVersion; use drive::error::query::QuerySyntaxError; +use drive::query::aggregate_routing::{compute_aggregate_mode_and_check_limit, AggregateRouting}; use drive::query::{HavingClause, OrderClause, SelectFunction, SelectProjection, WhereClause}; #[cfg(test)] use { @@ -152,7 +150,7 @@ pub(super) fn validate_and_route( .to_string(), )); } - match compute_aggregate_mode_and_check_limit( + match route_aggregate( select, group_by, where_clauses, @@ -197,7 +195,7 @@ pub(super) fn validate_and_route( .to_string(), )); } - match compute_aggregate_mode_and_check_limit( + match route_aggregate( select, group_by, where_clauses, @@ -258,7 +256,7 @@ pub(super) fn validate_and_route( // but the `any` shape is used here too so the routing // logic doesn't bake in an assumption that could go // stale if that validator's contract ever relaxes. - match compute_aggregate_mode_and_check_limit( + match route_aggregate( select, group_by, where_clauses, @@ -276,6 +274,38 @@ pub(super) fn validate_and_route( } } +/// Drive's routing of a `SELECT COUNT` / `SUM` / `AVG` request +/// ([`compute_aggregate_mode_and_check_limit`]), which a client runs before +/// sending too, with its refusals as the handler reports them: a query +/// syntax refusal as a query error, anything else (an unknown method +/// version) as a Drive error. +#[allow(clippy::too_many_arguments)] +fn route_aggregate( + select: &SelectProjection, + group_by: &[String], + where_clauses: &[WhereClause], + order_by: &[OrderClause], + limit: Option, + having: &[HavingClause], + function_name: &str, + platform_version: &PlatformVersion, +) -> Result { + compute_aggregate_mode_and_check_limit( + select, + group_by, + where_clauses, + order_by, + limit, + having, + function_name, + platform_version, + ) + .map_err(|error| match error { + drive::error::Error::Query(error) => QueryError::Query(error), + error => QueryError::Drive(error), + }) +} + /// The `OFFSET` gate, applied **after** routing. /// /// Offset pagination exists on exactly one path: the ranked executor, diff --git a/packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs b/packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs index aaa5c0963eb..2ef51ad121d 100644 --- a/packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs +++ b/packages/rs-drive-abci/tests/query_request_errors/index_coverage.rs @@ -67,8 +67,9 @@ fn listings(version: &PlatformVersion) -> Arc { ) } -/// A `review` whose index sums and counts `grade` per restaurant, and a `note` that counts and -/// sums nothing. +/// A `review` whose index sums and counts `grade` per restaurant, a `note` that counts and sums +/// nothing, and a `sale` whose index on `category` then `price` counts and sums `amount` over +/// price ranges. fn reviews(version: &PlatformVersion) -> Arc { contract( 32, @@ -94,6 +95,22 @@ fn reviews(version: &PlatformVersion) -> Arc { }, "required": ["name"], "additionalProperties": false + }, + "sale": { + "type": "object", + "properties": { + "category": {"type": "string", "minLength": 1, "maxLength": 59, "position": 0}, + "price": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 1}, + "amount": {"type": "integer", "minimum": 0, "maximum": 1_000_000, "position": 2} + }, + "required": ["category", "price", "amount"], + "indices": [ + {"name": "byCategoryPrice", + "properties": [{"category": "asc"}, {"price": "asc"}], + "averageable": "amount", + "rangeAverageable": true} + ], + "additionalProperties": false } }), version, @@ -144,6 +161,12 @@ async fn agree_at(version: &'static PlatformVersion) { let listing = || DocumentQuery::new(Arc::clone(&listings), "listing").expect("listing"); let review = || DocumentQuery::new(Arc::clone(&reviews), "review").expect("review"); let note = || DocumentQuery::new(Arc::clone(&reviews), "note").expect("note"); + let sale = || DocumentQuery::new(Arc::clone(&reviews), "sale").expect("sale"); + let price_above_zero = || WhereClause { + field: "price".to_string(), + operator: WhereOperator::GreaterThan, + value: Value::U64(0), + }; let price_window = || listing().with_integer_range("price", Value::U64(200)); let restaurants_in = || any_of("restaurantId", platform_value!(["a", "b"])); let categories_in = || any_of("category", platform_value!(["tools", "toys"])); @@ -237,6 +260,55 @@ async fn agree_at(version: &'static PlatformVersion) { .with_where(equal("category", Value::Text("tools".to_string()))), true, ), + // A range total reads through one prefix: no path query serves several `In` prefixes. + ( + "avg(amount) of sales in a price range under several categories", + check::, + sale() + .with_select(SelectProjection::avg("amount")) + .with_where(categories_in()) + .with_where(price_above_zero()), + false, + ), + ( + "avg(amount) of sales in a price range under one category", + check::, + sale() + .with_select(SelectProjection::avg("amount")) + .with_where(equal("category", Value::Text("tools".to_string()))) + .with_where(price_above_zero()), + true, + ), + // A total is one row and a grouping by an `In` field is bounded by the array: neither + // honors a `limit`. + ( + "count of reviews with a limit", + check::, + review() + .with_select(SelectProjection::count_star()) + .with_where(restaurants_in()) + .with_limit(1), + false, + ), + ( + "count per restaurant with a limit", + check::, + review() + .with_select(SelectProjection::count_star()) + .with_where(restaurants_in()) + .with_group_by("restaurantId") + .with_limit(1), + false, + ), + ( + "count per restaurant", + check::, + review() + .with_select(SelectProjection::count_star()) + .with_where(restaurants_in()) + .with_group_by("restaurantId"), + true, + ), // A `note` counts nothing. ( "count of notes", diff --git a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/mod.rs b/packages/rs-drive/src/query/aggregate_routing/mod.rs similarity index 80% rename from packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/mod.rs rename to packages/rs-drive/src/query/aggregate_routing/mod.rs index 4b5eb65758b..762033f2d51 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/mod.rs +++ b/packages/rs-drive/src/query/aggregate_routing/mod.rs @@ -24,17 +24,25 @@ //! which has neither path, while protocol version 14 selects v2 and //! answers both. //! -//! Lives next to the v1 query handler (the only call site today) and -//! is dispatched via the `DriveAbciDocumentQueryHelperVersions` slot -//! in `PlatformVersion`. +//! Lives in Drive, under `verify` as well as `server`, so drive-abci's v1 +//! query handler and a client's check before sending route one request +//! the same way. It is dispatched via the +//! `DriveAbciDocumentQueryHelperVersions` slot in `PlatformVersion`, the +//! query version the handler runs at. Each generation refuses with +//! Drive's `Error::Query` (an unknown version with `Error::Drive`), which +//! drive-abci reports as `QueryError::Query` (`QueryError::Drive`), the +//! errors its handler answers these refusals with at every protocol +//! version. mod v0; mod v1; mod v2; -use crate::error::query::QueryError; +use crate::error::drive::DriveError; +use crate::error::query::QuerySyntaxError; +use crate::error::Error; +use crate::query::{CountMode, HavingClause, OrderClause, SelectProjection, WhereClause}; use dpp::version::PlatformVersion; -use drive::query::{CountMode, HavingClause, OrderClause, SelectProjection, WhereClause}; /// What the helper decided a request should execute as. /// @@ -54,7 +62,7 @@ use drive::query::{CountMode, HavingClause, OrderClause, SelectProjection, Where /// disagree with it after a version bump. Routing decides *where* a /// request goes; drive decides what it means. #[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub(super) enum AggregateRouting { +pub enum AggregateRouting { /// Non-ranked aggregate: execute with this `(group_by × where)` mode. Grouped(CountMode), /// Ranked aggregate: execute through the ranked (top-k) surface. @@ -89,7 +97,7 @@ pub(super) enum AggregateRouting { /// /// Routes through `platform_version.drive_abci.query.document_query_helpers.compute_aggregate_mode_and_check_limit`. #[allow(clippy::too_many_arguments)] -pub(super) fn compute_aggregate_mode_and_check_limit( +pub fn compute_aggregate_mode_and_check_limit( select: &SelectProjection, group_by: &[String], where_clauses: &[WhereClause], @@ -98,7 +106,7 @@ pub(super) fn compute_aggregate_mode_and_check_limit( having: &[HavingClause], function_name: &str, platform_version: &PlatformVersion, -) -> Result { +) -> Result { match platform_version .drive_abci .query @@ -134,12 +142,19 @@ pub(super) fn compute_aggregate_mode_and_check_limit( having, function_name, ), - version => Err(QueryError::Drive(drive::error::Error::Drive( - drive::error::drive::DriveError::UnknownVersionMismatch { - method: "compute_aggregate_mode_and_check_limit".to_string(), - known_versions: vec![0, 1, 2], - received: version, - }, - ))), + version => Err(Error::Drive(DriveError::UnknownVersionMismatch { + method: "compute_aggregate_mode_and_check_limit".to_string(), + known_versions: vec![0, 1, 2], + received: version, + })), } } + +/// The refusal of a shape the wire carries but no node evaluates yet: a +/// capability rather than a malformed request. +fn not_yet_implemented(feature: &str) -> Error { + Error::Query(QuerySyntaxError::Unsupported(format!( + "{} is not yet implemented", + feature + ))) +} diff --git a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v0/mod.rs b/packages/rs-drive/src/query/aggregate_routing/v0/mod.rs similarity index 77% rename from packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v0/mod.rs rename to packages/rs-drive/src/query/aggregate_routing/v0/mod.rs index 9486be8ad92..8c73915cb59 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v0/mod.rs +++ b/packages/rs-drive/src/query/aggregate_routing/v0/mod.rs @@ -1,24 +1,20 @@ //! v0 of `compute_aggregate_mode_and_check_limit` — the protocol //! version 13 routing table. //! -//! Original routing table extracted verbatim from -//! `query/document_query/v1/mod.rs` so the v1 cutover is a pure code -//! move with no semantic change. See the dispatcher's module-level -//! docstring for the versioning rationale. +//! See the dispatcher's module-level docstring for the versioning +//! rationale. //! -//! The blanket `HAVING` rejection below moved in from the same place -//! for the same reason: it was an unversioned gate in -//! `validate_and_route`, and "reject every non-empty HAVING" is -//! precisely this table's behavior. Keeping it here rather than in the -//! dispatcher means an older node's routing decisions are described by -//! one function rather than two, and the ranked activation is a pure -//! version selection. +//! The blanket `HAVING` rejection below is part of this table: "reject +//! every non-empty HAVING" is precisely its behavior. Keeping it here +//! rather than in the dispatcher means an older node's routing decisions +//! are described by one function rather than two, and the ranked +//! activation is a pure version selection. +use super::not_yet_implemented; use super::AggregateRouting; -use crate::error::query::QueryError; -use crate::query::document_query::v1::not_yet_implemented; -use drive::error::query::QuerySyntaxError; -use drive::query::{CountMode, HavingClause, WhereClause, WhereOperator}; +use crate::error::query::QuerySyntaxError; +use crate::error::Error; +use crate::query::{CountMode, HavingClause, WhereClause, WhereOperator}; pub(super) fn compute_aggregate_mode_and_check_limit_v0( group_by: &[String], @@ -26,7 +22,7 @@ pub(super) fn compute_aggregate_mode_and_check_limit_v0( limit: Option, having: &[HavingClause], function_name: &str, -) -> Result { +) -> Result { // v0 has no ranked surface: every non-empty HAVING is refused, // whatever its shape. The wording signals future capability // rather than a malformed request — a client can keep the @@ -106,7 +102,7 @@ pub(super) fn compute_aggregate_mode_and_check_limit_v0( filtered them out" ), }; - return Err(QueryError::Query(QuerySyntaxError::InvalidLimit(reason))); + return Err(Error::Query(QuerySyntaxError::InvalidLimit(reason))); } Ok(AggregateRouting::Grouped(mode)) diff --git a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v1/mod.rs b/packages/rs-drive/src/query/aggregate_routing/v1/mod.rs similarity index 80% rename from packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v1/mod.rs rename to packages/rs-drive/src/query/aggregate_routing/v1/mod.rs index 11eb264b1c9..5d1b4a5c389 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v1/mod.rs +++ b/packages/rs-drive/src/query/aggregate_routing/v1/mod.rs @@ -23,10 +23,10 @@ //! and its index picker, and is itself versioned there. //! //! Re-validating any of that here would create two sources of truth -//! for one grammar: the SDK's proof helpers call drive's validator -//! directly (no abci in the path), so a routing-layer copy that -//! drifted would make the server accept or reject requests the client -//! disagrees about. The checks below are the minimum needed to *route*: +//! for one grammar: the ranked proof helpers call that validator +//! directly, so a routing-layer copy that drifted would make the server +//! accept or reject requests the client disagrees about. The checks +//! below are the minimum needed to *route*: //! //! 1. **`group_by` is non-empty.** A ranking ranks groups; with no //! grouping there is exactly one implicit group and `ORDER BY @@ -44,15 +44,15 @@ //! //! Note what is *not* checked: the limit's bounds, its presence at //! all, `where` / `start_at` presence, `offset`'s value. Those all -//! reach drive and come back as `Error::Query(...)`, which the ranked -//! dispatcher maps onto `QueryError::Query` — a client-visible -//! rejection, not an internal error. +//! reach the ranked executor and come back as `Error::Query(...)`, which +//! drive-abci's ranked dispatcher maps onto `QueryError::Query` — a +//! client-visible rejection, not an internal error. +use super::not_yet_implemented; use super::v0::compute_aggregate_mode_and_check_limit_v0; use super::AggregateRouting; -use crate::error::query::QueryError; -use crate::query::document_query::v1::not_yet_implemented; -use drive::query::{ +use crate::error::Error; +use crate::query::{ HavingClause, OrderClause, SelectProjection, WhereClause, RANKED_COUNT_ORDER_KEY, }; @@ -60,13 +60,12 @@ use drive::query::{ /// the projection's own field for `SUM(f)` / `AVG(f)`, and the /// [`RANKED_COUNT_ORDER_KEY`] sentinel for `COUNT(*)`. /// -/// Mirrors drive's private `ranked_order_key`. The duplication is -/// deliberate and safe in a way the rest of the grammar would not be: -/// this is a *name*, pinned by a shared public constant, not a rule. -/// A drift would be a compile-time constant mismatch, not a silent -/// semantic disagreement — and calling into drive here would mean -/// building a `DocumentRankedMode` before the contract has even been -/// fetched. +/// Mirrors `drive_document_ranked_query::mode_detection::ranked_order_key` +/// for the shapes this table routes. The duplication is deliberate and +/// safe in a way the rest of the grammar would not be: this is a *name*, +/// pinned by a shared public constant, not a rule. It stays separate +/// because the two differ for a `SUM` or `AVG` select without a field, +/// and this table is selected by a protocol version a network runs. fn aggregate_order_key(select: &SelectProjection) -> &str { if select.field.is_empty() { RANKED_COUNT_ORDER_KEY @@ -83,7 +82,7 @@ pub(super) fn compute_aggregate_mode_and_check_limit_v1( limit: Option, having: &[HavingClause], function_name: &str, -) -> Result { +) -> Result { let orders_by_the_aggregate = match order_by { [only] => only.field == aggregate_order_key(select), _ => false, diff --git a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v2/mod.rs b/packages/rs-drive/src/query/aggregate_routing/v2/mod.rs similarity index 94% rename from packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v2/mod.rs rename to packages/rs-drive/src/query/aggregate_routing/v2/mod.rs index 6f90620bb15..fa6ccd4cbcc 100644 --- a/packages/rs-drive-abci/src/query/document_query/v1/compute_aggregate_mode_and_check_limit/v2/mod.rs +++ b/packages/rs-drive/src/query/aggregate_routing/v2/mod.rs @@ -24,11 +24,11 @@ //! global aggregate produces one row, and bounding it is a client-side //! comparison, not a query. +use super::not_yet_implemented; use super::v1::compute_aggregate_mode_and_check_limit_v1; use super::AggregateRouting; -use crate::error::query::QueryError; -use crate::query::document_query::v1::not_yet_implemented; -use drive::query::{HavingClause, OrderClause, SelectProjection, WhereClause, WhereOperator}; +use crate::error::Error; +use crate::query::{HavingClause, OrderClause, SelectProjection, WhereClause, WhereOperator}; use std::borrow::Cow; #[allow(clippy::too_many_arguments)] @@ -40,7 +40,7 @@ pub(super) fn compute_aggregate_mode_and_check_limit_v2( limit: Option, having: &[HavingClause], function_name: &str, -) -> Result { +) -> Result { if !having.is_empty() && !group_by.is_empty() { return match having { [_single] => Ok(AggregateRouting::HavingRange), diff --git a/packages/rs-drive/src/query/drive_document_average_query/mod.rs b/packages/rs-drive/src/query/drive_document_average_query/mod.rs index 02014bc68f6..61b7fd68720 100644 --- a/packages/rs-drive/src/query/drive_document_average_query/mod.rs +++ b/packages/rs-drive/src/query/drive_document_average_query/mod.rs @@ -26,6 +26,8 @@ //! [`crate::query::drive_document_count_and_sum_query`] for the //! no-prove perf / atomicity contract. +use crate::query::CountMode; + #[cfg(feature = "server")] pub mod drive_dispatcher; // The request-only plan of a proved average, shared by the server's @@ -65,6 +67,19 @@ pub enum AverageMode { GroupByCompound, } +/// The routing ([`crate::query::aggregate_routing`]) decides one SQL-shape +/// mode for counts, sums and averages; an average reads it as its own. +impl From for AverageMode { + fn from(mode: CountMode) -> Self { + match mode { + CountMode::Aggregate => AverageMode::Aggregate, + CountMode::GroupByIn => AverageMode::GroupByIn, + CountMode::GroupByRange => AverageMode::GroupByRange, + CountMode::GroupByCompound => AverageMode::GroupByCompound, + } + } +} + /// A single per-key average entry. Carries BOTH count and sum so the /// client can divide; the server intentionally doesn't pre-divide /// (see the module docstring). diff --git a/packages/rs-drive/src/query/drive_document_count_query/execute_point_lookup.rs b/packages/rs-drive/src/query/drive_document_count_query/execute_point_lookup.rs index 1cfd5ee59f8..6bcaf92045a 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/execute_point_lookup.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/execute_point_lookup.rs @@ -132,9 +132,7 @@ impl DriveDocumentCountQuery<'_> { // `.unwrap()` on it: `CostContext::unwrap` is infallible (it just // drops the cost field), but the visual pattern collides with // `Option/Result::unwrap` and makes review noisier. Cost is - // discarded here because the per-mode dispatcher in - // `drive_dispatcher` wraps these executors with its own fee - // accounting. + // discarded here as the dispatcher's proof executor discards it. let CostContext { value, cost: _ } = drive.grove.get_proved_path_query( &path_query, None, diff --git a/packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs b/packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs index 1437e19e9c6..8ef2776ad38 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/executors/proof.rs @@ -1,20 +1,21 @@ //! Proof executor for every proved count mode //! ([`super::super::DocumentCountMode::PointLookupProof`], `RangeProof`, -//! `RangeDistinctProof` and `RangeAggregateCarrierProof`): it proves what the -//! request's [`CountProofPlan`] reads. The SDK's verifier rebuilds the path -//! query from the same plan. +//! `RangeDistinctProof` and `RangeAggregateCarrierProof`): it proves the +//! path query the request's [`CountProofPlan`] lowers to. A client lowers +//! the same plan before sending, and the verify method its plan names +//! rebuilds the path query with the same builders. use super::super::super::conditions::WhereClause; -use super::super::{CountProofPlan, DriveDocumentCountQuery}; +use super::super::CountProofPlan; use crate::drive::Drive; use crate::error::Error; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; use dpp::data_contract::document_type::DocumentTypeRef; use dpp::version::PlatformVersion; use grovedb::TransactionArg; +use grovedb_costs::CostContext; impl Drive { - /// Proof of what `plan` reads: + /// Proof of what `plan` reads ([`CountProofPlan::path_query`]): /// /// - the primary-key count tree: one merk path proof, O(log n) bytes; /// - a point lookup: the matched branches' count trees, whose @@ -25,7 +26,6 @@ impl Drive { /// the plan's limit of them; /// - a carrier: one aggregate per outer `In` value or outer-range match /// (grovedb's carrier-subquery composition). - /// #[allow(clippy::too_many_arguments)] pub(crate) fn execute_document_count_proof( &self, @@ -37,60 +37,19 @@ impl Drive { transaction: TransactionArg, platform_version: &PlatformVersion, ) -> Result, Error> { - // The index-reading arms each move the query parts into the query - // they prove. - let count_query = |index| DriveDocumentCountQuery { - document_type, + let path_query = plan.path_query( contract_id, + document_type, document_type_name, - index, where_clauses, - }; - match plan { - CountProofPlan::PrimaryKeyCountTree => { - let path_query = DriveDocumentCountQuery::primary_key_count_tree_path_query( - contract_id, - document_type.name(), - ); - self.grove - .get_proved_path_query( - &path_query, - None, - transaction, - &platform_version.drive.grove_version, - ) - .unwrap() - .map_err(|e| Error::GroveDB(Box::new(e))) - } - CountProofPlan::PointLookup(index) => count_query(index) - .execute_point_lookup_count_with_proof(self, transaction, platform_version), - CountProofPlan::Range(index) => count_query(index).execute_aggregate_count_with_proof( - self, - transaction, - platform_version, - ), - CountProofPlan::RangeDistinct { - index, - limit, - left_to_right, - } => count_query(index).execute_distinct_count_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ), - CountProofPlan::RangeAggregateCarrier { - index, - limit, - left_to_right, - } => count_query(index).execute_carrier_aggregate_count_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ), - } + platform_version, + )?; + let CostContext { value, cost: _ } = self.grove.get_proved_path_query( + &path_query, + None, + transaction, + &platform_version.drive.grove_version, + ); + value.map_err(|e| Error::GroveDB(Box::new(e))) } } diff --git a/packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs b/packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs index fff42587445..0b7677dfc15 100644 --- a/packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs +++ b/packages/rs-drive/src/query/drive_document_count_query/proof_plan.rs @@ -14,6 +14,8 @@ use crate::error::Error; use crate::query::{OrderClause, ResolvedTimeRange, WhereClause}; use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; use dpp::data_contract::document_type::{DocumentTypeRef, Index}; +use dpp::version::PlatformVersion; +use grovedb::PathQuery; /// What a proved count reads, decided from its request alone. #[derive(Debug, Clone, Copy, PartialEq)] @@ -181,3 +183,86 @@ impl DriveDocumentCountQuery<'_> { } } } + +impl CountProofPlan<'_> { + /// The path query a proof of this plan answers. The server proves it + /// (`Drive::execute_document_count_proof`), and a + /// client builds it from the same plan before sending and before it + /// verifies an answer, so a request whose path query cannot be built is + /// refused in the server's words. A `summableOffCountIndex` index counts + /// its documents through its range sums, so its range proofs read the sum + /// surface's path queries. + /// + /// The other arguments are the request's, as + /// [`DriveDocumentCountQuery::proof_plan`] read them. + pub fn path_query( + &self, + contract_id: [u8; 32], + document_type: DocumentTypeRef, + document_type_name: String, + where_clauses: Vec, + platform_version: &PlatformVersion, + ) -> Result { + let count_query = |index| DriveDocumentCountQuery { + document_type, + contract_id, + document_type_name, + index, + where_clauses, + }; + match *self { + CountProofPlan::PrimaryKeyCountTree => { + Ok(DriveDocumentCountQuery::primary_key_count_tree_path_query( + contract_id, + document_type.name(), + )) + } + CountProofPlan::PointLookup(index) => { + count_query(index).point_lookup_count_path_query(platform_version) + } + CountProofPlan::Range(index) => { + let query = count_query(index); + match query.counter_sums_query() { + Some(sums) => sums.aggregate_sum_path_query(platform_version), + None => query.aggregate_count_path_query(platform_version), + } + } + CountProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => { + let query = count_query(index); + match query.counter_sums_query() { + Some(sums) => { + sums.distinct_sum_path_query(Some(limit), left_to_right, platform_version) + } + None => query.distinct_count_path_query( + Some(limit), + left_to_right, + platform_version, + ), + } + } + CountProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => { + let query = count_query(index); + match query.counter_sums_query() { + Some(sums) => sums.carrier_aggregate_sum_path_query( + limit, + left_to_right, + platform_version, + ), + None => query.carrier_aggregate_count_path_query( + limit, + left_to_right, + platform_version, + ), + } + } + } + } +} diff --git a/packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs b/packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs index fb2a6b46225..56ee9e0fcb8 100644 --- a/packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs +++ b/packages/rs-drive/src/query/drive_document_sum_query/executors/proof.rs @@ -1,20 +1,21 @@ //! Proof executor for every proved sum mode //! ([`super::super::DocumentSumMode::PointLookupProof`], `RangeProof`, //! `RangeDistinctProof` and `RangeAggregateCarrierProof`) and every proved -//! average: it proves what the request's [`SumProofPlan`] reads. The SDK's -//! verifiers rebuild the path query from the same plan. +//! average: it proves the path query the request's [`SumProofPlan`] lowers +//! to. A client lowers the same plan before sending, and the verify method +//! its plan names rebuilds the path query with the same builders. -use super::super::{DriveDocumentSumQuery, SumProofPlan}; +use super::super::SumProofPlan; use crate::drive::Drive; use crate::error::Error; use crate::query::WhereClause; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; use dpp::data_contract::document_type::DocumentTypeRef; use dpp::version::PlatformVersion; use grovedb::TransactionArg; +use grovedb_costs::CostContext; impl Drive { - /// Proof of what `plan` reads: + /// Proof of what `plan` reads ([`SumProofPlan::path_query`]): /// /// - the primary-key sum tree: one merk path proof; /// - a point lookup: the matched branches' sum-bearing elements; @@ -26,10 +27,7 @@ impl Drive { /// - a carrier: one aggregate per outer `In` value or outer-range match, /// with `with_counts` a `(count, sum)` pair each. /// - /// `with_counts` is whether the request is an average, whose range and - /// carrier proofs read each element's count beside its sum; its point - /// lookups and distinct walks read the count-sum-bearing elements the - /// index's terminators already hold. + /// `with_counts` is whether the request is an average. #[allow(clippy::too_many_arguments)] pub(crate) fn execute_document_sum_proof( &self, @@ -43,75 +41,21 @@ impl Drive { transaction: TransactionArg, platform_version: &PlatformVersion, ) -> Result, Error> { - // The index-reading arms each move the query parts into the query - // they prove. - let sum_query = |index| DriveDocumentSumQuery { - document_type, + let path_query = plan.path_query( contract_id, + document_type, document_type_name, - index, where_clauses, sum_property, - }; - match plan { - SumProofPlan::PrimaryKeySumTree => { - let path_query = DriveDocumentSumQuery::primary_key_sum_path_query( - contract_id, - document_type.name(), - ); - self.grove - .get_proved_path_query( - &path_query, - None, - transaction, - &platform_version.drive.grove_version, - ) - .unwrap() - .map_err(|e| Error::GroveDB(Box::new(e))) - } - SumProofPlan::PointLookup(index) => sum_query(index) - .execute_point_lookup_sum_with_proof(self, transaction, platform_version), - SumProofPlan::Range(index) if with_counts => sum_query(index) - .execute_aggregate_count_and_sum_with_proof(self, transaction, platform_version), - SumProofPlan::Range(index) => sum_query(index).execute_aggregate_sum_with_proof( - self, - transaction, - platform_version, - ), - SumProofPlan::RangeDistinct { - index, - limit, - left_to_right, - } => sum_query(index).execute_distinct_sum_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ), - SumProofPlan::RangeAggregateCarrier { - index, - limit, - left_to_right, - } if with_counts => sum_query(index) - .execute_carrier_aggregate_count_and_sum_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ), - SumProofPlan::RangeAggregateCarrier { - index, - limit, - left_to_right, - } => sum_query(index).execute_carrier_aggregate_sum_with_proof( - self, - limit, - left_to_right, - transaction, - platform_version, - ), - } + with_counts, + platform_version, + )?; + let CostContext { value, cost: _ } = self.grove.get_proved_path_query( + &path_query, + None, + transaction, + &platform_version.drive.grove_version, + ); + value.map_err(|e| Error::GroveDB(Box::new(e))) } } diff --git a/packages/rs-drive/src/query/drive_document_sum_query/mod.rs b/packages/rs-drive/src/query/drive_document_sum_query/mod.rs index 23c410c6015..6afae30fb44 100644 --- a/packages/rs-drive/src/query/drive_document_sum_query/mod.rs +++ b/packages/rs-drive/src/query/drive_document_sum_query/mod.rs @@ -63,7 +63,7 @@ mod tests; #[cfg(feature = "server")] use crate::query::ResolvedTimeRange; #[cfg(any(feature = "server", feature = "verify"))] -use crate::query::{WhereClause, WhereOperator}; +use crate::query::{CountMode, WhereClause, WhereOperator}; #[cfg(any(feature = "server", feature = "verify"))] use dpp::data_contract::document_type::{DocumentTypeRef, Index}; @@ -114,6 +114,19 @@ pub enum SumMode { GroupByCompound, } +/// The routing ([`crate::query::aggregate_routing`]) decides one SQL-shape +/// mode for counts, sums and averages; a sum reads it as its own. +impl From for SumMode { + fn from(mode: CountMode) -> Self { + match mode { + CountMode::Aggregate => SumMode::Aggregate, + CountMode::GroupByIn => SumMode::GroupByIn, + CountMode::GroupByRange => SumMode::GroupByRange, + CountMode::GroupByCompound => SumMode::GroupByCompound, + } + } +} + /// The lower-level routing decision the dispatcher reaches after /// detecting the query's shape. Parallels count's `DocumentCountMode`. /// diff --git a/packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs b/packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs index a1dfd856788..cd2a3086a03 100644 --- a/packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs +++ b/packages/rs-drive/src/query/drive_document_sum_query/proof_plan.rs @@ -28,6 +28,8 @@ use crate::error::Error; use crate::query::{OrderClause, ResolvedTimeRange, WhereClause}; use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; use dpp::data_contract::document_type::{DocumentTypeRef, Index}; +use dpp::version::PlatformVersion; +use grovedb::PathQuery; /// What a proved sum or average reads, decided from its request alone. #[derive(Debug, Clone, Copy, PartialEq)] @@ -224,3 +226,81 @@ impl DriveDocumentSumQuery<'_> { } } } + +impl SumProofPlan<'_> { + /// The path query a proof of this plan answers. The server proves it + /// (`Drive::execute_document_sum_proof`), and a client builds it from the + /// same plan before sending and before it verifies an answer, so a + /// request whose path query cannot be built is refused in the server's + /// words. + /// + /// `with_counts` is whether the request is an average, whose range and + /// carrier proofs read each element's count beside its sum; its point + /// lookups and distinct walks read the count-sum-bearing elements the + /// index's terminators already hold. The other arguments are the + /// request's, as the planner read them. + #[allow(clippy::too_many_arguments)] + pub fn path_query( + &self, + contract_id: [u8; 32], + document_type: DocumentTypeRef, + document_type_name: String, + where_clauses: Vec, + sum_property: String, + with_counts: bool, + platform_version: &PlatformVersion, + ) -> Result { + let sum_query = |index| DriveDocumentSumQuery { + document_type, + contract_id, + document_type_name, + index, + where_clauses, + sum_property, + }; + match *self { + SumProofPlan::PrimaryKeySumTree => { + Ok(DriveDocumentSumQuery::primary_key_sum_path_query( + contract_id, + document_type.name(), + )) + } + SumProofPlan::PointLookup(index) => { + sum_query(index).point_lookup_sum_path_query(platform_version) + } + SumProofPlan::Range(index) if with_counts => { + sum_query(index).aggregate_count_and_sum_path_query(platform_version) + } + SumProofPlan::Range(index) => { + sum_query(index).aggregate_sum_path_query(platform_version) + } + SumProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => sum_query(index).distinct_sum_path_query( + Some(limit), + left_to_right, + platform_version, + ), + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } if with_counts => sum_query(index).carrier_aggregate_count_and_sum_path_query( + limit, + left_to_right, + platform_version, + ), + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => sum_query(index).carrier_aggregate_sum_path_query( + limit, + left_to_right, + platform_version, + ), + } + } +} diff --git a/packages/rs-drive/src/query/mod.rs b/packages/rs-drive/src/query/mod.rs index 6ca8eac8394..b9ec0f47b1e 100644 --- a/packages/rs-drive/src/query/mod.rs +++ b/packages/rs-drive/src/query/mod.rs @@ -280,6 +280,12 @@ pub mod filter; #[cfg(any(feature = "server", feature = "verify"))] pub mod token_status_drive_query; +/// How a `SELECT COUNT` / `SUM` / `AVG` request executes — one of the +/// grouped modes, ranked or having-range — and the grouped modes' limit +/// contract, decided from the request's shape alone. +#[cfg(any(feature = "server", feature = "verify"))] +pub mod aggregate_routing; + /// A query to count documents using CountTree elements #[cfg(any(feature = "server", feature = "verify"))] pub mod drive_document_count_query; @@ -4166,6 +4172,9 @@ pub(crate) mod unsigned_index_key_order_tests; #[cfg(all(test, feature = "server"))] mod window_selection_cardinality_tests; +#[cfg(all(test, feature = "server"))] +mod proof_plan_equivalence_tests; + #[cfg(feature = "server")] #[cfg(test)] mod tests { diff --git a/packages/rs-drive/src/query/proof_plan_equivalence_tests.rs b/packages/rs-drive/src/query/proof_plan_equivalence_tests.rs new file mode 100644 index 00000000000..cba825d9984 --- /dev/null +++ b/packages/rs-drive/src/query/proof_plan_equivalence_tests.rs @@ -0,0 +1,586 @@ +//! A proved count, sum or average is planned from its request alone +//! ([`CountProofPlan`], [`SumProofPlan`]) and the dispatcher proves the path +//! query the plan lowers to. These tests pin the dispatcher's answer — the +//! proof, or the refusal — for every request of a matrix over a populated +//! document type, to the answer of the per-mode `execute_*_with_proof` method +//! of the query object the plan names, and check the matrix reaches every +//! plan. The fixture has no `summableOffCountIndex` index; the count range +//! proofs that read such an index through its sums are proved through the +//! dispatcher and verified in `summable_off_count_index_e2e_tests`. + +use crate::config::DriveConfig; +use crate::drive::Drive; +use crate::query::drive_document_average_query::{ + AverageMode, DocumentAverageRequest, DocumentAverageResponse, +}; +use crate::query::drive_document_sum_query::mode_detection::detect_sum_mode_from_inputs; +use crate::query::drive_document_sum_query::{ + DocumentSumRequest, DocumentSumResponse, DriveDocumentSumQuery, SumMode, SumProofPlan, +}; +use crate::query::{ + validate_and_canonicalize_where_clauses, CountMode, CountProofPlan, DocumentCountRequest, + DocumentCountResponse, DriveDocumentCountQuery, OrderClause, WhereClause, WhereOperator, +}; +use crate::util::object_size_info::DocumentInfo::DocumentRefInfo; +use crate::util::object_size_info::{DocumentAndContractInfo, OwnedDocumentInfo}; +use crate::util::storage_flags::StorageFlags; +use crate::util::test_helpers::setup::setup_drive_with_initial_state_structure; +use dpp::block::block_info::BlockInfo; +use dpp::data_contract::accessors::v0::DataContractV0Getters; +use dpp::data_contract::document_type::DocumentTypeRef; +use dpp::data_contract::document_type::Index; +use dpp::data_contract::DataContractFactory; +use dpp::document::{Document, DocumentV0}; +use dpp::platform_value::{platform_value, Identifier, Value}; +use dpp::prelude::DataContract; +use dpp::version::PlatformVersion; +use std::collections::{BTreeMap, BTreeSet}; + +/// A `widget` type that counts and sums its documents by `amount`, with +/// brand and brand-and-colour indexes that count and sum over ranges, and a +/// colour index that only counts. +fn widget_contract() -> DataContract { + let schemas = platform_value!({"widget": { + "type": "object", + "documentsCountable": true, + "documentsSummable": "amount", + "properties": { + "brand": {"type": "string", "position": 0, "maxLength": 32}, + "color": {"type": "string", "position": 1, "maxLength": 32}, + "amount": {"type": "integer", "position": 2, "minimum": 0, "maximum": 1000} + }, + "required": ["brand", "color", "amount"], + "indices": [ + {"name": "byBrand", "properties": [{"brand": "asc"}], + "summable": "amount", "rangeSummable": true, + "countable": "countable", "rangeCountable": true}, + {"name": "byBrandColor", "properties": [{"brand": "asc"}, {"color": "asc"}], + "summable": "amount", "rangeSummable": true, + "countable": "countable", "rangeCountable": true}, + {"name": "byColor", "properties": [{"color": "asc"}], + "countable": "countable"} + ], + "additionalProperties": false + }}); + DataContractFactory::new(PlatformVersion::latest().protocol_version) + .expect("factory") + .create_with_value_config(Identifier::from([41u8; 32]), 0, schemas, None, None) + .expect("the widget contract is well-formed") + .data_contract_owned() +} + +fn populated_drive(contract: &DataContract, platform_version: &PlatformVersion) -> Drive { + let drive = setup_drive_with_initial_state_structure(Some(platform_version)); + drive + .apply_contract( + contract, + BlockInfo::default(), + true, + StorageFlags::optional_default_as_cow(), + None, + platform_version, + ) + .expect("apply the widget contract"); + let document_type = contract.document_type_for_name("widget").expect("widget"); + let rows = [ + ("a", "red", 3u64), + ("a", "zinc", 5), + ("b", "navy", 7), + ("b", "red", 11), + ("c", "olive", 17), + ("d", "plum", 23), + ]; + for (i, (brand, color, amount)) in rows.into_iter().enumerate() { + let document: Document = DocumentV0 { + id: Identifier::from([i as u8 + 1; 32]), + owner_id: Identifier::from([0u8; 32]), + properties: BTreeMap::from([ + ("brand".to_string(), Value::Text(brand.to_string())), + ("color".to_string(), Value::Text(color.to_string())), + ("amount".to_string(), Value::U64(amount)), + ]), + ..Default::default() + } + .into(); + drive + .add_document_for_contract( + DocumentAndContractInfo { + owned_document_info: OwnedDocumentInfo { + document_info: DocumentRefInfo(( + &document, + StorageFlags::optional_default_as_cow(), + )), + owner_id: None, + }, + contract, + document_type, + }, + false, + BlockInfo::default(), + true, + None, + platform_version, + None, + ) + .expect("insert a widget"); + } + drive +} + +fn clause(field: &str, operator: WhereOperator, value: Value) -> WhereClause { + WhereClause { + field: field.to_string(), + operator, + value, + } +} + +/// Where shapes across every proof mode: none, equalities, an `In`, ranges +/// with and without an `In` or a second range. +fn shapes() -> Vec> { + let text = |s: &str| Value::Text(s.to_string()); + vec![ + vec![], + vec![clause("brand", WhereOperator::Equal, text("a"))], + vec![clause( + "brand", + WhereOperator::In, + platform_value!(["a", "b"]), + )], + vec![clause("brand", WhereOperator::GreaterThan, text("a"))], + vec![ + clause("brand", WhereOperator::In, platform_value!(["a", "b"])), + clause("color", WhereOperator::GreaterThan, text("m")), + ], + vec![ + clause("brand", WhereOperator::GreaterThan, text("a")), + clause("color", WhereOperator::GreaterThan, text("m")), + ], + vec![ + clause("brand", WhereOperator::Equal, text("a")), + clause("color", WhereOperator::GreaterThan, text("m")), + ], + vec![clause("color", WhereOperator::Equal, text("red"))], + ] +} + +const MODES: [CountMode; 4] = [ + CountMode::Aggregate, + CountMode::GroupByIn, + CountMode::GroupByRange, + CountMode::GroupByCompound, +]; + +fn orders() -> [Vec; 2] { + [ + vec![], + vec![OrderClause { + field: "brand".to_string(), + ascending: false, + }], + ] +} + +fn count_query<'a>( + contract: &DataContract, + document_type: DocumentTypeRef<'a>, + where_clauses: &[WhereClause], + index: &'a Index, +) -> DriveDocumentCountQuery<'a> { + DriveDocumentCountQuery { + document_type, + contract_id: contract.id().to_buffer(), + document_type_name: "widget".to_string(), + index, + where_clauses: where_clauses.to_vec(), + } +} + +/// The answer, proof or refusal, a proved count gets from the per-mode +/// method its plan names, and the plan's variant. +#[allow(clippy::too_many_arguments)] +fn count_by_mode( + drive: &Drive, + contract: &DataContract, + document_type: DocumentTypeRef, + where_clauses: &[WhereClause], + mode: CountMode, + order_clauses: &[OrderClause], + limit: Option, + config: &DriveConfig, + platform_version: &PlatformVersion, +) -> Result<(Vec, &'static str), String> { + let canonical = + validate_and_canonicalize_where_clauses(where_clauses.to_vec(), platform_version) + .map_err(|e| format!("{e:?}"))?; + let proof_mode = + DriveDocumentCountQuery::detect_mode_versioned(&canonical, mode, true, platform_version) + .map_err(|e| format!("{:?}", crate::error::Error::Query(e)))?; + let plan = DriveDocumentCountQuery::proof_plan( + &document_type, + &canonical, + &[], + proof_mode, + order_clauses, + limit, + Some(config.max_query_limit), + ) + .map_err(|e| format!("{e:?}"))?; + let query = |index| count_query(contract, document_type, &canonical, index); + let (proof, variant) = match plan { + CountProofPlan::PrimaryKeyCountTree => ( + drive + .grove + .get_proved_path_query( + &DriveDocumentCountQuery::primary_key_count_tree_path_query( + contract.id().to_buffer(), + "widget", + ), + None, + None, + &platform_version.drive.grove_version, + ) + .unwrap() + .map_err(|e| crate::error::Error::GroveDB(Box::new(e))), + "primary key", + ), + CountProofPlan::PointLookup(index) => ( + query(index).execute_point_lookup_count_with_proof(drive, None, platform_version), + "point lookup", + ), + CountProofPlan::Range(index) => ( + query(index).execute_aggregate_count_with_proof(drive, None, platform_version), + "range", + ), + CountProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => ( + query(index).execute_distinct_count_with_proof( + drive, + limit, + left_to_right, + None, + platform_version, + ), + "distinct", + ), + CountProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => ( + query(index).execute_carrier_aggregate_count_with_proof( + drive, + limit, + left_to_right, + None, + platform_version, + ), + "carrier", + ), + }; + proof + .map(|proof| (proof, variant)) + .map_err(|e| format!("{e:?}")) +} + +const EVERY_PLAN: [&str; 5] = [ + "primary key", + "point lookup", + "range", + "distinct", + "carrier", +]; + +#[test] +fn should_prove_a_count_plan_as_its_mode_proves_its_index() { + let platform_version = PlatformVersion::latest(); + let contract = widget_contract(); + let drive = populated_drive(&contract, platform_version); + let document_type = contract.document_type_for_name("widget").expect("widget"); + let config = DriveConfig::default(); + let mut reached = BTreeSet::new(); + for where_clauses in shapes() { + for mode in MODES { + for limit in [None, Some(3u32)] { + for order_clauses in orders() { + let dispatched = match drive.execute_document_count_request( + DocumentCountRequest { + contract: &contract, + document_type, + where_clauses: where_clauses.clone(), + resolved_time_ranges: vec![], + order_clauses: order_clauses.clone(), + mode, + limit, + prove: true, + drive_config: &config, + }, + None, + platform_version, + ) { + Ok(DocumentCountResponse::Proof(proof)) => Ok(proof), + Ok(other) => panic!("a proved count answered {other:?}"), + Err(e) => Err(format!("{e:?}")), + }; + let by_mode = count_by_mode( + &drive, + &contract, + document_type, + &where_clauses, + mode, + &order_clauses, + limit, + &config, + platform_version, + ); + if let Ok((_, variant)) = &by_mode { + reached.insert(*variant); + } + assert_eq!( + dispatched, + by_mode.map(|(proof, _)| proof), + "{where_clauses:?} {mode:?} {limit:?} {order_clauses:?}" + ); + } + } + } + } + assert_eq!(reached, BTreeSet::from(EVERY_PLAN)); +} + +/// The answer, proof or refusal, a proved sum or average gets from the +/// per-mode method its plan names, and the plan's variant; `with_counts` for +/// an average. +fn sum_plan_by_mode( + drive: &Drive, + contract: &DataContract, + document_type: DocumentTypeRef, + where_clauses: &[WhereClause], + plan: SumProofPlan, + with_counts: bool, + platform_version: &PlatformVersion, +) -> Result<(Vec, &'static str), crate::error::Error> { + let query = |index| DriveDocumentSumQuery { + document_type, + contract_id: contract.id().to_buffer(), + document_type_name: "widget".to_string(), + index, + where_clauses: where_clauses.to_vec(), + sum_property: "amount".to_string(), + }; + let (proof, variant) = match plan { + SumProofPlan::PrimaryKeySumTree => ( + drive + .grove + .get_proved_path_query( + &DriveDocumentSumQuery::primary_key_sum_path_query( + contract.id().to_buffer(), + "widget", + ), + None, + None, + &platform_version.drive.grove_version, + ) + .unwrap() + .map_err(|e| crate::error::Error::GroveDB(Box::new(e))), + "primary key", + ), + SumProofPlan::PointLookup(index) => ( + query(index).execute_point_lookup_sum_with_proof(drive, None, platform_version), + "point lookup", + ), + SumProofPlan::Range(index) if with_counts => ( + query(index).execute_aggregate_count_and_sum_with_proof(drive, None, platform_version), + "range", + ), + SumProofPlan::Range(index) => ( + query(index).execute_aggregate_sum_with_proof(drive, None, platform_version), + "range", + ), + SumProofPlan::RangeDistinct { + index, + limit, + left_to_right, + } => ( + query(index).execute_distinct_sum_with_proof( + drive, + limit, + left_to_right, + None, + platform_version, + ), + "distinct", + ), + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } if with_counts => ( + query(index).execute_carrier_aggregate_count_and_sum_with_proof( + drive, + limit, + left_to_right, + None, + platform_version, + ), + "carrier", + ), + SumProofPlan::RangeAggregateCarrier { + index, + limit, + left_to_right, + } => ( + query(index).execute_carrier_aggregate_sum_with_proof( + drive, + limit, + left_to_right, + None, + platform_version, + ), + "carrier", + ), + }; + proof.map(|proof| (proof, variant)) +} + +#[test] +fn should_prove_a_sum_or_average_plan_as_its_mode_proves_its_index() { + let platform_version = PlatformVersion::latest(); + let contract = widget_contract(); + let drive = populated_drive(&contract, platform_version); + let document_type = contract.document_type_for_name("widget").expect("widget"); + let config = DriveConfig::default(); + let refusal = |e: crate::error::Error| format!("{e:?}"); + let (mut sums_reached, mut averages_reached) = (BTreeSet::new(), BTreeSet::new()); + for where_clauses in shapes() { + for mode in MODES { + for limit in [None, Some(3u32)] { + for order_clauses in orders() { + let canonical = || { + validate_and_canonicalize_where_clauses( + where_clauses.clone(), + platform_version, + ) + .map_err(refusal) + }; + + let dispatched = match drive.execute_document_sum_request( + DocumentSumRequest { + contract: &contract, + document_type, + sum_property: "amount".to_string(), + where_clauses: where_clauses.clone(), + resolved_time_ranges: vec![], + order_clauses: order_clauses.clone(), + mode: SumMode::from(mode), + limit, + prove: true, + drive_config: &config, + }, + None, + platform_version, + ) { + Ok(DocumentSumResponse::Proof(proof)) => Ok(proof), + Ok(other) => panic!("a proved sum answered {other:?}"), + Err(e) => Err(refusal(e)), + }; + let by_mode = canonical().and_then(|canonical| { + let proof_mode = detect_sum_mode_from_inputs( + &canonical, + SumMode::from(mode), + true, + platform_version, + ) + .map_err(refusal)?; + let plan = DriveDocumentSumQuery::proof_plan( + &document_type, + &canonical, + &[], + "amount", + proof_mode, + &order_clauses, + limit, + Some(config.max_query_limit), + ) + .map_err(refusal)?; + sum_plan_by_mode( + &drive, + &contract, + document_type, + &canonical, + plan, + false, + platform_version, + ) + .map_err(refusal) + }); + if let Ok((_, variant)) = &by_mode { + sums_reached.insert(*variant); + } + assert_eq!( + dispatched, + by_mode.map(|(proof, _)| proof), + "sum {where_clauses:?} {mode:?} {limit:?} {order_clauses:?}" + ); + + let dispatched = match drive.execute_document_average_request( + DocumentAverageRequest { + contract: &contract, + document_type, + sum_property: "amount".to_string(), + where_clauses: where_clauses.clone(), + resolved_time_ranges: vec![], + order_clauses: order_clauses.clone(), + mode: AverageMode::from(mode), + limit, + prove: true, + drive_config: &config, + }, + None, + platform_version, + ) { + Ok(DocumentAverageResponse::Proof(proof)) => Ok(proof), + Ok(other) => panic!("a proved average answered {other:?}"), + Err(e) => Err(refusal(e)), + }; + let by_mode = canonical().and_then(|canonical| { + let plan = DriveDocumentSumQuery::average_proof_plan( + &document_type, + &canonical, + &[], + "amount", + AverageMode::from(mode), + &order_clauses, + limit, + Some(config.max_query_limit), + ) + .map_err(refusal)?; + sum_plan_by_mode( + &drive, + &contract, + document_type, + &canonical, + plan, + true, + platform_version, + ) + .map_err(refusal) + }); + if let Ok((_, variant)) = &by_mode { + averages_reached.insert(*variant); + } + assert_eq!( + dispatched, + by_mode.map(|(proof, _)| proof), + "avg {where_clauses:?} {mode:?} {limit:?} {order_clauses:?}" + ); + } + } + } + } + assert_eq!(sums_reached, BTreeSet::from(EVERY_PLAN)); + assert_eq!(averages_reached, BTreeSet::from(EVERY_PLAN)); +} diff --git a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/mod.rs b/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/mod.rs index ab0f493c2a0..719b0cbd881 100644 --- a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/mod.rs +++ b/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/mod.rs @@ -62,7 +62,9 @@ pub struct DriveAbciDocumentQueryHelperVersions { /// Version of the helper that picks the `(group_by × where)` /// mode for `SELECT COUNT / SUM / AVG` and enforces the /// per-mode `accepts_limit()` contract. See - /// `query::document_query::v1::compute_aggregate_mode_and_check_limit`. + /// `drive::query::aggregate_routing::compute_aggregate_mode_and_check_limit`, + /// which drive-abci's v1 document query handler and the SDK's count, + /// sum and average views both route through. /// /// The SDK reads it too, to know from which protocol version every node routes a ranked /// aggregate (from 1) and a having-range aggregate (from 2)