Introduction

Welcome to The Dash Platform Book. This is a guide to the design philosophy, architectural patterns, and engineering conventions that shape the Dash Platform Rust codebase. It is not a user manual or an API reference -- it is the book you read before you open your editor, so that the thousands of files in the monorepo start to make sense.

Who This Book Is For

• Contributors who want to add a new state transition, query endpoint, or Drive operation and need to know where things go and why.
• Auditors reviewing the codebase for correctness, who need a map of the security-critical paths (validation pipelines, fee calculations, proof verification).
• Architects evaluating the system design, particularly the versioning strategy, the ABCI integration, and the GroveDB storage model.

If you have written Rust before and understand traits, enums, and feature flags, you are ready.

The Design Philosophy

Four principles recur throughout the codebase. Understanding them up front will save you hours of "why is it done this way?" confusion.

1. Version Everything

Every method that touches consensus has a version number. The version is not embedded in the code path -- it lives in a central PlatformVersion struct that is threaded through the entire call stack:

#![allow(unused)]
fn main() {
// From packages/rs-platform-version/src/version/protocol_version.rs
#[derive(Clone, Debug)]
pub struct PlatformVersion {
    pub protocol_version: ProtocolVersion,
    pub dpp: DPPVersion,
    pub drive: DriveVersion,
    pub drive_abci: DriveAbciVersion,
    pub consensus: ConsensusVersions,
    pub fee_version: FeeVersion,
    pub system_data_contracts: SystemDataContractVersions,
    pub system_limits: SystemLimits,
}
}

When you see a method that dispatches on a version number, this is the canonical pattern:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/execution/engine/finalize_block_proposal/mod.rs
pub(crate) fn finalize_block_proposal(
    &self,
    request_finalize_block: FinalizeBlockCleanedRequest,
    block_execution_context: BlockExecutionContext,
    transaction: &Transaction,
    platform_version: &PlatformVersion,
) -> Result<block_execution_outcome::v0::BlockFinalizationOutcome, Error> {
    match platform_version
        .drive_abci
        .methods
        .engine
        .finalize_block_proposal
    {
        0 => self.finalize_block_proposal_v0(
            request_finalize_block,
            block_execution_context,
            transaction,
            platform_version,
        ),
        version => Err(Error::Execution(ExecutionError::UnknownVersionMismatch {
            method: "finalize_block_proposal".to_string(),
            known_versions: vec![0],
            received: version,
        })),
    }
}
}

This pattern allows the network to upgrade without hard forks. Every node on the network agrees on which version to run for each method at each block height, and the version table is the single source of truth. The Versioning section covers this in depth.

2. Explicit Costs

Platform is a metered system. Every operation -- inserting a document, updating a contract, creating an identity -- has a fee expressed in credits. Costs are not estimated after the fact; they are tracked as operations execute, through GroveDB's cost accounting layer. The FeeResult type flows alongside the data, and sum trees in GroveDB let the platform verify fee totals against the Merkle-proven state.

The fee version itself is part of PlatformVersion, which means the network can adjust fee schedules across protocol upgrades without any node disagreeing on how much an operation costs at a given block height.

3. Clear Transformation Stages

A state transition does not go from "bytes on the wire" to "committed to disk" in one step. It passes through well-defined stages:

1. Decode -- raw bytes become a StateTransition enum.
2. Structure validation -- syntactic checks (field lengths, required fields).
3. State validation -- checks against current platform state (does this identity exist? does the nonce match?).
4. Transform into action -- the validated transition becomes a StateTransitionAction, a representation of what to do rather than what was requested.
5. Convert to operations -- the action becomes a list of DriveOperation values (GroveDB inserts, deletes, replacements).
6. Apply -- the operations execute inside a GroveDB transaction.

Each stage is a separate module with its own versioned dispatch. This separation means you can audit validation independently from execution, and you can test each stage in isolation.

4. Trait-Based Polymorphism

The codebase avoids dynamic dispatch where performance matters and embraces it where extensibility matters. ABCI handlers are defined against traits like PlatformApplication, TransactionalApplication, and BlockExecutionApplication:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/app/mod.rs
pub trait PlatformApplication<C = DefaultCoreRPC> {
    fn platform(&self) -> &Platform<C>;
}

pub trait TransactionalApplication<'a> {
    fn start_transaction(&self);
    fn transaction(&self) -> &RwLock<Option<Transaction<'a>>>;
    fn commit_transaction(&self, platform_version: &PlatformVersion)
        -> Result<(), Error>;
}

pub trait BlockExecutionApplication {
    fn block_execution_context(&self) -> &RwLock<Option<BlockExecutionContext>>;
    fn unsigned_withdrawal_txs_by_round(&self) -> &RwLock<UnsignedWithdrawalTxsByRound>;
}
}

This makes it possible to swap in mock implementations for testing while keeping the production path zero-cost.

How This Book Is Organized

The book follows the data as it flows through the system, from the outside in:

Each chapter follows the same arc: why the pattern exists (the problem it solves), what the pattern is (the types and modules involved), how it works (real code from the repository), and rules (the do's and don'ts that keep the codebase consistent).

Coding Conventions

A few conventions appear consistently across the codebase and are worth calling out early:

• #![forbid(unsafe_code)] is set in both dpp and drive. The platform avoids unsafe Rust entirely in its core logic. Unsafe operations are confined to external dependencies (RocksDB, cryptographic libraries).
• #![deny(missing_docs)] is enabled in drive, enforcing doc comments on every public item. DPP has this commented out but is moving toward it.
• Feature-gated compilation is pervasive. A typical crate has 20-80 Cargo features controlling which modules, serialization formats, and integrations are compiled. This keeps binary sizes small and compile times manageable for downstream consumers that only need a subset of functionality.
• Versioned module layout: When a function has multiple versions, they live in sibling directories named v0/, v1/, etc., with a parent mod.rs that dispatches based on PlatformVersion. This is the dominant structural pattern in Drive-ABCI.

A Note on Reading the Source

The codebase lives in a monorepo at packages/. The Rust crates are prefixed with rs- on disk but have shorter names in Cargo.toml:

The workspace currently targets Rust 1.98 and protocol version 14 (as of 4.2.0-dev). The workspace Cargo.toml lists 47 member crates, but the core platform logic lives in the first eight listed above.

Let's begin with the architecture.

Platform Comparison

How Dash Platform compares to other blockchain networks across architecture, features, and developer experience. Ratings from - (not supported) through + (basic), ++ (good), to +++ (best in class) reflect relative strength in each dimension.

Overview

Data and Querying

The standout difference is light client verification. Most chains either offer no state proofs (Solana, Avalanche), require trusting intermediaries (Polkadot's relay chain, Cosmos IBC relayers, NEAR's RPC providers), or give proofs that are expensive to verify (Ethereum's sync committee). Dash Platform serves a cryptographic proof with every query response, and a single BLS threshold signature is all a client needs to verify it. A mobile wallet gets the same security guarantees as a full node.

Smart Contracts and Programmability

Dash Platform takes a fundamentally different approach: instead of a VM that executes arbitrary code, developers define data contracts -- JSON Schema-based specifications that describe the structure and validation rules for their application data. The network stores, indexes, and enforces these schemas directly. This eliminates entire classes of smart contract vulnerabilities (reentrancy, unchecked external calls, gas manipulation). Smart contract support is planned for Platform v4.0 (targeted for mainnet in 2027).

Token Support

Dash Platform tokens are first-class protocol objects rather than smart contract deployments. Token behavior (minting rules, supply caps, freeze authority, distribution schedules) is configured declaratively in data contracts and enforced by the protocol itself.

Project and Ecosystem

SDK Support

Dash Platform provides SDKs for multiple languages and environments so developers can build applications on whatever stack they prefer.

Available SDKs

Supporting packages

Choosing an SDK

Building a server or CLI tool? Use the Rust SDK for maximum performance and direct access to all protocol features, or the JavaScript SDK if your stack is Node.js.

Building an iOS or macOS app? Use the Swift SDK (v3.1+), which wraps the Rust SDK through an FFI layer and provides native Swift types.

Building an Android app? The Android SDK (v3.2+) will wrap the same FFI layer with native Kotlin types.

Building for another language? The FFI layer (rs-sdk-ffi) exposes a C-compatible interface that can be called from Python, C#, or any language with C interop support.

What every SDK provides

All SDKs share the same underlying Rust implementation, so behavior is consistent across platforms:

• Identity management -- create, top up, and manage identities with hierarchical key support
• Data contract deployment -- define and publish JSON Schema-based data contracts
• Document operations -- create, update, delete, and query documents with proof verification
• Token operations -- query balances, supply, statuses, and pre-programmed distributions
• Name registration -- register and resolve DPNS usernames
• Proof verification -- every query response can be cryptographically verified against the platform state root

Getting Started

This guide covers prerequisites and local development setup for the Dash Platform monorepo.

Prerequisites

• Node.js v20+

• Docker v20.10+

• Rust v1.92+, with the wasm32 target:

  rustup target add wasm32-unknown-unknown
  

• protoc (Protocol Buffers compiler) v32.0+. If protoc is not on your PATH, set the PROTOC environment variable to the binary location.

• wasm-bindgen-cli:

  cargo install wasm-bindgen-cli@0.2.103
  

  Important: the wasm-bindgen-cli version must match the wasm-bindgen version in Cargo.lock. Check with grep 'name = "wasm-bindgen"' Cargo.lock.

  Depending on your system, you may need additional packages before wasm-bindgen-cli will compile (e.g. clang, llvm, libssl-dev).

• wasm-pack:

  curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
  

• Build essentials (Debian / Ubuntu):

  apt install -y build-essential libssl-dev pkg-config clang cmake llvm
  

macOS-specific notes

The built-in Apple llvm toolchain does not work for WASM compilation. Install LLVM from Homebrew and put it on your PATH:

brew install llvm
echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you use Bash, replace ~/.zshrc with ~/.bash_profile. You can check your default shell with echo $SHELL.

Setup

# Enable corepack (ships with Node.js) to get the correct yarn version
corepack enable

# Install dependencies, configure, and build all packages
yarn setup

# Start the local development environment (runs a local Dash network in Docker)
yarn start

# Run the full test suite (requires a running local node)
yarn test

# Stop the local environment (frees system resources)
yarn stop

# Rebuild after making changes
yarn build

# If you need to restart services after a rebuild
yarn restart

# Complete reset of all local data and builds
yarn reset

Running package-level tests

You can run tests for a single package instead of the entire suite:

yarn workspace <package_name> test

For example:

yarn workspace @dashevo/dapi-client test

See the packages directory for the full list of available packages.

Rust development

# Run tests for a specific Rust crate
cargo test -p <crate_name>

# Run all Rust workspace tests
cargo test --workspace

# Check compilation without building
cargo check --workspace

# Run the clippy linter
cargo clippy --workspace

# Format all Rust code
cargo fmt --all

Monorepo Overview

Dash Platform ships as a single Git repository containing 47 Rust crates, a handful of JavaScript/TypeScript packages, and supporting tooling. This chapter maps the territory: what each crate owns, how they depend on one another, and where the boundaries are drawn.

The Workspace

The top-level Cargo.toml declares a workspace with resolver = "2". It pins a few critical external dependencies at the workspace level -- most notably dashcore (the Rust Dash Core library) and the GroveDB family of crates:

# From Cargo.toml (workspace root)
[workspace.dependencies]
dashcore = { git = "https://github.com/dashpay/rust-dashcore", rev = "53d699c..." }

The workspace version (4.2.0-dev at time of writing, Rust edition 2021, MSRV 1.98) is shared by all member crates through version.workspace = true.

The Core Dependency Chain

Four crates form the spine of the platform. Understanding their dependency order is the single most important thing for navigating the codebase:

    dpp (rs-dpp)
      |
      v
    drive (rs-drive)
      |
      v
    drive-abci (rs-drive-abci)
      |
      v
    dash-sdk (rs-sdk)

Each layer adds a concern:

dpp -- Dash Platform Protocol

Crate name: dpp Path: packages/rs-dpp

DPP defines the data model of the platform. This is where you will find:

• Identity, IdentityPublicKey, and identity state transitions
• DataContract and the JSON Schema validation logic
• Document and document state transitions
• StateTransition -- the enum that unifies all transition types
• Prelude types used everywhere: Identifier, BlockHeight, IdentityNonce
• Token, voting, and withdrawal types

#![allow(unused)]
fn main() {
// From packages/rs-dpp/src/lib.rs
pub mod data_contract;
pub mod document;
pub mod identifier;
pub mod identity;
pub mod state_transition;
pub mod tokens;
pub mod voting;
pub mod fee;
pub mod validation;
}

DPP is deliberately storage-agnostic. It knows nothing about GroveDB, ABCI, or gRPC. It depends on platform-version, platform-value, and platform-serialization for versioned encoding, but it never opens a database.

A key design choice: DPP uses feature flags extensively. The Cargo.toml lists over 80 features that control which serialization formats, validation paths, and system contracts are compiled in. The abci feature, for instance, pulls in the subset needed by Drive-ABCI without dragging in client-side concerns:

# From packages/rs-dpp/Cargo.toml
[features]
abci = [
  "state-transitions",
  "state-transition-validation",
  "validation",
  "random-public-keys",
  "identity-serialization",
  "vote-serialization",
  "platform-value-cbor",
  "core-types",
  "core-types-serialization",
  "core-types-serde-conversion",
  "core_rpc_client",
]

Rule: If you are adding a new type that both the server and the SDK need, put it in DPP. If it needs GroveDB, it belongs in Drive.

drive -- Dash Drive

Crate name: drive Path: packages/rs-drive

Drive is the storage engine. It wraps GroveDB (a Merkle-tree-based key-value store) and provides domain-specific operations: inserting documents, managing identity balances, tracking fee pools, building cryptographic proofs.

#![allow(unused)]
fn main() {
// From packages/rs-drive/src/lib.rs
#[cfg(any(feature = "server", feature = "verify"))]
pub mod drive;
#[cfg(any(feature = "server", feature = "verify"))]
pub mod query;
#[cfg(feature = "server")]
pub mod state_transition_action;
#[cfg(any(feature = "server", feature = "verify"))]
pub mod verify;
#[cfg(feature = "server")]
pub mod fees;
}

Notice the feature split: server includes everything needed to write to the database, while verify includes only what is needed to prove and verify queries. The SDK only enables verify, which means it can check GroveDB proofs without linking in the full storage engine.

Drive depends on DPP for type definitions and on the GroveDB family of crates for storage:

# From packages/rs-drive/Cargo.toml
dpp = { path = "../rs-dpp", features = ["state-transitions"], default-features = false }
grovedb = { git = "https://github.com/dashpay/grovedb", rev = "33dfd48...", optional = true }
grovedb-path = { git = "https://github.com/dashpay/grovedb", rev = "33dfd48..." }
grovedb-costs = { git = "https://github.com/dashpay/grovedb", rev = "33dfd48...", optional = true }

Rule: Never import drive with the server feature from a client-side crate. Use verify only.

drive-abci -- The ABCI Application

Crate name: drive-abci Path: packages/rs-drive-abci

This is the application server. It implements the Tenderdash ABCI interface, orchestrates block processing, validates state transitions, manages platform state, and serves gRPC queries. It is the binary that masternodes run.

Drive-ABCI depends on both DPP and Drive, plus the Tenderdash ABCI library and the dapi-grpc protobuf definitions:

# From packages/rs-drive-abci/Cargo.toml
drive = { path = "../rs-drive", default-features = false, features = ["server"] }
dpp = { path = "../rs-dpp", default-features = false, features = ["abci"] }
tenderdash-abci = { git = "https://github.com/dashpay/rs-tenderdash-abci", tag = "v1.5.0" }
dapi-grpc = { path = "../dapi-grpc", default-features = false, features = ["server", "platform"] }

The crate is organized into three major subsystems:

1. abci/ -- Tenderdash handler functions (prepare_proposal, process_proposal, finalize_block, check_tx, etc.)
2. execution/ -- Block processing engine, state transition validation, platform events (epoch changes, withdrawals, voting)
3. query/ -- gRPC query service implementing the Platform API

Rule: Business logic goes in execution/. The abci/ handlers should be thin wrappers that delegate to the execution engine.

dash-sdk -- The Client SDK

Crate name: dash-sdk Path: packages/rs-sdk

The SDK is what application developers use. It provides high-level methods for fetching documents, creating identities, broadcasting state transitions, and verifying proofs. It depends on DPP for types, Drive (with verify only) for proof verification, and rs-dapi-client for network communication:

# From packages/rs-sdk/Cargo.toml
dpp = { path = "../rs-dpp", default-features = false, features = ["dash-sdk-features"] }
drive = { path = "../rs-drive", default-features = false, features = ["verify"] }
drive-proof-verifier = { path = "../rs-drive-proof-verifier", default-features = false }
rs-dapi-client = { path = "../rs-dapi-client", default-features = false }

Supporting Crates

Several smaller crates provide cross-cutting infrastructure:

platform-version

Path: packages/rs-platform-version

The versioning backbone. Defines PlatformVersion, ProtocolVersion, and the version tables for every consensus-critical method across DPP, Drive, and Drive-ABCI. Currently tracks 14 protocol versions (v1 through v14).

#![allow(unused)]
fn main() {
// From packages/rs-platform-version/src/version/mod.rs
pub type ProtocolVersion = u32;
pub const LATEST_VERSION: ProtocolVersion = PROTOCOL_VERSION_14;
pub const INITIAL_PROTOCOL_VERSION: ProtocolVersion = 1;
}

Every crate in the dependency chain depends on platform-version. It is the root of the version tree.

platform-serialization

Path: packages/rs-platform-serialization

A thin wrapper around bincode that adds platform-version-aware serialization. Paired with platform-serialization-derive for derive macros that generate versioned Encode/Decode implementations.

platform-value

Path: packages/rs-platform-value

A dynamically-typed value type (think serde_json::Value but with binary support). Used as the interchange format when converting between JSON, CBOR, and Rust types, especially in data contract and document processing.

drive-proof-verifier

Path: packages/rs-drive-proof-verifier

Client-side proof verification. Takes a GroveDB proof returned by a platform query and verifies it against a known root hash. Used by the SDK and the WASM bindings.

dapi-grpc

Path: packages/dapi-grpc

Protobuf definitions and generated Rust code for the Platform gRPC API. Both server-side (Drive-ABCI) and client-side (SDK, DAPI client) depend on this crate, using the server and client features respectively.

What Is GroveDB?

GroveDB is an external dependency -- a Merkle-tree-based authenticated data structure built on RocksDB. It is not part of this repository but is central to understanding Drive.

Key properties:

• Authenticated: Every read can produce a cryptographic proof that the data (or its absence) is consistent with the root hash stored in the block header.
• Hierarchical: Data is organized into nested trees (subtrees), addressed by paths. A document lives at a path like [contract_id, document_type, document_id].
• Sum trees: Some subtrees track the sum of their leaf values, used for balance accounting and fee verification.
• Transactional: All writes happen inside a transaction that can be committed or rolled back atomically.
• Cost-tracking: Every operation returns a CostResult that records storage and processing costs.

GroveDB is pinned to a specific Git revision in the workspace Cargo.toml and referenced by five sub-crates: grovedb, grovedb-path, grovedb-costs, grovedb-storage, and grovedb-version.

The Full Crate Map

Here is a simplified view of every Rust workspace member, grouped by role:

Rules

Do:

• Follow the dependency direction. DPP never imports Drive. Drive never imports Drive-ABCI.
• Use feature flags to keep compilation lean. The SDK should never compile server-side code.
• Put new domain types in DPP. Put new storage operations in Drive. Put new validation logic in Drive-ABCI.

Don't:

• Add GroveDB as a dependency to DPP. If you need tree structure knowledge in a type definition, use a path abstraction.
• Enable the server feature of Drive in client-facing crates. This pulls in RocksDB and doubles compile times.
• Create new top-level crates without updating the workspace Cargo.toml and ensuring the dependency direction is maintained.

Component Pipeline

This chapter traces a request from the moment it leaves a client application to the moment its effects are committed to GroveDB. Understanding this pipeline is essential because every bug, every audit finding, and every performance issue lives somewhere along this path.

The Big Picture

Client App
  |
  | gRPC (protobuf)
  v
DAPI (rs-dapi) -----------> Drive-ABCI query service (reads)
  |
  | BroadcastStateTransition
  v
Tenderdash mempool
  |
  | ABCI (check_tx, prepare_proposal, process_proposal, finalize_block)
  v
Drive-ABCI (rs-drive-abci)
  |
  | DriveOperations
  v
Drive (rs-drive)
  |
  | GroveDB transaction
  v
GroveDB -> RocksDB

There are two fundamentally different paths through this pipeline:

1. Reads (queries): Client sends a gRPC query, DAPI forwards it to Drive-ABCI's query service, which reads from GroveDB and returns data with a Merkle proof. No consensus involved.

2. Writes (state transitions): Client broadcasts a state transition, it enters the Tenderdash mempool, goes through consensus, and is applied to GroveDB during block processing.

Let's trace the write path in detail -- it is where all the complexity lives.

DAPI: The Entry Point

DAPI (packages/rs-dapi) is the internet-facing gRPC server. It implements two roles:

• Platform queries: Forwarded directly to Drive-ABCI's gRPC service (which runs as a separate listener within the same process).
• State transition broadcast: Submitted to Tenderdash via its RPC interface.

// Simplified from packages/rs-dapi/src/services/platform_service/broadcast_state_transition.rs
Client --gRPC--> DAPI --Tenderdash RPC--> Tenderdash mempool

DAPI itself does minimal validation. It is a routing layer. The heavy lifting happens in Drive-ABCI.

The ABCI Handler Layer

When Tenderdash needs the application to do something -- check a transaction, build a block, validate a proposal, or finalize a block -- it calls an ABCI method. Drive-ABCI implements these in packages/rs-drive-abci/src/abci/handler/:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/handler/mod.rs
mod check_tx;
mod echo;
mod extend_vote;
mod finalize_block;
mod info;
mod init_chain;
mod prepare_proposal;
mod process_proposal;
mod verify_vote_extension;
}

These handlers are implemented against trait bounds, not concrete types:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/handler/finalize_block.rs
pub fn finalize_block<'a, A, C>(
    app: &A,
    request: proto::RequestFinalizeBlock,
) -> Result<proto::ResponseFinalizeBlock, Error>
where
    A: PlatformApplication<C> + TransactionalApplication<'a> + BlockExecutionApplication,
    C: CoreRPCLike,
{ ... }
}

The FullAbciApplication struct wires everything together. It holds a reference to Platform, a GroveDB transaction, the current block execution context, and the withdrawal transactions of every proposal accepted at the current height, which vote extensions are verified against:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/app/full.rs
pub struct FullAbciApplication<'a, C> {
    pub platform: &'a Platform<C>,
    pub transaction: RwLock<Option<Transaction<'a>>>,
    pub block_execution_context: RwLock<Option<BlockExecutionContext>>,
    pub unsigned_withdrawal_txs_by_round: RwLock<UnsignedWithdrawalTxsByRound>,
}
}

It implements the tenderdash_abci::Application trait, delegating each method to the corresponding handler function.

Block Processing Lifecycle

Tenderdash uses a proposal-based consensus model. Here is the sequence of ABCI calls for a single block:

1. check_tx -- Mempool Gatekeeper

Before a state transition enters the mempool, Tenderdash calls check_tx. This is a lightweight validation that runs outside of consensus:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/handler/check_tx.rs
pub fn check_tx<C>(
    platform: &Platform<C>,
    core_rpc: &C,
    request: proto::RequestCheckTx,
) -> Result<proto::ResponseCheckTx, Error>
where
    C: CoreRPCLike,
{
    let platform_state = platform.state.load();
    let platform_version = platform_state.current_platform_version()?;

    let validation_result = platform.check_tx(
        tx.as_slice(),
        r#type.try_into()?,
        &platform_ref,
        platform_version,
    );
    // ...
}
}

check_tx operates in two modes: mode 0 (new transaction) and mode 1 (re-check existing mempool transactions after a new block). It returns a fee estimate (gas_wanted), a priority for ordering, and a sender identifier for deduplication. Importantly, check_tx does not run inside a GroveDB transaction -- it reads committed state only.

2. prepare_proposal -- The Proposer Builds a Block

The block proposer calls prepare_proposal with a list of candidate transactions. The handler starts a GroveDB transaction and runs the full block proposal:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/handler/prepare_proposal.rs
// Start a GroveDB transaction
app.start_transaction();

// Run the full proposal (validates + executes all state transitions)
let mut run_result = app.platform().run_block_proposal(
    block_proposal,
    true,         // known_from_us = true (we are the proposer)
    &platform_state,
    transaction,
    Some(&timer),
)?;
}

The response tells Tenderdash which transactions to keep, remove, or delay:

• TxAction::Unmodified -- valid transition, include in block
• TxAction::Removed -- unpaid error or internal error, strip from block
• TxAction::Delayed -- exceeded max block size, try next block

3. process_proposal -- Validators Verify the Block

Non-proposing validators receive the block and call process_proposal. This runs the same run_block_proposal logic but with known_from_us = false:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/handler/process_proposal.rs
let run_result = app.platform().run_block_proposal(
    (&request).try_into()?,
    false,        // known_from_us = false (we are validating someone else's proposal)
    &platform_state,
    transaction,
    None,
)?;
}

A key optimization: if the validator was also the proposer for this round (same height and round), the cached result from prepare_proposal is reused:

#![allow(unused)]
fn main() {
// From process_proposal.rs -- cache hit path
if let Some(proposal_info) = block_execution_context.proposer_results() {
    return Ok(proto::ResponseProcessProposal {
        status: proto::response_process_proposal::ProposalStatus::Accept.into(),
        app_hash: proposal_info.app_hash.clone(),
        tx_results: proposal_info.tx_results.clone(),
        // ...
    });
}
}

If the proposal contains failed or unpaid transitions, the validator rejects it.

4. finalize_block -- Commit

After consensus is reached, Tenderdash calls finalize_block. This is where the GroveDB transaction is committed to disk:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/abci/handler/finalize_block.rs
let block_finalization_outcome = app.platform().finalize_block_proposal(
    request_finalize_block,
    block_execution_context,
    transaction,
    platform_version,
)?;

// Commit the GroveDB transaction
let result = app.commit_transaction(platform_version);
}

After commit, the block height counter is updated and, if needed, a GroveDB checkpoint is created for crash recovery.

The finalize response also carries a proposer hint, propose_next_block_immediately (Tenderdash 1.8.0, ABCI 1.4.0). Drive sets it when the block leaves withdrawal work for the next block: untied withdrawal transactions waiting in the queue to be signed. Tenderdash then proposes round 0 of the next height without waiting for transactions or the empty-block interval, so a withdrawal is signed one block after it was pooled instead of one interval later. The hint is local to the node and never part of consensus: it is read from the same GroveDB transaction the block committed, but it does not change the state or the app hash. See has_pending_withdrawal_work under packages/rs-drive-abci/src/execution/platform_events/withdrawals/.

Inside run_block_proposal

The run_block_proposal method in packages/rs-drive-abci/src/execution/engine/run_block_proposal/v0/mod.rs is the heart of the block processing engine. It orchestrates everything that happens within a single block. Here is the sequence, in order:

1.  Verify protocol version matches expected version
2.  Validate block follows previous block (height, core height)
3.  Clear drive block cache
4.  Verify chain lock (if core chain lock update present)
5.  Update core info (masternode list, quorums)
6.  Update validator proposed app version
7.  Rebroadcast expired withdrawals
8.  Update broadcasted withdrawal statuses
9.  Dequeue and build unsigned withdrawal transactions
10. Run DAO platform events (vote tallying, contested documents)
11. Process raw state transitions  <-- the main work
12. Store address balance changes
13. Clean up expired address balance entries
14. Pool withdrawals into transaction queue
15. Clean up expired withdrawal amount locks
16. Process block fees and validate sum trees
17. Compute root hash (app_hash)
18. Determine validator set update

Steps 1-10 are "block-level housekeeping." Step 11 is where individual state transitions are decoded, validated, transformed into actions, and applied to GroveDB. Steps 12-18 finalize the block's effects.

State Transition Processing

State transition processing (step 11 above) follows its own pipeline within packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/:

decode_raw_state_transitions
       |
       v
process_raw_state_transitions
       |
       v
   For each transition:
       |
       +-> validate (structure, state, signatures)
       +-> transform_into_action
       +-> validate_fees_of_event
       +-> execute_event (apply DriveOperations to GroveDB)

The validation itself is split into modules per transition type:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/mod.rs
pub mod batch;
pub mod identity_create;
pub mod identity_credit_transfer;
pub mod identity_credit_withdrawal;
pub mod identity_top_up;
pub mod identity_update;
pub mod data_contract_create;
pub mod data_contract_update;
pub mod masternode_vote;
// ... and more
}

Each module provides versioned validation methods dispatched through PlatformVersion, following the same pattern shown in the Introduction.

The Query Path

Queries bypass consensus entirely. Drive-ABCI implements the Platform gRPC service directly:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/query/service.rs
// Implements dapi_grpc::platform::v0::platform_server::Platform
// with methods like:
//   get_identity()
//   get_documents()
//   get_data_contract()
//   get_identity_balance()
//   ... (50+ query endpoints)
}

Each query reads from the committed GroveDB state (no transaction), generates a Merkle proof, and returns both the data and the proof. The client SDK uses drive-proof-verifier to independently verify that the returned data matches the proof against a known root hash.

Protocol Version Upgrades During Block Processing

One subtlety worth highlighting: protocol version changes happen at epoch boundaries. The run_block_proposal method checks whether the current block is the first block of a new epoch and whether the locked-in next protocol version differs from the current one:

#![allow(unused)]
fn main() {
// From packages/rs-drive-abci/src/execution/engine/run_block_proposal/mod.rs
let block_platform_version = if epoch_info.is_epoch_change_but_not_genesis()
    && platform_state.next_epoch_protocol_version()
        != platform_state.current_protocol_version_in_consensus()
{
    let next_protocol_version = platform_state.next_epoch_protocol_version();
    let next_platform_version = PlatformVersion::get(next_protocol_version)?;

    // Perform structural changes for the new protocol version
    self.perform_events_on_first_block_of_protocol_change(
        platform_state,
        &block_info,
        transaction,
        old_protocol_version,
        next_platform_version,
    )?;

    next_platform_version
} else {
    last_committed_platform_version
};
}

This ensures that all nodes switch protocol versions at exactly the same block, and that any structural migrations (new GroveDB trees, schema changes) are applied atomically as part of that block's transaction.

Rules

Do:

• Keep ABCI handlers thin. They should parse the request, delegate to the execution engine, and format the response. No business logic.
• Always pass platform_version through the call stack. Never hard-code a version number in execution logic.
• Run check_tx validation as a strict subset of proposal validation. If check_tx accepts a transition, process_proposal should not reject it (modulo state changes between the two calls).

Don't:

• Read uncommitted state in check_tx. It reads committed state only because it runs outside the block transaction.
• Assume prepare_proposal and process_proposal see the same state. Another block may have been committed between the two calls if a round change occurs.
• Add new block-level events without inserting them in the correct position in the run_block_proposal sequence. Order matters -- withdrawals must be processed before state transitions, fee accounting must happen after.
• Panic in ABCI handlers except for truly unrecoverable situations (like app hash mismatches, which indicate data corruption).

Coding Conventions

The other chapters of this book explain how each subsystem works. This chapter is the prescriptive companion: the rules a change has to follow to keep the codebase maintainable, and the reason behind each one. Most of these rules were learned in code review rather than designed up front, so each entry says what goes wrong when the rule is skipped. Where a rule has mechanics, it links to the chapter that shows them.

Read this before your first non-trivial PR. Skim the checklists at the end before every PR.

The one constraint behind every rule

Dash Platform is a replicated state machine. Every masternode must produce a byte-identical state root for every block, including blocks from years ago that a fresh node replays from genesis. That means code that shipped inside a released protocol version must keep behaving exactly as it did on the day it shipped, forever, while the same binary also runs the newest behaviour for current blocks.

Almost everything below follows from that constraint: why behaviour is split into frozen generations, why numbers live in version tables, why a stray unwrap is a network outage and not a bug report, and why a check has to sit in the right validation tier. When a rule here seems pedantic, the question to ask is "could two nodes disagree because of this?"

Where code goes

The crates are layered, and dependencies only point downward: platform-version at the bottom, then dpp, then drive. Above drive the graph forks: drive-abci (the node) and dash-sdk (the client) both depend on drive, the SDK with the verify feature only, and dash-sdk does not depend on drive-abci at all (see the Monorepo Overview). Put a change in the lowest crate that has what the change needs, and no lower.

Three boundaries are enforced by CI and worth knowing by name:

