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: Replaced
type: Standards
layer: Core
created: 2020-07-10
superseded-by: TIP-20

Summary

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.

Motivation

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.

Detailed design

UTXO

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:

Structure

Serialized layout

A Transaction Payload is made up of two parts:

1. The Transaction Essence part which contains the inputs, outputs and an optional embedded payload.
2. 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.

Transaction parts

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.

Inputs

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.

UTXO Input

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.

Outputs

The Outputs part holds the outputs that are created by this Transaction Payload. The following output types are supported:

SigLockedSingleOutput

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.

SigLockedDustAllowanceOutput

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.

Payload

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:

Unlock Blocks

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:

Validation

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

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:

• Essence:
  • Transaction Type value must denote a Transaction Essence.
  • Inputs:
    • Inputs Count must be 0 < x ≤ 127.
    • For each input the following must be true:
      • Input Type must denote a UTXO Input.
      • Transaction Output Index must be 0 ≤ x < 127.
    • Inputs must be sorted in lexicographical order of their serialized form.¹
    • Each pair of Transaction ID and Transaction Output Index must be unique in the inputs set.
  • Outputs:
    • Outputs Count must be 0 < x ≤ 127.
    • For each input the following must be true:
      • Output Type must denote a SigLockedSingleOutput or a SigLockedDustAllowanceOutput.
      • Address Type must denote an Ed25519 Address.
      • Amount must be larger than zero.
    • Outputs must be sorted in lexicographical order of their serialized form.¹
    • Each Address must 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 Amount fields must not exceed the total IOTA supply of 2,779,530,283,277,761.
  • Payload (if present):
    • Payload Type must match one of the values described under Payload.
    • Data fields must be correctly parsable in the context of the Payload Type.
    • The payload itself must pass syntactic validation.
• Unlock Blocks:
  • Unlock Blocks Count must match Inputs Count of the Transaction Essence.
  • Each Unlock Type must 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 Reference must be a Signature Unlock Block.
• Given the type and length information, the Transaction Payload must consume the entire byte array of the Payload field of the encapsulating object.

¹ ensures that serialization of the transaction becomes deterministic, meaning that libraries always produce the same bytes given the logical transaction.

Semantic validation

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 ID and Transaction Output Index is known (booked) and unspent.
• The transaction must spend the entire balance, i.e. the sum of the Amount fields of all the UTXOs referenced by inputs must match the sum of the Amount fields 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:
    • The Signature Type must match the Address Type of the UTXO,
    • the BLAKE2b-256 hash of Public Key must match the Address of the UTXO and
    • the Signature field must contain a valid signature for Public Key.
  • If it is a Reference Unlock Block, the referenced Signature Unlock Block must be valid with respect to the UTXO.

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.

Miscellaneous

Transaction timestamps

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).

Address reuse

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.

Drawbacks

• 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

Copyright and related rights waived via CC0.