Skip to main content

5.1 UTXO

5.1.1 Introduction

The unspent transaction output (UTXO) model defines a ledger state where balances are not directly associated with addresses but with the outputs of transactions. In this model, transactions specify the outputs of previous transactions as inputs, which are consumed in order to create new outputs. A transaction must consume the entirety of the specified inputs. The section unlocking the inputs is called an unlock block. An unlock block may contain a signature proving ownership of a given input's address and/or other unlock criteria.

The following image depicts the flow of funds using UTXO:

Image 5.1.1: Flow of funds using UTXO.

The UTXO specification depends on the following specifications:

5.1.2 Transaction Layout

A Transaction payload is made up of two parts:

  1. The Transaction Essence part contains: version, timestamp, nodeID of the aMana pledge, nodeID of the cMana pledge, inputs, outputs and an optional data payload.
  2. The Unlock Blocks which unlock the Transaction Essence's inputs. In case the unlock block contains a signature, it signs the entire Transaction Essence part.

All values are serialized in little-endian encoding (it stores the most significant byte of a word at the largest address and the smallest byte at the smallest address). The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence.

The table describing the entirety of a Transaction's serialized form is presented in the Section 2.3 Standard Payloads Layout.

See [Data Types Notation 🛠️] for understanding the table schema.

5.1.2.1 Transaction Essence

The Transaction Essence of a Transaction carries a version, timestamp, nodeID of the aMana pledge, nodeID of the cMana pledge, inputs, outputs and an optional data payload.

5.1.2.2 Inputs

The Inputs part holds the inputs to consume, that in turn fund the outputs of the Transaction Essence. There is only one supported type of input as of now, the UTXO Input. In the future, more types of inputs may be specified as part of protocol upgrades.

Each defined input must be accompanied by a corresponding Unlock Block at the same index in the Unlock Blocks part of the Transaction. If multiple inputs may be unlocked through the same Unlock Block, the given Unlock Block only needs to be specified at the index of the first input that gets unlocked by it. Subsequent inputs that are unlocked through the same data must have a Reference Unlock Block pointing to the previous Unlock Block. This ensures that no duplicate data needs to occur in the same transaction.

UTXO Input

NameTypeDescription
Input Typeuint8Set to value 0 to denote an UTXO Input.
Transaction IDByteArray[32]The BLAKE2b-256 hash of the transaction from which the UTXO comes from.
Transaction Output Indexuint16The index of the output on the referenced transaction to consume.

Table 5.1.2: UTXO Input

A UTXO Input is an input which references an output of a previous transaction by using the given transaction's BLAKE2b-256 hash + the index of the output on that transaction. A UTXO Input must be accompanied by an Unlock Block for the corresponding type of output the UTXO Input is referencing.

Example: If the input references outputs to an Ed25519 address, then the corresponding unlock block must be of type Signature Unlock Block holding an Ed25519 signature.

5.1.2.3 Outputs

The Outputs part holds the outputs to create with this Transaction Payload. There are different types of output:

  • SigLockedSingleOutput
  • SigLockedAssetOutput

SigLockedSingleOutput

NameTypeDescription
Output Typeuint8Set to value 0 to denote a SigLockedSingleOutput.
Address oneOf
Ed25519 Address
NameTypeDescription
Address Typeuint8Set to value 0 to denote an Ed25519 Address.
AddressByteArray[32]The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key.
BLS Address
NameTypeDescription
Address Typeuint8Set to value 1 to denote a BLS Address.
AddressByteArray[49]The raw bytes of the BLS address which is a BLAKE2b-256 hash of the BLS public key.
Balanceuint64The balance of IOTA tokens to deposit with this SigLockedSingleOutput output.

Table 5.1.3: The SigLockedSingleOutput

The SigLockedSingleOutput defines an output holding an IOTA balance linked to a single address; it is unlocked via a valid signature proving ownership over the given address. Such output may hold an address of different types.

SigLockedAssetOutput

NameTypeDescription
Output Typeuint8Set to value 1 to denote a SigLockedAssetOutput.
Address oneOf
Ed25519 Address
NameTypeDescription
Address Typeuint8Set to value 0 to denote an Ed25519 Address.
AddressByteArray[32]The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key.
BLS Address
NameTypeDescription
Address Typeuint8Set to value 1 to denote a BLS Address.
AddressByteArray[49]The raw bytes of the BLS address which is a BLAKE2b-256 hash of the BLS public key.
Balances countuint32The number of individual balances.
AssetBalance anyOf
Asset Balance
The balance of the tokenized asset.
NameTypeDescription
AssetIDByteArray[32]The ID of the tokenized asset
Balanceuint64The balance of the tokenized asset.

Table 5.1.4: The SigLockedAssetOutput

The SigLockedAssetOutput defines an output holding a balance for each specified tokenized asset linked to a single address; it is unlocked via a valid signature proving ownership over the given address. Such output may hold an address of different types. The ID of any tokenized asset is defined by the BLAKE2b-256 hash of the OutputID that created the asset.

5.1.2.4 Payload

The payload part of a Transaction Essence may hold an optional payload. This payload does not affect the validity of the Transaction Essence. If the transaction is not valid, then the payload shall be discarded.

5.1.2.5 Unlock Blocks

The Unlock Blocks part holds the unlock blocks unlocking inputs within a Transaction Essence.

There are different types of Unlock Blocks:

NameUnlock TypeDescription
Signature Unlock Block0An unlock block holding one or more signatures unlocking one or more inputs.
Reference Unlock Block1An unlock block which must reference a previous unlock block which unlocks also the input at the same index as this Reference Unlock Block.