• The verify-only cut. packages/wasm-drive-verify builds drive with default-features = false, features = ["verify"]. Anything under src/verify/** that reaches a server-gated helper breaks the JavaScript build on a Rust-only PR. A helper both the prover and the verifier need goes in drive::util::common, and the server-side code delegates to it.
• The transport-free cut. drive-proof-verifier, dash-platform-queries, and the wasm32 dependency trees of dash-sdk and wasm-sdk must not pull in hyper, rustls, tower, or mio. Embedders with their own networking consume verification through these crates, so a dependency added for convenience in a shared crate can fail a job that has nothing to do with the change.
• The wallet closure. The wallet CI fast path compiles only the wallet crates and their known dependents. Adding a dependency on a wallet crate from a new place fails the build until the closure list in .github/scripts/check-wallet-closure.py is updated deliberately.

Versioned behaviour

The mechanics of PlatformVersion, feature version tables, and the dispatcher shape are covered in the Versioning chapters. The rules here are about what to do with those mechanics.

Shipped generations are frozen unless the change cannot modify consensus

A behaviour change to a versioned method means a new vN module selected only by the tables of the unreleased protocol version. A shipped vN may be edited in place only when we are sure the edit cannot modify consensus at any protocol version that selects it: the new code is unreachable there by construction (the data it acts on cannot exist under those versions, such as a keyword every one of their meta-schemas refuses and their parser ignores, judged through a dpp method whose own gate is None there), or the edit is a pure refactor with identical output. "Probably inert" is not enough. If the argument takes more than a sentence, or rests on a runtime check inside the shipped module, add a generation instead. Inside a new generation the capability is a constant fact (Index::try_from_value_map(map, true)), not a runtime check. For new changes, the patterns that compare protocol_version on purpose are the protocol upgrade ladder, the is_allowed gate for new transition kinds, and chain-creation content (create_genesis_state v1 and the Drive helpers that build the initial state structure); the Versioned Dispatch chapter describes them. Older comparisons elsewhere (for example the pre-version-9 arithmetic in DocumentPropertyType) stay because history replays through them; they are not a pattern to copy.

Why: replay safety is structural when a shipped file stays byte-identical, and becomes a proof the reviewer has to check the moment it does not. An in-place edit is acceptable when that proof is short and written down; a dead version check inside v1 that misleads the next reader into thinking v1 can take that path is not.

How, new generation: copy the previous generation into the new module, make the change there, move the tests that exercise the new behaviour into the new module, and bump the method's number in the new protocol version's tables only. Duplication between generations is the accepted cost; it is cheaper than a drift-prone flag.

How, in place: make the edit, leave a comment at the edited lines naming why they are inert for every protocol version that selects the module, and give the pull request description an "In-place changes to shipped generations" section that lists each edited generation, the protocol versions that select it, and the reason consensus cannot change there. Reviewers read that section first.

Table versions follow protocol-version boundaries, not PRs

Version-table constants (DRIVE_ABCI_VALIDATION_VERSIONS_V10, CONTRACT_VERSIONS_V6, SYSTEM_LIMITS_V4, and so on) exist to mark the point where a released protocol version froze them. If the unreleased protocol version already introduced a new table version, a second feature landing in the same protocol version amends that table in place. Adding another table version would leave one referenced by no PLATFORM_V* at all.

Leaf implementation modules are different: each feature still gets its own new vN implementation module under the method directory. The rule is about the tables.

Shared helpers get a versioned method, not a capability flag

When new behaviour lives in a helper reached from several generations (a value walker, a property-reference resolver, a shared insert path), the fix is the standard versioned-method pattern: an OptionalFeatureVersion field in the tables (None for versions that predate the feature, Some(0) to dispatch to a _v0 implementation), and the helper takes &PlatformVersion. A admit_property_references: bool on a shared context struct is the wrong shape, because it moves the version decision away from the tables into whichever caller happened to set the flag.

Generation-owned grammar constants may live on a per-generation struct. Feature gates reachable from more than one generation may not.

Numbers live in the version tables

If a protocol version changes only a number (a cap, a floor, a count), the number goes into SystemLimits or the relevant *_constants table, and the versioned method reads it. Do not add a vN method module whose entire body is return NEW_CONSTANT.

How: add the field with a doc comment naming the method version that reads it. Backfill every shipped SYSTEM_LIMITS_V* (and the mock tables under version/mocks/) with the old value so shipped protocol versions are behaviour-preserving. Add the next SYSTEM_LIMITS_V{n+1} for the unreleased protocol version with the new value. Keep a real method version only where the logic differs: in packages/rs-dpp/src/withdrawal/daily_withdrawal_limit/, v0 computes a tiered percentage of total credits and v2 reads daily_withdrawal_limit_percent from SystemLimits; that is a logic change and earns its own version. Raising the percentage later would be a table edit, not a v3.

Why: reviewers look for limits in the tables. A constant hidden in a method module is a second place to check and a dead module per bump.

Fees change through named schedules

A fee change for a new protocol version is a new named schedule (FEE_VERSION2 in packages/rs-platform-version/src/version/fee/v2.rs, and the next one for the next protocol version) referenced from that PLATFORM_V*, with versioned fee-group constants where a group changed. Never inline a nested FeeVersion { .. } override inside the platform version constant. Preserve earlier schedules. If the unreleased protocol version already owns a new schedule, amend that schedule instead of creating another generation nobody references.

fee_version_number is a separate concept from the schedule generation: it keys persisted fee history and storage-refund behaviour, and it is stored in platform state. Inspect its consumers before changing it. FEE_VERSION1 and FEE_VERSION2 both carry fee_version_number: 1 because storage rates did not change between them, only a fee group did. See the Fee System Overview.

Consensus code reads the version from state

PlatformVersion::latest() is what the binary supports. The active version is what the network agreed on, obtained from platform_state.current_platform_version(). During an upgrade window they differ. latest() belongs in tests and in client code that is choosing which format to emit; it never belongs on a path that decides what a block does.

Serde-based conversions of DataContract read a process-wide current version set through PlatformVersionCurrentVersion::set_current. Tests that build platforms at different protocol versions race on it. Prefer the explicit to_value(platform_version) style API wherever a version is in hand.

Dispatcher shape

The Versioned Dispatch chapter shows the canonical match and its rules. Three details that come up in review:

• The implementation is pub(super) fn name_v0 in v0/mod.rs, usually #[inline(always)]. Nothing outside the method directory calls it.
• The catch-all arm is version => Err(...UnknownVersionMismatch { method, known_versions, received: version }), using the crate's own error (DriveError, ExecutionError, ProtocolError). Optional stages add a None => Err(...VersionNotActive { .. }) arm.
• #[allow(clippy::too_many_arguments)] on a dispatcher and its implementations is accepted. Do not invent a one-off parameter struct only to silence the lint.

platform_version is the last parameter

The observed order in drive and drive-abci is: &self, domain inputs, block_info, mode flags (apply, stateful), the estimation map, transaction, the operations accumulator, platform_version. A new parameter goes up with the context items, never after platform_version. The same holds for fields on context structs such as parse contexts. The known exception is previous_fee_versions, which trails it on fee-returning methods.

Why: readers of a few hundred versioned signatures expect the closing parameter to be the version. Appending after it breaks that scan.

Versioned types

A protocol type that may evolve is an enum over per-version structs (DataContract { V0(DataContractV0), V1(DataContractV1) }) with accessor traits (DataContractV0Getters) implemented on the enum, so call sites never match on the variant. The serde tag for versioned enums is $formatVersion with variants renamed to "0", "1"; $version is reserved for the legacy protocol-version fields and must not be reused. New variants are appended.

The full pattern, including the derive stack and the round-trip test template, is in docs/json-value-conversion-canonical-pattern.md and the Serialization chapters.

Where a check belongs

A new validation rule has exactly one correct tier, determined by what it needs to read. The Validation Pipeline chapter walks the stages in order; this table is the placement guide.

Rules that fall out of the table:

• Basic structure runs inside check_tx on every mempool entry. Keep it cheap and stateless.
• Advanced structure without state uses the transition and the already fetched signing identity. Advanced structure with state uses data fetched by transform_into_action, such as the contract schema carried by a document action: the transformer performs the Drive reads, and the advanced validator consumes the resulting action. A transition opts into the second variant through has_advanced_structure_validation_with_state; today only Batch does.
• Checks that require additional Drive queries, such as uniqueness checks, belong in state validation. Needing a fetched contract does not by itself make a structural check a state-validation check.
• Preserve mempool coverage. Batch runs advanced structure with state during check_tx, while full state validation is skipped there (validates_full_state_on_check_tx defaults to false; masternode votes are the one transition that opts in, because a block refuses them unpaid, and they run advanced structure with state there too). Moving a contract-dependent structural check into state validation would remove that rejection from mempool admission.
• Validation outcomes are ConsensusValidationResult, returned as Ok. A Result::Err from a validation function means the node is broken, not that the transition is invalid. The block loop converts it into an internal-error result instead of halting, and process_proposal rejects any block that contains one.
• Validation lives once. wasm-dpp2, the SDKs, and the FFI layer never duplicate a length, range, or count check that rs-dpp enforces, even when the duplicate would give a friendlier early error. Two definitions of "valid" drift the day one of them changes.
• Consensus errors carry numeric codes in fixed bands (packages/rs-dpp/src/errors/consensus/codes.rs): basic errors in 10000-19999, signature in 20000-29999, fee in 30000-39999, state in 40000-49999, with sub-bands per domain. A new error takes the next free code in its band and is appended to its enum. See Consensus Errors and Error Codes.

Errors, panics, and arithmetic

A panic in block execution halts the chain

packages/rs-drive-abci/src/main.rs installs a panic hook that cancels the node, and there is no catch_unwind anywhere in the crate. A panic reachable from process_proposal or finalize_block is deterministic, so every validator hits it on the same block and the network stops. This is the strongest rule in the codebase:

• On any path reachable from block execution, no unwrap, no expect without a proof, no slice indexing without a bounds check, no unreachable!, no division by a value that could be zero.
• expect is allowed when the message states the invariant established immediately above it, in the style the codebase already uses: .expect("check above enforces it exists"), .expect("we have already shown there is 1 byte"). If you cannot write that sentence, return an error.
• A condition that "cannot happen" but is reachable returns DriveError::CorruptedCodeExecution (or CriticalCorruptedState when the right response is to stall) or ExecutionError::CorruptedCodeExecution. See Drive Errors.
• Action transformers under state_transition_action/**/transformer.rs run before fee and funding checks, so they are the most exposed surface. Treat every conversion there as untrusted input.

The *_blocking accessors in rs-platform-wallet are a related hazard on the client side: tokio::sync::RwLock::blocking_read panics on a runtime worker, and the iOS profiles build with panic = "abort". When the current thread may be inside a runtime, use try_read and return a typed busy error.

Integer arithmetic wraps in release

The root Cargo.toml does not enable overflow-checks, so a release build wraps silently and a debug build panics. Neither is acceptable in credit, fee, or balance math. Use the checked forms and surface Overflow; FeeResult already exposes checked_add_assign for the common case.

Append-only structures are enforced by CI

Structures marked // @append_only (the drive-abci error enums, the data contract error enums, document property types, storage key requirements, CheckTxLevel) accept new variants at the end and nothing else. Structures marked // @immutable (Epoch, BlockInfo) accept no change at all. The Detect immutable structure changes step in .github/workflows/tests-rs-workspace.yml diffs the tagged block against the base branch and fails the PR on a deletion or, for @immutable, any change. The reason is serialization: these types are encoded into proofs, responses, and stored state with positional discriminants. Reordering or removing a variant changes what old bytes mean.

The same rule applies without a marker to anything with a DO NOT CHANGE ORDER banner, to StateTransitionType discriminants, and to SystemDataContract slots (note the reserved FeatureFlags = 2).

Consensus errors versus internal errors

A ConsensusError is something two nodes must agree on: it is deterministic, carries a code, and is serialized to the client. A ProtocolError, DriveError or ExecutionError means the build is wrong, data is corrupt, or an API was misused. Never return a consensus error for an internal failure or an internal error for a user mistake; the block loop treats the two classes differently.

Module layout and style

• One method, one directory. method_name/mod.rs holds the public dispatcher and its doc comment; method_name/v0/mod.rs holds the implementation. The dispatcher's doc comment has # Parameters and # Returns sections. drive and drive-abci compile with #![deny(missing_docs)], so every public item needs a doc line.
• Drive's naming triad. *_operations gathers Vec<LowLevelDriveOperation> without applying anything and takes the estimated_costs_only_with_layer_info map for dry runs; *_apply_and_add_to_operations appends into a caller-owned accumulator and applies; the bare public method owns the accumulator and returns a FeeResult. Keep new storage methods in this shape so cost estimation and real execution share one code path. See Drive Operations.
• Tests sit with the implementation. A #[cfg(test)] mod tests block at the bottom of vN/mod.rs, or vN/tests/ when it outgrows the file. The dispatcher's mod.rs may carry end-to-end tests that need every version.
• Imports at the top. No fully qualified crate::a::b::c::function(...) at a call site or in a signature. Add a use and call it bare, or keep at most one module qualifier when the bare name would be ambiguous. Inline paths are fine in doc comments and inside macros that cannot see imports.
• No unsafe. dpp, drive, and drive-abci compile with #![forbid(unsafe_code)]. Unsafe stays in the FFI crates and in dependencies.
• Test-code lints are real lints. CI runs cargo clippy --workspace --all-targets --all-features -- -D warnings, so clippy::type_complexity in a test helper or &vec![..] passed as a slice in a test fails the build. drive-abci allows a fixed list of test lints at the crate root; do not extend it for convenience.
• State access is snapshot-based. Platform.state is an ArcSwap; read with load() and pass PlatformRef or PlatformStateRef down. The only locks are the ABCI application's transaction, block_execution_context and unsigned_withdrawal_txs_by_round, taken in that order. In async code, a guard's scope, not a drop() call, is what clears clippy::await_holding_lock; wrap the guard in a block that ends before the first .await.

Tests

• The latest generation tests against PlatformVersion::latest(). Only frozen older generations pin an explicit version with PlatformVersion::get(n). When you introduce v(N+1), that is the moment to pin the now-frozen vN module's tests. Pinning the current generation to today's number only creates churn when the next version lands.
• Test behaviour through the dispatcher, on both sides of the gate. "PV13 rejects this query shape, PV14 accepts it" is a real test. "Slot foo is 0 in PLATFORM_V13 and 1 in PLATFORM_V14" restates the table literal and cannot fail without the edit being deliberate; do not write it. The exception is a historical freeze test that guards a shipped on-chain table with a replay rationale, like historical_method_table_freeze in the drive document method versions.
• Names start with should, unit tests never touch the network, and randomness is seeded (StdRng::seed_from_u64). Platforms come from TestPlatformBuilder; Drives come from setup_drive_with_initial_state_structure. See Unit Tests.
• Multi-block behaviour is a strategy test. Anything involving epochs, upgrades, withdrawals over time, or proposer churn belongs in packages/rs-drive-abci/tests/strategy_tests/. See Strategy Tests.
• Fixtures are shared. rs-dpp exposes its fixtures under the fixtures-and-mocks feature; rs-sdk records test vectors from a devnet and replays them offline. Add to those rather than hand-rolling payloads.
• Struct-literal churn is caught by --all-targets. A new required field compiles clean under a lib-only cargo check and then fails in a test module in CI. After adding a field or changing a signature, run cargo check --workspace --all-targets.

Client layers

Proof verification is layered

drive::verify does the GroveDB work: each verifier is a method on the Drive*Query type, builds the path query with the same builder the prover uses, and returns (RootHash, T). drive-proof-verifier takes the full Proof message, calls into that method, and layers the Tenderdash signature check on top; the FromProof impl is the SDK's entry point. Never call GroveDb::verify_* from the proof-verifier crate and never build the path query at the SDK call site; both create a "these bytes must match the prover" invariant that nothing checks. Entry types live in drive and are re-exported so SDK consumers need no direct drive dependency.

The wasm layer mirrors, it does not reshape

rs-dpp serde defines the canonical wire shape and wasm-dpp2 mirrors it one to one, differing only in primitive encoding (Uint8Array versus base64, bigint versus number-or-string). Sum types are internally tagged with type, never wrapped in data. Field-like accessors are properties, verbs are methods. The rules and their reasons are in packages/wasm-dpp2/CONVENTIONS.md and the WASM chapters.

FFI and mobile SDKs hold no business logic

The FFI crates (rs-sdk-ffi, rs-platform-wallet-ffi, key-wallet-ffi) and the Swift and Kotlin SDKs do three things: persist Rust-emitted state, load it for views, and call a function that already exists in a Rust library. If the wrapper is deciding anything (an index, a derivation path, which key, how many), that decision moves into Rust, usually rs-platform-wallet. An FFI function is named for the user-facing verb (sendContactRequest, sendToContact), not for a cryptographic or wallet building block; DIP-14 and DIP-15 derivation primitives stay internal. The motivating case was a Swift view that iterated the gap limit, built the DIP-9 path, and pulled the mnemonic across the FFI twice to do what one preview_identity_registration_keys call now does.

Commits, pull requests, and what to run before pushing

• Conventional Commits, with the repository's own scope list. Types and scopes are enforced by .github/workflows/pr.yml. The subject starts lowercase. A change that spans packages uses no scope rather than an invented one (deps is not a scope; rs-platform-wallet-ffi changes use platform-wallet).

• ! means consensus-breaking. feat!: and fix!: are reserved for changes that would fork the network if rolled out unevenly: protocol rules, state-transition shapes, the fee model, anything nodes must agree on. Removing a public Swift symbol or an extern "C" function is ordinary feat: or refactor: work described in the PR body.

• Design documents are working artifacts. A spec or plan written to drive a change stays in the working tree and is never staged. Stage with explicit paths. Facts worth keeping after merge go into a code comment, a test name, or the PR description.

• Local gate before pushing. The exhaustive pass is CI's job; the local pass is scoped to what changed:

  cargo fmt --all
  cargo clippy -p <crate> --all-features --all-targets -- -D warnings
  cargo check --workspace --all-targets          # after any field or signature change
  cargo check -p drive --no-default-features --features verify   # when touching src/verify/**
  cargo test -p <crate> <filter>                 # the tests for the change, not the suite
  

  Do not block a push on the full drive-abci suite; it runs for a quarter of an hour and CI runs it anyway.

Checklists

Adding a new generation of a versioned method

1. Copy vN/ to v(N+1)/, make the change there, leave vN/ byte-identical.
2. Add the N+1 => arm to the dispatcher and extend known_versions.
3. Bump the method's number in the unreleased protocol version's tables only. If that protocol version already has a new table constant, amend it.
4. Move or write the behaviour tests in v(N+1)/ against PlatformVersion::latest(); pin vN/'s tests to PlatformVersion::get(n).
5. Add a test that runs both versions through the dispatcher.

Editing a shipped generation in place

1. Only when the edit cannot modify consensus at any protocol version that selects the module: unreachable by construction there, or output-identical.
2. Comment the edited lines with why they are inert for those versions.
3. Add a test that runs the module at the last shipped protocol version and shows the outcome unchanged.
4. Add an "In-place changes to shipped generations" section to the pull request description: each edited generation, the versions that select it, and the reason consensus cannot change there.

Changing a limit or a fee

1. A number: add or update the SystemLimits (or *_constants) field, backfill shipped tables with the old value, add the next table for the unreleased protocol version.
2. A fee: add or amend the unreleased protocol version's named FEE_VERSION* schedule; do not touch fee_version_number unless storage rates changed and you have read its consumers.
3. The method reads the table. No new vN unless the logic changed.

Adding a consensus error

1. New file under errors/consensus/{basic,state,signature,fee}/<domain>/ with the standard derive stack, private fields, new(), getters, and the ordering banner.
2. Append the variant to its sub-enum; add the From impl for ConsensusError.
3. Assign the next free code in the band in codes.rs.
4. If JavaScript branches on it, mirror the code in packages/wasm-dpp2/src/consensus_error.rs.

Adding a check to a state transition

1. Pick the tier from the table above by what the check reads.
2. Put it in <transition>/<tier>/v(N+1)/ if the transition has shipped, or in the existing vN if that generation is still unreleased.
3. Return it through ConsensusValidationResult; never Err.
4. Test the rejection through process_raw_state_transitions, and test that the previous protocol version still accepts the input.

Adding GroveDB structure

1. Put the key constant and the *_path() / *_path_vec() pair in the area's paths.rs. A new root key goes where writes below it are rare; see The GroveDB Structure.
2. Build it in one function that both create_initial_state_structure and the protocol upgrade (transition_to_version_N) call, in the same order, so a fresh chain and an upgraded one hold the same state.
3. Describe it in the structure.rs beside that paths.rs, from the same constant, with since set to the protocol version that introduces it and the element flags it is written with.
4. Regenerate the exported file and commit it: UPDATE_GROVEDB_STRUCTURE=1 cargo test -p drive --lib structure::tests.
5. Make sure something writes to the new nodes under test: a fixture in structure/tests.rs, or a strategy test (every chain they run is checked against the description). UNVERIFIED is empty; keep it that way.
6. The pull request gets a comment with a link to the structure viewer showing the new nodes. Check that it shows what you meant to add.

Adding a query end-to-end

1. Proto message in packages/dapi-grpc/protos/platform/v0/platform.proto, registered in build.rs's versioned request and response lists.
2. Drive query type and prover, then drive::verify method with its FeatureVersion slot, with a prover-verifier round trip test.
3. drive-abci handler under query/<name>/{mod.rs,v0/} dispatching on the request version against drive_abci.query bounds.
4. drive-proof-verifier FromProof wrapper, then the rs-sdk Query and Fetch/FetchMany impls per the checklist in packages/rs-sdk/README.md.
5. Genesis test data and a recorded test vector so the SDK test runs offline.

Platform Version

The Problem: Deterministic Upgrades in a Distributed System

Dash Platform is a replicated state machine. Every masternode in the network processes the same transactions and must arrive at the exact same state. If even one node computes a fee differently, serializes a document with one extra byte, or validates a field that others skip, the chain forks.

Now imagine you need to ship a bug fix. In a normal application you deploy the new binary and move on. In a blockchain you have a harder constraint: not every node upgrades at the same moment. Some masternodes will still be running the old code when the new protocol version activates. The system needs a way to say "at protocol version N, use these exact behaviors" -- and it needs to be impossible for a developer to accidentally mix behaviors from different versions.

The answer is the PlatformVersion struct: a single, massive, immutable snapshot that pins every versioned behavior in the entire platform to a concrete value.

The PlatformVersion Struct

Open packages/rs-platform-version/src/version/protocol_version.rs and you will find the heart of the system:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug)]
pub struct PlatformVersion {
    pub protocol_version: ProtocolVersion,
    pub dpp: DPPVersion,
    pub drive: DriveVersion,
    pub drive_abci: DriveAbciVersion,
    pub consensus: ConsensusVersions,
    pub fee_version: FeeVersion,
    pub system_data_contracts: SystemDataContractVersions,
    pub system_limits: SystemLimits,
}
}

Where ProtocolVersion is simply:

#![allow(unused)]
fn main() {
pub type ProtocolVersion = u32;
}

Every field inside PlatformVersion is itself a version struct -- and those structs contain more version structs, all the way down to individual method version numbers. We will explore that nesting in the next chapter. For now, the key insight is that PlatformVersion is the root of a tree. Given a single protocol version number (like 7), you can resolve the exact version of every method, every fee parameter, every system limit, and every data contract schema across the entire platform.

Think of it like a lockfile in a package manager. Cargo.lock pins every transitive dependency to a specific version so that builds are reproducible. PlatformVersion does the same thing for runtime behavior: it pins every 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:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/mod.rs

pub type ProtocolVersion = u32;

pub const LATEST_VERSION: ProtocolVersion = PROTOCOL_VERSION_14;
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 protocol_version.rs:

#![allow(unused)]
fn main() {
pub const PLATFORM_VERSIONS: &[PlatformVersion] = &[
    PLATFORM_V1,
    PLATFORM_V2,
    PLATFORM_V3,
    PLATFORM_V4,
    PLATFORM_V5,
    PLATFORM_V6,
    PLATFORM_V7,
    PLATFORM_V8,
    PLATFORM_V9,
    PLATFORM_V10,
    PLATFORM_V11,
    PLATFORM_V12,
    PLATFORM_V13,
    PLATFORM_V14,
];

pub const LATEST_PLATFORM_VERSION: &PlatformVersion = &PLATFORM_V14;
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 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 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 built today.

What a Version Snapshot Looks Like

Here is the very first version, PLATFORM_V1, slightly abbreviated:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/v1.rs

pub const PROTOCOL_VERSION_1: ProtocolVersion = 1;

pub const PLATFORM_V1: PlatformVersion = PlatformVersion {
    protocol_version: 1,
    drive: DRIVE_VERSION_V1,
    drive_abci: DriveAbciVersion {
        structs: DRIVE_ABCI_STRUCTURE_VERSIONS_V1,
        methods: DRIVE_ABCI_METHOD_VERSIONS_V1,
        validation_and_processing: DRIVE_ABCI_VALIDATION_VERSIONS_V1,
        withdrawal_constants: DRIVE_ABCI_WITHDRAWAL_CONSTANTS_V1,
        query: DRIVE_ABCI_QUERY_VERSIONS_V1,
        checkpoints: DRIVE_ABCI_CHECKPOINT_PARAMETERS_V1,
    },
    dpp: DPPVersion {
        costs: DPP_COSTS_VERSIONS_V1,
        validation: DPP_VALIDATION_VERSIONS_V1,
        state_transition_serialization_versions: STATE_TRANSITION_SERIALIZATION_VERSIONS_V1,
        state_transition_conversion_versions: STATE_TRANSITION_CONVERSION_VERSIONS_V1,
        state_transition_method_versions: STATE_TRANSITION_METHOD_VERSIONS_V1,
        state_transitions: STATE_TRANSITION_VERSIONS_V1,
        contract_versions: CONTRACT_VERSIONS_V1,
        document_versions: DOCUMENT_VERSIONS_V1,
        identity_versions: IDENTITY_VERSIONS_V1,
        voting_versions: VOTING_VERSION_V1,
        token_versions: TOKEN_VERSIONS_V1,
        asset_lock_versions: DPP_ASSET_LOCK_VERSIONS_V1,
        methods: DPP_METHOD_VERSIONS_V1,
        factory_versions: DPP_FACTORY_VERSIONS_V1,
    },
    system_data_contracts: SYSTEM_DATA_CONTRACT_VERSIONS_V1,
    fee_version: FEE_VERSION1,
    system_limits: SYSTEM_LIMITS_V1,
    consensus: ConsensusVersions {
        tenderdash_consensus_version: 0,
    },
};
}

Now compare with PLATFORM_V14, the latest at the time of writing. 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, validation (DPP_VALIDATION_VERSIONS_V4 to V5), is missing its comment, which is exactly the omission the convention exists to prevent:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/v14.rs

pub const PLATFORM_V14: PlatformVersion = PlatformVersion {
    protocol_version: PROTOCOL_VERSION_14,
    drive: DRIVE_VERSION_V9, // changed: drive document method versions v4 (v2 index walkers, detect_ranked_mode slot)
    drive_abci: DriveAbciVersion {
        structs: DRIVE_ABCI_STRUCTURE_VERSIONS_V1,
        methods: DRIVE_ABCI_METHOD_VERSIONS_V10, // changed: records the per-block total credits history
        validation_and_processing: DRIVE_ABCI_VALIDATION_VERSIONS_V10, // changed: contested-index cross-check + refersTo validation
        withdrawal_constants: DRIVE_ABCI_WITHDRAWAL_CONSTANTS_V3, // changed: prune bound for the total credits history
        query: DRIVE_ABCI_QUERY_VERSIONS_V2, // changed: ranked + boolean-HAVING routing gate
        checkpoints: DRIVE_ABCI_CHECKPOINT_PARAMETERS_V1,
    },
    dpp: DPPVersion {
        costs: DPP_COSTS_VERSIONS_V1,
        validation: DPP_VALIDATION_VERSIONS_V5,
        state_transition_serialization_versions: STATE_TRANSITION_SERIALIZATION_VERSIONS_V3, // changed: documentIndexOnlyDelete joins the wire
        state_transition_conversion_versions: STATE_TRANSITION_CONVERSION_VERSIONS_V2,
        state_transition_method_versions: STATE_TRANSITION_METHOD_VERSIONS_V1,
        state_transitions: STATE_TRANSITION_VERSIONS_V3,
        contract_versions: CONTRACT_VERSIONS_V6, // changed: v3 document meta-schema (ranked, refersTo, requiredSince, timeRange)
        document_versions: DOCUMENT_VERSIONS_V4, // changed: document serialization format 3
        identity_versions: IDENTITY_VERSIONS_V1,
        voting_versions: VOTING_VERSION_V2,
        token_versions: TOKEN_VERSIONS_V2,
        asset_lock_versions: DPP_ASSET_LOCK_VERSIONS_V1,
        methods: DPP_METHOD_VERSIONS_V3, // changed: daily_withdrawal_limit v2
        factory_versions: DPP_FACTORY_VERSIONS_V1,
    },
    system_data_contracts: SYSTEM_DATA_CONTRACT_VERSIONS_V3, // changed: DashPay v2 profile payment address fields
    fee_version: FEE_VERSION2,
    system_limits: SYSTEM_LIMITS_V4, // changed: relative daily withdrawal limit + time-range overlap cap
    consensus: ConsensusVersions {
        tenderdash_consensus_version: 1,
    },
};
}

Notice how only some subsystem versions change between V1 and V14. The ABCI structure versions and checkpoint parameters are still at V1 because nothing in them ever changed. The ABCI method versions, on the other hand, went from V1 to V10 -- ten revisions of the block processing logic -- and the query versions from V1 to V3.

This is the power of the snapshot model: each subsystem version evolves at its own pace. A new protocol version does not require bumping everything. You only change the sub-constants that actually differ.

Two annotation conventions make a version file reviewable:

• The file's doc comment is the changelog. v14.rs opens with a numbered list of every consensus change the version hosts, each with a paragraph on what it does and why it needed a protocol version. A change landing in the unreleased version adds an item there.
• Every bumped slot gets a // changed: comment saying what the new sub-constant does differently. A reviewer reading PLATFORM_V14 top to bottom sees every behaviour difference from PLATFORM_V13 without opening another file.

What Belongs in the Snapshot

The snapshot holds three kinds of values, and the third is the one people forget:

1. Method versions. FeatureVersion numbers that select a v0, v1, ... implementation. The next two chapters are about these.
2. Format bounds. FeatureVersionBounds for serialized structures: which structure versions a node accepts and which one it writes.
3. Protocol parameters. Plain numbers the code reads at runtime: size caps, per-block limits, penalty amounts, fee rates, retention windows, expiry heights. SystemLimits, FeeVersion, DriveAbciWithdrawalConstants, DriveAbciValidationConstants and PenaltyAmounts are all tables of these.

The rule for the third kind: a constant that might change in a future protocol version is declared in the version tables, not in an implementation file. Code reads it through platform_version. A const MAX_SOMETHING: u16 = 50; at the top of a Drive module is a value that cannot change without editing shipped code, which is exactly what the versioning system exists to avoid. A field on SystemLimits can change at a protocol-version boundary with the old value preserved for replay.

Two consequences:

• Changing a number never creates a new method version. You change the table, and the method that reads the table keeps its version. See Non-Method Version Fields for the recipe.
• Constants that genuinely cannot change stay in code: key and hash lengths, encoding widths, tree key bytes, anything whose change would be a new storage format rather than a new parameter. The test is whether a future protocol version could plausibly want a different value. If it could, it belongs in the tables from the start; moving it later means touching shipped code.

The Get Dispatch

The most important function on PlatformVersion is get:

#![allow(unused)]
fn main() {
impl PlatformVersion {
    pub fn get<'a>(version: ProtocolVersion) -> Result<&'a Self, PlatformVersionError> {
        if version > 0 {
            PLATFORM_VERSIONS.get(version as usize - 1).ok_or_else(|| {
                PlatformVersionError::UnknownVersionError(
                    format!("no platform version {version}")
                )
            })
        } else {
            Err(PlatformVersionError::UnknownVersionError(
                format!("no platform version {version}")
            ))
        }
    }
}
}

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 hash maps, no runtime registration, no dynamic dispatch -- just a static array of compile-time constants.

There are also convenience methods:

#![allow(unused)]
fn main() {
impl PlatformVersion {
    pub fn first<'a>() -> &'a Self {
        PLATFORM_VERSIONS.first()
            .expect("expected to have a platform version")
    }

    pub fn latest<'a>() -> &'a Self {
        PLATFORM_VERSIONS.last()
            .expect("expected to have a platform version")
    }

    pub fn desired<'a>() -> &'a Self {
        DESIRED_PLATFORM_VERSION
    }
}
}

first() is used in tests that need to verify behavior under the initial protocol. latest() is the default for new code. desired() returns the version that nodes want to upgrade to -- it equals latest() during normal operation but could theoretically differ during a staged rollout.

Version-Aware Traits

The rs-platform-version crate also defines traits that thread the platform version through standard Rust conversion patterns:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/lib.rs

pub trait TryFromPlatformVersioned<T>: Sized {
    type Error;

    fn try_from_platform_versioned(
        value: T,
        platform_version: &PlatformVersion,
    ) -> Result<Self, Self::Error>;
}

pub trait DefaultForPlatformVersion: Sized {
    type Error;

    fn default_for_platform_version(
        platform_version: &PlatformVersion,
    ) -> Result<Self, Self::Error>;
}
}

These are the versioned equivalents of TryFrom and Default. When you convert a data structure, you pass the platform version so the implementation can pick the right serialization format, the right field set, or the right validation rules. There is also FromPlatformVersioned for infallible conversions, and blanket IntoPlatformVersioned implementations that mirror the standard library pattern.

Mock Versions for Testing

The version system supports a mock-versions feature flag for tests:

#![allow(unused)]
fn main() {
#[cfg(feature = "mock-versions")]
pub static PLATFORM_TEST_VERSIONS: OnceLock<Vec<PlatformVersion>> = OnceLock::new();
}

When this feature is enabled, PlatformVersion::get checks for a special bit in the version number. If set, it routes to the test version array instead of the production one. This lets tests create synthetic platform versions with specific behaviors without polluting the production constants:

#![allow(unused)]
fn main() {
#[cfg(feature = "mock-versions")]
{
    if version >> TEST_PROTOCOL_VERSION_SHIFT_BYTES > 0 {
        let test_version = version - (1 << TEST_PROTOCOL_VERSION_SHIFT_BYTES);
        let versions = PLATFORM_TEST_VERSIONS
            .get_or_init(|| vec![TEST_PLATFORM_V2, TEST_PLATFORM_V3]);
        return versions.get(test_version as usize - 2).ok_or(/* ... */);
    }
}
}

This is a clever design: tests can exercise version upgrade logic (like "what happens when we transition from test version 2 to test version 3?") without needing to create real protocol versions.

Why Immutable Snapshots?

You might wonder: why not use a mutable configuration object? Why not a HashMap<&str, u16> that maps method names to versions?

Three reasons:

1. Determinism. A const value is baked into the binary at compile time. There is no way to accidentally modify it at runtime. Every node running the same binary with the same protocol version will use the exact same values.

2. Exhaustiveness. Because the version struct has named fields for every subsystem, adding a new versioned method forces you to set its version in every platform version constant. The compiler will refuse to compile if you forget one. A hash map cannot give you this guarantee.

3. Performance. Looking up a version number is a struct field access -- zero overhead at runtime. The entire version tree lives in static memory. No allocations, no lookups, no indirection.

The cost is verbosity. Each new platform version file is large and repetitive. But this is a deliberate trade-off: the system favors correctness and auditability over conciseness. When you read PLATFORM_V14, you can see every single version number in one place. There is no mystery about what version 14 means.

Rules

Do:

• Always pass &PlatformVersion (or &DriveVersion, etc.) to functions that have versioned behavior. Never hardcode a version number at a call site.
• Use PlatformVersion::latest() for tests of the current generation. Pin an explicit version with PlatformVersion::get(n) only for tests of a frozen, older generation, and use PlatformVersion::first() when you need the initial protocol behavior.
• Create vN.rs once, when the first consensus change after version N-1 ships needs a home: copy the previous version file and change only the constants that differ. Every later change destined for version N amends that file: add a numbered item to its doc comment and a // changed: comment on each slot it bumps.
• Declare any constant that might change in a future protocol version in the version tables (SystemLimits, FeeVersion, the *Constants structs) and read it through platform_version. Keep only genuinely invariant values as const items in implementation files.

Do not:

• Never mutate platform version data at runtime. The constants are const for a reason.
• Never edit a released vN.rs, or any table constant it references. Once a protocol version has run on the network its snapshot is part of the chain's history; a change there makes a fresh node replay history differently from 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.
• 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 the binary supports; the active version is what the network has agreed upon -- and they may differ during an upgrade window.

Feature Versions

The Problem: Granularity

The previous chapter showed how PlatformVersion is an immutable snapshot of the entire platform's behavior at a given protocol version. But a snapshot is only useful if it can describe behavior at a fine enough granularity.

Consider the Drive storage layer. It has dozens of grove operations, hundreds of document methods, contract methods, identity methods, and more. When you fix a bug in update_contract, you need to bump that one method's version without affecting insert_contract or prove_contract. The system needs a way to assign a version number to individual methods and then compose those numbers into larger subsystem snapshots.

This is where FeatureVersion and the nested version structs come in.

The FeatureVersion Type

At the very bottom of the version tree is a single type, defined in the external versioned-feature-core crate:

#![allow(unused)]
fn main() {
// versioned-feature-core/src/lib.rs

pub type FeatureVersion = u16;
pub type OptionalFeatureVersion = Option<u16>;
}

That is it. A FeatureVersion is a u16 -- a number that says "use version N of this particular function." The value 0 means "use the v0 implementation," 1 means "use v1," and so on.

OptionalFeatureVersion is Option<u16>. It represents a feature that did not exist in earlier protocol versions. When the value is None, the feature is not active -- calling it returns a VersionNotActive error. When it is Some(0), the feature exists and should use its v0 implementation.

There is also a bounds type for serialization format versions:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct FeatureVersionBounds {
    pub min_version: FeatureVersion,
    pub max_version: FeatureVersion,
    pub default_current_version: FeatureVersion,
}
}

This is used when a field can accept a range of versions -- for example, a data contract serialization format where the system can read versions 0 through 2 but writes version 2 by default.

Version Structs: The Middle of the Tree

Between the top-level PlatformVersion and the leaf-level FeatureVersion numbers sit dozens of intermediate structs. These structs group related method versions together, forming a hierarchy that mirrors the codebase's module structure.

Let us trace a path from the top down.

Level 1: PlatformVersion

#![allow(unused)]
fn main() {
pub struct PlatformVersion {
    pub protocol_version: ProtocolVersion,
    pub dpp: DPPVersion,
    pub drive: DriveVersion,
    pub drive_abci: DriveAbciVersion,
    pub consensus: ConsensusVersions,
    pub fee_version: FeeVersion,
    pub system_data_contracts: SystemDataContractVersions,
    pub system_limits: SystemLimits,
}
}

Level 2: DriveVersion

The drive field contains DriveVersion, which groups all storage layer versions:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/drive_versions/mod.rs

#[derive(Clone, Debug, Default)]
pub struct DriveVersion {
    pub structure: DriveStructureVersion,
    pub methods: DriveMethodVersions,
    pub grove_methods: DriveGroveMethodVersions,
    pub grove_version: GroveVersion,
}
}

Level 3: DriveMethodVersions

The methods field expands into every category of Drive operation:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DriveMethodVersions {
    pub initialization: DriveInitializationMethodVersions,
    pub credit_pools: DriveCreditPoolMethodVersions,
    pub protocol_upgrade: DriveProtocolUpgradeVersions,
    pub prefunded_specialized_balances: DrivePrefundedSpecializedMethodVersions,
    pub balances: DriveBalancesMethodVersions,
    pub document: DriveDocumentMethodVersions,
    pub vote: DriveVoteMethodVersions,
    pub contract: DriveContractMethodVersions,
    pub fees: DriveFeesMethodVersions,
    pub estimated_costs: DriveEstimatedCostsMethodVersions,
    pub asset_lock: DriveAssetLockMethodVersions,
    pub verify: DriveVerifyMethodVersions,
    pub identity: DriveIdentityMethodVersions,
    pub token: DriveTokenMethodVersions,
    pub platform_system: DrivePlatformSystemMethodVersions,
    pub operations: DriveOperationsMethodVersion,
    pub batch_operations: DriveBatchOperationsMethodVersion,
    pub fetch: DriveFetchMethodVersions,
    pub prove: DriveProveMethodVersions,
    pub state_transitions: DriveStateTransitionMethodVersions,
    pub platform_state: DrivePlatformStateMethodVersions,
    pub group: DriveGroupMethodVersions,
    pub address_funds: DriveAddressFundsMethodVersions,
    pub saved_block_transactions: DriveSavedBlockTransactionsMethodVersions,
}
}

Level 4: Individual Method Categories

Each category struct contains FeatureVersion fields for individual methods. For example, the contract method versions:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DriveContractMethodVersions {
    pub prove: DriveContractProveMethodVersions,
    pub apply: DriveContractApplyMethodVersions,
    pub insert: DriveContractInsertMethodVersions,
    pub update: DriveContractUpdateMethodVersions,
    pub costs: DriveContractCostsMethodVersions,
    pub get: DriveContractGetMethodVersions,
}

