diff --git a/tips/TIP-0054/tip-0054.md b/tips/TIP-0054/tip-0054.md new file mode 100644 index 000000000..7d43ca86f --- /dev/null +++ b/tips/TIP-0054/tip-0054.md @@ -0,0 +1,861 @@ +--- +tip: 54 +title: Anchor Output Type +description: Defines the IOTA 2.0 Anchor Output used to anchor commitments into Layer 1. +author: + Philipp Gackstatter (@PhilippGackstatter) +discussions-to: https://github.com/iotaledger/tips/pull/157 +status: Draft +type: Standards +layer: Core +created: 2023-11-02 +requires: TIP-21, TIP-22, TIP-38 and TIP-47 +replaces: TIP-18 +--- + +# Summary + +An Anchor Output represents an output in the ledger with two control levels and a permanent Anchor Address. The anchor +owns other outputs that are locked under Anchor Address. The anchor keeps track of state transitions (`State Index` +counter) and can be used to anchor layer 2 state as metadata into the UTXO ledger. The Anchor ID, the unique identifier, +is generated deterministically by the protocol and is not allowed to change in any future state transitions. + +The Anchor Output can be seen as the successor to the Alias Output in [TIP-18](../TIP-0018/tip-0018.md). However the +Anchor Output is not a strict extension of the functionality of the Alias Output. + +## Summary of changes compared to TIP-18 + +Compared to the _Alias Output_: + +- Add `Mana` field to the `Anchor`. +- Remove `Foundry Counter` field. The [_Account Output_](../TIP-0042/tip-0042.md#account-output) can hold Foundries + instead. See that TIP for _Alias Output_ migration details. +- Remove `Native Tokens` field. See [TIP-38 (Native Token Migration)](../TIP-0038/tip-0038.md#native-token-migration) + for migration details. + +# Motivation + +This TIP defines an Anchor Output type for the use case of anchoring state into Layer 1. The prime example for state +anchoring are IOTA Smart Contract Chains. This TIP accommodates that use case in particular through the two levels of +control given by the _state controller_ and _governor_. A governor can control the parameters of the chain and who is +allowed to change the state, but cannot do so themselves, while a state controller is allowed to update the state. + +# Building Blocks + +## Data Types & Subschema Notation + +Data types and subschemas used throughout this TIP are defined in [TIP-21](../TIP-0021/tip-0021.md). + +## Protocol Parameters + +Protocol parameters used throughout this TIP are defined in [TIP-49](../TIP-0049/tip-0049.md). + +## Transaction Payload + +[TIP-45](../TIP-0045/tip-0045.md) is the basis for output validation in this TIP. + +# Building Blocks + +## State Metadata Feature + +A _Metadata Feature_ that can only be changed by the _State Controller_. + +
+ State Metadata Feature +
Defines a map of key-value pairs that is stored in the output, that can only be modified by the State Controller.
+
+ + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 3 to denote a State Metadata Feature.
Entries Countuint8The number of entries in the map.
Entries anyOf +
+ Metadata Entry +
A map entry consisting of a string key and an arbitrary byte value.
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Key(uint8)ByteArrayA string which may only consist of printable ASCII characters. A leading uint8 denotes its length.
Value(uint16)ByteArrayAn array of arbitrary binary data. A leading uint16 denotes its length.
+
+
+ +The same syntactic transaction validation rules as for the _Metadata Feature_ defined in +[Metadata Feature (Additional Transaction Syntactic Validation Rules)](../TIP-0038/tip-0038.md#additional-transaction-syntactic-validation-rules-3) +apply. + +Additional constraints are defined in the [Anchor Output](#anchor-output) section. + +## State Controller Address Unlock Condition + +An unlock condition defined solely for Anchor Output. It is functionally equivalent to an Address Unlock +Condition, however there are additional transition constraints defined for the Anchor UTXO state machine that can +only be carried out by the `State Controller Address`, hence the distinct unlock condition type. + +
+ State Controller Address Unlock Condition +
Defines the State Controller Address that owns this output. It can unlock the output with the proper Unlock in a transaction that state transitions the anchor output.
+
+ + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 4 to denote a State Controller Address Unlock Condition.
Address oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
+ +The additional constraints are defined in the [Anchor Output](#anchor-output) section. + +## Governor Address Unlock Condition + +An unlock condition defined solely for Anchor Output. It is functionally equivalent to an Address Unlock +Condition, however there are additional transition constraints defined for the Anchor UTXO state machine that can +only be carried out by the `Governor Address`, hence the distinct unlock condition type. + +
+ Governor Address Unlock Condition +
Defines the Governor Address that owns this output. It can unlock the output with the proper Unlock in a transaction that governance transitions the anchor output.
+
+ + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 5 to denote a Governor Address Unlock Condition.
Address oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
+ +The additional constraints are defined in the [Anchor Output](#anchor-output) section. + +## Anchor Locking & Unlocking + +A transaction may consume an output that belongs to an Anchor Address by transitioning the anchor output with the +matching `Anchor ID`. This serves the exact same purpose as providing a signature to unlock an output locked under a +private key backed address, such as Ed25519 Addresses. + +On protocol level, anchor unlocking is done using a new unlock type, called **Anchor Unlock**. + +
+ Anchor Unlock +
Points to the unlock of a consumed Anchor Output.
+
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Typeuint8Set to value 3 to denote an Anchor Unlock.
Anchor Reference Unlock Indexuint16Index of input and unlock corresponding to an Anchor Output.
+ +This unlock is similar to the Reference Unlock. However, it is valid if and only if the input of the transaction +at index `Anchor Reference Unlock Index` is an anchor output with the same `Anchor ID` as the one derived from the +`Address` field of the to-be unlocked output. + +Additionally, the Anchor Unlocks must also be ordered to prevent circular dependencies: + +If the i-th _Unlock_ of a transaction is an _Anchor Unlock_ and has `Anchor Reference Unlock Index` set to k, it must +hold that i > k. Hence, an Anchor Unlock can only reference an _Unlock_ (unlocking the corresponding anchor) at a +smaller index. + +For example the scenario where `Anchor A` is locked to the address of `Anchor B` while `Anchor B` is in locked to the +address of `Anchor A` introduces a circular dependency and is not well-defined. By requiring the _Unlocks_ to be ordered +as described above, a transaction consuming `Anchor A` as well as `Anchor B` can never be valid as there would always +need to be one _Anchor Unlock_ referencing a greater index. + +#### Anchor Unlock Syntactic Validation + +- It must hold that 0 ≤ `Anchor Reference Unlock Index` < `Max Inputs Count - 1`. + +#### Anchor Unlock Semantic Validation + +- The address of the unlocking condition of the input being unlocked must be an Anchor Address. +- The index `i` of the _Anchor Unlock_ is the index of the input in the transaction that it unlocks. + `Anchor Reference Unlock Index` must be < `i`. +- `Anchor Reference Unlock Index` defines a previous input of the transaction and its unlock. This input must be an + _Anchor Output_ with `Anchor ID` that refers to the _Anchor Address_ being unlocked. +- The referenced _Anchor Output_ must be unlocked. + +# Anchor Output + +The _Anchor Output_ is a specific implementation of a UTXO state machine. `Anchor ID`, the unique identifier of an +instance of the deployed state machine, is generated deterministically by the protocol and is not allowed to change in +any future transitions. + +An _Anchor Output_ is an output with a permanent _Anchor Address_ and owns other outputs that are locked under this +_Anchor Address_. + +
+ Anchor Output +
An anchor in the ledger that can be controlled by the state and governance controllers.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Output Typeuint8Set to value 2 to denote an Anchor Output.
Amountuint64The amount of IOTA coins held by the output.
Manauint64The amount of Stored Mana held by the output.
Anchor IDByteArray[32]Unique identifier of the anchor, which is the BLAKE2b-256 hash of the Output ID that created it. Anchor Address = Anchor Address Type || Anchor ID.
State Indexuint32A counter that must increase by 1 every time the anchor is state transitioned.
Unlock Conditions Countuint8The number of unlock conditions following.
Unlock Conditions atMostOneOfEach +
+ State Controller Address Unlock Condition +
Defines the State Controller Address that owns this output. It can unlock the output with the proper Unlock in a transaction that state transitions the anchor output. Defined in TIP-54 (State Controller Address Unlock Condition).
+ + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 4 to denote a State Controller Address Unlock Condition.
Address oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
+
+
+ Governor Address Unlock Condition +
Defines the Governor Address that owns this output. It can unlock the output with the proper Unlock in a transaction that governance transitions the anchor output. Defined in TIP-54 (Governor Address Unlock Condition).
+ + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 5 to denote a Governor Address Unlock Condition.
Address oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
+
+
Features Countuint8The number of features following.
Features atMostOneOfEach +
+ Metadata Feature +
Defines a map of key-value pairs that is stored in the output. Defined in TIP-38 (Metadata Feature).
+ + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 2 to denote a Metadata Feature.
Entries Countuint8The number of entries in the map.
Entries anyOf +
+ Metadata Entry +
A map entry consisting of a string key and an arbitrary byte value.
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Key(uint8)ByteArrayA string which may only consist of printable ASCII characters. A leading uint8 denotes its length.
Value(uint16)ByteArrayAn array of arbitrary binary data. A leading uint16 denotes its length.
+
+
+
+
+ State Metadata Feature +
Defines a map of key-value pairs that is stored in the output, that can only be modified by the State Controller. Defined in TIP-54 (State Metadata Feature).
+ + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 3 to denote a State Metadata Feature.
Entries Countuint8The number of entries in the map.
Entries anyOf +
+ Metadata Entry +
A map entry consisting of a string key and an arbitrary byte value.
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Key(uint8)ByteArrayA string which may only consist of printable ASCII characters. A leading uint8 denotes its length.
Value(uint16)ByteArrayAn array of arbitrary binary data. A leading uint16 denotes its length.
+
+
+
+
Immutable Features Countuint8The number of immutable features following. Immutable features are defined upon deployment of the UTXO state machine and are not allowed to change in any future state transition.
Immutable Features atMostOneOfEach +
+ Issuer Feature +
Identifies the validated issuer of the UTXO state machine. Defined in TIP-38 (Issuer Feature).
+ + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 1 to denote a Issuer Feature.
Issuer oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
+
+
+ Metadata Feature +
Defines a map of key-value pairs that is stored in the output. Defined in TIP-38 (Metadata Feature).
+ + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 2 to denote a Metadata Feature.
Entries Countuint8The number of entries in the map.
Entries anyOf +
+ Metadata Entry +
A map entry consisting of a string key and an arbitrary byte value.
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Key(uint8)ByteArrayA string which may only consist of printable ASCII characters. A leading uint8 denotes its length.
Value(uint16)ByteArrayAn array of arbitrary binary data. A leading uint16 denotes its length.
+
+
+
+
+ +## Additional Transaction Syntactic Validation Rules + +- It must hold true that `Unlock Conditions Count = 2`. +- `Unlock Condition Type` of an Unlock Condition must define one of the following types: + - State Controller Address Unlock Condition + - Governor Address Unlock Condition +- Unlock Conditions must be sorted in ascending order based on their `Unlock Condition Type`. +- Syntactic validation of all present unlock conditions must pass. +- It must hold true that `0` ≤ `Features Count` ≤ `2`. +- `Feature Type` of a Feature in `Features` must define one of the following types: + - Metadata Feature + - State Metadata Feature +- It must hold true that `0` ≤ `Immutable Features Count` ≤ `2`. +- `Feature Type` of a Feature in `Immutable Features` must define on of the following types: + - Issuer Feature + - Metadata Feature +- Features must be sorted in ascending order based on their `Feature Type` both in `Features` and + `Immutable Features` fields. +- Syntactic validation of all present features must pass. +- `Address` of _State Controller Address Unlock Condition_ and `Address` of _Governor Address Unlock Condition_ must be + different from the anchor address derived from `Anchor ID`. + +## Additional Transaction Semantic Validation Rules + +- Explicit `Anchor ID`: `Anchor ID` is taken as the value of the `Anchor ID` field in the anchor output. +- Implicit `Anchor ID`: When an anchor output is consumed as an input in a transaction and the `Anchor ID` field is + zeroed out, take the BLAKE2b-256 hash of the `Output ID` of the input as `Anchor ID`. +- For every non-zero explicit `Anchor ID` on the output side there must be a corresponding anchor on the input side. The + corresponding anchor has the explicit or implicit `Anchor ID` equal to that of the anchor on the output side. + +### Consumed Outputs + +Whenever an anchor output is consumed in a transaction, it means that the anchor is transitioned into its next state. +The **current state** is defined as the **consumed anchor output**, while the **next state** is defined as the **anchor +output with the same explicit `AnchorID` on the output side**. There are two types of transitions: `state transition` +and `governance transition`. + +- State transition: + - A state transition is identified by an incremented `State Index`. + - The `State Index` must be incremented by 1. + - The unlock must correspond to the `Address` of State Controller Address Unlock Condition. + - State transition can only change the following fields in the next state: + - `Amount`, + - `Mana`, + - `State Index`, + - `State Metadata Feature` in `Features`. +- Governance transition: + - A governance transition is identified by an unchanged `State Index` in next state. If there is no anchor output on + the output side with a corresponding explicit `Anchor ID`, the anchor is being destroyed. The next state is the + empty state. The transaction is invalid if an Anchor Output is burned and the _Can destroy Anchor Outputs_ flag in + the _Transaction Capabilities_ is **unset**. + - The unlock must correspond to the `Address` of Governor Address Unlock Condition. + - Governance transition must only change the following fields: + - `Address` of State Controller Address Unlock Condition, + - `Address` of Governor Address Unlock Condition, + - `Metadata Feature` in `Features`. + - The `Metadata Feature` is optional, the governor can put additional info about the chain here, for example chain + name, fee structure, supported VMs, list of access nodes, etc., anything that helps clients to fetch info (i.e. + anchor balances) about the layer 2 network. +- When a consumed anchor output has Features defined in `Immutable Features` and a corresponding anchor output on + the output side, `Immutable Features` is not allowed to change. + +### Created Outputs + +- When Issuer Feature is present in an output and explicit `Anchor ID` is zeroed out, an input with `Address` + field that corresponds to `Issuer` must be unlocked in the transaction. + +### Notes + +- Indexers and node plugins shall map the anchor address of the output derived with `Anchor ID` to the regular + address -> output mapping table, so that given an Anchor Address, its most recent unspent anchor output + can be retrieved. + +# Test Vectors + +The protocol parameters used in the following test vectors are the same as in +[TIP-49 (Protocol Parameters Hash)](../TIP-0049/tip-0049.md#protocol-parameters-hash). + +## Storage Score + +The following test vector shows the calculation of the storage score according to [TIP-47](../TIP-0047/tip-0047.md). + +Anchor Output (json-encoded): + +```json +{ + "type": 2, + "amount": "420000000", + "mana": "42", + "anchorId": "0x0000000000000000000000000000000000000000000000000000000000000000", + "stateIndex": 0, + "unlockConditions": [ + { + "type": 4, + "address": { + "type": 8, + "accountId": "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + } + }, + { + "type": 5, + "address": { + "type": 8, + "accountId": "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + } + } + ], + "features": [ + { + "type": 2, + "entries": { + "iota": "0x322e30" + } + } + ], + "immutableFeatures": [ + { + "type": 2, + "entries": { + "iota": "0x322e30" + } + } + ] +} +``` + +Anchor Output (hex-encoded binary serialization): + +``` +0x0200b10819000000002a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000002040817432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a050817432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a01020104696f74610300322e3001020104696f74610300322e30 +``` + +Anchor Output Storage Score: `236`. + +# Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).