feat(platform)!: destroy a frozen identity's escrowed listings with its funds (PV15)

book/src/data-model/token-marketplace.md

@@ -217,6 +217,22 @@ buyer pays the storage of the `bid` and gets it back when the offer closes. A `T
 proven by its `bid` document, whose terms, untouched `remaining` and escrow (what the offer is
 worth at its decimals) the client checks, and a `TokenFillBid` by the seller's token balance.
 
+## Frozen accounts
+
+A frozen account's open listings cannot be filled, and the tokens they hold sit in escrow, out of
+the frozen balance. From protocol version 15 a `TokenDestroyFrozenFunds` destroys them with the
+balance: it reads the frozen identity's open listings of the token, oldest first, at most
+`max_frozen_listings_destroyed_per_transition` (16), destroys what they hold in escrow, deletes
+their `ask` documents and records the whole amount destroyed in its `destroyFrozenFunds` history
+document. A frozen identity with more listings needs one more destroy per 16. Its offers hold
+credits, which are not the token's to destroy, and stay; it can still withdraw them.
+
+```text
+Frozen identity: balance 5,000, listings of 3,000 and 2,000
+Before (protocol version 14 rules): the destroy burns 5,000; the 5,000 in escrow stays
+From protocol version 15:           the destroy burns all 10,000 and deletes both listings
+```
+
 ## History
 
 A token that keeps transfer history (`keepsHistory.keepsTransferHistory`, the default) also

packages/rs-drive/src/drive/contract/insert/insert_contract/v0/tests/batched_group_drain.rs

@@ -20,13 +20,15 @@
 //! batch state transition carries at most one document transition, and two
 //! transitions in the same block become two separate GroveDB batches
 //! (`execute_event` calls `apply_drive_operations` once per state transition).
-//! The cases that expose the defect are therefore `#[ignore]`d rather than
-//! deleted or weakened: they are the specification of one hazard raising that
-//! cap would have to fix — not of the whole shape, since a real multi-transition
-//! batch would also fold several writes to the same identity-contract nonce key
-//! into one batch. The cases that run pin what the system relies on today — the
-//! phantom is characterized as it actually is, the inverse shape fails loud,
-//! and the sequential controls drain correctly.
+//! From protocol version 15, `apply_drive_operations` 2 builds every operation
+//! of a batch against the batch's operations built before it, so two deletes
+//! that jointly empty a group see each other and the group is removed. The cases
+//! that specify the drain run at the latest version; the phantom generation 1
+//! leaves (protocol version 14 and earlier) stays characterized as it actually
+//! is, the inverse shape fails loud, and the sequential controls drain
+//! correctly. They specify one hazard raising the cap would have had to fix,
+//! not the whole shape: a real multi-transition batch would also fold several
+//! writes to the same identity-contract nonce key into one batch.
 //!
 //! The cap is not the only guard of its kind. `update_contract_keywords` builds
 //! its own multi-document blind batch over one shared index group and is kept