#[derive(Clone, Debug, Default)]
pub struct DriveContractUpdateMethodVersions {
    pub update_contract: FeatureVersion,
    pub update_description: FeatureVersion,
    pub update_keywords: FeatureVersion,
}
}

So the full path to read "which version of update_contract should I use?" is:

#![allow(unused)]
fn main() {
platform_version.drive.methods.contract.update.update_contract
}

That is a five-level deep field access, and it resolves to a plain u16.

The Grove Methods Branch

Let us trace a different path. The grove_methods field on DriveVersion holds versions for low-level GroveDB operations:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DriveGroveMethodVersions {
    pub basic: DriveGroveBasicMethodVersions,
    pub batch: DriveGroveBatchMethodVersions,
    pub apply: DriveGroveApplyMethodVersions,
    pub costs: DriveGroveCostMethodVersions,
}
}

The basic struct is where individual grove operations live:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DriveGroveBasicMethodVersions {
    pub grove_insert: FeatureVersion,
    pub grove_insert_empty_tree: FeatureVersion,
    pub grove_insert_if_not_exists: FeatureVersion,
    pub grove_clear: FeatureVersion,
    pub grove_delete: FeatureVersion,
    pub grove_get_raw: FeatureVersion,
    pub grove_get_raw_optional: FeatureVersion,
    pub grove_get: FeatureVersion,
    pub grove_get_path_query: FeatureVersion,
    pub grove_get_proved_path_query: FeatureVersion,
    pub grove_get_sum_tree_total_value: FeatureVersion,
    pub grove_has_raw: FeatureVersion,
    // ... and many more
}
}

So the path for grove_get_raw is:

#![allow(unused)]
fn main() {
drive_version.grove_methods.basic.grove_get_raw
}

Notice something: grove operations take a &DriveVersion rather than &PlatformVersion. This is a minor optimization -- when you are deep in the Drive layer, you only need the drive-specific version numbers, not the entire platform snapshot. The caller extracts &platform_version.drive once and passes it down.

The DPP Branch

The Dash Platform Protocol has its own deep tree. DPPVersion contains fourteen sub-version structs:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DPPVersion {
    pub costs: DPPCostsVersions,
    pub validation: DPPValidationVersions,
    pub state_transition_serialization_versions: DPPStateTransitionSerializationVersions,
    pub state_transition_conversion_versions: DPPStateTransitionConversionVersions,
    pub state_transition_method_versions: DPPStateTransitionMethodVersions,
    pub state_transitions: DPPStateTransitionVersions,
    pub contract_versions: DPPContractVersions,
    pub document_versions: DPPDocumentVersions,
    pub identity_versions: DPPIdentityVersions,
    pub voting_versions: DPPVotingVersions,
    pub token_versions: DPPTokenVersions,
    pub asset_lock_versions: DPPAssetLockVersions,
    pub methods: DPPMethodVersions,
    pub factory_versions: DPPFactoryVersions,
}
}

And those go deeper. For example, DPPContractVersions contains not just FeatureVersion values but also FeatureVersionBounds and further nesting:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DPPContractVersions {
    pub max_serialized_size: u32,
    pub contract_serialization_version: FeatureVersionBounds,
    pub contract_structure_version: FeatureVersion,
    pub created_data_contract_structure: FeatureVersion,
    pub config: FeatureVersionBounds,
    pub methods: DataContractMethodVersions,
    pub document_type_versions: DocumentTypeVersions,
    pub token_versions: TokenVersions,
}
}

Notice max_serialized_size: u32. Not every field is a FeatureVersion. Some are configuration values -- limits, thresholds, constants -- that change between protocol versions. The version struct is flexible enough to hold both "which implementation to use" and "what parameters to use."

The Drive ABCI Branch

The DriveAbciVersion struct covers the application blockchain interface -- the layer that processes blocks, validates state transitions, and handles protocol upgrades:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DriveAbciVersion {
    pub structs: DriveAbciStructureVersions,
    pub methods: DriveAbciMethodVersions,
    pub validation_and_processing: DriveAbciValidationVersions,
    pub withdrawal_constants: DriveAbciWithdrawalConstants,
    pub query: DriveAbciQueryVersions,
    pub checkpoints: DriveAbciCheckpointParameters,
}
}

The validation_and_processing field is where state transition validation versions live. This is where OptionalFeatureVersion becomes important:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Default)]
pub struct DriveAbciStateTransitionValidationVersion {
    pub basic_structure: OptionalFeatureVersion,
    pub advanced_structure: OptionalFeatureVersion,
    pub identity_signatures: OptionalFeatureVersion,
    pub nonce: OptionalFeatureVersion,
    pub state: FeatureVersion,
    pub transform_into_action: FeatureVersion,
}
}

basic_structure is OptionalFeatureVersion -- in some protocol versions, basic structure validation may not exist for a particular state transition. The dispatch code handles this with a three-arm match:

#![allow(unused)]
fn main() {
match platform_version
    .drive_abci
    .validation_and_processing
    .state_transitions
    .identity_create_state_transition
    .basic_structure
{
    Some(0) => self.validate_basic_structure_v0(platform_version),
    Some(version) => Err(Error::Execution(
        ExecutionError::UnknownVersionMismatch { /* ... */ }
    )),
    None => Err(Error::Execution(
        ExecutionError::VersionNotActive { /* ... */ }
    )),
}
}

Compare with state and transform_into_action which are plain FeatureVersion -- those validations always exist, so there is no None arm.

Non-Method Version Fields

Some version structs contain values that are not method versions at all, but protocol parameters. SystemLimits is the main one:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/system_limits/mod.rs

#[derive(Clone, Debug, Default)]
pub struct SystemLimits {
    pub estimated_contract_max_serialized_size: u16,
    pub max_field_value_size: u32,
    /// `None` preserves the behavior of protocol versions that predate this limit.
    pub max_document_value_depth: Option<u16>,
    pub max_state_transition_size: u64,
    pub max_transitions_in_documents_batch: u16,
    pub withdrawal_transactions_per_block_limit: u16,
    pub retry_signing_expired_withdrawal_documents_per_block_limit: u16,
    pub max_withdrawal_amount: u64,
    /// `None` for the protocol versions that predate the relative rule.
    pub daily_withdrawal_limit_percent: Option<u8>,
    pub core_credit_pool_unlock_limit_percent: Option<u8>,
    pub core_credit_pool_unlock_limit_floor: Option<u64>,
    pub core_credit_pool_window_blocks: Option<u32>,
    pub regtest_core_credit_pool_window_blocks: Option<u32>,
    pub min_withdrawal_amount: u64,
    pub max_contract_group_size: u16,
    pub max_token_redemption_cycles: u32,
    pub max_shielded_transition_actions: u16,
    pub max_time_range_overlap_factor: Option<u64>,
}
}

There are four SYSTEM_LIMITS_V* constants, one for each protocol version at which a limit changed. The Option fields show the idiom for a parameter that did not exist before some version: None in the tables of the versions that predate the rule, Some(value) from the version that introduced it. It is the parameter-shaped twin of OptionalFeatureVersion.

The same shape recurs wherever a subsystem owns tunables:

#![allow(unused)]
fn main() {
// drive_abci_versions/drive_abci_withdrawal_constants/mod.rs
pub struct DriveAbciWithdrawalConstants {
    pub core_expiration_blocks: u32,
    pub cleanup_expired_locks_of_withdrawal_amounts_limit: u16,
    pub total_credits_history_prune_limit: u16,
    pub core_blocks_scanned_per_block_limit: u16,
}

// drive_abci_versions/drive_abci_validation_versions/mod.rs
pub struct PenaltyAmounts {
    pub identity_id_not_correct: u64,
    pub unique_key_already_present: u64,
    // ...
    pub shielded_proof_verification_failure: u64,
}

pub struct DriveAbciCoreChainLockMethodVersionsAndConstants {
    pub choose_quorum: FeatureVersion,
    pub verify_chain_lock: FeatureVersion,
    // ...
    pub recent_block_count_amount: u32,
}
}

The chain lock struct mixes method versions (choose_quorum: FeatureVersion) with protocol constants (recent_block_count_amount: u32). This is perfectly fine -- the version snapshot captures all protocol-specific values, whether they control dispatch or configure behavior. Fee rates follow the same idea one level up: FeeVersion is a table of numbers, and a fee change is a new named FEE_VERSION* schedule referenced from the platform version, never an inline override inside PLATFORM_V*.

Changing a number

Because parameters live in tables, changing one is a table edit and not a method version:

1. If the field does not exist yet, add it to the struct with a doc comment naming the method version that reads it.
2. Backfill every shipped table constant (and the mock tables under version/mocks/) with the old value, so released protocol versions keep their behaviour. The compiler forces this step.
3. Add the next table constant for the unreleased protocol version with the new value, and point that version's PLATFORM_V* at it. If the unreleased version already introduced a new table constant, edit that one in place instead.
4. Make the method read the field through platform_version. The method keeps its version number: shipped versions read their old value from their own table, so their behaviour is unchanged.

Do not create a vN method module whose entire body returns the new constant. That hides a protocol parameter in an implementation file, which is the situation the tables exist to prevent, and it leaves a dead module behind every time the number moves. A new method version is warranted only when the logic changes. daily_withdrawal_limit in rs-dpp is the reference case: v0 derives the limit from the current total credits, v2 reads daily_withdrawal_limit_percent from SystemLimits. Raising the percentage later is a SYSTEM_LIMITS_V5, not a v3.

How Subsystem Version Constants Compose

Each subsystem version constant (like DRIVE_VERSION_V1) is assembled from smaller constants:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/drive_versions/v1.rs

pub const DRIVE_VERSION_V1: DriveVersion = DriveVersion {
    structure: DRIVE_STRUCTURE_V1,
    methods: DriveMethodVersions {
        initialization: DriveInitializationMethodVersions {
            create_initial_state_structure: 0,
        },
        credit_pools: CREDIT_POOL_METHOD_VERSIONS_V1,
        protocol_upgrade: DriveProtocolUpgradeVersions {
            clear_version_information: 0,
            fetch_versions_with_counter: 0,
            // ...
        },
        balances: DriveBalancesMethodVersions {
            add_to_system_credits: 0,
            remove_from_system_credits: 0,
            calculate_total_credits_balance: 0,
            // ...
        },
        contract: DRIVE_CONTRACT_METHOD_VERSIONS_V1,
        // ...
    },
    grove_methods: DRIVE_GROVE_METHOD_VERSIONS_V1,
    grove_version: GROVE_V1,
};
}

Notice the mix of inline construction and named constants. Small structs like DriveProtocolUpgradeVersions are often written inline because all their fields are 0 in every version. Larger, frequently-changing structs like DRIVE_CONTRACT_METHOD_VERSIONS_V1 get their own named constant so they can be reused or overridden in later versions.

When DRIVE_VERSION_V9 (used in PLATFORM_V14) needs new document method versions, it references DRIVE_DOCUMENT_METHOD_VERSIONS_V4 where V8 referenced V3, and annotates the slot:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/drive_versions/v9.rs

pub const DRIVE_VERSION_V9: DriveVersion = DriveVersion {
    structure: DRIVE_STRUCTURE_V1,
    methods: DriveMethodVersions {
        // ...
        document: DRIVE_DOCUMENT_METHOD_VERSIONS_V4, // changed in v9: v2 index walkers + v1 update walker
        contract: DRIVE_CONTRACT_METHOD_VERSIONS_V3, // changed in v8: count-tree-aware contract-insertion cost estimation
        // ...
        verify: DRIVE_VERIFY_METHOD_VERSIONS_V2, // changed in v8: compacted address-balance proof envelope
        identity: DRIVE_IDENTITY_METHOD_VERSIONS_V2, // changed in v9: v1 withdrawal-by-transaction-index query builder
        // ...
    },
    grove_methods: DRIVE_GROVE_METHOD_VERSIONS_V1,
    // changed in v9: GROVE_V4 activates the indexed-tree batch cleanup
    grove_version: GROVE_V4,
};
}

The unchanged parts reference the same constants they always did. Only the parts that actually changed get new constants. grove_version is how GroveDB behaviour is versioned from Platform's side: a new DRIVE_VERSION_V* points at a new GROVE_V*, and every GroveDB call receives it.

Two ways to write a new table constant

Older table files are full copies of the previous version with the changed slots edited. Newer ones use struct update syntax, so that the file is the diff:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v2.rs

/// Differs from v1 in two slots.
/// `document_query_helpers.compute_aggregate_mode_and_check_limit` is 2
/// rather than 0: the ranked and boolean-`HAVING` routing gate. ...
pub const DRIVE_ABCI_QUERY_VERSIONS_V2: DriveAbciQueryVersions = DriveAbciQueryVersions {
    document_query_helpers: DriveAbciDocumentQueryHelperVersions {
        compute_aggregate_mode_and_check_limit: 2,
    },
    data_contract_query_helpers: DriveAbciDataContractQueryHelperVersions {
        latest_versions_read: 1,
    },
    ..DRIVE_ABCI_QUERY_VERSIONS_V1
};
}

It nests, so one changed leaf deep in a table still reads as one line:

#![allow(unused)]
fn main() {
// packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v5.rs

pub const DPP_VALIDATION_VERSIONS_V5: DPPValidationVersions = DPPValidationVersions {
    document_type: DocumentTypeValidationVersions {
        validate_update: 1,
        ..DPP_VALIDATION_VERSIONS_V4.document_type
    },
    ..DPP_VALIDATION_VERSIONS_V4
};
}

Use the struct update form for new table constants. Either way, the doc comment on the constant names the slots that differ from the previous table and why, in the same spirit as the // changed: comments on PLATFORM_V*.

When to create a new table constant

Table constants mark the boundaries between released protocol versions. Create DRIVE_ABCI_QUERY_VERSIONS_V4 when the constant you would otherwise edit is referenced by a released PLATFORM_V*. If the unreleased protocol version already introduced a new constant for that table, a second feature landing in the same protocol version amends it in place. Otherwise the crate accumulates table versions that no protocol version references, and the numbering stops saying anything about what shipped when.

The File Layout

The version structs follow a consistent directory layout in packages/rs-platform-version/src/version/:

version/
  mod.rs                        # ProtocolVersion type alias, LATEST_VERSION, module declarations
  protocol_version.rs           # PlatformVersion struct, PLATFORM_VERSIONS array, get()
  consensus_versions.rs         # ConsensusVersions (Tenderdash consensus version)
  feature_initial_protocol_versions.rs  # first protocol version of whole new transition kinds
  v1.rs .. v14.rs               # PLATFORM_V* snapshot constants, one per protocol version
  drive_versions/
    mod.rs                      # DriveVersion, DriveMethodVersions, etc.
    v1.rs .. v9.rs              # DRIVE_VERSION_V* constants
    drive_grove_method_versions/
      mod.rs                    # DriveGroveMethodVersions struct
      v1.rs                     # DRIVE_GROVE_METHOD_VERSIONS_V1
    drive_contract_method_versions/
      mod.rs                    # DriveContractMethodVersions struct
      v1.rs .. v3.rs            # versioned constants
    drive_document_method_versions/
      mod.rs
      v1.rs .. v4.rs
    drive_verify_method_versions/
      mod.rs
      v1.rs, v2.rs
    ...
  drive_abci_versions/
    mod.rs                      # DriveAbciVersion struct
    drive_abci_method_versions/
      mod.rs                    # DriveAbciMethodVersions and sub-structs
      v1.rs .. v10.rs           # versioned constants
    drive_abci_validation_versions/
      mod.rs                    # DriveAbciValidationVersions, PenaltyAmounts, validation constants
      v1.rs .. v10.rs
    drive_abci_query_versions/
      mod.rs
      v0.rs .. v2.rs
    drive_abci_withdrawal_constants/
      mod.rs                    # DriveAbciWithdrawalConstants (parameters, not method versions)
      v1.rs .. v3.rs
    drive_abci_structure_versions/      v1.rs
    drive_abci_checkpoint_parameters/   v1.rs
  dpp_versions/
    mod.rs                      # DPPVersion struct
    dpp_contract_versions/
      mod.rs                    # DPPContractVersions struct
      v1.rs .. v6.rs
    dpp_validation_versions/
      mod.rs
      v1.rs .. v5.rs
    ...
  fee/
    mod.rs                      # FeeVersion struct, FEE_VERSIONS
    v1.rs, v2.rs                # FEE_VERSION* schedules
    storage/, signature/, processing/, ...   # per-group tables, each with its own v*.rs
  system_limits/
    mod.rs                      # SystemLimits struct
    v1.rs .. v4.rs
  system_data_contract_versions/
    mod.rs
    v1.rs .. v3.rs
  mocks/
    v2_test.rs, v3_test.rs      # TEST_PLATFORM_V* behind the mock-versions feature

The pattern is: mod.rs defines the struct, and v*.rs files define the concrete constants. The struct definition is the schema. The version files are the data. Note that each table's v* numbering is its own: DRIVE_VERSION_V9 is what PLATFORM_V14 uses, and SYSTEM_LIMITS_V4 likewise. The number says how many times that table has changed, not which protocol version it belongs to.

Rules

Do:

• When adding a new method to Drive, DPP, or Drive ABCI, add a corresponding FeatureVersion field to the appropriate version struct. Then set its value in every v*.rs constant -- the compiler will force you.
• Use OptionalFeatureVersion for features that are being introduced in a non-initial protocol version. Set them to None in earlier versions and Some(0) in the version that introduces the feature. Use an Option field the same way for a parameter that did not exist before some version.
• Declare every protocol parameter that might change (limits, penalties, retention windows, fee rates) as a table field and read it through platform_version. Change a number by adding a table version, not a method version.
• Write new table constants with struct update syntax (..PREVIOUS) and a doc comment naming the slots that differ and why.
• Group related methods into their own sub-struct when the parent struct grows too large. Follow the existing naming pattern: Drive<Category>MethodVersions.

Do not:

• Never use a raw u16 where you mean FeatureVersion. The type alias exists for readability and future-proofing -- if we ever need to change the underlying type, the alias is the single point of change.
• Never put runtime-computed values into a version struct. Every field must be a compile-time constant. This is what makes the snapshot deterministic.
• Never reuse a version constant with different semantics. If DRIVE_CONTRACT_METHOD_VERSIONS_V1 means something, creating a V2 that changes one field is correct. Silently modifying V1 is not -- it would change the behavior of every platform version that references it.
• Never create a new table constant for a second change landing in the same unreleased protocol version. Table versions mark released boundaries; amend the unreleased version's own constant in place.
• Never leave a const in an implementation file that a future protocol version might want to change. Move it to the tables the first time it is touched.

Versioned Dispatch

The Problem: Running the Right Code

The previous two chapters explained what gets versioned (every method in the platform) and how version numbers are stored (nested structs inside an immutable PlatformVersion snapshot). This chapter covers the most important part: how those version numbers actually select which code runs.

The core idea is simple. Every versioned function has a dispatch method that reads a FeatureVersion value and calls the corresponding implementation. But the way this dispatch is organized across files, the error handling conventions, and the step-by-step process of adding a new version -- these are the details that make the pattern work at scale.

The Canonical Match Pattern

Here is the most common pattern in the codebase. This is from packages/rs-drive/src/util/grove_operations/grove_get_raw/mod.rs:

#![allow(unused)]
fn main() {
impl Drive {
    pub fn grove_get_raw<B: AsRef<[u8]>>(
        &self,
        path: SubtreePath<'_, B>,
        key: &[u8],
        direct_query_type: DirectQueryType,
        transaction: TransactionArg,
        drive_operations: &mut Vec<LowLevelDriveOperation>,
        drive_version: &DriveVersion,
    ) -> Result<Option<Element>, Error> {
        match drive_version.grove_methods.basic.grove_get_raw {
            0 => self.grove_get_raw_v0(
                path,
                key,
                direct_query_type,
                transaction,
                drive_operations,
                drive_version,
            ),
            version => Err(Error::Drive(DriveError::UnknownVersionMismatch {
                method: "grove_get_raw".to_string(),
                known_versions: vec![0],
                received: version,
            })),
        }
    }
}
}

Let us break down what is happening:

1. The public method (grove_get_raw) is the entry point. It takes all the business parameters plus a version reference (drive_version: &DriveVersion).

2. The version lookup reads the specific FeatureVersion for this method: drive_version.grove_methods.basic.grove_get_raw. This resolves to a u16.

3. The match dispatches to the right implementation. Version 0 calls grove_get_raw_v0. The catch-all arm (version =>) returns an error.

4. The error (UnknownVersionMismatch) includes the method name, the list of known versions, and the version that was actually received. This makes debugging version mismatches trivial.

This pattern appears hundreds of times across the codebase. It is the fundamental building block of versioned execution.

Multiple Versions

When a method has been revised, the match grows. Here is update_contract from packages/rs-drive/src/drive/contract/update/update_contract/mod.rs:

#![allow(unused)]
fn main() {
impl Drive {
    pub fn update_contract(
        &self,
        contract: &DataContract,
        block_info: BlockInfo,
        apply: bool,
        transaction: TransactionArg,
        platform_version: &PlatformVersion,
        previous_fee_versions: Option<&CachedEpochIndexFeeVersions>,
    ) -> Result<FeeResult, Error> {
        match platform_version
            .drive
            .methods
            .contract
            .update
            .update_contract
        {
            0 => self.update_contract_v0(
                contract, block_info, apply,
                transaction, platform_version, previous_fee_versions,
            ),
            1 => self.update_contract_v1(
                contract, block_info, apply,
                transaction, platform_version, previous_fee_versions,
            ),
            version => Err(Error::Drive(DriveError::UnknownVersionMismatch {
                method: "update_contract".to_string(),
                known_versions: vec![0, 1],
                received: version,
            })),
        }
    }
}
}

The structure is identical. The only differences are: there are now two known versions (0 and 1), and the known_versions vector in the error arm lists both. When a node running protocol version 1 processes a block, the version number is 0 and update_contract_v0 runs. When the network upgrades and the version number becomes 1, update_contract_v1 runs instead.

Both v0 and v1 implementations coexist in the binary. Old code is never deleted (at least not until a version is permanently retired from the network). This is critical for replaying historical blocks -- a node syncing from genesis needs to execute v0 for early blocks and v1 for later ones.

OptionalFeatureVersion Dispatch

For features introduced after the initial protocol version, the dispatch handles a None case:

#![allow(unused)]
fn main() {
// From identity_create/mod.rs

match platform_version
    .drive_abci
    .validation_and_processing
    .state_transitions
    .identity_create_state_transition
    .basic_structure
{
    Some(0) => {
        self.validate_basic_structure_v0(platform_version)
    }
    Some(version) => Err(Error::Execution(
        ExecutionError::UnknownVersionMismatch {
            method: "identity create transition: validate_basic_structure"
                .to_string(),
            known_versions: vec![0],
            received: version,
        }
    )),
    None => Err(Error::Execution(
        ExecutionError::VersionNotActive {
            method: "identity create transition: validate_basic_structure"
                .to_string(),
            known_versions: vec![0],
        }
    )),
}
}

Three arms instead of two:

• Some(0) -- the feature exists, use v0.
• Some(version) -- the feature exists but the version is unrecognized.
• None -- the feature does not exist in this protocol version.

The VersionNotActive error is different from UnknownVersionMismatch. It means "this feature is legitimately not available," not "something went wrong." This distinction matters for callers that need to handle graceful degradation.

The Directory Convention

Versioned methods follow a strict directory layout. Let us use grove_get_raw as the example:

packages/rs-drive/src/util/grove_operations/
  grove_get_raw/
    mod.rs          # dispatch method (the match statement)
    v0/
      mod.rs        # grove_get_raw_v0 implementation

The dispatch method lives in grove_get_raw/mod.rs. Each implementation version gets its own subdirectory: v0/mod.rs, v1/mod.rs, etc. The dispatch file declares the version modules:

#![allow(unused)]
fn main() {
// grove_get_raw/mod.rs
mod v0;
}

And each version module provides the actual implementation as a method on Drive:

#![allow(unused)]
fn main() {
// grove_get_raw/v0/mod.rs

impl Drive {
    pub(super) fn grove_get_raw_v0<B: AsRef<[u8]>>(
        &self,
        path: SubtreePath<'_, B>,
        key: &[u8],
        direct_query_type: DirectQueryType,
        transaction: TransactionArg,
        drive_operations: &mut Vec<LowLevelDriveOperation>,
        drive_version: &DriveVersion,
    ) -> Result<Option<Element>, Error> {
        // actual implementation
        match direct_query_type {
            DirectQueryType::StatelessDirectQuery { /* ... */ } => {
                // estimate costs
            }
            DirectQueryType::StatefulDirectQuery => {
                let CostContext { value, cost } =
                    self.grove.get_raw(path, key, transaction,
                                       &drive_version.grove_version);
                drive_operations.push(CalculatedCostOperation(cost));
                Ok(Some(value.map_err(Error::from)?))
            }
        }
    }
}
}

Notice the visibility: pub(super). The v0 function is only visible to its parent module (the dispatch file). External code calls the public dispatch method, never the versioned implementation directly.

The layout is the versioning contract made physical, and three rules follow from it:

• One directory per generation. A behaviour change to a versioned method is a new v1/ (or v2/, ...) directory with its own mod.rs, plus a new match arm. An edit inside a shipped v0/ is allowed only when it cannot modify consensus at any protocol version that selects v0/, because the code it adds is unreachable there by construction or its output is identical; the edited lines say why, and the pull request description carries an "In-place changes to shipped generations" section (see the coding conventions). An if platform_version.protocol_version >= 14 inside v0/ is not that: it is a runtime check the reader has to trust, so it gets a generation.
• Inside a generation, a capability is a constant fact, not a check. If v1 admits a new keyword, v1 admits it unconditionally (Index::try_from_value_map(map, true)). The decision of whether the keyword is allowed was made by the table that selected v1. Old generations cannot reach the new path at all, so there is nothing for them to check.
• Start the new generation as a copy of the old one. Duplicate v0/ into v1/, rename the function, make the change, and move the tests that exercise the new behaviour across. Duplication between generations is the accepted cost; a shared helper with a flag is the thing it replaces.

When new behaviour lives in a helper reached from several generations (a value walker, a property-reference resolver), the helper itself becomes a versioned method: an OptionalFeatureVersion slot in the tables (None for versions that predate the feature, Some(0) to dispatch to _v0), and the helper takes &PlatformVersion. A bool on a shared context struct is the wrong shape, because it moves the version decision from the tables to whoever set the flag. Per-generation grammar constants may live on a generation-owned struct; feature gates reachable from more than one generation may not.

Tests live with the generation they test: a #[cfg(test)] mod tests at the bottom of vN/mod.rs, or vN/tests/ when it grows. The dispatcher's mod.rs may carry end-to-end tests that need every generation.

For state transitions in Drive ABCI, the same pattern applies but with trait implementations:

packages/rs-drive-abci/src/execution/validation/state_transition/
  state_transitions/
    identity_create/
      mod.rs                  # dispatch traits and match statements
      basic_structure/
        mod.rs                # just declares v0
        v0/
          mod.rs              # BasicStructureValidationV0 implementation
      advanced_structure/
        mod.rs
        v0/
          mod.rs
      state/
        mod.rs
        v0/
          mod.rs

The Error Types

There are two UnknownVersionMismatch error variants in the codebase -- one for Drive and one for Drive ABCI -- but they have the same shape:

#![allow(unused)]
fn main() {
// packages/rs-drive/src/error/drive.rs

#[derive(Debug, thiserror::Error)]
pub enum DriveError {
    #[error("drive unknown version on {method}, received: {received}")]
    UnknownVersionMismatch {
        method: String,
        known_versions: Vec<FeatureVersion>,
        received: FeatureVersion,
    },

    #[error("{method} not active for drive version")]
    VersionNotActive {
        method: String,
        known_versions: Vec<FeatureVersion>,
    },
    // ...
}
}

#![allow(unused)]
fn main() {
// packages/rs-drive-abci/src/error/execution.rs

#[derive(Debug, thiserror::Error)]
pub enum ExecutionError {
    #[error("platform unknown version on {method}, received: {received}")]
    UnknownVersionMismatch {
        method: String,
        known_versions: Vec<FeatureVersion>,
        received: FeatureVersion,
    },

    #[error("{method} not active for drive version")]
    VersionNotActive {
        method: String,
        known_versions: Vec<FeatureVersion>,
    },
    // ...
}
}

Both carry three pieces of information:

• method: A human-readable name identifying which dispatch failed.
• known_versions: The versions this binary knows how to handle.
• received: The version number that was actually in the platform version.

This makes the error message self-diagnosing. If you see "drive unknown version on update_contract, received: 2, known versions: [0, 1]", you immediately know that the binary is too old to handle the active protocol version.

How to Add a New Version: Step by Step

Let us walk through the exact steps to add a v1 implementation of a method that currently only has v0. We will use a fictional example: my_grove_operation.

Step 1: Write the new implementation

Create the v1 module:

my_grove_operation/
  mod.rs          # existing dispatch
  v0/
    mod.rs        # existing v0
  v1/
    mod.rs        # NEW: v1 implementation

#![allow(unused)]
fn main() {
// my_grove_operation/v1/mod.rs

impl Drive {
    pub(super) fn my_grove_operation_v1(
        &self,
        // same signature as v0, or possibly different
    ) -> Result<SomeResult, Error> {
        // new implementation with bug fix or feature
    }
}
}

Step 2: Update the dispatch

In my_grove_operation/mod.rs, declare the new module and add the match arm:

#![allow(unused)]
fn main() {
mod v0;
mod v1;  // NEW

impl Drive {
    pub fn my_grove_operation(
        &self,
        // ...
        drive_version: &DriveVersion,
    ) -> Result<SomeResult, Error> {
        match drive_version.grove_methods.basic.my_grove_operation {
            0 => self.my_grove_operation_v0(/* ... */),
            1 => self.my_grove_operation_v1(/* ... */),  // NEW
            version => Err(Error::Drive(DriveError::UnknownVersionMismatch {
                method: "my_grove_operation".to_string(),
                known_versions: vec![0, 1],  // UPDATED
                received: version,
            })),
        }
    }
}
}

Step 3: Bump the slot in the unreleased protocol version's tables

The new arm is dead until a table selects it. Which table you edit depends on whether the unreleased protocol version already owns one.

At the time of writing the latest released version is 13 and version 14 is in development. PLATFORM_V14 already references DRIVE_VERSION_V9, which was created for version 14, so a version-14 change edits v9.rs in place:

#![allow(unused)]
fn main() {
// drive_versions/v9.rs  (existing file, amended)

pub const DRIVE_VERSION_V9: DriveVersion = DriveVersion {
    // ...
    grove_methods: DRIVE_GROVE_METHOD_VERSIONS_V2, // changed in v9: my_grove_operation v1
    // ...
};
}

DRIVE_GROVE_METHOD_VERSIONS_V1 is referenced by released versions, so it cannot be edited. Create the next one with struct update syntax:

#![allow(unused)]
fn main() {
// drive_grove_method_versions/v2.rs  (NEW file)

/// Differs from v1 in one slot: `basic.my_grove_operation` is 1 rather
/// than 0. v1 of the operation <what changed and why>.
pub const DRIVE_GROVE_METHOD_VERSIONS_V2: DriveGroveMethodVersions =
    DriveGroveMethodVersions {
        basic: DriveGroveBasicMethodVersions {
            my_grove_operation: 1,
            ..DRIVE_GROVE_METHOD_VERSIONS_V1.basic
        },
        ..DRIVE_GROVE_METHOD_VERSIONS_V1
    };
}

Had DRIVE_VERSION_V9 also been shared with a released version, the same logic would apply one level up: a new drive_versions/v10.rs pointing at DRIVE_GROVE_METHOD_VERSIONS_V2, and PLATFORM_V14 pointing at DRIVE_VERSION_V10. The rule at every level is the same: edit in place if the constant belongs only to the unreleased version; create the next constant if a released version references it.

Step 4: Annotate the platform version file

Add or extend the // changed: comment on the affected slot of the unreleased PLATFORM_V*, and add a numbered item to the file's doc comment describing the consensus change. That doc comment is the release changelog for the protocol version.

Step 5: If this is the first change after a release, create the version

Only the first consensus change after a release creates a new protocol version. If version 14 had already shipped, the change above would start version 15:

#![allow(unused)]
fn main() {
// version/v15.rs  (NEW file, copied from v14.rs)

pub const PROTOCOL_VERSION_15: ProtocolVersion = 15;

/// v15 hosts one consensus change so far:
///
/// 1. **my_grove_operation v1**: ...
pub const PLATFORM_V15: PlatformVersion = PlatformVersion {
    protocol_version: PROTOCOL_VERSION_15,
    drive: DRIVE_VERSION_V10, // changed: my_grove_operation v1
    // ... everything else unchanged from V14
};
}

Then register it:

#![allow(unused)]
fn main() {
// version/mod.rs
pub mod v15;
pub const LATEST_VERSION: ProtocolVersion = PROTOCOL_VERSION_15;

// version/protocol_version.rs
pub const PLATFORM_VERSIONS: &[PlatformVersion] = &[
    PLATFORM_V1,
    // ...
    PLATFORM_V14,
    PLATFORM_V15,  // NEW
];

pub const LATEST_PLATFORM_VERSION: &PlatformVersion = &PLATFORM_V15;
}

A test in system_limits/mod.rs asserts that PLATFORM_VERSIONS.len() equals LATEST_VERSION, so a version that is declared but not registered fails the test run rather than silently resolving to the previous one. Every subsequent change destined for version 15 amends v15.rs and the constants it introduced, as in step 3.

Step 6: Write tests

Test both generations through the dispatcher, and put each test with the generation it exercises:

#![allow(unused)]
fn main() {
// my_grove_operation/v1/mod.rs
#[cfg(test)]
mod tests {
    #[test]
    fn should_apply_new_behaviour() {
        let platform_version = PlatformVersion::latest();
        // ... drive.my_grove_operation(..., &platform_version.drive)
    }
}

// my_grove_operation/v0/mod.rs
#[cfg(test)]
mod tests {
    #[test]
    fn should_keep_old_behaviour() {
        // frozen generation: pin the last protocol version that selected it
        let platform_version = PlatformVersion::get(13).expect("known version");
        // ...
    }
}
}

The current generation tests against PlatformVersion::latest() so it keeps tracking the tip; the moment v1 is introduced is the moment v0's tests get pinned to an explicit version. Do not write a test that merely asserts the table slot's value (assert_eq!(PLATFORM_V14.drive.grove_methods.basic.my_grove_operation, 1)); it restates the literal and cannot fail without the edit being deliberate. A behaviour test that runs both versions through the dispatcher pins the gate 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.

Passing Version References

A subtle but important convention is which version reference a function receives. There are three patterns:

&PlatformVersion -- used by high-level code that might need any part of the version tree. State transition processing, block execution, and similar entry points take this.

&DriveVersion -- used by mid-level Drive code that only needs drive- specific versions. The caller extracts &platform_version.drive once.

&GroveVersion -- used by the lowest-level GroveDB operations. Extracted from &drive_version.grove_version.

This layering avoids passing the entire PlatformVersion into the deepest functions. It also makes the dependency explicit: a function taking &DriveVersion cannot accidentally use a DPP version number.

The Version Flow in Block Processing

Here is how the version flows through a real execution path:

Block arrives from Tenderdash
    |
    v
PlatformState has the current protocol_version (e.g., 14)
    |
    v
PlatformVersion::get(14) -> &PLATFORM_V14
    |
    v
process_raw_state_transitions(&platform_version)
    |
    v
validate_state_for_identity_create_transition()
    reads: platform_version.drive_abci.validation_and_processing
           .state_transitions.identity_create_state_transition.state
    dispatches to: validate_state_v0()
    |
    v
drive.update_contract(&platform_version)
    reads: platform_version.drive.methods.contract.update.update_contract
    dispatches to: update_contract_v1()
    |
    v
drive.grove_get_raw(&platform_version.drive)
    reads: drive_version.grove_methods.basic.grove_get_raw
    dispatches to: grove_get_raw_v0()

The protocol version number enters at the top and the correct implementation is selected at every level. No function chooses its own version -- it is always determined by the version reference passed from above.

The First Block of a New Protocol Version

The version flow above assumes the protocol version is already known. The switch itself happens in run_block_proposal (packages/rs-drive-abci/src/execution/engine/run_block_proposal/mod.rs). On the first block of an epoch, if the protocol version the network locked in during the previous epoch differs from the one in consensus, the block runs under the new version:

#![allow(unused)]
fn main() {
// abbreviated
let block_platform_version = if epoch_info.is_epoch_change_but_not_genesis()
    && platform_state.next_epoch_protocol_version()
        != platform_state.current_protocol_version_in_consensus()
{
    let next_protocol_version = platform_state.next_epoch_protocol_version();

    // We should panic if this node is not supported a new protocol version
    let Ok(next_platform_version) = PlatformVersion::get(next_protocol_version) else {
        panic!("Failed to upgrade the network protocol version {next_protocol_version}. ...");
    };

    let old_protocol_version = block_platform_state.current_protocol_version_in_consensus();
    block_platform_state.set_current_protocol_version_in_consensus(next_protocol_version);

    // This is for events like adding stuff to the root tree, or making structural changes/fixes
    self.perform_events_on_first_block_of_protocol_change(
        platform_state, &block_info, transaction, old_protocol_version, next_platform_version,
    )?;

    next_platform_version
} else {
    last_committed_platform_version
};
}

