tip-0054.md

tip	title	description	author	discussions-to	status	type	layer	created	requires	replaces
54	Anchor Output Type	Defines the IOTA 2.0 Anchor Output used to anchor commitments into Layer 1.	Philipp Gackstatter (@PhilippGackstatter) <philipp.gackstatter@iota.org>	#157	Draft	Standards	Core	2023-11-02	TIP-21, TIP-22, TIP-38 and TIP-47	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. 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 can hold Foundries instead. See that TIP for Alias Output migration details.
• Remove Native Tokens field. See TIP-38 (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.

Protocol Parameters

Protocol parameters used throughout this TIP are defined in TIP-49.

Transaction Payload

TIP-45 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 Type	uint8	Set to value 3 to denote a State Metadata Feature.
Entries Count	uint8	The 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)ByteArray A string which may only consist of printable ASCII characters. A leading uint8 denotes its length. Value (uint16)ByteArray An 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) apply.

Additional constraints are defined in the 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 Type	uint8	Set 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 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 Type	uint8	Set 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 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 Type	uint8	Set to value 3 to denote an Anchor Unlock.
Anchor Reference Unlock Index	uint16	Index 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 Type	uint8	Set to value 2 to denote an Anchor Output.
Amount	uint64	The amount of IOTA coins held by the output.
Mana	uint64	The amount of Stored Mana held by the output.
Anchor ID	ByteArray[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 Index	uint32	A counter that must increase by 1 every time the anchor is state transitioned.
Unlock Conditions Count	uint8	The 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 Type uint8 Set 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 Type uint8 Set 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 Count	uint8	The 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 Type uint8 Set to value 2 to denote a Metadata Feature. Entries Count uint8 The 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)ByteArray A string which may only consist of printable ASCII characters. A leading uint8 denotes its length. Value (uint16)ByteArray An 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 Type uint8 Set to value 3 to denote a State Metadata Feature. Entries Count uint8 The 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)ByteArray A string which may only consist of printable ASCII characters. A leading uint8 denotes its length. Value (uint16)ByteArray An array of arbitrary binary data. A leading uint16 denotes its length.
Immutable Features Count	uint8	The 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 Type uint8 Set 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 Type uint8 Set to value 2 to denote a Metadata Feature. Entries Count uint8 The 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)ByteArray A string which may only consist of printable ASCII characters. A leading uint8 denotes its length. Value (uint16)ByteArray An 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).

Storage Score

The following test vector shows the calculation of the storage score according to TIP-47.

Anchor Output (json-encoded):

{
  "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.