diff --git a/tips/TIP-0041/tip-0041.md b/tips/TIP-0041/tip-0041.md new file mode 100644 index 000000000..8648a9cf8 --- /dev/null +++ b/tips/TIP-0041/tip-0041.md @@ -0,0 +1,575 @@ +--- +tip: 41 +title: Basic Output Type +description: Support for IOTA and native token transfers, Layer 2 smart contract requests and storing Mana +author: + Philipp Gackstatter (@PhilippGackstatter) , Levente Pap (@lzpap) , + Roman Overko (@roman1e2f5p8s) +discussions-to: TODO +status: Draft +type: Standards +layer: Core +created: 2023-05-03 +requires: TIP-21, TIP-22, TIP-45 and TIP-47 +replaces: TIP-18 +--- + +# Summary + +This document defines the Basic Output type and transaction validation rules for the IOTA protocol to support storage of +IOTA coins, native tokens and Mana as well as layer 2 smart contract requests, among other functionality. It was +originally introduced in [TIP-18](../TIP-0018/tip-0018.md) and the functionality defined in this document is an +extension of the Basic output of TIP-18. + +## Summary of changes compared to TIP-18 + +- Add `Mana` field. +- Remove `Native Tokens` field and add `Native Token Feature` to the allowed features. See + [TIP-38 (Native Token Migration)](../TIP-0038/tip-0038.md#native-token-migration) for migration details. + +# Motivation + +This TIP defines an output type for the support of basic ledger functionality. Such outputs can store IOTA coins, native +tokens and Mana. All unlock conditions and features defined in [TIP-38](../TIP-0038/tip-0038.md) are supported and can +be composed to create spending restrictions, attach metadata or enable indexed data storage in the UTXO ledger. Layer 2 +smart contract requests are enabled by posting requests through the Tangle. Such requests can be crafted by including +commands in the metadata of Basic outputs. This output thus supports both the native tokenization on layer 1 as well as +layer 2 smart contracts. + +# Building Blocks + +## Data Types & Subschema Notation + +Data types and subschemas used throughout this TIP are defined in [TIP-21](../TIP-0021/tip-0021.md). + +## Protocol Parameters + +Protocol parameters used throughout this TIP are defined in [TIP-49](../TIP-0049/tip-0049.md). + +## Transaction Payload + +[TIP-45](../TIP-0045/tip-0045.md) is the basis for output validation in this TIP. + +# Basic Output + +A Basic Output can have several unlock conditions and optional features, including the ability to hold Native +Tokens. 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. + +
+ Basic Output +
Describes a basic output with optional features.
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Output Typeuint8Set to value 0 to denote a Basic Output.
Amountuint64The amount of IOTA coins held by the output.
Manauint64The amount of Stored Mana held by the output.
Unlock Conditions Countuint8The number of unlock conditions following.
Unlock Conditions atMostOneOfEach +
+ Address Unlock Condition +
Defines the Address that owns this output. It can unlock the output with the proper Unlock in a transaction. Defined in TIP-38 (Address Unlock Condition).
+ + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 0 to denote an Address Unlock Condition.
Address oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
+ Implicit Account Creation Address +
Defines an address on which an Implicit Account is created when it receives a Basic Output. Defined in TIP-42 (Implicit Account Creation Address).
+
+
+
+
+ Storage Deposit Return Unlock Condition +
Defines the amount of IOTAs used as storage deposit that have to be returned to Return Address. Defined in TIP-38 (Storage Deposit Return Unlock Condition).
+ + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 1 to denote a Storage Deposit Return Unlock Condition.
Return Address oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
Return Amountuint64Amount of IOTA coins the consuming transaction should deposit to the address defined in Return Address.
+
+
+ Timelock Unlock Condition +
Defines a slot index until which the output can not be unlocked. Defined in TIP-38 (Timelock Unlock Condition).
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 2 to denote a Timelock Unlock Condition.
Slot Indexuint32Slot index starting from which the output can be consumed.
+
+
+ Expiration Unlock Condition +
Defines a slot index until which only the Address defined in the Address Unlock Condition is allowed to unlock the output. After the slot index is reached/passed, only the Return Address can unlock it. Defined in TIP-38 (Expiration Unlock Condition).
+ + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Unlock Condition Typeuint8Set to value 3 to denote an Expiration Unlock Condition.
Return Address oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
Slot Indexuint32Before this slot index, Address Unlock Condition is allowed to unlock the output, after that only the address defined in Return Address.
+
+
Features Countuint8The number of features following.
Features atMostOneOfEach +
+ Sender Feature +
Identifies the validated sender of the output. Defined in TIP-38 (Sender Feature).
+ + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 0 to denote a Sender Feature.
Sender oneOf +
+ Ed25519 Address +
An Address derived from an Ed25519 Public Key. Defined in TIP-38 (Ed25519 Address).
+
+
+ Account Address +
An Address derived from an Account ID which can be unlocked by unlocking the corresponding Account. Defined in TIP-38 (Account Address).
+
+
+ NFT Address +
An Address derived from an NFT ID which can be unlocked by unlocking the corresponding NFT. Defined in TIP-38 (NFT Address).
+
+
+ Anchor Address +
An Address derived from an Anchor ID which can be unlocked by unlocking the corresponding Anchor. Defined in TIP-38 (Anchor Address).
+
+
+ Multi Address +
Defines a Multi Address that consists of addresses with weights and a threshold value. The Multi Address can be unlocked if the cumulative weight of all unlocked addresses is equal to or exceeds the threshold. Defined in TIP-52 (Multi Address).
+
+
+ Restricted Address +
An address that contains another address and allows for configuring its capabilities. Defined in TIP-50 (Restricted Address).
+
+
+
+
+ Metadata Feature +
Defines a map of key-value pairs that is stored in the output. Defined in TIP-38 (Metadata Feature).
+ + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 2 to denote a Metadata Feature.
Entries Countuint8The number of entries in the map.
Entries anyOf +
+ Metadata Entry +
A map entry consisting of a string key and an arbitrary byte value.
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Key(uint8)ByteArrayA string which may only consist of printable ASCII characters. A leading uint8 denotes its length.
Value(uint16)ByteArrayAn array of arbitrary binary data. A leading uint16 denotes its length.
+
+
+
+
+ Tag Feature +
Defines an indexation tag to which the output can be indexed by additional node plugins. Defined in TIP-38 (Tag Feature).
+ + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 4 to denote a Tag Feature.
Tag(uint8)ByteArrayBinary indexation data. A leading uint8 denotes its length.
+
+
+ Native Token Feature +
A feature that carries a user-defined Native Token minted by a Foundry Output. Defined in TIP-38 (Native Token Feature).
+ + + + + + + + + + + + + + + + + + + + + +
+ Name + + Type + + Description +
Feature Typeuint8Set to value 5 to denote a Native Token Feature.
Token IDByteArray[38]Identifier of the native token. Its derivation is defined in TIP-44 (Foundry Output).
Amountuint256Amount of native tokens of the given Token ID.
+
+
+ +## Additional Transaction Syntactic Validation Rules + +- 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` ≤ `4`. +- `Feature Type` of a Feature must define one of the following types: + - Sender Feature + - Metadata Feature + - Tag Feature + - Native Token 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. + +# Test Vectors + +The protocol parameters used in the following test vectors are the same as in +[TIP-49 (Protocol Parameters Hash)](../TIP-0049/tip-0049.md#protocol-parameters-hash). + +## Storage Score + +The following test vector shows the calculation of the storage score according to [TIP-47](../TIP-0047/tip-0047.md). + +Basic Output (json-encoded): + +```json +{ + "type": 0, + "amount": "200000000", + "mana": "555000000", + "unlockConditions": [ + { + "type": 0, + "address": { + "type": 0, + "pubKeyHash": "0xed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a" + } + }, + { + "type": 2, + "slot": 999 + } + ], + "features": [ + { + "type": 2, + "entries": { + "iota": "0x322e30" + } + }, + { + "type": 4, + "tag": "0x73746f726167655f73636f7265" + }, + { + "type": 5, + "id": "0x083ef5555d65ba314fb1680147da0d54b08cecfd9a728bdcf5f1ebda1fedb9f852435d8d1000", + "amount": "0x2a" + } + ] +} +``` + +Basic Output (hex-encoded binary serialization): + +``` +0x0000c2eb0b00000000c0a0142100000000020000ed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a02e703000003020104696f74610300322e30040d73746f726167655f73636f726505083ef5555d65ba314fb1680147da0d54b08cecfd9a728bdcf5f1ebda1fedb9f852435d8d10002a00000000000000000000000000000000000000000000000000000000000000 +``` + +Basic Output Storage Score: `244`. + +# Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).