Three things to take from this:

• Epoch info is computed with the old version, before the switch. The new version applies to everything after it.
• A binary that does not know the new version panics with an upgrade message. That is deliberate: a node that cannot run the agreed protocol must stop rather than produce a divergent state root.
• perform_events_on_first_block_of_protocol_change is where state migrations live. Anything that needs to be done to the tree once for a new protocol version, before its first state transition runs, goes here: creating a new root-tree subtree, rewriting a system contract, back-filling a sum tree.

The migration hook is itself a versioned method (drive_abci.methods.protocol_upgrade.perform_events_on_first_block_of_protocol_change: None in the earliest method tables, Some(0) once the first migration existed, Some(1) in the two most recent tables). Its v0 is a ladder of guarded rungs, one per protocol version that needed a migration:

#![allow(unused)]
fn main() {
// packages/rs-drive-abci/src/execution/platform_events/protocol_upgrade/
//   perform_events_on_first_block_of_protocol_change/v0/mod.rs

if previous_protocol_version < 4 && platform_version.protocol_version >= 4 {
    self.transition_to_version_4(platform_state, block_info, transaction, platform_version)?;
}
if previous_protocol_version < 6 && platform_version.protocol_version >= 6 {
    self.transition_to_version_6(block_info, transaction, platform_version)?;
}
// ... 8, 9, 11, 12, 13 ...
if previous_protocol_version < 14 && platform_version.protocol_version >= 14 {
    self.transition_to_version_14(block_info, transaction, platform_version)?;
}
}

The guard shape matters. A node can cross more than one protocol version in a single switch (a network that skipped a version, or a devnet started at an old one), and the previous < N && new >= N form runs every rung it crossed, in order. A rung written as new == N would be skipped by such a node, and its state tree would be missing a subtree every other node has.

v1 exists because the migrations write system contracts through a path that bypasses the drive operation batch's cache invalidation; it runs the same ladder and then refreshes the cached contract definitions so that a validator with a warm cache and one with a cold cache serialize the same bytes. Read its doc comment before touching the hook: it is a worked example of a consensus-critical cache bug.

To add a migration for a new protocol version: add a rung at the bottom of the ladder in the current generation of the hook, guarded by that version, with a transition_to_version_N helper next to the others. A failure in a rung returns Err from block processing on every node, so a rung either succeeds deterministically or halts the network. The version 8 rung's or_else that logs and continues is the exception for a migration that does not touch the state structure, not a pattern to copy.

Whole new state transition kinds are gated separately, by the is_allowed stage of the validation pipeline reading the constants in feature_initial_protocol_versions.rs (ADDRESS_FUNDS_INITIAL_PROTOCOL_VERSION = 11, SHIELDED_POOL_INITIAL_PROTOCOL_VERSION = 12). A transition submitted before its initial version is rejected with a StateTransitionNotActiveError rather than an unknown-version dispatch error.

Genesis content is the other place a protocol_version comparison is the intended shape. create_genesis_state runs once per chain, under the protocol version the chain is born at. Mainnet and testnet were born at protocol version 1 and replay generation 0, which stays frozen. Generation 1 is selected only for chains born at protocol version 9 or later, and every such chain is a devnet, a local network or a test suite that is created again for each release, so no live node reproduces its genesis. When a protocol version adds a system contract or other genesis content, it goes into create_genesis_state_v1 behind if platform_version.protocol_version >= N (document history at 13, app connect and moderation charters at 14), and a chain that already exists gets the same content from its transition_to_version_N rung. A new genesis generation would add code for no replay benefit. Never edit generation 0.

The Drive helpers that build the initial state structure follow the same rule for the same reason: they run once, at chain creation, under the chain's initial protocol version, and a chain that already exists gets the same trees from its upgrade rung. add_initial_withdrawal_state_structure_operations adds the withdrawal sum trees behind >= 4, which replaying mainnet's genesis at protocol version 1 does not take. The withdrawal limit trees of protocol version 14 are not in that batch: genesis and transition_to_version_14 both add them one insert at a time through Drive::insert_withdrawal_limit_trees, so both build the withdrawals Merk in the same shape.

Rules

Do:

• Always include the method name in the UnknownVersionMismatch error. Use the same string format you see in existing code: the plain method name for Drive methods ("grove_get_raw"), and a descriptive path for ABCI methods ("identity create transition: validate_basic_structure").
• Keep the known_versions vector in the error arm up to date. When you add version 2, the vector should be vec![0, 1, 2].
• Make versioned implementation methods pub(super) -- visible to the dispatch module but not to external code.
• Put every new generation in its own vN/ directory, started as a copy of the previous one, with its tests inside it.
• Bump the slot in the unreleased protocol version's tables only: amend a constant that only the unreleased version references, create the next constant when a released version references it.
• Test the current generation against PlatformVersion::latest() and pin the previous generation's tests to the last protocol version that selected it.
• Put one-time state changes a protocol version needs in a guarded rung of perform_events_on_first_block_of_protocol_change.

Do not:

• Never call a versioned implementation directly (e.g., grove_get_raw_v0). Always go through the dispatch method. Direct calls bypass version control and break determinism.
• Never add a version to the match without also adding the corresponding FeatureVersion field value in the version constants. The dispatch will never be reached if no platform version sets that number.
• Never use _ => as the catch-all arm in a version dispatch. Always use version => so the variable is available for the error message. And never silently ignore unknown versions -- always return an error.
• Never modify a shipped generation, not even by threading a parameter or a version check through it. If v0 takes five parameters and v1 needs six, that is fine -- v0 keeps its original signature and body forever.
• Never gate new behaviour with a bool on a shared context struct. A helper reached from several generations gets an OptionalFeatureVersion slot and takes &PlatformVersion.
• Never write a test that only asserts a table slot's value. Test the behaviour through the dispatcher on both sides of the gate.

The State Transition Lifecycle

Every change to Dash Platform -- creating an identity, registering a data contract, storing a document, casting a masternode vote -- follows the same fundamental pattern: a state transition. If you understand this one concept, you understand the heartbeat of the entire platform.

What Is a State Transition?

A state transition is the atomic unit of state change on Dash Platform. Think of the platform's state as a database. You cannot write to that database directly. Instead, you construct a state transition object that describes what you want to change, sign it with your private key, serialize it to bytes, and broadcast it to the network. Validators receive it, validate it through a multi-stage pipeline, and -- if everything checks out -- apply it to their copy of the state.

This is fundamentally different from a smart contract model. There is no arbitrary code execution. Every possible mutation is one of a fixed set of state transition types, each with its own validation rules hardcoded into the platform. The benefit is predictability: you can reason about fees, security, and correctness without worrying about Turing-complete execution.

The StateTransition Enum

At the Rust level, every state transition is a variant of a single enum. This is defined in packages/rs-dpp/src/state_transition/mod.rs:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Encode, Decode, PlatformSerialize,
         PlatformDeserialize, PlatformSignable, From, PartialEq)]
#[platform_serialize(unversioned)]
#[platform_serialize(limit = 100000)]
pub enum StateTransition {
    DataContractCreate(DataContractCreateTransition),
    DataContractUpdate(DataContractUpdateTransition),
    Batch(BatchTransition),
    IdentityCreate(IdentityCreateTransition),
    IdentityTopUp(IdentityTopUpTransition),
    IdentityCreditWithdrawal(IdentityCreditWithdrawalTransition),
    IdentityUpdate(IdentityUpdateTransition),
    IdentityCreditTransfer(IdentityCreditTransferTransition),
    MasternodeVote(MasternodeVoteTransition),
    IdentityCreditTransferToAddresses(IdentityCreditTransferToAddressesTransition),
    IdentityCreateFromAddresses(IdentityCreateFromAddressesTransition),
    IdentityTopUpFromAddresses(IdentityTopUpFromAddressesTransition),
    AddressFundsTransfer(AddressFundsTransferTransition),
    AddressFundingFromAssetLock(AddressFundingFromAssetLockTransition),
    AddressCreditWithdrawal(AddressCreditWithdrawalTransition),
    Shield(ShieldTransition),
    ShieldedTransfer(ShieldedTransferTransition),
    Unshield(UnshieldTransition),
    ShieldFromAssetLock(ShieldFromAssetLockTransition),
    ShieldedWithdrawal(ShieldedWithdrawalTransition),
    IdentityCreateFromShieldedPool(IdentityCreateFromShieldedPoolTransition),
    ShieldFromIdentity(ShieldFromIdentityTransition),
    IdentityTopUpFromShieldedPool(IdentityTopUpFromShieldedPoolTransition),
    IdentityKeyLimitsUpdate(IdentityKeyLimitsUpdateTransition),
}
}

Each variant wraps a dedicated struct. Notice the derive macros: Encode and Decode for bincode serialization, PlatformSerialize and PlatformDeserialize for the platform's own serialization layer, and PlatformSignable for generating the "signable bytes" that get signed.

These variants fall into natural groups:

Identity lifecycle:

• IdentityCreate -- Register a new identity (funded by an asset lock on the Dash core chain)
• IdentityTopUp -- Add credits to an existing identity (also asset-lock funded)
• IdentityUpdate -- Add or disable public keys on an identity
• IdentityCreditWithdrawal -- Withdraw credits back to the core chain
• IdentityCreditTransfer -- Transfer credits between identities
• IdentityKeyLimitsUpdate -- Raise the budget or extend the expiry of one of the identity's keys

Data contracts and documents:

• DataContractCreate -- Register a new data contract (schema)
• DataContractUpdate -- Update an existing data contract
• Batch -- Create, replace, delete, or transfer documents; mint, burn, transfer, or freeze tokens

Governance:

• MasternodeVote -- Cast a vote in a contested resource election

Address-based (newer):

• IdentityCreateFromAddresses, IdentityTopUpFromAddresses, AddressFundsTransfer, AddressFundingFromAssetLock, AddressCreditWithdrawal -- Operations that use platform addresses instead of (or in addition to) identity-based authentication

Shielded pool:

• Shield, ShieldedTransfer, Unshield, ShieldFromAssetLock, ShieldedWithdrawal, IdentityCreateFromShieldedPool, ShieldFromIdentity, IdentityTopUpFromShieldedPool -- Operations that move credits into, inside, and out of the shielded pool

Each variant has its own numeric discriminant, defined in packages/rs-dpp/src/state_transition/state_transition_types.rs:

#![allow(unused)]
fn main() {
#[repr(u8)]
pub enum StateTransitionType {
    DataContractCreate = 0,
    Batch = 1,
    IdentityCreate = 2,
    IdentityTopUp = 3,
    DataContractUpdate = 4,
    IdentityUpdate = 5,
    IdentityCreditWithdrawal = 6,
    IdentityCreditTransfer = 7,
    MasternodeVote = 8,
    IdentityCreditTransferToAddresses = 9,
    IdentityCreateFromAddresses = 10,
    IdentityTopUpFromAddresses = 11,
    AddressFundsTransfer = 12,
    AddressFundingFromAssetLock = 13,
    AddressCreditWithdrawal = 14,
    Shield = 15,
    ShieldedTransfer = 16,
    Unshield = 17,
    ShieldFromAssetLock = 18,
    ShieldedWithdrawal = 19,
    IdentityCreateFromShieldedPool = 20,
    ShieldFromIdentity = 21,
    IdentityTopUpFromShieldedPool = 22,
    IdentityKeyLimitsUpdate = 23,
}
}

This type tag is what allows the platform to deserialize a raw byte buffer into the correct variant. When bytes arrive over the wire, the first byte tells the deserializer which struct to decode into.

The Batch Transition: A Swiss Army Knife

The Batch variant deserves special attention because it is the most complex. A single BatchTransition can contain multiple sub-transitions, each operating on a different document or token. The sub-transitions include:

• Document operations: Create, Replace, Delete, Transfer, UpdatePrice, Purchase
• Token operations: Transfer, Mint, Burn, Freeze, Unfreeze, DestroyFrozenFunds, EmergencyAction, ConfigUpdate, Claim, DirectPurchase, SetPriceForDirectPurchase

This batching is important for atomicity: either all operations in the batch succeed or none of them do. It also means a single identity nonce covers the entire batch, preventing partial replay attacks.

Signatures and Authentication

State transitions carry cryptographic signatures that prove authorization. There are two fundamentally different authentication models:

Identity-signed transitions -- The majority of transition types. The signer is an identity that already exists on the platform. The transition carries a signature_public_key_id referencing a key in the identity's key set, plus a signature over the signable bytes.

Asset-lock transitions -- IdentityCreate and IdentityTopUp are special because the identity may not exist yet (or the transition does not require an identity signature). Instead, they carry an AssetLockProof that references a transaction on the Dash core chain. The signature proves ownership of the funds being locked.

Address-based transitions -- Newer transition types like IdentityCreateFromAddresses use platform address inputs with their own nonces and balances, rather than identity-based authentication.

The sign method on StateTransition handles this:

#![allow(unused)]
fn main() {
pub fn sign(
    &mut self,
    identity_public_key: &IdentityPublicKey,
    private_key: &[u8],
    bls: &impl BlsModule,
) -> Result<(), ProtocolError> { ... }
}

It first verifies that the key's purpose and security level are appropriate for this transition type, then signs the signable_bytes() with the private key. Supported key types are ECDSA_SECP256K1, ECDSA_HASH160, and BLS12_381.

The signable bytes are produced by the PlatformSignable derive macro. It serializes the transition with the signature field zeroed out, producing a deterministic byte sequence that both client and platform can independently compute.

Serialization

The platform uses bincode for wire serialization of state transitions, wrapped in the PlatformSerialize / PlatformDeserialize layer. This gives us:

• Compact binary encoding (no field names, no JSON overhead)
• Deterministic output (critical for signature verification)
• Size limits (#[platform_serialize(limit = 100000)] -- 100KB max)
• Version awareness through the #[platform_serialize(unversioned)] annotation

Deserialization includes version-range checks:

#![allow(unused)]
fn main() {
pub fn deserialize_from_bytes_in_version(
    bytes: &[u8],
    platform_version: &PlatformVersion,
) -> Result<Self, ProtocolError> {
    let state_transition = StateTransition::deserialize_from_bytes(bytes)?;
    let active_version_range = state_transition.active_version_range();
    if active_version_range.contains(&platform_version.protocol_version) {
        Ok(state_transition)
    } else {
        Err(ProtocolError::StateTransitionError(
            StateTransitionIsNotActiveError { ... },
        ))
    }
}
}

This ensures that a transition type introduced in protocol version 9 cannot be submitted to a node running protocol version 8.

The Full Journey

Here is the end-to-end lifecycle of a state transition, from a client's perspective all the way through to state application:

1. Client constructs the transition. Using the Rust SDK (rs-sdk), JavaScript SDK (js-dash-sdk), or any client library, the application builds a concrete transition struct -- for example, a DataContractCreateTransition containing the new contract's schema.

2. Client signs the transition. The client calls sign() or sign_external(), which computes signable bytes, signs them with the appropriate private key, and attaches the signature and key ID to the transition struct.

3. Client serializes and broadcasts. The signed StateTransition is serialized to bytes via serialize_to_bytes() and sent to the network through DAPI (the Decentralized API).

4. Platform receives the bytes in check_tx. Before a state transition enters the mempool, it goes through a lighter validation pass. The platform deserializes the bytes, checks the signature, verifies the identity has sufficient balance, and validates basic structure. This is a gatekeeper -- it rejects obviously invalid transitions cheaply.

5. Platform processes during process_proposal. When a block is proposed, each state transition goes through the full validation pipeline: is_allowed, signature verification, nonce validation, basic structure, balance checks, advanced structure, transform_into_action, and state validation. (We will cover this pipeline in detail in the next chapter.)

6. Platform applies the action. If validation succeeds, the resulting StateTransitionAction is converted into DriveOperations, which are converted into LowLevelDriveOperations, which are applied atomically to GroveDB. Fees are calculated and deducted. The state has changed.

7. Result is returned. The client receives confirmation (or rejection) through DAPI.

The Versioning Pattern

You will notice that almost every method on StateTransition dispatches through a version table. For example:

#![allow(unused)]
fn main() {
match platform_version
    .drive_abci
    .validation_and_processing
    .process_state_transition
{
    0 => v0::process_state_transition_v0(...),
    version => Err(Error::Execution(ExecutionError::UnknownVersionMismatch { ... })),
}
}

This is the protocol versioning pattern. Every behavior that could conceivably change between protocol versions is gated behind a version number looked up from PlatformVersion. This means a node running protocol version 9 and a node running protocol version 10 can both validate the same block correctly, each using its own version's logic. It is how the platform achieves hard-fork-free upgrades.

The call_method Macro

Since StateTransition is an enum with 15 variants, dispatching a method call to the inner type would require writing out a 15-arm match statement every time. The codebase solves this with a family of macros:

#![allow(unused)]
fn main() {
macro_rules! call_method {
    ($state_transition:expr, $method:ident) => {
        match $state_transition {
            StateTransition::DataContractCreate(st) => st.$method(),
            StateTransition::DataContractUpdate(st) => st.$method(),
            StateTransition::Batch(st) => st.$method(),
            // ... all 15 variants
        }
    };
}
}

There are several variants: call_method for universal methods, call_getter_method_identity_signed for methods that return Option (returning None for non-identity-signed transitions like IdentityCreate), and call_errorable_method_identity_signed for methods that return Result (returning an error for inapplicable variants).

Rules and Guidelines

Do:

• Always deserialize with deserialize_from_bytes_in_version in production code, to enforce version-range checks.
• Use signable_bytes() when computing what to sign or verify -- never serialize the full transition (which includes the signature itself).
• Check active_version_range() before processing a transition to ensure it is valid for the current protocol version.

Do not:

• Assume all transitions have signatures. IdentityCreateFromAddresses and AddressFundsTransfer return None from signature().
• Assume all transitions have an owner_id. Address-based transitions do not.
• Modify the StateTransitionType discriminant values -- they are part of the wire format and changing them would break all existing serialized data.
• Add new variants without also updating every call_method macro and every match statement in the validation pipeline.

The Validation Pipeline

When a state transition arrives at a Dash Platform node, it does not get applied immediately. It must survive a gauntlet of validation stages, each designed to catch a different category of error. Understanding this pipeline is essential to understanding how the platform maintains security, prevents abuse, and ensures deterministic state across all validators.

Two Entry Points: check_tx and process_proposal

State transitions enter the pipeline through two different doors, depending on when they are being validated.

check_tx runs when a transition first arrives at a node (before entering the mempool) and again when rechecking mempool contents. It performs a lighter validation: signature verification, basic structure, and balance checks. The goal is to filter out obvious garbage cheaply, without doing expensive state lookups.

A MasternodeVote is the exception. A block refuses a failed vote without charging anyone, and the proposer drops it from the block without a trace, so check_tx runs the vote's advanced structure and state validation as well. A vote that a block would refuse, such as a Lock vote on a contest without locking, is refused when it is broadcast, with its error.

This is implemented in packages/rs-drive-abci/src/execution/validation/state_transition/check_tx_verification/mod.rs:

#![allow(unused)]
fn main() {
pub(in crate::execution) fn state_transition_to_execution_event_for_check_tx<'a, C: CoreRPCLike>(
    platform: &'a PlatformRef<C>,
    state_transition: StateTransition,
    check_tx_level: CheckTxLevel,
    platform_version: &PlatformVersion,
) -> Result<ConsensusValidationResult<Option<ExecutionEvent<'a>>>, Error> { ... }
}

process_proposal (also called the "Validator" path) runs during block execution. This is the full pipeline. It is implemented in packages/rs-drive-abci/src/execution/validation/state_transition/processor/v0/mod.rs:

#![allow(unused)]
fn main() {
pub(super) fn process_state_transition_v0<'a, C: CoreRPCLike>(
    platform: &'a PlatformRef<C>,
    block_info: &BlockInfo,
    state_transition: StateTransition,
    transaction: TransactionArg,
    platform_version: &PlatformVersion,
) -> Result<ConsensusValidationResult<ExecutionEvent<'a>>, Error> { ... }
}

Let us walk through the full pipeline, stage by stage.

Stage 1: Is Allowed

Some state transition types are only available starting from a certain protocol version. For example, address-based transitions like IdentityCreateFromAddresses require protocol version 11 or higher. The first check asks: is this transition type even permitted on the current network?

#![allow(unused)]
fn main() {
if state_transition.has_is_allowed_validation()? {
    let result = state_transition.validate_is_allowed(platform_version)?;
    if !result.is_valid() {
        return Ok(ConsensusValidationResult::new_with_errors(result.errors));
    }
}
}

The trait is defined in packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/is_allowed.rs:

#![allow(unused)]
fn main() {
pub(crate) trait StateTransitionIsAllowedValidationV0 {
    fn has_is_allowed_validation(&self) -> Result<bool, Error>;
    fn validate_is_allowed(
        &self,
        platform_version: &PlatformVersion,
    ) -> Result<ConsensusValidationResult<()>, Error>;
}
}

Transitions available since protocol version 1, like DataContractCreate, IdentityCreate and Batch, skip this check entirely.

Stage 2: Identity Signature Verification

For identity-signed transitions (everything except IdentityCreate, IdentityTopUp, and the address-based types), the platform fetches the signer's identity from state and verifies the signature against one of its registered public keys.

#![allow(unused)]
fn main() {
let mut maybe_identity = if state_transition.uses_identity_in_state() {
    let result = if state_transition.validates_signature_based_on_identity_info() {
        state_transition.validate_identity_signed_state_transition(
            platform.drive,
            transaction,
            &mut state_transition_execution_context,
            platform_version,
        )
    } else {
        state_transition.retrieve_identity_info(...)
    }?;
    if !result.is_valid() {
        return Ok(ConsensusValidationResult::new_with_errors(result.errors));
    }
    Some(result.into_data()?)
} else {
    None
};
}

If the signature does not match, the transition is rejected without charging a fee. This is critical: if someone forges a transition with your identity ID but a wrong signature, you should not pay for their garbage.

Stage 3: Address Witness Validation

For address-based transitions, instead of identity signatures, the platform validates witnesses (proofs of ownership) for the input addresses:

#![allow(unused)]
fn main() {
if state_transition.has_address_witness_validation(platform_version)? {
    let result = state_transition.validate_address_witnesses(
        &mut state_transition_execution_context,
        platform_version,
    )?;
    if !result.is_valid() {
        return Ok(ConsensusValidationResult::new_with_errors(result.errors));
    }
}
}

Stage 4: Address Balances and Nonces

For transitions that use platform addresses as inputs, the platform verifies that each input address has sufficient balance and that the provided nonces are correct (preventing replay):

#![allow(unused)]
fn main() {
let remaining_address_balances =
    if state_transition.has_addresses_balances_and_nonces_validation() {
        let result = state_transition.validate_address_balances_and_nonces(
            platform.drive,
            &mut state_transition_execution_context,
            transaction,
            platform_version,
        )?;
        if !result.is_valid() {
            return Ok(ConsensusValidationResult::new_with_errors(result.errors));
        }
        Some(result.into_data()?)
    } else {
        None
    };
}

Stage 5: Identity Nonce Validation

Nonces prevent replay attacks. Each identity-signed transition carries a nonce that must be strictly greater than the last used nonce for that identity (or identity-contract pair). The platform checks this against the stored nonce in state.

#![allow(unused)]
fn main() {
if state_transition.has_identity_nonce_validation(platform_version)? {
    let result = state_transition.validate_identity_nonces(
        &platform.into(),
        platform.state.last_block_info(),
        transaction,
        &mut state_transition_execution_context,
        platform_version,
    )?;
    if !result.is_valid() {
        return Ok(ConsensusValidationResult::new_with_errors(result.errors));
    }
}
}

Identity create and identity top up skip this check -- they do not have nonces because the identity may not exist yet.

Stage 6: Basic Structure Validation

This stage checks that the transition's data is well-formed without looking at platform state. For example: are all required fields present? Are field values within allowed ranges? Is the data contract schema valid JSON Schema?

#![allow(unused)]
fn main() {
if state_transition.has_basic_structure_validation(platform_version) {
    let consensus_result = state_transition.validate_basic_structure(
        platform.config.network,
        platform_version,
    )?;
    if !consensus_result.is_valid() {
        return Ok(ConsensusValidationResult::new_with_errors(
            consensus_result.errors,
        ));
    }
}
}

The trait lives in processor/traits/basic_structure.rs:

#![allow(unused)]
fn main() {
pub(crate) trait StateTransitionBasicStructureValidationV0 {
    fn validate_basic_structure(
        &self,
        network_type: Network,
        platform_version: &PlatformVersion,
    ) -> Result<SimpleConsensusValidationResult, Error>;

    fn has_basic_structure_validation(&self, _platform_version: &PlatformVersion) -> bool {
        true
    }
}
}

MasternodeVote skips basic structure validation entirely. DataContractCreate and DataContractUpdate conditionally enable it based on the platform version.

Stage 7: Balance Pre-Check

Before doing expensive state validation, the platform checks that the identity has enough credits to plausibly pay for this transition. For credit transfers and withdrawals, this includes checking that the transfer amount plus estimated fees does not exceed the balance.

#![allow(unused)]
fn main() {
if state_transition.has_identity_minimum_balance_pre_check_validation() {
    let result = state_transition.validate_identity_minimum_balance_pre_check(
        identity, platform_version,
    )?;
    if !result.is_valid() {
        return Ok(ConsensusValidationResult::new_with_errors(result.errors));
    }
}
}

A MasternodeVote is paid by its vote poll's prefunded specialized balance, not by the voter, so its pre-check is on that pot: a vote on a poll whose pot does not exist, or holds less than the single vote cost, is refused unpaid with PrefundedSpecializedBalanceNotFoundError or PrefundedSpecializedBalanceInsufficientError.

Stage 8: Advanced Structure Validation (without State)

Some transitions need structural validation that goes beyond basic checks but does not require reading from platform state. For example, IdentityUpdate verifies that added public keys have valid signatures. DataContractCreate validates the contract schema more deeply.

#![allow(unused)]
fn main() {
if state_transition.has_advanced_structure_validation_without_state() {
    let consensus_result = state_transition.validate_advanced_structure(
        identity, &mut state_transition_execution_context, platform_version,
    )?;
    if !consensus_result.is_valid() {
        // Note: this returns an action so the nonce gets bumped even on failure
        return consensus_result.map_result(|action| {
            ExecutionEvent::create_from_state_transition_action(...)
        });
    }
}
}

An important detail: if advanced structure validation fails, the identity's nonce is still bumped. This prevents an attacker from replaying a structurally invalid transition over and over without cost.

Stage 9: Transform Into Action + Advanced Structure (with State)

For certain transition types (Batch, IdentityCreate, MasternodeVote, AddressFundingFromAssetLock, IdentityCreateFromAddresses), the platform needs to read state before it can finish structure validation. For example, a document create transition needs to fetch the data contract to validate the document against its schema.

This stage first transforms the raw state transition into an action (reading state in the process), then validates the action's structure:

#![allow(unused)]
fn main() {
let action = if state_transition.has_advanced_structure_validation_with_state() {
    let state_transition_action_result = state_transition.transform_into_action(
        platform, block_info, &remaining_address_balances,
        ValidationMode::Validator, &mut state_transition_execution_context, transaction,
    )?;
    if !state_transition_action_result.is_valid_with_data() {
        return state_transition_action_result.map_result(|action| { ... });
    }
    let action = state_transition_action_result.into_data()?;

    let result = state_transition.validate_advanced_structure_from_state(
        block_info, platform.config.network, &action,
        maybe_identity.as_ref(), &mut state_transition_execution_context,
        platform_version,
    )?;
    if !result.is_valid() {
        return result.map_result(|action| { ... });
    }
    Some(action)
} else {
    None
};
}

We will cover transform_into_action in detail in the next chapter.

For IdentityCreateFromAddresses this stage also checks the proof of possession of each key the transition registers. The address witnesses cannot sign those signatures (both sign the same bytes), so the owners of the inputs never signed what this check judges. From protocol version 14 a failure is therefore refused without a fee, like a failed witness, instead of charging the inputs a penalty; check_tx runs this stage for the transition too, so such a transition does not reach a block.

Stage 10: State Validation

The final validation stage checks for state-level conflicts. Does a data contract with this ID already exist? Is there already a document with this unique index value? Has this asset lock already been spent?

#![allow(unused)]
fn main() {
let result = if state_transition.has_state_validation() {
    state_transition.validate_state(
        action, platform, ValidationMode::Validator, block_info,
        &mut state_transition_execution_context, transaction,
    )?
} else if let Some(action) = action {
    ConsensusValidationResult::new_with_data(action)
} else {
    state_transition.transform_into_action(...)? // For transitions that skipped earlier
};
}

Not all transitions need state validation. IdentityTopUp, IdentityCreditWithdrawal, AddressFundsTransfer, and several others skip it -- their validation is fully covered by the earlier stages.

ConsensusValidationResult: How Errors Accumulate

Throughout the pipeline, errors are communicated through ConsensusValidationResult, defined in packages/rs-dpp/src/validation/validation_result.rs:

#![allow(unused)]
fn main() {
pub type ConsensusValidationResult<TData> = ValidationResult<TData, ConsensusError>;
pub type SimpleConsensusValidationResult = ConsensusValidationResult<()>;

pub struct ValidationResult<TData: Clone, E: Debug> {
    pub errors: Vec<E>,
    pub data: Option<TData>,
}
}

Key properties of this type:

• It can carry data alongside errors. When transform_into_action partially succeeds but has warnings, the action is in data and the warnings are in errors.
• is_valid() checks if errors is empty. Any error means failure.
• is_valid_with_data() checks both. Valid and has associated data.
• Errors can be merged from multiple validation steps using add_errors() or merge().
• Chainable via and_then_validation() for pipeline-style composition.

The SimpleConsensusValidationResult alias (where TData = ()) is used by validation stages that just check pass/fail without producing a transformed object.

ValidationMode

The pipeline behavior varies based on context:

#![allow(unused)]
fn main() {
pub enum ValidationMode {
    CheckTx,       // Mempool admission -- lighter checks
    RecheckTx,     // Periodic mempool revalidation
    Validator,     // Full block execution
    NoValidation,  // Testing/tooling only
}
}

For example, should_fully_validate_contract_on_transform_into_action() returns true only in Validator mode. During CheckTx, the platform skips expensive contract validation to keep mempool admission fast.

The Early-Return Pattern

You will notice a consistent pattern throughout the pipeline: each stage checks is_valid() and returns early if validation failed. This is intentional.

When the pipeline returns early due to a signature failure or invalid nonce, the transition produces no execution event -- the user is not charged. This protects users from being billed for transitions they did not actually submit (forged signatures) or that are replays (invalid nonces).

But when the pipeline returns early after the nonce has been validated -- for example, during advanced structure validation or state validation -- it returns a nonce-bump action so the identity still pays a small fee. This prevents a different attack: submitting thousands of structurally invalid transitions to waste validator resources for free.

Rules and Guidelines

Do:

• Run the full pipeline in Validator mode during block execution. Skipping stages can lead to consensus divergence.
• Return early on signature/nonce failures without charging the user.
• Bump the nonce (and charge) when structure or state validation fails after the nonce check has passed.
• Use ConsensusValidationResult everywhere -- do not use Result<(), Error> for validation outcomes, because a validation failure is not a system error.

Do not:

• Add expensive state reads to basic structure validation. It runs during check_tx and must be fast.
• Skip is_allowed validation -- it is the mechanism that enables protocol upgrades to gate new transition types.
• Assume the pipeline order is arbitrary. Each stage depends on information established by previous stages (e.g., the identity fetched during signature validation is used in balance checks).
• Confuse ConsensusError (a validation failure that the user caused) with Error (a system error like a database failure). The former accumulates in ValidationResult::errors; the latter propagates via Result::Err.

Transform Into Action

After a state transition passes the early validation stages -- signature verification, nonce checks, basic structure -- the platform needs to translate it from a raw "what the client sent" representation into a "what the platform should do" representation. This translation step is called transform into action, and it is where the platform reads state, resolves references, and prepares a validated, self-contained instruction for the Drive storage layer.

Why Actions Exist

Consider a DataContractCreateTransition. The client sends the contract in its serialized form. But before the platform can store it, it needs to:

1. Deserialize the contract from its wire format
2. Validate the contract schema (JSON Schema validation, index rules, etc.)
3. Compute the contract ID from the owner ID and nonce
4. Check version compatibility

The transition is what the client sends. The action is what the platform will execute. The action is a validated, resolved, ready-to-apply object. It has already been through deserialization, its references have been resolved against current state, and it carries exactly the information needed to generate Drive operations.

This separation is a deliberate design choice. The transition type lives in rs-dpp (the protocol library, shared between client and platform). The action type lives in rs-drive (the storage layer, platform-only). By keeping them separate:

• Clients never need to depend on storage internals
• The platform can evolve its internal representation without changing the wire format
• Validation logic lives close to state access, not scattered across the protocol layer

The StateTransitionActionTransformer Trait

The transformation is defined by a trait in packages/rs-drive-abci/src/execution/validation/state_transition/transformer/mod.rs:

#![allow(unused)]
fn main() {
pub trait StateTransitionActionTransformer {
    fn transform_into_action<C: CoreRPCLike>(
        &self,
        platform: &PlatformRef<C>,
        block_info: &BlockInfo,
        remaining_address_input_balances: &Option<
            BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
        >,
        validation_mode: ValidationMode,
        execution_context: &mut StateTransitionExecutionContext,
        tx: TransactionArg,
    ) -> Result<ConsensusValidationResult<StateTransitionAction>, Error>;
}
}

The key parameters:

• platform -- Access to the full platform state, including Drive (the storage layer), the current platform state, and configuration.
• block_info -- The current block height, time, epoch. Some validations are time-dependent.
• remaining_address_input_balances -- For address-based transitions, the balances remaining after earlier deductions.
• validation_mode -- Controls how thorough the validation is (lighter for CheckTx, full for Validator).
• execution_context -- Accumulates information about what operations were performed during validation (used for fee estimation).
• tx -- The GroveDB transaction handle for consistent state reads.

The return type is ConsensusValidationResult<StateTransitionAction> -- it can carry both the resulting action and any validation errors encountered during transformation.

The Top-Level Dispatch

The StateTransition enum implements StateTransitionActionTransformer by dispatching to each variant's own implementation:

#![allow(unused)]
fn main() {
impl StateTransitionActionTransformer for StateTransition {
    fn transform_into_action<C: CoreRPCLike>(
        &self,
        platform: &PlatformRef<C>,
        block_info: &BlockInfo,
        remaining_address_input_balances: &Option<BTreeMap<PlatformAddress, (AddressNonce, Credits)>>,
        validation_mode: ValidationMode,
        execution_context: &mut StateTransitionExecutionContext,
        tx: TransactionArg,
    ) -> Result<ConsensusValidationResult<StateTransitionAction>, Error> {
        match self {
            StateTransition::DataContractCreate(st) => st.transform_into_action(
                platform, block_info, remaining_address_input_balances,
                validation_mode, execution_context, tx,
            ),
            StateTransition::Batch(st) => st.transform_into_action(
                platform, block_info, remaining_address_input_balances,
                validation_mode, execution_context, tx,
            ),
            StateTransition::IdentityCreate(st) => {
                let signable_bytes = self.signable_bytes()?;
                st.transform_into_action_for_identity_create_transition(
                    platform, signable_bytes, validation_mode,
                    execution_context, tx,
                )
            },
            StateTransition::IdentityTopUp(st) => {
                let signable_bytes = self.signable_bytes()?;
                st.transform_into_action_for_identity_top_up_transition(
                    platform, signable_bytes, validation_mode,
                    execution_context, tx,
                )
            },
            // ... remaining variants
        }
    }
}
}

Notice that IdentityCreate and IdentityTopUp use specialized method names (transform_into_action_for_identity_create_transition) and pass signable_bytes explicitly. This is because these transitions need the signable bytes to verify the asset lock proof signature, and computing them at the StateTransition level (before the inner struct is extracted) ensures the correct bytes are used.

The StateTransitionAction Enum

The output of transformation is a StateTransitionAction, defined in packages/rs-drive/src/state_transition_action/mod.rs:

#![allow(unused)]
fn main() {
pub enum StateTransitionAction {
    DataContractCreateAction(DataContractCreateTransitionAction),
    DataContractUpdateAction(DataContractUpdateTransitionAction),
    BatchAction(BatchTransitionAction),
    IdentityCreateAction(IdentityCreateTransitionAction),
    IdentityTopUpAction(IdentityTopUpTransitionAction),
    IdentityCreditWithdrawalAction(IdentityCreditWithdrawalTransitionAction),
    IdentityUpdateAction(IdentityUpdateTransitionAction),
    IdentityCreditTransferAction(IdentityCreditTransferTransitionAction),
    MasternodeVoteAction(MasternodeVoteTransitionAction),
    // ... address-based actions ...
    BumpIdentityNonceAction(BumpIdentityNonceAction),
    BumpIdentityDataContractNonceAction(BumpIdentityDataContractNonceAction),
    PartiallyUseAssetLockAction(PartiallyUseAssetLockAction),
    BumpAddressInputNoncesAction(BumpAddressInputNoncesAction),
}
}