Table 5.1.5: Types of Unlock Blocks

Signature Unlock Block

NameTypeDescription
Unlock Typeuint8Set to value 0 to denote a Signature Unlock Block.
Signature oneOf
BLS Signature
NameTypeDescription
Signature Typeuint8Set to value 0 to denote a BLS Signature.
SignatureByteArrayThe signature signing the serialized Transaction Essence.
Ed25519 Signature
NameTypeDescription
Signature Typeuint8Set to value 1 to denote an Ed25519 Signature.
Public keyByteArray[32]The public key of the Ed25519 keypair which is used to verify the signature.
SignatureByteArray[64]The signature signing the serialized Transaction Essence.

Table 5.1.6: The Signature Unlock Block

A Signature Unlock Block defines an Unlock Block which holds one or more signatures unlocking one or more inputs. Such a block signs the entire Transaction Essence part of a Transaction Payload including the optional payload.

Reference Unlock block

NameTypeDescription
Unlock Typeuint8Set to value 1 to denote a Reference Unlock Block.
Referenceuint16Represents the index of a previous unlock block.

Table 5.1.7: The Reference Unlock Block

A Reference Unlock Block defines an Unlock Block that references a previous Unlock Block (that must not be another Reference Unlock Block). It must be used if multiple inputs can be unlocked through the same origin Unlock Block.

Example: Consider a Transaction Essence containing UTXO Inputs A, B and C, where A and C are both spending the UTXOs originating from the same Ed25519 address. The Unlock Block part must thereby have the following structure:

IndexMust Contain
0A Signature Unlock Block holding the corresponding Ed25519 signature to unlock A and C.
1A Signature Unlock Block that unlocks B.
2A Reference Unlock Block that references index 0, since C also gets unlocked by the same signature as A.

Table 5.1.8: Example of Unlock Block

5.1.3 Validation

A Transaction payload has different validation stages since some validation steps can only be executed at the point when certain information has (or has not) been received. We, therefore, distinguish between syntactical and semantic validation.

5.1.3.1 Transaction Syntactical Validation

This validation can commence as soon as the transaction data has been received in its entirety. It validates the structure but not the signatures of the transaction. A transaction must be discarded right away if it does not pass this stage.

The following criteria define whether the transaction passes the syntactical validation:

  • Transaction Essence:
    • Transaction Essence Version value must be 0.
    • The timestamp of the Transaction Essence must be older than (or equal to) the timestamp of the message containing the transaction by at most 10 minutes.
    • A Transaction Essence must contain at least one input and output.
  • Inputs:
    • Inputs Count must be 0 < x < 128.
    • At least one input must be specified.
    • Input Type value must be 0, denoting an UTXO Input.
    • UTXO Input:
      • Transaction Output Index must be 0 ≤ x < 128.
      • Every combination of Transaction ID + Transaction Output Index must be unique in the inputs set.
    • Inputs must be in lexicographical order of their serialized form.1
  • Outputs:
    • Outputs Count must be 0 < x < 128.
    • At least one output must be specified.
    • Output Type must be 0, denoting a SigLockedSingleOutput.
    • SigLockedSingleOutput:
      • Address Type must either be 0 or 1, denoting an Ed25519 - or BLS address .
      • The Address must be unique in the set of SigLockedSingleOutputs.
      • Amount must be > 0.
    • Outputs must be in lexicographical order by their serialized form.1
    • Accumulated output balance must not exceed the total supply of tokens 2,779,530,283,277,761.
  • Payload Length must be 0 (to indicate that there's no payload) or be valid for the specified payload type.
  • Payload Type must be one of the supported payload types if Payload Length is not 0.
  • Unlock Blocks Count must match the number of inputs. Must be 0 < x < 128.
  • Unlock Block Type must either be 0 or 1, denoting a Signature Unlock Block or Reference Unlock block.
  • Signature Unlock Blocks must define either an Ed25519- or BLS Signature.
  • A Signature Unlock Block unlocking multiple inputs must only appear once (be unique) and be positioned at the same index of the first input it unlocks. All other inputs unlocked by the same Signature Unlock Block must have a companion Reference Unlock Block at the same index as the corresponding input that points to the origin Signature Unlock Block.
  • Reference Unlock Blocks must specify a previous Unlock Block that is not of type Reference Unlock Block. The referenced index must therefore be smaller than the index of the Reference Unlock Block.
  • Given the type and length information, the Transaction must consume the entire byte array the Payload Length field in the Message defines.
1 ensures that serialization of the transaction becomes deterministic, meaning that libraries always produce the same bytes given the logical transaction.

5.1.3.2 Transaction Semantic Validation

The following criteria define whether the transaction passes the semantic validation:

  1. All the UTXOs the transaction references are known (booked) and unspent.
  2. The transaction is spending the entirety of the funds of the referenced UTXOs to the outputs.
  3. The address type of the referenced UTXO must match the signature type contained in the corresponding Signature Unlock Block.
  4. The Signature Unlock Blocks are valid, i.e. the signatures prove ownership over the addresses of the referenced UTXOs.

If a transaction passes the semantic validation, its referenced UTXOs shall be marked as spent and the corresponding new outputs shall be booked/specified in the ledger. This process is described in Section 5.2 - Ledger state.

Transactions that do not pass semantic validation shall be discarded. Their UTXOs are not marked as spent and neither are their outputs booked into the ledger. Moreover, their messages shall be considered invalid.