Guides
Dash CoreDash PlatformDash.orgDash User DocsLog In
Guides

State Transition

🚧

New site!

All content has been migrated to docs.dash.org. You will be automatically redirected momentarily.

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:

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

All state transitions include the following fields:

FieldTypeDescription
protocolVersionintegerThe platform protocol version (currently 1)
typeintegerState transition type:
0 - data contract create
1 - documents batch
2 - identity create
3 - identity topup
4 - data contract update
5 - identity update
signaturearray of bytesSignature of state transition data (65 bytes)

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

FieldTypeDescription
signaturePublicKeyIdintegerThe id of the identity public key that signed the state transition (=> 0)

State Transition Types

Data Contract Create

FieldTypeDescription
dataContractdata contract objectObject containing valid data contract details
entropyarray of bytesEntropy used to generate the data contract ID (32 bytes)

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.

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

FieldTypeDescription
dataContractdata contract objectObject containing valid data contract details

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

Documents Batch

FieldTypeDescription
ownerIdarray of bytesIdentity submitting the document(s) (32 bytes)
transitionsarray of transition objectsDocument create, replace, or delete transitions (up to 10 objects)

More detailed information about the transitions array can be found in the document section.

Identity Create

FieldTypeDescription
assetLockProofarray of bytesLock outpoint from the layer 1 locking transaction (36 bytes)
publicKeysarray of keysPublic 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

FieldTypeDescription
assetLockProofarray of bytesLock outpoint from the layer 1 locking transaction (36 bytes)
identityIdarray of bytesAn Identity ID for the identity receiving the topup (can be any identity) (32 bytes)

Identity Update

FieldTypeDescription
identityIdarray of bytesThe Identity ID for the identity being updated (32 bytes)
revisionintegerIdentity 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.
addPublicKeysarray of public keys(Optional) Array of up to 10 new public keys to add to the identity. Required if adding keys.
disablePublicKeysarray of integers(Optional) Array of up to 10 existing identity public key ID(s) to disable for the identity. Required if disabling keys.
publicKeysDisabledAtinteger(Optional) Timestamp when keys were disabled. Required if disablePublicKeys is present.

State Transition Signing

State transitions must be signed by a private key associated with the identity creating the state transition. Since v0.23, 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 a state transition consists of the following steps:

  1. Canonical CBOR encode the state transition data - this include all ST fields except the signature and signaturePublicKeyId
  2. Sign the encoded data with a private key associated with the identity creating the state transition
  3. Set the state transition signature to the value of the signature created in the previous step
  4. For all state transitions other than identity create or topup, set the state transitionsignaturePublicKeyId to the public key id corresponding to the key used to sign

Signature Validation

The signature validation (see js-dpp) verifies that:

  1. The identity exists
  2. The identity has a public key
  3. The identity's public key is of type ECDSA
  4. The state transition signature is valid

The example test output below shows the necessary criteria:

validateStateTransitionIdentitySignatureFactory
  βœ” should pass properly signed state transition
  βœ” should return invalid result if owner id doesn't exist
  βœ” should return MissingPublicKeyError if the identity doesn't have a matching public key
  βœ” should return InvalidIdentityPublicKeyTypeError if type is not exist
  βœ” should return InvalidStateTransitionSignatureError if signature is invalid
  Consensus errors
    βœ” should return InvalidSignaturePublicKeySecurityLevelConsensusError if InvalidSignaturePublicKeySecurityLevelError was thrown
    βœ” should return PublicKeySecurityLevelNotMetConsensusError if PublicKeySecurityLevelNotMetError was thrown
    βœ” should return WrongPublicKeyPurposeConsensusError if WrongPublicKeyPurposeError was thrown
    βœ” should return PublicKeyIsDisabledConsensusError if PublicKeyIsDisabledError was thrown
    βœ” should return InvalidStateTransitionSignatureError if DPPError was thrown
    βœ” should throw unknown error
    βœ” should not verify signature on dry run