Notice the system actions at the bottom: BumpIdentityNonceAction, BumpIdentityDataContractNonceAction, PartiallyUseAssetLockAction, and BumpAddressInputNoncesAction. These are not user-requested actions. They are generated by the platform when a transition fails validation after the nonce check. The platform still needs to bump the nonce (so the same invalid transition cannot be replayed) and charge a fee. These system actions handle that housekeeping.

Versioned Dispatch Within transform_into_action

Each transition type's transform_into_action implementation uses the standard versioned dispatch pattern. Here is the data contract create example from packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/data_contract_create/mod.rs:

#![allow(unused)]
fn main() {
impl StateTransitionActionTransformer for DataContractCreateTransition {
    fn transform_into_action<C: CoreRPCLike>(
        &self,
        platform: &PlatformRef<C>,
        block_info: &BlockInfo,
        _remaining_address_input_balances: &Option<
            BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
        >,
        validation_mode: ValidationMode,
        execution_context: &mut StateTransitionExecutionContext,
        _tx: TransactionArg,
    ) -> Result<ConsensusValidationResult<StateTransitionAction>, Error> {
        let platform_version = platform.state.current_platform_version()?;

        match platform_version
            .drive_abci
            .validation_and_processing
            .state_transitions
            .contract_create_state_transition
            .transform_into_action
        {
            0 => self.transform_into_action_v0::<C>(
                block_info, validation_mode,
                execution_context, platform_version,
            ),
            version => Err(Error::Execution(ExecutionError::UnknownVersionMismatch {
                method: "data contract create transition: transform_into_action".to_string(),
                known_versions: vec![0],
                received: version,
            })),
        }
    }
}
}

The version number (0 here) is looked up from the platform version struct, allowing the logic to change in future protocol upgrades without modifying the dispatch layer.

What Happens Inside: Reading State

The core work inside transform_into_action varies by transition type, but the common thread is resolving references against current state. Here are the key patterns for different transition types:

DataContractCreate: Deserializes the contract from its wire format, validates the schema, and wraps it in a DataContractCreateTransitionAction. The validation depth depends on ValidationMode -- CheckTx mode skips full schema validation for speed.

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).

Batch (Documents): This is the most complex transformation. For each document sub-transition in the batch, the platform must:

1. Fetch the data contract that the document belongs to
2. Look up the document type within that contract
3. For creates: validate the document against the type's schema
4. For replaces/deletes: fetch the existing document to verify ownership and revision
5. For token operations: validate token configuration and authorization

IdentityCreate: Validates the asset lock proof against the core chain (via RPC), verifies the signature on the transition using keys embedded in the transition itself, and constructs the identity that will be created.

MasternodeVote: Fetches the contested resource being voted on, verifies that the masternode is eligible to vote, and constructs the vote action.

The Batch Transition: A Deeper Look

The BatchTransition is worth examining more closely because it demonstrates how transform_into_action handles multiple sub-operations. A single batch can contain dozens of document and token transitions targeting different contracts and document types.

During transformation, the platform:

1. Groups transitions by contract. This allows fetching each contract only once.
2. Fetches all needed contracts. Each contract is loaded from Drive (with caching).
3. Resolves each sub-transition. Document creates get validated against their type's schema. Replaces fetch the existing document. Token operations check authorization rules.
4. Produces a BatchTransitionAction containing individual BatchedTransitionAction items -- each of which is either a DocumentAction or a TokenAction.

If any sub-transition fails validation, the entire batch fails, and the platform produces a BumpIdentityDataContractNonceAction instead (bumping the nonce to prevent replay, while charging the user).

When Transformation Fails

Transformation can fail in two ways:

System error (Result::Err): Something unexpected happened -- a database read failed, a version mismatch, corrupted state. These propagate up as Error and typically halt block processing.

Consensus error (ValidationResult with errors): The transition itself is invalid. The document does not match its schema, the contract does not exist, the asset lock is already spent. In this case, the result still carries data -- typically a nonce-bump action -- so the pipeline can charge the user and move on.

This distinction is reflected in the return type: Result<ConsensusValidationResult<StateTransitionAction>, Error>. The outer Result is for system errors. The inner ConsensusValidationResult is for user errors.

Rules and Guidelines

Do:

• Always respect ValidationMode. Skip expensive work during CheckTx but never skip it during Validator mode.
• Accumulate validation costs in execution_context -- every state read, every schema validation -- so that fee calculation is accurate.
• Return a nonce-bump action when transformation fails for user-caused reasons. Never silently swallow the transition.
• Fetch contracts through Drive's caching layer. A batch transition might reference the same contract dozens of times; fetching it from disk each time would be prohibitively expensive.

Do not:

• Perform state writes during transform_into_action. This is a read-only phase. State is only modified when the resulting action is applied later.
• Mix up the transition and action types. The transition is DataContractCreateTransition (from rs-dpp). The action is DataContractCreateTransitionAction (from rs-drive). They live in different crates for good reason.
• Forget to handle the remaining_address_input_balances parameter for address-based transitions. It is None for identity-based transitions but must be Some for address-based ones -- failing to provide it is a corrupted code execution error.
• Add new transition types without implementing both the transformer trait and adding the variant to the StateTransitionAction enum. These must stay in sync.

Drive Operations: From Action to Storage

By this point in the pipeline, a state transition has been validated and transformed into a StateTransitionAction. But the action is still an abstract description of what should change. The final step is translating it into concrete storage mutations that get applied atomically to GroveDB, the platform's Merkle tree database. This translation happens through a three-tier pipeline of progressively lower-level operation types.

The Three-Tier Pipeline

The pipeline looks like this:

StateTransitionAction
    |
    | DriveHighLevelOperationConverter::into_high_level_drive_operations()
    v
Vec<DriveOperation>
    |
    | DriveLowLevelOperationConverter::into_low_level_drive_operations()
    v
Vec<LowLevelDriveOperation>
    |
    | apply_batch_low_level_drive_operations()
    v
GroveDB (applied atomically)

Each tier exists for a reason:

• StateTransitionAction speaks the language of the protocol: "create this identity," "store this document," "transfer these credits."
• DriveOperation speaks the language of Drive's domain model: "insert a document into this contract's document type tree," "update an identity's balance."
• LowLevelDriveOperation speaks the language of GroveDB: "insert this key-value pair at this path," "delete this element."

This layering allows each tier to be tested independently and evolved separately. A change to how documents are indexed in GroveDB only affects the DriveLowLevelOperationConverter implementation for DocumentOperationType -- it does not ripple up to the action layer.

Tier 1: DriveHighLevelOperationConverter

The first conversion step is defined in packages/rs-drive/src/state_transition_action/action_convert_to_operations/mod.rs:

#![allow(unused)]
fn main() {
pub trait DriveHighLevelOperationConverter {
    fn into_high_level_drive_operations<'a>(
        self,
        epoch: &Epoch,
        platform_version: &PlatformVersion,
    ) -> Result<Vec<DriveOperation<'a>>, Error>;
}
}

The StateTransitionAction enum implements this trait by dispatching to each variant:

#![allow(unused)]
fn main() {
impl DriveHighLevelOperationConverter for StateTransitionAction {
    fn into_high_level_drive_operations<'a>(
        self,
        epoch: &Epoch,
        platform_version: &PlatformVersion,
    ) -> Result<Vec<DriveOperation<'a>>, Error> {
        match self {
            StateTransitionAction::DataContractCreateAction(action) => {
                action.into_high_level_drive_operations(epoch, platform_version)
            }
            StateTransitionAction::DataContractUpdateAction(action) => {
                action.into_high_level_drive_operations(epoch, platform_version)
            }
            StateTransitionAction::BatchAction(action) => {
                action.into_high_level_drive_operations(epoch, platform_version)
            }
            StateTransitionAction::IdentityCreateAction(action) => {
                action.into_high_level_drive_operations(epoch, platform_version)
            }
            // ... all other variants
        }
    }
}
}

Each action type knows how to decompose itself into the appropriate DriveOperation variants. A single action often produces multiple drive operations. For example, IdentityCreateAction might produce:

1. An IdentityOperation to insert the identity
2. An IdentityOperation to set the initial balance
3. Multiple IdentityOperations to add each public key
4. A SystemOperation to update system credit tracking

For the BatchTransitionAction, there is an additional layer of delegation. The batch contains multiple BatchedTransitionAction items, each of which implements DriveHighLevelBatchOperationConverter:

#![allow(unused)]
fn main() {
pub trait DriveHighLevelBatchOperationConverter {
    fn into_high_level_batch_drive_operations<'a>(
        self,
        epoch: &Epoch,
        owner_id: Identifier,
        platform_version: &PlatformVersion,
    ) -> Result<Vec<DriveOperation<'a>>, Error>;
}
}

Notice the extra owner_id parameter -- batch operations need to know which identity owns the documents being created or modified.

Tier 2: The DriveOperation Enum

The DriveOperation enum represents domain-level storage operations. It is defined in packages/rs-drive/src/util/batch/drive_op_batch/mod.rs:

