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

All serialized data (including state transitions) is limited to a maximum size of 16 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	32 bits	The platform protocol version (currently 1)
type	unsigned integer	8 bits	State transition type: 0 - data contract create 1 - batch 2 - identity create 3 - identity topup 4 - data contract update 5 - identity update 6 - identity credit transfer 7 - identity credit withdrawal 8 - masternode vote
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

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 (up to 10 objects)

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
entropy	array of bytes	32 bytes	Entropy used to generate the data contract ID

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

Entropy Generation

Entropy is included in Data Contracts and Documents. Dash Platform using the following entropy generator found in rs-dpp:

// From the Rust reference implementation (rs-dpp)
// entropyGenerator.js
fn generate(&self) -> anyhow::Result<[u8; 32]> {
  let mut buffer = [0u8; 32];
  getrandom(&mut buffer).context("generating entropy failed")?;
  Ok(buffer)
}

Data Contract Update

Field	Type	Description
dataContract	data contract object	Object containing valid data contract details

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: 10)

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 10 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 bytes
pooling	unsigned integer	8 bytes	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 two 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 withdrawal, Masternode vote
Asset lock	Identity create, Identity topup

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 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