From d6ca1fba92c8b79bedc0aeaba755ec5c906f9086 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Tue, 4 Jul 2023 09:39:24 +0200 Subject: [PATCH] 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:
Description
Input Typeuint16The input type of Reward Input is 3.Context Input Typeuint8Set to value 2 to denote a Reward Input.
Index