#![allow(unused)]
fn main() {
pub enum DriveOperation<'a> {
    DataContractOperation(DataContractOperationType<'a>),
    DocumentOperation(DocumentOperationType<'a>),
    TokenOperation(TokenOperationType),
    WithdrawalOperation(WithdrawalOperationType),
    IdentityOperation(IdentityOperationType),
    PrefundedSpecializedBalanceOperation(PrefundedSpecializedBalanceOperationType),
    SystemOperation(SystemOperationType),
    GroupOperation(GroupOperationType),
    AddressFundsOperation(AddressFundsOperationType),
    GroveDBOperation(QualifiedGroveDbOp),
    GroveDBOpBatch(GroveDbOpBatch),
}
}

Each variant wraps a type-specific operation enum. For example, DocumentOperationType includes operations like AddDocument, UpdateDocument, DeleteDocument -- each carrying the document data, contract reference, and storage flags needed for insertion.

The last two variants -- GroveDBOperation and GroveDBOpBatch -- are escape hatches for when higher-level abstractions are not needed. They wrap raw GroveDB operations directly.

The DriveOperation enum implements the DriveLowLevelOperationConverter trait to convert itself into the next tier:

#![allow(unused)]
fn main() {
pub trait DriveLowLevelOperationConverter {
    fn into_low_level_drive_operations(
        self,
        drive: &Drive,
        estimated_costs_only_with_layer_info: &mut Option<
            HashMap<KeyInfoPath, EstimatedLayerInformation>,
        >,
        block_info: &BlockInfo,
        transaction: TransactionArg,
        platform_version: &PlatformVersion,
    ) -> Result<Vec<LowLevelDriveOperation>, Error>;
}
}

Two important parameters here:

• estimated_costs_only_with_layer_info: When this is Some, the converter does not actually read from or write to GroveDB. Instead, it estimates the cost of the operations using layer information. This is used for fee estimation before execution.
• transaction: The GroveDB transaction handle. All reads and writes within a single block happen within one transaction, ensuring atomicity.

Tier 3: LowLevelDriveOperation

The lowest tier is defined in packages/rs-drive/src/fees/op.rs:

#![allow(unused)]
fn main() {
pub enum LowLevelDriveOperation {
    GroveOperation(QualifiedGroveDbOp),
    FunctionOperation(FunctionOp),
    CalculatedCostOperation(OperationCost),
    PreCalculatedFeeResult(FeeResult),
}
}

At this level, there are only four kinds of things:

• GroveOperation: A concrete GroveDB operation -- insert, delete, or update a key-value pair at a specific path in the Merkle tree.
• FunctionOperation: A CPU-bound operation with a pre-defined cost (like hashing or signature verification). These do not touch storage but still cost processing fees.
• CalculatedCostOperation: A pre-computed cost that gets folded into the fee calculation.
• PreCalculatedFeeResult: An already-computed fee result, used when the fee for an operation was determined earlier in the pipeline.

The GroveOperation variant is where the rubber meets the road. QualifiedGroveDbOp is GroveDB's own batch operation type -- it specifies a path (a vector of byte-string segments navigating the tree), a key, and an operation (insert element, delete, replace, etc.).

Applying the Batch

The entire sequence -- from DriveOperation collection to GroveDB application -- is orchestrated by Drive::apply_drive_operations, defined in packages/rs-drive/src/util/batch/drive_op_batch/drive_methods/apply_drive_operations/v0/mod.rs:

#![allow(unused)]
fn main() {
pub(crate) fn apply_drive_operations_v0(
    &self,
    operations: Vec<DriveOperation>,
    apply: bool,
    block_info: &BlockInfo,
    transaction: TransactionArg,
    platform_version: &PlatformVersion,
    previous_fee_versions: Option<&CachedEpochIndexFeeVersions>,
) -> Result<FeeResult, Error> {
    if operations.is_empty() {
        return Ok(FeeResult::default());
    }
    let mut low_level_operations = vec![];
    let mut estimated_costs_only_with_layer_info = if apply {
        None
    } else {
        Some(HashMap::new())
    };

    let mut finalize_tasks: Vec<DriveOperationFinalizeTask> = Vec::new();

    for drive_op in operations {
        if let Some(tasks) = drive_op.finalization_tasks(platform_version)? {
            finalize_tasks.extend(tasks);
        }
        low_level_operations.append(
            &mut drive_op.into_low_level_drive_operations(
                self, &mut estimated_costs_only_with_layer_info,
                block_info, transaction, platform_version,
            )?
        );
    }

    let mut cost_operations = vec![];
    self.apply_batch_low_level_drive_operations(
        estimated_costs_only_with_layer_info, transaction,
        low_level_operations, &mut cost_operations, &platform_version.drive,
    )?;

    for task in finalize_tasks {
        task.execute(self, platform_version);
    }

    Drive::calculate_fee(
        None, Some(cost_operations), &block_info.epoch,
        self.config.epochs_per_era, platform_version, previous_fee_versions,
    )
}
}

Let us break this down:

1. Collect finalization tasks. Some operations need post-processing. For example, DataContractOperation may produce a RecordShieldedAnchor finalization task that runs after the batch is committed. Tasks are collected first, executed last.

2. Convert to low-level operations. Each DriveOperation is expanded into one or more LowLevelDriveOperations. A single document insertion might produce dozens of GroveDB operations (one for each index, plus the document itself, plus metadata).

3. Apply the batch atomically. apply_batch_low_level_drive_operations collects all GroveOperation items into a single GroveDB batch and applies them in one atomic write. This is critical -- if the node crashes mid-application, either all operations succeed or none do.

4. Execute finalization tasks. Post-commit callbacks run (e.g., updating caches).

5. Calculate fees. The cost of every operation (storage bytes written, bytes read, processing time) is tallied into a FeeResult that determines how many credits the user pays.

The apply Parameter

Notice the apply: bool parameter. When apply is false, the entire pipeline runs in estimation mode: operations are not actually written to GroveDB. Instead, the estimated_costs_only_with_layer_info map is populated with what would be written, and fees are estimated from that.

This is used during check_tx and fee estimation. The platform needs to know approximately how much a transition will cost before actually applying it, both for balance pre-checks and for returning fee estimates to clients.

The Fee Calculation

At the end of apply_drive_operations, fees are calculated from the accumulated cost operations:

#![allow(unused)]
fn main() {
Drive::calculate_fee(
    None,
    Some(cost_operations),
    &block_info.epoch,
    self.config.epochs_per_era,
    platform_version,
    previous_fee_versions,
)
}

The fee has two components:

• Storage fee: Proportional to the bytes written to disk. Stored bytes have an ongoing cost because they consume space in the state tree indefinitely (until deleted). When bytes are later removed, a portion of the storage fee is refunded.
• Processing fee: Proportional to the CPU work performed -- hashing, signature verification, tree traversal. This is ephemeral and not refundable.

The user's user_fee_increase (a percentage multiplier) applies to the processing fee, allowing users to bid higher for priority.

Finalization Tasks

Some DriveOperation variants carry finalization tasks -- callbacks that run after the batch is committed. These are defined in packages/rs-drive/src/util/batch/drive_op_batch/finalize_task.rs:

#![allow(unused)]
fn main() {
pub(crate) trait DriveOperationFinalizationTasks {
    fn finalization_tasks(
        &self,
        platform_version: &PlatformVersion,
    ) -> Result<Option<Vec<DriveOperationFinalizeTask>>, Error>;
}
}

The most common finalization task is RecordShieldedAnchor, used by shielded transaction operations to record Merkle tree anchors after the state changes are committed. Finalization tasks are intentionally limited -- they must be deterministic and must not fail, since they run after the batch is already committed.

Putting It All Together: A Document Create

Let us trace a document creation through the entire three-tier pipeline:

1. Action: BatchTransitionAction containing a DocumentAction::CreateAction with the document data, its type, and the contract reference.

2. DriveHighLevelOperationConverter: The document create action produces a DriveOperation::DocumentOperation(AddDocument { ... }) containing the owned document, contract info, document type info, and storage flags.

3. DriveLowLevelOperationConverter: The AddDocument operation produces multiple LowLevelDriveOperation::GroveOperation items:

   • Insert the serialized document at its primary key path
   • Insert index entries for each indexed property
   • Update the document type's document count
   • Record storage flags for fee tracking

4. GroveDB batch: All the GroveOperation items from all documents in the batch are collected into a single GroveDbOpBatch and applied atomically.

5. Fee calculation: The total bytes written, bytes read, and processing operations are summed to produce the FeeResult.

Rules and Guidelines

Do:

• Implement DriveHighLevelOperationConverter for new action types. This is the contract between the validation layer and the storage layer.
• Keep into_low_level_drive_operations deterministic. Given the same inputs and state, it must always produce the same operations. Non-determinism causes consensus failures.
• Use the estimation mode (apply = false) for fee pre-checks. Do not skip fee estimation -- users need accurate cost information before committing to a transition.
• Test both the estimation path and the application path. They can diverge if the estimation layer info is stale or incomplete.

Do not:

• Access GroveDB directly from action conversion code. Always go through Drive's methods, which handle versioning, caching, and error translation.
• Produce side effects in into_high_level_drive_operations. This conversion must be pure -- it maps data, it does not read or write state.
• Assume a 1:1 mapping between actions and GroveDB operations. A single document create can produce 10+ GroveDB operations (one per index). A batch with 50 documents can produce hundreds.
• Forget finalization tasks when adding new operation types that require post-commit work. If your operation needs to update a cache or record an anchor, implement DriveOperationFinalizationTasks.
• Mix up DriveOperation (high-level, domain-aware) with LowLevelDriveOperation (low-level, GroveDB-aware). The naming can be confusing, but the distinction is important: the former knows about documents and identities, the latter knows about tree paths and elements.

Fee System Overview

Every state transition on Dash Platform costs credits. Credits are the internal unit of account (1 Dash = 100,000,000,000 credits). The fee system ensures that validators are compensated for computation and storage, that spam is economically infeasible, and that the platform's state does not grow unboundedly without payment.

This section covers the three fee eras that the platform has gone through:

1. Identity Credit Fees (protocol versions 1--9) — Fees paid from an identity's credit balance, funded by asset lock transactions on Core.
2. Platform Address Fees (protocol versions 10--11) — Fees paid from platform address balances using a UTXO-like input/output model.
3. Shielded Transaction Fees (protocol version 12) — Fees embedded in zero-knowledge proofs and cryptographically bound to the Orchard bundle.

Each era introduced new ExecutionEvent variants and fee validation logic, but the underlying cost accounting (storage fees, processing fees, epoch distribution) is shared across all three.

Credits and Denomination

Platform credits are the smallest unit of value:

All fee constants in the codebase are denominated in credits.

Cost Components

The platform distinguishes two fundamental kinds of cost:

Storage Fees

Storage fees pay for bytes that persist in GroveDB indefinitely. The rate is set in FeeStorageVersion:

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 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 their storage fees are paid out to the epochs they live in, through the lifetime storage fee pools, instead of over the perpetual distribution. See Document Time To Live.

Processing Fees

Processing fees pay for computation that does not leave a permanent trace in storage: signature verification, hashing, tree traversal, and so on. These are non-refundable — the computation has already been performed.

Processing costs are built up from individual operations:

processing_fee =
    seek_count × storage_seek_cost
  + added_bytes × storage_processing_credit_per_byte
  + replaced_bytes × storage_processing_credit_per_byte
  + loaded_bytes × storage_load_credit_per_byte
  + hash_node_calls × (blake3_base + blake3_per_block)

Signature verification adds a fixed cost per algorithm:

Hashing costs scale with the number of blocks processed:

Minimum Fees

Every state transition type has a minimum fee that must be met regardless of the actual computation cost. This prevents zero-cost spam. The minimums are defined in StateTransitionMinFees:

Identity-Based Transitions (protocol versions 1--9)

Address-Based Transitions (protocol versions 10--11)

Data Contract Registration Fees (protocol version 9+)

Protocol version 9 introduced significant registration fees for data contracts to prevent namespace squatting:

Before protocol version 9, all registration fees were zero.

Contest Funds

A document create that opens or joins a contest (a contested unique index) prefunds the masternode votes: the amount leaves the contender's balance for the contest's prefunded balance, each vote takes a fixed cost from it, and what is left when the contest ends is released as processing fees. The amounts are VoteResolutionFundFees in the fee version:

required_vote_resolution_fund in rs-dpp picks between the two funds; the schedules before 14 carry the contested document amount in the moderation field, so the choice changes nothing there.

User Fee Increase

Every state transition carries a user_fee_increase field (a UserFeeIncrease value). This allows the sender to voluntarily pay more than the base fee to prioritize their transition. The multiplier works as follows:

• 0 = 100% of base fee (no increase)
• 1 = 101% of base fee
• 10 = 110% of base fee
• 100 = 200% of base fee

The increase applies only to the processing fee component, not to storage fees. This is because storage fees are a direct function of bytes stored and should not be inflated.

#![allow(unused)]
fn main() {
fn apply_user_fee_increase(&mut self, user_fee_increase: UserFeeIncrease) {
    let increase = self.processing_fee * user_fee_increase as u64 / 100;
    self.processing_fee = self.processing_fee.saturating_add(increase);
}
}

ExecutionEvent Variants

The ExecutionEvent enum (in rs-drive-abci) determines how fees are collected for each state transition. There are eight variants:

Each variant carries the operations to execute and enough context for the fee validation and execution pipeline to deduct the correct amount from the correct source.

Gas paid by the contract owner

From protocol version 14 a document action that is paid for with a token can have its gas (the storage and processing fee) paid by the contract owner. The document type's token cost offers it (gasFeesPaidBy: DocumentOwner, ContractOwner or PreferContractOwner) and the transition's $tokenPaymentInfo asks for it with the same enum; GasFeesPaidBy::resolve in rs-dpp names the payer. A document owner can always opt out, can always state a preference, and can insist (ContractOwner) only on a document type that commits to paying. Only a token-paid action can be sponsored, so every sponsored transition is backed by a token the contract owner chose to hand out.

The batch transformer (v2) resolves one payer for the whole batch, reads the contract owner's balance into the action (ResolvedGasSponsor, billed to the batch) and the execution event carries it in Paid.gas_sponsor. Fee validation v1 judges the fee against the sponsor's balance and the signer only has to fund removed_balance; when the sponsor's balance falls short a batch that insists is refused unpaid (GasSponsorInsufficientBalanceError, 40222) 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.

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 (purchases, contest collateral) and leaves the gas to fee validation, so an identity without credits can act on tokens it was given. Such a signer could not pay for a failed batch, and a failed batch is never sponsored, so check tx validates the batch of a signer under the fee minimum against the state in full, on the first check and on every recheck, as it does a masternode vote: what nobody could be charged for is refused there, or leaves the mempool once the tokens it counted on are spent, instead of being executed for free by a proposer.

Optional token costs

A token cost may declare optional: true (v3 meta-schema, protocol version 14). A transition on such an action may leave $tokenPaymentInfo out: it then pays no token, its signer pays the gas in credits as on an action without a token cost, and no sponsorship applies. With $tokenPaymentInfo present the token is charged exactly as for a required cost, sponsorship included, and an insufficient token balance is a rejection rather than a fallback to credits: the client chooses between token and credits before signing. Together with contract-owner gas this is the "free usage" pattern: an app hands out tokens, a user posts for free while they last, and keeps posting on credits after.

Document action fees

From protocol version 14 a document type may charge a fixed fee in credits for an action on one of its documents, on top of the gas. The actionFees keyword (v3 document meta-schema) sits beside tokenCost and prices the same six actions:

"post": {
  "type": "object",
  "actionFees": {
    "pricing": "feeMultiplier",
    "create": { "moderators": 100000000, "owner": 10000000 }
  }
}

Creating a post here costs an extra 0.001 Dash for the contract's moderation team and 0.0001 Dash for its owner. Each fee has those two parts, either of which may be left out. The owner parts collect in the contract's owner pot and the moderators parts in its moderators pot, and a ContractFeeClaim state transition pays a pot out (see Contract Moderation). A moderators part needs a contract that declares moderation (DocumentActionFeesWithoutModerationError, 10902): the moderation team is who that pot is for.

Pricing. fixed charges the declared amounts as written. feeMultiplier, the default, scales them by the fee multiplier of the epoch the action executes in (declared * multiplier_permille / 1000, rounded down), so a fee follows the network's fees. The multiplier is the item every epoch tree records, read once per batch and billed to it (fetch_action_fee_multiplier_with_fee). In the first block of an epoch that item is not there yet, because state transitions execute before the end of the block, where the epoch is initialized; the multiplier the epoch is about to be initialized with, the fee schedule's, is used then. Nothing else reads the epoch multiplier today: the metered fees do not scale with it. A scaled amount is held at the maximum number of credits rather than overflowing: a fee nobody can pay refuses the action for an insufficient balance, a consensus error, where an overflow would have failed every transition on the action with an internal one.

The transition agrees to the fee. The contract is read when the action executes, not when the transition was signed, so a transition that said nothing would pay whatever the contract declares by then. Every transition on an action that charges a fee therefore carries an action fee agreement ($actionFeeAgreement, on version 2 of the document base transition, the default from protocol version 14):

"$actionFeeAgreement": {
  "$formatVersion": "0",
  "owner": 10000000,
  "moderators": 100000000,
  "feeMultiplier": { "knownPermille": 1000, "increaseTolerancePercent": 20 }
}

• owner and moderators are the amounts the document type declares for the action, before any multiplier. They must match exactly, each pot on its own: a fee that was raised, lowered, or moved between the pots since the signer read the contract refuses the action (DocumentActionFeeAgreementMismatchError, 40133), and the signer reads the contract again.
• feeMultiplier says how the fee is priced. It is named for a feeMultiplier fee and left out for a fixed one, and an agreement to the other pricing is the same mismatch. knownPermille is the fee multiplier the signer priced the fee with, and increaseTolerancePercent how far above it the multiplier of the executing epoch may be, in percent of the known one: 20 accepts up to 1.2 times. A transition signed just before an epoch boundary is then not refused for a small move; one the multiplier outran is (DocumentActionFeeMultiplierNotToleratedError, 40134). A multiplier that fell is always accepted. What is charged follows the epoch's multiplier, never the known one.
• A transition without an agreement on an action that charges a fee is refused (DocumentActionFeeAgreementNotSetError, 40132), whoever pays: a sponsored action says what it agrees to as well, since a preferred sponsor can hand the fee back to the signer. An agreement on an action that charges nothing is ignored.

All three are paid refusals that bump the nonce and charge no fee. They are judged in the batch's advanced structure validation (BatchTransitionAction::validate_action_fee_agreements), off the action alone: the base action carries the declaration beside the agreement, and the batch action the multiplier its transformer read. The mempool runs the same check when a transition arrives and again on every recheck, so a transition whose agreement no longer holds leaves the mempool with the same error instead of failing in the block that would have refused it. A client builds the agreement from the contract it showed its user with DocumentActionFeeAgreement::for_document_type_action, never from a contract fetched behind their back at signing time.

A seated team's discount. On a document type an elected contract moderates, the moderators part of an agreement may name less than the declared amount: the share the contract's seated moderation charter takes (its proposal's moderatorsShare, a percentage; none declared is the full amount), applied to the declared amount and rounded down to the credit (moderation_charter::moderators_share_of). Everything else must still match: the owner part and the pricing. With a share of 60, the post above admits exactly 60000000 for the moderators:

"$actionFeeAgreement": {
  "$formatVersion": "0",
  "owner": 10000000,
  "moderators": 60000000,
  "feeMultiplier": { "knownPermille": 1000, "increaseTolerancePercent": 20 }
}

The action is then charged the agreed amount, which is what reaches the moderators pot (scaled by the multiplier for a feeMultiplier fee, like the declared amount). An agreement to the declared amount stays valid whatever the team charges and reads no charter; only one that names less has the batch transformer read the seated charter (the byTargetContract index of the moderation charters contract) and the proposal it runs on, billed to the batch. Any other amount below the declared one, including a discount on a contract with no seated charter yet, is refused like a mismatch, paid and without a fee (DocumentActionFeeModeratorsShareMismatchError, 40139). A lower amount anywhere else (a type the contract does not moderate, a contract that is not elected) is the plain mismatch (40133). The mempool judges it the same way on arrival and on every recheck, since the recheck transforms the batch anew.

The amounts do not change yet. A contract update may not add, change or remove the actionFees of an existing document type, nor switch their pricing (DocumentTypeUpdateError). A document type added by an update may declare its own, so a live contract gets fees through new document types only. The agreement is what makes lifting this safe later: an owner who changes a fee cannot make a transition signed against the old one pay the new one.

Who pays. Whoever pays the gas pays the action fee: the signer, or the contract owner when they sponsor the gas. A sponsor's balance has to cover the gas and the fees they would owe; one that insisted and falls short is the same unpaid refusal as before (40222), and one that only preferred hands the gas and the fees back to the signer. The gas is estimated for the payer: first with the sponsor paying, then, when the sponsor does not pay, with the signer paying. Fee validation settles the payer through one function (gas_sponsor_pays) and hands it to execution, which charges that payer, so they always name the same one. The contract owner never pays the owner part: it would travel through the owner pot back to them and only cost writes. A sponsor is always the contract owner, so a sponsored action pays into the moderators pot only, which a contract that sponsors gas should price in. The fee counts against the budget of a budgeted signing key when its identity pays it.

Only an action that executes is charged. A transition that fails, in the transformer or later in state validation, becomes a nonce bump, and a bump owes nothing. The fees are therefore read off the transitions when the execution event is built, after state validation had its say, not when the transformer ran.

The fee is not part of the FeeResult. It moves as balance operations in the batch's own operation list: one removal from the payer, one addition per pot. The transition may already write the payer's balance: a purchase moves its price, a contested document its voting fund, and a sale pays a contract owner who may be sponsoring the gas. A balance operation computes the new balance from the one committed before its batch and GroveDB keeps only the last write of a key, so apply_drive_operations (generation 1, protocol version 14) merges every write of one identity balance, one fee pot or one prefunded specialized balance in a batch into a single net operation. Token writes cannot be merged that way (a transfer writes two balances, a mint or a burn a balance and the supply), so a batch that writes one token balance or supply twice is refused; no state transition makes one. The fee pools and the proposers see exactly what they saw before. The pots sit under the PreFundedSpecializedBalances root sum tree, which the per-block total credits check already sums, so the credits stay accounted for while they wait to be claimed.

FeeResult

All fee calculations produce a FeeResult:

#![allow(unused)]
fn main() {
pub struct FeeResult {
    pub storage_fee: Credits,
    pub processing_fee: Credits,
    pub fee_refunds: FeeRefunds,
    pub removed_bytes_from_system: u32,
}
}

• storage_fee — credits for new bytes written to persistent storage
• processing_fee — credits for computation and I/O
• fee_refunds — credits returned because previously stored data was deleted
• removed_bytes_from_system — bytes removed that were stored by the system (not by any identity), so no refund is issued

The total base fee is storage_fee + processing_fee. The FeeResult is produced by Drive::apply_drive_operations(), which executes the GroveDB operations and measures the actual cost of each insert, delete, and query.

Refunds

When data is removed from GroveDB (a document is deleted, a key is removed), the system calculates a refund of the original storage fee. Refunds are tracked per identity per epoch:

#![allow(unused)]
fn main() {
pub struct FeeRefunds(pub CreditsPerEpochByIdentifier);
// BTreeMap<IdentifierBytes32, BTreeMap<EpochIndex, Credits>>
}

Refunds are not 1:1 with the original fee because storage fees are distributed across future epochs (see below). The refund amount depends on how many epochs have elapsed since the data was stored — the longer the data has been stored, the smaller the refund, because more of the distributed fees have already been paid out to proposers.

There is a dust limit: refunds below 32 bytes worth of storage credits are discarded to prevent micro-refund spam.

Epoch-Based Fee Distribution

Fees do not go directly to the block proposer. Instead, they accumulate in epoch-specific pools and are distributed to proposers at epoch boundaries.

How Epochs Work

• An epoch is a fixed window of blocks
• An era consists of 40 epochs
• Storage fees are distributed across 50 eras (2,000 epochs, roughly 50 years) using a declining schedule

The distribution table allocates percentages per era:

Within each era, the percentage is divided equally among the era's epochs. For example, a 1,000,000-credit storage fee distributes 50,000 credits (5%) to era 0, split evenly across 40 epochs = 1,250 credits per epoch.

Fee Flow

Block execution
  └→ FeeResult (storage + processing)
       └→ End of block: add_distribute_block_fees_into_pools()
            ├→ Processing fees → current epoch pool
            └→ Storage fees → global distribution pool → spread across future epochs

Epoch change
  └→ add_distribute_fees_from_oldest_unpaid_epoch_pool_to_proposers()
       ├→ Calculate Core block rewards for the epoch
       ├→ Add Core rewards to system credits
       └→ Distribute (Platform fees + Core rewards) to proposers

Processing fees are paid to proposers at the end of the epoch in which they were collected. Storage fees are spread across 50 eras of future epochs, providing a long-term revenue stream for validators.

Fee Versioning

All fee parameters are versioned through FeeVersion, stored in PlatformVersion. This allows the protocol to adjust fee rates without a hard fork — a new protocol version simply references different fee constants.

The current fee version structure:

#![allow(unused)]
fn main() {
pub struct FeeVersion {
    pub fee_version_number: FeeVersionNumber,
    pub uses_version_fee_multiplier_permille: Option<u64>,
    pub storage: FeeStorageVersion,
    pub signature: FeeSignatureVersion,
    pub hashing: FeeHashingVersion,
    pub processing: FeeProcessingVersion,
    pub data_contract_validation: FeeDataContractValidationVersion,
    pub data_contract_registration: FeeDataContractRegistrationVersion,
    pub state_transition_min_fees: StateTransitionMinFees,
    pub vote_resolution_fund_fees: VoteResolutionFundFees,
}
}

Fee versions are stored in the FEE_VERSIONS array and looked up by number. The uses_version_fee_multiplier_permille field allows a global scaling factor (permille = divide by 1000; a value of 1000 means no change).

Key Source Files

Platform Address Fees

Protocol versions 10 and 11 introduced a new class of state transitions that operate on platform addresses rather than identities. Platform addresses are derived from public keys (similar to Bitcoin addresses) and hold a credit balance directly, without requiring an identity to be registered.

This chapter explains how fees work for address-based transitions, how they differ from the identity credit model, and how the fee strategy mechanism gives clients control over fee deduction.

Background: Why Platform Addresses?

Before protocol version 10, every action on the platform required an identity — a registered entity funded by an asset lock transaction. Creating an identity required a Core transaction, waiting for confirmations, and then submitting a state transition. This was a multi-step process that created friction for simple operations like "send credits to an address."

Platform addresses solve this by allowing credits to exist at addresses without a full identity. Users can fund an address (via an asset lock or a transfer from another address) and then spend from it directly using a signature from the address's key pair.

Address-Based State Transitions

Protocol versions 10 and 11 added the following transition types:

All of these use the PaidFromAddressInputs execution event variant.

The Input/Output Model

Address-based transitions follow a UTXO-inspired model with inputs and outputs:

Inputs

Each input specifies a platform address, the expected nonce, and the amount to consume from that address's balance:

inputs: [
    { address: A, nonce: 5, amount: 100_000_000 },
    { address: B, nonce: 3, amount:  50_000_000 },
]

The platform validates each input by:

1. Checking the address exists in state
2. Verifying the nonce is exactly current_nonce + 1 (replay protection)
3. Confirming the address has sufficient balance for the requested amount

After validation, the remaining balance of each input is tracked:

remaining = actual_balance - requested_amount

This remaining balance is what is available to pay fees from (after the requested amount is committed to outputs).

Outputs

Outputs specify destination addresses and the credits to send:

outputs: [
    { address: C, amount: 80_000_000 },
    { address: D, amount: 60_000_000 },
]

Outputs are added to recipient balances. They can also be reduced to pay fees (see Fee Strategy below).

Balance Equation

The fundamental constraint is:

sum(input_amounts) >= sum(output_amounts) + fees

If the inputs cannot cover both the outputs and the fees, the transition is rejected with AddressesNotEnoughFundsError.

Fee Strategy

Unlike identity-based transitions where fees are always deducted from the identity's balance, address-based transitions use an explicit fee strategy that the client includes in the transition. The fee strategy is an ordered sequence of steps that tells the platform where to find the fee credits:

#![allow(unused)]
fn main() {
pub enum AddressFundsFeeStrategyStep {
    /// Deduct fee from a specific input address's remaining balance.
    DeductFromInput(u16),
    /// Reduce a specific output's amount to cover the fee.
    ReduceOutput(u16),
}

pub type AddressFundsFeeStrategy = Vec<AddressFundsFeeStrategyStep>;
}

How It Works

The platform processes the steps in order. At each step, it deducts as much of the remaining fee as possible from the specified source:

fee_strategy: [DeductFromInput(0), ReduceOutput(0)]

Step 1: Try to deduct full fee from input 0's remaining balance
  - remaining_fee = 10,000,000
  - input_0_remaining = 25,000,000
  - deducted = 10,000,000
  - input_0_remaining = 15,000,000
  - remaining_fee = 0 → done

If the first source is insufficient, the algorithm moves to the next step:

fee_strategy: [DeductFromInput(0), ReduceOutput(1)]

Step 1: Try to deduct from input 0
  - remaining_fee = 10,000,000
  - input_0_remaining = 3,000,000
  - deducted = 3,000,000
  - input_0_remaining = 0 (removed)
  - remaining_fee = 7,000,000

Step 2: Try to reduce output 1
  - remaining_fee = 7,000,000
  - output_1_amount = 60,000,000
  - deducted = 7,000,000
  - output_1_amount = 53,000,000
  - remaining_fee = 0 → done

Index Stability

The indices in the fee strategy refer to the original BTreeMap iteration order. The implementation snapshots the address lists before processing any steps, so removing a drained entry at step 1 does not shift the indices for step 2. This is critical for correctness:

#![allow(unused)]
fn main() {
let input_addresses: Vec<PlatformAddress> = inputs.keys().copied().collect();
let output_addresses: Vec<PlatformAddress> = outputs.keys().copied().collect();

for step in fee_strategy {
    match step {
        DeductFromInput(index) => {
            let address = input_addresses[*index as usize];
            // look up by address, not by index into the live BTreeMap
        }
        // ...
    }
}
}

FeeDeductionResult

The deduction algorithm produces:

#![allow(unused)]
fn main() {
pub struct FeeDeductionResult {
    pub remaining_input_balances: BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
    pub adjusted_outputs: BTreeMap<PlatformAddress, Credits>,
    pub fee_fully_covered: bool,
}
}

If fee_fully_covered is false, the transition is rejected.

Nonce System (Replay Protection)

Every platform address has a nonce that starts at 0 and increments by 1 with each transition that uses the address as an input. The transition must specify the expected nonce, which must be exactly current_nonce + 1:

#![allow(unused)]
fn main() {
let expected_next_nonce = state_nonce.saturating_add(1);
if provided_nonce != expected_next_nonce {
    return Err(AddressInvalidNonceError {
        expected: expected_next_nonce,
        provided: provided_nonce,
    });
}
}

This prevents:

• Replay attacks — resubmitting an old transition (wrong nonce)
• Double-spending — using the same balance twice (nonce already consumed)
• Ordering attacks — submitting transitions out of order (nonce gap)

If a nonce reaches u32::MAX, the address is exhausted and cannot be used as an input anymore.

Multiple addresses can be used as inputs in a single transition, each with its own nonce. The platform enforces a maximum number of inputs per transition (configured in platform_version.dpp.state_transitions.max_address_inputs).

The PaidFromAddressInputs Event

When an address-based transition passes validation, the processor creates a PaidFromAddressInputs execution event:

#![allow(unused)]
fn main() {
ExecutionEvent::PaidFromAddressInputs {
    input_current_balances: BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
    added_to_balance_outputs: BTreeMap<PlatformAddress, Credits>,
    fee_strategy: AddressFundsFeeStrategy,
    operations: Vec<DriveOperation>,
    execution_operations: Vec<ValidationOperation>,
    additional_fixed_fee_cost: Option<Credits>,
    user_fee_increase: UserFeeIncrease,
}
}

• input_current_balances — the remaining balance of each input after consuming the requested amounts, plus the validated nonce
• added_to_balance_outputs — the output amounts before any fee deductions
• fee_strategy — the client's ordered fee deduction instructions
• operations — the GroveDB operations (balance updates, nonce bumps)
• execution_operations — validation operations that also incur fees
• additional_fixed_fee_cost — optional fixed costs (e.g., registration fees)
• user_fee_increase — voluntary processing fee multiplier

Fee Validation Pipeline

Address-based fee validation runs in two phases:

Phase 1: Pre-Check (Minimum Balance)

Before expensive state reads, a quick estimate verifies that the inputs have enough credits to cover the minimum possible fee:

#![allow(unused)]
fn main() {
fn validate_addresses_minimum_balance_pre_check(
    &self,
    remaining_address_balances: &BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
    platform_version: &PlatformVersion,
) -> Result<SimpleConsensusValidationResult, Error>
}

This catches obviously insufficient balances early. Only AddressFundsTransfer, AddressCreditWithdrawal, IdentityCreateFromAddresses, and IdentityTopUpFromAddresses run this pre-check. AddressFundingFromAssetLock skips it because its funds come from the asset lock, not existing address balances.

Phase 2: Full Fee Validation

After the operations are determined, the platform:

1. Applies all drive operations (in estimation mode) to calculate the actual FeeResult
2. Adds validation operation costs
3. Applies the user_fee_increase multiplier
4. Adds any additional_fixed_fee_cost
5. Runs the fee strategy to deduct the total from inputs/outputs
6. Checks fee_fully_covered

#![allow(unused)]
fn main() {
let fee_deduction_result = deduct_fee_from_outputs_or_remaining_balance_of_inputs(
    input_current_balances.clone(),
    added_to_balance_outputs.clone(),
    fee_strategy,
    required_balance,
    platform_version,
)?;

if !fee_deduction_result.fee_fully_covered {
    return Err(AddressesNotEnoughFundsError);
}
}

Fee Execution

When the transition is executed, the fee deduction runs a second time with the real (not estimated) fee amount, and the adjusted balances are written to state:

1. Apply all drive operations — the core state changes (transfers, nonce bumps, etc.)
2. Calculate actual fee — from the FeeResult of the applied operations
3. Deduct fee — run the fee strategy against the actual fee amount
4. Adjust outputs — if any output was reduced, call remove_balance_from_address for the difference
5. Adjust inputs — if any input's remaining balance was reduced, call set_balance_to_address with the adjusted amount
6. Apply adjustment operations — batch the balance corrections into GroveDB

The fee goes into the epoch pool just like identity-based fees, and is distributed to proposers at epoch end.

Minimum Fee Calculation

For AddressFundsTransfer, the minimum fee scales with the number of inputs and outputs:

min_fee = num_inputs × address_funds_transfer_input_cost
        + num_outputs × address_funds_transfer_output_cost

With current constants:

For IdentityCreateFromAddresses:

min_fee = identity_create_base_cost + num_keys × identity_key_in_creation_cost

Key Differences from Identity Fees

No Debt, No Refunds

The most significant difference is that address-based transitions have no debt mechanism and no refund mechanism:

• Identity fees can create a negative balance when the processing fee cannot be fully covered. This debt is tracked and must be repaid before the identity can submit new transitions: credits the identity receives while its balance is empty repay the debt first. From protocol version 14 the repaid part goes to the processing fee pool of the epoch it is repaid in, where the unpaid fee would have gone.

• Address fees must be fully covered by available inputs and outputs. If the fee cannot be paid, the transition is rejected outright.

• Identity refunds return credits to the identity when stored data is deleted. The refund is calculated per epoch based on when the data was originally stored.

• Address-based transitions do not produce refundable storage. If an address-based transition stores data and that data is later deleted, no refund is issued to any address.

Example: AddressFundsTransfer

A concrete example of how fees flow for a two-input, two-output transfer:

Transition:
  inputs:  [{A, nonce: 5, amount: 1_000_000_000}, {B, nonce: 3, amount: 500_000_000}]
  outputs: [{C, amount: 800_000_000}, {D, amount: 600_000_000}]
  fee_strategy: [DeductFromInput(0), DeductFromInput(1)]
  user_fee_increase: 0

1. Validate inputs:
   A: state_nonce=4, balance=2_000_000_000 → nonce 5 ✓, balance ≥ 1B ✓
   B: state_nonce=2, balance=700_000_000  → nonce 3 ✓, balance ≥ 500M ✓

   Remaining: A=(5, 1_000_000_000), B=(3, 200_000_000)

2. Pre-check minimum fee:
   min = 2 × 500,000 + 2 × 6,000,000 = 13,000,000
   sum(remaining) = 1,200,000,000 >> 13M ✓

3. Create PaidFromAddressInputs event:
   input_current_balances: {A: (5, 1B), B: (3, 200M)}
   added_to_balance_outputs: {C: 800M, D: 600M}

4. Calculate actual fee:
   storage_fee = 14,000,000  (hypothetical)
   processing_fee = 2,500,000
   total = 16,500,000

5. Apply fee strategy:
   Step 1: DeductFromInput(0) → A: 1B - 16.5M = 983,500,000
   remaining_fee = 0 ✓

6. Execute:
   A.balance = 983,500,000, A.nonce = 5
   B.balance = 200,000,000, B.nonce = 3
   C.balance += 800,000,000
   D.balance += 600,000,000
   16,500,000 → epoch fee pool

Key Source Files

Shielded Transaction Fees

Introduced in protocol version 12. For the general fee system overview, see Fee System Overview. For address-based fees (protocol versions 10--11), see Platform Address Fees.

Shielded transactions use the Orchard protocol's zero-knowledge proofs to hide transaction amounts. Because amounts are hidden, the platform cannot inspect the transaction to compute fees the way it does for transparent transitions. Instead, the fee is embedded into the cryptographic structure of the bundle itself, and the platform enforces a minimum.

This chapter explains the fee model, how it is validated, and how it differs from the transparent and address-based fee systems.

The Problem: Fees in a Privacy System

In a transparent state transition like AddressFundsTransfer, the platform can see the transfer amount, compute the cost of storage and processing, and deduct the fee from the sender's balance. The fee calculation happens after the transition is applied.

Shielded transitions break this model. The amounts inside the ZK proof are hidden. The platform cannot look inside the proof to determine how much was sent or received. It can only see two things from the public fields:

1. value_balance — the net amount leaving the shielded pool (positive means credits flow out of the pool into the transparent world or to proposers as fees)
2. num_actions — the number of spend+output pairs in the bundle

The fee must therefore be encoded into value_balance by the client and validated by the platform before execution.

Fee Extraction by Transition Type

The fee is derived differently depending on the shielded transition type:

Token shielded pool fees

Token pools (protocol version 14, see Token Shielded Pools) hold tokens, and tokens cannot pay fees, so none of the three token pool transitions carves a fee from the bundle. They are TokenTransition variants inside a Batch, and the batch's signing identity pays in credits through the standard identity-paid path.

Because the verification fee is charged before the proof is checked, an invalid proof is a paid failure: the identity is charged, its identity contract nonce advances, and no token moves.

Identity-less token pool transitions

TokenShieldedTransferWithShieldedFee (26), TokenUnshieldWithShieldedFee (27) and TokenPurchaseFromShieldedPool (28) have no identity: the fee is carved from a second bundle spent in the credit shielded pool, exactly as ShieldedTransfer carves its own fee.

The fee bundle's value balance is credit_amount; the minimum-fee validation, the SDK builders and the transformer all use the same compute_token_* function so the threshold never drifts from what is carved. An invalid proof or a spent nullifier is an unpaid rejection: nothing is committed and no fee is charged, the same as for the credit pool's pool-paid transitions.

For ShieldedTransfer, the client constructs the bundle so that total_spent − total_output = desired_fee. The Orchard circuit proves that value is conserved (inputs = outputs + value_balance), and the binding signature cryptographically commits to the value_balance. Mutating value_balance after signing will cause the binding signature to fail verification.

Entry-Transition Fees (Shield, ShieldFromAssetLock, and ShieldFromIdentity)

The entry transitions — Shield (transparent → shielded), ShieldFromAssetLock (Core asset lock → shielded), and, from protocol version 14, ShieldFromIdentity (identity balance → shielded) — move value into the pool, so there is no spent note from which value_balance could carry a fee. Their fees are therefore charged from the funding side, and both cover the same Halo 2 proof verification and per-action work the other shielded transitions pay for — but they account for it differently. Shield debits a state-queryable transparent address balance, so GroveDB meters its real storage/processing and only the compute portion (compute_shielded_verification_fee, no storage term) is added on top. ShieldFromAssetLock is funded by a consumed asset lock with no metering anchor, so it pays the flat compute_minimum_shielded_fee(num_actions) (plus the asset-lock base cost). num_actions is the on-wire action count of the bundle (a single-output, spends-disabled Orchard bundle pads to 2 actions, so the minimum is the 2-action fee).

Every action of an outputs-only bundle still reveals a nullifier, that of a dummy spend, which becomes the new note's rho. From protocol version 14 the entry transitions record those nullifiers and refuse one repeated inside the bundle or already recorded (NullifierAlreadySpentError), as the spends do, so every revealed nullifier is recorded once. Shield and ShieldFromIdentity meter the nullifier writes like the rest of their storage; ShieldFromAssetLock's flat fee already prices a note and a nullifier write per action (see Per-Action Storage Fee).

Shield

Shield is charged like any other address-funded transition: GroveDB meters the real storage and processing cost of applying it (the note-commitment and nullifier writes plus the address-balance updates), and the shielded compute fee is added on top:

fee = metered_storage + metered_processing + shielded_verification_fee
shielded_verification_fee = proof_verification_fee + num_actions × per_action_processing_fee

shielded_verification_fee is the ZK-verification cost (Halo 2 proof + per-action spend-auth verification) that GroveDB metering cannot see. It is added as the transition's additional_fixed_fee_cost — exactly the mechanism IdentityCreateFromAddresses uses for its registration cost. It carries no storage term: storage comes entirely from metering, so it is never double-counted. The address inputs must cover shield_amount + fee, and the booked storage/processing equals the deducted amount, so credits are conserved by the standard machinery (no special-case override).

Shield is skipped by the value_balance-based minimum-fee validation (its value_balance is the amount entering the pool, not a fee). The stateless structure floor requires only shield_amount + shielded_verification_fee (a conservative lower bound, since metered storage is unknowable without state); the authoritative metered + compute funding gate is validate_fees_of_event.

ShieldFromIdentity

ShieldFromIdentity (protocol version 14) is Shield with the identity balance as the funding side. It is identity-signed (TRANSFER key, identity nonce) like IdentityCreditTransferToAddresses, and carries the same outputs-only Orchard bundle as Shield. The fee model is identical to Shield's: GroveDB meters the note and nullifier inserts and the identity balance and nonce writes, and the shielded compute fee is added as additional_fixed_fee_cost:

fee = metered_storage + metered_processing + shielded_verification_fee
identity_balance_after = identity_balance_before - amount - fee

user_fee_increase applies to the metered processing portion. The stateless floor requires identity_balance >= amount + compute_shielded_identity_balance_write_fee, the conservative complete admission estimate: compute_minimum_shielded_fee, plus PV14's versioned shielded_identity_action_write_storage_bytes (400 effective bytes per action) and shielded_identity_balance_write_storage_bytes (500 flat bytes), each priced at the storage rate. The allowances cover the complete execution-event estimate: note/nullifier writes at the estimator's depth 16, identity nonce/balance writes at its maximum-element depth, and the signature and state-read validation context. They are admission reserves, not physical payload sizes or changes to the actual metered charge. For two actions the base wallet estimate is 114,140,000 + (2 × 400 + 500) × 27,400 = 149,760,000 credits. Historical tables preserve the preceding zero per-action and 20-byte flat allowance. An identity that could not pay the complete fee is therefore refused before the Orchard proof is verified. The authoritative gate is the identity-paid fee validation of the execution event (Paid), which rejects with IdentityInsufficientBalanceError. The identity balance and the pool total are both terms of the block conservation equation, so the converter emits no AddToSystemCredits (the same rule Unshield and IdentityCreateFromShieldedPool follow).

A failed Orchard proof is a paid failure, not a free rejection. Like ShieldFromAssetLock, the proof is verified inside the transition's own transform rather than in the shared stateless proof step: on failure the transition executes as a BumpIdentityNonceAction, consuming the identity nonce and charging the identity the versioned shielded_proof_verification_failure penalty on top of the processing metered so far. This closes the path where a funded identity could resubmit invalid proofs indefinitely with its nonce and balance left untouched. CheckTx never charges; it admits the verification under its node-local proof budget only after the cheap checks passed, and rejects on failure.

ShieldFromAssetLock

The asset lock funds the pool, so the fee is taken from the consumed asset-lock value. The pool fee is:

pool_fee = compute_minimum_shielded_fee(num_actions) + asset_lock_base_cost

asset_lock_base_cost is the same asset-lock-proof processing base cost charged to every asset-lock-funded transition (e.g. IdentityCreate): required_asset_lock_duff_balance_for_processing_start_for_address_funding (50,000 duffs) × CREDITS_PER_DUFF (1,000) = 50,000,000 credits. Adding it makes the ShieldFromAssetLock pool fee strictly greater than the bare F paid by the transparent Shield, pricing the extra cost of verifying the Core asset-lock proof.

The asset lock must cover shield_amount + pool_fee; the remainder is the surplus:

surplus = consumed_asset_lock_value − shield_amount − pool_fee   (always ≥ 0)

The surplus is disposed of in one of two ways:

• surplus_output set — the transition carries an optional Option<PlatformAddress> surplus_output. When present, surplus is credited to that platform address (via an AddBalanceToAddress drive operation). This field is part of the signed payload (it sits before the signature field, which alone is excluded from the sighash), so a surplus recipient cannot be substituted or truncated after signing.
• surplus_output unset — the surplus folds into the fee pools, but only up to shielded_implicit_fee_cap (20,000,000,000 credits = 0.2 DASH, a versioned constant). If the unclaimed surplus would exceed the cap, the transition is rejected with ShieldedImplicitFeeCapExceededError so a client cannot accidentally donate a large remainder to proposers. To intentionally over-fund, the client must set surplus_output (which has no cap).

Value conservation across the whole transition is exact:

consumed_asset_lock_value = shield_amount + surplus_amount + fee_amount

where surplus_amount is surplus when surplus_output is set and 0 otherwise (in which case the surplus is part of fee_amount).

The Three-Component Fee Model

The minimum shielded fee has three components:

min_fee = proof_verification_fee + num_actions × (processing_fee + storage_fee)

1. Proof Verification Fee (per bundle)

A single Halo 2 ZK proof covers the entire bundle regardless of action count. The bundle's base verification work is benchmarked at approximately 5 ms. This is a fixed cost per bundle.

Protocol version 14 value: 40,000,000 credits (40M)

2. Per-Action Processing Fee

The per-action processing fee prices the marginal Halo 2 verification work that each additional action adds to the bundle (≈1.1 ms/action measured against a ≈5 ms bundle base): a bundle with more actions is a larger circuit and a longer batch verification. For a spend-bearing action that marginal work includes:

• RedPallas spend authorization signature verification
• Nullifier duplicate check (hash + tree lookup)
• Note commitment insertion into the Sinsemilla-based Merkle tree

Output-only entry transitions (Shield / ShieldFromAssetLock / ShieldFromIdentity) do no spends, but each output action still enlarges the proof and so carries the same per-action processing charge — this fee tracks the marginal verification work, not a fixed per-action checklist. From protocol version 14 it also prices the check of the nullifier each of their actions reveals.

At protocol version 14, the proof and per-action fees are versioned independently. Their numerical ratio is about 1.8:1 (40M : 22M).

Current value: 22,000,000 credits (22M)

3. Per-Action Storage Fee

Each action permanently stores data in two places:

Protocol version 14 prices a 550-byte allowance per action, covering the physical payload and database framing, at the platform's per-byte storage rates:

storage_fee_per_action = 550 × (storage_disk_usage_credit_per_byte
                              + storage_processing_credit_per_byte)
                       = 550 × (27,000 + 400)
                       = 550 × 27,400
                       = 15,070,000

The byte allowance is versioned. Its per-byte rates come from the storage fee version, so the fee tracks changes to those rates.

Fee Table

Combining all three components at protocol version 14:

Note: The Orchard protocol requires a minimum of 2 actions per bundle for privacy (even a single-input single-output transfer produces 2 actions with a dummy padding action). Bundles with 1 action are structurally invalid.

The totals above are the base compute_minimum_shielded_fee and apply directly to ShieldedTransfer. The three pool-paid transitions that write one extra per-transition output add a flat component on top of this base:

• Unshield adds the output-address write cost: a flat unshield_address_storage_fee = 222 × per_byte_rate = 222 × 27,400 = 6,082,800 credits, independent of action count. So the 2-action Unshield fee is 114,140,000 + 6,082,800 = 120,222,800 credits (and likewise +6,082,800 at every action count). See the Fee Extraction Unshield row for why this component exists.
• ShieldedWithdrawal adds the Core withdrawal-document storage cost: a flat withdrawal_document_storage_fee = 4100 × per_byte_rate = 4100 × 27,400 = 112,340,000 credits, independent of action count. So the 2-action ShieldedWithdrawal fee is 114,140,000 + 112,340,000 = 226,480,000 credits (and likewise +112,340,000 at every action count). See the Fee Extraction ShieldedWithdrawal row for why this component exists.
• IdentityTopUpFromShieldedPool adds the identity balance write cost: a flat identity_balance_storage_fee = 8 × per_byte_rate = 8 × 27,400 = 219,200 credits, independent of action count, so the top-up fee at any action count is the base plus 219,200. See the Fee Extraction IdentityTopUpFromShieldedPool row for why this component is so much smaller than the address write: it rewrites an existing balance element instead of storing a new entry.

Where Fee Validation Runs

Fee validation is integrated into the processor pipeline (see Validation Pipeline) between basic structure validation and ZK proof verification:

... → Basic Structure → Minimum Fee Check → ZK Proof Verification → ...

The ordering is deliberate. The fee check is stateless and cheap — it only reads value_balance and actions.len() from the transition, with no GroveDB lookups. Placing it before proof verification means that bundles with insufficient fees are rejected instantly, without spending ~100ms on Halo 2 verification.

The implementation lives in packages/rs-drive-abci/src/execution/validation/state_transition/processor/traits/shielded_proof.rs:

#![allow(unused)]
fn main() {
pub(crate) trait StateTransitionShieldedMinimumFeeValidationV0 {
    fn validate_minimum_shielded_fee(
        &self,
        platform_version: &PlatformVersion,
    ) -> Result<SimpleConsensusValidationResult, Error>;
}
}

If the fee is below the minimum, the transition is rejected with InsufficientShieldedFeeError — an unpaid consensus error. The sender is not charged (there is no identity to charge), and the transition produces no execution event.

Fee Constants in the Version System

The fee parameters are stored in the platform version under drive_abci.validation_and_processing.event_constants:

#![allow(unused)]
fn main() {
pub struct DriveAbciValidationConstants {
    pub maximum_vote_polls_to_process: u16,
    pub maximum_contenders_to_consider: u16,
    pub minimum_pool_notes_for_outgoing: u64,
    pub shielded_anchor_retention_blocks: u64,
    pub shielded_anchor_pruning_interval: u64,
    pub shielded_proof_verification_fee: u64,      // 40_000_000 at protocol 14
    pub shielded_per_action_processing_fee: u64,    // 22_000_000
    pub shielded_storage_bytes_per_action: u64,     // 550 at protocol 14
    pub shielded_implicit_fee_cap: u64,             // 20_000_000_000 (0.2 DASH)
}
}

The shielded_implicit_fee_cap bounds the surplus that a ShieldFromAssetLock may implicitly donate to the fee pools when no surplus_output is set (see Entry-Transition Fees).

The storage component is derived at runtime from fee_version.storage.storage_disk_usage_credit_per_byte and fee_version.storage.storage_processing_credit_per_byte, multiplied by the versioned shielded_storage_bytes_per_action allowance.

This design means:

• Proof and processing fees can be tuned independently via version bumps
• Storage fees automatically track changes to the platform-wide storage rates
• Storage allowances can be calibrated independently of the per-byte rates

How Fees Flow After Validation

Once the fee check passes and the transition is fully validated and executed, the shielded pool's total balance is decremented and the fee is booked via the PaidFromShieldedPool execution event:

ShieldedTransfer:              pool_balance -= fee_amount          // fee == value_balance
Unshield:                      pool_balance -= unshielding_amount   // gross
ShieldedWithdrawal:            pool_balance -= unshielding_amount   // gross
IdentityTopUpFromShieldedPool: pool_balance -= top_up_amount        // gross

For Unshield and ShieldedWithdrawal, unshielding_amount is the gross amount leaving the pool. Of that, unshielding_amount − fee_amount is credited to the output platform address (Unshield) or written into the Core withdrawal document (ShieldedWithdrawal), and fee_amount is booked as the transition fee. For Unshield that fee is compute_shielded_unshield_fee — the base fee plus the flat AddBalanceToAddress output-write storage cost (+6,082,800 credits), since Unshield also writes the net to a transparent platform address. For ShieldedWithdrawal it is compute_shielded_withdrawal_fee — the same base fee plus the flat Core withdrawal-document storage cost (+112,340,000 credits), since ShieldedWithdrawal also writes a real document into the withdrawals contract. Validation guarantees unshielding_amount ≥ fee_amount (and, for ShieldedWithdrawal, that the net also clears MIN_WITHDRAWAL_AMOUNT), so the subtraction never underflows. Because each fee prices its extra write, the booking split (storage routed to the storage pool, the remainder paid to the proposer) covers that write instead of zeroing the proposer's processing reward to cover it.

For IdentityTopUpFromShieldedPool, top_up_amount is likewise the gross amount leaving the pool: top_up_amount − fee_amount is added to the existing identity's balance and fee_amount (compute_shielded_identity_top_up_fee, the base fee plus the flat identity balance write component) is booked as the transition fee; validation guarantees top_up_amount ≥ fee_amount. The identity balance and the pool total are both terms of the block conservation equation, so no system-credit adjustment is emitted.

For ShieldedTransfer, the pool decreases by exactly the fee (the sender's notes are spent and the recipient's notes are created, but the pool's aggregate balance only drops by the fee).

In all cases the booked fee_amount is split the same way as every other transition's fee: the storage cost of the permanent shielded writes is routed to the storage pool (amortized across epochs and subject to the per-epoch fee multiplier at payout), and the remainder — proof verification plus per-action processing — is the processing fee paid to the current block proposer.

The three entry transitions (Shield, ShieldFromAssetLock, ShieldFromIdentity) do not decrement the pool (they add to it), so their fees are booked from the funding side instead:

Shield:              fee_amount = metered + shielded_verification_fee     // from transparent address inputs
ShieldFromAssetLock: fee_amount = pool_fee (+ unclaimed surplus)     // from the consumed asset lock

For Shield, the fee is deducted from the transparent address inputs and booked through the standard PaidFromAddressInputs event (deducted == booked, no override): metered storage and processing, plus the shielded_verification_fee folded into processing. For ShieldFromAssetLock, the consumed asset-lock value is partitioned into shield_amount (into the pool), surplus_amount (to surplus_output, or 0), and fee_amount (to the fee pools); see Entry-Transition Fees.

Cryptographic Binding

The fee is not just a field that the platform trusts. It is cryptographically bound to the ZK proof through two mechanisms:

1. Value commitments (cv_net): Each action contains a Pedersen commitment to the note value. The sum of all value commitments must equal value_balance (modulo the blinding factors). The binding signature proves this relationship holds.

2. Platform sighash: The bundle commitment (which includes value_balance) is hashed into the sighash that the spend authorization signatures sign over:

   sighash = SHA-256("DashPlatformSighash" || bundle_commitment || extra_data)
   

   Mutating value_balance after signing changes the sighash, invalidating all signatures. The BatchValidator checks both the Halo 2 proof and all signatures, so any tampering is caught.

This means a client cannot claim a lower fee than what the ZK proof actually commits to — the proof and signatures would fail verification.

Rules and Guidelines

Do:

• Always set value_balance to at least the minimum fee when building a shielded bundle on the client side. Use min_fee = proof_verification_fee + num_actions × (processing_fee + storage_fee) with the current platform version constants.
• Include the fee in the note arithmetic: total_spent = total_output + fee. The Orchard builder handles this when you set the output amount to spend_amount − desired_fee.
• Remember that the minimum action count is 2 (Orchard privacy requirement).

Do not:

• Assume the fee is free for Shield transitions — the fee comes from transparent address inputs and is validated through the address balance system, not here.
• Mutate value_balance after building the bundle. The binding signature and sighash will be invalidated.
• Hardcode fee amounts. Always read from PlatformVersion — the constants are versioned and will change as the protocol evolves.

What a Document Costs

drive::document::cost computes what creating one document costs, from the contract alone. The JavaScript SDKs expose it as documentCreateCost(contract, documentTypeName, options, platformVersion), which is what the contract visualizer shows per document type.

Amounts are in credits: 1 Dash is 100,000,000,000 credits.

Storage

The storage fee is the bytes the insert adds times storage_disk_usage_credit_per_byte (27,000 credits from protocol version 14). It is usually almost all of what a document costs.

The estimate is exact. It lists every element the insert writes (see GroveDB Structure for the layout), built with the functions the insert walkers use:

• the document by id, or with documentsKeepHistory a tree of revisions and a pointer to the newest;
• for each index, the value trees along its properties (created only when no earlier document has the value), the [0] terminal and the document's reference in it, or an indexOnly type's entry;
• the rows a ranked index keeps for the value in its secondary trees, one per ranking axis;
• the trees preallocated for other document types' preallocated indexes whose entries will reference the document, charged to its creator.

Each element is priced with GroveDB's byte formulas: the key with the 32-byte subtree prefix, the serialized element (or a fixed size standing for a tree), the value and node hashes, the aggregate feature of the tree it sits in (8 or 16 bytes in a count or sum tree), and the link its parent keeps to it. A document create's elements carry 35 bytes of storage flags (the owner and the epoch); index trees carry them only when the documents are mutable, the contract can be deleted, or the type is indexOnly and its documents can be deleted.

The storage depends on what is already stored, so it comes in two scenarios:

• every value new: the first document with these index values creates their trees;
• every value known: a later document with the same values adds only its own entries. A unique index still adds its value, which no earlier document can hold, as does every tree keyed by the document's own id (a preallocated index's, say) and a ttl document's expiration entry; a ranked index's row for an existing value only moves, which GroveDB bills as replaced bytes.

The estimate also splits the storage by index: the layers an index shares with other indexes (a common prefix of properties, paid once for the document) and the layers only it uses, so an index's cost on its own is its shared layers plus its own. A skipIfAbsent index that skips the document writes nothing, and adds no layer, just as Drive builds none for it; the rows of a ranked level under a time window with a ttl are priced like the window, as processing.

The test should_price_what_drive_charges inserts documents into 21 contracts covering every index shape and requires the estimate to equal the storage fee Drive charged, byte for byte, with the trees already stored read from GroveDB before each insert.

Processing

• Exact: verifying the signature (15,000 credits for an ECDSA key, 300,000 for BLS) and fetching the signing key and the identity's balance (18,000).
• Estimated: the work of the writes (seeks, hashing and rewriting the path to each new element in its tree and above), for an assumed number of stored documents, each with its own values (1,000 by default); and the small reads and writes around the insert (the document id check and the identity's contract nonce). The test should_estimate_the_processing_of_the_writes_within_a_factor_of_two holds the write estimate to Drive's processing fee. Processing is a few percent of a document's cost.
• A userFeeIncrease raises the processing fee only.

The per-document "minimum fee" of a batch (document_batch_sub_transition) is a balance check before processing, not a charge, and the unique index checks and the fetch of the batch's own contract are not billed.

What the contract adds

• Action fees (actionFees): the create's fee, in credits, scaled by the epoch's fee multiplier unless priced as fixed, paid into the contract's fee pots.
• Token cost (tokenCost): tokens transferred to the contract owner or burned.
• Contest fund: a contested index's vote fund (0.1 Dash, doubling past 250 contenders), paid when the value is contested.

Refunds

Deleting a document refunds the storage fee of its flagged elements, less what the epochs already passed were paid: about 99.9% in the epoch it was created, about 95% a year later, then less each year for fifty years.

Documents with a ttl

A document whose type declares a ttl is stored without flags and pays for its bytes by the lifetime it has left, all of its ttl when it is created, at the schedule's tier for that lifetime (from 1 credit per byte for an hour to 26 for a week, then 34 per 788,400 seconds) instead of the 27,000 of storage kept for good. It also adds its entry to the documents expirations tree, and prepays its deletion as processing (a base cost, a cost per index level and one per document byte). Nothing of it is refunded.

Not covered

• A create whose value starts a contest (a DPNS name matching the contest rule, say) is stored in the contest's vote poll until the contest ends, not in the index. The estimate prices an uncontested create and lists the contest fund; the vote poll's storage is not priced.
• A platform version whose insert methods differ from protocol version 14's is refused: other versions write other elements for some shapes.

Consensus Errors

When a Dash Platform node processes a state transition -- a document creation, an identity update, a credit withdrawal -- things can go wrong. The data contract might reference an invalid schema. The signature might not match. The identity might not have enough balance. These are not internal bugs; they are protocol-level validation failures that every node on the network must agree on. If one node rejects a transition for reason X and another rejects it for reason Y, the chain forks. If one node returns error code 40100 and another returns 40101, clients break.

This is why consensus errors in Dash Platform are not ordinary Rust errors. They are serializable, code-stable, network-transmitted data structures that must produce identical bytes on every node and remain decodable by every client version. The ConsensusError enum is the heart of this system.

The top-level enum

Open packages/rs-dpp/src/errors/consensus/consensus_error.rs and you will find the root of the hierarchy:

#![allow(unused)]
fn main() {
#[derive(
    thiserror::Error,
    Debug,
    Encode,
    Decode,
    PlatformSerialize,
    PlatformDeserialize,
    Clone,
    PartialEq,
)]
#[platform_serialize(limit = 2000)]
#[error(transparent)]
#[allow(clippy::large_enum_variant)]
pub enum ConsensusError {
    /*

    DO NOT CHANGE ORDER OF VARIANTS WITHOUT INTRODUCING OF NEW VERSION

    */
    #[error("default error")]
    DefaultError,

    #[error(transparent)]
    BasicError(BasicError),

    #[error(transparent)]
    StateError(StateError),

    #[error(transparent)]
    SignatureError(SignatureError),

    #[error(transparent)]
    FeeError(FeeError),

    #[cfg(test)]
    #[cfg_attr(test, error(transparent))]
    TestConsensusError(TestConsensusError),
}
}

There are five things worth understanding here.

The four categories

Every consensus error falls into one of four categories:

• BasicError -- structural and syntactic validation failures. The state transition itself is malformed, references a nonexistent document type, has an invalid identifier, exceeds size limits, or fails schema validation. These are caught before the node ever checks persistent state. The BasicError enum in packages/rs-dpp/src/errors/consensus/basic/basic_error.rs contains over 130 variants organized into sub-groups: versioning errors, structure errors, data contract errors, group errors, document errors, token errors, identity errors, state transition errors, and address errors.

• StateError -- the transition is structurally valid but conflicts with the current platform state. A document already exists, an identity nonce is wrong, a token account is frozen, a group action was already completed. The StateError enum in packages/rs-dpp/src/errors/consensus/state/state_error.rs contains roughly 80 variants covering data contracts, documents, identities, voting, tokens, groups, and address balances.

• SignatureError -- the cryptographic signature on the transition is invalid. The identity was not found, the key type is wrong, the key is disabled, the security level is insufficient, or the raw signature verification failed.

• FeeError -- the transition is valid in every other way, but the identity cannot pay for it. Currently this category has a single variant: BalanceIsNotEnoughError.

This layered structure mirrors the validation pipeline. Platform checks basic structure first, then state, then signatures, then fees. Each layer produces errors from its own category.

The DO NOT CHANGE ORDER rule

The comment at the top of every consensus error enum is not a suggestion:

#![allow(unused)]
fn main() {
/*

DO NOT CHANGE ORDER OF VARIANTS WITHOUT INTRODUCING OF NEW VERSION

*/
}

Why? Because ConsensusError derives Encode and Decode from bincode. Bincode serializes enum variants by their ordinal position -- the first variant is 0, the second is 1, and so on. If you reorder variants, the same bytes now decode to a different error on nodes running different code versions. This is a consensus failure.

The same rule applies to every nested error enum. Here is FeeError in packages/rs-dpp/src/errors/consensus/fee/fee_error.rs:

#![allow(unused)]
fn main() {
#[derive(
    Error, Debug, PartialEq, Encode, Decode, PlatformSerialize, PlatformDeserialize, Clone,
)]
pub enum FeeError {
    /*

    DO NOT CHANGE ORDER OF VARIANTS WITHOUT INTRODUCING OF NEW VERSION

    */
    #[error(transparent)]
    BalanceIsNotEnoughError(BalanceIsNotEnoughError),
}
}

