From 4ae35fc33fa2747ee5e18cc2fe922062667b8c59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daria=20Dziuba=C5=82towska?= Date: Mon, 8 May 2023 11:37:30 +0200 Subject: [PATCH 001/122] Add TX TIP layout with updated motivation --- tips/TIP-0045/tip-0045.md | 504 ++++++++++++++++++++++++++++++++++++++ tips/TIP-0045/utxo.png | Bin 0 -> 66064 bytes 2 files changed, 504 insertions(+) create mode 100644 tips/TIP-0045/tip-0045.md create mode 100644 tips/TIP-0045/utxo.png diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md new file mode 100644 index 000000000..b5a70b250 --- /dev/null +++ b/tips/TIP-0045/tip-0045.md @@ -0,0 +1,504 @@ +--- +tip: 45 +title: Transaction Payload with IOTA 2.0 Output Types +description: Add output types, unlocks, and output features from TIP-38 into updated Transaction Payload +author: TODO +discussions-to: TODO +status: draft +type: Standards +layer: Core +created: 2021-11-18 +requires: 38, 39, 41, 42, 43, 44 +replaces: 20 +--- + +# Summary + +This TIP proposes a new 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-46](../TIP-0046/tip-0046.md) and extends the transaction payload described in [TIP-20](../TIP-0007/tip-0020.md). + +# Motivation + +[TIP-20](../TIP-0020/tip-0020.md) describes the introduction of new extended transaction model for the Stardust update This TIP extends the +be aligned with all new mana and accounts features: +- accommodate for the new output types introduced in [TIP-38](../TIP-0038/tip-0038.md), [TIP-39](../TIP-0039/tip-0039.md), [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). +- include a _AllottedAccounts_ field in the transaction for mana allotment of Block Issuer Credits, +- Updates the syntactic validation rules for assuring the correctness of input and output balances accordingly to IOTA 2.0 mana changes. + +The motivation of such changes is to adjust the transaction and its validation rules with upcoming protocol upgrade to IOTA 2.0 v1.2.0. +Validation rules must now consider mana decay factor and possibility of mana allotment in the transaction to a Block Issuer Credits account. + + +# 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*. 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: + +![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 _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](../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. + +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): + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Payload Typeuint32 + Set to value 6 to denote a TIP-20 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 1 to denote a TIP-20 Transaction Essence. +
Network IDuint64 + 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. +
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 TIP-20 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.
+
+
Inputs CommitmentByteArray[32] + BLAKE2b-256 hash serving as a commitment to the serialized outputs referenced by Inputs. +
Outputs Countuint16The number of output entries.
Outputs anyOf +
+ Basic Output +
+ Describes a deposit to a single address. The output might contain optional features 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 +
+ Tagged Data Payload +
+ Describes data with optional tag, defined in TIP-23. +
+
+
+
+
Unlocks Countuint16The number of unlock entries. It must match the field Inputs Count.
Unlocks anyOf +
+ Signature Unlock +
+ Defines an unlock containing a signature. +
+
+
+ Reference Unlock +
+ References a previous unlock, where the same unlock can be used for multiple inputs. +
+
+
+ Alias Unlock +
+ References a previous unlock of a consumed alias output. +
+
+
+ NFT Unlock +
+ References a previous unlock 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 1 for TIP-20 Transaction Essence. + +#### Network ID + +The `Network ID` field of the transaction essence serves as a [replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). +It is a unique value denoting whether the transaction was meant for the IOTA mainnet, shimmer, testnet-1, or a private network. It consists of the first 8 bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as an unsigned integer number. + +| Network Name | Resulting `Network ID` | Network Name defined in | +|---------------------|------------------------|-----------------------------------------------------| +| `iota-mainnet` | `9374574019616453254` | [TIP-22](../TIP-0022/tip-0022.md#detailed-design) | +| `shimmer` | `14364762045254553490` | [TIP-32](../TIP-0032/tip-0032.md#global-parameters) | +| `testnet-1` | `1856588631910923207` | - | +| `example-mynetwork` | `1967754805504104511` | - | + +#### 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 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 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). 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 + +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](../TIP-0007/tip-0007.md) have been removed and are no longer supported. + +| Output Name | Type Value | TIP | +|-------------|------------|--------------------------------------------------| +| Basic | 3 | [TIP-18](../TIP-0018/tip-0018.md#basic-output) | +| Alias | 4 | [TIP-18](../TIP-0018/tip-0018.md#alias-output) | +| Foundry | 5 | [TIP-18](../TIP-0018/tip-0018.md#foundry-output) | +| NFT | 6 | [TIP-18](../TIP-0018/tip-0018.md#nft-output) | + +#### Payload + +The _Transaction Essence_ itself can contain another payload as described in general in [TIP-24](../TIP-0024/tip-0024.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 | +|-------------|------------|-----------------------------------| +| Tagged Data | 5 | [TIP-23](../TIP-0023/tip-0023.md) | + +### Unlocks + +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_ and the _Reference Unlock_ are specified as part of this TIP. + +| Unlock Name | Type Value | TIP | +|-------------|------------|------------------------------------------------------------| +| Signature | 0 | [TIP-20](#signature-unlock) | +| Reference | 1 | [TIP-20](#reference-unlock) | +| Alias | 2 | [TIP-18](../TIP-0018/tip-0018.md#alias-locking--unlocking) | +| NFT | 3 | [TIP-18](../TIP-0018/tip-0018.md#nft-locking--unlocking) | + +#### Signature Unlock + +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: + + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 0 to denote a Signature Unlock. +
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_ 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 + +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: + + + + + + + + + + + + + + + + + +
NameTypeDescription
Unlock Typeuint8 + Set to value 1 to denote a Reference Unlock. +
Referenceuint16Represents the index of a previous unlock.
+ +##### Unlock syntactic validation + +* 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 Unlocks part: + +| Index | Unlock | +|-------|------------------------------------------------------------------------------------| +| 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 features introduced by [TIP-18](../TIP-0018/tip-0018.md) 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](../TIP-0018/tip-0018.md#output-design) and [feature type](../TIP-0018/tip-0018.md#features) separately. + +### Syntactic validation + +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: + +* 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`. + * 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 output 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`. + * The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. + * Payload (if present): + * `Payload Type` must match one of the values described under [Payload](#payload). + * 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_. + * 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 + +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 _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. +* `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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is counted as one. +* 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 features](../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 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, + * 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_, 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_ 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_ 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)). + +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-8](../TIP-0008/tip-0008.md)) is used. + +### 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. +* It is not possible to produce a valid transaction without having access to the content of the consumed outputs. + +# Rationale and alternatives + +* _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 + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + diff --git a/tips/TIP-0045/utxo.png b/tips/TIP-0045/utxo.png new file mode 100644 index 0000000000000000000000000000000000000000..b29177df2139d3a254de7d3c03a746e3d8787dfb GIT binary patch literal 66064 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�AU^LAq{z-z*! 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 D7a`vM literal 0 HcmV?d00001 From 3bec6cf7e2c6015ab936a6455ed8033e43e0ca77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daria=20Dziuba=C5=82towska?= Date: Mon, 8 May 2023 12:20:47 +0200 Subject: [PATCH 002/122] Extend tx payload with allottedAccounts --- tips/TIP-0045/tip-0045.md | 76 ++++++++++++++++++++++++++++----------- 1 file changed, 55 insertions(+), 21 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index b5a70b250..a7b59a90f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -21,7 +21,7 @@ This TIP proposes a new UTXO-based transaction structure consisting of all the i [TIP-20](../TIP-0020/tip-0020.md) describes the introduction of new extended transaction model for the Stardust update This TIP extends the be aligned with all new mana and accounts features: - accommodate for the new output types introduced in [TIP-38](../TIP-0038/tip-0038.md), [TIP-39](../TIP-0039/tip-0039.md), [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). -- include a _AllottedAccounts_ field in the transaction for mana allotment of Block Issuer Credits, +- include a _AccountsAllotments_ field in the transaction for mana allotment of Block Issuer Credits, - Updates the syntactic validation rules for assuring the correctness of input and output balances accordingly to IOTA 2.0 mana changes. The motivation of such changes is to adjust the transaction and its validation rules with upcoming protocol upgrade to IOTA 2.0 v1.2.0. @@ -54,7 +54,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](../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. 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. @@ -70,11 +70,12 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Payload Type uint32 - Set to value 6 to denote a TIP-20 Transaction Payload. + TODO value ?? + Set to value 6 to denote a TIP-45 Transaction Payload. - Essence oneOf + Essence oneOf
Transaction Essence @@ -107,7 +108,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser The number of input entries. - Inputs anyOf + Inputs anyOf
UTXO Input @@ -154,7 +155,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser The number of output entries. - Outputs anyOf + Outputs anyOf
Basic Output @@ -163,9 +164,9 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
- Alias Output + Account Output
- Describes an alias account in the ledger. + Describes an account in the ledger.
@@ -182,13 +183,46 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
+ + Allotments Count + uint16 + The number of account allotment entries. + + + AccountsAllotments optAnyOf + +
+ Parent +
+ Allots mana value to indicated account. +
+ + + + + + + + + + + + + + + + +
NameTypeDescription
Account IDByteArray[32]The Account ID of the parent.
Valueuint64 Allotted mana value.
+
+ + Payload Length uint32 The length in bytes of the optional payload. - Payload optOneOf + Payload optOneOf
Tagged Data Payload @@ -223,9 +257,9 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
- Alias Unlock + Account Unlock
- References a previous unlock of a consumed alias output. + References a previous unlock of a consumed account output.
@@ -278,10 +312,10 @@ The following table lists all the output types that are currently supported as w | Output Name | Type Value | TIP | |-------------|------------|--------------------------------------------------| -| Basic | 3 | [TIP-18](../TIP-0018/tip-0018.md#basic-output) | -| Alias | 4 | [TIP-18](../TIP-0018/tip-0018.md#alias-output) | -| Foundry | 5 | [TIP-18](../TIP-0018/tip-0018.md#foundry-output) | -| NFT | 6 | [TIP-18](../TIP-0018/tip-0018.md#nft-output) | +| Basic | 3 | [TIP-41](../TIP-0041/tip-0041.md#basic-output) | +| Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | +| Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | +| NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | #### Payload @@ -299,12 +333,12 @@ The `Unlocks` field holds the unlocks unlocking inputs within a _Transaction Ess 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 | -|-------------|------------|------------------------------------------------------------| -| Signature | 0 | [TIP-20](#signature-unlock) | -| Reference | 1 | [TIP-20](#reference-unlock) | -| Alias | 2 | [TIP-18](../TIP-0018/tip-0018.md#alias-locking--unlocking) | -| NFT | 3 | [TIP-18](../TIP-0018/tip-0018.md#nft-locking--unlocking) | +| Unlock Name | Type Value | TIP | +|-------------|------------|--------------------------------------------------------------| +| Signature | 0 | [TIP-38](#signature-unlock) | +| Reference | 1 | [TIP-38](#reference-unlock) | +| Account | 2 | [TIP-18](../TIP-0042/tip-0042.md#account-locking--unlocking) | +| NFT | 3 | [TIP-43](../TIP-0043/tip-0043.md#nft-locking--unlocking) | #### Signature Unlock From cfbe787ed4436a1b82de9b393d0c11262030067a Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 12 May 2023 13:56:40 +0200 Subject: [PATCH 003/122] Adapt TIP-47 from TIP-19 --- .../assets/microtransactions_pt3_layer1.png | Bin 0 -> 151403 bytes .../assets/microtransactions_pt3_layer2.png | Bin 0 -> 135355 bytes tips/TIP-0047/tip-0047.md | 145 ++++++++++++++++++ 3 files changed, 145 insertions(+) create mode 100644 tips/TIP-0047/assets/microtransactions_pt3_layer1.png create mode 100644 tips/TIP-0047/assets/microtransactions_pt3_layer2.png create mode 100644 tips/TIP-0047/tip-0047.md diff --git a/tips/TIP-0047/assets/microtransactions_pt3_layer1.png b/tips/TIP-0047/assets/microtransactions_pt3_layer1.png new file mode 100644 index 0000000000000000000000000000000000000000..561db0bb10b06d55b8b34ad89ce27f95c5f45c22 GIT binary patch literal 151403 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
    0bU6`jY&V0Bfv!nW;`K!e*PYS%T;eKcRFCFJo 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 X;=Oo!w%qtV@SmEJCN@vO#P9zAY}gb> literal 0 HcmV?d00001 diff --git a/tips/TIP-0047/assets/microtransactions_pt3_layer2.png b/tips/TIP-0047/assets/microtransactions_pt3_layer2.png new file mode 100644 index 0000000000000000000000000000000000000000..67a46901dc89a453ddbd72cf8006a417f9097760 GIT binary patch literal 135355 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
    @GVI=78mTm?pJw;^-E|@&`a*Z@W2#uA( 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
    B*EQRjTbEL+idRQV9=N%hbD#_oNTh1~ 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 +discussions-to: TODO +status: Draft +type: Standards +layer: Core +created: 2023-05-12 +requires: TIP-20, TIP-21, TIP-22 and TIP-38 +replaces: TIP-19 +--- + +## Summary + +This document describes a `dust protection` concept, called `storage deposit` which was originally introduced in TIP-19. This cocnept creates a monetary incentive to keep the ledger state small. This is achieved by enforcing a minimum IOTA coin deposit in every output based on the actually used disc space of the output itself. + +This document minimally extends on TIP-19 by allowing for additional weights to be defined in other TIPs and no longer includes the deposit calculation for each individual output. Instead, each TIP defining outputs has to include the deposit calculation. + +## Motivation + +In a distributed ledger network, every participant, a so-called node, needs to keep track of the current ledger state. Since `chrysalis-pt2`, the IOTA ledger state is based on the UTXO model, where every node keeps track of all the currently unspent outputs. + +Misusage by honest users or intentionally bad behavior by malicious actors can lead to growing database and snapshot sizes and increasing computational costs (database lookups, balance calculations). Due to these increasing hardware requirements, the entry barrier to participate in the network becomes unaffordable and less nodes would operate the network. + +Especially in a fee-less system like IOTA, this is a serious issue, since an attacker can create a lot of damage with low effort. Other DLTs do not yet face this problem, as such an attack would be much more expensive due to the high transaction fees. +However, in order to solve scalability issues more and more transactions need to be handled. Therefore, other DLT projects will also eventually run into the same dust limitations. This document proposes to introduce `storage deposit` to address this. + +## Requirements + +- The maximum possible ledger database size must be limited to a reasonable and manageable size. +- The `dust protection` must not depend on a global shared state of the ledger, so that transaction validation can happen in parallel. +- The `dust protection` should work for outputs with arbitrary data and size. +- The ledger database size should be fairly allocated to users based on the scarce resource, IOTA coins. + +## Detailed Design + +A transaction validation rule is introduced which is exactly the same as the one defined in TIP-19, but stated here again for self-containment. + +Blocks including payloads, even transaction payloads, are considered to be pruned by the nodes, but unspent transaction outputs must be kept until they are spent. Therefore the `dust protection` is based on the unspent outputs only. + +**Every output created by a transaction needs to have at least a minimum amount of IOTA coins deposited in the output itself, otherwise the output is syntactically invalid.** + +min_deposit_of_output = ⌊v_byte_cost · v_byte⌋ +v_byte = ∑(weight𝑖 · byte_size𝑖) + offset + +where: +- v_byte_cost: costs in IOTA coins per virtual byte +- weight𝑖: factor of field 𝑖 that takes computational and storage costs into account +- byte_size𝑖: size of field 𝑖 in bytes +- offset: additional v_bytes that are caused by additional data that has to be stored in the database but is not part of the output itself + +| :warning: `min_deposit_of_output` is rounded down | +| ------------------------------------------------- | + +TIP-18 and its replacement TIPs introduce new output types that contain mandatory and optional fields with variable length. Each of these fields result in different computational and storage costs, which will be considered by the positive `weight_i`. The size of the field itself is expressed with `byte_size_i`. `offset` is used to take the overhead of the specific output itself into account. + +The `v_byte_cost` is a protocol value, which has to be defined based on reasonable calculations and estimates. + +**In simple words, the more data you write to the global ledger database, the more IOTA you need to deposit in the output.** +This is not a fee, because the deposited coins can be reclaimed by consuming the output in a new transaction. + +### How does it affect other parts of the protocol? + +The `dust protection` only affects "value-transactions". Since blocks containing other payloads are not stored in the ledger state and are subject to pruning, they cannot cause permanent "dust" and do not need to be considered for `dust protection`. +However, all output types like e.g. smart contract requests are affected and must comply with the `min_deposit_of_output` criteria. Therefore, these requests could get quite expensive for the user, but the same mechanism introduced for [Microtransactions on Layer 1](#Microtransactions-on-Layer-1) can be utilized for smart contract requests as well. + +### Byte cost calculations + +To limit the maximum database size, the total IOTA supply needs to be divided by the target database size in bytes to get the worst case scenario regarding the byte costs. + +However, in this scenario no outputs hold more IOTA coins than required for the `dust protection`. This does not represent the real distribution of funds over the UTXOs. We could assume that these output amounts follow Zipf's law. Unfortunately, fitting a Zipf distribution to the current ledger state will not match the future distribution of the funds for several reasons: + +- There is already another `dust protection` in place, which distorts the distribution. +- With new use cases enabled by the new `dust protection` (e.g. tokenization, storing arbitrary data in the ledger), the distribution will dramatically change. +- Fittings for other DLT projects do not match because there are transaction fees in place, which decrease the amount of dust outputs in the distribution. + +Another possibility would be to estimate how much percentage of the database will be used for outputs with minimum required deposit (`fund sparsitiy percentage`) in the future. The remaining IOTA coins can be ignored in that case to simplify the calculation. Since a fund sparsity percentage of less than 20% would already be bad for other upcoming protocol features like the mana calculation, we could take this value for our calculation instead of the worst case. + +### Weights for different outputs + +Output types contain several mandatory and optional fields. Every field itself creates individual computational and storage requirements for the node, which is considered by having different weights for every field. + +##### Field types + +The following table describes different field types in an output: + + + + + + + + + + + + + + + + + + + + +
    NameDescriptionWeightReasoning
    keyCreates a key lookup in the database.10.0Keys need to be stored in the LSM tree of the key-value database engine and need to be merged and leveled, which is computational-, memory- and read/write IO-wise a heavy task.
    dataPlain binary data on disk.1.0Data is stored as the value in the key-value database, and therefore only consumes disc space.
    + +TIPs that define new output types may define additional weights based on the storage and computational requirements that the affected fields induce for the node. However, the weights defined here should take precedence whenever possible and inform the newly defined weights. + +| :warning: Protocol parameters are not set yet | +| ---------------------------------------------- | + +Protocol parameters presented in this document are design parameters that will change in the future based on simulation results, benchmarking and security assumptions. The reader should not take these values as definitive. + +An example of such parameter for example is the `weight` assigned to different output field types. + +### Microtransactions + +#### Microtransactions on Layer 1 + +To enable microtransactions on Layer 1 and still satisfy the `min_deposit_of_output` requirement, a new mechanism called `conditional sending` is introduced with [TIP-38](../TIP-0038/tip-0038.md). + +![Microtransactions on Layer 1](assets/microtransactions_pt3_layer1.png) + +The preceding picture shows the process of the `conditional sending` mechanism. Alice uses the `Basic Output` ([TIP-41](../TIP-0041/tip-0041.md)) to send a microtransaction of 1 IOTA to Bob's `Address`. To fulfill the `min_deposit_of_output` requirement, the `Amount` is increased by `min_deposit_of_output` IOTA, which is 1 MIOTA in the above example. To prevent Bob from accessing these additional funds called the `storage deposit`, Alice adds the optional `Storage Deposit Return Unlock Condition` to the `Basic Output`. Now Bob can only consume the newly created output, if the unlocking transaction deposits the specified `Return Amount` IOTA coins, in this case 1 MIOTA, to the `Return Address` value defined by Alice. By consuming another UTXO and adding its amount to the received 1 IOTA, Bob takes care to create a valid output according to the dust protection rules. + +To prevent Bob from blocking access to the `storage deposit` forever, Alice specifies the additional `Expiration Unlock Condition` in the `Basic Output`. If Bob does not consume the output before the time window defined by Alice expires, Alice regains total control over the output. + +This means that there is no risk for Alice to lose the `storage deposit`, because either Bob needs to return the specified `Return Amount`, or the ownership of the created output switches back to Alice after the specified time-window has expired. + +This mechanism can also be used to transfer native tokens or on-chain requests to ISCP chains without losing control over the required `storage deposit`. + +#### Microtransactions on Layer 2 + +Another solution is to outsource microtransactions to Layer 2 applications like smart contracts. In Layer 2 there are no restrictions regarding the minimum balance of an output. + +![Microtransactions on Layer 2](assets/microtransactions_pt3_layer2.png) + +In this example, Alice sends funds to a smart contract chain on Layer 1 with an output that covers at least `min_deposit_of_output`. From this point on, Alice can send any number of off-chain requests to the smart contract chain, causing the smart contract to send microtransactions from Alice' on-chain account to Bob's on-chain account. Bob can now request his on-chain account balances to be withdrawn to his Layer 1 address. The last step can also be combined with the formerly introduced `conditional sending` mechanism, in case Bob wants to withdraw less than `min_deposit_of_output` IOTA coins or native assets. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 54d3faa1563cd1a0e12da1544ec86309f353a8ff Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 16 May 2023 09:32:29 +0200 Subject: [PATCH 004/122] Replace TIP-19, add TIP-47 in Readme --- README.md | 1 + tips/TIP-0019/tip-0019.md | 1 + tips/TIP-0047/tip-0047.md | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b1da09f1d..fd4f081c3 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,7 @@ more improvements. Browse the [list of TIPs](#list-of-tips) below with the _Star | 34 | [Wotsicide (Stardust update)](tips/TIP-0034/tip-0034.md) | Define migration from legacy W-OTS addresses to post-Chrysalis networks. Replaces TIP-17. | Standards | Core | Proposed | **Stardust** | | 35 | [Local Snapshot File Format (Stardust Update)](tips/TIP-0035/tip-0035.md) | File format to export/import ledger state. Replaces TIP-9. | Standards | Interface | Proposed | **Stardust** | | 37 | [Dynamic Proof-of-Work](https://github.com/iotaledger/tips/pull/81) | Dynamically adapt the PoW difficulty | Standards | Core | Draft | **Stardust** | +| 47 | [Storage Deposit Dust Protection (IOTA 2.0)](tips/TIP-0047/tip-0047.md) | Prevent bloating the ledger size with dust outputs | Standards | Core | Draft | **IOTA 2.0** | ## Need help? diff --git a/tips/TIP-0019/tip-0019.md b/tips/TIP-0019/tip-0019.md index a63145875..91dfb1058 100644 --- a/tips/TIP-0019/tip-0019.md +++ b/tips/TIP-0019/tip-0019.md @@ -10,6 +10,7 @@ layer: Core created: 2021-11-04 requires: TIP-18, TIP-20, TIP-21 and TIP-22 replaces: TIP-15 +superseded-by: TIP-47 --- ## Summary diff --git a/tips/TIP-0047/tip-0047.md b/tips/TIP-0047/tip-0047.md index 70410a6f6..db76ef3f2 100644 --- a/tips/TIP-0047/tip-0047.md +++ b/tips/TIP-0047/tip-0047.md @@ -1,6 +1,6 @@ --- tip: 47 -title: Dust Protection Based on Byte Costs (Storage Deposit) +title: Storage Deposit Dust Protection (IOTA 2.0) description: Prevent bloating the ledger size with dust outputs author: Max Hase (@muXxer) discussions-to: TODO From d07c4ffc137f83a4cee3cb29f41a484dc929c0c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daria=20Dziuba=C5=82towska?= Date: Thu, 18 May 2023 11:16:12 +0200 Subject: [PATCH 005/122] Rename allotments --- tips/TIP-0045/tip-0045.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index a7b59a90f..630821e49 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -21,7 +21,7 @@ This TIP proposes a new UTXO-based transaction structure consisting of all the i [TIP-20](../TIP-0020/tip-0020.md) describes the introduction of new extended transaction model for the Stardust update This TIP extends the be aligned with all new mana and accounts features: - accommodate for the new output types introduced in [TIP-38](../TIP-0038/tip-0038.md), [TIP-39](../TIP-0039/tip-0039.md), [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). -- include a _AccountsAllotments_ field in the transaction for mana allotment of Block Issuer Credits, +- include a _Allotments_ field in the transaction for mana allotment of Block Issuer Credits, - Updates the syntactic validation rules for assuring the correctness of input and output balances accordingly to IOTA 2.0 mana changes. The motivation of such changes is to adjust the transaction and its validation rules with upcoming protocol upgrade to IOTA 2.0 v1.2.0. @@ -60,6 +60,8 @@ The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rf 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): +TODO what about inputs committments? + @@ -189,10 +191,10 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - + - + - + - +
    NameThe number of account allotment entries.
    AccountsAllotments optAnyOfAllotments optAnyOf
    - Parent + Allotment
    Allots mana value to indicated account.
    From fa28fcface6936f450e1c6b08f37de880d265208 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daria=20Dziuba=C5=82towska?= Date: Tue, 30 May 2023 09:58:50 +0200 Subject: [PATCH 006/122] Further tip adjustments --- tips/TIP-0045/tip-0045.md | 74 +++++++++++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 14 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 630821e49..7f1815238 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -292,7 +292,11 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai #### 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` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are three types of input: + - _UTXO Input_ + - _Commitment Input_ + - _Block Issuance Credits 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 at the same index in the Unlocks part of the Transaction Payload. @@ -300,6 +304,13 @@ 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. +##### Commitment Input +A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node. It is used to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. + + +##### Block Issuance Credits Input +A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for destroying an _Account Output_, as it can be allowed only if the BIC balance is not negative at specific point in time. + #### Inputs Commitment 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. @@ -321,7 +332,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 [TIP-24](../TIP-0024/tip-0024.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 [TIP-46](../TIP-0024/tip-0046.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: @@ -360,7 +371,7 @@ The Signature Unlock defines an Unlock which holds a signature sig
    Signature oneOfSignature oneOf
    Ed25519 Signature @@ -439,7 +450,8 @@ 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 features introduced by [TIP-18](../TIP-0018/tip-0018.md) 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](../TIP-0018/tip-0018.md#output-design) and [feature type](../TIP-0018/tip-0018.md#features) separately. +The different output types and optional output features introduced by [TIP-38](../TIP-0038/tip-0038.md), [TIP-1](../TIP-0042/tip-0041.md),[TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md) and [TIP-44](../TIP-0044/tip-0044.md) +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](../TIP-0038/tip-0038.md#output-design) and [feature type](../TIP-0038/tip-0038.md#features) separately. ### Syntactic validation @@ -448,12 +460,12 @@ 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 _TIP-20 Transaction Essence_. + * `Transaction Type` value must denote a _TIP-45 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: - * `Input Type` must denote a _UTXO Input_. + * `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). * `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: @@ -462,6 +474,7 @@ The following criteria defines whether a payload passes the syntactical validati * `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`. + * The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. * The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. * Payload (if present): * `Payload Type` must match one of the values described under [Payload](#payload). @@ -476,22 +489,51 @@ 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 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). +The Semantic validation of a _Transaction Payload_ is performed when its encapsulating block is confirmed. The semantic validity of transactions depends on the partial order in which they are processed. The solidification mechanism of the protocol ensures that all inputs will be processed only when all inputs are known valid, and not conflicting. -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. +Processing transactions according to its partial-ordering enables users to spend UTXOs which are created at similar point in time, but the input transaction has not yet been confirmed by the network, as they will be processed by preserving thei input-output order relations. 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: +#### Criteria defining 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 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is counted as one. * 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 features](../TIP-0018/tip-0018.md#features) must pass semantic validation in the context of the following input: +* **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. + +**Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): + * The transaction must not spend more mana than allowed, briefly it must given following definitions: +- `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction timestamp, and decay function +- `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. +- `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` +- `outputStoredMana` sum of stored mana from outputs +comply that: +`potentialMana` + `inputStoredMana` >= `allottedMana` + `outputStoredMana` +The less or equal sign in the formula above implies that it is possible for a user not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, a user does not want to own Mana att all. Then, the user must be able to refuse to allot or store their potential Mana. +FMore specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following validation rule for Mana: + +```math +\sum_{i \in \mathcal{I}}\Big[\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big) + \text{Mana}_i * e^{-\beta(t - t_i)}\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, +``` +where: + +- $\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big)$ is the amount of potential Mana generated by consuming output `i`; +- $\text{Mana}_i * e^{-\beta(t - t_i)}$ is the amount of stored Mana on the consuming output `i` with applied decay; +- $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; +- $\text{Mana}_a$ is the amount of Mana transferred to account `a` as block issuance credit; +- $\text{IOTA}_i$ is the amount of IOTA tokens held in output `i`; +- $\beta$ is the global decay parameter for all kinds of Mana;; +- $t$ is the timestamp of the transaction (consuming unspent outputs $i \in \mathcal{I}$) being validated; +- $t_i$ is the timestamp of when output `i` was created; +- $\text{Mana}_i$ is the amount of stored Mana on output `i`; +- $\mathcal{O}$ is the set outputs to which Mana will be transferred as stored Mana; +- $\mathcal{A}$ is the set accounts to which Mana will be transferred as block issuance credit. + +#### Semantic criteria for each output and all its output features in the context of the following input: 1. The _Transaction Payload_, 2. the list of UTXOs referenced by inputs and - 3. the Unix timestamp of the confirming milestone. + 3. / TDOD how to change that?: 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, @@ -505,7 +547,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_ 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)). +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. 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. @@ -513,9 +555,13 @@ 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-8](../TIP-0008/tip-0008.md)) is used. +Since transaction timestamps – whether they are signed or not – do not provide accuracy guarantee, the time of the trnsaction is defined by the `slot index`, as no more detailed time granularity is needed. +The correctness of the timespams is indirectly restricted by the Fishing condition, which does not allowto reference blocks that are `Fishing threshold` older than latest confirmed block. This rule puts restrictions on the block timestamp. Which in turn, is used to validate the transaction creation slot: +* The transaction creation slot must be less than or equal to the current slot index, + * transaction slot must be less or equal to the encapsulation block timestamp. ### Address reuse +// todo is this valid? 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. From e1093305018541a2a0e5b11fea09352ca503c9c3 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 31 May 2023 20:37:11 +0200 Subject: [PATCH 007/122] Polish wording --- tips/TIP-0045/tip-0045.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 7f1815238..439b163f2 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -4,12 +4,12 @@ title: Transaction Payload with IOTA 2.0 Output Types description: Add output types, unlocks, and output features from TIP-38 into updated Transaction Payload author: TODO discussions-to: TODO -status: draft +status: Draft type: Standards layer: Core created: 2021-11-18 -requires: 38, 39, 41, 42, 43, 44 -replaces: 20 +requires: TIP-39, TIP-41, TIP-42, TIP-43 and TIP-44 +replaces: TIP-20 --- # Summary @@ -18,15 +18,13 @@ This TIP proposes a new UTXO-based transaction structure consisting of all the i # Motivation -[TIP-20](../TIP-0020/tip-0020.md) describes the introduction of new extended transaction model for the Stardust update This TIP extends the -be aligned with all new mana and accounts features: -- accommodate for the new output types introduced in [TIP-38](../TIP-0038/tip-0038.md), [TIP-39](../TIP-0039/tip-0039.md), [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). -- include a _Allotments_ field in the transaction for mana allotment of Block Issuer Credits, -- Updates the syntactic validation rules for assuring the correctness of input and output balances accordingly to IOTA 2.0 mana changes. - -The motivation of such changes is to adjust the transaction and its validation rules with upcoming protocol upgrade to IOTA 2.0 v1.2.0. -Validation rules must now consider mana decay factor and possibility of mana allotment in the transaction to a Block Issuer Credits account. +[TIP-20](../TIP-0020/tip-0020.md) introduced a new extended transaction model for the Stardust update. This TIP extends this model to be aligned with all new mana and account features: +- accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). +- include an _Allotments_ field in the transaction for mana allotment of Block Issuance Credits, +- updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA 2.0 mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). +The motivation of these changes is to adjust the transaction and its validation rules with the protocol upgrade to IOTA 2.0. +Validation rules must now consider the mana decay factor and the possibility of mana allotment in the transaction to a Block Issuance Credits account. # Detailed design @@ -210,9 +208,9 @@ TODO what about inputs committments?
    		The Account ID of the parent.
    ValueMana uint64 Allotted mana value.The amount of mana to allot to this account.
From 06eb01db8fdfe6d620ddb67ac9cdd1c1f077672f Mon Sep 17 00:00:00 2001 From: oliviasaa Date: Sun, 4 Jun 2023 16:53:01 +0100 Subject: [PATCH 008/122] Update tip-0045.md Updated decays --- tips/TIP-0045/tip-0045.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 439b163f2..49436eb03 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -512,19 +512,17 @@ The less or equal sign in the formula above implies that it is possible for a us FMore specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following validation rule for Mana: ```math -\sum_{i \in \mathcal{I}}\Big[\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big) + \text{Mana}_i * e^{-\beta(t - t_i)}\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, +\sum_{i \in \mathcal{I}}\Big[\text{IOTA}_i*f(t - t_i) + \text{Mana}_i * g(t - t_i)\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, ``` where: -- $\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big)$ is the amount of potential Mana generated by consuming output `i`; -- $\text{Mana}_i * e^{-\beta(t - t_i)}$ is the amount of stored Mana on the consuming output `i` with applied decay; +- $\text{IOTA}_i*f(t - t_i)$ is the amount of potential Mana generated by consuming output `i` ($\text{IOTA}_i$ is the amount of tokens in output `i`, and $f$ is given by the lookup table 1: Potential Mana generation in [TIP-39](../TIP-0039/tip-0039.md)); +- $\text{Mana}_i * g(t - t_i)$ is the amount of stored Mana on the consuming output `i` with applied decay ($\text{Mana}_i$ is the amount of stored Mana in output `i`, and $g$ is given by the lookup table 2: decays for Mana in [TIP-39](../TIP-0039/tip-0039.md)); - $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; - $\text{Mana}_a$ is the amount of Mana transferred to account `a` as block issuance credit; - $\text{IOTA}_i$ is the amount of IOTA tokens held in output `i`; -- $\beta$ is the global decay parameter for all kinds of Mana;; -- $t$ is the timestamp of the transaction (consuming unspent outputs $i \in \mathcal{I}$) being validated; -- $t_i$ is the timestamp of when output `i` was created; -- $\text{Mana}_i$ is the amount of stored Mana on output `i`; +- $n$ is the slot index of the transaction (consuming unspent outputs $i \in \mathcal{I}$) being validated; +- $n_i$ is the slot index of when output `i` was created; - $\mathcal{O}$ is the set outputs to which Mana will be transferred as stored Mana; - $\mathcal{A}$ is the set accounts to which Mana will be transferred as block issuance credit. From a24a35f106a6e6e9b853fe24727410248288320d Mon Sep 17 00:00:00 2001 From: oliviasaa Date: Sun, 4 Jun 2023 20:27:55 +0100 Subject: [PATCH 009/122] Update tip-0045.md Changed to a single lookup table --- tips/TIP-0045/tip-0045.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 49436eb03..c1fa78570 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -516,8 +516,8 @@ FMore specifically, for a transaction consuming a set of unspent outputs $\mathc ``` where: -- $\text{IOTA}_i*f(t - t_i)$ is the amount of potential Mana generated by consuming output `i` ($\text{IOTA}_i$ is the amount of tokens in output `i`, and $f$ is given by the lookup table 1: Potential Mana generation in [TIP-39](../TIP-0039/tip-0039.md)); -- $\text{Mana}_i * g(t - t_i)$ is the amount of stored Mana on the consuming output `i` with applied decay ($\text{Mana}_i$ is the amount of stored Mana in output `i`, and $g$ is given by the lookup table 2: decays for Mana in [TIP-39](../TIP-0039/tip-0039.md)); +- $\text{IOTA}_i*f(t - t_i)$ is the amount of potential Mana generated by consuming output `i` ($\text{IOTA}_i$ is the amount of tokens in output `i`, and $f$ is calculated with the aid of the Lookup Table: decays for Mana in [TIP-39](../TIP-0039/tip-0039.md)). More specifically, `f(n)` is an approximation of `Mana Generation * (1 - e^{-beta*SlotDuration*n})`, whereas the values stored in the lookup table are an approximation of `e^{-beta*SlotDuration*n}`. All the operations to calculate `f(n)` must be done using fixed point arithmetics. Example: if `Mana Generation = e^{-beta*SlotDuration*n}) = 0.1`, and `Amount = 1001`, the potential Mana must be calculated as `1001 * 1/10 * (1 - 1/10) = 1001 * 1/10 * 9/10 = (1001 * 1 * 9)/100 = 9009/100 = 90; +- $\text{Mana}_i * g(t - t_i)$ is the amount of stored Mana on the consuming output `i` with applied decay ($\text{Mana}_i$ is the amount of stored Mana in output `i`, and $g$ is given by the Lookup Table: decays for Mana in [TIP-39](../TIP-0039/tip-0039.md)); - $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; - $\text{Mana}_a$ is the amount of Mana transferred to account `a` as block issuance credit; - $\text{IOTA}_i$ is the amount of IOTA tokens held in output `i`; @@ -579,4 +579,3 @@ In essence, Ed25519 support allows for smaller transaction sizes and to safely s # Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). - From 9c9af7c3bb0c7abfe5aabc86aa1a48b6acc26780 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daria=20Dziuba=C5=82towska?= Date: Mon, 5 Jun 2023 14:00:48 +0200 Subject: [PATCH 010/122] Time and allotments description --- tips/TIP-0045/tip-0045.md | 54 +++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 22 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 439b163f2..4961c5472 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -58,8 +58,6 @@ The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rf 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): -TODO what about inputs committments? - @@ -102,6 +100,13 @@ TODO what about inputs committments? 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. + + + + + @@ -288,6 +293,9 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai | `testnet-1` | `1856588631910923207` | - | | `example-mynetwork` | `1967754805504104511` | - | +#### Creation Time +Transaction timestamp is now expressed with `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). + #### Inputs The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are three types of input: @@ -303,12 +311,15 @@ 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. ##### Commitment Input -A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node. It is used to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. - +A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node, to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. It is expressed as the _CommitmentID_ and can be resolved to the _Commitment_ value before it enters the VM. The _Commitment_ itself provides the `Slot Index` which serves as a time reference. ##### Block Issuance Credits Input -A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for destroying an _Account Output_, as it can be allowed only if the BIC balance is not negative at specific point in time. +A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for any _Account_ transitions, and account destroying. As any operation on the _Account_ can only be allowed if the BIC balance is not negative at specific point in time. _Block Issuance Credits Input_ is defined as follows. The input commitment will be resolved to hte `AccountID`, `CommitmentID` which contains the SLot Index and the BIC vector value for the given `AccountID` and `Slot Index`. +| Field Name | Type Value | +|--------------|------------| +| Account ID | ByteArray[32] | +| CommitmentID | ByteArray[32] | #### Inputs Commitment 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. @@ -327,6 +338,10 @@ The following table lists all the output types that are currently supported as w | Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | | Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | | NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | +#### Allotments +The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC vector of the slot that the transaction is issued in. + +Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. #### Payload @@ -346,9 +361,9 @@ The following table lists all the output types that are currently supported as w | Unlock Name | Type Value | TIP | |-------------|------------|--------------------------------------------------------------| -| Signature | 0 | [TIP-38](#signature-unlock) | -| Reference | 1 | [TIP-38](#reference-unlock) | -| Account | 2 | [TIP-18](../TIP-0042/tip-0042.md#account-locking--unlocking) | +| Signature | 0 | [TIP-45](#signature-unlock) | +| Reference | 1 | [TIP-45](#reference-unlock) | +| Account | 2 | [TIP-42](../TIP-0042/tip-0042.md#account-locking--unlocking) | | NFT | 3 | [TIP-43](../TIP-0043/tip-0043.md#nft-locking--unlocking) | #### Signature Unlock @@ -460,6 +475,7 @@ The following criteria defines whether a payload passes the syntactical validati * Essence: * `Transaction Type` value must denote a _TIP-45 Transaction Essence_. * `Network ID` must match the value of the current network. + * `CreationTime` must be a valid `Slot index` timestamp. * Inputs: * `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. * For each input the following must be true: @@ -474,6 +490,10 @@ The following criteria defines whether a payload passes the syntactical validati * The sum of all `Amount` fields must not exceed `Max IOTA Supply`. * The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. * The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. + * Allottments: + * `Allottments Count` must be 0 < x ≤ `Max Allottments Count`. + * The sum of all `Mana` fields must not exceed `Max Mana Supply`. + * There must be no duplicated `AccountID`s in the list of allotments. * Payload (if present): * `Payload Type` must match one of the values described under [Payload](#payload). * Payload fields must be correctly parsable in the context of the `Payload Type`. @@ -530,17 +550,16 @@ where: #### Semantic criteria for each output and all its output features in the context of the following input: 1. The _Transaction Payload_, - 2. the list of UTXOs referenced by inputs and - 3. / TDOD how to change that?: the Unix timestamp of the confirming milestone. + 2. the list of UTXOs referenced by inputsF * 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_, 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_ unlocks the alias defined by the unlocking address of the UTXO. + * If it is an _Account Unlock_: + * The address unlocking the UTXO must be an _Account Address_. + * The referenced _Unlock_ unlocks the account 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_ unlocks the NFT defined by the unlocking address of the UTXO. @@ -551,16 +570,7 @@ Transactions that do not pass semantic validation are ignored. Their UTXOs are n ## Miscellaneous -### Transaction timestamps - -Since transaction timestamps – whether they are signed or not – do not provide accuracy guarantee, the time of the trnsaction is defined by the `slot index`, as no more detailed time granularity is needed. -The correctness of the timespams is indirectly restricted by the Fishing condition, which does not allowto reference blocks that are `Fishing threshold` older than latest confirmed block. This rule puts restrictions on the block timestamp. Which in turn, is used to validate the transaction creation slot: -* The transaction creation slot must be less than or equal to the current slot index, - * transaction slot must be less or equal to the encapsulation block timestamp. - ### Address reuse -// todo is this valid? - 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. From e519051fc9d434e5822910277eaf8440e2c618f0 Mon Sep 17 00:00:00 2001 From: oliviasaa Date: Mon, 12 Jun 2023 09:30:11 +0100 Subject: [PATCH 011/122] Add decay algorithms --- tips/TIP-0045/tip-0045.md | 81 +++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 7 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index c1fa78570..41a326f8f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -509,20 +509,87 @@ Processing transactions according to its partial-ordering enables users to spend comply that: `potentialMana` + `inputStoredMana` >= `allottedMana` + `outputStoredMana` The less or equal sign in the formula above implies that it is possible for a user not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, a user does not want to own Mana att all. Then, the user must be able to refuse to allot or store their potential Mana. -FMore specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following validation rule for Mana: +More specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following validation rule for Mana: ```math -\sum_{i \in \mathcal{I}}\Big[\text{IOTA}_i*f(t - t_i) + \text{Mana}_i * g(t - t_i)\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, +\sum_{i \in \mathcal{I}}\Big[\text{Potential Mana Generated}_i + \text{Decayed Stored Mana}_i\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, ``` +$$ +\sum_{i \in \mathcal{I}}\Big[\text{Potential Mana Generated}_i + \text{Decayed Stored Mana}_i\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, +$$ where: -- $\text{IOTA}_i*f(t - t_i)$ is the amount of potential Mana generated by consuming output `i` ($\text{IOTA}_i$ is the amount of tokens in output `i`, and $f$ is calculated with the aid of the Lookup Table: decays for Mana in [TIP-39](../TIP-0039/tip-0039.md)). More specifically, `f(n)` is an approximation of `Mana Generation * (1 - e^{-beta*SlotDuration*n})`, whereas the values stored in the lookup table are an approximation of `e^{-beta*SlotDuration*n}`. All the operations to calculate `f(n)` must be done using fixed point arithmetics. Example: if `Mana Generation = e^{-beta*SlotDuration*n}) = 0.1`, and `Amount = 1001`, the potential Mana must be calculated as `1001 * 1/10 * (1 - 1/10) = 1001 * 1/10 * 9/10 = (1001 * 1 * 9)/100 = 9009/100 = 90; -- $\text{Mana}_i * g(t - t_i)$ is the amount of stored Mana on the consuming output `i` with applied decay ($\text{Mana}_i$ is the amount of stored Mana in output `i`, and $g$ is given by the Lookup Table: decays for Mana in [TIP-39](../TIP-0039/tip-0039.md)); +- $\text{Potential Mana Generated}_i$ is the amount of potential Mana generated by consuming output `i`. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. We reproduce this algorithm below: + - Let `Consumption Slot`, `Creation Slot` and `Amount` given by the table below +
Name
Creation Timeuint64 + The slot index of the block in which the transaction was created. +
Inputs Count uint16
+ + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Amountuint64 + The amount of IOTA tokens held in the output. +
Creation Slotuint64 + The index of slot in which the output was created. +
Consumption Slotuint64 + The index of slot in which the output is consumed. +
+ - Let `n = Consumption Slot - Creation Slot`. With the aid of the lookup table and the algorithm defined in [TIP-39](../TIP-0039/tip-0039.md), find `decay(n)`. If `decay(n)>0`: + - Approximate $2^{32}(1 - \exp{(-\beta \text{ SlotDuration } n)})$ by subtracting `2^32-decay(n)`. Since `decay(n)>0`, this value can be stored as a uint32. + - Multiply by an approximation of $\text{Generation Rate}/\beta$. To do so, multiply by `13410781` and subsequently apply a right-shift of 16 bits. The result will be a uint128. + - Finally, multiply the result by `Amount` (which will require 256 bits) and apply a right-shift of 32 bits. + - If `decay(n)=0`: + - Multiply `Amount*13410781` and apply a right-shift of 16 bits. +- $\text{Decayed Stored Mana}_i$ is the amount of stored Mana on the consuming output `i` with applied decay. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. We reproduce this algorithm below: + - Let `Mana Amount`, `Consumption Slot` and `Creation Slot`, be as follows + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
Mana Amountuint64 + The amount of stored Mana held by the output. +
Creation Slotuint64 + The index of slot in which the output was created. +
Consumption Slotuint64 + The index of slot in which the output is consumed. +
+ + - First multiply `Mana Amount * decay(Consumption Slot - Creation Slot)`, where `decay(Consumption Slot - Creation Slot)` is calculated with the lookup table and algorithm defined in section "Mana and fixed point arithmetics" of [TIP-39](../TIP-0039/tip-0039.md), by taking `n = Consumption Slot - Creation Slot`. This result will be a uint128. + - Apply a right-shift of 32 bits. The final result can be stored as a uint64, since it will be always smaller than $2^{64}$. - $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; - $\text{Mana}_a$ is the amount of Mana transferred to account `a` as block issuance credit; -- $\text{IOTA}_i$ is the amount of IOTA tokens held in output `i`; -- $n$ is the slot index of the transaction (consuming unspent outputs $i \in \mathcal{I}$) being validated; -- $n_i$ is the slot index of when output `i` was created; - $\mathcal{O}$ is the set outputs to which Mana will be transferred as stored Mana; - $\mathcal{A}$ is the set accounts to which Mana will be transferred as block issuance credit. From 7b15c0fd318e1f8f289ddd5397fabcf43ff9e158 Mon Sep 17 00:00:00 2001 From: oliviasaa Date: Mon, 12 Jun 2023 09:31:08 +0100 Subject: [PATCH 012/122] minor change --- tips/TIP-0045/tip-0045.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 41a326f8f..370d9910f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -514,9 +514,7 @@ More specifically, for a transaction consuming a set of unspent outputs $\mathca ```math \sum_{i \in \mathcal{I}}\Big[\text{Potential Mana Generated}_i + \text{Decayed Stored Mana}_i\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, ``` -$$ -\sum_{i \in \mathcal{I}}\Big[\text{Potential Mana Generated}_i + \text{Decayed Stored Mana}_i\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, -$$ + where: - $\text{Potential Mana Generated}_i$ is the amount of potential Mana generated by consuming output `i`. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. We reproduce this algorithm below: From 0da6c05f95b093355cc946a0de8217a975e1b441 Mon Sep 17 00:00:00 2001 From: oliviasaa Date: Sun, 18 Jun 2023 22:13:00 +0100 Subject: [PATCH 013/122] remove algorithms --- tips/TIP-0045/tip-0045.md | 71 ++------------------------------------- 1 file changed, 2 insertions(+), 69 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 370d9910f..10907d6a1 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -517,75 +517,8 @@ More specifically, for a transaction consuming a set of unspent outputs $\mathca where: -- $\text{Potential Mana Generated}_i$ is the amount of potential Mana generated by consuming output `i`. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. We reproduce this algorithm below: - - Let `Consumption Slot`, `Creation Slot` and `Amount` given by the table below - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
Amountuint64 - The amount of IOTA tokens held in the output. -
Creation Slotuint64 - The index of slot in which the output was created. -
Consumption Slotuint64 - The index of slot in which the output is consumed. -
- - Let `n = Consumption Slot - Creation Slot`. With the aid of the lookup table and the algorithm defined in [TIP-39](../TIP-0039/tip-0039.md), find `decay(n)`. If `decay(n)>0`: - - Approximate $2^{32}(1 - \exp{(-\beta \text{ SlotDuration } n)})$ by subtracting `2^32-decay(n)`. Since `decay(n)>0`, this value can be stored as a uint32. - - Multiply by an approximation of $\text{Generation Rate}/\beta$. To do so, multiply by `13410781` and subsequently apply a right-shift of 16 bits. The result will be a uint128. - - Finally, multiply the result by `Amount` (which will require 256 bits) and apply a right-shift of 32 bits. - - If `decay(n)=0`: - - Multiply `Amount*13410781` and apply a right-shift of 16 bits. -- $\text{Decayed Stored Mana}_i$ is the amount of stored Mana on the consuming output `i` with applied decay. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. We reproduce this algorithm below: - - Let `Mana Amount`, `Consumption Slot` and `Creation Slot`, be as follows - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
Mana Amountuint64 - The amount of stored Mana held by the output. -
Creation Slotuint64 - The index of slot in which the output was created. -
Consumption Slotuint64 - The index of slot in which the output is consumed. -
- - - First multiply `Mana Amount * decay(Consumption Slot - Creation Slot)`, where `decay(Consumption Slot - Creation Slot)` is calculated with the lookup table and algorithm defined in section "Mana and fixed point arithmetics" of [TIP-39](../TIP-0039/tip-0039.md), by taking `n = Consumption Slot - Creation Slot`. This result will be a uint128. - - Apply a right-shift of 32 bits. The final result can be stored as a uint64, since it will be always smaller than $2^{64}$. +- $\text{Potential Mana Generated}_i$ is the amount of potential Mana generated by consuming output `i`. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. +- $\text{Decayed Stored Mana}_i$ is the amount of stored Mana on the consuming output `i` with applied decay. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. - $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; - $\text{Mana}_a$ is the amount of Mana transferred to account `a` as block issuance credit; - $\mathcal{O}$ is the set outputs to which Mana will be transferred as stored Mana; From b69379c783407729998cbf9c04441326f5a470ac Mon Sep 17 00:00:00 2001 From: jkrvivian Date: Mon, 3 Jul 2023 20:53:32 +0800 Subject: [PATCH 014/122] Add context inputs --- tips/TIP-0045/tip-0045.md | 118 +++++++++++++++++++++++++++++++++----- 1 file changed, 105 insertions(+), 13 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 4961c5472..d5d386128 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -68,7 +68,6 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Payload Type uint32 - TODO value ?? Set to value 6 to denote a TIP-45 Transaction Payload. @@ -90,7 +89,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Transaction Type uint8 - Set to value 1 to denote a TIP-20 Transaction Essence. + Set to value 2 to denote a TIP-45 Transaction Essence. @@ -107,6 +106,34 @@ The following table describes the entirety of a _Transaction Payload_ in its ser The slot index of the block in which the transaction was created. + + Context Inputs Count + uint16 + The number of context input entries. + + + Context Inputs optAnyOf + +
+ Commitment Input +
+ Describes an input which references commitment to a certain slot. +
+
+
+ BIC Input +
+ Describes an input which denotes an BIC value of an account. +
+
+
+ Reward Input +
+ Describes an input which claims the reward. +
+
+ + Inputs Count uint16 @@ -296,30 +323,95 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai #### Creation Time Transaction timestamp is now expressed with `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). -#### Inputs +#### Context Inputs -The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are three types of input: - - _UTXO Input_ +The `Context Inputs` field holds that indicates the different functions related to account, commitment and more. Currently, there are 3 types of context input: - _Commitment Input_ - _Block Issuance Credits Input_ + - _Reward 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 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 that is allowed to unlock the referenced output. - ##### Commitment Input A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node, to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. It is expressed as the _CommitmentID_ and can be resolved to the _Commitment_ value before it enters the VM. The _Commitment_ itself provides the `Slot Index` which serves as a time reference. +Serialization Layout: + + + + + + + + + + + + + + + + +
NameTypeDescription
Input Typeuint16The input type of Commitment Input is 1.
Commitment IDByteArray[40]The commitment identifier to reference to.
+ ##### Block Issuance Credits Input A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for any _Account_ transitions, and account destroying. As any operation on the _Account_ can only be allowed if the BIC balance is not negative at specific point in time. _Block Issuance Credits Input_ is defined as follows. The input commitment will be resolved to hte `AccountID`, `CommitmentID` which contains the SLot Index and the BIC vector value for the given `AccountID` and `Slot Index`. -| Field Name | Type Value | -|--------------|------------| -| Account ID | ByteArray[32] | -| CommitmentID | ByteArray[32] | +Serialization layout: + + + + + + + + + + + + + + + + +
NameTypeDescription
Input Typeuint16The input type of BIC Input is 2.
Account IDByteArray[32]The BIC of an account to use.
+ +##### Reward Input + +A Reward Input is an input indicates which transaction `Input` is the claiming reward. + + + + + + + + + + + + + + + + + +
NameTypeDescription
Input Typeuint16The input type of Reward Input is 3.
Indexuint16The index of the transaction input for which to claim rewards.
+ +#### Inputs + +The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are one type of input: + - _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 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 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). It consists of the BLAKE2b-256 hash of the concatenated output hashes. From d6ca1fba92c8b79bedc0aeaba755ec5c906f9086 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 4 Jul 2023 09:39:24 +0200 Subject: [PATCH 015/122] Add Context Input syntactical validation --- tips/TIP-0045/tip-0045.md | 66 ++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 25 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index d5d386128..5693e4157 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -117,19 +117,19 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Commitment Input
- Describes an input which references commitment to a certain slot. + Describes an input which references a commitment to a certain slot.
- BIC Input + Block Issuance Credits Input
- Describes an input which denotes an BIC value of an account. + Describes an input which resolves to a BIC value of an account.
Reward Input
- Describes an input which claims the reward. + References a UTXO input which claims Mana rewards.
@@ -321,22 +321,23 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai | `example-mynetwork` | `1967754805504104511` | - | #### Creation Time -Transaction timestamp is now expressed with `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). + +The Transaction timestamp is now expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). #### Context Inputs -The `Context Inputs` field holds that indicates the different functions related to account, commitment and more. Currently, there are 3 types of context input: - - _Commitment Input_ - - _Block Issuance Credits Input_ - - _Reward Input_ - In the future, more types of inputs may be specified as part of protocol upgrades. +The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a transaction, such as for different functionality related to accounts, commitments or Mana rewards. Context inputs do not need to be unlocked. This TIP defines 3 types of context inputs: -Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks part of the Transaction Payload. +- _Commitment Input_ +- _Block Issuance Credits Input_ +- _Reward Input_ ##### Commitment Input -A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node, to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. It is expressed as the _CommitmentID_ and can be resolved to the _Commitment_ value before it enters the VM. The _Commitment_ itself provides the `Slot Index` which serves as a time reference. -Serialization Layout: +A _Commitment Input_ is an input that allows to reference a commitment to a certain slot. It is used to provide a notion of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at the transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference is expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The _Commitment_ itself provides the `Slot Index` which serves as the time reference. A Block that contains a transaction with a Commitment input has additional validation rules as defined in [TIP-0046](../TIP-0046/tip-0046.md). Only one _Commitment Input_ may be present in a transaction. + +It is serialized as follows: + @@ -344,9 +345,9 @@ Serialization Layout: - - - + + + @@ -356,9 +357,12 @@ Serialization Layout:
NameDescription
Input Typeuint16The input type of Commitment Input is 1.Context Input Typeuint8Set to value 0 to denote a Commitment Input.
Commitment ID
##### Block Issuance Credits Input -A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for any _Account_ transitions, and account destroying. As any operation on the _Account_ can only be allowed if the BIC balance is not negative at specific point in time. _Block Issuance Credits Input_ is defined as follows. The input commitment will be resolved to hte `AccountID`, `CommitmentID` which contains the SLot Index and the BIC vector value for the given `AccountID` and `Slot Index`. -Serialization layout: +A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is not negative at a specific point in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. +Multiple such inputs can be present in a single transaction to provide the BIC value for different accounts, however no two _Block Issuance Credits Inputs_ can reference the same account. + +It is serialized as follows: + @@ -366,9 +370,9 @@ Serialization layout: - - - + + + @@ -379,7 +383,9 @@ Serialization layout: ##### Reward Input -A Reward Input is an input indicates which transaction `Input` is the claiming reward. +A _Reward Input_ is an input that indicates which transaction `Input` is claiming Mana rewards. It can reference an _Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs can be present in a single transaction to claim rewards for different outputs, however no two Reward Inputs can reference the same index. + +It is serialized as follows:
NameDescription
Input Typeuint16The input type of BIC Input is 2.Context Input Typeuint8Set to value 1 to denote a Block Issuance Credits Input.
Account ID
@@ -388,9 +394,9 @@ A Reward Input is an input indicates which transaction `Input` is the claiming r - - - + + + @@ -430,7 +436,10 @@ The following table lists all the output types that are currently supported as w | Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | | Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | | NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | +| Delegation | 7 | [TIP-40](../TIP-0040/tip-0040.md#delegation-output) | + #### Allotments + The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC vector of the slot that the transaction is issued in. Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. @@ -574,6 +583,13 @@ The following criteria defines whether a payload passes the syntactical validati * `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). * `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. + * Context Inputs: + * `Context Inputs Count` must be 0 <= x ≤ `Max Inputs Count`. + * `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). + * There must be zero or one _Commitment Input_. + * All _Rewards Inputs_ must reference a different `Index`. + * _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. + * All _Block Issuance Credits Inputs_ must reference a different `Account ID`. * Outputs: * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. * For each output the following must be true: From 7dc17d19b79b9429d52ee871ac18877ec00f8663 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 4 Jul 2023 09:43:17 +0200 Subject: [PATCH 016/122] Rename `Creation Time` to `Creation Slot` --- tips/TIP-0045/tip-0045.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 5693e4157..a647f6432 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -100,7 +100,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - + @@ -321,22 +321,23 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai | `example-mynetwork` | `1967754805504104511` | - | #### Creation Time -Transaction timestamp is now expressed with `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). + +The Transaction timestamp is now expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). #### Context Inputs -The `Context Inputs` field holds that indicates the different functions related to account, commitment and more. Currently, there are 3 types of context input: - - _Commitment Input_ - - _Block Issuance Credits Input_ - - _Reward Input_ - In the future, more types of inputs may be specified as part of protocol upgrades. +The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a transaction, such as for different functionality related to accounts, commitments or Mana rewards. Context inputs do not need to be unlocked. This TIP defines 3 types of context inputs: -Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks part of the Transaction Payload. +- _Commitment Input_ +- _Block Issuance Credits Input_ +- _Reward Input_ ##### Commitment Input -A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node, to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. It is expressed as the _CommitmentID_ and can be resolved to the _Commitment_ value before it enters the VM. The _Commitment_ itself provides the `Slot Index` which serves as a time reference. -Serialization Layout: +A _Commitment Input_ is an input that allows to reference a commitment to a certain slot. It is used to provide a notion of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at the transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference is expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The _Commitment_ itself provides the `Slot Index` which serves as the time reference. A Block that contains a transaction with a Commitment input has additional validation rules as defined in [TIP-0046](../TIP-0046/tip-0046.md). Only one _Commitment Input_ may be present in a transaction. + +It is serialized as follows: +
Description
Input Typeuint16The input type of Reward Input is 3.Context Input Typeuint8Set to value 2 to denote a Reward Input.
Index
Creation TimeCreation Slot uint64 The slot index of the block in which the transaction was created. @@ -320,9 +320,9 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai | `testnet-1` | `1856588631910923207` | - | | `example-mynetwork` | `1967754805504104511` | - | -#### Creation Time +#### Creation Slot -The Transaction timestamp is now expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). +The transaction timestamp is expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). #### Context Inputs @@ -630,7 +630,7 @@ Processing transactions according to its partial-ordering enables users to spend **Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): * The transaction must not spend more mana than allowed, briefly it must given following definitions: -- `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction timestamp, and decay function +- `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and decay function - `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. - `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` - `outputStoredMana` sum of stored mana from outputs From 77acd992bf2480baad8697a2cf4e42822734891d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 4 Jul 2023 09:44:49 +0200 Subject: [PATCH 017/122] Format TIP-45 --- tips/TIP-0045/tip-0045.md | 406 ++++++++++++++++++++++++-------------- 1 file changed, 259 insertions(+), 147 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index a647f6432..29453fd93 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -14,31 +14,46 @@ replaces: TIP-20 # Summary -This TIP proposes a new 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-46](../TIP-0046/tip-0046.md) and extends the transaction payload described in [TIP-20](../TIP-0007/tip-0020.md). +This TIP proposes a new 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-46](../TIP-0046/tip-0046.md) and +extends the transaction payload described in [TIP-20](../TIP-0007/tip-0020.md). # Motivation -[TIP-20](../TIP-0020/tip-0020.md) introduced a new extended transaction model for the Stardust update. This TIP extends this model to be aligned with all new mana and account features: -- accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). +[TIP-20](../TIP-0020/tip-0020.md) introduced a new extended transaction model for the Stardust update. This TIP extends +this model to be aligned with all new mana and account features: + +- accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), + [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). - include an _Allotments_ field in the transaction for mana allotment of Block Issuance Credits, -- updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA 2.0 mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). +- updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA + 2.0 mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). -The motivation of these changes is to adjust the transaction and its validation rules with the protocol upgrade to IOTA 2.0. -Validation rules must now consider the mana decay factor and the possibility of mana allotment in the transaction to a Block Issuance Credits account. +The motivation of these changes is to adjust the transaction and its validation rules with the protocol upgrade to IOTA +2.0. Validation rules must now consider the mana decay factor and the possibility of mana allotment in the transaction +to a Block Issuance Credits account. # 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. +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*. An unlock may contain a signature proving ownership of a given input's address and/or other unlock criteria. +- 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_. 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: @@ -49,14 +64,19 @@ The following image depicts the flow of funds using UTXO: ### 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 _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. 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. 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. +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 [TIP-21](../TIP-0021/tip-0021.md): +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): @@ -306,15 +326,19 @@ 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 1 for TIP-20 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 1 for TIP-20 Transaction Essence. #### Network ID -The `Network ID` field of the transaction essence serves as a [replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). -It is a unique value denoting whether the transaction was meant for the IOTA mainnet, shimmer, testnet-1, or a private network. It consists of the first 8 bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as an unsigned integer number. +The `Network ID` field of the transaction essence serves as a +[replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). It is a unique value denoting whether +the transaction was meant for the IOTA mainnet, shimmer, testnet-1, or a private network. It consists of the first 8 +bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as an unsigned integer number. | Network Name | Resulting `Network ID` | Network Name defined in | -|---------------------|------------------------|-----------------------------------------------------| +| ------------------- | ---------------------- | --------------------------------------------------- | | `iota-mainnet` | `9374574019616453254` | [TIP-22](../TIP-0022/tip-0022.md#detailed-design) | | `shimmer` | `14364762045254553490` | [TIP-32](../TIP-0032/tip-0032.md#global-parameters) | | `testnet-1` | `1856588631910923207` | - | @@ -322,11 +346,15 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai #### Creation Slot -The transaction timestamp is expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). +The transaction timestamp is expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the +transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of +semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). #### Context Inputs -The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a transaction, such as for different functionality related to accounts, commitments or Mana rewards. Context inputs do not need to be unlocked. This TIP defines 3 types of context inputs: +The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a +transaction, such as for different functionality related to accounts, commitments or Mana rewards. Context inputs do not +need to be unlocked. This TIP defines 3 types of context inputs: - _Commitment Input_ - _Block Issuance Credits Input_ @@ -334,7 +362,13 @@ The `Context Inputs` field holds inputs that provide additional contextual infor ##### Commitment Input -A _Commitment Input_ is an input that allows to reference a commitment to a certain slot. It is used to provide a notion of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at the transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference is expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The _Commitment_ itself provides the `Slot Index` which serves as the time reference. A Block that contains a transaction with a Commitment input has additional validation rules as defined in [TIP-0046](../TIP-0046/tip-0046.md). Only one _Commitment Input_ may be present in a transaction. +A _Commitment Input_ is an input that allows to reference a commitment to a certain slot. It is used to provide a notion +of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at +the transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference +is expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The +_Commitment_ itself provides the `Slot Index` which serves as the time reference. A Block that contains a transaction +with a Commitment input has additional validation rules as defined in [TIP-0046](../TIP-0046/tip-0046.md). Only one +_Commitment Input_ may be present in a transaction. It is serialized as follows: @@ -358,8 +392,13 @@ It is serialized as follows: ##### Block Issuance Credits Input -A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is not negative at a specific point in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. -Multiple such inputs can be present in a single transaction to provide the BIC value for different accounts, however no two _Block Issuance Credits Inputs_ can reference the same account. +A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a +specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer +Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is not negative at a specific point +in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC +value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple such +inputs can be present in a single transaction to provide the BIC value for different accounts, however no two _Block +Issuance Credits Inputs_ can reference the same account. It is serialized as follows: @@ -383,7 +422,12 @@ It is serialized as follows: ##### Reward Input -A _Reward Input_ is an input that indicates which transaction `Input` is claiming Mana rewards. It can reference an _Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs can be present in a single transaction to claim rewards for different outputs, however no two Reward Inputs can reference the same index. +A _Reward Input_ is an input that indicates which transaction `Input` is claiming Mana rewards. It can reference an +_Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total +amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of +rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs +can be present in a single transaction to claim rewards for different outputs, however no two Reward Inputs can +reference the same index. It is serialized as follows: @@ -407,61 +451,81 @@ It is serialized as follows: #### Inputs -The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are one type of input: - - _UTXO Input_ - In the future, more types of inputs may be specified as part of protocol upgrades. +The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. +Currently, there are one type of input: -Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks part of the Transaction Payload. +- _UTXO Input_ In the future, more types of inputs may be specified as part of protocol upgrades. -##### UTXO Input +Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks part of the +Transaction Payload. -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. +##### 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 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). It consists of the BLAKE2b-256 hash of the concatenated output hashes. +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). +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 -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` 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](../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 | -|-------------|------------|--------------------------------------------------| -| Basic | 3 | [TIP-41](../TIP-0041/tip-0041.md#basic-output) | -| Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | -| Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | -| NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | -| Delegation | 7 | [TIP-40](../TIP-0040/tip-0040.md#delegation-output) | +| Output Name | Type Value | TIP | +| ----------- | ---------- | --------------------------------------------------- | +| Basic | 3 | [TIP-41](../TIP-0041/tip-0041.md#basic-output) | +| Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | +| Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | +| NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | +| Delegation | 7 | [TIP-40](../TIP-0040/tip-0040.md#delegation-output) | #### Allotments -The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC vector of the slot that the transaction is issued in. +The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that +converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA +tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC +vector of the slot that the transaction is issued in. -Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. +Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the +issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. #### Payload -The _Transaction Essence_ itself can contain another payload as described in general in [TIP-46](../TIP-0024/tip-0046.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 +[TIP-46](../TIP-0024/tip-0046.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: +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 | [TIP-23](../TIP-0023/tip-0023.md) | ### Unlocks 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_ and the _Reference Unlock_ are 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 | -|-------------|------------|--------------------------------------------------------------| +| ----------- | ---------- | ------------------------------------------------------------ | | Signature | 0 | [TIP-45](#signature-unlock) | | Reference | 1 | [TIP-45](#reference-unlock) | | Account | 2 | [TIP-42](../TIP-0042/tip-0042.md#account-locking--unlocking) | @@ -469,7 +533,8 @@ The following table lists all the output types that are currently supported as w #### Signature Unlock -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: +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:
@@ -520,12 +585,15 @@ The Signature Unlock defines an Unlock which holds a signature sig ##### Unlock syntactic validation -* `Signature` must contain an _Ed25519 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. +- `Signature` must contain an _Ed25519 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 -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: +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:
@@ -549,102 +617,134 @@ The Reference Unlock defines an Unlock which references a previous ##### Unlock syntactic validation -* The _Reference Unlock_ at index i must have `Reference` < i and the unlock at index `Reference` must be a _Signature Unlock_. +- 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 Unlocks part: +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 Unlocks part: | Index | Unlock | -|-------|------------------------------------------------------------------------------------| +| ----- | ---------------------------------------------------------------------------------- | | 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. +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 [TIP-38](../TIP-0038/tip-0038.md), [TIP-1](../TIP-0042/tip-0041.md),[TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md) and [TIP-44](../TIP-0044/tip-0044.md) -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](../TIP-0038/tip-0038.md#output-design) and [feature type](../TIP-0038/tip-0038.md#features) separately. +The different output types and optional output features introduced by [TIP-38](../TIP-0038/tip-0038.md), +[TIP-1](../TIP-0042/tip-0041.md),[TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md) and +[TIP-44](../TIP-0044/tip-0044.md) 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](../TIP-0038/tip-0038.md#output-design) and [feature type](../TIP-0038/tip-0038.md#features) separately. ### Syntactic validation -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. +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: -* Essence: - * `Transaction Type` value must denote a _TIP-45 Transaction Essence_. - * `Network ID` must match the value of the current network. - * `CreationTime` must be a valid `Slot index` timestamp. - * Inputs: - * `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. - * For each input the following must be true: - * `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). - * `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. - * Context Inputs: - * `Context Inputs Count` must be 0 <= x ≤ `Max Inputs Count`. - * `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). - * There must be zero or one _Commitment Input_. - * All _Rewards Inputs_ must reference a different `Index`. - * _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - * All _Block Issuance Credits Inputs_ must reference a different `Account ID`. - * Outputs: - * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. - * For each output 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`. - * The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. - * The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - * Allottments: - * `Allottments Count` must be 0 < x ≤ `Max Allottments Count`. - * The sum of all `Mana` fields must not exceed `Max Mana Supply`. - * There must be no duplicated `AccountID`s in the list of allotments. - * Payload (if present): - * `Payload Type` must match one of the values described under [Payload](#payload). - * 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_. - * 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. +- Essence: + - `Transaction Type` value must denote a _TIP-45 Transaction Essence_. + - `Network ID` must match the value of the current network. + - `CreationTime` must be a valid `Slot index` timestamp. + - Inputs: + - `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. + - For each input the following must be true: + - `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). + - `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. + - Context Inputs: + - `Context Inputs Count` must be 0 <= x ≤ `Max Inputs Count`. + - `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). + - There must be zero or one _Commitment Input_. + - All _Rewards Inputs_ must reference a different `Index`. + - _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. + - All _Block Issuance Credits Inputs_ must reference a different `Account ID`. + - Outputs: + - `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. + - For each output 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`. + - The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. + - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. + - Allottments: + - `Allottments Count` must be 0 < x ≤ `Max Allottments Count`. + - The sum of all `Mana` fields must not exceed `Max Mana Supply`. + - There must be no duplicated `AccountID`s in the list of allotments. + - Payload (if present): + - `Payload Type` must match one of the values described under [Payload](#payload). + - 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_. + - 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 -The Semantic validation of a _Transaction Payload_ is performed when its encapsulating block is confirmed. The semantic validity of transactions depends on the partial order in which they are processed. The solidification mechanism of the protocol ensures that all inputs will be processed only when all inputs are known valid, and not conflicting. +The Semantic validation of a _Transaction Payload_ is performed when its encapsulating block is confirmed. The semantic +validity of transactions depends on the partial order in which they are processed. The solidification mechanism of the +protocol ensures that all inputs will be processed only when all inputs are known valid, and not conflicting. -Processing transactions according to its partial-ordering enables users to spend UTXOs which are created at similar point in time, but the input transaction has not yet been confirmed by the network, as they will be processed by preserving thei input-output order relations. 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. +Processing transactions according to its partial-ordering enables users to spend UTXOs which are created at similar +point in time, but the input transaction has not yet been confirmed by the network, as they will be processed by +preserving thei input-output order relations. 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. #### Criteria defining 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 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is counted as one. -* 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. - -**Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): - * The transaction must not spend more mana than allowed, briefly it must given following definitions: -- `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and decay function -- `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. -- `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` -- `outputStoredMana` sum of stored mana from outputs -comply that: -`potentialMana` + `inputStoredMana` >= `allottedMana` + `outputStoredMana` -The less or equal sign in the formula above implies that it is possible for a user not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, a user does not want to own Mana att all. Then, the user must be able to refuse to allot or store their potential Mana. -FMore specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following validation rule for Mana: + +- 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 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must + not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is + counted as one. +- 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. + +**Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see +[TIP-39](../TIP-0039/tip-0039.md)): + +- The transaction must not spend more mana than allowed, briefly it must given following definitions: + +* `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and + decay function +* `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. +* `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` +* `outputStoredMana` sum of stored mana from outputs comply that: `potentialMana` + `inputStoredMana` >= + `allottedMana` + `outputStoredMana` The less or equal sign in the formula above implies that it is possible for a user + not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, + a user does not want to own Mana att all. Then, the user must be able to refuse to allot or store their potential + Mana. FMore specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following + validation rule for Mana: ```math \sum_{i \in \mathcal{I}}\Big[\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big) + \text{Mana}_i * e^{-\beta(t - t_i)}\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, ``` + where: -- $\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big)$ is the amount of potential Mana generated by consuming output `i`; +- $\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big)$ is the amount of potential Mana generated by consuming + output `i`; - $\text{Mana}_i * e^{-\beta(t - t_i)}$ is the amount of stored Mana on the consuming output `i` with applied decay; - $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; - $\text{Mana}_a$ is the amount of Mana transferred to account `a` as block issuance credit; @@ -657,46 +757,58 @@ where: - $\mathcal{A}$ is the set accounts to which Mana will be transferred as block issuance credit. #### Semantic criteria for each output and all its output features in the context of the following input: + 1. The _Transaction Payload_, 2. the list of UTXOs referenced by inputsF -* 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_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. - * If it is an _Account Unlock_: - * The address unlocking the UTXO must be an _Account Address_. - * The referenced _Unlock_ unlocks the account 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_ 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. - -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. + +- 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_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. + - If it is an _Account Unlock_: + - The address unlocking the UTXO must be an _Account Address_. + - The referenced _Unlock_ unlocks the account 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_ 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. + +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 ### 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. +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. -* It is not possible to produce a valid transaction without having access to the content of the consumed outputs. +- 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. +- It is not possible to produce a valid transaction without having access to the content of the consumed outputs. # Rationale and alternatives -* _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. +- _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 Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). - From 89843cb49b619070a423ec38133355cd7cdcb623 Mon Sep 17 00:00:00 2001 From: Roman Overko Date: Tue, 4 Jul 2023 14:55:24 +0200 Subject: [PATCH 018/122] Adapt changes from 9c9af7c --- tips/TIP-0045/tip-0045.md | 54 +++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 22 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 10907d6a1..fdefb655d 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -58,8 +58,6 @@ The *Transaction Payload ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rf 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): -TODO what about inputs committments? -
@@ -102,6 +100,13 @@ TODO what about inputs committments? 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. + + + + + @@ -288,6 +293,9 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai | `testnet-1` | `1856588631910923207` | - | | `example-mynetwork` | `1967754805504104511` | - | +#### Creation Time +Transaction timestamp is now expressed with `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). + #### Inputs The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are three types of input: @@ -303,12 +311,15 @@ 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. ##### Commitment Input -A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node. It is used to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. - +A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node, to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. It is expressed as the _CommitmentID_ and can be resolved to the _Commitment_ value before it enters the VM. The _Commitment_ itself provides the `Slot Index` which serves as a time reference. ##### Block Issuance Credits Input -A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for destroying an _Account Output_, as it can be allowed only if the BIC balance is not negative at specific point in time. +A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for any _Account_ transitions, and account destroying. As any operation on the _Account_ can only be allowed if the BIC balance is not negative at specific point in time. _Block Issuance Credits Input_ is defined as follows. The input commitment will be resolved to hte `AccountID`, `CommitmentID` which contains the SLot Index and the BIC vector value for the given `AccountID` and `Slot Index`. +| Field Name | Type Value | +|--------------|------------| +| Account ID | ByteArray[32] | +| CommitmentID | ByteArray[32] | #### Inputs Commitment 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. @@ -327,6 +338,10 @@ The following table lists all the output types that are currently supported as w | Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | | Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | | NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | +#### Allotments +The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC vector of the slot that the transaction is issued in. + +Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. #### Payload @@ -346,9 +361,9 @@ The following table lists all the output types that are currently supported as w | Unlock Name | Type Value | TIP | |-------------|------------|--------------------------------------------------------------| -| Signature | 0 | [TIP-38](#signature-unlock) | -| Reference | 1 | [TIP-38](#reference-unlock) | -| Account | 2 | [TIP-18](../TIP-0042/tip-0042.md#account-locking--unlocking) | +| Signature | 0 | [TIP-45](#signature-unlock) | +| Reference | 1 | [TIP-45](#reference-unlock) | +| Account | 2 | [TIP-42](../TIP-0042/tip-0042.md#account-locking--unlocking) | | NFT | 3 | [TIP-43](../TIP-0043/tip-0043.md#nft-locking--unlocking) | #### Signature Unlock @@ -460,6 +475,7 @@ The following criteria defines whether a payload passes the syntactical validati * Essence: * `Transaction Type` value must denote a _TIP-45 Transaction Essence_. * `Network ID` must match the value of the current network. + * `CreationTime` must be a valid `Slot index` timestamp. * Inputs: * `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. * For each input the following must be true: @@ -474,6 +490,10 @@ The following criteria defines whether a payload passes the syntactical validati * The sum of all `Amount` fields must not exceed `Max IOTA Supply`. * The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. * The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. + * Allottments: + * `Allottments Count` must be 0 < x ≤ `Max Allottments Count`. + * The sum of all `Mana` fields must not exceed `Max Mana Supply`. + * There must be no duplicated `AccountID`s in the list of allotments. * Payload (if present): * `Payload Type` must match one of the values described under [Payload](#payload). * Payload fields must be correctly parsable in the context of the `Payload Type`. @@ -526,17 +546,16 @@ where: #### Semantic criteria for each output and all its output features in the context of the following input: 1. The _Transaction Payload_, - 2. the list of UTXOs referenced by inputs and - 3. / TDOD how to change that?: the Unix timestamp of the confirming milestone. + 2. the list of UTXOs referenced by inputsF * 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_, 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_ unlocks the alias defined by the unlocking address of the UTXO. + * If it is an _Account Unlock_: + * The address unlocking the UTXO must be an _Account Address_. + * The referenced _Unlock_ unlocks the account 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_ unlocks the NFT defined by the unlocking address of the UTXO. @@ -547,16 +566,7 @@ Transactions that do not pass semantic validation are ignored. Their UTXOs are n ## Miscellaneous -### Transaction timestamps - -Since transaction timestamps – whether they are signed or not – do not provide accuracy guarantee, the time of the trnsaction is defined by the `slot index`, as no more detailed time granularity is needed. -The correctness of the timespams is indirectly restricted by the Fishing condition, which does not allowto reference blocks that are `Fishing threshold` older than latest confirmed block. This rule puts restrictions on the block timestamp. Which in turn, is used to validate the transaction creation slot: -* The transaction creation slot must be less than or equal to the current slot index, - * transaction slot must be less or equal to the encapsulation block timestamp. - ### Address reuse -// todo is this valid? - 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. From e054452b796201ea46fe7953df364459eb5f91e8 Mon Sep 17 00:00:00 2001 From: Roman Overko Date: Tue, 4 Jul 2023 15:09:51 +0200 Subject: [PATCH 019/122] Adapt changes from b69379c --- tips/TIP-0045/tip-0045.md | 118 +++++++++++++++++++++++++++++++++----- 1 file changed, 105 insertions(+), 13 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index fdefb655d..ceb8c3990 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -68,7 +68,6 @@ The following table describes the entirety of a _Transaction Payload_ in its ser @@ -90,7 +89,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser @@ -107,6 +106,34 @@ The following table describes the entirety of a _Transaction Payload_ in its ser The slot index of the block in which the transaction was created. + + + + + + + + + @@ -296,30 +323,95 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai #### Creation Time Transaction timestamp is now expressed with `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). -#### Inputs +#### Context Inputs -The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are three types of input: - - _UTXO Input_ +The `Context Inputs` field holds that indicates the different functions related to account, commitment and more. Currently, there are 3 types of context input: - _Commitment Input_ - _Block Issuance Credits Input_ + - _Reward 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 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 that is allowed to unlock the referenced output. - ##### Commitment Input A _Commitment Input_ is an input that allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node, to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. It is expressed as the _CommitmentID_ and can be resolved to the _Commitment_ value before it enters the VM. The _Commitment_ itself provides the `Slot Index` which serves as a time reference. +Serialization Layout: +
Name
Creation Timeuint64 + The slot index of the block in which the transaction was created. +
Inputs Count uint16Payload Type uint32 - TODO value ?? Set to value 6 to denote a TIP-45 Transaction Payload.
Transaction Type uint8 - Set to value 1 to denote a TIP-20 Transaction Essence. + Set to value 2 to denote a TIP-45 Transaction Essence.
Context Inputs Countuint16The number of context input entries.
Context Inputs optAnyOf +
+ Commitment Input +
+ Describes an input which references commitment to a certain slot. +
+
+
+ BIC Input +
+ Describes an input which denotes an BIC value of an account. +
+
+
+ Reward Input +
+ Describes an input which claims the reward. +
+
+
Inputs Count uint16
+ + + + + + + + + + + + + + + +
NameTypeDescription
Input Typeuint16The input type of Commitment Input is 1.
Commitment IDByteArray[40]The commitment identifier to reference to.
+ ##### Block Issuance Credits Input A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for any _Account_ transitions, and account destroying. As any operation on the _Account_ can only be allowed if the BIC balance is not negative at specific point in time. _Block Issuance Credits Input_ is defined as follows. The input commitment will be resolved to hte `AccountID`, `CommitmentID` which contains the SLot Index and the BIC vector value for the given `AccountID` and `Slot Index`. -| Field Name | Type Value | -|--------------|------------| -| Account ID | ByteArray[32] | -| CommitmentID | ByteArray[32] | +Serialization layout: + + + + + + + + + + + + + + + + +
NameTypeDescription
Input Typeuint16The input type of BIC Input is 2.
Account IDByteArray[32]The BIC of an account to use.
+ +##### Reward Input + +A Reward Input is an input indicates which transaction `Input` is the claiming reward. + + + + + + + + + + + + + + + + + +
NameTypeDescription
Input Typeuint16The input type of Reward Input is 3.
Indexuint16The index of the transaction input for which to claim rewards.
+ +#### Inputs + +The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are one type of input: + - _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 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 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). It consists of the BLAKE2b-256 hash of the concatenated output hashes. From 468c6b36cb3e976e3921e9bb226535504a7db0da Mon Sep 17 00:00:00 2001 From: Roman Overko Date: Tue, 4 Jul 2023 15:22:51 +0200 Subject: [PATCH 020/122] Adapt changes from d6ca1fb --- tips/TIP-0045/tip-0045.md | 66 ++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 25 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index ceb8c3990..5c269bab8 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -117,19 +117,19 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Commitment Input
- Describes an input which references commitment to a certain slot. + Describes an input which references a commitment to a certain slot.
- BIC Input + Block Issuance Credits Input
- Describes an input which denotes an BIC value of an account. + Describes an input which resolves to a BIC value of an account.
Reward Input
- Describes an input which claims the reward. + References a UTXO input which claims Mana rewards.
@@ -344,9 +345,9 @@ Serialization Layout: - - - + + + @@ -356,9 +357,12 @@ Serialization Layout:
NameDescription
Input Typeuint16The input type of Commitment Input is 1.Context Input Typeuint8Set to value 0 to denote a Commitment Input.
Commitment ID
##### Block Issuance Credits Input -A _Block Issuance Credits Input_ is an input that allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for any _Account_ transitions, and account destroying. As any operation on the _Account_ can only be allowed if the BIC balance is not negative at specific point in time. _Block Issuance Credits Input_ is defined as follows. The input commitment will be resolved to hte `AccountID`, `CommitmentID` which contains the SLot Index and the BIC vector value for the given `AccountID` and `Slot Index`. -Serialization layout: +A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is not negative at a specific point in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. +Multiple such inputs can be present in a single transaction to provide the BIC value for different accounts, however no two _Block Issuance Credits Inputs_ can reference the same account. + +It is serialized as follows: + @@ -366,9 +370,9 @@ Serialization layout: - - - + + + @@ -379,7 +383,9 @@ Serialization layout: ##### Reward Input -A Reward Input is an input indicates which transaction `Input` is the claiming reward. +A _Reward Input_ is an input that indicates which transaction `Input` is claiming Mana rewards. It can reference an _Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs can be present in a single transaction to claim rewards for different outputs, however no two Reward Inputs can reference the same index. + +It is serialized as follows:
NameDescription
Input Typeuint16The input type of BIC Input is 2.Context Input Typeuint8Set to value 1 to denote a Block Issuance Credits Input.
Account ID
@@ -388,9 +394,9 @@ A Reward Input is an input indicates which transaction `Input` is the claiming r - - - + + + @@ -430,7 +436,10 @@ The following table lists all the output types that are currently supported as w | Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | | Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | | NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | +| Delegation | 7 | [TIP-40](../TIP-0040/tip-0040.md#delegation-output) | + #### Allotments + The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC vector of the slot that the transaction is issued in. Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. @@ -574,6 +583,13 @@ The following criteria defines whether a payload passes the syntactical validati * `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). * `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. + * Context Inputs: + * `Context Inputs Count` must be 0 <= x ≤ `Max Inputs Count`. + * `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). + * There must be zero or one _Commitment Input_. + * All _Rewards Inputs_ must reference a different `Index`. + * _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. + * All _Block Issuance Credits Inputs_ must reference a different `Account ID`. * Outputs: * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. * For each output the following must be true: From 81b204f671d0c15a89cb9f2018f9ea2785f8ef7f Mon Sep 17 00:00:00 2001 From: Roman Overko Date: Tue, 4 Jul 2023 15:25:29 +0200 Subject: [PATCH 021/122] Adapt changes from 7dc17d1 --- tips/TIP-0045/tip-0045.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 5c269bab8..7721d14d4 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -100,7 +100,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - +
Description
Input Typeuint16The input type of Reward Input is 3.Context Input Typeuint8Set to value 2 to denote a Reward Input.
Index
Creation TimeCreation Slot uint64 The slot index of the block in which the transaction was created. @@ -320,9 +320,9 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai | `testnet-1` | `1856588631910923207` | - | | `example-mynetwork` | `1967754805504104511` | - | -#### Creation Time +#### Creation Slot -The Transaction timestamp is now expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). +The transaction timestamp is expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). #### Context Inputs @@ -630,7 +630,7 @@ Processing transactions according to its partial-ordering enables users to spend **Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): * The transaction must not spend more mana than allowed, briefly it must given following definitions: -- `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction timestamp, and decay function +- `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and decay function - `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. - `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` - `outputStoredMana` sum of stored mana from outputs From 0c434d29376c9c4f35c2842d460cad8cc8c50a05 Mon Sep 17 00:00:00 2001 From: Roman Overko Date: Tue, 4 Jul 2023 16:12:54 +0200 Subject: [PATCH 022/122] Adapt changes from 77acd99 --- tips/TIP-0045/tip-0045.md | 404 ++++++++++++++++++++++++-------------- 1 file changed, 259 insertions(+), 145 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 7721d14d4..608394114 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -14,31 +14,46 @@ replaces: TIP-20 # Summary -This TIP proposes a new 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-46](../TIP-0046/tip-0046.md) and extends the transaction payload described in [TIP-20](../TIP-0007/tip-0020.md). +This TIP proposes a new 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-46](../TIP-0046/tip-0046.md) and +extends the transaction payload described in [TIP-20](../TIP-0007/tip-0020.md). # Motivation -[TIP-20](../TIP-0020/tip-0020.md) introduced a new extended transaction model for the Stardust update. This TIP extends this model to be aligned with all new mana and account features: -- accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). +[TIP-20](../TIP-0020/tip-0020.md) introduced a new extended transaction model for the Stardust update. This TIP extends +this model to be aligned with all new mana and account features: + +- accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), + [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). - include an _Allotments_ field in the transaction for mana allotment of Block Issuance Credits, -- updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA 2.0 mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). +- updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA + 2.0 mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). -The motivation of these changes is to adjust the transaction and its validation rules with the protocol upgrade to IOTA 2.0. -Validation rules must now consider the mana decay factor and the possibility of mana allotment in the transaction to a Block Issuance Credits account. +The motivation of these changes is to adjust the transaction and its validation rules with the protocol upgrade to IOTA +2.0. Validation rules must now consider the mana decay factor and the possibility of mana allotment in the transaction +to a Block Issuance Credits account. # 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. +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*. An unlock may contain a signature proving ownership of a given input's address and/or other unlock criteria. +- 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_. 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: @@ -49,14 +64,19 @@ The following image depicts the flow of funds using UTXO: ### 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 _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. 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. 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. +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 [TIP-21](../TIP-0021/tip-0021.md): +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): @@ -306,15 +326,19 @@ 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 1 for TIP-20 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 1 for TIP-20 Transaction Essence. #### Network ID -The `Network ID` field of the transaction essence serves as a [replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). -It is a unique value denoting whether the transaction was meant for the IOTA mainnet, shimmer, testnet-1, or a private network. It consists of the first 8 bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as an unsigned integer number. +The `Network ID` field of the transaction essence serves as a +[replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). It is a unique value denoting whether +the transaction was meant for the IOTA mainnet, shimmer, testnet-1, or a private network. It consists of the first 8 +bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as an unsigned integer number. | Network Name | Resulting `Network ID` | Network Name defined in | -|---------------------|------------------------|-----------------------------------------------------| +| ------------------- | ---------------------- | --------------------------------------------------- | | `iota-mainnet` | `9374574019616453254` | [TIP-22](../TIP-0022/tip-0022.md#detailed-design) | | `shimmer` | `14364762045254553490` | [TIP-32](../TIP-0032/tip-0032.md#global-parameters) | | `testnet-1` | `1856588631910923207` | - | @@ -322,11 +346,15 @@ It is a unique value denoting whether the transaction was meant for the IOTA mai #### Creation Slot -The transaction timestamp is expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). +The transaction timestamp is expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the +transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of +semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). #### Context Inputs -The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a transaction, such as for different functionality related to accounts, commitments or Mana rewards. Context inputs do not need to be unlocked. This TIP defines 3 types of context inputs: +The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a +transaction, such as for different functionality related to accounts, commitments or Mana rewards. Context inputs do not +need to be unlocked. This TIP defines 3 types of context inputs: - _Commitment Input_ - _Block Issuance Credits Input_ @@ -334,7 +362,13 @@ The `Context Inputs` field holds inputs that provide additional contextual infor ##### Commitment Input -A _Commitment Input_ is an input that allows to reference a commitment to a certain slot. It is used to provide a notion of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at the transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference is expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The _Commitment_ itself provides the `Slot Index` which serves as the time reference. A Block that contains a transaction with a Commitment input has additional validation rules as defined in [TIP-0046](../TIP-0046/tip-0046.md). Only one _Commitment Input_ may be present in a transaction. +A _Commitment Input_ is an input that allows to reference a commitment to a certain slot. It is used to provide a notion +of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at +the transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference +is expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The +_Commitment_ itself provides the `Slot Index` which serves as the time reference. A Block that contains a transaction +with a Commitment input has additional validation rules as defined in [TIP-0046](../TIP-0046/tip-0046.md). Only one +_Commitment Input_ may be present in a transaction. It is serialized as follows: @@ -358,8 +392,13 @@ It is serialized as follows: ##### Block Issuance Credits Input -A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is not negative at a specific point in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. -Multiple such inputs can be present in a single transaction to provide the BIC value for different accounts, however no two _Block Issuance Credits Inputs_ can reference the same account. +A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a +specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer +Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is not negative at a specific point +in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC +value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple such +inputs can be present in a single transaction to provide the BIC value for different accounts, however no two _Block +Issuance Credits Inputs_ can reference the same account. It is serialized as follows: @@ -383,7 +422,12 @@ It is serialized as follows: ##### Reward Input -A _Reward Input_ is an input that indicates which transaction `Input` is claiming Mana rewards. It can reference an _Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs can be present in a single transaction to claim rewards for different outputs, however no two Reward Inputs can reference the same index. +A _Reward Input_ is an input that indicates which transaction `Input` is claiming Mana rewards. It can reference an +_Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total +amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of +rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs +can be present in a single transaction to claim rewards for different outputs, however no two Reward Inputs can +reference the same index. It is serialized as follows: @@ -407,61 +451,81 @@ It is serialized as follows: #### Inputs -The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there are one type of input: - - _UTXO Input_ - In the future, more types of inputs may be specified as part of protocol upgrades. +The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. +Currently, there are one type of input: -Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks part of the Transaction Payload. +- _UTXO Input_ In the future, more types of inputs may be specified as part of protocol upgrades. -##### UTXO Input +Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks part of the +Transaction Payload. -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. +##### 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 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). It consists of the BLAKE2b-256 hash of the concatenated output hashes. +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). +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 -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` 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](../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 | -|-------------|------------|--------------------------------------------------| -| Basic | 3 | [TIP-41](../TIP-0041/tip-0041.md#basic-output) | -| Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | -| Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | -| NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | -| Delegation | 7 | [TIP-40](../TIP-0040/tip-0040.md#delegation-output) | +| Output Name | Type Value | TIP | +| ----------- | ---------- | --------------------------------------------------- | +| Basic | 3 | [TIP-41](../TIP-0041/tip-0041.md#basic-output) | +| Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | +| Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | +| NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | +| Delegation | 7 | [TIP-40](../TIP-0040/tip-0040.md#delegation-output) | #### Allotments -The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC vector of the slot that the transaction is issued in. +The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that +converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA +tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC +vector of the slot that the transaction is issued in. -Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. +Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the +issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. #### Payload -The _Transaction Essence_ itself can contain another payload as described in general in [TIP-46](../TIP-0024/tip-0046.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 +[TIP-46](../TIP-0024/tip-0046.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: +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 | [TIP-23](../TIP-0023/tip-0023.md) | ### Unlocks 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_ and the _Reference Unlock_ are 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 | -|-------------|------------|--------------------------------------------------------------| +| ----------- | ---------- | ------------------------------------------------------------ | | Signature | 0 | [TIP-45](#signature-unlock) | | Reference | 1 | [TIP-45](#reference-unlock) | | Account | 2 | [TIP-42](../TIP-0042/tip-0042.md#account-locking--unlocking) | @@ -469,7 +533,8 @@ The following table lists all the output types that are currently supported as w #### Signature Unlock -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: +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:
@@ -520,12 +585,15 @@ The Signature Unlock defines an Unlock which holds a signature sig ##### Unlock syntactic validation -* `Signature` must contain an _Ed25519 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. +- `Signature` must contain an _Ed25519 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 -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: +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:
@@ -549,95 +617,125 @@ The Reference Unlock defines an Unlock which references a previous ##### Unlock syntactic validation -* The _Reference Unlock_ at index i must have `Reference` < i and the unlock at index `Reference` must be a _Signature Unlock_. +- 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 Unlocks part: +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 Unlocks part: | Index | Unlock | -|-------|------------------------------------------------------------------------------------| +| ----- | ---------------------------------------------------------------------------------- | | 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. +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 [TIP-38](../TIP-0038/tip-0038.md), [TIP-1](../TIP-0042/tip-0041.md),[TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md) and [TIP-44](../TIP-0044/tip-0044.md) -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](../TIP-0038/tip-0038.md#output-design) and [feature type](../TIP-0038/tip-0038.md#features) separately. +The different output types and optional output features introduced by [TIP-38](../TIP-0038/tip-0038.md), +[TIP-1](../TIP-0042/tip-0041.md),[TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md) and +[TIP-44](../TIP-0044/tip-0044.md) 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](../TIP-0038/tip-0038.md#output-design) and [feature type](../TIP-0038/tip-0038.md#features) separately. ### Syntactic validation -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. +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: -* Essence: - * `Transaction Type` value must denote a _TIP-45 Transaction Essence_. - * `Network ID` must match the value of the current network. - * `CreationTime` must be a valid `Slot index` timestamp. - * Inputs: - * `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. - * For each input the following must be true: - * `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). - * `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. - * Context Inputs: - * `Context Inputs Count` must be 0 <= x ≤ `Max Inputs Count`. - * `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). - * There must be zero or one _Commitment Input_. - * All _Rewards Inputs_ must reference a different `Index`. - * _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - * All _Block Issuance Credits Inputs_ must reference a different `Account ID`. - * Outputs: - * `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. - * For each output 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`. - * The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. - * The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - * Allottments: - * `Allottments Count` must be 0 < x ≤ `Max Allottments Count`. - * The sum of all `Mana` fields must not exceed `Max Mana Supply`. - * There must be no duplicated `AccountID`s in the list of allotments. - * Payload (if present): - * `Payload Type` must match one of the values described under [Payload](#payload). - * 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_. - * 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. +- Essence: + - `Transaction Type` value must denote a _TIP-45 Transaction Essence_. + - `Network ID` must match the value of the current network. + - `CreationTime` must be a valid `Slot index` timestamp. + - Inputs: + - `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. + - For each input the following must be true: + - `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). + - `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. + - Context Inputs: + - `Context Inputs Count` must be 0 <= x ≤ `Max Inputs Count`. + - `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). + - There must be zero or one _Commitment Input_. + - All _Rewards Inputs_ must reference a different `Index`. + - _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. + - All _Block Issuance Credits Inputs_ must reference a different `Account ID`. + - Outputs: + - `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. + - For each output 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`. + - The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. + - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. + - Allottments: + - `Allottments Count` must be 0 < x ≤ `Max Allottments Count`. + - The sum of all `Mana` fields must not exceed `Max Mana Supply`. + - There must be no duplicated `AccountID`s in the list of allotments. + - Payload (if present): + - `Payload Type` must match one of the values described under [Payload](#payload). + - 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_. + - 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 -The Semantic validation of a _Transaction Payload_ is performed when its encapsulating block is confirmed. The semantic validity of transactions depends on the partial order in which they are processed. The solidification mechanism of the protocol ensures that all inputs will be processed only when all inputs are known valid, and not conflicting. +The Semantic validation of a _Transaction Payload_ is performed when its encapsulating block is confirmed. The semantic +validity of transactions depends on the partial order in which they are processed. The solidification mechanism of the +protocol ensures that all inputs will be processed only when all inputs are known valid, and not conflicting. -Processing transactions according to its partial-ordering enables users to spend UTXOs which are created at similar point in time, but the input transaction has not yet been confirmed by the network, as they will be processed by preserving thei input-output order relations. 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. +Processing transactions according to its partial-ordering enables users to spend UTXOs which are created at similar +point in time, but the input transaction has not yet been confirmed by the network, as they will be processed by +preserving thei input-output order relations. 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. #### Criteria defining 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 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is counted as one. -* 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. - -**Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): - * The transaction must not spend more mana than allowed, briefly it must given following definitions: -- `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and decay function -- `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. -- `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` -- `outputStoredMana` sum of stored mana from outputs -comply that: -`potentialMana` + `inputStoredMana` >= `allottedMana` + `outputStoredMana` -The less or equal sign in the formula above implies that it is possible for a user not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, a user does not want to own Mana att all. Then, the user must be able to refuse to allot or store their potential Mana. -More specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following validation rule for Mana: + +- 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 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must + not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is + counted as one. +- 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. + +**Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see +[TIP-39](../TIP-0039/tip-0039.md)): + +- The transaction must not spend more mana than allowed, briefly it must given following definitions: + +* `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and + decay function +* `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. +* `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` +* `outputStoredMana` sum of stored mana from outputs comply that: `potentialMana` + `inputStoredMana` >= + `allottedMana` + `outputStoredMana` The less or equal sign in the formula above implies that it is possible for a user + not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, + a user does not want to own Mana att all. Then, the user must be able to refuse to allot or store their potential + Mana. FMore specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following + validation rule for Mana: ```math \sum_{i \in \mathcal{I}}\Big[\text{Potential Mana Generated}_i + \text{Decayed Stored Mana}_i\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, @@ -645,6 +743,9 @@ More specifically, for a transaction consuming a set of unspent outputs $\mathca where: +- $\frac{\text{IOTA}_i}{\beta}*\Big(1 - e^{-\beta(t - t_i)}\Big)$ is the amount of potential Mana generated by consuming + output `i`; +- TODO ^ - $\text{Potential Mana Generated}_i$ is the amount of potential Mana generated by consuming output `i`. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. - $\text{Decayed Stored Mana}_i$ is the amount of stored Mana on the consuming output `i` with applied decay. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. - $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; @@ -653,44 +754,57 @@ where: - $\mathcal{A}$ is the set accounts to which Mana will be transferred as block issuance credit. #### Semantic criteria for each output and all its output features in the context of the following input: + 1. The _Transaction Payload_, 2. the list of UTXOs referenced by inputsF -* 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_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. - * If it is an _Account Unlock_: - * The address unlocking the UTXO must be an _Account Address_. - * The referenced _Unlock_ unlocks the account 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_ 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. - -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. + +- 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_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. + - If it is an _Account Unlock_: + - The address unlocking the UTXO must be an _Account Address_. + - The referenced _Unlock_ unlocks the account 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_ 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. + +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 ### 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. +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. -* It is not possible to produce a valid transaction without having access to the content of the consumed outputs. +- 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. +- It is not possible to produce a valid transaction without having access to the content of the consumed outputs. # Rationale and alternatives -* _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. +- _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 a2d70b461c323687d42e204f93b55ff937bf76a7 Mon Sep 17 00:00:00 2001 From: Roman Overko Date: Tue, 4 Jul 2023 18:05:15 +0200 Subject: [PATCH 023/122] Fix formatting, typos, Latex formulas --- tips/TIP-0045/tip-0045.md | 133 +++++++++++++++++++------------------- 1 file changed, 66 insertions(+), 67 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 240de99da..110d437ab 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -21,16 +21,16 @@ extends the transaction payload described in [TIP-20](../TIP-0007/tip-0020.md). # Motivation [TIP-20](../TIP-0020/tip-0020.md) introduced a new extended transaction model for the Stardust update. This TIP extends -this model to be aligned with all new mana and account features: +this model to be aligned with all new Mana and account features: - accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), - [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md). -- include an _Allotments_ field in the transaction for mana allotment of Block Issuance Credits, + [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md); +- include an _Allotments_ field in the transaction for Mana allotment of Block Issuance Credits; - updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA - 2.0 mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). + 2.0 Mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). The motivation of these changes is to adjust the transaction and its validation rules with the protocol upgrade to IOTA -2.0. Validation rules must now consider the mana decay factor and the possibility of mana allotment in the transaction +2.0. Validation rules must now consider the Mana decay factor and the possibility of Mana allotment in the transaction to a Block Issuance Credits account. # Detailed design @@ -45,10 +45,10 @@ 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 +- 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 @@ -65,7 +65,7 @@ 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. +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 @@ -97,7 +97,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Transaction Essence
- Describes the essence data making up a transaction by defining its inputs, outputs and an optional payload. + Describes the essence data making up a transaction by defining its inputs, outputs, and an optional payload.
@@ -116,7 +116,8 @@ The following table describes the entirety of a _Transaction Payload_ in its ser @@ -246,7 +247,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Allotment
- Allots mana value to indicated account. + Allots Mana value to indicated account.
Network ID uint64 - 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. + 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.
@@ -262,7 +263,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - +
Mana uint64 The amount of mana to allot to this account.The amount of Mana to allot to this account.
@@ -327,7 +328,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 +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. #### Network ID @@ -353,7 +354,7 @@ semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md) #### Context Inputs The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a -transaction, such as for different functionality related to accounts, commitments or Mana rewards. Context inputs do not +transaction, such as for different functionality related to accounts, commitments, or Mana rewards. Context inputs do not need to be unlocked. This TIP defines 3 types of context inputs: - _Commitment Input_ @@ -394,10 +395,10 @@ It is serialized as follows: A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer -Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is not negative at a specific point +Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple such -inputs can be present in a single transaction to provide the BIC value for different accounts, however no two _Block +inputs can be present in a single transaction to provide the BIC value for different accounts; however, no two _Block Issuance Credits Inputs_ can reference the same account. It is serialized as follows: @@ -426,7 +427,7 @@ A _Reward Input_ is an input that indicates which transaction `Input` is claimin _Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs -can be present in a single transaction to claim rewards for different outputs, however no two Reward Inputs can +can be present in a single transaction to claim rewards for different outputs; however, no two *Reward Inputs* can reference the same index. It is serialized as follows: @@ -452,9 +453,9 @@ It is serialized as follows: #### Inputs The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. -Currently, there are one type of input: +Currently, there is one type of input: -- _UTXO Input_ In the future, more types of inputs may be specified as part of protocol upgrades. +- _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 at the same index in the Unlocks part of the Transaction Payload. @@ -496,13 +497,13 @@ specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanc #### Allotments -The `Allotments` field contains the list of all mana allotments, the `Account ID` and corresponding values, that -converts mana provided by the inputs in form of stored UTXO mana in inputs or potential mana derived from inputs' IOTA +The `Allotments` field contains the list of all Mana allotments, the `Account ID`, and corresponding values that +converts Mana provided by the inputs in form of stored UTXO Mana in inputs or potential Mana derived from inputs' IOTA tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC vector of the slot that the transaction is issued in. Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the -issuance slot. The good practice would be to always allot enough mana to cover for the block issuance. +issuance slot. The good practice would be to always allot enough Mana to cover for the block issuance. #### Payload @@ -521,7 +522,7 @@ the corresponding specification: 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 +The following table lists all the unlock 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 | @@ -533,7 +534,7 @@ specification. The _Signature Unlock_ and the _Reference Unlock_ are specified a #### Signature Unlock -The Signature Unlock defines an Unlock which holds a signature signing the BLAKE2b-256 hash of the +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: @@ -586,7 +587,7 @@ The Signature Unlock defines an Unlock which holds a signature sig ##### Unlock syntactic validation - `Signature` must contain an _Ed25519 Signature_. -- The _Signature Unlock_ must be unique, i.e. there must not be any other _Signature Unlocks_ in the `Unlocks` field of +- 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 @@ -617,22 +618,22 @@ is serialized as follows: ##### Unlock syntactic validation -- The _Reference Unlock_ at index i must have `Reference` < i and the unlock at index `Reference` must be a _Signature +- 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 +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_ 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. | +| 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 +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 [TIP-38](../TIP-0038/tip-0038.md), @@ -654,20 +655,20 @@ The following criteria defines whether a payload passes the syntactical validati - `Network ID` must match the value of the current network. - `CreationTime` must be a valid `Slot index` timestamp. - Inputs: - - `Inputs Count` must be 0 < x ≤ `Max Inputs Count`. + - `Inputs Count` must be `0 < x ≤ Max Inputs Count`. - For each input the following must be true: - `Input Type` must denote an allowed input type, listed in section [Inputs](#inputs). - - `Transaction Output Index` must be 0 ≤ x < `Max Outputs Count`. + - `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. - Context Inputs: - - `Context Inputs Count` must be 0 <= x ≤ `Max Inputs Count`. + - `Context Inputs Count` must be `0 ≤ x ≤ Max Inputs Count`. - `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). - There must be zero or one _Commitment Input_. - All _Rewards Inputs_ must reference a different `Index`. - _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - All _Block Issuance Credits Inputs_ must reference a different `Account ID`. - Outputs: - - `Outputs Count` must be 0 < x ≤ `Max Outputs Count`. + - `Outputs Count` must be `0 < x ≤ Max Outputs Count`. - For each output the following must be true: - `Output Type` must match one of the values described under [Outputs](#outputs). - The output itself must pass syntactic validation. @@ -675,7 +676,7 @@ The following criteria defines whether a payload passes the syntactical validati - The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - Allottments: - - `Allottments Count` must be 0 < x ≤ `Max Allottments Count`. + - `Allottments Count` must be `0 < x ≤ Max Allottments Count`. - The sum of all `Mana` fields must not exceed `Max Mana Supply`. - There must be no duplicated `AccountID`s in the list of allotments. - Payload (if present): @@ -698,16 +699,16 @@ protocol ensures that all inputs will be processed only when all inputs are know Processing transactions according to its partial-ordering enables users to spend UTXOs which are created at similar point in time, but the input transaction has not yet been confirmed by the network, as they will be processed by -preserving thei input-output order relations. In this case, it is recommended that users include the _Block ID_ of the +preserving their input-output order relations. 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. #### Criteria defining 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 +- 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 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 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is @@ -716,44 +717,42 @@ funding transaction as a parent of the block containing the spending transaction 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 + 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. -**Mana specific semantic validation rules** (for description of mana dynamics and the mana decay, see +**Mana specific semantic validation rules** (for description of Mana dynamics and the Mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): -- The transaction must not spend more mana than allowed, briefly it must given following definitions: +- The transaction must not spend more Mana than allowed, briefly it must given following definitions: * `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and decay function * `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. -* `inputStoredMana` sum of stored mana from inputs decayed by `Decayfactor` -* `outputStoredMana` sum of stored mana from outputs comply that: `potentialMana` + `inputStoredMana` >= - `allottedMana` + `outputStoredMana` The less or equal sign in the formula above implies that it is possible for a user +* `inputStoredMana` sum of stored Mana from inputs decayed by `Decayfactor` +* `outputStoredMana` sum of stored Mana from outputs comply that: `potentialMana + inputStoredMana ≥ + allottedMana + outputStoredMana` The less or equal sign in the formula above implies that it is possible for a user not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, - a user does not want to own Mana att all. Then, the user must be able to refuse to allot or store their potential - Mana. FMore specifically, for a transaction consuming a set of unspent outputs $\mathcal{I}$, we have the following + a user does not want to own Mana at all. Then, the user must be able to refuse to allot or store their potential + Mana. More specifically, for a transaction consuming a set of unspent outputs, we have the following validation rule for Mana: -```math -\sum_{i \in \mathcal{I}}\Big[\text{Potential Mana Generated}_i + \text{Decayed Stored Mana}_i\Big] \geq \sum_{o\in \mathcal{O}}\text{Mana}_o + \sum_{a\in \mathcal{A}}\text{Mana}_a, -``` +`Potential Mana Generated + Decayed Stored Mana ≥ Manao + Manaa`, where: -- $\text{Potential Mana Generated}_i$ is the amount of potential Mana generated by consuming output `i`. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. -- $\text{Decayed Stored Mana}_i$ is the amount of stored Mana on the consuming output `i` with applied decay. To calculate this value, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. -- $\text{Mana}_o$ is the amount of Mana transferred to output `o` as stored Mana; -- $\text{Mana}_a$ is the amount of Mana transferred to account `a` as block issuance credit; -- $\mathcal{O}$ is the set outputs to which Mana will be transferred as stored Mana; -- $\mathcal{A}$ is the set accounts to which Mana will be transferred as block issuance credit. +- `Potential Mana Generated` is the sum of all potential Mana values generated by consuming inputs (unspent outputs). + To calculate each summand of the sum, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. +- `Decayed Stored Mana` is the sum of all stored Mana values on the consuming inputs (unspent outputs) with applied decay. + To calculate each summand of the sum, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. +- Manao is the sum of all Mana values transferred to the outputs as stored Mana. +- Manaa is the amount of all Mana values transferred to the accounts as block issuance credit. #### Semantic criteria for each output and all its output features in the context of the following input: - 1. The _Transaction Payload_, - 2. the list of UTXOs referenced by inputsF + 1. The _Transaction Payload_. + 2. The list of UTXOs referenced by inputs. - Each unlock must be valid with respect to the UTXO referenced by the input of the same index: - If it is a _Signature Unlock_: @@ -765,7 +764,7 @@ where: - The address unlocking the UTXO must be an _Account Address_. - The referenced _Unlock_ unlocks the account 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 address unlocking the UTXO must be an _NFT Address_. - 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 @@ -789,15 +788,15 @@ used deposit address. Ed25519 addresses are not meant to be used like email addr # 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 + 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. - It is not possible to produce a valid transaction without having access to the content of the consumed outputs. # Rationale and alternatives -- _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 +- _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. From e4a1dbcff52a7c68bddf69fdf9ad8c8a3b40ac69 Mon Sep 17 00:00:00 2001 From: Roman Overko Date: Tue, 4 Jul 2023 18:09:47 +0200 Subject: [PATCH 024/122] Improve backquote formulas --- tips/TIP-0045/tip-0045.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 110d437ab..887239ec7 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -738,7 +738,7 @@ funding transaction as a parent of the block containing the spending transaction Mana. More specifically, for a transaction consuming a set of unspent outputs, we have the following validation rule for Mana: -`Potential Mana Generated + Decayed Stored Mana ≥ Manao + Manaa`, +Potential Mana Generated + Decayed Stored Mana ≥ Manao + Manaa, where: @@ -747,14 +747,14 @@ where: - `Decayed Stored Mana` is the sum of all stored Mana values on the consuming inputs (unspent outputs) with applied decay. To calculate each summand of the sum, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. - Manao is the sum of all Mana values transferred to the outputs as stored Mana. -- Manaa is the amount of all Mana values transferred to the accounts as block issuance credit. +- Manaa is the amount of all Mana values transferred to the accounts as block issuance credit. #### Semantic criteria for each output and all its output features in the context of the following input: - 1. The _Transaction Payload_. - 2. The list of UTXOs referenced by inputs. +1. The _Transaction Payload_. +2. The list of UTXOs referenced by inputs. -- Each unlock must be valid with respect to the UTXO referenced by the input of the same index: +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 From fb1be1fb14b17039e307f47d126eb30a34a1b583 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 12 Jul 2023 12:55:03 +0200 Subject: [PATCH 025/122] Add Table of Contents and format --- tips/TIP-0045/tip-0045.md | 107 +++++++++++++++++++++++--------------- 1 file changed, 65 insertions(+), 42 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 887239ec7..af3594555 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -12,6 +12,25 @@ requires: TIP-39, TIP-41, TIP-42, TIP-43 and TIP-44 replaces: TIP-20 --- +# Table of Contents + +1. [Summary](#summary) +2. [Motivation](#motivation) +3. [Detailed Design](#detailed-design) + - [UTXO](#utxo) + - [Transaction Structure](#transaction-structure) + - [Serialized Layout](#serialized-layout) + - [Essence](#essence) + - [Unlocks](#unlocks) + - [Validation](#validation) + - [Syntactic Validation](#syntactic-validation) + - [Semantic Validation](#semantic-validation) + - [Miscellaneous](#miscellaneous) + - [Address reuse](#address-reuse) +4. [Drawbacks](#drawbacks) +5. [Rationale and Alternatives](#rationale-and-alternatives) +6. [Copyright](#copyright) + # Summary This TIP proposes a new UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. @@ -59,9 +78,9 @@ The following image depicts the flow of funds using UTXO: ![UTXO flow](utxo.png) -## Structure +## Transaction Structure -### Serialized layout +### Serialized Layout A _Transaction Payload_ is made up of two parts: @@ -325,7 +344,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
-### Transaction Essence +### 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, @@ -354,8 +373,8 @@ semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md) #### Context Inputs The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a -transaction, such as for different functionality related to accounts, commitments, or Mana rewards. Context inputs do not -need to be unlocked. This TIP defines 3 types of context inputs: +transaction, such as for different functionality related to accounts, commitments, or Mana rewards. Context inputs do +not need to be unlocked. This TIP defines 3 types of context inputs: - _Commitment Input_ - _Block Issuance Credits Input_ @@ -427,7 +446,7 @@ A _Reward Input_ is an input that indicates which transaction `Input` is claimin _Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs -can be present in a single transaction to claim rewards for different outputs; however, no two *Reward Inputs* can +can be present in a single transaction to claim rewards for different outputs; however, no two _Reward Inputs_ can reference the same index. It is serialized as follows: @@ -622,11 +641,11 @@ is serialized as follows: 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 Unlocks part: +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 | -| ----- | ---------------------------------------------------------------------------------- | +| Index | Unlock | +| ----- | ------------------------------------------------------------------------------------ | | 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`. | @@ -706,10 +725,11 @@ funding transaction as a parent of the block containing the spending transaction - 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 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. +- `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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is counted as one. @@ -718,9 +738,9 @@ funding transaction as a parent of the block containing the spending transaction 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. + - **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. **Mana specific semantic validation rules** (for description of Mana dynamics and the Mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): @@ -731,21 +751,23 @@ funding transaction as a parent of the block containing the spending transaction decay function * `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. * `inputStoredMana` sum of stored Mana from inputs decayed by `Decayfactor` -* `outputStoredMana` sum of stored Mana from outputs comply that: `potentialMana + inputStoredMana ≥ - allottedMana + outputStoredMana` The less or equal sign in the formula above implies that it is possible for a user - not to allot all the Mana he/she has rights to. This requirement is needed in the case, because of any particularity, - a user does not want to own Mana at all. Then, the user must be able to refuse to allot or store their potential - Mana. More specifically, for a transaction consuming a set of unspent outputs, we have the following - validation rule for Mana: +* `outputStoredMana` sum of stored Mana from outputs comply that: + `potentialMana + inputStoredMana ≥ allottedMana + outputStoredMana` The less or equal sign in the formula above + implies that it is possible for a user not to allot all the Mana he/she has rights to. This requirement is needed in + the case, because of any particularity, a user does not want to own Mana at all. Then, the user must be able to refuse + to allot or store their potential Mana. More specifically, for a transaction consuming a set of unspent outputs, we + have the following validation rule for Mana: Potential Mana Generated + Decayed Stored Mana ≥ Manao + Manaa, where: -- `Potential Mana Generated` is the sum of all potential Mana values generated by consuming inputs (unspent outputs). - To calculate each summand of the sum, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. -- `Decayed Stored Mana` is the sum of all stored Mana values on the consuming inputs (unspent outputs) with applied decay. - To calculate each summand of the sum, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be used. +- `Potential Mana Generated` is the sum of all potential Mana values generated by consuming inputs (unspent outputs). To + calculate each summand of the sum, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be + used. +- `Decayed Stored Mana` is the sum of all stored Mana values on the consuming inputs (unspent outputs) with applied + decay. To calculate each summand of the sum, the algorithm and lookup table defined in + [TIP-39](../TIP-0039/tip-0039.md) must be used. - Manao is the sum of all Mana values transferred to the outputs as stored Mana. - Manaa is the amount of all Mana values transferred to the accounts as block issuance credit. @@ -755,17 +777,18 @@ where: 2. The list of UTXOs referenced by inputs. 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_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. - - If it is an _Account Unlock_: - - The address unlocking the UTXO must be an _Account Address_. - - The referenced _Unlock_ unlocks the account defined by the unlocking address of the UTXO. - - If it is an _NFT Unlock_: - - The address unlocking the UTXO must be an _NFT Address_. - - The referenced _Unlock_ unlocks the NFT defined by the unlocking address of the UTXO. + +- 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_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. +- If it is an _Account Unlock_: + - The address unlocking the UTXO must be an _Account Address_. + - The referenced _Unlock_ unlocks the account defined by the unlocking address of the UTXO. +- If it is an _NFT Unlock_: + - The address unlocking the UTXO must be an _NFT Address_. + - 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. @@ -788,12 +811,12 @@ used deposit address. Ed25519 addresses are not meant to be used like email addr # 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. + 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. - It is not possible to produce a valid transaction without having access to the content of the consumed outputs. -# Rationale and alternatives +# Rationale and Alternatives - _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 From 614f4509624e509b0676d436fe0b0722f4725d2d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 12 Jul 2023 13:18:47 +0200 Subject: [PATCH 026/122] Rename BIC Input --- tips/TIP-0045/tip-0045.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index af3594555..14905c019 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -161,7 +161,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
- Block Issuance Credits Input + Block Issuance Credit Input
Describes an input which resolves to a BIC value of an account.
@@ -377,7 +377,7 @@ transaction, such as for different functionality related to accounts, commitment not need to be unlocked. This TIP defines 3 types of context inputs: - _Commitment Input_ -- _Block Issuance Credits Input_ +- _Block Issuance Credit Input_ - _Reward Input_ ##### Commitment Input @@ -410,12 +410,12 @@ It is serialized as follows:
-##### Block Issuance Credits Input +##### Block Issuance Credit Input -A _Block Issuance Credits Input_ is an input that provides the VM with context for the value of the BIC vector of a +A _Block Issuance Credit Input_ is an input that provides the VM with context for the value of the BIC vector of a specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point -in time. A _Block Issuance Credits Input_ always requires a _Commitment Input_. The input will be resolved to the BIC +in time. A _Block Issuance Credit Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple such inputs can be present in a single transaction to provide the BIC value for different accounts; however, no two _Block Issuance Credits Inputs_ can reference the same account. @@ -431,7 +431,7 @@ It is serialized as follows: Context Input Type uint8 - Set to value 1 to denote a Block Issuance Credits Input. + Set to value 1 to denote a Block Issuance Credit Input. Account ID @@ -685,7 +685,7 @@ The following criteria defines whether a payload passes the syntactical validati - There must be zero or one _Commitment Input_. - All _Rewards Inputs_ must reference a different `Index`. - _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - - All _Block Issuance Credits Inputs_ must reference a different `Account ID`. + - All _Block Issuance Credit Inputs_ must reference a different `Account ID`. - Outputs: - `Outputs Count` must be `0 < x ≤ Max Outputs Count`. - For each output the following must be true: From 68f81dfa6d80935e825ec614d6ec15eb412fdd39 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 12 Jul 2023 14:47:44 +0200 Subject: [PATCH 027/122] Add reward input index <= max inputs count rule --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 14905c019..a3d4f03ea 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -683,8 +683,7 @@ The following criteria defines whether a payload passes the syntactical validati - `Context Inputs Count` must be `0 ≤ x ≤ Max Inputs Count`. - `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). - There must be zero or one _Commitment Input_. - - All _Rewards Inputs_ must reference a different `Index`. - - _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. + - All _Rewards Inputs_ must reference a different `Index` and it must hold that: `Index <= Max Inputs Count`. - All _Block Issuance Credit Inputs_ must reference a different `Account ID`. - Outputs: - `Outputs Count` must be `0 < x ≤ Max Outputs Count`. @@ -728,6 +727,7 @@ funding transaction as a parent of the block containing the spending transaction - `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. +- All _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must From 254311d22f9870997c787794bb42432158ab7275 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 14 Jul 2023 11:51:13 +0200 Subject: [PATCH 028/122] Fix `Public Key` casing --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index a3d4f03ea..2bdef8161 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -588,7 +588,7 @@ The Signature Unlock defines an Unlock, which holds a signature si - Public key + Public Key ByteArray[32] The Ed25519 public key of the signature. From 4945342aa926f8d905fdc337999666ad1a26b5cf Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 2 Aug 2023 12:47:13 +0200 Subject: [PATCH 029/122] Add other new fields to change summary --- tips/TIP-0045/tip-0045.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 2bdef8161..7c2b21127 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -44,7 +44,9 @@ this model to be aligned with all new Mana and account features: - accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md); -- include an _Allotments_ field in the transaction for Mana allotment of Block Issuance Credits; +- add the _Allotments_ field in the transaction for adding Mana to an Account's Block Issuance Credits; +- add the _Context Inputs_ field in the transaction for non-UTXO inputs that provide contextual information for the transaction; +- add the _Creation Slot_ field that is the index of the slot in which the transaction was created; - updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA 2.0 Mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). From c0fcdec164a6b18058d93e19c373002f00e7b3cb Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 2 Aug 2023 12:47:33 +0200 Subject: [PATCH 030/122] Add Delegation Output to allowed TX outputs --- tips/TIP-0045/tip-0045.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 7c2b21127..a6cd5e348 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -255,6 +255,12 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Describes a unique, non-fungible token deposit to a single address.
+
+ Delegation Output +
+ Describes a Delegation Output, which delegates its contained IOTA tokens to a validator. +
+
From c98d1a5d20c0e033b04147ed2d4df21036838bc5 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 2 Aug 2023 12:51:51 +0200 Subject: [PATCH 031/122] Fix typo, clarify BIC allotment --- tips/TIP-0045/tip-0045.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index a6cd5e348..10cefcfab 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -45,7 +45,8 @@ this model to be aligned with all new Mana and account features: - accommodate for the new output types introduced in [TIP-41](../TIP-0041/tip-0041.md), [TIP-42](../TIP-0042/tip-0042.md), [TIP-43](../TIP-0043/tip-0043.md), [TIP-44](../TIP-0044/tip-0044.md); - add the _Allotments_ field in the transaction for adding Mana to an Account's Block Issuance Credits; -- add the _Context Inputs_ field in the transaction for non-UTXO inputs that provide contextual information for the transaction; +- add the _Context Inputs_ field in the transaction for non-UTXO inputs that provide contextual information for the + transaction; - add the _Creation Slot_ field that is the index of the slot in which the transaction was created; - updates the syntactic validation rules to ensure the correctness of input and output Mana balances according to IOTA 2.0 Mana requirements, defined in [TIP-39](../TIP-0039/tip-0039.md). @@ -525,9 +526,9 @@ specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanc #### Allotments The `Allotments` field contains the list of all Mana allotments, the `Account ID`, and corresponding values that -converts Mana provided by the inputs in form of stored UTXO Mana in inputs or potential Mana derived from inputs' IOTA -tokes. Mana listed in this field will be added on the slot commitment, in form of _Block Issuance Credits_ to the BIC -vector of the slot that the transaction is issued in. +converts Mana provided by the inputs in form of stored Mana in inputs or potential Mana derived from the inputs' IOTA +tokens. Mana listed in this field will be added upon commitment of the slot in which the transaction was issued, in form +of _Block Issuance Credits_ to the account's BIC value. Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough Mana to cover for the block issuance. From 94cc2c1fa7cc413c97a979329e41af4509336e1f Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 14 Aug 2023 09:32:21 +0200 Subject: [PATCH 032/122] Add lexicographic constraint for `Allotments` --- tips/TIP-0045/tip-0045.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 10cefcfab..84db1cab1 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -706,6 +706,7 @@ The following criteria defines whether a payload passes the syntactical validati - `Allottments Count` must be `0 < x ≤ Max Allottments Count`. - The sum of all `Mana` fields must not exceed `Max Mana Supply`. - There must be no duplicated `AccountID`s in the list of allotments. + - Each entry in `Allotments` must be lexicographically ordered based on its `Account ID`. - Payload (if present): - `Payload Type` must match one of the values described under [Payload](#payload). - Payload fields must be correctly parsable in the context of the `Payload Type`. From e596148ba2e5ae9ad6f77f190577778dd14b4c34 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 14 Aug 2023 09:33:10 +0200 Subject: [PATCH 033/122] Fix `Allotments` misspelling --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 84db1cab1..d55ab12cb 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -702,8 +702,8 @@ The following criteria defines whether a payload passes the syntactical validati - The sum of all `Amount` fields must not exceed `Max IOTA Supply`. - The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - - Allottments: - - `Allottments Count` must be `0 < x ≤ Max Allottments Count`. + - Allotments: + - `Allotments Count` must be `0 < x ≤ Max Allotments Count`. - The sum of all `Mana` fields must not exceed `Max Mana Supply`. - There must be no duplicated `AccountID`s in the list of allotments. - Each entry in `Allotments` must be lexicographically ordered based on its `Account ID`. From 085f7b4328f7232fa296ad6942c12a39d918fc4d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 14 Aug 2023 12:30:03 +0200 Subject: [PATCH 034/122] Implement phrasing suggestions from reviewers --- tips/TIP-0045/tip-0045.md | 50 +++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index d55ab12cb..bf581cf46 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -146,7 +146,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser Creation Slot uint64 - The slot index of the block in which the transaction was created. + The slot index in which the transaction was created. @@ -391,10 +391,10 @@ not need to be unlocked. This TIP defines 3 types of context inputs: ##### Commitment Input -A _Commitment Input_ is an input that allows to reference a commitment to a certain slot. It is used to provide a notion -of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at -the transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference -is expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The +A _Commitment Input_ allows referencing a commitment to a certain slot. It is used to provide a notion of time for +transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at the +transaction execution is past a certain slot in the past, as the slot has already been committed. The slot reference is +expressed as the _Commitment ID_ and can be resolved to the _Commitment_ value before executing the transaction. The _Commitment_ itself provides the `Slot Index` which serves as the time reference. A Block that contains a transaction with a Commitment input has additional validation rules as defined in [TIP-0046](../TIP-0046/tip-0046.md). Only one _Commitment Input_ may be present in a transaction. @@ -421,13 +421,13 @@ It is serialized as follows: ##### Block Issuance Credit Input -A _Block Issuance Credit Input_ is an input that provides the VM with context for the value of the BIC vector of a -specific slot. It is required for any _Account_ transitions and destruction if the account contains a _Block Issuer -Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point -in time. A _Block Issuance Credit Input_ always requires a _Commitment Input_. The input will be resolved to the BIC -value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple such -inputs can be present in a single transaction to provide the BIC value for different accounts; however, no two _Block -Issuance Credits Inputs_ can reference the same account. +A _Block Issuance Credit Input_ provides the VM with context for the value of the BIC vector of a specific slot. It is +required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any +operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point in time. A _Block +Issuance Credit Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account +identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple such inputs can be present in a +single transaction to provide the BIC value for different accounts; however, no two _Block Issuance Credits Inputs_ can +reference the same account. It is serialized as follows: @@ -451,12 +451,11 @@ It is serialized as follows: ##### Reward Input -A _Reward Input_ is an input that indicates which transaction `Input` is claiming Mana rewards. It can reference an -_Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total -amount of rewards the respective output can claim which is provided as context for transaction execution. The amount of -rewards that can be claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs -can be present in a single transaction to claim rewards for different outputs; however, no two _Reward Inputs_ can -reference the same index. +A _Reward Input_ indicates which transaction `Input` is claiming Mana rewards. It can reference an _Account Output_ with +a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the +respective output can claim which is provided as context for transaction execution. The amount of rewards that can be +claimed is added to the total sum of Mana on the input side of the transaction. Multiple such inputs can be present in a +single transaction to claim rewards for different outputs; however, no two _Reward Inputs_ can reference the same index. It is serialized as follows: @@ -526,9 +525,9 @@ specification. The _SigLockedSingleOutput_ as well as the _SigLockedDustAllowanc #### Allotments The `Allotments` field contains the list of all Mana allotments, the `Account ID`, and corresponding values that -converts Mana provided by the inputs in form of stored Mana in inputs or potential Mana derived from the inputs' IOTA -tokens. Mana listed in this field will be added upon commitment of the slot in which the transaction was issued, in form -of _Block Issuance Credits_ to the account's BIC value. +converts Mana provided by the inputs in the form of stored Mana in inputs or potential Mana derived from the inputs' +IOTA tokens. Mana listed in this field will be added upon commitment of the slot in which the transaction was issued, in +form of _Block Issuance Credits_ to the account's BIC value. Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough Mana to cover for the block issuance. @@ -562,8 +561,8 @@ specification. The _Signature Unlock_ and the _Reference Unlock_ are specified a #### Signature Unlock -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: +The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including +the optional payload). It is serialized as follows: @@ -620,9 +619,8 @@ The Signature Unlock defines an Unlock, which holds a signature si #### Reference Unlock -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: +The Reference Unlock 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:
From 4b8ecf8e3261fd984cec7e96ed0d59c63edaf873 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 14 Aug 2023 15:52:30 +0200 Subject: [PATCH 035/122] Fix concept typo --- tips/TIP-0047/tip-0047.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0047/tip-0047.md b/tips/TIP-0047/tip-0047.md index db76ef3f2..0384eb0f3 100644 --- a/tips/TIP-0047/tip-0047.md +++ b/tips/TIP-0047/tip-0047.md @@ -14,7 +14,7 @@ replaces: TIP-19 ## Summary -This document describes a `dust protection` concept, called `storage deposit` which was originally introduced in TIP-19. This cocnept creates a monetary incentive to keep the ledger state small. This is achieved by enforcing a minimum IOTA coin deposit in every output based on the actually used disc space of the output itself. +This document describes a `dust protection` concept, called `storage deposit` which was originally introduced in TIP-19. This concept creates a monetary incentive to keep the ledger state small. This is achieved by enforcing a minimum IOTA coin deposit in every output based on the actually used disc space of the output itself. This document minimally extends on TIP-19 by allowing for additional weights to be defined in other TIPs and no longer includes the deposit calculation for each individual output. Instead, each TIP defining outputs has to include the deposit calculation. From b4ad7dbfe8d9c3cdda8675792badabc92da6e2a8 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 4 Sep 2023 12:30:24 +0200 Subject: [PATCH 036/122] Add Max Mana check & Allotment Mana > 0 --- tips/TIP-0045/tip-0045.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index bf581cf46..d702ee4c9 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -698,11 +698,12 @@ The following criteria defines whether a payload passes the syntactical validati - `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`. - - The sum of all `Mana Amount` field must not exceed `Max Mana Supply`. + - The sum of all `Mana` fields must not exceed `2^Mana Bits Exponent - 1`. - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - Allotments: - - `Allotments Count` must be `0 < x ≤ Max Allotments Count`. - - The sum of all `Mana` fields must not exceed `Max Mana Supply`. + - `Allotments Count` must be `0 ≤ x ≤ 128`. + - The sum of all `Mana` fields must not exceed `2^Mana Bits Exponent - 1`. + - Every `Mana` field in an Allotment must be `> 0`. - There must be no duplicated `AccountID`s in the list of allotments. - Each entry in `Allotments` must be lexicographically ordered based on its `Account ID`. - Payload (if present): From cf3ab2270855b170518d8c369d5f193c049aa8a6 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 13 Sep 2023 11:35:09 +0200 Subject: [PATCH 037/122] Use `Mana Bits Count` --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index d702ee4c9..d4bb5c003 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -698,11 +698,11 @@ The following criteria defines whether a payload passes the syntactical validati - `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`. - - The sum of all `Mana` fields must not exceed `2^Mana Bits Exponent - 1`. + - The sum of all `Mana` fields must not exceed `2^Mana Bits Count - 1`. - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - Allotments: - `Allotments Count` must be `0 ≤ x ≤ 128`. - - The sum of all `Mana` fields must not exceed `2^Mana Bits Exponent - 1`. + - The sum of all `Mana` fields must not exceed `2^Mana Bits Count - 1`. - Every `Mana` field in an Allotment must be `> 0`. - There must be no duplicated `AccountID`s in the list of allotments. - Each entry in `Allotments` must be lexicographically ordered based on its `Account ID`. From d59cd41be79d2d845f7ccce237b4749fc0c1b7d6 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 15 Sep 2023 10:28:47 +0200 Subject: [PATCH 038/122] Update BIC Input description --- tips/TIP-0045/tip-0045.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index d4bb5c003..6a09eae83 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -425,9 +425,9 @@ A _Block Issuance Credit Input_ provides the VM with context for the value of th required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point in time. A _Block Issuance Credit Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account -identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple such inputs can be present in a -single transaction to provide the BIC value for different accounts; however, no two _Block Issuance Credits Inputs_ can -reference the same account. +identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple _Block Issuance Credit Inputs_ +can be present in a single transaction to provide the BIC for different accounts; however, no two _Block Issuance +Credits Inputs_ can reference the same account. It is serialized as follows: @@ -445,7 +445,7 @@ It is serialized as follows: - +
Account ID ByteArray[32]The BIC of an account to use.The ID of the Account for which this input provides the BIC.
From a7404961b28c7cac5b0aa7ee016db3b1a793967b Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 19 Sep 2023 14:11:22 +0200 Subject: [PATCH 039/122] Add transaction work score --- tips/TIP-0045/tip-0045.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 6a09eae83..c527224c6 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -657,6 +657,23 @@ in the following structure of the Unlocks part: | 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`. | +### Work Score + +Let the work score of a transaction be defined as follows. + +- Let `Input Score` be `Inputs Count * Input`. +- Let `Context Input Score` be `Context Inputs Count * Context Input`. +- Let `Output Score` be the sum of work scores of each output `UTXO Output` in `Outputs`: + - Let `Native Token Score` be `Native Token * Native Tokens Count` if `UTXO Output` contains `Native Tokens`. + - Let `Token Scheme Score` be `Native Token` if `UTXO Output` contains a _Simple Token Scheme_, `0` otherwise. + - Let `Staking Score` be `Staking` if `UTXO Output` contains a _Staking Feature_, `0` otherwise. + - Let `Block Issuer Score` be `Block Issuer` if `UTXO Output` contains a _Block Issuer Feature_, `0` otherwise. + - Return `Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. +- Let `Allotment Score` be `Allotment * Allotments Count`. +- Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ within `Unlocks`. + - Signature work scores are defined in TIP-46. +- Return `Input Score + Context Input Score + Output Score + Allotment Score + Signature Score`. + ## Validation A Transaction Payload has different validation stages since some validation steps can only be executed when From fbb1cadbd0d8c55bacadc8ccbee4615821837a35 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 19 Sep 2023 14:48:40 +0200 Subject: [PATCH 040/122] Add Work Score to ToC --- tips/TIP-0045/tip-0045.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index c527224c6..df93a1446 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -22,6 +22,7 @@ replaces: TIP-20 - [Serialized Layout](#serialized-layout) - [Essence](#essence) - [Unlocks](#unlocks) + - [Work Score](#work-score) - [Validation](#validation) - [Syntactic Validation](#syntactic-validation) - [Semantic Validation](#semantic-validation) From 2ef6ae4ea10959f3572f590cfad32838fae2ded6 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 20 Sep 2023 13:32:26 +0200 Subject: [PATCH 041/122] Align with new proto parameter names --- tips/TIP-0045/tip-0045.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index df93a1446..9d33ac515 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -662,15 +662,16 @@ in the following structure of the Unlocks part: Let the work score of a transaction be defined as follows. -- Let `Input Score` be `Inputs Count * Input`. -- Let `Context Input Score` be `Context Inputs Count * Context Input`. -- Let `Output Score` be the sum of work scores of each output `UTXO Output` in `Outputs`: - - Let `Native Token Score` be `Native Token * Native Tokens Count` if `UTXO Output` contains `Native Tokens`. - - Let `Token Scheme Score` be `Native Token` if `UTXO Output` contains a _Simple Token Scheme_, `0` otherwise. - - Let `Staking Score` be `Staking` if `UTXO Output` contains a _Staking Feature_, `0` otherwise. - - Let `Block Issuer Score` be `Block Issuer` if `UTXO Output` contains a _Block Issuer Feature_, `0` otherwise. - - Return `Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. -- Let `Allotment Score` be `Allotment * Allotments Count`. +- Let `Input Score` be `Inputs Count * Work Score Input`. +- Let `Context Input Score` be `Context Inputs Count * Work Score Context Input`. +- Let `Output Score` be the sum of work scores of each output `Output` in `Outputs`: + - Let `Native Token Score` be `Work Score Native Token * Native Tokens Count` if `Output` contains `Native Tokens`, + `0` otherwise. + - Let `Token Scheme Score` be `Work Score Native Token` if `Output` contains a _Simple Token Scheme_, `0` otherwise. + - Let `Staking Score` be `Work Score Staking` if `Output` contains a _Staking Feature_, `0` otherwise. + - Let `Block Issuer Score` be `Work Score Block Issuer` if `Output` contains a _Block Issuer Feature_, `0` otherwise. + - Return `Work Score Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. +- Let `Allotment Score` be `Work Score Allotment * Allotments Count`. - Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ within `Unlocks`. - Signature work scores are defined in TIP-46. - Return `Input Score + Context Input Score + Output Score + Allotment Score + Signature Score`. From 6ba82e5ddc15bb10e3bf7928c40c376cea734afc Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 22 Sep 2023 14:13:28 +0200 Subject: [PATCH 042/122] Use namespacing for work score parameters --- tips/TIP-0045/tip-0045.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 9d33ac515..4b6762901 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -662,16 +662,19 @@ in the following structure of the Unlocks part: Let the work score of a transaction be defined as follows. -- Let `Input Score` be `Inputs Count * Work Score Input`. -- Let `Context Input Score` be `Context Inputs Count * Work Score Context Input`. +- Let `Input Score` be `Inputs Count * Work Score Structure::Input`. +- Let `Context Input Score` be `Context Inputs Count * Work Score Structure::Context Input`. - Let `Output Score` be the sum of work scores of each output `Output` in `Outputs`: - - Let `Native Token Score` be `Work Score Native Token * Native Tokens Count` if `Output` contains `Native Tokens`, - `0` otherwise. - - Let `Token Scheme Score` be `Work Score Native Token` if `Output` contains a _Simple Token Scheme_, `0` otherwise. - - Let `Staking Score` be `Work Score Staking` if `Output` contains a _Staking Feature_, `0` otherwise. - - Let `Block Issuer Score` be `Work Score Block Issuer` if `Output` contains a _Block Issuer Feature_, `0` otherwise. - - Return `Work Score Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. -- Let `Allotment Score` be `Work Score Allotment * Allotments Count`. + - Let `Native Token Score` be `Work Score Structure::Native Token * Native Tokens Count` if `Output` contains + `Native Tokens`, `0` otherwise. + - Let `Token Scheme Score` be `Work Score Structure::Native Token` if `Output` contains a _Simple Token Scheme_, `0` + otherwise. + - Let `Staking Score` be `Work Score Structure::Staking` if `Output` contains a _Staking Feature_, `0` otherwise. + - Let `Block Issuer Score` be `Work Score Structure::Block Issuer` if `Output` contains a _Block Issuer Feature_, `0` + otherwise. + - Return + `Work Score Structure::Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. +- Let `Allotment Score` be `Work Score Structure::Allotment * Allotments Count`. - Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ within `Unlocks`. - Signature work scores are defined in TIP-46. - Return `Input Score + Context Input Score + Output Score + Allotment Score + Signature Score`. From d30714e558b5aee7704d08d8337d0108d8970949 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 25 Sep 2023 16:59:45 +0200 Subject: [PATCH 043/122] Add transaction size in work score --- tips/TIP-0045/tip-0045.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 4b6762901..58451c15f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -662,6 +662,8 @@ in the following structure of the Unlocks part: Let the work score of a transaction be defined as follows. +- Let `Size Score` be `Work Score Structure::DataByte * Transaction Size` where `Transaction Size` is the size of the + serialized _Transaction_. - Let `Input Score` be `Inputs Count * Work Score Structure::Input`. - Let `Context Input Score` be `Context Inputs Count * Work Score Structure::Context Input`. - Let `Output Score` be the sum of work scores of each output `Output` in `Outputs`: @@ -677,7 +679,7 @@ Let the work score of a transaction be defined as follows. - Let `Allotment Score` be `Work Score Structure::Allotment * Allotments Count`. - Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ within `Unlocks`. - Signature work scores are defined in TIP-46. -- Return `Input Score + Context Input Score + Output Score + Allotment Score + Signature Score`. +- Return `Size Score + Input Score + Context Input Score + Output Score + Allotment Score + Signature Score`. ## Validation From 21fc627700928b408111145f5d010855078fc338 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 26 Sep 2023 17:30:09 +0200 Subject: [PATCH 044/122] Fix sparsity typo --- tips/TIP-0047/tip-0047.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0047/tip-0047.md b/tips/TIP-0047/tip-0047.md index 0384eb0f3..ff6ef32b4 100644 --- a/tips/TIP-0047/tip-0047.md +++ b/tips/TIP-0047/tip-0047.md @@ -76,7 +76,7 @@ However, in this scenario no outputs hold more IOTA coins than required for the - With new use cases enabled by the new `dust protection` (e.g. tokenization, storing arbitrary data in the ledger), the distribution will dramatically change. - Fittings for other DLT projects do not match because there are transaction fees in place, which decrease the amount of dust outputs in the distribution. -Another possibility would be to estimate how much percentage of the database will be used for outputs with minimum required deposit (`fund sparsitiy percentage`) in the future. The remaining IOTA coins can be ignored in that case to simplify the calculation. Since a fund sparsity percentage of less than 20% would already be bad for other upcoming protocol features like the mana calculation, we could take this value for our calculation instead of the worst case. +Another possibility would be to estimate how much percentage of the database will be used for outputs with minimum required deposit (`fund sparsity percentage`) in the future. The remaining IOTA coins can be ignored in that case to simplify the calculation. Since a fund sparsity percentage of less than 20% would already be bad for other upcoming protocol features like the mana calculation, we could take this value for our calculation instead of the worst case. ### Weights for different outputs From a1c8a678d9748b675779d7b76b239b763be7aa5f Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 2 Oct 2023 14:56:24 +0200 Subject: [PATCH 045/122] Update BIC Input description --- tips/TIP-0045/tip-0045.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 58451c15f..759b3bb53 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -422,8 +422,7 @@ It is serialized as follows: ##### Block Issuance Credit Input -A _Block Issuance Credit Input_ provides the VM with context for the value of the BIC vector of a specific slot. It is -required for any _Account_ transitions and destruction if the account contains a _Block Issuer Feature_, as any +A _Block Issuance Credit Input_ provides the BIC balance of a specific account as context to transaction execution of a specific slot. It is required for any _Account_ transition and destruction if the account contains a _Block Issuer Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point in time. A _Block Issuance Credit Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple _Block Issuance Credit Inputs_ From 6ef049ddbae20986de1e253cc9166ebfe89bd3c3 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 4 Oct 2023 19:27:23 +0200 Subject: [PATCH 046/122] Replace Transaction with Signed Transaction --- tips/TIP-0045/tip-0045.md | 310 ++++++++++++++++++++++---------------- 1 file changed, 182 insertions(+), 128 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 759b3bb53..caa0e4597 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -101,113 +101,178 @@ payload data including unlocks. 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): +
+ Signed Transaction +
A transaction with its unlocks.
+
- - - + + + - - + + - + - + @@ -443,7 +439,7 @@ A Transaction ID consists of two commitments, the _Transaction Commitment_ and t #### Network ID -The `Network ID` field of the transaction essence serves as a +The `Network ID` field of the transaction serves as a [replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). It is a unique value denoting whether the transaction was meant for the IOTA mainnet, shimmer, testnet-1, or a private network. It consists of the first 8 bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as an unsigned integer number. @@ -605,12 +601,12 @@ issuance slot. The good practice would be to always allot enough Mana to cover f #### Payload -The _Transaction Essence_ itself can contain another payload as described in general in -[TIP-46](../TIP-0024/tip-0046.md). The [semantic validity](#semantic-validation) of the encapsulating _Transaction -Payload_ does not have any impact on the payload. +The _Transaction_ itself can contain another payload as described in general in [TIP-46](../TIP-0046/tip-0046.md). The +[semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ is unaffected by the possibly +contained 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_ as well as links to the +corresponding specification: | Name | Type Value | TIP | | ----------- | ---------- | --------------------------------- | @@ -618,22 +614,23 @@ the corresponding specification: ### Unlocks -The `Unlocks` field holds the unlocks unlocking inputs within a _Transaction Essence_. +The `Unlocks` field holds the unlocks which unlock the inputs in a _Transaction_. The following table lists all the unlock 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 | -| ----------- | ---------- | ------------------------------------------------------------ | -| Signature | 0 | [TIP-45](#signature-unlock) | -| Reference | 1 | [TIP-45](#reference-unlock) | -| Account | 2 | [TIP-42](../TIP-0042/tip-0042.md#account-locking--unlocking) | -| NFT | 3 | [TIP-43](../TIP-0043/tip-0043.md#nft-locking--unlocking) | +| Unlock Name | Type Value | TIP | +| ------------ | ---------- | ------------------------------------------------------------ | +| Signature | 0 | [TIP-45](#signature-unlock) | +| Reference | 1 | [TIP-45](#reference-unlock) | +| Account | 2 | [TIP-42](../TIP-0042/tip-0042.md#account-locking--unlocking) | +| NFT | 3 | [TIP-43](../TIP-0043/tip-0043.md#nft-locking--unlocking) | +| Multi Unlock | 4 | [TIP-52](../TIP-0052/tip-0052.md#multi-unlock) | #### Signature Unlock -The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the Transaction Essence (including -the optional payload). It is serialized as follows: +The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the Transaction (including the +optional payload). It is serialized as follows:
NameTypeDescription + Name + + Type + + Description +
Payload Typeuint32 - Set to value 6 to denote a TIP-45 Transaction Payload. - uint8Set to value 8 to denote a Signed Transaction.
Essence oneOfTransaction oneOf
- Transaction Essence -
- Describes the essence data making up a transaction by defining its inputs, outputs, and an optional payload. -
+ Transaction +
A transaction. Defined in TIP-45 (Transaction).
- - - - - - - + + - + - - - + + + - + - + - + - + - +
NameTypeDescription
Transaction Typeuint8 - Set to value 2 to denote a TIP-45 Transaction Essence. + Name + + Type + + Description
Network ID uint64 - 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. - The ID of the network for which this essence is valid for. It consists of the first 8 bytes of the BLAKE2b-256 hash of the Network Name.
Creation Slotuint64 - The slot index in which the transaction was created. - Creation Slotuint32The slot index in which the transaction was created.
Context Inputs Count uint16The number of context input entries.The number of Context Inputs following.
Context Inputs optAnyOf
Commitment Input -
- Describes an input which references a commitment to a certain slot. -
+
A Commitment Input allows referencing a commitment to a certain slot and is used to provide a notion of time for transaction execution that is linked to the containing Block's Issuing Time. Defined in TIP-45 (Commitment Input).
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Context Input Typeuint8Set to value 0 to denote a Commitment Input.
Commitment IDByteArray[40]The commitment identifier to reference to.
Block Issuance Credit Input -
- Describes an input which resolves to a BIC value of an account. -
+
A Block Issuance Credit Input provides the BIC balance of a specific account as context to transaction execution. Defined in TIP-45 (Block Issuance Credit Input).
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Context Input Typeuint8Set to value 1 to denote a Block Issuance Credit Input.
Account IDByteArray[32]The ID of the Account for which this input provides the BIC.
Reward Input -
- References a UTXO input which claims Mana rewards. -
+
A Reward Input indicates which transaction Input is claiming Mana rewards. Defined in TIP-45 (Reward Input).
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Context Input Typeuint8Set to value 2 to denote a Reward Input.
Indexuint16The index of the transaction input for which to claim rewards.
Inputs Count uint16The number of input entries.The number of Inputs following.
Inputs anyOfInputs anyOf
UTXO Input -
- Describes an input which references an unspent transaction output to consume. -
+
Describes an input which references an unspent transaction output to consume. Defined in TIP-45 (UTXO Input).
- - - + + + - + - - + + @@ -218,81 +283,38 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - - - - - - - - - - - - - - - + - + - + + + + + + + + + + @@ -321,34 +371,30 @@ The following table describes the entirety of a _Transaction Payload_ in its ser - + @@ -360,6 +406,14 @@ The Transaction Essence of a Transaction Payload carries the input 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. +### Transaction ID + +The _Transaction ID_ is a `ByteArray[36]` which is computed as follows: +- Let `Essence Bytes` be the concatenated serialization of the fields from `Network ID` to `Payload`. +- Let `Output Bytes` be the concatenated serialization of the fields `Outputs Count` and `Outputs`. +- Let `ID` be the BLAKE2b-256 of the concatenation of `Essence Bytes` and `Output Bytes`. +- Construct the `Transaction ID` as the concatenation of the `ID` and the little-endian encoded `Creation Slot`. + #### Network ID The `Network ID` field of the transaction essence serves as a From 7b9bdbb9065d6dcbff5af321b1b761b939e7e0df Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 4 Oct 2023 19:54:09 +0200 Subject: [PATCH 047/122] Remove Essence section --- tips/TIP-0045/tip-0045.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index caa0e4597..b5552e646 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -400,12 +400,6 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
NameTypeDescription + Name + + Type + + Description +
Input Type uint8 - Set to value 0 to denote an TIP-20 UTXO Input. - Set to value 0 to denote a UTXO Input.
Transaction IDByteArray[32]The BLAKE2b-256 hash of the transaction payload containing the referenced output.ByteArray[36]The identifier of the transaction that created the referenced output.
Transaction Output Index
Inputs CommitmentByteArray[32] - BLAKE2b-256 hash serving as a commitment to the serialized outputs referenced by Inputs. -
Outputs Countuint16The number of output entries.
Outputs anyOf -
- Basic Output -
- Describes a deposit to a single address. The output might contain optional features and native tokens. -
-
-
- Account Output -
- Describes an 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. -
-
-
- Delegation Output -
- Describes a Delegation Output, which delegates its contained IOTA tokens to a validator. -
-
-
Allotments Count uint16The number of account allotment entries.The number of Allotments following.
Allotments optAnyOfAllotments optAnyOf
Allotment -
- Allots Mana value to indicated account. -
+
Allots Mana to the account identified by the contained Account ID. Defined in TIP-45 (Allotment).
- - - + + + - + - - + +
NameTypeDescription + Name + + Type + + Description +
Account ID ByteArray[32]The Account ID of the parent.The ID of the Account to which the Mana is allotted.
Manauint64 The amount of Mana to allot to this account.uint64The amount of Mana to allot.
@@ -304,13 +326,41 @@ The following table describes the entirety of a _Transaction Payload_ in its ser 		The length in bytes of the optional payload.
Payload optOneOfPayload optOneOf
- Tagged Data Payload -
- Describes data with optional tag, defined in TIP-23. -
+ Tagged Data +
Data with optional tag. Defined in TIP-23 (Specification).
+
+
Outputs Countuint16The number of Outputs following,
Outputs anyOf +
+ Basic Output +
Describes a basic output with optional features. Defined in TIP-41 (Basic Output).
+
+
+ Foundry Output +
Describes a foundry output that is controlled by an account. Defined in TIP-44 (Foundry Output).
+
+
+ Account Output +
Describes an account in the ledger that can be controlled by the state and governance controllers. Defined in TIP-42 (Account Output).
+
+
+ NFT Output +
Describes an NFT output, a globally unique token with metadata attached. Defined in TIP-43 (NFT Output).
+
+
+ Delegation Output +
Describes a Delegation Output, which delegates its contained IOTA tokens to a validator. Defined in TIP-40 (Delegation Output).
Unlocks Count uint16The number of unlock entries. It must match the field Inputs Count.The number of unlocks following.
Unlocks anyOf
Signature Unlock -
- Defines an unlock containing a signature. -
+
Unlocks the address derived from the contained Public Key in the transaction in which it is contained in. Defined in TIP-45 (Signature Unlock).
Reference Unlock -
- References a previous unlock, where the same unlock can be used for multiple inputs. -
+
References a previous unlock to support unlocking multiple inputs owned by the same address. Defined in TIP-45 (Reference Unlock).
Account Unlock -
- References a previous unlock of a consumed account output. -
+
Points to the unlock of a consumed Account Output. Defined in TIP-42 (Account Unlock).
NFT Unlock -
- References a previous unlock of a consumed NFT output. -
+
Points to the unlock of a consumed NFT Output. Defined in TIP-43 (NFT Unlock).
+
+
+ Multi Unlock +
Unlocks a Multi Address with a list of other unlocks. Defined in TIP-52 (Multi Unlock).
-### 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 1 for TIP-20 Transaction Essence. - ### Transaction ID The _Transaction ID_ is a `ByteArray[36]` which is computed as follows: From 749278f769227295d3fd345922d475d3fae9806b Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 16 Oct 2023 12:03:09 +0100 Subject: [PATCH 048/122] Remove subschema indicator from `transaction` --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index b5552e646..b0a8b1d06 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -123,7 +123,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Set to value 8 to denote a Signed Transaction.
Transaction oneOfTransaction
Transaction @@ -180,7 +180,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Commitment IDByteArray[40]ByteArray[36] The commitment identifier to reference to.
From 7e58ca99c032967171215886992a5f4f3ee8c9a1 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 16 Oct 2023 12:27:50 +0100 Subject: [PATCH 049/122] Remove superfluous link --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index b0a8b1d06..5a9c21ed5 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -127,7 +127,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Transaction -
A transaction. Defined in TIP-45 (Transaction).
+
A transaction.
From c31c3205393a7320a28066cf3a1ecdcf05218198 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daria=20Dziuba=C5=82towska?= Date: Tue, 17 Oct 2023 10:00:20 +0200 Subject: [PATCH 050/122] Add author --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 5a9c21ed5..2c7a11de8 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -2,7 +2,7 @@ tip: 45 title: Transaction Payload with IOTA 2.0 Output Types description: Add output types, unlocks, and output features from TIP-38 into updated Transaction Payload -author: TODO +author: TODO, Daria Dziubałtowska (@daria305) discussions-to: TODO status: Draft type: Standards From 8df87435685069f60d7110f70838f2a9f404bfd0 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 09:11:12 +0100 Subject: [PATCH 051/122] Remove Inputs Commitment, add Output ID Proof --- tips/TIP-0045/tip-0045.md | 77 ++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 29 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 5a9c21ed5..3baf313d3 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -400,12 +400,45 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
+### Output ID Proof + +TIP-20 introduced an Inputs Commitment in the transaction to prevent +[an attack vector](https://github.com/iotaledger/tips/discussions/51) on the client. Consider a client requesting Output +IDs from a node which it wants to use as inputs to a transaction. The client has no way to check whether the received +Outputs correspond to the Output IDs it requested. 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. A client will only include +the Output ID in a transaction as an input, not the entire output. Hence, if a client receives fake outputs from a +malicious node, it might end up producing a transaction that consumes an output it did not intend to consume. For that +reason the Inputs Commitment was introduced, which provides a cryptographic commitment to the _content_ of all used +inputs. This enables the protocol to detect such attacks, since the transaction would be invalid if the client used a +(e.g. fake) output for their transaction that does not match the one stored by the nodes in the ledger. + +This TIP removes the Inputs Commitment and introduces an Output Commitment through which the Transaction ID becomes +dependent on the outputs it creates. This is used to create proofs which a client can use to verify that an Output ID +indeed belongs to a certain Output. This means that instead of the protocol checking the Inputs Commitment to prevent +the above-mentioned attack, this responsibility now falls to the client, which, when fetching an Output for a certain +Output ID, receives the output as well as the corresponding proof for its Output ID. The client can trustlessly verify +that the output and its ID match which in turn renders the Inputs Commitment unnecessary. + +More generally, this setup is also useful to prove that a given transaction produced an output with a certain state. + +Such an Output ID Proof is a [merkle proof](https://en.wikipedia.org/wiki/Merkle_tree), with the array of the serialized +`Outputs` as the leaves of the tree. A proof is generated for a specific index in the array. + +A proof is serialized as follows: + +TODO + ### Transaction ID -The _Transaction ID_ is a `ByteArray[36]` which is computed as follows: -- Let `Essence Bytes` be the concatenated serialization of the fields from `Network ID` to `Payload`. -- Let `Output Bytes` be the concatenated serialization of the fields `Outputs Count` and `Outputs`. -- Let `ID` be the BLAKE2b-256 of the concatenation of `Essence Bytes` and `Output Bytes`. +A Transaction ID consists of two commitments, the _Transaction Commitment_ and the _Ouptut Commitment_. It is a +`ByteArray[36]` which is computed as follows: + +- Let `Transaction Bytes` be the concatenated serialization of the fields from `Network ID` to `Payload`. +- Let `Transaction Commitment` be the BLAKE2b-256 hash of `Transaction Bytes`. +- Let `Output Commitment` be the root of the merkle tree over the `Outputs`. See [Output ID Proof](#output-id-proof) for + more details. +- Let `ID` be the BLAKE2b-256 of the concatenation of `Transaction Commitment` and `Output Commitment`. - Construct the `Transaction ID` as the concatenation of the `ID` and the little-endian encoded `Creation Slot`. #### Network ID @@ -470,12 +503,13 @@ It is serialized as follows: ##### Block Issuance Credit Input -A _Block Issuance Credit Input_ provides the BIC balance of a specific account as context to transaction execution of a specific slot. It is required for any _Account_ transition and destruction if the account contains a _Block Issuer Feature_, as any -operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point in time. A _Block -Issuance Credit Input_ always requires a _Commitment Input_. The input will be resolved to the BIC value of the account -identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple _Block Issuance Credit Inputs_ -can be present in a single transaction to provide the BIC for different accounts; however, no two _Block Issuance -Credits Inputs_ can reference the same account. +A _Block Issuance Credit Input_ provides the BIC balance of a specific account as context to transaction execution of a +specific slot. It is required for any _Account_ transition and destruction if the account contains a _Block Issuer +Feature_, as any operation on the _Account_ can only be allowed if the BIC balance is non-negative at a specific point +in time. A _Block Issuance Credit Input_ always requires a _Commitment Input_. The input will be resolved to the BIC +value of the account identified by `Account ID` at the `Slot Index` given by the _Commitment Input_. Multiple _Block +Issuance Credit Inputs_ can be present in a single transaction to provide the BIC for different accounts; however, no +two _Block Issuance Credits Inputs_ can reference the same account. It is serialized as follows: @@ -542,17 +576,6 @@ identified by its _Output ID_, defined by the _Transaction ID_ of the creating t 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). 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 The `Outputs` field holds the outputs that are created by the Transaction Payload. There are different output @@ -804,9 +827,6 @@ funding transaction as a parent of the block containing the spending transaction - 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 equal BLAKE2( BLAKE2(O1) || … || BLAKE2(On) ), where - O1, ..., On are the complete serialized outputs referenced by the - `Inputs` field in that order. - All _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - 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. @@ -898,11 +918,10 @@ used deposit address. Ed25519 addresses are not meant to be used like email addr # Rationale and Alternatives -- _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. +- _Network ID_ is an explicit field in the transaction while it could be made a configuration parameter for the + signature generating process. In this scenario, the signature would be invalid if the parameter 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 6ca883591dc2b9eef40fbd3c5ef26a17b8d9dd29 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 09:15:23 +0100 Subject: [PATCH 052/122] Beautify exponent rendering --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 3baf313d3..d5e10944d 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -792,11 +792,11 @@ The following criteria defines whether a payload passes the syntactical validati - `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`. - - The sum of all `Mana` fields must not exceed `2^Mana Bits Count - 1`. + - The sum of all `Mana` fields must not exceed 2Mana Bits Count - 1. - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - Allotments: - `Allotments Count` must be `0 ≤ x ≤ 128`. - - The sum of all `Mana` fields must not exceed `2^Mana Bits Count - 1`. + - The sum of all `Mana` fields must not exceed 2Mana Bits Count - 1. - Every `Mana` field in an Allotment must be `> 0`. - There must be no duplicated `AccountID`s in the list of allotments. - Each entry in `Allotments` must be lexicographically ordered based on its `Account ID`. From 646bd7bfdfd177b854653850b5edd930b091b772 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 09:33:08 +0100 Subject: [PATCH 053/122] Replace essence with transaction --- tips/TIP-0045/tip-0045.md | 56 ++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index d5e10944d..a47a2a633 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -20,7 +20,6 @@ replaces: TIP-20 - [UTXO](#utxo) - [Transaction Structure](#transaction-structure) - [Serialized Layout](#serialized-layout) - - [Essence](#essence) - [Unlocks](#unlocks) - [Work Score](#work-score) - [Validation](#validation) @@ -86,19 +85,16 @@ The following image depicts the flow of funds using UTXO: ### Serialized Layout -A _Transaction Payload_ is made up of two parts: +A _Signed 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_. +1. The _Transaction_ part which contains the inputs, outputs, and an optional embedded payload. +2. The _Unlocks_ which unlock, or _sign_, the inputs of the _Transaction_. The serialized form of the transaction is deterministic, meaning the same logical transaction always results in the same serialized byte sequence. 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. - -The following table describes the entirety of a _Transaction Payload_ in its serialized form following the notation from +The following table describes the entirety of a _Signed Transaction_ in its serialized form following the notation from [TIP-21](../TIP-0021/tip-0021.md):
@@ -143,7 +139,7 @@ The following table describes the entirety of a _Transaction Payload_ in its ser
Network ID uint64The ID of the network for which this essence is valid for. It consists of the first 8 bytes of the BLAKE2b-256 hash of the Network Name.The ID of the network for which this transaction is valid for. It consists of the first 8 bytes of the BLAKE2b-256 hash of the Network Name.
Creation Slot
@@ -718,9 +715,9 @@ The Reference Unlock references a previous Unlock (which must not - 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 Unlocks part: +Example: Consider a Transaction 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 | | ----- | ------------------------------------------------------------------------------------ | @@ -770,8 +767,7 @@ discarded right away. The following criteria defines whether a payload passes the syntactical validation: -- Essence: - - `Transaction Type` value must denote a _TIP-45 Transaction Essence_. +- Transaction: - `Network ID` must match the value of the current network. - `CreationTime` must be a valid `Slot index` timestamp. - Inputs: @@ -805,7 +801,7 @@ The following criteria defines whether a payload passes the syntactical validati - 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_. + - `Unlocks Count` must match `Inputs Count` of the _Transaction_. - 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. From b1e6976753d0d0431b9635c0cfdfcd913d1dd297 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 09:35:11 +0100 Subject: [PATCH 054/122] Auto-generate signature and ref unlock schemas --- tips/TIP-0045/tip-0045.md | 63 ++++++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 21 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index a47a2a633..46d00b69b 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -632,46 +632,59 @@ specification. The _Signature Unlock_ and the _Reference Unlock_ are specified a The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the Transaction (including the optional payload). It is serialized as follows: +
+ Signature Unlock +
Unlocks the address derived from the contained Public Key in the transaction in which it is contained in.
+
- - - + + + - + - + - + From 639cb114fedce403c63987e42c104e1b1df86855 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 15:07:23 +0100 Subject: [PATCH 061/122] Update Context Input type prefiex & u32 slot index --- tips/TIP-0045/tip-0045.md | 120 ++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 45 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index b675a5e61..0449acc0c 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -487,22 +487,32 @@ _Commitment Input_ may be present in a transaction. It is serialized as follows: +
+ Commitment Input +
A Commitment Input allows referencing a commitment to a certain slot and is used to provide a notion of time for transaction execution that is linked to the containing Block's Issuing Time.
+
NameTypeDescription + Name + + Type + + Description +
Unlock Type uint8 - Set to value 0 to denote a Signature Unlock. - Set to value 0 to denote a Signature Unlock.
Signature oneOfSignature oneOf
Ed25519 Signature +
An Ed25519 Signature with the public key that verifies it. Defined in TIP-38 (Ed25519 Signature).
- - - + + + - + - + - +
NameTypeDescription + Name + + Type + + Description +
Signature Type uint8 - Set to value 0 to denote an Ed25519 Signature. - Set to value 0 to denote an Ed25519 Signature.
Public Key ByteArray[32]The Ed25519 public key of the signature.The Ed25519 public key that verifies the signature.
Signature ByteArray[64]The Ed25519 signature signing the Blake2b-256 hash of the serialized Transaction Essence.The Ed25519 signature that must be verified according to TIP-14.
@@ -690,18 +703,26 @@ optional payload). It is serialized as follows: The Reference Unlock 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: +
+ Reference Unlock +
References a previous unlock to support unlocking multiple inputs owned by the same address.
+
- - - + + + - + From 85c6673906de3db29d18cae6b4ed7022d933f0dd Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 09:38:58 +0100 Subject: [PATCH 055/122] Update authors --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index f8b0423bb..fdd418f1c 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -2,7 +2,7 @@ tip: 45 title: Transaction Payload with IOTA 2.0 Output Types description: Add output types, unlocks, and output features from TIP-38 into updated Transaction Payload -author: TODO, Daria Dziubałtowska (@daria305) +author: Philipp Gackstatter (@PhilippGackstatter) , Daria Dziubałtowska (@daria305) discussions-to: TODO status: Draft type: Standards From ba7c141a9f6738f1870352006ac905b96e8f4b5d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 09:46:27 +0100 Subject: [PATCH 056/122] Add transaction capabilites (schema only) --- tips/TIP-0045/tip-0045.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index fdd418f1c..32c2d682f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -139,7 +139,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri - + @@ -316,6 +316,11 @@ The following table describes the entirety of a _Signed Transaction_ in its seri + + + + + From 55834b75cef1efcd885228e2cabd3fd71ef2f59d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 10:55:07 +0100 Subject: [PATCH 057/122] Add transaction id test vector --- tips/TIP-0045/tip-0045.md | 141 +++++++++++++++++++++++++++++++++++++- 1 file changed, 139 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 32c2d682f..8f741e3e1 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -2,7 +2,9 @@ tip: 45 title: Transaction Payload with IOTA 2.0 Output Types description: Add output types, unlocks, and output features from TIP-38 into updated Transaction Payload -author: Philipp Gackstatter (@PhilippGackstatter) , Daria Dziubałtowska (@daria305) +author: + Philipp Gackstatter (@PhilippGackstatter) , Daria Dziubałtowska (@daria305) + discussions-to: TODO status: Draft type: Standards @@ -29,7 +31,8 @@ replaces: TIP-20 - [Address reuse](#address-reuse) 4. [Drawbacks](#drawbacks) 5. [Rationale and Alternatives](#rationale-and-alternatives) -6. [Copyright](#copyright) +6. [Test Vectors](#test-vectors) +7. [Copyright](#copyright) # Summary @@ -946,6 +949,140 @@ used deposit address. Ed25519 addresses are not meant to be used like email addr 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. +# Test Vectors + +## Transaction ID + +The following shows a transaction and its computed Transaction ID. + +Transaction (json-encoded): + +```json +{ + "type": 1, + "transaction": { + "networkId": "14147312347886322761", + "creationSlot": 1048576, + "contextInputs": [ + { + "type": 1, + "commitmentId": "0x760702593b59500420722f3a1634005f11360b133a030f46282c0f690a55084855000000" + }, + { + "type": 2, + "accountId": "0x3407603d0f725b7e7214205f254305743d5362512f36153236435e796b6a1c2e" + }, + { + "type": 3, + "index": 0 + } + ], + "inputs": [ + { + "type": 0, + "transactionId": "0x3ca1f23b83708ee7c59d6d7fe71453106bb0a0abc1c9cc4b340c755238ae6daa00000000", + "transactionOutputIndex": 0 + }, + { + "type": 0, + "transactionId": "0xecb673f194640b2067b8da136b5f5437c2c723e7f3fdaa53984d7588ed21071a00000000", + "transactionOutputIndex": 0 + } + ], + "allotments": [ + { + "accountID": "0x0e0f253479566103415e29060f79772445531564733e214b54084358413f7c70", + "value": "6648" + }, + { + "accountID": "0x445e204c1f747503106b5663664c43591e63235804057c445d073a5f10597e2d", + "value": "9988" + } + ], + "capabilities": "0x01", + "outputs": [ + { + "type": 0, + "amount": "100000", + "mana": "0", + "unlockConditions": [ + { + "type": 0, + "address": { + "type": 0, + "pubKeyHash": "0x7f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e" + } + } + ], + "features": [ + { + "type": 4, + "id": "0x082a1c2429352945216e3f547a03226b2f014d3d2e185a2459473a362c4d124d511a6c2d6000", + "amount": "0xd54f92ae8c34fbb4" + } + ] + }, + { + "type": 1, + "amount": "100000", + "mana": "5000", + "accountId": "0x0000000000000000000000000000000000000000000000000000000000000000", + "stateIndex": 0, + "foundryCounter": 0, + "unlockConditions": [ + { + "type": 4, + "address": { + "type": 0, + "pubKeyHash": "0x7f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e" + } + }, + { + "type": 5, + "address": { + "type": 0, + "pubKeyHash": "0x7f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e" + } + } + ], + "features": [ + { + "type": 2, + "data": "0x1e69562e763b1125080c1a7161390e42" + } + ] + } + ] + }, + "unlocks": [ + { + "type": 0, + "signature": { + "type": 0, + "publicKey": "0xa6bbccb2380a3a941a7bfdd5f2afcb8a6f5236bbe12ae8b931b593efd76864b6", + "signature": "0x98a18fd0083c7d9b6b05e218c7f764bb915148762ce342d795f7acac4083b40dbfc01f5fd23f6d1e652eee0e5951b87dd6307adf1389f8f16c08ade12be01c0a" + } + }, + { + "type": 1, + "reference": 0 + } + ] +} +``` + +Transaction (binary-encoded): + +``` +0x01490443ee9f5955c400001000030001760702593b59500420722f3a1634005f11360b133a030f46282c0f690a55084855000000023407603d0f725b7e7214205f254305743d5362512f36153236435e796b6a1c2e0300000200003ca1f23b83708ee7c59d6d7fe71453106bb0a0abc1c9cc4b340c755238ae6daa00000000000000ecb673f194640b2067b8da136b5f5437c2c723e7f3fdaa53984d7588ed21071a00000000000002000e0f253479566103415e29060f79772445531564733e214b54084358413f7c70f819000000000000445e204c1f747503106b5663664c43591e63235804057c445d073a5f10597e2d0427000000000000010100000000020000a08601000000000000000000000000000100007f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e0104082a1c2429352945216e3f547a03226b2f014d3d2e185a2459473a362c4d124d511a6c2d6000b4fb348cae924fd500000000000000000000000000000000000000000000000001a08601000000000088130000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000204007f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e05007f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e010210001e69562e763b1125080c1a7161390e420002000000a6bbccb2380a3a941a7bfdd5f2afcb8a6f5236bbe12ae8b931b593efd76864b698a18fd0083c7d9b6b05e218c7f764bb915148762ce342d795f7acac4083b40dbfc01f5fd23f6d1e652eee0e5951b87dd6307adf1389f8f16c08ade12be01c0a010000 +``` + +Transaction ID: + +``` +0x4125a5129ece49933dc24a38df82ecf62dd107bd07403648cb935478f394fc5a00001000 +``` + # Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 11711ef170507ce19b2e4789d8a24d3cdce87129 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 12:32:10 +0100 Subject: [PATCH 058/122] Remove outdated TIP-47 --- .../assets/microtransactions_pt3_layer1.png | Bin 151403 -> 0 bytes .../assets/microtransactions_pt3_layer2.png | Bin 135355 -> 0 bytes tips/TIP-0047/tip-0047.md | 145 ------------------ 3 files changed, 145 deletions(-) delete mode 100644 tips/TIP-0047/assets/microtransactions_pt3_layer1.png delete mode 100644 tips/TIP-0047/assets/microtransactions_pt3_layer2.png delete mode 100644 tips/TIP-0047/tip-0047.md diff --git a/tips/TIP-0047/assets/microtransactions_pt3_layer1.png b/tips/TIP-0047/assets/microtransactions_pt3_layer1.png deleted file mode 100644 index 561db0bb10b06d55b8b34ad89ce27f95c5f45c22..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 151403 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
    0bU6`jY&V0Bfv!nW;`K!e*PYS%T;eKcRFCFJo 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 X;=Oo!w%qtV@SmEJCN@vO#P9zAY}gb> diff --git a/tips/TIP-0047/assets/microtransactions_pt3_layer2.png b/tips/TIP-0047/assets/microtransactions_pt3_layer2.png deleted file mode 100644 index 67a46901dc89a453ddbd72cf8006a417f9097760..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 135355 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
    @GVI=78mTm?pJw;^-E|@&`a*Z@W2#uA( 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
    B*EQRjTbEL+idRQV9=N%hbD#_oNTh1~ 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 -discussions-to: TODO -status: Draft -type: Standards -layer: Core -created: 2023-05-12 -requires: TIP-20, TIP-21, TIP-22 and TIP-38 -replaces: TIP-19 ---- - -## Summary - -This document describes a `dust protection` concept, called `storage deposit` which was originally introduced in TIP-19. This concept creates a monetary incentive to keep the ledger state small. This is achieved by enforcing a minimum IOTA coin deposit in every output based on the actually used disc space of the output itself. - -This document minimally extends on TIP-19 by allowing for additional weights to be defined in other TIPs and no longer includes the deposit calculation for each individual output. Instead, each TIP defining outputs has to include the deposit calculation. - -## Motivation - -In a distributed ledger network, every participant, a so-called node, needs to keep track of the current ledger state. Since `chrysalis-pt2`, the IOTA ledger state is based on the UTXO model, where every node keeps track of all the currently unspent outputs. - -Misusage by honest users or intentionally bad behavior by malicious actors can lead to growing database and snapshot sizes and increasing computational costs (database lookups, balance calculations). Due to these increasing hardware requirements, the entry barrier to participate in the network becomes unaffordable and less nodes would operate the network. - -Especially in a fee-less system like IOTA, this is a serious issue, since an attacker can create a lot of damage with low effort. Other DLTs do not yet face this problem, as such an attack would be much more expensive due to the high transaction fees. -However, in order to solve scalability issues more and more transactions need to be handled. Therefore, other DLT projects will also eventually run into the same dust limitations. This document proposes to introduce `storage deposit` to address this. - -## Requirements - -- The maximum possible ledger database size must be limited to a reasonable and manageable size. -- The `dust protection` must not depend on a global shared state of the ledger, so that transaction validation can happen in parallel. -- The `dust protection` should work for outputs with arbitrary data and size. -- The ledger database size should be fairly allocated to users based on the scarce resource, IOTA coins. - -## Detailed Design - -A transaction validation rule is introduced which is exactly the same as the one defined in TIP-19, but stated here again for self-containment. - -Blocks including payloads, even transaction payloads, are considered to be pruned by the nodes, but unspent transaction outputs must be kept until they are spent. Therefore the `dust protection` is based on the unspent outputs only. - -**Every output created by a transaction needs to have at least a minimum amount of IOTA coins deposited in the output itself, otherwise the output is syntactically invalid.** - -min_deposit_of_output = ⌊v_byte_cost · v_byte⌋ -v_byte = ∑(weight𝑖 · byte_size𝑖) + offset - -where: -- v_byte_cost: costs in IOTA coins per virtual byte -- weight𝑖: factor of field 𝑖 that takes computational and storage costs into account -- byte_size𝑖: size of field 𝑖 in bytes -- offset: additional v_bytes that are caused by additional data that has to be stored in the database but is not part of the output itself - -| :warning: `min_deposit_of_output` is rounded down | -| ------------------------------------------------- | - -TIP-18 and its replacement TIPs introduce new output types that contain mandatory and optional fields with variable length. Each of these fields result in different computational and storage costs, which will be considered by the positive `weight_i`. The size of the field itself is expressed with `byte_size_i`. `offset` is used to take the overhead of the specific output itself into account. - -The `v_byte_cost` is a protocol value, which has to be defined based on reasonable calculations and estimates. - -**In simple words, the more data you write to the global ledger database, the more IOTA you need to deposit in the output.** -This is not a fee, because the deposited coins can be reclaimed by consuming the output in a new transaction. - -### How does it affect other parts of the protocol? - -The `dust protection` only affects "value-transactions". Since blocks containing other payloads are not stored in the ledger state and are subject to pruning, they cannot cause permanent "dust" and do not need to be considered for `dust protection`. -However, all output types like e.g. smart contract requests are affected and must comply with the `min_deposit_of_output` criteria. Therefore, these requests could get quite expensive for the user, but the same mechanism introduced for [Microtransactions on Layer 1](#Microtransactions-on-Layer-1) can be utilized for smart contract requests as well. - -### Byte cost calculations - -To limit the maximum database size, the total IOTA supply needs to be divided by the target database size in bytes to get the worst case scenario regarding the byte costs. - -However, in this scenario no outputs hold more IOTA coins than required for the `dust protection`. This does not represent the real distribution of funds over the UTXOs. We could assume that these output amounts follow Zipf's law. Unfortunately, fitting a Zipf distribution to the current ledger state will not match the future distribution of the funds for several reasons: - -- There is already another `dust protection` in place, which distorts the distribution. -- With new use cases enabled by the new `dust protection` (e.g. tokenization, storing arbitrary data in the ledger), the distribution will dramatically change. -- Fittings for other DLT projects do not match because there are transaction fees in place, which decrease the amount of dust outputs in the distribution. - -Another possibility would be to estimate how much percentage of the database will be used for outputs with minimum required deposit (`fund sparsity percentage`) in the future. The remaining IOTA coins can be ignored in that case to simplify the calculation. Since a fund sparsity percentage of less than 20% would already be bad for other upcoming protocol features like the mana calculation, we could take this value for our calculation instead of the worst case. - -### Weights for different outputs - -Output types contain several mandatory and optional fields. Every field itself creates individual computational and storage requirements for the node, which is considered by having different weights for every field. - -##### Field types - -The following table describes different field types in an output: - -
NameTypeDescription + Name + + Type + + Description +
Unlock Type uint8 - Set to value 1 to denote a Reference Unlock. - Set to value 1 to denote a Reference Unlock.
Reference
Network ID uint64The ID of the network for which this transaction is valid for. It consists of the first 8 bytes of the BLAKE2b-256 hash of the Network Name.The ID of the network for which this essence is valid for. It consists of the first 8 bytes of the BLAKE2b-256 hash of the Network Name.
Creation Slot
Capabilities(uint8)ByteArrayThe capabilities of the transaction.
Payload Length uint32
- - - - - - - - - - - - - - - - - - -
NameDescriptionWeightReasoning
keyCreates a key lookup in the database.10.0Keys need to be stored in the LSM tree of the key-value database engine and need to be merged and leveled, which is computational-, memory- and read/write IO-wise a heavy task.
dataPlain binary data on disk.1.0Data is stored as the value in the key-value database, and therefore only consumes disc space.
- -TIPs that define new output types may define additional weights based on the storage and computational requirements that the affected fields induce for the node. However, the weights defined here should take precedence whenever possible and inform the newly defined weights. - -| :warning: Protocol parameters are not set yet | -| ---------------------------------------------- | - -Protocol parameters presented in this document are design parameters that will change in the future based on simulation results, benchmarking and security assumptions. The reader should not take these values as definitive. - -An example of such parameter for example is the `weight` assigned to different output field types. - -### Microtransactions - -#### Microtransactions on Layer 1 - -To enable microtransactions on Layer 1 and still satisfy the `min_deposit_of_output` requirement, a new mechanism called `conditional sending` is introduced with [TIP-38](../TIP-0038/tip-0038.md). - -![Microtransactions on Layer 1](assets/microtransactions_pt3_layer1.png) - -The preceding picture shows the process of the `conditional sending` mechanism. Alice uses the `Basic Output` ([TIP-41](../TIP-0041/tip-0041.md)) to send a microtransaction of 1 IOTA to Bob's `Address`. To fulfill the `min_deposit_of_output` requirement, the `Amount` is increased by `min_deposit_of_output` IOTA, which is 1 MIOTA in the above example. To prevent Bob from accessing these additional funds called the `storage deposit`, Alice adds the optional `Storage Deposit Return Unlock Condition` to the `Basic Output`. Now Bob can only consume the newly created output, if the unlocking transaction deposits the specified `Return Amount` IOTA coins, in this case 1 MIOTA, to the `Return Address` value defined by Alice. By consuming another UTXO and adding its amount to the received 1 IOTA, Bob takes care to create a valid output according to the dust protection rules. - -To prevent Bob from blocking access to the `storage deposit` forever, Alice specifies the additional `Expiration Unlock Condition` in the `Basic Output`. If Bob does not consume the output before the time window defined by Alice expires, Alice regains total control over the output. - -This means that there is no risk for Alice to lose the `storage deposit`, because either Bob needs to return the specified `Return Amount`, or the ownership of the created output switches back to Alice after the specified time-window has expired. - -This mechanism can also be used to transfer native tokens or on-chain requests to ISCP chains without losing control over the required `storage deposit`. - -#### Microtransactions on Layer 2 - -Another solution is to outsource microtransactions to Layer 2 applications like smart contracts. In Layer 2 there are no restrictions regarding the minimum balance of an output. - -![Microtransactions on Layer 2](assets/microtransactions_pt3_layer2.png) - -In this example, Alice sends funds to a smart contract chain on Layer 1 with an output that covers at least `min_deposit_of_output`. From this point on, Alice can send any number of off-chain requests to the smart contract chain, causing the smart contract to send microtransactions from Alice' on-chain account to Bob's on-chain account. Bob can now request his on-chain account balances to be withdrawn to his Layer 1 address. The last step can also be combined with the formerly introduced `conditional sending` mechanism, in case Bob wants to withdraw less than `min_deposit_of_output` IOTA coins or native assets. - -## Copyright - -Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 41743396f0a714e0fd19519a07d8898bf0766068 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 12:33:11 +0100 Subject: [PATCH 059/122] Revert changes to README and TIP-19 --- README.md | 1 - tips/TIP-0019/tip-0019.md | 1 - 2 files changed, 2 deletions(-) diff --git a/README.md b/README.md index fd4f081c3..b1da09f1d 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,6 @@ more improvements. Browse the [list of TIPs](#list-of-tips) below with the _Star | 34 | [Wotsicide (Stardust update)](tips/TIP-0034/tip-0034.md) | Define migration from legacy W-OTS addresses to post-Chrysalis networks. Replaces TIP-17. | Standards | Core | Proposed | **Stardust** | | 35 | [Local Snapshot File Format (Stardust Update)](tips/TIP-0035/tip-0035.md) | File format to export/import ledger state. Replaces TIP-9. | Standards | Interface | Proposed | **Stardust** | | 37 | [Dynamic Proof-of-Work](https://github.com/iotaledger/tips/pull/81) | Dynamically adapt the PoW difficulty | Standards | Core | Draft | **Stardust** | -| 47 | [Storage Deposit Dust Protection (IOTA 2.0)](tips/TIP-0047/tip-0047.md) | Prevent bloating the ledger size with dust outputs | Standards | Core | Draft | **IOTA 2.0** | ## Need help? diff --git a/tips/TIP-0019/tip-0019.md b/tips/TIP-0019/tip-0019.md index 91dfb1058..a63145875 100644 --- a/tips/TIP-0019/tip-0019.md +++ b/tips/TIP-0019/tip-0019.md @@ -10,7 +10,6 @@ layer: Core created: 2021-11-04 requires: TIP-18, TIP-20, TIP-21 and TIP-22 replaces: TIP-15 -superseded-by: TIP-47 --- ## Summary From 41a2f752050d384bba5738a3a3a340013ec9fa18 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 14:46:12 +0100 Subject: [PATCH 060/122] Set new Signed Transaction Type Prefix --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 8f741e3e1..b675a5e61 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -119,7 +119,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Payload Type uint8Set to value 8 to denote a Signed Transaction.Set to value 1 to denote a Signed Transaction.
Transaction
- - - - - - - - - - - - - - - + + + + + + + + + + + + + + +
NameTypeDescription
Context Input Typeuint8Set to value 0 to denote a Commitment Input.
Commitment IDByteArray[40]The commitment identifier to reference to.
+ Name + + Type + + Description +
Input Typeuint8Set to value 1 to denote a Commitment Input.
Commitment IDByteArray[36]The commitment identifier to reference to.
##### Block Issuance Credit Input @@ -517,22 +527,32 @@ two _Block Issuance Credits Inputs_ can reference the same account. It is serialized as follows: +
+ Block Issuance Credit Input +
A Block Issuance Credit Input provides the BIC balance of a specific account as context to transaction execution.
+
- - - - - - - - - - - - - - - + + + + + + + + + + + + + + +
NameTypeDescription
Context Input Typeuint8Set to value 1 to denote a Block Issuance Credit Input.
Account IDByteArray[32]The ID of the Account for which this input provides the BIC.
+ Name + + Type + + Description +
Input Typeuint8Set to value 2 to denote a Block Issuance Credit Input.
Account IDByteArray[32]The ID of the Account for which this input provides the BIC.
##### Reward Input @@ -545,22 +565,32 @@ single transaction to claim rewards for different outputs; however, no two _Rewa It is serialized as follows: +
+ Reward Input +
A Reward Input indicates which transaction Input is claiming Mana rewards.
+
- - - - - - - - - - - - - - - + + + + + + + + + + + + + + +
NameTypeDescription
Context Input Typeuint8Set to value 2 to denote a Reward Input.
Indexuint16The index of the transaction input for which to claim rewards.
+ Name + + Type + + Description +
Input Typeuint8Set to value 3 to denote a Reward Input.
Indexuint16The index of the transaction input for which to claim rewards.
#### Inputs From bb0615878f0e98d5a738dc0b3a0952f481102959 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 15:26:21 +0100 Subject: [PATCH 062/122] Add UTXO Input schema --- tips/TIP-0045/tip-0045.md | 73 ++++++++++++++++++++++++++++----------- 1 file changed, 53 insertions(+), 20 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 0449acc0c..019f73406 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -465,15 +465,65 @@ The transaction timestamp is expressed as a `Slot Index`, as there is no need fo transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). +#### Inputs + +The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. +Currently, there is one type of input: + +- _UTXO Input_. + +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 that is allowed to unlock the referenced +output. + +
+ UTXO Input +
Describes an input which references an unspent transaction output to consume.
+
+ + + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Input Typeuint8Set to value 0 to denote a UTXO Input.
Transaction IDByteArray[36]The identifier of the transaction that created the referenced output.
Transaction Output Indexuint16The output index of the referenced output.
+ #### Context Inputs The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a transaction, such as for different functionality related to accounts, commitments, or Mana rewards. Context inputs do not need to be unlocked. This TIP defines 3 types of context inputs: -- _Commitment Input_ -- _Block Issuance Credit Input_ -- _Reward Input_ +- _Commitment Input_. +- _Block Issuance Credit Input_. +- _Reward Input_. ##### Commitment Input @@ -593,23 +643,6 @@ It is serialized as follows: -#### Inputs - -The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. -Currently, there is one type of input: - -- _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 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 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 From 535b128fc93eceb67c41f430d8ab30e41f1b74d1 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 17 Oct 2023 15:28:41 +0100 Subject: [PATCH 063/122] Remove duplicated typedefs for maintenance reasons --- tips/TIP-0045/tip-0045.md | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 019f73406..f9c41d2e9 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -648,18 +648,6 @@ It is serialized as follows: 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](../TIP-0007/tip-0007.md) have been removed and are no longer supported. - -| Output Name | Type Value | TIP | -| ----------- | ---------- | --------------------------------------------------- | -| Basic | 3 | [TIP-41](../TIP-0041/tip-0041.md#basic-output) | -| Account | 4 | [TIP-42](../TIP-0042/tip-0042.md#account-output) | -| Foundry | 5 | [TIP-44](../TIP-0044/tip-0044.md#foundry-output) | -| NFT | 6 | [TIP-43](../TIP-0043/tip-0043.md#nft-output) | -| Delegation | 7 | [TIP-40](../TIP-0040/tip-0040.md#delegation-output) | - #### Allotments The `Allotments` field contains the list of all Mana allotments, the `Account ID`, and corresponding values that @@ -676,28 +664,10 @@ The _Transaction_ itself can contain another payload as described in general in [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ is unaffected by the possibly contained payload. -The following table lists all the payload types that can be nested inside a _Transaction_ as well as links to the -corresponding specification: - -| Name | Type Value | TIP | -| ----------- | ---------- | --------------------------------- | -| Tagged Data | 5 | [TIP-23](../TIP-0023/tip-0023.md) | - ### Unlocks The `Unlocks` field holds the unlocks which unlock the inputs in a _Transaction_. -The following table lists all the unlock 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 | -| ------------ | ---------- | ------------------------------------------------------------ | -| Signature | 0 | [TIP-45](#signature-unlock) | -| Reference | 1 | [TIP-45](#reference-unlock) | -| Account | 2 | [TIP-42](../TIP-0042/tip-0042.md#account-locking--unlocking) | -| NFT | 3 | [TIP-43](../TIP-0043/tip-0043.md#nft-locking--unlocking) | -| Multi Unlock | 4 | [TIP-52](../TIP-0052/tip-0052.md#multi-unlock) | - #### Signature Unlock The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the Transaction (including the From 96b5193dd6120ee3f6e36f158e16b18dceb593bf Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 23 Oct 2023 15:26:09 +0100 Subject: [PATCH 064/122] Update transaction descr & context input types --- tips/TIP-0045/tip-0045.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index f9c41d2e9..ca59d3ba0 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -126,7 +126,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Transaction -
A transaction.
+
A transaction without its unlocks.
- + - + @@ -200,9 +200,9 @@ The following table describes the entirety of a _Signed Transaction_ in its seri - + - + @@ -227,9 +227,9 @@ The following table describes the entirety of a _Signed Transaction_ in its seri - + - + @@ -364,7 +364,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Delegation Output -
Describes a Delegation Output, which delegates its contained IOTA tokens to a validator. Defined in TIP-40 (Delegation Output).
+
Describes a Delegation Output, which delegates its contained IOTA coins to a validator. Defined in TIP-40 (Delegation Output).
From f4dbfef6271f22cae87ebc8199c4c893a83dbbb8 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 23 Oct 2023 15:39:44 +0100 Subject: [PATCH 065/122] Replace "IOTA tokens" -> "IOTA coins" --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index ca59d3ba0..08301d540 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -652,7 +652,7 @@ types, but they must all have an `Amount` field denoting the number of IOTA coin The `Allotments` field contains the list of all Mana allotments, the `Account ID`, and corresponding values that converts Mana provided by the inputs in the form of stored Mana in inputs or potential Mana derived from the inputs' -IOTA tokens. Mana listed in this field will be added upon commitment of the slot in which the transaction was issued, in +IOTA coins. Mana listed in this field will be added upon commitment of the slot in which the transaction was issued, in form of _Block Issuance Credits_ to the account's BIC value. Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the From 94c41015ee203010ad03869155fcab10284c628d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 23 Oct 2023 18:17:56 +0100 Subject: [PATCH 066/122] Update title & description --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 08301d540..1bb3dffbb 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1,7 +1,7 @@ --- tip: 45 -title: Transaction Payload with IOTA 2.0 Output Types -description: Add output types, unlocks, and output features from TIP-38 into updated Transaction Payload +title: IOTA 2.0 Transaction Payload +description: Defines the Transaction with the corresponding IOTA 2.0 output types author: Philipp Gackstatter (@PhilippGackstatter) , Daria Dziubałtowska (@daria305) From 77d023d3d18b8553e5e0b7316580582dfee8decb Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 23 Oct 2023 18:20:02 +0100 Subject: [PATCH 067/122] Remove manually added Table of Contents GitHub and the Wiki both auto-generate a ToC, so it's unnecessary to maintain it. --- tips/TIP-0045/tip-0045.md | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 1bb3dffbb..5702d0ab7 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -14,26 +14,6 @@ requires: TIP-39, TIP-41, TIP-42, TIP-43 and TIP-44 replaces: TIP-20 --- -# Table of Contents - -1. [Summary](#summary) -2. [Motivation](#motivation) -3. [Detailed Design](#detailed-design) - - [UTXO](#utxo) - - [Transaction Structure](#transaction-structure) - - [Serialized Layout](#serialized-layout) - - [Unlocks](#unlocks) - - [Work Score](#work-score) - - [Validation](#validation) - - [Syntactic Validation](#syntactic-validation) - - [Semantic Validation](#semantic-validation) - - [Miscellaneous](#miscellaneous) - - [Address reuse](#address-reuse) -4. [Drawbacks](#drawbacks) -5. [Rationale and Alternatives](#rationale-and-alternatives) -6. [Test Vectors](#test-vectors) -7. [Copyright](#copyright) - # Summary This TIP proposes a new UTXO-based transaction structure consisting of all the inputs and outputs of a transfer. From 2a674e3d18a0346976d954a2b69f56133731c9cf Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 23 Oct 2023 18:20:47 +0100 Subject: [PATCH 068/122] Fix creation date --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 5702d0ab7..a20eaba1e 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -9,7 +9,7 @@ discussions-to: TODO status: Draft type: Standards layer: Core -created: 2021-11-18 +created: 2023-05-08 requires: TIP-39, TIP-41, TIP-42, TIP-43 and TIP-44 replaces: TIP-20 --- From a46d11b8ef2b40248eee4dde9ff37162ce4c5f39 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 24 Oct 2023 09:27:37 +0100 Subject: [PATCH 069/122] Update to `Work Score Parameters` name --- tips/TIP-0045/tip-0045.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index a20eaba1e..d5d9d717b 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -771,21 +771,21 @@ following structure of the Unlocks part: Let the work score of a transaction be defined as follows. -- Let `Size Score` be `Work Score Structure::DataByte * Transaction Size` where `Transaction Size` is the size of the +- Let `Size Score` be `Work Score Parameters::DataByte * Transaction Size` where `Transaction Size` is the size of the serialized _Transaction_. -- Let `Input Score` be `Inputs Count * Work Score Structure::Input`. -- Let `Context Input Score` be `Context Inputs Count * Work Score Structure::Context Input`. +- Let `Input Score` be `Inputs Count * Work Score Parameters::Input`. +- Let `Context Input Score` be `Context Inputs Count * Work Score Parameters::Context Input`. - Let `Output Score` be the sum of work scores of each output `Output` in `Outputs`: - - Let `Native Token Score` be `Work Score Structure::Native Token * Native Tokens Count` if `Output` contains + - Let `Native Token Score` be `Work Score Parameters::Native Token * Native Tokens Count` if `Output` contains `Native Tokens`, `0` otherwise. - - Let `Token Scheme Score` be `Work Score Structure::Native Token` if `Output` contains a _Simple Token Scheme_, `0` + - Let `Token Scheme Score` be `Work Score Parameters::Native Token` if `Output` contains a _Simple Token Scheme_, `0` otherwise. - - Let `Staking Score` be `Work Score Structure::Staking` if `Output` contains a _Staking Feature_, `0` otherwise. - - Let `Block Issuer Score` be `Work Score Structure::Block Issuer` if `Output` contains a _Block Issuer Feature_, `0` + - Let `Staking Score` be `Work Score Parameters::Staking` if `Output` contains a _Staking Feature_, `0` otherwise. + - Let `Block Issuer Score` be `Work Score Parameters::Block Issuer` if `Output` contains a _Block Issuer Feature_, `0` otherwise. - Return - `Work Score Structure::Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. -- Let `Allotment Score` be `Work Score Structure::Allotment * Allotments Count`. + `Work Score Parameters::Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. +- Let `Allotment Score` be `Work Score Parameters::Allotment * Allotments Count`. - Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ within `Unlocks`. - Signature work scores are defined in TIP-46. - Return `Size Score + Input Score + Context Input Score + Output Score + Allotment Score + Signature Score`. From f76f9c2e67f20229fb2b97897e2c66620be077ed Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 24 Oct 2023 16:50:25 +0100 Subject: [PATCH 070/122] Clarify what sig unlock signs --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index d5d9d717b..b82f881c7 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -650,8 +650,8 @@ The `Unlocks` field holds the unlocks which unlock the inputs in a _Transaction_ #### Signature Unlock -The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the Transaction (including the -optional payload). It is serialized as follows: +The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the serialized `Transaction` field. It is +serialized as follows:
Signature Unlock From 145d0f89c8669bda4f240c759dfd96678d345140 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 10:37:45 +0100 Subject: [PATCH 071/122] Specify Merkle Tree Proof Computation --- tips/TIP-0045/tip-0045.md | 335 +++++++++++++++++++++++++++++++++++++- 1 file changed, 330 insertions(+), 5 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index b82f881c7..7ba973b0b 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -38,6 +38,185 @@ The motivation of these changes is to adjust the transaction and its validation 2.0. Validation rules must now consider the Mana decay factor and the possibility of Mana allotment in the transaction to a Block Issuance Credits account. +# Building Blocks + +## Merkle Tree + +A [merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) is a tree data structure that allows for efficient proofs of +inclusion. + +A merkle tree proof is serialized as one of three possible schemas: A tree node, the hash of a leaf or the hash of the +value for which the proof is computed. + +### Node + +
+ Node +
Contains the hash of the value for which the proof is being computed.
+
+
@@ -173,9 +173,9 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Context Input TypeInput Type uint8Set to value 0 to denote a Commitment Input.Set to value 1 to denote a Commitment Input.
Commitment ID
Context Input TypeInput Type uint8Set to value 1 to denote a Block Issuance Credit Input.Set to value 2 to denote a Block Issuance Credit Input.
Account ID
Context Input TypeInput Type uint8Set to value 2 to denote a Reward Input.Set to value 3 to denote a Reward Input.
Index
+ + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Merkle Tree Component Typeuint8Set to value 0 to denote a Node.
Left oneOf +
+ Node +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
+
+ Leaf Hash +
Contains the hash of a leaf in the tree. Defined in TIP-45 (Leaf Hash).
+
+
+ Value Hash +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Value Hash).
+
+
Right oneOf +
+ Node +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
+
+ Leaf Hash +
Contains the hash of a leaf in the tree. Defined in TIP-45 (Leaf Hash).
+
+
+ Value Hash +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Value Hash).
+
+
+ +### Leaf Hash + +
+ Leaf Hash +
Contains the hash of a leaf in the tree.
+
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Merkle Tree Component Typeuint8Set to value 1 to denote a Leaf Hash.
Hash(uint8)ByteArrayThe hash of the leaf.
+ +### Value Hash + +
+ Value Hash +
Contains the hash of the value for which the proof is being computed.
+
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Merkle Tree Component Typeuint8Set to value 2 to denote a Value Hash.
Hash(uint8)ByteArrayThe hash of the value.
+ +### Proof Computation + +A **merkle proof** is computed as follows: + +- Preliminary Definitions: + - Let `Leaves` be an array of serialized values, representing the leaves of the tree and `Leaves Len` the length of + that array. + - Let `Leaves[i]` denote the `i`-th element in the `Leaves` array. + - Let `Leaves[Start:End]` denote the subslice of `Leaves` from `Start` (inclusive) to `End` (exclusive). + - Let `Largest Power Of Two(n)` be a procedure that returns the largest power of two less than `n`. + - BLAKE2b-256 is used as the hash function. +- Let `Hash Leaf(Bytes)` be a procedure that produces the hash of the given byte array consisting of these values in + their displayed order: + - the leaf domain-separation prefix with value `0` of type `uint8`, + - and `Bytes`. +- Let `Hash Node(Left Bytes, Right Bytes)` be a procedure that produces the hash of the given byte arrays consisting of + these values in their displayed order: + - the node domain-separation prefix with value `1` of type `uint8`, + - and `Left Bytes`, + - and `Right Bytes`. +- Let `Hash Subtree(Leaves)` be a procedure that produces the hash of a sub-tree in the following way: + - If `Leaves Len == 0` return the hash of the empty string. + - If `Leaves Len == 1` return a `Value Hash` with its `Hash` field set to `Hash Leaf(Leaves[0])`. + - Otherwise, compute `Split` as `Largest Power Of Two(Leaves Len)`: + - Let `Left` be the result of `Hash Subtree(Leaves[0:Split])`. + - Let `Right` be the result of `Hash Subtree(Leaves[Split:Leaves Len])`. + - Return `Hash Node(Left, Right)` +- Let `Compute Proof(Leaves, Index)` be the procedure that computes the proof for the leaf at index `Index`, defined as + follows: + - If `Leaves Len == 0` return an error, since at least one item is required to compute a proof. + - If `Leaves Len == 1` return a `Value Hash` with its `Hash` field set to `Hash Leaf(Leaves[0])`. + - If `Leaves Len == 2`: + - If `Index == 0` return a `Node` with: + - `Left` set to a `Value Hash` with its `Hash` field set to `Hash Leaf(Leaves[0])`. + - `Right` set to a `Leaf Hash` with its `Hash` field set to `Hash Leaf(Leaves[1])`. + - If `Index == 1` return a `Node` with: + - `Left` set to a `Leaf Hash` with its `Hash` field set to `Hash Leaf(Leaves[0])`. + - `Right` set to a `Value Hash` with its `Hash` field set to `Hash Leaf(Leaves[1])`. + - Otherwise, compute `Split` as `Largest Power Of Two(Leaves Len)`: + - If `Index < Split` return a `Node` with: + - `Left` set to the result of `Compute Proof(Leaves[0:Split], Index)`. + - `Right` set to a `Leaf Hash` with its `Hash` field set to `Hash Subtree(Leaves[Split:Leaves Len])`. + - Otherwise return a `Node` with: + - `Left` set to a `Leaf Hash` with its `Hash` field set to `Hash Subtree(Leaves[0:Split])`. + - `Right` set to the result of `Compute Proof(Leaves[Split:Leaves Len], Index)`. + +### Root Computation + +The **merkle root** is the result of `Hash Subtree(Leaves)`. + # Detailed design ## UTXO @@ -406,12 +585,158 @@ that the output and its ID match which in turn renders the Inputs Commitment unn More generally, this setup is also useful to prove that a given transaction produced an output with a certain state. -Such an Output ID Proof is a [merkle proof](https://en.wikipedia.org/wiki/Merkle_tree), with the array of the serialized -`Outputs` as the leaves of the tree. A proof is generated for a specific index in the array. +Such an Output ID Proof is a [merkle proof](#merkle-tree), with the array of the serialized `Outputs` as the `Leaves` of +the tree. A proof is serialized as follows: -TODO +
+ Output ID Proof +
A merkle proof that allows for cryptographic verification that an Output ID belongs to a given Output.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Slotuint32The slot in which the Output was created.
Output Indexuint16The index of the output in the transaction.
Transaction CommitmentByteArray[32]The commitment to the transaction.
Output Commitment Proof oneOf +
+ Node +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+ + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Merkle Tree Component Typeuint8Set to value 0 to denote a Node.
Left oneOf +
+ Node +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
+
+ Leaf Hash +
Contains the hash of a leaf in the tree. Defined in TIP-45 (Leaf Hash).
+
+
+ Value Hash +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Value Hash).
+
+
Right oneOf +
+ Node +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
+
+ Leaf Hash +
Contains the hash of a leaf in the tree. Defined in TIP-45 (Leaf Hash).
+
+
+ Value Hash +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Value Hash).
+
+
+
+
+ Leaf Hash +
Contains the hash of a leaf in the tree. Defined in TIP-45 (Leaf Hash).
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Merkle Tree Component Typeuint8Set to value 1 to denote a Leaf Hash.
Hash(uint8)ByteArrayThe hash of the leaf.
+
+
+ Value Hash +
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Value Hash).
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Merkle Tree Component Typeuint8Set to value 2 to denote a Value Hash.
Hash(uint8)ByteArrayThe hash of the value.
+
+
### Transaction ID @@ -420,8 +745,8 @@ A Transaction ID consists of two commitments, the _Transaction Commitment_ and t - Let `Transaction Bytes` be the concatenated serialization of the fields from `Network ID` to `Payload`. - Let `Transaction Commitment` be the BLAKE2b-256 hash of `Transaction Bytes`. -- Let `Output Commitment` be the root of the merkle tree over the `Outputs`. See [Output ID Proof](#output-id-proof) for - more details. +- Let `Output Commitment` be the [merkle root](#root-computation) over the merkle tree with the serialized `Outputs` as + its `Leaves`. - Let `ID` be the BLAKE2b-256 of the concatenation of `Transaction Commitment` and `Output Commitment`. - Construct the `Transaction ID` as the concatenation of the `ID` and the little-endian encoded `Creation Slot`. From 5875752dd946a0d05c53f085924e524ac3cfacf8 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 10:57:28 +0100 Subject: [PATCH 072/122] Add procedure for computing root from proof --- tips/TIP-0045/tip-0045.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 7ba973b0b..2d9f2607f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -215,7 +215,14 @@ A **merkle proof** is computed as follows: ### Root Computation -The **merkle root** is the result of `Hash Subtree(Leaves)`. +The **merkle root** can be computed from two different inputs: + +- From an array of `Leaves` by calling `Hash Subtree(Leaves)`. +- From a merkle proof by calling `Hash Component` the top-level component of the proof, where `Hash Component` is + defined as: + - If the component is a `Leaf Hash`, return its field `Hash`. + - If the component is a `Value Hash`, return its field `Hash`. + - If the component is a `Node` return `Hash Node(Hash Component(Left), Hash Component(Right))`. # Detailed design From 3a8a9e3623453f413b6e5b7b1ae34a7ed3ffa214 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 10:58:23 +0100 Subject: [PATCH 073/122] Clarify merkle tree input --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 2d9f2607f..fedabd7d1 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -217,7 +217,7 @@ A **merkle proof** is computed as follows: The **merkle root** can be computed from two different inputs: -- From an array of `Leaves` by calling `Hash Subtree(Leaves)`. +- From a merkle tree with its array of `Leaves` by calling `Hash Subtree(Leaves)`. - From a merkle proof by calling `Hash Component` the top-level component of the proof, where `Hash Component` is defined as: - If the component is a `Leaf Hash`, return its field `Hash`. From 9ee74106cf45bec30b7e169ef3cffd09003602ba Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 10:59:04 +0100 Subject: [PATCH 074/122] Add missing word --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index fedabd7d1..4bdd95c56 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -218,7 +218,7 @@ A **merkle proof** is computed as follows: The **merkle root** can be computed from two different inputs: - From a merkle tree with its array of `Leaves` by calling `Hash Subtree(Leaves)`. -- From a merkle proof by calling `Hash Component` the top-level component of the proof, where `Hash Component` is +- From a merkle proof by calling `Hash Component` on the top-level component of the proof, where `Hash Component` is defined as: - If the component is a `Leaf Hash`, return its field `Hash`. - If the component is a `Value Hash`, return its field `Hash`. From 99e455e1f74fcfb0e559aa4e05c64e21926056d5 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 11:04:40 +0100 Subject: [PATCH 075/122] Clarify `Leaf Hash` cannot be at top-level --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 4bdd95c56..310b024fc 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -45,8 +45,8 @@ to a Block Issuance Credits account. A [merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) is a tree data structure that allows for efficient proofs of inclusion. -A merkle tree proof is serialized as one of three possible schemas: A tree node, the hash of a leaf or the hash of the -value for which the proof is computed. +A merkle tree proof is serialized as one of two possible schemas: A tree node or the hash of the +value for which the proof is computed. A `Leaf Hash` schema is additionally used in tree nodes, but cannot be at the top-level of a proof. ### Node From d55c12c13407850d47d2dd9377a4cbb4576c24cf Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 11:05:38 +0100 Subject: [PATCH 076/122] Remove Leaf Hash from allowed proof schemas --- tips/TIP-0045/tip-0045.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 310b024fc..93ae4630b 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -687,33 +687,6 @@ A proof is serialized as follows:
-
- Leaf Hash -
Contains the hash of a leaf in the tree. Defined in TIP-45 (Leaf Hash).
- - - - - - - - - - - - - - - - -
- Name - - Type - - Description -
Merkle Tree Component Typeuint8Set to value 1 to denote a Leaf Hash.
Hash(uint8)ByteArrayThe hash of the leaf.
-
Value Hash
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Value Hash).
From 3e03c71f8d269467c9a2d660f5b9324377e04d80 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 11:08:03 +0100 Subject: [PATCH 077/122] Fix Node description --- tips/TIP-0045/tip-0045.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 93ae4630b..595b4e89a 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -52,7 +52,7 @@ value for which the proof is computed. A `Leaf Hash` schema is additionally used
Node -
Contains the hash of the value for which the proof is being computed.
+
A merkle tree node that contains two child components.
@@ -76,7 +76,7 @@ value for which the proof is computed. A `Leaf Hash` schema is additionally used
Node -
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
A merkle tree node that contains two child components. Defined in TIP-45 (Node).
Leaf Hash @@ -93,7 +93,7 @@ value for which the proof is computed. A `Leaf Hash` schema is additionally used
Node -
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
A merkle tree node that contains two child components. Defined in TIP-45 (Node).
Leaf Hash @@ -633,7 +633,7 @@ A proof is serialized as follows:
Node -
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
A merkle tree node that contains two child components. Defined in TIP-45 (Node).
@@ -656,7 +656,7 @@ A proof is serialized as follows:
Node -
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
A merkle tree node that contains two child components. Defined in TIP-45 (Node).
Leaf Hash @@ -673,7 +673,7 @@ A proof is serialized as follows:
Node -
Contains the hash of the value for which the proof is being computed. Defined in TIP-45 (Node).
+
A merkle tree node that contains two child components. Defined in TIP-45 (Node).
Leaf Hash From b0f827877b00e68d38c6aca88e72a0a9b663120f Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 11:28:48 +0100 Subject: [PATCH 078/122] Add type for merkle root --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 595b4e89a..03f9ea79b 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -215,7 +215,7 @@ A **merkle proof** is computed as follows: ### Root Computation -The **merkle root** can be computed from two different inputs: +The **merkle root** is a `ByteArray[32]` and can be computed from two different inputs: - From a merkle tree with its array of `Leaves` by calling `Hash Subtree(Leaves)`. - From a merkle proof by calling `Hash Component` on the top-level component of the proof, where `Hash Component` is From 2198aa5afd500d822e8e6ff054f37ba9e8688e90 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 11:47:55 +0100 Subject: [PATCH 079/122] Add Output ID Proof test vectors --- tips/TIP-0045/tip-0045.md | 203 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 03f9ea79b..254c1c988 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1401,6 +1401,209 @@ Transaction ID: 0x4125a5129ece49933dc24a38df82ecf62dd107bd07403648cb935478f394fc5a00001000 ``` +## Output ID Proof + +### Single Output + +An Output ID Proof for a transaction with a single output. + +Transaction (1 Output) (binary-encoded): + +``` +0x490443ee9f5955c4cf1fe14d00000100002aa135e8d314aed6c1576616e2d38b73589a221f914e2036938ff3294a1a04760000000001000000000000000001000040420f00000000000000000000000000010000150e514b09393e50122d27267510724c036743754277443079355c07152f222500 +``` + +Output ID Proof (Output Index 0) (json-encoded): + +```json +{ + "slot": 1306599375, + "outputIndex": 0, + "transactionCommitment": "0xf19781740f56e40014579adb74ca05c0d41d7395458e0c28f85204b4c3831a41", + "outputCommitmentProof": { + "type": 2, + "hash": "0x399c949535c72bb4b696dd1569f63915b5dd26822e7138349dde74a619ebe46a" + } +} +``` + +Output ID Proof (Output Index 0) (binary-encoded): + +``` +0xcf1fe14d0000f19781740f56e40014579adb74ca05c0d41d7395458e0c28f85204b4c3831a410220399c949535c72bb4b696dd1569f63915b5dd26822e7138349dde74a619ebe46a +``` + +### Five Outputs + +An Output ID Proof for a transaction with five outputs (not a power of two number of outputs). + +Transaction (5 Outputs) (binary-encoded): + +``` +0x490443ee9f5955c42a69480400000100002aa135e8d314aed6c1576616e2d38b73589a221f914e2036938ff3294a1a04760000000001000000000000000020000040420f000000000000000000000000000100004e6614257d0f11460315281e11274b272d465c0c06087778294b6e3e505f3200000040420f00000000000000000000000000010000424f1f695e16503f76476f7d541d051c016b130d502e4f3b502249152c5b7c54000040420f000000000000000000000000000100002d1a401d1470606f21733a184f3f4a713010651a2211033a690b3c6f21015c52000040420f00000000000000000000000000010000150c0d09214a7e6f4d11645f6d24406f6c3950090f782b37440d2719134f070d000040420f00000000000000000000000000010000652e08620a3b4c436d4a120b5d2f20723374403754232166792e4a29000e0f13000040420f00000000000000000000000000010000587b322e037420120c51576b2e2e4d205c3d46080c1d2971055c1a2069794838000040420f000000000000000000000000000100001f6311134d4736093340793d363459186943670103561f2d20436a090e3e451d000040420f00000000000000000000000000010000680113416907254311613a111a2b5b735f6e436c11220a372f0e5d28507c454a000040420f0000000000000000000000000001000034492d4f734b011f4878120053534c5f424066517b652f3609171a1e0c190709000040420f000000000000000000000000000100003b02352954251034220943153c631f6473595f6e5a2c157351606850621a1a5b000040420f000000000000000000000000000100005171045931294f265b675b1c3d557e0a5f56072e4a630b597b32742f65572e1e000040420f000000000000000000000000000100003c713b3d2d5e1f4b0348711b714c2b5e657e1968061c4e372e3d4b6921062331000040420f000000000000000000000000000100002c6f2a4741107c412f39593d4742457171630541721f6c4b7a3a04190e0a721c000040420f000000000000000000000000000100000f38217d311079404a0a7a762b0f125972795f22561577776a31415b531e173c000040420f000000000000000000000000000100007d1d1f5a7a2d492123187721446527791f5d172454495c0146683b6417567448000040420f0000000000000000000000000001000026586b714d20651e7d05032d7c2f431e2311174910237d725065502062195934000040420f0000000000000000000000000001000065287565632a66420063022f253f4564447624704f503b102a37610028246a7e000040420f00000000000000000000000000010000024a04246574032502172a36640d1935462714311f78120127581d47714f6d49000040420f00000000000000000000000000010000383d6958267d415462515d70590d160e09262c103e6a5b27334a2c0b3b644f79000040420f0000000000000000000000000001000065552c286513794c4769340f6d492f627337411b2a3f0f6558256d0d3c593b0c000040420f000000000000000000000000000100000f7573063d626b1163490a4362262a3a3044366d2d7d6a5e470a03675c121c26000040420f000000000000000000000000000100006e05524732705e325f651b3c0f1f045e1a6f23610e1b2066795e5a05116d3f24000040420f0000000000000000000000000001000034471553696a0031045b666d7a0b2c761260023a376a101e057556147d551c70000040420f00000000000000000000000000010000615e0716310e0326304a45552b4e6a1d7c4403704b240f1430643c5b513a4961000040420f00000000000000000000000000010000157c721907161a173e780d4e09285f4467422b790715335964765d3c4d205a0f000040420f000000000000000000000000000100003109614f3a1c511b442a2b1b5032393b3811216757577960745b4b623c447d2e000040420f00000000000000000000000000010000536133335c0867403f7a2a300e453d57205d595a66775e4634575e4803526709000040420f000000000000000000000000000100007424116251541033114a6277472b5017013b0f02225d363c493915647d107602000040420f00000000000000000000000000010000477862677e1a3b4a352f657355421a433a172a045c22306c406a594e65653d56000040420f00000000000000000000000000010000555d6964565e082a7248670537242266503c5e2f37735e3a2f14413163703978000040420f000000000000000000000000000100000c767a111356470e0f553f1b3e1a45431b6d745036505d23121f4d7e03594d27000040420f000000000000000000000000000100003c51753a1e207b4c4b6f4e6419161a393807104316584d0b1d7955766825521b00 +``` + +Output ID Proof (Output Index 2) (json-encoded): + +```json +{ + "slot": 1688515374, + "outputIndex": 2, + "transactionCommitment": "0x136e4de73da82ea76984d400a4d71fd827f54d05a411519870e6b12dfd6f715c", + "outputCommitmentProof": { + "type": 0, + "l": { + "type": 0, + "l": { + "type": 1, + "hash": "0x246e927334aa19300bd2e329e9b89f2a6cc317c14e26eef1974a70532df4e8d3" + }, + "r": { + "type": 0, + "l": { + "type": 2, + "hash": "0x2acb2638e5245e2a6e8fbf6ed3fce77d51dbd64d12d04663f3634f43edc62b71" + }, + "r": { + "type": 1, + "hash": "0xf6487a13fb0700732b6933f0ddbacb01ee5d282dd730fc08160fee2825be9f45" + } + } + }, + "r": { + "type": 1, + "hash": "0xa7226628c1173a6b8fef343b51fddcd140f283b8736838759183b179fad5e396" + } + } +} +``` + +Output ID Proof (Output Index 2) (binary-encoded): + +``` +0x2eb3a4640200136e4de73da82ea76984d400a4d71fd827f54d05a411519870e6b12dfd6f715c00000120246e927334aa19300bd2e329e9b89f2a6cc317c14e26eef1974a70532df4e8d30002202acb2638e5245e2a6e8fbf6ed3fce77d51dbd64d12d04663f3634f43edc62b710120f6487a13fb0700732b6933f0ddbacb01ee5d282dd730fc08160fee2825be9f450120a7226628c1173a6b8fef343b51fddcd140f283b8736838759183b179fad5e396 +``` + +### 32 Outputs + +An Output ID Proof for a transaction with 32 outputs. + +Transaction (32 Outputs) (binary-encoded): + +``` +0x490443ee9f5955c42a69480400000100002aa135e8d314aed6c1576616e2d38b73589a221f914e2036938ff3294a1a04760000000001000000000000000020000040420f000000000000000000000000000100004e6614257d0f11460315281e11274b272d465c0c06087778294b6e3e505f3200000040420f00000000000000000000000000010000424f1f695e16503f76476f7d541d051c016b130d502e4f3b502249152c5b7c54000040420f000000000000000000000000000100002d1a401d1470606f21733a184f3f4a713010651a2211033a690b3c6f21015c52000040420f00000000000000000000000000010000150c0d09214a7e6f4d11645f6d24406f6c3950090f782b37440d2719134f070d000040420f00000000000000000000000000010000652e08620a3b4c436d4a120b5d2f20723374403754232166792e4a29000e0f13000040420f00000000000000000000000000010000587b322e037420120c51576b2e2e4d205c3d46080c1d2971055c1a2069794838000040420f000000000000000000000000000100001f6311134d4736093340793d363459186943670103561f2d20436a090e3e451d000040420f00000000000000000000000000010000680113416907254311613a111a2b5b735f6e436c11220a372f0e5d28507c454a000040420f0000000000000000000000000001000034492d4f734b011f4878120053534c5f424066517b652f3609171a1e0c190709000040420f000000000000000000000000000100003b02352954251034220943153c631f6473595f6e5a2c157351606850621a1a5b000040420f000000000000000000000000000100005171045931294f265b675b1c3d557e0a5f56072e4a630b597b32742f65572e1e000040420f000000000000000000000000000100003c713b3d2d5e1f4b0348711b714c2b5e657e1968061c4e372e3d4b6921062331000040420f000000000000000000000000000100002c6f2a4741107c412f39593d4742457171630541721f6c4b7a3a04190e0a721c000040420f000000000000000000000000000100000f38217d311079404a0a7a762b0f125972795f22561577776a31415b531e173c000040420f000000000000000000000000000100007d1d1f5a7a2d492123187721446527791f5d172454495c0146683b6417567448000040420f0000000000000000000000000001000026586b714d20651e7d05032d7c2f431e2311174910237d725065502062195934000040420f0000000000000000000000000001000065287565632a66420063022f253f4564447624704f503b102a37610028246a7e000040420f00000000000000000000000000010000024a04246574032502172a36640d1935462714311f78120127581d47714f6d49000040420f00000000000000000000000000010000383d6958267d415462515d70590d160e09262c103e6a5b27334a2c0b3b644f79000040420f0000000000000000000000000001000065552c286513794c4769340f6d492f627337411b2a3f0f6558256d0d3c593b0c000040420f000000000000000000000000000100000f7573063d626b1163490a4362262a3a3044366d2d7d6a5e470a03675c121c26000040420f000000000000000000000000000100006e05524732705e325f651b3c0f1f045e1a6f23610e1b2066795e5a05116d3f24000040420f0000000000000000000000000001000034471553696a0031045b666d7a0b2c761260023a376a101e057556147d551c70000040420f00000000000000000000000000010000615e0716310e0326304a45552b4e6a1d7c4403704b240f1430643c5b513a4961000040420f00000000000000000000000000010000157c721907161a173e780d4e09285f4467422b790715335964765d3c4d205a0f000040420f000000000000000000000000000100003109614f3a1c511b442a2b1b5032393b3811216757577960745b4b623c447d2e000040420f00000000000000000000000000010000536133335c0867403f7a2a300e453d57205d595a66775e4634575e4803526709000040420f000000000000000000000000000100007424116251541033114a6277472b5017013b0f02225d363c493915647d107602000040420f00000000000000000000000000010000477862677e1a3b4a352f657355421a433a172a045c22306c406a594e65653d56000040420f00000000000000000000000000010000555d6964565e082a7248670537242266503c5e2f37735e3a2f14413163703978000040420f000000000000000000000000000100000c767a111356470e0f553f1b3e1a45431b6d745036505d23121f4d7e03594d27000040420f000000000000000000000000000100003c51753a1e207b4c4b6f4e6419161a393807104316584d0b1d7955766825521b00 +``` + +Output ID Proof (Output Index 0) (json-encoded): + +```json +{ + "slot": 71854378, + "outputIndex": 0, + "transactionCommitment": "0x904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e4", + "outputCommitmentProof": { + "type": 0, + "l": { + "type": 0, + "l": { + "type": 0, + "l": { + "type": 0, + "l": { + "type": 0, + "l": { + "type": 2, + "hash": "0x94406e58a06ee2dd1a99472caed7bed6d82b1ea3d692195bcfec18cabdb16674" + }, + "r": { + "type": 1, + "hash": "0x52d24e8cbbe5a92dc800e48a0135a5bb0f2d151c3345fbe122f63ad58f379cd8" + } + }, + "r": { + "type": 1, + "hash": "0x08de9a5e8b92bafd57fef8bc3d2f4a3dbcf7eaed3efc59bd966891f6df836d1b" + } + }, + "r": { + "type": 1, + "hash": "0xbc4ef7e28be5b72785eb1d00bb98cf190aad0a91d3bc1176b091c3bc5d5d5d53" + } + }, + "r": { + "type": 1, + "hash": "0x0571ab27a77432a693bc717c325402b79121a7bd718fb8adefa7f4e9bbec09a8" + } + }, + "r": { + "type": 1, + "hash": "0xa300087aefa3f2b42818c9edb5135ae5708dc2a3617daf9e654f09a96e4859d9" + } + } +} +``` + +Output ID Proof (Output Index 0) (binary-encoded): + +``` +0x2a6948040000904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e40000000000022094406e58a06ee2dd1a99472caed7bed6d82b1ea3d692195bcfec18cabdb16674012052d24e8cbbe5a92dc800e48a0135a5bb0f2d151c3345fbe122f63ad58f379cd8012008de9a5e8b92bafd57fef8bc3d2f4a3dbcf7eaed3efc59bd966891f6df836d1b0120bc4ef7e28be5b72785eb1d00bb98cf190aad0a91d3bc1176b091c3bc5d5d5d5301200571ab27a77432a693bc717c325402b79121a7bd718fb8adefa7f4e9bbec09a80120a300087aefa3f2b42818c9edb5135ae5708dc2a3617daf9e654f09a96e4859d9 +``` + +Output ID Proof (Output Index 28) (json-encoded): + +```json +{ + "slot": 71854378, + "outputIndex": 28, + "transactionCommitment": "0x904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e4", + "outputCommitmentProof": { + "type": 0, + "l": { + "type": 1, + "hash": "0x24c6ff8772cb21ecc443f6f12a4db2e624c4e5710793575c4c74242c38f641cc" + }, + "r": { + "type": 0, + "l": { + "type": 1, + "hash": "0xa058d1f3196d12febcd561cc60fb31ec4afaa935cb9781028e08a6b0df1bb5a2" + }, + "r": { + "type": 0, + "l": { + "type": 1, + "hash": "0xd3b68289625ab76aba41ce4254731a94cd047efbe449973bbde5fa74c11d9f8e" + }, + "r": { + "type": 0, + "l": { + "type": 0, + "l": { + "type": 2, + "hash": "0xcf02568a886a5c7c91c730d710d1b65b36a7656129817f408e1780905716ece9" + }, + "r": { + "type": 1, + "hash": "0x0045ac64f5fdea88388b16737c273d3326437d67fd802e32b6364a2bf32b9325" + } + }, + "r": { + "type": 1, + "hash": "0x93ae83d3031afb93c7e1eb0ef050d4b66c67fcd4f3cea280ffa5ea5deceb9223" + } + } + } + } + } +} +``` + +Output ID Proof (Output Index 28) (binary-encoded): + +``` +0x2a6948041c00904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e400012024c6ff8772cb21ecc443f6f12a4db2e624c4e5710793575c4c74242c38f641cc000120a058d1f3196d12febcd561cc60fb31ec4afaa935cb9781028e08a6b0df1bb5a2000120d3b68289625ab76aba41ce4254731a94cd047efbe449973bbde5fa74c11d9f8e00000220cf02568a886a5c7c91c730d710d1b65b36a7656129817f408e1780905716ece901200045ac64f5fdea88388b16737c273d3326437d67fd802e32b6364a2bf32b9325012093ae83d3031afb93c7e1eb0ef050d4b66c67fcd4f3cea280ffa5ea5deceb9223 +``` + # Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From deb7a3510a6b14c6cbcec7d69022d3c176df5755 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 12:40:26 +0100 Subject: [PATCH 080/122] Add note on how the output id proof can be used --- tips/TIP-0045/tip-0045.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 254c1c988..1a26a2ffc 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -45,8 +45,8 @@ to a Block Issuance Credits account. A [merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) is a tree data structure that allows for efficient proofs of inclusion. -A merkle tree proof is serialized as one of two possible schemas: A tree node or the hash of the -value for which the proof is computed. A `Leaf Hash` schema is additionally used in tree nodes, but cannot be at the top-level of a proof. +A merkle tree proof is serialized as one of two possible schemas: A tree node or the hash of the value for which the +proof is computed. A `Leaf Hash` schema is additionally used in tree nodes, but cannot be at the top-level of a proof. ### Node @@ -718,6 +718,10 @@ A proof is serialized as follows:
+By computing the [merkle root](#root-computation) from the `Output Commitment Proof` the +[Transaction ID](#transaction-id) and Output ID can be reconstructed, using the other fields of the proof. The +`Output ID Proof` can thus be used to prove that a given Output ID was derived from a given Output. + ### Transaction ID A Transaction ID consists of two commitments, the _Transaction Commitment_ and the _Ouptut Commitment_. It is a From b5115b3398b2be1d52e321d50cad36a6bfd3ba78 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 12:50:30 +0100 Subject: [PATCH 081/122] Improve merkle tree section, clarify serialization --- tips/TIP-0045/tip-0045.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 1a26a2ffc..fe3461456 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -43,12 +43,16 @@ to a Block Issuance Credits account. ## Merkle Tree A [merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) is a tree data structure that allows for efficient proofs of -inclusion. +inclusion. The serialization schemes defined here are only for a merkle proof of a value in the tree or for the tree's +merkle root. As the tree itself can be represented as the array of its leaves, it does not have its own serialization +scheme. + +### Merkle Proof A merkle tree proof is serialized as one of two possible schemas: A tree node or the hash of the value for which the proof is computed. A `Leaf Hash` schema is additionally used in tree nodes, but cannot be at the top-level of a proof. -### Node +#### Node
Node @@ -107,7 +111,7 @@ proof is computed. A `Leaf Hash` schema is additionally used in tree nodes, but
-### Leaf Hash +#### Leaf Hash
Leaf Hash @@ -137,7 +141,7 @@ proof is computed. A `Leaf Hash` schema is additionally used in tree nodes, but -### Value Hash +#### Value Hash
Value Hash @@ -167,7 +171,7 @@ proof is computed. A `Leaf Hash` schema is additionally used in tree nodes, but -### Proof Computation +#### Proof Computation A **merkle proof** is computed as follows: @@ -213,13 +217,13 @@ A **merkle proof** is computed as follows: - `Left` set to a `Leaf Hash` with its `Hash` field set to `Hash Subtree(Leaves[0:Split])`. - `Right` set to the result of `Compute Proof(Leaves[Split:Leaves Len], Index)`. -### Root Computation +### Merkle Root The **merkle root** is a `ByteArray[32]` and can be computed from two different inputs: -- From a merkle tree with its array of `Leaves` by calling `Hash Subtree(Leaves)`. -- From a merkle proof by calling `Hash Component` on the top-level component of the proof, where `Hash Component` is - defined as: +- From a merkle tree with its array of `Leaves` by executing `Hash Subtree(Leaves)`. +- From a merkle proof by executing `Hash Component` on the top-level component of the proof, where + `Hash Component(Merkle Tree Component)` is a procedure defined as: - If the component is a `Leaf Hash`, return its field `Hash`. - If the component is a `Value Hash`, return its field `Hash`. - If the component is a `Node` return `Hash Node(Hash Component(Left), Hash Component(Right))`. @@ -592,8 +596,8 @@ that the output and its ID match which in turn renders the Inputs Commitment unn More generally, this setup is also useful to prove that a given transaction produced an output with a certain state. -Such an Output ID Proof is a [merkle proof](#merkle-tree), with the array of the serialized `Outputs` as the `Leaves` of -the tree. +Such an Output ID Proof is a [merkle proof](#merkle-proof), with the array of the serialized `Outputs` as the `Leaves` +of the tree. A proof is serialized as follows: @@ -718,9 +722,9 @@ A proof is serialized as follows: -By computing the [merkle root](#root-computation) from the `Output Commitment Proof` the -[Transaction ID](#transaction-id) and Output ID can be reconstructed, using the other fields of the proof. The -`Output ID Proof` can thus be used to prove that a given Output ID was derived from a given Output. +By computing the [merkle root](#merkle-root) from the `Output Commitment Proof` the [Transaction ID](#transaction-id) +and Output ID can be reconstructed, using the other fields of the proof. The `Output ID Proof` can thus be used to prove +that a given Output ID was derived from a given Output. ### Transaction ID @@ -729,8 +733,8 @@ A Transaction ID consists of two commitments, the _Transaction Commitment_ and t - Let `Transaction Bytes` be the concatenated serialization of the fields from `Network ID` to `Payload`. - Let `Transaction Commitment` be the BLAKE2b-256 hash of `Transaction Bytes`. -- Let `Output Commitment` be the [merkle root](#root-computation) over the merkle tree with the serialized `Outputs` as - its `Leaves`. +- Let `Output Commitment` be the [merkle root](#merkle-root) over the merkle tree with the serialized `Outputs` as its + `Leaves`. - Let `ID` be the BLAKE2b-256 of the concatenation of `Transaction Commitment` and `Output Commitment`. - Construct the `Transaction ID` as the concatenation of the `ID` and the little-endian encoded `Creation Slot`. From aad1c43512e95c83735cb7a9f3cbda358656af2b Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 13:09:09 +0100 Subject: [PATCH 082/122] Fix header indentation --- tips/TIP-0045/tip-0045.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index fe3461456..4d59097c5 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -738,7 +738,7 @@ A Transaction ID consists of two commitments, the _Transaction Commitment_ and t - Let `ID` be the BLAKE2b-256 of the concatenation of `Transaction Commitment` and `Output Commitment`. - Construct the `Transaction ID` as the concatenation of the `ID` and the little-endian encoded `Creation Slot`. -#### Network ID +### Network ID The `Network ID` field of the transaction serves as a [replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). It is a unique value denoting whether @@ -752,13 +752,13 @@ bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpre | `testnet-1` | `1856588631910923207` | - | | `example-mynetwork` | `1967754805504104511` | - | -#### Creation Slot +### Creation Slot The transaction timestamp is expressed as a `Slot Index`, as there is no need for finer granularity. The validity of the transaction timestamp is checked in comparison with the `Block` timestamp. Therefore, it is performed at the level of semantic validation of a block, described in [TIP-0046](../TIP-0046/tip-0046.md). -#### Inputs +### Inputs The `Inputs` field holds the inputs to consume in order to fund the outputs of the Transaction Payload. Currently, there is one type of input: @@ -768,7 +768,7 @@ Currently, there is one type of input: Each input must be accompanied by a corresponding Unlock at the same index in the Unlocks part of the Transaction Payload. -##### UTXO Input +#### 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 @@ -808,7 +808,7 @@ output. -#### Context Inputs +### Context Inputs The `Context Inputs` field holds inputs that provide additional contextual information for the execution of a transaction, such as for different functionality related to accounts, commitments, or Mana rewards. Context inputs do @@ -818,7 +818,7 @@ not need to be unlocked. This TIP defines 3 types of context inputs: - _Block Issuance Credit Input_. - _Reward Input_. -##### Commitment Input +#### Commitment Input A _Commitment Input_ allows referencing a commitment to a certain slot. It is used to provide a notion of time for transaction execution that is linked to the containing _Block_'s _Issuing Time_. It proves that the time at the @@ -858,7 +858,7 @@ It is serialized as follows: -##### Block Issuance Credit Input +#### Block Issuance Credit Input A _Block Issuance Credit Input_ provides the BIC balance of a specific account as context to transaction execution of a specific slot. It is required for any _Account_ transition and destruction if the account contains a _Block Issuer @@ -898,7 +898,7 @@ It is serialized as follows: -##### Reward Input +#### Reward Input A _Reward Input_ indicates which transaction `Input` is claiming Mana rewards. It can reference an _Account Output_ with a _Staking Feature_ or a _Delegation Output_. The input is resolved by calculating the total amount of rewards the @@ -936,12 +936,12 @@ It is serialized as follows: -#### 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. -#### Allotments +### Allotments The `Allotments` field contains the list of all Mana allotments, the `Account ID`, and corresponding values that converts Mana provided by the inputs in the form of stored Mana in inputs or potential Mana derived from the inputs' @@ -951,7 +951,7 @@ form of _Block Issuance Credits_ to the account's BIC value. Note that _Block Issuance Credits_ are used to pay for the block issuance, they are burned on the slot commitment of the issuance slot. The good practice would be to always allot enough Mana to cover for the block issuance. -#### Payload +### Payload The _Transaction_ itself can contain another payload as described in general in [TIP-46](../TIP-0046/tip-0046.md). The [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ is unaffected by the possibly From 71a977576233f7cb2749e4acd25e255e37d93380 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 13:22:40 +0100 Subject: [PATCH 083/122] Remove outdated or duplicated native token rules --- tips/TIP-0045/tip-0045.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 4d59097c5..847608961 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1181,17 +1181,6 @@ funding transaction as a parent of the block containing the spending transaction - All _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - 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 count of all distinct native tokens present in the UTXOs referenced by inputs and in the transaction outputs must - not be larger than `Max Native Token Count`. A native token that occurs several times in both inputs and outputs is - counted as one. -- 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. **Mana specific semantic validation rules** (for description of Mana dynamics and the Mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): From de15975e7c61287f49907c9629d6d0db8bfe7ae5 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 25 Oct 2023 13:36:01 +0100 Subject: [PATCH 084/122] Add transaction capabilities --- tips/TIP-0045/tip-0045.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 847608961..7f2b50829 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -957,6 +957,36 @@ The _Transaction_ itself can contain another payload as described in general in [semantic validity](#semantic-validation) of the encapsulating _Transaction Payload_ is unaffected by the possibly contained payload. +### Transaction Capabilities + +Transaction Capabilities are represented as a `ByteArray` with a length prefix. For the transaction that contains them to be +valid, the following conditions must hold: + +- The length prefix must be `0` or `1`. + - This condition may be relaxed in the future and implementations should already allow for greater lengths. +- Bit indices start at `0`. For each byte, they are counted starting from the least-significant bit. If there was a + previous byte, the indices continue where the previous byte's indices left off. + - For example: In a list of two bytes with the bit patterns `0001 0000` and `0000 0100`, bits with indices `4` and + `10` are set. + +#### Capability Flags + +The following table shows the mapping from the bit pattern to the capability flags, where the `Flag Index` is the index +of the bit. + +This list is an Allowlist: If the bit is `1` (**set**) the transaction has the capability, if the bit is `0` (**unset**) it +does not have it. + +| Flag Index | Capability (if flag is set) | +| ---------- | ---------------------------- | +| 0 | Can burn Native Tokens. | +| 1 | Can burn Mana. | +| 2 | Can destroy Account Outputs. | +| 3 | Can destroy Foundry Outputs. | +| 4 | Can destroy NFT Outputs. | + +The transaction validation rules for each flag are defined where the respective asset to which it applies is defined. + ### Unlocks The `Unlocks` field holds the unlocks which unlock the inputs in a _Transaction_. From 76eabe24e6b4c45d055cee341015a3462e632a4c Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 26 Oct 2023 11:04:05 +0100 Subject: [PATCH 085/122] Cleanup scattered unlock validation rules --- tips/TIP-0045/tip-0045.md | 55 +++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 7f2b50829..29349f479 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -959,8 +959,8 @@ contained payload. ### Transaction Capabilities -Transaction Capabilities are represented as a `ByteArray` with a length prefix. For the transaction that contains them to be -valid, the following conditions must hold: +Transaction Capabilities are represented as a `ByteArray` with a length prefix. For the transaction that contains them +to be valid, the following conditions must hold: - The length prefix must be `0` or `1`. - This condition may be relaxed in the future and implementations should already allow for greater lengths. @@ -974,8 +974,8 @@ valid, the following conditions must hold: The following table shows the mapping from the bit pattern to the capability flags, where the `Flag Index` is the index of the bit. -This list is an Allowlist: If the bit is `1` (**set**) the transaction has the capability, if the bit is `0` (**unset**) it -does not have it. +This list is an Allowlist: If the bit is `1` (**set**) the transaction has the capability, if the bit is `0` (**unset**) +it does not have it. | Flag Index | Capability (if flag is set) | | ---------- | ---------------------------- | @@ -1056,12 +1056,19 @@ serialized as follows: -##### Unlock syntactic validation +##### Signature Unlock Syntactic Validation - `Signature` must contain an _Ed25519 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. +##### Signature Unlock Semantic Validation + +- 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. +- The `Signature` field must contain a signature, signing the BLAKE2b-256 hash of the serialized `Transaction` field + which is validated by the `Public Key`. + #### Reference Unlock The Reference Unlock references a previous Unlock (which must not be another Reference Unlock). It @@ -1095,7 +1102,7 @@ The Reference Unlock references a previous Unlock (which must not -##### Unlock syntactic validation +##### Reference Unlock Syntactic Validation - The _Reference Unlock_ at index `i` must have `Reference < i` and the unlock at index `Reference` must be a _Signature Unlock_. @@ -1110,6 +1117,11 @@ following structure of the Unlocks part: | 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`. | +##### Reference Unlock Semantic Validation + +- The _Signature Unlock_ at index `Reference`, to which the _Reference Unlock_ at index `i` points, must be a + [semantically valid signature unlock](#signature-unlock-semantic-validation) for the input at index `i`. + ### Work Score Let the work score of a transaction be defined as follows. @@ -1211,6 +1223,12 @@ funding transaction as a parent of the block containing the spending transaction - All _Reward Inputs_ must reference a Delegation Output or an Account Output which contains a Staking Feature. - 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. +- Each unlock must be valid with respect to the UTXO referenced by the input of the same index, according to their + respective semantic unlock validation rules. +- 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. +- 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. **Mana specific semantic validation rules** (for description of Mana dynamics and the Mana decay, see [TIP-39](../TIP-0039/tip-0039.md)): @@ -1241,31 +1259,6 @@ where: - Manao is the sum of all Mana values transferred to the outputs as stored Mana. - Manaa is the amount of all Mana values transferred to the accounts as block issuance credit. -#### Semantic criteria for each output and all its output features in the context of the following input: - -1. The _Transaction Payload_. -2. The list of UTXOs referenced by inputs. - -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_, the referenced _Signature Unlock_ must be valid with respect to the UTXO. -- If it is an _Account Unlock_: - - The address unlocking the UTXO must be an _Account Address_. - - The referenced _Unlock_ unlocks the account defined by the unlocking address of the UTXO. -- If it is an _NFT Unlock_: - - The address unlocking the UTXO must be an _NFT Address_. - - 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. - -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 ### Address reuse From c21ffe4879139977cc4c086d3f1e9a07e360524f Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 26 Oct 2023 11:07:46 +0100 Subject: [PATCH 086/122] Rename header --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 29349f479..9300d367c 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1216,7 +1216,7 @@ point in time, but the input transaction has not yet been confirmed by the netwo preserving their input-output order relations. 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. -#### Criteria defining whether a payload passes the semantic validation +#### Transaction 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. From 3d976427953a8872991dac483c9bba3579602620 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 27 Oct 2023 12:34:07 +0100 Subject: [PATCH 087/122] Add `Can destroy Anchor Outputs` tx cap flag --- tips/TIP-0045/tip-0045.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 9300d367c..48ba05c8d 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -982,8 +982,9 @@ it does not have it. | 0 | Can burn Native Tokens. | | 1 | Can burn Mana. | | 2 | Can destroy Account Outputs. | -| 3 | Can destroy Foundry Outputs. | -| 4 | Can destroy NFT Outputs. | +| 3 | Can destroy Anchor Outputs. | +| 4 | Can destroy Foundry Outputs. | +| 5 | Can destroy NFT Outputs. | The transaction validation rules for each flag are defined where the respective asset to which it applies is defined. From 49243d745a0a4f2ceb7bf364a4d027a249fa4cbb Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 27 Oct 2023 12:42:04 +0100 Subject: [PATCH 088/122] Point to Mana TX rules in TIP-39 --- tips/TIP-0045/tip-0045.md | 30 +----------------------------- 1 file changed, 1 insertion(+), 29 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 48ba05c8d..6ccbdd4bc 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1230,35 +1230,7 @@ funding transaction as a parent of the block containing the spending transaction outputs must be created/booked in the ledger. - 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. - -**Mana specific semantic validation rules** (for description of Mana dynamics and the Mana decay, see -[TIP-39](../TIP-0039/tip-0039.md)): - -- The transaction must not spend more Mana than allowed, briefly it must given following definitions: - -* `potentialMana` sum of values for each UTXO in inputs based on their creation times, transaction creation slot, and - decay function -* `allottedMana` as sum of all block issuance credits listed in `Allotments` transaction field. -* `inputStoredMana` sum of stored Mana from inputs decayed by `Decayfactor` -* `outputStoredMana` sum of stored Mana from outputs comply that: - `potentialMana + inputStoredMana ≥ allottedMana + outputStoredMana` The less or equal sign in the formula above - implies that it is possible for a user not to allot all the Mana he/she has rights to. This requirement is needed in - the case, because of any particularity, a user does not want to own Mana at all. Then, the user must be able to refuse - to allot or store their potential Mana. More specifically, for a transaction consuming a set of unspent outputs, we - have the following validation rule for Mana: - -Potential Mana Generated + Decayed Stored Mana ≥ Manao + Manaa, - -where: - -- `Potential Mana Generated` is the sum of all potential Mana values generated by consuming inputs (unspent outputs). To - calculate each summand of the sum, the algorithm and lookup table defined in [TIP-39](../TIP-0039/tip-0039.md) must be - used. -- `Decayed Stored Mana` is the sum of all stored Mana values on the consuming inputs (unspent outputs) with applied - decay. To calculate each summand of the sum, the algorithm and lookup table defined in - [TIP-39](../TIP-0039/tip-0039.md) must be used. -- Manao is the sum of all Mana values transferred to the outputs as stored Mana. -- Manaa is the amount of all Mana values transferred to the accounts as block issuance credit. +- The [semantic rules of Mana](../TIP-0039/tip-0039.md#mana-transaction-validation-rules) pass. ## Miscellaneous From ca06f0ec65f7ea4b6738322e16455cf8b09c710b Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 2 Nov 2023 12:02:53 +0100 Subject: [PATCH 089/122] Rename header to Signed Transaction --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 6ccbdd4bc..d790dfdc3 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -254,7 +254,7 @@ The following image depicts the flow of funds using UTXO: ![UTXO flow](utxo.png) -## Transaction Structure +## Signed Transaction ### Serialized Layout From 4314d1bda6c2f42007d53d486c36a7d1ad9e15b4 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 2 Nov 2023 12:28:18 +0100 Subject: [PATCH 090/122] Reference Tagged Data in TIP-53 instead --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index d790dfdc3..695a86348 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -504,7 +504,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Tagged Data -
Data with optional tag. Defined in TIP-23 (Specification).
+
Data with an optional tag. Defined in TIP-53 (Tagged Data).
@@ -526,7 +526,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Account Output -
Describes an account in the ledger that can be controlled by the state and governance controllers. Defined in TIP-42 (Account Output).
+
Describes an account in the ledger which can be used to issue blocks or stake for validation. Defined in TIP-42 (Account Output).
NFT Output From 7e3d2536d531a7d602ccc30f104eceb713fcbdfc Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 3 Nov 2023 10:02:56 +0100 Subject: [PATCH 091/122] Add Anchor Unlock to allowed unlocks --- tips/TIP-0045/tip-0045.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 695a86348..266bb7f4f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -462,7 +462,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Allotment -
Allots Mana to the account identified by the contained Account ID. Defined in TIP-45 (Allotment).
+
Allots Mana to the account identified by the contained Account ID.
From 2d33b5bb4c179af354daaba3421099fd1c17f5ed Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 24 Nov 2023 10:29:27 +0100 Subject: [PATCH 097/122] Update work score with Native Token Feature --- tips/TIP-0045/tip-0045.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 91dc14564..2051aa2a5 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1138,9 +1138,10 @@ Let the work score of a transaction be defined as follows. serialized _Transaction_. - Let `Input Score` be `Inputs Count * Work Score Parameters::Input`. - Let `Context Input Score` be `Context Inputs Count * Work Score Parameters::Context Input`. -- Let `Output Score` be the sum of work scores of each output `Output` in `Outputs`: - - Let `Native Token Score` be `Work Score Parameters::Native Token * Native Tokens Count` if `Output` contains - `Native Tokens`, `0` otherwise. +- Let `Outputs Score` be the sum of work scores of each output `Output` in `Outputs`, where the work score of `Output` + is defined as: + - Let `Native Token Score` be `Work Score Parameters::Native Token` if `Output` contains a `Native Token Feature`, `0` + otherwise. - Let `Token Scheme Score` be `Work Score Parameters::Native Token` if `Output` contains a _Simple Token Scheme_, `0` otherwise. - Let `Staking Score` be `Work Score Parameters::Staking` if `Output` contains a _Staking Feature_, `0` otherwise. @@ -1151,7 +1152,7 @@ Let the work score of a transaction be defined as follows. - Let `Allotment Score` be `Work Score Parameters::Allotment * Allotments Count`. - Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ within `Unlocks`. - Signature work scores are defined in TIP-46. -- Return `Size Score + Input Score + Context Input Score + Output Score + Allotment Score + Signature Score`. +- Return `Size Score + Input Score + Context Input Score + Outputs Score + Allotment Score + Signature Score`. ## Validation From b6c7a027efacd073fca3360ede57bf51d3a99c2d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 27 Nov 2023 13:33:41 +0100 Subject: [PATCH 098/122] Update Transaction ID calculation example --- tips/TIP-0045/tip-0045.md | 52 +++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 2051aa2a5..af1996b65 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1286,11 +1286,11 @@ Transaction (json-encoded): "contextInputs": [ { "type": 1, - "commitmentId": "0x760702593b59500420722f3a1634005f11360b133a030f46282c0f690a55084855000000" + "commitmentId": "0x3c3709521a0b0c6d5928645a635159516d1c7933082074024c5f05111c7d4f1a55000000" }, { "type": 2, - "accountId": "0x3407603d0f725b7e7214205f254305743d5362512f36153236435e796b6a1c2e" + "accountId": "0x387957486f4d5e623a15266655282836167b6b35432f0f112b03465860670127" }, { "type": 3, @@ -1300,23 +1300,23 @@ Transaction (json-encoded): "inputs": [ { "type": 0, - "transactionId": "0x3ca1f23b83708ee7c59d6d7fe71453106bb0a0abc1c9cc4b340c755238ae6daa00000000", + "transactionId": "0x87d8ae3c94e403cb75c3b755fdd521cf389cf5edb3d7d425e7f2da1cdf7fe8dd00000000", "transactionOutputIndex": 0 }, { "type": 0, - "transactionId": "0xecb673f194640b2067b8da136b5f5437c2c723e7f3fdaa53984d7588ed21071a00000000", + "transactionId": "0xc65092dd8d4b9740b6af10e9f7735c37f9c36065b8a00286f96226a55718a73c00000000", "transactionOutputIndex": 0 } ], "allotments": [ { - "accountID": "0x0e0f253479566103415e29060f79772445531564733e214b54084358413f7c70", - "value": "6648" + "accountId": "0x4c7b105d1032286f594c45622a6d724e751a407154625a574f524b001c09707d", + "mana": "6131" }, { - "accountID": "0x445e204c1f747503106b5663664c43591e63235804057c445d073a5f10597e2d", - "value": "9988" + "accountId": "0x735b594c2303623d625e3949125a7966796d1e13591d01491d52693c1b717069", + "mana": "5366" } ], "capabilities": "0x01", @@ -1330,15 +1330,15 @@ Transaction (json-encoded): "type": 0, "address": { "type": 0, - "pubKeyHash": "0x7f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e" + "pubKeyHash": "0x39962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b913653" } } ], "features": [ { - "type": 4, - "id": "0x082a1c2429352945216e3f547a03226b2f014d3d2e185a2459473a362c4d124d511a6c2d6000", - "amount": "0xd54f92ae8c34fbb4" + "type": 5, + "id": "0x08065b07165742126157243d111f692a504d325c00224e443f79724b630a1641793f01010c00", + "amount": "0x50745d2c83723e2b" } ] }, @@ -1347,28 +1347,22 @@ Transaction (json-encoded): "amount": "100000", "mana": "5000", "accountId": "0x0000000000000000000000000000000000000000000000000000000000000000", - "stateIndex": 0, "foundryCounter": 0, "unlockConditions": [ { - "type": 4, - "address": { - "type": 0, - "pubKeyHash": "0x7f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e" - } - }, - { - "type": 5, + "type": 0, "address": { "type": 0, - "pubKeyHash": "0x7f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e" + "pubKeyHash": "0x39962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b913653" } } ], "features": [ { - "type": 2, - "data": "0x1e69562e763b1125080c1a7161390e42" + "type": 3, + "entries": { + "hello": "0x776f726c64" + } } ] } @@ -1379,8 +1373,8 @@ Transaction (json-encoded): "type": 0, "signature": { "type": 0, - "publicKey": "0xa6bbccb2380a3a941a7bfdd5f2afcb8a6f5236bbe12ae8b931b593efd76864b6", - "signature": "0x98a18fd0083c7d9b6b05e218c7f764bb915148762ce342d795f7acac4083b40dbfc01f5fd23f6d1e652eee0e5951b87dd6307adf1389f8f16c08ade12be01c0a" + "publicKey": "0x62c30511c661dff48f85da4ef3b277986dfd0370165bb25c65e835c6fcdffa78", + "signature": "0x820f8aa63dc815515b888d64ac57d749484a30af8cf723d80bfb977d4d6f9c031568f22fdf6cb295853043088935bb61c3160ea5afeedab75418a94e396f3501" } }, { @@ -1391,16 +1385,16 @@ Transaction (json-encoded): } ``` -Transaction (binary-encoded): +Transaction (hex-encoded binary serialization): ``` -0x01490443ee9f5955c400001000030001760702593b59500420722f3a1634005f11360b133a030f46282c0f690a55084855000000023407603d0f725b7e7214205f254305743d5362512f36153236435e796b6a1c2e0300000200003ca1f23b83708ee7c59d6d7fe71453106bb0a0abc1c9cc4b340c755238ae6daa00000000000000ecb673f194640b2067b8da136b5f5437c2c723e7f3fdaa53984d7588ed21071a00000000000002000e0f253479566103415e29060f79772445531564733e214b54084358413f7c70f819000000000000445e204c1f747503106b5663664c43591e63235804057c445d073a5f10597e2d0427000000000000010100000000020000a08601000000000000000000000000000100007f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e0104082a1c2429352945216e3f547a03226b2f014d3d2e185a2459473a362c4d124d511a6c2d6000b4fb348cae924fd500000000000000000000000000000000000000000000000001a08601000000000088130000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000204007f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e05007f34f61bd0ecd2654a1ec3c9bf3fbc0de91abcbd7397e09faaaffc89d17a8f6e010210001e69562e763b1125080c1a7161390e420002000000a6bbccb2380a3a941a7bfdd5f2afcb8a6f5236bbe12ae8b931b593efd76864b698a18fd0083c7d9b6b05e218c7f764bb915148762ce342d795f7acac4083b40dbfc01f5fd23f6d1e652eee0e5951b87dd6307adf1389f8f16c08ade12be01c0a010000 +0x01490443ee9f5955c4000010000300013c3709521a0b0c6d5928645a635159516d1c7933082074024c5f05111c7d4f1a5500000002387957486f4d5e623a15266655282836167b6b35432f0f112b0346586067012703000002000087d8ae3c94e403cb75c3b755fdd521cf389cf5edb3d7d425e7f2da1cdf7fe8dd00000000000000c65092dd8d4b9740b6af10e9f7735c37f9c36065b8a00286f96226a55718a73c00000000000002004c7b105d1032286f594c45622a6d724e751a407154625a574f524b001c09707df317000000000000735b594c2303623d625e3949125a7966796d1e13591d01491d52693c1b717069f614000000000000010100000000020000a086010000000000000000000000000001000039962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b913653010508065b07165742126157243d111f692a504d325c00224e443f79724b630a1641793f01010c002b3e72832c5d745000000000000000000000000000000000000000000000000001a086010000000000881300000000000000000000000000000000000000000000000000000000000000000000000000000000000001000039962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b9136530103010568656c6c6f0500776f726c64000200000062c30511c661dff48f85da4ef3b277986dfd0370165bb25c65e835c6fcdffa78820f8aa63dc815515b888d64ac57d749484a30af8cf723d80bfb977d4d6f9c031568f22fdf6cb295853043088935bb61c3160ea5afeedab75418a94e396f3501010000 ``` Transaction ID: ``` -0x4125a5129ece49933dc24a38df82ecf62dd107bd07403648cb935478f394fc5a00001000 +0x45efc26ddcbbadb0e58f8f1d220fe50f72cc52c8720a60e7d5aceb826a77f1ce00001000 ``` ## Output ID Proof From d55a77152ce2bea654ba834c599eeccac55a90cf Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 4 Dec 2023 09:07:32 +0100 Subject: [PATCH 099/122] Remove unnecessary creation slot syntactic rule --- tips/TIP-0045/tip-0045.md | 1 - 1 file changed, 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index af1996b65..47db059b1 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1175,7 +1175,6 @@ The following criteria defines whether a payload passes the syntactical validati - Transaction: - `Network ID` must match the value of the current network. - - `CreationTime` must be a valid `Slot index` timestamp. - Inputs: - `Inputs Count` must be `0 < x ≤ Max Inputs Count`. - For each input the following must be true: From c4c66ecf52ae39243a2e17f950f9a68e77b07e2d Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 12 Dec 2023 17:25:50 +0100 Subject: [PATCH 100/122] Require Reward Input to point within inputs range --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 47db059b1..70bedad83 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1185,7 +1185,7 @@ The following criteria defines whether a payload passes the syntactical validati - `Context Inputs Count` must be `0 ≤ x ≤ Max Inputs Count`. - `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). - There must be zero or one _Commitment Input_. - - All _Rewards Inputs_ must reference a different `Index` and it must hold that: `Index <= Max Inputs Count`. + - All _Reward Inputs_ must reference a different `Index` and it must hold that: `Index < Inputs Count`. - All _Block Issuance Credit Inputs_ must reference a different `Account ID`. - Outputs: - `Outputs Count` must be `0 < x ≤ Max Outputs Count`. From efd3adfed59202b5c76b91ac2ac6c979333d51c2 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 13 Dec 2023 15:49:31 +0100 Subject: [PATCH 101/122] Update TX ID test vector w/ consistent values --- tips/TIP-0045/tip-0045.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 70bedad83..868fc5b11 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1280,16 +1280,16 @@ Transaction (json-encoded): { "type": 1, "transaction": { - "networkId": "14147312347886322761", + "networkId": "8342982141227064571", "creationSlot": 1048576, "contextInputs": [ { "type": 1, - "commitmentId": "0x3c3709521a0b0c6d5928645a635159516d1c7933082074024c5f05111c7d4f1a55000000" + "commitmentId": "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a" }, { "type": 2, - "accountId": "0x387957486f4d5e623a15266655282836167b6b35432f0f112b03465860670127" + "accountId": "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" }, { "type": 3, @@ -1299,23 +1299,23 @@ Transaction (json-encoded): "inputs": [ { "type": 0, - "transactionId": "0x87d8ae3c94e403cb75c3b755fdd521cf389cf5edb3d7d425e7f2da1cdf7fe8dd00000000", + "transactionId": "0xf09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000", "transactionOutputIndex": 0 }, { "type": 0, - "transactionId": "0xc65092dd8d4b9740b6af10e9f7735c37f9c36065b8a00286f96226a55718a73c00000000", + "transactionId": "0xd2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa826100000000", "transactionOutputIndex": 0 } ], "allotments": [ { - "accountId": "0x4c7b105d1032286f594c45622a6d724e751a407154625a574f524b001c09707d", - "mana": "6131" + "accountId": "0x7e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507", + "mana": "2285" }, { - "accountId": "0x735b594c2303623d625e3949125a7966796d1e13591d01491d52693c1b717069", - "mana": "5366" + "accountId": "0x476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b6915", + "mana": "2189" } ], "capabilities": "0x01", @@ -1329,15 +1329,15 @@ Transaction (json-encoded): "type": 0, "address": { "type": 0, - "pubKeyHash": "0x39962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b913653" + "pubKeyHash": "0xed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a" } } ], "features": [ { "type": 5, - "id": "0x08065b07165742126157243d111f692a504d325c00224e443f79724b630a1641793f01010c00", - "amount": "0x50745d2c83723e2b" + "id": "0x086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00", + "amount": "0x14be8149371263f4" } ] }, @@ -1352,7 +1352,7 @@ Transaction (json-encoded): "type": 0, "address": { "type": 0, - "pubKeyHash": "0x39962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b913653" + "pubKeyHash": "0xed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a" } } ], @@ -1372,8 +1372,8 @@ Transaction (json-encoded): "type": 0, "signature": { "type": 0, - "publicKey": "0x62c30511c661dff48f85da4ef3b277986dfd0370165bb25c65e835c6fcdffa78", - "signature": "0x820f8aa63dc815515b888d64ac57d749484a30af8cf723d80bfb977d4d6f9c031568f22fdf6cb295853043088935bb61c3160ea5afeedab75418a94e396f3501" + "publicKey": "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac", + "signature": "0x328034c1701ae304fcf69b542ceeacf7aa2e94df6e2191b0e1e345c62c49d4afa5f4f58ccc8fa3d400e8c01a19719cf26820337d5c35d5cb5fcafe6d97eab402" } }, { @@ -1387,13 +1387,13 @@ Transaction (json-encoded): Transaction (hex-encoded binary serialization): ``` -0x01490443ee9f5955c4000010000300013c3709521a0b0c6d5928645a635159516d1c7933082074024c5f05111c7d4f1a5500000002387957486f4d5e623a15266655282836167b6b35432f0f112b0346586067012703000002000087d8ae3c94e403cb75c3b755fdd521cf389cf5edb3d7d425e7f2da1cdf7fe8dd00000000000000c65092dd8d4b9740b6af10e9f7735c37f9c36065b8a00286f96226a55718a73c00000000000002004c7b105d1032286f594c45622a6d724e751a407154625a574f524b001c09707df317000000000000735b594c2303623d625e3949125a7966796d1e13591d01491d52693c1b717069f614000000000000010100000000020000a086010000000000000000000000000001000039962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b913653010508065b07165742126157243d111f692a504d325c00224e443f79724b630a1641793f01010c002b3e72832c5d745000000000000000000000000000000000000000000000000001a086010000000000881300000000000000000000000000000000000000000000000000000000000000000000000000000000000001000039962151ac0109c4f5f62f59a72cbec19ec9d7e0f00b5b8bd67caf497b9136530103010568656c6c6f0500776f726c64000200000062c30511c661dff48f85da4ef3b277986dfd0370165bb25c65e835c6fcdffa78820f8aa63dc815515b888d64ac57d749484a30af8cf723d80bfb977d4d6f9c031568f22fdf6cb295853043088935bb61c3160ea5afeedab75418a94e396f3501010000 +0x01fb5c44ef0d3ac873000010000300013a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a0217432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a030000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa826100000000000002007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0103010568656c6c6f0500776f726c6400020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac328034c1701ae304fcf69b542ceeacf7aa2e94df6e2191b0e1e345c62c49d4afa5f4f58ccc8fa3d400e8c01a19719cf26820337d5c35d5cb5fcafe6d97eab402010000 ``` Transaction ID: ``` -0x45efc26ddcbbadb0e58f8f1d220fe50f72cc52c8720a60e7d5aceb826a77f1ce00001000 +0x62f7a1a63f3bfd5f0872b9d2689efaa83af530680d849e3383c07c35101dfa6900001000 ``` ## Output ID Proof From 11165f45a9e6794684dd7baa56846a87277586d9 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 19 Dec 2023 14:50:48 +0100 Subject: [PATCH 102/122] Split Input and Context Inputs --- tips/TIP-0045/tip-0045.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 868fc5b11..6f86c52fc 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -343,9 +343,9 @@ The following table describes the entirety of a _Signed Transaction_ in its seri - + - + @@ -370,9 +370,9 @@ The following table describes the entirety of a _Signed Transaction_ in its seri - + - + @@ -397,9 +397,9 @@ The following table describes the entirety of a _Signed Transaction_ in its seri - + - + @@ -851,9 +851,9 @@ It is serialized as follows: - + - + @@ -891,9 +891,9 @@ It is serialized as follows: - + - + @@ -929,9 +929,9 @@ It is serialized as follows: - + - + From 050274a7258ca3225d44337d829c4fcf91f25932 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 19 Dec 2023 14:52:20 +0100 Subject: [PATCH 103/122] Update Transaction ID Test Vector --- tips/TIP-0045/tip-0045.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 6f86c52fc..5fe6c099b 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1284,15 +1284,15 @@ Transaction (json-encoded): "creationSlot": 1048576, "contextInputs": [ { - "type": 1, + "type": 0, "commitmentId": "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a" }, { - "type": 2, + "type": 1, "accountId": "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" }, { - "type": 3, + "type": 2, "index": 0 } ], @@ -1373,7 +1373,7 @@ Transaction (json-encoded): "signature": { "type": 0, "publicKey": "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac", - "signature": "0x328034c1701ae304fcf69b542ceeacf7aa2e94df6e2191b0e1e345c62c49d4afa5f4f58ccc8fa3d400e8c01a19719cf26820337d5c35d5cb5fcafe6d97eab402" + "signature": "0x469a3426bf88a8ed1a0346892a519e5b56cd8f686b1ce9b904898a62b25a8f96124f4ad3db9b6241fee5be98d067d083e91b2c4ce96e91fb8bc0871443764f00" } }, { @@ -1387,13 +1387,13 @@ Transaction (json-encoded): Transaction (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac873000010000300013a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a0217432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a030000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa826100000000000002007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0103010568656c6c6f0500776f726c6400020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac328034c1701ae304fcf69b542ceeacf7aa2e94df6e2191b0e1e345c62c49d4afa5f4f58ccc8fa3d400e8c01a19719cf26820337d5c35d5cb5fcafe6d97eab402010000 +0x01fb5c44ef0d3ac873000010000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a0117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa826100000000000002007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0103010568656c6c6f0500776f726c6400020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac469a3426bf88a8ed1a0346892a519e5b56cd8f686b1ce9b904898a62b25a8f96124f4ad3db9b6241fee5be98d067d083e91b2c4ce96e91fb8bc0871443764f00010000 ``` Transaction ID: ``` -0x62f7a1a63f3bfd5f0872b9d2689efaa83af530680d849e3383c07c35101dfa6900001000 +0x7845f92882df0f16860f1adc076a2c3b6b33416a0eee2fd225f2ac74f6def99b00001000 ``` ## Output ID Proof From 206b568292093defee48b6aadf69fb1a10c58aec Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 19 Dec 2023 16:00:42 +0100 Subject: [PATCH 104/122] Update Output ID Proof test vectors --- tips/TIP-0045/tip-0045.md | 117 ++++++++++++++++++++++---------------- 1 file changed, 69 insertions(+), 48 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 5fe6c099b..b756bc570 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1402,100 +1402,107 @@ Transaction ID: An Output ID Proof for a transaction with a single output. -Transaction (1 Output) (binary-encoded): +Signed Transaction (1 Output) (hex-encoded binary serialization): ``` -0x490443ee9f5955c4cf1fe14d00000100002aa135e8d314aed6c1576616e2d38b73589a221f914e2036938ff3294a1a04760000000001000000000000000001000040420f00000000000000000000000000010000150e514b09393e50122d27267510724c036743754277443079355c07152f222500 +0x01fb5c44ef0d3ac873000010000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000002000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d00010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac45fda13b781c8957f22a278061cba17cc4ed4f31b5c592a7cd455b06143a4a1e9102def005ea39f859aff77cb3879334a1a694b1678b722afae8d4c37d1a9400 ``` Output ID Proof (Output Index 0) (json-encoded): ```json { - "slot": 1306599375, + "slot": 1048576, "outputIndex": 0, - "transactionCommitment": "0xf19781740f56e40014579adb74ca05c0d41d7395458e0c28f85204b4c3831a41", + "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", "outputCommitmentProof": { - "type": 2, - "hash": "0x399c949535c72bb4b696dd1569f63915b5dd26822e7138349dde74a619ebe46a" + "type": 0, + "l": { + "type": 2, + "hash": "0xb750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b" + }, + "r": { + "type": 1, + "hash": "0x6b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab72" + } } } ``` -Output ID Proof (Output Index 0) (binary-encoded): +Output ID Proof (Output Index 0) (hex-encoded binary serialization): ``` -0xcf1fe14d0000f19781740f56e40014579adb74ca05c0d41d7395458e0c28f85204b4c3831a410220399c949535c72bb4b696dd1569f63915b5dd26822e7138349dde74a619ebe46a +0x000010000000135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589000220b750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b01206b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab72 ``` ### Five Outputs An Output ID Proof for a transaction with five outputs (not a power of two number of outputs). -Transaction (5 Outputs) (binary-encoded): +Signed Transaction (5 Outputs) (hex-encoded binary serialization): ``` -0x490443ee9f5955c42a69480400000100002aa135e8d314aed6c1576616e2d38b73589a221f914e2036938ff3294a1a04760000000001000000000000000020000040420f000000000000000000000000000100004e6614257d0f11460315281e11274b272d465c0c06087778294b6e3e505f3200000040420f00000000000000000000000000010000424f1f695e16503f76476f7d541d051c016b130d502e4f3b502249152c5b7c54000040420f000000000000000000000000000100002d1a401d1470606f21733a184f3f4a713010651a2211033a690b3c6f21015c52000040420f00000000000000000000000000010000150c0d09214a7e6f4d11645f6d24406f6c3950090f782b37440d2719134f070d000040420f00000000000000000000000000010000652e08620a3b4c436d4a120b5d2f20723374403754232166792e4a29000e0f13000040420f00000000000000000000000000010000587b322e037420120c51576b2e2e4d205c3d46080c1d2971055c1a2069794838000040420f000000000000000000000000000100001f6311134d4736093340793d363459186943670103561f2d20436a090e3e451d000040420f00000000000000000000000000010000680113416907254311613a111a2b5b735f6e436c11220a372f0e5d28507c454a000040420f0000000000000000000000000001000034492d4f734b011f4878120053534c5f424066517b652f3609171a1e0c190709000040420f000000000000000000000000000100003b02352954251034220943153c631f6473595f6e5a2c157351606850621a1a5b000040420f000000000000000000000000000100005171045931294f265b675b1c3d557e0a5f56072e4a630b597b32742f65572e1e000040420f000000000000000000000000000100003c713b3d2d5e1f4b0348711b714c2b5e657e1968061c4e372e3d4b6921062331000040420f000000000000000000000000000100002c6f2a4741107c412f39593d4742457171630541721f6c4b7a3a04190e0a721c000040420f000000000000000000000000000100000f38217d311079404a0a7a762b0f125972795f22561577776a31415b531e173c000040420f000000000000000000000000000100007d1d1f5a7a2d492123187721446527791f5d172454495c0146683b6417567448000040420f0000000000000000000000000001000026586b714d20651e7d05032d7c2f431e2311174910237d725065502062195934000040420f0000000000000000000000000001000065287565632a66420063022f253f4564447624704f503b102a37610028246a7e000040420f00000000000000000000000000010000024a04246574032502172a36640d1935462714311f78120127581d47714f6d49000040420f00000000000000000000000000010000383d6958267d415462515d70590d160e09262c103e6a5b27334a2c0b3b644f79000040420f0000000000000000000000000001000065552c286513794c4769340f6d492f627337411b2a3f0f6558256d0d3c593b0c000040420f000000000000000000000000000100000f7573063d626b1163490a4362262a3a3044366d2d7d6a5e470a03675c121c26000040420f000000000000000000000000000100006e05524732705e325f651b3c0f1f045e1a6f23610e1b2066795e5a05116d3f24000040420f0000000000000000000000000001000034471553696a0031045b666d7a0b2c761260023a376a101e057556147d551c70000040420f00000000000000000000000000010000615e0716310e0326304a45552b4e6a1d7c4403704b240f1430643c5b513a4961000040420f00000000000000000000000000010000157c721907161a173e780d4e09285f4467422b790715335964765d3c4d205a0f000040420f000000000000000000000000000100003109614f3a1c511b442a2b1b5032393b3811216757577960745b4b623c447d2e000040420f00000000000000000000000000010000536133335c0867403f7a2a300e453d57205d595a66775e4634575e4803526709000040420f000000000000000000000000000100007424116251541033114a6277472b5017013b0f02225d363c493915647d107602000040420f00000000000000000000000000010000477862677e1a3b4a352f657355421a433a172a045c22306c406a594e65653d56000040420f00000000000000000000000000010000555d6964565e082a7248670537242266503c5e2f37735e3a2f14413163703978000040420f000000000000000000000000000100000c767a111356470e0f553f1b3e1a45431b6d745036505d23121f4d7e03594d27000040420f000000000000000000000000000100003c51753a1e207b4c4b6f4e6419161a393807104316584d0b1d7955766825521b00 +0x01fb5c44ef0d3ac873000010000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000006000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d000040420f00000000000000000000000000010000c3d789866209202d21895e9a5a69ceb4b1fba08f53237c697e32cf6780a89a71000040420f000000000000000000000000000100008b1697f39c48f841e78e9e3fb2eae08d6af3463fc26fdfbf8ae23ad86ef5353d000040420f00000000000000000000000000010000145a6400ae4ce60e2192b6e538bb790a774db03070afaff1f0c83beedd15fa65000040420f00000000000000000000000000010000f25fbe26abe7ddc7b1ba9fc94a8f6c5a1ac025b0f8027fb7c5ec6047b771527100010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac6d0979cc04a7effca39f80ee0dbb0208f4812d0de8b38fc2fbd9b0c707cde292f896a65250cc7a64284596f386142634958a3ad7def2b70effcc94122feb0107 ``` Output ID Proof (Output Index 2) (json-encoded): ```json { - "slot": 1688515374, + "slot": 1048576, "outputIndex": 2, - "transactionCommitment": "0x136e4de73da82ea76984d400a4d71fd827f54d05a411519870e6b12dfd6f715c", + "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", "outputCommitmentProof": { "type": 0, "l": { "type": 0, "l": { "type": 1, - "hash": "0x246e927334aa19300bd2e329e9b89f2a6cc317c14e26eef1974a70532df4e8d3" + "hash": "0xdb9fc09b2bdea181fd4f9775116a2ec3c27c93a7ce0ce8f5835fda73bfd09b49" }, "r": { "type": 0, "l": { "type": 2, - "hash": "0x2acb2638e5245e2a6e8fbf6ed3fce77d51dbd64d12d04663f3634f43edc62b71" + "hash": "0xe6fc3cdc50433760d43adfe52426648597c092d8973a30529ad0058d6a03b55d" }, "r": { "type": 1, - "hash": "0xf6487a13fb0700732b6933f0ddbacb01ee5d282dd730fc08160fee2825be9f45" + "hash": "0x7392fe9c9e518a0bc1b0f032e003dbf73096fb95a8bfdbfe05e05f67e0894038" } } }, "r": { "type": 1, - "hash": "0xa7226628c1173a6b8fef343b51fddcd140f283b8736838759183b179fad5e396" + "hash": "0xc00b8503cb3aa5473f1a4b4d68cdad468c52e628fdf8dc175caae2d8bec75297" } } } ``` -Output ID Proof (Output Index 2) (binary-encoded): +Output ID Proof (Output Index 2) (hex-encoded binary serialization): ``` -0x2eb3a4640200136e4de73da82ea76984d400a4d71fd827f54d05a411519870e6b12dfd6f715c00000120246e927334aa19300bd2e329e9b89f2a6cc317c14e26eef1974a70532df4e8d30002202acb2638e5245e2a6e8fbf6ed3fce77d51dbd64d12d04663f3634f43edc62b710120f6487a13fb0700732b6933f0ddbacb01ee5d282dd730fc08160fee2825be9f450120a7226628c1173a6b8fef343b51fddcd140f283b8736838759183b179fad5e396 +0x000010000200135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac1458900000120db9fc09b2bdea181fd4f9775116a2ec3c27c93a7ce0ce8f5835fda73bfd09b49000220e6fc3cdc50433760d43adfe52426648597c092d8973a30529ad0058d6a03b55d01207392fe9c9e518a0bc1b0f032e003dbf73096fb95a8bfdbfe05e05f67e08940380120c00b8503cb3aa5473f1a4b4d68cdad468c52e628fdf8dc175caae2d8bec75297 ``` ### 32 Outputs An Output ID Proof for a transaction with 32 outputs. -Transaction (32 Outputs) (binary-encoded): +Signed Transaction (32 Outputs) (hex-encoded binary serialization): ``` -0x490443ee9f5955c42a69480400000100002aa135e8d314aed6c1576616e2d38b73589a221f914e2036938ff3294a1a04760000000001000000000000000020000040420f000000000000000000000000000100004e6614257d0f11460315281e11274b272d465c0c06087778294b6e3e505f3200000040420f00000000000000000000000000010000424f1f695e16503f76476f7d541d051c016b130d502e4f3b502249152c5b7c54000040420f000000000000000000000000000100002d1a401d1470606f21733a184f3f4a713010651a2211033a690b3c6f21015c52000040420f00000000000000000000000000010000150c0d09214a7e6f4d11645f6d24406f6c3950090f782b37440d2719134f070d000040420f00000000000000000000000000010000652e08620a3b4c436d4a120b5d2f20723374403754232166792e4a29000e0f13000040420f00000000000000000000000000010000587b322e037420120c51576b2e2e4d205c3d46080c1d2971055c1a2069794838000040420f000000000000000000000000000100001f6311134d4736093340793d363459186943670103561f2d20436a090e3e451d000040420f00000000000000000000000000010000680113416907254311613a111a2b5b735f6e436c11220a372f0e5d28507c454a000040420f0000000000000000000000000001000034492d4f734b011f4878120053534c5f424066517b652f3609171a1e0c190709000040420f000000000000000000000000000100003b02352954251034220943153c631f6473595f6e5a2c157351606850621a1a5b000040420f000000000000000000000000000100005171045931294f265b675b1c3d557e0a5f56072e4a630b597b32742f65572e1e000040420f000000000000000000000000000100003c713b3d2d5e1f4b0348711b714c2b5e657e1968061c4e372e3d4b6921062331000040420f000000000000000000000000000100002c6f2a4741107c412f39593d4742457171630541721f6c4b7a3a04190e0a721c000040420f000000000000000000000000000100000f38217d311079404a0a7a762b0f125972795f22561577776a31415b531e173c000040420f000000000000000000000000000100007d1d1f5a7a2d492123187721446527791f5d172454495c0146683b6417567448000040420f0000000000000000000000000001000026586b714d20651e7d05032d7c2f431e2311174910237d725065502062195934000040420f0000000000000000000000000001000065287565632a66420063022f253f4564447624704f503b102a37610028246a7e000040420f00000000000000000000000000010000024a04246574032502172a36640d1935462714311f78120127581d47714f6d49000040420f00000000000000000000000000010000383d6958267d415462515d70590d160e09262c103e6a5b27334a2c0b3b644f79000040420f0000000000000000000000000001000065552c286513794c4769340f6d492f627337411b2a3f0f6558256d0d3c593b0c000040420f000000000000000000000000000100000f7573063d626b1163490a4362262a3a3044366d2d7d6a5e470a03675c121c26000040420f000000000000000000000000000100006e05524732705e325f651b3c0f1f045e1a6f23610e1b2066795e5a05116d3f24000040420f0000000000000000000000000001000034471553696a0031045b666d7a0b2c761260023a376a101e057556147d551c70000040420f00000000000000000000000000010000615e0716310e0326304a45552b4e6a1d7c4403704b240f1430643c5b513a4961000040420f00000000000000000000000000010000157c721907161a173e780d4e09285f4467422b790715335964765d3c4d205a0f000040420f000000000000000000000000000100003109614f3a1c511b442a2b1b5032393b3811216757577960745b4b623c447d2e000040420f00000000000000000000000000010000536133335c0867403f7a2a300e453d57205d595a66775e4634575e4803526709000040420f000000000000000000000000000100007424116251541033114a6277472b5017013b0f02225d363c493915647d107602000040420f00000000000000000000000000010000477862677e1a3b4a352f657355421a433a172a045c22306c406a594e65653d56000040420f00000000000000000000000000010000555d6964565e082a7248670537242266503c5e2f37735e3a2f14413163703978000040420f000000000000000000000000000100000c767a111356470e0f553f1b3e1a45431b6d745036505d23121f4d7e03594d27000040420f000000000000000000000000000100003c51753a1e207b4c4b6f4e6419161a393807104316584d0b1d7955766825521b00 +0x01fb5c44ef0d3ac873000010000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000021000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d000040420f00000000000000000000000000010000c3d789866209202d21895e9a5a69ceb4b1fba08f53237c697e32cf6780a89a71000040420f000000000000000000000000000100008b1697f39c48f841e78e9e3fb2eae08d6af3463fc26fdfbf8ae23ad86ef5353d000040420f00000000000000000000000000010000145a6400ae4ce60e2192b6e538bb790a774db03070afaff1f0c83beedd15fa65000040420f00000000000000000000000000010000f25fbe26abe7ddc7b1ba9fc94a8f6c5a1ac025b0f8027fb7c5ec6047b7715271000040420f00000000000000000000000000010000ea2e3aa40282125d37373a7a51b94e806156f3d4d5a3e4a7679e9dac36ae5daa000040420f000000000000000000000000000100003475a41594b179a940fe311fddb2b8f0f68ff86fc88d50b085ed0af6dc916879000040420f00000000000000000000000000010000e7f9581f4105471c428dcba08f274986fbc084cbebbe77e0121f6486d7543dab000040420f00000000000000000000000000010000b2313d9e1e500c0105496d43459c33692af0d72c5412a6aa896c2d968aa09d0b000040420f0000000000000000000000000001000056db5b539ddeda7e1c81602669e26506d1a5b3119713d30090ba674cd837e567000040420f000000000000000000000000000100000f29bab850895afefbc2fcc2db1d60f1d86e275ef406b8d98c4e7ed6112c74e5000040420f00000000000000000000000000010000bda720e6d8bf203933dbf1dc4bd00e87e39e93fe514f6e64c9288ae8ce0ca84a000040420f000000000000000000000000000100009d3fd662ba96b4df02d578526090c1f9a580e1d93376380b302bc153b08c9bca000040420f00000000000000000000000000010000613fc72ee7c78035e0cc469a1f49629a98e5ad9c87ce441b9605baa249c42744000040420f000000000000000000000000000100004400a5ed5664a913bb87cb0af6b81bbe01b6a34824f92822cacf6d28f24c235e000040420f000000000000000000000000000100000b4cca1c8d620d650c8bf0f6b3575278732bb79b0156080557a72ffca84e4049000040420f00000000000000000000000000010000f8d2c1579c46b28987a0ed69f1d751b166c4dfd8c1701066aa9d3ad16761785a000040420f00000000000000000000000000010000cd682775e623f1b3f4a99f4d10509aae49a9e4fb2bb959c604d95b7f053fbd38000040420f000000000000000000000000000100006de2cd6d6b75cdf3ecdddcab903e6df6ca288d8ae3ea66c4281b7f86cf063e36000040420f000000000000000000000000000100002a207ba664da0a73f7722868af1396e35e94c96ceb32ddba28dfe862258ac8cb000040420f000000000000000000000000000100004e9807d3cfd5b26ad015b3a8c746d602234a8aeeb09a4f0b814ccf092170086c000040420f000000000000000000000000000100008c2150b4207ba52c8b75ebf13bcb9db776ca103c3ccd6fd25c065a4c91878751000040420f000000000000000000000000000100003293f372d83017fb62eddadf4dfe963c92b5aaa9a4b955da9e8c165318fe8e05000040420f00000000000000000000000000010000c439c102d9b01aab0c7dd33763fb9d376defb5b0d3238122835b9b0eb2def7c6000040420f00000000000000000000000000010000757a899de49f0b2a00dc90ef5bd901c3e24e4998d939cff0f0cf55e8e208e41d000040420f0000000000000000000000000001000032a40408819bfce14fc7101a42d4fc6cf02780c385fc2c3c07e38ddab307f57e000040420f000000000000000000000000000100003f010f28a30d3a5caf57b682ee1b29a89fe13847d761f751a2efef3079d20047000040420f00000000000000000000000000010000c1c3d93b0a50cae27cbfc53cf0195430cda86ce34a63471a59120a61cbc3f5ea000040420f0000000000000000000000000001000009ee1ed9707cec374bdc4977ed77fa237e9f788f6bd47ecbe65d5e3788ccc9b1000040420f00000000000000000000000000010000df40b4f6fe643a1ab1a4ecc7f2f1d2feb24aea9b8cfedb09d21d4dd1870f784e000040420f00000000000000000000000000010000f77ec745cf5fe977cd02905d866cb2ecce4631d02910f96ac49945db418966cb000040420f000000000000000000000000000100009d1879ca302277d00c6a00aa70a23caae1aadbc1232cd3026875ba9291cce11600010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257acfba02659d987606ac64863e1102c455d6d485a3032d92d98c00bf8c920f43a0209c8fce9a6e331b52b7fdbda420141a73830982ba2167fea5345aa90393f8a08 ``` Output ID Proof (Output Index 0) (json-encoded): ```json { - "slot": 71854378, + "slot": 1048576, "outputIndex": 0, - "transactionCommitment": "0x904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e4", + "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", "outputCommitmentProof": { "type": 0, "l": { @@ -1507,96 +1514,110 @@ Output ID Proof (Output Index 0) (json-encoded): "l": { "type": 0, "l": { - "type": 2, - "hash": "0x94406e58a06ee2dd1a99472caed7bed6d82b1ea3d692195bcfec18cabdb16674" + "type": 0, + "l": { + "type": 2, + "hash": "0xb750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b" + }, + "r": { + "type": 1, + "hash": "0x6b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab72" + } }, "r": { "type": 1, - "hash": "0x52d24e8cbbe5a92dc800e48a0135a5bb0f2d151c3345fbe122f63ad58f379cd8" + "hash": "0xb125aad50138d88d8c43459345cbab04523c7e8fc4ea00a2c63bf9c792734775" } }, "r": { "type": 1, - "hash": "0x08de9a5e8b92bafd57fef8bc3d2f4a3dbcf7eaed3efc59bd966891f6df836d1b" + "hash": "0x91ce0e100a30fed59e0ef34bc4fae37aa46811d48cc18f95b2cc02371fb7e7b8" } }, "r": { "type": 1, - "hash": "0xbc4ef7e28be5b72785eb1d00bb98cf190aad0a91d3bc1176b091c3bc5d5d5d53" + "hash": "0x8211ee89080681552986e3321b231ff1cfdc114a952c1e3d3fc934283603df1f" } }, "r": { "type": 1, - "hash": "0x0571ab27a77432a693bc717c325402b79121a7bd718fb8adefa7f4e9bbec09a8" + "hash": "0x84fc02511dfc0326c9c82aa7081430cbfac7dc9d4e9144527374f66399e5c790" } }, "r": { "type": 1, - "hash": "0xa300087aefa3f2b42818c9edb5135ae5708dc2a3617daf9e654f09a96e4859d9" + "hash": "0x4ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39" } } } ``` -Output ID Proof (Output Index 0) (binary-encoded): +Output ID Proof (Output Index 0) (hex-encoded binary serialization): ``` -0x2a6948040000904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e40000000000022094406e58a06ee2dd1a99472caed7bed6d82b1ea3d692195bcfec18cabdb16674012052d24e8cbbe5a92dc800e48a0135a5bb0f2d151c3345fbe122f63ad58f379cd8012008de9a5e8b92bafd57fef8bc3d2f4a3dbcf7eaed3efc59bd966891f6df836d1b0120bc4ef7e28be5b72785eb1d00bb98cf190aad0a91d3bc1176b091c3bc5d5d5d5301200571ab27a77432a693bc717c325402b79121a7bd718fb8adefa7f4e9bbec09a80120a300087aefa3f2b42818c9edb5135ae5708dc2a3617daf9e654f09a96e4859d9 +0x000010000000135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac145890000000000000220b750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b01206b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab720120b125aad50138d88d8c43459345cbab04523c7e8fc4ea00a2c63bf9c792734775012091ce0e100a30fed59e0ef34bc4fae37aa46811d48cc18f95b2cc02371fb7e7b801208211ee89080681552986e3321b231ff1cfdc114a952c1e3d3fc934283603df1f012084fc02511dfc0326c9c82aa7081430cbfac7dc9d4e9144527374f66399e5c79001204ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39 ``` Output ID Proof (Output Index 28) (json-encoded): ```json { - "slot": 71854378, + "slot": 1048576, "outputIndex": 28, - "transactionCommitment": "0x904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e4", + "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", "outputCommitmentProof": { "type": 0, "l": { - "type": 1, - "hash": "0x24c6ff8772cb21ecc443f6f12a4db2e624c4e5710793575c4c74242c38f641cc" - }, - "r": { "type": 0, "l": { "type": 1, - "hash": "0xa058d1f3196d12febcd561cc60fb31ec4afaa935cb9781028e08a6b0df1bb5a2" + "hash": "0x7f564883c631d43a902ef144a674e6ac11ed7db1c9e88ecf7a664c19885de497" }, "r": { "type": 0, "l": { "type": 1, - "hash": "0xd3b68289625ab76aba41ce4254731a94cd047efbe449973bbde5fa74c11d9f8e" + "hash": "0xaa70d7aab4560bcafda057bcffca504f4d6ca89bc5652d4cf60a33e85a39bc5f" }, "r": { "type": 0, "l": { + "type": 1, + "hash": "0xc6e9e11d1ae2b9479e778fed77d273ced27cfee60b8d9c2cb0fce4efe5b1d179" + }, + "r": { "type": 0, "l": { - "type": 2, - "hash": "0xcf02568a886a5c7c91c730d710d1b65b36a7656129817f408e1780905716ece9" + "type": 0, + "l": { + "type": 2, + "hash": "0x56cf9617298303d80e0b0bc7a38e9807db5e6b5c1dbe32338ec54efa830f1d93" + }, + "r": { + "type": 1, + "hash": "0x45d50fb24eecc01fed1254b75e0ddc97c3d8825f02e68b75da3f16f14573cc53" + } }, "r": { "type": 1, - "hash": "0x0045ac64f5fdea88388b16737c273d3326437d67fd802e32b6364a2bf32b9325" + "hash": "0x2e88c7335dcc28ef7cf618d77336b62f49c1d0c05d956e516eb9a37f556373e2" } - }, - "r": { - "type": 1, - "hash": "0x93ae83d3031afb93c7e1eb0ef050d4b66c67fcd4f3cea280ffa5ea5deceb9223" } } } + }, + "r": { + "type": 1, + "hash": "0x4ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39" } } } ``` -Output ID Proof (Output Index 28) (binary-encoded): +Output ID Proof (Output Index 28) (hex-encoded binary serialization): ``` -0x2a6948041c00904d514becc987a2950297476ee07fec838d780f60e6a67cc655cddc4c5333e400012024c6ff8772cb21ecc443f6f12a4db2e624c4e5710793575c4c74242c38f641cc000120a058d1f3196d12febcd561cc60fb31ec4afaa935cb9781028e08a6b0df1bb5a2000120d3b68289625ab76aba41ce4254731a94cd047efbe449973bbde5fa74c11d9f8e00000220cf02568a886a5c7c91c730d710d1b65b36a7656129817f408e1780905716ece901200045ac64f5fdea88388b16737c273d3326437d67fd802e32b6364a2bf32b9325012093ae83d3031afb93c7e1eb0ef050d4b66c67fcd4f3cea280ffa5ea5deceb9223 +0x000010001c00135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589000001207f564883c631d43a902ef144a674e6ac11ed7db1c9e88ecf7a664c19885de497000120aa70d7aab4560bcafda057bcffca504f4d6ca89bc5652d4cf60a33e85a39bc5f000120c6e9e11d1ae2b9479e778fed77d273ced27cfee60b8d9c2cb0fce4efe5b1d1790000022056cf9617298303d80e0b0bc7a38e9807db5e6b5c1dbe32338ec54efa830f1d93012045d50fb24eecc01fed1254b75e0ddc97c3d8825f02e68b75da3f16f14573cc5301202e88c7335dcc28ef7cf618d77336b62f49c1d0c05d956e516eb9a37f556373e201204ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39 ``` # Copyright From dff4621c49f3f9ed6aa3586e783caf2d3dcecae8 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 21 Dec 2023 15:10:37 +0100 Subject: [PATCH 105/122] Fix test vector syntactic correctness --- tips/TIP-0045/tip-0045.md | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index b756bc570..fe232da00 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1281,11 +1281,11 @@ Transaction (json-encoded): "type": 1, "transaction": { "networkId": "8342982141227064571", - "creationSlot": 1048576, + "creationSlot": 11, "contextInputs": [ { "type": 0, - "commitmentId": "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a" + "commitmentId": "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d707601000000" }, { "type": 1, @@ -1309,13 +1309,13 @@ Transaction (json-encoded): } ], "allotments": [ - { - "accountId": "0x7e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507", - "mana": "2285" - }, { "accountId": "0x476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b6915", "mana": "2189" + }, + { + "accountId": "0x7e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507", + "mana": "2285" } ], "capabilities": "0x01", @@ -1362,6 +1362,27 @@ Transaction (json-encoded): "entries": { "hello": "0x776f726c64" } + }, + { + "type": 6, + "expirySlot": 4294967295, + "blockIssuerKeys": [ + { + "type": 0, + "publicKey": "0x9e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b5" + }, + { + "type": 0, + "publicKey": "0xa504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21" + } + ] + }, + { + "type": 7, + "stakedAmount": "10000", + "fixedCost": "400", + "startEpoch": 0, + "endEpoch": 4294967295 } ] } @@ -1373,7 +1394,7 @@ Transaction (json-encoded): "signature": { "type": 0, "publicKey": "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac", - "signature": "0x469a3426bf88a8ed1a0346892a519e5b56cd8f686b1ce9b904898a62b25a8f96124f4ad3db9b6241fee5be98d067d083e91b2c4ce96e91fb8bc0871443764f00" + "signature": "0x6d22cc707780425e3478518e9d0b66c1e9a08204d7e553cf2417a7089f5860c3ccbe2dc188a6c8a1c7bcdf8944da0ed1849ec162bbc45cc56879e32658a1360c" } }, { @@ -1387,13 +1408,13 @@ Transaction (json-encoded): Transaction (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac873000010000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a0117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa826100000000000002007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0103010568656c6c6f0500776f726c6400020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac469a3426bf88a8ed1a0346892a519e5b56cd8f686b1ce9b904898a62b25a8f96124f4ad3db9b6241fee5be98d067d083e91b2c4ce96e91fb8bc0871443764f00010000 +0x01fb5c44ef0d3ac8730b0000000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076010000000117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa82610000000000000200476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d080000000000007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0303010568656c6c6f0500776f726c6406ffffffff02009e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b500a504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21071027000000000000900100000000000000000000ffffffff00020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac6d22cc707780425e3478518e9d0b66c1e9a08204d7e553cf2417a7089f5860c3ccbe2dc188a6c8a1c7bcdf8944da0ed1849ec162bbc45cc56879e32658a1360c010000 ``` Transaction ID: ``` -0x7845f92882df0f16860f1adc076a2c3b6b33416a0eee2fd225f2ac74f6def99b00001000 +0x41f9a4798788e17c468b0424d295e89c0646ca92ce6fc87557d113f00bc3486d0b000000 ``` ## Output ID Proof From fa37db046f06656e52d03250f9eab28ba69da35b Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 10 Jan 2024 15:29:35 +0100 Subject: [PATCH 106/122] Fix transaction id test vector --- tips/TIP-0045/tip-0045.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index fe232da00..8659904cc 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1394,7 +1394,7 @@ Transaction (json-encoded): "signature": { "type": 0, "publicKey": "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac", - "signature": "0x6d22cc707780425e3478518e9d0b66c1e9a08204d7e553cf2417a7089f5860c3ccbe2dc188a6c8a1c7bcdf8944da0ed1849ec162bbc45cc56879e32658a1360c" + "signature": "0x9ddb1a12cee815e5ff18477e8e59849fd3b8f9c96f35f3af00b1b77f71fc604ffd6c18920831a97825b30497806814c9facd02eee72383e59988a1782deacf07" } }, { @@ -1408,13 +1408,13 @@ Transaction (json-encoded): Transaction (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac8730b0000000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076010000000117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa82610000000000000200476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d080000000000007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0303010568656c6c6f0500776f726c6406ffffffff02009e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b500a504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21071027000000000000900100000000000000000000ffffffff00020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac6d22cc707780425e3478518e9d0b66c1e9a08204d7e553cf2417a7089f5860c3ccbe2dc188a6c8a1c7bcdf8944da0ed1849ec162bbc45cc56879e32658a1360c010000 +0x01fb5c44ef0d3ac8730b0000000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076010000000117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa82610000000000000200476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d080000000000007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0303010568656c6c6f0500776f726c6406ffffffff02009e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b500a504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21071027000000000000900100000000000000000000ffffffff00020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac9ddb1a12cee815e5ff18477e8e59849fd3b8f9c96f35f3af00b1b77f71fc604ffd6c18920831a97825b30497806814c9facd02eee72383e59988a1782deacf07010000 ``` Transaction ID: ``` -0x41f9a4798788e17c468b0424d295e89c0646ca92ce6fc87557d113f00bc3486d0b000000 +0x6a4e5452865ff6491f9df3b39cff69e7e5b365618e2789a21f71700ba1b087260b000000 ``` ## Output ID Proof From 8d167f12c3549e724d35a848128010b507db6b97 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 16 Jan 2024 13:08:34 +0100 Subject: [PATCH 107/122] Add Mana Transaction Test Vector --- tips/TIP-0045/tip-0045.md | 96 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 8659904cc..8910c0fc7 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1641,6 +1641,102 @@ Output ID Proof (Output Index 28) (hex-encoded binary serialization): 0x000010001c00135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589000001207f564883c631d43a902ef144a674e6ac11ed7db1c9e88ecf7a664c19885de497000120aa70d7aab4560bcafda057bcffca504f4d6ca89bc5652d4cf60a33e85a39bc5f000120c6e9e11d1ae2b9479e778fed77d273ced27cfee60b8d9c2cb0fce4efe5b1d1790000022056cf9617298303d80e0b0bc7a38e9807db5e6b5c1dbe32338ec54efa830f1d93012045d50fb24eecc01fed1254b75e0ddc97c3d8825f02e68b75da3f16f14573cc5301202e88c7335dcc28ef7cf618d77336b62f49c1d0c05d956e516eb9a37f556373e201204ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39 ``` +## Potential and Stored Mana + +The following test vector shows a transaction where one output is being consumed and one is created. The potential mana +generated by the consumed output is stored in the created output while the decayed stored mana of the consumed output is +allotted to an account. + +Transaction (json-encoded): + +```json +{ + "type": 1, + "transaction": { + "networkId": "8342982141227064571", + "creationSlot": 5000000, + "contextInputs": [ + { + "type": 0, + "commitmentId": "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076364b4c00" + } + ], + "inputs": [ + { + "type": 0, + "transactionId": "0xf09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195005000000", + "transactionOutputIndex": 0 + } + ], + "allotments": [ + { + "accountId": "0x476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b6915", + "mana": "2272" + } + ], + "outputs": [ + { + "type": 0, + "amount": "100000", + "mana": "2502459", + "unlockConditions": [ + { + "type": 0, + "address": { + "type": 0, + "pubKeyHash": "0xed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a" + } + } + ] + } + ] + }, + "unlocks": [ + { + "type": 0, + "signature": { + "type": 0, + "publicKey": "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac", + "signature": "0x7a3da62e0c314918170a2dc476588dd6e27032b7817a08be7482643b434604a5ecec55616bd77730e86bfd223bd3a2d09b0d5366058d5470d192a9adef77a007" + } + } + ] +} +``` + +Transaction (hex-encoded binary serialization): + +``` +0x01fb5c44ef0d3ac873404b4c000100003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076364b4c00010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719500500000000000100476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b6915e0080000000000000000000000010000a0860100000000003b2f260000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a00010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac7a3da62e0c314918170a2dc476588dd6e27032b7817a08be7482643b434604a5ecec55616bd77730e86bfd223bd3a2d09b0d5366058d5470d192a9adef77a007 +``` + +Input with Output ID: `0xf09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed71950050000000000` (= creation +slot 5) (json-encoded): + +```json +{ + "type": 0, + "amount": "100000", + "mana": "4000", + "unlockConditions": [ + { + "type": 0, + "address": { + "type": 0, + "pubKeyHash": "0xed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a" + } + } + ] +} +``` + +Input with Output ID: `0xf09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed71950050000000000` (= creation +slot 5) (hex-encoded binary serialization): + +``` +0x00a086010000000000a00f000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a00 +``` + # Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 0cff7d363bdef54ec66d19bae02279cc1468b59c Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 19 Jan 2024 14:33:51 +0100 Subject: [PATCH 108/122] Fix metadata feature in account in test vector --- tips/TIP-0045/tip-0045.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 8910c0fc7..394994600 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1358,7 +1358,7 @@ Transaction (json-encoded): ], "features": [ { - "type": 3, + "type": 2, "entries": { "hello": "0x776f726c64" } @@ -1394,7 +1394,7 @@ Transaction (json-encoded): "signature": { "type": 0, "publicKey": "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac", - "signature": "0x9ddb1a12cee815e5ff18477e8e59849fd3b8f9c96f35f3af00b1b77f71fc604ffd6c18920831a97825b30497806814c9facd02eee72383e59988a1782deacf07" + "signature": "0x8e5601da2696080082cdfe9b1d0f8ee6eaa68b1777f4b830c649ec805ff2e33173776bb5f7da35866fbb3da243fdb2e27992dbfe59227635ab0304160ec09f02" } }, { @@ -1408,13 +1408,13 @@ Transaction (json-encoded): Transaction (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac8730b0000000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076010000000117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa82610000000000000200476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d080000000000007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0303010568656c6c6f0500776f726c6406ffffffff02009e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b500a504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21071027000000000000900100000000000000000000ffffffff00020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac9ddb1a12cee815e5ff18477e8e59849fd3b8f9c96f35f3af00b1b77f71fc604ffd6c18920831a97825b30497806814c9facd02eee72383e59988a1782deacf07010000 +0x01fb5c44ef0d3ac8730b0000000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076010000000117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa82610000000000000200476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d080000000000007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0302010568656c6c6f0500776f726c6406ffffffff02009e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b500a504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21071027000000000000900100000000000000000000ffffffff00020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac8e5601da2696080082cdfe9b1d0f8ee6eaa68b1777f4b830c649ec805ff2e33173776bb5f7da35866fbb3da243fdb2e27992dbfe59227635ab0304160ec09f02010000 ``` Transaction ID: ``` -0x6a4e5452865ff6491f9df3b39cff69e7e5b365618e2789a21f71700ba1b087260b000000 +0x79803e7fb8f972d22e9e42c2f8a38d413bc0b8bb2cf3848a0db5b85162ceafe60b000000 ``` ## Output ID Proof From 7cd4554c5f02563a0245b051f0d777c007d5bb2b Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 22 Jan 2024 12:17:16 +0100 Subject: [PATCH 109/122] Explicitly mention Multi Unlocks for work score --- tips/TIP-0045/tip-0045.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 394994600..9aaade836 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1150,8 +1150,9 @@ Let the work score of a transaction be defined as follows. - Return `Work Score Parameters::Output + Native Token Score + Token Scheme Score + Staking Score + Block Issuer Score`. - Let `Allotment Score` be `Work Score Parameters::Allotment * Allotments Count`. -- Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ within `Unlocks`. - - Signature work scores are defined in TIP-46. +- Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ (directly or within + _Multi Unlocks_) within `Unlocks`. + - Signature work scores are defined in [TIP-46 (Work Score)](../TIP-0046/tip-0046.md#work-score-1). - Return `Size Score + Input Score + Context Input Score + Outputs Score + Allotment Score + Signature Score`. ## Validation From 8f85f1678d7db958bdd362a0ed9ff333fe7af81f Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 22 Jan 2024 15:13:58 +0100 Subject: [PATCH 110/122] Require lexical order for `Context Inputs` --- tips/TIP-0045/tip-0045.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 9aaade836..590d8b45f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1185,9 +1185,12 @@ The following criteria defines whether a payload passes the syntactical validati - Context Inputs: - `Context Inputs Count` must be `0 ≤ x ≤ Max Inputs Count`. - `Context Input Type` must denote an allowed input type, listed in section [Context Inputs](#context-inputs). + - The Context Inputs must be lexically ordered and unique, both based on the following comparison criteria: + - `Context Input Type` as the first criteria for all Context Inputs. + - `Index` as the second criteria for _Reward Inputs_. + - `Account ID` as the second criteria for _Block Issuance Credit Inputs_. - There must be zero or one _Commitment Input_. - - All _Reward Inputs_ must reference a different `Index` and it must hold that: `Index < Inputs Count`. - - All _Block Issuance Credit Inputs_ must reference a different `Account ID`. + - For each `Index` in the _Reward Inputs_ it must hold that: `Index < Inputs Count`. - Outputs: - `Outputs Count` must be `0 < x ≤ Max Outputs Count`. - For each output the following must be true: @@ -1268,6 +1271,12 @@ used deposit address. Ed25519 addresses are not meant to be used like email addr 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. +- The sorting criteria for _Commitment Inputs_ is only based on their _Context Input Type_ and does not take into + account the _Commitment ID_, which allows for an optimization when determining whether there are zero or one + _Commitment Inputs_. An algorithm checking lexical order and uniqueness will detect the violation of the desired "at + most one" semantic as soon as two or more _Commitment Inputs_ are present, since those would be considered duplicates. +- Requiring lexical order in various places (such as for _Context Inputs_) is mostly an optimization in order to allow + for efficient duplicate detection. # Test Vectors From 261deb5b46a73f953a25afc9528b65028d772002 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 25 Jan 2024 09:30:33 +0100 Subject: [PATCH 111/122] Add explicit Commitment Input syntax requirement --- tips/TIP-0045/tip-0045.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 590d8b45f..0e3db764f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1190,6 +1190,7 @@ The following criteria defines whether a payload passes the syntactical validati - `Index` as the second criteria for _Reward Inputs_. - `Account ID` as the second criteria for _Block Issuance Credit Inputs_. - There must be zero or one _Commitment Input_. + - A _Commitment Input_ must be present if one or more _Block Issuance Credit Inputs_ or _Reward Inputs_ are present. - For each `Index` in the _Reward Inputs_ it must hold that: `Index < Inputs Count`. - Outputs: - `Outputs Count` must be `0 < x ≤ Max Outputs Count`. From d9bb471ea89a53806030d2e5f21de4d1ad7428ea Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 25 Jan 2024 11:59:18 +0100 Subject: [PATCH 112/122] Update test vector with changed block issuer key --- tips/TIP-0045/tip-0045.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 0e3db764f..135a3008c 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1380,11 +1380,11 @@ Transaction (json-encoded): "blockIssuerKeys": [ { "type": 0, - "publicKey": "0x9e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b5" + "pubKeyHash": "0x295409de79016133647d4078cb01618a4ba018eb74ff613138d8ff8dc05de73c" }, { "type": 0, - "publicKey": "0xa504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21" + "pubKeyHash": "0x868f4c6ef7b5b1d55838cbfb8ae4f3a9776c53cdd3e3d33000094d72acab5a2f" } ] }, @@ -1405,7 +1405,7 @@ Transaction (json-encoded): "signature": { "type": 0, "publicKey": "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac", - "signature": "0x8e5601da2696080082cdfe9b1d0f8ee6eaa68b1777f4b830c649ec805ff2e33173776bb5f7da35866fbb3da243fdb2e27992dbfe59227635ab0304160ec09f02" + "signature": "0x5bb409d59e01d2ea9f1a1fb67feb681d0d3ecb05787cadad2f89fdf13ef7ff03ad5cebf28df5dddd8510992596d98b133f86e14f76824e6ccc369a8f5df44806" } }, { @@ -1419,13 +1419,13 @@ Transaction (json-encoded): Transaction (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac8730b0000000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076010000000117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa82610000000000000200476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d080000000000007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0302010568656c6c6f0500776f726c6406ffffffff02009e05a32eafedefd40298e24ad4f8c334580187f7e9afbd9da13b5ba4007dd1b500a504844f7a0df2c5101d31696593b309040f8660d41035aba508f24c00668b21071027000000000000900100000000000000000000ffffffff00020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac8e5601da2696080082cdfe9b1d0f8ee6eaa68b1777f4b830c649ec805ff2e33173776bb5f7da35866fbb3da243fdb2e27992dbfe59227635ab0304160ec09f02010000 +0x01fb5c44ef0d3ac8730b0000000300003a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d7076010000000117432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a020000020000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000000000d2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa82610000000000000200476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b69158d080000000000007e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507ed08000000000000010100000000020000a0860100000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0105086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00f46312374981be1400000000000000000000000000000000000000000000000001a0860100000000008813000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a0302010568656c6c6f0500776f726c6406ffffffff0200295409de79016133647d4078cb01618a4ba018eb74ff613138d8ff8dc05de73c00868f4c6ef7b5b1d55838cbfb8ae4f3a9776c53cdd3e3d33000094d72acab5a2f071027000000000000900100000000000000000000ffffffff00020000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac5bb409d59e01d2ea9f1a1fb67feb681d0d3ecb05787cadad2f89fdf13ef7ff03ad5cebf28df5dddd8510992596d98b133f86e14f76824e6ccc369a8f5df44806010000 ``` Transaction ID: ``` -0x79803e7fb8f972d22e9e42c2f8a38d413bc0b8bb2cf3848a0db5b85162ceafe60b000000 +0xb16af73e9f3aa82e90e11908886d61661f0a34b5f6cb939daac8086e7b2093120b000000 ``` ## Output ID Proof From eacf76eac4abb5fbd22aca5d9f17d14b62b60aa4 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 25 Jan 2024 12:02:41 +0100 Subject: [PATCH 113/122] Update Output ID Proof Test Vector --- tips/TIP-0045/tip-0045.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 135a3008c..da7444592 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1437,16 +1437,16 @@ An Output ID Proof for a transaction with a single output. Signed Transaction (1 Output) (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac873000010000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000002000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d00010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac45fda13b781c8957f22a278061cba17cc4ed4f31b5c592a7cd455b06143a4a1e9102def005ea39f859aff77cb3879334a1a694b1678b722afae8d4c37d1a9400 +0x01fb5c44ef0d3ac8730b0000000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000002000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d00010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257acea95793c5a8aef7eeb0daa2a1632f0abf6eeb4c7ca19808f20f6101a6d22ea8f8b4d85dbbbd21d0ac521991a57536fbd37bccd85ab29254a3b5d2e534fda5506 ``` Output ID Proof (Output Index 0) (json-encoded): ```json { - "slot": 1048576, + "slot": 11, "outputIndex": 0, - "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", + "transactionCommitment": "0xe5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f470", "outputCommitmentProof": { "type": 0, "l": { @@ -1464,7 +1464,7 @@ Output ID Proof (Output Index 0) (json-encoded): Output ID Proof (Output Index 0) (hex-encoded binary serialization): ``` -0x000010000000135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589000220b750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b01206b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab72 +0x0b0000000000e5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f470000220b750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b01206b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab72 ``` ### Five Outputs @@ -1474,16 +1474,16 @@ An Output ID Proof for a transaction with five outputs (not a power of two numbe Signed Transaction (5 Outputs) (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac873000010000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000006000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d000040420f00000000000000000000000000010000c3d789866209202d21895e9a5a69ceb4b1fba08f53237c697e32cf6780a89a71000040420f000000000000000000000000000100008b1697f39c48f841e78e9e3fb2eae08d6af3463fc26fdfbf8ae23ad86ef5353d000040420f00000000000000000000000000010000145a6400ae4ce60e2192b6e538bb790a774db03070afaff1f0c83beedd15fa65000040420f00000000000000000000000000010000f25fbe26abe7ddc7b1ba9fc94a8f6c5a1ac025b0f8027fb7c5ec6047b771527100010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac6d0979cc04a7effca39f80ee0dbb0208f4812d0de8b38fc2fbd9b0c707cde292f896a65250cc7a64284596f386142634958a3ad7def2b70effcc94122feb0107 +0x01fb5c44ef0d3ac8730b0000000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000006000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d000040420f00000000000000000000000000010000c3d789866209202d21895e9a5a69ceb4b1fba08f53237c697e32cf6780a89a71000040420f000000000000000000000000000100008b1697f39c48f841e78e9e3fb2eae08d6af3463fc26fdfbf8ae23ad86ef5353d000040420f00000000000000000000000000010000145a6400ae4ce60e2192b6e538bb790a774db03070afaff1f0c83beedd15fa65000040420f00000000000000000000000000010000f25fbe26abe7ddc7b1ba9fc94a8f6c5a1ac025b0f8027fb7c5ec6047b771527100010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac75b951fbf7c55b41b6323cd9b00fe5c444f3145d7bc75da7ae366756f01ee8a18a8e15c6321eb0972084d05422b6eb257869f6f5333ae17b763c0f111d65510e ``` Output ID Proof (Output Index 2) (json-encoded): ```json { - "slot": 1048576, + "slot": 11, "outputIndex": 2, - "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", + "transactionCommitment": "0xe5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f470", "outputCommitmentProof": { "type": 0, "l": { @@ -1515,7 +1515,7 @@ Output ID Proof (Output Index 2) (json-encoded): Output ID Proof (Output Index 2) (hex-encoded binary serialization): ``` -0x000010000200135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac1458900000120db9fc09b2bdea181fd4f9775116a2ec3c27c93a7ce0ce8f5835fda73bfd09b49000220e6fc3cdc50433760d43adfe52426648597c092d8973a30529ad0058d6a03b55d01207392fe9c9e518a0bc1b0f032e003dbf73096fb95a8bfdbfe05e05f67e08940380120c00b8503cb3aa5473f1a4b4d68cdad468c52e628fdf8dc175caae2d8bec75297 +0x0b0000000200e5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f47000000120db9fc09b2bdea181fd4f9775116a2ec3c27c93a7ce0ce8f5835fda73bfd09b49000220e6fc3cdc50433760d43adfe52426648597c092d8973a30529ad0058d6a03b55d01207392fe9c9e518a0bc1b0f032e003dbf73096fb95a8bfdbfe05e05f67e08940380120c00b8503cb3aa5473f1a4b4d68cdad468c52e628fdf8dc175caae2d8bec75297 ``` ### 32 Outputs @@ -1525,16 +1525,16 @@ An Output ID Proof for a transaction with 32 outputs. Signed Transaction (32 Outputs) (hex-encoded binary serialization): ``` -0x01fb5c44ef0d3ac873000010000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000021000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d000040420f00000000000000000000000000010000c3d789866209202d21895e9a5a69ceb4b1fba08f53237c697e32cf6780a89a71000040420f000000000000000000000000000100008b1697f39c48f841e78e9e3fb2eae08d6af3463fc26fdfbf8ae23ad86ef5353d000040420f00000000000000000000000000010000145a6400ae4ce60e2192b6e538bb790a774db03070afaff1f0c83beedd15fa65000040420f00000000000000000000000000010000f25fbe26abe7ddc7b1ba9fc94a8f6c5a1ac025b0f8027fb7c5ec6047b7715271000040420f00000000000000000000000000010000ea2e3aa40282125d37373a7a51b94e806156f3d4d5a3e4a7679e9dac36ae5daa000040420f000000000000000000000000000100003475a41594b179a940fe311fddb2b8f0f68ff86fc88d50b085ed0af6dc916879000040420f00000000000000000000000000010000e7f9581f4105471c428dcba08f274986fbc084cbebbe77e0121f6486d7543dab000040420f00000000000000000000000000010000b2313d9e1e500c0105496d43459c33692af0d72c5412a6aa896c2d968aa09d0b000040420f0000000000000000000000000001000056db5b539ddeda7e1c81602669e26506d1a5b3119713d30090ba674cd837e567000040420f000000000000000000000000000100000f29bab850895afefbc2fcc2db1d60f1d86e275ef406b8d98c4e7ed6112c74e5000040420f00000000000000000000000000010000bda720e6d8bf203933dbf1dc4bd00e87e39e93fe514f6e64c9288ae8ce0ca84a000040420f000000000000000000000000000100009d3fd662ba96b4df02d578526090c1f9a580e1d93376380b302bc153b08c9bca000040420f00000000000000000000000000010000613fc72ee7c78035e0cc469a1f49629a98e5ad9c87ce441b9605baa249c42744000040420f000000000000000000000000000100004400a5ed5664a913bb87cb0af6b81bbe01b6a34824f92822cacf6d28f24c235e000040420f000000000000000000000000000100000b4cca1c8d620d650c8bf0f6b3575278732bb79b0156080557a72ffca84e4049000040420f00000000000000000000000000010000f8d2c1579c46b28987a0ed69f1d751b166c4dfd8c1701066aa9d3ad16761785a000040420f00000000000000000000000000010000cd682775e623f1b3f4a99f4d10509aae49a9e4fb2bb959c604d95b7f053fbd38000040420f000000000000000000000000000100006de2cd6d6b75cdf3ecdddcab903e6df6ca288d8ae3ea66c4281b7f86cf063e36000040420f000000000000000000000000000100002a207ba664da0a73f7722868af1396e35e94c96ceb32ddba28dfe862258ac8cb000040420f000000000000000000000000000100004e9807d3cfd5b26ad015b3a8c746d602234a8aeeb09a4f0b814ccf092170086c000040420f000000000000000000000000000100008c2150b4207ba52c8b75ebf13bcb9db776ca103c3ccd6fd25c065a4c91878751000040420f000000000000000000000000000100003293f372d83017fb62eddadf4dfe963c92b5aaa9a4b955da9e8c165318fe8e05000040420f00000000000000000000000000010000c439c102d9b01aab0c7dd33763fb9d376defb5b0d3238122835b9b0eb2def7c6000040420f00000000000000000000000000010000757a899de49f0b2a00dc90ef5bd901c3e24e4998d939cff0f0cf55e8e208e41d000040420f0000000000000000000000000001000032a40408819bfce14fc7101a42d4fc6cf02780c385fc2c3c07e38ddab307f57e000040420f000000000000000000000000000100003f010f28a30d3a5caf57b682ee1b29a89fe13847d761f751a2efef3079d20047000040420f00000000000000000000000000010000c1c3d93b0a50cae27cbfc53cf0195430cda86ce34a63471a59120a61cbc3f5ea000040420f0000000000000000000000000001000009ee1ed9707cec374bdc4977ed77fa237e9f788f6bd47ecbe65d5e3788ccc9b1000040420f00000000000000000000000000010000df40b4f6fe643a1ab1a4ecc7f2f1d2feb24aea9b8cfedb09d21d4dd1870f784e000040420f00000000000000000000000000010000f77ec745cf5fe977cd02905d866cb2ecce4631d02910f96ac49945db418966cb000040420f000000000000000000000000000100009d1879ca302277d00c6a00aa70a23caae1aadbc1232cd3026875ba9291cce11600010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257acfba02659d987606ac64863e1102c455d6d485a3032d92d98c00bf8c920f43a0209c8fce9a6e331b52b7fdbda420141a73830982ba2167fea5345aa90393f8a08 +0x01fb5c44ef0d3ac8730b0000000000010000f09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed719520000000000000000013f0000000021000040420f0000000000000000000000000001000041b5fc0f730776b9d25dc9ffba236ce34bd9433f8a4bc8e286612e42654e0138000040420f00000000000000000000000000010000c5797137d27ceeb1d7a7f712b2dbbd2cb6b9e3fa39fe98a7751ea5913f00495d000040420f00000000000000000000000000010000c3d789866209202d21895e9a5a69ceb4b1fba08f53237c697e32cf6780a89a71000040420f000000000000000000000000000100008b1697f39c48f841e78e9e3fb2eae08d6af3463fc26fdfbf8ae23ad86ef5353d000040420f00000000000000000000000000010000145a6400ae4ce60e2192b6e538bb790a774db03070afaff1f0c83beedd15fa65000040420f00000000000000000000000000010000f25fbe26abe7ddc7b1ba9fc94a8f6c5a1ac025b0f8027fb7c5ec6047b7715271000040420f00000000000000000000000000010000ea2e3aa40282125d37373a7a51b94e806156f3d4d5a3e4a7679e9dac36ae5daa000040420f000000000000000000000000000100003475a41594b179a940fe311fddb2b8f0f68ff86fc88d50b085ed0af6dc916879000040420f00000000000000000000000000010000e7f9581f4105471c428dcba08f274986fbc084cbebbe77e0121f6486d7543dab000040420f00000000000000000000000000010000b2313d9e1e500c0105496d43459c33692af0d72c5412a6aa896c2d968aa09d0b000040420f0000000000000000000000000001000056db5b539ddeda7e1c81602669e26506d1a5b3119713d30090ba674cd837e567000040420f000000000000000000000000000100000f29bab850895afefbc2fcc2db1d60f1d86e275ef406b8d98c4e7ed6112c74e5000040420f00000000000000000000000000010000bda720e6d8bf203933dbf1dc4bd00e87e39e93fe514f6e64c9288ae8ce0ca84a000040420f000000000000000000000000000100009d3fd662ba96b4df02d578526090c1f9a580e1d93376380b302bc153b08c9bca000040420f00000000000000000000000000010000613fc72ee7c78035e0cc469a1f49629a98e5ad9c87ce441b9605baa249c42744000040420f000000000000000000000000000100004400a5ed5664a913bb87cb0af6b81bbe01b6a34824f92822cacf6d28f24c235e000040420f000000000000000000000000000100000b4cca1c8d620d650c8bf0f6b3575278732bb79b0156080557a72ffca84e4049000040420f00000000000000000000000000010000f8d2c1579c46b28987a0ed69f1d751b166c4dfd8c1701066aa9d3ad16761785a000040420f00000000000000000000000000010000cd682775e623f1b3f4a99f4d10509aae49a9e4fb2bb959c604d95b7f053fbd38000040420f000000000000000000000000000100006de2cd6d6b75cdf3ecdddcab903e6df6ca288d8ae3ea66c4281b7f86cf063e36000040420f000000000000000000000000000100002a207ba664da0a73f7722868af1396e35e94c96ceb32ddba28dfe862258ac8cb000040420f000000000000000000000000000100004e9807d3cfd5b26ad015b3a8c746d602234a8aeeb09a4f0b814ccf092170086c000040420f000000000000000000000000000100008c2150b4207ba52c8b75ebf13bcb9db776ca103c3ccd6fd25c065a4c91878751000040420f000000000000000000000000000100003293f372d83017fb62eddadf4dfe963c92b5aaa9a4b955da9e8c165318fe8e05000040420f00000000000000000000000000010000c439c102d9b01aab0c7dd33763fb9d376defb5b0d3238122835b9b0eb2def7c6000040420f00000000000000000000000000010000757a899de49f0b2a00dc90ef5bd901c3e24e4998d939cff0f0cf55e8e208e41d000040420f0000000000000000000000000001000032a40408819bfce14fc7101a42d4fc6cf02780c385fc2c3c07e38ddab307f57e000040420f000000000000000000000000000100003f010f28a30d3a5caf57b682ee1b29a89fe13847d761f751a2efef3079d20047000040420f00000000000000000000000000010000c1c3d93b0a50cae27cbfc53cf0195430cda86ce34a63471a59120a61cbc3f5ea000040420f0000000000000000000000000001000009ee1ed9707cec374bdc4977ed77fa237e9f788f6bd47ecbe65d5e3788ccc9b1000040420f00000000000000000000000000010000df40b4f6fe643a1ab1a4ecc7f2f1d2feb24aea9b8cfedb09d21d4dd1870f784e000040420f00000000000000000000000000010000f77ec745cf5fe977cd02905d866cb2ecce4631d02910f96ac49945db418966cb000040420f000000000000000000000000000100009d1879ca302277d00c6a00aa70a23caae1aadbc1232cd3026875ba9291cce11600010000002daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257accae4a03e1357e6ce71deb6f0de8ec9cf2c0f62cbcc0a54a7ea8db5c05257f2c538139739cc41aebd32ffee5f45d8b2c5004079d4d675189d3aa092cc673de704 ``` Output ID Proof (Output Index 0) (json-encoded): ```json { - "slot": 1048576, + "slot": 11, "outputIndex": 0, - "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", + "transactionCommitment": "0xe5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f470", "outputCommitmentProof": { "type": 0, "l": { @@ -1587,16 +1587,16 @@ Output ID Proof (Output Index 0) (json-encoded): Output ID Proof (Output Index 0) (hex-encoded binary serialization): ``` -0x000010000000135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac145890000000000000220b750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b01206b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab720120b125aad50138d88d8c43459345cbab04523c7e8fc4ea00a2c63bf9c792734775012091ce0e100a30fed59e0ef34bc4fae37aa46811d48cc18f95b2cc02371fb7e7b801208211ee89080681552986e3321b231ff1cfdc114a952c1e3d3fc934283603df1f012084fc02511dfc0326c9c82aa7081430cbfac7dc9d4e9144527374f66399e5c79001204ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39 +0x0b0000000000e5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f4700000000000000220b750f19d60bdd576e8eb617d101ae54146b5511b76d41294b8b9a869f12ab13b01206b9c6672c54f7dc2012fea833416a8425a3dc40a4855a63908e741568843ab720120b125aad50138d88d8c43459345cbab04523c7e8fc4ea00a2c63bf9c792734775012091ce0e100a30fed59e0ef34bc4fae37aa46811d48cc18f95b2cc02371fb7e7b801208211ee89080681552986e3321b231ff1cfdc114a952c1e3d3fc934283603df1f012084fc02511dfc0326c9c82aa7081430cbfac7dc9d4e9144527374f66399e5c79001204ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39 ``` Output ID Proof (Output Index 28) (json-encoded): ```json { - "slot": 1048576, + "slot": 11, "outputIndex": 28, - "transactionCommitment": "0x135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589", + "transactionCommitment": "0xe5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f470", "outputCommitmentProof": { "type": 0, "l": { @@ -1649,7 +1649,7 @@ Output ID Proof (Output Index 28) (json-encoded): Output ID Proof (Output Index 28) (hex-encoded binary serialization): ``` -0x000010001c00135ed822d4695d06c1844ebeb8d033e4d42b4a341144f44e6ce006dafac14589000001207f564883c631d43a902ef144a674e6ac11ed7db1c9e88ecf7a664c19885de497000120aa70d7aab4560bcafda057bcffca504f4d6ca89bc5652d4cf60a33e85a39bc5f000120c6e9e11d1ae2b9479e778fed77d273ced27cfee60b8d9c2cb0fce4efe5b1d1790000022056cf9617298303d80e0b0bc7a38e9807db5e6b5c1dbe32338ec54efa830f1d93012045d50fb24eecc01fed1254b75e0ddc97c3d8825f02e68b75da3f16f14573cc5301202e88c7335dcc28ef7cf618d77336b62f49c1d0c05d956e516eb9a37f556373e201204ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39 +0x0b0000001c00e5cd573b65e2e10f8811a5a5df5af36b385dc2d75bf13b7c731aa4660125f470000001207f564883c631d43a902ef144a674e6ac11ed7db1c9e88ecf7a664c19885de497000120aa70d7aab4560bcafda057bcffca504f4d6ca89bc5652d4cf60a33e85a39bc5f000120c6e9e11d1ae2b9479e778fed77d273ced27cfee60b8d9c2cb0fce4efe5b1d1790000022056cf9617298303d80e0b0bc7a38e9807db5e6b5c1dbe32338ec54efa830f1d93012045d50fb24eecc01fed1254b75e0ddc97c3d8825f02e68b75da3f16f14573cc5301202e88c7335dcc28ef7cf618d77336b62f49c1d0c05d956e516eb9a37f556373e201204ad094e37e0ec880bb6a24f03f3bc3ca5fdb60af734606ba639bd413eb1a1e39 ``` ## Potential and Stored Mana From 47aa10299dff302b35502de116952483a8fd3c61 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Thu, 25 Jan 2024 15:41:47 +0100 Subject: [PATCH 114/122] Update signature work score description --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index da7444592..758a30c96 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1152,7 +1152,7 @@ Let the work score of a transaction be defined as follows. - Let `Allotment Score` be `Work Score Parameters::Allotment * Allotments Count`. - Let `Signature Score` be the sum of work scores of the signatures contained in _Signature Unlocks_ (directly or within _Multi Unlocks_) within `Unlocks`. - - Signature work scores are defined in [TIP-46 (Work Score)](../TIP-0046/tip-0046.md#work-score-1). + - Signature work scores are defined with the respective schema definition. - Return `Size Score + Input Score + Context Input Score + Outputs Score + Allotment Score + Signature Score`. ## Validation From 35d5e7296e1123eb57c7638c413c72089f978b71 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 12 Feb 2024 09:32:22 +0100 Subject: [PATCH 115/122] Correct token supply parameter name --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 758a30c96..11a292fbf 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1199,7 +1199,7 @@ The following criteria defines whether a payload passes the syntactical validati - The `Amount` field must not be `0`. - The `Amount` field must be at least the minimum storage deposit according to [TIP-47](../TIP-0047/tip-0047.md). - The output itself must pass syntactic validation. - - The sum of all `Amount` fields must not exceed `Max IOTA Supply`. + - The sum of all `Amount` fields must not exceed `Token Supply`. - The sum of all `Mana` fields must not exceed 2Mana Bits Count - 1. - Allotments: - `Allotments Count` must be `0 ≤ x ≤ 128`. From 659f54f78ce1811e2c5ae459dcbc23fb95868ceb Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 1 Mar 2024 11:14:38 +0800 Subject: [PATCH 116/122] Define Sig Unlock Uniqueness through Signer Uid --- tips/TIP-0045/tip-0045.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 11a292fbf..2a9dfd465 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1067,8 +1067,8 @@ serialized as follows: ##### Signature Unlock Syntactic Validation - `Signature` must contain an _Ed25519 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. +- The _Signature Unlock_ must be unique within the subset of _Signature Unlocks_ in the `Unlocks` field of the + transaction based on the contained signature's _Signer UID_. ##### Signature Unlock Semantic Validation From 6043d14eafb0baf380a978386abd321c0fc9a8cd Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 1 Mar 2024 11:46:25 +0800 Subject: [PATCH 117/122] Remove link to unmaintained list --- tips/TIP-0045/tip-0045.md | 1 - 1 file changed, 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 2a9dfd465..1a2e36662 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1214,7 +1214,6 @@ The following criteria defines whether a payload passes the syntactical validati - Unlocks: - `Unlocks Count` must match `Inputs Count` of the _Transaction_. - 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. From e08b92867c7a6221f3be90056af6438cb1beb5b0 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 1 Mar 2024 15:00:58 +0800 Subject: [PATCH 118/122] Introduce Signer UID --- tips/TIP-0045/tip-0045.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 1a2e36662..78cb4da84 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -999,6 +999,13 @@ The transaction validation rules for each flag are defined where the respective The `Unlocks` field holds the unlocks which unlock the inputs in a _Transaction_. +#### Signer UID + +A _Signer UID_ uniquely identifies a signer and is used to check whether different addresses are backed by the same +keypair, i.e. the same signer. One common way to identify a signer is by hashing the public key of the signature. This +concept is introduced as an abstraction over all kinds of signatures, some of which may not have a public key. The +_Signer UID_ is defined by Signatures as well as Addresses that are backed by a cryptographic key pair. + #### Signature Unlock The Signature Unlock holds a signature signing the BLAKE2b-256 hash of the serialized `Transaction` field. It is @@ -1073,7 +1080,7 @@ serialized as follows: ##### Signature Unlock Semantic Validation - 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. +- The _Signer UID_ of the signature must match the _Signer UID_ of the `Address` of the UTXO. - The `Signature` field must contain a signature, signing the BLAKE2b-256 hash of the serialized `Transaction` field which is validated by the `Public Key`. From 344f66049335759da5ffbc8f9bbff62037ff9565 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 1 Mar 2024 16:03:32 +0800 Subject: [PATCH 119/122] Rephrase Reference Unlock validity --- tips/TIP-0045/tip-0045.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 78cb4da84..a77ec0233 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1079,7 +1079,6 @@ serialized as follows: ##### Signature Unlock Semantic Validation -- The `Signature Type` must match the `Address Type` of the UTXO. - The _Signer UID_ of the signature must match the _Signer UID_ of the `Address` of the UTXO. - The `Signature` field must contain a signature, signing the BLAKE2b-256 hash of the serialized `Transaction` field which is validated by the `Public Key`. @@ -1134,8 +1133,9 @@ following structure of the Unlocks part: ##### Reference Unlock Semantic Validation -- The _Signature Unlock_ at index `Reference`, to which the _Reference Unlock_ at index `i` points, must be a - [semantically valid signature unlock](#signature-unlock-semantic-validation) for the input at index `i`. +- It must hold for the `Unlock` at index `Reference`, to which the _Reference Unlock_ at index `i` points and the + corresponding address `Address` of the input at index `i`: + - The `Unlock` must be a semantically valid unlock for `Address`. ### Work Score From 26dab2cf73d6d9cdaa2a3776b4c7df6e2012abd3 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 1 Mar 2024 16:32:22 +0800 Subject: [PATCH 120/122] Improve phrasing of signature unlock validation --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index a77ec0233..b4a662e71 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1079,7 +1079,7 @@ serialized as follows: ##### Signature Unlock Semantic Validation -- The _Signer UID_ of the signature must match the _Signer UID_ of the `Address` of the UTXO. +- The _Signer UID_ of the signature must match the _Signer UID_ of the to-be-unlocked `Address`. - The `Signature` field must contain a signature, signing the BLAKE2b-256 hash of the serialized `Transaction` field which is validated by the `Public Key`. From f3ab027eb84e68841a89252ae3a1c7cbeae2237b Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 1 Mar 2024 16:37:40 +0800 Subject: [PATCH 121/122] Include Multi Unlock as valid reference target --- tips/TIP-0045/tip-0045.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index b4a662e71..6b6f05097 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1116,11 +1116,6 @@ The Reference Unlock references a previous Unlock (which must not
@@ -562,6 +562,10 @@ The following table describes the entirety of a _Signed Transaction_ in its seri Account Unlock
Points to the unlock of a consumed Account Output. Defined in TIP-42 (Account Unlock).
+
+ Anchor Unlock +
Points to the unlock of a consumed Anchor Output. Defined in TIP-54 (Anchor Unlock).
+
NFT Unlock
Points to the unlock of a consumed NFT Output. Defined in TIP-43 (NFT Unlock).
From 331df3d0e191f55a37e78df59941bf8ff5c48cf2 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 8 Nov 2023 10:49:25 +0100 Subject: [PATCH 092/122] Add no trailing zero bytes rule --- tips/TIP-0045/tip-0045.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 266bb7f4f..00b1fe65f 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -972,6 +972,9 @@ to be valid, the following conditions must hold: previous byte, the indices continue where the previous byte's indices left off. - For example: In a list of two bytes with the bit patterns `0001 0000` and `0000 0100`, bits with indices `4` and `10` are set. +- There must be no trailing zero bytes in the byte array. + - This rule ensures that two transactions whose content is identical, and in particular, that have the same + capabilities will have the same binary representation. #### Capability Flags From 96ae7d51e34200827b564bd5ecfe33beacde4cd8 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Wed, 8 Nov 2023 15:41:41 +0100 Subject: [PATCH 093/122] Add amount rules to each created output --- tips/TIP-0045/tip-0045.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 00b1fe65f..e2e820cdb 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1191,6 +1191,8 @@ The following criteria defines whether a payload passes the syntactical validati - `Outputs Count` must be `0 < x ≤ Max Outputs Count`. - For each output the following must be true: - `Output Type` must match one of the values described under [Outputs](#outputs). + - The `Amount` field must not be `0`. + - The `Amount` field must be at least the minimum storage deposit according to [TIP-47](../TIP-0047/tip-0047.md). - The output itself must pass syntactic validation. - The sum of all `Amount` fields must not exceed `Max IOTA Supply`. - The sum of all `Mana` fields must not exceed 2Mana Bits Count - 1. From d2044c0feb099aaf6bfe6ad1d582a9d79f063401 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 20 Nov 2023 09:46:16 +0100 Subject: [PATCH 094/122] Remove outdated max native token count rule --- tips/TIP-0045/tip-0045.md | 1 - 1 file changed, 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index e2e820cdb..fdf281fa6 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -1196,7 +1196,6 @@ The following criteria defines whether a payload passes the syntactical validati - The output itself must pass syntactic validation. - The sum of all `Amount` fields must not exceed `Max IOTA Supply`. - The sum of all `Mana` fields must not exceed 2Mana Bits Count - 1. - - The count of all distinct native tokens present in outputs must not be larger than `Max Native Token Count`. - Allotments: - `Allotments Count` must be `0 ≤ x ≤ 128`. - The sum of all `Mana` fields must not exceed 2Mana Bits Count - 1. From 45eebdccd519bd81c6709b935f1e8bb2edfd5f47 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 20 Nov 2023 11:56:45 +0100 Subject: [PATCH 095/122] Update tips/TIP-0045/tip-0045.md Co-authored-by: Thibault Martinez --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index fdf281fa6..3d313b760 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -732,7 +732,7 @@ that a given Output ID was derived from a given Output. ### Transaction ID -A Transaction ID consists of two commitments, the _Transaction Commitment_ and the _Ouptut Commitment_. It is a +A Transaction ID consists of two commitments, the _Transaction Commitment_ and the _Output Commitment_. It is a `ByteArray[36]` which is computed as follows: - Let `Transaction Bytes` be the concatenated serialization of the fields from `Network ID` to `Payload`. From 054a719fa169109f656a768fb14a47692688c616 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Mon, 20 Nov 2023 12:52:41 +0100 Subject: [PATCH 096/122] Update Tagged Data description --- tips/TIP-0045/tip-0045.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index fdf281fa6..a3fbfb772 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -504,7 +504,7 @@ The following table describes the entirety of a _Signed Transaction_ in its seri
Tagged Data -
Data with an optional tag. Defined in TIP-53 (Tagged Data).
+
Optional Data with an optional Tag. Defined in TIP-53 (Tagged Data).
Input TypeContext Input Type uint8Set to value 1 to denote a Commitment Input.Set to value 0 to denote a Commitment Input.
Commitment ID
Input TypeContext Input Type uint8Set to value 2 to denote a Block Issuance Credit Input.Set to value 1 to denote a Block Issuance Credit Input.
Account ID
Input TypeContext Input Type uint8Set to value 3 to denote a Reward Input.Set to value 2 to denote a Reward Input.
Index
Input TypeContext Input Type uint8Set to value 1 to denote a Commitment Input.Set to value 0 to denote a Commitment Input.
Commitment ID
Input TypeContext Input Type uint8Set to value 2 to denote a Block Issuance Credit Input.Set to value 1 to denote a Block Issuance Credit Input.
Account ID
Input TypeContext Input Type uint8Set to value 3 to denote a Reward Input.Set to value 2 to denote a Reward Input.
Index
-##### Reference Unlock Syntactic Validation - -- 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 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: @@ -1131,6 +1126,11 @@ following structure of the Unlocks part: | 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`. | +##### Reference Unlock Syntactic Validation + +- The _Reference Unlock_ at index `i` must have `Reference < i` and the unlock at index `Reference` must be a _Signature + Unlock_ or _Multi Unlock_. + ##### Reference Unlock Semantic Validation - It must hold for the `Unlock` at index `Reference`, to which the _Reference Unlock_ at index `i` points and the From 0043c197a349a0e362db4b3f7f80c2c557fdfb21 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 12 Mar 2024 14:40:10 +0800 Subject: [PATCH 122/122] Clarify Network ID construction --- tips/TIP-0045/tip-0045.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tips/TIP-0045/tip-0045.md b/tips/TIP-0045/tip-0045.md index 6b6f05097..0502cc5cd 100644 --- a/tips/TIP-0045/tip-0045.md +++ b/tips/TIP-0045/tip-0045.md @@ -747,7 +747,8 @@ A Transaction ID consists of two commitments, the _Transaction Commitment_ and t The `Network ID` field of the transaction serves as a [replay protection mechanism](https://github.com/iotaledger/tips/discussions/56). It is a unique value denoting whether the transaction was meant for the IOTA mainnet, shimmer, testnet-1, or a private network. It consists of the first 8 -bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as an unsigned integer number. +bytes of the BLAKE2b-256 hash of the `Network Name` protocol parameter, interpreted as a `uint64` in little endian +encoding. | Network Name | Resulting `Network ID` | Network Name defined in | | ------------------- | ---------------------- | --------------------------------------------------- |