feat!: add time-range indexes for trending/leaderboard queries

packages/dapi-grpc/clients/drive/v0/nodejs/drive_pbjs.js

@@ -20039,6 +20039,7 @@ $root.org = (function() {
                          * @property {number} BETWEEN_EXCLUDE_RIGHT=8 BETWEEN_EXCLUDE_RIGHT value
                          * @property {number} IN=9 IN value
                          * @property {number} STARTS_WITH=10 STARTS_WITH value
+                         * @property {number} IN_TIME_RANGE=11 IN_TIME_RANGE value
                          */
                         GetDocumentsRequest.WhereOperator = (function() {
                             var valuesById = {}, values = Object.create(valuesById);
@@ -20053,6 +20054,7 @@ $root.org = (function() {
                             values[valuesById[8] = "BETWEEN_EXCLUDE_RIGHT"] = 8;
                             values[valuesById[9] = "IN"] = 9;
                             values[valuesById[10] = "STARTS_WITH"] = 10;
+                            values[valuesById[11] = "IN_TIME_RANGE"] = 11;
                             return values;
                         })();
 
@@ -20870,6 +20872,7 @@ $root.org = (function() {
                                     case 8:
                                     case 9:
                                     case 10:
+                                    case 11:
                                         break;
                                     }
                                 if (message.value != null && message.hasOwnProperty("value")) {
@@ -20939,6 +20942,10 @@ $root.org = (function() {
                                 case 10:
                                     message.operator = 10;
                                     break;
+                                case "IN_TIME_RANGE":
+                                case 11:
+                                    message.operator = 11;
+                                    break;
                                 }
                                 if (object.value != null) {
                                     if (typeof object.value !== "object")

packages/dapi-grpc/clients/platform/v0/nodejs/platform_pbjs.js

@@ -19531,6 +19531,7 @@ $root.org = (function() {
                          * @property {number} BETWEEN_EXCLUDE_RIGHT=8 BETWEEN_EXCLUDE_RIGHT value
                          * @property {number} IN=9 IN value
                          * @property {number} STARTS_WITH=10 STARTS_WITH value
+                         * @property {number} IN_TIME_RANGE=11 IN_TIME_RANGE value
                          */
                         GetDocumentsRequest.WhereOperator = (function() {
                             var valuesById = {}, values = Object.create(valuesById);
@@ -19545,6 +19546,7 @@ $root.org = (function() {
                             values[valuesById[8] = "BETWEEN_EXCLUDE_RIGHT"] = 8;
                             values[valuesById[9] = "IN"] = 9;
                             values[valuesById[10] = "STARTS_WITH"] = 10;
+                            values[valuesById[11] = "IN_TIME_RANGE"] = 11;
                             return values;
                         })();
 
@@ -20362,6 +20364,7 @@ $root.org = (function() {
                                     case 8:
                                     case 9:
                                     case 10:
+                                    case 11:
                                         break;
                                     }
                                 if (message.value != null && message.hasOwnProperty("value")) {
@@ -20431,6 +20434,10 @@ $root.org = (function() {
                                 case 10:
                                     message.operator = 10;
                                     break;
+                                case "IN_TIME_RANGE":
+                                case 11:
+                                    message.operator = 11;
+                                    break;
                                 }
                                 if (object.value != null) {
                                     if (typeof object.value !== "object")

packages/dapi-grpc/clients/platform/v0/nodejs/platform_protoc.js

@@ -24389,7 +24389,8 @@ proto.org.dash.platform.dapi.v0.GetDocumentsRequest.WhereOperator = {
   BETWEEN_EXCLUDE_LEFT: 7,
   BETWEEN_EXCLUDE_RIGHT: 8,
   IN: 9,
-  STARTS_WITH: 10
+  STARTS_WITH: 10,
+  IN_TIME_RANGE: 11
 };
 
 

packages/dapi-grpc/clients/platform/v0/web/platform_pb.d.ts

@@ -2739,6 +2739,7 @@ export namespace GetDocumentsRequest {
     BETWEEN_EXCLUDE_RIGHT: 8;
     IN: 9;
     STARTS_WITH: 10;
+    IN_TIME_RANGE: 11;
   }
 
   export const WhereOperator: WhereOperatorMap;

packages/dapi-grpc/clients/platform/v0/web/platform_pb.js

@@ -24389,7 +24389,8 @@ proto.org.dash.platform.dapi.v0.GetDocumentsRequest.WhereOperator = {
   BETWEEN_EXCLUDE_LEFT: 7,
   BETWEEN_EXCLUDE_RIGHT: 8,
   IN: 9,
-  STARTS_WITH: 10
+  STARTS_WITH: 10,
+  IN_TIME_RANGE: 11
 };
 
 

packages/dapi-grpc/protos/platform/v0/platform.proto

@@ -594,6 +594,18 @@ message GetDocumentsRequest {
     BETWEEN_EXCLUDE_RIGHT = 8;
     IN = 9;
     STARTS_WITH = 10;
+    // Time-range bucket selection (v1 only; the v0 CBOR surface is
+    // unaffected). `field` names a timestamp covered by a `timeRange`
+    // index. Operand: `text` selector `"newest"`/`"oldest"` when one grid
+    // buckets the field, or `list` `[selector, range, step(, phase)]` in
+    // the contract's declared seconds to name one of several grids (zero
+    // phase is spelled by omission — one wire spelling per grid). The
+    // server resolves it to a bucket-start equality from current block
+    // time; the verifier re-derives the same bucket from the quorum-signed
+    // metadata time — an ordinary index/count proof. See `timeRange` in
+    // the document meta-schema and
+    // `drive::query::resolve_time_range_bucket_clause`.
+    IN_TIME_RANGE = 11;
   }
 
   // Tagged scalar (or list) operand for a `WhereClause`. The

packages/dash-platform-queries/src/documents/average_proof_helpers.rs

@@ -96,11 +96,33 @@ pub(super) fn assert_select_is_avg(
 ///   that should be unreachable here (`prove = true`); reject as
 ///   `RequestError` if they bubble through.
 pub(super) fn verify_average_query(
-    request: DocumentQuery,
+    mut request: DocumentQuery,
     response: GetDocumentsResponse,
     platform_version: &PlatformVersion,
     provider: &dyn ContextProvider,
 ) -> Result<(Option<Vec<AverageEntry>>, ResponseMetadata, Proof), drive_proof_verifier::Error> {
+    let proof = response
+        .proof()
+        .or(Err(drive_proof_verifier::Error::NoProofInResult))?;
+    let mtd = response
+        .metadata()
+        .or(Err(drive_proof_verifier::Error::EmptyResponseMetadata))?;
+    let contract_id = request.data_contract.id().to_buffer();
+    let sum_property = request.select.field.clone();
+
+    // Resolve any pending time-range (`IN_TIME_RANGE`) selections into
+    // concrete bucket-equality clauses using the quorum-signed metadata
+    // block time — BEFORE mode detection and covering-index selection
+    // below, which read `request.where_clauses`; the prover routed on
+    // the resolved shape.
+    // ...and enforce the same provenance-vs-shape contract the server
+    // dispatchers do, through the one shared normalization helper.
+    let resolved_time_ranges =
+        super::document_query::normalize_time_range_clauses_with_metadata_time(
+            &mut request,
+            mtd.time_ms,
+        )?;
+
     let document_type = request
         .data_contract
         .document_type_for_name(&request.document_type_name)
@@ -110,14 +132,6 @@ pub(super) fn verify_average_query(
                 request.document_type_name, e
             ),
         })?;
-    let proof = response
-        .proof()
-        .or(Err(drive_proof_verifier::Error::NoProofInResult))?;
-    let mtd = response
-        .metadata()
-        .or(Err(drive_proof_verifier::Error::EmptyResponseMetadata))?;
-    let contract_id = request.data_contract.id().to_buffer();
-    let sum_property = request.select.field.clone();
 
     // Resolve the SQL-shape `SumMode` the request implies — AVG
     // shares the routing table with SUM (see module docstring), so
@@ -174,6 +188,7 @@ pub(super) fn verify_average_query(
             document_type.indexes(),
             &request.where_clauses,
             &sum_property,
+            &resolved_time_ranges,
         )
         .filter(|idx| idx.range_countable)
         .ok_or_else(|| drive_proof_verifier::Error::RequestError {
@@ -189,6 +204,7 @@ pub(super) fn verify_average_query(
             document_type.indexes(),
             &request.where_clauses,
             &sum_property,
+            &resolved_time_ranges,
         )
         .filter(|idx| idx.countable.is_countable())
         .ok_or_else(|| drive_proof_verifier::Error::RequestError {