And the same rule applies to individual error structs. Here is DocumentAlreadyPresentError in packages/rs-dpp/src/errors/consensus/state/document/document_already_present_error.rs:

#![allow(unused)]
fn main() {
#[derive(
    Error, Debug, Clone, PartialEq, Eq, Encode, Decode, PlatformSerialize, PlatformDeserialize,
)]
#[error("Document {document_id} is already present")]
#[platform_serialize(unversioned)]
pub struct DocumentAlreadyPresentError {
    /*

    DO NOT CHANGE ORDER OF FIELDS WITHOUT INTRODUCING OF NEW VERSION

    */
    document_id: Identifier,
}
}

Notice the comment says fields too, not just variants. Bincode serializes struct fields in declaration order. Swap two fields and the bytes change.

The derive stack

Every consensus error type carries the same set of derives:

#![allow(unused)]
fn main() {
#[derive(
    Error,              // thiserror -- provides Display and Error trait
    Debug,              // standard Rust debug formatting
    Clone,              // errors need to be cloneable
    PartialEq,          // errors need to be comparable
    Encode,             // bincode encoding (field-level)
    Decode,             // bincode decoding (field-level)
    PlatformSerialize,  // platform wrapper around bincode (size limits, etc.)
    PlatformDeserialize,// platform wrapper around bincode
)]
}

The thiserror::Error derive gives each variant a Display implementation. For enums, #[error(transparent)] delegates to the inner type's Display. For leaf structs, you write the message directly:

#![allow(unused)]
fn main() {
#[error("Document {document_id} is already present")]
pub struct DocumentAlreadyPresentError {
    document_id: Identifier,
}
}

The Encode and Decode derives come from bincode and handle the actual byte-level serialization of each field. The PlatformSerialize and PlatformDeserialize derives are the platform's own wrappers that add size limits and error type conversion on top of bincode. We will cover those in the serialization chapters.

The #[platform_serialize] attribute

On the top-level ConsensusError, you will notice:

#![allow(unused)]
fn main() {
#[platform_serialize(limit = 2000)]
}

This sets a maximum serialized size of 2000 bytes. If a consensus error somehow serializes to more than 2000 bytes, the platform will return a MaxEncodedBytesReachedError instead. This is a defense against oversized error payloads being transmitted across the network.

On individual leaf error structs, you will see a different attribute:

#![allow(unused)]
fn main() {
#[platform_serialize(unversioned)]
}

The unversioned flag means the struct does not need a PlatformVersion parameter for serialization. Most leaf error structs are simple enough that they do not change between protocol versions -- their serialization format is stable. The top-level ConsensusError enum does not use unversioned because it may need version-aware behavior as the protocol evolves.

How errors nest

The nesting is three levels deep:

1. ConsensusError -- the top level, with four category variants
2. Category enums (BasicError, StateError, SignatureError, FeeError) -- each holds dozens of specific error variants
3. Leaf error structs -- the actual error data (identifiers, messages, amounts)

Each level has From implementations to make conversion ergonomic:

#![allow(unused)]
fn main() {
// Leaf -> Category
impl From<DocumentAlreadyPresentError> for ConsensusError {
    fn from(err: DocumentAlreadyPresentError) -> Self {
        Self::StateError(StateError::DocumentAlreadyPresentError(err))
    }
}

// Category -> Top-level
impl From<StateError> for ConsensusError {
    fn from(error: StateError) -> Self {
        Self::StateError(error)
    }
}
}

This means you can use ? to propagate any leaf error up to a ConsensusError:

#![allow(unused)]
fn main() {
fn validate_document(doc: &Document) -> Result<(), ConsensusError> {
    if document_exists(doc.id()) {
        return Err(DocumentAlreadyPresentError::new(doc.id()).into());
    }
    Ok(())
}
}

The .into() call walks the From chain: DocumentAlreadyPresentError -> ConsensusError::StateError(StateError::DocumentAlreadyPresentError(...)).

Anatomy of a leaf error

Every leaf error follows the same pattern. Let us look at the full DocumentAlreadyPresentError:

#![allow(unused)]
fn main() {
use crate::consensus::state::state_error::StateError;
use crate::consensus::ConsensusError;
use crate::errors::ProtocolError;
use bincode::{Decode, Encode};
use platform_serialization_derive::{PlatformDeserialize, PlatformSerialize};
use platform_value::Identifier;
use thiserror::Error;

#[derive(
    Error, Debug, Clone, PartialEq, Eq, Encode, Decode, PlatformSerialize, PlatformDeserialize,
)]
#[error("Document {document_id} is already present")]
#[platform_serialize(unversioned)]
pub struct DocumentAlreadyPresentError {
    /*

    DO NOT CHANGE ORDER OF FIELDS WITHOUT INTRODUCING OF NEW VERSION

    */
    document_id: Identifier,
}

impl DocumentAlreadyPresentError {
    pub fn new(document_id: Identifier) -> Self {
        Self { document_id }
    }

    pub fn document_id(&self) -> &Identifier {
        &self.document_id
    }
}

impl From<DocumentAlreadyPresentError> for ConsensusError {
    fn from(err: DocumentAlreadyPresentError) -> Self {
        Self::StateError(StateError::DocumentAlreadyPresentError(err))
    }
}
}

The pattern is:

1. Fields are private with getter methods
2. A new() constructor
3. A From impl that chains through the category enum to ConsensusError
4. The full derive stack including PlatformSerialize and PlatformDeserialize
5. The #[platform_serialize(unversioned)] attribute
6. The ordering warning comment

The test-only variant

You may have noticed this in ConsensusError:

#![allow(unused)]
fn main() {
#[cfg(test)]
#[cfg_attr(test, error(transparent))]
TestConsensusError(TestConsensusError),
}

This variant only exists in test builds. It allows tests to create synthetic consensus errors without depending on real validation logic. The #[cfg(test)] attribute ensures it is completely stripped from production builds and does not affect the binary encoding of the other variants.

Rules

Do:

• Always add new variants at the end of the enum
• Always add new fields at the end of the struct
• Always include the ordering warning comment in new error types
• Always implement From<YourError> for ConsensusError through the appropriate category
• Always derive the full stack: Error, Debug, Clone, PartialEq, Encode, Decode, PlatformSerialize, PlatformDeserialize
• Use #[platform_serialize(unversioned)] on leaf error structs
• Keep fields private with getter methods

Do not:

• Reorder existing variants or fields -- this breaks network serialization
• Remove existing variants -- old nodes might still produce them
• Change the #[error(...)] message without considering client-side parsing
• Add large fields to error structs -- the 2000-byte limit on ConsensusError applies to the entire serialized tree
• Use #[platform_serialize(limit = ...)] on leaf structs -- the limit is enforced at the ConsensusError level

Error Codes

In the previous chapter we saw how ConsensusError organizes errors into a tree of enums and structs. But when a client -- whether a JavaScript SDK, a mobile app, or a third-party tool -- receives a validation failure from the platform, it does not receive a Rust enum. It receives bytes on a wire. To make those bytes useful, every consensus error maps to a stable numeric code through the ErrorWithCode trait.

These codes are the public API of the error system. They appear in gRPC responses, they are documented for client developers, and they must never change once assigned. A client that handles error code 40100 ("document already present") today must still be able to handle that same code a year from now, even after dozens of protocol upgrades.

The ErrorWithCode trait

The trait lives in packages/rs-dpp/src/errors/consensus/codes.rs and is as simple as it gets:

#![allow(unused)]
fn main() {
pub trait ErrorWithCode {
    /// Returns the error code
    fn code(&self) -> u32;
}
}

One method, one number, no room for ambiguity. The trait is implemented for ConsensusError and for each of the four category enums.

How ConsensusError delegates

The top-level implementation just forwards to the appropriate category:

#![allow(unused)]
fn main() {
impl ErrorWithCode for ConsensusError {
    fn code(&self) -> u32 {
        match self {
            Self::BasicError(e) => e.code(),
            Self::SignatureError(e) => e.code(),
            Self::StateError(e) => e.code(),
            Self::FeeError(e) => e.code(),

            #[cfg(test)]
            ConsensusError::TestConsensusError(_) => 1000,
            ConsensusError::DefaultError => 1, // this should never happen
        }
    }
}
}

The DefaultError variant returns code 1 -- a sentinel value that should never appear in practice. The TestConsensusError returns 1000, safely outside any production range.

The code ranges

Error codes are organized into ranges that correspond to error categories and subcategories. Here is the complete map as it stands in the codebase:

BasicError codes (10000-10949)

SignatureError codes (20000-20012)

#![allow(unused)]
fn main() {
impl ErrorWithCode for SignatureError {
    fn code(&self) -> u32 {
        match self {
            Self::IdentityNotFoundError { .. } => 20000,
            Self::InvalidIdentityPublicKeyTypeError { .. } => 20001,
            Self::InvalidStateTransitionSignatureError { .. } => 20002,
            Self::MissingPublicKeyError { .. } => 20003,
            Self::InvalidSignaturePublicKeySecurityLevelError { .. } => 20004,
            Self::WrongPublicKeyPurposeError { .. } => 20005,
            Self::PublicKeyIsDisabledError { .. } => 20006,
            Self::PublicKeySecurityLevelNotMetError { .. } => 20007,
            Self::SignatureShouldNotBePresentError(_) => 20008,
            Self::BasicECDSAError(_) => 20009,
            Self::BasicBLSError(_) => 20010,
            Self::InvalidSignaturePublicKeyPurposeError(_) => 20011,
            Self::UncompressedPublicKeyNotAllowedError(_) => 20012,
        }
    }
}
}

Signature errors occupy the 20000 range. There are only 13 of them -- cryptographic validation is relatively binary (the signature is valid or it is not), so there are fewer failure modes to distinguish.

FeeError codes (30000)

#![allow(unused)]
fn main() {
impl ErrorWithCode for FeeError {
    fn code(&self) -> u32 {
        match self {
            Self::BalanceIsNotEnoughError { .. } => 30000,
        }
    }
}
}

The fee category currently has a single code. The 30000 range is reserved for future fee-related errors.

StateError codes (40000-41299)

Notice how the DataTriggerError sub-enum has its own ErrorWithCode implementation that the StateError delegates to:

#![allow(unused)]
fn main() {
impl ErrorWithCode for StateError {
    fn code(&self) -> u32 {
        match self {
            // ...
            // Data trigger errors: 40500-40699
            Self::DataTriggerError(ref e) => e.code(),
            // ...
        }
    }
}

impl ErrorWithCode for DataTriggerError {
    fn code(&self) -> u32 {
        match self {
            Self::DataTriggerConditionError { .. } => 40500,
            Self::DataTriggerExecutionError { .. } => 40501,
            Self::DataTriggerInvalidResultError { .. } => 40502,
        }
    }
}
}

This is the only case where StateError delegates to a sub-enum rather than mapping directly. All other state error variants map to their codes inline.

The pattern: one variant, one code, one match arm

Look at how codes are assigned inside BasicError:

#![allow(unused)]
fn main() {
impl ErrorWithCode for BasicError {
    fn code(&self) -> u32 {
        match self {
            // Versioning Errors: 10000-10099
            Self::UnsupportedVersionError(_) => 10000,
            Self::ProtocolVersionParsingError { .. } => 10001,
            Self::SerializedObjectParsingError { .. } => 10002,
            Self::UnsupportedProtocolVersionError(_) => 10003,
            Self::IncompatibleProtocolVersionError(_) => 10004,
            Self::VersionError(_) => 10005,
            Self::UnsupportedFeatureError(_) => 10006,

            // Structure Errors: 10100-10199
            Self::JsonSchemaCompilationError(..) => 10100,
            Self::JsonSchemaError(_) => 10101,
            // ...
        }
    }
}
}

Every single variant gets its own match arm and its own code. There is no default case, no wildcard, no range-based mapping. This is deliberate -- if you add a new variant to the enum and forget to add a code for it, the Rust compiler will refuse to compile because the match is non-exhaustive. The type system enforces completeness.

Nested ContractError patterns

One interesting detail is how BasicError handles DataContractError variants. The ContractError wrapper contains a nested enum, so the code mapping matches through two levels:

#![allow(unused)]
fn main() {
Self::ContractError(DataContractError::DocumentTypesAreMissingError { .. }) => 10214,
Self::ContractError(DataContractError::DecodingContractError { .. }) => 10222,
Self::ContractError(DataContractError::DecodingDocumentError { .. }) => 10223,
Self::ContractError(DataContractError::InvalidDocumentTypeError { .. }) => 10224,
Self::ContractError(DataContractError::MissingRequiredKey(_)) => 10225,
Self::ContractError(DataContractError::FieldRequirementUnmet(_)) => 10226,
// ... many more
}

Each specific DataContractError variant gets its own distinct code. This ensures that clients can distinguish between "the contract is missing a required key" (10225) and "the contract has a wrong type for a value" (10228) even though both come wrapped in BasicError::ContractError.

Adding a new error code

Here is the procedure for adding a new consensus error:

1. Choose the category. Is it a structural validation issue (BasicError), a state conflict (StateError), a signature problem (SignatureError), or a fee issue (FeeError)?

2. Choose the subcategory range. Look at the existing ranges within that category. If your error is about tokens in StateError, you would use the 40700-40799 range.

3. Pick the next available code. Within the range, find the highest existing code and add 1. Never reuse a code, even if the original error was removed.

4. Add the variant to the appropriate enum (at the end -- remember the ordering rule).

5. Add the match arm to the ErrorWithCode implementation.

6. Document the code so client developers know what it means.

Here is what the diff would look like for adding a hypothetical new token state error:

#![allow(unused)]
fn main() {
// In state_error.rs -- add at the end of the enum:
#[error(transparent)]
TokenNewError(TokenNewError),

// In codes.rs -- add to the StateError match:
Self::TokenNewError(_) => 40722,  // next available in the 40700 range
}

Why codes can never change

Consider what happens if code 40100 is changed from DocumentAlreadyPresentError to something else:

• A client SDK has a handler for code 40100 that displays "This document already exists" to the user.
• After the change, the platform sends 40100 for a completely different error.
• The user sees "This document already exists" when actually their token balance is insufficient.
• Trust in the platform erodes.

Error codes are part of the platform's wire protocol. They are as immutable as protobuf field numbers or HTTP status codes. Once assigned, they live forever.

Rules

Do:

• Assign new codes at the end of the appropriate range
• Use the compiler's exhaustive match checking to ensure every variant has a code
• Keep codes within their designated range (do not put a document error in the identity range)
• Leave gaps between ranges for future expansion (this is already done)

Do not:

• Change an existing error code -- ever
• Reuse a code from a removed error variant
• Add a wildcard (_) match arm to ErrorWithCode implementations
• Assign codes outside the established ranges without allocating a new range first
• Skip codes within a range (assign sequentially within each subcategory)

Drive Errors

The previous two chapters covered consensus errors -- the carefully serialized, code-stable errors that get sent across the network. Drive errors are a different beast entirely. They are internal errors that arise from the storage layer, the database, and the logic that sits between state transitions and GroveDB. They are not serialized as consensus errors, and they do not need stable numeric codes. The one place they reach a client is a query's gRPC status, described in Query errors on the wire.

But they do need to be well-organized, because Drive is where most of the platform's complexity lives. When something goes wrong in Drive, you need to know immediately whether it is a corrupted database, a protocol-level validation failure, a fee calculation error, or a bug in your own code.

Query errors on the wire

A gRPC query answers a failed request with a status code, and clients read that code to decide whose fault the failure is. rs-dapi-client takes INVALID_ARGUMENT as the caller's mistake: the error goes back to the caller, and nothing else happens. It takes UNKNOWN and INTERNAL as a fault of the node: the client stops using that node for a while (a ban) and sends the request to the next one. A request error answered as INTERNAL therefore gets every node banned in turn, since every node refuses the request the same way.

The mapping lives in packages/rs-drive-abci/src/query/service.rs:

A status message is cut at 1024 bytes, because it travels in the grpc-message HTTP/2 header and may echo a request field of any length.

A handler checks the request before Drive sees it, and refuses what no node can answer with a validation error, never with ?. Two rules decide what it refuses:

• Refuse only what fails. A request that has an answer keeps it, even an empty one, so no caller that depends on it breaks.
• GroveDB cannot prove an empty query, or one with a limit of 0. When a proof is asked, an empty id list or a limit of 0 is refused; without a proof, the answer is empty.

An empty identities balances request with a proof used to get a proof the client could not verify. A proof that fails to verify is treated as a node fault too, so refusing that request matters as much as the status codes.

Nodes released before these rules answer the same requests with UNKNOWN, INTERNAL, or that unverifiable proof.

The Drive Error enum

The top-level error type lives in packages/rs-drive/src/error/mod.rs:

