Dash CoreDash PlatformDash.orgDash User DocsLog In
These docs are for v0.21.0. Click to read the latest docs for v0.25-redirect.

State Transition

The means of storing and updating Dash Platform data


At any given point in time, the data stored by each application (and more broadly, the entire platform) is in a specific state. State transitions are the means for submitting data that creates, updates, or deletes platform data and results in a change to a new state.

For example, Alice may have already added Bob and Carol as friends in DashPay while also having a pending friend request to Dan. If Dan declines the friend request, the state will transition to a new one where Alice and Bob remain in Alice’s friend list while Dan moves to the declined list.


State Transition Example

Implementation Overview

To ensure the consistency and integrity of data stored on Layer 2, all data is governed by the Dash Platform Protocol (DPP) which describes serialization and validation rules. Since state transitions are the vehicle for delivering data to the platform, the implementation of state transitions resides in DPP alongside the validation logic.


To support the various data types used on the platform and enable future updates, state transitions were designed to be flexible. Each state transition consists of a:

  1. Header - version and payload type
  2. Payload - contents vary depending on payload type
  3. Signature - signature of the header/payload by the identity submitting to state transition

The following table contains a list of currently defined payload types:

Payload TypePayload Description
Data Contract (0)Database schema for a single application
Documents Batch (1)An array of 1 or more document transition objects containing application data
Identity Create (2)Identity creation information
Identity Topup (3)Identity topup information

Application Usage

State transitions are constructed by client-side libraries and then submitted to the platform via DAPI. Based on the validation rules described in DPP (and an application data contract where relevant), Dash Platform first validates the state transition. Some state transitions (e.g. data contracts, identity) are validated solely by explicit rules defined in DPP, while others (e.g. documents) are also subject to the rules defined by the relevant application’s data contract. Once the state transition has been validated, the platform stores the data and updates the platform state.

What’s Next