Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
a9ce612
feat(platform)!: delta-based data contract update transition for prot…
QuantumExplorer Sep 8, 2026
7d66ee3
fix(platform): verify a delta update against the whole contract it pr…
QuantumExplorer Sep 15, 2026
f63b3e4
Merge branch 'v4.3-dev' into feat/delta-contract-update-pv15
QuantumExplorer Sep 15, 2026
83537ad
fix(platform): gate the delta merge from protocol version 15 and fini…
QuantumExplorer Sep 15, 2026
f8698d6
fix(platform): keep the delta update out of the shipped generations
QuantumExplorer Sep 16, 2026
036f158
fix(drive-abci): reject a delta update ahead of the shipped state gen…
QuantumExplorer Sep 16, 2026
53cb036
fix(dpp): version the delta merge and keep the $defs presence out of …
QuantumExplorer Sep 18, 2026
3f7154d
feat(platform)!: rebuild delta contract updates on v5.1-dev
QuantumExplorer Nov 10, 2026
b371ebd
Merge remote-tracking branch 'origin/v5.1-dev' into fixup-4730-delta-…
QuantumExplorer Nov 10, 2026
7883f41
test(drive-abci): refuse to prove or verify a delta contract update a…
QuantumExplorer Nov 10, 2026
6af9bee
Merge remote-tracking branch 'origin/v5.1-dev' into fixup-4730-delta-…
QuantumExplorer Nov 10, 2026
f639b97
fix(sdk): verify a delta contract update against the contract it was …
QuantumExplorer Nov 10, 2026
14c7a59
fix(dpp): cap the entry name a delta contract update error carries
QuantumExplorer Nov 10, 2026
0799d76
fix(platform-wallet): send only the schemas a contract update changes
QuantumExplorer Nov 10, 2026
48991c9
fix(dpp): compare a delta's keyword lists in linear time
QuantumExplorer Nov 10, 2026
7f426ab
fix(wasm-dpp2): declare a delta's plain object as the values toObject…
QuantumExplorer Nov 10, 2026
f8ffc85
fix(wasm-dpp2): declare a delta's kept config as null in its JSON form
QuantumExplorer Nov 10, 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
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,23 @@

### Changed

