From 469fe2cb6078d524267213c7797663e651431e41 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 18 Nov 2021 17:26:25 +0100 Subject: [PATCH 01/40] Update Transaction Payload and Validation for RFC-0038 New output types, unlock blocks and output feature blocks are introduced in RFC-0038 that modify the Transaction Payload structure and validation rules. --- .../0018-transaction-payload.md | 483 +++++++++++------- 1 file changed, 296 insertions(+), 187 deletions(-) diff --git a/text/0018-transaction-payload/0018-transaction-payload.md b/text/0018-transaction-payload/0018-transaction-payload.md index f3d2d19c4..a8ca0aaa0 100644 --- a/text/0018-transaction-payload/0018-transaction-payload.md +++ b/text/0018-transaction-payload/0018-transaction-payload.md @@ -1,6 +1,8 @@ + Feature name: `transaction-payload` + Start date: 2020-07-10 + RFC PR: [iotaledger/protocol-rfcs#18](https://github.com/iotaledger/protocol-rfcs/pull/18) ++ Recent updates: + + () Update Payload Layout and Validation for [New Output Types](https://github.com/iotaledger/protocol-rfcs/pull/38) # Summary @@ -43,17 +45,20 @@ The following image depicts the flow of funds using UTXO: ## Structure -### Serialized layout +### 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. +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 Transaction Essence's inputs. In case the unlock block contains a + signature, it signs the Blake2b-256 hash of the serialized 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. +All values are serialized in little-endian encoding. In contrast to the [current IOTA protocol](https://github.com/iotaledger/protocol-rfcs/pull/18) +inputs and outputs are encoded as lists, which means that they can contain duplicates and may not be sorted. -The *Transaction ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including signatures. +A [Blake2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized data makes up +Transaction Payload's ID. -The following table structure describes the entirety of a _Transaction Payload_ in its serialized form: +Following table structure describes the entirety of a Transaction Payload's serialized form. * Data Type Notation, see [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html#data-types) *
Subschema Notation @@ -75,7 +80,9 @@ The following table structure describes the entirety of a _Transaction Payload_ Any (one or more) of the listed subschemas. -
+ +* New output types and unlock blocks are discussed in detail in [RFC-38](https://github.com/iotaledger/protocol-rfcs/pull/38), + but they are mentioned in the payload structure to help the reader understand their context.

@@ -162,108 +169,35 @@ The following table structure describes the entirety of a _Transaction Payload_ Outputs anyOf
- SigLockedSingleOutput + SimpleOutput
Describes a deposit to a single address which is unlocked via a signature.
- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
Output Typeuint8 - Set to value 0 to denote a SigLockedSingleOutput. -
Address oneOf -
- Ed25519 Address - - - - - - - - - - - - - - - - -
NameTypeDescription
Address Typeuint8 - Set to value 0 to denote an Ed25519 Address. -
AddressByteArray[32]The raw bytes of the Ed25519 address which is the BLAKE2b-256 hash of the public key.
-
-
Amountuint64The amount of tokens to deposit.
- SigLockedDustAllowanceOutput + ExtendedOutput
- Describes a deposit which as a special property also alters the dust allowance of the target address. + Describes a deposit to a single address. The output might contain optional feature + blocks and native tokens. +
+
+
+ AliasOutput +
+ Describes an alias account in the ledger. +
+
+
+ FoundryOutput +
+ Describes a foundry that controls supply of native tokens. +
+
+
+ NFTOutput +
+ Describes a unique, non-fungible token deposit to a single address.
- - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
Output Typeuint8 - Set to value 1 to denote a SigLockedDustAllowanceOutput. -
Address oneOf -
- Ed25519 Address - - - - - - - - - - - - - - - - -
NameTypeDescription
Address Typeuint8 - Set to value 0 to denote an Ed25519 Address. -
AddressByteArray[32]The raw bytes of the Ed25519 address which is the BLAKE2b-256 hash of the public key.
-
-
Amountuint64The amount of tokens to deposit.
@@ -308,15 +242,15 @@ The following table structure describes the entirety of a _Transaction Payload_ Unlock Blocks Count uint16 - The number of unlock block entries. It must match the field Inputs Count. + The number of unlock block entries. It must match the field Inputs Count. Unlock Blocks anyOf -
+
Signature Unlock Block
- Defines an unlock block containing a signature. + Defines an unlock block containing a signature unlocking input(s).
@@ -365,7 +299,7 @@ The following table structure describes the entirety of a _Transaction Payload_
-
+
Reference Unlock Block
References a previous unlock block, where the same unlock block can be used for multiple inputs. @@ -390,48 +324,136 @@ The following table structure describes the entirety of a _Transaction Payload_
+
+ Alias Unlock Block +
+ Points to the unlock block of a consumed alias output. +
+ + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 2 to denote an Alias Unlock Block. +
Alias Reference Unlock Indexuint16Index of input and unlock block corresponding to an alias output.
+
+
+ NFT Unlock Block +
+ Points to the unlock block of a consumed NFT output. +
+ + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 3 to denote a NFT Unlock Block. +
NFT Reference Unlock Indexuint16Index of input and unlock block corresponding to an NFT output.
+
-### Transaction parts +### 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. +In general, all parts of a Transaction Payload begin with a byte describing the type of the given part to keep +the flexibility to introduce new types/versions of the given part in the future. -#### Transaction Essence data +#### 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 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. +The Inputs part holds the inputs to consume, respectively, to fund the outputs of the +Transaction Essence. There is only one 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 input must be accompanied by a corresponding Unlock Block at the same index in the Unlock Blocks +part of the Transaction Payload. + +If multiple inputs can be unlocked through the same Unlock Block, then the given Unlock Block only needs +to be specified at the index of the first input which gets unlocked by it. -Each input must be accompanied by a corresponding Unlock Block at the same index in the Unlock Blocks part of the Transaction Payload. +Subsequent inputs which are unlocked through the same data must have a Reference Unlock Block, +Alias Unlock Block or NFT Unlock Block depending on the unlock mechanism, pointing to the index of a +previous Unlock Block. This ensures that no duplicate data needs to occur in the same transaction. ###### 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. +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. +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: +The Outputs part holds the outputs that are created by this Transaction Payload. The following output +types are supported: + +###### SimpleOutput + +Formerly known as SigLockedSingleOutput, the SimpleOutput 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. + +###### ExtendedOutput -###### SigLockedSingleOutput +An output to a single target address that may carry native tokens and optional feature blocks. Defined in +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#extended-output) -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. +###### AliasOutput -###### SigLockedDustAllowanceOutput +An output that represents an alias account in the ledger. Defined in +[RFC-0038](#https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-output) -The SigLockedDustAllowanceOutput works in the same way as a SigLockedSingleOutput but additionally controls the dust allowance on the target address. See [Dust Protection RFC-0032 (draft)](https://github.com/iotaledger/protocol-rfcs/pull/32) for further information. +###### FoundryOutput + +An output that represents a token foundry in the ledger. Defined in +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#foundry-output) + +###### NFTOutput + +An output that represents a non-fungible token in the ledger. Defined in +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-output) ##### Payload -The _Transaction Essence_ itself can contain another payload as described in general in [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html). The [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ does not have any impact on the payload. +The _Transaction Essence_ itself can contain another payload as described in general in [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html). +The [semantic validity](#semantic-validation) 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 following table lists all the payload types that can be nested inside a _Transaction Essence_ as well as links to +the corresponding specification: | Name | Type Value | RFC | | ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | @@ -439,18 +461,52 @@ The following table lists all the payload types that can be nested inside a _Tra #### Unlock Blocks -The Unlock Blocks part holds the unlock blocks unlocking inputs within a Transaction Essence. The following types of unlock blocks are supported: +The Unlock Blocks part holds the unlock blocks unlocking inputs within a Transaction Essence. The +following types of unlock blocks are supported: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Signature Unlock Block0An unlock block holding a signature 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.
Alias Unlock Block2An unlock block which must reference a previous unlock block which unlocks the alias that the input is locked to.
NFT Unlock Block3An unlock block which must reference a previous unlock block which unlocks the NFT that the input is locked to.
##### 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). +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 +##### 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. +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: +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: | Index | Unlock Block | | ----- | ---------------------------------------------------------------------------------------- | @@ -458,66 +514,119 @@ Consider a Transaction Essence containing the UTXO Inputs 0, 1 and | 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. | -## 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.1 - * 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.1 - * 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](#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. - -1 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 [RFC-005](https://iotaledger.github.io/protocol-rfcs/0005-white-flag/0005-white-flag.html#deterministically-ordering-the-tangle). - -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 ([RFC-0012](https://iotaledger.github.io/protocol-rfcs/0012-milestone-merkle-validation/0012-milestone-merkle-validation.html)). - -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. +##### Alias Unlock Block + +An Alias Unlock Block defines an Unlock Block which references a previous Unlock Block +corresponding to the alias that the input is locked to. Defined in +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-locking--unlocking) + +##### NFT Unlock Block + +An NFT Unlock Block defines an Unlock Block which references a previous Unlock Block corresponding +to the NFT that the input is locked to. Defined in +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-locking--unlocking) + +### 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 syntactic and semantic +validation. + +The different output types and optional output feature blocks introduced by [RFC-0038](https://github.com/iotaledger/protocol-rfcs/pull/38) +add extra constraints to transaction validation rules, but since these are specific to the given outputs and features, +they are discussed for each [output types](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#output-design) +and [feature block types](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features) +separately. + +#### 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 +broadcast further and can be discarded right away. + +The following criteria defines whether the transaction passes the syntactic validation: +* `Transaction Essence Type` value must be 0, denoting an `Transaction Essence`. +* Inputs: + * `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. + * 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 < `Max Outputs Count`. + * Every combination of `Transaction ID` + `Transaction Output Index` must be unique in the list of inputs. +* Outputs: + * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. + * At least one output must be specified. + * `Output Type` must denote a `SimpleOutput`, `ExtendedOutput`, `AliasOutput`, `FoundryOutput` or `NFTOutput`. + * Output must fulfill the [dust protection requirements.](https://github.com/iotaledger/protocol-rfcs/pull/39) + * Output is syntactically valid based on its type. + * 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 amount of inputs. Must be 0 < x ≤ `Max Inputs Count`. +* `Unlock Block Type` must either be 0, 1, 2 or 3, denoting a `Signature Unlock Block`, a `Reference Unlock block`, an + `Alias Unlock Block` or an `NFT Unlock Block`. +* `Signature Unlock Blocks` must define a `Ed25519 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 which points to the origin + `Signature Unlock Block`. +* `Reference Unlock Blocks` must specify a previous `Unlock Block` which is not of type `Reference Unlock Block`. The + referenced index must therefore be < the index of the `Reference Unlock Block`. +* `Alias Unlock Blocks` must specify a previous `Unlock Block` which unlocks the alias the input is locked to. The + referenced index must be < the index of the `Alias Unlock Block`. +* `NFT Unlock Blocks` must specify a previous `Unlock Block` which unlocks the NFT the input is locked to. The + reference index must be < the index of the `NFT Unlock Block`. +* Given the type and length of the information, the Transaction Payload must consume the entire byte array for + the `Payload Length` field in the Message it defines. + +#### 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 [RFC-005](https://iotaledger.github.io/protocol-rfcs/0005-white-flag/0005-white-flag.html#deterministically-ordering-the-tangle). + +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 the transaction passes the semantic validation: +1. 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. +2. 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. +3. The transaction is balanced in terms of native tokens, meaning the amount of native tokens present in inputs equals + to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in + the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. +4. The UTXOs the transaction references must be unlocked based on the transaction context, that is the + Transaction Payload plus the list of consumed UTXOs. (output syntactic unlock validation in transaction + context) +5. The UTXOs the transaction references must be unlocked with respect to the + [milestone index and Unix timestamp of the confirming milestone](https://github.com/jakubcech/protocol-rfcs/blob/jakubcech-milestonepayload/text/0019-milestone-payload/0019-milestone-payload.md#structure). (output semantic unlock validation in transaction context) +6. The outputs of the transaction must pass additional validation rules defined by the present + [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features). +7. The sum of all `Native Token Counts` in the transaction plus `Outputs Count` is ≤ + `Max Native Token Count Per Output`. +8. 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 address unlocking the UTXO, + * the BLAKE2b-256 hash of `Public Key` must match the unlocking `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 it is an _Alias Unlock Block_: + * The address unlocking the UTXO must be an _Alias Address_. + * The referenced _Unlock Block_ unlocks the alias defined by the unlocking address of the UTXO. + * If it is an _NFT Unlock Block_: + * The address unlocking the UTXO must be a _NFT Address_. + * The referenced _Unlock Block_ unlocks the NFT defined by the unlocking address of 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 ([RFC-0012](https://iotaledger.github.io/protocol-rfcs/0012-milestone-merkle-validation/0012-milestone-merkle-validation.html)). + +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 From 8fbdd77666e2b1f77f1cc82c46debbe42acc8573 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 18 Nov 2021 17:45:29 +0100 Subject: [PATCH 02/40] Minor formatting --- .../0018-transaction-payload.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/text/0018-transaction-payload/0018-transaction-payload.md b/text/0018-transaction-payload/0018-transaction-payload.md index a8ca0aaa0..c736fd9de 100644 --- a/text/0018-transaction-payload/0018-transaction-payload.md +++ b/text/0018-transaction-payload/0018-transaction-payload.md @@ -2,7 +2,7 @@ + Start date: 2020-07-10 + RFC PR: [iotaledger/protocol-rfcs#18](https://github.com/iotaledger/protocol-rfcs/pull/18) + Recent updates: - + () Update Payload Layout and Validation for [New Output Types](https://github.com/iotaledger/protocol-rfcs/pull/38) + + [iotaledger/protocol-rfcs#0040](https://github.com/iotaledger/protocol-rfcs/pull/40) Update Payload Layout and Validation for [New Output Types](https://github.com/iotaledger/protocol-rfcs/pull/38) # Summary @@ -429,22 +429,22 @@ addresses of different types. ###### ExtendedOutput An output to a single target address that may carry native tokens and optional feature blocks. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#extended-output) +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#extended-output). ###### AliasOutput An output that represents an alias account in the ledger. Defined in -[RFC-0038](#https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-output) +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-output). ###### FoundryOutput An output that represents a token foundry in the ledger. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#foundry-output) +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#foundry-output). ###### NFTOutput An output that represents a non-fungible token in the ledger. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-output) +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-output). ##### Payload @@ -518,13 +518,13 @@ following structure of the Unlock Blocks part: An Alias Unlock Block defines an Unlock Block which references a previous Unlock Block corresponding to the alias that the input is locked to. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-locking--unlocking) +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-locking--unlocking). ##### NFT Unlock Block An NFT Unlock Block defines an Unlock Block which references a previous Unlock Block corresponding to the NFT that the input is locked to. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-locking--unlocking) +[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-locking--unlocking). ### Validation From 82ba00a45c50f352c7931a07b4a4bdc04c2a1e70 Mon Sep 17 00:00:00 2001 From: Wolfgang Welz Date: Thu, 25 Nov 2021 11:57:24 +0100 Subject: [PATCH 03/40] Improve validation description --- .../0018-transaction-payload.md | 566 ++++++------------ 1 file changed, 191 insertions(+), 375 deletions(-) diff --git a/text/0018-transaction-payload/0018-transaction-payload.md b/text/0018-transaction-payload/0018-transaction-payload.md index c736fd9de..02969f452 100644 --- a/text/0018-transaction-payload/0018-transaction-payload.md +++ b/text/0018-transaction-payload/0018-transaction-payload.md @@ -2,28 +2,22 @@ + Start date: 2020-07-10 + RFC PR: [iotaledger/protocol-rfcs#18](https://github.com/iotaledger/protocol-rfcs/pull/18) + Recent updates: - + [iotaledger/protocol-rfcs#0040](https://github.com/iotaledger/protocol-rfcs/pull/40) Update Payload Layout and Validation for [New Output Types](https://github.com/iotaledger/protocol-rfcs/pull/38) + + [iotaledger/protocol-rfcs#0040](https://github.com/iotaledger/protocol-rfcs/pull/40) Update payload layout and validation for [new output types](https://github.com/iotaledger/protocol-rfcs/pull/38) # 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 RFC proposes a new UTXO-based transaction structure containing all the inputs and outputs of a transfer. Specifically, this RFC defines a transaction payload for the _messages_ described in the IOTA protocol [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html). +This RFC proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this document defines a transaction payload for the _messages_ described in the IOTA protocol [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html). # 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. +There are several options on how transfers of IOTA coins can be embedded into the actual vertices of the Tangle. In the legacy IOTA protocol, each vertex corresponds to a single transaction, i.e. an input or an output. In order to support atomic transfers, input/output transactions have to be grouped into a so-called bundle and then either the entire bundle is applied to the ledger or none of its transactions. -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. +The bundle concept has proven to be rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this RFC proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle message/vertex. -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 new transaction structure should fulfill the following criteria: +- Support for Ed25519 signatures. +- Support for adding new types of signature schemes, addresses, inputs, and outputs as part of protocol upgrades. +- Implement the UTXO model. # Detailed design @@ -31,11 +25,11 @@ The new transaction structure should fulfil the following criteria: 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: +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. +* Balances are no longer strictly associated to addresses. This allows a higher 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. @@ -45,46 +39,17 @@ The following image depicts the flow of funds using UTXO: ## Structure -### Serialized Layout +### 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 Transaction Essence's inputs. In case the unlock block contains a - signature, it signs the Blake2b-256 hash of the serialized Transaction Essence part. +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_. -All values are serialized in little-endian encoding. In contrast to the [current IOTA protocol](https://github.com/iotaledger/protocol-rfcs/pull/18) -inputs and outputs are encoded as lists, which means that they can contain duplicates and may not be sorted. +The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to [Chrysalis Phase 2](https://github.com/iotaledger/protocol-rfcs/pull/18) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. -A [Blake2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized data makes up -Transaction Payload's ID. +The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlock blocks. -Following table structure describes the entirety of a Transaction Payload's serialized form. -* Data Type Notation, see [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html#data-types) -*
- Subschema Notation - - - - - - - - - - - - - - - - - -
NameDescription
oneOfOne of the listed subschemas.
optOneOfOptionally one of the listed subschemas.
anyOfAny (one or more) of the listed subschemas.
-
-* New output types and unlock blocks are discussed in detail in [RFC-38](https://github.com/iotaledger/protocol-rfcs/pull/38), - but they are mentioned in the payload structure to help the reader understand their context. - -

+The following table describes the entirety of a _Transaction Payload_ in its serialized form following the notation from [draft RFC-0041](https://github.com/iotaledger/protocol-rfcs/pull/41): @@ -169,32 +134,25 @@ Following table structure describes the entirety of a Transaction Payload
Outputs anyOf
- SimpleOutput -
- Describes a deposit to a single address which is unlocked via a signature. -
-
-
- ExtendedOutput + Extended Output
- Describes a deposit to a single address. The output might contain optional feature - blocks and native tokens. + Describes a deposit to a single address. The output might contain optional feature blocks and native tokens.
- AliasOutput + Alias Output
Describes an alias account in the ledger.
- FoundryOutput + Foundry Output
Describes a foundry that controls supply of native tokens.
- NFTOutput + NFT Output
Describes a unique, non-fungible token deposit to a single address.
@@ -250,389 +208,247 @@ Following table structure describes the entirety of a Transaction Payload
Signature Unlock Block
- Defines an unlock block containing a signature unlocking input(s). + Defines an unlock block containing a signature.
- - - - - - - - - - - - - - - -
NameTypeDescription
Unlock Typeuint8 - Set to value 0 to denote a Signature Unlock Block. -
Signature oneOf -
- Ed25519 Signature - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
Signature Typeuint8 - Set to value 0 to denote an Ed25519 Signature. -
Public keyByteArray[32]The Ed25519 public key of the signature.
SignatureByteArray[64]The Ed25519 signature signing the Blake2b-256 hash of the serialized Transaction Essence.
-
-
Reference Unlock Block
References a previous unlock block, where the same unlock block can be used for multiple inputs.
- - - - - - - - - - - - - - - - -
NameTypeDescription
Unlock Typeuint8 - Set to value 1 to denote a Reference Unlock Block. -
Referenceuint16Represents the index of a previous unlock block.
Alias Unlock Block
- Points to the unlock block of a consumed alias output. + References a previous unlock block of a consumed alias output.
- - - - - - - - - - - - - - - - -
NameTypeDescription
Unlock Typeuint8 - Set to value 2 to denote an Alias Unlock Block. -
Alias Reference Unlock Indexuint16Index of input and unlock block corresponding to an alias output.
NFT Unlock Block
- Points to the unlock block of a consumed NFT output. + References a previous unlock block of a consumed NFT output.
- - - - - - - - - - - - - - - - -
NameTypeDescription
Unlock Typeuint8 - Set to value 3 to denote a NFT Unlock Block. -
NFT Reference Unlock Indexuint16Index of input and unlock block corresponding to an NFT output.
-### Transaction Parts - -In general, all parts of a Transaction Payload begin with a byte describing the type of the given part to keep -the flexibility to introduce new types/versions of the given part in the future. +### Transaction Essence -#### 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 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 -##### Inputs +The `Inputs` field 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. -The Inputs part holds the inputs to consume, respectively, to fund the outputs of the -Transaction Essence. There is only one 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 input must be accompanied by a corresponding Unlock Block at the same index in the Unlock Blocks part of the Transaction Payload. -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 -If multiple inputs can be unlocked through the same Unlock Block, then the given Unlock Block only needs -to be specified at the index of the first input which gets unlocked by it. +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 referenced output. -Subsequent inputs which are unlocked through the same data must have a Reference Unlock Block, -Alias Unlock Block or NFT Unlock Block depending on the unlock mechanism, pointing to the index of a -previous Unlock Block. This ensures that no duplicate data needs to occur in the same transaction. - -###### 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 -##### Outputs +The `Outputs` field holds the outputs that are created by the Transaction Payload. There are different output types, but they must all have an `Amount` field denoting the number of IOTA coins to deposit. -The Outputs part holds the outputs that are created by this Transaction Payload. The following output -types are supported: +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanceOutput_ introduced in [Chrysalis Phase 2](https://github.com/iotaledger/protocol-rfcs/pull/18) have been removed and are no longer supported. -###### SimpleOutput +| Output Name | Type Value | RFC | +| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Extended | 3 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#extended-output) | +| Alias | 4 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-output) | +| Foundry | 5 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#foundry-output) | +| NFT | 6 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-output) | -Formerly known as SigLockedSingleOutput, the SimpleOutput 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. +#### Payload -###### ExtendedOutput +The _Transaction Essence_ itself can contain another payload as described in general in [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html). -An output to a single target address that may carry native tokens and optional feature blocks. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#extended-output). +The following table lists all the payload types that can be nested inside a _Transaction Essence_ as well as links to the corresponding specification: -###### AliasOutput +| Payload Name | Type Value | RFC | +| ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------- | +| Indexation | 2 | [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html#indexation-payload) | -An output that represents an alias account in the ledger. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-output). +### Unlock Blocks -###### FoundryOutput +The `Unlock Blocks` field holds the unlock blocks unlocking inputs within a Transaction Essence. -An output that represents a token foundry in the ledger. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#foundry-output). +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock Block_ as well as the _Reference Unlock Block_ is specified as part of this RFC. -###### NFTOutput +| Unlock Block Name | Type Value | RFC | +| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Signature | 0 | [RFC-0018](#signature-unlock-block) | +| Reference | 1 | [RFC-0018](#reference-unlock-block) | +| Alias | 2 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-locking--unlocking) | +| NFT | 3 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-locking--unlocking) | -An output that represents a non-fungible token in the ledger. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-output). +#### Signature Unlock Block -##### Payload +The Signature Unlock Block defines an Unlock Block which holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including the optional payload). It is serialized as follows: -The _Transaction Essence_ itself can contain another payload as described in general in [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html). -The [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ does not have any impact on -the payload. + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 0 to denote a Signature Unlock Block. +
Signature oneOf +
+ Ed25519 Signature + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Signature Typeuint8 + Set to value 0 to denote an Ed25519 Signature. +
Public keyByteArray[32]The Ed25519 public key of the signature.
SignatureByteArray[64]The Ed25519 signature signing the Blake2b-256 hash of the serialized Transaction Essence.
+
+
-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 syntactic validation -| Name | Type Value | RFC | -| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | -| Indexation | 2 | [RFC-0017](https://iotaledger.github.io/protocol-rfcs/0017-tangle-message/0017-tangle-message.html#indexation-payload) | +* `Signature` must contain an _Ed25519 Signature_. +* The _Signature Unlock Block_ must be unique, i.e. there must not be any other _Signature Unlock Blocks_ in the `Unlock Blocks` field of the transaction payload with the same signature. -#### Unlock Blocks +#### Reference Unlock Block -The Unlock Blocks part holds the unlock blocks unlocking inputs within a Transaction Essence. The -following types of unlock blocks are supported: +The 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. It is serialized as follows: - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +
NameTypeDescription
Signature Unlock Block0An unlock block holding a signature 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.
Alias Unlock Block2An unlock block which must reference a previous unlock block which unlocks the alias that the input is locked to.
NFT Unlock Block3An unlock block which must reference a previous unlock block which unlocks the NFT that the input is locked to.
NameTypeDescription
Unlock Typeuint8 + Set to value 1 to denote a Reference Unlock Block. +
Referenceuint16Represents the index of a previous unlock block.
-##### 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). +##### Unlock syntactic validation -##### 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. +* The _Reference Unlock Block_ at index i must have `Reference` < i and the unlock block at index `Reference` must be a _Signature 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: - +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: | Index | Unlock Block | | ----- | ---------------------------------------------------------------------------------------- | | 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. | -##### Alias Unlock Block - -An Alias Unlock Block defines an Unlock Block which references a previous Unlock Block -corresponding to the alias that the input is locked to. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-locking--unlocking). - -##### NFT Unlock Block - -An NFT Unlock Block defines an Unlock Block which references a previous Unlock Block corresponding -to the NFT that the input is locked to. Defined in -[RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-locking--unlocking). - -### Validation +## 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 syntactic and semantic -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 -The different output types and optional output feature blocks introduced by [RFC-0038](https://github.com/iotaledger/protocol-rfcs/pull/38) -add extra constraints to transaction validation rules, but since these are specific to the given outputs and features, -they are discussed for each [output types](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#output-design) -and [feature block types](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features) -separately. +The different output types and optional output feature blocks introduced by [draft RFC-0038](https://github.com/iotaledger/protocol-rfcs/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#output-design) and [feature block type](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features) separately. -#### Syntactic 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 -broadcast further and can be discarded right away. +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 broadcast further and can be discarded right away. -The following criteria defines whether the transaction passes the syntactic validation: -* `Transaction Essence Type` value must be 0, denoting an `Transaction Essence`. -* Inputs: +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 ≤ `Max Inputs Count`. - * 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 < `Max Outputs Count`. - * Every combination of `Transaction ID` + `Transaction Output Index` must be unique in the list of inputs. -* Outputs: + * For each input the following must be true: + * `Input Type` must denote a _UTXO Input_. + * `Transaction Output Index` must be 0 ≤ x < `Max Outputs Count`. + * Each pair of `Transaction ID` and `Transaction Output Index` must be unique in the list of inputs. + * Outputs: * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. - * At least one output must be specified. - * `Output Type` must denote a `SimpleOutput`, `ExtendedOutput`, `AliasOutput`, `FoundryOutput` or `NFTOutput`. - * Output must fulfill the [dust protection requirements.](https://github.com/iotaledger/protocol-rfcs/pull/39) - * Output is syntactically valid based on its type. - * 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 amount of inputs. Must be 0 < x ≤ `Max Inputs Count`. -* `Unlock Block Type` must either be 0, 1, 2 or 3, denoting a `Signature Unlock Block`, a `Reference Unlock block`, an - `Alias Unlock Block` or an `NFT Unlock Block`. -* `Signature Unlock Blocks` must define a `Ed25519 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 which points to the origin - `Signature Unlock Block`. -* `Reference Unlock Blocks` must specify a previous `Unlock Block` which is not of type `Reference Unlock Block`. The - referenced index must therefore be < the index of the `Reference Unlock Block`. -* `Alias Unlock Blocks` must specify a previous `Unlock Block` which unlocks the alias the input is locked to. The - referenced index must be < the index of the `Alias Unlock Block`. -* `NFT Unlock Blocks` must specify a previous `Unlock Block` which unlocks the NFT the input is locked to. The - reference index must be < the index of the `NFT Unlock Block`. -* Given the type and length of the information, the Transaction Payload must consume the entire byte array for - the `Payload Length` field in the Message it defines. - -#### 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 [RFC-005](https://iotaledger.github.io/protocol-rfcs/0005-white-flag/0005-white-flag.html#deterministically-ordering-the-tangle). - -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 the transaction passes the semantic validation: -1. 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. -2. 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. -3. The transaction is balanced in terms of native tokens, meaning the amount of native tokens present in inputs equals - to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in - the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. -4. The UTXOs the transaction references must be unlocked based on the transaction context, that is the - Transaction Payload plus the list of consumed UTXOs. (output syntactic unlock validation in transaction - context) -5. The UTXOs the transaction references must be unlocked with respect to the - [milestone index and Unix timestamp of the confirming milestone](https://github.com/jakubcech/protocol-rfcs/blob/jakubcech-milestonepayload/text/0019-milestone-payload/0019-milestone-payload.md#structure). (output semantic unlock validation in transaction context) -6. The outputs of the transaction must pass additional validation rules defined by the present - [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features). -7. The sum of all `Native Token Counts` in the transaction plus `Outputs Count` is ≤ - `Max Native Token Count Per Output`. -8. 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 address unlocking the UTXO, - * the BLAKE2b-256 hash of `Public Key` must match the unlocking `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 it is an _Alias Unlock Block_: - * The address unlocking the UTXO must be an _Alias Address_. - * The referenced _Unlock Block_ unlocks the alias defined by the unlocking address of the UTXO. - * If it is an _NFT Unlock Block_: - * The address unlocking the UTXO must be a _NFT Address_. - * The referenced _Unlock Block_ unlocks the NFT defined by the unlocking address of 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 ([RFC-0012](https://iotaledger.github.io/protocol-rfcs/0012-milestone-merkle-validation/0012-milestone-merkle-validation.html)). - -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. + * For each input the following must be true: + * `Output Type` must match one of the values described under [Outputs](#outputs). + * The output itself must pass syntactic validation. + * The sum of all `Amount` fields must not exceed `Max IOTA Supply`. + * Payload (if present): + * `Payload Type` must match one of the values described under [Payload](#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_. + * For each unlock block the following must be true: + * Each `Unlock Block Type` must match one of the values described under [Unlock Blocks](#unlock-blocks). + * The unlock block itself must pass syntactic validation. +* Given the type and length information, the _Transaction Payload_ must consume the entire byte array of the `Payload` field of the encapsulating object. + +### 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 [RFC-005](https://iotaledger.github.io/protocol-rfcs/0005-white-flag/0005-white-flag.html#deterministically-ordering-the-tangle). + +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 coin 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. +* The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. +* The transaction must be balanced in terms of native tokens, i.e. the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. +* Each output and all its [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features) must pass semantic validation in the context of the following input: + 1. The _Transaction Payload_, + 2. the list of UTXOs referenced by inputs and + 3. the [milestone index and Unix timestamp](https://iotaledger.github.io/protocol-rfcs/0019-milestone-payload/0019-milestone-payload.html#structure) of the confirming milestone. +* 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 it is an _Alias Unlock Block_: + * The address unlocking the UTXO must be an _Alias Address_. + * The referenced _Unlock Block_ unlocks the alias defined by the unlocking address of the UTXO. + * If it is an _NFT Unlock Block_: + * The address unlocking the UTXO must be a _NFT Address_. + * The referenced _Unlock Block_ unlocks the NFT defined by the unlocking address of 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 ([RFC-0012](https://iotaledger.github.io/protocol-rfcs/0012-milestone-merkle-validation/0012-milestone-merkle-validation.html)). + +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 ([RFC-0019](https://iotaledger.github.io/protocol-rfcs/0019-milestone-payload/0019-milestone-payload.html)). +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_. Instead, the global timestamp of the confirming milestone ([RFC-0019](https://iotaledger.github.io/protocol-rfcs/0019-milestone-payload/0019-milestone-payload.html)) is used. ### Address reuse From 004d535f3477c84116df6b2a879ca59ebd47a79d Mon Sep 17 00:00:00 2001 From: Wolfgang Welz Date: Mon, 17 Jan 2022 18:21:48 +0100 Subject: [PATCH 04/40] update links --- tips/TIP-0007/tip-0007.md | 48 +++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/tips/TIP-0007/tip-0007.md b/tips/TIP-0007/tip-0007.md index 70b72b607..bd4b2facd 100644 --- a/tips/TIP-0007/tip-0007.md +++ b/tips/TIP-0007/tip-0007.md @@ -12,13 +12,13 @@ created: 2020-07-10 # Summary -This RFC proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for the _messages_ described in [TIP-6](../TIP-0006/tip-0006.md). +This TIP proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for the _messages_ described in [TIP-6](../TIP-0006/tip-0006.md). # Motivation There are several options on how transfers of IOTA coins can be embedded into the actual vertices of the Tangle. In the legacy IOTA protocol, each vertex corresponds to a single transaction, i.e. an input or an output. In order to support atomic transfers, input/output transactions have to be grouped into a so-called bundle and then either the entire bundle is applied to the ledger or none of its transactions. -The bundle concept has proven to be rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this RFC proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle message/vertex. +The bundle concept has proven to be rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle message/vertex. The new transaction structure should fulfill the following criteria: - Support for Ed25519 signatures. @@ -51,7 +51,7 @@ 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_. -The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to [Chrysalis Phase 2](https://github.com/iotaledger/protocol-rfcs/pull/18) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. +The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlock blocks. @@ -257,14 +257,14 @@ A UTXO Input is an input which references an unspent output of a previous The `Outputs` field holds the outputs that are created by the Transaction Payload. There are different output types, but they must all have an `Amount` field denoting the number of IOTA coins to deposit. -The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanceOutput_ introduced in [Chrysalis Phase 2](https://github.com/iotaledger/protocol-rfcs/pull/18) have been removed and are no longer supported. +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanceOutput_ introduced in Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) have been removed and are no longer supported. -| Output Name | Type Value | RFC | -| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Extended | 3 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#extended-output) | -| Alias | 4 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-output) | -| Foundry | 5 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#foundry-output) | -| NFT | 6 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-output) | +| Output Name | Type Value | TIP | +| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------ | +| Extended | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#extended-output) | +| Alias | 4 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-output) | +| Foundry | 5 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#foundry-output) | +| NFT | 6 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-output) | #### Payload @@ -272,22 +272,22 @@ The _Transaction Essence_ itself can contain another payload as described in ge The following table lists all the payload types that can be nested inside a _Transaction Essence_ as well as links to the corresponding specification: -| Name | Type Value | TIP | -| ---------- | ---------- | -----------------------------------------------------| -| Indexation | 2 | [TIP-6](../TIP-0006/tip-0006.md#indexation-payload) | +| Name | Type Value | TIP | +| ---------- | ---------- | ----------------------------------------------------| +| Indexation | 2 | [TIP-6](../TIP-0006/tip-0006.md#indexation-payload) | ### Unlock Blocks The `Unlock Blocks` field holds the unlock blocks unlocking inputs within a _Transaction Essence_. -The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock Block_ as well as the _Reference Unlock Block_ is specified as part of this RFC. +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock Block_ as well as the _Reference Unlock Block_ is specified as part of this TIP. -| Unlock Block Name | Type Value | RFC | -| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Signature | 0 | [RFC-0018](#signature-unlock-block) | -| Reference | 1 | [RFC-0018](#reference-unlock-block) | -| Alias | 2 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#alias-locking--unlocking) | -| NFT | 3 | [draft RFC-0038](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#nft-locking--unlocking) | +| Unlock Block Name | Type Value | TIP | +| ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | +| Signature | 0 | [TIP-20](#signature-unlock-block) | +| Reference | 1 | [TIP-20](#reference-unlock-block) | +| Alias | 2 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-locking--unlocking) | +| NFT | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-locking--unlocking) | #### Signature Unlock Block @@ -385,7 +385,7 @@ Consider a Transaction Essence containing the UTXO Inputs 0, 1 and 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 -The different output types and optional output feature blocks introduced by [draft RFC-0038](https://github.com/iotaledger/protocol-rfcs/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#output-design) and [feature block type](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features) separately. +The different output types and optional output feature blocks introduced by [draft TIP-18](https://github.com/iotaledger/tips/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-design) and [feature block type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) separately. ### Syntactic validation @@ -429,10 +429,10 @@ The following criteria defines whether a payload passes the semantic validation: * The transaction must spend the entire coin 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. * The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. * The transaction must be balanced in terms of native tokens, i.e. the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. -* Each output and all its [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/text/0038-output-types-for-tokenization-and-sc/0038-output-types-for-tokenization-and-sc.md#optional-output-features) must pass semantic validation in the context of the following input: +* Each output and all its [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) must pass semantic validation in the context of the following input: 1. The _Transaction Payload_, 2. the list of UTXOs referenced by inputs and - 3. the [milestone index and Unix timestamp](https://iotaledger.github.io/protocol-rfcs/0019-milestone-payload/0019-milestone-payload.html#structure) of the confirming milestone. + 3. the milestone index and Unix timestamp of the confirming milestone. * 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, @@ -471,7 +471,7 @@ In essence, Ed25519 support allows for smaller transaction sizes and to safely s * 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. +* Not switching to the new transaction structure described in this TIP 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 From a76981b5b2fcf07106d9f26e0c7a14abd67f6113 Mon Sep 17 00:00:00 2001 From: Wolfgang Welz Date: Mon, 17 Jan 2022 19:00:43 +0100 Subject: [PATCH 05/40] move to correct file --- tips/TIP-0007/tip-0007.md | 441 ++++++++++++++++++++--------------- tips/TIP-0020/tip-0020.md | 479 ++++++++++++++++++++++++++++++++++++++ tips/TIP-0020/utxo.png | Bin 0 -> 52729 bytes 3 files changed, 738 insertions(+), 182 deletions(-) create mode 100644 tips/TIP-0020/tip-0020.md create mode 100644 tips/TIP-0020/utxo.png diff --git a/tips/TIP-0007/tip-0007.md b/tips/TIP-0007/tip-0007.md index bd4b2facd..f515c5bbc 100644 --- a/tips/TIP-0007/tip-0007.md +++ b/tips/TIP-0007/tip-0007.md @@ -12,18 +12,24 @@ created: 2020-07-10 # Summary -This TIP proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for the _messages_ described in [TIP-6](../TIP-0006/tip-0006.md). +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](../TIP-0006/tip-0006.md). # Motivation -There are several options on how transfers of IOTA coins can be embedded into the actual vertices of the Tangle. In the legacy IOTA protocol, each vertex corresponds to a single transaction, i.e. an input or an output. In order to support atomic transfers, input/output transactions have to be grouped into a so-called bundle and then either the entire bundle is applied to the ledger or none of its transactions. +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 rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle message/vertex. +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. -The new transaction structure should fulfill the following criteria: -- Support for Ed25519 signatures. -- Support for adding new types of signature schemes, addresses, inputs, and outputs as part of protocol upgrades. -- Implement the UTXO model. +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 @@ -31,11 +37,11 @@ The new transaction structure should fulfill the following criteria: 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: +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. -* Balances are no longer strictly associated to addresses. This allows a higher level of abstraction and thus enables other types of outputs with particular unlock criteria. +* 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. @@ -49,13 +55,37 @@ The following image depicts the flow of funds using UTXO: 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_. +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. -The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. +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 Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlock blocks. +The *Transaction ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) 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 [draft TIP-21](https://github.com/iotaledger/tips/pull/41): +The following table structure describes the entirety of a _Transaction Payload_ in its serialized form: +* Data Type Notation, see [TIP-6](../TIP-0006/tip-0006.md#data-types) +*
+ Subschema Notation + + + + + + + + + + + + + + + + + +
NameDescription
oneOfOne of the listed subschemas.
optOneOfOptionally one of the listed subschemas.
anyOfAny (one or more) of the listed subschemas.
+
+ +

@@ -140,28 +170,108 @@ The following table describes the entirety of a _Transaction Payload_ in its ser @@ -206,175 +316,150 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - +
Outputs anyOf
- Extended Output -
- Describes a deposit to a single address. The output might contain optional feature blocks and native tokens. -
-
-
- Alias Output -
- Describes an alias account in the ledger. -
-
-
- Foundry Output + SigLockedSingleOutput
- Describes a foundry that controls supply of native tokens. + Describes a deposit to a single address which is unlocked via a signature.
+ + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Output Typeuint8 + Set to value 0 to denote a SigLockedSingleOutput. +
Address oneOf +
+ Ed25519 Address + + + + + + + + + + + + + + + + +
NameTypeDescription
Address Typeuint8 + Set to value 0 to denote an Ed25519 Address. +
AddressByteArray[32]The raw bytes of the Ed25519 address which is the BLAKE2b-256 hash of the public key.
+
+
Amountuint64The amount of tokens to deposit.
- NFT Output + SigLockedDustAllowanceOutput
- Describes a unique, non-fungible token deposit to a single address. + Describes a deposit which as a special property also alters the dust allowance of the target address.
+ + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Output Typeuint8 + Set to value 1 to denote a SigLockedDustAllowanceOutput. +
Address oneOf +
+ Ed25519 Address + + + + + + + + + + + + + + + + +
NameTypeDescription
Address Typeuint8 + Set to value 0 to denote an Ed25519 Address. +
AddressByteArray[32]The raw bytes of the Ed25519 address which is the BLAKE2b-256 hash of the public key.
+
+
Amountuint64The amount of tokens to deposit.
Unlock Blocks Count uint16The number of unlock block entries. It must match the field Inputs Count.The number of unlock block entries. It must match the field Inputs Count.
Unlock Blocks anyOf -
+
Signature Unlock Block
Defines an unlock block containing a signature.
+ + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 0 to denote a Signature Unlock Block. +
Signature oneOf +
+ Ed25519 Signature + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Signature Typeuint8 + Set to value 0 to denote an Ed25519 Signature. +
Public keyByteArray[32]The Ed25519 public key of the signature.
SignatureByteArray[64]The Ed25519 signature signing the Blake2b-256 hash of the serialized Transaction Essence.
+
+
-
+
Reference Unlock Block
References a previous unlock block, where the same unlock block can be used for multiple inputs.
-
-
- Alias Unlock Block -
- References a previous unlock block of a consumed alias output. -
-
-
- NFT Unlock Block -
- References a previous unlock block of a consumed NFT output. -
+ + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 1 to denote a Reference Unlock Block. +
Referenceuint16Represents the index of a previous unlock block.
-### Transaction Essence +### Transaction parts -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. +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. -#### Inputs +#### Transaction Essence data -The `Inputs` field 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 referenced output. +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. -#### Outputs +##### Inputs -The `Outputs` field holds the outputs that are created by the Transaction Payload. There are different output types, but they must all have an `Amount` field denoting the number of IOTA coins to deposit. +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. -The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanceOutput_ introduced in Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) have been removed and are no longer supported. +Each input must be accompanied by a corresponding Unlock Block at the same index in the Unlock Blocks part of the Transaction Payload. -| Output Name | Type Value | TIP | -| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------ | -| Extended | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#extended-output) | -| Alias | 4 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-output) | -| Foundry | 5 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#foundry-output) | -| NFT | 6 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-output) | +###### UTXO Input -#### 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. -The _Transaction Essence_ itself can contain another payload as described in general in [TIP-6](../TIP-0006/tip-0006.md). The [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ does not have any impact on the payload. +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 following table lists all the payload types that can be nested inside a _Transaction Essence_ as well as links to the corresponding specification: +##### Outputs -| Name | Type Value | TIP | -| ---------- | ---------- | ----------------------------------------------------| -| Indexation | 2 | [TIP-6](../TIP-0006/tip-0006.md#indexation-payload) | +The Outputs part holds the outputs that are created by this Transaction Payload. The following output types are supported: -### Unlock Blocks +###### SigLockedSingleOutput -The `Unlock Blocks` field holds the unlock blocks unlocking inputs within a _Transaction Essence_. +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 following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock Block_ as well as the _Reference Unlock Block_ is specified as part of this TIP. +###### SigLockedDustAllowanceOutput -| Unlock Block Name | Type Value | TIP | -| ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | -| Signature | 0 | [TIP-20](#signature-unlock-block) | -| Reference | 1 | [TIP-20](#reference-unlock-block) | -| Alias | 2 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-locking--unlocking) | -| NFT | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-locking--unlocking) | +The SigLockedDustAllowanceOutput works in the same way as a SigLockedSingleOutput but additionally controls the dust allowance on the target address. See [TIP-14](../TIP-0014/tip-0014.md) for further information. -#### Signature Unlock Block +##### Payload -The Signature Unlock Block defines an Unlock Block which holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including the optional payload). It is serialized as follows: +The _Transaction Essence_ itself can contain another payload as described in general in [TIP-6](../TIP-0006/tip-0006.md). The [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ does not have any impact on the payload. - - - - - - - - - - - - - - - -
NameTypeDescription
Unlock Typeuint8 - Set to value 0 to denote a Signature Unlock Block. -
Signature oneOf -
- Ed25519 Signature - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
Signature Typeuint8 - Set to value 0 to denote an Ed25519 Signature. -
Public keyByteArray[32]The Ed25519 public key of the signature.
SignatureByteArray[64]The Ed25519 signature signing the Blake2b-256 hash of the serialized Transaction Essence.
-
-
+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 syntactic validation +| Name | Type Value | TIP | +| ---------- | ---------- | -----------------------------------------------------| +| Indexation | 2 | [TIP-6](../TIP-0006/tip-0006.md#indexation-payload) | -* `Signature` must contain an _Ed25519 Signature_. -* The _Signature Unlock Block_ must be unique, i.e. there must not be any other _Signature Unlock Blocks_ in the `Unlock Blocks` field of the transaction payload with the same signature. +#### Unlock Blocks -#### Reference Unlock Block +The Unlock Blocks part holds the unlock blocks unlocking inputs within a Transaction Essence. The following types of unlock blocks are supported: -The 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. It is serialized as follows: +##### Signature Unlock Block - - - - - - - - - - - - - - - - -
NameTypeDescription
Unlock Typeuint8 - Set to value 1 to denote a Reference Unlock Block. -
Referenceuint16Represents the index of a previous 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). -##### Unlock syntactic validation +##### Reference Unlock block -* The _Reference Unlock Block_ at index i must have `Reference` < i and the unlock block at index `Reference` must be a _Signature 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: + | Index | Unlock Block | | ----- | ---------------------------------------------------------------------------------------- | | 0 | A _Signature Unlock Block_ holding the Ed25519 signature for address A. | @@ -383,41 +468,45 @@ Consider a Transaction Essence containing the UTXO Inputs 0, 1 and ## 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 - -The different output types and optional output feature blocks introduced by [draft TIP-18](https://github.com/iotaledger/tips/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-design) and [feature block type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) separately. +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 broadcast further and can be discarded right away. +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 ≤ `Max Inputs Count`. + * `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 < `Max Outputs Count`. - * Each pair of `Transaction ID` and `Transaction Output Index` must be unique in the list of inputs. + * `Transaction Output Index` must be 0 ≤ x < 127. + * `Inputs` must be sorted in lexicographical order of their serialized form.1 + * Each pair of `Transaction ID` and `Transaction Output Index` must be unique in the inputs set. * Outputs: - * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. + * `Outputs Count` must be 0 < x ≤ 127. * For each input the following must be true: - * `Output Type` must match one of the values described under [Outputs](#outputs). - * The output itself must pass syntactic validation. - * The sum of all `Amount` fields must not exceed `Max IOTA Supply`. + * `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.1 + * 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](#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_. - * For each unlock block the following must be true: - * Each `Unlock Block Type` must match one of the values described under [Unlock Blocks](#unlock-blocks). - * The unlock block itself must pass syntactic validation. + * 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. +1 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](../TIP-0002/tip-0002.md#deterministically-ordering-the-tangle). @@ -426,25 +515,13 @@ Processing transactions according to the White-Flag ordering enables users to sp 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 coin 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. -* The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. -* The transaction must be balanced in terms of native tokens, i.e. the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. -* Each output and all its [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) must pass semantic validation in the context of the following input: - 1. The _Transaction Payload_, - 2. the list of UTXOs referenced by inputs and - 3. the milestone index and Unix timestamp of the confirming milestone. +* 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 it is an _Alias Unlock Block_: - * The address unlocking the UTXO must be an _Alias Address_. - * The referenced _Unlock Block_ unlocks the alias defined by the unlocking address of the UTXO. - * If it is an _NFT Unlock Block_: - * The address unlocking the UTXO must be a _NFT Address_. - * The referenced _Unlock Block_ unlocks the NFT defined by the unlocking address of 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](../TIP-0004/tip-0004.md)). @@ -454,7 +531,7 @@ Transactions that do not pass semantic validation are ignored. Their UTXOs are n ### 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_. Instead, the global timestamp of the confirming milestone ([TIP-6](../TIP-0008/tip-0008.md)) is uesd. +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](../TIP-0008/tip-0008.md)). ### Address reuse @@ -471,7 +548,7 @@ In essence, Ed25519 support allows for smaller transaction sizes and to safely s * 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 TIP 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. +* 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 diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md new file mode 100644 index 000000000..19fc4d747 --- /dev/null +++ b/tips/TIP-0020/tip-0020.md @@ -0,0 +1,479 @@ +--- +tip: 20 +title: Transaction Payload with TIP-18 Output Types +description: Add output types, unlock blocks and output feature blocks from TIP-18 into Transaction Payload +author: Levente Pap (@lzpap) +discussions-to: https://github.com/iotaledger/tips/pull/40 +status: Draft +type: Standards +layer: Core +created: 2021-11-18 +requires: TIP-7 and TIP-18 +--- + +# Summary + +This TIP proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for the _messages_ described in [TIP-6](../TIP-0006/tip-0006.md). + +# Motivation + +There are several options on how transfers of IOTA coins can be embedded into the actual vertices of the Tangle. In the legacy IOTA protocol, each vertex corresponds to a single transaction, i.e. an input or an output. In order to support atomic transfers, input/output transactions have to be grouped into a so-called bundle and then either the entire bundle is applied to the ledger or none of its transactions. + +The bundle concept has proven to be rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle message/vertex. + +The new transaction structure should fulfill the following criteria: +- Support for Ed25519 signatures. +- Support for adding new types of signature schemes, addresses, inputs, and outputs as part of protocol upgrades. +- Implement the UTXO 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. +* Balances are no longer strictly associated to addresses. This allows a higher 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: + +![UTXO flow](utxo.png) + +## 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_. + +The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. + +The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlock blocks. + +The following table describes the entirety of a _Transaction Payload_ in its serialized form following the notation from [draft TIP-21](https://github.com/iotaledger/tips/pull/41): + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Payload Typeuint32 + Set to value 0 to denote a Transaction Payload. +
Essence oneOf +
+ Transaction Essence +
+ Describes the essence data making up a transaction by defining its inputs, outputs and an optional payload. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Transaction Typeuint8 + Set to value 0 to denote a Transaction Essence. +
Inputs Countuint16The number of input entries.
Inputs anyOf +
+ UTXO Input +
+ Describes an input which references an unspent transaction output to consume. +
+ + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Input Typeuint8 + Set to value 0 to denote an UTXO Input. +
Transaction IDByteArray[32]The BLAKE2b-256 hash of the transaction payload containing the referenced output.
Transaction Output Indexuint16The output index of the referenced output.
+
+
Outputs Countuint16The number of output entries.
Outputs anyOf +
+ Extended Output +
+ Describes a deposit to a single address. The output might contain optional feature blocks and native tokens. +
+
+
+ Alias Output +
+ Describes an alias account in the ledger. +
+
+
+ Foundry Output +
+ Describes a foundry that controls supply of native tokens. +
+
+
+ NFT Output +
+ Describes a unique, non-fungible token deposit to a single address. +
+
+
Payload Lengthuint32The length in bytes of the optional payload.
Payload optOneOf +
+ Generic Payload +
+ An outline of a generic payload. +
+ + + + + + + + + + + + + + + + +
NameTypeDescription
Payload Typeuint32 + The type of the payload. It will instruct the node how to parse the fields that follow. +
Data FieldsANYA sequence of fields, where the structure depends on Payload Type.
+
+
+
+
Unlock Blocks Countuint16The number of unlock block entries. It must match the field Inputs Count.
Unlock Blocks anyOf +
+ 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. +
+
+
+ Alias Unlock Block +
+ References a previous unlock block of a consumed alias output. +
+
+
+ NFT Unlock Block +
+ References a previous unlock block of a consumed NFT output. +
+
+
+ +### Transaction Essence + +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` field 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 referenced output. + +#### Outputs + +The `Outputs` field holds the outputs that are created by the Transaction Payload. There are different output types, but they must all have an `Amount` field denoting the number of IOTA coins to deposit. + +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanceOutput_ introduced in Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) have been removed and are no longer supported. + +| Output Name | Type Value | TIP | +| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------ | +| Extended | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#extended-output) | +| Alias | 4 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-output) | +| Foundry | 5 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#foundry-output) | +| NFT | 6 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-output) | + +#### Payload + +The _Transaction Essence_ itself can contain another payload as described in general in [TIP-6](../TIP-0006/tip-0006.md). The [semantic validity](#semantic-validation) 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: + +| Name | Type Value | TIP | +| ---------- | ---------- | ----------------------------------------------------| +| Indexation | 2 | [TIP-6](../TIP-0006/tip-0006.md#indexation-payload) | + +### Unlock Blocks + +The `Unlock Blocks` field holds the unlock blocks unlocking inputs within a _Transaction Essence_. + +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock Block_ as well as the _Reference Unlock Block_ is specified as part of this TIP. + +| Unlock Block Name | Type Value | TIP | +| ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | +| Signature | 0 | [TIP-20](#signature-unlock-block) | +| Reference | 1 | [TIP-20](#reference-unlock-block) | +| Alias | 2 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-locking--unlocking) | +| NFT | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-locking--unlocking) | + +#### Signature Unlock Block + +The Signature Unlock Block defines an Unlock Block which holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including the optional payload). It is serialized as follows: + + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 0 to denote a Signature Unlock Block. +
Signature oneOf +
+ Ed25519 Signature + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Signature Typeuint8 + Set to value 0 to denote an Ed25519 Signature. +
Public keyByteArray[32]The Ed25519 public key of the signature.
SignatureByteArray[64]The Ed25519 signature signing the Blake2b-256 hash of the serialized Transaction Essence.
+
+
+ +##### Unlock syntactic validation + +* `Signature` must contain an _Ed25519 Signature_. +* The _Signature Unlock Block_ must be unique, i.e. there must not be any other _Signature Unlock Blocks_ in the `Unlock Blocks` field of the transaction payload with the same signature. + +#### Reference Unlock Block + +The 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. It is serialized as follows: + + + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 1 to denote a Reference Unlock Block. +
Referenceuint16Represents the index of a previous unlock block.
+ +##### Unlock syntactic validation + +* The _Reference Unlock Block_ at index i must have `Reference` < i and the unlock block at index `Reference` must be a _Signature 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: +| Index | Unlock Block | +| ----- | ---------------------------------------------------------------------------------------- | +| 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. | + +## 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 + +The different output types and optional output feature blocks introduced by [draft TIP-18](https://github.com/iotaledger/tips/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-design) and [feature block type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) separately. + +### 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 broadcast 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 ≤ `Max Inputs Count`. + * For each input the following must be true: + * `Input Type` must denote a _UTXO Input_. + * `Transaction Output Index` must be 0 ≤ x < `Max Outputs Count`. + * Each pair of `Transaction ID` and `Transaction Output Index` must be unique in the list of inputs. + * Outputs: + * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. + * For each input the following must be true: + * `Output Type` must match one of the values described under [Outputs](#outputs). + * The output itself must pass syntactic validation. + * The sum of all `Amount` fields must not exceed `Max IOTA Supply`. + * Payload (if present): + * `Payload Type` must match one of the values described under [Payload](#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_. + * For each unlock block the following must be true: + * Each `Unlock Block Type` must match one of the values described under [Unlock Blocks](#unlock-blocks). + * The unlock block itself must pass syntactic validation. +* Given the type and length information, the _Transaction Payload_ must consume the entire byte array of the `Payload` field of the encapsulating object. + +### 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](../TIP-0002/tip-0002.md#deterministically-ordering-the-tangle). + +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 coin 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. +* The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. +* The transaction must be balanced in terms of native tokens, i.e. the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. +* Each output and all its [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) must pass semantic validation in the context of the following input: + 1. The _Transaction Payload_, + 2. the list of UTXOs referenced by inputs and + 3. the milestone index and Unix timestamp of the confirming milestone. +* 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 it is an _Alias Unlock Block_: + * The address unlocking the UTXO must be an _Alias Address_. + * The referenced _Unlock Block_ unlocks the alias defined by the unlocking address of the UTXO. + * If it is an _NFT Unlock Block_: + * The address unlocking the UTXO must be a _NFT Address_. + * The referenced _Unlock Block_ unlocks the NFT defined by the unlocking address of 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](../TIP-0004/tip-0004.md)). + +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_. Instead, the global timestamp of the confirming milestone ([TIP-6](../TIP-0008/tip-0008.md)) is uesd. + +### 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](https://en.bitcoin.it/wiki/Address_reuse) 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 TIP 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](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/tips/TIP-0020/utxo.png b/tips/TIP-0020/utxo.png new file mode 100644 index 0000000000000000000000000000000000000000..b6f9f198869b3485acf8c67b7a98331a41a9f18a GIT binary patch literal 52729 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

`=; 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 lijjX`%s;&_yU$Hm$oImi4*R}p Date: Mon, 17 Jan 2022 19:38:29 +0100 Subject: [PATCH 06/40] add network ID to essence --- tips/TIP-0020/tip-0020.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 19fc4d747..782525282 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -92,6 +92,13 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Set to value 0 to denote a Transaction Essence. + + Network ID + uint64 + + The unique value denoting whether the message was meant for mainnet, testnet, or a private networks. The Network ID should usually match the corresponding field of the encapsulating message, but this is not enforced. + + Inputs Count uint16 @@ -396,6 +403,7 @@ The following criteria defines whether a payload passes the syntactical validati * Essence: * `Transaction Type` value must denote a _Transaction Essence_. + * `Network ID` must match the value of the current network. * Inputs: * `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. * For each input the following must be true: From 1632afd81ddffe564a29f00bdd2585c1af8e3e39 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 3 Feb 2022 16:41:03 +0100 Subject: [PATCH 07/40] Introduce Inputs Commitment field --- tips/TIP-0020/tip-0020.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 782525282..73333f19e 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -99,6 +99,13 @@ The following table describes the entirety of a _Transaction Payload_ in its ser The unique value denoting whether the message was meant for mainnet, testnet, or a private networks. The Network ID should usually match the corresponding field of the encapsulating message, but this is not enforced. + + Inputs Commitment + ByteArray[32] + + BLAKE2b-256 hash of the serialized outputs referenced in Inputs by their Output IDs (Transaction ID || Transaction Output Index). + + Inputs Count uint16 @@ -435,6 +442,7 @@ Processing transactions according to the White-Flag ordering enables users to sp 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. +* `Inputs Commitment` must be equal to the BLAKE2b-256 hash of the serialized outputs that are referenced as inputs. The order of the serialized outputs must be the same as their order in `Inputs`. * The transaction must spend the entire coin 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. * The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. * The transaction must be balanced in terms of native tokens, i.e. the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. From 574bcdcdc8a113d878a88daac3fccb03006d85ab Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 10 Feb 2022 19:59:10 +0100 Subject: [PATCH 08/40] `InputsCommitment` after `Inputs` --- tips/TIP-0020/tip-0020.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 73333f19e..76c678c54 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -99,13 +99,6 @@ The following table describes the entirety of a _Transaction Payload_ in its ser The unique value denoting whether the message was meant for mainnet, testnet, or a private networks. The Network ID should usually match the corresponding field of the encapsulating message, but this is not enforced. - - Inputs Commitment - ByteArray[32] - - BLAKE2b-256 hash of the serialized outputs referenced in Inputs by their Output IDs (Transaction ID || Transaction Output Index). - - Inputs Count uint16 @@ -146,6 +139,13 @@ The following table describes the entirety of a _Transaction Payload_ in its ser

+ + Inputs Commitment + ByteArray[32] + + BLAKE2b-256 hash of the serialized outputs referenced in Inputs by their Output IDs (Transaction ID || Transaction Output Index). + + Outputs Count uint16 From 9dfa23d6d133d6de3aade3d5d90047f3402d82fb Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Mon, 21 Feb 2022 09:22:15 +0100 Subject: [PATCH 09/40] Remove obsolete sentence --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 76c678c54..351106374 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -96,7 +96,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Network ID uint64 - The unique value denoting whether the message was meant for mainnet, testnet, or a private networks. The Network ID should usually match the corresponding field of the encapsulating message, but this is not enforced. + The unique value denoting whether the message was meant for mainnet, testnet, or a private networks. From 15cc7b365a39cd12cac0450b61618e90f14a6072 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Mon, 28 Feb 2022 11:23:20 +0100 Subject: [PATCH 10/40] Bump types - Bump Tx Payload type to 6 - Bump Tx Essence type to 1 - Add Tagged Data as supported payload type instead of Indexation --- tips/TIP-0020/tip-0020.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 351106374..564a322f6 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -68,7 +68,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Payload Type uint32 - Set to value 0 to denote a Transaction Payload. + Set to value 6 to denote a TIP-20 Transaction Payload. @@ -89,7 +89,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Transaction Type uint8 - Set to value 0 to denote a Transaction Essence. + Set to value 1 to denote a TIP-20 Transaction Essence. @@ -256,7 +256,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser ### Transaction Essence -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 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 1 for TIP-20 Transaction Essence. #### Inputs @@ -283,13 +283,13 @@ The following table lists all the output types that are currently supported as w #### Payload -The _Transaction Essence_ itself can contain another payload as described in general in [TIP-6](../TIP-0006/tip-0006.md). The [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ does not have any impact on the payload. +The _Transaction Essence_ itself can contain another payload as described in general in [draft TIP-24](https://github.com/iotaledger/tips/pull/55). The [semantic validity](#semantic-validation) 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: -| Name | Type Value | TIP | -| ---------- | ---------- | ----------------------------------------------------| -| Indexation | 2 | [TIP-6](../TIP-0006/tip-0006.md#indexation-payload) | +| Name | Type Value | TIP | +|-------------|------------|------------------------------------------------------------| +| Tagged Data | 5 | [draft TIP-23](https://github.com/iotaledger/tips/pull/54) | ### Unlock Blocks @@ -471,7 +471,7 @@ Transactions that do not pass semantic validation are ignored. Their UTXOs are n ### 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_. Instead, the global timestamp of the confirming milestone ([TIP-6](../TIP-0008/tip-0008.md)) is uesd. +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_. Instead, the global timestamp of the confirming milestone ([TIP-8](../TIP-0008/tip-0008.md)) is used. ### Address reuse From 88b7bce62fa5f68ea51fd71cd9a906a7dec90974 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Fri, 4 Mar 2022 11:53:31 +0100 Subject: [PATCH 11/40] Introduce native token minting, melting and burning Minting and melting are restricted to the foundry, while burning is performed by the user without the need for the foundry to be update. --- tips/TIP-0020/tip-0020.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 564a322f6..fde7eb614 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -445,7 +445,9 @@ The following criteria defines whether a payload passes the semantic validation: * `Inputs Commitment` must be equal to the BLAKE2b-256 hash of the serialized outputs that are referenced as inputs. The order of the serialized outputs must be the same as their order in `Inputs`. * The transaction must spend the entire coin 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. * The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. -* The transaction must be balanced in terms of native tokens, i.e. the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. Otherwise, the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the outstanding balances are valid. +* The transaction is balanced in terms of native tokens, when the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. When the transaction is imbalanced, it must hold true that when there is a **surplus of native tokens** on the: + * **output side of the transaction:** the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the minting operations are valid. + * **input side of the transaction:** the transaction destroys tokens. The presence and validation of the foundry outputs of the native tokens determines whether the tokens are burned (removed from the ledger) or melted within the foundry. When the foundry output is not present in the transaction, outstanding token balances must be burned. * Each output and all its [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) must pass semantic validation in the context of the following input: 1. The _Transaction Payload_, 2. the list of UTXOs referenced by inputs and From e2f59c7336569c8831716811ca05839d85a35cfb Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Wed, 13 Apr 2022 10:59:45 +0200 Subject: [PATCH 12/40] Add Output ID definition --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index fde7eb614..6dc147301 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -266,7 +266,7 @@ Each input must be accompanied by a corresponding Unlock Block at the sam ##### 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 referenced output. +A UTXO Input is an input which references an unspent output of a previous transaction. This UTXO is uniquely identified by its _Output ID_, defined by the _Transaction ID_ of the creating transaction together with corresponding output index. Each UTXO Input must be accompanied by an Unlock Block that is allowed to unlock the referenced output. #### Outputs From 087dee5a6b4a04d688fbc976a48df4e3220213e9 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Fri, 13 May 2022 17:37:29 +0200 Subject: [PATCH 13/40] Update ref to "Message" to "Block" to align with IOTA 2.0 terminology --- tips/TIP-0020/tip-0020.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 6dc147301..19e9f3a22 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -13,13 +13,13 @@ requires: TIP-7 and TIP-18 # Summary -This TIP proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for the _messages_ described in [TIP-6](../TIP-0006/tip-0006.md). +This TIP proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for _blocks_ described in [TIP-24](../TIP-0024/tip-0024.md). # Motivation There are several options on how transfers of IOTA coins can be embedded into the actual vertices of the Tangle. In the legacy IOTA protocol, each vertex corresponds to a single transaction, i.e. an input or an output. In order to support atomic transfers, input/output transactions have to be grouped into a so-called bundle and then either the entire bundle is applied to the ledger or none of its transactions. -The bundle concept has proven to be rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle message/vertex. +The bundle concept has proven to be rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle block/vertex. The new transaction structure should fulfill the following criteria: - Support for Ed25519 signatures. @@ -96,7 +96,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Network ID uint64 - The unique value denoting whether the message was meant for mainnet, testnet, or a private networks. + The unique value denoting whether the block was meant for mainnet, shimmer, testnet, or a private networks. @@ -436,9 +436,9 @@ The following criteria defines whether a payload passes the syntactical validati ### 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](../TIP-0002/tip-0002.md#deterministically-ordering-the-tangle). +The Semantic validation of a _Transaction Payload_ is performed when its encapsulating block 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](../TIP-0002/tip-0002.md#deterministically-ordering-the-tangle). -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. +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 _Block ID_ of the funding transaction as a parent of the block 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. @@ -465,7 +465,7 @@ The following criteria defines whether a payload passes the semantic validation: * The address unlocking the UTXO must be a _NFT Address_. * The referenced _Unlock Block_ unlocks the NFT defined by the unlocking address of 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](../TIP-0004/tip-0004.md)). +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 _Block ID_ of the block encapsulating the processed payload then also becomes part of the input for the White-Flag Merkle tree hash of the confirming milestone ([TIP-4](../TIP-0004/tip-0004.md)). 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. From f67f43f83ec30fe8fca041a9a733e7c58a35b8ff Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 19 May 2022 14:30:51 +0200 Subject: [PATCH 14/40] Rename "unlock blocks" to simply "unlocks" --- tips/TIP-0020/tip-0020.md | 110 +++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 19e9f3a22..f0a242bfe 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -1,7 +1,7 @@ --- tip: 20 title: Transaction Payload with TIP-18 Output Types -description: Add output types, unlock blocks and output feature blocks from TIP-18 into Transaction Payload +description: Add output types, unlocks and output featured from TIP-18 into Transaction Payload author: Levente Pap (@lzpap) discussions-to: https://github.com/iotaledger/tips/pull/40 status: Draft @@ -38,7 +38,7 @@ Using a UTXO-based model provides several benefits: * 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. * Balances are no longer strictly associated to addresses. This allows a higher 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. +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*. An unlock 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: @@ -50,11 +50,11 @@ The following image depicts the flow of funds using UTXO: 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_. +2. The _Unlocks_ which unlock the inputs of the _Transaction Essence_. The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. -The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlock blocks. +The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlocks. The following table describes the entirety of a _Transaction Payload_ in its serialized form following the notation from [draft TIP-21](https://github.com/iotaledger/tips/pull/41): @@ -157,7 +157,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Extended Output
- Describes a deposit to a single address. The output might contain optional feature blocks and native tokens. + Describes a deposit to a single address. The output might contain optional features and native tokens.
@@ -219,35 +219,35 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - Unlock Blocks Count + Unlocks Count uint16 - The number of unlock block entries. It must match the field Inputs Count. + The number of unlock entries. It must match the field Inputs Count. - Unlock Blocks anyOf + Unlocks anyOf
- Signature Unlock Block + Signature Unlock
- Defines an unlock block containing a signature. + Defines an unlock containing a signature.
- Reference Unlock Block + Reference Unlock
- References a previous unlock block, where the same unlock block can be used for multiple inputs. + References a previous unlock, where the same unlock can be used for multiple inputs.
- Alias Unlock Block + Alias Unlock
- References a previous unlock block of a consumed alias output. + References a previous unlock of a consumed alias output.
- NFT Unlock Block + NFT Unlock
- References a previous unlock block of a consumed NFT output. + References a previous unlock of a consumed NFT output.
@@ -262,11 +262,11 @@ The Transaction Essence of a Transaction Payload carries the input The `Inputs` field 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. +Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks 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 identified by its _Output ID_, defined by the _Transaction ID_ of the creating transaction together with corresponding output index. Each UTXO Input must be accompanied by an Unlock Block that is allowed to unlock the referenced output. +A UTXO Input is an input which references an unspent output of a previous transaction. This UTXO is uniquely identified by its _Output ID_, defined by the _Transaction ID_ of the creating transaction together with corresponding output index. Each UTXO Input must be accompanied by an Unlock that is allowed to unlock the referenced output. #### Outputs @@ -291,22 +291,22 @@ The following table lists all the payload types that can be nested inside a _Tra |-------------|------------|------------------------------------------------------------| | Tagged Data | 5 | [draft TIP-23](https://github.com/iotaledger/tips/pull/54) | -### Unlock Blocks +### Unlocks -The `Unlock Blocks` field holds the unlock blocks unlocking inputs within a _Transaction Essence_. +The `Unlocks` field holds the unlocks unlocking inputs within a _Transaction Essence_. -The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock Block_ as well as the _Reference Unlock Block_ is specified as part of this TIP. +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock_ as well as the _Reference Unlock_ is specified as part of this TIP. -| Unlock Block Name | Type Value | TIP | -| ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | -| Signature | 0 | [TIP-20](#signature-unlock-block) | -| Reference | 1 | [TIP-20](#reference-unlock-block) | -| Alias | 2 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-locking--unlocking) | -| NFT | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-locking--unlocking) | +| Unlock Name | Type Value | TIP | +|-------------|------------|-----------------------------------------------------------------------------------------------------------------------| +| Signature | 0 | [TIP-20](#signature-unlock) | +| Reference | 1 | [TIP-20](#reference-unlock) | +| Alias | 2 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-locking--unlocking) | +| NFT | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-locking--unlocking) | -#### Signature Unlock Block +#### Signature Unlock -The Signature Unlock Block defines an Unlock Block which holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including the optional payload). It is serialized as follows: +The Signature Unlock defines an Unlock which holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including the optional payload). It is serialized as follows: @@ -318,7 +318,7 @@ The Signature Unlock Block defines an Unlock Block which holds a s @@ -358,11 +358,11 @@ The Signature Unlock Block defines an Unlock Block which holds a s ##### Unlock syntactic validation * `Signature` must contain an _Ed25519 Signature_. -* The _Signature Unlock Block_ must be unique, i.e. there must not be any other _Signature Unlock Blocks_ in the `Unlock Blocks` field of the transaction payload with the same signature. +* The _Signature Unlock_ must be unique, i.e. there must not be any other _Signature Unlocks_ in the `Unlocks` field of the transaction payload with the same signature. -#### Reference Unlock Block +#### Reference Unlock -The 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. It is serialized as follows: +The Reference Unlock defines an Unlock which references a previous Unlock (which must not be another Reference Unlock). It **must** be used if multiple inputs can be unlocked via the same Unlock. It is serialized as follows:
Unlock Type uint8 - Set to value 0 to denote a Signature Unlock Block. + Set to value 0 to denote a Signature Unlock.
@@ -374,33 +374,33 @@ The Reference Unlock Block defines an Unlock Block which reference - +
Unlock Type uint8 - Set to value 1 to denote a Reference Unlock Block. + Set to value 1 to denote a Reference Unlock.
Reference uint16Represents the index of a previous unlock block.Represents the index of a previous unlock.
##### Unlock syntactic validation -* The _Reference Unlock Block_ at index i must have `Reference` < i and the unlock block at index `Reference` must be a _Signature Unlock Block_. +* The _Reference Unlock_ at index i must have `Reference` < i and the unlock at index `Reference` must be a _Signature Unlock_. 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: -| Index | Unlock Block | +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 Unlocks part: +| Index | Unlock | | ----- | ---------------------------------------------------------------------------------------- | -| 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. | +| 0 | A _Signature Unlock_ holding the Ed25519 signature for address A. | +| 1 | A _Signature Unlock_ holding the Ed25519 signature for address B. | +| 2 | A _Reference Unlock_ which references 0, as both require the same signature for A. | ## 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 -The different output types and optional output feature blocks introduced by [draft TIP-18](https://github.com/iotaledger/tips/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-design) and [feature block type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) separately. +The different output types and optional output features introduced by [draft TIP-18](https://github.com/iotaledger/tips/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-design) and [feature type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) separately. ### Syntactic validation @@ -427,11 +427,11 @@ The following criteria defines whether a payload passes the syntactical validati * `Payload Type` must match one of the values described under [Payload](#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_. - * For each unlock block the following must be true: - * Each `Unlock Block Type` must match one of the values described under [Unlock Blocks](#unlock-blocks). - * The unlock block itself must pass syntactic validation. +* Unlocks: + * `Unlocks Count` must match `Inputs Count` of the _Transaction Essence_. + * For each unlock the following must be true: + * Each `Unlock Type` must match one of the values described under [Unlocks](#unlocks). + * The unlock itself must pass syntactic validation. * Given the type and length information, the _Transaction Payload_ must consume the entire byte array of the `Payload` field of the encapsulating object. ### Semantic validation @@ -448,22 +448,22 @@ The following criteria defines whether a payload passes the semantic validation: * The transaction is balanced in terms of native tokens, when the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. When the transaction is imbalanced, it must hold true that when there is a **surplus of native tokens** on the: * **output side of the transaction:** the foundry outputs controlling outstanding native token balances must be present in the transaction. The validation of the foundry output(s) determines if the minting operations are valid. * **input side of the transaction:** the transaction destroys tokens. The presence and validation of the foundry outputs of the native tokens determines whether the tokens are burned (removed from the ledger) or melted within the foundry. When the foundry output is not present in the transaction, outstanding token balances must be burned. -* Each output and all its [output feature blocks](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) must pass semantic validation in the context of the following input: +* Each output and all its [output features](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#features) must pass semantic validation in the context of the following input: 1. The _Transaction Payload_, 2. the list of UTXOs referenced by inputs and 3. the milestone index and Unix timestamp of the confirming milestone. -* 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_: +* Each unlock must be valid with respect to the UTXO referenced by the input of the same index: + * If it is a _Signature Unlock_: * 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 it is an _Alias Unlock Block_: + * If it is a _Reference Unlock_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. + * If it is an _Alias Unlock_: * The address unlocking the UTXO must be an _Alias Address_. - * The referenced _Unlock Block_ unlocks the alias defined by the unlocking address of the UTXO. - * If it is an _NFT Unlock Block_: + * The referenced _Unlock_ unlocks the alias defined by the unlocking address of the UTXO. + * If it is an _NFT Unlock_: * The address unlocking the UTXO must be a _NFT Address_. - * The referenced _Unlock Block_ unlocks the NFT defined by the unlocking address of the UTXO. + * The referenced _Unlock_ unlocks the NFT defined by the unlocking address of 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 _Block ID_ of the block encapsulating the processed payload then also becomes part of the input for the White-Flag Merkle tree hash of the confirming milestone ([TIP-4](../TIP-0004/tip-0004.md)). From c2879207fdc7d3ea6d26b07b4b19babeb744e212 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Fri, 20 May 2022 12:32:50 +0200 Subject: [PATCH 15/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: muXxer --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index f0a242bfe..f7c3fb038 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -143,7 +143,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Inputs Commitment ByteArray[32] - BLAKE2b-256 hash of the serialized outputs referenced in Inputs by their Output IDs (Transaction ID || Transaction Output Index). + BLAKE2b-256 hash of the BLAKE2b-256 hashes of the serialized outputs referenced in Inputs by their Output IDs (Transaction ID || Transaction Output Index). From 7f3d57a87d9626cdff28724351cdc0fbef22436d Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Fri, 20 May 2022 12:32:59 +0200 Subject: [PATCH 16/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: muXxer --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index f7c3fb038..1f45924cb 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -442,7 +442,7 @@ Processing transactions according to the White-Flag ordering enables users to sp 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. -* `Inputs Commitment` must be equal to the BLAKE2b-256 hash of the serialized outputs that are referenced as inputs. The order of the serialized outputs must be the same as their order in `Inputs`. +* `Inputs Commitment` must be equal to the BLAKE2b-256 hash of the BLAKE2b-256 hashes of the serialized outputs that are referenced as inputs. The order of the serialized outputs must be the same as their order in `Inputs`. * The transaction must spend the entire coin 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. * The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. * The transaction is balanced in terms of native tokens, when the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. When the transaction is imbalanced, it must hold true that when there is a **surplus of native tokens** on the: From efe9fefad979e9ad8fa4433558a6f836196b58cd Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Fri, 20 May 2022 12:33:05 +0200 Subject: [PATCH 17/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Sam Chen --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 1f45924cb..0500ea9fc 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -1,7 +1,7 @@ --- tip: 20 title: Transaction Payload with TIP-18 Output Types -description: Add output types, unlocks and output featured from TIP-18 into Transaction Payload +description: Add output types, unlocks, and output features from TIP-18 into Transaction Payload author: Levente Pap (@lzpap) discussions-to: https://github.com/iotaledger/tips/pull/40 status: Draft From 86cd1d198f72fa7c517625f6a5ec76448c215e64 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Wed, 13 Jul 2022 14:40:12 +0200 Subject: [PATCH 18/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Thibault Martinez --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 0500ea9fc..ca3eb9202 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -19,7 +19,7 @@ This TIP proposes a UTXO-based transaction structure consisting of all the input There are several options on how transfers of IOTA coins can be embedded into the actual vertices of the Tangle. In the legacy IOTA protocol, each vertex corresponds to a single transaction, i.e. an input or an output. In order to support atomic transfers, input/output transactions have to be grouped into a so-called bundle and then either the entire bundle is applied to the ledger or none of its transactions. -The bundle concept has proven to be rather challenging in practices as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle block/vertex. +The bundle concept has proven to be rather challenging in practice as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle block/vertex. The new transaction structure should fulfill the following criteria: - Support for Ed25519 signatures. From eed1b075c1616d484da739999c710505a229af75 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Wed, 13 Jul 2022 14:40:38 +0200 Subject: [PATCH 19/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Thibault Martinez --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index ca3eb9202..73428b02e 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -155,7 +155,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Outputs anyOf
- Extended Output + Basic Output
Describes a deposit to a single address. The output might contain optional features and native tokens.
From 436906fb26a333836c0b7c8acc011ff8fda0eb0c Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Wed, 13 Jul 2022 14:40:52 +0200 Subject: [PATCH 20/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Thibault Martinez --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 73428b02e..74d30a592 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -276,7 +276,7 @@ The following table lists all the output types that are currently supported as w | Output Name | Type Value | TIP | | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------ | -| Extended | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#extended-output) | +| Basic | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#basic-output) | | Alias | 4 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-output) | | Foundry | 5 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#foundry-output) | | NFT | 6 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-output) | From 2109b7cf39664cbb2814119a3f6972e853efc5ac Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Wed, 13 Jul 2022 14:41:23 +0200 Subject: [PATCH 21/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Thibault Martinez --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 74d30a592..e3de74bfa 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -295,7 +295,7 @@ The following table lists all the payload types that can be nested inside a _Tra The `Unlocks` field holds the unlocks unlocking inputs within a _Transaction Essence_. -The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock_ as well as the _Reference Unlock_ is specified as part of this TIP. +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _Signature Unlock_ and the _Reference Unlock_ are specified as part of this TIP. | Unlock Name | Type Value | TIP | |-------------|------------|-----------------------------------------------------------------------------------------------------------------------| From 74dc0cc11a26982c464cb8482dc0393e74f32fb8 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Fri, 15 Jul 2022 13:15:41 +0200 Subject: [PATCH 22/40] Add Inputs Commitment explanation --- tips/TIP-0020/tip-0020.md | 4 ++++ tips/TIP-0020/utxo.png | Bin 52729 -> 66064 bytes 2 files changed, 4 insertions(+) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index e3de74bfa..b96e5276d 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -268,6 +268,10 @@ Each input must be accompanied by a corresponding Unlock at the same inde A UTXO Input is an input which references an unspent output of a previous transaction. This UTXO is uniquely identified by its _Output ID_, defined by the _Transaction ID_ of the creating transaction together with corresponding output index. Each UTXO Input must be accompanied by an Unlock that is allowed to unlock the referenced output. +#### Inputs Commitment + +The _Inputs Commitment_ field of the _Transaction Essence_ is a cryptographic commitment to the content of the consumed outputs (inputs). The transaction itself only references inputs by _Output ID_, therefore the client has to be aware of the content to produce a semantically valid transaction. The commitment is a security mechanism that protects clients against [eclipse attacks that would result in loss of funds.](https://github.com/iotaledger/tips/discussions/51) + #### Outputs The `Outputs` field holds the outputs that are created by the Transaction Payload. There are different output types, but they must all have an `Amount` field denoting the number of IOTA coins to deposit. diff --git a/tips/TIP-0020/utxo.png b/tips/TIP-0020/utxo.png index b6f9f198869b3485acf8c67b7a98331a41a9f18a..b29177df2139d3a254de7d3c03a746e3d8787dfb 100644 GIT binary patch literal 66064 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�AU^LAq{z-z*! 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 D7a`vM literal 52729 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

`=; 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 lijjX`%s;&_yU$Hm$oImi4*R}p Date: Fri, 15 Jul 2022 13:22:53 +0200 Subject: [PATCH 23/40] Apply PR review suggestions --- tips/TIP-0020/tip-0020.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index b96e5276d..359edfb91 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -402,13 +402,13 @@ Consider a Transaction Essence containing the UTXO Inputs 0, 1 and ## 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 +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. The different output types and optional output features introduced by [draft TIP-18](https://github.com/iotaledger/tips/pull/38) add additional constraints to the transaction validation rules, but since these are specific to the given outputs and features, they are discussed for each [output type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-design) and [feature type](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#output-features) separately. ### 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 broadcast further and can be discarded right away. +Syntactic validation is checked as soon as the transaction has been received. It validates the structure but not the signatures of the transaction. If the transaction does not pass this stage, it must not be broadcast further and can be discarded right away. The following criteria defines whether a payload passes the syntactical validation: @@ -429,7 +429,7 @@ The following criteria defines whether a payload passes the syntactical validati * The sum of all `Amount` fields must not exceed `Max IOTA Supply`. * Payload (if present): * `Payload Type` must match one of the values described under [Payload](#payload). - * `Data fields` must be correctly parsable in the context of the `Payload Type`. + * Payload fields must be correctly parsable in the context of the `Payload Type`. * The payload itself must pass syntactic validation. * Unlocks: * `Unlocks Count` must match `Inputs Count` of the _Transaction Essence_. @@ -455,7 +455,7 @@ The following criteria defines whether a payload passes the semantic validation: * Each output and all its [output features](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#features) must pass semantic validation in the context of the following input: 1. The _Transaction Payload_, 2. the list of UTXOs referenced by inputs and - 3. the milestone index and Unix timestamp of the confirming milestone. + 3. the Unix timestamp of the confirming milestone. * Each unlock must be valid with respect to the UTXO referenced by the input of the same index: * If it is a _Signature Unlock_: * The `Signature Type` must match the `Address Type` of the UTXO, From 52ab7666afab161350478bf51e0aae8393ddbbd7 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 21 Jul 2022 15:59:47 +0200 Subject: [PATCH 24/40] Rewrite motivation --- tips/TIP-0020/tip-0020.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 359edfb91..9a466dd19 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -8,23 +8,27 @@ status: Draft type: Standards layer: Core created: 2021-11-18 -requires: TIP-7 and TIP-18 +requires: [TIP-18](../TIP-0018/tip-0018.md) +replaces: [TIP-7](../TIP-0007/tip-0007.md) --- # Summary -This TIP proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for _blocks_ described in [TIP-24](../TIP-0024/tip-0024.md). +This TIP proposes a UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. Specifically, this TIP defines a transaction payload for _blocks_ described in [TIP-24](../TIP-0024/tip-0024.md) and extends the transaction payload described in [TIP-7](../TIP-0007/tip-0007.md). # Motivation -There are several options on how transfers of IOTA coins can be embedded into the actual vertices of the Tangle. In the legacy IOTA protocol, each vertex corresponds to a single transaction, i.e. an input or an output. In order to support atomic transfers, input/output transactions have to be grouped into a so-called bundle and then either the entire bundle is applied to the ledger or none of its transactions. - -The bundle concept has proven to be rather challenging in practice as validation can get very complex, especially in the context of reattachments. Therefore, this TIP proposes an alternative approach: It defines a self-contained transaction payload, containing the entire transfer, that is then embedded into a single Tangle block/vertex. - -The new transaction structure should fulfill the following criteria: -- Support for Ed25519 signatures. -- Support for adding new types of signature schemes, addresses, inputs, and outputs as part of protocol upgrades. -- Implement the UTXO model. +[TIP-7](../TIP-0007/tip-0007.md) describes the introduction of the UTXO ledger model for Chrysalis. This TIP extends the +transaction model of the UTXO ledger to: + - accommodate for the new output types introduced in [TIP-18](../TIP-0018/tip-0018.md), + - include a _Network ID_ field in the transaction for replay protection, + - introduce _Inputs Commitment_ field to prevent client [eclipse attacks that would result in loss of funds,](https://github.com/iotaledger/tips/discussions/51) + - relax syntactic validation rules such that inputs and outputs of a transaction are no longer lexicographically ordered, furthermore + outputs don't have to be unique. + +The motivation for such changes is to provide a more flexible and secure framework for wallets and layer 2 applications. Chrysalis +focused solely on using the ledger as a payment application, while Stardust transforms the ledger into a settlement layer +for interconnected layer 2 blockchains and applications. # Detailed design From 84522e844116ff6497ccb1371b8d7d5e7f779596 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 21 Jul 2022 16:00:27 +0200 Subject: [PATCH 25/40] Fix links --- tips/TIP-0020/tip-0020.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 9a466dd19..b9efda6e5 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -56,7 +56,7 @@ 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 _Unlocks_ which unlock the inputs of the _Transaction Essence_. -The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. +The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. However, in contrast to Chrysalis Phase 2 [TIP-7](../TIP-0007/tip-0007.md) the inputs and outputs are considered as lists. They can contain duplicates and their serialization order matches the order of the list; they do not need to be sorted. The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlocks. @@ -295,9 +295,9 @@ The _Transaction Essence_ itself can contain another payload as described in ge The following table lists all the payload types that can be nested inside a _Transaction Essence_ as well as links to the corresponding specification: -| Name | Type Value | TIP | -|-------------|------------|------------------------------------------------------------| -| Tagged Data | 5 | [draft TIP-23](https://github.com/iotaledger/tips/pull/54) | +| Name | Type Value | TIP | +|-------------|------------|-----------------------------------| +| Tagged Data | 5 | [TIP-23](../TIP-0023/tip-0023.md) | ### Unlocks From 7d4e9dcc385f1964fa6eb6dae5b4f79bbedb50f3 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 21 Jul 2022 16:00:39 +0200 Subject: [PATCH 26/40] replace Generic Payload with supported payload(s) --- tips/TIP-0020/tip-0020.md | 23 ++--------------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index b9efda6e5..6fee70cc0 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -193,29 +193,10 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Payload optOneOf

- Generic Payload + Tagged Data Payload
- An outline of a generic payload. + Describes data with optional tag, defined in TIP-23.
- - - - - - - - - - - - - - - - -
NameTypeDescription
Payload Typeuint32 - The type of the payload. It will instruct the node how to parse the fields that follow. -
Data FieldsANYA sequence of fields, where the structure depends on Payload Type.
From b0c4c489540da48a33550fb4d44ddef6fb375b8a Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 21 Jul 2022 16:01:06 +0200 Subject: [PATCH 27/40] Update drawbacks and rationale --- tips/TIP-0020/tip-0020.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 6fee70cc0..1f246a6e0 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -473,13 +473,15 @@ In essence, Ed25519 support allows for smaller transaction sizes and to safely s # 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. +* It is not possible to produce a valid transaction without having access to the content of the consumed outputs. # 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 TIP 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. +* _Inputs Commitment_ and _Network ID_ are both explicit fields of the transaction, while they could be made configuration + parameters for the signature generating process. In this scenario the signature would be invalid if the parameters on client + and network side mismatch. While this would reduce the size of a transaction, it would make it impossible to debug the + reason for having an invalid signature and transaction. With the current solution we intend to optimize for ease of development. +* Uniqueness of all inputs is kept as it prevents introducing double spends in the same transaction. # Copyright From 42c57a0c412041b76b0f13d2566873bb3af0a08a Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 21 Jul 2022 16:03:22 +0200 Subject: [PATCH 28/40] Fix links --- tips/TIP-0020/tip-0020.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 1f246a6e0..64bbd2dc8 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -8,8 +8,8 @@ status: Draft type: Standards layer: Core created: 2021-11-18 -requires: [TIP-18](../TIP-0018/tip-0018.md) -replaces: [TIP-7](../TIP-0007/tip-0007.md) +requires: 18 +replaces: 7 --- # Summary From 07d56b8cb63a067d9af6d38d2f549907b6e9f3ef Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Thu, 21 Jul 2022 16:05:29 +0200 Subject: [PATCH 29/40] Fix table --- tips/TIP-0020/tip-0020.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 64bbd2dc8..d9a159607 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -198,6 +198,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Describes data with optional tag, defined in TIP-23.
+
From 267b0335dcb7b0fb76d927079f2bdd560638732e Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 9 Aug 2022 14:32:30 +0200 Subject: [PATCH 30/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Thoralf-M <46689931+Thoralf-M@users.noreply.github.com> --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index d9a159607..4b2ed3668 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -100,7 +100,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Network ID uint64 - The unique value denoting whether the block was meant for mainnet, shimmer, testnet, or a private networks. + The unique value denoting whether the block was meant for mainnet, shimmer, testnet, or a private network. It consists of the first 8 bytes of the BLAKE2b-256 hash of the network name. From 2fedc5b6cac1b7f91f6afa2ae86d98f72e2fee4b Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:41:37 +0200 Subject: [PATCH 31/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 4b2ed3668..478051769 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -24,7 +24,7 @@ transaction model of the UTXO ledger to: - include a _Network ID_ field in the transaction for replay protection, - introduce _Inputs Commitment_ field to prevent client [eclipse attacks that would result in loss of funds,](https://github.com/iotaledger/tips/discussions/51) - relax syntactic validation rules such that inputs and outputs of a transaction are no longer lexicographically ordered, furthermore - outputs don't have to be unique. + outputs do not have to be unique. The motivation for such changes is to provide a more flexible and secure framework for wallets and layer 2 applications. Chrysalis focused solely on using the ledger as a payment application, while Stardust transforms the ledger into a settlement layer From adfa65634115720dfe12dfd636885e857fb90e6c Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:41:57 +0200 Subject: [PATCH 32/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 478051769..d8cf2e83e 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -60,7 +60,7 @@ The serialized form of the transaction is deterministic, meaning the same logica The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized payload data including unlocks. -The following table describes the entirety of a _Transaction Payload_ in its serialized form following the notation from [draft TIP-21](https://github.com/iotaledger/tips/pull/41): +The following table describes the entirety of a _Transaction Payload_ in its serialized form following the notation from [TIP-21](../TIP-0021/tip-0021.md): From a2015d9d8a4d35fe4d841b0846de48b8fc6e6c62 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:42:14 +0200 Subject: [PATCH 33/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index d8cf2e83e..5f0f42b35 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -126,7 +126,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser From ae21906b02b7a292d997d6edcdb1dbeac6b7149e Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:43:48 +0200 Subject: [PATCH 34/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 5f0f42b35..7befb3d26 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -147,7 +147,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser From fffbdef52ef3ffde343a78eec64e9f167bd4d134 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:43:57 +0200 Subject: [PATCH 35/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 7befb3d26..42969c315 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -256,7 +256,9 @@ A UTXO Input is an input which references an unspent output of a previous #### Inputs Commitment -The _Inputs Commitment_ field of the _Transaction Essence_ is a cryptographic commitment to the content of the consumed outputs (inputs). The transaction itself only references inputs by _Output ID_, therefore the client has to be aware of the content to produce a semantically valid transaction. The commitment is a security mechanism that protects clients against [eclipse attacks that would result in loss of funds.](https://github.com/iotaledger/tips/discussions/51) +The `Inputs Commitment` field of the _Transaction Essence_ is a cryptographic commitment to the content of the consumed outputs (inputs). It consists of the BLAKE2b-256 hash of the concatenated output hashes. + +In the `Inputs` field, they are only referenced by _Output ID_. While the _Output ID_ technically depends on the content of the actual output, a client has no way of validating this without access to the original transaction. For the `Inputs Commitment`, the client has to be aware of the outputs’ content in order to produce a semantically valid transaction. This protects clients against [eclipse attacks that would result in loss of funds](https://github.com/iotaledger/tips/discussions/51). #### Outputs From d3e5d5e70407ab1b0ab56cd0f0e28738aa33a5c9 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:44:19 +0200 Subject: [PATCH 36/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 42969c315..292305b10 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -268,7 +268,7 @@ The following table lists all the output types that are currently supported as w | Output Name | Type Value | TIP | | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------ | -| Basic | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#basic-output) | +| Basic | 3 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#basic-output) | | Alias | 4 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#alias-output) | | Foundry | 5 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#foundry-output) | | NFT | 6 | [draft TIP-18](https://github.com/lzpap/protocol-rfcs/blob/master/tips/TIP-0018/tip-0018.md#nft-output) | From d10d3e5910fc5c5eaa0a4cb817224cbfa82b38c3 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:45:06 +0200 Subject: [PATCH 37/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 292305b10..4f41e94c3 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -264,7 +264,7 @@ In the `Inputs` field, they are only referenced by _Output ID_. While the _Outp The `Outputs` field holds the outputs that are created by the Transaction Payload. There are different output types, but they must all have an `Amount` field denoting the number of IOTA coins to deposit. -The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanceOutput_ introduced in Chrysalis Phase 2 [TIP-7](https://github.com/iotaledger/tips/blob/main/tips/TIP-0007/tip-0007.md) have been removed and are no longer supported. +The following table lists all the output types that are currently supported as well as links to the corresponding specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanceOutput_ introduced in Chrysalis Phase 2 [TIP-7](../TIP-0007/tip-0007.md) have been removed and are no longer supported. | Output Name | Type Value | TIP | | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------ | From 95221fd850158897eb5455a8595a115067b81e37 Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:45:34 +0200 Subject: [PATCH 38/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 4f41e94c3..e61f33246 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -275,7 +275,7 @@ The following table lists all the output types that are currently supported as w #### Payload -The _Transaction Essence_ itself can contain another payload as described in general in [draft TIP-24](https://github.com/iotaledger/tips/pull/55). The [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ does not have any impact on the payload. +The _Transaction Essence_ itself can contain another payload as described in general in [TIP-24](../TIP-0024/tip-004.md). The [semantic validity](#semantic-validation) 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: From 0f42971f39713149498cac00dc520d00f8a58f2b Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:46:49 +0200 Subject: [PATCH 39/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index e61f33246..0acb114e4 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -401,7 +401,7 @@ Syntactic validation is checked as soon as the transaction has been received. It The following criteria defines whether a payload passes the syntactical validation: * Essence: - * `Transaction Type` value must denote a _Transaction Essence_. + * `Transaction Type` value must denote a _TIP-20 Transaction Essence_. * `Network ID` must match the value of the current network. * Inputs: * `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. From ffe0a19ecff9447ae50997e73675fe4557d1fada Mon Sep 17 00:00:00 2001 From: Levente Pap Date: Tue, 30 Aug 2022 10:51:49 +0200 Subject: [PATCH 40/40] Update tips/TIP-0020/tip-0020.md Co-authored-by: Wolfgang Welz --- tips/TIP-0020/tip-0020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0020/tip-0020.md b/tips/TIP-0020/tip-0020.md index 0acb114e4..d9ba32282 100644 --- a/tips/TIP-0020/tip-0020.md +++ b/tips/TIP-0020/tip-0020.md @@ -434,7 +434,7 @@ Processing transactions according to the White-Flag ordering enables users to sp 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. -* `Inputs Commitment` must be equal to the BLAKE2b-256 hash of the BLAKE2b-256 hashes of the serialized outputs that are referenced as inputs. The order of the serialized outputs must be the same as their order in `Inputs`. +* `Inputs Commitment` must equal BLAKE2( BLAKE2(O1) || … || BLAKE2(On) ), where O1, ..., On are the complete serialized outputs referenced by the `Inputs` field in that order. * The transaction must spend the entire coin 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. * The sum of all `Native Token Counts` in the UTXOs referenced by inputs plus the sum of all `Native Token Counts` in the outputs must not be larger than `Max Native Token Count`. * The transaction is balanced in terms of native tokens, when the amount of native tokens present in all the UTXOs referenced by inputs equals to that of outputs. When the transaction is imbalanced, it must hold true that when there is a **surplus of native tokens** on the:
Input Type uint8 - Set to value 0 to denote an UTXO Input. + Set to value 0 to denote an TIP-20 UTXO Input.
Inputs Commitment ByteArray[32] - BLAKE2b-256 hash of the BLAKE2b-256 hashes of the serialized outputs referenced in Inputs by their Output IDs (Transaction ID || Transaction Output Index). + BLAKE2b-256 hash serving as a commitment to the serialized outputs referenced by Inputs.