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:
- The Transaction Essence part contains: version, timestamp, nodeID of the aMana pledge, nodeID of the cMana pledge, inputs, outputs and an optional data payload.
- 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.
22.214.171.124 Transaction Essence
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.
|Input Type||uint8||Set to value 0 to denote an UTXO Input.|
|Transaction ID||ByteArray||The BLAKE2b-256 hash of the transaction from which the UTXO comes from.|
|Transaction Output Index||uint16||The 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.
The Outputs part holds the outputs to create with this Transaction Payload. There are different types of output:
|Output Type||uint8||Set to value 0 to denote a SigLockedSingleOutput.|
|Balance||uint64||The 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.
|Output Type||uint8||Set to value 1 to denote a SigLockedAssetOutput.|
|Balances count||uint32||The number of individual balances.|
The 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.
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.
126.96.36.199 Unlock Blocks
The Unlock Blocks part holds the unlock blocks unlocking inputs within a Transaction Essence.
There are different types of Unlock Blocks:
|Signature Unlock Block||0||An unlock block holding one or more signatures unlocking one or more inputs.|
|Reference Unlock Block||1||An 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
|Unlock Type||uint8||Set to value 0 to denote a Signature Unlock Block.|
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
|Unlock Type||uint8||Set to value 1 to denote a Reference Unlock Block.|
|Reference||uint16||Represents 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:
|0||A Signature Unlock Block holding the corresponding Ed25519 signature to unlock A and C.|
|1||A Signature Unlock Block that unlocks B.|
|2||A 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
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.
188.8.131.52 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 Versionvalue must be 0.
timestampof the Transaction Essence must be older than (or equal to) the
timestampof the message containing the transaction by at most 10 minutes.
- A Transaction Essence must contain at least one input and output.
Inputs Countmust be 0 < x < 128.
- At least one input must be specified.
Input Typevalue must be 0, denoting an
Transaction Output Indexmust be 0 ≤ x < 128.
- Every combination of
Transaction Output Indexmust be unique in the inputs set.
- Inputs must be in lexicographical order of their serialized form.1
Outputs Countmust be 0 < x < 128.
- At least one output must be specified.
Output Typemust be 0, denoting a
Address Typemust either be 0 or 1, denoting an
Addressmust be unique in the set of
Amountmust be > 0.
- Outputs must be in lexicographical order by their serialized form.1
- Accumulated output balance must not exceed the total supply of tokens
Payload Lengthmust be 0 (to indicate that there's no payload) or be valid for the specified payload type.
Payload Typemust be one of the supported payload types if
Payload Lengthis not 0.
Unlock Blocks Countmust match the number of inputs. Must be 0 < x < 128.
Unlock Block Typemust either be 0 or 1, denoting a
Signature Unlock Blockor
Reference Unlock block.
Signature Unlock Blocksmust define either an
Signature Unlock Blockunlocking 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 Blockmust have a companion
Reference Unlock Blockat the same index as the corresponding input that points to the origin
Signature Unlock Block.
Reference Unlock Blocksmust specify a previous
Unlock Blockthat 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 Lengthfield in the Message defines.
184.108.40.206 Transaction Semantic Validation
The following criteria define whether the transaction passes the semantic validation:
- All the UTXOs the transaction references are known (booked) and unspent.
- The transaction is spending the entirety of the funds of the referenced UTXOs to the outputs.
- The address type of the referenced UTXO must match the signature type contained in the corresponding Signature Unlock Block.
- 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.