@@ -214,13 +216,22 @@ fn update_op<'a>(
 }
 
 fn apply_batch(drive: &Drive, operations: Vec<DriveOperation>) {
+    apply_batch_at(drive, operations, platform_version());
+}
+
+/// Applies `operations` as one batch the way `platform_version` does.
+fn apply_batch_at(
+    drive: &Drive,
+    operations: Vec<DriveOperation>,
+    platform_version: &PlatformVersion,
+) {
     drive
         .apply_drive_operations(
             operations,
             true,
             &BlockInfo::default(),
             None,
-            platform_version(),
+            platform_version,
             None,
         )
         .expect("the batch must apply");
@@ -570,21 +581,32 @@ fn assert_baseline(drive: &Drive, contract: &DataContract, axis: Axis) {
 /// storage, grovedb's integrity sweep reports nothing, and the proved page
 /// both equals the unproved one and reconstructs the live root hash.
 ///
-/// It goes red the day the defect is fixed, or the day grovedb starts
-/// detecting it. That is the intended signal, not a regression: delete this
-/// test then, and un-ignore the cases below.
+/// It applies the batch the way protocol version 14 does: generation 1 of
+/// `apply_drive_operations`, which every released version runs. Generation 2
+/// (protocol version 15) builds each operation against the batch's earlier
+/// ones and removes the group; the cases below specify that.
 #[test]
 fn a_batched_drain_leaves_a_phantom_group_that_verifies_and_proves() {
+    let generation_1 = PlatformVersion::get(14).expect("expected protocol version 14");
+    assert_eq!(
+        generation_1
+            .drive
+            .methods
+            .batch_operations
+            .apply_drive_operations,
+        1
+    );
     for axis in AXES {
         let (drive, contract, docs) = setup_g_two_h_one(axis);
         assert_baseline(&drive, &contract, axis);
 
-        apply_batch(
+        apply_batch_at(
             &drive,
             vec![
                 delete_op(&contract, axis.doctype, docs[1].id()),
                 delete_op(&contract, axis.doctype, docs[2].id()),
             ],
+            generation_1,
         );
 
         let path = indexed_property_name_tree_path(&contract, axis.doctype);
@@ -651,18 +673,18 @@ fn a_batched_drain_leaves_a_phantom_group_that_verifies_and_proves() {
     }
 }
 
-/// **Known latent defect.** Both of `G`'s documents are deleted in one
+/// **A latent defect before protocol version 15.** Both of `G`'s documents are deleted in one
 /// `apply_drive_operations` call. Neither delete can see the other, so neither
 /// removes `G`'s group tree: `G` stays in the ranked secondary with a zero
 /// aggregate and no documents behind it, on all three axes, with
 /// `verify_grovedb` clean and the proof reconstructing the live root hash.
 ///
-/// Unreachable today because `max_transitions_in_documents_batch` is 1, which
-/// keeps any two document operations out of a shared GroveDB batch. Raising
-/// that cap arms this; see the documentation on
-/// `SystemLimits::max_transitions_in_documents_batch`.
+/// From protocol version 15 the second delete is built against the first and the
+/// group is removed; this case runs at the latest version. Before 15 the defect
+/// stands (see `a_batched_drain_leaves_a_phantom_group_that_verifies_and_proves`)
+/// and is unreachable because `max_transitions_in_documents_batch` is 1; see the
+/// documentation on `SystemLimits::max_transitions_in_documents_batch`.
 #[test]
-#[ignore = "documents a latent defect in shared write-path machinery that is unreachable while max_transitions_in_documents_batch is 1; un-ignore before raising that cap"]
 fn deleting_a_groups_last_two_documents_in_one_batch_removes_the_group() {
     for axis in AXES {
         let (drive, contract, docs) = setup_g_two_h_one(axis);
@@ -687,14 +709,13 @@ fn deleting_a_groups_last_two_documents_in_one_batch_removes_the_group() {
     }
 }
 
-/// **Known latent defect**, same as
+/// **A latent defect before protocol version 15**, same as
 /// [`deleting_a_groups_last_two_documents_in_one_batch_removes_the_group`],
 /// with the two deletes in the opposite order — the group's emptiness is
 /// mis-observed either way, so the defect is not an artefact of one ordering.
 ///
-/// Unreachable while `max_transitions_in_documents_batch` is 1.
+/// Removed from protocol version 15; this case runs at the latest version.
 #[test]
-#[ignore = "documents a latent defect in shared write-path machinery that is unreachable while max_transitions_in_documents_batch is 1; un-ignore before raising that cap"]
 fn reverse_ordered_batched_deletes_remove_the_group_too() {
     for axis in AXES {
         let (drive, contract, docs) = setup_g_two_h_one(axis);
@@ -718,14 +739,13 @@ fn reverse_ordered_batched_deletes_remove_the_group_too() {
     }
 }
 
-/// **Known latent defect**, same as
+/// **A latent defect before protocol version 15**, same as
 /// [`deleting_a_groups_last_two_documents_in_one_batch_removes_the_group`], on
 /// a Drive configured the way a shipped node is — so it cannot be dismissed as
 /// an artefact of the test harness's `batching_consistency_verification: true`.
 ///
-/// Unreachable while `max_transitions_in_documents_batch` is 1.
+/// Removed from protocol version 15; this case runs at the latest version.
 #[test]
-#[ignore = "documents a latent defect in shared write-path machinery that is unreachable while max_transitions_in_documents_batch is 1; un-ignore before raising that cap"]
 fn batched_deletes_remove_the_group_under_the_shipped_batching_config() {
     for axis in AXES {
         let (drive, contract) = setup_restaurants_with_shipped_batching_config();
@@ -754,7 +774,7 @@ fn batched_deletes_remove_the_group_under_the_shipped_batching_config() {
     }
 }
 
-/// **Known latent defect.** The batched drain and the identical drain applied
+/// **A latent defect before protocol version 15.** The batched drain and the identical drain applied
 /// one delete at a time must land the same logical index; they do not.
 ///
 /// The comparison is over entries and primary aggregates rather than the root
@@ -764,9 +784,8 @@ fn batched_deletes_remove_the_group_under_the_shipped_batching_config() {
 /// deterministic for nodes replaying identical history, so it is not itself a
 /// consensus hazard — but it makes the app hash the wrong instrument here.
 ///
-/// Unreachable while `max_transitions_in_documents_batch` is 1.
+/// Removed from protocol version 15; this case runs at the latest version.
 #[test]
-#[ignore = "documents a latent defect in shared write-path machinery that is unreachable while max_transitions_in_documents_batch is 1; un-ignore before raising that cap"]
 fn batched_and_sequential_drains_agree_on_the_logical_state() {
     for axis in AXES {
         let (batched, batched_contract, batched_docs) = setup_g_two_h_one(axis);
@@ -841,16 +860,15 @@ fn update_document_singly(drive: &Drive, contract: &DataContract, axis: Axis, do
         .expect("the single-document update must succeed");
 }
 
-/// **Known latent defect**, reached through `UpdateDocument` rather than
+/// **A latent defect before protocol version 15**, reached through `UpdateDocument` rather than
 /// `DeleteDocument`: one batch moves both of `G`'s documents into `H`. `H`
 /// correctly gains all three contributions, but `G` survives as a zero-valued
 /// phantom, so the defect is not specific to deletes — any operation that
 /// empties a group while a sibling operation in the same batch has not been
 /// observed reproduces it.
 ///
-/// Unreachable while `max_transitions_in_documents_batch` is 1.
+/// Removed from protocol version 15; this case runs at the latest version.
 #[test]
-#[ignore = "documents a latent defect in shared write-path machinery that is unreachable while max_transitions_in_documents_batch is 1; un-ignore before raising that cap"]
 fn moving_a_groups_last_two_documents_to_another_group_in_one_batch_drains_it() {
     for axis in AXES {
         let (drive, contract, docs) = setup_g_two_h_one(axis);

packages/rs-drive/src/drive/tokens/order_escrow/fetch_order.rs

@@ -1,18 +1,23 @@
 use crate::drive::contract::DataContractFetchInfo;
 use crate::drive::document::query::QueryDocumentsOutcomeV0Methods;
 use crate::drive::Drive;
+use crate::error::drive::DriveError;
 use crate::error::Error;
+use crate::query::ordering::OrderClause;
 use crate::query::{DriveDocumentQuery, InternalClauses, WhereClause, WhereOperator};
 use dpp::block::epoch::Epoch;
 use dpp::data_contract::accessors::v0::DataContractV0Getters;
 use dpp::data_contract::DataContract;
 use dpp::document::Document;
 use dpp::identifier::Identifier;
 use dpp::platform_value::Value;
+use dpp::tokens::token_order::TokenOrder;
 use dpp::tokens::token_order_side::TokenOrderSide;
 use dpp::version::PlatformVersion;
 use grovedb::TransactionArg;
 use grovedb_costs::OperationCost;
+use indexmap::IndexMap;
+use std::collections::BTreeMap;
 use std::sync::Arc;
 
 impl Drive {
@@ -82,4 +87,141 @@ impl Drive {
         let cost = outcome.cost();
         Ok((outcome.documents_owned().into_iter().next(), cost))
     }
+
+    /// The open listings of `owner_id` for `token_id` that a `TokenDestroyFrozenFunds` destroys
+    /// with the frozen balance: the oldest first, at most
+    /// `max_frozen_listings_destroyed_per_transition`, read through the `ask` type's `byOwner`
+    /// index, with the processing cost of the read billed at `epoch`. None where
+    /// `fetch_frozen_listings` is `None`, which reads nothing: there the frozen balance alone is
+    /// destroyed, as before the marketplace.
+    pub fn fetch_frozen_token_listings(
+        &self,
+        token_id: Identifier,
+        owner_id: Identifier,
+        epoch: &Epoch,
+        transaction: TransactionArg,
+        platform_version: &PlatformVersion,
+    ) -> Result<(Vec<TokenOrder>, u64), Error> {
+        match platform_version
+            .drive
+            .methods
+            .token
+            .order_escrow
+            .fetch_frozen_listings
+        {
+            None => Ok((vec![], 0)),
+            Some(0) => self.fetch_frozen_token_listings_v0(
+                token_id,
+                owner_id,
+                epoch,
+                transaction,
+                platform_version,
+            ),
+            Some(version) => Err(Error::Drive(DriveError::UnknownVersionMismatch {
+                method: "fetch_frozen_token_listings".to_string(),
+                known_versions: vec![0],
+                received: version,
+            })),
+        }
+    }
+
+    fn fetch_frozen_token_listings_v0(
+        &self,
+        token_id: Identifier,
+        owner_id: Identifier,
+        epoch: &Epoch,
+        transaction: TransactionArg,
+        platform_version: &PlatformVersion,
+    ) -> Result<(Vec<TokenOrder>, u64), Error> {
+        let token_market_contract = self
+            .cache
+            .system_data_contracts
+            .load_token_market(platform_version)?;
+        let document_type = token_market_contract
+            .document_type_for_name(TokenOrderSide::Ask.document_type_name())?;
+        let equal = |field: &str, value: Identifier| {
+            (
+                field.to_string(),
+                WhereClause {
+                    field: field.to_string(),
+                    operator: WhereOperator::Equal,
+                    value: Value::Identifier(value.to_buffer()),
+                },
+            )
+        };
+        let query = DriveDocumentQuery {
+            contract: &token_market_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: BTreeMap::from([
+                    equal("$ownerId", owner_id),
+                    equal("tokenId", token_id),
+                ]),
+            },
+            offset: None,
+            limit: Some(
+                platform_version
+                    .system_limits
+                    .max_frozen_listings_destroyed_per_transition,
+            ),
+            order_by: IndexMap::from([(
+                "$createdAt".to_string(),
+                OrderClause {
+                    field: "$createdAt".to_string(),
+                    ascending: true,
+                },
+            )]),
+            start_at: None,
+            start_at_included: false,
+            block_time_ms: None,
+            resolved_time_ranges: vec![],
+            sub_queries: vec![],
+        };
+        let outcome = self.query_documents(
+            query,
+            Some(epoch),
+            false,
+            transaction,
+            Some(platform_version.protocol_version),
+        )?;
+        let cost = outcome.cost();
+        let listings = outcome
+            .documents_owned()
+            .iter()
+            .map(|document| TokenOrder::from_document(document, TokenOrderSide::Ask))
+            .collect::<Result<Vec<_>, _>>()?;
+        Ok((listings, cost))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::util::test_helpers::setup::setup_drive_with_initial_state_structure;
+    use dpp::block::epoch::Epoch;
+    use dpp::identifier::Identifier;
+    use dpp::version::PlatformVersion;
+
+    /// Before protocol version 15 a destroy of frozen funds reads no listings: on a chain with no
+    /// marketplace state (no escrow trees, no token market contract) the read returns none and
+    /// costs nothing.
+    #[test]
+    fn should_read_no_frozen_listings_before_protocol_version_15() {
+        let platform_version = PlatformVersion::get(14).expect("expected protocol version 14");
+        let drive = setup_drive_with_initial_state_structure(Some(platform_version));
+        let (listings, cost) = drive
+            .fetch_frozen_token_listings(
+                Identifier::from([5; 32]),
+                Identifier::from([6; 32]),
+                &Epoch::new(0).expect("expected an epoch"),
+                None,
+                platform_version,
+            )
+            .expect("expected the read to be skipped");
+        assert!(listings.is_empty());
+        assert_eq!(cost, 0);
+    }
 }