State Transition

State Transition Overview

State transitions are the means for submitting data that creates, updates, or deletes platform data and results in a change to a new state. Each one must contain:

• Common fields present in all state transitions

• Additional fields specific to the type of action the state transition provides (e.g., creating an identity)

Fees

State transition fees are paid via the credits established when an identity is created. Credits are created at a rate of 1000 credits/satoshi. Fees for actions vary based on parameters related to storage and computational effort that are defined in rs-dpp.

Size

State transitions are limited to a maximum size of 20 KB.

Common Fields

The list of common fields used by multiple state transitions is defined in rs-dpp. All state transitions include the following fields:

Field	Type	Size	Description
$version	unsigned integer	16 bits	The state transition format version (FeatureVersion). Currently 0 for most transitions, 1 for Batch. This is not the global platform protocol version, which is negotiated separately.
type	unsigned integer	8 bits	State transition type (defined in rs-dpp): 0 - data contract create 1 - batch 2 - identity create 3 - identity topup 4 - data contract update 5 - identity update 6 - identity credit withdrawal 7 - identity credit transfer 8 - masternode vote 9 - identity credit transfer to addresses 10 - identity create from addresses 11 - identity topup from addresses 12 - address funds transfer 13 - address funding from asset lock 14 - address credit withdrawal 15 - shield 16 - shielded transfer 17 - unshield 18 - shield from asset lock 19 - shielded withdrawal
userFeeIncrease	unsigned integer	16 bits	Extra fee to prioritize processing if the mempool is full. Typically set to zero.
signature	array of bytes	65 bytes	Signature of state transition data

Note

The masternode vote transition does not include the userFeeIncrease field.

Additionally, all state transitions except the identity create and topup state transitions include:

Field	Type	Size	Description
signaturePublicKeyId	unsigned integer	32 bits	The id of the identity public key that signed the state transition (=> 0)

State Transition Types

Dash Platform Protocol defines the state transition types that perform identity, contract, document, and token operations. See the subsections below for details on each state transition type.

Batch

Field	Type	Size	Description
ownerId	array of bytes	32 bytes	Identity submitting the document(s)
transitions	array of transition objects	Varies	A batch of document or token actions (currently limited to 1 object per batch)

More detailed information about the transitions array can be found in the document section. See the implementation in rs-dpp.

Data Contract Create

Field	Type	Size	Description
dataContract	data contract object	Varies	Object containing valid data contract details
identityNonce	unsigned integer	64 bits	Identity nonce for this transition to prevent replay attacks

More detailed information about the dataContract object can be found in the data contract section.

Data Contract Update

Field	Type	Size	Description
dataContract	data contract object	Varies	Object containing valid data contract details
identityContractNonce	unsigned integer	64 bits	Identity contract nonce for replay protection

More detailed information about the dataContract object can be found in the data contract section.

Identity Create

Field	Type	Size	Description
assetLockProof	array of bytes	36 bytes	Lock outpoint from the layer 1 locking transaction (36 bytes)
publicKeys	array of keys	Varies	Public key(s) associated with the identity (maximum number of keys: 6)

More detailed information about the publicKeys object can be found in the identity section.

Identity TopUp

Field	Type	Size	Description
assetLockProof	array of bytes	36 bytes	Lock outpoint from the layer 1 locking transaction (36 bytes)
identityId	array of bytes	32 bytes	An Identity ID for the identity receiving the topup (can be any identity) (32 bytes)

Identity Update

Field	Type	Size	Description
identityId	array of bytes	32 bytes	The Identity ID for the identity being updated
revision	unsigned integer	64 bits	Identity update revision. Used for optimistic concurrency control. Incremented by one with each new update so that the update will fail if the underlying data is modified between reading and writing.
nonce	unsigned integer	64 bits	Identity nonce for this transition to prevent replay attacks
addPublicKeys	array of public keys	Varies	(Optional) Array of up to 6 new public keys to add to the identity. Required if adding keys.
disablePublicKeys	array of integers	Varies	(Optional) Array of up to 10 existing identity public key ID(s) to disable for the identity. Required if disabling keys.

Identity Credit Transfer

Field	Type	Size	Description
identityId	array of bytes	32 bytes	An Identity ID for the identity sending the credits
recipientId	array of bytes	32 bytes	An Identity ID for the identity receiving the credits
amount	unsigned integer	64 bits	Number of credits being transferred
nonce	unsigned integer	64 bits	Identity nonce for this transition to prevent replay attacks

See the implementation in rs-dpp.

Identity Credit Withdrawal

Field	Type	Size	Description
identityId	array of bytes	32 bytes	An Identity ID for the identity sending the credits
amount	unsigned integer	64 bits	Number of credits being transferred
coreFeePerByte	unsigned integer	32 bits
pooling	unsigned integer	8 bits	0 = Never, 1 = If Available, 2 = Standard
outputScript	script	Varies	If None, the withdrawal is sent to the address set by Core
nonce	unsigned integer	64 bits	Identity nonce for this transition to prevent replay attacks

See the implementation in rs-dpp.

Masternode Vote

