tip: 7 title: Transaction Payload description: UTXO-based transaction structure author: Luca Moser (@luca-moser)
discussions-to: https://github.com/iotaledger/tips/pull/18 status: Active type: Standards layer: Core created: 2020-07-10
In the current IOTA protocol, transactions are grouped into so-called bundles to assure that they can only be confirmed as one unit. This TIP proposes a new UTXO-based transaction structure containing all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for the messages described in the IOTA protocol TIP-6.
Currently, the vertices of the Tangle are represented by transactions, where each transaction defines either an input or output. A grouping of those input/output transaction vertices makes up a bundle which transfers the given values as an atomic unit (the entire bundle is applied or none of it). An applied bundle consumes the input transactions' funds and creates the corresponding deposits into the output transactions' target addresses. Furthermore, additional meta transactions can be part of the bundle to carry parts of the signature which do not fit into a single input transaction.
The bundle concept has proven to be very challenging in practice because of the following issues:
- Since the data making up the bundle is split across multiple vertices, it complicates the validation of the entire transfer. Instead of being able to immediately tell whether a bundle is valid or not, a node implementation must first collect all parts of the bundle before any actual validation can happen. This increases the complexity of the node implementation.
- Reattaching the tail transaction of a bundle causes the entire transfer to be reapplied.
- Due to the split across multiple transaction vertices and having to do PoW for each of them, a bundle might already be lazy in terms of where it attaches, reducing its chances to be confirmed.
To fix the problems mentioned above and to create a more flexible transaction structure, the goal is to achieve a self-contained transaction structure defining the data of the entire transfer as a payload to be embedded into a message.
The new transaction structure should fulfil the following criteria:
- Support for Ed25519 (and thus reusable addresses).
- Support for adding new types of signature schemes, addresses, inputs, and outputs as part of protocol upgrades.
- Self-contained, as in being able to validate the transaction immediately after receiving it.
- Enable unspent transaction outputs (UTXO) as inputs instead of an account based model.
The unspent transaction output (UTXO) model defines a ledger state where balances are not directly associated to addresses but to the outputs of transactions. In this model, transactions reference outputs of previous transactions as inputs, which are consumed (removed) to create new outputs. A transaction must consume all the funds of the referenced inputs.
Using a UTXO based model provides several benefits:
- Parallel validation of transactions.
- Easier double-spend detection, since conflicting transactions would reference the same UTXO.
- Replay-protection which is important when having reusable addresses. Replaying the same transaction would manifest itself as already being applied or existent and thus not have any impact.
- Technically seen, balances are no longer associated to addresses which raises the level of abstraction and thus enables other types of outputs with particular unlock criteria.
Within a transaction using UTXOs, inputs and outputs make up the to-be-signed data of the transaction. The section unlocking the inputs is called the 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:
A Transaction Payload is made up of two parts:
- The Transaction Essence part which contains the inputs, outputs and an optional embedded payload.
- The Unlock Blocks which unlock the inputs of the Transaction Essence. When an unlock block contains a signature, it signs the entire Transaction Essence part.
All values are serialized in little-endian encoding. The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence.
The Transaction ID is the BLAKE2b-256 hash of the entire serialized payload data including signatures.
The following table describes the entirety of a Transaction Payload in its serialized form following the notation from TIP-21.
|Payload Type||uint32||Set to value 0 to denote a Transaction Payload.|
Describes the essence data making up a transaction by defining its inputs, outputs and an optional payload.
|Unlock Blocks Count||uint16||The number of unlock block entries. It must match the field
Signature Unlock Block
Defines an unlock block containing a signature.
Reference Unlock Block
References a previous unlock block, where the same unlock block can be used for multiple inputs.
In general, all parts of a Transaction Payload begin with a byte describing the type of the given part. This improves the flexibility to introduce new types/versions of the given part in the future.
Transaction Essence data
The Transaction Essence of a Transaction Payload carries the inputs, outputs, and an optional payload. The Transaction Essence is an explicit type and therefore starts with its own Transaction Essence Type byte which is of value 0.
The Inputs part holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there is only one type of input, the UTXO Input. In the future, more types of inputs may be specified as part of protocol upgrades.
Each input must be accompanied by a corresponding Unlock Block at the same index in the Unlock Blocks part of the Transaction Payload.
A UTXO Input is an input which references an unspent output of a previous transaction. This UTXO is uniquely defined by the Transaction ID of that transaction together with corresponding output index. Each UTXO Input must be accompanied by an Unlock Block that is allowed to unlock the output the UTXO Input is referencing.
Example: If the input references an output 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 that are created by this Transaction Payload. The following output types are supported:
The SigLockedSingleOutput defines an output (with a certain amount) to a single target address which is unlocked via a signature proving ownership over the given address. This output supports addresses of different types.
The SigLockedDustAllowanceOutput works in the same way as a SigLockedSingleOutput but additionally controls the dust allowance on the target address. See TIP-14 for further information.
The Transaction Essence itself can contain another payload as described in general in TIP-6. The semantic validity of the encapsulating Transaction Payload does not have any impact on the payload.
The following table lists all the payload types that can be nested inside a Transaction Essence as well as links to the corresponding specification:
The Unlock Blocks part holds the unlock blocks unlocking inputs within a Transaction Essence. The following types of unlock blocks are supported:
Signature Unlock Block
A Signature Unlock Block defines an Unlock Block which holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including the optional payload).
Reference Unlock block
A Reference Unlock Block defines an Unlock Block which references a previous Unlock Block (which must not be another Reference Unlock Block). It must be used if multiple inputs can be unlocked via the same Unlock Block.
Example: Consider a Transaction Essence containing the UTXO Inputs 0, 1 and 2, where 0 and 2 are both spending outputs belonging to the same Ed25519 address A and 1 is spending from a different address B. This results in the following structure of the Unlock Blocks part:
|0||A Signature Unlock Block holding the Ed25519 signature for address A.|
|1||A Signature Unlock Block holding the Ed25519 signature for address B.|
|2||A Reference Unlock Block which references 0, as both require the same signature for A.|
A Transaction Payload has different validation stages, since some validation steps can only be executed when certain information has (or has not) been received. We therefore distinguish between syntactic and semantic validation:
Syntactic validation is checked as soon as the transaction data has been received in its entirety. It validates the structure but not the signatures of the transaction. If the transaction does not pass this stage, it must not be broadcasted further and can be discarded right away.
The following criteria defines whether a payload passes the syntactical validation:
Transaction Typevalue must denote a Transaction Essence.
Inputs Countmust be 0 < x ≤ 127.
- For each input the following must be true:
Input Typemust denote a UTXO Input.
Transaction Output Indexmust be 0 ≤ x < 127.
Inputsmust be sorted in lexicographical order of their serialized form.1
- Each pair of
Transaction Output Indexmust be unique in the inputs set.
Outputs Countmust be 0 < x ≤ 127.
- For each input the following must be true:
Output Typemust denote a SigLockedSingleOutput or a SigLockedDustAllowanceOutput.
Address Typemust denote an Ed25519 Address.
Amountmust be larger than zero.
Outputsmust be sorted in lexicographical order of their serialized form.1
Addressmust be unique per output type. For example, a SigLockedSingleOutput and a SigLockedDustAllowanceOutput can have the same address, but not two SigLockedSingleOutputs.
- The sum of all
Amountfields must not exceed the total IOTA supply of 2,779,530,283,277,761.
- Payload (if present):
Payload Typemust match one of the values described under Payload.
Data fieldsmust be correctly parsable in the context of the
- The payload itself must pass syntactic validation.
- Unlock Blocks:
Unlock Blocks Countmust match
Inputs Countof the Transaction Essence.
Unlock Typemust denote a Signature Unlock Block or a Reference Unlock Block.
- Each Signature Unlock Block must contain an Ed25519 Signature.
- Each Signature Unlock Block must be unique.
- A Reference Unlock Block at index i must have
Reference< i and the unlock block at index
Referencemust be a Signature Unlock Block.
- Given the type and length information, the Transaction Payload must consume the entire byte array of the
Payloadfield of the encapsulating object.
1 ensures that serialization of the transaction becomes deterministic, meaning that libraries always produce the same bytes given the logical transaction.
The Semantic validation of a Transaction Payload is performed when its encapsulating message is confirmed by a milestone. The semantic validity of transactions depends on the order in which they are processed. Thus, it is necessary that all the nodes in the network perform the checks in the same order, no matter the order in which the transactions are received. This is assured by using the White-Flag ordering as described in TIP-2.
Processing transactions according to the White-Flag ordering enables users to spend UTXOs which are created in the same milestone confirmation cone, as long as the spending transaction comes after the funding transaction in the aforementioned White-Flag order. In this case, it is recommended that users include the Message ID of the funding transaction as a parent of the message containing the spending transaction.
The following criteria defines whether a payload passes the semantic validation:
- Each input must reference a valid UTXO, i.e. the output referenced by the input's
Transaction Output Indexis known (booked) and unspent.
- The transaction must spend the entire balance, i.e. the sum of the
Amountfields of all the UTXOs referenced by inputs must match the sum of the
Amountfields of all outputs.
- Each unlock block must be valid with respect to the UTXO referenced by the input of the same index:
- If it is a Signature Unlock Block:
Signature Typemust match the
Address Typeof the UTXO,
- the BLAKE2b-256 hash of
Public Keymust match the
Addressof the UTXO and
Signaturefield must contain a valid signature for
- If it is a Reference Unlock Block, the referenced Signature Unlock Block must be valid with respect to the UTXO.
- If it is a Signature Unlock Block:
If a Transaction Payload passes the semantic validation, its referenced UTXOs must be marked as spent and its new outputs must be created/booked in the ledger. The Message ID of the message encapsulating the processed payload then also becomes part of the input for the White-Flag Merkle tree hash of the confirming milestone (TIP-4).
Transactions that do not pass semantic validation are ignored. Their UTXOs are not marked as spent and their outputs are not booked in the ledger.
Since transaction timestamps – whether they are signed or not – do not provide any guarantee of correctness, they have been left out of the Transaction Payload. Applications relying on some notion of time for transactions can use the local solidification time or the global timestamp of the confirming milestone (TIP-6).
While, in contrast to Winternitz one-time signatures (W-OTS), producing multiple Ed25519 signatures for the same private key and address does not decrease its security, it still drastically reduces the privacy of users. It is thus considered best practice that applications and services create a new address per deposit to circumvent these privacy issues.
In essence, Ed25519 support allows for smaller transaction sizes and to safely spend funds which were sent to an already used deposit address. Ed25519 addresses are not meant to be used like email addresses. See this Bitcoin wiki article for further information.
- The new transaction format is the core data type within the IOTA ecosystem. Changing it means that all projects need to accommodate it, including wallets, web services, client libraries and applications using IOTA in general. It is not possible to keep these changes backwards compatible, meaning that all nodes must upgrade to further participate in the network.
- Additionally, local snapshots can no longer be represented by a list of addresses and their balances, since the ledger is now made up of the UTXOs on which the actual funds reside. Therefore, local snapshot file schemes have to be adjusted to incorporate the transaction hashes, output indices, and then the destination addresses including the balances.
Rationale and alternatives
- Introducing this new transaction structure allows for extensions in the future, to accommodate new requirements. With the support for Ed25519 addresses/signatures, transaction size is drastically reduced and allows for safe re-signing in case of address reuse. Due to the switch to a complete binary transaction, the transaction size is reduced even further, saving network bandwidth and processing time.
- Other transaction structures have been considered but they would have misused existing transaction fields to accommodate for new features, instead of putting them into a proper descriptive structure. Additionally, those ideas would not have been safe against replay attacks, which deems reusing the old transaction structure, for example for Ed25519 addresses/signatures, as infeasible.
- Not switching to the new transaction structure described in this RFC would have led to more people losing funds because of W-OTS address reuse and it would prevent extending the IOTA protocol further down the line.
Copyright and related rights waived via CC0.