From f6fe3731b019acfddcc70f8362f51dddb3bb7f77 Mon Sep 17 00:00:00 2001 From: Ivan Shumkov Date: Thu, 12 Nov 2026 00:32:24 +0700 Subject: [PATCH 1/3] test(drive-abci): run the consume tests at protocol versions 14 and 15 and pin consume fees MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document reference validation 0 and the create conversion 0 are still what protocol version 14 runs. #5360 moved the consume tests to PlatformVersion::latest(), which now selects generation 1, so no test ran generation 0's contested arm (a ForceDeleteDocument for each consumed document). Breaking that arm would have left CI green. The plain, onlyWhenConsumed, contested and shared-bucket (ticket) consume tests now run at protocol versions 14 and 15. should_pin_the_fees_of_a_consume_through_a_plain_and_a_contested_create pins the processing fee, the storage fee and the commitment owner's refund at both versions. The DPNS v3 consume tests stay at latest(): DPNS v3 exists only from protocol version 15. Test would have caught a broken generation-0 contested arm. With the arm's delete loop skipped: - ✖ should_consume_a_commitment_its_owner_can_not_delete_through_a_contested_create fails with "expected the commitment consumed at 14". - ✖ the fee pin fails on its 14 row (refund 0, processing 2_600_980 where 3_489_420 is pinned). - The 15 row is unchanged, which is why the latest()-only tests missed the break. ✔ Both pass once the arm is restored. Co-Authored-By: Claude Opus 5.5 --- .../tests/document/commit_reveal_lookup.rs | 436 +++++++++++------- 1 file changed, 280 insertions(+), 156 deletions(-) diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs index 0e9bd5e85c5..783ace4b8a2 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs @@ -644,148 +644,267 @@ mod commit_reveal_lookup_tests { ); } + /// The protocol versions a consume is pinned at: 14 runs document reference validation 0 + /// and the create conversion 0, which delete a consumed document by its id, and 15 runs + /// their generation 1, which deletes it from what its lookup read. + const CONSUME_PROTOCOL_VERSIONS: [u32; 2] = [14, 15]; + + /// The fixture contract with a `preorder` only a consume deletes + /// (`canBeDeleted: "onlyWhenConsumed"`). + fn preorder_only_consumed(contract: &mut serde_json::Value) { + contract["documentSchemas"]["preorder"]["canBeDeleted"] = + serde_json::json!("onlyWhenConsumed"); + } + + /// [`preorder_only_consumed`], with a `domain` contested by its normalized label, so a + /// reveal joins a contest and its consumed commitments are deleted beside the contest's own + /// trees rather than with a plain insert. + fn contested_domain_and_preorder_only_consumed(contract: &mut serde_json::Value) { + preorder_only_consumed(contract); + contract["documentSchemas"]["domain"]["indices"] = serde_json::json!([{ + "name": "byNormalizedLabel", + "properties": [{ "normalizedLabel": "asc" }], + "unique": true, + "contested": { + "fieldMatches": [ + { "field": "normalizedLabel", "regexPattern": "^[a-zA-Z01-]{3,19}$" } + ], + "resolution": 0 + } + }]); + } + #[tokio::test] async fn should_create_a_domain_revealing_its_writers_old_enough_commitment_and_consume_it() { - let mut fixture = CommitRevealFixture::new(); - let alice = fixture.id(Who::Alice); - let salt = [0x11; 32]; - let preorder = fixture - .commit(Who::Alice, salt, "al1ce.dash", COMMIT_HEIGHT) - .await; - assert!(fixture.preorder_exists(preorder.id())); + for protocol_version in CONSUME_PROTOCOL_VERSIONS { + let mut fixture = CommitRevealFixture::new_at( + PlatformVersion::get(protocol_version).expect("expected the platform version"), + |_| {}, + ); + let alice = fixture.id(Who::Alice); + let salt = [0x11; 32]; + let preorder = fixture + .commit(Who::Alice, salt, "al1ce.dash", COMMIT_HEIGHT) + .await; + assert!(fixture.preorder_exists(preorder.id())); - let result = fixture - .reveal_domain( - Who::Alice, - subdomain("Alice", "al1ce", "dash", salt), - &[], - REVEAL_HEIGHT, - ) - .await; + let result = fixture + .reveal_domain( + Who::Alice, + subdomain("Alice", "al1ce", "dash", salt), + &[], + REVEAL_HEIGHT, + ) + .await; - let StateTransitionExecutionResult::SuccessfulExecution { fee_result, .. } = result else { - panic!("expected the reveal to be accepted, got {result:?}"); - }; - // The commitment is gone, deleted with the create, and its storage is - // refunded to its owner, the writer - assert!(!fixture.preorder_exists(preorder.id())); - assert!( - fee_result - .fee_refunds - .calculate_refunds_amount_for_identity(alice) - .is_some_and(|refund| refund > 0), - "expected the consumed commitment's storage to be refunded to its owner" - ); + let StateTransitionExecutionResult::SuccessfulExecution { fee_result, .. } = result + else { + panic!("expected the reveal to be accepted at {protocol_version}, got {result:?}"); + }; + // The commitment is gone, deleted with the create, and its storage is + // refunded to its owner, the writer + assert!( + !fixture.preorder_exists(preorder.id()), + "expected the commitment consumed at {protocol_version}" + ); + assert!( + fee_result + .fee_refunds + .calculate_refunds_amount_for_identity(alice) + .is_some_and(|refund| refund > 0), + "expected the consumed commitment's storage to be refunded to its owner at \ + {protocol_version}" + ); - // A second reveal of the same commitment finds nothing - let result = fixture - .reveal_domain( - Who::Alice, - subdomain("Alice", "al1ce", "dash", salt), - &[], - REVEAL_HEIGHT + 1, - ) - .await; - assert_no_commitment(result, revealed_key(salt, "al1ce", "dash")); + // A second reveal of the same commitment finds nothing + let result = fixture + .reveal_domain( + Who::Alice, + subdomain("Alice", "al1ce", "dash", salt), + &[], + REVEAL_HEIGHT + 1, + ) + .await; + assert_no_commitment(result, revealed_key(salt, "al1ce", "dash")); + } } /// `canBeDeleted: "onlyWhenConsumed"` on the commitment: its owner can not take it back /// with a delete, and the reveal still consumes it. #[tokio::test] async fn should_consume_a_commitment_its_owner_can_not_delete() { - let mut fixture = CommitRevealFixture::new_with(|contract| { - contract["documentSchemas"]["preorder"]["canBeDeleted"] = - serde_json::json!("onlyWhenConsumed"); - }); - let alice = fixture.id(Who::Alice); - let salt = [0x15; 32]; - let preorder = fixture - .commit(Who::Alice, salt, "al1ce.dash", COMMIT_HEIGHT) - .await; + for protocol_version in CONSUME_PROTOCOL_VERSIONS { + let mut fixture = CommitRevealFixture::new_at( + PlatformVersion::get(protocol_version).expect("expected the platform version"), + preorder_only_consumed, + ); + let alice = fixture.id(Who::Alice); + let salt = [0x15; 32]; + let preorder = fixture + .commit(Who::Alice, salt, "al1ce.dash", COMMIT_HEIGHT) + .await; - let result = fixture - .delete(Who::Alice, "preorder", &preorder, COMMIT_HEIGHT) - .await; - assert_matches!( - result, - StateTransitionExecutionResult::PaidConsensusError { - error: ConsensusError::BasicError( - BasicError::InvalidDocumentTransitionActionError(_) - ), - .. - } - ); - assert!(fixture.preorder_exists(preorder.id())); + let result = fixture + .delete(Who::Alice, "preorder", &preorder, COMMIT_HEIGHT) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::PaidConsensusError { + error: ConsensusError::BasicError( + BasicError::InvalidDocumentTransitionActionError(_) + ), + .. + }, + "expected the owner's delete refused at {protocol_version}" + ); + assert!(fixture.preorder_exists(preorder.id())); - let result = fixture - .reveal_domain( - Who::Alice, - subdomain("Alice", "al1ce", "dash", salt), - &[], - REVEAL_HEIGHT, - ) - .await; - let StateTransitionExecutionResult::SuccessfulExecution { fee_result, .. } = result else { - panic!("expected the reveal to be accepted, got {result:?}"); - }; - // Consumed as a delete by its owner would be: gone, its storage refunded to its owner - assert!(!fixture.preorder_exists(preorder.id())); - assert!( - fee_result - .fee_refunds - .calculate_refunds_amount_for_identity(alice) - .is_some_and(|refund| refund > 0), - "expected the consumed commitment's storage to be refunded to its owner" - ); + let result = fixture + .reveal_domain( + Who::Alice, + subdomain("Alice", "al1ce", "dash", salt), + &[], + REVEAL_HEIGHT, + ) + .await; + let StateTransitionExecutionResult::SuccessfulExecution { fee_result, .. } = result + else { + panic!("expected the reveal to be accepted at {protocol_version}, got {result:?}"); + }; + // Consumed as a delete by its owner would be: gone, its storage refunded to its + // owner + assert!( + !fixture.preorder_exists(preorder.id()), + "expected the commitment consumed at {protocol_version}" + ); + assert!( + fee_result + .fee_refunds + .calculate_refunds_amount_for_identity(alice) + .is_some_and(|refund| refund > 0), + "expected the consumed commitment's storage to be refunded to its owner at \ + {protocol_version}" + ); + } } /// The same through a contested create, whose consumed commitments are deleted beside /// the contest's own trees rather than with a plain insert. #[tokio::test] async fn should_consume_a_commitment_its_owner_can_not_delete_through_a_contested_create() { - let mut fixture = CommitRevealFixture::new_with(|contract| { - contract["documentSchemas"]["preorder"]["canBeDeleted"] = - serde_json::json!("onlyWhenConsumed"); - contract["documentSchemas"]["domain"]["indices"] = serde_json::json!([{ - "name": "byNormalizedLabel", - "properties": [{ "normalizedLabel": "asc" }], - "unique": true, - "contested": { - "fieldMatches": [ - { "field": "normalizedLabel", "regexPattern": "^[a-zA-Z01-]{3,19}$" } - ], - "resolution": 0 - } - }]); - }); - let alice = fixture.id(Who::Alice); - let salt = [0x16; 32]; - let preorder = fixture - .commit(Who::Alice, salt, "al1ce.dash", COMMIT_HEIGHT) - .await; + for protocol_version in CONSUME_PROTOCOL_VERSIONS { + let mut fixture = CommitRevealFixture::new_at( + PlatformVersion::get(protocol_version).expect("expected the platform version"), + contested_domain_and_preorder_only_consumed, + ); + let alice = fixture.id(Who::Alice); + let salt = [0x16; 32]; + let preorder = fixture + .commit(Who::Alice, salt, "al1ce.dash", COMMIT_HEIGHT) + .await; - let (domain, result) = fixture - .create( - Who::Alice, - "domain", - &subdomain("Alice", "al1ce", "dash", salt), - &[], - REVEAL_HEIGHT, - ) - .await; - let StateTransitionExecutionResult::SuccessfulExecution { fee_result, .. } = result else { - panic!("expected the contested reveal to be accepted, got {result:?}"); - }; - // The domain waits in its contest, not in the type's storage, and the commitment is - // consumed, its storage refunded to its owner - assert!(!fixture.document_exists("domain", domain.id())); - assert!(!fixture.preorder_exists(preorder.id())); - assert!( - fee_result - .fee_refunds - .calculate_refunds_amount_for_identity(alice) - .is_some_and(|refund| refund > 0), - "expected the consumed commitment's storage to be refunded to its owner" + let (domain, result) = fixture + .create( + Who::Alice, + "domain", + &subdomain("Alice", "al1ce", "dash", salt), + &[], + REVEAL_HEIGHT, + ) + .await; + let StateTransitionExecutionResult::SuccessfulExecution { fee_result, .. } = result + else { + panic!( + "expected the contested reveal to be accepted at {protocol_version}, got \ + {result:?}" + ); + }; + // The domain waits in its contest, not in the type's storage, and the commitment is + // consumed, its storage refunded to its owner + assert!(!fixture.document_exists("domain", domain.id())); + assert!( + !fixture.preorder_exists(preorder.id()), + "expected the commitment consumed at {protocol_version}" + ); + assert!( + fee_result + .fee_refunds + .calculate_refunds_amount_for_identity(alice) + .is_some_and(|refund| refund > 0), + "expected the consumed commitment's storage to be refunded to its owner at \ + {protocol_version}" + ); + } + } + + /// The fees of a reveal consuming its commitment, through a plain and through a contested + /// create: the processing fee, the storage fee and the refund of the consumed commitment's + /// storage to its owner. At 15 the create deletes the commitment from what its lookup read, + /// so it pays one read of it fewer than at 14; the storage fee and the refund are the same. + #[tokio::test] + async fn should_pin_the_fees_of_a_consume_through_a_plain_and_a_contested_create() { + // A fee of a reveal: processing, storage, and the refund to the commitment's owner + type Fees = (Credits, Credits, Credits); + let mut measured: Vec<(u32, Fees, Fees)> = Vec::new(); + for protocol_version in CONSUME_PROTOCOL_VERSIONS { + let platform_version = + PlatformVersion::get(protocol_version).expect("expected the platform version"); + let mut fees = Vec::new(); + for contested in [false, true] { + let mut fixture = CommitRevealFixture::new_at(platform_version, |contract| { + if contested { + contested_domain_and_preorder_only_consumed(contract) + } else { + preorder_only_consumed(contract) + } + }); + let alice = fixture.id(Who::Alice); + let salt = [0x17; 32]; + fixture + .commit(Who::Alice, salt, "al1ce.dash", COMMIT_HEIGHT) + .await; + let result = fixture + .reveal_domain( + Who::Alice, + subdomain("Alice", "al1ce", "dash", salt), + &[], + REVEAL_HEIGHT, + ) + .await; + let StateTransitionExecutionResult::SuccessfulExecution { fee_result, .. } = result + else { + panic!( + "expected the reveal (contested {contested}) to be accepted at \ + {protocol_version}, got {result:?}" + ); + }; + fees.push(( + fee_result.processing_fee, + fee_result.storage_fee, + fee_result + .fee_refunds + .calculate_refunds_amount_for_identity(alice) + .unwrap_or_default(), + )); + } + measured.push((protocol_version, fees[0], fees[1])); + } + // Each row: the protocol version, then the plain create's fees, then the contested + // create's + assert_eq!( + measured, + vec![ + ( + 14, + (1_777_440, 9_720_000, 15_181_239), + (3_489_420, 75_411_000, 15_181_239) + ), + ( + 15, + (1_766_860, 9_720_000, 15_181_239), + (3_478_880, 75_411_000, 15_181_239) + ), + ] ); } @@ -1291,41 +1410,46 @@ mod commit_reveal_lookup_tests { /// the create adds to while the consumed ticket leaves it. #[tokio::test] async fn should_create_a_ticket_that_consumes_an_earlier_ticket_of_its_writer() { - let mut fixture = CommitRevealFixture::new(); - let first_secret = [0x31; 32]; - let (first, result) = fixture - .create( - Who::Alice, - "ticket", - &[("commitment", Value::Bytes32(hash_double(first_secret)))], - &["secret"], - COMMIT_HEIGHT, - ) - .await; - assert_matches!( - result, - StateTransitionExecutionResult::SuccessfulExecution { .. } - ); + for protocol_version in CONSUME_PROTOCOL_VERSIONS { + let mut fixture = CommitRevealFixture::new_at( + PlatformVersion::get(protocol_version).expect("expected the platform version"), + |_| {}, + ); + let first_secret = [0x31; 32]; + let (first, result) = fixture + .create( + Who::Alice, + "ticket", + &[("commitment", Value::Bytes32(hash_double(first_secret)))], + &["secret"], + COMMIT_HEIGHT, + ) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. } + ); - let (second, result) = fixture - .create( - Who::Alice, - "ticket", - &[ - ("commitment", Value::Bytes32(hash_double([0x32; 32]))), - ("secret", Value::Bytes32(first_secret)), - ], - &[], - REVEAL_HEIGHT, - ) - .await; - assert_matches!( - result, - StateTransitionExecutionResult::SuccessfulExecution { .. }, - "expected the second ticket to consume the first" - ); - assert!(!fixture.document_exists("ticket", first.id())); - assert!(fixture.document_exists("ticket", second.id())); + let (second, result) = fixture + .create( + Who::Alice, + "ticket", + &[ + ("commitment", Value::Bytes32(hash_double([0x32; 32]))), + ("secret", Value::Bytes32(first_secret)), + ], + &[], + REVEAL_HEIGHT, + ) + .await; + assert_matches!( + result, + StateTransitionExecutionResult::SuccessfulExecution { .. }, + "expected the second ticket to consume the first at {protocol_version}" + ); + assert!(!fixture.document_exists("ticket", first.id())); + assert!(fixture.document_exists("ticket", second.id())); + } } /// A key bound to the `domain` type signs a domain that reveals and From cf67b29fdc2fed2fd716ad28fd0692c56302c9bb Mon Sep 17 00:00:00 2001 From: Ivan Shumkov Date: Thu, 12 Nov 2026 00:32:41 +0700 Subject: [PATCH 2/3] refactor(platform): read a consumed document through generation 0's lookup (PV15) At protocol version 15, a refersTo lookup declaring consume read the document it found through query_documents_with_flags, in a copy of generation 0's lookup helper. The only reason was to carry ConsumedDocumentRead.storage_flags to the delete, and no delete operation carries those flags: GroveDB refunds a removed element by the flags stored on it. The flags plumbing was dead consensus surface, and the comments saying the delete refunds by those flags were wrong. Document reference validation 1 now reads every lookup through generation 0's fetch_document_through_lookup and keeps only the document: - ConsumedDocument.read is an Option. - ConsumedDocumentRead and the copied v1/lookup.rs are removed. - force_delete_read_document_for_contract_operations loses its storage_flags parameter, and its doc gains # Parameters and # Returns. - The read that #5360 saved stays saved: conversion 1 still deletes from the document the lookup read, without reading it again by id. No fee or state change at protocol version 15 or 14. Fees (processing, storage, refund) and the GroveDB root hash after seven consume flows were identical before and after this change, at both versions where a flow runs: - a plain create and a contested create - a ttl preorder chosen first among its competitors - a ticket sharing its index bucket with the one it consumes - a voucher found by a plain lookup - a DPNS v3 name, plain and contested (protocol version 15 only) The fee pins pass unchanged: - should_pin_the_fees_of_a_consume_through_a_plain_and_a_contested_create - should_pin_the_fees_of_a_reveal_choosing_the_first_of_its_preorders - should_charge_a_name_at_protocol_versions_14_and_15 should_delete_a_read_document_as_a_force_delete_does_less_its_read now compares the by-id delete, which carries the stored element's flags, with a read delete given none, and their operations are equal. The v15 note now says a consume pays for one read fewer, a saving that differs from create to create, rather than a fixed 10,660 credits. Refs #5360 Co-Authored-By: Claude Opus 5.5 --- .../v1/lookup.rs | 177 ------------------ .../document_reference_validation/v1/mod.rs | 34 ++-- .../tests/document/commit_reveal_lookup.rs | 42 ++--- .../mod.rs | 38 ++-- .../v0/mod.rs | 16 +- .../v0/mod.rs | 19 +- .../src/util/batch/drive_op_batch/document.rs | 5 +- .../drive_abci_validation_versions/v11.rs | 6 +- .../rs-platform-version/src/version/v15.rs | 15 +- 9 files changed, 71 insertions(+), 281 deletions(-) delete mode 100644 packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/lookup.rs diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/lookup.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/lookup.rs deleted file mode 100644 index 37ca1acb524..00000000000 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/lookup.rs +++ /dev/null @@ -1,177 +0,0 @@ -//! The `refersTo` lookup of document reference validation 1 (protocol version 15). - -use crate::error::Error; -use crate::execution::types::execution_operation::ValidationOperation; -use crate::execution::types::state_transition_execution_context::{ - StateTransitionExecutionContext, StateTransitionExecutionContextMethodsV0, -}; -use crate::execution::validation::state_transition::batch::state::v0::fetch_documents::{ - fetch_document_through_lookup, hash_lookup_key, holds_key_part, BilledLookupKey, -}; -use dpp::block::epoch::Epoch; -use dpp::data_contract::document_type::methods::DocumentTypeV0Methods; -use dpp::data_contract::document_type::{DocumentReferenceLookup, DocumentTypeRef}; -use dpp::data_contract::DataContract; -use dpp::document::Document; -use dpp::fee::fee_result::FeeResult; -use dpp::platform_value::{Identifier, Value}; -use dpp::version::PlatformVersion; -use drive::drive::document::query::QueryDocumentsWithFlagsOutcomeV0Methods; -use drive::drive::Drive; -use drive::grovedb::TransactionArg; -use drive::query::{DriveDocumentQuery, InternalClauses, WhereClause, WhereOperator}; -use drive::util::storage_flags::StorageFlags; -use std::collections::BTreeMap; - -/// What `fetch_document_through_lookup` (batch state 0) finds. For a lookup declaring `consume`, -/// it also returns the storage flags of the document's stored element. That is the same path -/// query, read through `query_documents_with_flags` instead of `query_documents` and billed the -/// same way, and the create that consumes the document deletes it from this read without -/// reading it again. -/// -/// The two GroveDB calls behind those queries part ways only past a layer a query item misses: -/// `query` goes on with the next item, `query_item_value` stops. A lookup fixes every property -/// of a unique index, one key a layer, so a consuming lookup that finds nothing stops at the -/// same layer either way and pays what generation 0's pays -/// (`should_bill_a_consuming_lookup_that_finds_nothing_the_same_at_protocol_versions_14_and_15`). -/// A lookup that does not consume needs no flags, so it calls generation 0's read itself. -#[allow(clippy::too_many_arguments)] -pub(super) fn fetch_document_with_flags_through_lookup( - drive: &Drive, - contract: &DataContract, - document_type: DocumentTypeRef, - declaring_document_type: DocumentTypeRef, - lookup: &DocumentReferenceLookup, - reference_value: &Value, - document_data: &BTreeMap, - owner_id: Identifier, - billed_key: Option, - epoch: &Epoch, - execution_context: &mut StateTransitionExecutionContext, - transaction: TransactionArg, - platform_version: &PlatformVersion, -) -> Result)>, Error> { - if !lookup.consume { - return Ok(fetch_document_through_lookup( - drive, - contract, - document_type, - declaring_document_type, - lookup, - reference_value, - document_data, - owner_id, - billed_key, - epoch, - execution_context, - transaction, - platform_version, - )? - .map(|document| (document, None))); - } - // Registration resolved the index its `findBy` names, and a type's indexes - // never change, so this only guards a declaration no registration admits: - // one naming no unique index finds no document - if lookup.resolve_index(document_type).is_err() { - return Ok(None); - } - // A function's `"."` param reads an identifier (an element, the writer or - // the creator); a property carrying the reference is named by its path. - // The writer is passed in place, inert before protocol version 14: only - // meta-schema v3 admits a computed key, and the `"$ownerId"` param that - // reads the writer - let reference_id = match reference_value { - Value::Identifier(id) => Some(Identifier::from(*id)), - _ => None, - }; - let billed_key = billed_key.or_else(|| { - lookup.hash_key().and_then(|(_, key)| { - hash_lookup_key( - key, - declaring_document_type, - reference_id, - owner_id, - document_data, - execution_context, - ) - }) - }); - let computed_key = billed_key.map(|key| Value::Bytes32(key.digest())); - let Some(key_values) = lookup.key_values( - reference_value, - document_data, - owner_id, - computed_key.as_ref(), - ) else { - return Ok(None); - }; - // A key part no index entry can hold finds no document. Serializing it is - // what the query does first, and its failure is the value's, not the state's - if key_values.iter().any(|(index_property, value)| { - document_type - .serialize_value_for_key(index_property, value, platform_version) - .is_err() - }) { - return Ok(None); - } - let equal_clauses = key_values - .iter() - .map(|(field, value)| { - ( - field.clone(), - WhereClause { - field: field.clone(), - operator: WhereOperator::Equal, - value: value.clone(), - }, - ) - }) - .collect(); - - let drive_query = DriveDocumentQuery { - contract, - document_type, - internal_clauses: InternalClauses { - primary_key_in_clause: None, - primary_key_equal_clause: None, - in_clauses: Vec::new(), - range_clause: None, - equal_clauses, - }, - offset: None, - // The index is unique and every one of its properties is fixed, so at - // most one document matches - limit: Some(1), - order_by: Default::default(), - start_at: None, - start_at_included: false, - block_time_ms: None, - resolved_time_ranges: vec![], - sub_queries: vec![], - }; - - let documents_outcome = drive.query_documents_with_flags( - drive_query, - Some(epoch), - false, - transaction, - Some(platform_version.protocol_version), - )?; - execution_context.add_operation(ValidationOperation::PrecalculatedOperation(FeeResult { - storage_fee: 0, - processing_fee: documents_outcome.cost(), - fee_refunds: Default::default(), - removed_bytes_from_system: 0, - lifetime_storage_fees: Default::default(), - })); - - Ok(documents_outcome - .documents_owned() - .into_iter() - .next() - .filter(|(document, _)| { - key_values.iter().all(|(index_property, value)| { - holds_key_part(document_type, document, index_property, value) - }) - })) -} diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs index 9e433122b71..5db0aec65a8 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs @@ -64,9 +64,7 @@ use drive::drive::identity::key::fetch::{ use drive::query::{TransactionArg, WhereClause, WhereOperator}; use drive::state_transition_action::batch::batched_transition::document_transition::document_base_transition_action::DocumentBaseTransitionAction; use drive::state_transition_action::batch::batched_transition::document_transition::document_base_transition_action::DocumentBaseTransitionActionAccessorsV0; -use drive::state_transition_action::batch::batched_transition::document_transition::document_create_transition_action::{ - ConsumedDocument, ConsumedDocumentRead, -}; +use drive::state_transition_action::batch::batched_transition::document_transition::document_create_transition_action::ConsumedDocument; use dpp::fee::fee_result::FeeResult; use dpp::fee::Credits; use std::slice; @@ -81,23 +79,18 @@ use crate::execution::types::state_transition_execution_context::{ }; use crate::execution::validation::state_transition::batch::action_validation::document::document_reference_validation::ConsumedLookupDocument; use crate::execution::validation::state_transition::batch::state::v0::fetch_documents::{ - fetch_document_with_id, fetch_documents_holding_in_order, hash_lookup_key, holds_key_part, - BilledLookupKey, + fetch_document_through_lookup, fetch_document_with_id, fetch_documents_holding_in_order, + hash_lookup_key, holds_key_part, BilledLookupKey, }; use crate::execution::validation::state_transition::batch::action_validation::document::document_reference_validation::v0::choose_first_scan_budget; -use drive::util::storage_flags::StorageFlags; use crate::execution::validation::state_transition::common::validate_document_not_expired::document_is_expired; use crate::platform_types::platform::PlatformStateRef; -mod lookup; - -use lookup::fetch_document_with_flags_through_lookup; - /// Versioned, stateful validation of document references using the v1 rules (protocol /// version 15): generation 0's, but a `refersTo` lookup of a reference declaring `consume` -/// reads the document it finds with its stored element's storage flags and keeps that read in -/// the [`ConsumedDocument`] it records, so the create conversion 1 deletes the document from it -/// without reading it again. Any other lookup reads as generation 0's does. +/// keeps the document it finds in the [`ConsumedDocument`] it records, so the create +/// conversion 1 deletes the document from it without reading it again. Every lookup reads as +/// generation 0's does. /// /// It is intended to be called via the higher-level `DocumentReferenceValidation` dispatcher /// that selects the version; `deletable_document_reference_target_is_gone` stays generation @@ -1387,7 +1380,7 @@ fn validate_reference_target_v1( } } }; - let mut looked_up_document: Option<(Document, Option)> = None; + let mut looked_up_document: Option = None; let referenced_document: Option<&Document> = match (lookup, document_id) { (_, None) => None, (Some(lookup), Some(document_id)) => { @@ -1402,7 +1395,7 @@ fn validate_reference_target_v1( &id_value } }; - looked_up_document = fetch_document_with_flags_through_lookup( + looked_up_document = fetch_document_through_lookup( platform.drive, referenced_contract, referenced_document_type, @@ -1417,7 +1410,7 @@ fn validate_reference_target_v1( transaction, platform_version, )?; - looked_up_document.as_ref().map(|(document, _)| document) + looked_up_document.as_ref() } (None, Some(document_id)) => fetched_documents.document( effective_contract_id, @@ -1700,18 +1693,13 @@ fn validate_reference_target_v1( // The commitment the reference consumes, recorded once nothing above reads it any // more: what the lookup read moves into it, so the create deletes the document from // that read without reading it again - if let (Some(lookup), Some((document, storage_flags))) = - (lookup, looked_up_document.take()) - { + if let (Some(lookup), Some(document)) = (lookup, looked_up_document.take()) { if lookup.consume { consumed_documents.push(ConsumedLookupDocument { document: ConsumedDocument { document_id: document.id(), document_type_name: document_type_name.to_string(), - read: Some(ConsumedDocumentRead { - document, - storage_flags, - }), + read: Some(document), }, referenced_id: Identifier::from(referenced_id), reference_target: reference_target.clone(), diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs index 783ace4b8a2..5b32acbd224 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/commit_reveal_lookup.rs @@ -61,10 +61,8 @@ mod commit_reveal_lookup_tests { use crate::test::helpers::fast_forward_to_block::fast_forward_to_block; use dpp::util::hash::hash_double; use dpp::version::DefaultForPlatformVersion; - use drive::drive::document::query::QueryDocumentsWithFlagsOutcomeV0Methods; use drive::query::DriveDocumentQuery; use drive::state_transition_action::batch::batched_transition::document_transition::document_base_transition_action::{DocumentBaseTransitionAction, DocumentBaseTransitionActionV0}; - use drive::state_transition_action::batch::batched_transition::document_transition::document_create_transition_action::ConsumedDocumentRead; use crate::execution::validation::state_transition::batch::action_validation::document::document_reference_validation::ConsumedLookupDocument; use dpp::validation::SimpleConsensusValidationResult; use dpp::platform_value::string_encoding::Encoding; @@ -1362,12 +1360,11 @@ mod commit_reveal_lookup_tests { ); // Generation 1 (protocol version 15) keeps what the lookup read, for the create to // delete the commitment from: the stored preorder whole, which its index removals are - // built from, and its element's flags, which its refund goes by. Every block of the - // fixture is in epoch 0, and the preorder is Alice's - let (stored, stored_flags) = fixture + // built from + let stored = fixture .platform .drive - .query_documents_with_flags( + .query_documents( DriveDocumentQuery::new_primary_key_single_item_query( &fixture.contract, fixture @@ -1385,17 +1382,7 @@ mod commit_reveal_lookup_tests { .documents_owned() .pop() .expect("expected the stored preorder"); - assert_eq!( - stored_flags, - Some(StorageFlags::new_single_epoch(0, Some(alice.to_buffer()))) - ); - assert_eq!( - consumed[0].document.read, - Some(ConsumedDocumentRead { - document: stored, - storage_flags: stored_flags, - }) - ); + assert_eq!(consumed[0].document.read, Some(stored)); // A replace neither reads nor consumes: the commitment was revealed once let changed = BTreeSet::from(["label".to_string()]); @@ -1843,11 +1830,10 @@ mod commit_reveal_lookup_tests { ); } - /// Only a lookup declaring `consume` reads the storage flags of what it finds from protocol - /// version 15. A lookup that does not consume reads as before, so a post finding its - /// handle, and one finding none, cost the same at protocol versions 14 and 15. The handle - /// is keyed by its name alone, then by its owner and its name, where a writer with no - /// handle finds no tree of their own under the index's owner level. + /// A lookup that does not consume reads and bills at protocol version 15 as at 14, so a post + /// finding its handle, and one finding none, cost the same at both. The handle is keyed by + /// its name alone, then by its owner and its name, where a writer with no handle finds no + /// tree of their own under the index's owner level. #[tokio::test] async fn should_bill_a_lookup_that_does_not_consume_the_same_at_protocol_versions_14_and_15() { for keyed_by_owner in [false, true] { @@ -1897,13 +1883,11 @@ mod commit_reveal_lookup_tests { } } - /// From protocol version 15 a consuming lookup reads through `query_documents_with_flags`, - /// where generation 0 reads through `query_documents`. Their GroveDB calls part ways only - /// past a layer a query item misses: `query` goes on with the next item, `query_item_value` - /// stops. A lookup fixes every property of a unique index, one key a layer, so a consuming - /// lookup that finds nothing stops at the same layer either way and pays the same. Pinned - /// for a commitment no preorder holds, a voucher nobody made, and a voucher keyed by its - /// owner, whose writer holds no tree under the owner level, or holds another serial. + /// A consuming lookup reads and bills at protocol version 15 as at 14: only what the create + /// does with the document found changes. So a consuming lookup that finds nothing refuses + /// the create for the same fee at both. Pinned for a commitment no preorder holds, a voucher + /// nobody made, and a voucher keyed by its owner, whose writer holds no tree under the owner + /// level, or holds another serial. #[tokio::test] async fn should_bill_a_consuming_lookup_that_finds_nothing_the_same_at_protocol_versions_14_and_15( ) { diff --git a/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/mod.rs b/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/mod.rs index f900a89beb6..c2dbb152c77 100644 --- a/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/mod.rs +++ b/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/mod.rs @@ -5,7 +5,6 @@ use crate::error::drive::DriveError; use crate::error::Error; use crate::fees::op::LowLevelDriveOperation; use crate::util::estimated_layers::EstimatedLayers; -use crate::util::storage_flags::StorageFlags; use dpp::data_contract::document_type::DocumentTypeRef; use dpp::data_contract::DataContract; @@ -154,17 +153,29 @@ impl Drive { } } - /// Deletes `document`, a document a create consumes, which the create's `refersTo` lookup - /// read with its element's `storage_flags`, without its type's `canBeDeleted` guard and - /// without reading it again: the operations - /// [`Self::force_delete_document_for_contract_operations`] gives, less its read. Only the - /// create conversion 1 (protocol version 15) deletes through it, with what document - /// reference validation 1 read. + /// Deletes `document`, a document a create consumes, as the create's `refersTo` lookup + /// read it, without its type's `canBeDeleted` guard and without reading it again: the + /// operations [`Self::force_delete_document_for_contract_operations`] gives, less its read. + /// Only the create conversion 1 (protocol version 15) deletes through it, with what + /// document reference validation 1 read. + /// + /// # Parameters + /// * `document`: The document to delete, as read from its primary storage. + /// * `contract`: The contract that contains the document. + /// * `document_type`: The type of the document. + /// * `previous_batch_operations`: Previous batch operations to include. + /// * `estimated_costs_only_with_layer_info`: Estimated costs with layer info. + /// * `block_time_ms`: The time of the block the delete is in. + /// * `transaction`: The transaction argument. + /// * `platform_version`: The platform version to select the correct function version to run. + /// + /// # Returns + /// * `Ok(Vec)` if the operation was successful. + /// * `Err(DriveError::UnknownVersionMismatch)` if the drive version does not match known versions. #[allow(clippy::too_many_arguments)] pub(crate) fn force_delete_read_document_for_contract_operations( &self, document: Document, - storage_flags: Option, contract: &DataContract, document_type: DocumentTypeRef, previous_batch_operations: Option<&mut Vec>, @@ -182,7 +193,6 @@ impl Drive { { 0 => self.force_delete_read_document_for_contract_operations_v0( document, - storage_flags, contract, document_type, previous_batch_operations, @@ -229,8 +239,8 @@ mod tests { type DeleteOutcome = (Vec, Option); /// Deleting a stored `person` under `platform_version`: by its id, as the force delete - /// does, and from the document and storage flags already read, each with a layer - /// information map of its own when `estimate` is set. Gives the drive holding it too. + /// does, and from the document already read, each with a layer information map of its own + /// when `estimate` is set. Gives the drive holding it too. fn force_delete_by_id_and_from_read( platform_version: &PlatformVersion, estimate: bool, @@ -295,7 +305,6 @@ mod tests { let from_read = drive .force_delete_read_document_for_contract_operations( document.clone(), - Some(storage_flags), &contract, document_type, None, @@ -351,7 +360,9 @@ mod tests { let (_, (by_id, _), (from_read, _)) = force_delete_by_id_and_from_read(PlatformVersion::latest(), false); // The force delete reads the document first; every operation after that read is - // the same, the storage removed and refunded included + // the same, the storage removed and refunded included. The by-id delete goes on with + // the storage flags of the element it read, the read delete with none: no operation + // carries them, as GroveDB refunds a removed element by the flags it holds assert_eq!(by_id.len(), from_read.len() + 1); assert_eq!(&by_id[1..], from_read.as_slice()); } @@ -399,7 +410,6 @@ mod tests { .expect("expected the document type"); drive.force_delete_read_document_for_contract_operations( Document::V0(DocumentV0::default()), - None, &contract, document_type, None, diff --git a/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/v0/mod.rs b/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/v0/mod.rs index c1a48696762..6544010a859 100644 --- a/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/v0/mod.rs +++ b/packages/rs-drive/src/drive/document/delete/delete_document_for_contract_operations/v0/mod.rs @@ -7,8 +7,6 @@ use grovedb::{Element, TransactionArg}; use dpp::data_contract::document_type::DocumentTypeRef; -use std::borrow::Cow; - use crate::drive::document::paths::contract_documents_primary_key_path; use crate::util::object_size_info::DocumentInfo; use crate::util::object_size_info::DocumentInfo::{ @@ -192,17 +190,17 @@ impl Drive { ) } - /// [`Self::force_delete_document_for_contract_operations_v0`] for a document already read - /// with its element's `storage_flags`: the same guards, then the operations - /// [`Self::delete_read_document_for_contract_operations_v0`] gives, without the read. When - /// only estimating costs, the document's type's estimated size stands for it, as it does - /// for the by-id delete. + /// [`Self::force_delete_document_for_contract_operations_v0`] for a document already read: + /// the same guards, then the operations + /// [`Self::delete_read_document_for_contract_operations_v0`] gives, without the read. The + /// document goes without storage flags, which none of those operations carries: GroveDB + /// refunds a removed element by the flags it holds. When only estimating costs, the + /// document's type's estimated size stands for it, as it does for the by-id delete. #[inline(always)] #[allow(clippy::too_many_arguments)] pub(super) fn force_delete_read_document_for_contract_operations_v0( &self, document: Document, - storage_flags: Option, contract: &DataContract, document_type: DocumentTypeRef, previous_batch_operations: Option<&mut Vec>, @@ -238,7 +236,7 @@ impl Drive { )?; DocumentEstimatedAverageSize(document_type.estimated_size(platform_version)? as u32) } else { - DocumentOwnedInfo((document, storage_flags.map(Cow::Owned))) + DocumentOwnedInfo((document, None)) }; self.delete_read_document_for_contract_operations_v0( diff --git a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_create_transition_action/v0/mod.rs b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_create_transition_action/v0/mod.rs index e25335ee705..feaef07ee5d 100644 --- a/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_create_transition_action/v0/mod.rs +++ b/packages/rs-drive/src/state_transition_action/batch/batched_transition/document_transition/document_create_transition_action/v0/mod.rs @@ -24,7 +24,6 @@ use crate::state_transition_action::batch::batched_transition::document_transiti use crate::state_transition_action::batch::batched_transition::document_transition::drop_transient_values; use crate::drive::votes::resolved::vote_polls::contested_document_resource_vote_poll::ContestedDocumentResourceVotePollWithContractInfo; -use crate::util::storage_flags::StorageFlags; use dpp::version::PlatformVersion; use dpp::voting::vote_info_storage::contested_document_vote_poll_stored_info::ContestedDocumentVotePollStoredInfo; @@ -95,20 +94,10 @@ pub struct ConsumedDocument { pub document_id: Identifier, /// The consumed document's type, in the create's contract. pub document_type_name: String, - /// What the lookup read of the consumed document, kept by document reference validation 1 - /// (protocol version 15) so the create conversion 1 deletes it without reading it again. - /// `None` from document reference validation 0, whose conversion deletes it by id. - pub read: Option, -} - -/// A consumed document as its `refersTo` lookup read it: the document and the storage flags -/// of its stored element, which the delete refunds by. -#[derive(Debug, Clone, PartialEq)] -pub struct ConsumedDocumentRead { - /// The consumed document. - pub document: Document, - /// The storage flags of the consumed document's stored element. - pub storage_flags: Option, + /// The consumed document as its `refersTo` lookup read it, kept by document reference + /// validation 1 (protocol version 15) so the create conversion 1 deletes it without reading + /// it again. `None` from document reference validation 0, whose conversion deletes it by id. + pub read: Option, } /// document create transition action accessors v0 diff --git a/packages/rs-drive/src/util/batch/drive_op_batch/document.rs b/packages/rs-drive/src/util/batch/drive_op_batch/document.rs index 93133d72c79..9e6b351761e 100644 --- a/packages/rs-drive/src/util/batch/drive_op_batch/document.rs +++ b/packages/rs-drive/src/util/batch/drive_op_batch/document.rs @@ -224,9 +224,8 @@ fn force_delete_consumed_document_operations( platform_version: &PlatformVersion, ) -> Result, Error> { match consumed_document.read { - Some(read) => drive.force_delete_read_document_for_contract_operations( - read.document, - read.storage_flags, + Some(document) => drive.force_delete_read_document_for_contract_operations( + document, contract, document_type, previous_batch_operations, diff --git a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v11.rs b/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v11.rs index 7032b632e0b..e679b035be7 100644 --- a/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v11.rs +++ b/packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_validation_versions/v11.rs @@ -51,10 +51,8 @@ use super::{ /// document would take the unique index entry the contest awards. Only such a type pays the /// lookup, so a DPNS domain create costs what it did. /// - `document_reference_validation` 1: v0, but the `refersTo` lookup of a reference declaring -/// `consume` reads the commitment it finds with its stored element's storage flags -/// (`query_documents_with_flags`) and keeps that read in the `ConsumedDocument`, so the create -/// conversion 1 deletes the commitment from it without reading it again. Any other lookup reads -/// as v0's does. +/// `consume` keeps the commitment it finds in the `ConsumedDocument`, so the create conversion 1 +/// deletes the commitment from it without reading it again. Every lookup reads as v0's does. /// - the contract user moderation `transform_into_action`, 1 rather than 0: a moderator's /// document field change reads the stored document with its stored element's storage flags /// (`query_documents_with_flags`), and the action carries the owner they name, so that the diff --git a/packages/rs-platform-version/src/version/v15.rs b/packages/rs-platform-version/src/version/v15.rs index 22d8b219f40..19ad719680a 100644 --- a/packages/rs-platform-version/src/version/v15.rs +++ b/packages/rs-platform-version/src/version/v15.rs @@ -239,17 +239,18 @@ pub const PROTOCOL_VERSION_15: ProtocolVersion = 15; /// a simple majority) of yes plus no. Decision proposals (note 12) open the polls. /// /// 11. **A consume deletes what its lookup read**: document reference validation 1 -/// (`DRIVE_ABCI_VALIDATION_VERSIONS_V11`) reads the commitment that the `refersTo` lookup of -/// a reference declaring `consume` finds with its stored element's storage flags -/// (`query_documents_with_flags`), and keeps that read in the `ConsumedDocument`. Any other -/// lookup reads as document reference validation 0's does. The create +/// (`DRIVE_ABCI_VALIDATION_VERSIONS_V11`) keeps the commitment that the `refersTo` lookup of +/// a reference declaring `consume` finds in the `ConsumedDocument`; every lookup reads as +/// document reference validation 0's does. The create /// conversion 1 (`DRIVE_STATE_TRANSITION_METHOD_VERSIONS_V5`, which `DRIVE_VERSION_V10` /// selects) deletes the document from it /// (`Drive::force_delete_read_document_for_contract_operations`, the force delete's /// operations less its read), where conversion 0 deletes it by id and bills a second read. -/// A consume costs one document read less: a DPNS v3 name create's processing fee drops by -/// 10,660 credits. Storage fees and refunds are unchanged. Protocol v14 and earlier keep -/// document reference validation 0 and the create conversion 0. +/// A consume costs one document read fewer. What that read cost depends on where the +/// commitment sits in its tree, so the drop differs from create to create (10,660 credits +/// for the DPNS v3 name create the tests pin). Storage fees and refunds are unchanged. +/// Protocol v14 and earlier keep document reference validation 0 and the create +/// conversion 0. /// /// 12. **Decision proposals**: the decision proposals system contract /// (`SystemDataContract::DecisionProposals`, `SYSTEM_DATA_CONTRACT_VERSIONS_V4`'s From 64fe5df25c4a7764a85b2921cb709a10c6ea1095 Mon Sep 17 00:00:00 2001 From: Ivan Shumkov Date: Thu, 12 Nov 2026 00:32:47 +0700 Subject: [PATCH 3/3] docs(platform): correct the generation notes and the consume saving Text only, no code change. - Document reference validation 1 carried the replay-safety notes of the generation it was copied from: "in place in generation 0, which every table selects", "reached from protocol version 14 only". Generation 1 is selected only by protocol version 15, which has not shipped, so it needs no in-place argument. Those notes are removed. - Generation 0 of reference validation and of the create conversion said "which every table selects", which stopped being true when protocol version 15 selected generation 1 of both. That phrase is dropped. - The book said a consuming create pays for one read of the commitment. A chooseFirst scan can read it again, so the book now says one read fewer than before. Refs #5360 Co-Authored-By: Claude Opus 5.5 --- .../src/contract-keywords/refers-to-lookup.md | 2 +- .../document_reference_validation/v0/mod.rs | 24 ++++----- .../document_reference_validation/v1/mod.rs | 52 ++++--------------- .../document/document_create_transition.rs | 10 ++-- 4 files changed, 28 insertions(+), 60 deletions(-) diff --git a/book/src/contract-keywords/refers-to-lookup.md b/book/src/contract-keywords/refers-to-lookup.md index 6b29c0e8ae1..bbfda406d80 100644 --- a/book/src/contract-keywords/refers-to-lookup.md +++ b/book/src/contract-keywords/refers-to-lookup.md @@ -177,7 +177,7 @@ WHERE saltedDomainHash = -- findBy `constraints` (holding `minimumAgeBlocks` and [`chooseFirst`](#choosing-the-first-commitment-choosefirst)) and `consume` sit on the `refersTo`, beside `findBy`: they describe the document `findBy` finds when the referring document is created, so the reference must be judged on the create alone. A function in `findBy` makes it so, and so does a referring type whose documents are never replaced (`documentsMutable: false`): a replace is the one write that checks a reference again. Any other `findBy` declaring either is refused at registration (10231), and so is either beside [`inList`](refers-to-list-element.md), which checks that a list holds the value rather than finding a document by a key. - **`constraints.minimumAgeBlocks`**: the commitment's `$createdAtBlockHeight` is at least that many blocks below the create's height. The commitment type must list `$createdAtBlockHeight` in `required`. -- **`consume: true`**: the create deletes the commitment, its storage refunded to its owner. Only on a `deletableDocument` reference with the `where` entry `"$ownerId": "$ownerId"`, into a type of the same contract whose owner may delete its documents (`canBeDeleted: true`) or whose documents only a consume deletes (`canBeDeleted: "onlyWhenConsumed"`, see [Deletion](deletion.md#canbedeleted)), that declares no delete token cost or delete action fee and no [`deleteConstraints`](deletion.md#deleteconstraints) (no delete transition charges or judges them), and that requires no stricter signature security level than the revealing type. A contract-bound key signing the create must be allowed to act on the consumed type too (`ContractBoundedKeyOutOfBoundsError`, 20014). From protocol version 15 the delete uses the commitment `findBy` read, so the create pays for one read of it; before, the delete read it again by id and that read was charged too. +- **`consume: true`**: the create deletes the commitment, its storage refunded to its owner. Only on a `deletableDocument` reference with the `where` entry `"$ownerId": "$ownerId"`, into a type of the same contract whose owner may delete its documents (`canBeDeleted: true`) or whose documents only a consume deletes (`canBeDeleted: "onlyWhenConsumed"`, see [Deletion](deletion.md#canbedeleted)), that declares no delete token cost or delete action fee and no [`deleteConstraints`](deletion.md#deleteconstraints) (no delete transition charges or judges them), and that requires no stricter signature security level than the revealing type. A contract-bound key signing the create must be allowed to act on the consumed type too (`ContractBoundedKeyOutOfBoundsError`, 20014). From protocol version 15 the delete uses the commitment `findBy` read instead of reading it again by id, so the create pays for one read of it fewer than before. A create missing a param, or with a value holding its separator, is refused before any read (`DocumentReferencePreimageInvalidError`, 10423). No commitment is `ReferencedEntityNotFoundError` (40120), another identity's `ReferencedDocumentPropertyMismatchError` (40127), and one too young `ReferencedDocumentRequirementNotMetError` (40142). The [Documents chapter](../data-model/documents.md#commit-and-reveal-a-findby-function) has the full rules. diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v0/mod.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v0/mod.rs index 71bf567e90c..b3af3ff2337 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v0/mod.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v0/mod.rs @@ -973,10 +973,10 @@ struct RevealedValue<'a> { /// The recursion is as deep as the expression, which registration keeps /// within `SystemLimits::max_reference_expression_depth`. /// -/// In place in generation 0, which every table selects: its callers, the -/// document create and replace state validations, reach it from protocol -/// version 14 only, and only that version's parser produces an expression, so -/// every earlier write goes straight to the leaf check it always ran. +/// In place in generation 0: its callers, the document create and replace +/// state validations, reach it from protocol version 14 only, and only that +/// version's parser produces an expression, so every earlier write goes +/// straight to the leaf check it always ran. #[allow(clippy::too_many_arguments)] fn validate_reference_v0( contract: &DataContract, @@ -1577,10 +1577,10 @@ fn validate_reference_target_v0( // differing value would be. (Some(_), None) | (None, Some(_)) => return Ok(mismatch()), }; - // In place in generation 0, which every table selects: a - // `where` only parses from protocol version - // 14 (`apply_property_reference` 0), so before it no - // document type carries a pair to reach this comparison + // In place in generation 0: a `where` only parses from + // protocol version 14 (`apply_property_reference` 0), so + // before it no document type carries a pair to reach this + // comparison if !referring_value.same_scalar_data(&referenced_value) { return Ok(mismatch()); } @@ -2527,10 +2527,10 @@ fn validate_key_id_reference_v0( // may add a property carrying this reference to such a type, so a // replace setting the key id of an old document names no identity, // and is refused as a key id set while its identity property is not. - // In place in generation 0, which every table selects: its callers, - // the document create and replace state validations, reach it from - // protocol version 14 only, the only version whose parser produces a - // key reference, so no earlier write gets here + // In place in generation 0: its callers, the document create and + // replace state validations, reach it from protocol version 14 only, + // the only version whose parser produces a key reference, so no + // earlier write gets here KeyReferenceIdentityProperty::CreatorId => match creator_id { Some(creator_id) => creator_id, None => { diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs index 5db0aec65a8..d7ac060cea1 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/mod.rs @@ -281,9 +281,7 @@ fn validate_document_type_references_v1( // A string or byte array property whose value its `findBy` reads in // place of an id: as `"."`, filling an index property holding the same // kind of value, or revealed into a computed key, a commitment judged - // when the document is created only. An unset one is not validated. In - // place in generation 0: only the protocol version 14 parser produces - // one + // when the document is created only. An unset one is not validated PropertyReference::Revealed(target) => { let ReferenceHolder::Property(property_path) = holder else { continue; @@ -329,10 +327,7 @@ fn validate_document_type_references_v1( // stands for the value in the errors; the create's structure // validation refused a value it could not reveal, before any read. A // value read as is has no hash to stand for it, so the errors carry - // an all-zero id beside its path. The writer is passed in place in - // generation 0, inert before protocol version 14: only meta-schema v3 - // admits a computed key at all, and the `"$ownerId"` param that reads - // the writer + // an all-zero id beside its path let (referenced_id, billed_key) = match hash_key { Some((_, key)) => { let Some(billed_key) = hash_lookup_key( @@ -719,8 +714,7 @@ fn binds_a_changed_property( ) -> bool { // A lookup with a computed key is judged on a create only: nothing it reads can change, // and the commitment it found may be gone. Only a replace asks, which a document type - // whose documents are never replaced does not reach. In place in generation 0, reached - // from protocol version 14 only, the only version whose parser produces one + // whose documents are never replaced does not reach if reference_target .as_any_document_reference() .and_then(|declaration| declaration.lookup) @@ -765,8 +759,7 @@ fn binds_a_changed_property( // finds now being the target: an expression holding one is // re-validated on every replace through the walk below, and an // `ownerRefersTo` one gates every replace on the writer's document - // still existing. Reached from protocol version 14 only, the version - // whose parser produces it. + // still existing. DocumentPropertyReferenceTarget::DeletableDocument { .. } | DocumentPropertyReferenceTarget::DeletableDocumentLookup { .. } => true, DocumentPropertyReferenceTarget::IdentityPublicKey { @@ -804,19 +797,14 @@ fn binds_a_changed_property( // never bring a reference back and stay checked when the reference // is written, a create or a replace changing it. A reference the // owner requirement brings back is checked whole, as a writer - // gate's is. In place in generation 0, reached from protocol version - // 14 only: the document create and replace state validations that - // call this validation run at that version alone, and only its - // parser produces `contractRequirements` + // gate's is DocumentPropertyReferenceTarget::Contract { contract_requirements, } => writer_can_change && contract_requirements.owner.is_some(), DocumentPropertyReferenceTarget::Identity | DocumentPropertyReferenceTarget::Token => false, - // In place in generation 0, reached from protocol version 14 only, - // the only version whose parser produces an expression. A contract - // target is never an operand (the parser combines identity and - // document targets only), but the flag is passed down so an operand - // is judged as the same target alone + // A contract target is never an operand (the parser combines identity + // and document targets only), but the flag is passed down so an + // operand is judged as the same target alone DocumentPropertyReferenceTarget::AnyOf(operands) | DocumentPropertyReferenceTarget::AllOf(operands) => operands .operands() @@ -887,11 +875,6 @@ struct RevealedValue<'a> { /// read is billed as it is made, those of the operands that failed included. /// The recursion is as deep as the expression, which registration keeps /// within `SystemLimits::max_reference_expression_depth`. -/// -/// In place in generation 0, which every table selects: its callers, the -/// document create and replace state validations, reach it from protocol -/// version 14 only, and only that version's parser produces an expression, so -/// every earlier write goes straight to the leaf check it always ran. #[allow(clippy::too_many_arguments)] fn validate_reference_v1( contract: &DataContract, @@ -1190,8 +1173,7 @@ fn validate_reference_target_v1( ))); }; // A commitment is revealed once, by the create; nothing the lookup reads can - // change on a replace. In place in generation 0: only the protocol version 14 - // parser produces a lookup judged on the create alone + // change on a replace if !is_create && lookup.is_some_and(|lookup| { lookup.is_checked_on_create_only(document_type.documents_mutable()) @@ -1551,8 +1533,7 @@ fn validate_reference_target_v1( // Two typed arrays, which registration pairs with nothing // else, are equal as lists: the same elements in the same // order, each compared by value, a list either document - // leaves out the empty one. In place in generation 0: a - // pair of lists registers from protocol version 14 only + // leaves out the empty one let lists = typed_array_property( referenced_document_type.flattened_properties(), referenced_property, @@ -1586,10 +1567,6 @@ fn validate_reference_target_v1( // differing value would be. (Some(_), None) | (None, Some(_)) => return Ok(mismatch()), }; - // In place in generation 0, which every table selects: a - // `where` only parses from protocol version - // 14 (`apply_property_reference` 0), so before it no - // document type carries a pair to reach this comparison if !referring_value.same_scalar_data(&referenced_value) { return Ok(mismatch()); } @@ -1929,8 +1906,6 @@ fn found_order_bound(found: &Document, property: &str) -> Result { /// documents that are none can make a create cost more but never refuse it. A `found` or a /// candidate missing an ordered property, or a `found` missing `among`, are what registration /// rules out, so each is an internal error. -/// -/// In place in generation 0: only the protocol version 14 parser produces a `chooseFirst`. #[allow(clippy::too_many_arguments)] fn validate_choose_first_v1( choose_first: &LookupChooseFirst, @@ -2248,9 +2223,6 @@ impl RemovalRecord<'_> { /// record was read and billed by the caller. The list elements an entry /// comparing typed arrays reads are billed before it compares them /// ([`bill_where_list_elements`]), as against a document in state. -/// -/// In place in generation 0: reached from protocol version 14 only, the only -/// version whose parser produces a `moderatedDocument` reference. #[allow(clippy::too_many_arguments)] fn validate_pairs_against_removal( property_agreement: &BTreeMap, @@ -2448,10 +2420,6 @@ fn validate_key_id_reference_v1( // may add a property carrying this reference to such a type, so a // replace setting the key id of an old document names no identity, // and is refused as a key id set while its identity property is not. - // In place in generation 0, which every table selects: its callers, - // the document create and replace state validations, reach it from - // protocol version 14 only, the only version whose parser produces a - // key reference, so no earlier write gets here KeyReferenceIdentityProperty::CreatorId => match creator_id { Some(creator_id) => creator_id, None => { diff --git a/packages/rs-drive/src/state_transition_action/action_convert_to_operations/batch/document/document_create_transition.rs b/packages/rs-drive/src/state_transition_action/action_convert_to_operations/batch/document/document_create_transition.rs index 731173aad29..cc90bff8265 100644 --- a/packages/rs-drive/src/state_transition_action/action_convert_to_operations/batch/document/document_create_transition.rs +++ b/packages/rs-drive/src/state_transition_action/action_convert_to_operations/batch/document/document_create_transition.rs @@ -52,11 +52,11 @@ impl DriveHighLevelBatchOperationConverter for DocumentCreateTransitionAction { let document_creation_token_cost_operations = self.base().token_cost_operations(owner_id); - // In place in generation 0, which every table selects: only the protocol - // version 14 batch state validation sets consumed documents, and only for a - // create revealing a commitment through a `refersTo` lookup with a computed key - // declaring `consume`, which only that version's parser produces. Every earlier - // create has none and converts to exactly the operations it always did + // In place in generation 0: only the protocol version 14 batch state validation + // sets consumed documents, and only for a create revealing a commitment through a + // `refersTo` lookup with a computed key declaring `consume`, which only that + // version's parser produces. Every earlier create has none and converts to + // exactly the operations it always did let consumed_documents = self.consumed_documents().to_vec(); // The values of the type's derived index properties (protocol version 14), which