```{eval-rst}
.. _explanations-state-transition:
```

# 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](../explanations/dashpay.md) 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.

```{eval-rst}
.. figure:: ../../img/state-transition.svg
   :class: no-scaled-link
   :align: center
   :width: 90%
   :alt: 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](../explanations/platform-protocol.md) (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:

1. Header - version and payload type
2. Payload - contents vary depending on payload type
3. Authorization - authorization data for the header/payload

Authorization varies by transition family. Transitions submitted by an identity are signed with one of that identity's keys. Transitions that spend from [Platform addresses](../protocol-ref/address-system.md) instead use a witness signature for each address input. [Shielded pool](../explanations/shielded-pool.md) transitions use the authorization included in their shielded actions and, where applicable, address witnesses or an asset-lock signature. Shield from Identity is also signed by the identity whose balance supplies the credits.

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

| Payload Type | Payload Description |
| - | - |
| [Data Contract Create](../protocol-ref/data-contract.md#data-contract-create) (`0`) | [Database schema](../explanations/platform-protocol-data-contract.md) for a single application |
| [Batch](../protocol-ref/document.md#document-overview) (`1`) | An array of 1 or more (currently limited to exactly one per batch) transition objects acting on [documents](../explanations/platform-protocol-document.md) or [tokens](../explanations/tokens.md). See [Batch transitions](#batch-transitions) below for the available actions. |
| [Identity Create](../protocol-ref/identity.md#identity-create) (`2`) | Information including the public keys required to create a new [Identity](../explanations/identity.md) |
| [Identity Topup](../protocol-ref/identity.md#identity-topup) (`3`) | Information including proof of a transaction containing an amount to add to the provided identity's balance |
| [Data Contract Update](../protocol-ref/data-contract.md#data-contract-update) (`4`) | An updated [database schema](../explanations/platform-protocol-data-contract.md) to modify an existing application |
| [Identity Update](../protocol-ref/identity.md#identity-update) (`5`) | A set of one or more new public keys to add to the [identity](../explanations/identity.md) or a list of existing keys to disable |
| [Identity Credit Withdrawal](../protocol-ref/identity.md) (`6`) | Information required to withdraw credits from Dash Platform |
| [Identity Credit Transfer](../protocol-ref/identity.md) (`7`) | Information required to transfer credits |
| Masternode Vote (`8`) | Contested resource vote details (e.g., [DPNS premium name vote](../explanations/dpns.md#conflict-resolution)) |
| [Identity Credit Transfer To Addresses](../protocol-ref/address-system.md#identity-credit-transfer-to-addresses) (`9`) | Transfer identity credits to one or more Platform addresses |
| [Identity Create From Addresses](../protocol-ref/address-system.md#identity-create-from-addresses) (`10`) | Create a new identity funded from Platform addresses |
| [Identity Top Up From Addresses](../protocol-ref/address-system.md#identity-top-up-from-addresses) (`11`) | Add credits to an existing identity from Platform addresses |
| [Address Funds Transfer](../protocol-ref/address-system.md#address-funds-transfer) (`12`) | Transfer funds between Platform addresses |
| [Address Funding From Asset Lock](../protocol-ref/address-system.md#address-funding-from-asset-lock) (`13`) | Fund a Platform address using an asset lock proof |
| [Address Credit Withdrawal](../protocol-ref/address-system.md#address-credit-withdrawal) (`14`) | Withdraw credits from a Platform address |
| [Shield](../protocol-ref/shielded-pool.md#shield) (`15`) | Move transparent Platform funds into the [shielded pool](../explanations/shielded-pool.md) |
| [Shielded Transfer](../protocol-ref/shielded-pool.md#shielded-transfer) (`16`) | Transfer value privately between shielded notes |
| [Unshield](../protocol-ref/shielded-pool.md#unshield) (`17`) | Move funds from the shielded pool back to a Platform address |
| [Shield From Asset Lock](../protocol-ref/shielded-pool.md#shield-from-asset-lock) (`18`) | Fund the shielded pool directly from an asset lock proof |
| [Shielded Withdrawal](../protocol-ref/shielded-pool.md#shielded-withdrawal) (`19`) | Withdraw funds from the shielded pool to Dash Core (L1) |
| [Identity Create From Shielded Pool](../protocol-ref/shielded-pool.md#identity-create-from-shielded-pool) (`20`) | Create a new identity funded from the shielded pool |
| [Shield from Identity](../protocol-ref/shielded-pool.md#shield-from-identity) (`21`) | Move credits from an identity balance into the [shielded pool](../explanations/shielded-pool.md) |
| [Identity Top Up From Shielded Pool](../protocol-ref/shielded-pool.md#identity-top-up-from-shielded-pool) (`22`) | Add credits to an existing identity from the shielded pool |
| Identity Key Limits Update (`23`) | Raise the credit budget or extend the expiry of one of an [identity's keys](../explanations/identity.md#keys) |
| Contract User Moderation (`24`) | A moderator action on a moderated data contract, such as banning, suspending, or warning an identity, or removing or restoring a document |
| Contract Fee Claim (`25`) | Pay out the credit action fees a data contract's document types have collected to its owner or, in equal shares, to its moderation team |
| Token Shielded Transfer With Shielded Fee (`26`) | Transfer tokens privately within a [token shielded pool](../explanations/shielded-pool.md#token-shielded-pools), paying the fee from the credit shielded pool |
| Token Unshield With Shielded Fee (`27`) | Move tokens from a token shielded pool to an identity's token balance, paying the fee from the credit shielded pool |
| Token Purchase From Shielded Pool (`28`) | Buy tokens at their direct purchase price into a token shielded pool, paying the price and fee from the credit shielded pool |

### Batch transitions

Batch transitions (payload type `1`) carry either document or token actions:

- **Document actions** — create, replace, delete, transfer, purchase, update price, and index-only delete for index-only document types. See [Document](../explanations/platform-protocol-document.md) for details.
- **Token actions** — mint, burn, transfer, freeze/unfreeze, claim, direct purchase, and set price, along with administrative actions. Tokens with a shielded pool also support [shielded pool actions](../explanations/tokens.md#shielded-pool-actions). See [Tokens](../explanations/tokens.md) for details.

### Application Usage

State transitions are constructed by client-side libraries and then submitted to the platform via [DAPI](../explanations/dapi.md). Based on the validation rules described in [DPP](../explanations/platform-protocol.md) (and an application [data contract](../explanations/platform-protocol-data-contract.md) 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](../protocol-ref/state-transition.md) page.
:::