#![allow(unused)]
fn main() {
/// Errors
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// Query error
    #[error("query: {0}")]
    Query(#[from] QuerySyntaxError),
    /// Storage Flags error
    #[error("storage flags: {0}")]
    StorageFlags(#[from] StorageFlagsError),
    /// Drive error
    #[error("drive: {0}")]
    Drive(#[from] DriveError),
    /// Proof error
    #[error("proof: {0}")]
    Proof(#[from] ProofError),
    /// GroveDB error
    #[error("grovedb: {0}")]
    GroveDB(Box<grovedb::Error>),
    /// Protocol error
    #[error("protocol: {0}")]
    Protocol(Box<ProtocolError>),
    /// Identity error
    #[error("identity: {0}")]
    Identity(#[from] IdentityError),
    /// Fee error
    #[error("fee: {0}")]
    Fee(#[from] FeeError),
    /// Document error
    #[error("document: {0}")]
    Document(#[from] DocumentError),
    /// Value error
    #[error("value: {0}")]
    Value(#[from] ValueError),
    /// DataContract error
    #[error("contract: {0}")]
    DataContract(#[from] DataContractError),
    /// Cache error
    #[error("contract: {0}")]
    Cache(#[from] CacheError),
    /// Protocol error with info string
    #[error("protocol: {0} ({1})")]
    ProtocolWithInfoString(Box<ProtocolError>, String),
    /// IO error with info string
    #[error("io: {0} ({1})")]
    IOErrorWithInfoString(Box<io::Error>, String),
}
}

This enum is a classic Rust error aggregator. It collects errors from every subsystem that Drive interacts with -- the query parser, the storage flags system, GroveDB, the protocol layer, identities, fees, documents, data contracts, and the cache. Each variant wraps a specific error type from that subsystem.

Notice the organizational difference from ConsensusError:

• ConsensusError is organized by validation phase (basic, state, signature, fee)
• Drive's Error is organized by subsystem (query, storage, grovedb, protocol, identity, etc.)

This makes sense. Consensus errors are about "what rule was violated." Drive errors are about "what component failed."

Box<ProtocolError> -- avoiding large enum variants

Two variants wrap their inner error in a Box:

#![allow(unused)]
fn main() {
/// GroveDB error
#[error("grovedb: {0}")]
GroveDB(Box<grovedb::Error>),

/// Protocol error
#[error("protocol: {0}")]
Protocol(Box<ProtocolError>),
}

Why? Because ProtocolError and grovedb::Error are large types. Without the Box, the entire Error enum would be as large as its largest variant, which could be hundreds of bytes. Since most Drive operations return Result<T, Error>, you would be paying that size cost on every Ok path too -- the Result itself is as large as the larger of T and Error.

Boxing the large variants means the Error enum stores only an 8-byte pointer for those cases, keeping the overall size reasonable. This is a common Rust pattern, and Clippy will warn you about it via the clippy::large_enum_variant lint.

The From trait chain

The #[from] attribute on most variants is a thiserror feature that automatically generates From implementations. For example, #[from] DriveError generates:

#![allow(unused)]
fn main() {
impl From<DriveError> for Error {
    fn from(value: DriveError) -> Self {
        Self::Drive(value)
    }
}
}

But look at the manually written From implementations at the bottom of the file:

#![allow(unused)]
fn main() {
impl From<ProtocolError> for Error {
    fn from(value: ProtocolError) -> Self {
        Self::Protocol(Box::new(value))
    }
}

impl From<grovedb::Error> for Error {
    fn from(value: grovedb::Error) -> Self {
        Self::GroveDB(Box::new(value))
    }
}

impl From<grovedb::element::error::ElementError> for Error {
    fn from(value: grovedb::element::error::ElementError) -> Self {
        Self::GroveDB(Box::new(grovedb::Error::ElementError(value)))
    }
}

impl From<ProtocolDataContractError> for Error {
    fn from(value: ProtocolDataContractError) -> Self {
        Self::Protocol(Box::new(ProtocolError::DataContractError(value)))
    }
}
}

These cannot use #[from] because they involve boxing or wrapping through an intermediate type. The ProtocolError conversion boxes the value. The grovedb::element::error::ElementError conversion wraps the error inside grovedb::Error::ElementError first, then boxes it. The ProtocolDataContractError conversion wraps through ProtocolError::DataContractError and then boxes.

These manual From implementations create multi-hop error conversion chains. When a function deep in Drive's GroveDB interaction layer returns a grovedb::element::error::ElementError, the ? operator can propagate it all the way up to a drive::Error in a single step, with the conversion chain handling the wrapping automatically.

The DriveError enum -- internal errors

The DriveError enum in packages/rs-drive/src/error/drive.rs is where Drive reports its own internal problems:

#![allow(unused)]
fn main() {
/// Drive errors
#[derive(Debug, thiserror::Error)]
pub enum DriveError {
    /// This error should never occur, it is the equivalent of a panic.
    #[error("corrupted code execution error: {0}")]
    CorruptedCodeExecution(&'static str),

    /// Platform expected some specific versions
    #[error("drive unknown version on {method}, received: {received}")]
    UnknownVersionMismatch {
        method: String,
        known_versions: Vec<FeatureVersion>,
        received: FeatureVersion,
    },

    /// A critical corrupted state should stall the chain.
    #[error("critical corrupted state error: {0}")]
    CriticalCorruptedState(&'static str),

    /// Error
    #[error("not supported error: {0}")]
    NotSupported(&'static str),

    // ... many more variants
}
}

Notice how DriveError uses &'static str for most of its error messages rather than String. This is deliberate -- these are internal error messages that should be known at compile time. A CorruptedCodeExecution("document tree missing expected root") is a fixed message that describes a specific bug or data corruption scenario. Using &'static str makes it clear that these are not user-facing messages and avoids allocations on error paths.

There are a few variants that do use String -- these are cases where the error message needs to include runtime data:

#![allow(unused)]
fn main() {
#[error("corrupted contract indexes error: {0}")]
CorruptedContractIndexes(String),

#[error("corrupted drive state error: {0}")]
CorruptedDriveState(String),
}

The severity spectrum

DriveError variants implicitly encode severity through naming conventions:

• Corrupted* variants indicate data corruption. The database is in an unexpected state. These are serious problems that may indicate bugs or hardware failures:

  #![allow(unused)]
  fn main() {
  CorruptedCodeExecution(&'static str),
  CriticalCorruptedState(&'static str),
  CorruptedContractPath(&'static str),
  CorruptedDocumentPath(&'static str),
  CorruptedBalancePath(&'static str),
  CorruptedSerialization(String),
  CorruptedElementType(&'static str),
  CorruptedDriveState(String),
  }

• Invalid* and NotSupported variants indicate logic errors -- the code is trying to do something that should not be possible:

  #![allow(unused)]
  fn main() {
  InvalidDeletionOfDocumentThatKeepsHistory(&'static str),
  InvalidContractHistoryFetchLimit(u16),
  NotSupported(&'static str),
  }

• *NotFound and *DoesNotExist variants indicate missing data that was expected:

  #![allow(unused)]
  fn main() {
  DataContractNotFound(String),
  ElementNotFound(&'static str),
  PrefundedSpecializedBalanceDoesNotExist(String),
  }

• Version mismatch variants indicate protocol version problems:

  #![allow(unused)]
  fn main() {
  UnknownVersionMismatch { method, known_versions, received },
  VersionNotActive { method, known_versions },
  }

When to use consensus errors vs drive errors

This is the key design decision you face when adding error handling to Drive code:

Use a consensus error when:

• The error is caused by invalid user input (a malformed state transition)
• The error needs to be communicated back to the client
• The error needs a stable numeric code
• Other nodes must produce the same error for the same input

Use a drive error when:

• The error is caused by internal state (database corruption, missing paths)
• The error indicates a bug in the platform code
• The error is about version mismatches or unsupported features
• The error involves the storage layer (GroveDB problems)

In practice, Drive functions often work with both. A typical pattern is a function that validates input (producing consensus errors) and then performs storage operations (which might produce drive errors). The return type is usually Result<T, Error> where Error is the Drive error, and consensus errors are embedded inside ProtocolError which is itself a variant of the Drive error.

The ? propagation pattern

Here is how error propagation typically works in Drive code:

#![allow(unused)]
fn main() {
fn apply_document_create(
    &self,
    document: &Document,
    contract: &DataContract,
    // ...
) -> Result<(), Error> {
    // This might return a grovedb::Error, which auto-converts via From
    let existing = self.grove_get(path, key, transaction)?;

    // This might return a DriveError
    if existing.is_some() {
        return Err(DriveError::CorruptedDocumentAlreadyExists(
            "document should not exist at this point"
        ).into());
    }

    // This might return a ProtocolError, which auto-converts via From + Box
    let serialized = document.serialize(platform_version)?;

    // This might return a grovedb::Error
    self.grove_insert(path, key, element, transaction)?;

    Ok(())
}
}

The ? operator handles all the conversions transparently. A grovedb::Error becomes Error::GroveDB(Box::new(...)). A DriveError becomes Error::Drive(...). A ProtocolError becomes Error::Protocol(Box::new(...)). The developer does not need to think about which From implementation is being invoked -- the type system figures it out.

Sub-module error types

Drive organizes its errors into submodules, each with its own error enum:

#![allow(unused)]
fn main() {
pub mod cache;      // CacheError
pub mod contract;   // DataContractError (Drive's own, distinct from DPP's)
pub mod document;   // DocumentError
pub mod drive;      // DriveError
pub mod fee;        // FeeError (Drive's own, distinct from consensus FeeError)
pub mod identity;   // IdentityError
pub mod proof;      // ProofError
pub mod query;      // QuerySyntaxError
}

Each of these has a #[from] conversion to the top-level Error, creating a clean hierarchy where subsystem-specific code can work with its own error type and callers can propagate through ? to the unified type.

Rules

Do:

• Use Box for large error types (ProtocolError, grovedb::Error) to keep the enum small
• Use &'static str for internal error messages that are known at compile time
• Use String only when the message needs runtime data
• Let #[from] generate From implementations where possible
• Write manual From implementations when boxing or intermediate wrapping is needed
• Follow the naming conventions: Corrupted* for data corruption, Invalid* for logic errors, *NotFound for missing data

Do not:

• Use consensus errors for internal Drive problems
• Use drive errors for user-facing validation failures
• Forget to add a From implementation when introducing a new error type
• Return a String error message when a typed error variant would be more informative
• Panic in Drive code -- return a CorruptedCodeExecution or CriticalCorruptedState error instead

Platform Serialization

Dash Platform needs to serialize data structures -- state transitions, consensus errors, documents, identities -- into bytes and back. You might ask: why not just use bincode directly? Or serde? Or protobuf? The answer is that Platform has requirements that no off-the-shelf serialization library handles on its own:

1. Version awareness. The serialization of a type may differ between protocol versions. A DataContract serialized under protocol version 3 might have different fields than under version 4. The serialization system needs to accept a PlatformVersion parameter and dispatch accordingly.

2. Size limits. A malicious actor should not be able to send a 100 MB state transition that costs the node minutes to decode. Serialization must enforce configurable byte limits.

3. Determinism. Every node must produce identical bytes for identical data. This rules out serialization formats that allow field reordering (like JSON) or that depend on hash map iteration order.

4. Compatibility with bincode. Platform already uses bincode extensively for its compact binary format and deterministic encoding. The custom layer should wrap bincode, not replace it.

The rs-platform-serialization crate provides this layer. It sits between bincode and the rest of the platform, adding version-aware encoding/decoding while delegating the actual byte-level work to bincode.

The core traits

The crate defines two pairs of traits in packages/rs-platform-serialization/src/enc/mod.rs and packages/rs-platform-serialization/src/de/mod.rs.

Encoding: PlatformVersionEncode

#![allow(unused)]
fn main() {
pub trait PlatformVersionEncode {
    /// Encode a given type.
    fn platform_encode<E: Encoder>(
        &self,
        encoder: &mut E,
        platform_version: &PlatformVersion,
    ) -> Result<(), EncodeError>;
}
}

Compare this to bincode's standard Encode trait:

#![allow(unused)]
fn main() {
// bincode's Encode (for reference)
pub trait Encode {
    fn encode<E: Encoder>(&self, encoder: &mut E) -> Result<(), EncodeError>;
}
}

The only difference is the platform_version parameter. For types whose serialization does not change between versions, the implementation simply ignores it and delegates to bincode's Encode:

#![allow(unused)]
fn main() {
impl PlatformVersionEncode for String {
    fn platform_encode<E: Encoder>(
        &self,
        encoder: &mut E,
        _: &PlatformVersion,  // ignored -- String encoding never changes
    ) -> Result<(), EncodeError> {
        Encode::encode(self, encoder)
    }
}
}

For types that do change between versions, the implementation can dispatch to different encoding logic based on the version.

Decoding: PlatformVersionedDecode

#![allow(unused)]
fn main() {
pub trait PlatformVersionedDecode: Sized {
    fn platform_versioned_decode<D: Decoder<Context = crate::BincodeContext>>(
        decoder: &mut D,
        platform_version: &PlatformVersion,
    ) -> Result<Self, DecodeError>;
}
}

Again, this mirrors bincode's Decode but with the version parameter. There is also a borrowed variant for zero-copy decoding:

#![allow(unused)]
fn main() {
pub trait PlatformVersionedBorrowDecode<'de>: Sized {
    fn platform_versioned_borrow_decode<
        D: BorrowDecoder<'de, Context = crate::BincodeContext>,
    >(
        decoder: &mut D,
        platform_version: &PlatformVersion,
    ) -> Result<Self, DecodeError>;
}
}

And a convenience macro to implement PlatformVersionedBorrowDecode for any type that implements PlatformVersionedDecode:

#![allow(unused)]
fn main() {
#[macro_export]
macro_rules! impl_platform_versioned_borrow_decode {
    ($ty:ty) => {
        impl<'de> $crate::PlatformVersionedBorrowDecode<'de> for $ty {
            fn platform_versioned_borrow_decode<
                D: bincode::de::BorrowDecoder<'de, Context = $crate::BincodeContext>,
            >(
                decoder: &mut D,
                platform_version: &PlatformVersion,
            ) -> core::result::Result<Self, bincode::error::DecodeError> {
                <$ty as $crate::PlatformVersionedDecode>::platform_versioned_decode(
                    decoder,
                    platform_version,
                )
            }
        }
    };
}
}

The convenience functions

The crate provides top-level functions that mirror bincode's API but add version support. The most commonly used one is platform_encode_to_vec in packages/rs-platform-serialization/src/features/impl_alloc.rs:

#![allow(unused)]
fn main() {
pub fn platform_encode_to_vec<E: PlatformVersionEncode, C: Config>(
    val: E,
    config: C,
    platform_version: &PlatformVersion,
) -> Result<Vec<u8>, EncodeError> {
    let size = {
        let mut size_writer = enc::EncoderImpl::<_, C>::new(SizeWriter::default(), config);
        val.platform_encode(&mut size_writer, platform_version)?;
        size_writer.into_writer().bytes_written
    };
    let writer = VecWriter::with_capacity(size);
    let mut encoder = enc::EncoderImpl::<_, C>::new(writer, config);
    val.platform_encode(&mut encoder, platform_version)?;
    Ok(encoder.into_writer().inner)
}
}

This function does something clever: it encodes twice. The first pass uses a SizeWriter that counts bytes without allocating. The second pass uses a VecWriter pre-allocated to exactly the right size. This avoids reallocations during encoding.

For decoding:

#![allow(unused)]
fn main() {
pub fn platform_versioned_decode_from_slice<D: PlatformVersionedDecode, C: Config>(
    src: &[u8],
    config: C,
    platform_version: &PlatformVersion,
) -> Result<D, error::DecodeError> {
    let reader = read::SliceReader::new(src);
    let mut decoder = DecoderImpl::<_, C, crate::BincodeContext>::new(reader, config, ());
    D::platform_versioned_decode(&mut decoder, platform_version)
}
}

There are also platform_encode_into_slice for encoding into a pre-allocated buffer, encode_into_writer for encoding into arbitrary writers, and platform_versioned_decode_from_reader for decoding from arbitrary readers.

How it wraps bincode

The wrapping is lightweight. Platform serialization does not add a version prefix to the bytes by default. It does not change the wire format. When you call platform_encode_to_vec, the resulting bytes are identical to what bincode::encode_to_vec would produce -- the difference is that the encoding logic can vary based on the PlatformVersion parameter.

The bincode configuration used throughout the platform is:

#![allow(unused)]
fn main() {
let config = bincode::config::standard()
    .with_big_endian()  // network byte order for determinism
    .with_no_limit();   // or .with_limit::<{ N }>() for size-limited encoding
}

Big endian is used for deterministic cross-platform encoding. The limit is applied at the PlatformSerialize / PlatformDeserialize level (see the derive macros chapter) rather than at the raw bincode level.

Standard type implementations

The crate provides PlatformVersionEncode and PlatformVersionedDecode implementations for all standard Rust types. These live in packages/rs-platform-serialization/src/features/impl_alloc.rs and the other impl files. Here are the key patterns:

Types that ignore the version

Primitive types, strings, and simple wrappers just delegate to bincode:

#![allow(unused)]
fn main() {
impl PlatformVersionedDecode for String {
    fn platform_versioned_decode<D: Decoder<Context = crate::BincodeContext>>(
        decoder: &mut D,
        _: &PlatformVersion,
    ) -> Result<Self, DecodeError> {
        bincode::Decode::decode(decoder)
    }
}
}

Collections that propagate the version

Collections like Vec, BTreeMap, and BTreeSet encode their length, then encode each element with the platform version:

#![allow(unused)]
fn main() {
impl<T> PlatformVersionEncode for Vec<T>
where
    T: PlatformVersionEncode + 'static,
{
    fn platform_encode<E: Encoder>(
        &self,
        encoder: &mut E,
        platform_version: &PlatformVersion,
    ) -> Result<(), EncodeError> {
        crate::enc::encode_slice_len(encoder, self.len())?;
        // Optimization: byte slices are written directly
        if core::any::TypeId::of::<T>() == core::any::TypeId::of::<u8>() {
            let slice: &[u8] = unsafe { core::mem::transmute(self.as_slice()) };
            encoder.writer().write(slice)?;
            return Ok(());
        }
        for item in self.iter() {
            item.platform_encode(encoder, platform_version)?;
        }
        Ok(())
    }
}
}

Notice the Vec<u8> optimization -- byte vectors are written in bulk rather than element-by-element, which is significantly faster for large binary data.

Smart pointers

Box<T>, Rc<T>, Arc<T>, and Cow<T> all delegate to their inner type:

#![allow(unused)]
fn main() {
impl<T> PlatformVersionEncode for Box<T>
where
    T: PlatformVersionEncode + ?Sized,
{
    fn platform_encode<E: Encoder>(
        &self,
        encoder: &mut E,
        platform_version: &PlatformVersion,
    ) -> Result<(), EncodeError> {
        T::platform_encode(self, encoder, platform_version)
    }
}
}

Size limits and why they matter

Without size limits, a malicious state transition could contain a Vec claiming to have 2^64 elements, causing the node to allocate unbounded memory during decoding. Or a deeply nested document structure could produce a multi-megabyte serialized form that consumes excessive bandwidth.

Size limits are enforced at two levels:

1. At the PlatformSerialize trait level -- the #[platform_serialize(limit = N)] attribute on a type causes the derive macro to use bincode::config::standard().with_big_endian().with_limit::<{ N }>(). If encoding exceeds N bytes, it returns a MaxEncodedBytesReachedError.

2. At the bincode decoder level -- bincode's claim_container_read mechanism prevents allocating excessive memory for containers:

#![allow(unused)]
fn main() {
fn platform_versioned_decode<D: Decoder<Context = crate::BincodeContext>>(
    decoder: &mut D,
    platform_versioned: &PlatformVersion,
) -> Result<Self, DecodeError> {
    let len = crate::de::decode_slice_len(decoder)?;
    decoder.claim_container_read::<T>(len)?;  // checks memory budget

    let mut vec = Vec::with_capacity(len);
    for _ in 0..len {
        decoder.unclaim_bytes_read(core::mem::size_of::<T>());
        vec.push(T::platform_versioned_decode(decoder, platform_version)?);
    }
    Ok(vec)
}
}

The claim_container_read call tells the decoder "I am about to read len elements of type T" and the decoder checks whether this fits within the remaining byte budget. If not, it returns an error before any allocation happens.

The BincodeContext type alias

You will see crate::BincodeContext throughout the code:

#![allow(unused)]
fn main() {
pub type BincodeContext = ();
}

This is the bincode context type. Bincode supports contextual decoding where a context value is threaded through the decoder -- useful for things like string interning or reference resolution. Platform does not use this feature, so the context is the unit type (). The alias exists to make it easy to change later if needed.

Rules

Do:

• Use PlatformVersionEncode / PlatformVersionedDecode for types whose serialization may change between protocol versions
• Use standard bincode Encode / Decode for types whose format is permanently fixed
• Use big-endian configuration everywhere for deterministic encoding
• Apply size limits on types that are received from untrusted sources (state transitions, consensus errors)
• Use the platform_encode_to_vec convenience function rather than constructing encoders manually

Do not:

• Use little-endian or native-endian configuration -- this breaks determinism across architectures
• Forget to propagate the platform_version parameter through collection types
• Skip claim_container_read in custom collection decoders -- this is a denial-of-service defense
• Add a version prefix to the bytes manually -- the platform version is a parameter, not part of the wire format
• Use serde for consensus-critical serialization -- serde's flexibility (field names, human-readable formats) is a liability when you need deterministic bytes

Document Serialization

This chapter describes the binary wire format used to serialize and deserialize documents on Dash Platform. If you are building a tool that reads documents from gRPC responses, GroveDB storage, or any other source of raw document bytes, this is the specification you need.

Documents are not self-describing. The binary format does not include field names or type tags. To interpret the bytes, you must know which data contract and document type the document belongs to. The document type's schema defines the field order, types, and sizes that determine how the bytes map to values.

High-level structure

Every serialized document follows this layout:

┌──────────────────────┐
│  Serialization       │  varint (1-2 bytes)
│  Version             │  Currently: 0, 1, 2, or 3
├──────────────────────┤
│  Contract version    │  V3 only: varint
│  stamp               │  (0 = unstamped)
├──────────────────────┤
│  $id                 │  32 bytes
├──────────────────────┤
│  $ownerId            │  32 bytes
├──────────────────────┤
│  $creatorId          │  V2 only, if document type supports
│  (optional)          │  transfers/trading: 1 byte flag + 32 bytes
├──────────────────────┤
│  $revision           │  varint (if document type is mutable)
├──────────────────────┤
│  Time fields         │  2-byte bitfield + variable-length data
│  bitfield + data     │
├──────────────────────┤
│  Price               │  Only if document type supports trading
│  (optional)          │  1 byte flag + 8 bytes
├──────────────────────┤
│  User properties     │  Variable length, schema-dependent
│  (in schema order)   │
└──────────────────────┘

Source: packages/rs-dpp/src/document/v0/serialize.rs

Serialization versions

The first bytes of a serialized document are a varint encoding the serialization version. This is not the protocol version or the document struct version — it is the version of the serialization format itself.

The varint encoding uses the integer-encoding crate's VarInt format. For values 0 through 3, the varint is a single byte: 0x00, 0x01, 0x02, or 0x03.

#![allow(unused)]
fn main() {
// Serialization version is written first
let mut buffer: Vec<u8> = 2u64.encode_var_vec(); // version 2 → byte 0x02
}

When deserializing, the version varint is read first, then the appropriate deserialization logic is dispatched:

#![allow(unused)]
fn main() {
let serialized_version: u64 = serialized_document.read_varint()?;
match serialized_version {
    0 => DocumentV0::from_bytes_v0(serialized_document, document_type, platform_version),
    1 => DocumentV0::from_bytes_v1(serialized_document, document_type, platform_version),
    2 => DocumentV0::from_bytes_v2(serialized_document, document_type, platform_version),
    3 => DocumentV0::from_bytes_v3(serialized_document, document_type, platform_version),
    _ => Err(/* unknown version */),
}
}

Note: version 0 has a fallback — if deserialization as v0 (all i64) fails, it retries as v1 (native integer types). This handles edge cases from protocol versions 1–8 where the version byte was 0 but non-i64 integer types may have been used.

The contract version stamp (v3)

Serialization version 3 (the default from protocol v14) writes one extra varint immediately after the version varint: the contract version stamp — the version of the data contract the document's bytes conform to. A value of 0 means unstamped: the document was originally serialized before format 3 existed and has merely been rewritten in the new envelope (for example by a transfer).

The stamp exists because contract updates may add new required properties from a specific contract version onward, using the requiredSince schema keyword:

"properties": {
  "newField": { "type": "string", "maxLength": 63, "position": 4, "requiredSince": 3 }
},
"required": ["existingField", "newField"]

Requiredness is baked into the wire format — a required property serializes raw while an optional one carries a presence flag — so a property whose requiredness varies by contract version needs the stamp to resolve its layout. The rule, per property:

A property is encoded as required (no presence flag) if it is listed in required and either it has no requiredSince annotation, or the document's stamp is at or above the annotation. Otherwise it is encoded as optional (presence-flagged).

An unstamped document (0) predates every requiredSince annotation, so only unconditionally required properties count as required for it. This means the latest contract alone reconstructs the byte layout of every document ever stored — no historical contract lookups are needed.

The stamp is platform-assigned: Drive sets it to the current contract version whenever document content is supplied (create and replace), and preserves it untouched through server-side rewrites that do not re-supply content (transfer and purchase). A document created before a contract update therefore keeps its old stamp — and may legitimately omit properties the newest schema requires — until a replace re-supplies its content and re-stamps it. Clients can also use the stamp as a staleness signal: a document stamped above the client's cached contract version means the contract needs refetching.

Formats 0–2 have no stamp; documents read from them deserialize with contract_version = None, equivalent to a 0 stamp.

Field-by-field breakdown

$id (32 bytes)

The document's unique identifier, written as raw bytes. This is a 256-bit value derived from the contract ID, owner ID, document type name, entropy and (protocol v14+) the identity contract nonce of the create transition via double SHA-256.

$ownerId (32 bytes)

The identity that currently owns the document, written as raw bytes.

$creatorId (v2 and v3, conditional)

Present only in serialization versions 2 and 3, and only if the document type supports transfers (documents_transferable) or trading (trade_mode != None).

0x01  [32 bytes creatorId]    — creator ID present
0x00                           — creator ID absent

$revision (varint, conditional)

Present only if the document type requires revisions (mutable documents). Encoded as a varint (u64). New documents start at revision 1 (INITIAL_REVISION).

Time fields (2-byte bitfield + data)

Time-related fields use a compact encoding with a bitfield to indicate which fields are present, followed by the data for each present field.

Bitfield (2 bytes, big-endian u16):

Data: For each bit that is set (in the order above), the corresponding value is appended:

• $createdAt, $updatedAt, $transferredAt: 8 bytes big-endian u64 — milliseconds since Unix epoch
• $createdAtBlockHeight, $updatedAtBlockHeight, $transferredAtBlockHeight: 8 bytes big-endian u64 — platform block height
• $createdAtCoreBlockHeight, $updatedAtCoreBlockHeight, $transferredAtCoreBlockHeight: 4 bytes big-endian u32 — core chain block height
• $moderatedAt: 8 bytes big-endian u64, milliseconds since Unix epoch
• $moderatedBy: 32 bytes, the moderator's identity id

Bits 9 and 10 are read only in version 3, the format of protocol version 14. They are set only on a document a moderator has written the fields only moderators write of (see System Properties), so every other document's bitfield is as it was before the bits had a meaning. An earlier format has no place for them: serializing a stamped document in format 0, 1 or 2 is refused rather than dropping the stamp.

For example, if a document has $createdAt and $updatedAt set, the bitfield would be 0x0003, followed by 16 bytes (8 for each timestamp).

Price (conditional)

If the document type's trade_mode allows seller-set pricing:

0x01  [8 bytes big-endian u64]   — price in credits
0x00                              — no price set

User-defined properties

Properties are serialized in schema position order — each property in the data contract schema has a position field, and document_type.properties() returns an IndexMap sorted by that position. This is not alphabetical order.

Each property is encoded based on its type and whether it is required. In serialization version 3, "required" means required at the document's contract version stamp (see above); in versions 0–2 — and for every property without a requiredSince annotation — it is simply whether the property is listed in required.

Required fields: The value is written directly with no prefix byte.

Optional fields: A 1-byte presence flag is written first:

• 0x01 followed by the encoded value — field is present
• 0x00 — field is absent

Transient fields: Always get a presence byte, even if marked as required. The serializer checks if !property.required || property.transient to decide whether to write the flag.

Value encoding by type

All numeric values use big-endian byte order.

Note on date types: User-property date fields are encoded as f64 (8 bytes). System timestamps ($createdAt, $updatedAt, $transferredAt) are u64 milliseconds. Both are 8 bytes big-endian but use different numeric representations.

Important: In serialization version 0, all integer types are encoded as i64 (8 bytes big-endian), regardless of the actual type in the schema. This means a u8 field that should be 1 byte is encoded as 8 bytes in v0.

Worked example: withdrawal document

The withdrawals contract defines a withdrawal document type with these properties (in schema position order):

The document type requires $createdAt, $updatedAt, and $revision.

Here is a real serialized withdrawal document (hex), broken down byte by byte:

02                                      ← serialization version (varint: 2)
0222 9eda 94b3 5be5 5ac2 22ca 8cc4      ← $id (32 bytes)
631c 0717 c9ee 4a22 3f2a 269e 06c9
a1be 7c54
36b3 e63b a54a ba9b 7599 4128 d124      ← $ownerId (32 bytes)
e9e1 cebe 348c d304 15b5 098c 6052
6de0 157e
                                        ← no $creatorId: withdrawal document type
                                          does not support transfers/trading
c501                                    ← $revision (varint: 197)
0003                                    ← time bitfield: bits 0,1 set
                                          ($createdAt + $updatedAt)
0000019cd70f3323                        ← $createdAt: 1773134623523 ms
                                          (2026-03-10 09:23:43 UTC)
0000019d05406f0c                        ← $updatedAt: 1773909602060 ms
                                          (2026-03-19 08:40:02 UTC)
                                        ← user properties follow (schema-dependent)

To properly decode the properties section, you need the document type schema — field names, types, required flags, and order. This is why the decode-document CLI tool (in packages/rs-scripts) requires the contract and document type to be specified.

Using the tool on this document produces:

id:         9LSAr59Fw7A1PHvX9WV1RWHCjL4PrijrHZpwhYDPkMq
owner_id:   4gY7wFM4o53jc8PJZ9KNzqzaJhXhPVMivJREKVwihKVF
created_at: 2026-03-10 09:23:43 UTC
updated_at: 2026-03-19 08:40:02 UTC
revision:   197

properties:
  amount: (i64)191000
  coreFeePerByte: (i64)1
  outputScript: bytes 76a914...88ac
  pooling: (i64)0
  status: (i64)2
  transactionIndex: (i64)9815
  transactionSignHeight: (i64)2440497

The decode-document CLI tool

For convenience, the rs-scripts crate provides a decode-document binary that handles all of this deserialization automatically:

# Install
cargo install --path packages/rs-scripts

# Decode a withdrawal document from base64
decode-document -c withdrawals -d withdrawal "AgIintqUs1vl..."

# Decode from hex
decode-document -c withdrawals -d withdrawal "0202229eda94b35b..."

# Use a contract ID instead of a name
decode-document -c 4fJLR2GYTPFdomuTVvNy3VRrvWgvkKPzqehEBpNf2nk6 -d withdrawal "..."

See packages/rs-scripts/README.md for full usage details.

Common pitfalls for third-party deserializers

1. The serialization version varint changed the layout. If your code was written for version 0 or 1, version 2 documents will have different field offsets due to the $creatorId field. Always read the version varint first and branch accordingly.

2. Integer encoding differs between v0 and v1+. In version 0, a u8 field occupies 8 bytes (encoded as i64). In version 1+, it occupies 1 byte. Parsing with the wrong version assumption will shift every subsequent field.

3. The time fields bitfield is variable-length data. The 2-byte bitfield tells you how many time fields follow. If you assume a fixed number of time fields, any document with a different set of time fields (e.g., one that includes $transferredAt or block heights) will be misaligned.

4. Property order is schema position order, not alphabetical. Each property in the data contract schema has a position field. Properties are serialized in ascending position order (stored in an IndexMap). If you assume alphabetical order or JSON declaration order, fields will be read from the wrong positions.

5. Optional fields have a presence byte. If you forget to read the 0x00/0x01 prefix for optional fields, every subsequent field will be shifted by one byte.

6. ByteArray encoding depends on size constraints. Fixed-size byte arrays (where minItems == maxItems in the schema) have no length prefix. Variable-size byte arrays have a varint length prefix. Check the schema to know which encoding is used.

7. A typed array's element width comes from its items schema. Each element is laid out as a required property of the element's type, so an integer element bounded 0..100 is 1 byte and an unbounded one 8, and a fixed-size byte array or identifier element has no length prefix. Parse the items schema exactly as a property schema to know the width, including the contract's sizedIntegerTypes setting.

8. In version 3, the same document type can produce different property layouts. A property annotated with requiredSince is presence-flagged in documents stamped below the annotation and raw in documents stamped at or above it. Two version-3 documents of the same type may therefore differ in layout — always read the stamp varint and resolve each property's requiredness against it before decoding the properties section.

Derive Macros

In the previous chapter we looked at the PlatformVersionEncode and PlatformVersionedDecode traits and the platform_encode_to_vec / platform_versioned_decode_from_slice functions. But you rarely implement those traits by hand. Instead, you use three derive macros from the rs-platform-serialization-derive crate:

• PlatformSerialize -- generates a high-level serialize_to_bytes() method
• PlatformDeserialize -- generates a high-level deserialize_from_bytes() method
• PlatformSignable -- generates a signable_bytes() method that excludes signature fields

These macros live in packages/rs-platform-serialization-derive/src/lib.rs and are the glue that connects Rust struct definitions to the platform serialization system.

PlatformSerialize and PlatformDeserialize

These two macros work as a pair. Let us start with how they are used on the ConsensusError type:

#![allow(unused)]
fn main() {
#[derive(
    thiserror::Error,
    Debug,
    Encode,
    Decode,
    PlatformSerialize,
    PlatformDeserialize,
    Clone,
    PartialEq,
)]
#[platform_serialize(limit = 2000)]
#[error(transparent)]
pub enum ConsensusError {
    // ...
}
}

And on a leaf error struct:

#![allow(unused)]
fn main() {
#[derive(
    Error, Debug, Clone, PartialEq, Eq, Encode, Decode, PlatformSerialize, PlatformDeserialize,
)]
#[error("Document {document_id} is already present")]
#[platform_serialize(unversioned)]
pub struct DocumentAlreadyPresentError {
    document_id: Identifier,
}
}

And on the StateTransition enum:

#![allow(unused)]
fn main() {
#[derive(
    Debug, Clone, Encode, Decode,
    PlatformSerialize, PlatformDeserialize, PlatformSignable,
    From, PartialEq,
)]
#[platform_serialize(unversioned)]
#[platform_serialize(limit = 100000)]
pub enum StateTransition {
    DataContractCreate(DataContractCreateTransition),
    DataContractUpdate(DataContractUpdateTransition),
    Batch(BatchTransition),
    // ...
}
}

Notice that StateTransition uses two #[platform_serialize] attributes -- one for unversioned and one for limit. These are combined internally.

What the derives generate

PlatformSerialize generates an implementation of one of two traits, depending on whether unversioned is set:

With unversioned -- implements PlatformSerializable:

#![allow(unused)]
fn main() {
// Generated code (simplified):
impl PlatformSerializable for DocumentAlreadyPresentError {
    type Error = ProtocolError;

    fn serialize_to_bytes(&self) -> Result<Vec<u8>, Self::Error> {
        let config = bincode::config::standard()
            .with_big_endian()
            .with_no_limit();
        bincode::encode_to_vec(self, config)
            .map_err(|e| {
                ProtocolError::PlatformSerializationError(
                    format!("unable to serialize DocumentAlreadyPresentError: {}", e)
                )
            })
    }

    fn serialize_consume_to_bytes(self) -> Result<Vec<u8>, Self::Error> {
        // same as above, taking self by value
    }
}
}

Without unversioned -- implements PlatformSerializableWithPlatformVersion:

#![allow(unused)]
fn main() {
// Generated code (simplified):
impl PlatformSerializableWithPlatformVersion for ConsensusError {
    type Error = ProtocolError;

    fn serialize_to_bytes_with_platform_version(
        &self,
        platform_version: &PlatformVersion,
    ) -> Result<Vec<u8>, ProtocolError> {
        let config = bincode::config::standard()
            .with_big_endian()
            .with_limit::<{ 2000 }>();
        platform_serialization::platform_encode_to_vec(self, config, platform_version)
            .map_err(|e| match e {
                bincode::error::EncodeError::Io { inner, index } =>
                    ProtocolError::MaxEncodedBytesReachedError {
                        max_size_kbytes: 2000,
                        size_hit: index,
                    },
                _ => ProtocolError::PlatformSerializationError(
                    format!("unable to serialize ConsensusError: {}", e)
                ),
            })
    }
}
}

The key differences: the unversioned variant uses plain bincode::encode_to_vec, while the versioned variant uses platform_serialization::platform_encode_to_vec which threads the PlatformVersion through the encode chain. When a limit is set, the config uses with_limit::<{ N }>() and the error mapping converts bincode IO errors to MaxEncodedBytesReachedError.

In both cases, the derive also generates bincode Encode and Decode implementations by internally calling into derive_bincode -- this is why you still need Encode and Decode in the derive list alongside PlatformSerialize and PlatformDeserialize.

The #[platform_serialize] attributes

The #[platform_serialize(...)] attribute accepts several parameters. Here is the full list from the derive macro source in packages/rs-platform-serialization-derive/src/lib.rs:

limit = N

Sets the maximum serialized size in bytes:

#![allow(unused)]
fn main() {
#[platform_serialize(limit = 2000)]
}

When encoding exceeds this limit, the error is MaxEncodedBytesReachedError. This is critical for types received from the network.

unversioned

Generates PlatformSerializable instead of PlatformSerializableWithPlatformVersion:

#![allow(unused)]
fn main() {
#[platform_serialize(unversioned)]
}

Use this when the type's serialization format does not change between protocol versions. Most leaf types (individual error structs, simple data holders) use this.

passthrough

For enums, serializes by delegating directly to the inner variant's serialization method:

#![allow(unused)]
fn main() {
#[platform_serialize(passthrough)]
}

When MyEnum::Variant(inner) is serialized with passthrough, it calls inner.serialize() directly rather than encoding the enum tag + inner data. This means the enum variant information is lost in serialization -- deserialization must use platform_version_path to know which variant to decode into.

Cannot be combined with limit, untagged, or into.

untagged

For enums, serializes without the variant tag number:

#![allow(unused)]
fn main() {
#[platform_serialize(untagged)]
}

Similar to passthrough but still uses the enum's own encoding logic rather than delegating to the inner type. The variant index is omitted from the output. Like passthrough, deserialization requires knowing which variant to expect.

Cannot be combined with passthrough.

into = "TypePath"

For structs, converts the value to another type before serialization:

#![allow(unused)]
fn main() {
#[platform_serialize(into = "DataContractInSerializationFormat")]
}

The generated code calls .into() to convert to the target type, then serializes that type. This is useful for types that have a different in-memory representation than their serialization format.

Cannot be used on enums.

platform_version_path = "..."

Used with passthrough or untagged to specify how to determine the correct variant during deserialization:

#![allow(unused)]
fn main() {
#[platform_serialize(
    passthrough,
    platform_version_path = "dpp.contract_versions.contract_serialization_version.default_current_version"
)]
}

The deserialization code reads this field path from the PlatformVersion to determine which variant index to decode.

crate_name = "..."

Overrides the default crate path (defaults to crate):

#![allow(unused)]
fn main() {
#[platform_serialize(crate_name = "dpp")]
}

allow_prepend_version and force_prepend_version

These flags are defined in the code but currently not actively used in the main serialization path. They were designed for prepending version bytes to serialized output. Only one can be used at a time.

The #[platform_error_type] attribute

By default, the derives use ProtocolError as the error type. You can override this:

#![allow(unused)]
fn main() {
#[derive(PlatformSerialize, PlatformDeserialize)]
#[platform_error_type(MyCustomError)]
pub struct MyType { ... }
}

The error type must have PlatformSerializationError(String) and MaxEncodedBytesReachedError { max_size_kbytes, size_hit } variants (or equivalent conversion paths).

PlatformSignable -- the signature hash derive

The PlatformSignable derive solves a specific problem: when you sign a state transition, you need to hash all the fields except the signature itself. You cannot include the signature in the data that was signed -- that would be circular.

Here is how it is used on DataContractCreateTransitionV0 in packages/rs-dpp/src/state_transition/state_transitions/contract/data_contract_create_transition/v0/mod.rs:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Encode, Decode, PartialEq, PlatformSignable)]
pub struct DataContractCreateTransitionV0 {
    pub data_contract: DataContractInSerializationFormat,
    pub identity_nonce: IdentityNonce,
    pub user_fee_increase: UserFeeIncrease,
    #[platform_signable(exclude_from_sig_hash)]
    pub signature_public_key_id: KeyID,
    #[platform_signable(exclude_from_sig_hash)]
    pub signature: BinaryData,
}
}

The #[platform_signable(exclude_from_sig_hash)] attribute marks fields that should be excluded from the signature hash. The derive generates:

1. A new struct DataContractCreateTransitionV0Signable<'a> containing only the non-excluded fields as Cow references
2. A From<&DataContractCreateTransitionV0> implementation for the signable struct
3. An implementation of the Signable trait on the original struct

The generated code looks approximately like this:

#![allow(unused)]
fn main() {
// Generated by PlatformSignable derive:

#[derive(Debug, Clone, bincode::Encode)]
pub struct DataContractCreateTransitionV0Signable<'a> {
    data_contract: std::borrow::Cow<'a, DataContractInSerializationFormat>,
    identity_nonce: std::borrow::Cow<'a, IdentityNonce>,
    user_fee_increase: std::borrow::Cow<'a, UserFeeIncrease>,
    // signature_public_key_id -- excluded
    // signature -- excluded
}

impl<'a> From<&'a DataContractCreateTransitionV0>
    for DataContractCreateTransitionV0Signable<'a>
{
    fn from(original: &'a DataContractCreateTransitionV0) -> Self {
        DataContractCreateTransitionV0Signable {
            data_contract: std::borrow::Cow::Borrowed(&original.data_contract),
            identity_nonce: std::borrow::Cow::Borrowed(&original.identity_nonce),
            user_fee_increase: std::borrow::Cow::Borrowed(&original.user_fee_increase),
        }
    }
}

impl crate::serialization::Signable for DataContractCreateTransitionV0 {
    fn signable_bytes(&self) -> Result<Vec<u8>, ProtocolError> {
        let config = bincode::config::standard().with_big_endian();
        let intermediate: DataContractCreateTransitionV0Signable = self.into();
        bincode::encode_to_vec(intermediate, config).map_err(|e| {
            ProtocolError::PlatformSerializationError(
                format!("unable to serialize to produce sig hash \
                    DataContractCreateTransitionV0: {}", e)
            )
        })
    }
}
}

The Cow references avoid cloning the data just to produce a hash. The intermediate struct borrows from the original and only serializes the fields that matter for the signature.

PlatformSignable on enums

When used on an enum (like StateTransition), the derive generates a corresponding Signable enum where each variant wraps the signable version of its inner type:

#![allow(unused)]
fn main() {
// On StateTransition:
#[derive(PlatformSignable)]
pub enum StateTransition {
    DataContractCreate(DataContractCreateTransition),
    DataContractUpdate(DataContractUpdateTransition),
    // ...
}

// Generates:
#[derive(Debug, Clone, bincode::Encode, derive_more::From)]
pub enum StateTransitionSignable<'a> {
    DataContractCreate(DataContractCreateTransitionSignable<'a>),
    DataContractUpdate(DataContractUpdateTransitionSignable<'a>),
    // ...
}
}

The signable_bytes implementation on the enum encodes a variant index (as u16) followed by the inner type's signable bytes:

#![allow(unused)]
fn main() {
impl Signable for StateTransition {
    fn signable_bytes(&self) -> Result<Vec<u8>, ProtocolError> {
        let config = bincode::config::standard().with_big_endian();
        let signable_bytes = match self {
            StateTransition::DataContractCreate(ref inner) => {
                let mut buf = bincode::encode_to_vec(&(0u16), config).unwrap();
                let inner_signable_bytes = inner.signable_bytes()?;
                buf.extend(inner_signable_bytes);
                buf
            }
            StateTransition::DataContractUpdate(ref inner) => {
                let mut buf = bincode::encode_to_vec(&(1u16), config).unwrap();
                let inner_signable_bytes = inner.signable_bytes()?;
                buf.extend(inner_signable_bytes);
                buf
            }
            // ...
        };
        Ok(signable_bytes)
    }
}
}

PlatformSignable attributes

• exclude_from_sig_hash -- marks a field to be excluded from the signable struct
• into = "TypePath" -- converts a field to a different type in the signable struct (used for fields that need a different representation for hashing)
• derive_into -- on enums, generates From conversions from the original enum to the signable enum
• derive_bincode_with_borrowed_vec -- manually implements bincode::Encode for the signable struct instead of deriving it (needed when fields contain borrowed Vec types)

The relationship between Encode/Decode and PlatformSerialize/PlatformDeserialize

This is a common source of confusion. Here is how the pieces fit together:

• Encode / Decode (from bincode) -- field-level encoding. These know how to write each field to bytes and read it back. They are the low-level building blocks.

• PlatformVersionEncode / PlatformVersionedDecode (from rs-platform-serialization) -- version-aware field-level encoding. These wrap Encode/Decode with a PlatformVersion parameter.

• PlatformSerialize / PlatformDeserialize (derive macros) -- high-level serialization. These generate the serialize_to_bytes() and deserialize_from_bytes() methods that configure bincode, enforce size limits, and convert errors.

When you derive all of them on a type, the call chain is:

your_type.serialize_to_bytes()           // PlatformSerialize-generated method
  -> platform_encode_to_vec(...)         // from rs-platform-serialization
    -> your_type.platform_encode(...)    // PlatformVersionEncode (auto-generated)
      -> field.encode(encoder)           // bincode Encode for each field

You need Encode and Decode in the derive list alongside PlatformSerialize and PlatformDeserialize because the platform derives internally delegate to bincode encoding.

Rules

Do:

• Always derive Encode, Decode, PlatformSerialize, PlatformDeserialize together
• Use #[platform_serialize(unversioned)] for types with a stable serialization format
• Use #[platform_serialize(limit = N)] on types received from untrusted sources
• Use #[platform_signable(exclude_from_sig_hash)] on signature and signature key ID fields
• Keep the #[platform_error_type] attribute consistent with the crate's error type

Do not:

• Use passthrough on structs (it is enum-only)
• Use into on enums (it is struct-only)
• Combine passthrough with limit, untagged, or into
• Combine force_prepend_version with allow_prepend_version
• Forget that PlatformSignable on enums requires each inner type to also implement Signable
• Change the order of fields in a PlatformSignable struct -- this changes the signature hash, which invalidates existing signatures

Platform Addresses

Dash Platform has its own address system, independent of the legacy Base58Check addresses used on the Core chain. Platform addresses use Bech32m encoding (BIP-350), following the specification in DIP-0018. There are three address types: two transparent and one shielded.

If you are coming from Bitcoin or Dash Core, the key mental shift is this: platform addresses are not derived from a single private key via a single algorithm. They are typed containers for a hash or a public key, unified under a single encoding scheme with a shared human-readable prefix.

The Three Address Types

The type byte is the first byte of the Bech32m data payload. It determines how the rest of the payload is interpreted. The type bytes were chosen so that the first character after dash1 (or tdash1) is a memorable letter: k for keys (P2PKH), s for scripts (P2SH), z for zero-knowledge (Orchard).

PlatformAddress

The transparent address type is defined in packages/rs-dpp/src/address_funds/platform_address.rs:

#![allow(unused)]
fn main() {
pub enum PlatformAddress {
    P2pkh([u8; 20]),
    P2sh([u8; 20]),
}
}

Two variants, both wrapping a 20-byte hash. A P2pkh address contains a Hash160(compressed_pubkey), just like on Core. A P2sh address contains a Hash160(redeem_script), supporting standard multisig scripts.

Bech32m Encoding

The human-readable part (HRP) depends on the network:

#![allow(unused)]
fn main() {
const PLATFORM_HRP_MAINNET: &str = "dash";
const PLATFORM_HRP_TESTNET: &str = "tdash";  // also devnet, regtest
}

Encoding produces addresses like:

• dash1krma5z3ttj75la4m93xcndna9ullamq9y5e9n5rs (P2PKH, mainnet)
• tdash1sppl5xpu70aka8nacc4kj2htflydspzkc8jtru5 (P2SH, testnet)

The wire format is type_byte || hash -- 21 bytes total, then Bech32m-encoded with the appropriate HRP.

Storage vs. Bech32m: Two Byte Schemes

There is an important distinction between how addresses are encoded for users and how they are serialized for storage. The Bech32m type bytes (0xb0, 0x80) are not the same as the bincode variant indices (0x00, 0x01) used in GroveDB keys:

This matters when you encounter raw bytes. If the leading byte is 0xb0 or 0x80, you are looking at a Bech32m payload. If it is 0x00 or 0x01, it is bincode-serialized. The to_bytes() method produces bincode format; to_bech32m_string() produces the user-facing string.

Conversion to Core Addresses

PlatformAddress can be converted to and from dashcore::Address, the type used by the Core chain RPC client. This allows the platform layer to interoperate with Core's address format when needed -- for example, when processing withdrawals that ultimately create Core chain transactions.

OrchardAddress

The shielded address type is defined in packages/rs-dpp/src/address_funds/orchard_address.rs:

#![allow(unused)]
fn main() {
pub struct OrchardAddress(grovedb_commitment_tree::PaymentAddress);
}

It wraps the Orchard protocol's native PaymentAddress, which consists of two components:

Total: 43 bytes. The Bech32m payload is 0x10 || diversifier || pk_d -- 44 bytes.

Key Constants

#![allow(unused)]
fn main() {
const ORCHARD_DIVERSIFIER_SIZE: usize = 11;
const ORCHARD_PKD_SIZE: usize = 32;
const ORCHARD_ADDRESS_SIZE: usize = 43;
const ORCHARD_TYPE: u8 = 0x10;
}

Diversifiers and Unlinkability

A single Orchard spending key can derive an unlimited number of addresses by varying the diversifier. Each address looks completely unrelated to any other address derived from the same key. Only the holder of the corresponding Incoming Viewing Key (IVK) can link them.

This is the fundamental privacy property: a merchant can give every customer a unique address, and no observer can determine that all those addresses belong to the same wallet. The diversifier is the mechanism that makes this possible.

Differences from Zcash Encoding

Dash's OrchardAddress uses the same 43-byte raw format as Zcash Orchard addresses (identical diversifier + pk_d structure). But the Bech32m encoding is Dash-specific:

• No F4Jumble: Zcash applies an F4Jumble permutation before encoding; Dash does not.
• No Unified Address wrapper: Zcash wraps Orchard addresses in a Unified Address (UA) envelope with typecodes and length prefixes; Dash uses a simple type-byte scheme.
• Different HRP: Zcash uses u1; Dash uses dash/tdash.

The result is simpler, shorter addresses that are not interoperable with Zcash wallets.

Converting to Orchard's Native Type

The builder functions that construct shielded transactions need the Orchard library's native PaymentAddress, not our wrapper. Conversion is straightforward:

#![allow(unused)]
fn main() {
impl From<&OrchardAddress> for PaymentAddress {
    fn from(address: &OrchardAddress) -> Self {
        *address.inner()
    }
}
}

This is used in the shielded builder module (packages/rs-dpp/src/shielded/builder/) when adding outputs to an Orchard bundle.

Address Witnesses

When a transparent address is used as an input (for example, funding a shield transition), the sender must prove ownership. This is done through an AddressWitness, defined in packages/rs-dpp/src/address_funds/witness.rs:

#![allow(unused)]
fn main() {
pub enum AddressWitness {
    P2pkh {
        signature: BinaryData,
    },
    P2sh {
        signatures: Vec<BinaryData>,
        redeem_script: BinaryData,
    },
}
}

P2PKH Witnesses

A P2PKH witness contains a single 65-byte recoverable ECDSA signature. The public key is recovered from the signature rather than transmitted alongside it -- saving 33 bytes per witness. Verification recovers the public key, hashes it with Hash160, and checks the result against the address hash.

P2SH Witnesses

A P2SH witness contains the signatures and the redeem script. Only standard bare multisig scripts are supported:

OP_M <pubkey1> <pubkey2> ... <pubkeyN> OP_N OP_CHECKMULTISIG

Constraints:

• Maximum 17 signature entries (MAX_P2SH_SIGNATURES) -- 16 keys plus 1 dummy for the CHECKMULTISIG bug
• Only compressed public keys (33 bytes)
• No timelocks, hash puzzles, or custom scripts
• The redeem script must hash to the address: Hash160(script) == address_hash

Verification Cost Tracking

Every witness verification has a measurable cost. The AddressWitnessVerificationOperations struct tracks the work:

#![allow(unused)]
fn main() {
pub struct AddressWitnessVerificationOperations {
    pub ecdsa_signature_verifications: u16,
    pub message_hash_count: u16,
    pub pubkey_hash_verifications: u16,
    pub script_hash_verifications: u16,
    pub signable_bytes_len: usize,
}
}

These counts feed into the fee system. A P2PKH witness costs one ECDSA verification. An M-of-N multisig costs N verifications (all public keys are checked against all signatures, per Bitcoin's CHECKMULTISIG semantics).

How Addresses Are Used in Shielded Transitions

Each of the five shielded transition types uses addresses differently:

Shield (Transparent to Shielded)

The sender provides one or more PlatformAddress inputs, each with a nonce and a maximum contribution amount. An AddressWitness proves ownership of each input. The funds enter the shielded pool and are received by an OrchardAddress embedded in the Orchard bundle's encrypted outputs.

#![allow(unused)]
fn main() {
pub struct ShieldTransitionV0 {
    pub inputs: BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
    pub input_witnesses: Vec<AddressWitness>,
    pub actions: Vec<SerializedAction>,  // contains encrypted OrchardAddress recipient
    pub amount: u64,
    // ...
}
}

Shielded Transfer (Shielded to Shielded)

No transparent addresses are involved. The sender spends notes from the shielded pool and creates new notes for the recipient's OrchardAddress and a change OrchardAddress. Both addresses are hidden inside the Orchard bundle -- only the respective recipients can decrypt them.

#![allow(unused)]
fn main() {
pub struct ShieldedTransferTransitionV0 {
    pub actions: Vec<SerializedAction>,  // spend + output pairs
    pub value_balance: u64,             // fee extracted from pool
    // ...
}
}

Unshield (Shielded to Transparent)

The sender spends shielded notes and sends the funds to a PlatformAddress visible on-chain. The transparent output address is explicitly included in the transition and bound into the Orchard sighash to prevent substitution.

#![allow(unused)]
fn main() {
pub struct UnshieldTransitionV0 {
    pub output_address: PlatformAddress,  // visible transparent recipient
    pub unshielding_amount: u64,
    pub actions: Vec<SerializedAction>,   // spend + change output
    // ...
}
}

Shielded Withdrawal (Shielded to Core Chain)

Similar to unshield, but the destination is a Core chain script rather than a platform address. The CoreScript holds a raw P2PKH or P2SH script that will be used in a Core chain withdrawal transaction.

#![allow(unused)]
fn main() {
pub struct ShieldedWithdrawalTransitionV0 {
    pub output_script: CoreScript,  // Core chain P2PKH or P2SH
    pub core_fee_per_byte: u32,
    pub pooling: Pooling,
    // ...
}
}

Shield From Asset Lock (Core Chain to Shielded)

An asset lock proof from the Core chain funds the shielded pool directly. The recipient is an OrchardAddress inside the Orchard bundle. No PlatformAddress inputs are needed -- the asset lock proof substitutes for them.

The transition also carries an optional surplus_output: Option<PlatformAddress>. When the consumed asset lock exceeds shield_amount + pool_fee, the leftover surplus is credited to this platform address; if it is unset, the surplus folds into the fee pools (bounded by shielded_implicit_fee_cap). See Entry-Transition Fees. Unlike the transparent recipients of Unshield/ShieldedWithdrawal (which are bound through the Orchard sighash extra_data above), surplus_output is bound through the state transition's own platform_signable signature -- it sits before the signature field, so it is part of the signed payload and cannot be substituted or truncated after signing. The Orchard extra_data therefore does not carry it; what it binds instead is the asset lock itself (see below).