State Transition#


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

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 Type

Payload Description

Data Contract Create (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)

Information including the public keys required to create a new Identity

Identity Topup (3)

Information including proof of a transaction containing an amount to add to the provided identity’s balance

Data Contract Update (4)

An updated database schema to modify an existing application

Identity Update (5)

A set of one or more new public keys to add to the identity or a list of existing keys to disable

Identity Credit Withdrawal (6)

Information required to withdraw credits from Dash Platform

Identity Credit Transfer (7)

Information required to transfer credits

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 rules explicitly 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.


For more detailed information, see the Platform Protocol Reference - State Transition page.