feat(platform)!: require fee history for storage refunds and credit their recorded owners

book/src/fees/overview.md

@@ -49,8 +49,9 @@ in `FeeStorageVersion`:
 | `storage_seek_cost` | 2,000 | Cost of a single disk seek |
 
 Storage fees are **refundable**: when data is deleted, a portion of the original
-storage fee is returned to the identity that paid it (see [Refunds](#refunds)
-below).
+storage fee becomes a refund for the owner recorded in the stored bytes' storage
+flags, which is not always the identity that paid the fee (see
+[Refunds](#refunds) below).
 
 The documents of a type that declares a `ttl` (protocol version 14) are the exception: they
 carry no storage flags and refund nothing, their bytes are priced for the time they live, and
@@ -468,6 +469,38 @@ out to proposers.
 There is a **dust limit**: refunds below 32 bytes worth of storage credits are
 discarded to prevent micro-refund spam.
 
+### Fee history and refund ownership (protocol version 15 onward)
+
+A refund is priced with the fee history of the block that removes the bytes:
+the `previous_fee_versions` map platform state carries, which the epoch change
+hook extends whenever the fee version number changes. `Drive::calculate_fee`
+v1 (`DRIVE_VERSION_V10`) consults that history for every owner-attributed
+storage removal, on every fee version number, and returns an internal error
+when a caller passes none. Earlier generations priced fee version number 1
+against an empty history, so a caller that forgot the history silently
+refunded at the first generation's storage rates; from protocol version 15
+that omission halts instead of mispricing. Every shipped schedule shares fee
+version number 1 and the same storage rates, so the credits themselves are
+unchanged for every shipped input.
+
+Refunds follow the recorded owner in the element's storage flags.
+`Drive::credit_storage_refunds_to_owners_operations` credits each owner that
+has a balance element without consulting any key or permission, so a frozen
+but existing owner still receives its bookkeeping refund. Two shares of a
+refund never reach a balance and are reported for the caller instead: the
+part that clears an owner's negative credit (identity debt, which lives
+outside the credit sum trees) and the part whose owner has no balance element
+(the native stand-in for a wiped owner). The caller moves both into the
+current epoch's processing pool with a single pool write and records every
+refund against its storage epoch in the pending epoch refunds, so the credit
+conservation check stays balanced. This primitive is the settlement step
+block lifecycle paths that remove owner-attributed bytes are meant to use in
+the block that removes them; at protocol version 15 the vote poll end cleanup
+does not yet price or settle its refunds, and wiring it up is a separate
+change. The protocol 12 schema migration, which shrank stored contracts
+without refunding the stripped bytes, ran once at that activation and is the
+recorded historical exception; it replays exactly as executed.
+
 ## Epoch-Based Fee Distribution
 
 Fees do not go directly to the block proposer. Instead, they accumulate in
@@ -541,6 +574,15 @@ Fee versions are stored in the `FEE_VERSIONS` array and looked up by number. The
 `uses_version_fee_multiplier_permille` field allows a global scaling factor
 (permille = divide by 1000; a value of 1000 means no change).
 
+`fee_version_number` keys the persisted fee history that refunds are priced
+against. A schedule that changes storage rates needs a new number, because the
+refund code resolves the schedule for an epoch through the history and (in
+generations before protocol version 15) shortcut number 1 to the first
+generation's rates. `FEE_VERSION1` and `FEE_VERSION2` share number 1 because
+only a non-storage group changed between them; a test in `rs-drive`'s fee
+operation module pins that every shipped schedule keeps the first generation's
+storage rates.
+
 ## Key Source Files
 
 | File | Contents |

packages/rs-drive-abci/src/query/document_query/v1/dispatch/chained.rs

@@ -278,10 +278,13 @@ mod tests {
     use dpp::dashcore::Network;
     use dpp::data_contract::document_type::random_document::CreateRandomDocument;
     use dpp::document::{Document, DocumentV0Getters, DocumentV0Setters};
+    use dpp::fee::default_costs::CachedEpochIndexFeeVersions;
     use dpp::identifier::Identifier;
     use dpp::platform_value::Value;
     use dpp::tests::json_document::json_document_to_contract;
+    use dpp::version::fee::FeeVersion;
     use drive::drive::contract::moderation::types::ContractDocumentRemovalEntry;
+    use std::collections::BTreeMap;
 
     const YAPPR_CONTRACT_PATH: &str =
         "../rs-drive/tests/supporting_files/contract/yappr-likes/yappr-likes-contract.json";
@@ -509,6 +512,9 @@ mod tests {
     fn should_report_a_deleted_post_of_a_deletable_document_join() {
         let (platform, state, version, contract) =
             setup_yappr_state_at(YAPPR_DELETABLE_POSTS_CONTRACT_PATH);
+        // The post is owner-flagged, so pricing its removal needs the fee history of the
+        // removing block, as every production caller passes.
+        let fee_history: CachedEpochIndexFeeVersions = BTreeMap::from([(0, FeeVersion::first())]);
         platform
             .drive
             .delete_document_for_contract(
@@ -519,7 +525,7 @@ mod tests {
                 true,
                 None,
                 version,
-                None,
+                Some(&fee_history),
             )
             .expect("expected to delete the post");