perf(platform)!: delete a consumed document from what its lookup read (PV15)

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).
+- **`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.
 
 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.
 

packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/mod.rs

@@ -1,4 +1,5 @@
 pub mod v0;
+pub mod v1;
 
 use std::collections::{BTreeMap, BTreeSet};
 
@@ -17,6 +18,7 @@ use crate::error::execution::ExecutionError;
 use crate::error::Error;
 use crate::execution::types::state_transition_execution_context::StateTransitionExecutionContext;
 use crate::execution::validation::state_transition::batch::action_validation::document::document_reference_validation::v0::DocumentReferenceValidationV0;
+use crate::execution::validation::state_transition::batch::action_validation::document::document_reference_validation::v1::DocumentReferenceValidationV1;
 use crate::platform_types::platform::PlatformStateRef;
 
 /// A document a create consumes: the commitment a `refersTo` lookup with a computed key
@@ -152,7 +154,8 @@ impl DocumentReferenceValidation for DocumentBaseTransitionAction {
             .batch_state_transition
             .document_reference_validation
         {
-            0 => self.deletable_document_reference_target_is_gone_v0(
+            // Generation 1 changes what a lookup keeps of a consumed document only
+            0 | 1 => self.deletable_document_reference_target_is_gone_v0(
                 property,
                 referenced_id,
                 platform,
@@ -164,7 +167,7 @@ impl DocumentReferenceValidation for DocumentBaseTransitionAction {
             version => Err(Error::Execution(ExecutionError::UnknownVersionMismatch {
                 method: "DocumentBaseTransitionAction::deletable_document_reference_target_is_gone"
                     .to_string(),
-                known_versions: vec![0],
+                known_versions: vec![0, 1],
                 received: version,
             })),
         }
@@ -210,9 +213,25 @@ impl DocumentReferenceValidation for DocumentBaseTransitionAction {
                 execution_context,
                 platform_version,
             ),
+            1 => self.validate_document_references_v1(
+                document_data,
+                owner_id,
+                creator_id,
+                referring_system,
+                changed_fields,
+                stored_values,
+                platform,
+                block_info,
+                consumed_documents,
+                derived_index_values,
+                referenced_documents,
+                transaction,
+                execution_context,
+                platform_version,
+            ),
             version => Err(Error::Execution(ExecutionError::UnknownVersionMismatch {
                 method: "DocumentBaseTransitionAction::validate_document_references".to_string(),
-                known_versions: vec![0],
+                known_versions: vec![0, 1],
                 received: version,
             })),
         }

packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v0/mod.rs

@@ -1665,6 +1665,9 @@ fn validate_reference_target_v0(
                         document: ConsumedDocument {
                             document_id: found.id(),
                             document_type_name: document_type_name.to_string(),
+                            // Inert: the create conversion 0 that deletes it reads it by id;
+                            // only generation 1 (protocol version 15) keeps the lookup's read
+                            read: None,
                         },
                         referenced_id: Identifier::from(referenced_id),
                         reference_target: reference_target.clone(),

packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/action_validation/document/document_reference_validation/v1/lookup.rs

@@ -0,0 +1,177 @@
+//! 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<String, Value>,
+    owner_id: Identifier,
+    billed_key: Option<BilledLookupKey>,
+    epoch: &Epoch,
+    execution_context: &mut StateTransitionExecutionContext,
+    transaction: TransactionArg,
+    platform_version: &PlatformVersion,
+) -> Result<Option<(Document, Option<StorageFlags>)>, 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)
+            })
+        }))
+}