- **dpp, drive (Rust API):** `DataContractUpdateTransition` gains version 1, the delta form,
which carries only what an update changes (protocol v15 note 33). An exhaustive match on
the transition or on `DataContractUpdateTransitionAction` needs a `V1` arm.
`DataContractUpdateTransitionAccessorsV0::data_contract()` returns
`Option<&DataContractInSerializationFormat>`, `None` for a delta, which embeds no contract,
and `set_data_contract` returns a `Result`; `data_contract_id()` is new and reads either
version. `new_from_data_contract`, which has only the new contract, always builds version
0; the new `new_from_contract_update(old_contract, new_contract, ...)` and
`from_contract_update` build the version the platform version defaults to, a delta from
protocol version 15. A delta's execution proof is verified against the contract as it was
before the update, and fails with `ProofError::MissingContextRequirement` without it: the
Rust SDK's new `wait_for_data_contract_update(sdk, &transition, &pre_update_contract,
settings)` takes that contract with the wait, where the context provider, which keeps
only the latest version of a contract, may no longer hold it. New consensus errors: 10283,
10284, 40010, 40011; the three that name a delta's entry (10283, 40010, 40011) carry at
most 256 bytes of its name.

- **drive, dpp (Rust API):** `Drive::calculate_fee` is now a method and no longer takes
`epochs_per_era` or `previous_fee_versions`:
`drive.calculate_fee(base_operations, drive_operations, &epoch, platform_version)`.
Expand Down
32 changes: 32 additions & 0 deletions book/src/data-model/data-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,38 @@ This intermediate format is important because serialization versions and code st

There is also `versioned_limit_deserialize`, which imposes a size limit and always performs full validation -- this is used for data coming from untrusted sources (anything not from Drive's own storage).

## Updating a Contract: the Whole Contract or a Delta

A `DataContractUpdateTransition` has two versions, and a contract owner may send either.

**Version 0 carries the whole contract.** The node compares it with the stored contract and stores it. Because a state transition is capped at `max_state_transition_size` (20,480 bytes), well below the `max_serialized_size` a contract may take (65,000 bytes), an update of this form cannot grow a contract past what one transition carries. It also pays the registration cost of the whole contract again, whatever it changes.

**Version 1 carries a delta** (`DataContractUpdateTransitionV1`, from protocol version 15, where it is the form built by default). It names the contract, its owner and the version it produces, and carries only what changes:

| Field | Meaning |
|-------|---------|
| `new_document_schemas`, `updated_document_schemas` | Document types to add, and new schemas for existing ones |
| `new_schema_defs`, `updated_schema_defs` | `$defs` definitions to add, and new schemas for existing ones |
| `new_groups`, `new_tokens` | Groups and tokens to add, at the positions after the stored ones |
| `add_keywords`, `remove_keywords` | Keywords to add after the stored ones that stay, and keywords to remove |
| `description` | `Keep`, `Clear` or `Set(text)` |
| `config` | A replacement config, or none to keep the stored one |

A delta has no way to remove a document type, a definition, a group or a token, or to change a group or a token, as no contract update may.

The node reads the stored contract, merges the delta onto it (`DataContract::apply_update`), and validates the update carrying the whole merged contract with the code that validates version 0. A delta is therefore held to every rule of a version 0 update, and the two cannot drift apart. What only a delta can get wrong is refused with its own errors: an entry named in two sections that cannot both apply (`DataContractUpdateOverlappingEntriesError`, 10283, without a fee), an entry to add that the contract already has (`DataContractUpdateEntryAlreadyExistsError`, 40010), and an entry to replace or remove that it does not have (`DataContractUpdateEntryNotFoundError`, 40011).

Two things differ from version 0:

- **Fee.** A delta pays the registration cost of what it registers alone: its new and replaced document types with their indexes, its new tokens and its added keywords. It pays the processing of validating the whole merged contract as version 0 does.
- **Size.** A delta grows a contract a transition at a time, up to `max_serialized_size`. A contract that would take more is refused with `DataContractMaxSizeExceededError` (10284).

Build either form with `DataContractUpdateTransition::new_from_contract_update(old_contract, new_contract, ...)`, which computes the delta between the stored contract and the wanted one and refuses a change a delta cannot express. `new_from_data_contract`, which has only the new contract, always builds version 0.

**Verifying a delta's execution proof needs the contract it was built on.** The proof of a contract update holds the contract as it is after the update. Version 0 is compared with it directly. A delta is first merged, by the same `apply_update`, onto the contract as it was before the update, which the verifier takes from its contract lookup; the proved contract must be the result, and a lookup that does not hold that version fails with `ProofError::MissingContextRequirement`.

In the Rust SDK, wait for a delta with `wait_for_data_contract_update(sdk, &transition, &pre_update_contract, settings)`. It makes the pre-update contract known for that one verification and leaves the SDK's context provider as it is. Registering the pre-update contract with the context provider instead is not reliable: a provider keeps the latest version of each contract, so once the update is committed, any other operation may give it the updated contract before the proof is verified, and an update that executed is then reported as failed.

## Evolving a Contract: Adding Required Fields

Contract updates are deliberately conservative: existing documents must stay valid and their stored bytes must stay readable, so most schema changes that would break either are rejected. Historically that froze the `required` set of a document type in both directions — requiredness is baked into the document wire format (required properties serialize raw, optional ones carry a presence flag), so changing it would desynchronize every stored document's bytes from the schema used to read them.
Expand Down
4 changes: 2 additions & 2 deletions book/src/error-handling/error-codes.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Error codes are organized into ranges that correspond to error categories and su
|-------|----------|----------|
| 10000-10099 | Versioning | `UnsupportedVersionError` (10000), `ProtocolVersionParsingError` (10001), `IncompatibleProtocolVersionError` (10004) |
| 10100-10199 | Structure | `JsonSchemaCompilationError` (10100), `InvalidIdentifierError` (10102), `ValueError` (10103) |
| 10200-10277 | Data Contract | `DataContractMaxDepthExceedError` (10200), `DuplicateIndexError` (10201), `InvalidDataContractIdError` (10204), `DataContractInvalidRequiredFieldsUpdateError` (10276), `PreProgrammedDistributionAmountOverLimitError` (10277) |
| 10200-10284 | Data Contract | `DataContractMaxDepthExceedError` (10200), `DuplicateIndexError` (10201), `InvalidDataContractIdError` (10204), `DataContractInvalidRequiredFieldsUpdateError` (10276), `PreProgrammedDistributionAmountOverLimitError` (10277), `DataContractCompiledMaxSizeExceededError` (10282), `DataContractUpdateOverlappingEntriesError` (10283), `DataContractMaxSizeExceededError` (10284) |
| 10350-10359 | Groups | `GroupPositionDoesNotExistError` (10350), `GroupExceedsMaxMembersError` (10354) |
| 10360-10367 | Contract Groups | `ContractGroupMembershipsOverLimitError` (10360), `InvalidContractGroupAdminsError` (10364), `InvalidContractGroupDescriptionLengthError` (10367); 10365 unassigned |
| 10400-10425 | Documents | `DataContractNotPresentError` (10400), `DuplicateDocumentTransitionsWithIdsError` (10401), `DocumentPropertyNotDistinctError` (10419), `InvalidEncryptedPropertyShapeError` (10420), `DocumentPropertyMaxBytesExceededError` (10421), `DocumentPropertyConstraintViolatedError` (10422), `DocumentReferencePreimageInvalidError` (10423), `DocumentPropertyNotGeneratedError` (10424), `DocumentTypePrivateError` (10425) |
Expand Down Expand Up @@ -107,7 +107,7 @@ The fee category currently has a single code. The 30000 range is reserved for fu

| Range | Category | Examples |
|-------|----------|----------|
| 40000-40009 | Data Contract | `DataContractAlreadyPresentError` (40000), `DataContractIsReadonlyError` (40001), `DataContractNotFoundError` (40008) |
| 40000-40011 | Data Contract | `DataContractAlreadyPresentError` (40000), `DataContractIsReadonlyError` (40001), `DataContractNotFoundError` (40008), `DataContractUpdateEntryAlreadyExistsError` (40010), `DataContractUpdateEntryNotFoundError` (40011), which carry at most 256 bytes of the entry's name, as `DataContractUpdateOverlappingEntriesError` (10283) does |
| 40100-40199 | Documents | `DocumentAlreadyPresentError` (40100), `DocumentNotFoundError` (40101), `DuplicateUniqueIndexError` (40105), `DocumentActionFeeAgreementNotSetError` (40132), `DocumentActionFeeAgreementMismatchError` (40133), `DocumentActionFeeMultiplierNotToleratedError` (40134), `DocumentActionFeeModeratorsShareMismatchError` (40139), `DocumentExpiredError` (40140), `DocumentContestMaximumContendersReachedError` (40141), `ReferencedDocumentRequirementNotMetError` (40142), `ReferencedDocumentTypeNotModeratedError` (40143), `ReferencedDocumentTypeModeratedError` (40144), `ReferencedDocumentRemovedError` (40145), `ReferencedDocumentTypeIndexOnlyError` (40146), `DocumentDeleteConstraintViolatedError` (40147), `ReferencedDocumentRuleReadInvalidError` (40148), `ReferencedDocumentPrecededError` (40149), `ReferencedDocumentTypePrivateError` (40150) |
| 40200-40217 | Identity | `IdentityAlreadyExistsError` (40200), `InvalidIdentityRevisionError` (40203), `IdentityInsufficientBalanceError` (40210) |
| 40300-40308 | Voting | `MasternodeNotFoundError` (40300), `MasternodeVoteAlreadyPresentError` (40304), `VoteChoiceNotAllowedForVotePollError` (40307), `YesNoVotePollNotAvailableForVotingError` (40308) |
Expand Down
6 changes: 5 additions & 1 deletion book/src/state-transitions/transform-into-action.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,11 @@ depends on `ValidationMode` -- `CheckTx` mode skips full schema validation for s

**DataContractUpdate:** Fetches the existing contract from Drive to compare against
the proposed update. Validates that schema changes are backward-compatible (e.g., you
can add fields but not remove required ones).
can add fields but not remove required ones). A delta update (version 1 of the
transition, from protocol version 15) carries only what changes: it is first merged onto
the existing contract, and the update carrying the whole merged contract is validated in
its place, so both forms run the same checks. See
[Updating a Contract](../data-model/data-contracts.md#updating-a-contract-the-whole-contract-or-a-delta).

**Batch (Documents):** This is the most complex transformation. For each document
sub-transition in the batch, the platform must:
Expand Down
29 changes: 15 additions & 14 deletions book/src/versioning/platform-version.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,19 +59,19 @@ function version so that execution is deterministic.
## The Version Array

Each protocol version gets its own constant, defined in a separate file. At
the time of writing, the platform has fourteen versions:
the time of writing, the platform has fifteen versions:

```rust
// packages/rs-platform-version/src/version/mod.rs

