From ec68658c1cdcb398ad9db0176bb9e6226da8bad4 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Thu, 1 Oct 2026 11:13:04 +0700 Subject: [PATCH 1/6] fix(platform)!: refund sponsor-paid document storage to the gas sponsor (PV14) Gas sponsorship (#4826) lets a contract owner pay the storage and processing fees of token-paid document actions, but storage refunds followed the storage flags, which named the document owner. A user could delete or shrink a sponsored document and be refunded storage the sponsor paid for. - execute_event v1 names a paying sponsor as the owner in the storage flags of the batch's document writes (record_gas_sponsor_as_storage_owner). - Contested document insert v1 names whoever the document's flags name on the contest's end date entries. - Document update v1 keeps a stored document the sponsor holds with the sponsor when an update that is not sponsored rewrites it, a transfer included (storage_held_by_gas_sponsor). New index entries the update adds keep naming whoever pays for them. - A moderator's restore on a type that offers sponsorship names the contract owner. - Book and v14 note describe the rules, including GroveDB's flag merge limits and the sponsor's remaining storage cost. Co-Authored-By: Claude Opus 5.5 --- book/src/contract-keywords/deletion.md | 4 +- .../contract-keywords/moderator-abilities.md | 4 +- book/src/contract-keywords/token-cost.md | 5 +- book/src/data-model/contract-moderation.md | 4 +- book/src/fees/overview.md | 43 +- .../execute_event/v1/mod.rs | 15 +- .../validate_fees_of_event/v1/mod.rs | 5 + .../batch/tests/document/action_fees.rs | 17 +- .../batch/tests/document/gas_sponsorship.rs | 424 +++++++++++++++--- .../v1/mod.rs | 17 +- .../v1/mod.rs | 185 +++++--- .../contract_user_moderation_transition.rs | 38 +- .../src/state_transition_action/batch/mod.rs | 85 +++- .../util/object_size_info/document_info.rs | 17 + .../rs-platform-version/src/version/v14.rs | 11 +- 15 files changed, 708 insertions(+), 166 deletions(-) diff --git a/book/src/contract-keywords/deletion.md b/book/src/contract-keywords/deletion.md index 4956407170d..2272e845ad7 100644 --- a/book/src/contract-keywords/deletion.md +++ b/book/src/contract-keywords/deletion.md @@ -42,7 +42,7 @@ A commenter may take a comment down at any time. Since `true` is the usual defau ### How it works - The owner deletes a document with a delete transition that names its id. Anyone else is refused (`DocumentOwnerIdMismatchError`, 40102), and a document that does not exist is `DocumentNotFoundError` (40101). -- The owner is refunded the part of the document's storage fee that has not yet been paid out to past epochs. A document of a type with a `ttl` refunds nothing. See [Refunds](../fees/overview.md#refunds). +- The owner is refunded the part of the document's storage fee that has not yet been paid out to past epochs. Storage the contract owner paid for as the document's [gas sponsor](token-cost.md#who-pays-the-gas-gasfeespaidby) is refunded to them instead. A document of a type with a `ttl` refunds nothing. See [Refunds](../fees/overview.md#refunds). - A delete may carry a token cost or an action fee, like any document action. See [Token Costs](token-cost.md) and [Action Fees](action-fees.md). - An identity that is banned or suspended on a moderated contract may still delete its own documents. See [Contract Moderation](../data-model/contract-moderation.md#the-model). - `false` binds only the owner. The contract's moderators, when the type allows them, and the platform, when the type has a `ttl`, still delete such documents. @@ -297,7 +297,7 @@ Whether the owner of a document a moderator deletes is refunded its storage. By ### How it works -- With `true`, the owner is refunded as for their own deletion: the part of the storage fee not yet paid out to past epochs. The refund goes to the owner, not to the moderator, who still pays for the transition and the record. A document of a type with a `ttl` refunds nothing either way. +- With `true`, the storage is refunded as for the owner's own deletion: the part of the storage fee not yet paid out to past epochs, to the owner, or to the contract owner for storage they paid for as the document's [gas sponsor](token-cost.md#who-pays-the-gas-gasfeespaidby). The deleting moderator gets none of it as moderator, and still pays for the transition and the record. A document of a type with a `ttl` refunds nothing either way. - With `false`, the credits stay in the storage pools they were paid into. ### Rules at registration diff --git a/book/src/contract-keywords/moderator-abilities.md b/book/src/contract-keywords/moderator-abilities.md index 222dd70596e..6c600fa0fc7 100644 --- a/book/src/contract-keywords/moderator-abilities.md +++ b/book/src/contract-keywords/moderator-abilities.md @@ -17,7 +17,7 @@ The keys: | `delete` | The moderators delete documents of the type. By default each deletion leaves a removal record and can be restored within a week; with `deleteKeepsRecord: false` it leaves none and is final. | [Deletion](deletion.md#moderatorabilitiesdelete) | | `deleteWithin` | Limits `delete` to so many seconds after a document's last change. | [Deletion](deletion.md#moderatorabilitiesdeletewithin) | | `deleteKeepsRecord` | Whether a deletion leaves a removal record, and so can be restored. Default `true`. | [Deletion](deletion.md#moderatorabilitiesdeletekeepsrecord) | -| `deleteRefundsOwner` | Whether the deleted document's owner is refunded its storage. Default `false`. | [Deletion](deletion.md#moderatorabilitiesdeleterefundsowner) | +| `deleteRefundsOwner` | Whether the deleted document's storage is refunded to whoever it names: its owner, or the contract owner for storage they paid for as its gas sponsor. Default `false`. | [Deletion](deletion.md#moderatorabilitiesdeleterefundsowner) | | `deleteSettled` | Past `deleteWithin`, the seated team of an elected contract deletes a document together: one member proposes, and so many approve, the leader among them only when the rule says so (`leader: true`). | [Deletion](deletion.md#moderatorabilitiesdeletesettled) | | `deleteKeepsFields` | The fields of a deleted document whose values stay public in its removal record, such as a post's hashtag. | [Deletion](deletion.md#moderatorabilitiesdeletekeepsfields) | | `changeFields` | The listed properties are written only by the moderators. | [below](#changefields) | @@ -76,7 +76,7 @@ A user files a report and can never edit it. A report starts with no `status`: t - The document records who wrote the fields last, and when: [`$moderatedAt` and `$moderatedBy`](system-properties.md#moderatedat-and-moderatedby), which an index of the type may name to find what the moderators handled. - The document is updated in place. Every other property stays as its owner wrote it, `$updatedAt` among them, so a change never opens a [`deleteWithin`](deletion.md#moderatorabilitiesdeletewithin) window again. `$revision` goes up by one, so a replace its owner built on the earlier revision is refused (`InvalidDocumentRevisionError`, 40106) rather than writing over the change. - References are not checked again: no field a moderator writes holds one or is read by one (see the rules below). A report whose post a moderator has already deleted can still be marked handled. -- The moderator pays for the transition and the bytes it adds. Storage the change frees, or index entries it moves, are refunded to the document's owner, who paid for them. Nothing the type prices is charged: a moderator's change is no action of the owner's. +- The moderator pays for the transition and the bytes it adds. Storage the change frees, or index entries it moves, are refunded to whoever paid for them: the document's owner, or the contract owner for a document whose storage they hold as its [gas sponsor](token-cost.md#who-pays-the-gas-gasfeespaidby). Nothing the type prices is charged: a moderator's change is no action of the owner's. - A change that changes nothing, every field already holding the value named, is refused (10905): it would bump `$revision` for nothing. - A change needs a listed reason from a seated team, but does not count toward the team's action share: changes of one document have no bound, as deletions of the content that exists do, so counting them would let a member farm the share. - The proof of the change is the document as it now stands, holding the values the change set. diff --git a/book/src/contract-keywords/token-cost.md b/book/src/contract-keywords/token-cost.md index d71dcdc19d7..a8cce3a2c53 100644 --- a/book/src/contract-keywords/token-cost.md +++ b/book/src/contract-keywords/token-cost.md @@ -100,7 +100,10 @@ From protocol version 14 the contract owner can pay the gas (the storage and pro - A batch has one payer. Transitions of one batch that resolve to different payers are refused (`InconsistentGasFeesPaidByInBatchError`, 40130); a token transition in the batch is never sponsored, so it counts as the signer paying. - When the contract owner's balance does not cover the gas (and any action fees they would owe), a batch that insisted is refused and charged nothing (`GasSponsorInsufficientBalanceError`, 40222), and a batch that only preferred falls back to the signer. - A transition that fails validation is never sponsored: its signer pays for the work that ran. -- Storage refunds still go to the document's owner, whoever paid for the storage. Each token the contract owner hands out is therefore worth up to the storage fee of the largest document the type allows, so a type that offers to pay should bound its documents' size (`maxLength`, `maxItems`, [maxBytes](max-bytes.md)) and price the action to match. +- Storage refunds go to whoever paid for the storage. A sponsored action records the contract owner as the owner of the storage it writes, a contested document's vote poll entries included, so deleting or shrinking the document later refunds the contract owner, not the document's owner. A document of a type with a `ttl` is stored without storage flags and refunds nobody, sponsored or not. +- The contract owner still pays the storage fee of each document a sponsored action writes, up to the largest the type allows, and gets back only the part not yet paid out to past epochs, only when the document is deleted or shrinks. A type that offers to pay should bound its documents' size (`maxLength`, `maxItems`, [maxBytes](max-bytes.md)) and price the action to match. +- A stored document the contract owner holds stays theirs when its owner replaces or transfers it at their own expense: the refund of what that write adds to it goes to the contract owner too. Otherwise one small replace of their own would hand the owner the whole document, and its refund. New index entries the write adds name whom the write names: its signer, or the new owner on a transfer. +- Each stored part of a document has one owner. A sponsored action that grows a part the document's owner paid for, or shrinks it, takes that part over, with the refund of what the owner paid for it; a part holding the bytes of one epoch only keeps its owner when it shrinks in a later epoch, as does a part rewritten at the same size. A document owner who would rather keep it pays for the action themself. - A sponsor also pays any [action fee](action-fees.md) the action charges. Before protocol version 14 the key was accepted and stored but not acted on: the signer always paid. diff --git a/book/src/data-model/contract-moderation.md b/book/src/data-model/contract-moderation.md index fd12072cc7f..1c3b22889cd 100644 --- a/book/src/data-model/contract-moderation.md +++ b/book/src/data-model/contract-moderation.md @@ -180,7 +180,7 @@ ContractUserModerationAction::RestoreDocument { It names no identity and no id: the document is inside the bytes, and its id and owner with it. The transform checks, in order and each refusal paid: the document type exists (10406) and carries `moderatorAbilities.delete` (41115, only such a type keeps records), the signer is the owner or a moderator (41101, whoever deleted), the bytes decode under the type (a basic decoding error, never an execution error: the bytes are the signer's), the document has a removal record (`ContractDocumentRemovalNotFoundError`, 41119) that is not marked restored (`ContractDocumentAlreadyRestoredError`, 41122: the document is live), block time is within `SystemLimits::contract_document_restore_window_ms` of the removal, a week, the last millisecond included (`DocumentRestoreWindowElapsedError`, 41120), the bytes hash to what the record holds (`DocumentRestoreHashMismatchError`, 41121: the document as it was, not an edit of it), and no other document of the type holds a value of one of its unique indexes (`DuplicateUniqueIndexError`, 40105: the value was free while the document was gone, and someone may have taken it). The record read is billed; the hash pins everything else, so the owner, the revision, the timestamps, the references and the schema are not checked again. Whether the document's owner is banned is not asked either: a ban stops writes, it never removed documents. -The action carries the contract, the decoded document and the record marked restored by the signer at the block's time, so Drive puts the document back through the ordinary insert (`DocumentOperationType::AddDocument`, every index and aggregate of the type included) and replaces the record in place, without reading again. The restored document's storage flags name its owner, as they did before the deletion: the signer pays for the bytes, and the refund of a later deletion is the owner's, as it always was. Nothing the document type prices is charged, neither its creation token cost nor its `actionFees` creation fee, and no fee agreement is asked: a moderator undoes a moderation, it does not create content. The restore is proved by the record, now marked restored and holding the hash of the bytes the transition carried; the verifier reads the document's id out of those bytes under the contract's document type, so it needs the contract, which the SDKs register with their context provider before broadcasting. +The action carries the contract, the decoded document and the record marked restored by the signer at the block's time, so Drive puts the document back through the ordinary insert (`DocumentOperationType::AddDocument`, every index and aggregate of the type included) and replaces the record in place, without reading again. The restored document's storage flags name its owner: the signer pays for the bytes, and the refund of a later deletion is the owner's. On a document type whose token costs offer gas sponsorship they name the contract owner instead: such a type's documents are the sponsor's storage as a rule, the contract owner or one of their moderators pays for the restore, and Drive's document update v1 keeps the document with the contract owner through its owner's own updates, so the owner can not take the restore's storage, and its refund, for nothing. Nothing the document type prices is charged, neither its creation token cost nor its `actionFees` creation fee, and no fee agreement is asked: a moderator undoes a moderation, it does not create content. The restore is proved by the record, now marked restored and holding the hash of the bytes the transition carried; the verifier reads the document's id out of those bytes under the contract's document type, so it needs the contract, which the SDKs register with their context provider before broadcasting. Two consequences follow from the document coming back byte for byte. Its `$updatedAt` does not move, so a type with `moderatorAbilities.deleteWithin` may have settled it while it was gone: no moderator deletes it again alone until its author edits it, though the author still can, and on a type that sets `deleteSettled` the seated team can, by a fresh proposal (the action that deleted it ran and is closed). A deletion the team approved together is never restored: it is the only removal made after the document settled, since a moderator alone deletes up to the settling time and the team only after it, so the restore transform compares the removal time with the settling time of the document the bytes hash to (no read), and refuses the restore of a later removal, paid (`SettledDeletionNotRestorableError`, 41209), so no single moderator undoes what the leader and the members agreed on. And a type with a contested index can not carry `moderatorAbilities.delete` at all (`InvalidContractStructure`, 10231): a contested index only takes a document through a vote, which no restore can go through, so such a deletion could never be undone. The bytes are decoded under the type as the contract holds it when the restore is processed, and the hash is of the document serialized under the type as it was when the document was deleted: a contract update that changes the type's layout inside the window (a property added, say) leaves the record unrestorable, since bytes that decode under the new layout cannot hash to what the record holds. A client therefore serializes under the contract's current version, as Drive does, and keeps the document rather than the bytes. @@ -260,7 +260,7 @@ ContractUserModerationAction::ChangeDocumentFields { Basic structure refuses one that names no field or a system property (`InvalidContractModerationDocumentFieldsError`, 10905, unpaid). The transform (`transform_document_fields_change_v0`) checks, in order and each refusal paid: the document type exists (10406), every field is one it keeps for its moderators (`DocumentFieldNotChangeableByModeratorsError`, 41123), the signer moderates the contract (41101) and a seated team holds `changeDocumentFields` on the type (41201) and names a listed reason (41203), the document exists (40101) and has not expired (40140). It then builds the changed document: the stored one with each field set or removed, compared as a replace compares (`Value::equal_underlying_data`, so an integer sent at another width than the stored one is no change), `$revision` one higher (`OverflowError`, 10700, at `u64::MAX`), `$moderatedAt` the block's time and `$moderatedBy` the signer, everything else as stored, `$updatedAt` and its heights included. That document is judged as a replace judges one: `validate_document_properties` (the schema and `propertyConstraints`, with the `countOf` and `sumOf` totals read as they will be once it is stored, `read_property_constraint_aggregates_for_moderator_change`), `distinctFrom` and the shapes of `encryptedFor` properties, then, when a changed field is in a unique index, `Drive::validate_moderated_document_uniqueness`, the restore's check generalized to a changed document (only the changed fields are checked, and the document's own entries do not clash). Whoever owns the document is no protection: the fields are the moderators'. Nothing the document type prices is charged. -The action carries the contract and the changed document, and Drive stores it with `DocumentOperationType::UpdateDocument`, the replace's update, every index and aggregate of the type included. The document's storage flags name its owner, as a replace's do: the moderator pays for the bytes the change adds, and what the change frees (a smaller value, an index entry that moved) is refunded to the owner, who paid for it. A seated team's member does not have the change counted toward the team's action share: the changes of one document have no bound, and counting them would let a member farm it. A change that changes nothing is refused (10905) rather than written. `$updatedAt` does not move, so a change never opens a `moderatorAbilities.deleteWithin` window again: a moderator can not keep a post deletable by touching it. +The action carries the contract and the changed document, and Drive stores it with `DocumentOperationType::UpdateDocument`, the replace's update, every index and aggregate of the type included. The document's storage flags name its owner, as a replace's do: the moderator pays for the bytes the change adds, and what the change frees (a smaller value, an index entry that moved) is refunded to whoever paid for it, the owner, or the contract owner for a document whose storage they hold as its gas sponsor (whose stored document the update keeps with them). A seated team's member does not have the change counted toward the team's action share: the changes of one document have no bound, and counting them would let a member farm it. A change that changes nothing is refused (10905) rather than written. `$updatedAt` does not move, so a change never opens a `moderatorAbilities.deleteWithin` window again: a moderator can not keep a post deletable by touching it. The stamp is two system properties of document serialization format 3 (bits 9 and 10 of its time field flags): absent on a document no moderator has written, set only here and by the batch transformer, which stamps a moderator's create or replace of such a field (an action it did not judge is written unstamped), carried over by a replace that leaves the fields alone and by every transfer, purchase and price update, and put back by a restore with the rest of the bytes. A type that keeps fields for its moderators may index either, never in a unique index (`apply_moderator_abilities`, 10231; the core index check admits the two names from parser generation 3, `ParserGeneration::admit_moderation_stamp_indexes`). See [System Properties](../contract-keywords/system-properties.md#moderatedat-and-moderatedby). diff --git a/book/src/fees/overview.md b/book/src/fees/overview.md index 94af5b6e964..a1c3efefce9 100644 --- a/book/src/fees/overview.md +++ b/book/src/fees/overview.md @@ -225,13 +225,42 @@ and a batch that prefers falls back to the signer's balance. Execution v1 then charges whoever fee validation admitted. A batch that fails validation is never sponsored: its signer pays for the work that ran, and a request the document type does not offer is a paid rejection (`GasFeesPaidByNotAllowedError`, -40129). Storage refunds still go to the document's owner, whoever paid the -storage: a sponsored document refunds its owner when it is deleted or replaced -by a smaller one, even when the sponsor pays for that transition too. Each -token the sponsor hands out is therefore worth up to the storage fee of the -largest document the type allows, so a document type that offers sponsorship -should bound its documents' size (`maxLength`, `maxItems`) and price the -action accordingly. +40129). + +Storage refunds go to whoever paid for the storage. Execution v1 names the +sponsor it charges as the owner in the storage flags of everything the batch's +documents write (`record_gas_sponsor_as_storage_owner`; the owner's 32 bytes +are there either way and the estimate reads no owner, so no fee changes), and +Drive's contested document insert v1 names whoever the document's flags name +on the contest's end date entries. A sponsored document therefore refunds the +sponsor when it is deleted or shrinks. A document of a type with a `ttl` is +stored without storage flags and refunds nobody, sponsored or not. The sponsor +still pays the storage fee of every document it sponsors, up to the largest +the type allows, and gets back only the part not yet paid out to past epochs, +so a document type that offers sponsorship should bound its documents' size +(`maxLength`, `maxItems`, `maxBytes`) and price the action accordingly. + +A stored element names one owner. An update that grows an element, or shrinks +it, hands the whole element to the owner the update names, except that an +element holding the bytes of one epoch only keeps its flags when it shrinks in +a later epoch; an update at the same size keeps the flags too. Two rules +follow: + +- A sponsored update takes over every element it resizes so, with the refund + of what the document's owner paid for it before. +- An update that is not sponsored leaves a stored document the sponsor holds + with the sponsor. Drive's document update v1 reads the stored flags: when + they name the contract owner, the document is someone else's, and the + document type's token costs offer sponsorship, the stored document it writes + names the contract owner, a transfer's included. Otherwise one small replace + paid by the document's owner would hand them the whole element, and its + refund. The new index entries such an update adds are paid for by its signer + and name whom the update names. + +A document the contract owner gave away by a transfer that kept its size still +names the contract owner in its flags, and is treated alike: they paid for it. +A moderator's restore on such a type names the contract owner too (see +[Contract Moderation](../data-model/contract-moderation.md)). The signer's minimum balance pre-check runs before the contracts are loaded; its v1 asks a batch that requests sponsorship for its principal only diff --git a/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v1/mod.rs b/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v1/mod.rs index 9c32fec557e..e2744b9e1bf 100644 --- a/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v1/mod.rs +++ b/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v1/mod.rs @@ -21,7 +21,9 @@ use dpp::fee::Credits; use dpp::version::PlatformVersion; use drive::drive::identity::update::apply_balance_change_outcome::ApplyBalanceChangeOutcomeV0Methods; use drive::grovedb::Transaction; -use drive::state_transition_action::batch::{action_fee_operations, action_fees_total}; +use drive::state_transition_action::batch::{ + action_fee_operations, action_fees_total, record_gas_sponsor_as_storage_owner, +}; use drive::util::batch::DriveOperation; use std::collections::BTreeMap; @@ -40,10 +42,10 @@ where /// /// The fee is charged to whoever fee validation settled on (`settle_fees_of_event_v1`, of the /// same generation): the gas sponsor when their balance covers the gas estimated with them - /// paying, and the identity otherwise. Storage refunds still - /// go to whoever paid the storage originally, so a sponsored document refunds its owner when - /// it is deleted. A failed batch (`consensus_errors`) is never sponsored: its signer pays for - /// the work that ran. + /// paying, and the identity otherwise. A sponsor who pays is named as the owner of the storage + /// the batch's documents write (`record_gas_sponsor_as_storage_owner`), so the refunds of that + /// storage go back to them and not to the documents' owners. A failed batch + /// (`consensus_errors`) is never sponsored: its signer pays for the work that ran. /// /// A budgeted signing key is then charged with what the transition took from its identity: /// the balance it moved out (`removed_balance`) plus the fee the identity owes, net of the @@ -155,6 +157,9 @@ where // gas, by the rule that already governs a principal, and never the pots against // credits that were not there. let mut operations = operations; + if let Some(gas_sponsor) = paying_sponsor { + record_gas_sponsor_as_storage_owner(&mut operations, gas_sponsor.identity_id); + } operations.extend(action_fee_operations(payer_id, &action_fees)?); let action_fees_owed_by_identity = if paying_sponsor.is_some() { 0 diff --git a/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/validate_fees_of_event/v1/mod.rs b/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/validate_fees_of_event/v1/mod.rs index 2c3c34a99f0..13c0be4ba5b 100644 --- a/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/validate_fees_of_event/v1/mod.rs +++ b/packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/validate_fees_of_event/v1/mod.rs @@ -226,6 +226,11 @@ where // What the batch is estimated to cost when `payer_id` pays its gas, and so its action // fees, charged by the operations execution appends and merged with the batch's own as // execution applies them; and the part of the processing fee the user fee increase adds. + // + // Execution names a paying sponsor as the owner of the storage the batch writes + // (`record_gas_sponsor_as_storage_owner`); the estimate does not need to: it prices the + // operations without reading state, so it reads no owner, and an owner takes the same + // bytes whoever it is. let estimate_paid_by = |payer_id: Identifier| -> Result<(FeeResult, Credits), Error> { let mut operations = operations.clone(); operations.extend(action_fee_operations(payer_id, action_fees)?); diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/action_fees.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/action_fees.rs index f1d201505c8..aae6e09b782 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/action_fees.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/action_fees.rs @@ -6,8 +6,8 @@ //! sum of all credits changes by the gas alone. use super::gas_sponsorship::gas_sponsorship_tests::{ - balance_of, process_alone, total_fee, Sponsorship, GAS_SPONSOR_INSUFFICIENT_BALANCE, - IDENTITY_INSUFFICIENT_BALANCE, + balance_of, credits_in_trees_of, process_alone, total_fee, Sponsorship, + GAS_SPONSOR_INSUFFICIENT_BALANCE, IDENTITY_INSUFFICIENT_BALANCE, }; use super::*; @@ -1234,19 +1234,6 @@ mod action_fee_tests { (pot(ContractFeePot::Owner), pot(ContractFeePot::Moderators)) } - fn credits_in_trees_of( - platform: &TempPlatform, - tx: &Transaction, - platform_version: &PlatformVersion, - ) -> Credits { - platform - .drive - .calculate_total_credits_balance(Some(tx), &platform_version.drive) - .expect("expected to sum the credits") - .total_in_trees() - .expect("expected the credits to add up") - } - /// The agreement to what `document_type` declares for `action`, at the fee multiplier of /// the fee schedule fn agreeing_to( diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs index eb783055d19..fe089c7cb54 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs @@ -34,7 +34,7 @@ pub(crate) mod gas_sponsorship_tests { use dpp::identity::accessors::IdentitySettersV0; use dpp::identity::identity_public_key::accessors::v0::IdentityPublicKeyGettersV0; use dpp::identity::{Identity, IdentityPublicKey}; - use dpp::prelude::{Identifier, Revision}; + use dpp::prelude::{Identifier, IdentityNonce, Revision}; use dpp::state_transition::batch_transition::batched_transition::document_transition_action_type::DocumentTransitionActionType; use dpp::state_transition::batch_transition::methods::StateTransitionCreationOptions; use dpp::state_transition::StateTransition; @@ -288,22 +288,7 @@ pub(crate) mod gas_sponsorship_tests { /// The user's deletion of the card they created, without any token payment info async fn card_deletion_without_token_payment(&self) -> StateTransition { - let (document, _) = self.card_of(&self.user); - BatchTransition::new_document_deletion_transition_from_document( - document, - self.contract - .document_type_for_name("card") - .expect("expected the card document type"), - &self.user_key, - 3, - 0, - None, - &self.user_signer, - self.platform_version, - None, - ) - .await - .expect("expected a batch transition") + self.card_deletion_paying(3, None).await } /// The contract owner's own card creation, asking `requested` for the gas @@ -320,28 +305,96 @@ pub(crate) mod gas_sponsorship_tests { .await } + /// A payment of at most `maximum` of the game's second token, which pays for replacing, + /// deleting and transferring a card, asking `requested` for the gas + fn game_token_payment(maximum: TokenAmount, requested: GasFeesPaidBy) -> TokenPaymentInfo { + TokenPaymentInfo::V0(TokenPaymentInfoV0 { + payment_token_contract_id: None, + token_contract_position: 1, + minimum_token_cost: None, + maximum_token_cost: Some(maximum), + gas_fees_paid_by: requested, + }) + } + /// The user's replacement of the card they created, at `revision`, preferring that the /// contract owner pays the gas async fn card_replacement(&self, revision: Revision) -> StateTransition { let (mut document, _) = self.card_of(&self.user); document.set("attack", 5.into()); document.set_revision(Some(revision)); + self.card_replacement_of(document, 3, GasFeesPaidBy::PreferContractOwner) + .await + } + /// The user's replacement of the card they created, at `revision` and identity contract + /// `nonce`, giving it a description of `description_length` characters and asking + /// `requested` for the gas + async fn card_replacement_describing( + &self, + revision: Revision, + nonce: IdentityNonce, + description_length: usize, + requested: GasFeesPaidBy, + ) -> StateTransition { + let (mut document, _) = self.card_of(&self.user); + document.set("description", "d".repeat(description_length).into()); + document.set_revision(Some(revision)); + self.card_replacement_of(document, nonce, requested).await + } + + /// The user's replacement of their card by `document`, at identity contract `nonce`, + /// paying its token and asking `requested` for the gas + async fn card_replacement_of( + &self, + document: Document, + nonce: IdentityNonce, + requested: GasFeesPaidBy, + ) -> StateTransition { BatchTransition::new_document_replacement_transition_from_document( document, self.contract .document_type_for_name("card") .expect("expected the card document type"), &self.user_key, - 3, + nonce, + 0, + Some(Self::game_token_payment(2, requested)), + &self.user_signer, + self.platform_version, + None, + ) + .await + .expect("expected a batch transition") + } + + /// The user's deletion of the card they created, at identity contract `nonce`, paying + /// its token and the gas themselves: the card game offers no sponsorship of a deletion + async fn card_deletion(&self, nonce: IdentityNonce) -> StateTransition { + self.card_deletion_paying( + nonce, + Some(Self::game_token_payment(1, GasFeesPaidBy::DocumentOwner)), + ) + .await + } + + /// The user's deletion of the card they created, at identity contract `nonce`, with + /// `token_payment_info` + async fn card_deletion_paying( + &self, + nonce: IdentityNonce, + token_payment_info: Option, + ) -> StateTransition { + let (document, _) = self.card_of(&self.user); + BatchTransition::new_document_deletion_transition_from_document( + document, + self.contract + .document_type_for_name("card") + .expect("expected the card document type"), + &self.user_key, + nonce, 0, - Some(TokenPaymentInfo::V0(TokenPaymentInfoV0 { - payment_token_contract_id: None, - token_contract_position: 1, - minimum_token_cost: None, - maximum_token_cost: Some(2), - gas_fees_paid_by: GasFeesPaidBy::PreferContractOwner, - })), + token_payment_info, &self.user_signer, self.platform_version, None, @@ -350,6 +403,53 @@ pub(crate) mod gas_sponsorship_tests { .expect("expected a batch transition") } + /// Gives the user `amount` of the game's second token, which pays for replacing and + /// deleting a card + fn give_the_user_game_tokens(&self, amount: TokenAmount) { + let token_id: Identifier = calculate_token_id(self.contract.id().as_bytes(), 1).into(); + add_tokens_to_identity(&self.platform, token_id, self.user.id(), amount); + } + + /// Processes `transition` in a block of its own and commits it + fn process_and_commit( + &self, + transition: &StateTransition, + ) -> StateTransitionExecutionResult { + self.process_in_and_commit(transition, &BlockInfo::default()) + } + + /// `process_and_commit` in the block `block_info` describes + fn process_in_and_commit( + &self, + transition: &StateTransition, + block_info: &BlockInfo, + ) -> StateTransitionExecutionResult { + let tx = self.platform.drive.grove.start_transaction(); + let result = self.process_in(transition, block_info, &tx); + self.platform + .drive + .grove + .commit_transaction(tx) + .unwrap() + .expect("expected to commit the transition"); + result + } + + /// The committed credits held in the trees + fn committed_credits_in_trees(&self) -> Credits { + let tx = self.platform.drive.grove.start_transaction(); + credits_in_trees_of(&self.platform, &tx, self.platform_version) + } + + /// The committed balances of the user and of the contract owner + fn committed_credits(&self) -> (Credits, Credits) { + let tx = self.platform.drive.grove.start_transaction(); + ( + self.credits(&self.user, &tx), + self.credits(&self.contract_owner, &tx), + ) + } + /// The card `creator` creates, always the same one, with the entropy of its id pub(crate) fn card_of(&self, creator: &Identity) -> (Document, Bytes32) { let mut rng = StdRng::seed_from_u64(433); @@ -593,6 +693,20 @@ pub(crate) mod gas_sponsorship_tests { .expect("expected a balance") } + /// The credits held in the trees in `tx` + pub(crate) fn credits_in_trees_of( + platform: &TempPlatform, + tx: &drive::grovedb::Transaction, + platform_version: &PlatformVersion, + ) -> Credits { + platform + .drive + .calculate_total_credits_balance(Some(tx), &platform_version.drive) + .expect("expected to sum the credits") + .total_in_trees() + .expect("expected the credits to add up") + } + pub(crate) fn total_fee(result: &StateTransitionExecutionResult) -> Credits { match result { SuccessfulExecution { fee_result, .. } => fee_result.total_base_fee(), @@ -867,19 +981,13 @@ pub(crate) mod gas_sponsorship_tests { // and on a recheck, while its validation mode stays what it is. let setup = Sponsorship::new(GasFeesPaidBy::ContractOwner, dash_to_credits!(0.1), 0, 15); // Replacing a card costs 2 of the game's second token - let gas_token_id: Identifier = calculate_token_id(setup.contract.id().as_bytes(), 1).into(); - add_tokens_to_identity(&setup.platform, gas_token_id, setup.user.id(), 5); + setup.give_the_user_game_tokens(5); let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; - let tx = setup.platform.drive.grove.start_transaction(); - assert_matches!(setup.process(&creation, &tx), SuccessfulExecution { .. }); - setup - .platform - .drive - .grove - .commit_transaction(tx) - .unwrap() - .expect("expected to commit the creation"); + assert_matches!( + setup.process_and_commit(&creation), + SuccessfulExecution { .. } + ); for (revision, expected) in [(2, Vec::::new()), (3, vec![INVALID_DOCUMENT_REVISION])] { let replacement = setup.card_replacement(revision).await; @@ -988,6 +1096,224 @@ pub(crate) mod gas_sponsorship_tests { } } + // ---------- Storage refunds ---------- + + /// What processing `transition` in the block `block_info` describes and committing it + /// refunded the user and the contract owner. Checks that whoever paid was charged the fee + /// less their own refund, that the other was credited theirs, and that only the fee less + /// the refunds left the credits held in the trees. + fn settle( + setup: &Sponsorship, + transition: &StateTransition, + block_info: &BlockInfo, + paid_by_the_contract_owner: bool, + ) -> (Option, Option) { + let (user_credits, contract_owner_credits) = setup.committed_credits(); + let credits_in_trees = setup.committed_credits_in_trees(); + + let result = setup.process_in_and_commit(transition, block_info); + + let SuccessfulExecution { fee_result, .. } = &result else { + panic!("expected the transition to execute, got {result:?}"); + }; + let fee = fee_result.total_base_fee(); + let refunded_to_user = fee_result + .fee_refunds + .calculate_refunds_amount_for_identity(setup.user.id()); + let refunded_to_contract_owner = fee_result + .fee_refunds + .calculate_refunds_amount_for_identity(setup.contract_owner.id()); + let (user_fee, contract_owner_fee) = if paid_by_the_contract_owner { + (0, fee) + } else { + (fee, 0) + }; + assert_eq!( + setup.committed_credits(), + ( + user_credits - user_fee + refunded_to_user.unwrap_or_default(), + contract_owner_credits - contract_owner_fee + + refunded_to_contract_owner.unwrap_or_default(), + ), + "the payer is charged the fee, and each is credited their refund" + ); + assert_eq!( + setup.committed_credits_in_trees(), + credits_in_trees - fee + + refunded_to_user.unwrap_or_default() + + refunded_to_contract_owner.unwrap_or_default(), + "only the fee less the refunds leaves the trees" + ); + (refunded_to_user, refunded_to_contract_owner) + } + + #[tokio::test] + async fn should_refund_a_sponsored_cards_storage_to_the_contract_owner() { + // The contract owner paid for the card's storage, so its refund is theirs: a user who + // deletes the card pays for the deletion and gets nothing back. + let setup = Sponsorship::new( + GasFeesPaidBy::ContractOwner, + dash_to_credits!(0.1), + dash_to_credits!(0.1), + 15, + ); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; + settle(&setup, &creation, &block, true); + + let deletion = setup.card_deletion(3).await; + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &deletion, &block, false); + + assert_eq!(refunded_to_user, None, "the user is refunded nothing"); + assert!( + refunded_to_contract_owner.is_some_and(|refund| refund > 0), + "the contract owner is refunded the storage they paid for" + ); + } + + #[tokio::test] + async fn should_keep_a_sponsored_card_with_the_contract_owner_through_the_users_own_replacement( + ) { + // Growing the card at the user's own expense would hand the whole stored card to the + // user, and with it the contract owner's refund. The card stays the contract owner's: + // they get the refund of what the user added too. + let setup = Sponsorship::new( + GasFeesPaidBy::ContractOwner, + dash_to_credits!(0.1), + dash_to_credits!(0.1), + 15, + ); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; + settle(&setup, &creation, &block, true); + + let replacement = setup + .card_replacement_describing(2, 3, 200, GasFeesPaidBy::DocumentOwner) + .await; + assert_eq!( + settle(&setup, &replacement, &block, false), + (None, None), + "the user pays for their own replacement, which frees nothing" + ); + + let deletion = setup.card_deletion(4).await; + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &deletion, &block, false); + + assert_eq!(refunded_to_user, None, "the user is refunded nothing"); + assert!(refunded_to_contract_owner.is_some_and(|refund| refund > 0)); + } + + #[tokio::test] + async fn should_refund_the_user_the_index_entries_their_own_replacement_added() { + // Moving an indexed value writes new index entries: the user pays for them in full, so + // they are the user's, while the stored card stays the contract owner's and the entries + // it replaced refund the contract owner. + let setup = Sponsorship::new( + GasFeesPaidBy::ContractOwner, + dash_to_credits!(0.1), + dash_to_credits!(0.1), + 15, + ); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; + settle(&setup, &creation, &block, true); + + let (mut document, _) = setup.card_of(&setup.user); + document.set("attack", 5.into()); + document.set_revision(Some(2)); + let replacement = setup + .card_replacement_of(document, 3, GasFeesPaidBy::DocumentOwner) + .await; + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &replacement, &block, false); + assert_eq!(refunded_to_user, None); + assert!( + refunded_to_contract_owner.is_some_and(|refund| refund > 0), + "the replaced index entries refund the contract owner" + ); + + let deletion = setup.card_deletion(4).await; + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &deletion, &block, false); + + assert!( + refunded_to_user.is_some_and(|refund| refund > 0), + "the user is refunded the index entries they paid for" + ); + assert!( + refunded_to_contract_owner.is_some_and(|refund| refund > 0), + "the contract owner is refunded the card" + ); + } + + #[tokio::test] + async fn should_give_a_users_card_to_the_contract_owner_who_sponsors_its_replacement() { + // A stored element has one owner, and a sponsored write that grows it takes it: the + // contract owner paid for what was added to the card, and is refunded what the user + // paid for it before too. The index entries the replacement leaves as they are stay + // the user's. A user who would rather keep the card pays for the replacement. + let setup = Sponsorship::new( + GasFeesPaidBy::ContractOwner, + dash_to_credits!(0.1), + dash_to_credits!(0.1), + 15, + ); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup.card_creation(GasFeesPaidBy::DocumentOwner).await; + settle(&setup, &creation, &block, false); + + let replacement = setup + .card_replacement_describing(2, 3, 200, GasFeesPaidBy::ContractOwner) + .await; + assert_eq!( + settle(&setup, &replacement, &block, true), + (None, None), + "the contract owner pays for the replacement, which frees nothing" + ); + + let deletion = setup.card_deletion(4).await; + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &deletion, &block, false); + + assert!( + refunded_to_contract_owner.is_some_and(|refund| refund > 0), + "the contract owner is refunded the card" + ); + assert!( + refunded_to_user.is_some_and(|refund| refund > 0), + "the user is refunded the index entries" + ); + } + + #[tokio::test] + async fn should_refund_the_user_who_paid_when_the_contract_owner_could_not() { + // A preference the contract owner cannot honour falls back to the user, who then paid + // for the storage and is refunded it. + let setup = Sponsorship::new(GasFeesPaidBy::ContractOwner, 0, dash_to_credits!(0.1), 15); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup + .card_creation(GasFeesPaidBy::PreferContractOwner) + .await; + settle(&setup, &creation, &block, false); + + let deletion = setup.card_deletion(3).await; + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &deletion, &block, false); + + assert!( + refunded_to_user.is_some_and(|refund| refund > 0), + "the user is refunded the storage they paid for" + ); + assert_eq!(refunded_to_contract_owner, None); + } + // ---------- Optional token costs ---------- #[tokio::test] @@ -1105,15 +1431,10 @@ pub(crate) mod gas_sponsorship_tests { 0, ); let creation = setup.card_creation_without_token_payment().await; - let tx = setup.platform.drive.grove.start_transaction(); - assert_matches!(setup.process(&creation, &tx), SuccessfulExecution { .. }); - setup - .platform - .drive - .grove - .commit_transaction(tx) - .unwrap() - .expect("expected to commit the creation"); + assert_matches!( + setup.process_and_commit(&creation), + SuccessfulExecution { .. } + ); let deletion = setup.card_deletion_without_token_payment().await; assert_eq!(setup.check_tx(&deletion), Vec::::new()); @@ -1133,15 +1454,10 @@ pub(crate) mod gas_sponsorship_tests { 15, ); let creation = setup.card_creation(GasFeesPaidBy::DocumentOwner).await; - let tx = setup.platform.drive.grove.start_transaction(); - assert_matches!(setup.process(&creation, &tx), SuccessfulExecution { .. }); - setup - .platform - .drive - .grove - .commit_transaction(tx) - .unwrap() - .expect("expected to commit the creation"); + assert_matches!( + setup.process_and_commit(&creation), + SuccessfulExecution { .. } + ); let deletion = setup.card_deletion_without_token_payment().await; assert_eq!( setup.check_tx(&deletion), diff --git a/packages/rs-drive/src/drive/document/insert_contested/add_contested_document_for_contract_operations/v1/mod.rs b/packages/rs-drive/src/drive/document/insert_contested/add_contested_document_for_contract_operations/v1/mod.rs index 073bfc9cfbd..fa436f78f68 100644 --- a/packages/rs-drive/src/drive/document/insert_contested/add_contested_document_for_contract_operations/v1/mod.rs +++ b/packages/rs-drive/src/drive/document/insert_contested/add_contested_document_for_contract_operations/v1/mod.rs @@ -15,7 +15,7 @@ use crate::query::vote_poll_vote_state_query::{ use crate::query::GroveError; use crate::util::grove_operations::QueryTarget::QueryTargetValue; use crate::util::grove_operations::{BatchDeleteUpTreeApplyType, DirectQueryType}; -use crate::util::object_size_info::DocumentAndContractInfo; +use crate::util::object_size_info::{DocumentAndContractInfo, DocumentInfoV0Methods}; use dpp::block::block_info::BlockInfo; use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::data_contract::document_type::ContestedIndexResolution; @@ -96,7 +96,16 @@ impl Drive { platform_version, )?; - let owner_id = document_and_contract_info.owned_document_info.owner_id; + // The vote poll's end date entries are paid for with the document, so they name whoever + // its storage flags name: its creator, or the gas sponsor of a sponsored creation + // (protocol version 14, `record_gas_sponsor_as_storage_owner`), so that their refund, + // when a second contender's arrival moves the end date, goes to whoever paid. + let end_date_storage_owner_id = document_and_contract_info + .owned_document_info + .document_info + .get_storage_flags_ref() + .and_then(|storage_flags| storage_flags.owner_id().copied()) + .or(document_and_contract_info.owned_document_info.owner_id); if !contest_already_existed { if let Some(vote_poll_stored_start_info) = also_insert_vote_poll_stored_info { @@ -129,7 +138,7 @@ impl Drive { }; self.add_vote_poll_end_date_query_operations( - owner_id, + end_date_storage_owner_id, VotePoll::ContestedDocumentResourceVotePoll( contested_document_resource_vote_poll.into(), ), @@ -246,7 +255,7 @@ impl Drive { )?; self.add_vote_poll_end_date_query_operations( - owner_id, + end_date_storage_owner_id, vote_poll, vote_end, block_info, diff --git a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs index 528f186d5fb..4f6cfe28546 100644 --- a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs +++ b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs @@ -32,10 +32,12 @@ use dpp::block::block_info::BlockInfo; use dpp::data_contract::accessors::v0::DataContractV0Getters; use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV2Getters}; +use crate::state_transition_action::batch::document_type_offers_gas_sponsorship; use dpp::document::document_methods::DocumentMethodsV0; use dpp::document::serialization_traits::DocumentPlatformConversionMethodsV0; use dpp::document::{Document, DocumentV0Getters}; use dpp::fee::fee_result::FeeResult; +use dpp::prelude::Identifier; use crate::drive::document::paths::{ contract_document_type_path, @@ -84,6 +86,25 @@ fn known_index_path(path: &[DriveKeyInfo]) -> Result>, Error> { .collect() } +/// Whether a gas sponsor holds a stored document, so that its refunds go to them (protocol +/// version 14): its stored flags name the contract owner as the owner of a document they do not +/// own, on a document type whose token costs let them pay the gas. A sponsored write records +/// them so (`record_gas_sponsor_as_storage_owner`). +/// +/// A transfer that kept the size of a document left its flags as they were, so a document the +/// contract owner gave away that way also still names them. It is treated alike: the contract +/// owner paid for that storage too. +fn storage_held_by_gas_sponsor( + contract_owner_id: Identifier, + document_type: DocumentTypeRef, + old_document: &Document, + old_storage_flags: Option<&StorageFlags>, +) -> bool { + old_storage_flags.and_then(StorageFlags::owner_id) == Some(contract_owner_id.as_bytes()) + && old_document.owner_id() != contract_owner_id + && document_type_offers_gas_sponsorship(document_type) +} + /// `[0]`-key reference-bucket `TreeType` dispatch for the /// terminator level. Mirrors the dispatch in /// `add_reference_for_index_level_for_contract_operations_v0` — @@ -162,6 +183,11 @@ impl Drive { /// sides, computing the old entry's layout from the old document's /// nullness and the new entry's from the new document's. /// + /// v1 also leaves a stored document a gas sponsor holds with the + /// sponsor when an update that is not sponsored rewrites it + /// (`storage_held_by_gas_sponsor`), reading the stored document + /// before it writes the new one. + /// /// The `[0]` reference-bucket tree-type dispatch and everything /// else match v0. pub(in crate::drive::document::update) fn update_document_for_contract_operations_v1( @@ -222,13 +248,14 @@ impl Drive { let contract = document_and_contract_info.contract; let document_type = document_and_contract_info.document_type; let owner_id = document_and_contract_info.owned_document_info.owner_id; - let Some((document, storage_flags)) = document_and_contract_info + let Some(document_id) = document_and_contract_info .owned_document_info .document_info - .get_borrowed_document_and_storage_flags() + .get_borrowed_document() + .map(|document| document.id()) else { return Err(Error::Drive(DriveError::CorruptedCodeExecution( - "must have document and storage flags", + "must have a document", ))); }; // we need to construct the path for documents on the contract @@ -242,25 +269,13 @@ impl Drive { let contract_documents_primary_key_path = contract_documents_primary_key_path(contract.id_ref().as_bytes(), document_type.name()); - // Per-document reference is built per-index below because - // summable indexes need `Element::ReferenceWithSumItem` (sum - // contribution propagates to ancestor sum trees) while plain - // indexes use `Element::Reference`. The non-sum reference is - // computed once here for reuse on all non-summable indexes; - // summable indexes build their own variant inside the loop. - let document_reference = make_document_reference( - document, - document_and_contract_info.document_type, - storage_flags, - ); - // next we need to get the old document from storage let old_document_element = if document_type.documents_keep_history() { let contract_documents_keeping_history_primary_key_path_for_document_id = contract_documents_keeping_history_primary_key_path_for_document_id( contract.id_ref().as_bytes(), document_type.name().as_str(), - document.id_ref().as_slice(), + document_id.as_slice(), ); // When keeping document history the 0 is a reference that points to the current value // O is just on one byte, so we have at most one hop of size 1 (1 byte) @@ -275,7 +290,7 @@ impl Drive { } else { self.grove_get_raw( (&contract_documents_primary_key_path).into(), - document.id().as_slice(), + document_id.as_slice(), DirectQueryType::StatefulDirectQuery, transaction, &mut batch_operations, @@ -283,10 +298,89 @@ impl Drive { )? }; + let Some(old_document_element) = old_document_element else { + return Err(Error::Drive(DriveError::UpdatingDocumentThatDoesNotExist( + "document being updated does not exist", + ))); + }; + // Accept BOTH plain `Item` (non-summable doctypes) AND + // `ItemWithSumItem` (summable doctypes — primary storage on + // doctypes with `documents_summable: Some(_)` is written as + // ItemWithSumItem by `add_document_to_primary_storage`). + // The sum_value is discarded here because the reload only + // needs the document body + flags; the new write below + // re-computes the sum from the freshly-supplied document. + let (old_serialized_document, element_flags) = match old_document_element { + Element::Item(bytes, flags) => (bytes, flags), + Element::ItemWithSumItem(bytes, _sum_value, flags) => (bytes, flags), + _ => { + return Err(Error::Drive(DriveError::CorruptedDocumentNotItem( + "old document is not an item or item-with-sum-item", + ))) + } + }; + // The stored size of the document before the change, which a type with a `ttl` needs + // to prepay the deletion of the bytes the change adds. + let old_document_bytes = old_serialized_document.len() as u64; + let mut old_document = Document::from_bytes( + old_serialized_document.as_slice(), + document_type, + platform_version, + )?; + let old_storage_flags = StorageFlags::map_some_element_flags_ref(&element_flags)?; + + let Some((document, storage_flags)) = document_and_contract_info + .owned_document_info + .document_info + .get_borrowed_document_and_storage_flags() + else { + return Err(Error::Drive(DriveError::CorruptedCodeExecution( + "must have document and storage flags", + ))); + }; + + // Per-document reference is built per-index below because + // summable indexes need `Element::ReferenceWithSumItem` (sum + // contribution propagates to ancestor sum trees) while plain + // indexes use `Element::Reference`. The non-sum reference is + // computed once here for reuse on all non-summable indexes; + // summable indexes build their own variant inside the loop. + let document_reference = make_document_reference( + document, + document_and_contract_info.document_type, + storage_flags, + ); + + // A document whose stored element a gas sponsor holds stays theirs when an update that is + // not sponsored rewrites that element, a transfer included: GroveDB hands an element + // whose size the update changes to the owner the update names (unless it shrinks a + // single-epoch element in a later epoch, which keeps its flags), so the rewrite names + // the sponsor. A sponsored update names the sponsor already. A reference the update + // refreshes keeps its stored flags, and every other element it writes is new, paid for + // by the signer, and names whom the update names; a type keeping history writes each + // version as a new element too. + let sponsor_held_primary_storage = (!document_type.documents_keep_history() + && storage_held_by_gas_sponsor( + contract.owner_id(), + document_type, + &old_document, + old_storage_flags.as_ref(), + )) + .then(|| { + let mut primary_storage = document_and_contract_info.clone(); + primary_storage + .owned_document_info + .document_info + .set_storage_flags_owner(contract.owner_id().to_buffer()); + primary_storage + }); + // we need to store the document for it's primary key // we should be overriding if the document_type does not have history enabled self.add_document_to_primary_storage( - &document_and_contract_info, + sponsor_held_primary_storage + .as_ref() + .unwrap_or(&document_and_contract_info), block_info, true, estimated_costs_only_with_layer_info, @@ -295,52 +389,21 @@ impl Drive { platform_version, )?; - // The stored size of the document before the change, which a type with a `ttl` needs - // to prepay the deletion of the bytes the change adds. - let old_document_bytes: u64; - let old_document_info = if let Some(old_document_element) = old_document_element { - // Accept BOTH plain `Item` (non-summable doctypes) AND - // `ItemWithSumItem` (summable doctypes — primary storage on - // doctypes with `documents_summable: Some(_)` is written as - // ItemWithSumItem by `add_document_to_primary_storage`). - // The sum_value is discarded here because the reload only - // needs the document body + flags; the new write below - // re-computes the sum from the freshly-supplied document. - let (old_serialized_document, element_flags) = match old_document_element { - Element::Item(bytes, flags) => (bytes, flags), - Element::ItemWithSumItem(bytes, _sum_value, flags) => (bytes, flags), - _ => { - return Err(Error::Drive(DriveError::CorruptedDocumentNotItem( - "old document is not an item or item-with-sum-item", - ))) - } - }; - old_document_bytes = old_serialized_document.len() as u64; - let mut old_document = Document::from_bytes( - old_serialized_document.as_slice(), + if !document_type.derived_index_properties().is_empty() { + let values = self.derived_index_values( + &old_document, + Some(document), + contract, document_type, + false, + transaction, + &mut batch_operations, platform_version, )?; - if !document_type.derived_index_properties().is_empty() { - let values = self.derived_index_values( - &old_document, - Some(document), - contract, - document_type, - false, - transaction, - &mut batch_operations, - platform_version, - )?; - set_derived_index_values(&mut old_document, values); - } - let storage_flags = StorageFlags::map_some_element_flags_ref(&element_flags)?; - DocumentOwnedInfo((old_document, storage_flags.map(Cow::Owned))) - } else { - return Err(Error::Drive(DriveError::UpdatingDocumentThatDoesNotExist( - "document being updated does not exist", - ))); - }; + set_derived_index_values(&mut old_document, values); + } + let old_document_info = + DocumentOwnedInfo((old_document, old_storage_flags.map(Cow::Owned))); let mut batch_insertion_cache: HashSet>> = HashSet::new(); // Pre-built tree of every index path in the doctype. Walking diff --git a/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs b/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs index 5b775a33cac..134496b68c3 100644 --- a/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs +++ b/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs @@ -5,6 +5,7 @@ use crate::drive::contract::moderation::types::{ use crate::error::drive::DriveError; use crate::error::Error; use crate::state_transition_action::action_convert_to_operations::DriveHighLevelOperationConverter; +use crate::state_transition_action::batch::document_type_offers_gas_sponsorship; use crate::state_transition_action::contract::contract_user_moderation::v0::{ ContractDocumentChangeContext, ContractDocumentDeletionContext, ContractDocumentRemovalRecordContext, ContractDocumentRestorationContext, @@ -266,22 +267,36 @@ impl DriveHighLevelOperationConverter for ContractUserModerationTransitionAction // restoration and nothing else let replaced_record_size = removal_record_size(&removal)? .saturating_sub(CONTRACT_DOCUMENT_RESTORATION_SIZE as u32); + let document_type = data_contract_fetch_info + .contract + .document_type_for_name(&document_type_name)?; let estimated_kept_fields_size = estimated_document_removal_kept_fields_size( - data_contract_fetch_info - .contract - .document_type_for_name(&document_type_name)?, + document_type, platform_version, )?; // The document goes back the way a create puts it in, every index and - // aggregate of its type included. Its storage flags name its owner, as - // they did before the deletion: the moderator pays for the bytes, and - // the refund of a later deletion is the owner's, as it always was. Then - // the record, marked restored in place: two operations on one key + // aggregate of its type included. Its storage flags name its owner: the + // moderator pays for the bytes, and the refund of a later deletion is + // the owner's. On a type that offers gas sponsorship they name the + // contract owner instead (protocol version 14): its documents' storage + // is the sponsor's as a rule (`record_gas_sponsor_as_storage_owner`), + // the restore is paid for by the contract owner or one of their + // moderators, and the document's owner, who paid for none of it, keeps + // it with them through their own updates (Drive's document update v1). + // Then the record, marked restored in place: two operations on one key // would fail the batch, so it is replaced rather than deleted and // written again, and it is never deleted. - let storage_flags = - StorageFlags::new_single_epoch(epoch.index, Some(owner_id.to_buffer())); + let storage_owner_id = + if document_type_offers_gas_sponsorship(document_type) { + data_contract_fetch_info.contract.owner_id() + } else { + owner_id + }; + let storage_flags = StorageFlags::new_single_epoch( + epoch.index, + Some(storage_owner_id.to_buffer()), + ); operations.push(DocumentOperation(DocumentOperationType::AddDocument { owned_document_info: OwnedDocumentInfo { document_info: DocumentOwnedInfo(( @@ -324,7 +339,10 @@ impl DriveHighLevelOperationConverter for ContractUserModerationTransitionAction // The document is updated the way a replace updates it, every index and // aggregate of its type included. Its storage flags name its owner, as a // replace's do: the moderator pays for the bytes the change adds, and a - // refund of the document's storage stays the owner's, as it always was. + // refund of the document's storage goes to whoever its stored flags + // name, its owner, or the contract owner for a document whose storage + // they hold as its gas sponsor (Drive's document update v1 keeps it + // with them). let owner_id = document.owner_id(); let storage_flags = StorageFlags::new_single_epoch(epoch.index, Some(owner_id.to_buffer())); diff --git a/packages/rs-drive/src/state_transition_action/batch/mod.rs b/packages/rs-drive/src/state_transition_action/batch/mod.rs index 6cee61f8c7f..586e0699426 100644 --- a/packages/rs-drive/src/state_transition_action/batch/mod.rs +++ b/packages/rs-drive/src/state_transition_action/batch/mod.rs @@ -3,7 +3,9 @@ use crate::state_transition_action::batch::v0::BatchTransitionActionV0; use crate::state_transition_action::contract::moderators_pot_settlement::ModeratorsPotSettlement; use derive_more::From; use dpp::data_contract::accessors::v0::DataContractV0Getters; -use dpp::data_contract::document_type::accessors::DocumentTypeV0Getters; +use dpp::data_contract::document_type::accessors::{DocumentTypeV0Getters, DocumentTypeV1Getters}; +use dpp::data_contract::document_type::DocumentTypeRef; +use dpp::tokens::gas_fees_paid_by::GasFeesPaidBy; use crate::drive::contract_groups::types::ContractGroupMembershipsForContract; use dpp::fee::fee_result::FeeResult; use dpp::consensus::ConsensusError; @@ -18,7 +20,9 @@ use dpp::data_contract::document_type::action_fees::{ ActionFeePricing, ContractFeePot, DocumentActionFee, FEE_MULTIPLIER_PERMILLE_BASE, }; use dpp::prelude::FeeMultiplier; -use crate::util::batch::drive_op_batch::{ContractFeePotOperationType, IdentityOperationType}; +use crate::util::batch::drive_op_batch::{ + ContractFeePotOperationType, DocumentOperationType, IdentityOperationType, +}; use crate::util::batch::DriveOperation; use crate::state_transition_action::batch::batched_transition::document_transition::document_base_transition_action::DocumentBaseTransitionActionAccessorsV0; @@ -171,6 +175,83 @@ pub fn action_fee_operations( Ok(operations) } +/// Names the gas sponsor as the owner of the storage the batch's documents write (protocol +/// version 14), once fee validation settled that the sponsor pays: storage refunds go to whoever +/// paid for the storage, and a document's would otherwise go to its owner, who could delete it +/// and keep what the sponsor paid. +/// +/// A stored element names one owner. An update that grows it, or shrinks it in the epoch it was +/// paid in or once it holds bytes of several epochs, hands the whole element to the owner the +/// update names; a single-epoch element shrunk in a later epoch keeps its flags. So a sponsored +/// write takes over an element of the document's owner that it resizes so, including what the +/// owner paid for before. Updates that are not sponsored leave a stored document the sponsor +/// holds with the sponsor (Drive's document update v1), or the owner could take it back with +/// one small replace of their own. A contested document's vote poll end date entries name +/// whoever its flags name (Drive's contested document insert v1). +/// +/// Deletes name no owner (their refunds go to the owners recorded on what they remove), history +/// entries, which are never deleted, refund nobody, and the withdrawal and multi-document +/// operations are never part of a batch. A document of a type with a `ttl` is stored without +/// flags and refunds nobody. +/// +/// Execution applies it once fee validation settled that the sponsor pays. The estimate needs +/// no owner, and an owner takes no more bytes than any other, so it changes no fee. +pub fn record_gas_sponsor_as_storage_owner( + operations: &mut [DriveOperation], + gas_sponsor_id: Identifier, +) { + for operation in operations { + let DriveOperation::DocumentOperation(document_operation) = operation else { + continue; + }; + match document_operation { + DocumentOperationType::AddDocument { + owned_document_info, + .. + } + | DocumentOperationType::AddContestedDocument { + owned_document_info, + .. + } + | DocumentOperationType::UpdateDocument { + owned_document_info, + .. + } + | DocumentOperationType::AddDocumentAndDeleteConsumed { + owned_document_info, + .. + } => owned_document_info + .document_info + .set_storage_flags_owner(gas_sponsor_id.to_buffer()), + DocumentOperationType::DeleteDocument { .. } + | DocumentOperationType::ForceDeleteDocument { .. } + | DocumentOperationType::DeleteIndexOnlyDocument { .. } + | DocumentOperationType::AddWithdrawalDocument { .. } + | DocumentOperationType::MultipleDocumentOperationsForSameContractDocumentType { + .. + } + | DocumentOperationType::DocumentHistory { .. } => {} + } + } +} + +/// Whether a document type's token costs let the contract owner pay the gas of some action on +/// its documents (protocol version 14): only then can the contract owner hold the storage of a +/// document someone else owns as its gas sponsor. +pub fn document_type_offers_gas_sponsorship(document_type: DocumentTypeRef) -> bool { + [ + document_type.document_creation_token_cost(), + document_type.document_replacement_token_cost(), + document_type.document_deletion_token_cost(), + document_type.document_transfer_token_cost(), + document_type.document_update_price_token_cost(), + document_type.document_purchase_token_cost(), + ] + .into_iter() + .flatten() + .any(|token_cost| token_cost.gas_fees_paid_by != GasFeesPaidBy::DocumentOwner) +} + /// Who pays the gas of a whole batch, as `GasFeesPaidBy::resolve` names it for each of its /// transitions #[derive(Debug, Clone, Copy, PartialEq, Eq)] diff --git a/packages/rs-drive/src/util/object_size_info/document_info.rs b/packages/rs-drive/src/util/object_size_info/document_info.rs index 5683c71abe0..4cb7aa568a1 100644 --- a/packages/rs-drive/src/util/object_size_info/document_info.rs +++ b/packages/rs-drive/src/util/object_size_info/document_info.rs @@ -104,6 +104,23 @@ impl DocumentInfo<'_> { } } } + + /// Names `owner_id` as the owner of the storage this document writes, the identity its + /// storage refunds go to. Storage flags without an owner refund nobody and stay that way, + /// as does a document without flags or a worst-case size. The owner takes no more bytes + /// than any other, so the write costs the same. + pub fn set_storage_flags_owner(&mut self, owner_id: [u8; 32]) { + let storage_flags = match self { + DocumentInfo::DocumentOwnedInfo((_, storage_flags)) + | DocumentInfo::DocumentRefInfo((_, storage_flags)) + | DocumentInfo::DocumentRefAndSerialization((_, _, storage_flags)) + | DocumentInfo::DocumentAndSerialization((_, _, storage_flags)) => storage_flags, + DocumentInfo::DocumentEstimatedAverageSize(_) => return, + }; + if let Some(storage_flags) = storage_flags { + storage_flags.to_mut().set_owner_id(owner_id); + } + } } impl DocumentInfoV0Methods for DocumentInfo<'_> { diff --git a/packages/rs-platform-version/src/version/v14.rs b/packages/rs-platform-version/src/version/v14.rs index 526599c176e..b0e6894e5bc 100644 --- a/packages/rs-platform-version/src/version/v14.rs +++ b/packages/rs-platform-version/src/version/v14.rs @@ -289,7 +289,16 @@ pub const PROTOCOL_VERSION_14: ProtocolVersion = 14; /// requests sponsorship. A failed batch is never sponsored, so check tx /// validates the state of a sponsored batch whose signer is under the fee /// minimum in full, on the first check and on every recheck (mempool -/// policy, not consensus). +/// policy, not consensus). Storage refunds go to whoever paid for the +/// storage: `execute_event` v1 names the sponsor it charges as the owner in +/// the storage flags of everything the batch's documents write +/// (`record_gas_sponsor_as_storage_owner`), contested document insert v1 +/// names whoever the document's flags name on the contest's end date +/// entries, document update v1 (`storage_held_by_gas_sponsor`) writes the +/// stored document of a document whose flags name the contract owner, on a +/// type whose token costs offer sponsorship, with the contract owner when an +/// update that is not sponsored rewrites it, a transfer included, and a +/// moderator's restore on such a type names the contract owner. /// 12. **Optional token costs**: a document type's token cost may declare /// `optional: true` (v3 meta-schema). A transition that leaves /// `$tokenPaymentInfo` out then pays no token and its signer pays the gas From de3556bee5c3ba4be793e8009ed6c9ad74f0596e Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Thu, 1 Oct 2026 12:14:41 +0700 Subject: [PATCH 2/6] test(dashmate): expect the build's config format version in the image migration test Since the 5.0.0-beta.1 bump the package version is newer than the newest config migration (4.2.0), so a migrated config records the package version. The test hard-coded 4.2.0; it now expects what getConfigFormatVersion gives for this build. Co-Authored-By: Claude Opus 5.5 --- .../unit/config/configFile/tenderdashImageMigration.spec.js | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/dashmate/test/unit/config/configFile/tenderdashImageMigration.spec.js b/packages/dashmate/test/unit/config/configFile/tenderdashImageMigration.spec.js index 300e666ca85..14196c8ffe7 100644 --- a/packages/dashmate/test/unit/config/configFile/tenderdashImageMigration.spec.js +++ b/packages/dashmate/test/unit/config/configFile/tenderdashImageMigration.spec.js @@ -2,6 +2,7 @@ import fs from 'fs'; import path from 'path'; import getBaseConfigFactory from '../../../../configs/defaults/getBaseConfigFactory.js'; import getConfigFileMigrationsFactory from '../../../../configs/getConfigFileMigrationsFactory.js'; +import getConfigFormatVersion from '../../../../src/config/configFile/getConfigFormatVersion.js'; import migrateConfigFileFactory from '../../../../src/config/configFile/migrateConfigFileFactory.js'; import { PACKAGE_ROOT_DIR } from '../../../../src/constants.js'; @@ -38,7 +39,10 @@ describe('Tenderdash image migration', () => { expect(migrated.configs.withoutDocker).to.deep.equal({ platform: { drive: { tenderdash: {} } }, }); - expect(migrated.configFormatVersion).to.equal('4.2.0'); + // The format this build writes: the newest migration, or the package version once a + // release passes it + expect(migrated.configFormatVersion) + .to.equal(getConfigFormatVersion(getMigrations(), version)); expect(migrateConfigFile(migrated, migrated.configFormatVersion, version)).to.equal(migrated); }); } From 9265524961fbb463848a773fdd73c7318073d91a Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Thu, 1 Oct 2026 12:15:45 +0700 Subject: [PATCH 3/6] fix(platform)!: a moderator restore names the document owner again (PV14) A restore is not sponsored: the moderator who signs it pays for the bytes, and a gas sponsor who held the deleted document's storage was already settled by the deletion. Naming the contract owner could credit them with a moderator's payment, so the restore keeps the existing rule (the document owner), and the comments and book say why. Co-Authored-By: Claude Opus 5.5 --- book/src/data-model/contract-moderation.md | 2 +- book/src/fees/overview.md | 2 -- .../contract_user_moderation_transition.rs | 35 ++++++------------- .../rs-platform-version/src/version/v14.rs | 3 +- 4 files changed, 13 insertions(+), 29 deletions(-) diff --git a/book/src/data-model/contract-moderation.md b/book/src/data-model/contract-moderation.md index 1c3b22889cd..f4ba3c4eda1 100644 --- a/book/src/data-model/contract-moderation.md +++ b/book/src/data-model/contract-moderation.md @@ -180,7 +180,7 @@ ContractUserModerationAction::RestoreDocument { It names no identity and no id: the document is inside the bytes, and its id and owner with it. The transform checks, in order and each refusal paid: the document type exists (10406) and carries `moderatorAbilities.delete` (41115, only such a type keeps records), the signer is the owner or a moderator (41101, whoever deleted), the bytes decode under the type (a basic decoding error, never an execution error: the bytes are the signer's), the document has a removal record (`ContractDocumentRemovalNotFoundError`, 41119) that is not marked restored (`ContractDocumentAlreadyRestoredError`, 41122: the document is live), block time is within `SystemLimits::contract_document_restore_window_ms` of the removal, a week, the last millisecond included (`DocumentRestoreWindowElapsedError`, 41120), the bytes hash to what the record holds (`DocumentRestoreHashMismatchError`, 41121: the document as it was, not an edit of it), and no other document of the type holds a value of one of its unique indexes (`DuplicateUniqueIndexError`, 40105: the value was free while the document was gone, and someone may have taken it). The record read is billed; the hash pins everything else, so the owner, the revision, the timestamps, the references and the schema are not checked again. Whether the document's owner is banned is not asked either: a ban stops writes, it never removed documents. -The action carries the contract, the decoded document and the record marked restored by the signer at the block's time, so Drive puts the document back through the ordinary insert (`DocumentOperationType::AddDocument`, every index and aggregate of the type included) and replaces the record in place, without reading again. The restored document's storage flags name its owner: the signer pays for the bytes, and the refund of a later deletion is the owner's. On a document type whose token costs offer gas sponsorship they name the contract owner instead: such a type's documents are the sponsor's storage as a rule, the contract owner or one of their moderators pays for the restore, and Drive's document update v1 keeps the document with the contract owner through its owner's own updates, so the owner can not take the restore's storage, and its refund, for nothing. Nothing the document type prices is charged, neither its creation token cost nor its `actionFees` creation fee, and no fee agreement is asked: a moderator undoes a moderation, it does not create content. The restore is proved by the record, now marked restored and holding the hash of the bytes the transition carried; the verifier reads the document's id out of those bytes under the contract's document type, so it needs the contract, which the SDKs register with their context provider before broadcasting. +The action carries the contract, the decoded document and the record marked restored by the signer at the block's time, so Drive puts the document back through the ordinary insert (`DocumentOperationType::AddDocument`, every index and aggregate of the type included) and replaces the record in place, without reading again. The restored document's storage flags name its owner: the signer pays for the bytes, and the refund of a later deletion is the owner's. A gas sponsor who held the deleted document's storage was settled by the deletion (forfeited, or refunded to them with `deleteRefundsOwner`), so the restore is new storage they have no claim on. Nothing the document type prices is charged, neither its creation token cost nor its `actionFees` creation fee, and no fee agreement is asked: a moderator undoes a moderation, it does not create content. The restore is proved by the record, now marked restored and holding the hash of the bytes the transition carried; the verifier reads the document's id out of those bytes under the contract's document type, so it needs the contract, which the SDKs register with their context provider before broadcasting. Two consequences follow from the document coming back byte for byte. Its `$updatedAt` does not move, so a type with `moderatorAbilities.deleteWithin` may have settled it while it was gone: no moderator deletes it again alone until its author edits it, though the author still can, and on a type that sets `deleteSettled` the seated team can, by a fresh proposal (the action that deleted it ran and is closed). A deletion the team approved together is never restored: it is the only removal made after the document settled, since a moderator alone deletes up to the settling time and the team only after it, so the restore transform compares the removal time with the settling time of the document the bytes hash to (no read), and refuses the restore of a later removal, paid (`SettledDeletionNotRestorableError`, 41209), so no single moderator undoes what the leader and the members agreed on. And a type with a contested index can not carry `moderatorAbilities.delete` at all (`InvalidContractStructure`, 10231): a contested index only takes a document through a vote, which no restore can go through, so such a deletion could never be undone. The bytes are decoded under the type as the contract holds it when the restore is processed, and the hash is of the document serialized under the type as it was when the document was deleted: a contract update that changes the type's layout inside the window (a property added, say) leaves the record unrestorable, since bytes that decode under the new layout cannot hash to what the record holds. A client therefore serializes under the contract's current version, as Drive does, and keeps the document rather than the bytes. diff --git a/book/src/fees/overview.md b/book/src/fees/overview.md index a1c3efefce9..e523df55d1b 100644 --- a/book/src/fees/overview.md +++ b/book/src/fees/overview.md @@ -259,8 +259,6 @@ follow: A document the contract owner gave away by a transfer that kept its size still names the contract owner in its flags, and is treated alike: they paid for it. -A moderator's restore on such a type names the contract owner too (see -[Contract Moderation](../data-model/contract-moderation.md)). The signer's minimum balance pre-check runs before the contracts are loaded; its v1 asks a batch that requests sponsorship for its principal only diff --git a/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs b/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs index 134496b68c3..109ab8e8689 100644 --- a/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs +++ b/packages/rs-drive/src/state_transition_action/action_convert_to_operations/contract/contract_user_moderation_transition.rs @@ -5,7 +5,6 @@ use crate::drive::contract::moderation::types::{ use crate::error::drive::DriveError; use crate::error::Error; use crate::state_transition_action::action_convert_to_operations::DriveHighLevelOperationConverter; -use crate::state_transition_action::batch::document_type_offers_gas_sponsorship; use crate::state_transition_action::contract::contract_user_moderation::v0::{ ContractDocumentChangeContext, ContractDocumentDeletionContext, ContractDocumentRemovalRecordContext, ContractDocumentRestorationContext, @@ -267,36 +266,24 @@ impl DriveHighLevelOperationConverter for ContractUserModerationTransitionAction // restoration and nothing else let replaced_record_size = removal_record_size(&removal)? .saturating_sub(CONTRACT_DOCUMENT_RESTORATION_SIZE as u32); - let document_type = data_contract_fetch_info - .contract - .document_type_for_name(&document_type_name)?; let estimated_kept_fields_size = estimated_document_removal_kept_fields_size( - document_type, + data_contract_fetch_info + .contract + .document_type_for_name(&document_type_name)?, platform_version, )?; // The document goes back the way a create puts it in, every index and // aggregate of its type included. Its storage flags name its owner: the // moderator pays for the bytes, and the refund of a later deletion is - // the owner's. On a type that offers gas sponsorship they name the - // contract owner instead (protocol version 14): its documents' storage - // is the sponsor's as a rule (`record_gas_sponsor_as_storage_owner`), - // the restore is paid for by the contract owner or one of their - // moderators, and the document's owner, who paid for none of it, keeps - // it with them through their own updates (Drive's document update v1). - // Then the record, marked restored in place: two operations on one key - // would fail the batch, so it is replaced rather than deleted and - // written again, and it is never deleted. - let storage_owner_id = - if document_type_offers_gas_sponsorship(document_type) { - data_contract_fetch_info.contract.owner_id() - } else { - owner_id - }; - let storage_flags = StorageFlags::new_single_epoch( - epoch.index, - Some(storage_owner_id.to_buffer()), - ); + // the owner's. A gas sponsor who held the deleted document's storage + // was settled by the deletion (forfeited, or refunded to them), so the + // restore is new storage they have no claim on. Then the record, marked + // restored in place: two operations on one key would fail the batch, so + // it is replaced rather than deleted and written again, and it is never + // deleted. + let storage_flags = + StorageFlags::new_single_epoch(epoch.index, Some(owner_id.to_buffer())); operations.push(DocumentOperation(DocumentOperationType::AddDocument { owned_document_info: OwnedDocumentInfo { document_info: DocumentOwnedInfo(( diff --git a/packages/rs-platform-version/src/version/v14.rs b/packages/rs-platform-version/src/version/v14.rs index b0e6894e5bc..c1f807fbe21 100644 --- a/packages/rs-platform-version/src/version/v14.rs +++ b/packages/rs-platform-version/src/version/v14.rs @@ -297,8 +297,7 @@ pub const PROTOCOL_VERSION_14: ProtocolVersion = 14; /// entries, document update v1 (`storage_held_by_gas_sponsor`) writes the /// stored document of a document whose flags name the contract owner, on a /// type whose token costs offer sponsorship, with the contract owner when an -/// update that is not sponsored rewrites it, a transfer included, and a -/// moderator's restore on such a type names the contract owner. +/// update that is not sponsored rewrites it, a transfer included. /// 12. **Optional token costs**: a document type's token cost may declare /// `optional: true` (v3 meta-schema). A transition that leaves /// `$tokenPaymentInfo` out then pays no token and its signer pays the gas From c431447ba5505b144a2402713a1666a47f72eebc Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Thu, 1 Oct 2026 15:24:17 +0700 Subject: [PATCH 4/6] fix(platform)!: keep a sponsor-held history version with the sponsor within its block (PV14) A type keeping history stores each version under the block's time, so a second update to a document in the same block rewrites the version the first wrote, in place. Document update v1 skipped history types when keeping a sponsor-held document with the sponsor, so a user's own rewrite could take that version, and its refund. History versions are never deleted, so naming the sponsor on every version of a sponsor-held document moves no other refund. The primary write now borrows the document with only its storage flags replaced instead of cloning it, the sponsorship predicate is crate private, and tests cover a same-block history rewrite and a transfer of a sponsor-held card. Co-Authored-By: Claude Opus 5.5 --- .../batch/tests/document/gas_sponsorship.rs | 155 ++++++++++++++++++ .../v1/mod.rs | 39 +++-- .../src/state_transition_action/batch/mod.rs | 2 +- .../util/object_size_info/document_info.rs | 38 +++++ 4 files changed, 216 insertions(+), 18 deletions(-) diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs index fe089c7cb54..316cf6a96d1 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs @@ -45,6 +45,9 @@ pub(crate) mod gas_sponsorship_tests { }; use dpp::tokens::token_payment_info::v0::TokenPaymentInfoV0; use dpp::tokens::token_payment_info::TokenPaymentInfo; + use dpp::data_contract::schema::DataContractSchemaMethodsV0; + use dpp::document::DocumentV0Setters; + use drive::query::DriveDocumentQuery; use drive::util::test_helpers::setup_contract; use simple_signer::signer::SimpleSigner; @@ -435,6 +438,34 @@ pub(crate) mod gas_sponsorship_tests { result } + /// The identity the committed storage flags of the user's card name as its storage owner + fn stored_card_storage_owner(&self) -> Option { + let (card, _) = self.card_of(&self.user); + let query = DriveDocumentQuery::new_primary_key_single_item_query( + &self.contract, + self.contract + .document_type_for_name("card") + .expect("expected the card document type"), + card.id(), + ); + let mut documents = self + .platform + .drive + .query_documents_with_flags( + query, + None, + false, + None, + Some(self.platform_version.protocol_version), + ) + .expect("expected to query the card") + .documents_owned(); + let (_, storage_flags) = documents.pop().expect("expected the card to be stored"); + storage_flags + .and_then(|storage_flags| storage_flags.owner_id().copied()) + .map(Identifier::from) + } + /// The committed credits held in the trees fn committed_credits_in_trees(&self) -> Credits { let tx = self.platform.drive.grove.start_transaction(); @@ -1251,6 +1282,130 @@ pub(crate) mod gas_sponsorship_tests { ); } + #[tokio::test] + async fn should_keep_a_sponsored_card_with_the_contract_owner_through_a_transfer() { + // The user transfers the card the contract owner paid for, at their own expense: the + // stored card stays the contract owner's, and the index entries the transfer moves are + // the recipient's. + let mut setup = Sponsorship::new( + GasFeesPaidBy::ContractOwner, + dash_to_credits!(0.1), + dash_to_credits!(0.1), + 15, + ); + let (recipient, _, _) = setup_identity(&mut setup.platform, 571, dash_to_credits!(0.1)); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; + settle(&setup, &creation, &block, true); + assert_eq!( + setup.stored_card_storage_owner(), + Some(setup.contract_owner.id()) + ); + + let (mut card, _) = setup.card_of(&setup.user); + card.increment_revision() + .expect("expected the revision to increment"); + let transfer = BatchTransition::new_document_transfer_transition_from_document( + card, + setup + .contract + .document_type_for_name("card") + .expect("expected the card document type"), + recipient.id(), + &setup.user_key, + 3, + 0, + Some(Sponsorship::game_token_payment( + 1, + GasFeesPaidBy::DocumentOwner, + )), + &setup.user_signer, + setup.platform_version, + None, + ) + .await + .expect("expected a batch transition"); + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &transfer, &block, false); + + assert_eq!(refunded_to_user, None, "the user is refunded nothing"); + assert!( + refunded_to_contract_owner.is_some_and(|refund| refund > 0), + "the index entries the transfer moves refund the contract owner" + ); + assert_eq!( + setup.stored_card_storage_owner(), + Some(setup.contract_owner.id()), + "the stored card stays the contract owner's" + ); + } + + #[tokio::test] + async fn should_keep_a_sponsored_history_version_with_the_contract_owner_when_rewritten_in_its_block( + ) { + // A type keeping history stores each version under the block's time, so a second + // update in the same block rewrites the version the first wrote. The version the + // contract owner paid for stays theirs when the user grows it at their own expense, so + // the user's later shrink in that block refunds the contract owner. + let setup = Sponsorship::build_customized( + PlatformVersion::latest(), + GasFeesPaidBy::ContractOwner, + false, + dash_to_credits!(0.1), + dash_to_credits!(0.1), + 15, + None, + |contract| { + let mut schema = contract + .document_type_for_name("card") + .expect("expected the card document type") + .schema() + .clone(); + schema + .set_value("documentsKeepHistory", true.into()) + .expect("expected to keep history"); + schema + .set_value("canBeDeleted", false.into()) + .expect("expected to refuse deletion"); + contract + .set_document_schema( + "card", + schema, + false, + &mut vec![], + PlatformVersion::latest(), + ) + .expect("expected the card type to keep history"); + }, + ); + assert!(setup + .contract + .document_type_for_name("card") + .expect("expected the card document type") + .documents_keep_history()); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; + settle(&setup, &creation, &block, true); + + let growth = setup + .card_replacement_describing(2, 3, 200, GasFeesPaidBy::DocumentOwner) + .await; + assert_eq!(settle(&setup, &growth, &block, false), (None, None)); + + let shrink = setup + .card_replacement_describing(3, 4, 10, GasFeesPaidBy::DocumentOwner) + .await; + let (refunded_to_user, refunded_to_contract_owner) = settle(&setup, &shrink, &block, false); + + assert_eq!(refunded_to_user, None, "the user is refunded nothing"); + assert!( + refunded_to_contract_owner.is_some_and(|refund| refund > 0), + "the version the contract owner paid for refunds them what the shrink frees" + ); + } + #[tokio::test] async fn should_give_a_users_card_to_the_contract_owner_who_sponsors_its_replacement() { // A stored element has one owner, and a sponsored write that grows it takes it: the diff --git a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs index 4f6cfe28546..b5356ff2852 100644 --- a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs +++ b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs @@ -25,7 +25,8 @@ use crate::util::object_size_info::DocumentInfo::DocumentOwnedInfo; use crate::util::object_size_info::DriveKeyInfo::{Key, KeyRef, KeySize}; use crate::util::object_size_info::PathKeyElementInfo::PathKeyRefElement; use crate::util::object_size_info::{ - DocumentAndContractInfo, DocumentInfo, DocumentInfoV0Methods, DriveKeyInfo, PathKeyInfo, + DocumentAndContractInfo, DocumentInfo, DocumentInfoV0Methods, DriveKeyInfo, OwnedDocumentInfo, + PathKeyInfo, }; use crate::util::storage_flags::StorageFlags; use dpp::block::block_info::BlockInfo; @@ -357,22 +358,26 @@ impl Drive { // single-epoch element in a later epoch, which keeps its flags), so the rewrite names // the sponsor. A sponsored update names the sponsor already. A reference the update // refreshes keeps its stored flags, and every other element it writes is new, paid for - // by the signer, and names whom the update names; a type keeping history writes each - // version as a new element too. - let sponsor_held_primary_storage = (!document_type.documents_keep_history() - && storage_held_by_gas_sponsor( - contract.owner_id(), - document_type, - &old_document, - old_storage_flags.as_ref(), - )) - .then(|| { - let mut primary_storage = document_and_contract_info.clone(); - primary_storage - .owned_document_info - .document_info - .set_storage_flags_owner(contract.owner_id().to_buffer()); - primary_storage + // by the signer, and names whom the update names. A type keeping history stores each + // version under the block's time, so a second update in the same block rewrites the + // version the first wrote; its versions are never deleted, so naming the sponsor on a + // new one moves no refund but that rewrite's. + let sponsor_held_primary_storage = storage_held_by_gas_sponsor( + contract.owner_id(), + document_type, + &old_document, + old_storage_flags.as_ref(), + ) + .then(|| DocumentAndContractInfo { + owned_document_info: OwnedDocumentInfo { + document_info: document_and_contract_info + .owned_document_info + .document_info + .borrowed_with_storage_flags_owner(contract.owner_id().to_buffer()), + owner_id, + }, + contract, + document_type, }); // we need to store the document for it's primary key diff --git a/packages/rs-drive/src/state_transition_action/batch/mod.rs b/packages/rs-drive/src/state_transition_action/batch/mod.rs index 586e0699426..7ce75e65c71 100644 --- a/packages/rs-drive/src/state_transition_action/batch/mod.rs +++ b/packages/rs-drive/src/state_transition_action/batch/mod.rs @@ -238,7 +238,7 @@ pub fn record_gas_sponsor_as_storage_owner( /// Whether a document type's token costs let the contract owner pay the gas of some action on /// its documents (protocol version 14): only then can the contract owner hold the storage of a /// document someone else owns as its gas sponsor. -pub fn document_type_offers_gas_sponsorship(document_type: DocumentTypeRef) -> bool { +pub(crate) fn document_type_offers_gas_sponsorship(document_type: DocumentTypeRef) -> bool { [ document_type.document_creation_token_cost(), document_type.document_replacement_token_cost(), diff --git a/packages/rs-drive/src/util/object_size_info/document_info.rs b/packages/rs-drive/src/util/object_size_info/document_info.rs index 4cb7aa568a1..1c101022bb5 100644 --- a/packages/rs-drive/src/util/object_size_info/document_info.rs +++ b/packages/rs-drive/src/util/object_size_info/document_info.rs @@ -121,6 +121,44 @@ impl DocumentInfo<'_> { storage_flags.to_mut().set_owner_id(owner_id); } } + + /// The same document, borrowed, with storage flags naming `owner_id`: for one write that + /// names a different owner than the others of the same document. Only the flags are + /// copied; the document and its serialization are borrowed. + pub fn borrowed_with_storage_flags_owner(&self, owner_id: [u8; 32]) -> DocumentInfo<'_> { + let with_owner = |storage_flags: &Option>| { + storage_flags.as_ref().map(|storage_flags| { + let mut storage_flags = storage_flags.clone().into_owned(); + storage_flags.set_owner_id(owner_id); + Cow::Owned(storage_flags) + }) + }; + match self { + DocumentInfo::DocumentOwnedInfo((document, storage_flags)) => { + DocumentInfo::DocumentRefInfo((document, with_owner(storage_flags))) + } + DocumentInfo::DocumentRefInfo((document, storage_flags)) => { + DocumentInfo::DocumentRefInfo((document, with_owner(storage_flags))) + } + DocumentInfo::DocumentRefAndSerialization((document, serialization, storage_flags)) => { + DocumentInfo::DocumentRefAndSerialization(( + document, + serialization, + with_owner(storage_flags), + )) + } + DocumentInfo::DocumentAndSerialization((document, serialization, storage_flags)) => { + DocumentInfo::DocumentRefAndSerialization(( + document, + serialization.as_slice(), + with_owner(storage_flags), + )) + } + DocumentInfo::DocumentEstimatedAverageSize(size) => { + DocumentInfo::DocumentEstimatedAverageSize(*size) + } + } + } } impl DocumentInfoV0Methods for DocumentInfo<'_> { From e1cc0f89c73827940713fd6b21881623ebec2903 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Thu, 1 Oct 2026 16:49:03 +0700 Subject: [PATCH 5/6] fix(platform)!: a new history version names its payer, not the sponsor (PV14) The sponsor-held check reads the current history version through the `[0]` reference, but an update writes its version under the block's time. Only a second update in the same block rewrites a stored version; a version written in a later block is a new element the signer pays for in full. Document update v1 now keeps naming the sponsor on a history version only when this block's version key already exists (a metered existence read, made only for sponsor-held documents of history types), and a test covers a later-block version shrunk in its own block. Co-Authored-By: Claude Opus 5.5 --- .../batch/tests/document/gas_sponsorship.rs | 55 ++++++++++++++++--- .../v1/mod.rs | 25 +++++++-- 2 files changed, 67 insertions(+), 13 deletions(-) diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs index 316cf6a96d1..7404234115b 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs @@ -1341,13 +1341,9 @@ pub(crate) mod gas_sponsorship_tests { ); } - #[tokio::test] - async fn should_keep_a_sponsored_history_version_with_the_contract_owner_when_rewritten_in_its_block( - ) { - // A type keeping history stores each version under the block's time, so a second - // update in the same block rewrites the version the first wrote. The version the - // contract owner paid for stays theirs when the user grows it at their own expense, so - // the user's later shrink in that block refunds the contract owner. + /// The card game with a card type that keeps history, its creation and replacement + /// offering the contract owner's gas + fn history_card_game() -> Sponsorship { let setup = Sponsorship::build_customized( PlatformVersion::latest(), GasFeesPaidBy::ContractOwner, @@ -1384,6 +1380,17 @@ pub(crate) mod gas_sponsorship_tests { .document_type_for_name("card") .expect("expected the card document type") .documents_keep_history()); + setup + } + + #[tokio::test] + async fn should_keep_a_sponsored_history_version_with_the_contract_owner_when_rewritten_in_its_block( + ) { + // A type keeping history stores each version under the block's time, so a second + // update in the same block rewrites the version the first wrote. The version the + // contract owner paid for stays theirs when the user grows it at their own expense, so + // the user's later shrink in that block refunds the contract owner. + let setup = history_card_game(); setup.give_the_user_game_tokens(5); let block = BlockInfo::default(); let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; @@ -1406,6 +1413,40 @@ pub(crate) mod gas_sponsorship_tests { ); } + #[tokio::test] + async fn should_leave_a_history_version_the_user_paid_for_with_the_user_in_a_later_block() { + // A version written in a later block than the sponsored one is a new element, paid for + // by the user: it names the user, so the user's shrink of it in that block refunds + // the user. + let setup = history_card_game(); + setup.give_the_user_game_tokens(5); + let creation_block = BlockInfo::default(); + let later_block = BlockInfo { + time_ms: 1_000, + height: 1, + ..Default::default() + }; + let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; + settle(&setup, &creation, &creation_block, true); + + let growth = setup + .card_replacement_describing(2, 3, 200, GasFeesPaidBy::DocumentOwner) + .await; + assert_eq!(settle(&setup, &growth, &later_block, false), (None, None)); + + let shrink = setup + .card_replacement_describing(3, 4, 10, GasFeesPaidBy::DocumentOwner) + .await; + let (refunded_to_user, refunded_to_contract_owner) = + settle(&setup, &shrink, &later_block, false); + + assert!( + refunded_to_user.is_some_and(|refund| refund > 0), + "the user is refunded what the shrink frees of the version they paid for" + ); + assert_eq!(refunded_to_contract_owner, None); + } + #[tokio::test] async fn should_give_a_users_card_to_the_contract_owner_who_sponsors_its_replacement() { // A stored element has one owner, and a sponsored write that grows it takes it: the diff --git a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs index b5356ff2852..a7b754b92dd 100644 --- a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs +++ b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs @@ -47,7 +47,7 @@ use crate::drive::document::paths::{ }; use dpp::data_contract::document_type::methods::DocumentTypeBasicMethods; use dpp::data_contract::document_type::{ - DocumentTypeRef, Index, IndexBucketing, IndexCountability, IndexLevel, + DocumentPropertyType, DocumentTypeRef, Index, IndexBucketing, IndexCountability, IndexLevel, }; use dpp::version::PlatformVersion; use grovedb::batch::key_info::KeyInfo; @@ -359,15 +359,28 @@ impl Drive { // the sponsor. A sponsored update names the sponsor already. A reference the update // refreshes keeps its stored flags, and every other element it writes is new, paid for // by the signer, and names whom the update names. A type keeping history stores each - // version under the block's time, so a second update in the same block rewrites the - // version the first wrote; its versions are never deleted, so naming the sponsor on a - // new one moves no refund but that rewrite's. - let sponsor_held_primary_storage = storage_held_by_gas_sponsor( + // version under the block's time: only a second update in the same block rewrites the + // version the first wrote, so only then does the version keep naming the sponsor, and a + // version written in a later block is new and names whom the update names. + let sponsor_held_primary_storage = (storage_held_by_gas_sponsor( contract.owner_id(), document_type, &old_document, old_storage_flags.as_ref(), - ) + ) && (!document_type.documents_keep_history() + || self.grove_has_raw( + (&contract_documents_keeping_history_primary_key_path_for_document_id( + contract.id_ref().as_bytes(), + document_type.name().as_str(), + document_id.as_slice(), + )) + .into(), + DocumentPropertyType::encode_date_timestamp(block_info.time_ms).as_slice(), + DirectQueryType::StatefulDirectQuery, + transaction, + &mut batch_operations, + drive_version, + )?)) .then(|| DocumentAndContractInfo { owned_document_info: OwnedDocumentInfo { document_info: document_and_contract_info From 49bd8d9b91e4e062109e63932affec92080713da Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Thu, 1 Oct 2026 19:21:29 +0700 Subject: [PATCH 6/6] fix(platform)!: price the history version probe alike in estimate and execution (PV14) Document update v1 probes whether a sponsor-held document's history already holds this block's version. The probe was metered in execution only, while the fee estimate prices an update as an insert and never saw it. Both now charge it at its average-case (stateless) cost: the estimate for every update of a history type that offers sponsorship, execution when it probes, which reads state without metering it again. An update whose flags already name the sponsor (a sponsored one) skips the check and the probe altogether. Co-Authored-By: Claude Opus 5.5 --- .../batch/tests/document/gas_sponsorship.rs | 32 +++++ .../v1/mod.rs | 122 ++++++++++++++---- 2 files changed, 132 insertions(+), 22 deletions(-) diff --git a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs index 7404234115b..bd1a25b4d60 100644 --- a/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs +++ b/packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/batch/tests/document/gas_sponsorship.rs @@ -1413,6 +1413,38 @@ pub(crate) mod gas_sponsorship_tests { ); } + #[tokio::test] + async fn should_estimate_a_sponsor_held_history_rewrite_at_no_less_than_it_costs() { + // Keeping a history version with its sponsor probes whether the block's version exists: + // the estimate charges that probe too, so it never falls short of the execution. + let setup = history_card_game(); + setup.give_the_user_game_tokens(5); + let block = BlockInfo::default(); + let creation = setup.card_creation(GasFeesPaidBy::ContractOwner).await; + settle(&setup, &creation, &block, true); + + let growth = setup + .card_replacement_describing(2, 3, 200, GasFeesPaidBy::DocumentOwner) + .await; + let result = setup.process_and_commit(&growth); + + let SuccessfulExecution { + estimated_fees: Some(estimated_fees), + fee_result, + .. + } = &result + else { + panic!("expected an execution with an estimated fee, got {result:?}"); + }; + assert!( + estimated_fees.processing_fee >= fee_result.processing_fee, + "estimated {} below the {} the rewrite cost", + estimated_fees.processing_fee, + fee_result.processing_fee + ); + assert!(estimated_fees.total_base_fee() >= fee_result.total_base_fee()); + } + #[tokio::test] async fn should_leave_a_history_version_the_user_paid_for_with_the_user_in_a_later_block() { // A version written in a later block than the sponsored one is a new element, paid for diff --git a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs index a7b754b92dd..49eff7c0249 100644 --- a/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs +++ b/packages/rs-drive/src/drive/document/update/internal/update_document_for_contract_operations/v1/mod.rs @@ -17,6 +17,7 @@ use crate::drive::Drive; use crate::error::drive::DriveError; use crate::error::Error; use crate::fees::op::LowLevelDriveOperation; +use crate::util::grove_operations::QueryTarget::QueryTargetValue; use crate::util::grove_operations::{ BatchDeleteUpTreeApplyType, BatchInsertApplyType, BatchInsertTreeApplyType, DirectQueryType, QueryType, @@ -45,7 +46,7 @@ use crate::drive::document::paths::{ contract_documents_keeping_history_primary_key_path_for_document_id, contract_documents_primary_key_path, }; -use dpp::data_contract::document_type::methods::DocumentTypeBasicMethods; +use dpp::data_contract::document_type::methods::{DocumentTypeBasicMethods, DocumentTypeV0Methods}; use dpp::data_contract::document_type::{ DocumentPropertyType, DocumentTypeRef, Index, IndexBucketing, IndexCountability, IndexLevel, }; @@ -106,6 +107,46 @@ fn storage_held_by_gas_sponsor( && document_type_offers_gas_sponsorship(document_type) } +impl Drive { + /// Charges the probe of whether a document's history already holds a version at the block's + /// time (protocol version 14) at its average-case cost. Execution and the fee estimate both + /// charge it this way, so they price the probe alike, whatever the node's state holds. + fn add_history_version_probe_cost( + &self, + contract_id: &[u8], + document_type: DocumentTypeRef, + document_id: &[u8], + block_info: &BlockInfo, + drive_operations: &mut Vec, + platform_version: &PlatformVersion, + ) -> Result<(), Error> { + let in_tree_type = if document_type.documents_summable().is_some() { + TreeType::SumTree + } else { + TreeType::NormalTree + }; + self.grove_has_raw( + (&contract_documents_keeping_history_primary_key_path_for_document_id( + contract_id, + document_type.name().as_str(), + document_id, + )) + .into(), + DocumentPropertyType::encode_date_timestamp(block_info.time_ms).as_slice(), + DirectQueryType::StatelessDirectQuery { + in_tree_type, + query_target: QueryTargetValue( + document_type.estimated_size(platform_version)? as u32 + ), + }, + None, + drive_operations, + &platform_version.drive, + )?; + Ok(()) + } +} + /// `[0]`-key reference-bucket `TreeType` dispatch for the /// terminator level. Mirrors the dispatch in /// `add_reference_for_index_level_for_contract_operations_v0` — @@ -224,14 +265,37 @@ impl Drive { .is_document_size() || estimated_costs_only_with_layer_info.is_some() { - return self.estimate_document_change_as_insert_operations_v1( + let contract = document_and_contract_info.contract; + let document_type = document_and_contract_info.document_type; + let document_id = document_and_contract_info + .owned_document_info + .document_info + .get_borrowed_document() + .map(|document| document.id().to_buffer()) + .unwrap_or_default(); + let mut operations = self.estimate_document_change_as_insert_operations_v1( document_and_contract_info, block_info, previous_batch_operations, estimated_costs_only_with_layer_info, transaction, platform_version, - ); + )?; + // An update that may keep a history version with its gas sponsor probes whether + // the version exists (below), at the cost charged here too. + if document_type.documents_keep_history() + && document_type_offers_gas_sponsorship(document_type) + { + self.add_history_version_probe_cost( + contract.id_ref().as_bytes(), + document_type, + &document_id, + block_info, + &mut operations, + platform_version, + )?; + } + return Ok(operations); } // A type with derived index properties (protocol version 14) keys its documents by @@ -361,32 +425,46 @@ impl Drive { // by the signer, and names whom the update names. A type keeping history stores each // version under the block's time: only a second update in the same block rewrites the // version the first wrote, so only then does the version keep naming the sponsor, and a - // version written in a later block is new and names whom the update names. - let sponsor_held_primary_storage = (storage_held_by_gas_sponsor( - contract.owner_id(), - document_type, - &old_document, - old_storage_flags.as_ref(), - ) && (!document_type.documents_keep_history() - || self.grove_has_raw( - (&contract_documents_keeping_history_primary_key_path_for_document_id( + // version written in a later block is new and names whom the update names. The probe + // is charged at its average-case cost, as the fee estimate charges it. + let contract_owner_id = contract.owner_id(); + let sponsor_held_primary_storage = (storage_flags.and_then(StorageFlags::owner_id) + != Some(contract_owner_id.as_bytes()) + && storage_held_by_gas_sponsor( + contract_owner_id, + document_type, + &old_document, + old_storage_flags.as_ref(), + ) + && (!document_type.documents_keep_history() || { + self.add_history_version_probe_cost( contract.id_ref().as_bytes(), - document_type.name().as_str(), + document_type, document_id.as_slice(), - )) - .into(), - DocumentPropertyType::encode_date_timestamp(block_info.time_ms).as_slice(), - DirectQueryType::StatefulDirectQuery, - transaction, - &mut batch_operations, - drive_version, - )?)) + block_info, + &mut batch_operations, + platform_version, + )?; + self.grove_has_raw( + (&contract_documents_keeping_history_primary_key_path_for_document_id( + contract.id_ref().as_bytes(), + document_type.name().as_str(), + document_id.as_slice(), + )) + .into(), + DocumentPropertyType::encode_date_timestamp(block_info.time_ms).as_slice(), + DirectQueryType::StatefulDirectQuery, + transaction, + &mut vec![], + drive_version, + )? + })) .then(|| DocumentAndContractInfo { owned_document_info: OwnedDocumentInfo { document_info: document_and_contract_info .owned_document_info .document_info - .borrowed_with_storage_flags_owner(contract.owner_id().to_buffer()), + .borrowed_with_storage_flags_owner(contract_owner_id.to_buffer()), owner_id, }, contract,