tip: 18 title: Multi-Asset Ledger and ISC Support description: Transform IOTA into a multi-asset ledger that supports running IOTA Smart Contracts author: Levente Pap (@lzpap)discussions-to: https://github.com/iotaledger/tips/pull/38 status: Proposed type: Standards layer: Core created: 2021-11-04 requires: TIP-19, TIP-20, TIP-21 and TIP-22
Summary
This document proposes new output types and transaction validation rules for the IOTA protocol to support native tokenization and smart contract features.
Native tokenization refers to the capability of the IOTA ledger to track the ownership and transfer of user defined tokens, so-called native tokens, thus making it a multi-asset ledger. The scalable and feeless nature of IOTA makes it a prime candidate for tokenization use cases.
The IOTA Smart Contract Protocol (ISCP) is a layer 2 extension of the IOTA protocol that adds smart contract features to the Tangle. Many so-called smart contract chains, which anchor their state to the base ledger, can be run in parallel. Users wishing to interact with smart contract chains can send requests to layer 1 chain accounts either as regular transactions or directly to the chain, but chains may also interact with other chains in a trustless manner through the Tangle.
This TIP presents output types that realize the required new features:
- Smart contract chains have a new account type, called alias account, represented by an alias output.
- Requests to smart contract chains can be carried out using the configurable new output type called basic output.
- Native tokens have their own supply control policy enforced by foundry outputs.
- Layer 1 native non-fungible tokens (unique tokens with attached metadata) are introduced via NFT outputs.
Motivation
IOTA transitioned from an account based ledger model to an unspent transaction output (UTXO) model with the upgrade to Chrysalis phase 2. In this model, transactions explicitly reference funds produced by previous transactions to be consumed. This property is desired for scalability: transaction validation does not depend on the shared global state and, as such, transactions can be validated in parallel. Double-spends can easily be detected as they spend the very same output more than once.
The UTXO model becomes even more powerful when unlocking criteria (validation) of outputs is extended as demonstrated by the EUTXO model (Chakravarty et al., 2020): instead of requiring only a valid signature for the output's address to unlock it, additional unlocking conditions can be programmed into outputs. This programmability of outputs is the main idea behind the new output types presented in this document.
Today, outputs in the IOTA protocol are designed for one specific use case: the single asset cryptocurrency. The aim of this TIP is to design several output types for the use cases of:
- Native Tokenization Framework,
- ISCP style smart contracts,
- seamless interoperability between layer 1 and layer 2 tokenization concepts.
Users will be able to mint their own native tokens directly in the base ledger, which can then be transferred without any fees just like regular IOTA coins. Each native token has its own supply control policy enforced by the protocol. These policies are transparent to all network participants. Issuers will be able to store metadata about their tokens on-ledger, accessible to anyone.
Non-fungible tokens can be minted and transferred with zero fees. The validated issuers of such NFTs are immutably attached to the tokens, making it impossible to counterfeit them.
Users will be able to interact with smart contracts by posting requests through the Tangle. Requests can carry commands to smart contracts and can additionally also transfer native tokens and NFTs. By depositing native tokens to smart contracts, their features can be greatly enhanced and programmed to specific use cases.
The proposal in this TIP not only makes it possible to transfer native tokens to layer 2 smart contracts, but tokens that originate from layer 2 smart contract chains can also be wrapped into their respective layer 1 representation. Smart contract chains may transfer tokens between themselves through this mechanism, and they can also post requests to other chains.
Composability of smart contracts extends the realm of one smart contract chain, as smart contracts residing on different chains can call each other in a trustless manner.
In conclusion, the IOTA protocol will become a scalable general purpose multi-asset DLT with the addition of smart contracts and native tokenization frameworks. The transition is motivated by the ever-growing need for a scalable and affordable decentralized application platform.
Detailed Design
Outputs in the UTXO model are essential, core parts of the protocol. The new output types introduce new validation and unlocking mechanisms, therefore the protocol needs to be adapted. The structure of the remaining sections is as follows:
- Introduction to ledger programmability
- Data types, subschemas and protocol constants
- Transaction Payload changes compared to Chrysalis Part 2
- New concepts of output design
- Detailed design of new output types
- New unlocking mechanisms
- Discussion
Ledger Programmability
The current UTXO model only provides support to transfer IOTA coins. However, the UTXO model presents a unique opportunity to extend the range of possible applications by programming outputs.
Programming the base ledger of a DLT is not a new concept. Bitcoin uses the UTXO model and attaches small executables (scripts) that need to be executed during transaction validation. The bitcoin script language is however not Turing-complete as it can only support a small set of instructions that are executed in a stack based environment. As each validator has to execute the same scripts and arrive at the same conclusion, such scripts must terminate very quickly. Also, as transaction validation happens in the context of the transaction and block, the scripts have no access to the global shared state of the system (all unspent transaction outputs).
The novelty of Ethereum was to achieve quasi Turing-completeness by employing an account based model and gas to limit resource usage during program execution. As the amount of gas used per block is limited, only quasi Turing-completeness can be achieved. The account based model of Ethereum makes it possible for transactions to have access to the global shared state of the system, furthermore, transactions are executed one-after-the-other. These two properties make Ethereum less scalable and susceptible to high transaction fees.
Cardano achieves UTXO programmability by using the EUTXO model. This makes it possible to represent smart contracts in a UTXO model as state machines. In EUTXO, states of the machine are encoded in outputs, while state transition rules are governed by scripts. Just like in bitcoin, these scripts may only use a limited set of instructions.
It would be quite straightforward to support EUTXO in IOTA too, except that IOTA transactions are feeless. There is no reward to be paid out to validators for validating transactions, as all nodes in the network validate all transactions. Due to the unique data structure of the Tangle, there is no need for miners to explicitly choose which transactions are included in the ledger, but there still has to be a notion of objective validity of transactions. Since it is not possible without fees to penalize scripts that consume excessive network resources (node CPU cycles) during transaction validation, IOTA has to be overly restrictive about what instructions are supported on layer 1.
It must also be noted that UTXO scripts are finite state machines with the state space restricted by the output and transaction validation rules. It makes expressiveness of UTXO scripts inherently limited. In the context of complicated application logic required by use cases such as modern DeFi, this leads to unconventional and complicated architectures of the application, consisting of many interacting finite state machines. Apart from complexity and UX costs, it also has performance and scalability penalties.
For the reason mentioned above, IOTA chooses to support configurable yet hard-coded scripts for output and transaction validation on layer 1. The general full-scale quasi Turing-complete programmability of the IOTA ledger is achieved by extending the ledger state transition function with layer 2 smart contract chains. This not only makes it possible to keep layer 1 scalable and feeless, but also allows to support any type of virtual machine on layer 2 to program advanced business logic and features.
Below, several new output types are discussed that implement their own configurable script logic. They can be viewed as UTXO state machines in which the state of the machine is encoded as data inside the output. The state transition rules are defined by the output type and by the parameters chosen upon deployment.
Data Types & Subschema Notation
Data types and subschemas used throughout this TIP are defined in TIP-21.
Global Protocol Parameters
Global protocol parameters used throughout this TIP are defined in TIP-22 (IOTA) and TIP-32 (Shimmer).
Transaction Payload Changes
The new output types and unlocking mechanisms require new transaction validation rules, furthermore some protocol rules have been modified compared to Chrysalis Part 2 Transaction Payload TIP-7.
TIP-20 replaces aforementioned TIP-7 with the new transaction layout and validation rules. The updated version is the basis for output validation in this TIP.
Summary of Changes
- Deprecating SigLockedSingleOutput and SigLockedDustAllowanceOutput.
- The new dust protection mechanism does not need a distinct output type, therefore SigLockedDustAllowanceOutput will be deprecated. One alternative is that during migration to the new protocol version, all dust outputs sitting on an address will be merged into a Basic Output together with their respective SigLockedDustAllowanceOutputs to create the snapshot for the updated protocol. The exact migration strategy will be decided later.
- Adding new output types to Transaction Payload.
- Adding new unlock types to Transaction Payload.
- Inputs and Outputs of a transaction become a list instead of a set. Binary duplicate inputs are not allowed as they anyway mean double-spends, but binary duplicate outputs are allowed.
- There can be many outputs created to the same address in the transaction.
- Confirming milestone supplies notion of time to semantic transaction validation.
New Concepts
New output types add new features to the protocol and hence new transaction validation rules. While some of these new features are specifically tied to one output type, some are general, LEGO like building blocks that may be put in several types of outputs.
Below is a summary of such new features and the validation rules they introduce.
Native Tokens in Outputs
Outputs are records in the UTXO ledger that track ownership of funds. Thus, each output must be able to specify which funds it holds. With the addition of the Native Tokenization Framework, outputs may also carry user defined native tokens, that is, tokens that are not IOTA coins but were minted by foundries and are tracked in the very same ledger. Therefore, every output must be able to hold not only IOTA coins, but also native tokens.
Dust protection applies to all outputs, therefore it is not possible for outputs to hold only native tokens, the storage deposit requirements must be covered via IOTA coins.
User defined tokens are called Native Tokens on protocol level. The maximum supply of a particular native token
is defined by the representation chosen on protocol level for defining their amounts in outputs. Since native tokens
are also a vehicle to wrap layer 2 tokens into layer 1 tokens, the chosen representation must take into account the
maximum possible supply of layer 2 tokens. Solidity, the most popular smart contract language defines the
maximum supply of an ERC-20 token as MaxUint256
, therefore it should be possible to represent such huge amount of
assets on layer 1.
Outputs must have the following fields to define the balance of native tokens they hold:
Name | Type | Description | |||||||||
Native Tokens Count | uint8 | The number of native tokens present in the output. | |||||||||
Native Tokens optAnyOf |
Native Token
|
Additional syntactic output validation rules:
Native Tokens
must be lexicographically sorted based onToken ID
.- Each Native Token must be unique in the set of
Native Tokens
based on itsToken ID
. No duplicates are allowed. Amount
of any Native Token must not be0
.
Additional semantic transaction validation rules:
- The transaction is balanced in terms of native tokens, that is, the sum of native token balances in consumed outputs equals that of the created outputs.
- When the transaction is imbalanced and 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 in the foundry.
New Functionalities in Outputs
The programmability of outputs opens the door for implementing new functionalities for the base protocol. While some outputs were specifically designed for such new features, some are optional additions that may be used with any outputs that support them.
These new functionalities are grouped into two categories:
- Unlock Conditions and
- simple Features.
The Output Design section lists all supported Unlock Conditions and Features for each output type.
Unlock Conditions
New output features that introduce unlocking conditions, that is, they define constraints on how the output can be unlocked and spent, are grouped under the field Unlock Conditions.
Each output must not contain more than one unlock condition of each type and not all unlock condition types are supported for each output type.
Address Unlock Condition
It is merely a layout change that the previously defined Address
field of outputs (TIP-7)
is represented as an Address Unlock Condition. Unlocking an Ed25519 Address doesn't change, it has to
be performed via a Signature Unlock in a transaction by signing the hash of the transaction essence.
Transaction validation rules are detailed in TIP-20.
New additions are the Alias Address and NFT Address types, which have to be unlocked with their corresponding unlocks, as defined in Unlocking Chain Script Locked Outputs.
Address Unlock
Defines the Address that owns this output, that is, it can unlock it with the proper Unlock in a transaction.
Name | Type | Description | |||||||||||||||||||||||||||
Unlock Condition Type | uint8 | Set to value 0 to denote an Address Unlock Condition. | |||||||||||||||||||||||||||
Address |
Ed25519 Address
Alias Address
NFT Address
|
:information_source: Good to know about address format |
---|
The Address Type byte of a raw address has an effect on the starting character of the bech32 encoded address, which is the recommended address format for user facing applications.
A usual bech32 encoded mainnet address starts with iota1
, and continues with the bech32 encoded bytes of the address.
By choosing Address Type as a multiple of 8 for different address types, the first character after the 1
separator in the bech32 address will always be different.
Address | Type Byte as uint8 | Bech32 Encoded |
---|---|---|
Ed25519 | 0 | iota1q... |
Alias | 8 | iota1p... |
NFT | 16 | iota1z... |
A user can identify by looking at the address whether it is a signature backed address, a smart contract chain account or an NFT address.
Storage Deposit Return Unlock Condition
This unlock condition is employed to achieve conditional sending. An output that has
Storage Deposit Return Unlock Condition specified can only be consumed in a transaction that deposits
Return Amount
IOTA coins into Return Address
. When several of such outputs are consumed, their return amounts per
Return Addresses
are summed up and the output side must deposit this total sum per Return Address
.
Additional syntactic transaction validation rule:
Minimum Storage Deposit
is the storage deposit in the base currency required for a Basic Output that only has an Address Unlock Condition, no additional unlock conditions, no features and no native tokens.- It must hold true, that
Minimum Storage Deposit
≤Return Amount
≤Amount
.
Additional semantic transaction validation rule:
- An output that has Storage Deposit Return Unlock Condition specified must only be consumed and unlocked in a
transaction that deposits
Return Amount
IOTA coins toReturn Address
via one or more outputs that:- are of type Basic Output,
- have only an Address Unlock Condition defined,
- have no Native Tokens, and
- have no Features.
- When several outputs with Storage Deposit Return Unlock Condition and the same
Return Address
are consumed, their return amounts perReturn Addresses
are summed up and the output side of the transaction must deposit at least this total sum perReturn Address
via output(s) that satisfy the previous condition.
Storage Deposit Return Unlock Condition
Defines the amount of IOTAs used as storage deposit that have to be returned to Return Address.
Name | Type | Description | |||||||||||||||||||||||||||
Unlock Condition Type | uint8 | Set to value 1 to denote a Storage Deposit Return Unlock Condition. | |||||||||||||||||||||||||||
Return AddressoneOf |
Ed25519 Address
Alias Address
NFT Address
|
||||||||||||||||||||||||||||
Return Amount | uint64 | Amount of IOTA coins the consuming transaction should deposit to Return Address. |
This unlock condition makes it possible to send small amounts of IOTA coins or native tokens to addresses without having to lose control of the required storage deposit. It is also a vehicle to send on-chain requests to ISCP chains that do not require fees. To prevent the receiving party from blocking access to the storage deposit, it is advised to be used together with the Expiration Unlock Conditions. The receiving party then has a sender-defined time window to agree to the transfer by consuming the output, or the sender regains total control after expiration.
Timelock Unlock Condition
The notion of time in the Tangle is introduced via milestones. Each milestone carries the current unix timestamp corresponding to that milestone index. Whenever a new milestone appears, nodes perform the white-flag ordering and transaction validation on its past cone. The timestamp of the confirming milestone provide the time as an input parameter to transaction validation.
An output that contains a Timelock Unlock Condition can not be unlocked before the specified timelock has expired. The timelock is expired when the timestamp of the confirming milestone is equal or past the timestamp defined in the Timelock Unlock Condition.
Additional syntactic transaction validation rules:
Unix Time
field of a Timelock Unlock Condition must be >0
.
Additional semantic transaction validation rules:
- An output that has Timelock Unlock Condition specified must only be consumed and unlocked in a
transaction, if the timestamp of the confirming milestone is equal or past the
Unix Time
specified in the unlock condition.
Timelock Unlock Condition
Defines a unix timestamp until which the output can not be unlocked.
Name | Type | Description |
Unlock Condition Type | uint8 | Set to value 2 to denote a Timelock Unlock Condition. |
Unix Time | uint32 | Unix time (seconds since Unix epoch) starting from which the output can be consumed. |
Expiration Unlock Condition
The expiration feature of outputs makes it possible for the return address to reclaim an output after a given expiration time has been passed. The expiration can be specified as a unix timestamp.
The expiration feature can be viewed as an opt-in receive feature, because the recipient loses access to the received funds after the output expires, while the return address specified by the sender regains control over them. This feature is a big help for on-chain smart contract requests. Those that have expiration set and are sent to dormant smart contract chains can be recovered by their senders. Not to mention the possibility to time requests by specifying both a timelock and an expiration unlock condition.
Additional syntactic transaction validation rules:
Unix Time
field of an Expiration Unlock Condition must be >0
.
Additional semantic transaction validation rules:
- An output that has Expiration Unlock Condition set must only be consumed and
unlocked by the target
Address
(defined in Address Unlock Condition) in a transaction that has a confirming milestone timestamp earlier than theUnix Time
defined in the unlock condition. - An output that has Expiration Unlock Condition set must only be consumed and unlocked by the
Return Address
in a transaction that has a confirming milestone timestamp same or later than theUnix Time
defined in the unlock condition. - Semantic validation of an output that has Expiration Unlock Condition set and is unlocked by the
Return Address
must ignore:
The following table summarizes the outcome of syntactic and semantic validation rules with respect to which account is allowed to unlock the output containing the Expiration Unlock Condition:
Milestone Unix Timestamp Condition | Outcome |
---|---|
Unix Time = 0 | Output and containing transaction is invalid. |
Unix Time > Confirming Milestone Unix Timestamp | Unlockable by Address |
Unix Time ≤ Confirming Milestone Unix Timestamp | Unlockable by Return Address |
Expiration Unlock Condition
Defines a unix time until which only Address, defined in Address Unlock Condition, is allowed to unlock the output. After the unix time is reached/passed, only Return Address can unlock it.
Name | Type | Description | |||||||||||||||||||||||||||
Unlock Condition Type | uint8 | Set to value 3 to denote a Expiration Unlock Condition. | |||||||||||||||||||||||||||
Return Address oneOf |
Ed25519 Address
Alias Address
NFT Address
|
||||||||||||||||||||||||||||
Unix Time | uint32 | Before this unix time, Address Unlock Condition is allowed to unlock the output, after that only the address defined in Return Address. |
State Controller Address Unlock Condition
An unlock condition defined solely for Alias Output. It is functionally equivalent to an
Address Unlock Condition, however there are additional transition constraints defined for the Alias UTXO state
machine that can only be carried out by the State Controller Address
, hence the distinct unlock condition type.
State Controller Address Unlock
Defines the State Controller Address that owns this output, that is, it can unlock it with the proper Unlock in a transaction that state transitions the alias output.
Name | Type | Description | |||||||||||||||||||||||||||
Unlock Condition Type | uint8 | Set to value 4 to denote an State Controller Address Unlock Condition. | |||||||||||||||||||||||||||
Address |
Ed25519 Address
Alias Address
NFT Address
|
The additional constraints are defined in Alias Output Design section.
Governor Address Unlock Condition
An unlock condition defined solely for Alias Output. It is functionally equivalent to an
Address Unlock Condition, however there are additional transition constraints defined for the Alias UTXO state
machine that can only be carried out by the Governor Address
, hence the distinct unlock condition type.
Governor Address Unlock
Defines the Governor Address that owns this output, that is, it can unlock it with the proper Unlock in a transaction that governance transitions the alias output.
Name | Type | Description | |||||||||||||||||||||||||||
Unlock Condition Type | uint8 | Set to value 5 to denote an Governor Address Unlock Condition. | |||||||||||||||||||||||||||
Address |
Ed25519 Address
Alias Address
NFT Address
|
The additional constraints are defined in Alias Output Design section.
Immutable Alias Address Unlock Condition
An unlock condition defined for chain constrained UTXOs that can only be unlocked by a permanent Alias Address.
Output unlocking is functionally equivalent to an Address Unlock Condition with an Alias Address, however there are additional transition constraints: the next state of the UTXO machine must have the same Immutable Alias Address Unlock Condition.
Immutable Alias Address Unlock Condition
Defines the permanent Alias Address that owns this output.
Name | Type | Description | |||||||||
Unlock Condition Type | uint8 | Set to value 6 to denote an Immutable Alias Address Unlock Condition. | |||||||||
Address |
Alias Address
|
Additional semantic transaction validation rules:
- The output must be unlocked with an Alias Unlock.
- The next state of the UTXO state machine must have the same Immutable Alias Address Unlock Condition defined.
Features
New output features that do not introduce unlocking conditions, but rather add new functionality and add constraints on output creation are grouped under Features.
Each output must not contain more than one feature of each type and not all feature types are supported for each output type.
Sender Feature
Every transaction consumes several elements from the UTXO set and creates new outputs. However, certain applications (smart contracts) require to associate each output with exactly one sender address. Here, the sender feature is used to specify the validated sender of an output.
Outputs that support the Sender Feature may specify a Sender
address which is validated by the protocol during
transaction validation.
Additional semantic transaction validation rule:
- The Sender Feature, and hence the output and transaction that contain it, is valid, if and only if
Sender
address is unlocked in the transaction. Based on theAddress Type
, an address is unlocked in the transaction, if and only if:- Ed25519 Address:
- The Unlock of the first output in the transaction that contains the address is a valid Signature Unlock with respect to the address.
- Alias Address:
- The Alias Output that defines the address is state transitioned in the transaction. A governance transition does not unlock the address.
- NFT Address:
- The NFT Output that defines the address is consumed as input in the transaction.
- Ed25519 Address:
Sender Feature
Identifies the validated sender of the output.
Name | Type | Description | |||||||||||||||||||||||||||
Feature Type | uint8 | Set to value 0 to denote a Sender Feature. | |||||||||||||||||||||||||||
Address oneOf |
Ed25519 Address
Alias Address
NFT Address
|
Issuer Feature
The issuer feature is a special case of the sender feature that is only supported by outputs that implement a UTXO state
machine with chain constraint (alias, NFT).
Only when the state machine is created (e.g. minted) it is checked during transaction validation that an output
corresponding to the Issuer
address is consumed. In every future transition of the state machine, it is instead
checked that the issuer feature is still present and unchanged.
Additional semantic transaction validation rule:
- When an Issuer Feature is present in an output representing the initial state of an UTXO state machine, the
transaction that contains this output is valid, if and only if
Issuer
address is unlocked in the transaction. Based on theAddress Type
, an address is unlocked in the transaction, if and only if:- Ed25519 Address:
- The Unlock of the first output in the transaction that contains the address is a valid Signature Unlock with respect to the address.
- Alias Address:
- The Alias Output that defines the address is state transitioned in the transaction. A governance transition does not unlock the address.
- NFT Address:
- The NFT Output that defines the address is consumed as input in the transaction.
- Ed25519 Address:
The main use case is proving authenticity of NFTs. Whenever an NFT is minted as an NFT output, the creator (issuer) can fill the Issuer Feature with their address that they have to unlock in the transaction. Issuers then can publicly disclose their addresses to prove the authenticity of the NFT once it is in circulation.
Issuer Feature
Identifies the validated issuer of the UTXO state machine.
Name | Type | Description | |||||||||||||||||||||||||||
Feature Type | uint8 | Set to value 1 to denote an Issuer Feature. | |||||||||||||||||||||||||||
Address oneOf |
Ed25519 Address
Alias Address
NFT Address
|
Whenever a chain account mints an NFT on layer 1 on behalf of some user, the Issuer
field can only contain the
chain's address, since user does not sign the layer 1 transaction. As a consequence, artist would have to mint NFTs
themselves on layer 1 and then deposit it to chains if they want to place their own address in the Issuer
field.
Metadata Feature
Outputs may carry additional data with them that is interpreted by higher layer applications built on the Tangle. The protocol treats this metadata as pure binary data, it has no effect on the validity of an output except that it increases the required storage deposit. ISC is a great example of a higher layer protocol that makes use of Metadata Feature: smart contract request parameters are encoded in the metadata field of outputs.
Additional syntactic transaction validation rules:
- An output with Metadata Feature is valid, if and only if 0 <
length(Data)
≤Max Metadata Length
.
Metadata Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name | Type | Description |
Feature Type | uint8 | Set to value 2 to denote a Metadata Feature. |
Data | (uint16)ByteArray | Binary data. A leading uint16 denotes its length. |
Tag Feature
A Tag Feature makes it possible to tag outputs with an index, so they can be retrieved through an indexer API not
only by their address, but also based on the Tag
. The combination of a Tag Feature, a
Metadata Feature and a Sender Feature makes it possible to retrieve data associated to an address and stored
in outputs that were created by a specific party (Sender
) for a specific purpose (Tag
).
An example use case is voting on the Tangle via the participation plugin.
Additional syntactic transaction validation rules:
- An output with Tag Feature is valid, if and only if 0 <
length(Tag)
≤Max Tag Length
.
Tag Feature
Defines an indexation tag to which the output can be indexed by additional node plugins.
Name | Type | Description |
Feature Type | uint8 | Set to value 3 to denote a Tag Feature. |
Tag | (uint8)ByteArray | Binary indexation tag. A leading uint8 denotes its length. |
Chain Constraint in UTXO
Previously created transaction outputs are destroyed when they are consumed in a subsequent transaction as an input. The chain constraint makes it possible to carry the UTXO state machine state encoded in outputs across transactions. When an output with chain constraint is consumed, that transaction has to create a single subsequent output that carries the state forward. The state can be updated according to the transition rules defined for the given type of output and its current state. As a consequence, each such output has a unique successor, and together they form a path or chain in the graph induced by the UTXO spends. Each chain is identified by its globally unique identifier.
Alias outputs, foundry outputs and NFT outputs all use this chain constraint concept and define their own unique identifiers.
Output Design
In the following, we define four new output types. They are all designed with specific use cases in mind:
- Basic Output: transfer of funds with attached metadata and optional spending restrictions. Main use cases are on-ledger ISC requests, native asset transfers and indexed data storage in the UTXO ledger.
- Alias Output: representing ISC chain accounts on L1 that can process requests and transfer funds.
- Foundry Output: supply control of user defined native tokens. A vehicle for cross-chain asset transfers and asset wrapping.
- NFT Output: an output that represents a Non-fungible token with attached metadata and proof-of-origin. A NFT is represented as an output so that the token and metadata are transferred together, for example as a smart contract requests. NFTs are possible to implement with native tokens as well, but then ownership of the token does not mean ownership of the foundry that holds its metadata.
The validation of outputs is part of the transaction validation process. There are two levels of validation for transactions: syntactic and semantic validation. The former validates the structure of the transaction (and outputs), while the latter validates whether protocol rules are respected in the semantic context of the transaction. Outputs hence are validated on both levels:
- Transaction Syntactic Validation: validates the structure of each output created by the transaction.
- Transaction Semantic Validation:
- For consumed outputs: validates whether the output can be unlocked in a transaction given the semantic transaction context.
- For created outputs: validates whether the output can be created in a transaction given the semantic transaction context.
Each new output type may add its own validation rules which become part of the transaction validation rules if the output is placed inside a transaction. Unlock Conditions and Features described previously also add constraints to transaction validation when they are placed in outputs.
Basic Output
Basic Output can hold native tokens and might have several unlock conditions and optional features. The combination of several features provide the base functionality for the output to be used as an on-ledger smart contract request:
- Verified
Sender
, - Attached
Metadata
that can encode the request payload for layer 2, Return Amount
to get back the storage deposit,Timelock
to be able to time requests,Expiration
to recover funds in case of chain inactivity.
Besides, the Tag Feature is a tool to store arbitrary, indexed data with verified origin in the ledger.
Note, that a Basic Output in its simplest possible form with only an Address Unlock Condition and without features or native tokens is functionally equivalent to a SigLockedSingleOutput: it has an address and an IOTA balance. Therefore, aforementioned output type, that was introduced for Chrysalis Part 2 via TIP-7 is deprecated with the replacement of the TIP-20 Transaction Payload.
Name | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Output Type | uint8 | Set to value 3 to denote a Basic Output. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Amount | uint64 | The amount of IOTA coins to held by the output. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Native Tokens Count | uint8 | The number of native tokens held by the output. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Native Tokens optAnyOf |
Native Token
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Unlock Conditions Count | uint8 | The number of unlock conditions following. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Unlock Conditions atMostOneOfEach |
Address Unlock Condition
Storage Deposit Return Unlock ConditionDefines the amount of IOTAs used as storage deposit that have to be returned to Return Address.
Timelock Unlock ConditionDefines a unix timestamp until which the output can not be unlocked.
Expiration Unlock ConditionDefines a unix time until which only Address, defined in Address Unlock Condition, is allowed to unlock the output. After the unix time is reached or passed, only Return Address can unlock it.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Features Count | uint8 | The number of features following. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Features atMostOneOfEach |
Sender FeatureIdentifies the validated sender of the output.
Metadata FeatureDefines metadata (arbitrary binary data) that will be stored in the output.
Tag FeatureDefines an indexation tag to which the output can be indexed by additional node plugins.
|
Additional Transaction Syntactic Validation Rules
Amount
field must fulfill the dust protection requirements and must not be0
.Amount
field must be ≤Max IOTA Supply
.Native Tokens Count
must not be greater thanMax Native Tokens Count
.Native Tokens
must be lexicographically sorted based onToken ID
.- Each Native Token must be unique in the set of
Native Tokens
based on itsToken ID
. No duplicates are allowed. Amount
of any Native Token must not be0
.- It must hold true that
1
≤Unlock Conditions Count
≤4
. Unlock Condition Type
of an Unlock Condition must define one of the following types:- Address Unlock Condition
- Storage Deposit Return Unlock Condition
- Timelock Unlock Condition
- Expiration 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.
- Address Unlock Condition must be present.
- It must hold true that
0
≤Features Count
≤3
. Feature Type
of a Feature must define one of the following types:- Sender Feature
- Metadata Feature
- Tag Feature
- Features must be sorted in ascending order based on their
Feature Type
. - Syntactic validation of all present features must pass.
Additional Transaction Semantic Validation Rules
Consumed Outputs
- The unlock of the input must correspond to
Address
field in the Address Unlock Condition and the unlock must be valid. - The unlock is valid if and only if all unlock conditions and features present in the output validate.
Created Outputs
- All Unlock Condition imposed transaction validation criteria must be fulfilled.
- All Feature imposed transaction validation criteria must be fulfilled.
Alias Output
The Alias Output is a specific implementation of a UTXO state machine. Alias 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 state transitions.
Alias Output represents an alias account in the ledger with two control levels and a permanent
Alias Address. The account owns other outputs that are locked under Alias Address. The account keeps
track of state transitions (State Index
counter), controlled foundries (Foundry Counter
) and anchors the layer 2
state as metadata into the UTXO ledger.
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Output Type | uint8 | Set to value 4 to denote a Alias Output. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Amount | uint64 | The amount of IOTA coins held by the output. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Native Tokens Count | uint8 | The number of native tokens held by the output. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Native Tokens optAnyOf |
Native Token
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Alias ID | ByteArray[32] | Unique identifier of the alias, which is the BLAKE2b-256 hash of the Output ID that created it. Alias Address = Alias Address Type || Alias ID | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
State Index | uint32 | A counter that must increase by 1 every time the alias is state transitioned. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
State Metadata | (uint16)ByteArray | Metadata that can only be changed by the state controller. A leading uint16 denotes its length. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Foundry Counter | uint32 | A counter that denotes the number of foundries created by this alias account. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Unlock Conditions Count | uint8 | The number of unlock conditions following. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Unlock Conditions atMostOneOfEach |
State Controller Address Unlock Condition
Governor Address Unlock Condition
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Features Count | uint8 | The number of features following. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Features atMostOneOfEach |
Sender FeatureIdentifies the validated sender of the output.
Metadata FeatureDefines metadata (arbitrary binary data) that will be stored in the output.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 FeatureIdentifies the validated issuer of the UTXO state machine.
Metadata FeatureDefines metadata (arbitrary binary data) that will be stored in the output.
|
Additional Transaction Syntactic Validation Rules
Output Syntactic Validation
Amount
field must fulfill the dust protection requirements and must not be0
.Amount
field must be ≤Max IOTA Supply
.Native Tokens Count
must not be greater thanMax Native Tokens Count
.Native Tokens
must be lexicographically sorted based onToken ID
.- Each Native Token must be unique in the set of
Native Tokens
based on itsToken ID
. No duplicates are allowed. Amount
of any Native Token must not be0
.- 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 inFeatures
must define one of the following types:- Sender Feature
- Metadata Feature
- It must hold true that
0
≤Immutable Features Count
≤2
. Feature Type
of a Feature inImmutable 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 inFeatures
andImmutable Features
fields. - Syntactic validation of all present features must pass.
- When
Alias ID
is zeroed out,State Index
andFoundry Counter
must be0
. length(State Metadata)
must not be greater thanMax Metadata Length
.Address
of State Controller Address Unlock Condition andAddress
of Governor Address Unlock Condition must be different from the alias address derived fromAlias ID
.
Additional Transaction Semantic Validation Rules
- Explicit
Alias ID
:Alias ID
is taken as the value of theAlias ID
field in the alias output. - Implicit
Alias ID
: When an alias output is consumed as an input in a transaction andAlias ID
field is zeroed out whileState Index
andFoundry Counter
are zero, take the BLAKE2b-256 hash of theOutput ID
of the input asAlias ID
. - For every non-zero explicit
Alias ID
on the output side there must be a corresponding alias on the input side. The corresponding alias has the explicit or implicitAlias ID
equal to that of the alias on the output side.
Consumed Outputs
Whenever an alias output is consumed in a transaction, it means that the alias is transitioned into its next state. The
current state is defined as the consumed alias output, while the next state is defined as the alias
output with the same explicit AliasID
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:
IOTA Amount
,Native Tokens
,State Index
,State Metadata
,Foundry Counter
andSender Feature
inFeatures
.
Foundry Counter
field must increase by the number of foundry outputs created in the transaction that map toAlias ID
. TheSerial Number
fields of the created foundries must be the set of natural numbers that cover the open-ended interval between the previous and next values of theFoundry Counter
field in the alias output.- The created foundry outputs must be sorted in the list of outputs by their
Serial Number
. Note, that any foundry that maps toAlias ID
and has aSerial Number
that is less or equal to theFoundry Counter
of the input alias is ignored when it comes to sorting. - Newly created foundries in the transaction that map to different aliases can be interleaved when it comes to sorting.
- A state transition is identified by an incremented
- Governance transition:
- A governance transition is identified by an unchanged
State Index
in next state. If there is no alias output on the output side with a corresponding explicitAlias ID
, the alias is being destroyed. The next state is the empty state. - 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
andSender Feature
inFeatures
.
- 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. account balances) about the layer 2 network.
- A governance transition is identified by an unchanged
- When a consumed alias output has Features defined in
Immutable Features
and a corresponding alias output on the output side,Immutable Features
is not allowed to change.
Created Outputs
- When Issuer Feature is present in an output and explicit
Alias ID
is zeroed out, an input withAddress
field that corresponds toIssuer
must be unlocked in the transaction.
Notes
- Governor Address Unlock Condition field is made mandatory for now to help formal verification. When the same entity is defined for state and governance controllers, the output is self governed. Later, for compression reasons, it is possible to make the governance controller optional and define a self-governed alias as one that does not have the governance Governor Address Unlock Condition set.
- Indexers and node plugins shall map the alias address of the output derived with
Alias ID
to the regular address -> output mapping table, so that given an Alias Address, its most recent unspent alias output can be retrieved.
Foundry Output
A foundry output is an output that controls the supply of user defined native tokens. It can mint and melt tokens
according to the policy defined in the Token Scheme
field of the output. Foundries can only be created and
controlled by aliases.
The concatenation of Address
|| Serial Number
|| Token Scheme Type
fields defines the unique identifier of the
foundry, the Foundry ID
.
Upon creation of the foundry, the alias defined in the Address
field of the
Immutable Alias Address Unlock Condition must be unlocked in the same transaction, and its Foundry Counter
field must increment. This incremented value defines Serial Number
, while the Token Scheme
can be chosen freely.
Foundry ID
is not allowed to change after deployment, therefore neither Address
, nor Serial Number
or
Token Scheme
can change during the lifetime of the foundry.
Foundries control the supply of tokens with unique identifiers, so-called Token IDs
. The **Token ID
of tokens
controlled by a specific foundry is the same as the Foundry ID
.
Name | Type | Description | ||||||||||||||||||
Output Type | uint8 | Set to value 5 to denote a Foundry Output. | ||||||||||||||||||
Amount | uint64 | The amount of IOTA coins to held by the output. | ||||||||||||||||||
Native Tokens Count | uint8 | The number of different native tokens held by the output. | ||||||||||||||||||
Native Tokens optAnyOf |
Native Token
|
|||||||||||||||||||
Serial Number | uint32 | The serial number of the foundry with respect to the controlling alias. | ||||||||||||||||||
Token Scheme oneOf |
Simple Token Scheme
|
|||||||||||||||||||
Unlock Conditions Count | uint8 | The number of unlock conditions following. | ||||||||||||||||||
Unlock Conditions atMostOneOfEach |
Immutable Alias Address Unlock Condition
|
|||||||||||||||||||
Features Count | uint8 | The number of features following. | ||||||||||||||||||
Features atMostOneOfEach |
Metadata FeatureDefines metadata (arbitrary binary data) that will be stored in the output.
|
|||||||||||||||||||
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 |
Metadata FeatureDefines metadata (arbitrary binary data) that will be stored in the output.
|
Additional Transaction Syntactic Validation Rules
Output Syntactic Validation
Amount
field must fulfill the dust protection requirements and must not be0
.Amount
field must be ≤Max IOTA Supply
.Native Tokens Count
must not be greater thanMax Native Tokens Count
.Native Tokens
must be lexicographically sorted based onToken ID
.- Each Native Token must be unique in the set of
Native Tokens
based on itsToken ID
. No duplicates are allowed. Amount
of any Native Token must not be0
.- It must hold true that
Unlock Conditions Count
=1
. Unlock Condition Type
of an Unlock Condition must define one of the following types:- Immutable Alias Address Unlock Condition
- Syntactic validation of all present unlock conditions must pass.
- It must hold true that
0
≤Features Count
≤1
. Feature Type
of a Feature inFeatures
must define one of the following types:- Metadata Feature
- It must hold true that
0
≤Immutable Features Count
≤1
. Feature Type
of a Feature inImmutable Features
must define one of the following types:- Metadata Feature
- Syntactic validation of all present features must pass.
Token Scheme
must define one of the following types:- Simple Token Scheme
Simple Token Scheme Syntactic Validation
Token Scheme Type
of a Simple Token Scheme must be0
.Minted Tokens
-Melted Tokens
must not be greater thanMaximum Supply
.Melted Tokens
must not be greater thanMinted Tokens
.Maximum Supply
must be larger than zero.
Additional Transaction Semantic Validation Rules
A foundry is essentially a UTXO state machine. A transaction might either create a new foundry with a unique
Foundry ID
, transition an already existing foundry or destroy it. The current and next states of the state machine
are encoded in inputs and outputs respectively.
- The current state of the foundry with
Foundry ID
X
in a transaction is defined as the consumed foundry output whereFoundry ID
=X
. - The next state of the foundry with
Foundry ID
X
in a transaction is defined as the created foundry output whereFoundry ID
=X
. Foundry Diff
is the pair of the current and next state of the foundry output in the transaction.
A transaction that... | Current State | Next State |
---|---|---|
Creates the foundry | Empty | Output with Foundry ID |
Transitions the foundry | Input with Foundry ID | Output with Foundry ID |
Destroys the foundry | Input with Foundry ID | Empty |
- The foundry output must be unlocked like any other output type where the Address Unlock Condition defines an Alias Address, by transitioning the alias in the very same transaction. See section alias unlocking for more details.
- When the current state of the foundry with
Foundry ID
is empty, it must hold true forSerial Number
in the next state, that:Foundry Counter(InputAlias) < Serial Number <= Foundry Counter(OutputAlias)
- An alias can create several new foundries in one transaction. It was written for the alias output that freshly
created foundry outputs must be sorted in the list of outputs based on their
Serial Number
. No duplicates are allowed. - The two previous rules make sure that each foundry output produced by an alias has a unique
Serial Number
, hence eachFoundry ID
is unique.
- Native tokens present in a transaction are all native tokens present in inputs and outputs of the transaction. Native
tokens of a transaction must be a set based on their
Token ID
. - There must be at most one
Token ID
in the native token set of the transaction that maps to a specificFoundry ID
. - When neither
Current State
norNext State
is empty:- Immutable Alias Address Unlock Condition must not change.
Serial Number
must not change.Token Scheme Type
must not change.- Features in
Immutable Features
must not change.
- Token Scheme Semantic Validation Rules must be fulfilled.
Token Scheme Semantic Validation Rules
Token Scheme Validation
takes Token Diff
and Foundry Diff
and validates if the scheme constraints are respected.
Simple Token Scheme Validation Rules
- Let
Token Diff
denote the difference between native token balances of the input and the output side of the transaction of the singleToken ID
that maps to theFoundry ID
. Minting results in excess of tokens on the output side (positive diff), melting results in excess on the input side (negative diff). Now, the following conditions must hold forToken Diff
:- When
Token Diff
> 0
Current State(Minted Tokens) + Token Diff = Next State(Minted Tokens)
.Current State(Melted Tokens) = Next State(Melted Tokens)
- When
Token Diff
< 0, it must hold true that:
Current State(Melted Tokens) <= Next State(Melted Tokens)
[Next State(Melted Tokens) - Current State(Melted Tokens)] <= |Token Diff|
.- When
Current State(Melted Tokens) != Next State(Melted Tokens)
, it must be true thatCurrent State(Minted Tokens) = Next State(Minted Tokens)
- When
Current State
is empty,Current State(Minted Tokens) = 0
andCurrent State(Melted Tokens) = 0
. - When
Next State
is empty, condition1
and2
are ignored. It must hold true, thatCurrent State(Minted Tokens) + Token Diff = Current State(Melted Tokens)
- When
- When neither
Current State
norNext State
is empty:Maximum Supply
field must not change.
Notes
- A token scheme is a list of hard coded constraints. It is not feasible at the moment to foresee the future
needs/requirements of hard coded constraints, so it is impossible to design token schemes as any possible combination
of those constraints. A better design would be to have a list of possible constraints (and their related fields) from
which the user can choose. The chosen combination should still be encoded as a bitmask inside the
Token ID
. - Additional token schemes will be defined that make use of the
Foundry Diff
as well, for example validating that a certain amount of tokens can only be minted/melted after a certain date. - For now, only token scheme
0
is supported. Additional token schemes will be designed iteratively when the need arises. - The
Foundry ID
of a foundry output should be queryable in indexers, so that given aFoundry ID
, theOutput ID
of the foundry output can be retrieved.Foundry ID
behaves like an address that can't unlock anything. While it is not necessarily needed for the protocol, it is needed for client side operations, such as:- Retrieving the current state of the foundry.
- Accessing token metadata in foundry based on
Foundry ID
/Tokend ID
.
NFT Output
Non-fungible tokens in the ledger are implemented with a special output type, the so-called NFTOutput.
Each NFT output gets assigned a unique identifier NFT ID
upon creation by the protocol. NFT ID
is BLAKE2b-256 hash
of the Output ID that created the NFT. The address of the NFT is the concatenation of NFT Address Type
||
NFT ID
.
The NFT may contain immutable metadata set upon creation, and a verified Issuer
. The output type supports all
non-alias specific (state controller, governor) unlock conditions and optional features so that the output can be
sent as a request to smart contract chain accounts.
Name | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Output Type | uint8 | Set to value 6 to denote a NFT Output. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Amount | uint64 | The amount of IOTA coins held by the output. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Native Tokens Count | uint8 | The number of native tokens held by the output. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Native Tokens optAnyOf |
Native Token
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
NFT ID | ByteArray[32] | Unique identifier of the NFT, which is the BLAKE2b-256 hash of the Output ID that created it. NFT Address = NFT Address Type || NFT ID | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Unlock Conditions Count | uint8 | The number of unlock conditions following. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Unlock Conditions atMostOneOfEach |
Address Unlock Condition
Storage Deposit Return Unlock ConditionDefines the amount of IOTAs used as storage deposit that have to be returned to Return Address.
Timelock Unlock ConditionDefines a unix timestamp until which the output can not be unlocked.
Expiration Unlock ConditionDefines a unix time until which only Address, defined in Address Unlock Condition, is allowed to unlock the output. After the unix time is reached or passed, only Return Address can unlock it.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Features Count | uint8 | The number of features following. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Features atMostOneOfEach |
Sender FeatureIdentifies the validated sender of the output.
Metadata FeatureDefines metadata (arbitrary binary data) that will be stored in the output.
Tag FeatureDefines an indexation tag to which the output can be indexed by additional node plugins.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 FeatureIdentifies the validated issuer of the UTXO state machine.
Metadata FeatureDefines metadata (arbitrary binary data) that will be stored in the output.
|
Additional Transaction Syntactic Validation Rules
Output Syntactic Validation
Amount
field must fulfill the dust protection requirements and must not be0
.Amount
field must be ≤Max IOTA Supply
.Native Tokens Count
must not be greater thanMax Native Tokens Count
.Native Tokens
must be lexicographically sorted based onToken ID
.- Each Native Token must be unique in the set of
Native Tokens
based on itsToken ID
. No duplicates are allowed. Amount
of any Native Token must not be0
.- It must hold true that
1
≤Unlock Conditions Count
≤4
. Unlock Condition Type
of an Unlock Condition must define one of the following types:- Address Unlock Condition
- Storage Deposit Return Unlock Condition
- Timelock Unlock Condition
- Expiration 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.
- Address Unlock Condition must be present.
- It must hold true that
0
≤Features Count
≤3
. Feature Type
of a Feature inFeatures
must define one of the following types:- Sender Feature
- Metadata Feature
- Tag Feature
- It must hold true that
0
≤Immutable Features Count
≤2
. Feature Type
of a Feature inImmutable Features
must define one of the following types:- Issuer Feature
- Metadata Feature
- Features must be sorted in ascending order based on their
Feature Type
both inFeatures
andImmutable Features
fields. - Syntactic validation of all present features must pass.
Address
field of the Address Unlock Condition must not be the same as the NFT address derived fromNFT ID
.
Additional Transaction Semantic Validation Rules
- Explicit
NFT ID
:NFT ID
is taken as the value of theNFT ID
field in the NFT output. - Implicit
NFT ID
: When an NFT output is consumed as an input in a transaction andNFT ID
field is zeroed out, take the BLAKE2b-256 hash of theOutput ID
of the input asNFT ID
. - For every non-zero explicit
NFT ID
on the output side there must be a corresponding NFT on the input side. The corresponding NFT has the explicit or implicitNFT ID
equal to that of the NFT on the output side.
Consumed Outputs
- The unlock of the input corresponds to
Address
field of the Address Unlock Condition and the unlock is valid. - The unlock is valid if and only if all unlock conditions and features present in the output validate.
- When a consumed NFT output has a corresponding NFT output on the output side,
Immutable Features
field must not change. - When a consumed NFT output has no corresponding NFT output on the output side, the NFT it is being burned. Funds and assets inside the burned NFT output must be redistributed to other outputs in the burning transaction.
:bangbang: Careful with NFT burning :bangbang: |
---|
Other outputs in the ledger that are locked to the address of the NFT can only be unlocked by including the NFT itself in the transaction. If the NFT is burned, such funds are locked forever. It is strongly advised to always check and sweep what the NFT owns in the ledger before burning it.
Created Outputs
- When
Issuer Feature
is present in an output and explicitNFT ID
is zeroed out, an input withAddress
field that corresponds toIssuer
must be unlocked in the transaction. IfAddress
is either Alias Address or NFT Address, their corresponding outputs (defined byAlias ID
andNFT ID
) must be unlocked in the transaction. - All Unlock Condition imposed transaction validation criteria must be fulfilled.
- All Feature imposed transaction validation criteria must be fulfilled.
Notes
- It would be possible to have two-step issuer verification: First NFT is minted, and then metadata can be immutably
locked into the output. The metadata contains an issuer public key plus a signature of the unique
NFT ID
. This way a smart contract chain can mint on behalf of the user, and then push the issuer signature in a next step.
Unlocking Chain Script Locked Outputs
Two of the introduced output types (Alias, NFT) implement the so-called UTXO chain
constraint. These outputs receive their unique identifiers upon creation, generated by the protocol, and carry it
forward with them through transactions until they are destroyed. These unique identifiers (Alias ID
, NFT ID
) also
function as global addresses for the state machines, but unlike Ed25519 Addresses, they are not backed by private
keys that could be used for signing. The rightful owners who can unlock these addresses are defined in the outputs
themselves.
Since such addresses are accounts in the ledger, it is possible to send funds to these addresses. The unlock mechanism of such funds is designed in a way that proving ownership of the address is reduced to the ability to unlock the corresponding output that defines the address.
Alias Locking & Unlocking
A transaction may consume a (non-alias) output that belongs to an Alias Address by state transitioning the alias output with the matching Alias 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, alias unlocking is done using a new unlock type, called Alias Unlock.
Alias Unlock
Points to the unlock of a consumed alias output.
Name | Type | Description |
Unlock Type | uint8 | Set to value 2 to denote a Alias Unlock. |
Alias Reference Unlock Index | uint16 | Index of input and unlock corresponding to an alias output. |
This unlock is similar to the Reference Unlock. However, it is valid if and only if the input of the
transaction at index Alias Reference Unlock Index
is an alias output with the same Alias ID
as the one derived from
the Address
field of the to-be unlocked output.
Additionally, the Alias Unlocks must also be ordered to prevent circular dependencies:
If the i-th Unlock of a transaction is an Alias Unlock and has Alias Reference Unlock Index
set to k,
it must hold that i > k. Hence, an Alias Unlock can only reference an Unlock (unlocking the
corresponding alias) at a smaller index.
For example the scenario where Alias A
is locked to the address of Alias B
while Alias B
is in locked to the
address of Alias A
introduces a circular dependency and is not well-defined. By requiring the Unlocks to be
ordered as described above, a transaction consuming Alias A
as well as Alias B
can never be valid as there would
always need to be one Alias Unlock referencing a greater index.
Alias Unlock Syntactic Validation
- It must hold that 0 ≤
Alias Reference Unlock Index
<Max Inputs Count
.
Alias Unlock Semantic Validation
- The address of the unlocking condition of the input being unlocked must be an Alias Address.
- The index
i
of the Alias Unlock is the index of the input in the transaction that it unlocks.Alias Reference Unlock Index
must be <i
. Alias Reference Unlock Index
defines a previous input of the transaction and its unlock. This input must be an Alias Output withAlias ID
that refers to the Alias Address being unlocked.- The referenced Alias Output must be unlocked for state transition.
NFT Locking & Unlocking
NFT ID
field is functionally equivalent to Alias ID
of an alias output. It is generated the same way, but it can
only exist in NFT outputs. Following the same analogy as for alias addresses, NFT addresses are iota addresses that are
controlled by whoever owns the NFT output itself.
Outputs that are locked under NFT Address
can be unlocked by unlocking the NFT output in the same transaction that
defines NFT Address
, that is, the NFT output where NFT Address Type Byte || NFT ID = NFT Address
.
An NFT Unlock looks and behaves like an Alias Unlock, but the referenced input at the index must
be an NFT output with the matching NFT ID
.
NFT Unlock
Points to the unlock of a consumed NFT output.
Name | Type | Description |
Unlock Type | uint8 | Set to value 3 to denote a NFT Unlock. |
NFT Reference Unlock Index | uint16 | Index of input and unlock corresponding to an NFT output. |
An NFT Unlock is only valid if the input in the transaction at index NFT Reference Unlock Index
is the NFT
output with the same NFT ID
as the one derived from the Address
field of the to-be unlocked output.
If the i-th Unlock of a transaction is an NFT Unlock and has NFT Reference Unlock Index
set to k, it
must hold that i > k. Hence, an NFT Unlock can only reference an Unlock at a smaller index.
NFT Unlock Syntactic Validation
- It must hold that 0 ≤
NFT Reference Unlock Index
<Max Inputs Count
.
NFT Unlock Semantic Validation
- The address of the input being unlocked must be an NFT Address.
- The index
i
of the NFT Unlock is the index of the input in the transaction that it unlocks.NFT Reference Unlock Index
must be <i
. NFT Reference Unlock Index
defines a previous input of the transaction and its unlock. This input must be an NFT Output withNFT ID
that refers to the NFT Address being unlocked.
Drawbacks
- New output types increase transaction validation complexity, however it is still bounded.
- Outputs take up more space in the ledger, UTXO database size might increase.
- It is possible to intentionally deadlock aliases and NFTs, however client side software can notify users when they perform such action. Deadlocked aliases and NFTs can not be unlocked, but this is true for any funds locked into unspendable addresses.
- Time based output locking conditions can only be evaluated after attachment to the Tangle, during milestone confirmation.
- IOTA ledger can only support hard-coded scripts. Users can not write their own scripts because there is no way currently to charge them based on resource usage, all IOTA transactions are feeless by nature.
- Aliases can be destroyed even if there are foundries alive that they control. Since only the controlling alias can unlock the foundry, such foundries and the supply of the tokens remain forever locked in the Tangle.
- Token schemes and needed supply control rules are unclear.
Rationale and alternatives
The feeless nature of IOTA makes it inherently impossible to implement smart contracts on layer 1. A smart contract platform shall not only be capable of executing smart contracts, but also to limit their resource usage and make users pay validators for the used resources. IOTA has no concept of validators, neither fees. While it would technically be possible to run EUTXO smart contracts on the layer 1 Tangle, it is not possible to properly charge users for executing them.
The current design aims to combine the best of both worlds: Scalable and feeless layer 1 and Turing-complete smart contracts on layer 2. Layer 1 remains scalable because of parallel transaction validation, feeless because the bounded hard-coded script execution time, and layer 2 can offer support for all kinds of virtual machines, smart contracts and advanced tokenization use cases.
Unresolved questions
- List of supported Token Schemes is not complete.
- Deflationary token scheme
- Inflationary token scheme with scheduled minting
- etc.
- Adapt the current congestion control, i.e. Block PoW, to better match the validation complexity of the different outputs and types.
Copyright
Copyright and related rights waived via CC0.