pub type ProtocolVersion = u32;

pub const LATEST_VERSION: ProtocolVersion = PROTOCOL_VERSION_14;
pub const LATEST_VERSION: ProtocolVersion = PROTOCOL_VERSION_15;
pub const INITIAL_PROTOCOL_VERSION: ProtocolVersion = 1;
pub const ALL_VERSIONS: RangeInclusive<ProtocolVersion> = 1..=LATEST_VERSION;
```

These fourteen snapshots are collected into a single static array in
These fifteen snapshots are collected into a single static array in
`protocol_version.rs`:

```rust
Expand All @@ -90,22 +90,23 @@ pub const PLATFORM_VERSIONS: &[PlatformVersion] = &[
PLATFORM_V12,
PLATFORM_V13,
PLATFORM_V14,
PLATFORM_V15,
];

pub const LATEST_PLATFORM_VERSION: &PlatformVersion = &PLATFORM_V14;
pub const LATEST_PLATFORM_VERSION: &PlatformVersion = &PLATFORM_V15;
pub const DESIRED_PLATFORM_VERSION: &PlatformVersion = LATEST_PLATFORM_VERSION;
```

The array is indexed by protocol version number minus one (since versions are
1-indexed). `PLATFORM_V1` sits at index 0, `PLATFORM_V14` at index 13. This
1-indexed). `PLATFORM_V1` sits at index 0, `PLATFORM_V15` at index 14. This
simple layout is what makes the `get` function so fast.

One file, one protocol version. `v14.rs` was created when the first consensus
change after version 13 shipped needed somewhere to live, and every later
change destined for version 14 amends that same file. The day version 14 is
One file, one protocol version. `v15.rs` was created when the first consensus
change after version 14 shipped needed somewhere to live, and every later
change destined for version 15 amends that same file. The day version 15 is
released the file freezes: from then on it is part of the chain's historical
record, and the next consensus change creates `v15.rs`. There is never a
`v14.rs` that means one thing on a node built last month and another on a node
record, and the next consensus change creates `v16.rs`. There is never a
`v15.rs` that means one thing on a node built last month and another on a node
built today.

## What a Version Snapshot Looks Like
Expand Down Expand Up @@ -153,7 +154,7 @@ pub const PLATFORM_V1: PlatformVersion = PlatformVersion {
};
```

