State Transition#
Overview#
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.
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.
Structure#
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:
Header - version and payload type
Payload - contents vary depending on payload type
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 |
---|---|
Database schema for a single application |
|
Documents Batch ( |
An array of 1 or more document transition objects containing application data |
Identity Create ( |
Information including the public keys required to create a new Identity |
Identity Topup ( |
Information including proof of a transaction containing an amount to add to the provided identity’s balance |
An updated database schema to modify an existing application |
|
Identity Update ( |
A set of one or more new public keys to add to the identity or a list of existing keys to disable |
Information required to withdraw credits from Dash Platform |
|
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.
Note
For more detailed information, see the Platform Protocol Reference - State Transition page.