├── .github ├── markdownlint-config.yml └── workflows │ ├── gh-rfcs-mdbook.yml │ ├── markdownlint.yml │ └── test-docs-build.yml ├── .gitignore ├── .yarnrc.yml ├── CONTRIBUTE.md ├── LICENSE-APACHE ├── README.md ├── book.toml ├── docusaurus.config.js ├── format-tip-header.sh ├── generate-book.sh ├── meeting-minutes ├── 2020-06-04.md ├── 2020-06-09.md ├── 2020-06-16.md ├── 2020-06-25.md ├── 2020-07-13.md ├── 2020-08-18.md └── 2020-11-09.md ├── package.json ├── tip-template.md └── tips ├── TIP-0001 ├── process.svg └── tip-0001.md ├── TIP-0002 ├── tangle-conflict.svg ├── tangle.svg └── tip-0002.md ├── TIP-0003 ├── cnf_tx_roots.PNG ├── otrsi_ytrsi.PNG └── tip-0003.md ├── TIP-0004 └── tip-0004.md ├── TIP-0005 └── tip-0005.md ├── TIP-0006 └── tip-0006.md ├── TIP-0007 ├── tip-0007.md └── utxo.png ├── TIP-0008 └── tip-0008.md ├── TIP-0009 ├── diffs_1.png ├── diffs_2.png └── tip-0009.md ├── TIP-0010 └── tip-0010.md ├── TIP-0011 └── tip-0011.md ├── TIP-0012 └── tip-0012.md ├── TIP-0013 ├── rest-api.yaml └── tip-0013.md ├── TIP-0014 ├── test.json └── tip-0014.md ├── TIP-0015 └── tip-0015.md ├── TIP-0016 ├── event-api.yml └── tip-0016.md ├── TIP-0017 └── tip-0017.md ├── TIP-0018 ├── chain-constraint.png └── tip-0018.md ├── TIP-0019 ├── assets │ ├── deposit_miota_AliasOutput_(max_functionality).jpg │ ├── deposit_miota_AliasOutput_(min_functionality).jpg │ ├── deposit_miota_BasicOutput_(max_functionality).jpg │ ├── deposit_miota_BasicOutput_(min_functionality).jpg │ ├── deposit_miota_FoundryOutput_(max_functionality).jpg │ ├── deposit_miota_FoundryOutput_(min_functionality).jpg │ ├── deposit_miota_NFTOutput_(max_functionality).jpg │ ├── deposit_miota_NFTOutput_(min_functionality).jpg │ ├── microtransactions_pt3_layer1.png │ └── microtransactions_pt3_layer2.png └── tip-0019.md ├── TIP-0020 ├── tip-0020.md └── utxo.png ├── TIP-0021 └── tip-0021.md ├── TIP-0022 └── tip-0022.md ├── TIP-0023 └── tip-0023.md ├── TIP-0024 └── tip-0024.md ├── TIP-0025 ├── core-rest-api.yaml └── tip-0025.md ├── TIP-0026 ├── indexer-rest-api.yaml └── tip-0026.md ├── TIP-0027 ├── irc27.schema.json └── tip-0027.md ├── TIP-0028 ├── event-api.yml └── tip-0028.md ├── TIP-0029 └── tip-0029.md ├── TIP-0030 ├── examples │ ├── 1-valid.json │ ├── 2-valid.json │ └── 3-invalid.json ├── irc30.schema.json └── tip-0030.md ├── TIP-0031 └── tip-0031.md ├── TIP-0032 ├── genesis-supply.png └── tip-0032.md ├── TIP-0034 └── tip-0034.md └── TIP-0035 ├── delta_snapshot.png ├── full_snapshot.png └── tip-0035.md /.github/markdownlint-config.yml: -------------------------------------------------------------------------------- 1 | default: false # excludes all rules by default 2 | 3 | # Files should end with a single newline character 4 | MD047: true 5 | -------------------------------------------------------------------------------- /.github/workflows/gh-rfcs-mdbook.yml: -------------------------------------------------------------------------------- 1 | name: TIP Book 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | deploy: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Checkout 13 | uses: actions/checkout@v2 14 | 15 | # Install Rust package manager 16 | # 17 | - name: Install cargo 18 | uses: actions-rs/toolchain@v1 19 | with: 20 | toolchain: stable 21 | profile: minimal 22 | 23 | # Cache installation assets 24 | # 25 | - name: Cache cargo registry 26 | uses: actions/cache@v1 27 | with: 28 | path: ~/.cargo/registry 29 | key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }} 30 | - name: Cache cargo index 31 | uses: actions/cache@v1 32 | with: 33 | path: ~/.cargo/git 34 | key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }} 35 | - name: Cache cargo build 36 | uses: actions/cache@v1 37 | with: 38 | path: target 39 | key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }} 40 | 41 | # Install mdbook and requirements 42 | # 43 | - name: Install mdbook 44 | uses: actions-rs/cargo@v1 45 | with: 46 | command: install 47 | args: mdbook 48 | 49 | - name: Generate summary 50 | run: ./generate-book.sh 51 | 52 | # HTML publication as Github Page 53 | # 54 | - name: Publish HTML 55 | uses: peaceiris/actions-gh-pages@v3 56 | with: 57 | github_token: ${{ secrets.GITHUB_TOKEN }} 58 | publish_dir: ./book 59 | publich_branch: ${{ github.ref }} 60 | -------------------------------------------------------------------------------- /.github/workflows/markdownlint.yml: -------------------------------------------------------------------------------- 1 | name: Markdown Lint 2 | 3 | on: 4 | pull_request: 5 | branches: [ main ] 6 | 7 | 8 | jobs: 9 | lint: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Checkout 13 | uses: actions/checkout@v2 14 | - name: Markdown Linting 15 | uses: avto-dev/markdown-lint@v1.5.0 16 | with: 17 | config: './.github/markdownlint-config.yml' 18 | args: './tips/**/*.md' 19 | -------------------------------------------------------------------------------- /.github/workflows/test-docs-build.yml: -------------------------------------------------------------------------------- 1 | name: Test Docs Build 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | pull_request: 8 | branches: 9 | - main 10 | 11 | concurrency: 12 | group: ${{ github.workflow }}-${{ github.ref }} 13 | cancel-in-progress: true 14 | 15 | jobs: 16 | checks: 17 | runs-on: ubuntu-latest 18 | steps: 19 | - uses: actions/checkout@v3 20 | - name: Test Build 21 | run: | 22 | corepack enable 23 | yarn install --no-immutable 24 | yarn build 25 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | book/ 2 | src/ 3 | 4 | # Dependencies 5 | node_modules 6 | 7 | # Yarn 8 | yarn.lock 9 | .pnp.* 10 | .yarn/* 11 | !.yarn/patches 12 | !.yarn/plugins 13 | !.yarn/releases 14 | !.yarn/sdks 15 | !.yarn/versions 16 | 17 | # Production 18 | /build 19 | 20 | # Generated files 21 | .docusaurus 22 | .cache-loader 23 | package-lock.json 24 | 25 | # Misc 26 | .DS_Store 27 | .env.local 28 | .env.development.local 29 | .env.test.local 30 | .env.production.local 31 | 32 | npm-debug.log* 33 | yarn-debug.log* 34 | yarn-error.log* 35 | -------------------------------------------------------------------------------- /.yarnrc.yml: -------------------------------------------------------------------------------- 1 | nodeLinker: node-modules 2 | -------------------------------------------------------------------------------- /CONTRIBUTE.md: -------------------------------------------------------------------------------- 1 | > **Note** 2 | > This guide is meant for local development and contributing to the repository only, for guidance on the TIPs process and how to propose Tangle improvements, please see the [README](README.md) 3 | 4 | 5 | # Documentation 6 | 7 | The TIPs online documentation is built using [Docusaurus 2](https://docusaurus.io/). The deployment is done through a centralized build from [IOTA WIKI](https://github.com/iota-wiki/iota-wiki). To run a local instance, the [IOTA WIKI CLI](https://www.npmjs.com/package/@iota-wiki/cli) is used. 8 | 9 | ## Prerequisites 10 | 11 | - [Node.js 16.10 or above](https://nodejs.org/en/download/). 12 | - [Modern Yarn](https://yarnpkg.com/getting-started/install) enabled by running `corepack enable`. 13 | 14 | ## Installation 15 | 16 | ```console 17 | yarn 18 | ``` 19 | 20 | This command installs all necessary dependencies. 21 | 22 | ## Local Development 23 | 24 | ```console 25 | yarn start 26 | ``` 27 | 28 | This command starts a local, wiki themed development server and opens up a browser window. Most changes are reflected live without having to restart the server. 29 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright 2019 IOTA Foundation 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | > [!WARNING] 2 | > The Tangle Improvement Proposal (TIP) repository and framework is deprecated. Please refer to the [IOTA Improvement Proposals (IIP)](https://github.com/iotaledger/IIPs) 3 | > for contributing to IOTA's technology. 4 | > Since all TIPs refer to outdated protocol versions, they are all obsolete and no longer maintained. 5 | 6 | # Tangle Improvement Proposal (TIP) Repository 7 | 8 | TIPs are improvement proposals for bettering the IOTA technology stack. 9 | 10 | Building the IOTA ecosystem is a community effort, therefore we welcome anyone to propose, discuss and debate ideas that will later become formalized TIPs. 11 | 12 | ## Propose new ideas 13 | 14 | Do you have an idea how to improve the IOTA technology stack? 15 | - Head over to the [discussions](https://github.com/iotaledger/tips/discussions) page to browse already submitted ideas or share yours! 16 | - Once your idea is discussed, you can submit a draft TIP ([template here](https://github.com/iotaledger/tips/blob/main/tip-template.md) as a PR to the repository. 17 | - You will receive feedback from the TIP Editors and review from core devs. 18 | - Once accepted, your TIP is merged as Draft. 19 | - It is your responsibility to drive its implementation and to present a clear plan on how the new feature will be adopted by the network. 20 | - Once implementation is ready and testing yields satisfactory result, the TIP becomes Proposed. 21 | - Proposed TIPs that are supported by majority of the network become Active. 22 | 23 | You may find more information about the TIP Process in [TIP-1](./tips/TIP-0001/tip-0001.md). 24 | 25 | ## Stardust TIPs 26 | 27 | Stardust is the next upgrade of the IOTA protocol that adds tokenization and smart contract chain support besides many 28 | more improvements. Browse the [list of TIPs](#list-of-tips) below with the _Stardust_ tag to learn more about what changes. 29 | 30 | ## List of TIPs 31 | 32 | - Last updated: 2023-10-19 33 | - The _Status_ of a TIP reflects its current state with respect to its progression to being supported on the IOTA mainnet. 34 | - `Draft` TIPs are work in progress. They may or may not have a working implementation on a testnet. 35 | - `Proposed` TIPs are demonstrated to have a working implementation. These TIPs are supported on Shimmer, the staging network of IOTA. 36 | - `Active` TIPs are supported on the IOTA mainnet. 37 | - `Replaced` TIPs have been replaced by a newer TIP. 38 | - `Obsolete` TIPs are no longer in use. 39 | 40 | ![image](tips/TIP-0001/process.svg) 41 | 42 | 43 | | # | Title | Description | Type | Layer | Status | Initial Target | 44 | |----|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------|--------------------|----------------| 45 | | 1 | [TIP Process](tips/TIP-0001/tip-0001.md) | Purpose and guidelines of the contribution framework | Process | - | Active | - | 46 | | 2 | [White Flag Ordering](tips/TIP-0002/tip-0002.md) | Mitigate conflict spamming by ignoring conflicts | Standards | Core | Active | Chrysalis | 47 | | 3 | [Uniform Random Tip Selection](tips/TIP-0003/tip-0003.md) | Perform fast tip-selection to increase message throughput | Standards | Core | Active | Chrysalis | 48 | | 4 | [Milestone Merkle Validation](tips/TIP-0004/tip-0004.md) | Add Merkle tree hash to milestone for local ledger state verification | Standards | Core | Active | Chrysalis | 49 | | 5 | [Binary To Ternary Encoding](tips/TIP-0005/tip-0005.md) | Define the conversion between binary and ternary data | Standards | Core | Active | Chrysalis | 50 | | 6 | [Tangle Message](tips/TIP-0006/tip-0006.md) | Generalization of the Tangle transaction concept | Standards | Core | Replaced by TIP-24 | Chrysalis | 51 | | 7 | [Transaction Payload](tips/TIP-0007/tip-0007.md) | UTXO-based transaction structure | Standards | Core | Replaced by TIP-20 | Chrysalis | 52 | | 8 | [Milestone Payload](tips/TIP-0008/tip-0008.md) | Coordinator issued milestone structure with Ed25519 authentication | Standards | Core | Replaced by TIP-29 | Chrysalis | 53 | | 9 | [Local Snapshot File Format](tips/TIP-0009/tip-0009.md) | File format to export/import ledger state | Standards | Interface | Replaced by TIP-35 | Chrysalis | 54 | | 10 | [Mnemonic Ternary Seed](tips/TIP-0010/tip-0010.md) | Represent ternary seed as a mnemonic sentence | Standards | IRC | Obsolete | Legacy IOTA | 55 | | 11 | [Bech32 Address Format](tips/TIP-0011/tip-0011.md) | Extendable address format supporting various signature schemes and address types | Standards | Interface | Replaced by TIP-31 | Chrysalis | 56 | | 12 | [Message PoW](tips/TIP-0012/tip-0012.md) | Define message proof-of-work as a means to rate-limit the network | Standards | Core | Active | Chrysalis | 57 | | 13 | [REST API](tips/TIP-0013/tip-0013.md) | Node REST API routes and objects in OpenAPI Specification | Standards | Interface | Replaced by TIP-25 | Chrysalis | 58 | | 14 | [Ed25519 Validation](tips/TIP-0014/tip-0014.md) | Adopt [ZIP-215](https://zips.z.cash/zip-0215) to explicitly define Ed25519 validation criteria | Standards | Core | Active | Chrysalis | 59 | | 15 | [Dust Protection](tips/TIP-0015/tip-0015.md) | Prevent bloating the ledger size with to dust outputs | Standards | Core | Replaced by TIP-19 | Chrysalis | 60 | | 16 | [Event API](tips/TIP-0016/tip-0016.md) | Node event API definitions in AsyncAPI Specification | Standards | Interface | Replaced by TIP-28 | Chrysalis | 61 | | 17 | [Wotsicide](tips/TIP-0017/tip-0017.md) | Define migration from legacy WOTS addresses to post-Chrysalis Phase 2 network | Standards | Core | Obsolete | Chrysalis | 62 | | 18 | [Multi-Asset Ledger and ISC Support](tips/TIP-0018/tip-0018.md) | Transform IOTA into a multi-asset ledger that supports running IOTA Smart Contracts | Standards | Core | Active | **Stardust** | 63 | | 19 | [Dust Protection Based on Byte Costs](tips/TIP-0019/tip-0019.md) | Prevent bloating the ledger size with dust outputs | Standards | Core | Active | **Stardust** | 64 | | 20 | [Transaction Payload with New Output Types](tips/TIP-0020/tip-0020.md) | UTXO-based transaction structure with TIP-18 | Standards | Core | Active | **Stardust** | 65 | | 21 | [Serialization Primitives](tips/TIP-0021/tip-0021.md) | Introduce primitives to describe the binary serialization of objects | Standards | Core | Active | **Stardust** | 66 | | 22 | [IOTA Protocol Parameters](tips/TIP-0022/tip-0022.md) | Describes the global protocol parameters for the IOTA protocol | Standards | Core | Active | **Stardust** | 67 | | 23 | [Tagged Data Payload](tips/TIP-0023/tip-0023.md) | Payload for arbitrary data | Standards | Core | Active | **Stardust** | 68 | | 24 | [Tangle Block](tips/TIP-0024/tip-0024.md) | A new version of TIP-6 that renames messages to blocks and removes the Indexation Payload in favor of the Tagged Data Payload. Replaces TIP-6. | Standards | Core | Active | **Stardust** | 69 | | 25 | [Core REST API](tips/TIP-0025/tip-0025.md) | Node Core REST API routes and objects in OpenAPI Specification. Replaces TIP-13. | Standards | Interface | Active | **Stardust** | 70 | | 26 | [UTXO Indexer REST API](tips/TIP-0026/tip-0026.md) | UTXO Indexer REST API routes and objects in OpenAPI Specification. | Standards | Interface | Active | **Stardust** | 71 | | 27 | [IOTA NFT standards](tips/TIP-0027/tip-0027.md) | Define NFT metadata standard, collection system and creator royalties | Standards | IRC | Active | **Stardust** | 72 | | 28 | [Node Event API](tips/TIP-0028/tip-0028.md) | Node event API definitions in AsyncAPI Specification. Replaces TIP-16. | Standards | Interface | Active | **Stardust** | 73 | | 29 | [Milestone Payload](tips/TIP-0029/tip-0029.md) | Milestone Payload with keys removed from essence. Replaces TIP-8. | Standards | Core | Active | **Stardust** | 74 | | 30 | [Native Token Metadata Standard](tips/TIP-0030/tip-0030.md) | A JSON schema that describes token metadata format for native token foundries | Standards | IRC | Active | **Stardust** | 75 | | 31 | [Bech32 Address Format for IOTA and Shimmer](tips/TIP-0031/tip-0031.md) | Extendable address format supporting various signature schemes and address types. Replaces TIP-11. | Standards | Interface | Active | **Stardust** | 76 | | 32 | [Shimmer Protocol Parameters](tips/TIP-0032/tip-0032.md) | Describes the global protocol parameters for the Shimmer network | Standards | Core | Active | **Stardust** | 77 | | 33 | [Public Token Registry](https://github.com/iotaledger/tips/pull/72) | Defines an open public registry for NFT collection ID and native tokens metadata | Standards | IRC | Draft | **Stardust** | 78 | | 34 | [Wotsicide (Stardust update)](tips/TIP-0034/tip-0034.md) | Define migration from legacy W-OTS addresses to post-Chrysalis networks. Replaces TIP-17. | Standards | Core | Obsolete | **Stardust** | 79 | | 35 | [Local Snapshot File Format (Stardust Update)](tips/TIP-0035/tip-0035.md) | File format to export/import ledger state. Replaces TIP-9. | Standards | Interface | Active | **Stardust** | 80 | | 37 | [Dynamic Proof-of-Work](https://github.com/iotaledger/tips/pull/81) | Dynamically adapt the PoW difficulty | Standards | Core | Withdrawn | **Stardust** | 81 | 82 | ## Need help? 83 | 84 | If you want to get involved in the community, need help getting started, have any issues related to the repository or just want to discuss blockchain, distributed ledgers, and IoT with other people, feel free to join our [Discord](https://discord.iota.org/). 85 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | title = "The Tangle Improvement Proposal (TIP) Book" 3 | 4 | [output.html] 5 | no-section-label = true -------------------------------------------------------------------------------- /docusaurus.config.js: -------------------------------------------------------------------------------- 1 | const { link } = require('fs'); 2 | const path = require('path'); 3 | 4 | module.exports = { 5 | plugins: [ 6 | [ 7 | '@docusaurus/plugin-content-docs', 8 | { 9 | id: 'iota-tips', 10 | path: path.resolve(__dirname, './'), 11 | routeBasePath: 'tips', 12 | editUrl: 'https://github.com/iotaledger/tips/edit/main/', 13 | remarkPlugins: [require('remark-import-partial')], 14 | include: ['tips/**/*.md', 'README.md'], 15 | 16 | // Create own sidebar to flatten hierarchy and use own labeling 17 | async sidebarItemsGenerator({ 18 | defaultSidebarItemsGenerator, 19 | ...args 20 | }) { 21 | const items = await defaultSidebarItemsGenerator(args); 22 | 23 | const result = items[1].items.map((item) => { 24 | if (item.type === 'category') { 25 | if (item.link.type === 'doc') { 26 | // Get TIP number and append TIP name 27 | item.label = item.link.id.slice(-4) + '-' + item.label 28 | } 29 | } 30 | return item; 31 | }); 32 | 33 | return [items[0]].concat(result); 34 | }, 35 | } 36 | ], 37 | ], 38 | staticDirectories: [], 39 | }; 40 | -------------------------------------------------------------------------------- /format-tip-header.sh: -------------------------------------------------------------------------------- 1 | C=0 2 | touch tmp 3 | while IFS= read -r line 4 | do 5 | if [[ $line == "---" && "$C" -eq 0 ]]; then 6 | ((C++)) 7 | line="
"
 8 |   fi
 9 |     if [[ $line == "---" && "$C" -eq 1 ]]; then
10 |         ((C++))
11 |         line="
" 12 | fi 13 | echo "$line" >> tmp 14 | done < "$1" 15 | 16 | mv tmp $1 -------------------------------------------------------------------------------- /generate-book.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # SPDX-License-Identifier: Apache-2.0 4 | # Source: https://github.com/rust-lang/rfcs/blob/85c95c7179acc8986eae709f773ff3a91f1e2e43/generate-book.sh 5 | 6 | set -e 7 | 8 | rm -rf src 9 | mkdir src 10 | cp -r tips src 11 | 12 | printf '[Introduction](introduction.md)\n\n' > src/SUMMARY.md 13 | 14 | # create summary, extract tip titles and numbers 15 | find ./src ! -type d -name '*.md' ! -path ./src ! -path ./src/SUMMARY.md -print0 \ 16 | | sed -e 's/.\/src\///g' \ 17 | | sort -z \ 18 | | while read -r -d '' file; 19 | do 20 | tipNum=$(sed 's/-0*/-/' <<< $(basename "$file" ".md")) 21 | printf -- '- [%s%s](%s)\n' ${tipNum^^} "$(sed -n 's/^title:\(.*\)$/\1/p' < $file)" "$file" 22 | done >> src/SUMMARY.md 23 | 24 | # remove "---" from tip header and replace it h 
 and
