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 f866d2ee474..631762657f3 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,100 +104,45 @@ 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. 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 + /// + /// - `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, 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, ) -> 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 with history 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)) - } - } - } - - /// 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]); - } + 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, + })), } - - 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)) } } @@ -215,6 +159,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 +170,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 +186,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,18 +197,60 @@ mod tests { document_type_keeps_history, document_id: [9; 32], block_time_ms, - contested_status: SingleDocumentDriveQueryContestedStatus::MaybeContested, + contested_status, } } - /// 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 + /// 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, + ) + }) + }) + }) + } + + /// Generation 1 changes one lookup only, at a block time in a document type that keeps + /// history. Every other query is the one protocol version 14 built, the capped one of a + /// document that may be contested included, 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() { + 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()) @@ -267,18 +258,43 @@ 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:?}" ); } } - /// Protocol version 14 does not enter the new branch: it builds the plain merge of the two - /// lookups, with and without a block time + /// Protocol version 14 selects generation 0, whose range takes every key up to the block + /// time, the pointer to the latest version at `[0]` included + #[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"); + 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 + ); + } + + /// Protocol version 14 selects generation 0 for a document that may be contested too: 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"); 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 @@ -298,14 +314,81 @@ 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}" + ); + } + } + + /// 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(); + 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::Drive(DriveError::UnknownVersionMismatch { method, known_versions, received })) + if method == "SingleDocumentDriveQuery::construct_path_query" + && known_versions == &vec![0, 1] + && *received == 255 + ), + "{result:?}" + ); } /// A create stating a contest fund is looked for in the contest's area, while a decision 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..e5f8e1911c2 --- /dev/null +++ b/packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs @@ -0,0 +1,85 @@ +use crate::error::query::QuerySyntaxError; +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. + /// + /// 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, + platform_version: &PlatformVersion, + ) -> Result { + match self.contested_status { + SingleDocumentDriveQueryContestedStatus::NotContested => { + 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 { + 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 4029d24df6d..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 @@ -6,14 +6,18 @@ 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 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. /// - /// 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 +25,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, and its query takes 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 +43,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() )))); } @@ -286,7 +299,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"); @@ -352,18 +372,173 @@ mod tests { ); } + /// 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, + ) -> SingleDocumentDriveQuery { + SingleDocumentDriveQuery { + 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, as a whole proof and as a subset #[test] - fn should_refuse_to_look_up_a_document_that_may_be_contested_at_a_block_time() { + 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, _) = person_with_two_versions(&drive, &contract); + let (first, second) = person_with_two_versions(&drive, &contract); + + 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), + ); - let result = maybe_contested(&contract, "person", first.id().to_buffer(), Some(1500)) - .construct_path_query(PlatformVersion::latest()); + assert_eq!( + found.map(|found| serialized(&found, &contract)), + expected.map(|expected| serialized(expected, &contract)), + "at block time {block_time_ms}" + ); + } + } + + #[test] + 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); - assert!( - matches!(result, Err(Error::Query(QuerySyntaxError::Unsupported(_)))), - "{result:?}" + let found = prove_and_verify( + &drive, + &contract, + &person_at_block_time(&contract, [9; 32], 1500), ); + + assert_eq!(found, None); + } + + /// 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(); + let (drive, contract) = drive_with_contract(FAMILY_WITH_HISTORY); + let (first, _) = person_with_two_versions(&drive, &contract); + + // 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}" + ); + } + } + } + + /// 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] + 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); + 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 more than the document's query, the document together with an identity's 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..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 @@ -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, and is refused at a block time, as a contest's area keeps no history. + 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..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 @@ -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,20 @@ 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 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 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..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,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 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 { @@ -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 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 e7c917d5470..97523299aa8 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,12 @@ 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 31): +/// `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 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 { methods: DriveMethodVersions { @@ -121,7 +127,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 a90c6dc8541..611d6f5d769 100644 --- a/packages/rs-platform-version/src/version/v15.rs +++ b/packages/rs-platform-version/src/version/v15.rs @@ -590,12 +590,11 @@ 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. 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. +/// 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 chain asset lock proof is not held to the input cap**: the asset lock transaction /// an instant proof embeds, with its InstantSend lock, may carry at most @@ -611,9 +610,25 @@ pub const PROTOCOL_VERSION_15: ProtocolVersion = 15; /// proof gets the verdict and the error it got before. Both refusals are unpaid. Protocol /// v14 and earlier keep both at 0, so the blocks committed under them replay with the same /// verdicts. +/// +/// 31. **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. +/// 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) + 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 31) 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 377a168693f..d4e2b442869 100644 --- a/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md +++ b/packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md @@ -74,10 +74,17 @@ A `MaybeContested` query looks in both places at once, so its proof has to cover made for a `NotContested` or a `Contested` query does not verify against it. Such a proof 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. +## 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 `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