From d0f7c07f7b56bd777c075d1c2ee12659e8210898 Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 13:57:35 +0700 Subject: [PATCH 1/8] fix(drive): verify a single document that may be contested (PV15) A single document query in its "maybe contested" status looks among the documents of its type and in the contest's area at once. No proof of one verified at any protocol version: the verifier asked GroveDB to name the absent keys, which needs an overall limit the merged query does not have. verify_proof_keep_serialized 1, selected by protocol version 15, verifies the proof against the merged query and answers with the document from whichever place holds it. Under GROVE_V5 the query of a document type that keeps history states its cap itself, since the merge no longer derives one above a subquery, and builds the query protocol version 14 built. A lookup at a block time is refused in this status. Co-Authored-By: Claude Fable 5.2 --- .../src/query/single_document_drive_query.rs | 72 ++- .../verify_proof_keep_serialized/mod.rs | 6 +- .../verify_proof_keep_serialized/v1/mod.rs | 454 ++++++++++++++++++ .../drive_verify_method_versions/v4.rs | 13 +- .../src/version/drive_versions/v10.rs | 6 +- .../rs-platform-version/src/version/v15.rs | 14 +- .../README_SINGLE_DOCUMENT.md | 4 + 7 files changed, 561 insertions(+), 8 deletions(-) create mode 100644 packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs diff --git a/packages/rs-drive/src/query/single_document_drive_query.rs b/packages/rs-drive/src/query/single_document_drive_query.rs index 1bee60799c3..98e9b5a3d45 100644 --- a/packages/rs-drive/src/query/single_document_drive_query.rs +++ b/packages/rs-drive/src/query/single_document_drive_query.rs @@ -115,8 +115,35 @@ impl SingleDocumentDriveQuery { Ok(self.construct_non_contested_path_query(true)) } SingleDocumentDriveQueryContestedStatus::MaybeContested => { - let non_contested = self.construct_non_contested_path_query(true); + let mut non_contested = self.construct_non_contested_path_query(true); let contested = self.construct_contested_path_query(true); + // A lookup in a document's history has a subquery. From its generation 2 the + // merge refuses an overall limit above a subquery, where the generation before + // turned it into the cap of the merged branch. + if self.document_type_keeps_history + && platform_version + .drive + .grove_version + .grovedb_versions + .path_query_methods + .merge + >= 2 + { + // A lookup at a block time is refused: no proof of one verifies, in any + // contested status, and its range also reaches the pointer to the latest + // version, so a time before the document was stored would answer with + // that version. + if self.block_time_ms.is_some() { + return Err(Error::Query(QuerySyntaxError::Unsupported( + "a document that may be contested can not be looked up at a block \ + time" + .to_string(), + ))); + } + // The cap is written here instead, which merges to the query the + // generation before built. + non_contested.query.query.limit = non_contested.query.limit.take(); + } PathQuery::merge( vec![&non_contested, &contested], &platform_version.drive.grove_version, @@ -210,6 +237,49 @@ mod tests { DocumentTransition::Create(create) } + fn maybe_contested( + document_type_keeps_history: bool, + block_time_ms: Option, + ) -> SingleDocumentDriveQuery { + SingleDocumentDriveQuery { + contract_id: [7; 32], + document_type_name: "card".to_string(), + document_type_keeps_history, + document_id: [9; 32], + block_time_ms, + contested_status: SingleDocumentDriveQueryContestedStatus::MaybeContested, + } + } + + #[test] + fn should_build_the_maybe_contested_query_the_protocol_version_before_built() { + let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); + for document_type_keeps_history in [false, true] { + let query = maybe_contested(document_type_keeps_history, None); + + assert_eq!( + query + .construct_path_query(PlatformVersion::latest()) + .expect("expected to build the query"), + query + .construct_path_query(protocol_version_14) + .expect("expected to build the query at protocol version 14"), + "keeps history: {document_type_keeps_history}" + ); + } + } + + #[test] + fn should_refuse_a_maybe_contested_lookup_at_a_block_time() { + let result = + maybe_contested(true, Some(1500)).construct_path_query(PlatformVersion::latest()); + + assert!( + matches!(result, Err(Error::Query(QuerySyntaxError::Unsupported(_)))), + "{result:?}" + ); + } + /// A create stating a contest fund is looked for in the contest's area, while a decision /// proposal, which states the decision proposal fund, is stored and looked for as any /// document diff --git a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/mod.rs b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/mod.rs index 53d95501279..444071f2581 100644 --- a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/mod.rs +++ b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/mod.rs @@ -1,4 +1,5 @@ mod v0; +mod v1; use crate::error::drive::DriveError; use crate::verify::RootHash; @@ -44,9 +45,10 @@ impl SingleDocumentDriveQuery { .verify_proof_keep_serialized { 0 => self.verify_proof_keep_serialized_v0(is_subset, proof, platform_version), + 1 => self.verify_proof_keep_serialized_v1(is_subset, proof, platform_version), version => Err(Error::Drive(DriveError::UnknownVersionMismatch { method: "SingleDocumentDriveQuery::verify_proof_keep_serialized".to_string(), - known_versions: vec![0], + known_versions: vec![0, 1], received: version, })), } @@ -82,7 +84,7 @@ mod tests { assert!( matches!(result, Err(Error::Drive(DriveError::UnknownVersionMismatch { method, known_versions, received })) - if method == "SingleDocumentDriveQuery::verify_proof_keep_serialized" && known_versions == vec![0] && received == 255 + if method == "SingleDocumentDriveQuery::verify_proof_keep_serialized" && known_versions == vec![0, 1] && received == 255 ) ); } diff --git a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs new file mode 100644 index 00000000000..5f72203b267 --- /dev/null +++ b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs @@ -0,0 +1,454 @@ +use crate::error::proof::ProofError; +use crate::error::Error; +use crate::query::{SingleDocumentDriveQuery, SingleDocumentDriveQueryContestedStatus}; +use crate::verify::RootHash; +use grovedb::GroveDb; +use platform_version::version::PlatformVersion; + +impl SingleDocumentDriveQuery { + /// Generation 0, except that a document that may be contested is verified. + /// + /// Such a query looks in two places, among the documents of its type and in the contest's + /// area, each under a cap of its own, so the merged query has no overall limit. Generation + /// 0 asks GroveDB to name the keys that are absent, which needs that limit, and so refused + /// every such query. Here the proof is verified against the merged query as it is: it + /// answers with the document from whichever place holds it, and with nothing when neither + /// does, which the proof then shows. + #[inline(always)] + pub(super) fn verify_proof_keep_serialized_v1( + &self, + is_subset: bool, + proof: &[u8], + platform_version: &PlatformVersion, + ) -> Result<(RootHash, Option>), Error> { + if self.contested_status != SingleDocumentDriveQueryContestedStatus::MaybeContested { + return self.verify_proof_keep_serialized_v0(is_subset, proof, platform_version); + } + let path_query = self.construct_path_query(platform_version)?; + let (root_hash, mut proved_key_values) = if is_subset { + GroveDb::verify_subset_query(proof, &path_query, &platform_version.drive.grove_version)? + } else { + GroveDb::verify_query(proof, &path_query, &platform_version.drive.grove_version)? + }; + + // A document is stored among the documents of its type or waits in a contest, never both + if proved_key_values.len() > 1 { + return Err(Error::Proof(ProofError::CorruptedProof(format!( + "a document is in one place at most, we got {} elements", + proved_key_values.len() + )))); + } + + let serialized = proved_key_values + .pop() + .and_then(|(_, _, element)| element) + .map(|element| element.into_item_bytes().map_err(Error::from)) + .transpose()?; + + Ok((root_hash, serialized)) + } +} + +#[cfg(test)] +mod tests { + use crate::drive::votes::resolved::vote_polls::contested_document_resource_vote_poll::ContestedDocumentResourceVotePollWithContractInfo; + use crate::drive::Drive; + use crate::error::proof::ProofError; + use crate::error::query::QuerySyntaxError; + use crate::error::Error; + use crate::query::{SingleDocumentDriveQuery, SingleDocumentDriveQueryContestedStatus}; + use crate::util::object_size_info::DocumentInfo::DocumentRefInfo; + use crate::util::object_size_info::{ + DataContractOwnedResolvedInfo, DocumentAndContractInfo, OwnedDocumentInfo, + }; + use crate::util::test_helpers::setup::setup_drive_with_initial_state_structure; + use crate::util::test_helpers::setup_contract; + use dpp::block::block_info::BlockInfo; + use dpp::data_contract::accessors::v0::DataContractV0Getters; + use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; + use dpp::data_contract::document_type::random_document::CreateRandomDocument; + use dpp::data_contract::DataContract; + use dpp::document::serialization_traits::DocumentPlatformConversionMethodsV0; + use dpp::document::{Document, DocumentV0Getters, DocumentV0Setters}; + use dpp::platform_value::Value; + use dpp::version::PlatformVersion; + use dpp::voting::vote_info_storage::contested_document_vote_poll_stored_info::ContestedDocumentVotePollStoredInfo; + + const DPNS: &str = + "tests/supporting_files/contract/dpns/dpns-contract-contested-unique-index.json"; + const FAMILY_WITH_HISTORY: &str = + "tests/supporting_files/contract/family/family-contract-with-history-only-message-index.json"; + + fn drive_with_contract(path: &str) -> (Drive, DataContract) { + let platform_version = PlatformVersion::latest(); + let drive = setup_drive_with_initial_state_structure(Some(platform_version)); + let contract = setup_contract( + &drive, + path, + None, + None, + None::, + None, + Some(platform_version), + ); + (drive, contract) + } + + fn info<'a>( + document: &'a Document, + contract: &'a DataContract, + document_type_name: &str, + ) -> DocumentAndContractInfo<'a> { + DocumentAndContractInfo { + owned_document_info: OwnedDocumentInfo { + document_info: DocumentRefInfo((document, None)), + owner_id: Some(document.owner_id().to_buffer()), + }, + contract, + document_type: contract + .document_type_for_name(document_type_name) + .expect("expected the document type"), + } + } + + fn maybe_contested( + contract: &DataContract, + document_type_name: &str, + document_id: [u8; 32], + block_time_ms: Option, + ) -> SingleDocumentDriveQuery { + let document_type = contract + .document_type_for_name(document_type_name) + .expect("expected the document type"); + SingleDocumentDriveQuery { + contract_id: contract.id().to_buffer(), + document_type_name: document_type_name.to_string(), + document_type_keeps_history: document_type.documents_keep_history(), + document_id, + block_time_ms, + contested_status: SingleDocumentDriveQueryContestedStatus::MaybeContested, + } + } + + /// The document the query proves, verified as the whole proof and as a part of one. + fn prove_and_verify( + drive: &Drive, + contract: &DataContract, + query: &SingleDocumentDriveQuery, + ) -> Option { + let platform_version = PlatformVersion::latest(); + let path_query = query + .construct_path_query(platform_version) + .expect("expected to build the query"); + let proof = drive + .grove_get_proved_path_query(&path_query, None, &mut vec![], &platform_version.drive) + .expect("expected a proof"); + let document_type = contract + .document_type_for_name(query.document_type_name.as_str()) + .expect("expected the document type"); + let (root_hash, document) = query + .verify_proof(false, proof.as_slice(), document_type, platform_version) + .expect("expected the proof to verify"); + let (subset_root_hash, subset_document) = query + .verify_proof(true, proof.as_slice(), document_type, platform_version) + .expect("expected the proof to verify as a subset"); + assert_eq!(root_hash, subset_root_hash); + assert_eq!(document, subset_document); + assert_eq!( + root_hash, + drive + .grove + .root_hash(None, &platform_version.drive.grove_version) + .unwrap() + .expect("expected a root hash"), + "the proof is of the stored state" + ); + document + } + + fn domain(contract: &DataContract, seed: u64, label: &str) -> Document { + let mut document = contract + .document_type_for_name("domain") + .expect("expected the domain document type") + .random_document(Some(seed), PlatformVersion::latest()) + .expect("expected a random document"); + document.set( + "normalizedParentDomainName", + Value::Text("dash".to_string()), + ); + document.set("normalizedLabel", Value::Text(label.to_string())); + document + } + + /// Stores `document` as a contender for the name "quantum", in the contest's area. + fn add_to_contest(drive: &Drive, contract: &DataContract, document: &Document) { + let platform_version = PlatformVersion::latest(); + drive + .add_contested_document_for_contract( + info(document, contract, "domain"), + ContestedDocumentResourceVotePollWithContractInfo { + contract: DataContractOwnedResolvedInfo::OwnedDataContract(contract.clone()), + document_type_name: "domain".to_string(), + index_name: "parentNameAndLabel".to_string(), + index_values: vec![ + Value::Text("dash".to_string()), + Value::Text("quantum".to_string()), + ], + }, + false, + BlockInfo::default(), + true, + Some( + ContestedDocumentVotePollStoredInfo::new( + BlockInfo::default(), + platform_version, + ) + .expect("expected the stored info of a new poll"), + ), + None, + platform_version, + ) + .expect("expected to add the contested document"); + } + + #[test] + fn should_find_a_document_stored_among_its_type_when_it_may_be_contested() { + let platform_version = PlatformVersion::latest(); + let (drive, contract) = drive_with_contract(DPNS); + let document = domain(&contract, 1, "quantum"); + drive + .add_document_for_contract( + info(&document, &contract, "domain"), + false, + BlockInfo::default(), + true, + None, + platform_version, + ) + .expect("expected to add the document"); + + let found = prove_and_verify( + &drive, + &contract, + &maybe_contested(&contract, "domain", document.id().to_buffer(), None), + ); + + assert_eq!(found.map(|found| found.id()), Some(document.id())); + } + + #[test] + fn should_find_a_document_waiting_in_a_contest_when_it_may_be_contested() { + let (drive, contract) = drive_with_contract(DPNS); + let document = domain(&contract, 1, "quantum"); + add_to_contest(&drive, &contract, &document); + + let found = prove_and_verify( + &drive, + &contract, + &maybe_contested(&contract, "domain", document.id().to_buffer(), None), + ); + + assert_eq!(found.map(|found| found.id()), Some(document.id())); + } + + #[test] + fn should_prove_a_document_is_in_neither_place_when_it_may_be_contested() { + let platform_version = PlatformVersion::latest(); + let (drive, contract) = drive_with_contract(DPNS); + // Another document, so both places hold something the proof must tell apart + let other = domain(&contract, 1, "quantum"); + drive + .add_document_for_contract( + info(&other, &contract, "domain"), + false, + BlockInfo::default(), + true, + None, + platform_version, + ) + .expect("expected to add the document"); + + let found = prove_and_verify( + &drive, + &contract, + &maybe_contested(&contract, "domain", [9; 32], None), + ); + + assert_eq!(found, None); + } + + /// A person stored at time 1000 and changed at time 2000, with the two versions. + fn person_with_two_versions(drive: &Drive, contract: &DataContract) -> (Document, Document) { + let platform_version = PlatformVersion::latest(); + let document_type = contract + .document_type_for_name("person") + .expect("expected the person document type"); + let mut first = document_type + .random_document(Some(7), platform_version) + .expect("expected a random document"); + first.set("age", Value::U8(33)); + drive + .add_document_for_contract( + info(&first, contract, "person"), + false, + BlockInfo::default_with_time(1000), + true, + None, + platform_version, + ) + .expect("expected to add the document"); + let mut second = first.clone(); + second.set("age", Value::U8(34)); + drive + .update_document_for_contract( + &second, + contract, + document_type, + Some(second.owner_id().to_buffer()), + BlockInfo::default_with_time(2000), + true, + None, + None, + platform_version, + ) + .expect("expected to update the document"); + (first, second) + } + + fn serialized(document: &Document, contract: &DataContract) -> Vec { + document + .serialize( + contract + .document_type_for_name("person") + .expect("expected the person document type"), + contract, + PlatformVersion::latest(), + ) + .expect("expected to serialize the document") + } + + #[test] + fn should_find_the_latest_version_of_a_document_with_history_when_it_may_be_contested() { + let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); + let (_, second) = person_with_two_versions(&drive, &contract); + + let found = prove_and_verify( + &drive, + &contract, + &maybe_contested(&contract, "person", second.id().to_buffer(), None), + ) + .expect("expected the document"); + + assert_eq!( + serialized(&found, &contract), + serialized(&second, &contract) + ); + } + + #[test] + fn should_refuse_to_look_up_a_document_that_may_be_contested_at_a_block_time() { + let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); + let (first, _) = person_with_two_versions(&drive, &contract); + + let result = maybe_contested(&contract, "person", first.id().to_buffer(), Some(1500)) + .construct_path_query(PlatformVersion::latest()); + + assert!( + matches!(result, Err(Error::Query(QuerySyntaxError::Unsupported(_)))), + "{result:?}" + ); + } + + /// A proof of the document's query in `proved_status`, which looks in one place only. + fn proof_of_one_place( + drive: &Drive, + query: &SingleDocumentDriveQuery, + proved_status: SingleDocumentDriveQueryContestedStatus, + ) -> Vec { + let platform_version = PlatformVersion::latest(); + let one_place = SingleDocumentDriveQuery { + contested_status: proved_status, + ..query.clone() + }; + drive + .grove_get_proved_path_query( + &one_place + .construct_path_query(platform_version) + .expect("expected to build the query"), + None, + &mut vec![], + &platform_version.drive, + ) + .expect("expected a proof") + } + + #[test] + fn should_refuse_a_proof_that_covers_only_one_of_the_two_places() { + let platform_version = PlatformVersion::latest(); + let (drive, contract) = drive_with_contract(DPNS); + let document = domain(&contract, 1, "quantum"); + drive + .add_document_for_contract( + info(&document, &contract, "domain"), + false, + BlockInfo::default(), + true, + None, + platform_version, + ) + .expect("expected to add the document"); + add_to_contest(&drive, &contract, &domain(&contract, 2, "quantum")); + let query = maybe_contested(&contract, "domain", document.id().to_buffer(), None); + + for proved_status in [ + SingleDocumentDriveQueryContestedStatus::NotContested, + SingleDocumentDriveQueryContestedStatus::Contested, + ] { + let proof = proof_of_one_place(&drive, &query, proved_status.clone()); + for is_subset in [false, true] { + assert!( + query + .verify_proof_keep_serialized(is_subset, proof.as_slice(), platform_version) + .is_err(), + "a proof of the {proved_status:?} place alone, is_subset {is_subset}" + ); + } + } + } + + #[test] + fn should_refuse_a_document_proved_to_be_in_both_places() { + let platform_version = PlatformVersion::latest(); + let (drive, contract) = drive_with_contract(DPNS); + let document = domain(&contract, 1, "quantum"); + drive + .add_document_for_contract( + info(&document, &contract, "domain"), + false, + BlockInfo::default(), + true, + None, + platform_version, + ) + .expect("expected to add the document"); + add_to_contest(&drive, &contract, &document); + let query = maybe_contested(&contract, "domain", document.id().to_buffer(), None); + let proof = drive + .grove_get_proved_path_query( + &query + .construct_path_query(platform_version) + .expect("expected to build the query"), + None, + &mut vec![], + &platform_version.drive, + ) + .expect("expected a proof"); + + let result = query.verify_proof_keep_serialized(false, proof.as_slice(), platform_version); + + assert!( + matches!(result, Err(Error::Proof(ProofError::CorruptedProof(_)))), + "{result:?}" + ); + } +} diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs b/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs index 14a415f5f97..cdd25234f94 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs @@ -1,14 +1,17 @@ use crate::version::drive_versions::drive_verify_method_versions::v3::DRIVE_VERIFY_METHOD_VERSIONS_V3; use crate::version::drive_versions::drive_verify_method_versions::{ - DriveVerifyDocumentMethodVersions, DriveVerifyMethodVersions, DriveVerifyVoteMethodVersions, + DriveVerifyDocumentMethodVersions, DriveVerifyMethodVersions, + DriveVerifySingleDocumentMethodVersions, DriveVerifyVoteMethodVersions, }; /// Version 4 of the Drive verify method versions, introduced in protocol version 15 with the /// yes/no poll kind: `voting.verify_yes_no_vote_poll_state_proof`, /// `voting.verify_masternode_yes_no_vote` and `voting.verify_identity_yes_no_vote` are `Some(0)` /// (`None`, not active, in every earlier table), and so is -/// `document.verify_private_document_entries`, with private document types. Everything else -/// matches `DRIVE_VERIFY_METHOD_VERSIONS_V3`. +/// `document.verify_private_document_entries`, with private document types. +/// `single_document.verify_proof_keep_serialized` is 1: a document that may be contested is +/// verified, where generation 0 refused every such query. Everything else matches +/// `DRIVE_VERIFY_METHOD_VERSIONS_V3`. pub const DRIVE_VERIFY_METHOD_VERSIONS_V4: DriveVerifyMethodVersions = DriveVerifyMethodVersions { voting: DriveVerifyVoteMethodVersions { verify_yes_no_vote_poll_state_proof: Some(0), @@ -20,5 +23,9 @@ pub const DRIVE_VERIFY_METHOD_VERSIONS_V4: DriveVerifyMethodVersions = DriveVeri verify_private_document_entries: Some(0), // changed: a proved page of a private type's store ..DRIVE_VERIFY_METHOD_VERSIONS_V3.document }, + single_document: DriveVerifySingleDocumentMethodVersions { + verify_proof_keep_serialized: 1, // changed: verifies a document that may be contested + ..DRIVE_VERIFY_METHOD_VERSIONS_V3.single_document + }, ..DRIVE_VERIFY_METHOD_VERSIONS_V3 }; diff --git a/packages/rs-platform-version/src/version/drive_versions/v10.rs b/packages/rs-platform-version/src/version/drive_versions/v10.rs index 4a321bcd4fb..e7c917d5470 100644 --- a/packages/rs-platform-version/src/version/drive_versions/v10.rs +++ b/packages/rs-platform-version/src/version/drive_versions/v10.rs @@ -95,6 +95,10 @@ use grovedb_version::version::v5::GROVE_V5; /// * **Storage handover** (protocol v15 note 28): `grove_methods` is /// `DRIVE_GROVE_METHOD_VERSIONS_V2`. /// +/// * **A document that may be contested** (protocol v15 note 29): +/// `DRIVE_VERIFY_METHOD_VERSIONS_V4` sets `single_document.verify_proof_keep_serialized` to +/// 1, which verifies the proof of a single document query in its "maybe contested" status. +/// /// Everything else matches `DRIVE_VERSION_V9`. pub const DRIVE_VERSION_V10: DriveVersion = DriveVersion { methods: DriveMethodVersions { @@ -127,7 +131,7 @@ pub const DRIVE_VERSION_V10: DriveVersion = DriveVersion { ..DRIVE_VERSION_V9.methods.prefunded_specialized_balances }, vote: DRIVE_VOTE_METHOD_VERSIONS_V4, // changed in v10: the yes/no poll kind - verify: DRIVE_VERIFY_METHOD_VERSIONS_V4, // changed in v10: the yes/no and private document entries proof verifiers + verify: DRIVE_VERIFY_METHOD_VERSIONS_V4, // changed in v10: the yes/no and private document entries proof verifiers; a document that may be contested is verified state_transitions: DRIVE_STATE_TRANSITION_METHOD_VERSIONS_V5, // changed in v10: a consume deletes what its lookup read platform_system: DrivePlatformSystemMethodVersions { estimation_costs: DriveSystemEstimationCostsMethodVersions { diff --git a/packages/rs-platform-version/src/version/v15.rs b/packages/rs-platform-version/src/version/v15.rs index 6c8dd077561..f237e71106f 100644 --- a/packages/rs-platform-version/src/version/v15.rs +++ b/packages/rs-platform-version/src/version/v15.rs @@ -583,9 +583,21 @@ pub const PROTOCOL_VERSION_15: ProtocolVersion = 15; /// document's flags name (contract user moderation `transform_into_action` 1, /// `DRIVE_ABCI_VALIDATION_VERSIONS_V11`), so the moderator pays for the bytes the change /// adds and a document a sponsor paid for stays the sponsor's. +/// +/// 29. **A document that may be contested is looked up and verified**: a single document query +/// in its "maybe contested" status looks among the documents of its type and in the +/// contest's area at once. `verify_proof_keep_serialized` 1 +/// (`DRIVE_VERIFY_METHOD_VERSIONS_V4`) verifies its proof against the merged query and +/// answers with the document from whichever place holds it. Generation 0 asked for the +/// absent keys by name, which needs an overall limit the merged query does not have, and +/// so refused every such query. Under `GROVE_V5` (note 26) the query of a document type +/// that keeps history states its cap itself, as the merge no longer derives one above a +/// subquery, and builds the query protocol v14 built. A lookup at a block time is refused +/// in this status. No state transition is proved in this status, so block execution and +/// the proofs of state transitions are unchanged. pub const PLATFORM_V15: PlatformVersion = PlatformVersion { protocol_version: PROTOCOL_VERSION_15, - drive: DRIVE_VERSION_V10, // changed: calculate_fee 1 prices a refund at the storing epoch's rate (note 27); apply_contract_with_serialization 1 writes nothing for a contract whose format version 1 bytes match the stored one's (note 8); vote method versions v4: register_identity_vote 1 registers a yes/no vote, remove_all_votes_given_by_identities 1 also removes the yes/no votes of a masternode that left the list, every yes_no method and remove_vote_poll_end_date_query_operations Some(0) make yes/no polls active, add_vote_poll_end_date_query_operations 1 adds only the entry when the batch already queues the end date's tree with other storage flags, and verify methods v4 make the yes/no proof verifiers active (note 10) and verify_private_document_entries Some(0) a page of a private type's store (note 13); state transition method versions v5: document_create_transition 1 deletes a consumed document from what its lookup read (note 11); document method versions v5: insert_empty_private_document_store_operation Some(0) creates a private document type's store, and fetch_private_document_entries and prove_private_document_entries Some(0) read and prove a page of it (note 13); apply_drive_operations 2 resolves a batch's estimate, remove_reference_for_index_level_for_contract_operations 2, stateless_delete_of_non_tree_for_costs 1 and for_total_system_credits_update 1 describe their layers as they are (note 14); create_initial_state_structure 5 adds the token marketplace escrow trees; calculate_total_tokens_balance 2 counts escrowed tokens; the escrow primitives; the identity balance, token balance, prefunded specialized balance and contract fee pot estimations (for_balances 1, for_token_balances 1, estimated_cost_for_prefunded_specialized_balance_update 2, add_estimation_costs_for_contract_fee_pot_update 1) keep a deeper layer description (note 17); fetch_core_fork_activation_height and store_core_fork_activation_height Some(0) keep the Core fork activations (note 18); document method versions v5: append_private_document_entries_operations Some(0) appends a private document create's entries (note 25); grove_version GROVE_V5 (note 26) + drive: DRIVE_VERSION_V10, // changed: calculate_fee 1 prices a refund at the storing epoch's rate (note 27); apply_contract_with_serialization 1 writes nothing for a contract whose format version 1 bytes match the stored one's (note 8); vote method versions v4: register_identity_vote 1 registers a yes/no vote, remove_all_votes_given_by_identities 1 also removes the yes/no votes of a masternode that left the list, every yes_no method and remove_vote_poll_end_date_query_operations Some(0) make yes/no polls active, add_vote_poll_end_date_query_operations 1 adds only the entry when the batch already queues the end date's tree with other storage flags, and verify methods v4 make the yes/no proof verifiers active (note 10) and verify_private_document_entries Some(0) a page of a private type's store (note 13); state transition method versions v5: document_create_transition 1 deletes a consumed document from what its lookup read (note 11); document method versions v5: insert_empty_private_document_store_operation Some(0) creates a private document type's store, and fetch_private_document_entries and prove_private_document_entries Some(0) read and prove a page of it (note 13); apply_drive_operations 2 resolves a batch's estimate, remove_reference_for_index_level_for_contract_operations 2, stateless_delete_of_non_tree_for_costs 1 and for_total_system_credits_update 1 describe their layers as they are (note 14); create_initial_state_structure 5 adds the token marketplace escrow trees; calculate_total_tokens_balance 2 counts escrowed tokens; the escrow primitives; the identity balance, token balance, prefunded specialized balance and contract fee pot estimations (for_balances 1, for_token_balances 1, estimated_cost_for_prefunded_specialized_balance_update 2, add_estimation_costs_for_contract_fee_pot_update 1) keep a deeper layer description (note 17); fetch_core_fork_activation_height and store_core_fork_activation_height Some(0) keep the Core fork activations (note 18); document method versions v5: append_private_document_entries_operations Some(0) appends a private document create's entries (note 25); grove_version GROVE_V5 (note 26); verify methods v4: verify_proof_keep_serialized 1 verifies a document that may be contested (note 29) drive_abci: DriveAbciVersion { structs: DRIVE_ABCI_STRUCTURE_VERSIONS_V2, methods: DRIVE_ABCI_METHOD_VERSIONS_V11, // changed: the yes/no poll's tally, record, clean-up and finish hook are Some(0) (note 10); verify_chain_lock_locally 1 rejects a chain lock locally only when Platform holds the quorums active at its signing height, and verify_chain_lock_through_core 1 has Core's verifychainlock check the others before submitchainlock; consensus_params_update 2 installs the full evidence policy (note 16); update_core_info 1 records the chain locked height at which Core's V24 is first seen active (note 18); build_untied_withdrawal_transactions_from_documents 1 emits asset unlock payload version 2 once V24 is recorded as active (note 20); update_voter_identity 1 re-enables the voter key of the address a masternode returns to (note 22) diff --git a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md index c34b38fc244..9ce44319c16 100644 --- a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md +++ b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md @@ -70,6 +70,10 @@ Documents in Drive can have different contested statuses: - **MaybeContested (1)**: We don't know if the document was contested, or we're not sure if the contest is over - **Contested (2)**: We know that the document was contested and the contest is not over +A `MaybeContested` query looks in both places at once, so its proof has to cover both: a proof +made for a `NotContested` or a `Contested` query does not verify against it. Such a proof +verifies from protocol version 15. A `MaybeContested` query with a block time is not supported. + ## API Reference ### Classes From 5b1033f90be22341cc73ef1ebb34f60a3963e141 Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 13:58:36 +0700 Subject: [PATCH 2/8] test(drive): pin the maybe contested query of protocol version 14 Co-Authored-By: Claude Fable 5.2 --- .../src/query/single_document_drive_query.rs | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/packages/rs-drive/src/query/single_document_drive_query.rs b/packages/rs-drive/src/query/single_document_drive_query.rs index 98e9b5a3d45..ef520d7bee8 100644 --- a/packages/rs-drive/src/query/single_document_drive_query.rs +++ b/packages/rs-drive/src/query/single_document_drive_query.rs @@ -119,7 +119,8 @@ impl SingleDocumentDriveQuery { let contested = self.construct_contested_path_query(true); // A lookup in a document's history has a subquery. From its generation 2 the // merge refuses an overall limit above a subquery, where the generation before - // turned it into the cap of the merged branch. + // turned it into the cap of the merged branch. Protocol version 15 is the + // first to select that generation, so no earlier version enters here. if self.document_type_keeps_history && platform_version .drive @@ -269,6 +270,29 @@ mod tests { } } + #[test] + fn should_leave_the_maybe_contested_query_of_protocol_version_14_as_it_was() { + let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); + for block_time_ms in [None, Some(1500)] { + let query = maybe_contested(true, block_time_ms); + + assert_eq!( + query + .construct_path_query(protocol_version_14) + .expect("expected to build the query"), + PathQuery::merge( + vec![ + &query.construct_non_contested_path_query(true), + &query.construct_contested_path_query(true), + ], + &protocol_version_14.drive.grove_version, + ) + .expect("expected to merge the two lookups"), + "block time: {block_time_ms:?}" + ); + } + } + #[test] fn should_refuse_a_maybe_contested_lookup_at_a_block_time() { let result = From 6b8940fffb233d70616deb018dac2fbfd79d28d3 Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 14:00:27 +0700 Subject: [PATCH 3/8] docs(drive): say which lookups at a block time do not verify Co-Authored-By: Claude Fable 5.2 --- .../rs-drive/src/query/single_document_drive_query.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/rs-drive/src/query/single_document_drive_query.rs b/packages/rs-drive/src/query/single_document_drive_query.rs index ef520d7bee8..632b26c794a 100644 --- a/packages/rs-drive/src/query/single_document_drive_query.rs +++ b/packages/rs-drive/src/query/single_document_drive_query.rs @@ -130,10 +130,10 @@ impl SingleDocumentDriveQuery { .merge >= 2 { - // A lookup at a block time is refused: no proof of one verifies, in any - // contested status, and its range also reaches the pointer to the latest - // version, so a time before the document was stored would answer with - // that version. + // A lookup at a block time is refused. No proof of one verifies for a + // document outside a contest either, and its range also reaches the + // pointer to the latest version, so a time before the document was + // stored would answer with that version. if self.block_time_ms.is_some() { return Err(Error::Query(QuerySyntaxError::Unsupported( "a document that may be contested can not be looked up at a block \ From 620918a83e9740df72377d137320202a789ffac5 Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 15:33:09 +0700 Subject: [PATCH 4/8] docs(drive): say when a maybe contested lookup refuses a block time Only a document type that keeps history refuses a block time in this status. A type without history has one version and ignores it, as in every status. The README, note 29 and the error say so. Tests: a block time is ignored for a type without history, and protocol version 14 still refuses a proof that generation 1 accepts, whole and as a subset. Co-Authored-By: Claude Fable 5.2 --- .../src/query/single_document_drive_query.rs | 4 +- .../verify_proof_keep_serialized/v1/mod.rs | 81 ++++++++++++++++++- .../rs-platform-version/src/version/v15.rs | 7 +- .../README_SINGLE_DOCUMENT.md | 9 ++- 4 files changed, 93 insertions(+), 8 deletions(-) diff --git a/packages/rs-drive/src/query/single_document_drive_query.rs b/packages/rs-drive/src/query/single_document_drive_query.rs index 632b26c794a..240829c9d3a 100644 --- a/packages/rs-drive/src/query/single_document_drive_query.rs +++ b/packages/rs-drive/src/query/single_document_drive_query.rs @@ -136,8 +136,8 @@ impl SingleDocumentDriveQuery { // stored would answer with that version. if self.block_time_ms.is_some() { return Err(Error::Query(QuerySyntaxError::Unsupported( - "a document that may be contested can not be looked up at a block \ - time" + "a document with history that may be contested can not be looked \ + up at a block time" .to_string(), ))); } diff --git a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs index 5f72203b267..28d21911bbe 100644 --- a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs +++ b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs @@ -80,7 +80,13 @@ mod tests { "tests/supporting_files/contract/family/family-contract-with-history-only-message-index.json"; fn drive_with_contract(path: &str) -> (Drive, DataContract) { - let platform_version = PlatformVersion::latest(); + drive_with_contract_at(path, PlatformVersion::latest()) + } + + fn drive_with_contract_at( + path: &str, + platform_version: &PlatformVersion, + ) -> (Drive, DataContract) { let drive = setup_drive_with_initial_state_structure(Some(platform_version)); let contract = setup_contract( &drive, @@ -359,6 +365,79 @@ mod tests { ); } + #[test] + fn should_ignore_a_block_time_for_a_document_type_without_history() { + let platform_version = PlatformVersion::latest(); + let (drive, contract) = drive_with_contract(DPNS); + let document = domain(&contract, 1, "quantum"); + drive + .add_document_for_contract( + info(&document, &contract, "domain"), + false, + BlockInfo::default(), + true, + None, + platform_version, + ) + .expect("expected to add the document"); + + let found = prove_and_verify( + &drive, + &contract, + &maybe_contested(&contract, "domain", document.id().to_buffer(), Some(1500)), + ); + + assert_eq!(found.map(|found| found.id()), Some(document.id())); + } + + #[test] + fn should_still_refuse_a_document_that_may_be_contested_at_protocol_version_14() { + // Generation 1 is protocol version 15's. The version before keeps refusing a proof + // that generation 1 accepts. + let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); + let (drive, contract) = drive_with_contract_at(DPNS, protocol_version_14); + let document = domain(&contract, 1, "quantum"); + drive + .add_document_for_contract( + info(&document, &contract, "domain"), + false, + BlockInfo::default(), + true, + None, + protocol_version_14, + ) + .expect("expected to add the document"); + let query = maybe_contested(&contract, "domain", document.id().to_buffer(), None); + let proof = drive + .grove_get_proved_path_query( + &query + .construct_path_query(protocol_version_14) + .expect("expected to build the query"), + None, + &mut vec![], + &protocol_version_14.drive, + ) + .expect("expected a proof"); + + for is_subset in [false, true] { + let refused = query.verify_proof_keep_serialized( + is_subset, + proof.as_slice(), + protocol_version_14, + ); + assert!(refused.is_err(), "is_subset {is_subset}: {refused:?}"); + + let (_, accepted) = query + .verify_proof_keep_serialized( + is_subset, + proof.as_slice(), + PlatformVersion::latest(), + ) + .expect("expected generation 1 to verify the same proof"); + assert!(accepted.is_some(), "is_subset {is_subset}"); + } + } + /// A proof of the document's query in `proved_status`, which looks in one place only. fn proof_of_one_place( drive: &Drive, diff --git a/packages/rs-platform-version/src/version/v15.rs b/packages/rs-platform-version/src/version/v15.rs index f237e71106f..22a73dac212 100644 --- a/packages/rs-platform-version/src/version/v15.rs +++ b/packages/rs-platform-version/src/version/v15.rs @@ -592,9 +592,10 @@ pub const PROTOCOL_VERSION_15: ProtocolVersion = 15; /// absent keys by name, which needs an overall limit the merged query does not have, and /// so refused every such query. Under `GROVE_V5` (note 26) the query of a document type /// that keeps history states its cap itself, as the merge no longer derives one above a -/// subquery, and builds the query protocol v14 built. A lookup at a block time is refused -/// in this status. No state transition is proved in this status, so block execution and -/// the proofs of state transitions are unchanged. +/// subquery, and builds the query protocol v14 built. For such a type a lookup at a block +/// time is refused in this status; a type without history has one version and ignores the +/// time, as it does in every status. No state transition is proved in this status, so +/// block execution and the proofs of state transitions are unchanged. pub const PLATFORM_V15: PlatformVersion = PlatformVersion { protocol_version: PROTOCOL_VERSION_15, drive: DRIVE_VERSION_V10, // changed: calculate_fee 1 prices a refund at the storing epoch's rate (note 27); apply_contract_with_serialization 1 writes nothing for a contract whose format version 1 bytes match the stored one's (note 8); vote method versions v4: register_identity_vote 1 registers a yes/no vote, remove_all_votes_given_by_identities 1 also removes the yes/no votes of a masternode that left the list, every yes_no method and remove_vote_poll_end_date_query_operations Some(0) make yes/no polls active, add_vote_poll_end_date_query_operations 1 adds only the entry when the batch already queues the end date's tree with other storage flags, and verify methods v4 make the yes/no proof verifiers active (note 10) and verify_private_document_entries Some(0) a page of a private type's store (note 13); state transition method versions v5: document_create_transition 1 deletes a consumed document from what its lookup read (note 11); document method versions v5: insert_empty_private_document_store_operation Some(0) creates a private document type's store, and fetch_private_document_entries and prove_private_document_entries Some(0) read and prove a page of it (note 13); apply_drive_operations 2 resolves a batch's estimate, remove_reference_for_index_level_for_contract_operations 2, stateless_delete_of_non_tree_for_costs 1 and for_total_system_credits_update 1 describe their layers as they are (note 14); create_initial_state_structure 5 adds the token marketplace escrow trees; calculate_total_tokens_balance 2 counts escrowed tokens; the escrow primitives; the identity balance, token balance, prefunded specialized balance and contract fee pot estimations (for_balances 1, for_token_balances 1, estimated_cost_for_prefunded_specialized_balance_update 2, add_estimation_costs_for_contract_fee_pot_update 1) keep a deeper layer description (note 17); fetch_core_fork_activation_height and store_core_fork_activation_height Some(0) keep the Core fork activations (note 18); document method versions v5: append_private_document_entries_operations Some(0) appends a private document create's entries (note 25); grove_version GROVE_V5 (note 26); verify methods v4: verify_proof_keep_serialized 1 verifies a document that may be contested (note 29) diff --git a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md index 9ce44319c16..377a168693f 100644 --- a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md +++ b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md @@ -19,7 +19,7 @@ const query = createSingleDocumentQuery( 'myDocumentType', // string - The document type name false, // boolean - Whether the document type keeps history documentId, // Uint8Array(32) - The document ID - Date.now() // number (optional) - Block time in milliseconds + Date.now() // number (optional) - Block time in milliseconds, ignored unless the type keeps history ); // For a maybe contested document @@ -72,7 +72,12 @@ Documents in Drive can have different contested statuses: A `MaybeContested` query looks in both places at once, so its proof has to cover both: a proof made for a `NotContested` or a `Contested` query does not verify against it. Such a proof -verifies from protocol version 15. A `MaybeContested` query with a block time is not supported. +verifies from protocol version 15. + +The block time selects a version only for a document type that keeps history. For a type +without history there is one version, and the block time is ignored in every status. From +protocol version 15, a `MaybeContested` query for a type that keeps history is refused when it +has a block time. ## API Reference From 8b8f5ef9fd7bb5736e008ea68537fe05c39ff01f Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 15:43:18 +0700 Subject: [PATCH 5/8] fix(drive): look up a single document at a block time (PV15) In a document type that keeps history, a single document query with a block time asks for the newest version stored at or before that time. It never worked: its range also reached the pointer to the latest version at key [0], so a time before the document was first stored answered with the latest version, and no proof of it verified, as the verifier asked GroveDB to name the absent keys of a range. The query gets generations. single_document_path_query 1, selected only by protocol version 15's document method table, stops the range above the pointer, and states the cap of a document that may be contested as the merge of GROVE_V5 needs it. Generation 0 is what protocol versions 1 to 14 build. verify_proof_keep_serialized 1 verifies such a lookup against the query as it is, for a document outside a contest and for one that may be contested, which is no longer refused at a block time. Co-Authored-By: Claude Fable 5.2 --- .../src/query/single_document_drive_query.rs | 265 +++++++++++------- .../single_document_drive_query/v0/mod.rs | 85 ++++++ .../single_document_drive_query/v1/mod.rs | 73 +++++ .../verify_proof_keep_serialized/v1/mod.rs | 210 ++++++++++++-- .../drive_document_method_versions/mod.rs | 8 + .../drive_document_method_versions/v1.rs | 1 + .../drive_document_method_versions/v2.rs | 1 + .../drive_document_method_versions/v3.rs | 1 + .../drive_document_method_versions/v4.rs | 1 + .../drive_document_method_versions/v5.rs | 9 +- .../drive_verify_method_versions/v4.rs | 5 +- .../src/version/drive_versions/v10.rs | 7 +- .../rs-platform-version/src/version/v15.rs | 25 +- .../README_SINGLE_DOCUMENT.md | 12 +- 14 files changed, 567 insertions(+), 136 deletions(-) create mode 100644 packages/rs-drive/src/query/single_document_drive_query/v0/mod.rs create mode 100644 packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs diff --git a/packages/rs-drive/src/query/single_document_drive_query.rs b/packages/rs-drive/src/query/single_document_drive_query.rs index 632b26c794a..7ccada93a3e 100644 --- a/packages/rs-drive/src/query/single_document_drive_query.rs +++ b/packages/rs-drive/src/query/single_document_drive_query.rs @@ -1,16 +1,15 @@ -use crate::drive::document::paths::contract_document_type_path_vec; -use crate::util::common::encode::encode_u64; +mod v0; +mod v1; -use crate::drive::votes; +use crate::error::drive::DriveError; use crate::error::query::QuerySyntaxError; use crate::error::Error; -use crate::query::Query; use dpp::decision_proposal::is_decision_proposal; use dpp::state_transition::batch_transition::batched_transition::document_transition::{ DocumentTransition, DocumentTransitionV0Methods, }; use dpp::state_transition::batch_transition::document_create_transition::v0::v0_methods::DocumentCreateTransitionV0Methods; -use grovedb::{PathQuery, SizedQuery}; +use grovedb::PathQuery; use platform_version::version::PlatformVersion; use platform_version::TryFromPlatformVersioned; @@ -105,101 +104,44 @@ impl SingleDocumentDriveQuery { } } - /// Operations to construct a path query. + /// The GroveDB query that looks the document up, which the prover and the verifier both + /// build here. + /// + /// In a document type that keeps history, a query with no block time asks for the latest + /// version, and one with a block time for the newest version stored at or before that + /// time. A lookup at a block time answers so from protocol version 15: before it, a time + /// before the document was first stored answers with the latest version, and no proof of + /// such a lookup verifies. + /// + /// # Parameters + /// + /// - `platform_version`: The platform version, whose + /// `drive.methods.document.query.single_document_path_query` selects the query built. + /// + /// # Returns + /// + /// The path query, or an error when the version is unknown or the two places a document + /// that may be contested is looked for in can not be merged into one query. pub fn construct_path_query( &self, platform_version: &PlatformVersion, ) -> Result { - match self.contested_status { - SingleDocumentDriveQueryContestedStatus::NotContested => { - Ok(self.construct_non_contested_path_query(true)) - } - SingleDocumentDriveQueryContestedStatus::MaybeContested => { - let mut non_contested = self.construct_non_contested_path_query(true); - let contested = self.construct_contested_path_query(true); - // A lookup in a document's history has a subquery. From its generation 2 the - // merge refuses an overall limit above a subquery, where the generation before - // turned it into the cap of the merged branch. Protocol version 15 is the - // first to select that generation, so no earlier version enters here. - if self.document_type_keeps_history - && platform_version - .drive - .grove_version - .grovedb_versions - .path_query_methods - .merge - >= 2 - { - // A lookup at a block time is refused. No proof of one verifies for a - // document outside a contest either, and its range also reaches the - // pointer to the latest version, so a time before the document was - // stored would answer with that version. - if self.block_time_ms.is_some() { - return Err(Error::Query(QuerySyntaxError::Unsupported( - "a document that may be contested can not be looked up at a block \ - time" - .to_string(), - ))); - } - // The cap is written here instead, which merges to the query the - // generation before built. - non_contested.query.query.limit = non_contested.query.limit.take(); - } - PathQuery::merge( - vec![&non_contested, &contested], - &platform_version.drive.grove_version, - ) - .map_err(Error::from) - } - SingleDocumentDriveQueryContestedStatus::Contested => { - Ok(self.construct_contested_path_query(true)) - } + match platform_version + .drive + .methods + .document + .query + .single_document_path_query + { + 0 => self.construct_path_query_v0(platform_version), + 1 => self.construct_path_query_v1(platform_version), + version => Err(Error::Drive(DriveError::UnknownVersionMismatch { + method: "SingleDocumentDriveQuery::construct_path_query".to_string(), + known_versions: vec![0, 1], + received: version, + })), } } - - /// Operations to construct the normal path query. - fn construct_non_contested_path_query(&self, with_limit_1: bool) -> PathQuery { - // First we should get the overall document_type_path - let mut path = - contract_document_type_path_vec(&self.contract_id, self.document_type_name.as_str()); - - path.push(vec![0]); - - let mut query = Query::new(); - query.insert_key(self.document_id.to_vec()); - - if self.document_type_keeps_history { - // if the documents keep history then we should insert a subquery - if let Some(block_time) = self.block_time_ms { - let encoded_block_time = encode_u64(block_time); - let mut sub_query = Query::new_with_direction(false); - sub_query.insert_range_to_inclusive(..=encoded_block_time); - query.set_subquery(sub_query); - } else { - query.set_subquery_key(vec![0]); - } - } - - let limit = if with_limit_1 { Some(1) } else { None }; - - PathQuery::new(path, SizedQuery::new(query, limit, None)) - } - - /// Operations to construct the contested path query. - fn construct_contested_path_query(&self, with_limit_1: bool) -> PathQuery { - // First we should get the overall document_type_path - let path = votes::paths::vote_contested_resource_contract_documents_storage_path_vec( - &self.contract_id, - self.document_type_name.as_str(), - ); - - let mut query = Query::new(); - query.insert_key(self.document_id.to_vec()); - - let limit = if with_limit_1 { Some(1) } else { None }; - - PathQuery::new(path, SizedQuery::new(query, limit, None)) - } } impl TryFromPlatformVersioned for PathQuery { @@ -215,6 +157,9 @@ impl TryFromPlatformVersioned for PathQuery { #[cfg(test)] mod tests { use super::*; + use crate::drive::document::paths::contract_document_type_path_vec; + use crate::query::Query; + use crate::util::common::encode::encode_u64; use dpp::decision_proposal::{ DECISION_PROPOSALS_CONTRACT_ID, DECISION_PROPOSAL_FUND_NAME, PROPOSAL_DOCUMENT_TYPE_NAME, }; @@ -223,6 +168,7 @@ mod tests { use dpp::state_transition::batch_transition::document_base_transition::document_base_transition_trait::DocumentBaseTransitionAccessors; use dpp::state_transition::batch_transition::document_base_transition::v0::v0_methods::DocumentBaseTransitionV0Methods; use dpp::state_transition::batch_transition::document_create_transition::DocumentCreateTransition; + use grovedb::SizedQuery; fn create( contract_id: Identifier, @@ -238,7 +184,8 @@ mod tests { DocumentTransition::Create(create) } - fn maybe_contested( + fn single_document( + contested_status: SingleDocumentDriveQueryContestedStatus, document_type_keeps_history: bool, block_time_ms: Option, ) -> SingleDocumentDriveQuery { @@ -248,16 +195,56 @@ mod tests { document_type_keeps_history, document_id: [9; 32], block_time_ms, - contested_status: SingleDocumentDriveQueryContestedStatus::MaybeContested, + contested_status, } } + /// The query of the document among the documents of its type, in a type that keeps + /// history, with `versions` as the lookup in the document's history. + fn history_lookup(versions: Query) -> PathQuery { + let mut path = contract_document_type_path_vec(&[7; 32], "card"); + path.push(vec![0]); + let mut query = Query::new(); + query.insert_key(vec![9; 32]); + query.set_subquery(versions); + PathQuery::new(path, SizedQuery::new(query, Some(1), None)) + } + + /// Whether generation 1 builds another query than generation 0: a lookup at a block time + /// among the documents of a type that keeps history + fn looks_in_history_at_block_time(query: &SingleDocumentDriveQuery) -> bool { + query.document_type_keeps_history + && query.block_time_ms.is_some() + && query.contested_status != SingleDocumentDriveQueryContestedStatus::Contested + } + + fn every_query() -> impl Iterator { + [ + SingleDocumentDriveQueryContestedStatus::NotContested, + SingleDocumentDriveQueryContestedStatus::MaybeContested, + SingleDocumentDriveQueryContestedStatus::Contested, + ] + .into_iter() + .flat_map(|contested_status| { + [false, true] + .into_iter() + .flat_map(move |document_type_keeps_history| { + let contested_status = contested_status.clone(); + [None, Some(1500)].into_iter().map(move |block_time_ms| { + single_document( + contested_status.clone(), + document_type_keeps_history, + block_time_ms, + ) + }) + }) + }) + } + #[test] - fn should_build_the_maybe_contested_query_the_protocol_version_before_built() { + fn should_build_the_query_the_protocol_version_before_built_except_at_a_block_time() { let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); - for document_type_keeps_history in [false, true] { - let query = maybe_contested(document_type_keeps_history, None); - + for query in every_query().filter(|query| !looks_in_history_at_block_time(query)) { assert_eq!( query .construct_path_query(PlatformVersion::latest()) @@ -265,16 +252,40 @@ mod tests { query .construct_path_query(protocol_version_14) .expect("expected to build the query at protocol version 14"), - "keeps history: {document_type_keeps_history}" + "{query:?}" ); } } + #[test] + fn should_leave_the_lookup_at_a_block_time_of_protocol_version_14_as_it_was() { + let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); + // Every key up to the block time, the pointer to the latest version at `[0]` included + let mut versions = Query::new_with_direction(false); + versions.insert_range_to_inclusive(..=encode_u64(1500)); + let not_contested = history_lookup(versions); + + assert_eq!( + single_document( + SingleDocumentDriveQueryContestedStatus::NotContested, + true, + Some(1500), + ) + .construct_path_query(protocol_version_14) + .expect("expected to build the query"), + not_contested + ); + } + #[test] fn should_leave_the_maybe_contested_query_of_protocol_version_14_as_it_was() { let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); for block_time_ms in [None, Some(1500)] { - let query = maybe_contested(true, block_time_ms); + let query = single_document( + SingleDocumentDriveQueryContestedStatus::MaybeContested, + true, + block_time_ms, + ); assert_eq!( query @@ -294,12 +305,54 @@ mod tests { } #[test] - fn should_refuse_a_maybe_contested_lookup_at_a_block_time() { - let result = - maybe_contested(true, Some(1500)).construct_path_query(PlatformVersion::latest()); + fn should_stop_a_lookup_at_a_block_time_above_the_pointer_to_the_latest_version() { + for (block_time_ms, last_time_ms) in [ + (1500, 1500), + // A time the history can not order asks for the last one it can + (u64::MAX, i64::MAX as u64), + ] { + let mut versions = Query::new_with_direction(false); + versions.insert_range_after_to_inclusive(vec![0]..=encode_u64(last_time_ms)); + + assert_eq!( + single_document( + SingleDocumentDriveQueryContestedStatus::NotContested, + true, + Some(block_time_ms), + ) + .construct_path_query(PlatformVersion::latest()) + .expect("expected to build the query"), + history_lookup(versions), + "block time: {block_time_ms}" + ); + } + } + + #[test] + fn should_refuse_an_unknown_version_of_the_query() { + let mut platform_version = PlatformVersion::latest().clone(); + platform_version + .drive + .methods + .document + .query + .single_document_path_query = 255; + + let result = single_document( + SingleDocumentDriveQueryContestedStatus::NotContested, + false, + None, + ) + .construct_path_query(&platform_version); assert!( - matches!(result, Err(Error::Query(QuerySyntaxError::Unsupported(_)))), + matches!( + &result, + Err(Error::Drive(DriveError::UnknownVersionMismatch { method, known_versions, received })) + if method == "SingleDocumentDriveQuery::construct_path_query" + && known_versions == &vec![0, 1] + && *received == 255 + ), "{result:?}" ); } diff --git a/packages/rs-drive/src/query/single_document_drive_query/v0/mod.rs b/packages/rs-drive/src/query/single_document_drive_query/v0/mod.rs new file mode 100644 index 00000000000..ff0becaadcd --- /dev/null +++ b/packages/rs-drive/src/query/single_document_drive_query/v0/mod.rs @@ -0,0 +1,85 @@ +use crate::drive::document::paths::contract_document_type_path_vec; +use crate::drive::votes; +use crate::error::Error; +use crate::query::{Query, SingleDocumentDriveQuery, SingleDocumentDriveQueryContestedStatus}; +use crate::util::common::encode::encode_u64; +use grovedb::{PathQuery, SizedQuery}; +use platform_version::version::PlatformVersion; + +impl SingleDocumentDriveQuery { + /// The query protocol versions 1 to 14 build. + /// + /// In a document type that keeps history, a lookup at a block time ranges over every key + /// up to that time. That reaches the pointer to the latest version at key `[0]`, which + /// sorts below every time, so a time before the document was first stored answers with the + /// latest version. No proof of such a lookup verifies either: generation 0 of the verifier + /// asks GroveDB to name the absent keys, which a range that is open at one end does not + /// allow. + #[inline(always)] + pub(super) fn construct_path_query_v0( + &self, + platform_version: &PlatformVersion, + ) -> Result { + match self.contested_status { + SingleDocumentDriveQueryContestedStatus::NotContested => { + Ok(self.construct_non_contested_path_query(true)) + } + SingleDocumentDriveQueryContestedStatus::MaybeContested => { + let non_contested = self.construct_non_contested_path_query(true); + let contested = self.construct_contested_path_query(true); + PathQuery::merge( + vec![&non_contested, &contested], + &platform_version.drive.grove_version, + ) + .map_err(Error::from) + } + SingleDocumentDriveQueryContestedStatus::Contested => { + Ok(self.construct_contested_path_query(true)) + } + } + } + + /// Operations to construct the normal path query. + pub(super) fn construct_non_contested_path_query(&self, with_limit_1: bool) -> PathQuery { + // First we should get the overall document_type_path + let mut path = + contract_document_type_path_vec(&self.contract_id, self.document_type_name.as_str()); + + path.push(vec![0]); + + let mut query = Query::new(); + query.insert_key(self.document_id.to_vec()); + + if self.document_type_keeps_history { + // if the documents keep history then we should insert a subquery + if let Some(block_time) = self.block_time_ms { + let encoded_block_time = encode_u64(block_time); + let mut sub_query = Query::new_with_direction(false); + sub_query.insert_range_to_inclusive(..=encoded_block_time); + query.set_subquery(sub_query); + } else { + query.set_subquery_key(vec![0]); + } + } + + let limit = if with_limit_1 { Some(1) } else { None }; + + PathQuery::new(path, SizedQuery::new(query, limit, None)) + } + + /// Operations to construct the contested path query. + pub(super) fn construct_contested_path_query(&self, with_limit_1: bool) -> PathQuery { + // First we should get the overall document_type_path + let path = votes::paths::vote_contested_resource_contract_documents_storage_path_vec( + &self.contract_id, + self.document_type_name.as_str(), + ); + + let mut query = Query::new(); + query.insert_key(self.document_id.to_vec()); + + let limit = if with_limit_1 { Some(1) } else { None }; + + PathQuery::new(path, SizedQuery::new(query, limit, None)) + } +} diff --git a/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs b/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs new file mode 100644 index 00000000000..4effd96b296 --- /dev/null +++ b/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs @@ -0,0 +1,73 @@ +use crate::error::Error; +use crate::query::{Query, SingleDocumentDriveQuery, SingleDocumentDriveQueryContestedStatus}; +use crate::util::common::encode::encode_u64; +use grovedb::PathQuery; +use platform_version::version::PlatformVersion; + +/// The last time a document's history can order. A time is stored with its top bit flipped, so +/// a time past this one would sort below every time before it. +const LAST_ORDERED_TIME_MS: u64 = i64::MAX as u64; + +impl SingleDocumentDriveQuery { + /// Generation 0, except for two lookups in a document type that keeps history. + /// + /// A lookup at a block time stops above the pointer to the latest version, so it answers + /// with the newest version stored at or before that time, and with nothing for a time + /// before the document was first stored. + /// + /// The lookup of a document that may be contested states its cap itself. Its history lookup + /// has a subquery, above which GroveDB's merge refuses an overall limit from its generation + /// 2 (`GROVE_V5`, which protocol version 15 is the first to select), where the generation + /// before turned that limit into the cap of the merged branch. Written as that cap here, it + /// merges to the query generation 0 built. + #[inline(always)] + pub(super) fn construct_path_query_v1( + &self, + platform_version: &PlatformVersion, + ) -> Result { + match self.contested_status { + SingleDocumentDriveQueryContestedStatus::NotContested => { + Ok(self.construct_non_contested_path_query_v1()) + } + SingleDocumentDriveQueryContestedStatus::MaybeContested => { + let mut non_contested = self.construct_non_contested_path_query_v1(); + let contested = self.construct_contested_path_query(true); + if self.document_type_keeps_history { + non_contested.query.query.limit = non_contested.query.limit.take(); + } + PathQuery::merge( + vec![&non_contested, &contested], + &platform_version.drive.grove_version, + ) + .map_err(Error::from) + } + SingleDocumentDriveQueryContestedStatus::Contested => { + Ok(self.construct_contested_path_query(true)) + } + } + } + + /// Generation 0's query of the document among the documents of its type, with the range of + /// a lookup at a block time replaced. + fn construct_non_contested_path_query_v1(&self) -> PathQuery { + let mut path_query = self.construct_non_contested_path_query(true); + if self.document_type_keeps_history { + if let Some(block_time_ms) = self.block_time_ms { + // A document's history holds one key per time a version was stored, and the + // pointer to the latest version at key `[0]`, below all of them. Walking down + // from the block time and stopping above the pointer, the first key met is the + // newest version stored at or before that time, and there is none when the + // document was first stored later. + let mut versions_up_to_block_time = Query::new_with_direction(false); + versions_up_to_block_time.insert_range_after_to_inclusive( + vec![0]..=encode_u64(block_time_ms.min(LAST_ORDERED_TIME_MS)), + ); + path_query + .query + .query + .set_subquery(versions_up_to_block_time); + } + } + path_query + } +} diff --git a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs index 5f72203b267..6920425127d 100644 --- a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs +++ b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs @@ -6,14 +6,16 @@ use grovedb::GroveDb; use platform_version::version::PlatformVersion; impl SingleDocumentDriveQuery { - /// Generation 0, except that a document that may be contested is verified. + /// Generation 0, except that two kinds of lookup it refused are verified: a document that + /// may be contested, and a document at a block time in a type that keeps history. /// - /// Such a query looks in two places, among the documents of its type and in the contest's - /// area, each under a cap of its own, so the merged query has no overall limit. Generation - /// 0 asks GroveDB to name the keys that are absent, which needs that limit, and so refused - /// every such query. Here the proof is verified against the merged query as it is: it - /// answers with the document from whichever place holds it, and with nothing when neither - /// does, which the proof then shows. + /// Generation 0 asks GroveDB to name the keys that are absent. That needs an overall limit + /// and keys that can be listed. A query for a document that may be contested looks in two + /// places, among the documents of its type and in the contest's area, each under a cap of + /// its own, so the merged query has no overall limit. A lookup at a block time ranges over + /// the times a version was stored at, which can not be listed. Here the proof of either is + /// verified against the query as it is: it answers with the one document the query finds, + /// and with nothing when there is none, which the proof then shows. #[inline(always)] pub(super) fn verify_proof_keep_serialized_v1( &self, @@ -21,7 +23,15 @@ impl SingleDocumentDriveQuery { proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, Option>), Error> { - if self.contested_status != SingleDocumentDriveQueryContestedStatus::MaybeContested { + let verified_by_generation_0 = match self.contested_status { + SingleDocumentDriveQueryContestedStatus::NotContested => { + !(self.document_type_keeps_history && self.block_time_ms.is_some()) + } + SingleDocumentDriveQueryContestedStatus::MaybeContested => false, + // A contest's area keeps no history, so its query has no block time + SingleDocumentDriveQueryContestedStatus::Contested => true, + }; + if verified_by_generation_0 { return self.verify_proof_keep_serialized_v0(is_subset, proof, platform_version); } let path_query = self.construct_path_query(platform_version)?; @@ -31,10 +41,11 @@ impl SingleDocumentDriveQuery { GroveDb::verify_query(proof, &path_query, &platform_version.drive.grove_version)? }; - // A document is stored among the documents of its type or waits in a contest, never both + // A document is stored among the documents of its type or waits in a contest, never + // both, and a lookup in its history is capped at one version if proved_key_values.len() > 1 { return Err(Error::Proof(ProofError::CorruptedProof(format!( - "a document is in one place at most, we got {} elements", + "a single document query finds one document at most, we got {} elements", proved_key_values.len() )))); } @@ -54,7 +65,6 @@ mod tests { use crate::drive::votes::resolved::vote_polls::contested_document_resource_vote_poll::ContestedDocumentResourceVotePollWithContractInfo; use crate::drive::Drive; use crate::error::proof::ProofError; - use crate::error::query::QuerySyntaxError; use crate::error::Error; use crate::query::{SingleDocumentDriveQuery, SingleDocumentDriveQueryContestedStatus}; use crate::util::object_size_info::DocumentInfo::DocumentRefInfo; @@ -80,7 +90,13 @@ mod tests { "tests/supporting_files/contract/family/family-contract-with-history-only-message-index.json"; fn drive_with_contract(path: &str) -> (Drive, DataContract) { - let platform_version = PlatformVersion::latest(); + drive_with_contract_at(path, PlatformVersion::latest()) + } + + fn drive_with_contract_at( + path: &str, + platform_version: &PlatformVersion, + ) -> (Drive, DataContract) { let drive = setup_drive_with_initial_state_structure(Some(platform_version)); let contract = setup_contract( &drive, @@ -279,7 +295,14 @@ mod tests { /// A person stored at time 1000 and changed at time 2000, with the two versions. fn person_with_two_versions(drive: &Drive, contract: &DataContract) -> (Document, Document) { - let platform_version = PlatformVersion::latest(); + person_with_two_versions_at(drive, contract, PlatformVersion::latest()) + } + + fn person_with_two_versions_at( + drive: &Drive, + contract: &DataContract, + platform_version: &PlatformVersion, + ) -> (Document, Document) { let document_type = contract .document_type_for_name("person") .expect("expected the person document type"); @@ -345,18 +368,167 @@ mod tests { ); } + /// The query of the person `document_id` as it stood at `block_time_ms`. + fn person_at_block_time( + contract: &DataContract, + document_id: [u8; 32], + block_time_ms: u64, + contested_status: SingleDocumentDriveQueryContestedStatus, + ) -> SingleDocumentDriveQuery { + SingleDocumentDriveQuery { + contested_status, + ..maybe_contested(contract, "person", document_id, Some(block_time_ms)) + } + } + + #[test] + fn should_find_the_version_of_a_document_stored_at_or_before_a_block_time() { + let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); + let (first, second) = person_with_two_versions(&drive, &contract); + + for contested_status in [ + SingleDocumentDriveQueryContestedStatus::NotContested, + SingleDocumentDriveQueryContestedStatus::MaybeContested, + ] { + for (block_time_ms, expected) in [ + // Before the document was first stored there is no version of it + (0, None), + (999, None), + (1000, Some(&first)), + (1500, Some(&first)), + (1999, Some(&first)), + (2000, Some(&second)), + (2500, Some(&second)), + (u64::MAX, Some(&second)), + ] { + let found = prove_and_verify( + &drive, + &contract, + &person_at_block_time( + &contract, + first.id().to_buffer(), + block_time_ms, + contested_status.clone(), + ), + ); + + assert_eq!( + found.map(|found| serialized(&found, &contract)), + expected.map(|expected| serialized(expected, &contract)), + "{contested_status:?} at block time {block_time_ms}" + ); + } + } + } + #[test] - fn should_refuse_to_look_up_a_document_that_may_be_contested_at_a_block_time() { + fn should_prove_a_document_that_was_never_stored_is_absent_at_a_block_time() { + let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); + // Another document, so the type holds a history the proof must tell apart + person_with_two_versions(&drive, &contract); + + for contested_status in [ + SingleDocumentDriveQueryContestedStatus::NotContested, + SingleDocumentDriveQueryContestedStatus::MaybeContested, + ] { + let found = prove_and_verify( + &drive, + &contract, + &person_at_block_time(&contract, [9; 32], 1500, contested_status.clone()), + ); + + assert_eq!(found, None, "{contested_status:?}"); + } + } + + #[test] + fn should_refuse_a_proof_made_for_another_block_time() { + let platform_version = PlatformVersion::latest(); let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); let (first, _) = person_with_two_versions(&drive, &contract); - let result = maybe_contested(&contract, "person", first.id().to_buffer(), Some(1500)) - .construct_path_query(PlatformVersion::latest()); + for contested_status in [ + SingleDocumentDriveQueryContestedStatus::NotContested, + SingleDocumentDriveQueryContestedStatus::MaybeContested, + ] { + // Each pair of times answers with a different version, or with none for one of them + for (proved_block_time_ms, verified_block_time_ms) in + [(1500, 2500), (2500, 1500), (500, 1500), (1500, 500)] + { + let proved = person_at_block_time( + &contract, + first.id().to_buffer(), + proved_block_time_ms, + contested_status.clone(), + ); + let proof = drive + .grove_get_proved_path_query( + &proved + .construct_path_query(platform_version) + .expect("expected to build the query"), + None, + &mut vec![], + &platform_version.drive, + ) + .expect("expected a proof"); + let verified = SingleDocumentDriveQuery { + block_time_ms: Some(verified_block_time_ms), + ..proved + }; + + for is_subset in [false, true] { + assert!( + verified + .verify_proof_keep_serialized( + is_subset, + proof.as_slice(), + platform_version + ) + .is_err(), + "{contested_status:?}, a proof at {proved_block_time_ms} verified at \ + {verified_block_time_ms}, is_subset {is_subset}" + ); + } + } + } + } - assert!( - matches!(result, Err(Error::Query(QuerySyntaxError::Unsupported(_)))), - "{result:?}" + /// Protocol version 14 selects generation 0 of the query and of this verifier, which a + /// lookup at a block time never passed. + #[test] + fn should_leave_a_lookup_at_a_block_time_refused_at_protocol_version_14() { + let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); + let (drive, contract) = drive_with_contract_at(FAMILY_WITH_HISTORY, protocol_version_14); + let (first, _) = person_with_two_versions_at(&drive, &contract, protocol_version_14); + let query = person_at_block_time( + &contract, + first.id().to_buffer(), + 1500, + SingleDocumentDriveQueryContestedStatus::NotContested, ); + let proof = drive + .grove_get_proved_path_query( + &query + .construct_path_query(protocol_version_14) + .expect("expected to build the query"), + None, + &mut vec![], + &protocol_version_14.drive, + ) + .expect("expected a proof"); + + for is_subset in [false, true] { + let result = query.verify_proof_keep_serialized( + is_subset, + proof.as_slice(), + protocol_version_14, + ); + + assert!( + matches!(result, Err(Error::GroveDB(_))), + "is_subset {is_subset}: {result:?}" + ); + } } /// A proof of the document's query in `proved_status`, which looks in one place only. diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs index cbd815cb9ef..03158de2e51 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs @@ -142,6 +142,14 @@ pub struct DriveDocumentQueryMethodVersions { /// on such a type (`DocumentQuery::required_protocol_version` in /// `dash-platform-queries`). pub start_at_document: FeatureVersion, + /// Building the GroveDB query of a `SingleDocumentDriveQuery`, which the prover and the + /// verifier both do. 0 is what protocol versions 1 to 14 build. 1 (protocol version 15) + /// changes two lookups in a document type that keeps history: one at a block time stops + /// above the pointer to the latest version, so it answers with the newest version stored + /// at or before that time and with nothing before the first, and one of a document that + /// may be contested states its cap itself, which GroveDB's merge no longer derives above + /// a subquery. + pub single_document_path_query: FeatureVersion, } #[derive(Clone, Debug, Default)] diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v1.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v1.rs index f75c5277222..8ae9322d14e 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v1.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v1.rs @@ -27,6 +27,7 @@ pub const DRIVE_DOCUMENT_METHOD_VERSIONS_V1: DriveDocumentMethodVersions = non_primary_key_multiple_in_path_query: 0, where_clause_grouping: 0, start_at_document: 0, + single_document_path_query: 0, }, delete: DriveDocumentDeleteMethodVersions { add_estimation_costs_for_remove_document_to_primary_storage: 0, diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v2.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v2.rs index 6d7a5711d5c..d70d285e533 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v2.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v2.rs @@ -29,6 +29,7 @@ pub const DRIVE_DOCUMENT_METHOD_VERSIONS_V2: DriveDocumentMethodVersions = non_primary_key_multiple_in_path_query: 0, where_clause_grouping: 0, start_at_document: 0, + single_document_path_query: 0, }, delete: DriveDocumentDeleteMethodVersions { add_estimation_costs_for_remove_document_to_primary_storage: 0, diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v3.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v3.rs index 6e66106a5ff..a146d6c1bdd 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v3.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v3.rs @@ -39,6 +39,7 @@ pub const DRIVE_DOCUMENT_METHOD_VERSIONS_V3: DriveDocumentMethodVersions = non_primary_key_multiple_in_path_query: 0, where_clause_grouping: 0, start_at_document: 0, + single_document_path_query: 0, }, delete: DriveDocumentDeleteMethodVersions { add_estimation_costs_for_remove_document_to_primary_storage: 0, diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v4.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v4.rs index 7a98b33664c..ad53874fc0e 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v4.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v4.rs @@ -113,6 +113,7 @@ pub const DRIVE_DOCUMENT_METHOD_VERSIONS_V4: DriveDocumentMethodVersions = // from any item element, so a `documentsSummable` type (stored as // `ItemWithSumItem`) can be paginated. start_at_document: 1, + single_document_path_query: 0, }, delete: DriveDocumentDeleteMethodVersions { add_estimation_costs_for_remove_document_to_primary_storage: 0, diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs index c6954ed119c..06bc7f48e5f 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs @@ -2,7 +2,7 @@ use crate::version::drive_versions::drive_document_method_versions::v4::DRIVE_DO use crate::version::drive_versions::drive_document_method_versions::{ DriveDocumentDeleteMethodVersions, DriveDocumentEstimationCostsMethodVersions, DriveDocumentInsertContestedMethodVersions, DriveDocumentMethodVersions, - DriveDocumentUpdateMethodVersions, + DriveDocumentQueryMethodVersions, DriveDocumentUpdateMethodVersions, }; /// V5 is protocol version 15's document-method table. Relative to V4: @@ -25,12 +25,19 @@ use crate::version::drive_versions::drive_document_method_versions::{ /// on its own hands storage over as one in a batch of drive operations does. /// * `insert_contested.add_contested_document_for_contract_operations` is 2: a poll's end date /// entries name whoever the document's storage flags name. +/// * `query.single_document_path_query` is 1: in a document type that keeps history, the lookup +/// of a single document at a block time stops above the pointer to the latest version, and +/// the lookup of a document that may be contested states its cap itself. pub const DRIVE_DOCUMENT_METHOD_VERSIONS_V5: DriveDocumentMethodVersions = DriveDocumentMethodVersions { insert_empty_private_document_store_operation: Some(0), // changed: a private document type's store is created with it fetch_private_document_entries: Some(0), // changed: a page of a store's entries can be read prove_private_document_entries: Some(0), // changed: and proved append_private_document_entries_operations: Some(0), // changed: a PrivateDocumentCreateFromShieldedPool appends entries to a store + query: DriveDocumentQueryMethodVersions { + single_document_path_query: 1, // changed: a lookup at a block time stops above the pointer to the latest version + ..DRIVE_DOCUMENT_METHOD_VERSIONS_V4.query + }, delete: DriveDocumentDeleteMethodVersions { remove_reference_for_index_level_for_contract_operations: 2, // changed: the entries layer is described as references ..DRIVE_DOCUMENT_METHOD_VERSIONS_V4.delete diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs b/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs index cdd25234f94..2b5d7c3e88b 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs @@ -10,7 +10,8 @@ use crate::version::drive_versions::drive_verify_method_versions::{ /// (`None`, not active, in every earlier table), and so is /// `document.verify_private_document_entries`, with private document types. /// `single_document.verify_proof_keep_serialized` is 1: a document that may be contested is -/// verified, where generation 0 refused every such query. Everything else matches +/// verified, and so is a document at a block time in a type that keeps history, where +/// generation 0 refused every such query. Everything else matches /// `DRIVE_VERIFY_METHOD_VERSIONS_V3`. pub const DRIVE_VERIFY_METHOD_VERSIONS_V4: DriveVerifyMethodVersions = DriveVerifyMethodVersions { voting: DriveVerifyVoteMethodVersions { @@ -24,7 +25,7 @@ pub const DRIVE_VERIFY_METHOD_VERSIONS_V4: DriveVerifyMethodVersions = DriveVeri ..DRIVE_VERIFY_METHOD_VERSIONS_V3.document }, single_document: DriveVerifySingleDocumentMethodVersions { - verify_proof_keep_serialized: 1, // changed: verifies a document that may be contested + verify_proof_keep_serialized: 1, // changed: verifies a document that may be contested, and one at a block time ..DRIVE_VERIFY_METHOD_VERSIONS_V3.single_document }, ..DRIVE_VERIFY_METHOD_VERSIONS_V3 diff --git a/packages/rs-platform-version/src/version/drive_versions/v10.rs b/packages/rs-platform-version/src/version/drive_versions/v10.rs index e7c917d5470..6d6369fe312 100644 --- a/packages/rs-platform-version/src/version/drive_versions/v10.rs +++ b/packages/rs-platform-version/src/version/drive_versions/v10.rs @@ -99,6 +99,11 @@ use grovedb_version::version::v5::GROVE_V5; /// `DRIVE_VERIFY_METHOD_VERSIONS_V4` sets `single_document.verify_proof_keep_serialized` to /// 1, which verifies the proof of a single document query in its "maybe contested" status. /// +/// * **A single document at a block time** (protocol v15 note 30): +/// `DRIVE_DOCUMENT_METHOD_VERSIONS_V5` sets `query.single_document_path_query` to 1, which +/// stops a lookup in a document's history above the pointer to the latest version, and +/// `verify_proof_keep_serialized` 1 verifies its proof. +/// /// Everything else matches `DRIVE_VERSION_V9`. pub const DRIVE_VERSION_V10: DriveVersion = DriveVersion { methods: DriveMethodVersions { @@ -121,7 +126,7 @@ pub const DRIVE_VERSION_V10: DriveVersion = DriveVersion { }, ..DRIVE_IDENTITY_METHOD_VERSIONS_V2 }, - document: DRIVE_DOCUMENT_METHOD_VERSIONS_V5, // changed in v10: private document type stores, delete estimates + document: DRIVE_DOCUMENT_METHOD_VERSIONS_V5, // changed in v10: private document type stores, delete estimates; a single document at a block time batch_operations: DriveBatchOperationsMethodVersion { apply_drive_operations: 2, // changed in v10: a batch's estimate is resolved (note 14) ..DRIVE_VERSION_V9.methods.batch_operations diff --git a/packages/rs-platform-version/src/version/v15.rs b/packages/rs-platform-version/src/version/v15.rs index f237e71106f..9c9aef034fc 100644 --- a/packages/rs-platform-version/src/version/v15.rs +++ b/packages/rs-platform-version/src/version/v15.rs @@ -590,14 +590,27 @@ pub const PROTOCOL_VERSION_15: ProtocolVersion = 15; /// (`DRIVE_VERIFY_METHOD_VERSIONS_V4`) verifies its proof against the merged query and /// answers with the document from whichever place holds it. Generation 0 asked for the /// absent keys by name, which needs an overall limit the merged query does not have, and -/// so refused every such query. Under `GROVE_V5` (note 26) the query of a document type -/// that keeps history states its cap itself, as the merge no longer derives one above a -/// subquery, and builds the query protocol v14 built. A lookup at a block time is refused -/// in this status. No state transition is proved in this status, so block execution and -/// the proofs of state transitions are unchanged. +/// so refused every such query. The query of a document type that keeps history states +/// its cap itself (`single_document_path_query` 1, `DRIVE_DOCUMENT_METHOD_VERSIONS_V5`), +/// as the merge of `GROVE_V5` (note 26) no longer derives one above a subquery, and builds +/// the query protocol v14 built. No state transition is proved in this status, so block +/// execution and the proofs of state transitions are unchanged. +/// +/// 30. **A single document is looked up at a block time**: in a document type that keeps +/// history, a single document query with a block time asks for the newest version stored +/// at or before that time. A document's history holds one key per time a version was +/// stored and, below them all, the pointer to the latest version at key `[0]`. +/// `single_document_path_query` 1 (`DRIVE_DOCUMENT_METHOD_VERSIONS_V5`) stops the lookup +/// above that pointer. Generation 0 reached it, so a time before the document was first +/// stored answered with the latest version. `verify_proof_keep_serialized` 1 +/// (`DRIVE_VERIFY_METHOD_VERSIONS_V4`) verifies the proof against the query as it is, for +/// a document outside a contest and for one that may be contested. Generation 0 asked for +/// the absent keys by name, which a range of times does not allow, and so refused every +/// such lookup. No state transition is proved at a block time, so block execution and the +/// proofs of state transitions are unchanged. pub const PLATFORM_V15: PlatformVersion = PlatformVersion { protocol_version: PROTOCOL_VERSION_15, - drive: DRIVE_VERSION_V10, // changed: calculate_fee 1 prices a refund at the storing epoch's rate (note 27); apply_contract_with_serialization 1 writes nothing for a contract whose format version 1 bytes match the stored one's (note 8); vote method versions v4: register_identity_vote 1 registers a yes/no vote, remove_all_votes_given_by_identities 1 also removes the yes/no votes of a masternode that left the list, every yes_no method and remove_vote_poll_end_date_query_operations Some(0) make yes/no polls active, add_vote_poll_end_date_query_operations 1 adds only the entry when the batch already queues the end date's tree with other storage flags, and verify methods v4 make the yes/no proof verifiers active (note 10) and verify_private_document_entries Some(0) a page of a private type's store (note 13); state transition method versions v5: document_create_transition 1 deletes a consumed document from what its lookup read (note 11); document method versions v5: insert_empty_private_document_store_operation Some(0) creates a private document type's store, and fetch_private_document_entries and prove_private_document_entries Some(0) read and prove a page of it (note 13); apply_drive_operations 2 resolves a batch's estimate, remove_reference_for_index_level_for_contract_operations 2, stateless_delete_of_non_tree_for_costs 1 and for_total_system_credits_update 1 describe their layers as they are (note 14); create_initial_state_structure 5 adds the token marketplace escrow trees; calculate_total_tokens_balance 2 counts escrowed tokens; the escrow primitives; the identity balance, token balance, prefunded specialized balance and contract fee pot estimations (for_balances 1, for_token_balances 1, estimated_cost_for_prefunded_specialized_balance_update 2, add_estimation_costs_for_contract_fee_pot_update 1) keep a deeper layer description (note 17); fetch_core_fork_activation_height and store_core_fork_activation_height Some(0) keep the Core fork activations (note 18); document method versions v5: append_private_document_entries_operations Some(0) appends a private document create's entries (note 25); grove_version GROVE_V5 (note 26); verify methods v4: verify_proof_keep_serialized 1 verifies a document that may be contested (note 29) + drive: DRIVE_VERSION_V10, // changed: calculate_fee 1 prices a refund at the storing epoch's rate (note 27); apply_contract_with_serialization 1 writes nothing for a contract whose format version 1 bytes match the stored one's (note 8); vote method versions v4: register_identity_vote 1 registers a yes/no vote, remove_all_votes_given_by_identities 1 also removes the yes/no votes of a masternode that left the list, every yes_no method and remove_vote_poll_end_date_query_operations Some(0) make yes/no polls active, add_vote_poll_end_date_query_operations 1 adds only the entry when the batch already queues the end date's tree with other storage flags, and verify methods v4 make the yes/no proof verifiers active (note 10) and verify_private_document_entries Some(0) a page of a private type's store (note 13); state transition method versions v5: document_create_transition 1 deletes a consumed document from what its lookup read (note 11); document method versions v5: insert_empty_private_document_store_operation Some(0) creates a private document type's store, and fetch_private_document_entries and prove_private_document_entries Some(0) read and prove a page of it (note 13); apply_drive_operations 2 resolves a batch's estimate, remove_reference_for_index_level_for_contract_operations 2, stateless_delete_of_non_tree_for_costs 1 and for_total_system_credits_update 1 describe their layers as they are (note 14); create_initial_state_structure 5 adds the token marketplace escrow trees; calculate_total_tokens_balance 2 counts escrowed tokens; the escrow primitives; the identity balance, token balance, prefunded specialized balance and contract fee pot estimations (for_balances 1, for_token_balances 1, estimated_cost_for_prefunded_specialized_balance_update 2, add_estimation_costs_for_contract_fee_pot_update 1) keep a deeper layer description (note 17); fetch_core_fork_activation_height and store_core_fork_activation_height Some(0) keep the Core fork activations (note 18); document method versions v5: append_private_document_entries_operations Some(0) appends a private document create's entries (note 25); grove_version GROVE_V5 (note 26); verify methods v4: verify_proof_keep_serialized 1 verifies a document that may be contested (note 29); document method versions v5: single_document_path_query 1 stops a single document lookup at a block time above the pointer to the latest version, and verify_proof_keep_serialized 1 verifies it (note 30) drive_abci: DriveAbciVersion { structs: DRIVE_ABCI_STRUCTURE_VERSIONS_V2, methods: DRIVE_ABCI_METHOD_VERSIONS_V11, // changed: the yes/no poll's tally, record, clean-up and finish hook are Some(0) (note 10); verify_chain_lock_locally 1 rejects a chain lock locally only when Platform holds the quorums active at its signing height, and verify_chain_lock_through_core 1 has Core's verifychainlock check the others before submitchainlock; consensus_params_update 2 installs the full evidence policy (note 16); update_core_info 1 records the chain locked height at which Core's V24 is first seen active (note 18); build_untied_withdrawal_transactions_from_documents 1 emits asset unlock payload version 2 once V24 is recorded as active (note 20); update_voter_identity 1 re-enables the voter key of the address a masternode returns to (note 22) diff --git a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md index 9ce44319c16..b70ba256dd7 100644 --- a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md +++ b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md @@ -72,7 +72,17 @@ Documents in Drive can have different contested statuses: A `MaybeContested` query looks in both places at once, so its proof has to cover both: a proof made for a `NotContested` or a `Contested` query does not verify against it. Such a proof -verifies from protocol version 15. A `MaybeContested` query with a block time is not supported. +verifies from protocol version 15. + +## Block Time + +In a document type that keeps history, a query with a block time asks for the newest version of +the document stored at or before that time. It answers with no document for a time before the +document was first stored. Without a block time the query asks for the latest version. + +A query with a block time verifies from protocol version 15, in the `NotContested` and +`MaybeContested` statuses. A contest's area keeps no history, so a `Contested` query ignores the +block time, as does a query in a document type that keeps no history. ## API Reference From 938326c60d538c757e81a8c844126c833e89db44 Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 15:45:31 +0700 Subject: [PATCH 6/8] docs(drive): say what the looping maybe contested tests show Co-Authored-By: Claude Fable 5.2 --- packages/rs-drive/src/query/single_document_drive_query.rs | 4 ++++ .../single_document/verify_proof_keep_serialized/v1/mod.rs | 6 ++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/rs-drive/src/query/single_document_drive_query.rs b/packages/rs-drive/src/query/single_document_drive_query.rs index 240829c9d3a..f866d2ee474 100644 --- a/packages/rs-drive/src/query/single_document_drive_query.rs +++ b/packages/rs-drive/src/query/single_document_drive_query.rs @@ -252,6 +252,8 @@ mod tests { } } + /// The cap written at protocol version 15 merges to the query protocol version 14 built, + /// with and without history, so a proof keeps its shape from one version to the next #[test] fn should_build_the_maybe_contested_query_the_protocol_version_before_built() { let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); @@ -270,6 +272,8 @@ mod tests { } } + /// Protocol version 14 does not enter the new branch: it builds the plain merge of the two + /// lookups, with and without a block time #[test] fn should_leave_the_maybe_contested_query_of_protocol_version_14_as_it_was() { let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); diff --git a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs index 28d21911bbe..206b0f7ccc4 100644 --- a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs +++ b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs @@ -390,10 +390,10 @@ mod tests { assert_eq!(found.map(|found| found.id()), Some(document.id())); } + /// Generation 1 is protocol version 15's: the version before keeps refusing a proof that + /// generation 1 accepts, as a whole proof and as a subset #[test] fn should_still_refuse_a_document_that_may_be_contested_at_protocol_version_14() { - // Generation 1 is protocol version 15's. The version before keeps refusing a proof - // that generation 1 accepts. let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); let (drive, contract) = drive_with_contract_at(DPNS, protocol_version_14); let document = domain(&contract, 1, "quantum"); @@ -461,6 +461,8 @@ mod tests { .expect("expected a proof") } + /// A proof made for the not contested or for the contested query shows one place only, so + /// it can not show the document absent from the other, as a whole proof or as a subset #[test] fn should_refuse_a_proof_that_covers_only_one_of_the_two_places() { let platform_version = PlatformVersion::latest(); From 5948001aa0f4d626aee1ae22bc51970440442c41 Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 15:53:47 +0700 Subject: [PATCH 7/8] docs(drive): say what the looping block time tests show Co-Authored-By: Claude Fable 5.2 --- .../single_document/verify_proof_keep_serialized/v1/mod.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs index b743211c59f..a655223d492 100644 --- a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs +++ b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs @@ -381,6 +381,9 @@ mod tests { } } + /// A person stored at time 1000 and changed at time 2000 has no version before 1000, the + /// first from 1000 and the second from 2000, outside a contest and when it may be + /// contested, as a whole proof and as a subset #[test] fn should_find_the_version_of_a_document_stored_at_or_before_a_block_time() { let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); @@ -441,6 +444,8 @@ mod tests { } } + /// A proof shows the newest version at or before its own block time: it does not verify + /// at a time that answers otherwise, as a whole proof or as a subset #[test] fn should_refuse_a_proof_made_for_another_block_time() { let platform_version = PlatformVersion::latest(); @@ -494,7 +499,7 @@ mod tests { } /// Protocol version 14 selects generation 0 of the query and of this verifier, which a - /// lookup at a block time never passed. + /// lookup at a block time never passed, as a whole proof or as a subset #[test] fn should_leave_a_lookup_at_a_block_time_refused_at_protocol_version_14() { let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); From 14df42a7c8067fda18d0cb6379e8cfe6fd66d33c Mon Sep 17 00:00:00 2001 From: QuantumExplorer Date: Tue, 10 Nov 2026 18:16:39 +0700 Subject: [PATCH 8/8] fix(drive): refuse a document with history that may be contested at a block time A contest's area holds each contender as it was submitted, a plain item with no time to compare, so a lookup that may be contested would find a contender submitted after the block time there, and the proof would verify. Generation 1 of the query refuses that lookup again, as #5835 did, until the contest's area can answer at a time. A lookup at a block time outside a contest still works. Tests: the refusal through the query and through the verifier, as a whole proof and as a subset. The block time tests now look outside a contest only. Co-Authored-By: Claude Opus 5.5 --- .../src/query/single_document_drive_query.rs | 33 ++- .../single_document_drive_query/v1/mod.rs | 12 ++ .../verify_proof_keep_serialized/v1/mod.rs | 194 +++++++++--------- .../drive_document_method_versions/mod.rs | 2 +- .../drive_document_method_versions/v5.rs | 3 +- .../drive_verify_method_versions/v4.rs | 6 +- .../src/version/drive_versions/v10.rs | 3 +- .../rs-platform-version/src/version/v15.rs | 14 +- .../README_SINGLE_DOCUMENT.md | 8 +- 9 files changed, 162 insertions(+), 113 deletions(-) diff --git a/packages/rs-drive/src/query/single_document_drive_query.rs b/packages/rs-drive/src/query/single_document_drive_query.rs index c836c1175c6..631762657f3 100644 --- a/packages/rs-drive/src/query/single_document_drive_query.rs +++ b/packages/rs-drive/src/query/single_document_drive_query.rs @@ -111,7 +111,8 @@ impl SingleDocumentDriveQuery { /// version, and one with a block time for the newest version stored at or before that /// time. A lookup at a block time answers so from protocol version 15: before it, a time /// before the document was first stored answers with the latest version, and no proof of - /// such a lookup verifies. + /// such a lookup verifies. From protocol version 15 a document with history that may be + /// contested is refused at a block time, as a contest's area keeps no history. /// /// # Parameters /// @@ -120,8 +121,9 @@ impl SingleDocumentDriveQuery { /// /// # Returns /// - /// The path query, or an error when the version is unknown or the two places a document - /// that may be contested is looked for in can not be merged into one query. + /// The path query, or an error when the version is unknown, the lookup is refused, or the + /// two places a document that may be contested is looked for in can not be merged into one + /// query. pub fn construct_path_query( &self, platform_version: &PlatformVersion, @@ -335,6 +337,31 @@ mod tests { } } + /// A contest's area keeps no history, so a document with history that may be contested + /// can not be looked up at a block time. Without history the time is ignored, as in every + /// status + #[test] + fn should_refuse_a_lookup_at_a_block_time_of_a_document_with_history_that_may_be_contested() { + let result = single_document( + SingleDocumentDriveQueryContestedStatus::MaybeContested, + true, + Some(1500), + ) + .construct_path_query(PlatformVersion::latest()); + + assert!( + matches!(result, Err(Error::Query(QuerySyntaxError::Unsupported(_)))), + "{result:?}" + ); + assert!(single_document( + SingleDocumentDriveQueryContestedStatus::MaybeContested, + false, + Some(1500), + ) + .construct_path_query(PlatformVersion::latest()) + .is_ok()); + } + #[test] fn should_refuse_an_unknown_version_of_the_query() { let mut platform_version = PlatformVersion::latest().clone(); diff --git a/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs b/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs index 4effd96b296..e5f8e1911c2 100644 --- a/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs +++ b/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs @@ -1,3 +1,4 @@ +use crate::error::query::QuerySyntaxError; use crate::error::Error; use crate::query::{Query, SingleDocumentDriveQuery, SingleDocumentDriveQueryContestedStatus}; use crate::util::common::encode::encode_u64; @@ -20,6 +21,10 @@ impl SingleDocumentDriveQuery { /// 2 (`GROVE_V5`, which protocol version 15 is the first to select), where the generation /// before turned that limit into the cap of the merged branch. Written as that cap here, it /// merges to the query generation 0 built. + /// + /// Such a lookup at a block time is refused. A contest's area keeps no history: it holds + /// each contender as it was submitted, with no time to compare, so a document submitted + /// after the block time would be found there. #[inline(always)] pub(super) fn construct_path_query_v1( &self, @@ -30,6 +35,13 @@ impl SingleDocumentDriveQuery { Ok(self.construct_non_contested_path_query_v1()) } SingleDocumentDriveQueryContestedStatus::MaybeContested => { + if self.document_type_keeps_history && self.block_time_ms.is_some() { + return Err(Error::Query(QuerySyntaxError::Unsupported( + "a document with history that may be contested can not be looked up at \ + a block time" + .to_string(), + ))); + } let mut non_contested = self.construct_non_contested_path_query_v1(); let contested = self.construct_contested_path_query(true); if self.document_type_keeps_history { diff --git a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs index b37844bd953..fd9b95b9399 100644 --- a/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs +++ b/packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs @@ -7,7 +7,9 @@ use platform_version::version::PlatformVersion; impl SingleDocumentDriveQuery { /// Generation 0, except that two kinds of lookup it refused are verified: a document that - /// may be contested, and a document at a block time in a type that keeps history. + /// may be contested, and a document outside a contest at a block time in a type that keeps + /// history. A document with history that may be contested is not looked up at a block time: + /// the query refuses it, as a contest's area keeps no history. /// /// Generation 0 asks GroveDB to name the keys that are absent. That needs an overall limit /// and keys that can be listed. A query for a document that may be contested looks in two @@ -28,7 +30,7 @@ impl SingleDocumentDriveQuery { !(self.document_type_keeps_history && self.block_time_ms.is_some()) } SingleDocumentDriveQueryContestedStatus::MaybeContested => false, - // A contest's area keeps no history, so its query has no block time + // A contest's area keeps no history, and its query takes no block time SingleDocumentDriveQueryContestedStatus::Contested => true, }; if verified_by_generation_0 { @@ -66,6 +68,7 @@ mod tests { use crate::drive::votes::resolved::vote_polls::contested_document_resource_vote_poll::ContestedDocumentResourceVotePollWithContractInfo; use crate::drive::Drive; use crate::error::proof::ProofError; + use crate::error::query::QuerySyntaxError; use crate::error::Error; use crate::query::{SingleDocumentDriveQuery, SingleDocumentDriveQueryContestedStatus}; use crate::util::object_size_info::DocumentInfo::DocumentRefInfo; @@ -369,59 +372,47 @@ mod tests { ); } - /// The query of the person `document_id` as it stood at `block_time_ms`. + /// The query of the person `document_id` as it stood at `block_time_ms`, outside a contest. fn person_at_block_time( contract: &DataContract, document_id: [u8; 32], block_time_ms: u64, - contested_status: SingleDocumentDriveQueryContestedStatus, ) -> SingleDocumentDriveQuery { SingleDocumentDriveQuery { - contested_status, + contested_status: SingleDocumentDriveQueryContestedStatus::NotContested, ..maybe_contested(contract, "person", document_id, Some(block_time_ms)) } } /// A person stored at time 1000 and changed at time 2000 has no version before 1000, the - /// first from 1000 and the second from 2000, outside a contest and when it may be - /// contested, as a whole proof and as a subset + /// first from 1000 and the second from 2000, as a whole proof and as a subset #[test] fn should_find_the_version_of_a_document_stored_at_or_before_a_block_time() { let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); let (first, second) = person_with_two_versions(&drive, &contract); - for contested_status in [ - SingleDocumentDriveQueryContestedStatus::NotContested, - SingleDocumentDriveQueryContestedStatus::MaybeContested, + for (block_time_ms, expected) in [ + // Before the document was first stored there is no version of it + (0, None), + (999, None), + (1000, Some(&first)), + (1500, Some(&first)), + (1999, Some(&first)), + (2000, Some(&second)), + (2500, Some(&second)), + (u64::MAX, Some(&second)), ] { - for (block_time_ms, expected) in [ - // Before the document was first stored there is no version of it - (0, None), - (999, None), - (1000, Some(&first)), - (1500, Some(&first)), - (1999, Some(&first)), - (2000, Some(&second)), - (2500, Some(&second)), - (u64::MAX, Some(&second)), - ] { - let found = prove_and_verify( - &drive, - &contract, - &person_at_block_time( - &contract, - first.id().to_buffer(), - block_time_ms, - contested_status.clone(), - ), - ); + let found = prove_and_verify( + &drive, + &contract, + &person_at_block_time(&contract, first.id().to_buffer(), block_time_ms), + ); - assert_eq!( - found.map(|found| serialized(&found, &contract)), - expected.map(|expected| serialized(expected, &contract)), - "{contested_status:?} at block time {block_time_ms}" - ); - } + assert_eq!( + found.map(|found| serialized(&found, &contract)), + expected.map(|expected| serialized(expected, &contract)), + "at block time {block_time_ms}" + ); } } @@ -431,18 +422,13 @@ mod tests { // Another document, so the type holds a history the proof must tell apart person_with_two_versions(&drive, &contract); - for contested_status in [ - SingleDocumentDriveQueryContestedStatus::NotContested, - SingleDocumentDriveQueryContestedStatus::MaybeContested, - ] { - let found = prove_and_verify( - &drive, - &contract, - &person_at_block_time(&contract, [9; 32], 1500, contested_status.clone()), - ); + let found = prove_and_verify( + &drive, + &contract, + &person_at_block_time(&contract, [9; 32], 1500), + ); - assert_eq!(found, None, "{contested_status:?}"); - } + assert_eq!(found, None); } /// A proof shows the newest version at or before its own block time: it does not verify @@ -453,52 +439,75 @@ mod tests { let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); let (first, _) = person_with_two_versions(&drive, &contract); - for contested_status in [ - SingleDocumentDriveQueryContestedStatus::NotContested, - SingleDocumentDriveQueryContestedStatus::MaybeContested, - ] { - // Each pair of times answers with a different version, or with none for one of them - for (proved_block_time_ms, verified_block_time_ms) in - [(1500, 2500), (2500, 1500), (500, 1500), (1500, 500)] - { - let proved = person_at_block_time( - &contract, - first.id().to_buffer(), - proved_block_time_ms, - contested_status.clone(), + // Each pair of times answers with a different version, or with none for one of them + for (proved_block_time_ms, verified_block_time_ms) in + [(1500, 2500), (2500, 1500), (500, 1500), (1500, 500)] + { + let proved = + person_at_block_time(&contract, first.id().to_buffer(), proved_block_time_ms); + let proof = drive + .grove_get_proved_path_query( + &proved + .construct_path_query(platform_version) + .expect("expected to build the query"), + None, + &mut vec![], + &platform_version.drive, + ) + .expect("expected a proof"); + let verified = SingleDocumentDriveQuery { + block_time_ms: Some(verified_block_time_ms), + ..proved + }; + + for is_subset in [false, true] { + assert!( + verified + .verify_proof_keep_serialized(is_subset, proof.as_slice(), platform_version) + .is_err(), + "a proof at {proved_block_time_ms} verified at {verified_block_time_ms}, \ + is_subset {is_subset}" ); - let proof = drive - .grove_get_proved_path_query( - &proved - .construct_path_query(platform_version) - .expect("expected to build the query"), - None, - &mut vec![], - &platform_version.drive, - ) - .expect("expected a proof"); - let verified = SingleDocumentDriveQuery { - block_time_ms: Some(verified_block_time_ms), - ..proved - }; - - for is_subset in [false, true] { - assert!( - verified - .verify_proof_keep_serialized( - is_subset, - proof.as_slice(), - platform_version - ) - .is_err(), - "{contested_status:?}, a proof at {proved_block_time_ms} verified at \ - {verified_block_time_ms}, is_subset {is_subset}" - ); - } } } } + /// A contest's area holds each contender as it was submitted, with no time to compare, so + /// a contender submitted after the block time would be found there. A document with + /// history that may be contested is refused at a block time, before any proof is read, as + /// a whole proof and as a subset + #[test] + fn should_refuse_to_look_up_a_document_with_history_that_may_be_contested_at_a_block_time() { + let platform_version = PlatformVersion::latest(); + let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); + let (first, _) = person_with_two_versions(&drive, &contract); + let outside_a_contest = person_at_block_time(&contract, first.id().to_buffer(), 1500); + let proof = drive + .grove_get_proved_path_query( + &outside_a_contest + .construct_path_query(platform_version) + .expect("expected to build the query"), + None, + &mut vec![], + &platform_version.drive, + ) + .expect("expected a proof"); + let query = SingleDocumentDriveQuery { + contested_status: SingleDocumentDriveQueryContestedStatus::MaybeContested, + ..outside_a_contest + }; + + for is_subset in [false, true] { + let result = + query.verify_proof_keep_serialized(is_subset, proof.as_slice(), platform_version); + + assert!( + matches!(result, Err(Error::Query(QuerySyntaxError::Unsupported(_)))), + "is_subset {is_subset}: {result:?}" + ); + } + } + /// Protocol version 14 selects generation 0 of the query and of this verifier, which a /// lookup at a block time never passed, as a whole proof or as a subset #[test] @@ -506,12 +515,7 @@ mod tests { let protocol_version_14 = PlatformVersion::get(14).expect("expected protocol version 14"); let (drive, contract) = drive_with_contract_at(FAMILY_WITH_HISTORY, protocol_version_14); let (first, _) = person_with_two_versions_at(&drive, &contract, protocol_version_14); - let query = person_at_block_time( - &contract, - first.id().to_buffer(), - 1500, - SingleDocumentDriveQueryContestedStatus::NotContested, - ); + let query = person_at_block_time(&contract, first.id().to_buffer(), 1500); let proof = drive .grove_get_proved_path_query( &query diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs index 03158de2e51..c000cf89f32 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/mod.rs @@ -148,7 +148,7 @@ pub struct DriveDocumentQueryMethodVersions { /// above the pointer to the latest version, so it answers with the newest version stored /// at or before that time and with nothing before the first, and one of a document that /// may be contested states its cap itself, which GroveDB's merge no longer derives above - /// a subquery. + /// a subquery, and is refused at a block time, as a contest's area keeps no history. pub single_document_path_query: FeatureVersion, } diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs index 06bc7f48e5f..9caf31288e0 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_document_method_versions/v5.rs @@ -27,7 +27,8 @@ use crate::version::drive_versions::drive_document_method_versions::{ /// entries name whoever the document's storage flags name. /// * `query.single_document_path_query` is 1: in a document type that keeps history, the lookup /// of a single document at a block time stops above the pointer to the latest version, and -/// the lookup of a document that may be contested states its cap itself. +/// the lookup of a document that may be contested states its cap itself and is refused at a +/// block time. pub const DRIVE_DOCUMENT_METHOD_VERSIONS_V5: DriveDocumentMethodVersions = DriveDocumentMethodVersions { insert_empty_private_document_store_operation: Some(0), // changed: a private document type's store is created with it diff --git a/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs b/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs index 2b5d7c3e88b..65e5395e661 100644 --- a/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs +++ b/packages/rs-platform-version/src/version/drive_versions/drive_verify_method_versions/v4.rs @@ -10,8 +10,8 @@ use crate::version::drive_versions::drive_verify_method_versions::{ /// (`None`, not active, in every earlier table), and so is /// `document.verify_private_document_entries`, with private document types. /// `single_document.verify_proof_keep_serialized` is 1: a document that may be contested is -/// verified, and so is a document at a block time in a type that keeps history, where -/// generation 0 refused every such query. Everything else matches +/// verified, and so is a document outside a contest at a block time in a type that keeps +/// history, where generation 0 refused every such query. Everything else matches /// `DRIVE_VERIFY_METHOD_VERSIONS_V3`. pub const DRIVE_VERIFY_METHOD_VERSIONS_V4: DriveVerifyMethodVersions = DriveVerifyMethodVersions { voting: DriveVerifyVoteMethodVersions { @@ -25,7 +25,7 @@ pub const DRIVE_VERIFY_METHOD_VERSIONS_V4: DriveVerifyMethodVersions = DriveVeri ..DRIVE_VERIFY_METHOD_VERSIONS_V3.document }, single_document: DriveVerifySingleDocumentMethodVersions { - verify_proof_keep_serialized: 1, // changed: verifies a document that may be contested, and one at a block time + verify_proof_keep_serialized: 1, // changed: verifies a document that may be contested, and one outside a contest at a block time ..DRIVE_VERIFY_METHOD_VERSIONS_V3.single_document }, ..DRIVE_VERIFY_METHOD_VERSIONS_V3 diff --git a/packages/rs-platform-version/src/version/drive_versions/v10.rs b/packages/rs-platform-version/src/version/drive_versions/v10.rs index 6d6369fe312..68fc9fb7489 100644 --- a/packages/rs-platform-version/src/version/drive_versions/v10.rs +++ b/packages/rs-platform-version/src/version/drive_versions/v10.rs @@ -102,7 +102,8 @@ use grovedb_version::version::v5::GROVE_V5; /// * **A single document at a block time** (protocol v15 note 30): /// `DRIVE_DOCUMENT_METHOD_VERSIONS_V5` sets `query.single_document_path_query` to 1, which /// stops a lookup in a document's history above the pointer to the latest version, and -/// `verify_proof_keep_serialized` 1 verifies its proof. +/// `verify_proof_keep_serialized` 1 verifies its proof outside a contest. A document with +/// history that may be contested is refused at a block time. /// /// Everything else matches `DRIVE_VERSION_V9`. pub const DRIVE_VERSION_V10: DriveVersion = DriveVersion { diff --git a/packages/rs-platform-version/src/version/v15.rs b/packages/rs-platform-version/src/version/v15.rs index bd6c5b4b05d..d21e693ef7d 100644 --- a/packages/rs-platform-version/src/version/v15.rs +++ b/packages/rs-platform-version/src/version/v15.rs @@ -603,12 +603,14 @@ pub const PROTOCOL_VERSION_15: ProtocolVersion = 15; /// `single_document_path_query` 1 (`DRIVE_DOCUMENT_METHOD_VERSIONS_V5`) stops the lookup /// above that pointer. Generation 0 reached it, so a time before the document was first /// stored answered with the latest version. `verify_proof_keep_serialized` 1 -/// (`DRIVE_VERIFY_METHOD_VERSIONS_V4`) verifies the proof against the query as it is, for -/// a document outside a contest and for one that may be contested. Generation 0 asked for -/// the absent keys by name, which a range of times does not allow, and so refused every -/// such lookup. A document type without history has one version and ignores the time, as -/// it does at every protocol version. No state transition is proved at a block time, so -/// block execution and the proofs of state transitions are unchanged. +/// (`DRIVE_VERIFY_METHOD_VERSIONS_V4`) verifies the proof against the query as it is. +/// Generation 0 asked for the absent keys by name, which a range of times does not allow, +/// and so refused every such lookup. A document with history that may be contested is +/// refused at a block time: a contest's area keeps no history, so a contender submitted +/// after the time would be found there. A document type without history has one version +/// and ignores the time, as it does at every protocol version. No state transition is +/// proved at a block time, so block execution and the proofs of state transitions are +/// unchanged. pub const PLATFORM_V15: PlatformVersion = PlatformVersion { protocol_version: PROTOCOL_VERSION_15, drive: DRIVE_VERSION_V10, // changed: calculate_fee 1 prices a refund at the storing epoch's rate (note 27); apply_contract_with_serialization 1 writes nothing for a contract whose format version 1 bytes match the stored one's (note 8); vote method versions v4: register_identity_vote 1 registers a yes/no vote, remove_all_votes_given_by_identities 1 also removes the yes/no votes of a masternode that left the list, every yes_no method and remove_vote_poll_end_date_query_operations Some(0) make yes/no polls active, add_vote_poll_end_date_query_operations 1 adds only the entry when the batch already queues the end date's tree with other storage flags, and verify methods v4 make the yes/no proof verifiers active (note 10) and verify_private_document_entries Some(0) a page of a private type's store (note 13); state transition method versions v5: document_create_transition 1 deletes a consumed document from what its lookup read (note 11); document method versions v5: insert_empty_private_document_store_operation Some(0) creates a private document type's store, and fetch_private_document_entries and prove_private_document_entries Some(0) read and prove a page of it (note 13); apply_drive_operations 2 resolves a batch's estimate, remove_reference_for_index_level_for_contract_operations 2, stateless_delete_of_non_tree_for_costs 1 and for_total_system_credits_update 1 describe their layers as they are (note 14); create_initial_state_structure 5 adds the token marketplace escrow trees; calculate_total_tokens_balance 2 counts escrowed tokens; the escrow primitives; the identity balance, token balance, prefunded specialized balance and contract fee pot estimations (for_balances 1, for_token_balances 1, estimated_cost_for_prefunded_specialized_balance_update 2, add_estimation_costs_for_contract_fee_pot_update 1) keep a deeper layer description (note 17); fetch_core_fork_activation_height and store_core_fork_activation_height Some(0) keep the Core fork activations (note 18); document method versions v5: append_private_document_entries_operations Some(0) appends a private document create's entries (note 25); grove_version GROVE_V5 (note 26); verify methods v4: verify_proof_keep_serialized 1 verifies a document that may be contested (note 29); document method versions v5: single_document_path_query 1 stops a single document lookup at a block time above the pointer to the latest version, and verify_proof_keep_serialized 1 verifies it (note 30) diff --git a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md index 64fdb8be128..d4e2b442869 100644 --- a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md +++ b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md @@ -80,9 +80,11 @@ In a document type that keeps history, a query with a block time asks for the ne the document stored at or before that time. It answers with no document for a time before the document was first stored. Without a block time the query asks for the latest version. -A query with a block time verifies from protocol version 15, in the `NotContested` and -`MaybeContested` statuses. A contest's area keeps no history, so a `Contested` query ignores the -block time, as does a query in a document type that keeps no history. +A `NotContested` query with a block time verifies from protocol version 15. A contest's area +keeps no history: it holds each contender as it was submitted. So a `Contested` query ignores the +block time, and a `MaybeContested` query with a block time is refused, since a contender +submitted after that time would be found there. A query in a document type that keeps no +history ignores the block time in every status. ## API Reference