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. The current fee rate is 1 credit/byte.

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:

Field	Type	Description
protocolVersion	integer	The platform protocol version (currently 1)
type	integer	State transition type: 0 - data contract create 1 - documents batch 2 - identity create 3 - identity topup 4 - data contract update
signature	array of bytes	Signature of state transition data (65 bytes)

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

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

State Transition Types

Data Contract Create

Field	Type	Description
dataContract	data contract object	Object containing valid data contract details
entropy	array of bytes	Entropy 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.

JavaScript

// From the JavaScript reference implementation (js-dpp)
// entropyGenerator.js
function generate() {
  return crypto.randomBytes(32);
}

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.

Documents Batch

Field	Type	Description
ownerId	array of bytes	Identity submitting the document(s) (32 bytes)
transitions	array of transition objects	Document 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

Field	Type	Description
lockedOutPoint	array of bytes	Lock outpoint from the layer 1 locking transaction (36 bytes)
publicKeys	array of keys	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	Description
lockedOutPoint	array of bytes	Lock outpoint from the layer 1 locking transaction (36 bytes)
identityId	array of bytes	An Identity ID for the identity receiving the topup (can be any identity) (32 bytes)

State Transition Signing

State transitions must be signed by a private key associated with the identity creating the state transition.

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:

Text

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 ECDSA_SECP256K1 and not ECDSA_HASH160
  ✔ should return InvalidStateTransitionSignatureError if signature is invalid