25 | find ./src ! -type d -name '*.md' ! -path ./src ! -path ./src/SUMMARY.md -print0 \ 26 | | sort -z \ 27 | | while read -r -d '' file; 28 | do 29 | ./format-tip-header.sh $file 30 | done 31 | 32 | ln -frs README.md src/introduction.md 33 | 34 | mdbook build 35 | -------------------------------------------------------------------------------- /meeting-minutes/2020-06-04.md: -------------------------------------------------------------------------------- 1 | # Chrysalis RFC Call - 2020-06-04 2 | 3 | ## Participants 4 | 5 | - Wolfgang 6 | - Thibault 7 | - Luca 8 | - Gal 9 | - Hans 10 | 11 | ## Topics 12 | 13 | ### Communication 14 | 15 | - General discussions on Discord #protocol 16 | - More special Slack #rfc-consensus 17 | - Upload meeting notes to GitHub 18 | (@Wolfgang check and set up) 19 | - Have another call to clarify about UTxO basics before drafting that RFC 20 | 21 | ### RFC Status 22 | 23 | - [RFC-0001](https://github.com/iotaledger/protocol-rfcs/pull/1): simple but not directly Chrysalis related @all please review 24 | - [RFC-0002](https://github.com/iotaledger/protocol-rfcs/pull/2): @Luca close 25 | - [RFC-0009](https://github.com/Wollac/protocol-rfcs/blob/ed25519/text/0009-ed25519-signature-scheme/0009-ed25519-signature-scheme.md): no longer relevant, @Wolfgang close to avoid confusion 26 | - [RFC-0010](https://github.com/Wollac/protocol-rfcs/blob/mnemonic-seed/text/0010-mnemonic-seed/0010-mnemonic-seed.md): Not part of Chrysalis, relevant for the wallet team 27 | - [RFC-0005](https://github.com/iotaledger/protocol-rfcs/blob/master/text/0005-white-flag/0005-white-flag.md): @Thibault clarify bundle validity 28 | - [RFC-0008](https://github.com/luca-moser/protocol-rfcs/blob/rfc-urts-tip-sel/text/0008-weighted-uniform-random-tip-selection/0008-weighted-uniform-random-tip-selection.md): 29 | - @Luca add bundle validity and selection delay as discussed 30 | - @all review (and approve) when Luca is done 31 | - [RFC-0012](https://github.com/Wollac/protocol-rfcs/blob/milestone-merkle-validation/text/0012-milestone-merkle-validation/0012-milestone-merkle-validation.md): 32 | - There are ambiguities about the bytes->trytes conversion preventing the approval. 33 | - @Wolfgang write a separate RFC about this particular conversion with pseudo-code and examples. 34 | 35 | #### Bundle validity 36 | 37 | - A bundle is to be considered valid, if it is syntactically valid (e.g. indices, balance 0, < max supply, ...) _and_ its signatures are valid. 38 | - White-flag and tip selection must only include valid bundles. Invalid bundles will be discarded and _not_ ignored. 39 | 40 | #### Tip Selection delay 41 | 42 | - Motivation: For low TPS there should be the possibility to keep transactions in the selection pool, in order for the Tangle to remain wide enough. 43 | - time based: there are possibilities of race conditions and finding a good values for TPS scenarios is hard 44 | - #approver based: reasonable mechanism, automatically "adapting" to different TPS scenarios: remove a transaction only from the pool, if it has at least k direct approvers. A k of 2 is a good start, but this should be configurable. No further discussion, analysis needed. 45 | 46 | ### New RFCs 47 | 48 | #### MS selection 49 | 50 | - Briefly discussed idea/motivation: https://iota.cafe/t/coordinator-improvements/310 51 | - White flag + Check Points already offers strong protection but "heaviest branch" aims to "mathematically" maximize CTPS so it is worth looking at it. 52 | - PoC https://github.com/Wollac/hornet/tree/feat/hps initial artificial benchmarks promising for several thousands of bundles 53 | - Not the highest priority as any reasonable Tip Selection will already work well for white-flag. 54 | - Gal, Wolfgang will continue working on this topic/RFC in parallel with the other topics 55 | 56 | ### UTxO (with a Coordinator) 57 | 58 | - Re-attachment are still very much relevant (although much more unlikely after white flag) 59 | - Re-attachments with OTS must be possible without re-signing - just like now 60 | - Re-attachments can be conflicts - just like now 61 | - Terminology is (even in the current protocol) very confusing, it's crucial to clear this up before further discussions: 62 | - (try to change existing bundle/transactions names as less as possible) 63 | - Transaction (vertex in the Tangle) -> will be called "Message" 64 | - Bundle (transfer that is moving funds) -> will be called "Transaction" (to be consistent with UTxO names) 65 | - copies of the same "Transaction" can be in different "Messages" (re-attachment) 66 | - 0-value Transaction (a bundle transferring no funds) -> will just be a "Message" without a "Transaction" 67 | 68 | More discussions are needed to clarify basics as this will speed up the writing of the RFC and help identify partitions. 69 | -------------------------------------------------------------------------------- /meeting-minutes/2020-06-09.md: -------------------------------------------------------------------------------- 1 | # Chrysalis RFC Call - 2020-06-09 2 | 3 | ## Participants 4 | 5 | - Wolfgang 6 | - Thibault 7 | - Luca 8 | - Gal 9 | - Hans 10 | 11 | ## Action items 12 | 13 | @all design a UTxO transaction layout proposal to be discussed and compared in the next week! 14 | 15 | ## Topics 16 | 17 | ### Communication 18 | 19 | - Meeting notes will be uploaded under github.com/iotaledger/protocol-rfcs/tree/master in a separate folder 20 | - Next call in the next week 21 | 22 | ### RFC Status 23 | 24 | Chrysalis RFCs: 25 | - [Draft RFC](https://hackmd.io/hldMvepaTpuKovr5-LdcZA) bytes->trytes: presented RFC, no open questions or objections, @wolfgang prepare PR, @all review 26 | - [RFC-0001](https://github.com/iotaledger/protocol-rfcs/pull/1): @Gal address review comments 27 | - [RFC-0005](https://github.com/iotaledger/protocol-rfcs/blob/master/text/0005-white-flag/0005-white-flag.md): discussed and approved changes in PR#14 28 | - [RFC-0008](https://github.com/luca-moser/protocol-rfcs/blob/rfc-urts-tip-sel/text/0008-weighted-uniform-random-tip-selection/0008-weighted-uniform-random-tip-selection.md): discussed changes, approved by everyone 29 | - [RFC-0012](https://github.com/Wollac/protocol-rfcs/blob/milestone-merkle-validation/text/0012-milestone-merkle-validation/0012-milestone-merkle-validation.md): requires minor changes to reference the Draft RFC (@Wolfgang), @all review after that 30 | 31 | ### UTxO (with a Coordinator) 32 | 33 | ``` 34 | input #1 >---* *---> output #1 35 | \ / 36 | input #2 >---*--------* 37 | / \ 38 | input #3 >---* *---> output #2 39 | ``` 40 | 41 | #### General 42 | 43 | - Unless _every_ part of an transaction supports a version/type byte, there should be a version type in the Tx. 44 | 45 | #### Inputs 46 | 47 | - Signatures: 48 | - should not directly be part of the input, but in a separate "witness". This enables providing only one signature for all the inputs of the same address 49 | - only the actual transaction is signed not the "witness" 50 | 51 | - Input types: 52 | - Allowing inputs of different types enables very fine granular control for each particular input 53 | - An input must uniquely reference a TxO. More information like value, meta data, etc is not required 54 | - There seems to be no realistic scenario which requires a different input type. 55 | 56 | - Outputs: 57 | - One transaction should only have one output per address. This needs to be assured by a validation step. 58 | 59 | - Input format: 60 | - There are two conceptually different design ideas: 61 | - `TxID` + `TxOutputIndex` 62 | - This is the most wide-spread input format in UTxO models. 63 | - It allows to reference any potential output types (even outputs not bound to an address). 64 | - Closer to the transaction memory model, in which the output is retrieved by an array access with the corresponding index. 65 | - `TxID` + `TxOutputAddress` 66 | - If only one output per address per transaction is allowed and only outputs to addresses are supported, this is equivalent to `TxID` + `TxOutputIndex`. 67 | - In a realistic DB model, (unspent) outputs should be addressable by `TxID` + `TxOutputAddress`. Thus, this format is closer to those DB keys. 68 | -------------------------------------------------------------------------------- /meeting-minutes/2020-06-16.md: -------------------------------------------------------------------------------- 1 | # Chrysalis RFC Call - 2020-06-16 2 | 3 | ## Participants 4 | 5 | - Wolfgang 6 | - Thibault 7 | - Luca 8 | - Gal 9 | - Hans 10 | 11 | ## Action Items 12 | 13 | - Everyone develops a layout proposal of UTxO transaction with respect to the design decisions described below 14 | - Schedule a longer meeting to have enough time to discuss the layouts properly 15 | 16 | ## Topics 17 | 18 | ### RFC Status 19 | 20 | Chrysalis RFCs: 21 | - [RFC-0001](https://github.com/iotaledger/protocol-rfcs/pull/1): 22 | - All comments addressed 23 | - Review later (minor) changes and approve 24 | - [RFC-0012](https://github.com/Wollac/protocol-rfcs/blob/milestone-merkle-validation/text/0012-milestone-merkle-validation/0012-milestone-merkle-validation.md): 25 | - Blockers: 26 | - Merge RFC-0015 27 | - Finish rust implementation to verify examples and feasibility 28 | - [RFC-0015](https://github.com/iotaledger/protocol-rfcs/pull/15): 29 | - Ready for review, look at it till next call 30 | 31 | ### UTxO for Chrysalis (with a Coordinator) 32 | 33 | - Discussed proposals: 34 | - Hans: https://github.com/hmoog/protocol-rfcs/blob/master/text/0011-utxo-model/0011-utxo-model.md 35 | - Wolfgang: https://hackmd.io/@CcRtfCBnRbW82-AdbFJUig/H1zu0q7p8 36 | - Gal: https://hackmd.io/@cIrs3AfUSq2uSeQ2tBF9fw/rJoT5xIT8 37 | - Discussed pros/cons of `tx_id` + `tx_output_index` vs `tx_id` + `address` 38 | - Larger transaction size should lead to greater PoW difficulty, but issuing one larger tx should be encouraged over multiple small txs. 39 | - Discussed, whether the the credential/witness should be type-able 40 | - Serialization and model description; different pros/can they can be different for now 41 | 42 | ## Design decisions 43 | 44 | - Design a flexible layout, that is likely to handle Coordicide and future changes; not "just" Chrysalis. 45 | - Use `tx_id` + `tx_output_index`: 46 | - This is closer to existing UTxO models and improves interoperability 47 | - Smaller transaction sizes 48 | - Higher flexibility of output types (e.g. multiple addresses, no address, ...) 49 | - `tx_id` + `address` closer (only) to key-value storage model, leading to smaller databases or less lookups. However, this only relevant for output lookups by address. This is less critical than input lookups and might even be disabled/filtered on nodes. 50 | - Each transaction should include `transaction_type`/`version`. 51 | - `input_type` should be added to each input: 52 | - There are applications for differently typed inputs in one transaction 53 | - Will be `0` for now 54 | - Each output should be type-able: 55 | - Use `output_type` or `opcode` as motivated in the RFC 56 | - Use `protobuf`-like design language for the draft process 57 | -------------------------------------------------------------------------------- /meeting-minutes/2020-06-25.md: -------------------------------------------------------------------------------- 1 | # Chrysalis RFC Call - 2020-06-25 2 | 3 | ## Participants 4 | 5 | - Wolfgang 6 | - Thibault 7 | - Luca 8 | - Gal 9 | - Hans 10 | 11 | ## Topics 12 | 13 | ### RFC Status 14 | 15 | Chrysalis RFCs: 16 | - Reduced min approval count to 3 17 | - [RFC-0001](https://github.com/iotaledger/protocol-rfcs/pull/1): 18 | - No more remarks 19 | - Ask Hornet devs for feedback 20 | - [RFC-0015](https://github.com/iotaledger/protocol-rfcs/pull/15): 21 | - Discuss Gal's comments offline 22 | - Ask Hornet devs for feedback 23 | - [RFC-0012](https://github.com/Wollac/protocol-rfcs/blob/milestone-merkle-validation/text/0012-milestone-merkle-validation/0012-milestone-merkle-validation.md): 24 | - Blockers: 25 | - Merge RFC-0015 (reference merged RFC after that) 26 | 27 | ### UTxO for Chrysalis Meeting 28 | 29 | #### Proposals: 30 | - Hans: https://github.com/hmoog/protocol-rfcs/blob/master/text/0011-utxo-model/0011-utxo-model.md 31 | - Wolfgang: https://hackmd.io/@CcRtfCBnRbW82-AdbFJUig/H1zu0q7p8 32 | - Gal: https://hackmd.io/@cIrs3AfUSq2uSeQ2tBF9fw/rJoT5xIT8 33 | - Luca: https://hackmd.io/@XFC6dFQkSiOpICDucms41Q/SJtyp71CL 34 | 35 | #### Decisions 36 | 37 | - Design a flexible layout, that is likely to handle Coordicide and future changes; not "just" Chrysalis. 38 | - Do this iteratively: Start with the most simple amount-based UTxO and then extend (multisig, W-OTS, tokens, ...) 39 | - Prefer `protobuf`-like design language for the draft process 40 | - Motivate potential types in e.g. input, even if currently unused 41 | - Detailed (see Chrysalis RFC Call 06-16): 42 | - Use `tx_id` + `tx_output_index` 43 | - Each transaction should include `transaction_type`/`version` 44 | - `input_type` should be added to each input 45 | - Each output should be type-able (Use `output_type` or `opcode`) 46 | 47 | #### Topics to discuss 48 | 49 | 1. UTxO base layout: discuss proposals of everyone 50 | 3. Serialization (e.g. deterministic `protobuf`, `CBOR`, manual, ...): Wolfgang will present existing solution a bit 51 | 4. Address encoding 52 | 5. UTxO with backward compatible W-OTS 53 | 6. UTxO with multisig 54 | 7. Colored Coins: Hans will present/motivate his proposed solution 55 | 56 | #### When? Who? How? 57 | 58 | - Mon July 6 - Wed July 8 all day 59 | - (Wednesday is reserve; Hans might not be able to join that day) 60 | - Attendees: 61 | - Wolfgang, Thibault, Luca, Gal, Hans 62 | - Invite Vlad whether he has time and wants to listen in 63 | - Format: 64 | - All day remote meeting 65 | - We will try miro.com 66 | - Preparation: 67 | - Read up on what other cryptos are doing wrt. Transaction Layout, Serialization, Address encoding, (non-smart contract) Colored Coins 68 | - We will prepare a HackMD to collect all the links, comments, etc. for preparation 69 | -------------------------------------------------------------------------------- /meeting-minutes/2020-07-13.md: -------------------------------------------------------------------------------- 1 | # Chrysalis RFC Call - 2020-07-13 2 | 3 | ## Participants 4 | 5 | - Wolfgang 6 | - Thibault 7 | - Luca 8 | - Gal 9 | - Hans 10 | - Angelo 11 | 12 | ## Topics 13 | 14 | ### RFC Status 15 | 16 | Chrysalis RFCs: 17 | - [RFC-0008](https://github.com/iotaledger/protocol-rfcs/blob/master/text/0008-weighted-uniform-random-tip-selection/0008-weighted-uniform-random-tip-selection.md) (Weighted URTS): 18 | - Implementation improvements are considered 19 | - [RFC-0012](https://github.com/iotaledger/protocol-rfcs/pull/12): 20 | - Merged. 21 | - Question [BLAKE2b-512 vs BLAKE2b-256](https://github.com/iotaledger/protocol-rfcs/pull/12#discussion_r453506575) 22 | - @Wolfgang add issue to Protocol RFC repo to switch to BLAKE2b-256 in the future, when BLAKE2b-256 signatures are the default 23 | 24 | ### ChrysSum Retrospec 25 | 26 | #### General Open Questions 27 | 28 | - Task assignments 29 | - See below 30 | - Timelines for RFCs 31 | - First draft of RFC until end of this week! (doesn't need to be ready PR yet e.g. HackMD is fine, it's OK to propose options, all open questions should be assessable) 32 | - People to include 33 | - Focus on participants for now 34 | - Re-evaluate when drafts are done 35 | - Webpage based RFC visualization 36 | - Present RFCs in a nicer website 37 | - @Thibault will check Bee-RFC solution 38 | 39 | #### Tasks 40 | 41 | 1. Agree on nice way to implement our layout 42 | - Use HTML `details` and (nested) `table`: https://gist.github.com/luca-moser/e3afd2ff5af2e6c1374a4135629b28aa 43 | 1. Agree on Process to define new _Payload Types_ (by IF and community) 44 | - Message RFC contains a table with type and link to the payload RFC 45 | - Each payload type comes in its own RFC also modifying this table 46 | - Reserve certain range for IF payloads up to 1024 47 | - Distinction between mandatory core payloads and optional ones 48 | - Add _Network Version_ to the MS payload and maybe every _Message_: 49 | - breaking changes in the mandatory core payloads require a version bump 50 | 1. Serialization Primitives 51 | - Describe primitives in Message RFC and reference this in the others 52 | 1. Create _Message_ RFC @Gal 53 | - Motivate layered approach 54 | - Describe serialization primitives and its fields 55 | - Add Payload table 56 | - Provide unsigned data payload as first trivial example 57 | 1. Create _Signed transaction_ RFC @Luca 58 | - Serialization format 59 | - Validation rules (e.g. sorting) 60 | - Move payload length outside the payload: Length of the payload byte-array 61 | 1. Create _Milestone Payload_ RFC @Angelo 62 | - Select signature scheme: 63 | - Quantum-robust vs conventional 64 | - Suited for several years of signatures 65 | - Not malleable 66 | - Present reasonable alternative for security/PR decision 67 | - Describe fields (should include _Network Version_) 68 | 1. Create _Address Encoding_ RFC @Wolfgang 69 | - Based on Bech32, for W-OTS and ED25519 70 | - `t5b1` or Keccak-384: https://hackmd.io/bi-t_qOSRuCdYFpkX4_SFQ 71 | - Since W-OTS will be de-prioritized we should select the easiest solution to implement 72 | - Keccak-384 is preferable but requires more modularity for the Kerl implementation 73 | - `t5b1` is more consistent with current interfaces, but also requires additional work to validate and prevent malleability 74 | 1. Create _Colored Coins_ RFC @Thibault 75 | - Motivate Colored Coins 76 | - Add new Output type extending _Signed transaction_ RFC 77 | 1. Create _Indexation Payload_ RFC 78 | - Provide _Tag_, _Message_ for backward compatibility 79 | 1. Create a signed data payload RFC 80 | 1. Create one/multiple Stream/MAM RFCs 81 | 1. Multisig - BLS discussion 82 | - Focus on the existing RFCs first 83 | -------------------------------------------------------------------------------- /meeting-minutes/2020-08-18.md: -------------------------------------------------------------------------------- 1 | # Chrysalis RFC Call - 2020-08-18 2 | 3 | ## Topics 4 | 5 | ### RFC Status 6 | 7 | - [RFC-0008](https://github.com/iotaledger/protocol-rfcs/blob/master/text/0008-weighted-uniform-random-tip-selection/0008-weighted-uniform-random-tip-selection.md) (Weighted URTS): 8 | - **Depricated** 9 | - Modified in Hornet implementation; "healthy spam": works™ 10 | - Should be re-visited later 11 | - [mdBook](https://github.com/iotaledger/protocol-rfcs/pull/16): 12 | - Merge it now 13 | - Finding a nicer style can be outsourced to frontend later 14 | - @all please approve https://github.com/iotaledger/protocol-rfcs/pull/16 15 | 16 | ### Chrysalis Stage 2 17 | 18 | #### Missing RFCs 19 | 20 | ##### Binary W-OTS 21 | 22 | @Vlad @Wolfgang 23 | 24 | - Computation of the "bundle hash" 25 | - Normalization 26 | - Security of Kerl hash chain 27 | - GitHub discussion: https://github.com/iotaledger/protocol-rfcs/pull/18#discussion_r471824298 28 | 29 | ##### Payload Registration Process: 30 | 31 | - Similar to [SLIP-44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) or [SLIP-173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) 32 | - Just a table with Payload ID, Name and link 33 | - Creation of the RFC will be postponed until Message RFC and payload types are clearer 34 | 35 | @Gal double check in Message RFC: Unknown/unsupported payloads must still be gossiped, but the actual content can be ignored if the node does not care. 36 | 37 | ##### PoW 38 | 39 | - Plain Curl is not feasible: 40 | - `nonce` should be at a fixed position 41 | - Curl is only defined for multiples of 243 trits 42 | - Curl is too slow especially for larger messages 43 | - Batched Curl is very difficult due to arbitrary message lengths 44 | - Solution: 45 | - Compute the Blake2b-256 hash of the message *excluding* the last 8-byte for `nonce` 46 | - Convert to 192-trit string using the `b1t6` encoding. 47 | - Append 0,0,0 to reach trits 48 | - Take the 8-byte little endian encoded `nonce`, convert it into 48 trits using `b1t6`, append 49 | - Compute the Curl-P-81 hash of those 243-trits (always exactly one block) 50 | - Count the trailing zeros 51 | - PoW = 3#zeros / len(message) 52 | - Naive verify implementation (not batched, etc): < 0.1ms 53 | - Existing SW/HW miners can be converted easily 54 | - PoC implementation: [github.com/wollac/iota-crypto-demo](https://github.com/Wollac/iota-crypto-demo/tree/master/pkg/pow) 55 | - Open Questions: 56 | - Score threshold? Start with something that is close to the current MWM. 57 | - Should the 3-trit padding be in the middle or in the end? 58 | - The larger the message the more can be added for free. 59 | 60 | @Wolfgang create a new RFC 61 | 62 | #### Snapshot Format 63 | 64 | - Snapshots need to work for Hornet and Bee 65 | - We need an RFC to coordinate 66 | - Blocked by the "Signed Transaction Payload" RFC 67 | - Add a section describing the migration from account model to UTXO: 68 | - Create a dummy Tx with exactly one output consisting of the total funds on each address. 69 | - Tx hashes need to be consistent. 70 | 71 | Written by Bee/Hornet team; @Luca DRI 72 | 73 | ### Open Questions 74 | 75 | - Capitalization of `Feature Name`? 76 | - We will us all lower case with dash. 77 | - @all please check in each PR that this is correct 78 | - [bech32-address-format](https://github.com/iotaledger/protocol-rfcs/pull/20) 79 | - HRP `iot` / `tio` ok? 80 | - @Wolfgang escalate this question 81 | - [Milestone Payload](https://github.com/iotaledger/protocol-rfcs/pull/19) 82 | - [Break in layer concept](https://github.com/iotaledger/protocol-rfcs/pull/19#discussion_r466194210) 83 | - We will keep the current solution. 84 | - DevOps requirements for COO private key 85 | - @Angelo schedule a call with Andrea 86 | - Ed25519 vs Ed448 87 | - Ed25519 has much better hardware/software support. The required additional security of Ed448 is not really necessary. 88 | - Quantum Robustness 89 | - Non quantum signature scheme is fine. 90 | - Security review 91 | - We should get a security review of the finalized RFCs. 92 | - Network ID 93 | - A uint64 is sufficient 94 | - It makes no sense to only have that in the MS payload. If desired it should be in the Message. 95 | - Milestone index 96 | - should be a `uint64` instead of a `varint` 97 | - @Angelo make discussed changes in the RFC and removed solved unanswered questions 98 | - [Tangle Messages](https://github.com/iotaledger/protocol-rfcs/pull/17) 99 | - PoW: See above; can (should) be migrated later 100 | - Examples: Serialized message with valid PoW 101 | - "Indexation" payload is important as it is relevant for certain use-cases. 102 | - We need to describe all payloads in more detail with example 103 | - @Gal will add (temporary) links section for all the missing payloads 104 | - @Gal consider adding a column with message / Tx payload or similar 105 | - `varint` and limits on lengths and counts 106 | - It is very difficult to find tight limits without knowledge of network usage, use-cases, dust prevention... 107 | - This is just a design decision or matter of personal preference. For all practical purposes both solutions will work. 108 | - Pros `varint` 109 | - Very flexible, no need at all to think about limits or choose larger bounds just to have bits reserved. 110 | - By far the most compact representation, as most of the times values will be small even for larger bounds. 111 | - Grammar is as simple as it gets. 112 | - Consistent with protobuf wire types. 113 | - We have dynamic arrays. Thus, the length will not be fixed anyways. 114 | - Cons `varint` 115 | - Elements don't have a fixed size. This prevents accessing array element without parsing. However, probably everything needs to be parsed anyway for validation. 116 | - Same value has different encodings depending on the number of leading zeros. This needs to be considered during validation/serialization. 117 | - When parsing varints into a struct, it needs to always reserve the largest possible type (probably uint32) anyway. 118 | - Parsing is slightly more compatible to implement than for fixed integer types. 119 | - Mixing `varint` with fixed size integer seems inconsistent. 120 | - @Wolfgang prepare two exemplified alternatives all `varint` vs. all fixed int. And put this to a vote. 121 | - [signed_transaction_payload](https://github.com/iotaledger/protocol-rfcs/pull/18) 122 | - Add examples once the types are finalized. 123 | 124 | -------------------------------------------------------------------------------- /meeting-minutes/2020-11-09.md: -------------------------------------------------------------------------------- 1 | # Chrysalis RFC Call - 2020-11-09 2 | 3 | ## Participants 4 | 5 | - Wolfgang 6 | - Andrea 7 | - Luca 8 | - Gal 9 | - Thibault 10 | 11 | ## Topics 12 | 13 | ### RFC Status 14 | 15 | #### Merged 16 | 17 | https://iotaledger.github.io/protocol-rfcs/ 18 | 19 | - [RFC-0005](https://github.com/iotaledger/protocol-rfcs/blob/master/text/0005-white-flag/0005-white-flag.md) (White Flag): 20 | - Remove old Bundle/Tx structure: 21 | - done: https://github.com/iotaledger/protocol-rfcs/pull/30 22 | - [RFC-0008](https://github.com/iotaledger/protocol-rfcs/blob/master/text/0008-weighted-uniform-random-tip-selection/0008-weighted-uniform-random-tip-selection.md) (Weighted URTS): 23 | - Everyone is happy with the changes to reflect the current implementation (in Hornet) 24 | - @all approve 25 | - [RFC-0012](https://github.com/iotaledger/protocol-rfcs/blob/master/text/0012-milestone-merkle-validation/0012-milestone-merkle-validation.md) (Milestone Validation): 26 | - Remove old Bundle/Tx structure: 27 | - State mutations -> UTXO mutations (circular transactions are not possible with UTXO) 28 | - Tx Hash -> Message ID 29 | - Blake2b-512 -> Blake2b-256 30 | - @Wolfgang create PR 31 | 32 | ### Open Questions 33 | 34 | #### `Network ID` field in the message 35 | 36 | - Purpose: 37 | - Distinguish between different (private) networks 38 | - Detect/handle breaking protocol changes independently of the network/peering layer 39 | - Prevent replays of the same message in different networks without PoW 40 | - Have network/version as part of the Message ID (for MSs, queries, ...) 41 | - Since the MS payload signs the Message IDs, replays of the MS payload to a different network is not possible. 42 | - Decision: 43 | - It should be included as a single message field. 44 | - It should encode the network (mainnet, testnet, private x, ...) as well as the protocol version. 45 | - It should be a `uint64`. This offers a good compromise between size and accidentally having the same value for incompatible situations. 46 | - Local snapshots (and probably peering) should use the same value. 47 | - It should not be signed to potentially allow replays of the same payload (but with different Message ID and new PoW). 48 | - Nodes should reject message with an incompatible `Network ID`. (What actually causes a protocol version bump is a case-by-case definition, but as a rule of thumb consensus changes are breaking.) 49 | - (Perma)nodes trying to sync across different protocol versions is a special case and does not need to be considered for regular nodes (same premise as when introducing white-flag). 50 | - How the `Network ID` is constructed is an implementation decision. It does not need to be part of the Message RFC, but it is still very relevant for the node implementations. Options: 51 | - Hash(`Network Name`+`Protocol Version`) (probably the most promising) 52 | - Use a couple of static bytes for the "Network" 53 | - Combination of the above 54 | - @Gal update the PR to include those changes 55 | - After that, [RFC-0025 (Local Snapshots)](https://github.com/iotaledger/protocol-rfcs/pull/25) needs to be adapted 56 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "iota-tips", 3 | "version": "0.0.0", 4 | "scripts": { 5 | "start": "iota-wiki start", 6 | "build": "iota-wiki build" 7 | }, 8 | "license": "UNLICENSED", 9 | "engines": { 10 | "node": ">=16.10.0" 11 | }, 12 | "devDependencies": { 13 | "@iota-wiki/cli": "latest" 14 | }, 15 | "packageManager": "yarn@3.2.0" 16 | } 17 | -------------------------------------------------------------------------------- /tip-template.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 3 | title: 4 | description: 5 | author: , FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername)> 6 | discussions-to: 7 | status: Draft 8 | type: 9 | layer (*only required for Standards Track): 10 | created: 11 | requires (*optional): 12 | replaces (*optional): 13 | superseded-by (*optional): 14 | --- 15 | 16 | This is the suggested template for new TIPs. 17 | 18 | Note that an TIP number will be assigned by an editor. When opening a pull request to submit your TIP, please use an abbreviated title in the filename, `tip-draft_title_abbrev.md`. 19 | 20 | The title should be 44 characters or less. It should not repeat the TIP number in title, irrespective of the category. 21 | 22 | ## Abstract 23 | Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read only the abstract to get the gist of what this specification does. 24 | 25 | ## Motivation 26 | The motivation section should describe the "why" of this TIP. What problem does it solve? Why should someone want to implement this standard? What benefit does it provide to the IOTA ecosystem? What use cases does this TIP address? 27 | 28 | ## Specification 29 | The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. 30 | 31 | The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current IOTA platforms (TODO: link to wiki). 32 | 33 | ## Rationale 34 | The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. 35 | 36 | ## Backwards Compatibility 37 | All TIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The TIP must explain how the author proposes to deal with these incompatibilities. TIP submissions without a sufficient backwards compatibility treatise may be rejected outright. 38 | 39 | ## Test Cases 40 | Test cases for an implementation are mandatory for TIPs that are affecting consensus changes. If the test suite is too large to reasonably be included inline, then consider adding it as one or more files in the TIPs directory. 41 | 42 | ## Reference Implementation 43 | An optional section that contains a reference/example implementation that people can use to assist in understanding or implementing this specification. If the implementation is too large to reasonably be included inline, then consider adding it as one or more files in the TIPs directory. 44 | 45 | ## Copyright 46 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 47 | -------------------------------------------------------------------------------- /tips/TIP-0002/tip-0002.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 2 3 | title: White Flag Ordering 4 | description: Mitigate conflict spamming by ignoring conflicts 5 | author: Thibault Martinez (@thibault-martinez) 6 | discussions-to: https://github.com/iotaledger/tips/pull/5, https://github.com/iotaledger/tips/pull/30 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2020-03-06 11 | --- 12 | 13 | # Summary 14 | 15 | This RFC is part of a set of protocol changes, [Chrysalis](https://roadmap.iota.org/chrysalis), aiming at improving the 16 | network before [Coordicide](https://coordicide.iota.org/) is complete. 17 | 18 | The feature presented in this RFC, White Flag, allows milestones to confirm conflicting messages by enforcing 19 | deterministic ordering of the Tangle and applying only the first message(s) that will not violate the ledger state. 20 | 21 | The content of this RFC is based on [Conflict white flag: Mitigate conflict spamming by ignoring conflicts](https://iota.cafe/t/conflict-white-flag-mitigate-conflict-spamming-by-ignoring-conflicts/233). 22 | 23 | # Motivation 24 | 25 | - Eliminates the [Conflict spamming attack](https://iota.cafe/t/conflict-spamming-attack/232); 26 | - As conflicts are ignored in the balance computation, they do not need to be considered during tip selection of the 27 | nodes allowing much easier tip selection algorithms leading to increased TPS; 28 | - By using this approach in combination with an appropriate TSA, during regular use, no honest message will ever 29 | require re-attaching leading to increased CTPS; 30 | - Does not come with added computation complexity by integrating nicely into already existing algorithms; 31 | 32 | # Detailed design 33 | 34 | First, let us define what it means for a message A to be: 35 | 36 | - referenced (indirectly or directly) by message B: A is contained in the past cone of B; 37 | - confirmed: A is referenced by a milestone; 38 | - applied: A is confirmed and applied to the ledger state; 39 | - ignored: A is confirmed but not applied because it is semantically invalid; 40 | - conflicting: A would lead to an invalid ledger state if applied; 41 | 42 | In case of conflicting messages with White Flag, a node applies only one message to the ledger state and ignores 43 | all the others. For this to work, all the nodes need to be sure they are all applying the same message; hence, the 44 | need for a deterministic ordering of the Tangle. 45 | 46 | First, this RFC proposes a deterministic ordering of the Tangle, then it explains which message is selected in case 47 | of conflicts. 48 | 49 | **Note: The past-cone of milestone can only contain syntactically valid messages. If an invalid message is encountered, 50 | operations must be stopped immediately.** 51 | 52 | ## Deterministically ordering the Tangle 53 | 54 | When a new milestone is broadcasted to the network, nodes will need to order the set of messages it confirms. 55 | 56 | A subset of the Tangle can be ordered depending on many of its properties (e.g. alphanumeric sort of the message 57 | hashes); however, to compute the ledger state, a graph traversal has to be done so it can be used to order the messages 58 | in a deterministic order with no extra overhead. 59 | 60 | This ordering is then defined as a [topological ordering](https://en.wikipedia.org/wiki/Topological_sorting) because 61 | it respects the dependency of messages, ensuring that parents of a message are applied before it. 62 | Since there are multiple valid topological orders for the same graph and, to avoid conflicting ledger states, it 63 | is required that all nodes apply messages in the exact same order. 64 | 65 | For this reason, this RFC proposes an order that has to be rigorously followed by all node implementations. 66 | This order is the topological ordering generated by a post-order [Depth-First Search (DFS)](https://en.wikipedia.org/wiki/Depth-first_search) 67 | starting from a milestone message, going through its parents (in the order they appear in the message) and finally 68 | analysing the current message. Since only a subset of messages is considered, the stopping condition of this DFS is 69 | reaching messages that are already confirmed by another milestone. 70 | 71 | ## Applying first message(s) that does not violate the ledger state 72 | 73 | If a conflict is occurring in the set of messages confirmed by a milestone, nodes have to apply the first - with regards 74 | to the order previously proposed - of the conflicting messages to the ledger and ignore all the others. 75 | 76 | Once a message is marked as ignored, this is final and cannot be changed by a later milestone. 77 | 78 | Since the ledger state is maintained from one milestone to another, a message conflicting with a message already 79 | confirmed by a previous milestone would also be ignored. 80 | 81 | ## Pseudo-code 82 | 83 | The following algorithm describes the process of updating the ledger state which is usually triggered by the arrival of 84 | a new milestone confirming many new messages. 85 | 86 | Pseudo-code means that implementation details such as types, parameters, ..., are not important but that the logic has 87 | to be followed with care when implementing a node to avoid differences in the ledger state. 88 | 89 | ``` 90 | update_ledger_state(ledger, milestone, solid_entry_points) { 91 | s = new Stack() 92 | visited = new Set() 93 | 94 | s.push(milestone) 95 | 96 | while (!s.is_empty()) { 97 | curr = s.peek() 98 | next = null 99 | 100 | // Look for the first eligible parent that was not already visited 101 | for parent in curr.parents { 102 | if (!solid_entry_points.contains(parent) && !parent.confirmed && !visited.contains(parent)) { 103 | next = parent 104 | break 105 | } 106 | } 107 | 108 | // All parents have been visited, apply and visit the current message 109 | if next == null { 110 | ledger.apply(curr) 111 | visited.add(curr) 112 | s.pop() 113 | } 114 | // Otherwise, go to the parent 115 | else { 116 | s.push(next) 117 | } 118 | } 119 | } 120 | ``` 121 | 122 | **Notes**: 123 | - `solid_entry_points` is a set of hashes that are considered solid even though we do not have them or their past in 124 | a database. They often come from a snapshot file and allow a node to solidify without needing the full tangle history. 125 | The hash of the genesis message is also a solid entry point. 126 | - `confirmation_index` is the index of the milestone that confirmed the message. 127 | 128 | ### Example 129 | 130 | In this example, there are 26 messages labeled from `A` to `Z`. 131 | The set of red messages `{A, B, C, E, F, H}` is confirmed by milestone `H`. 132 | The set of purple messages `{D, G, J, L, M, N, K, I, O, S, R, V}` is confirmed by milestone `V`. 133 | The set of blue messages `{Q, U, X, Y, Z, W, T, P}` is confirmed by another milestone. 134 | 135 | ![][Tangle] 136 | 137 | Applying the previously shown algorithm on the purple set produces the topological order 138 | `{D, G, J, L, M, R, I, K, N O, S, V}`. 139 | 140 | ![][Tangle-conflict] 141 | 142 | Here, message `G` and message `O`, both confirmed by milestone `V`, are conflicting. Since in the topological order just 143 | produced, `G` appears before `O`, `G` is applied to the ledger and `O` is ignored. 144 | 145 | # Drawbacks 146 | 147 | - The ledger state is now only well-defined at milestones, meaning that we have to wait until each milestone is 148 | issued in order to confirm a spend; 149 | - Everything that is seen is now part of the Tangle, including double-spend attempts, meaning that malicious data will 150 | now be saved as part of the consensus set of the Tangle; 151 | - To prove that a specific (non-milestone) message is valid, it is no longer sufficient to just provide the "path" 152 | to its confirming milestone, but instead all messages in its past cone. 153 | 154 | # Rationale and alternatives 155 | 156 | The main alternative to White Flag is what has been done so far i.e. not allowing conflicting messages confirmation. 157 | As explained in this RFC, this comes with added complexity when performing a Tip Selection Algorithm because a node has 158 | to constantly check for ledger inconsistencies. 159 | 160 | As part of Chrysalis and coupled with an adequate Tip Selection Algorithm, White Flag is an improvement of the network 161 | by allowing a potential increase of TPS/CTPS. 162 | 163 | # Unresolved questions 164 | 165 | A node consumes and produces snapshot files and bases the computation of its ledger state on them. In the current 166 | network, if one of these files was tampered with and fed to a node, it would eventually lead to an invalid ledger state 167 | where a message confirmed by a milestone would actually be a double spend. This situation would be detected by the node 168 | and it would stop its activities as a security measure. However, with White Flag, such messages would be confirmed by 169 | milestones but ignored by the node, the fake snapshot then going unnoticed. The ledger state would then become more and 170 | more corrupted and the view of the balances completely wrong, errors just accumulating over time. The need for a 171 | snapshot verification mechanism is then amplified by the implementation of White Flag. This mechanism being out of the 172 | scope of this RFC, it will be described in another RFC. 173 | 174 | # Copyright 175 | 176 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 177 | 178 | [Tangle]: tangle.svg 179 | [Tangle-conflict]: tangle-conflict.svg 180 | -------------------------------------------------------------------------------- /tips/TIP-0003/cnf_tx_roots.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0003/cnf_tx_roots.PNG -------------------------------------------------------------------------------- /tips/TIP-0003/otrsi_ytrsi.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0003/otrsi_ytrsi.PNG -------------------------------------------------------------------------------- /tips/TIP-0003/tip-0003.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 3 3 | title: Uniform Random Tip Selection 4 | description: Perform fast tip-selection to increase message throughput 5 | author: Luca Moser (@luca-moser) 6 | discussions-to: https://github.com/iotaledger/tips/pull/8 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2020-03-09 11 | --- 12 | 13 | # Summary 14 | 15 | Weighted Uniform Random Tip Selection on a subset enables a node to perform fast tip-selection to increase message throughput. 16 | The algorithm selects tips which are non-lazy to maximize confirmation rate. 17 | 18 | # Motivation 19 | 20 | Because of the `white-flag` confirmation algorithm, it is no longer necessary to perform complex 21 | tip-selection which evaluates ledger mutations while walking. Therefore, a more simple, better 22 | performing algorithm can be used to select tips, which in turn increases overall message throughput. 23 | 24 | To maximize confirmation rate however, the algorithm needs to return tips which are `non-lazy`. 25 | Non-lazy in this context means that a tip does not attach to a cone of messages which is too far 26 | in the past. Such a cone is likely to be already confirmed and does not contribute to the 27 | rate of newly confirmed messages when a milestone is issued. 28 | 29 | # Detailed design 30 | 31 | Definitions: 32 | * `Direct Approvers` - The set of messages which directly approve a given message. 33 | * `Approvee` - The directly approved message of a given message. 34 | * `Solid Message` - A message that its past cone is known to the node. 35 | * `Valid Message`- A message which is syntactically valid. 36 | * `Tip` - A valid solid message that doesn't have approvers. Its past cone contains only valid messages. 37 | * `Score` - An integer assigned to a `tip`. The tip selection algorithm uses it to determine how to select tips. 38 | * `Confirmed Root Message` - The set of first seen messages which are confirmed by a previous milestone 39 | when we walk the past cone of a given message. The walk stops on a confirmed message. 40 | Note that the red marked milestone is also a `Confirmed Root Message`. 41 | ![sdf](cnf_tx_roots.PNG) 42 | * `Message Snapshot Index (MSI)` defines the index of the milestone which confirmed a given message. 43 | * `Oldest Message Root Snapshot Index (OMRSI)` defines the lowest milestone index of a set of 44 | `Confirmed Root Messages` of a given messages. 45 | * `Youngest Message Root Snapshot Index (YMRSI)` defines the highest milestone index of a set of 46 | `Confirmed Root Messages` of a given message. 47 | * `Latest Solid Milestone Index (LSMI)` the index of the latest solid milestone. 48 | * `Below Max Depth (BMD)` defines a threshold value up on which it is decided on whether a message is not 49 | relevant in relation to the recent parts of the Tangle. The current `BMD` for mainnet nodes is 15 milestones, 50 | which means that messages of which their `OMRSI` in relation to the `LSMI` is more than 15, are "below max depth". 51 | 52 | ### OMRSI / YMRSI example 53 | Given the blue PoV message, the `OMRSI` of it is milestone 1 and `YMRSI` milestone 2. 54 | Note that, here again, the milestones are also `Confirmed Root Messages`. 55 | ![sdf](otrsi_ytrsi.PNG) 56 | 57 | ### Milestone based tip scoring 58 | 59 | The milestone based scoring defines a tip's score by investigating the tip's relation to 60 | the cone it approves and previous issued milestones. 61 | 62 | A tip can have one of 3 score states: 63 | * `0`: The tip is lazy and should not be selected. 64 | * `1`: The tip is somewhat lazy. 65 | * `2`: The tip is a non-lazy tip. 66 | 67 | Definitions: 68 | * `C1`: Max allowed delta value for the `YMRSI` of a given message in relation to the current `LSMI`. 69 | * `C2`: Max allowed delta value between `OMRSI` of a given message in relation to the current `LSMI`. 70 | * `M`: Max allowed delta value between `OMRSI` of the given message in relation to the current `LSMI`. 71 | `M` is the `below max depth (BMD)` parameter. 72 | 73 | Recommended defaults: 74 | * `C1` = 8 milestones 75 | * `C2` = 13 milestones 76 | * `M` = 15 milestones 77 | 78 | Scoring Algorithm (pseudo code): 79 | ``` 80 | 81 | enum Score ( 82 | LAZY = 0 83 | SEMI_LAZY = 1 84 | NON_LAZY = 2 85 | ) 86 | 87 | const ( 88 | C1 = 8 89 | C2 = 13 90 | M = 15 91 | ) 92 | 93 | func score(tip Tip) Score { 94 | 95 | // if the LSMI to YMRSI delta is over C1, then the tip is lazy 96 | if (LSMI - YMRSI(tip) > C1) { 97 | return Score.LAZY 98 | } 99 | 100 | // if the OMRSI to LSMI delta is over M/below-max-depth, then the tip is lazy 101 | if (LSMI - OMRSI(tip) > M) { 102 | return Score.LAZY 103 | } 104 | 105 | if (LSMI - OMRSI(tip) > C2) { 106 | return Score.SEMI_LAZY 107 | } 108 | 109 | return Score.NON_LAZY 110 | } 111 | ``` 112 | 113 | ### Random Tip-Selection 114 | 115 | A node should keep a set of non-lazy tips (score 2). 116 | Every time a node is asked to select tips to be approved, it will pick randomly from the set. 117 | A node must not execute tip-selection if it is not synchronized. 118 | 119 | A tip should not be removed from the tips set immediately after it was selected in `select()`, to make it possible for it to be re-selected, which in turn makes the Tangle wider 120 | and improves synchronization speed. A tip is removed from the tips set if `X` amount of direct 121 | approvers are reached or if a certain amount of time `T` passed. 122 | It is recommended to use `X` = 2 and `T` = 3 but the threshold should be configurable. 123 | 124 | ### Purpose Of Semi-Lazy Tips 125 | 126 | Semi-Lazy tips are not eligible for tip-selection, but the coordinator node may implement a tip selection algorithm 127 | that confirms semi-lazy tips. Semi-lazy tips will usually be left behind, but parties interested in having them confirmed 128 | are incentivized to run spammers that will actively reduce the amount of semi-lazy tips eligible for coordinator's tip selection. 129 | Given a coordinator that chooses semi-lazy tips, running such spammers may get those messages confirmed before 130 | they become lazy. 131 | 132 | 133 | # Drawbacks 134 | 135 | Depending on when and how often `YMRSI`/`OMRSI` values are computed, this tip-selection could still 136 | have a slow runtime, as one would need to constantly walk down the Tangle to compute those 137 | values. However, smart caching might resolve this issue. 138 | 139 | # Rationale and alternatives 140 | 141 | The previous tip-selection was written in accordance to the original IOTA whitepaper, as it also 142 | functioned as part of the consensus mechanism. 143 | However, relatively soon it became apparent that the cumulative weight computation was too heavy 144 | for an actual high throughput scenario and, as such, the CW calculation is currently not used within 145 | node implementations at all. 146 | 147 | Because confirmations with the [white-flag](../TIP-0002/tip-0002.md) approach no longer approve cones only with state mutations, 148 | which are consistent with a previous ledger state, it makes sense to alter the tip-selection to provide 149 | a fast way to get tips to approve with one's own message. 150 | The only important thing is to disincentive lazy behaviour to be able to maximize confirmation rate. 151 | 152 | # Unresolved questions 153 | 154 | #### When to compute the score and `YMRSI`/`OMRSI` of a transaction? 155 | It is not yet clear when or how often the `YMRSI`/`OMRSI` values of a transaction should be updated. 156 | If the values are only computed once after a transaction became solid, the `YMRSI`/`OMRSI` might not 157 | resemble the true values, as subsequent milestones might confirm transactions within the same cone the 158 | given transaction approved. 159 | 160 | Currently, we suggest recomputing the values every time a new milestone solidifies. 161 | Since different tips indirectly reference the same transactions, this computation can be optimized. 162 | 163 | # Copyright 164 | 165 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 166 | -------------------------------------------------------------------------------- /tips/TIP-0004/tip-0004.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 4 3 | title: Milestone Merkle Validation 4 | description: Add Merkle tree hash to milestone for local ledger state verification 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/12, https://github.com/iotaledger/tips/pull/31 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2020-05-04 11 | --- 12 | 13 | # Summary 14 | 15 | In the IOTA protocol, nodes use the milestones issued by the Coordinator to reach a consensus on which transactions are confirmed. This RFC adds extra information to each milestone in the form of a Merkle tree hash, which allows nodes to explicitly validate their local view of the ledger state against the Coordinator's. This mechanism further enables a simple cryptographic proof of inclusion for transactions confirmed by the particular milestone. 16 | 17 | # Motivation 18 | 19 | With the changes proposed in the IOTA protocol [TIP-2](../TIP-0002/tip-0002.md), milestones are allowed to reference conflicting transactions. These conflicts are then resolved by traversing the newly confirmed transactions in a global, deterministic order and applying the corresponding ledger state changes in that order. Conflicts or invalid transactions are ignored, but stay in the Tangle. 20 | This approach has considerable advantages in terms of network security (e.g. protection against [conflict spamming attacks](https://iota.cafe/t/conflict-spamming-attack/232)) and network performance. However, a milestone no longer represents the inclusion state of all its referenced transactions, but only marks the order in which transactions are checked against the ledger state and then, if not violating, applied. This has two significant drawbacks: 21 | - Milestone validation: In the IOTA protocol, each node always compares the milestones issued by the Coordinator against its current ledger state. Discrepancies are reported and force an immediate halt of the node software. However, in the white flag proposal this detection is no longer possible as any milestone can lead to a valid ledger state by ignoring the corresponding violating ledger changes. 22 | - Proof of inclusion: In the pre-white-flag protocol, the inclusion of transaction t in the Tangle, and thus, the ledger, can be shown by providing an audit path of referencing transactions from t to its confirming milestone. In the white flag proposal this is no longer possible, as such an audit path does not provide any information on whether the transaction has been included or ignored. 23 | 24 | Note that the white flag proposal only changes the behavior of conflicting transactions. Messages without a transaction payload can never conflict and are thus always included in Tangle when they are first referenced by a milestone. As such, these messages do not need to be considered by the RFC and their processing and inclusion proof remain unchanged. 25 | 26 | Where previously the structure of the Tangle alone was sufficient to address those issues, this RFC proposes to add the Merkle tree hash of all the valid (i.e. not ignored) newly confirmed transactions to the signed part of a milestone. This way, each IOTA node can check that the hash matches its local ledger state changes or provide a Merkle audit path for that milestone to prove the inclusion of a particular transaction. 27 | 28 | # Detailed design 29 | 30 | ## Creating a Milestone 31 | 32 | - Perform tip selection to choose the parents referenced by the milestone. 33 | - Determine the topological order according to [TIP-2](../TIP-0002/tip-0002.md) of the referenced messages that are not yet confirmed by a previous milestone. 34 | - Construct the list D consisting of the message IDs of all the not-ignored state-mutating transaction payloads in that particular order. A UTXO transaction is considered state-mutating, if it creates a new output. 35 | - Compute the 32-byte Merkle tree hash H = MTH(D). 36 | - Prepare the milestone payload as described in [TIP-8](../TIP-0008/tip-0008.md), where the field `Inclusion Merkle Root` is set to H. 37 | 38 | ## Milestone validation 39 | 40 | - Verify the signature of the milestone m. 41 | - Construct the ordered list D of the message IDs of all the not-ignored state-mutating transaction payloads m confirms. 42 | - Compute H = MTH(D). 43 | - Verify that the field `Inclusion Merkle Root` in m matches H. 44 | 45 | ## Proof of inclusion 46 | 47 | - Identify the confirming milestone m of the input transaction t. 48 | - Determine the ordered list of the not-ignored messages m confirms. 49 | - Compute the Merkle audit path of t with respect to the Merkle tree for this ordered list. 50 | - Provide the audit path as well as m as proof of inclusion for t. 51 | 52 | ## Cryptographic components 53 | 54 | ### Merkle hash trees 55 | 56 | This RFC uses a binary Merkle hash tree for efficient auditing. In general, any cryptographic hashing algorithm can be used for this. However, we propose to use [BLAKE2b-256](https://tools.ietf.org/html/rfc7693), as it provides a faster and more secure alternative to the widely used SHA-256. 57 | In the following we define the Merkle tree hash (MTH) function that returns the hash of the root node of a Merkle tree: 58 | - The input is a list of binary data entries; these entries will be hashed to form the leaves of the tree. 59 | - The output is a single 32-byte hash. 60 | 61 | Given an ordered list of n input strings Dn = {d1, d2, ..., dn}, the Merkle tree hash of D is defined as follows: 62 | - If D is an empty list, MTH(D) is the hash of an empty string:
63 | MTH({}) = BLAKE2(). 64 | - If D has the length 1, the hash (also known as a leaf hash) is:
65 | MTH({d1}) = BLAKE2( 0x00 || d1 ). 66 | - Otherwise, for Dn with n > 1: 67 | - Let k be the largest power of two less than n, i.e. k < n ≤ 2k. 68 | - The Merkle tree hash can be defined recursively:
69 | MTH(Dn) = BLAKE2( 0x01 || MTH({d1, ..., dk}) || MTH({dk+1, ..., dn}) ). 70 | 71 | Note that the hash calculations for leaves and nodes differ. This is required to provide second preimage resistance: Without such a prefix, for a given input D an attacker could replace two (or more) leaves with their corresponding aggregated node hash without changing the final value of MTH(D). This violates the fundamental assumption that, given MTH(D), it should be practically impossible to find a different input D' leading to the same value. Adding a simple prefix mitigates this issue, since now leaf and node hashes are computed differently and can no longer be interchanged. 72 | 73 | Note that we do not require the length of the input to be a power of two. However, its shape is still uniquely determined by the number of leaves. 74 | 75 | ### Merkle audit paths 76 | 77 | A Merkle audit path for a leaf in a Merkle hash tree is the shortest list of additional nodes in a Merkle tree required to compute the Merkle tree hash for that tree. At each step towards the root, a node from the audit path is combined with a node computed so far. If the root computed from the audit path matches the Merkle tree hash, then the audit path is proof that the leaf exists in the tree. 78 | 79 | ## Example 80 | 81 | Merkle tree with 7 leaves: 82 | - input D: 83 | 1. 52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649 84 | 1. 81855ad8681d0d86d1e91e00167939cb6694d2c422acd208a0072939487f6999 85 | 1. eb9d18a44784045d87f3c67cf22746e995af5a25367951baa2ff6cd471c483f1 86 | 1. 5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621 87 | 1. 6325253fec738dd7a9e28bf921119c160f0702448615bbda08313f6a8eb668d2 88 | 1. 0bf5059875921e668a5bdf2c7fc4844592d2572bcd0668d2d6c52f5054e2d083 89 | 1. 6bf84c7174cb7476364cc3dbd968b0f7172ed85794bb358b0c3b525da1786f9f 90 | - Merkle tree hash H = MTH(D) (32-byte): bf67ce7ba23e8c0951b5abaec4f5524360d2c26d971ff226d3359fa70cdb0beb 91 | 92 | ``` 93 | root: bf67ce7ba23e8c0951b5abaec4f5524360d2c26d971ff226d3359fa70cdb0beb 94 | ├─ node: 03bcbb3cf4314eab2f5ae68c767ff0a5fec4573c865728231f71d596fd867b56 95 | │ ├─ node: ae4505f4cfae93586e23958ca88d35d2f34d43def49786b6d0d4224b819f4cda 96 | │ │ │ ┌ msg id: 52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c649 97 | │ │ ├──┴ leaf: 3d1399c64ff0ae6a074afa4cd2ce4eab8d5c499c1da6afdd1d84b7447cc00544 98 | │ │ │ ┌ msg id: 81855ad8681d0d86d1e91e00167939cb6694d2c422acd208a0072939487f6999 99 | │ │ └──┴ leaf: 83b0b255014e9a3656f0004a3f17943a20b715ef9c3e7cb85a6b2abac15e00d0 100 | │ └─ node: 54d51291aca22ce5b04cd3e6584fa3026ebe86ef86f0a6dfb47ab843801d4b38 101 | │ │ ┌ msg id: eb9d18a44784045d87f3c67cf22746e995af5a25367951baa2ff6cd471c483f1 102 | │ ├──┴ leaf: ad4bc0a34b27f37810f2ff3a8177ecc98402f8f59a06270f9d285fdf764e45fe 103 | │ │ ┌ msg id: 5fb90badb37c5821b6d95526a41a9504680b4e7c8b763a1b1d49d4955c848621 104 | │ └──┴ leaf: ffb3a7c6bea8f9fdcfb26f4701ad6e912a6076e1a40663607dbe110ebfc9a571 105 | └─ node: ce22d5bc728023e7ab6a9eb8f58baf62b9565fc8baeef4b377daa6709dbe598c 106 | ├─ node: e14c8af1258005cd0dbed88f0c5885c6988f319bb8f24272a7495592b873c169 107 | │ │ ┌ msg id: 6325253fec738dd7a9e28bf921119c160f0702448615bbda08313f6a8eb668d2 108 | │ ├──┴ leaf: 1c062628a7a147cc6a4defa655ce6c4ae5b838b4b4cd81b12e8924b5b4b5cca6 109 | │ │ ┌ msg id: 0bf5059875921e668a5bdf2c7fc4844592d2572bcd0668d2d6c52f5054e2d083 110 | │ └──┴ leaf: 2ef4e2ad06b8c8ae1fd4b28b5ed166829533fbfff1f6c14218358537da277fa3 111 | │ ┌ msg id: 6bf84c7174cb7476364cc3dbd968b0f7172ed85794bb358b0c3b525da1786f9f 112 | └──┴ leaf: 7ec774ebc33ed4ca298e8a1cf1f569e36c6784467d63b055efd7612abe2858a4 113 | ``` 114 | 115 | # Drawbacks 116 | 117 | - The computation of the Merkle tree hash of Dn requires 2n-1 evaluations of the underlying hashing algorithm. This makes the milestone creation and validation computationally slightly more expensive. 118 | 119 | # Rationale and alternatives 120 | 121 | It is a crucial security feature of the IOTA network that nodes are able to validate the issued milestones. As a result, if the Coordinator were to ever send an invalid milestone, such as one that references counterfeit transactions, the rest of the nodes would not accept it. In a pure implementation of [TIP-2](../TIP-0002/tip-0002.md) this feature is lost and must be provided by external mechanisms. 122 | A Merkle tree hash provides an efficient, secure and well-established method to compress the information about the confirmed transactions in such a way, that they fit in the milestone transaction. 123 | 124 | In this context, it could also be possible to use an unsecured checksum (such as CRCs) of the message IDs instead of a Merkle tree hash. However, the small benefit of faster computation times does no justify the potential security risks and attack vectors. 125 | 126 | # Reference implementation 127 | 128 | Example Go implementation in [wollac/iota-crypto-demo](https://github.com/Wollac/iota-crypto-demo): 129 | - Merkle tree computation of message IDs: [pkg/merkle/merkle.go](https://github.com/Wollac/iota-crypto-demo/blob/master/pkg/merkle/merkle.go) 130 | - Example: [examples/merkle/pt2](https://github.com/Wollac/iota-crypto-demo/tree/master/examples/merkle/pt2) 131 | 132 | # Copyright 133 | 134 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 135 | -------------------------------------------------------------------------------- /tips/TIP-0005/tip-0005.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 5 3 | title: Binary To Ternary Encoding 4 | description: Define the conversion between binary and ternary data 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/15 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2020-06-08 11 | --- 12 | 13 | # Summary 14 | 15 | In the IOTA protocol, a transaction is represented as ternary data. However, sometimes it is necessary to store binary data (e.g. the digest of a binary hash function) inside of a transaction. This requires the conversion of binary into ternary strings. 16 | The IOTA client libraries support the opposite conversion that encodes 5 trits as 1 byte (sometimes also referred to as `t5b1` encoding), which is used for network communication and in storage layers. This RFC describes the corresponding counterpart to encode 1 byte as 6 trits. 17 | 18 | # Motivation 19 | 20 | A byte is composed of 8 bits that can represent 28 = 256 different values. On the other hand, 6 trits can hold 36 = 729 values while 5 trits can hold 35 = 243 values. Therefore, the most memory-efficient way to encode one byte requires the use of 6 trits. Although there exist many potential encoding schemes to convert binary data into ternary, the proposed version has been designed to directly match the widely used `t5b1` encoding. 21 | 22 | It is important to note that the `b1t6` encoding presented in this RFC does not replace the current `t5b1` encoding (or its corresponding decoding): `t5b1` is for example used to store trytes in a binary database, while `b1t6` will be used to attach binary data to an IOTA transaction. 23 | 24 | # Detailed design 25 | 26 | ### Bytes to trits 27 | In order to encode a binary string S into ternary, each byte of S is interpreted as a signed (two's complement) 8-bit integer value v. Then, v is encoded as a little-endian 6-trit string in balanced ternary representation. Finally, the resulting groups of trits are concatenated. 28 | 29 | This algorithm can also be described using the following pseudocode: 30 | ``` 31 | T ← [] 32 | foreach byte b in S: 33 | v ← int8(b) 34 | g ← IntToTrits(v, 6) 35 | T ← T || g 36 | ``` 37 | 38 | Here, the function `IntToTrits` converts a signed integer value into its corresponding balanced ternary representation in little-endian order of the given length. The functionality of `IntToTrits` exactly matches the one used to e.g. encode the transaction values as trits in the current IOTA protocol. 39 | 40 | ### Trits to bytes 41 | 42 | Given a trit string T as the result of the previous encoding, T is converted back to its original byte string S by simply reversing the conversion: 43 | ``` 44 | S ← [] 45 | foreach 6-trit group g in T: 46 | v ← TritsToInt(g) 47 | b ← byte(v) 48 | S ← S || b 49 | ``` 50 | 51 | ## Examples 52 | 53 | - I 54 | - binary (hex): `00` 55 | - ternary (trytes): `99` 56 | - II 57 | - binary (hex): `0001027e7f8081fdfeff` 58 | - ternary (trytes): 59 | `99A9B9RESEGVHVX9Y9Z9` 60 | - III 61 | - binary (hex): `9ba06c78552776a596dfe360cc2b5bf644c0f9d343a10e2e71debecd30730d03` 62 | - ternary (trytes): `GWLW9DLDDCLAJDQXBWUZYZODBYPBJCQ9NCQYT9IYMBMWNASBEDTZOYCYUBGDM9C9` 63 | 64 | # Drawbacks 65 | 66 | - Conceptually, one byte can be encoded using log3(256) ≈ 5.0474 trits. Thus, encoding 1 byte as 6 trits consumes considerably more memory than the mathematical minimum. 67 | - Depending on the actual implementation the conversion might be malleable: E.g. since `byte(-1) = 0xff` and `byte(255) = 0xff`, both `Z9` (-1) and `LI`(255) could be decoded as `ff`. However, `LI` can never be the result of a valid `b1t6` encoding. As such, the implementation must reject such invalid inputs. 68 | 69 | # Rationale and alternatives 70 | 71 | There are several ways to convert binary data into ternary, e.g. 72 | - the conversion used as part of the [Kerl](https://github.com/iotaledger/kerl/blob/master/IOTA-Kerl-spec.md) hash function encoding chunks of 48 bytes as 242 trits, 73 | - or by encoding each bit as one trit with the corresponding value. 74 | 75 | The current client libraries do not provide any functionality to convert an arbitrary amount of bytes into trits. The closest available functionality is the ASCII to trit conversion, which is used for human-readable messages in transactions: 76 | ``` 77 | T ← [] 78 | foreach char c in S: 79 | first ← uint8(c) mod 27 80 | second ← (uint8(c)-first) / 27 81 | T ← T || IntToTrits(first, 3) || IntToTrits(second, 3) 82 | ``` 83 | This function can be adapted to encode any general byte string. However, the conversion seems rather arbitrary and the algorithm is computationally more intense than the proposed solution. 84 | On the other hand, using the algorithm from this RFC also for the conversion of ASCII messages would break backward compatibility, which is also undesirable. 85 | 86 | Each conversion method has different advantages and disadvantages. However, since the `t5b1` encoding is well-defined and has been used in [IRI](https://github.com/iotaledger/iri) for both network communications and storage layers for a long time, choosing the direct counterpart for the opposite conversion represents the most logical solution providing a nice balance between performance and memory-efficiency. 87 | 88 | # Reference implementation 89 | 90 | Example Go implementation in [wollac/iota-crypto-demo](https://github.com/Wollac/iota-crypto-demo): 91 | - Binary-to-Ternary Encoding: [pkg/encoding/ternary/ternary.go](https://github.com/Wollac/iota-crypto-demo/blob/master/pkg/encoding/ternary/ternary.go) 92 | 93 | # Copyright 94 | 95 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 96 | -------------------------------------------------------------------------------- /tips/TIP-0006/tip-0006.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 6 3 | title: Tangle Message 4 | description: Generalization of the Tangle transaction concept 5 | author: Gal Rogozinski (@GalRogozinski) 6 | discussions-to: https://github.com/iotaledger/tips/pull/17 7 | status: Replaced 8 | type: Standards 9 | layer: Core 10 | created: 2020-07-28 11 | superseded-by: TIP-24 12 | --- 13 | 14 | + Changelog: 15 | + ([iotaledger/tips#0037](https://github.com/iotaledger/tips/pull/0037)) Fixed internal links 16 | 17 | # Summary 18 | 19 | The Tangle is the graph data structure behind IOTA. In the current IOTA protocol, the vertices of the Tangle are represented by transactions. This document proposes an abstraction of this idea where the vertices are generalized *messages*, which then contain the transactions or other structures that are processed by the IOTA protocol. Just as before, each message directly approves other messages, which are known as _parents_. 20 | 21 | The messages can contain payloads. These are core payloads that will be processed by all nodes as part of the IOTA protocol. Some payloads may have other nested payloads embedded inside. Hence, parsing is done layer by layer. 22 | 23 | # Motivation 24 | 25 | To better understand this layered design, consider the Internet Protocol (IP), for example: There is an Ethernet frame that contains an IP payload. This in turn contains a TCP packet that encapsulates an HTTP payload. Each layer has a certain responsibility and once this responsibility is completed, we move on to the next layer. 26 | 27 | The same is true with how messages are parsed. The outer layer of the message enables the mapping of the message to a vertex in the Tangle and allow us to perform some basic validation. The next layer may be a transaction that mutates the ledger state, and one layer further may provide some extra functionality on the transactions to be used by applications. 28 | 29 | By making it possible to add and exchange payloads, an architecture is being created that can easily be extended to accommodate future needs. 30 | 31 | # Detailed design 32 | 33 | ## Structure 34 | 35 | ### Message ID 36 | 37 | The *Message ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized message. 38 | 39 | ### Serialized layout 40 | 41 | The following table describes the serialization of a _Message_ following the notation from [RFC-0041](https://iotaledger.github.io/protocol-rfcs/0041-serialization-primitives/0041-serialization-primitives.html): 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 116 | 117 | 118 | 119 | 120 | 121 | 122 |
NameTypeDescription
Network IDuint64Network identifier. This field denotes whether the message was meant for mainnet, testnet, or a private net. It also marks what protocol rules apply to the message. Usually, it will be set to the first 8 bytes of the BLAKE2b-256 hash of the concatenation of the network type and the protocol version string.
Parents Countuint8The number of messages that are directly approved.
Parents anyOf 62 |
63 | Parent 64 |
65 | References another directly approved message. 66 |
67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 |
NameTypeDescription
Message IDByteArray[32]The Message ID of the parent.
79 |
80 |
Payload Lengthuint32The length of the following payload in bytes. A length of 0 means no payload will be attached.
Payload oneOf 90 |
91 | Generic Payload 92 |
93 | An outline of a generic payload 94 |
95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 107 | 108 | 109 | 110 | 111 | 112 | 113 |
NameTypeDescription
Payload Typeuint32 105 | The type of the payload. It will instruct the node how to parse the fields that follow. 106 |
Data FieldsANYA sequence of fields, where the structure depends on Payload Type.
114 |
115 |
Nonceuint64The nonce which lets this message fulfill the PoW requirement.
123 | 124 | 125 | ## Message validation 126 | 127 | The following criteria defines whether the message passes the syntactical validation: 128 | 129 | - The total message size must not exceed 32 KiB (32 * 1024 bytes). 130 | - Parents: 131 | - `Parents Count` must be at least 1 and not larger than 8. 132 | - `Parents` must be sorted in lexicographical order. 133 | - Each `Message ID` must be unique. 134 | - Payload (if present): 135 | - `Payload Type` must match one of the values described under [Payloads](#payloads). 136 | - `Data fields` must be correctly parsable in the context of the `Payload Type`. 137 | - The payload itself must pass syntactic validation. 138 | - `Nonce` must be a valid solution of the message PoW as described in [TIP-12](../TIP-0012/tip-0012.md). 139 | - There must be no trailing bytes after all message fields have been parsed. 140 | 141 | ## Payloads 142 | 143 | While messages without a payload, i.e. `Payload Length` set to zero, are valid, such messages do not contain any information. As such, messages usually contain a payload. The detailed specification of each payload type is out of scope of this RFC. The following table lists all currently specified payloads that can be part of a message and links to their specification. The _indexation payload_ will be specified here as an example: 144 | 145 | | Payload Name | Type Value | TIP | 146 | | ------------ | ---------- | ------------------------------------------------------------------------------------------------------------- | 147 | | Transaction | 0 | [TIP-7](../TIP-0007/tip-0007.md) | 148 | | Milestone | 1 | [TIP-8](../TIP-0008/tip-0008.md) | 149 | | Indexation | 2 | [TIP-6](#indexation-payload) | 150 | 151 | ### Indexation payload 152 | 153 | This payload allows the addition of an index to the encapsulating message, as well as some arbitrary data. Nodes will expose an API that allows to query messages by index. 154 | 155 | The structure of the indexation payload is as follows: 156 | 157 | | Name | Type | Description | 158 | | ------------ | ----------------------- | ------------------------------------------------------------- | 159 | | Payload Type | uint32 | Set to value 2 to denote an Indexation Payload. | 160 | | Index Length | uint16 | The length of the following index field in bytes. | 161 | | Index | ByteArray[Index Length] | The index key of the message | 162 | | Data | ByteArray | Binary data. | 163 | 164 | Note that `Index` field must be at least 1 byte and not longer than 64 bytes for the payload to be valid. The `Data` may have a length of 0. 165 | 166 | ## Example 167 | 168 | Below is the full serialization of a valid message with an indexation payload. The index is the "IOTA" ASCII string and the data is the "hello world" ASCII string. Bytes are expressed as hexadecimal numbers. 169 | 170 | - Network ID (8-byte): `0000000000000000` (0) 171 | - Parents Count (1-byte): `02` (2) 172 | - Parents (64-byte): 173 | - `210fc7bb818639ac48a4c6afa2f1581a8b9525e20fda68927f2b2ff836f73578` 174 | - `db0fa54c29f7fd928d92ca43f193dee47f591549f597a811c8fa67ab031ebd9c` 175 | - Payload Length (4-byte): `19000000` (25) 176 | - Payload (25-byte): 177 | - Payload Type (4-byte): `02000000` (2) 178 | - Index Length (2-byte): `0400` (4) 179 | - Index (4-byte): `494f5441` ("IOTA") 180 | - Data (15-byte): 181 | - Length (4-byte): `0b000000` (11) 182 | - Data (11-byte): `68656c6c6f20776f726c64` ("hello world") 183 | - Nonce (8-byte): `ce6d000000000000` (28110) 184 | 185 | # Rationale and alternatives 186 | 187 | Instead of creating a layered approach, we could have simply created a flat transaction message that is tailored to mutate the ledger state, and try to fit all the use cases there. For example, with the indexed data use case, we could have filled some section of the transaction with that particular data. Then, this transaction would not correspond to a ledger mutation but instead only carry data. 188 | 189 | This approach seems less extensible. It might have made sense if we had wanted to build a protocol that is just for ledger mutating transactions, but we want to be able to extend the protocol to do more than that. 190 | 191 | # Copyright 192 | 193 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 194 | -------------------------------------------------------------------------------- /tips/TIP-0007/utxo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0007/utxo.png -------------------------------------------------------------------------------- /tips/TIP-0009/diffs_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0009/diffs_1.png -------------------------------------------------------------------------------- /tips/TIP-0009/diffs_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0009/diffs_2.png -------------------------------------------------------------------------------- /tips/TIP-0010/tip-0010.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 10 3 | title: Mnemonic Ternary Seed 4 | description: Represent ternary seed as a mnemonic sentence 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/10 7 | status: Obsolete 8 | type: Standards 9 | layer: IRC 10 | created: 2020-03-11 11 | --- 12 | 13 | # Summary 14 | 15 | The IOTA protocol uses a 81-tryte seed to derive all the private keys for one account. This RFC describes a method to represent that seed as a mnemonic sentence - a group of easily comprehensible words. 16 | 17 | # Motivation 18 | 19 | The used seed is a 384-bit or 243-trit random string. There are several ways to represent this in a human-readable form, but a mnemonic sentence is superior to raw binary or ternary strings. These sentences can easily be written down or they can even be recorded over a phone. 20 | Furthermore, having raw strings tempts the user to copy and paste the seed due to convenience over security. This practice opens new attack vectors such as theft or manipulation of the string in the clipboard. 21 | 22 | # Detailed design 23 | 24 | The [BIP-0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) specification exactly describes an implementation for its use case and how to uniquely represent binary entropy using mnemonic words. However, it is only defined for binary input of 128 - 256 bits. The section(s) below describe the canonical extension of BIP-0039 for longer inputs of 81 trytes or 384 bits. 25 | 26 | The 243-trit (81-tryte) seed is used as input for the [Kerl](https://github.com/iotaledger/kerl/blob/master/IOTA-Kerl-spec.md) hash function to derive the private keys. Therefore, it is first converted to a 384-bit string to be absorbed by [Keccak-384](https://keccak.team/keccak.html). As the set of all possible 243-trit strings is larger than the set of 384-bit strings, the most significant trit is fixed to zero before converting. This means that the 243rd of the seed is ignored and does not have any impact on the following key derivation and does not need to be considered for the encoding. 27 | 28 | ### Generating the mnemonic from seed 29 | 30 | - Interpret the IOTA seed as a little-endian 243-trit balanced ternary integer; assure that its most significant trit is 0 and encode the number as a 384-bit signed integer in big-endian two's complement representation. [This exact conversion](https://github.com/iotaledger/kerl/blob/master/IOTA-Kerl-spec.md#trits---bytes-encoding) is also used as part of the current Kerl hash function. 31 | - Compute the [SHA-256](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) hash of the resulting bit string and use its first 384/32=12 bits as the checksum. 32 | - The 12-bit checksum is appended to the end of the initial result, making it a 396-bit string. 33 | - These concatenated bits are split into 36 groups of 11 bits, each encoding a number from 0-2047, corresponding to an index into the wordlist. 34 | - Finally, convert these numbers into words from any one of the [BIP-0039 wordlists](https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md) and use the joined words as a mnemonic sentence. 35 | 36 | ### Generating the seed from mnemonic 37 | 38 | - Convert the 36-word mnemonic sentence into its corresponding 396-bit string by taking the 11-bit wordlist index for each word and concatenating all the bits. 39 | - Split the resulting bit string into 384-bit entropy and 12-bit checksum. 40 | - Verify that the checksum corresponds to the first bits of the SHA-256 hash of the entropy. 41 | - Convert the 384-bit entropy, interpreted as a signed integer in big-endian two's complement representation, back to a little-endian 243-trit balanced ternary integer. (The most significant trit will always be zero.) This corresponds to the usual 243-trit or 81-tryte IOTA seed. 42 | 43 | ## Examples 44 | 45 | - Using the [English word list](https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt): 46 | - IOTA seed (81-tryte): `TLEV9HDTGZOXIIGA9DZG9VAKAIUZKNIMAFUGGARTWPOGDLLVUFZZVAABXRMFPWJAYWBBHOERV9EZBAOJD` 47 | - mnemonic (36-word): `forget small borrow baby wing law monkey fiber jealous canyon melt all order lift now fish mind index neither discover divert fit curtain raw wealth arrow frozen plug catalog public winner emerge pulse mixture cry arch` 48 | - Using the [Japanese word list](https://github.com/bitcoin/bips/blob/master/bip-0039/japanese.txt): 49 | - IOTA seed (81-tryte): `KMQDKKLGGTPUBRJXYWLMQOIA9WIEWUAAJPASYPVAWOTYYH9JESDKPLVZIWITHDIUMLFEWQUQ9LHAV9GHC` 50 | - mnemonic (36-word): `げどく　まもる　してい　ていへん　つめたい　ちつじょ　だいたい　てうち　まいにち　さゆう　よそく　がはく　ねらう　いちおう　くみあわせ　ふいうち　せつでん　きせい　すべて　きひん　しかい　さぎょう　うけたまわる　つとめる　おんしゃ　きかい　なやむ　たいせつ　うんこう　むすめ　いってい　ふめつ　そとづら　つくね　おいこす　ききて` 51 | 52 | # Drawbacks 53 | 54 | - This RFC describes a way to represent computer-generated randomness in a human-readable transcription. It is in no way meant to process user created sentences into a binary key. This technique is also sometimes called a "brain wallet" and must not be confused with these mnemonics. 55 | - The mnemonics only encode 384 bits of entropy which only covers 242 trits. The 243rd trit will *not* be encoded and always padded with 0. This is fine, when Kerl is used to derive the private keys, since the Kerl hash function only works on the first 242 trits itself. However, other - currently not used - key derivation functions relying on the full 243-trit entropy are *not* compatible with this RFC. 56 | 57 | # Rationale and alternatives 58 | 59 | - BIP-0039 provides an industry standard to present computer generated, secure entropy in a way that can be "processed" by humans in a much less error-prone way. The word lists are chosen in a way to reduce ambiguity, as such, typos can either be autocorrected or corrected with the help of a dictionary. This is in contrast to a raw ternary (or binary) representation, where typos automatically lead to a completely new seed, changing and breaking all successive private keys. 60 | - Thanks to the integrated 12-bit checksum, it is even possible to detect whether one or more words have been exchanged completely. 61 | - Presenting the user with a tryte or hex string will lead to situations in which the seed is copied into a text file, while human-readable words encourage the user to copy them on a piece of paper. 62 | 63 | # Unresolved questions 64 | 65 | - This RFC does not cover usability aspects of entering mnemonics. Forcing the user to enter a mnemonic sentence and then discarding the input, due to one easily correctable typo in one word, would almost be as frustrating as typing a tryte string. Therefore, this must be combined with different usability improvements, e.g. only allowing entering characters that lead to valid words or fixing the word as soon as it can be unambiguously identified. 66 | - The BIP-0039 specification includes several word lists for different languages. Should these word lists be allowed or is it sufficient to only use the English list? 67 | - The BIP-0039 specification only considers entropy between 128 and 256 bits, while this RFC extends it in an analogue way for 384 bits. Is it also relevant for certain use cases to extend this for 512 bits (or even longer)? 68 | 69 | # Reference implementation 70 | 71 | Example Go implementation in [wollac/iota-crypto-demo](https://github.com/Wollac/iota-crypto-demo): 72 | - Conversion from mnemonic to seed: [pkg/bip39/bip39.go](https://github.com/Wollac/iota-crypto-demo/blob/master/pkg/bip39/bip39.go) 73 | - Example: [examples/mnemseed](https://github.com/Wollac/iota-crypto-demo/tree/master/examples/mnemseed) 74 | 75 | # Copyright 76 | 77 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 78 | -------------------------------------------------------------------------------- /tips/TIP-0011/tip-0011.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 11 3 | title: Bech32 Address Format 4 | description: Extendable address format supporting various signature schemes and address types 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/20 7 | status: Replaced 8 | type: Standards 9 | layer: Interface 10 | created: 2020-07-28 11 | superseded-by: TIP-31 12 | --- 13 | 14 | # Summary 15 | 16 | This document proposes an extendable address format for the IOTA protocol supporting various signature schemes and address types. It relies on the [Bech32](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki) format to provide a compact, human-readable encoding with strong error correction guarantees. 17 | 18 | # Motivation 19 | 20 | With [Chrysalis](https://roadmap.iota.org/chrysalis), IOTA uses Ed25519 to generate digital signatures, in which addresses correspond to a BLAKE2b-256 hash. It is necessary to define a new universal and extendable address format capable of encoding different types of addresses. 21 | 22 | The current IOTA protocol relies on Base27 addresses with a truncated Kerl checksum. However, both the character set and the checksum algorithm have limitations: 23 | - Base27 is designed for ternary and is ill-suited for binary data. 24 | - The Kerl hash function also requires ternary input. Further, it is slow and provides no error-detection guarantees. 25 | - It does not support the addition of version or type information to distinguish between different kinds of addresses with the same length. 26 | 27 | All of these points are addressed in the Bech32 format introduced in [BIP-0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki): In addition to the usage of the human-friendly Base32 encoding with an optimized character set, it implements a [BCH code](https://en.wikipedia.org/wiki/BCH_code) that _guarantees detection_ of any error affecting at most four characters and has less than a 1 in 109 chance of failing to detect more errors. 28 | 29 | This RFC proposes a simple and extendable binary serialization for addresses of different types that is then Bech32 encoded to provide a unique appearance for human-facing applications such as wallets. 30 | 31 | # Detailed design 32 | 33 | ## Binary serialization 34 | 35 | The address format uses a simple serialization scheme which consists of two parts: 36 | 37 | - The first byte describes the type of the address. 38 | - The remaining bytes contain the type-specific raw address bytes. 39 | 40 | Currently, only one kind of addresses are supported: 41 | - Ed25519, where the address consists of the BLAKE2b-256 hash of the Ed25519 public key. 42 | 43 | They are serialized as follows: 44 | 45 | | Type | First byte | Address bytes | 46 | | ------- | ---------- | --------------------------------------------------------- | 47 | | Ed25519 | `0x00` | 32 bytes: The BLAKE2b-256 hash of the Ed25519 public key. | 48 | 49 | 50 | ## Bech32 for human-readable encoding 51 | 52 | The human-readable encoding of the address is Bech32 (as described in [BIP-0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)). A Bech32 string is at most 90 characters long and consists of: 53 | 54 | - The **human-readable part** (HRP), which conveys the IOTA protocol and distinguishes between Mainnet (the IOTA token) and Testnet (testing version): 55 | - `iota` is the human-readable part for Mainnet addresses 56 | - `atoi` is the human-readable part for Testnet addresses 57 | - The **separator**, which is always `1`. 58 | - The **data part**, which consists of the Base32 encoded serialized address and the 6-character checksum. 59 | 60 | Hence, Ed25519-based addresses will result in a Bech32 string of 64 characters. 61 | 62 | ## Examples 63 | 64 | - **Mainnet** 65 | - Ed25519 compressed public key (32-byte): `6f1581709bb7b1ef030d210db18e3b0ba1c776fba65d8cdaad05415142d189f8` 66 | - BLAKE2b-256 hash (32-byte): `efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3` 67 | - serialized (33-byte): `00efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3` 68 | - Bech32 string: `iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx` 69 | - **Testnet** 70 | - Ed25519 compressed public key (32-byte): `6f1581709bb7b1ef030d210db18e3b0ba1c776fba65d8cdaad05415142d189f8` 71 | - BLAKE2b-256 hash (32-byte): `efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3` 72 | - serialized (33-byte): `00efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3` 73 | - Bech32 string: `atoi1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6x8x4r7t` 74 | 75 | # Drawbacks 76 | 77 | - The new addresses look fundamentally different from the established 81-tryte IOTA addresses. However, since the switch from binary to ternary and Chrysalis in general is a substantial change, this is a very reasonable and desired consequence. 78 | - A four character HRP plus one type byte only leaves a maximum of 48 bytes for the actual address. 79 | 80 | # Rationale and alternatives 81 | 82 | - There are several ways to convert the binary serialization into a human-readable format, e.g. Base58 or hexadecimal. The Bech32 format, however, offers the best compromise between compactness and error correction guarantees. A more detailed motivation can be found in [BIP-0173 Motivation](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#motivation). 83 | - The binary serialization itself must be as compact as possible while still allowing you to distinguish between different address types of the same byte length. As such, the introduction of a version byte offers support for up to 256 different kinds of addresses at only the cost of one single byte. 84 | - The HRP of the Bech32 string offers a good opportunity to clearly distinguish IOTA addresses from other Bech32 encoded data. Here, any three or four character ASCII strings can be used. However, selecting `iota` as well as `atoi` seems like the most recognizable option. 85 | 86 | # Reference implementation 87 | 88 | Example Go implementation in [wollac/iota-crypto-demo](https://github.com/Wollac/iota-crypto-demo): 89 | - Bech32 encoding: [pkg/bech32](https://github.com/Wollac/iota-crypto-demo/tree/master/pkg/bech32) 90 | - Example: [examples/bech32](https://github.com/Wollac/iota-crypto-demo/tree/master/examples/bech32) 91 | 92 | # Copyright 93 | 94 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 95 | -------------------------------------------------------------------------------- /tips/TIP-0012/tip-0012.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 12 3 | title: Message PoW 4 | description: Define message proof-of-work as a means to rate-limit the network 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/24 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2020-08-25 11 | --- 12 | 13 | # Summary 14 | 15 | The IOTA protocol uses proof-of-work as a means to rate-limit the network. Currently, the Curl-P-81 trinary hash function is used and is required to provide a hash with the matching number of trailing zero trits to issue a transaction to the Tangle. With [Chrysalis](https://roadmap.iota.org/chrysalis), it will be possible to issue binary messages of arbitrary size. This RFC presents a proposal to adapt the existing PoW mechanism to these new requirements. It aims to be less disruptive to the current PoW mechanism as possible. 16 | 17 | # Motivation 18 | 19 | In the current IOTA Protocol, each transaction has a fixed size of 8019 trits and is hashed using Curl-P-81 to compute its 243-trit transaction hash, where the PoW's difficulty equals the number of trailing zero trits in that hash.
20 | Unfortunately, the performance of Curl-P-81 is slow, achieving only about 2 MB/s on a single core. This would make the PoW validation a bottleneck, especially for high usage scenarios with larger messages. Thus, this RFC proposes a two-stage approach to speed up the validation process: First, the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash function is used to create a short, fixed length digest of the message. Then, this digest, together with the nonce, is hashed using Curl-P-81. Since the digest only needs to be computed once while iterating over different nonce values, this preserves Curl as the PoW-relevant hash. However, the validation is much faster, as BLAKE2b-256 has a performance of about 1 GB/s and Curl then only needs to be executed for one single 243-trit block of input. Since the input of the final Curl computation is always fixed, parallel Curl variants can be used in this stage to further speed up the validation if necessary.
21 | Furthermore, it is important to note that the time required to do the PoW depends on the PoW difficulty and not on the message length. As such, to treat messages with different lengths differently, we need to weight the PoW difficulty by the message length. 22 | 23 | It will be easy to adapt existing hardware and software implementations of the current PoW mechanism to work with the proposed design. Only the input and the position of the nonce in the buffer needs to be adapted. This enables existing Curl projects to continue persisting and also the entire PoW landscape should stay almost the same. 24 | 25 | # Detailed design 26 | 27 | The PoW score is defined as the average number of iterations required to find the number of trailing zero trits in the hash divided by the message size. 28 | 29 | The PoW validation is performed in the following way: 30 | - Compute the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the serialized message (as described in [TIP-6](../TIP-0006/tip-0006.md)) *excluding* the 8-byte `Nonce` field and convert the hash into its 192-trit `b1t6` encoding. (See [TIP-5](../TIP-0005/tip-0005.md) for a description of the encoding.) 31 | - Take the 8-byte `Nonce` in little-endian representation, convert it into its 48-trit `b1t6` encoding and append it to the hash trits. 32 | - Add a padding of three zero trits to create a 243-trit string. 33 | - Compute the Curl-P-81 hash. 34 | - Count the number of trailing zero trits in the hash. 35 | - Then, the PoW score equals 3#zeros / size(message). 36 | 37 | This can also be summarized with the following pseudocode: 38 | ``` 39 | pow_digest ← BLAKE2b-256(serialized message excluding nonce field) 40 | pow_hash ← Curl-P-81(b1t6(pow_digest) || b1t6(nonce) || [0, 0, 0]) 41 | pow ← 3**trailing_zeros(pow_hash) / size 42 | ``` 43 | where `size` is the number of bytes of the full serialized message. 44 | 45 | ## Example 46 | 47 | - Message including nonce (21-byte): `48656c6c6f2c20576f726c64215ee6aaaaaaaaaaaa` 48 | - PoW digest (32-byte): `511bc81dde11180838c562c82bb35f3223f46061ebde4a955c27b3f489cf1e03` 49 | - Nonce (8-byte): `5ee6aaaaaaaaaaaa` (12297829382473049694) 50 | - Curl input (81-tryte): `9C9AYYBATZQAXAH9BBVYQDYYPBDXNDWBHAO9ODPDFZTZTCAWKCLADXO9PWEYCAC9MCAZVXVXVXVXVXVX9` 51 | - PoW hash (81-tryte): `DJCAGKILZPLXNXWFTNXFLCHRFVUHHMTPFIOFKQXMGIKITSEVWECMQOKCFXDIIHK9YVHGQICAIVEVDJ999` 52 | - Trailing zeros: 9 53 | - PoW score: 39 / 21 = 937.2857142857143 54 | 55 | # Drawbacks 56 | 57 | - Curl is a ternary hash function that is applied on binary data. This makes it necessary to introduce an additional encoding step. However, the proposed `b1t6` encoding is reasonably performant. Additionally, hash functions usually contain an encoding step to write the input into their internal state. In that sense, the `b1t6` encoding is not much different. 58 | - One additional trailing zero in the PoW hash effectively allows the message size to be tripled. This could potentially incentivize users to add otherwise unnecessary data, when the PoW difficulty stays the same. Using a binary hash function instead of Curl would only slightly improve this situation as the allowed message length remains exponential in the difficulty parameter. 59 | 60 | # Rationale and alternatives 61 | 62 | The premise of this proposal is that the PoW should remain Curl-based to cause the least amount of disruption to the protocol and its established projects. Therefore, other hash functions or PoW algorithms have not been considered. However, modifications of the described calculation are possible: 63 | - There are several potential encodings for the nonce: E.g. converting its value directly to balanced ternary (the most compact encoding) or using the `b1t8` encoding. The chosen `b1t6` encoding achieves a nice balance between compactness and performance. Since it is possible to fit the PoW digest and the `b1t6` encoded nonce into one Curl block, the simplicity of having only one encoding (for PoW digest and nonce) was preferred over minimal performance improvements other encodings could bring. 64 | - Curl can be computed directly on the `b1t6` encoded message (after an appropriate padding has been added). However, performance analysis of existing node implementation suggests that the Curl computations during the PoW could become critical, especially since parallel Curl implementations would be much more difficult to deploy because of the dynamic message lengths. 65 | - BLAKE2b-256 could be replaced with BLAKE2b-512 or any other binary cryptographic hash function. However, a 256-bit digest fits very nicely into exactly one Curl block and since BLAKE2b-256 is also used for the _message ID_, it is reasonable to also use it for the PoW digest. This reduces the number of required hashing implementations and even allows reusage of intermediate values between the PoW digest and the message ID computation. 66 | 67 | The PoW score formula 3#zeros / size(message) could be replaced with an alternative function to better match the network usage, e.g. in order to penalize longer message more than linearly. 68 | 69 | # Reference implementation 70 | 71 | Example Go implementation in [wollac/iota-crypto-demo](https://github.com/Wollac/iota-crypto-demo): 72 | - b1t6 encoding: [pkg/encoding/b1t6](https://github.com/Wollac/iota-crypto-demo/blob/master/pkg/encoding/b1t6/b1t6.go) 73 | - PoW computation: [pkg/pow](https://github.com/Wollac/iota-crypto-demo/blob/master/pkg/pow/pow.go) 74 | 75 | # Copyright 76 | 77 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 78 | -------------------------------------------------------------------------------- /tips/TIP-0013/tip-0013.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 13 3 | title: REST API 4 | description: Node REST API routes and objects in OpenAPI Specification 5 | author: Samuel Rufinatscha (@rufsam) 6 | discussions-to: https://github.com/iotaledger/tips/pull/26 7 | status: Replaced 8 | type: Standards 9 | layer: Interface 10 | created: 2020-09-10 11 | superseded-by: TIP-25 12 | --- 13 | 14 | # Summary 15 | 16 | This document proposes the REST API for nodes supporting the IOTA protocol. 17 | 18 | # API 19 | 20 | The API is described using the OpenAPI Specification: 21 | 22 | [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/iotaledger/tips/main/tips/TIP-0013/rest-api.yaml) 23 | 24 | # Copyright 25 | 26 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 27 | -------------------------------------------------------------------------------- /tips/TIP-0014/test.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "address": "008f5a6fdcfef8989fb88312cbc956ccc54dceb9c693ec99c08a28bdda5f11da44", 4 | "message": "8c93255d71dcab10e8f379c26200f3c7bd5f09d9bc3068d3ef4edeb4853022b6", 5 | "pub_key": "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa", 6 | "signature": "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a0000000000000000000000000000000000000000000000000000000000000000", 7 | "valid": true 8 | }, 9 | { 10 | "address": "008f5a6fdcfef8989fb88312cbc956ccc54dceb9c693ec99c08a28bdda5f11da44", 11 | "message": "9bd9f44f4dcc75bd531b56b2cd280b0bb38fc1cd6d1230e14861d861de092e79", 12 | "pub_key": "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa", 13 | "signature": "f7badec5b8abeaf699583992219b7b223f1df3fbbea919844e3f7c554a43dd43a5bb704786be79fc476f91d3f3f89b03984d8068dcf1bb7dfc6637b45450ac04", 14 | "valid": true 15 | }, 16 | { 17 | "address": "00df7de50e110ead8cb83451a503dbe03cc5edb2eced7e35212ae10af28d38c000", 18 | "message": "aebf3f2601a0c8c5d39cc7d8911642f740b78168218da8471772b35f9d35b9ab", 19 | "pub_key": "f7badec5b8abeaf699583992219b7b223f1df3fbbea919844e3f7c554a43dd43", 20 | "signature": "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa8c4bd45aecaca5b24fb97bc10ac27ac8751a7dfe1baff8b953ec9f5833ca260e", 21 | "valid": true 22 | }, 23 | { 24 | "address": "001482f60b75cc1a6b1fe9810b64b95a978c35ed73ff371cb99f6f1fd0479d7b21", 25 | "message": "9bd9f44f4dcc75bd531b56b2cd280b0bb38fc1cd6d1230e14861d861de092e79", 26 | "pub_key": "cdb267ce40c5cd45306fa5d2f29731459387dbf9eb933b7bd5aed9a765b88d4d", 27 | "signature": "9046a64750444938de19f227bb80485e92b83fdb4b6506c160484c016cc1852f87909e14428a7a1d62e9f22f3d3ad7802db02eb2e688b6c52fcd6648a98bd009", 28 | "valid": true 29 | }, 30 | { 31 | "address": "001482f60b75cc1a6b1fe9810b64b95a978c35ed73ff371cb99f6f1fd0479d7b21", 32 | "message": "e47d62c63f830dc7a6851a0b1f33ae4bb2f507fb6cffec4011eaccd55b53f56c", 33 | "pub_key": "cdb267ce40c5cd45306fa5d2f29731459387dbf9eb933b7bd5aed9a765b88d4d", 34 | "signature": "160a1cb0dc9c0258cd0a7d23e94d8fa878bcb1925f2c64246b2dee1796bed5125ec6bc982a269b723e0668e540911a9a6a58921d6925e434ab10aa7940551a09", 35 | "valid": true 36 | }, 37 | { 38 | "address": "001482f60b75cc1a6b1fe9810b64b95a978c35ed73ff371cb99f6f1fd0479d7b21", 39 | "message": "e47d62c63f830dc7a6851a0b1f33ae4bb2f507fb6cffec4011eaccd55b53f56c", 40 | "pub_key": "cdb267ce40c5cd45306fa5d2f29731459387dbf9eb933b7bd5aed9a765b88d4d", 41 | "signature": "21122a84e0b5fca4052f5b1235c80a537878b38f3142356b2c2384ebad4668b7e40bc836dac0f71076f9abe3a53f9c03c1ceeeddb658d0030494ace586687405", 42 | "valid": true 43 | }, 44 | { 45 | "address": "002aeb2a345ceecd740ffa7cd891ac0116dd10fe169079d158e492043ec49b834d", 46 | "message": "85e241a07d148b41e47d62c63f830dc7a6851a0b1f33ae4bb2f507fb6cffec40", 47 | "pub_key": "442aad9f089ad9e14647b1ef9099a1ff4798d78589e66f28eca69c11f582a623", 48 | "signature": "e96f66be976d82e60150baecff9906684aebb1ef181f67a7189ac78ea23b6c0e547f7690a0e2ddcd04d87dbc3490dc19b3b3052f7ff0538cb68afb369ba3a514", 49 | "valid": false 50 | }, 51 | { 52 | "address": "002aeb2a345ceecd740ffa7cd891ac0116dd10fe169079d158e492043ec49b834d", 53 | "message": "85e241a07d148b41e47d62c63f830dc7a6851a0b1f33ae4bb2f507fb6cffec40", 54 | "pub_key": "442aad9f089ad9e14647b1ef9099a1ff4798d78589e66f28eca69c11f582a623", 55 | "signature": "8ce5b96c8f26d0ab6c47958c9e68b937104cd36e13c33566acd2fe8d38aa19427e71f98a473474f2f13f06f97c20d58cc3f54b8bd0d272f42b695dd7e89a8c22", 56 | "valid": false 57 | }, 58 | { 59 | "address": "00df7de50e110ead8cb83451a503dbe03cc5edb2eced7e35212ae10af28d38c000", 60 | "message": "9bedc267423725d473888631ebf45988bad3db83851ee85c85e241a07d148b41", 61 | "pub_key": "f7badec5b8abeaf699583992219b7b223f1df3fbbea919844e3f7c554a43dd43", 62 | "signature": "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff03be9678ac102edcd92b0210bb34d7428d12ffc5df5f37e359941266a4e35f0f", 63 | "valid": false 64 | }, 65 | { 66 | "address": "00df7de50e110ead8cb83451a503dbe03cc5edb2eced7e35212ae10af28d38c000", 67 | "message": "9bedc267423725d473888631ebf45988bad3db83851ee85c85e241a07d148b41", 68 | "pub_key": "f7badec5b8abeaf699583992219b7b223f1df3fbbea919844e3f7c554a43dd43", 69 | "signature": "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffca8c5b64cd208982aa38d4936621a4775aa233aa0505711d8fdcfdaa943d4908", 70 | "valid": true 71 | }, 72 | { 73 | "address": "00f25275baf4e267a1ec213dfd8283e9c97bf8c3494752c1c14b4bd5e5f9bfa9d8", 74 | "message": "e96b7021eb39c1a163b6da4e3093dcd3f21387da4cc4572be588fafae23c155b", 75 | "pub_key": "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", 76 | "signature": "a9d55260f765261eb9b84e106f665e00b867287a761990d7135963ee0a7d59dca5bb704786be79fc476f91d3f3f89b03984d8068dcf1bb7dfc6637b45450ac04", 77 | "valid": false 78 | }, 79 | { 80 | "address": "003e7cca5d2979e71caa7325ce147026402da2aec6f95586be89e24f84bfb7f8fc", 81 | "message": "39a591f5321bbe07fd5a23dc2f39d025d74526615746727ceefd6e82ae65c06f", 82 | "pub_key": "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", 83 | "signature": "a9d55260f765261eb9b84e106f665e00b867287a761990d7135963ee0a7d59dca5bb704786be79fc476f91d3f3f89b03984d8068dcf1bb7dfc6637b45450ac04", 84 | "valid": true 85 | } 86 | ] 87 | -------------------------------------------------------------------------------- /tips/TIP-0014/tip-0014.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 14 3 | title: Ed25519 Validation 4 | description: Adopt https://zips.z.cash/zip-0215 to explicitly define Ed25519 validation criteria 5 | author: Gal Rogozinski (@GalRogozinski) , Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/28 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2020-10-30 11 | --- 12 | 13 | # Summary 14 | 15 | The IOTA protocol uses Ed25519 signatures to assure the authenticity of transactions in Chrysalis. However, although Ed25519 is standardized in [IETF RFC 8032](https://tools.ietf.org/html/rfc8032), it does not define strict validation criteria. As a result, compatible implementations do not need to agree on whether a particular signature is valid or not. While this might be acceptable for classical message signing, it is unacceptable in the context of consensus critical applications like IOTA. 16 | 17 | This RFC proposes to adopt [ZIP-215](https://zips.z.cash/zip-0215) to explicitly define validation criteria. This mainly involves the following sections of the Ed25519 spec: 18 | - decoding of elliptic curve points as described in [Section 5.1.3](https://tools.ietf.org/html/rfc8032#section-5.1.3) 19 | - validation itself as described in [Section 5.1.7](https://tools.ietf.org/html/rfc8032#section-5.1.7) 20 | 21 | # Motivation 22 | 23 | Based on [Chalkias et al. 2020](https://eprint.iacr.org/2020/1244) we know that: 24 | 1. Not all implementations follow the decoding rules defined in RFC 8032, but instead accept non-canonically encoded inputs. 25 | 2. The RFC 8032 provides two alternative verification equations, whereas one is stronger than the other. Different implementations use different equations and therefore validation results vary even across implementations that follow the RFC 8032. 26 | 27 | This lack of consistent validation behavior is especially critical for IOTA as they can cause a breach of consensus across node implementations! For example, one node implementation may consider a particular transaction valid and mutate the ledger state accordingly, while a different implementation may discard the same transaction due to invalidity. This would result in a network fork and could only be resolved outside of the protocol. Therefore, an explicit and unambiguous definition of validation criteria, such as ZIP-215, is necessary. 28 | 29 | Furthermore, it is important to note that the holder of the secret key can produce more than one valid distinct signature. Such transactions with the same essence but different signatures are considered as double spends by the consensus protocol and handled accordingly. While this does not pose a problem for the core protocol, it may be a problem for 2nd layer solutions, similar to how [transaction malleability in bitcoin presented an issue for the lightning network](https://en.bitcoinwiki.org/wiki/Transaction_Malleability#How_Does_Transaction_Malleability_Affect_The_Lightning_Network.3F). 30 | 31 | # Detailed design 32 | 33 | In order to have consistent validation of Ed25519 signatures for all edge cases and throughout different implementations, this RFC proposes explicit validation criteria. These three criteria **must** be checked to evaluate whether a signature is valid. 34 | 35 | Using the notation and Ed25519 parameters as described in the RFC 8032, the criteria are defined as follows: 36 | 37 | 1. Accept non-canonical encodings of A and R. 38 | 2. Reject values for S that are greater or equal than L. 39 | 3. Use the equation [8][S]B = [8]R + [8][k]A' for validation. 40 | 41 | In the following, we will explain each of these in more detail. 42 | 43 | ## Decoding 44 | 45 | The Curve25519 is defined over the finite field of order p=2255−19. A curve point (x,y) is encoded into its compressed 32-byte representation, namely by the 255-bit encoding of the field element y followed by a single sign bit that is 1 for negative x (see [RFC 8032, Section 3.1](https://tools.ietf.org/html/rfc8032#section-3.1)) and 0 otherwise. This approach provides a unique encoding for each valid point. However, there are two classes of edge cases representing non-canonical encodings of valid points: 46 | - encoding a y-coordinate as y + p 47 | - encoding a curve point (0,y) with the sign bit set to 1 48 | 49 | In contrast to RFC 8032, it is _not_ required that the encodings of A and R are canonical. As long as the corresponding (x,y) is a valid curve point, any of such edge cases will be accepted. 50 | 51 | ## Validation 52 | 53 | The RFC 8032 mentions two alternative verification equations: 54 | 1. [8][S]B = [8]R + [8][k]A' 55 | 2. [S]B = R + [k]A' 56 | 57 | Each honestly generated signature following RFC 8032 satisfies the second, cofactorless equation and thus, also the first equation. However, the opposite is not true. This is due to the fact that dishonestly generated nonce R and public key A' might have order other than L. Testing whether a point has order L is costly. The first, cofactored equation accepts more nonces and public keys including dishonestly generated ones but lets us skip costly order checks. This has the impact that each secret key has not one but eight corresponding public keys. However all those public keys correspond to different addresses.
There are solutions only satisfying the first equation but not the latter. This ambiguity in RFC 8032 has led to the current situation in which different implementations rely on different verification equations. 58 | 59 | Ed25519 also supports batch signature verification, which allows verifying several signatures in a single step, much faster than verifying signatures one-by-one. Without going into detail, there are also two alternative verification equations for the batch verification:
[8][∑zᵢsᵢ] B = [8]∑[zᵢ]Rᵢ + [8]∑[zᵢhᵢ]Aᵢ and its corresponding cofactorless version. However, only cofactored verifications, single and batch, are compatible with each other. All other combinations are inconsistent and can lead to false positives or false negatives (see [Chalkias et al. 2020](https://eprint.iacr.org/2020/1244), Section 3.2) for certain edge-cases introduced by an attacker.
Thus, in order to allow batch signature verification and its faster performance in IOTA nodes, the cofactored version _must_ be used for validation, i.e. the group equation [8][S]B = [8]R + [8][k]A' for the single verification. 60 | 61 | Since non-canonical encodings of A and R are allowed, it is crucial to also specify which representation must be used for the hash functions: 62 | - The provided binary encodings of A and R must be used as input to the hash function H instead of their canonical – and potentially different – representation. 63 | - During transaction validation, when the public key A is checked against the output's address, the provided binary encoding must be used for the BLAKE2b-256 hash instead of its canonical representation. 64 | 65 | ## Malleability 66 | 67 | The non-negative integer S is encoded into 32 bytes as part of the signature. However, a third party could replace S with S' = S + n·L for any natural n with S' < 2256 and the modified signature R || S' would still pass verification. Requiring a value less than L resolves this malleability issue. Unfortunately, this check is not present in all common Ed25519 implementations. 68 | 69 | Analogous to RFC 8032, the encoding of S _must_ represent an integer less than L. 70 | 71 | It is not possible for an external party to mutate R and still pass verification. The owner of the secret key, however, can create many different signatures for the same content: While Ed25519 defines a deterministic method of calculating the integer scalar r from the private key and the message, it is impossible to tell during signature verification if the point R = [r]B was created properly or any other scalar has been used.
As a result, there is a practically countless amount of different valid signatures corresponding to a certain message and public key. 72 | 73 | We allow users to have a zero-scalar secret key and consider eight corresponding public keys valid. However, users should not use it as it is equivalent to publishing one's secret key. This also has the impact that any valid signature produced with a zero-scalar secret key will authenticate any message thus making it "super"-malleable. 74 | 75 | ## Test vectors 76 | 77 | The test vectors are taken directly from [Chalkias et al. 2020](https://eprint.iacr.org/2020/1244). Here, `pub_key` corresponds to the encoding of A and `address` is a 33-byte _Ed25519 Address_ as described in [TIP-7](../TIP-0007/tip-0007.md#serialized-layout). The address is computed by hashing A. As mentioned in the paper, for test case #10 the key A is reduced before hashing, while in the others it is not. The key `valid` denotes whether the corresponding item represents a valid `signature` for the provided `address` and `message` or not. 78 | - [JSON tests](test.json) 79 | 80 | # Drawbacks 81 | 82 | - Allowing non-canonical encodings is a direct contradiction of RFC 8032 and rather unintuitive. Furthermore, it introduces alternative encodings for a handful of points on the curve. Even though such points will, for all practical purposes, never occur in honest signatures, it still theoretically introduces an external party malleability vector. 83 | - The cofactored validation is computationally slightly more expensive than the cofactorless version since it requires a multiplication by 8. 84 | 85 | # Rationale and alternatives 86 | 87 | In the IOTA protocol, the _Transaction ID_ corresponds to the hash over the entire transaction including the actual signature bytes. Therefore, it is absolutely crucial that (valid) signatures are not malleable by a public attacker, i.e. that the used Ed25519 variant is strongly-unforgeable. Allowing non-canonical point encodings does not introduce the same attack vector. As such, both options would lead to valid Ed25519 variants. 88 | 89 | Unfortunately, the Ed25519 `ref10` reference implementation as well as other implementations accept non-canonical points. As such, rejecting those inputs now would introduce a breaking change. While this might be acceptable for the IOTA protocol itself, since no Ed25519 signatures have been added to the ledger prior to this RFC, other consensus-critical applications require this backward compatibility with previously accepted signatures. Due to these considerations, the criterion was included in ZIP-215 to allow a seamless transition for existing consensus-critical contexts. This RFC aims to rather follow the existing ZIP-215 specification for compatibility and maintainability than to create a new standard. 90 | 91 | Using the cofactorless validation poses a similar breaking change since signatures accepted by implementations using the cofactored validation would then be rejected. More importantly, however, in order to be able to use the much faster batch verification, the cofactored version is required. 92 | 93 | # Copyright 94 | 95 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 96 | -------------------------------------------------------------------------------- /tips/TIP-0015/tip-0015.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 15 3 | title: Dust Protection 4 | description: Prevent bloating the ledger size with dust outputs 5 | author: Gal Rogozinski (@GalRogozinski) 6 | discussions-to: https://github.com/iotaledger/tips/pull/32 7 | status: Replaced 8 | type: Standards 9 | layer: Core 10 | created: 2020-12-07 11 | superseded-by: TIP-19 12 | --- 13 | 14 | # Summary 15 | 16 | In the UTXO model, each node in the network needs to keep track of all the currently unspent outputs. When the number of outputs gets too large, this can cause performance and memory issues. 17 | This RFC proposes a new protocol rule regarding the processing of outputs that transfer a very small amount of IOTA, so-called dust outputs: Dust outputs are only allowed when they are backed up by a certain deposit on the receiving address. This limits the amount of dust outputs, thus making it expensive to proliferate dust. Since a receiver must make a deposit, the protocol makes receiving dust an opt-in feature. 18 | 19 | # Motivation 20 | 21 | An attacker, or even honest users, can proliferate the UTXO ledger with outputs holding a tiny amount of IOTA coins. This can cause the ledger to grow to a prohibitively large size. 22 | 23 | In order to protect nodes from such attacks, one possible solution is to make accumulating dust outputs expensive. Since IOTA does not have any fees that might limit the feasibility of issuing many dust transactions, deposits pose a valid alternative to achieve a similar effect. 24 | 25 | When an address is supposed to receive micro transactions, it must have an unspent output of a special type as a deposit. This deposit cannot be consumed by any transaction as long as the dust outputs remain unspent. 26 | 27 | An additional benefit of this rule is that it makes a mass of privacy violating [forced address reuse attacks](https://en.bitcoin.it/wiki/Privacy#Forced_address_reuse) more expensive to carry out. 28 | 29 | 30 | # Detailed design 31 | 32 | ### Definitions 33 | 34 | *Dust output*: A transaction output that has an amount smaller than 1 Mi 35 | 36 | *SigLockedDustAllowanceOutput*: A new output type for deposits that enables an address to receive dust outputs. It can be consumed as an input like a regular `SigLockedSingleOutput`. 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 50 | 51 | 52 | 53 | 77 | 78 | 79 | 80 | 81 | 82 | 83 |
NameTypeDescription
Output Typeuint8 48 | Set to value 1 to denote a SigLockedDustAllowanceOutput. 49 |
Address oneOf 54 |
55 | Ed25519 Address 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 68 | 69 | 70 | 71 | 72 | 73 | 74 |
NameTypeDescription
Address Typeuint8 66 | Set to value 0 to denote an Ed25519 Address. 67 |
AddressByteArray[32]The raw bytes of the Ed25519 address which is the BLAKE2b-256 hash of the public key.
75 |
76 |
Amountuint64The amount of tokens to deposit with this SigLockedDustAllowanceOutput output.
84 | 85 | 86 | ### Validation 87 | 88 | Let A be the address that should hold the dust outputs' balances. Let S be the sum of all the amounts of all unspent `SigLockedDustAllowanceOutputs` on A. Then, the maximum number of allowed dust outputs on A is S divided by 100,000 and rounded down, i.e. 10 outputs for each 1 Mi deposited. 89 | However, regardless of S, the number of dust outputs must never exceed 100 per address. 90 | 91 | The amount of a `SigLockedDustAllowanceOutput` must be at least 1 Mi. Apart from this, `SigLockedDustAllowanceOutputs` are processed identical to `SigLockedSingleOutput`. The transaction validation as defined in the IOTA protocol [TIP-7](../TIP-0007/tip-0007.md), however, needs to be adapted. 92 | 93 | _Syntactical validation_ for `SigLockedDustAllowanceOutput`: 94 | - The `Address` must be unique in the set of `SigLockedDustAllowanceOutputs` in one transaction T. However, there can be one `SigLockedSingleOutput` and one `SigLockedDustAllowanceOutputs` T. 95 | - The `Amount` must be ≥ 1,000,000. 96 | 97 | The _semantic validation_ remains unchanged and are checked for both `SigLockedSingleOutputs` and `SigLockedDustAllowanceOutput`, but this RFC introduces one additional criterion: 98 | 99 | A transaction T 100 | - consuming a `SigLockedDustAllowanceOutput` on address A **or** 101 | - creating a dust output with address A, 102 | 103 | is only semantically valid, if, after T is booked, the number of confirmed unspent dust outputs on A does not exceed the allowed threshold of min(S / 100000, 100). 104 | 105 | # Drawbacks 106 | 107 | - There can no longer be addresses holding less than 1 Mi. 108 | - The actual validity of dust transaction can only be checked during semantic validation. 109 | - A service receiving micropayments may fail receiving them, if it did not consolidate dust outputs or raised the deposit for the receiving address. 110 | - An attacker can send microtransactions to an address with a `SigLockedDustAllowanceOutput` in order to fill the allowed threshold and block honest senders of microtransactions. The owner of the address can mitigate this by simply consolidating the attacker's dust and collecting it for profit. 111 | 112 | # Rationale and alternatives 113 | 114 | The rationale for creating a special `SigLockedDustAllowanceOutput` rather than rely on the default `SigLockedSingleOutputs` is to prevent attackers from polluting arbitrary addresses that happen to hold 115 | a large amount of funds with dust. 116 | 117 | One may note that an attacker can deposit a dust allowance on 3rd party address outside his control and pollute that address with dust. 118 | From a security perspective this is better than an attacker depositing a dust allowance on addresses under his control. 119 | This is because the receiving party might later choose to consolidate the dust outputs and hence relief UTXO memory consumption. 120 | The receiving party is also unlikely to be displeased from obtaining more funds, small as they may be. 121 | 122 | There are potential alternatives to introducing dust allowance deposits: 123 | 124 | - *Burning dust*: Allow dust outputs to exists only for a limited amount of time in the ledger. After this, they are removed completely and the associated funds are invalidated. 125 | - *Sweeping dust into Merkle trees*: Instead of burning dust outputs after some time, they are instead compressed into a Merkle tree and only the tree root is kept. In order to spend one of these compressed outputs, the corresponding Merkle audit path needs to be supplied in addition to a regular signature. 126 | 127 | The first option can cause issues, when dust outputs were burned before users could consolidate them. Also, changing the supply can be controversial. 128 | 129 | The second option is much more complicated as it introduces a completely new unlock mechanisms and requires the nodes to store the Merkle tree roots indefinitely. 130 | 131 | # Copyright 132 | 133 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 134 | -------------------------------------------------------------------------------- /tips/TIP-0016/event-api.yml: -------------------------------------------------------------------------------- 1 | asyncapi: 2.0.0 2 | info: 3 | title: Node Event API 4 | contact: 5 | email: contact@iota.org 6 | version: 1.0.0 7 | description: The node event API is in charge of publishing information about events within the node software. 8 | externalDocs: 9 | description: Find out more about IOTA 10 | url: 'https://iota.org' 11 | channels: 12 | milestones/latest: 13 | subscribe: 14 | operationId: milestoneLatest 15 | description: Publishes the newest latest known milestone. 16 | message: 17 | $ref: '#/components/messages/MilestonePayload' 18 | milestones/confirmed: 19 | subscribe: 20 | operationId: milestoneConfirmed 21 | description: Publishes the newly confirmed milestone. 22 | message: 23 | $ref: '#/components/messages/MilestonePayload' 24 | messages: 25 | subscribe: 26 | operationId: messages 27 | description: Publishes newly received messages in their serialized binary form. 28 | message: 29 | $ref: '#/components/messages/Message' 30 | messages/referenced: 31 | subscribe: 32 | operationId: messagesReferenced 33 | description: Publishes metadata of messages newly referenced by a milestone. 34 | message: 35 | $ref: '#/components/messages/MessageMetadata' 36 | messages/indexation/[index]: 37 | subscribe: 38 | operationId: messagesWithIndex 39 | description: Publishes newly received messages which contain indexation payloads with the specified index parameter (encoded in hex) in their serialized binary form. 40 | message: 41 | $ref: '#/components/messages/Message' 42 | messages/[messageId]/metadata: 43 | subscribe: 44 | operationId: messagesSpecificMetadata 45 | description: Publishes metadata of a particular message whenever its metadata changes. 46 | message: 47 | $ref: '#/components/messages/MessageMetadata' 48 | outputs/[outputId]: 49 | subscribe: 50 | operationId: output 51 | description: Publishes the given wanted output on subscription and when its state changes (created, spent). 52 | message: 53 | $ref: '#/components/messages/OutputPayload' 54 | transactions/[transactionId]/included-message: 55 | subscribe: 56 | operationId: transactions 57 | description: Publishes the confirmed message which carried the transaction with the specified transaction id. 58 | message: 59 | $ref: '#/components/messages/Message' 60 | addresses/[address]/outputs: 61 | subscribe: 62 | operationId: bech32AddressOutputs 63 | description: Publishes newly created or spent outputs on the specified Bech32 address. 64 | message: 65 | $ref: '#/components/messages/OutputPayload' 66 | addresses/ed25519/[address]/outputs: 67 | subscribe: 68 | operationId: hexEd25519AddressOutputs 69 | description: Publishes newly created or spent outputs on the specified hex-encoded Ed25519 address. 70 | message: 71 | $ref: '#/components/messages/OutputPayload' 72 | components: 73 | messages: 74 | MilestonePayload: 75 | contentType: application/json 76 | payload: 77 | type: object 78 | required: 79 | - "index" 80 | - "timestamp" 81 | properties: 82 | index: 83 | type: number 84 | description: The index of the milestone. 85 | example: 242412 86 | timestamp: 87 | type: number 88 | description: The UNIX timestamp in seconds of the milestone. 89 | example: 1609950538 90 | Message: 91 | contentType: application/octet-stream 92 | description: The message in its serialized binary form. 93 | payload: 94 | type: string 95 | format: binary 96 | example: >- 97 | 0100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000eb000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000020000016920b176f613ec7be59e68fc68f597eb3393af80f74c7c3db78198147d5f1f92640000000000000000018afe1f314622cc1ef52f16d619d1baccff81816b7e4e35fe268dc247b730acd65d5d2dd3f7df09000000000001000001f7868ab6bb55800b77b8b74191ad8285a9bf428ace579d541fda47661803ff44e0af5c34ad4edf475a01fb46e089a7afcab158b4a0133f32e889083e1c77eef65548933e0c6d2c3b0ac006cd77e77d778bf37b8d38d219fb62a9a2f718d4c9095100000000000000 98 | OutputPayload: 99 | contentType: application/json 100 | payload: 101 | type: object 102 | required: 103 | - "messageId" 104 | - "transactionId" 105 | - "outputIndex" 106 | - "isSpent" 107 | - "output" 108 | properties: 109 | messageId: 110 | type: string 111 | description: The ID of the message. 112 | example: cf5f77d62285b9ed8d617729e9232ae346a328c1897f0939837198e93ec13e85 113 | transactionId: 114 | type: string 115 | description: The ID of the transaction which created this output. 116 | example: d026f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7 117 | outputIndex: 118 | type: number 119 | description: The index of the this output within its transaction. 120 | example: 0 121 | isSpent: 122 | type: boolean 123 | description: Whether the output is spent or not. 124 | example: true 125 | output: 126 | type: object 127 | description: The output object itself. 128 | MessageMetadata: 129 | contentType: application/json 130 | payload: 131 | type: object 132 | required: 133 | - "messageId" 134 | - "parentMessageIds" 135 | - "isSolid" 136 | properties: 137 | messageId: 138 | type: string 139 | description: The ID of the message. 140 | example: cf5f77d62285b9ed8d617729e9232ae346a328c1897f0939837198e93ec13e85 141 | parentMessageIds: 142 | type: array 143 | description: The IDs of the referenced parent messages. 144 | example: 145 | - d026f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7 146 | - cf5f77d62285b9ed8d617729e9232ae346a328c1897f0939837198e93ec13e85 147 | isSolid: 148 | type: boolean 149 | description: Whether the message is solid or not. 150 | example: true 151 | referencedByMilestoneIndex: 152 | type: number 153 | description: The index of the milestone which referenced this message. 154 | example: 242544 155 | ledgerInclusionState: 156 | type: string 157 | description: The inclusion state of the message. 158 | enum: [ noTransaction, conflicting, included ] 159 | shouldPromote: 160 | type: boolean 161 | description: Whether the message should be promoted. This is determined automatically by the node by using the OCRI/YCRI of the message. 162 | example: true 163 | shouldReattach: 164 | type: boolean 165 | description: Whether the message should be re-attached. This is determined automatically by the node by using the OCRI/YCRI of the message. 166 | example: false -------------------------------------------------------------------------------- /tips/TIP-0016/tip-0016.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 16 3 | title: Event API 4 | description: Node event API definitions in AsyncAPI Specification 5 | author: Luca Moser (@luca-moser) 6 | discussions-to: https://github.com/iotaledger/tips/pull/33 7 | status: Replaced 8 | type: Standards 9 | layer: Interface 10 | created: 2021-01-06 11 | superseded-by: TIP-28 12 | --- 13 | 14 | # Summary 15 | 16 | This document proposes the Event API for nodes supporting the IOTA protocol. 17 | 18 | # API 19 | 20 | The API is described using the AsyncAPI Specification: 21 | 22 | [AsyncAPI Editor](https://studio.asyncapi.com/?load=https://raw.githubusercontent.com/iotaledger/tips/main/tips/TIP-0016/event-api.yml) 23 | 24 | # Copyright 25 | 26 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 27 | -------------------------------------------------------------------------------- /tips/TIP-0018/chain-constraint.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0018/chain-constraint.png -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_AliasOutput_(max_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_AliasOutput_(max_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_AliasOutput_(min_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_AliasOutput_(min_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_BasicOutput_(max_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_BasicOutput_(max_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_BasicOutput_(min_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_BasicOutput_(min_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_FoundryOutput_(max_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_FoundryOutput_(max_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_FoundryOutput_(min_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_FoundryOutput_(min_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_NFTOutput_(max_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_NFTOutput_(max_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/deposit_miota_NFTOutput_(min_functionality).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/deposit_miota_NFTOutput_(min_functionality).jpg -------------------------------------------------------------------------------- /tips/TIP-0019/assets/microtransactions_pt3_layer1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/microtransactions_pt3_layer1.png -------------------------------------------------------------------------------- /tips/TIP-0019/assets/microtransactions_pt3_layer2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0019/assets/microtransactions_pt3_layer2.png -------------------------------------------------------------------------------- /tips/TIP-0020/utxo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0020/utxo.png -------------------------------------------------------------------------------- /tips/TIP-0021/tip-0021.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 21 3 | title: Serialization Primitives 4 | description: Introduce primitives to describe the binary serialization of objects. 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/41 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2021-11-22 11 | --- 12 | 13 | # Summary 14 | 15 | This document introduces the primitives and concepts that are used throughout the IOTA protocol RFCs to describe the binary serialization of objects. 16 | 17 | # Motivation 18 | 19 | Prior to this document, each RFC contained its own section and version describing the serialization of its objects. This RFC introduces consistent serialization concepts and avoids duplication in other RFCs. 20 | 21 | # Detailed design 22 | ## Schemas 23 | 24 | Serializable objects are represented by a _schema_. Each schema consists of a list of _fields_, which each have a name and a type. The type of a field can either be a simple data type or another schema, then called subschema. 25 | 26 | ### Data types 27 | 28 | All the supported data types are described in the following table: 29 | 30 | | Name | Description | 31 | |-------------------|-------------------------------------------------------------------------------| 32 | | uint8 | An unsigned 8-bit integer encoded in Little Endian. | 33 | | uint16 | An unsigned 16-bit integer encoded in Little Endian. | 34 | | uint32 | An unsigned 32-bit integer encoded in Little Endian. | 35 | | uint64 | An unsigned 64-bit integer encoded in Little Endian. | 36 | | uint256 | An unsigned 256 bits integer encoded in Little Endian. | 37 | | ByteArray[N] | A static size byte array of N bytes. | 38 | | (uint8)ByteArray | A dynamically sized byte array. A leading uint8 denotes its length in bytes. | 39 | | (uint16)ByteArray | A dynamically sized byte array. A leading uint16 denotes its length in bytes. | 40 | | (uint32)ByteArray | A dynamically sized byte array. A leading uint32 denotes its length in bytes. | 41 | 42 | ### Subschemas 43 | 44 | In order to create complex schemas, one or multiple subschemas can be included into an outer schema. The keywords that describe the allowed combinations of such subschemas is described in the following table: 45 | 46 | | Name | Description | 47 | |----------------------|-------------------------------------------------------------| 48 | | `oneOf` | One of the listed subschemas. | 49 | | `optOneOf` | One of the listed subschemas or none. | 50 | | `anyOf` | Any (one or more) of the listed subschemas. | 51 | | `optAnyOf` | Any (one or more) of the listed subschemas or none. | 52 | | `atMostOneOfEach` | At most one (none or one) of each of the listed subschemas. | 53 | 54 | # Copyright 55 | 56 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 57 | -------------------------------------------------------------------------------- /tips/TIP-0022/tip-0022.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 22 3 | title: IOTA Protocol Parameters 4 | description: Describes the global protocol parameters for the IOTA protocol 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/43 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2021-11-29 11 | --- 12 | 13 | # Summary 14 | 15 | This TIP describes the global protocol parameters for the IOTA protocol. 16 | 17 | # Motivation 18 | 19 | Various other protocol TIPs rely on certain constants that need to be defined for an actual implementations of nodes or other applications using the protocol. This TIP serves as a single document to provide these parameters. It also serves as a historical record of protocol parameter changes. 20 | 21 | # Detailed design 22 | 23 | | Name | Value | Description | 24 | |---------------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| 25 | | Network Name | "iota-mainnet" | Identifier string of the network. Its hash it used for the `Network ID` field in transactions. | 26 | | Protocol Version | 2 | Protocol version currently used by the network | 27 | | Max Block Length | 32768 | Maximum length of a block in bytes. Limits Tangle storage size and communication costs. | 28 | | Max Parents Count | 8 | Maximum number of parents of a block. | 29 | | Min PoW Score | 1500.0 | Minimum PoW score for blocks to pass syntactic validation. | 30 | | First Milestone Index | 1 | First valid milestone index. | 31 | | | | | 32 | | Max IOTA Supply | 4600000000000000 | Total amount of IOTA coins in circulation. | 33 | | Max Inputs Count | 128 | Maximum number of inputs in a transaction payload. | 34 | | Max Outputs Count | 128 | Maximum number of outputs in a transaction payload. | 35 | | Max Native Token Count | 64 | Maximum number of different native tokens that can be referenced in one transaction. | 36 | | | | | 37 | | Max Tag Length | 64 | Maximum length of a `Tag` field in bytes. | 38 | | Max Metadata Length | 8192 | Maximum length of a `Metadata` field in bytes. | 39 | | | | | 40 | | VByte Cost | 250 | Minimum amount of IOTA that need to be deposited per vbyte of an output. | 41 | | | | | 42 | | SLIP-44 Coin Type (decimal) | 4218 | Registered coin type (decimal) for usage in level 2 of [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) described in chapter "Coin type". | 43 | | SLIP-44 Path Component (`coin_type'`) | 0x8000107a | Registered path component for usage in level 2 of [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) described in chapter "Coin type". | 44 | | | | | 45 | | Bech32 Human-Readable Part | `iota` | HRP prefix to use for Bech32 encoded IOTA addresses. (e.g. `iota1zzy3drvj6zugek60srqwhqctkjldx3qle5yuvapj`) | 46 | | Bech32 Human-Readable Part (Test) | `atoi` | HRP prefix to use for Bech32 encoded IOTA addresses on test- or development networks. (e.g. `atoi1zzy3drvj6zugek60srqwhqctkjldx3qle5fhvhm6`) | 47 | 48 | # Rationale for parameter choices 49 | 50 | ## Transaction and block limits 51 | 52 | The block parameter `Max Block Length` and `Max Parent Count`, as well as the transaction parameters `Max Inputs Count`, `Max Outputs Count`, `Max Native Token Count`, `Max Tag Length` and `Max Metadata Length` govern the block and transaction validity. Their values have been chosen to ensure functionality of the protocol within constrained resource restrictions. Furthermore, choosing more conservatives values here is preferable as increasing such limits can always been done preserving backward compatibility. 53 | 54 | ## Dust protection 55 | 56 | The `VByte Cost` is the core parameter of the dust protection. The reasoning behind its value is explained in [TIP-19 Dust Protection](../TIP-0019/tip-0019.md). 57 | 58 | # Copyright 59 | 60 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 61 | -------------------------------------------------------------------------------- /tips/TIP-0023/tip-0023.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 23 3 | title: Tagged Data Payload 4 | description: Block payload for arbitrary data 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/54 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | created: 2022-01-24 11 | --- 12 | 13 | # Abstract 14 | 15 | The payload concept offers a very flexible way to combine and encapsulate information in the IOTA protocol. This document proposes a basic payload type that allows the addition of arbitrary data. 16 | 17 | # Motivation 18 | 19 | The most flexible way to extend an existing object is by the addition of arbitrary data. This payload provides a way to do just that. An optional tag can be used to categorize the data. 20 | 21 | # Specification 22 | 23 | ## Serialized Layout 24 | 25 | The following table describes the serialization of a _Tagged Data Payload_ following the notation from [TIP-21](../TIP-0021/tip-0021.md): 26 | 27 | | Name | Type | Description | 28 | |--------------|-------------------|----------------------------------------------------------| 29 | | Payload Type | uint32 | Set to *value 5* to denote an _Tagged Data Payload_. | 30 | | Tag | (uint8)ByteArray | The tag of the data. A leading uint8 denotes its length. | 31 | | Data | (uint32)ByteArray | Binary data. A leading uint32 denotes its length. | 32 | 33 | It is important to note that `Tag` is not considered by the protocol, it just serves as a marker for second layer applications. 34 | 35 | ## Syntactic Validation 36 | 37 | - `length(Tag)` must not be larger than [`Max Tag Length`](../TIP-0022/tip-0022.md). 38 | - Given the type and length information, the _Tagged Data Payload_ must consume the entire byte array of the `Payload` field of the encapsulating object. 39 | 40 | # Rationale 41 | 42 | As the tag is not considered by the protocol, it could also be removed completely. However, Legacy IOTA and Chrysalis supported sending of arbitrary data indexed with a tag. Thus, in order to simplify the migration of second layer applications using these protocols, the optional `Tag` has been added which can be used in a similar manner. 43 | 44 | # Copyright 45 | 46 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 47 | -------------------------------------------------------------------------------- /tips/TIP-0024/tip-0024.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 24 3 | title: Tangle Block 4 | description: Generalization of the Tangle transaction concept 5 | author: Wolfgang Welz (@Wollac) 6 | discussions-to: https://github.com/iotaledger/tips/pull/55 7 | status: Active 8 | type: Standards 9 | layer: Core 10 | replaces: 6 11 | created: 2022-01-24 12 | --- 13 | 14 | # Abstract 15 | 16 | The Tangle is the graph data structure behind IOTA. In the legacy IOTA protocol, the vertices of the Tangle are represented by transactions. This document proposes an abstraction of this idea where the vertices are generalized *blocks*, which then contain the transactions or other structures that are processed by the IOTA protocol. Just as before, each block directly approves other blocks, which are known as _parents_. 17 | 18 | The blocks can contain payloads. These are core payloads that will be processed by all nodes as part of the IOTA protocol. Some payloads may have other nested payloads embedded inside. Hence, parsing is done layer by layer. 19 | 20 | # Motivation 21 | 22 | To better understand this layered design, consider the Internet Protocol (IP), for example: There is an Ethernet frame that contains an IP payload. This in turn contains a TCP packet that encapsulates an HTTP payload. Each layer has a certain responsibility and once this responsibility is completed, we move on to the next layer. 23 | 24 | The same is true with how blocks are parsed. The outer layer of the block enables the mapping of the block to a vertex in the Tangle and allows us to perform some basic validation. The next layer may be a transaction that mutates the ledger state, and one layer further may provide some extra functionality on the transactions to be used by applications. 25 | 26 | By making it possible to add and exchange payloads, an architecture is being created that can easily be extended to accommodate future needs. 27 | 28 | # Specification 29 | 30 | ## Block ID 31 | 32 | The *Block ID* is the [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the entire serialized block. 33 | 34 | ## Serialized Layout 35 | 36 | The following table describes the serialization of a _Block_ following the notation from [TIP-21](../TIP-0021/tip-0021.md): 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 111 | 112 | 113 | 114 | 115 | 116 | 117 |
NameTypeDescription
Protocol Versionuint8 Protocol version number of the block.
Parents Countuint8The number of blocks that are directly approved.
Parents anyOf 57 |
58 | Parent 59 |
60 | References another directly approved block. 61 |
62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 |
NameTypeDescription
Block IDByteArray[32]The Block ID of the parent.
74 |
75 |
Payload Lengthuint32The length of the following payload in bytes. A length of 0 means no payload will be attached.
Payload optOneOf 85 |
86 | Generic Payload 87 |
88 | An outline of a generic payload 89 |
90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 102 | 103 | 104 | 105 | 106 | 107 | 108 |
NameTypeDescription
Payload Typeuint32 100 | The type of the payload. It will instruct the node how to parse the fields that follow. 101 |
Data FieldsANYA sequence of fields, where the structure depends on Payload Type.
109 |
110 |
Nonceuint64The nonce which lets this block fulfill the PoW requirement.
118 | 119 | ## Syntactic validation 120 | 121 | The Tangle can only contain syntactically valid blocks. Invalid blocks must be rejected by the node. 122 | The following criteria defines whether the block passes the syntactic validation: 123 | 124 | - The total length of the serialized block must not exceed `Max Block Length`. 125 | - `Protocol Version` must match the `Protocol Version` config parameter of the node. 126 | - Parents: 127 | - `Parents Count` must be at least 1 and not larger than `Max Parents Count`. 128 | - `Parents` must be sorted in lexicographical order. 129 | - Each `Block ID` must be unique. 130 | - Payload (if present): 131 | - `Payload Type` must match one of the values described under [Payloads](#payloads). 132 | - `Data Fields` must be correctly parsable in the context of the `Payload Type`. 133 | - The payload itself must pass syntactic validation. 134 | - `Nonce` must be valid with respect to the PoW condition described under [Payloads](#payloads). The PoW score itself is computed according to [TIP-12](../TIP-0012/tip-0012.md). 135 | - There must be no trailing bytes after all block fields have been parsed. 136 | 137 | ### PoW validation 138 | 139 | The PoW that needs to be performed for each block protects the network against denial-of-service attacks where in a short time too many blocks are issued for the nodes to process. As the processing time of a block heavily depends on the contained payload, the PoW check can also depend on the `Payload Type` and is described under [Payloads](#payloads). 140 | It is important to note, that the actual parsing and validating of a payload can be computationally expensive. Thus, it is recommended to first parse the block with all its fields including `Payload Type` (but not parsing or validating the actual payload `Data Fields`). Now, simple syntactic validation steps – including PoW validation – can be performed and invalid blocks already filtered out before the payload is validated. With this approach, payload-based PoW validation is not significantly more expensive than payload-agnostic validation. 141 | 142 | ## Payloads 143 | 144 | While blocks without a payload, i.e. `Payload Length` set to zero, are valid, such blocks do not contain any information. As such, blocks usually contain a payload. The detailed specification of each payload type is out of scope of this TIP. The following table lists all currently specified payloads that can be part of a block and links to their specification: 145 | 146 | | Payload Name | Type Value | TIP | PoW Condition | 147 | |--------------|------------|-----------------------------------|--------------------------------| 148 | | No Payload | - | - | PoW score ≥ `Min PoW Score` | 149 | | Tagged Data | 5 | [TIP-23](../TIP-0023/tip-0023.md) | PoW score ≥ `Min PoW Score` | 150 | | Transaction | 6 | [TIP-20](../TIP-0020/tip-0020.md) | PoW score ≥ `Min PoW Score` | 151 | | Milestone | 7 | [TIP-29](../TIP-0029/tip-0029.md) | `nonce` = `0x0000000000000000` | 152 | 153 | ## Example 154 | 155 | Below is the full serialization of a valid block with a _Tagged Data Payload_. The tag is the "IOTA" ASCII string and the data is the "hello world" ASCII string. Bytes are expressed as hexadecimal numbers. 156 | 157 | - Protocol Version (1-byte): `02` (2) 158 | - Parents Count (1-byte): `02` (2) 159 | - Parents (64-byte): 160 | - `210fc7bb818639ac48a4c6afa2f1581a8b9525e20fda68927f2b2ff836f73578` 161 | - `db0fa54c29f7fd928d92ca43f193dee47f591549f597a811c8fa67ab031ebd9c` 162 | - Payload Length (4-byte): `18000000` (24) 163 | - Payload (24-byte): 164 | - Payload Type (4-byte): `05000000` (5) 165 | - Tag (5-byte): 166 | - Length (1-byte): `04` (4) 167 | - Tag (4-byte): `494f5441` ("IOTA") 168 | - Data (15-byte): 169 | - Length (4-byte): `0b000000` (11) 170 | - Data (11-byte): `68656c6c6f20776f726c64` ("hello world") 171 | - Nonce (8-byte): `ce6d000000000000` (28110) 172 | 173 | # Rationale and alternatives 174 | 175 | Instead of creating a layered approach, we could have simply created a flat transaction block that is tailored to mutate the ledger state, and try to fit all the use cases there. For example, with the tagged data use case, we could have filled some section of the transaction with that particular data. Then, this transaction would not correspond to a ledger mutation but instead only carry data. 176 | 177 | This approach seems less extensible. It might have made sense if we had wanted to build a protocol that is just for ledger mutating transactions, but we want to be able to extend the protocol to do more than that. 178 | 179 | # Copyright 180 | 181 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 182 | -------------------------------------------------------------------------------- /tips/TIP-0025/tip-0025.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 25 3 | title: Core REST API 4 | description: Node Core REST API routes and objects in OpenAPI Specification 5 | author: Samuel Rufinatscha (@rufsam) , Levente Pap (@lzpap) 6 | discussions-to: https://github.com/iotaledger/tips/pull/27, https://github.com/iotaledger/tips/discussions/53, https://github.com/iotaledger/tips/pull/57 7 | status: Active 8 | type: Standards 9 | layer: Interface 10 | replaces: 13 11 | created: 2022-01-26 12 | --- 13 | 14 | # Summary 15 | 16 | This document proposes the core REST API for nodes supporting the IOTA protocol. 17 | 18 | # API 19 | 20 | The API is described using the OpenAPI Specification: 21 | 22 | [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/iotaledger/tips/main/tips/TIP-0025/core-rest-api.yaml) 23 | 24 | # Copyright 25 | 26 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 27 | -------------------------------------------------------------------------------- /tips/TIP-0026/tip-0026.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 26 3 | title: UTXO Indexer API 4 | description: UTXO Indexer REST API routes and objects in OpenAPI Specification 5 | author: Levente Pap (@lzpap) 6 | discussions-to: https://github.com/iotaledger/tips/pull/62, https://github.com/iotaledger/tips/discussions/53 7 | status: Active 8 | type: Standards 9 | layer: Interface 10 | created: 2022-01-27 11 | --- 12 | 13 | ## Abstract 14 | 15 | The IOTA UTXO Indexer API defines the standard REST API interface that need to be fulfilled by indexer node plugins 16 | or standalone indexer applications. 17 | 18 | The purpose of the UTXO Indexer API is to: 19 | - Provide access to structured, indexed records (outputs) of the UTXO ledger of the Tangle, 20 | - Support client queries on the structured data to fetch outputs of interest, 21 | - Offload network critical nodes from having to run the indexer application. 22 | 23 | ## Motivation 24 | 25 | [TIP-18](../TIP-0018/tip-0018.md) introduces new output types into the IOTA UTXO ledger. These new 26 | outputs support a variety of new features such as different unlocking conditions and feature blocks. 27 | 28 | The indexer API makes it possible for clients to retrieve outputs based on present features, furthermore to filter them 29 | with more complex queries. 30 | 31 | The main client application the API is designed for are wallets, but it does not mean that other applications could 32 | not use or extend it. 33 | 34 | ## Specification 35 | 36 | The API is described using the OpenAPI Specification: 37 | 38 | [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/iotaledger/tips/main/tips/TIP-0026/indexer-rest-api.yaml) 39 | 40 | ## Rationale 41 | 42 | [This discussion](https://github.com/iotaledger/tips/discussions/53) gives a good overview of why the core and indexer 43 | APIs are separated. In short, indexing the ledger is considered to be a L2 application, and as such, it is not a 44 | mandatory part of IOTA core node implementations. 45 | 46 | Alternatively, all indexing could be baked into the core software that would require us to factor in the "cost" of 47 | indexing into byte cost of outputs, resulting in higher minimal dust deposit requirements. Network nodes that do not 48 | interact with clients but are the backbone of the network would also have to perform indexing tasks for no reason. 49 | 50 | The new architecture also opens up the door for developing more advanced indexing applications detached from node 51 | implementations. 52 | 53 | ## Backwards Compatibility 54 | 55 | Some routes from the previous REST API ([TIP-13](../TIP-0013/tip-0013.md)) are removed and are supported in the new 56 | indexer API. For more details, browse [TIP-25](../TIP-0025/tip-0025.md). 57 | 58 | ## Reference Implementation 59 | 60 | Hornet reference implementation: 61 | - https://github.com/gohornet/inx-indexer 62 | 63 | ## Copyright 64 | 65 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 66 | -------------------------------------------------------------------------------- /tips/TIP-0027/irc27.schema.json: -------------------------------------------------------------------------------- 1 | 2 | { 3 | "$schema": "https://json-schema.org/draft/2020-12/schema", 4 | "$id": "https://github.com/iotaledger/tips/main/tips/TIP-0027/irc27.schema.json", 5 | "title": "IRC27 IOTA NFT Metadata Schema", 6 | "description": "A JSON schema for validating IRC27 compliant NFT metadata", 7 | "type": "object", 8 | "properties": { 9 | "standard": { 10 | "type": "string", 11 | "description": "identifier for the metadata standard used", 12 | "pattern": "^IRC27$" 13 | }, 14 | "version": { 15 | "type": "string", 16 | "description": "version of the metadata standard used", 17 | "pattern": "^v\\d+.\\d+$" 18 | }, 19 | "name": { 20 | "type": "string", 21 | "description": "A descriptive name of the token" 22 | }, 23 | "description": { 24 | "type": "string", 25 | "description": "some information about the NFT project" 26 | }, 27 | "type": { 28 | "type": "string", 29 | "description": "MIME type of the asset" 30 | }, 31 | "uri": { 32 | "type": "string", 33 | "description": "URI pointing to the resource where the file with `type` MIME type is hosted" 34 | }, 35 | "collectionName": { 36 | "type": "string", 37 | "description": "A human readable name for the NFT collection" 38 | }, 39 | "royalties": { 40 | "type": "object", 41 | "description": "object containing the payout addresses mapped to their percentage share" 42 | }, 43 | "issuerName": { 44 | "type": "string", 45 | "description": "name of the artist" 46 | }, 47 | "attributes": { 48 | "type": "array", 49 | "description": "array containing any additional data as objects." 50 | } 51 | }, 52 | "required": [ "standard", "type", "version", "uri", "name" ] 53 | } 54 | -------------------------------------------------------------------------------- /tips/TIP-0028/tip-0028.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 28 3 | title: Event API 4 | description: Node event API definitions in AsyncAPI Specification 5 | author: Luca Moser (@luca-moser) , Levente Pap (@lzpap) 6 | discussions-to: https://github.com/iotaledger/tips/pull/33, https://github.com/iotaledger/tips/pull/66 7 | status: Active 8 | type: Standards 9 | layer: Interface 10 | created: 2022-03-02 11 | replaces: 16 12 | --- 13 | 14 | ## Abstract 15 | 16 | This proposal describes the [MQTT](https://mqtt.org/) based Node Event API for IOTA nodes. Clients may subscribe to 17 | topics provided by the node, that acts as the message publisher and broker at the same time. 18 | 19 | ## Motivation 20 | 21 | The event API makes it possible for clients to implement event-based architectures as opposed to polling supported 22 | by the REST API defined in [draft TIP-25](../TIP-0025/tip-0025.md). 23 | 24 | The event-based architecture should be of great benefit to: 25 | - wallets monitoring status of submitted blocks or transactions, 26 | - explorers displaying the evolution of the Tangle and ledger state, 27 | - archivers documenting the history of the Tangle. 28 | 29 | ## Specification 30 | 31 | The API is described using the AsyncAPI Specification: 32 | 33 | [AsyncAPI Editor](https://studio.asyncapi.com/?url=https://raw.githubusercontent.com/iotaledger/tips/main/tips/TIP-0028/event-api.yml) 34 | 35 | ## Rationale 36 | 37 | - MQTT is a lightweight protocol that is good at minimizing bandwidth and ensuring message delivery via Quality of Service. 38 | - It may run on resource constrained devices as well and works on top of TCP/IP protocol. 39 | - The publish-subscribe model makes information dissemination effective to interested clients only. 40 | 41 | ## Backwards Compatibility 42 | 43 | The previously employed event API described in [TIP-16](../TIP-0016/tip-0016.md) is not backwards compatible with the 44 | current proposal, therefore versioning is introduced in the access URL of the API. 45 | 46 | The response models are shared between the REST API and the event API. 47 | 48 | The access route of the message broker should be updated to: 49 | - `{nodeURL}/api/mqtt/v1` 50 | 51 | ## Reference Implementation 52 | 53 | ### Broker 54 | - https://github.com/gohornet/inx-mqtt 55 | 56 | ### Client 57 | - Go: https://github.com/iotaledger/iota.go/blob/develop/nodeclient/event_api_client.go 58 | - Rust: https://github.com/iotaledger/iota.rs/tree/develop/client/src/node_api/mqtt 59 | - TypeScript: https://github.com/iotaledger/iota.js/tree/feat/stardust/packages/mqtt 60 | 61 | ## Copyright 62 | 63 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 64 | -------------------------------------------------------------------------------- /tips/TIP-0030/examples/1-valid.json: -------------------------------------------------------------------------------- 1 | { 2 | "standard": "IRC30", 3 | "name": "FooCoin", 4 | "symbol": "FOO", 5 | "decimals": 3 6 | } 7 | -------------------------------------------------------------------------------- /tips/TIP-0030/examples/2-valid.json: -------------------------------------------------------------------------------- 1 | { 2 | "standard": "IRC30", 3 | "name": "FooCoin", 4 | "description": "FooCoin is the utility and governance token of FooLand, a revolutionary protocol in the play-to-earn crypto gaming field.", 5 | "symbol": "FOO", 6 | "decimals": 3, 7 | "url": "https://foocoin.io", 8 | "logoUrl": "https://ipfs.io/ipfs/QmR36VFfo1hH2RAwVs4zVJ5btkopGip5cW7ydY4jUQBrkR" 9 | } 10 | -------------------------------------------------------------------------------- /tips/TIP-0030/examples/3-invalid.json: -------------------------------------------------------------------------------- 1 | { 2 | "standard": "IRC27", 3 | "name": "FooCoin", 4 | "description": "FooCoin is the utility and governance token of FooLand, a revolutionary protocol in the play-to-earn crypto gaming field.", 5 | "decimals": 0.5 6 | } 7 | -------------------------------------------------------------------------------- /tips/TIP-0030/irc30.schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://json-schema.org/draft/2020-12/schema", 3 | "$id": "https://github.com/iotaledger/tips/main/tips/TIP-0030/irc30.schema.json", 4 | "title": "IRC30 Native Token Metadata Schema", 5 | "description": "A JSON schema for validating IRC30 compliant native token metadata", 6 | "type": "object", 7 | "properties": { 8 | "standard": { 9 | "description": "The IRC standard of the token metadata", 10 | "type": "string", 11 | "pattern": "^IRC30$" 12 | }, 13 | "name": { 14 | "description": "The human-readable name of the native token", 15 | "type": "string" 16 | }, 17 | "description": { 18 | "description": "The human-readable description of the token", 19 | "type": "string" 20 | }, 21 | "symbol": { 22 | "description": "The symbol/ticker of the token", 23 | "type": "string" 24 | }, 25 | "decimals": { 26 | "description": "Number of decimals the token uses (divide the token amount by decimals to get its user representation)", 27 | "type": "integer", 28 | "minimum": 0 29 | }, 30 | "url": { 31 | "description": "URL pointing to more resources about the token", 32 | "type": "string" 33 | }, 34 | "logoUrl": { 35 | "description": "URL pointing to an image resource of the token logo", 36 | "type": "string" 37 | }, 38 | "logo": { 39 | "description": "The logo of the token encoded as a byte string", 40 | "type": "string" 41 | } 42 | }, 43 | "required": [ "standard", "name", "symbol", "decimals" ] 44 | } 45 | -------------------------------------------------------------------------------- /tips/TIP-0030/tip-0030.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 30 3 | title: Native Token Metadata JSON Schema 4 | description: A JSON schema that describes token metadata format for native token foundries. 5 | author: Levente Pap @lzpap 6 | discussions-to: https://github.com/iotaledger/tips/pull/68 7 | status: Active 8 | type: Standards 9 | layer: IRC 10 | created: 2022-03-25 11 | requires: 18 12 | --- 13 | 14 | ## Abstract 15 | 16 | This TIP describes a JSON schema to store native token metadata on-chain in foundry outputs. 17 | 18 | ## Motivation 19 | 20 | By introducing a standardized token metadata schema we aim to address the following problems: 21 | - Storing structured token metadata on-chain, 22 | - Interoperability of dApps, wallets and clients handling native tokens, 23 | - Creating the possibility of off-chain token verification based on social consensus. 24 | 25 | ## Specification 26 | 27 | Native tokens are user defined tokens controlled by foundries, as described in 28 | [TIP-18](../TIP-0018/tip-0018.md). Each native token is identified by its 38 bytes long 29 | Token ID, that also identifies the unique identifier of the foundry, Foundry ID. 30 | 31 | Given Foundry ID, the most recent unspent foundry output controlling the supply of the native token can be 32 | fetched via the UTXO indexer API defined in [draft TIP 26](https://github.com/iotaledger/tips/pull/62). 33 | 34 | The foundry output may contain an immutable Metadata Feature that holds raw binary data. By encoding metadata in 35 | JSON format adhering to the JSON schema defined in this TIP and placing it in the immutable Metadata Feature of 36 | a foundry output, issuers can supply metadata to wallets, dApps and clients on-tangle, without the need for a 37 | metadata server. 38 | 39 | Standardizing the JSON schema for token metadata plays an important role in establishing interoperability of 40 | decentralized applications and wallets. 41 | 42 | ### JSON Schema 43 | 44 | The proposed JSON schema is located [here](./irc30.schema.json): 45 | 46 | ```json 47 | { 48 | "$schema": "https://json-schema.org/draft/2020-12/schema", 49 | "$id": "https://github.com/iotaledger/tips/main/tips/TIP-0030/irc30.schema.json", 50 | "title": "IRC30 Native Token Metadata Schema", 51 | "description": "A JSON schema for IRC30 compliant native token metadata", 52 | "type": "object", 53 | "properties": { 54 | "standard": { 55 | "description": "The IRC standard of the token metadata", 56 | "type": "string", 57 | "pattern": "^IRC30$" 58 | }, 59 | "name": { 60 | "description": "The human-readable name of the native token", 61 | "type": "string" 62 | }, 63 | "description": { 64 | "description": "The human-readable description of the token", 65 | "type": "string" 66 | }, 67 | "symbol": { 68 | "description": "The symbol/ticker of the token", 69 | "type": "string" 70 | }, 71 | "decimals": { 72 | "description": "Number of decimals the token uses (divide the token amount by 10^decimals to get its user representation)", 73 | "type": "integer", 74 | "minimum": 0 75 | }, 76 | "url": { 77 | "description": "URL pointing to more resources about the token", 78 | "type": "string" 79 | }, 80 | "logoUrl": { 81 | "description": "URL pointing to an image resource of the token logo", 82 | "type": "string" 83 | }, 84 | "logo": { 85 | "description": "The svg logo of the token encoded as a byte string", 86 | "type": "string" 87 | } 88 | }, 89 | "required": [ 90 | "standard", 91 | "name", 92 | "symbol", 93 | "decimals" 94 | ] 95 | } 96 | ``` 97 | 98 | ### Examples 99 | 100 | The following examples are located in the [`examples/`](https://github.com/iotaledger/tips/tree/main/tips/TIP-0030/examples) folder. 101 | 102 | To try the schema validation in Python, install [jsonschema](https://python-jsonschema.readthedocs.io/en/stable/) 103 | package by running: 104 | ```bash 105 | pip install jsonschema 106 | ``` 107 | Then navigate into the folder of this TIP (`tips/TIP-0030/`) of the cloned 108 | [TIP repository](https://github.com/iotaledger/tips) and run the validation in console: 109 | ```bash 110 | jsonschema -i examples/1-valid.json irc30.schema.json 111 | ``` 112 | 113 | If the validation fails, error messages are printed out to the console. 114 | 115 | #### 1. A minimum valid token metadata JSON 116 | 117 | ```json 118 | { 119 | "standard": "IRC30", 120 | "name": "FooCoin", 121 | "symbol": "FOO", 122 | "decimals": 3, 123 | } 124 | ``` 125 | 126 | #### 2. A more descriptive valid token metadata JSON 127 | 128 | ```json 129 | { 130 | "standard": "IRC30", 131 | "name": "FooCoin", 132 | "description": "FooCoin is the utility and governance token of FooLand, a revolutionary protocol in the play-to-earn crypto gaming field.", 133 | "symbol": "FOO", 134 | "decimals": 3, 135 | "url": "https://foocoin.io", 136 | "logoUrl": "https://ipfs.io/ipfs/QmR36VFfo1hH2RAwVs4zVJ5btkopGip5cW7ydY4jUQBrkR" 137 | } 138 | ``` 139 | 140 | #### 3. Invalid token metadata 141 | 142 | ```json 143 | { 144 | "standard": "IRC27", 145 | "name": "FooCoin", 146 | "description": "FooCoin is the utility and governance token of FooLand, a revolutionary protocol in the play-to-earn crypto gaming field.", 147 | "decimals": 0.5 148 | } 149 | ``` 150 | The metadata JSON is not a valid IRC30 token metadata JSON as: 151 | - The `standard` field is not `IRC30` 152 | - `symbol` property is missing, although it is required, and 153 | - `decimals` is not an integer. 154 | 155 | ## Rationale 156 | 157 | The main motive of this design is to allow interoperability of applications handling native tokens while also leaving 158 | room for optional, non-required fields that might be needed for certain use-cases. 159 | 160 | Alternatively, a non-standardized token metadata structure would lead to a fragmented application space and hence 161 | worse developer and user experiences while interacting with the network. 162 | 163 | ## Backwards Compatibility 164 | IRC30 aims to be a minimum standard that can be compatible with future token standards, as long as the few originally 165 | required fields are respected. 166 | 167 | ## Copyright 168 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 169 | -------------------------------------------------------------------------------- /tips/TIP-0031/tip-0031.md: -------------------------------------------------------------------------------- 1 | --- 2 | tip: 31 3 | title: Bech32 Address Format 4 | description: Extendable address format supporting various signature schemes and address types 5 | author: Wolfgang Welz (@Wollac) , Levente Pap (@lzpap) 6 | discussions-to: https://github.com/iotaledger/tips/pull/20 7 | status: Active 8 | type: Standards 9 | layer: Interface 10 | created: 2022-04-04 11 | replaces: 11 12 | --- 13 | 14 | # Summary 15 | 16 | This document proposes an extendable address format for the IOTA protocol supporting various signature schemes and address types. It relies on the [Bech32](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki) format to provide a compact, human-readable encoding with strong error correction guarantees. 17 | 18 | # Motivation 19 | 20 | With [Chrysalis](https://roadmap.iota.org/chrysalis), IOTA started using Ed25519 to generate digital signatures, in which addresses correspond to a BLAKE2b-256 hash. It is necessary to define a universal and extendable address format capable of encoding different types of addresses (introduced also in [TIP-18](../TIP-0018/tip-0018.md)). 21 | 22 | The legacy IOTA protocol (1.0, pre-Chrysalis) relies on Base27 addresses with a truncated Kerl checksum. However, both the character set and the checksum algorithm have limitations: 23 | - Base27 is designed for ternary and is ill-suited for binary data. 24 | - The Kerl hash function also requires ternary input. Further, it is slow and provides no error-detection guarantees. 25 | - It does not support the addition of version or type information to distinguish between different kinds of addresses with the same length. 26 | 27 | All of these points are addressed in the Bech32 format introduced in [BIP-0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki): In addition to the usage of the human-friendly Base32 encoding with an optimized character set, it implements a [BCH code](https://en.wikipedia.org/wiki/BCH_code) that _guarantees detection_ of any error affecting at most four characters and has less than a 1 in 109 chance of failing to detect more errors. 28 | 29 | This TIP proposes a simple and extendable binary serialization for addresses of different types that is then Bech32 encoded to provide a unique appearance for human-facing applications such as wallets. 30 | 31 | # Detailed design 32 | 33 | ## Binary serialization 34 | 35 | The address format uses a simple serialization scheme which consists of two parts: 36 | 37 | - The first byte describes the type of the address. 38 | - The remaining bytes contain the type-specific raw address bytes. 39 | 40 | Currently, only three kind of addresses are supported: 41 | - Ed25519, where the address consists of the BLAKE2b-256 hash of the Ed25519 public key. 42 | - Alias, where the address consists of the BLAKE2b-256 hash of the Output ID (defined in [TIP-0020](../TIP-0020/tip-0020.md#utxo-input)) that created the alias. 43 | - NFT, where the address consists of the BLAKE2b-256 hash of the Output ID (defined in [TIP-0020](../TIP-0020/tip-0020.md#utxo-input)) that created the NFT. 44 | 45 | They are serialized as follows: 46 | 47 | | Type | First byte | Address bytes | 48 | |---------|------------|--------------------------------------------------------------------------------| 49 | | Ed25519 | `0x00` | 32 bytes: The BLAKE2b-256 hash of the Ed25519 public key. | 50 | | Alias | `0x08` | 32 bytes: The BLAKE2b-256 hash of the Output ID that created the alias. | 51 | | NFT | `0x10` | 32 bytes: The BLAKE2b-256 hash of the Output ID that created the NFT. | 52 | 53 | 54 | ## Bech32 for human-readable encoding 55 | 56 | The human-readable encoding of the address is Bech32 (as described in [BIP-0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)). A Bech32 string is at most 90 characters long and consists of: 57 | 58 | - The **human-readable part** (HRP), which conveys the protocol and distinguishes between the different networks. HRPs are registered in [SLIP-0173]( https://github.com/satoshilabs/slips/blob/master/slip-0173.md): 59 | - `iota` is the human-readable part for IOTA Mainnet addresses (IOTA tokens) 60 | - `atoi` is the human-readable part for IOTA Testnet/Devnet addresses 61 | - `smr` is the human-readable part for Shimmer network addresses (Shimmer tokens) 62 | - `rms` is the human-readable part for Shimmer Testnet/Devnet addresses 63 | - The **separator**, which is always `1`. 64 | - The **data part**, which consists of the Base32 encoded serialized address and the 6-character checksum. 65 | 66 | ## Examples 67 | - Ed25519 Address 68 | - Ed25519 public key (32-byte): `6f1581709bb7b1ef030d210db18e3b0ba1c776fba65d8cdaad05415142d189f8` 69 | - BLAKE2b-256 hash (32-byte): `efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3` 70 | - serialized (33-byte): `00efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3` 71 | - Bech32 string: 72 | - **IOTA** (64-char):`iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx` 73 | - **IOTA Testnet** (64-char): `atoi1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6x8x4r7t` 74 | - **Shimmer** (63-char): `smr1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xhcazjh` 75 | - **Shimmer Testnet**: (63-char) `rms1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xrlkcfw` 76 | - Alias Address 77 | - _Output ID_ (34-byte): `52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c6490000` 78 | - _Alias ID_, BLAKE2b-256 hash (32-byte): `fe80c2eb7c736da2f7c98ecf135ee9e34e4e076afe6e1dfebc9ec578b8f56d2f` 79 | - serialized (33-byte): `08fe80c2eb7c736da2f7c98ecf135ee9e34e4e076afe6e1dfebc9ec578b8f56d2f` 80 | - Bech32 string: 81 | - **IOTA** (64-char): `iota1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj76j6rev` 82 | - **IOTA Testnet** (64-char): `atoi1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7autzrp` 83 | - **Shimmer** (63-char): `smr1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7dzrr0a` 84 | - **Shimmer Testnet** (63-char): `rms1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7e9ge5y` 85 | - NFT Address 86 | - _Output ID_ (34-byte): `97b9d84d33419199483daab1f81ddccdeff478b6ee9040cfe026c517f67757880000` 87 | - _NFT ID_, BLAKE2b-256 hash (32-byte): `3159b115e27128b6db16db5e61f1aa4c70d84a99be753faa3ee70d9ad9c6a6b7` 88 | - serialized (33-byte): `103159b115e27128b6db16db5e61f1aa4c70d84a99be753faa3ee70d9ad9c6a6b7` 89 | - Bech32 string: 90 | - **IOTA** (64-char): `iota1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntw0vklm7` 91 | - **IOTA Testnet** (64-char): `atoi1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntwgz87pn` 92 | - **Shimmer** (63-char): `smr1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntwcu0ld0` 93 | - **Shimmer Testnet** (63-char): `rms1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntwvmy9kk` 94 | 95 | # Drawbacks 96 | 97 | - Addresses look fundamentally different from the established 81-tryte legacy IOTA addresses. However, since the switch from binary to ternary and Chrysalis in general was a substantial change, this is a very reasonable and desired consequence. 98 | - A four character HRP plus one type byte only leaves a maximum of 48 bytes for the actual address. 99 | 100 | # Rationale and alternatives 101 | 102 | - There are several ways to convert the binary serialization into a human-readable format, e.g. Base58 or hexadecimal. The Bech32 format, however, offers the best compromise between compactness and error correction guarantees. A more detailed motivation can be found in [BIP-0173 Motivation](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#motivation). 103 | - The binary serialization itself must be as compact as possible while still allowing you to distinguish between different address types of the same byte length. As such, the introduction of a version byte offers support for up to 256 different kinds of addresses at only the cost of one single byte. 104 | 105 | # Reference implementation 106 | 107 | Example Go implementation in [wollac/iota-crypto-demo](https://github.com/Wollac/iota-crypto-demo): 108 | - Bech32 encoding: [pkg/bech32](https://github.com/Wollac/iota-crypto-demo/tree/master/pkg/bech32) 109 | - Example: [examples/bech32](https://github.com/Wollac/iota-crypto-demo/tree/master/examples/bech32) 110 | 111 | Example Go implementation in [iotaledger/iota.go/v3](https://github.com/iotaledger/iota.go/tree/v3): 112 | - Bech32 encoding: [bech32](https://github.com/iotaledger/iota.go/tree/v3/bech32) 113 | - Address implementations: [Ed25519](https://github.com/iotaledger/iota.go/blob/v3/address_ed25519.go), [Alias](https://github.com/iotaledger/iota.go/blob/v3/address_alias.go), [NFT](https://github.com/iotaledger/iota.go/blob/v3/address_nft.go) 114 | 115 | # Copyright 116 | 117 | Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 118 | -------------------------------------------------------------------------------- /tips/TIP-0032/genesis-supply.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0032/genesis-supply.png -------------------------------------------------------------------------------- /tips/TIP-0035/delta_snapshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0035/delta_snapshot.png -------------------------------------------------------------------------------- /tips/TIP-0035/full_snapshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/iotaledger/tips/f95ce04680d53fef0ade905c03109ce6fd600af7/tips/TIP-0035/full_snapshot.png --------------------------------------------------------------------------------