From 143ceed4b72840215bb9eaafde4c8d41cc23938b Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 27 Sep 2026 18:37:40 +0700 Subject: [PATCH 1/2] refactor(platform): fold DRIVE_ABCI_QUERY_VERSIONS_V3 into V2 #4266 added DRIVE_ABCI_QUERY_VERSIONS_V2 for protocol version 14 and #4384 added V3 on top of it for the same unreleased version, so V2 was selected by no protocol version. A second feature landing in the same protocol version amends that version's table in place. V2 now carries both slot changes (compute_aggregate_mode_and_check_limit 2, latest_versions_read 1) and PLATFORM_V14 selects it; the values protocol version 14 sees are unchanged. Co-Authored-By: Claude Opus 5.5 --- book/src/versioning/feature-versions.md | 13 +++-- book/src/versioning/platform-version.md | 2 +- .../drive_abci_query_versions/mod.rs | 1 - .../drive_abci_query_versions/v2.rs | 55 +++++++++++++------ .../drive_abci_query_versions/v3.rs | 46 ---------------- .../rs-platform-version/src/version/v14.rs | 6 +- 6 files changed, 49 insertions(+), 74 deletions(-) delete mode 100644 packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v3.rs diff --git a/book/src/versioning/feature-versions.md b/book/src/versioning/feature-versions.md index 0301f170b06..c3ad33aaee4 100644 --- a/book/src/versioning/feature-versions.md +++ b/book/src/versioning/feature-versions.md @@ -485,16 +485,19 @@ slots edited. Newer ones use struct update syntax, so that the file *is* the diff: ```rust -// packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v3.rs +// packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v2.rs -/// Differs from v2 in exactly one slot: +/// Differs from v1 in two slots. /// `document_query_helpers.compute_aggregate_mode_and_check_limit` is 2 -/// rather than 1. That is the boolean-`HAVING` routing gate. ... -pub const DRIVE_ABCI_QUERY_VERSIONS_V3: DriveAbciQueryVersions = DriveAbciQueryVersions { +/// rather than 0: the ranked and boolean-`HAVING` routing gate. ... +pub const DRIVE_ABCI_QUERY_VERSIONS_V2: DriveAbciQueryVersions = DriveAbciQueryVersions { document_query_helpers: DriveAbciDocumentQueryHelperVersions { compute_aggregate_mode_and_check_limit: 2, }, - ..DRIVE_ABCI_QUERY_VERSIONS_V2 + data_contract_query_helpers: DriveAbciDataContractQueryHelperVersions { + latest_versions_read: 1, + }, + ..DRIVE_ABCI_QUERY_VERSIONS_V1 }; ``` diff --git a/book/src/versioning/platform-version.md b/book/src/versioning/platform-version.md index e7317d3b924..32e7db207f5 100644 --- a/book/src/versioning/platform-version.md +++ b/book/src/versioning/platform-version.md @@ -171,7 +171,7 @@ pub const PLATFORM_V14: PlatformVersion = PlatformVersion { methods: DRIVE_ABCI_METHOD_VERSIONS_V10, // changed: records the per-block total credits history validation_and_processing: DRIVE_ABCI_VALIDATION_VERSIONS_V10, // changed: contested-index cross-check + refersTo validation withdrawal_constants: DRIVE_ABCI_WITHDRAWAL_CONSTANTS_V3, // changed: prune bound for the total credits history - query: DRIVE_ABCI_QUERY_VERSIONS_V3, // changed: ranked + boolean-HAVING routing gate + query: DRIVE_ABCI_QUERY_VERSIONS_V2, // changed: ranked + boolean-HAVING routing gate checkpoints: DRIVE_ABCI_CHECKPOINT_PARAMETERS_V1, }, dpp: DPPVersion { 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 17483a5b79c..fff1a461416 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 @@ -1,7 +1,6 @@ pub mod v0; pub mod v1; pub mod v2; -pub mod v3; use versioned_feature_core::{FeatureVersion, FeatureVersionBounds}; diff --git a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v2.rs b/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v2.rs index f70c889fcf6..9ed60e2d313 100644 --- a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v2.rs +++ b/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v2.rs @@ -1,29 +1,48 @@ use crate::version::drive_abci_versions::drive_abci_query_versions::v1::DRIVE_ABCI_QUERY_VERSIONS_V1; use crate::version::drive_abci_versions::drive_abci_query_versions::{ - DriveAbciDocumentQueryHelperVersions, DriveAbciQueryVersions, + DriveAbciDataContractQueryHelperVersions, DriveAbciDocumentQueryHelperVersions, + DriveAbciQueryVersions, }; -/// Version 2 of the Drive ABCI query versions. +/// Version 2 of the Drive ABCI query versions, selected by protocol version 14. /// -/// Differs from v1 in exactly one slot: -/// `document_query_helpers.compute_aggregate_mode_and_check_limit` is 1 -/// rather than 0. That is the ranked-routing gate. The v0 helper has no -/// ranked path at all; the v1 helper routes a grouped aggregate whose -/// single `order_by` names the selected aggregate (`ORDER BY -/// [ASC|DESC] LIMIT n [OFFSET m]`) to the ranked executor, and otherwise -/// behaves exactly as v0. Both reject every non-empty `having` with -/// "HAVING clause is not yet implemented". +/// Differs from v1 in two slots. /// -/// Keeping the flip in v14's own table is what lets a mixed-version network -/// agree: protocol version 13 and earlier keep the v1 table, so those nodes -/// still reject ranked queries, while v14 nodes answer them. The wire -/// surface is unchanged — `document_query` stays at v1 because -/// `GetDocumentsRequestV1` already carries `selects` / `group_by` / -/// `having`, and the ranked *response* shape is an additive -/// `ResultData.ranked` variant older clients simply never receive. +/// `document_query_helpers.compute_aggregate_mode_and_check_limit` is 2 +/// rather than 0. That opens two routes on the v1 document-query handler: +/// the ranked path, a grouped aggregate whose single `order_by` names the +/// selected aggregate (`ORDER BY [ASC|DESC] LIMIT n [OFFSET m]`), +/// served by the ranked executor; and the boolean-`HAVING` range path, a +/// grouped aggregate carrying exactly one `having` clause +/// (`GROUP BY p HAVING LIMIT n`), served as a +/// value-bounded range read of the covering ranked index's axis secondary. +/// Everything else, including multi-clause `having` and `having` on a +/// select with no ranked axis, is rejected as before ("HAVING clause is not +/// yet implemented"). +/// +/// `data_contract_query_helpers.latest_versions_read` is 1 rather than 0: +/// from protocol version 14 every contract carries a four-byte version item +/// beside it (`[64, id, 2] / 64`, backfilled on the first block of the version), +/// so `getDataContractsLatestVersions` without `include_contracts` reads that +/// item and proves it instead of the contracts. The tables protocol versions +/// 1 to 13 select keep helper version 0, which reads and proves the contracts +/// a state without the items still has. +/// +/// Mixed-network safety comes from the shipped tables: protocol versions +/// 1-11 select `DRIVE_ABCI_QUERY_VERSIONS_V0` and 12-13 select +/// `DRIVE_ABCI_QUERY_VERSIONS_V1`. Both use helper version 0 and reject +/// ranked and `HAVING` shapes, so nodes agree until the protocol version 14 +/// upgrade carries. The wire surface is unchanged: `document_query` stays at +/// v1 because `GetDocumentsRequestV1` already carries `selects` / `group_by` +/// / `having`, and the ranked and range responses reuse the additive +/// `ResultData.ranked` entries shape (with `skipped` unset for a range page, +/// which has no rank base), which older clients never receive. pub const DRIVE_ABCI_QUERY_VERSIONS_V2: DriveAbciQueryVersions = DriveAbciQueryVersions { document_query_helpers: DriveAbciDocumentQueryHelperVersions { - compute_aggregate_mode_and_check_limit: 1, + compute_aggregate_mode_and_check_limit: 2, + }, + data_contract_query_helpers: DriveAbciDataContractQueryHelperVersions { + latest_versions_read: 1, }, ..DRIVE_ABCI_QUERY_VERSIONS_V1 }; diff --git a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v3.rs b/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v3.rs deleted file mode 100644 index 0da6b62f902..00000000000 --- a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v3.rs +++ /dev/null @@ -1,46 +0,0 @@ -use crate::version::drive_abci_versions::drive_abci_query_versions::v2::DRIVE_ABCI_QUERY_VERSIONS_V2; -use crate::version::drive_abci_versions::drive_abci_query_versions::{ - DriveAbciDataContractQueryHelperVersions, DriveAbciDocumentQueryHelperVersions, - DriveAbciQueryVersions, -}; - -/// Version 3 of the Drive ABCI query versions. -/// -/// Differs from v2 in two slots. -/// -/// `data_contract_query_helpers.latest_versions_read` is 1 rather than 0: -/// from protocol version 14 every contract carries a four-byte version item -/// beside it (`[64, id, 2] / 64`, backfilled on the first block of the version), -/// so `getDataContractsLatestVersions` without `include_contracts` reads that -/// item and proves it instead of the contracts. The tables protocol versions -/// 1 to 13 select keep helper version 0, which reads and proves the contracts -/// a state without the items still has. -/// -/// `document_query_helpers.compute_aggregate_mode_and_check_limit` is 2 -/// rather than 1. That is the boolean-`HAVING` routing gate. The v1 -/// helper rejects every non-empty `having` ("HAVING clause is not yet -/// implemented"); the v2 helper routes a grouped aggregate carrying -/// exactly one `having` clause (`GROUP BY p HAVING -/// LIMIT n`) to the having-range executor, which serves it as a -/// value-bounded range read of the covering ranked index's axis -/// secondary. Everything else — including multi-clause `having` and -/// `having` on a select with no ranked axis — keeps the v1 behavior. -/// -/// Mixed-network safety comes from the shipped tables: protocol -/// versions 1–11 select `DRIVE_ABCI_QUERY_VERSIONS_V0`, and versions -/// 12–13 select `DRIVE_ABCI_QUERY_VERSIONS_V1`. Both use helper -/// version 0 and reject ranked and `HAVING` shapes, so nodes agree -/// until the PV14 upgrade carries. The wire surface is unchanged — -/// `GetDocumentsRequestV1.having` has been wire-stable since the v1 -/// document query, and the response reuses the additive -/// `ResultData.ranked` entries shape (with `skipped` unset, since a -/// range page has no rank base). -pub const DRIVE_ABCI_QUERY_VERSIONS_V3: DriveAbciQueryVersions = DriveAbciQueryVersions { - document_query_helpers: DriveAbciDocumentQueryHelperVersions { - compute_aggregate_mode_and_check_limit: 2, - }, - data_contract_query_helpers: DriveAbciDataContractQueryHelperVersions { - latest_versions_read: 1, - }, - ..DRIVE_ABCI_QUERY_VERSIONS_V2 -}; diff --git a/packages/rs-platform-version/src/version/v14.rs b/packages/rs-platform-version/src/version/v14.rs index 5c0236287d8..a8289c2d0ef 100644 --- a/packages/rs-platform-version/src/version/v14.rs +++ b/packages/rs-platform-version/src/version/v14.rs @@ -16,7 +16,7 @@ use crate::version::dpp_versions::dpp_voting_versions::v2::VOTING_VERSION_V2; use crate::version::dpp_versions::DPPVersion; use crate::version::drive_abci_versions::drive_abci_checkpoint_parameters::v1::DRIVE_ABCI_CHECKPOINT_PARAMETERS_V1; use crate::version::drive_abci_versions::drive_abci_method_versions::v10::DRIVE_ABCI_METHOD_VERSIONS_V10; -use crate::version::drive_abci_versions::drive_abci_query_versions::v3::DRIVE_ABCI_QUERY_VERSIONS_V3; +use crate::version::drive_abci_versions::drive_abci_query_versions::v2::DRIVE_ABCI_QUERY_VERSIONS_V2; use crate::version::drive_abci_versions::drive_abci_structure_versions::v2::DRIVE_ABCI_STRUCTURE_VERSIONS_V2; use crate::version::drive_abci_versions::drive_abci_validation_versions::v10::DRIVE_ABCI_VALIDATION_VERSIONS_V10; use crate::version::drive_abci_versions::drive_abci_withdrawal_constants::v3::DRIVE_ABCI_WITHDRAWAL_CONSTANTS_V3; @@ -181,7 +181,7 @@ pub const PROTOCOL_VERSION_14: ProtocolVersion = 14; /// moderation election (an `electedCharter` contest) runs on its target /// contract's join and vote windows, which the document create join check /// and the contested insert read. -/// * `DRIVE_ABCI_QUERY_VERSIONS_V3` bumps +/// * `DRIVE_ABCI_QUERY_VERSIONS_V2` bumps /// `document_query_helpers.compute_aggregate_mode_and_check_limit` 0 → 2, /// opening two routes on the v1 document-query handler: the ranked path /// (a grouped aggregate whose single `order_by` names the selected @@ -1389,7 +1389,7 @@ pub const PLATFORM_V14: PlatformVersion = PlatformVersion { methods: DRIVE_ABCI_METHOD_VERSIONS_V10, // changed: records the per-block total credits history for the daily withdrawal limit validation_and_processing: DRIVE_ABCI_VALIDATION_VERSIONS_V10, // changed: contested-index cross-check + refersTo document reference validation; the ContractUserModeration gates and the batch transformer's contract_moderation_gate; a contest accepts at most max_contenders_per_contest contenders and maximum_contenders_to_consider rises to 10,000; a contender's fund doubles past 250 contenders and for every 50 more withdrawal_constants: DRIVE_ABCI_WITHDRAWAL_CONSTANTS_V3, // changed: prune bound for the total credits history - query: DRIVE_ABCI_QUERY_VERSIONS_V3, // changed: ranked + boolean-HAVING routing gate; the v1 handler also resolves IN_TIME_RANGE from committed block time + query: DRIVE_ABCI_QUERY_VERSIONS_V2, // changed: ranked + boolean-HAVING routing gate; the v1 handler also resolves IN_TIME_RANGE from committed block time checkpoints: DRIVE_ABCI_CHECKPOINT_PARAMETERS_V1, }, dpp: DPPVersion { From 86b6da1a2b7da7ef228f24cb7ab3f3d2a944cd8b Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 27 Sep 2026 23:56:36 +0700 Subject: [PATCH 2/2] docs(platform): list query versions v0 to v2 in the feature versions chapter Review follow-up: the directory listing still ended at v3.rs, which this PR removes. Co-Authored-By: Claude Opus 5.5 --- book/src/versioning/feature-versions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/versioning/feature-versions.md b/book/src/versioning/feature-versions.md index c3ad33aaee4..f2395089285 100644 --- a/book/src/versioning/feature-versions.md +++ b/book/src/versioning/feature-versions.md @@ -567,7 +567,7 @@ version/ v1.rs .. v10.rs drive_abci_query_versions/ mod.rs - v0.rs .. v3.rs + v0.rs .. v2.rs drive_abci_withdrawal_constants/ mod.rs # DriveAbciWithdrawalConstants (parameters, not method versions) v1.rs .. v3.rs