tip: 19
title: Dust Protection Based on Byte Costs (Storage Deposit)
description: Prevent bloating the ledger size with dust outputs
author: Max Hase (@muXxer)
discussions-to: https://github.com/iotaledger/tips/pull/39
status: Active
type: Standards
layer: Core
created: 2021-11-04
requires: TIP-18, TIP-20, TIP-21 and TIP-22
replaces: TIP-15
The current dust protection
in chrysalis-pt2
is only an intermediate solution to prevent attacks or misbehavior that could bloat the ledger database. The design has several drawbacks, e.g. it does not scale, relies on a total ordering of the tangle and it is rather complicated to use from a user point of view.
This document describes a new dust protection
concept, called storage deposit
, which solves the mentioned drawbacks and creates a monetary incentive to keep the ledger state small. It focuses on the underlying problem, the increase in database size, instead of artificially limiting the number of UTXOs. This is achieved by enforcing a minimum IOTA coin deposit in every output based on the actually used disc space of the output itself.
In a distributed ledger network, every participant, a so-called node, needs to keep track of the current ledger state. Since chrysalis-pt2
, the IOTA ledger state is based on the UTXO model, where every node keeps track of all the currently unspent outputs. Without dust protection
, even outputs containing only one single IOTA coin are valid and therefore stored in the database.
Misusage by honest users or intentionally bad behavior by malicious actors can lead to growing database and snapshot sizes and increasing computational costs (database lookups, balance calculations). Due to these increasing hardware requirements, the entry barrier to participate in the network becomes unaffordable and less nodes would operate the network.
Especially in a fee-less system like IOTA, this is a serious issue, since an attacker can create a lot of damage with low effort. Other DLTs do not yet face this problem, as such an attack would be much more expensive due to the high transaction fees.
However, in order to solve scalability issues more and more transactions need to be handled. Therefore, other DLT projects will also eventually run into the same dust limitations. This document proposes to introduce storage deposit
to address this.
- The maximum possible ledger database size must be limited to a reasonable and manageable size.
- The
dust protection
must not depend on a global shared state of the ledger, so that transaction validation can happen in parallel.
- The
dust protection
should work for outputs with arbitrary data and size.
- The ledger database size should be fairly allocated to users based on the scarce resource, IOTA coins.
The current dust protection
solution in chrysalis-pt2
does not satisfy the mentioned requirements for the following reasons:
- The enforced maximum limit of disc space is ~6.5 TB.
- The dust allowance mechanism depends on the total amount of funds in
DustAllowanceOutput
per address, which is a global shared state.
- It is designed for one fixed output size.
Therefore, a new transaction validation rule is introduced which replaces the former dust protection
solution completely.
Blocks including payloads, even transaction payloads, are considered to be pruned by the nodes, but unspent transaction outputs must be kept until they are spent. Therefore the dust protection
is based on the unspent outputs only.
Every output created by a transaction needs to have at least a minimum amount of IOTA coins deposited in the output itself, otherwise the output is syntactically invalid.
min_deposit_of_output = βv_byte_cost Β· v_byteβ
v_byte = β(weightπ Β· byte_sizeπ) + offset
where:
- v_byte_cost: costs in IOTA coins per virtual byte
- weightπ: factor of field π that takes computational and storage costs into account
- byte_sizeπ: size of field π in bytes
- offset: additional v_bytes that are caused by additional data that has to be stored in the database but is not part of the output itself
:warning: min_deposit_of_output is rounded down |
Starting with the tokenization and smart contracts mainnet upgrade, new output types are introduced by TIP-18 that contain mandatory and optional fields with variable length. Each of these fields result in different computational and storage costs, which will be considered by the positive weight_i
. The size of the field itself is expressed with byte_size_i
. offset
is used to take the overhead of the specific output itself into account.
The v_byte_cost
is a protocol value, which has to be defined based on reasonable calculations and estimates.
In simple words, the more data you write to the global ledger database, the more IOTA you need to deposit in the output.
This is not a fee, because the deposited coins can be reclaimed by consuming the output in a new transaction.
The proposed solution has several advantages over the former solution.
First of all, the database size is limited to an absolute maximum size. Since the total supply of IOTA coins stays constant, also the maximum amount of v_bytes
that can ever be written to the database remains constant.
Total ordering of the tangle is not necessary because there is no shared global ledger state for transaction validation anymore. The node can determine if the transaction is valid and the dust protection rules are fulfilled, just by looking at the transaction itself. Therefore this solution is also suitable for IOTA 2.0.
By introducing a certain cost for every byte stored in the ledger, it is possible to store arbitrary data in the outputs, as long as enough IOTA coins are deposited in the output itself to keep the information retained. This enables permanent storage of data in a distributed and decentralized way, without the need of a permanode.
Users have an economic incentive to clean up the database. By consuming old unused outputs, users can reclaim their deposited IOTA coins.
This solution prevents seamless microtransactions, which are a unique selling point for IOTA, because the issuer of the transaction always needs to deposit min_deposit_of_output
IOTA coins in the output created by the transaction. This minimum deposit will have a higher value than the microtransaction itself, which basically makes microtransactions impossible. Two different solutions to circumvent this obstacle are introduced here.
The dust protection
only affects "value-transactions". Since blocks containing other payloads are not stored in the ledger state and are subject to pruning, they cannot cause permanent "dust" and do not need to be considered for dust protection
.
However, all output types like e.g. smart contract requests are affected and must comply with the min_deposit_of_output
criteria. Therefore, these requests could get quite expensive for the user, but the same mechanism introduced for Microtransactions on Layer 1 can be utilized for smart contract requests as well.
To limit the maximum database size, the total IOTA supply needs to be divided by the target database size in bytes to get the worst case scenario regarding the byte costs.
However, in this scenario no outputs hold more IOTA coins than required for the dust protection
. This does not represent the real distribution of funds over the UTXOs. We could assume that these output amounts follow Zipf's law. Unfortunately, fitting a Zipf distribution to the current ledger state will not match the future distribution of the funds for several reasons:
- There is already another
dust protection
in place, which distorts the distribution.
- With new use cases enabled by the new
dust protection
(e.g. tokenization, storing arbitrary data in the ledger), the distribution will dramatically change.
- Fittings for other DLT projects do not match because there are transaction fees in place, which decrease the amount of dust outputs in the distribution.
Another possibility would be to estimate how much percentage of the database will be used for outputs with minimum required deposit (fund sparsitiy percentage
) in the future. The remaining IOTA coins can be ignored in that case to simplify the calculation. Since a fund sparsity percentage of less than 20% would already be bad for other upcoming protocol features like the mana calculation, we could take this value for our calculation instead of the worst case.
The different output types mentioned in the Output Types TIP-18 contain several mandatory and optional fields. Every field itself creates individual computational and storage requirements for the node, which is considered by having different weights for every field.
The following table describes different field types in an output:
Name |
Description |
Weight |
Reasoning |
key |
Creates a key lookup in the database. |
10.0 |
Keys need to be stored in the LSM tree of the key-value database engine and need to be merged and leveled, which is computational-, memory- and read/write IO-wise a heavy task. |
data |
Plain binary data on disk. |
1.0 |
Data is stored as the value in the key-value database, and therefore only consumes disc space. |
:warning: Protocol parameters are not set yet |
Protocol parameters presented in this document are design parameters that will change in the future based on simulation results, benchmarking and security assumptions. The reader should not take these values as definitive.
An example of such parameter for example is the weight
assigned to different output field types.
The following tables show the different outputs including the possible fields and their specific weight.
Basic Output
Describes a basic output with optional features.
Offset |
Field |
Field type |
Length Minimum |
Length Maximum |
Description |
OutputID |
key |
34 |
34 |
The ID of the output. |
Block ID (included) |
data |
32 |
32 |
The ID of the block in which the transaction payload that created this output was included. |
Confirmation Milestone Index |
data |
4 |
4 |
The index of the milestone which confirmed the transaction that created the output. |
Confirmation Unix Timestamp |
data |
4 |
4 |
The unix timestamp of the milestone which confirmed the transaction that created the output. |
|
Fields |
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Output Type |
data |
1 |
1 |
Set to value 3 to denote an Basic Output.
|
Amount |
data |
8 |
8 |
The amount of IOTA coins held by the output. |
Native Tokens Count |
data |
1 |
1 |
The number of native tokens held by the output. |
Native Tokens optAnyOf |
Native Token
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Token ID |
data |
38 |
38 |
Identifier of the native token.
|
Amount |
data |
32 |
32 |
Amount of native tokens of the given Token ID.
|
|
Unlock Conditions Count |
data |
1 |
1 |
The number of unlock conditions following. |
Unlock Conditions atMostOneOfEach |
Address Unlock Condition
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 0 to denote an Address Unlock Condition.
|
Address |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Storage Deposit Return Unlock Condition
Defines the amount of IOTAs used as storage deposit that have to be returned to Return Address.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 1 to denote a Storage Deposit Return Unlock Condition.
|
Return Address oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Return Amount |
data |
8 |
8 |
Amount of IOTA coins the consuming transaction should deposit to the address defined in Return Address.
|
Timelock Unlock Condition
Defines a unix timestamp until which the output can not be unlocked.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 2 to denote a Timelock Unlock Condition.
|
Unix Time |
data |
4 |
4 |
Unix time (seconds since Unix epoch) starting from which the output can be consumed.
|
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 |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 3 to denote a Expiration Unlock Condition.
|
Return Address oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Unix Time |
data |
4 |
4 |
Before this unix time, Address Unlock Condition is allowed to unlock the output, after that only the address defined in Return Address.
|
|
Features Count |
data |
1 |
1 |
The number of features following. |
Features atMostOneOfEach |
Sender Feature
Identifies the validated sender of the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 0 to denote a Sender Feature.
|
Sender oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Metadata Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 2 to denote a Metadata Feature.
|
Data Length |
data |
2 |
2 |
Length of the following data field in bytes.
|
Data |
data |
1 |
8192 |
Binary data. |
Tag Feature
Defines an indexation tag to which the output can be indexed by additional node plugins.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 3 to denote a Tag Feature.
|
Tag Length |
data |
1 |
1 |
Length of the following tag field in bytes.
|
Tag |
data |
1 |
255 |
Binary indexation data. |
|
|
v_byte Minimum |
426 |
v_byte Maximum |
13477 |
Alias Output
Describes an alias account in the ledger that can be controlled by the state and governance controllers.
Offset |
Field |
Field type |
Length Minimum |
Length Maximum |
Description |
OutputID |
key |
34 |
34 |
The ID of the output. |
Block ID (included) |
data |
32 |
32 |
The ID of the block in which the transaction payload that created this output was included. |
Confirmation Milestone Index |
data |
4 |
4 |
The index of the milestone which confirmed the transaction that created the output. |
Confirmation Unix Timestamp |
data |
4 |
4 |
The unix timestamp of the milestone which confirmed the transaction that created the output. |
|
Fields |
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Output Type |
data |
1 |
1 |
Set to value 4 to denote a Alias Output.
|
Amount |
data |
8 |
8 |
The amount of IOTA coins held by the output. |
Native Tokens Count |
data |
1 |
1 |
The number of native tokens held by the output. |
Native Tokens optAnyOf |
Native Token
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Token ID |
data |
38 |
38 |
Identifier of the native token.
|
Amount |
data |
32 |
32 |
Amount of native tokens of the given Token ID.
|
|
Alias ID |
data |
32 |
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 |
data |
4 |
4 |
A counter that must increase by 1 every time the alias is state transitioned. |
State Metadata Length |
data |
2 |
2 |
Length of the following State Metadata field. |
State Metadata |
data |
0 |
8192 |
Metadata that can only be changed by the state controller. |
Foundry Counter |
data |
4 |
4 |
A counter that denotes the number of foundries created by this alias account. |
Unlock Conditions Count |
data |
1 |
1 |
The number of unlock conditions following. |
Unlock Conditions atMostOneOfEach |
State Controller Address Unlock Condition
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 4 to denote an State Controller Address Unlock Condition.
|
Address |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Governor Address Unlock Condition
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 5 to denote an Governor Address Unlock Condition.
|
Address |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
|
Features Count |
data |
1 |
1 |
The number of features following. |
Features atMostOneOfEach |
Sender Feature
Identifies the validated sender of the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 0 to denote a Sender Feature.
|
Sender oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Metadata Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 2 to denote a Metadata Feature.
|
Data Length |
data |
2 |
2 |
Length of the following data field in bytes.
|
Data |
data |
1 |
8192 |
Binary data. |
|
Immutable Features Count |
data |
1 |
1 |
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.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 1 to denote an Issuer Feature.
|
Issuer oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Metadata Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 2 to denote a Metadata Feature.
|
Data Length |
data |
2 |
2 |
Length of the following data field in bytes.
|
Data |
data |
1 |
8192 |
Binary data. |
|
|
v_byte Minimum |
469 |
v_byte Maximum |
29633 |
Foundry Output
Describes a foundry output that is controlled by an alias.
Offset |
Field |
Field type |
Length Minimum |
Length Maximum |
Description |
OutputID |
key |
34 |
34 |
The ID of the output. |
Block ID (included) |
data |
32 |
32 |
The ID of the block in which the transaction payload that created this output was included. |
Confirmation Milestone Index |
data |
4 |
4 |
The index of the milestone which confirmed the transaction that created the output. |
Confirmation Unix Timestamp |
data |
4 |
4 |
The unix timestamp of the milestone which confirmed the transaction that created the output. |
|
Fields |
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Output Type |
data |
1 |
1 |
Set to value 5 to denote a Foundry Output.
|
Amount |
data |
8 |
8 |
The amount of IOTA coins held by the output. |
Native Tokens Count |
data |
1 |
1 |
The number of different native tokens held by the output. |
Native Tokens optAnyOf |
Native Token
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Token ID |
data |
38 |
38 |
Identifier of the native token.
|
Amount |
data |
32 |
32 |
Amount of native tokens of the given Token ID.
|
|
Serial Number |
data |
4 |
4 |
The serial number of the foundry with respect to the controlling alias. |
Token Scheme oneOf |
Simple Token Scheme
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Token Scheme Type |
data |
1 |
1 |
Set to value 0 to denote an Simple Token Scheme.
|
Minted Tokens |
data |
32 |
32 |
Amount of tokens minted by this foundry. |
Melted Tokens |
data |
32 |
32 |
Amount of tokens melted by this foundry. |
Maximum Supply |
data |
32 |
32 |
Maximum supply of tokens controlled by this foundry. |
|
Unlock Conditions Count |
data |
1 |
1 |
The number of unlock conditions following. |
Unlock Conditions atMostOneOfEach |
Immutable Alias Address Unlock Condition
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 6 to denote an Immutable Alias Address Unlock Condition.
|
Address |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
|
Features Count |
data |
1 |
1 |
The number of features following. |
Features atMostOneOfEach |
Metadata Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 2 to denote a Metadata Feature.
|
Data Length |
data |
2 |
2 |
Length of the following data field in bytes.
|
Data |
data |
1 |
8192 |
Binary data. |
|
Immutable Features Count |
data |
1 |
1 |
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 Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 2 to denote a Metadata Feature.
|
Data Length |
data |
2 |
2 |
Length of the following data field in bytes.
|
Data |
data |
1 |
8192 |
Binary data. |
|
|
v_byte Minimum |
528 |
v_byte Maximum |
21398 |
NFT Output
Describes an NFT output, a globally unique token with metadata attached.
Offset |
Field |
Field type |
Length Minimum |
Length Maximum |
Description |
OutputID |
key |
34 |
34 |
The ID of the output. |
Block ID (included) |
data |
32 |
32 |
The ID of the block in which the transaction payload that created this output was included. |
Confirmation Milestone Index |
data |
4 |
4 |
The index of the milestone which confirmed the transaction that created the output. |
Confirmation Unix Timestamp |
data |
4 |
4 |
The unix timestamp of the milestone which confirmed the transaction that created the output. |
|
Fields |
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Output Type |
data |
1 |
1 |
Set to value 6 to denote a NFT Output.
|
Amount |
data |
8 |
8 |
The amount of IOTA coins held by the output. |
Native Tokens Count |
data |
1 |
1 |
The number of native tokens held by the output. |
Native Tokens optAnyOf |
Native Token
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Token ID |
data |
38 |
38 |
Identifier of the native token.
|
Amount |
data |
32 |
32 |
Amount of native tokens of the given Token ID.
|
|
NFT ID |
data |
32 |
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 |
data |
1 |
1 |
The number of unlock conditions following. |
Unlock Conditions atMostOneOfEach |
Address Unlock Condition
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 0 to denote an Address Unlock Condition.
|
Address |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Storage Deposit Return Unlock Condition
Defines the amount of IOTAs used as storage deposit that have to be returned to Return Address.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 1 to denote a Storage Deposit Return Unlock Condition.
|
Return Address oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Return Amount |
data |
8 |
8 |
Amount of IOTA coins the consuming transaction should deposit to the address defined in Return Address.
|
Timelock Unlock Condition
Defines a unix timestamp until which the output can not be unlocked.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 2 to denote a Timelock Unlock Condition.
|
Unix Time |
data |
4 |
4 |
Unix time (seconds since Unix epoch) starting from which the output can be consumed.
|
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 |
Field type |
Length Minimum |
Length Maximum |
Description |
Unlock Condition Type |
data |
1 |
1 |
Set to value 3 to denote a Expiration Unlock Condition.
|
Return Address oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Unix Time |
data |
4 |
4 |
Before this unix time, Address Unlock Condition is allowed to unlock the output, after that only the address defined in Return Address.
|
|
Features Count |
data |
1 |
1 |
The number of features following. |
Features atMostOneOfEach |
Sender Feature
Identifies the validated sender of the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 0 to denote a Sender Feature.
|
Sender oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Metadata Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 2 to denote a Metadata Feature.
|
Data Length |
data |
2 |
2 |
Length of the following data field in bytes.
|
Data |
data |
1 |
8192 |
Binary data. |
Tag Feature
Defines an indexation tag to which the output can be indexed by additional node plugins.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 3 to denote a Tag Feature.
|
Tag Length |
data |
1 |
1 |
Length of the following tag field in bytes.
|
Tag |
data |
1 |
255 |
Binary indexation data. |
|
Immutable Features Count |
data |
1 |
1 |
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.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 1 to denote an Issuer Feature.
|
Issuer oneOf |
Ed25519 Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 0 to denote an Ed25519 Address.
|
PubKeyHash |
data |
32 |
32 |
The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. |
Alias Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 8 to denote an Alias Address.
|
Alias ID |
data |
32 |
32 |
The raw bytes of the Alias ID which is the BLAKE2b-256 hash of the outputID that created it. |
NFT Address
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Address Type |
data |
1 |
1 |
Set to value 16 to denote an NFT Address.
|
NFT ID |
data |
32 |
32 |
The raw bytes of the NFT ID which is the BLAKE2b-256 hash of the outputID that created it. |
|
Metadata Feature
Defines metadata (arbitrary binary data) that will be stored in the output.
Name |
Field type |
Length Minimum |
Length Maximum |
Description |
Feature Type |
data |
1 |
1 |
Set to value 2 to denote a Metadata Feature.
|
Data Length |
data |
2 |
2 |
Length of the following data field in bytes.
|
Data |
data |
1 |
8192 |
Binary data. |
|
|
v_byte Minimum |
459 |
v_byte Maximum |
21739 |
To enable microtransactions on Layer 1 and still satisfy the min_deposit_of_output
requirement, a new mechanism called conditional sending
is introduced with the new Output Types TIP-18.
The preceding picture shows the process of the conditional sending
mechanism. Alice uses the Basic Output
to send a microtransaction of 1 IOTA to Bob's Address
. To fulfill the min_deposit_of_output
requirement, the Amount
is increased by min_deposit_of_output
IOTA, which is 1 MIOTA in the above example. To prevent Bob from accessing these additional funds called the storage deposit
, Alice adds the optional Storage Deposit Return Unlock Condition
to the Basic Output
. Now Bob can only consume the newly created output, if the unlocking transaction deposits the specified Return Amount
IOTA coins, in this case 1 MIOTA, to the Return Address
value defined by Alice. By consuming another UTXO and adding its amount to the received 1 IOTA, Bob takes care to create a valid output according to the dust protection rules.
To prevent Bob from blocking access to the storage deposit
forever, Alice specifies the additional Expiration Unlock Condition
in the Basic Output
. If Bob does not consume the output before the time window defined by Alice expires, Alice regains total control over the output.
This means that there is no risk for Alice to lose the storage deposit
, because either Bob needs to return the specified Return Amount
, or the ownership of the created output switches back to Alice after the specified time-window has expired.
This mechanism can also be used to transfer native tokens or on-chain requests to ISCP chains without losing control over the required storage deposit
.
Another solution is to outsource microtransactions to Layer 2 applications like smart contracts. In Layer 2 there are no restrictions regarding the minimum balance of an output.
In this example, Alice sends funds to a smart contract chain on Layer 1 with an output that covers at least min_deposit_of_output
. From this point on, Alice can send any number of off-chain requests to the smart contract chain, causing the smart contract to send microtransactions from Alice' on-chain account to Bob's on-chain account. Bob can now request his on-chain account balances to be withdrawn to his Layer 1 address. The last step can also be combined with the formerly introduced conditional sending
mechanism, in case Bob wants to withdraw less than min_deposit_of_output
IOTA coins or native assets.
:information_source: Potential additional mechanisms for microtransactions are currently being discussed. |
All SigLockedSingleOutput
below 1 MIOTA and SigLockedDustAllowanceOutput
of an address could be collected and migrated to a single new BasicOutput
with the smallest Output ID
(byte-wise) of all these collected outputs as the new identifier.
This could probably be done in the form of a global snapshot and would represent a hard-fork.
Another solution is to convert all SigLockedDustAllowanceOutput
into BasicOutputs
and leave the SigLockedSingleOutput
below 1 MIOTA untouched.
Copyright and related rights waived via CC0.