Field	Type	Size	Description
proTxHash	array of bytes	32 bytes	An identifier based on a masternode or evonode’s provider registration transaction hash
voterIdentityId	array of bytes	32 bytes	The voter’s Identity ID. This will be a masternode identity based on the protx hash.
vote	Vote	Varies	Vote information
nonce	unsigned integer	64 bits	Identity nonce for this transition to prevent replay attacks

See the implementation in rs-dpp.

State Transition Signing

State transitions must be cryptographically signed to prove that an authorized party submitted them. There are three ways to sign state transitions, with the difference being the source of the private key used for signing. The following table specifies which signing method is used by each state transition type:

Signing Method	State Transitions
Identity	Batch, Contract create, Contract update, Identity update, Identity credit transfer, Identity credit transfer to addresses, Identity credit withdrawal, Masternode vote
Asset lock	Identity create, Identity topup, Address funding from asset lock*
Address witness	Identity create from addresses, Identity topup from addresses, Address funds transfer, Address credit withdrawal, Address funding from asset lock*

* Address funding from asset lock requires both an asset lock signature and address witnesses (input_witnesses).

Note

Shield-related state transitions (types 15-19: Shield, ShieldedTransfer, Unshield, ShieldFromAssetLock, ShieldedWithdrawal) are defined in the protocol but their signing methods are not yet documented here.

Note

Address-based state transitions (types 9-14) were introduced in Protocol Version 11. For detailed information on these transitions, see Address-Based State Transitions.

Signing with Asset Lock

The identity create and topup state transition signatures are unique in that they must be signed by the private key used in the Core chain asset lock transaction funding the identity. The signing process consists of the following steps:

1. Create a canonical, signable state transition encoded using Bincode.

   • Exclude the signature field and any other non-signable fields indicated in the table below.

2. Calculate the double SHA-256 hash of the encoded signable state transition.

3. Sign the computed hash using the private key associated with the asset lock transaction.

4. Store the signature in the state transition’s signature field.

5. For identity create only, sign any public keys as described in the signing public keys section.

6. Finalize the state transition by re-encoding it with Bincode, including all previously excluded fields such as signature.

Signing with Identity

Most state transitions must be signed by a private key associated with the identity creating the state transition. Each identity must have at least two keys: a primary key (security level 0) that is only used when signing identity update state transitions and an additional key (security level 2) that is used to sign all other state transitions.

The process to sign state transitions using an identity consists of the following steps:

1. Create a canonical, signable state transition encoded using Bincode.

   • Certain fields must excluded before signing. See the non-signable fields table for details.

2. Calculate the double SHA-256 hash of the encoded signable state transition.

3. Sign the computed hash using the identity’s relevant private key.

4. Store the signature in the state transition’s signature field

5. For identity update only, sign any added public keys as described in the signing public keys section.

6. Finalize the state transition by re-encoding it with Bincode, including all previously excluded fields such as signature.

Signing with Address Witness

Address-based state transitions (types 10-12, 14) use address witnesses to prove ownership of Platform addresses. Unlike identity-signed transitions, these do not require an existing identity. Instead, each input address requires a corresponding witness containing cryptographic proof of address ownership.

Note

Identity credit transfer to addresses (type 9) is not signed with address witnesses — it uses identity signing because it requires an existing identity.

The process to sign state transitions using address witnesses consists of the following steps:

1. Create a canonical, signable state transition encoded using Bincode.

   • Exclude the input_witnesses field and any other non-signable fields.

2. Calculate the double SHA-256 hash of the encoded signable state transition.

3. For each input address, create an appropriate witness:

   • P2PKH addresses: Create a recoverable ECDSA signature (65 bytes) using the private key that derives the address.

   • P2SH multisig addresses: Collect the required number of signatures and include the redeem script.

4. Store witnesses in the state transition’s input_witnesses field in the same order as inputs.

5. Finalize the state transition by re-encoding it with Bincode, including all previously excluded fields.

For detailed information on address witnesses and Platform addresses, see Address-Based State Transitions.

Signing public keys

Public keys can be added to an identity by the identity create or identity update state transitions. Any new public keys must include a signature to prove that the associated private key is accessible. To sign new public keys:

1. Get the double SHA-256 hash of the encoded signable state transition from step 2 of the signing with asset lock or signing with identity section.

2. Sign each new public key:

   • Use the private key that derived the public key to sign the hash.

   • Store the result in the public key’s signature field.

Non-signable Fields

This table shows the fields that must be excluded when creating state transition signatures. All transitions exclude the signature field. Some transitions contain other fields that must be excluded also. Click the state transition name to see the rs-dpp implementation for additional context.

State transition	Signature	Signature public key ID	Identity ID	Identity public key signature(s)
Batch	Exclude	Exclude	N/A	N/A
Contract create	Exclude	Exclude	N/A	N/A
Contract update	Exclude	Exclude	N/A	N/A
Identity create	Exclude	N/A	Exclude	Exclude
Identity topup	Exclude	N/A	N/A	N/A
Identity update	Exclude	Exclude	N/A	Exclude for any keys being added by the state transition
Identity credit transfer	Exclude	Exclude	N/A	N/A
Identity credit withdrawal	Exclude	Exclude	N/A	N/A
Masternode vote	Exclude	Exclude	N/A	N/A