Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
56 commits
Select commit Hold shift + click to select a range
35926bc
feat(platform)!: introduce protocol version 15 with drive table v10 f…
DCG-Claude Sep 12, 2026
9ca1e39
feat(drive)!: require fee history for storage refunds and credit thei…
DCG-Claude Sep 12, 2026
8860f1b
test(drive): pin fee history handling of calculate_fee v0 and v1
DCG-Claude Sep 12, 2026
dc166c9
test(drive): cover the recorded-owner refund credit primitive
DCG-Claude Sep 12, 2026
fea0e57
test(drive): close group actions through the production funnel with f…
DCG-Claude Sep 12, 2026
5c07b34
test(drive): pin the protocol 12 schema strip as the recorded refund …
DCG-Claude Sep 12, 2026
b087724
docs(book): describe fee history and refund ownership from protocol v…
DCG-Claude Sep 12, 2026
39cbdb7
test(drive): pass the fee history where tests replace epoch-flagged d…
DCG-Claude Sep 12, 2026
2c8f0fc
test(drive): name the per-owner refund fixtures for clippy
DCG-Claude Sep 12, 2026
6b0eeb7
fix(drive): report refund credits that repay identity debt for the pr…
DCG-Claude Sep 12, 2026
f6448f2
docs(book): say lifecycle refund settlement is not yet wired at proto…
DCG-Claude Sep 12, 2026
bc113d8
docs(book): attribute storage refunds to the recorded owner in the fe…
DCG-Claude Sep 12, 2026
2fc11c1
refactor(drive): read each refund owner once when crediting its balance
DCG-Claude Sep 12, 2026
346d481
test(drive): unban, unsuspend and replace suspensions through the pro…
DCG-Claude Sep 22, 2026
58d6eef
fix(drive): price ephemeral TTL bytes in calculate_fee v1 as v0 does
DCG-Claude Sep 22, 2026
b064de5
test(drive): close the structure fixture's group action with fee hist…
DCG-Claude Sep 22, 2026
1576eb4
fix(drive)!: price a batch before committing the transaction drive owns
DCG-Claude Sep 23, 2026
5fb247a
test(drive): assert a rejected refund pricing leaves state untouched …
DCG-Claude Sep 23, 2026
2b059a3
fix(drive)!: price document and contract writes before committing the…
DCG-Claude Sep 24, 2026
11b781d
test(drive): assert rejected document and contract pricing leaves sta…
DCG-Claude Sep 24, 2026
27628d9
fix(drive)!: price add_document, index-only deletes and warning repla…
DCG-Claude Sep 27, 2026
8b4caed
test(drive): assert rejected add_document, index-only delete and warn…
DCG-Claude Sep 27, 2026
e1850c7
refactor(drive): take the repaid debt of a storage refund from the ba…
DCG-Claude Sep 27, 2026
0c25a08
fix(drive): price the contract fetch when adding a document by contra…
DCG-Claude Sep 27, 2026
f8a73fd
fix(drive)!: price contested document inserts before committing
DCG-Claude Sep 27, 2026
fe715fa
test(drive): assert a rejected second contender leaves a no-locking c…
DCG-Claude Sep 27, 2026
8e5f847
test(drive): give the refund regression fixtures fixed owner ids
DCG-Claude Sep 27, 2026
7a6ecd0
test(drive): pass the fee history in fixtures that remove flagged byt…
DCG-Claude Oct 19, 2026
5590340
fix(drive)!: price a removal of only system bytes without the fee his…
DCG-Claude Oct 19, 2026
7487910
docs(drive): say why the in-place edits to shipped generations are inert
DCG-Claude Oct 19, 2026
29b76e0
refactor(platform): write the protocol 15 drive tables as struct updates
DCG-Claude Oct 20, 2026
b561115
refactor(drive): write refund owners' negative credit through the ver…
DCG-Claude Oct 20, 2026
37b525f
test(drive): strip more than the refund dust limit in the migration f…
DCG-Claude Oct 20, 2026
8fbf2b2
refactor(drive): give price-before-commit its own apply contract gene…
DCG-Claude Oct 28, 2026
f500212
refactor(drive): reach the protocol 15 fee generation only through ca…
DCG-Claude Oct 28, 2026
a6b051d
refactor(drive): keep the protocol 15 fee and batch generations behin…
DCG-Claude Oct 28, 2026
9768b75
docs(drive): record protocol 15 refund fee history and owner credits …
DCG-Claude Oct 28, 2026
0203d33
test(drive): pin that the genesis epoch's empty fee history prices ow…
DCG-Claude Oct 28, 2026
eb6bf5c
fix(drive)!: reject an empty fee history after the genesis epoch
DCG-Claude Oct 28, 2026
b139754
docs(drive): name generation 2 as protocol 15's apply contract genera…
DCG-Claude Oct 28, 2026
826ac2d
test(drive-abci): record a changed fee version where fast-forwarding …
DCG-Claude Oct 30, 2026
b87d6a3
refactor(drive): give price-before-commit its own apply_drive_operati…
DCG-Claude Nov 1, 2026
1934b4f
docs(platform): drop a stale generation from protocol 15's drive comment
DCG-Claude Nov 2, 2026
a481ffd
test(drive): seed debt in the positive-balance refund credit test
DCG-Claude Nov 2, 2026
81731a0
docs(drive): record the apply contract wrapper's double-counted read …
DCG-Claude Nov 2, 2026
af6e224
Merge branch 'v5.1-dev' into dashvm/r12-02
QuantumExplorer Nov 3, 2026
851dffb
fix(drive): price an applied contract's lookup once in the protocol 1…
QuantumExplorer Nov 3, 2026
c2528db
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 4, 2026
84bbe73
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 4, 2026
5dd3139
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 4, 2026
3d896d9
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 4, 2026
796c051
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 5, 2026
3451a35
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 6, 2026
e58c9b1
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 6, 2026
0351b3b
chore: merge v5.1-dev into dashvm/r12-02
DCG-Claude Nov 7, 2026
6c62f8a
chore: merge v5.1-dev into dashvm/r12-02 and narrow to recorded-owner…
DCG-Claude Nov 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,15 @@
gains `DataContractCompiledMaxSizeExceededError` and `ProtocolValidationOperation`
gains `ContractCompiledSizeValidation`, so struct literals and exhaustive matches
need them. See [#5579](https://github.com/dashpay/platform/pull/5579).
- **drive (breaking):** `Drive::credit_storage_refunds_to_owners_operations` credits each
recorded owner of a storage refund without consulting keys or permissions, clearing an
owner's debt first, and returns a `StorageRefundCreditOutcome` whose
`processing_pool_share()` is the refunds without an owner balance plus the repaid debt,
for the caller's processing pool write. It is active from protocol version 15
(`DRIVE_IDENTITY_METHOD_VERSIONS_V3`); nothing calls it yet, and settling refunds on
block lifecycle paths comes in a follow-up. `DriveIdentityUpdateMethodVersions` gains
`credit_storage_refunds_to_owners`, so struct literals need it. See
[#4706](https://github.com/dashpay/platform/pull/4706).

### [5.0.3](https://github.com/dashpay/platform/compare/v5.0.2...v5.0.3) (2026-11-03)

Expand Down
25 changes: 23 additions & 2 deletions book/src/fees/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,9 @@ in `FeeStorageVersion`:
| `storage_seek_cost` | 2,000 | Cost of a single disk seek |

Storage fees are **refundable**: when data is deleted, a portion of the original
storage fee is returned to the identity that paid it (see [Refunds](#refunds)
below).
storage fee becomes a refund for the owner recorded in the stored bytes' storage
flags, which is not always the identity that paid the fee (see
[Refunds](#refunds) below).

The documents of a type that declares a `ttl` (protocol version 14) are the exception: they
carry no storage flags and refund nothing, their bytes are priced for the time they live, and
Expand Down Expand Up @@ -494,6 +495,26 @@ rate. Every schedule so far has the same storage rate, so the two agree.
There is a **dust limit**: refunds below 32 bytes worth of storage credits are
discarded to prevent micro-refund spam.

### Refund ownership (protocol version 15 onward)

Refunds follow the recorded owner in the element's storage flags.
`Drive::credit_storage_refunds_to_owners_operations` credits each owner that
has a balance element without consulting any key or permission, so a frozen
but existing owner still receives its bookkeeping refund. Two shares of a
refund never reach a balance and are reported for the caller instead: the part
that clears an owner's negative credit (identity debt, which lives outside the
credit sum trees) and the part whose owner has no balance element (the native
stand-in for a wiped owner). The caller moves both into the current epoch's
processing pool with a single pool write and records every refund against its
storage epoch in the pending epoch refunds, so the credit conservation check
stays balanced. This primitive is the settlement step block lifecycle paths
that remove owner-attributed bytes are meant to use in the block that removes
them; at protocol version 15 the vote poll end cleanup does not yet settle its
refunds, and wiring it up is a separate change. The protocol 12 schema
migration, which shrank stored contracts without refunding the stripped bytes,
ran once at that activation and is the recorded historical exception; it
replays exactly as executed.

## Epoch-Based Fee Distribution

Fees do not go directly to the block proposer. Instead, they accumulate in
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
mod v0;

use crate::drive::identity::update::storage_refund_credit_outcome::StorageRefundCreditOutcome;
use crate::drive::Drive;
use crate::error::drive::DriveError;
use crate::error::Error;
use crate::fees::op::LowLevelDriveOperation;
use dpp::fee::fee_result::refunds::FeeRefunds;
use dpp::version::PlatformVersion;
use grovedb::TransactionArg;

impl Drive {
/// Credits storage refunds to their recorded owners and reports what could
/// not be routed.
///
/// For every owner in `fee_refunds` except `skip_owner`, the owner's
/// per-epoch credits are summed with checked arithmetic. An owner with a
/// balance element is credited the way a state transition payer's own
/// refund is (one balance read feeding `add_to_previous_balance`, then the
/// balance and negative credit updates); no key, signature or permission
/// is consulted, so a frozen but existing owner receives its bookkeeping
/// refund. When that owner's balance is
/// zero the helper first clears its negative credit (identity debt), and
/// only the remainder reaches the balance; the cleared debt is reported as
/// `repaid_debt` because debt lives outside the credit sum trees and is
/// processing fee the pools were short of when it was incurred. An owner
/// without a balance element (the native proxy for a wiped owner) is not
/// credited and its amount is reported as `routed_to_processing_pool`.
/// The caller settles `processing_pool_share()` (both amounts) into the
/// current epoch's processing pool with one pool write and records the
/// pending refunds; the primitive does neither, so the block keeps a
/// single pending-refund and pool write per batch.
///
/// # Parameters
///
/// * `fee_refunds` - The refunds to settle, per owner and storage epoch.
/// * `skip_owner` - An owner whose refund the caller settles itself (a
/// state transition payer, whose refund folds into its balance change);
/// `None` on lifecycle paths.
/// * `transaction` - The current transaction.
/// * `drive_operations` - The accumulator the balance operations are
/// appended to; the caller applies them.
/// * `platform_version` - The platform version.
///
/// # Returns
///
/// * `Ok(StorageRefundCreditOutcome)` - The owners credited, the debt the
/// refunds repaid and the amount routed to the processing pool.
/// * `Err(Error)` - On overflow, a corrupted balance element, or when the
/// method is not active for the platform version.
pub fn credit_storage_refunds_to_owners_operations(
&self,
fee_refunds: &FeeRefunds,
skip_owner: Option<[u8; 32]>,
transaction: TransactionArg,
drive_operations: &mut Vec<LowLevelDriveOperation>,
platform_version: &PlatformVersion,
) -> Result<StorageRefundCreditOutcome, Error> {
Comment thread
DCG-Claude marked this conversation as resolved.
Resolved
match platform_version
.drive
.methods
.identity
.update
.credit_storage_refunds_to_owners
{
Some(0) => self.credit_storage_refunds_to_owners_operations_v0(
fee_refunds,
skip_owner,
transaction,
drive_operations,
platform_version,
),
Some(version) => Err(Error::Drive(DriveError::UnknownVersionMismatch {
method: "credit_storage_refunds_to_owners_operations".to_string(),
known_versions: vec![0],
received: version,
})),
None => Err(Error::Drive(DriveError::VersionNotActive {
method: "credit_storage_refunds_to_owners_operations".to_string(),
known_versions: vec![0],
})),
}
}
}
Loading
Loading