Now compare with `PLATFORM_V14`, the latest at the time of writing. By
Now compare with `PLATFORM_V14`, a snapshot that bumped many slots at once. By
convention, each sub-constant slot that was bumped carries a trailing
`// changed:` comment saying what changed. The `protocol_version` field is the
snapshot's identity and is never annotated. One bumped slot in this snapshot,
Expand Down Expand Up @@ -278,8 +279,8 @@ impl PlatformVersion {
}
```

This is a simple array lookup. Protocol version 1 maps to index 0, version 14
to index 13. If the version number is out of range, you get a clear error. No
This is a simple array lookup. Protocol version 1 maps to index 0, version 15
to index 14. If the version number is out of range, you get a clear error. No
hash maps, no runtime registration, no dynamic dispatch -- just a static array
of compile-time constants.

Expand Down Expand Up @@ -425,7 +426,7 @@ version 14 means.
every node that was there at the time.
- Never add a new field to `PlatformVersion` without also updating every
`PLATFORM_V*` constant. The compiler will enforce this, but be aware that
the fix is updating fourteen files, not one.
the fix is updating fifteen files, not one.
- Never use `PlatformVersion::latest()` in consensus-critical code paths.
Always use the version from the current platform state, obtained via
`platform_state.current_platform_version()`. The "latest" version is what
Expand Down
2 changes: 1 addition & 1 deletion book/src/versioning/versioned-dispatch.md
Original file line number Diff line number Diff line change
Expand Up @@ -529,7 +529,7 @@ meaningfully.

This is a lot of steps, but each one is mechanical and the compiler guides you
through most of it. If you add a field to a version struct and forget to set it
in one of the fourteen platform version constants, the build fails.
in one of the fifteen platform version constants, the build fails.

## Passing Version References

Expand Down
49 changes: 49 additions & 0 deletions packages/rs-dpp/src/data_contract/methods/apply_update/mod.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
mod v0;

use crate::data_contract::serialized_version::DataContractInSerializationFormat;
use crate::data_contract::update_values::DataContractUpdateValues;
use crate::data_contract::DataContract;
use crate::validation::ConsensusValidationResult;
use crate::ProtocolError;
use platform_version::version::feature_initial_protocol_versions::DATA_CONTRACT_UPDATE_V1_INITIAL_PROTOCOL_VERSION;
use platform_version::version::PlatformVersion;

impl DataContract {
/// Merges a delta contract update onto this contract, the stored one, and returns the
/// contract the update asks for, in the format state transitions carry.
///
/// This is the one definition of what a delta means. Block execution runs it on the
/// contract it reads from state and then holds the result to every rule of an update that
/// carries the whole contract; the verification of a delta's execution proof runs it on
/// the contract the client held before the update and compares the result with the proved
/// contract. Both dispatch on `contract_versions.methods.apply_update`, so they always
/// merge alike.
///
/// Only what the shape of a delta makes checkable is checked here: the submitter owns the
/// contract, an entry to replace or remove exists, and an entry to add does not. The
/// merged contract keeps this contract's time fields; the caller stamps the update's.
///
/// # Returns
/// - The merged contract, or the consensus error that says why the delta does not fit this
/// contract.
/// - `Err(ProtocolError)` when `platform_version` predates delta contract updates (the
/// slot is `None`) or selects a generation this build does not know.
pub fn apply_update(
&self,
update_values: DataContractUpdateValues<'_>,
platform_version: &PlatformVersion,
) -> Result<ConsensusValidationResult<DataContractInSerializationFormat>, ProtocolError> {
match platform_version.dpp.contract_versions.methods.apply_update {
None => Err(ProtocolError::UnknownVersionError(format!(
"DataContract::apply_update is not active at protocol version {}, delta contract updates activate with protocol version {}",
platform_version.protocol_version, DATA_CONTRACT_UPDATE_V1_INITIAL_PROTOCOL_VERSION
))),
Some(0) => Ok(self.apply_update_v0(update_values)),
Some(version) => Err(ProtocolError::UnknownVersionMismatch {
method: "DataContract::apply_update".to_string(),
known_versions: vec![0],
received: version,
}),
}
}
}
Loading
Loading