├── .gitattributes ├── .github ├── CODEOWNERS └── workflows │ ├── link-check-config.json │ ├── link-check.yml │ └── markdown-lint.yml ├── .gitignore ├── .markdownlint-cli2.jsonc ├── .markdownlint.jsonc ├── CHANGELOG.md ├── LICENSE ├── Makefile ├── README.md ├── archive ├── README.md ├── papers │ └── 2020-05 │ │ ├── Makefile │ │ ├── README.md │ │ ├── aspell_dict │ │ ├── build │ │ └── paper.pdf │ │ └── src │ │ ├── LICENSE │ │ ├── acknowledgements.md │ │ ├── appendix-a.md │ │ ├── appendix-b.md │ │ ├── appendix-c.md │ │ ├── bibliography.bib │ │ ├── bibliography.csl │ │ ├── channels.md │ │ ├── clients.md │ │ ├── connections.md │ │ ├── fungible-token-transfer.md │ │ ├── host-requirements.md │ │ ├── introduction.md │ │ ├── metadata.yaml │ │ ├── paper.md │ │ ├── relayers.md │ │ ├── structure.md │ │ ├── template.latex │ │ ├── testing-and-deployment.md │ │ └── usage-patterns.md └── v0_3_1_IBC.pdf ├── assets ├── interchain-standards-image.jpg └── interchain-standards.png ├── meta ├── CONTRIBUTING.md ├── PROCESS.md └── STANDARDS_COMMITTEE.md └── spec ├── IBC_V2 ├── README.md └── core │ ├── ics-002-client-semantics │ └── README.md │ ├── ics-004-packet-semantics │ ├── PACKET.md │ └── PACKET_HANDLER.md │ ├── ics-005-port-allocation │ └── README.md │ ├── ics-024-host-requirements │ └── README.md │ └── ics-026-application-callbacks │ └── README.md ├── app ├── ics-020-fungible-token-transfer │ ├── README.md │ └── deprecated │ │ ├── README.md │ │ ├── forwarding-3-chains-failure.png │ │ ├── forwarding-3-chains-success.png │ │ ├── forwarding-3-chains.excalidraw │ │ └── source-and-sink-zones.png ├── ics-027-interchain-accounts │ └── README.md ├── ics-028-cross-chain-validation │ ├── README.md │ ├── data_structures.md │ ├── figures │ │ ├── ccv-distribution-overview.excalidraw │ │ ├── ccv-distribution-overview.png │ │ ├── ccv-evidence-overview.excalidraw │ │ ├── ccv-evidence-overview.png │ │ ├── ccv-height-mapping-overview.excalidraw │ │ ├── ccv-height-mapping-overview.png │ │ ├── ccv-init-overview.excalidraw │ │ ├── ccv-init-overview.png │ │ ├── ccv-mapping-intuition.excalidraw │ │ ├── ccv-mapping-intuition.png │ │ ├── ccv-preccv-init-overview.excalidraw │ │ ├── ccv-preccv-init-overview.png │ │ ├── ccv-unbonding-overview.excalidraw │ │ ├── ccv-unbonding-overview.png │ │ ├── ccv-vsc-overview.excalidraw │ │ └── ccv-vsc-overview.png │ ├── methods.md │ ├── overview_and_basic_concepts.md │ ├── system_model_and_properties.md │ └── technical_specification.md ├── ics-029-fee-payment │ └── README.md ├── ics-030-middleware │ └── README.md ├── ics-031-crosschain-queries │ └── README.md ├── ics-100-atomic-swap │ ├── README.md │ └── ibcswap.png └── ics-721-nft-transfer │ └── README.md ├── client ├── Rollup-Integration-guide.md ├── ics-006-solo-machine-client │ └── README.md ├── ics-007-tendermint-client │ └── README.md ├── ics-008-wasm-client │ └── README.md ├── ics-009-loopback-cilent │ └── README.md └── ics-010-grandpa-client │ └── README.md ├── core ├── ics-002-client-semantics │ └── README.md ├── ics-003-connection-semantics │ ├── README.md │ ├── client-validation-removal.excalidraw │ ├── client-validation-removal.md │ ├── client-validation-removal.png │ └── state.png ├── ics-004-channel-and-packet-semantics │ ├── README.md │ ├── UPGRADES.md │ ├── channel-state-machine.png │ ├── channel-upgrade-flow.png │ ├── dataflow.png │ ├── packet-state-machine.png │ └── packet-transit.png ├── ics-005-port-allocation │ └── README.md ├── ics-023-vector-commitments │ └── README.md ├── ics-024-host-requirements │ └── README.md ├── ics-025-handler-interface │ └── README.md ├── ics-026-routing-module │ ├── README.md │ └── UPGRADES.md └── ics-033-multi-hop │ ├── README.md │ ├── proof_generation.png │ ├── proof_query.png │ ├── proof_query_algorithm.png │ ├── proof_verification.png │ ├── relayer_calc_update_heights.png │ └── relayer_query_proof_and_submit.png ├── ics-001-ics-standard └── README.md ├── ics-template.md └── relayer └── ics-018-relayer-algorithms └── README.md /.gitattributes: -------------------------------------------------------------------------------- 1 | _layouts/* linguist-vendored 2 | *.pdf filter=lfs diff=lfs merge=lfs -text 3 | *.png filter=lfs diff=lfs merge=lfs -text 4 | *.jpg filter=lfs diff=lfs merge=lfs -text 5 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Default owners for repository 2 | # 2/n quorum required for merge 3 | 4 | * @adityasripal @cwgoes @angbrav @damiannolan @sangier 5 | 6 | # CODEOWNERS for the CODEOWNER file 7 | 8 | /.github/CODEOWNERS @adityasripal @cwgoes @angbrav 9 | 10 | # CODEOWNERS for the specs 11 | 12 | /spec/app @adityasripal @cwgoes @damiannolan @sangier 13 | 14 | /spec/app/ics-028-cross-chain-validation @mpoke @adityasripal @cwgoes @angbrav @insumity 15 | -------------------------------------------------------------------------------- /.github/workflows/link-check-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "ignorePatterns": [ 3 | { 4 | "pattern": "(localhost)" 5 | } 6 | ], 7 | "replacementPatterns": [ 8 | { 9 | "pattern": "(^\\/(architecture|event)[^#]*)(#.*|$)", 10 | "replacement": "$1.md$3" 11 | }, 12 | { 13 | "pattern": "^(\\/|@site\\/)", 14 | "replacement": "{{BASEURL}}/docs/" 15 | } 16 | ], 17 | "retryOn429": true, 18 | "retryCount": 3, 19 | "fallbackRetryDelay": "10s" 20 | } 21 | -------------------------------------------------------------------------------- /.github/workflows/link-check.yml: -------------------------------------------------------------------------------- 1 | name: Check Markdown links 2 | on: [push, pull_request] 3 | jobs: 4 | markdown-link-check: 5 | runs-on: ubuntu-latest 6 | steps: 7 | - uses: actions/checkout@v4 8 | - uses: gaurav-nelson/github-action-markdown-link-check@v1 9 | 10 | -------------------------------------------------------------------------------- /.github/workflows/markdown-lint.yml: -------------------------------------------------------------------------------- 1 | name: Markdown Lint 2 | on: 3 | pull_request: 4 | branches: 5 | - main 6 | paths: 7 | - "**.md" 8 | - "!.github/**" 9 | jobs: 10 | lint: 11 | runs-on: ubuntu-latest 12 | steps: 13 | - uses: actions/checkout@v4 14 | with: 15 | fetch-depth: 0 16 | - uses: tj-actions/changed-files@v41 17 | id: changed-files 18 | with: 19 | files: '**/*.md' 20 | separator: "," 21 | - uses: DavidAnson/markdownlint-cli2-action@v13 22 | if: steps.changed-files.outputs.any_changed == 'true' 23 | with: 24 | globs: ${{ steps.changed-files.outputs.all_changed_files }} 25 | separator: "," 26 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # editors 2 | .idea/ 3 | .vscode/ 4 | 5 | # macOS 6 | .DS_Store 7 | -------------------------------------------------------------------------------- /.markdownlint-cli2.jsonc: -------------------------------------------------------------------------------- 1 | // This file is used by markdownlint-cli2 to configure the linting process 2 | // in conjunction with .markdownlint.jsonc. 3 | { 4 | "ignores": [ 5 | ".github", 6 | "**/CHANGELOG.md" 7 | ] 8 | } 9 | -------------------------------------------------------------------------------- /.markdownlint.jsonc: -------------------------------------------------------------------------------- 1 | { 2 | "default": true, 3 | "MD003": { "style": "atx" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md003---heading-style 4 | "MD004": { "style": "dash" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md004---unordered-list-style 5 | "MD007": { "indent": 2 }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md007---unordered-list-indentation 6 | "MD009": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md009---trailing-spaces 7 | "MD010": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md010---hard-tabs 8 | "MD013": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length 9 | "MD024": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content 10 | "MD025": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md025---multiple-top-level-headings-in-the-same-document 11 | "MD029": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix 12 | "MD031": { "list_items": false }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines 13 | "MD033": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033---inline-html 14 | "MD036": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md036---emphasis-used-instead-of-a-heading 15 | "MD041": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041---first-line-in-a-file-should-be-a-top-level-heading 16 | "MD049": { "style": "asterisk" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md049---emphasis-style-should-be-consistent 17 | "MD050": { "style": "asterisk" } // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md050---strong-style-should-be-consistent 18 | } 19 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | 37 | 38 | # Changelog 39 | 40 | ## [Unreleased] 41 | 42 | ### API-Breaking 43 | 44 | - [\#873](https://github.com/cosmos/ibc/pull/873) Defines the connection `Version` datatype and adjusts the signature of `getCompatibleVersions()` and `pickVersion()` accordingly 45 | - [\#813](https://github.com/cosmos/ibc/pull/813) Breaks up `checkValidityAndUpdateState` into `verifyClientMessage` and `UpdateState` 46 | - [\#813](https://github.com/cosmos/ibc/pull/813) Breaks up `checkMisbehaviourAndUpdateState` into `checkForMisbehaviour` and `UpdateStateOnMisbehaviour` 47 | - [\#813](https://github.com/cosmos/ibc/pull/813) Removes `Header` and `Misbehaviour` interfaces for generic `ClientMessage` interface 48 | - [\#813](https://github.com/cosmos/ibc/pull/813) Removes specific verify functions from ClientState interface in exchange for generic `verifyMembership` and `verifyNonMembership` methods 49 | - [\#813](https://github.com/cosmos/ibc/pull/813) Adds `getTimeoutAtHeight` method to ClientState interface. 50 | 51 | ### Bug Fixes 52 | 53 | - [\#808](https://github.com/cosmos/ibc/pull/808) Fix channel sequence paths in ICS4 54 | - [\#863](https://github.com/cosmos/ibc/pull/863) Fix allowed range for `trustLevel` 55 | - [\#878](https://github.com/cosmos/ibc/pull/878) Removes broken localhost client spec ICS9 56 | 57 | ### Improvements 58 | 59 | - [\#802](https://github.com/cosmos/ibc/pull/802) Move `ClientState` to the `provableStore` and add `ClientState` validation in `connOpenTry` and `connOpenAck` 60 | - [\#803](https://github.com/cosmos/ibc/pull/803) Changed UpgradeState enums to match the opening handshake enum style. 61 | - [\#804](https://github.com/cosmos/ibc/pull/804) Increment upgrade sequence at the start of a new handshake rather than the end of a completed handshake 62 | - [\#806](https://github.com/cosmos/ibc/pull/806) Adds previous version to UpgradeInit and UpgradeTry callback arguments 63 | - [\#807](https://github.com/cosmos/ibc/pull/807) Upgrade keys will now prefix the channel path to align with the rest of ICS4 keys 64 | - [\#842](https://github.com/cosmos/ibc/pull/842) Adds metadata field to FungibleTokenPacketData 65 | - [\#844](https://github.com/cosmos/ibc/pull/844) Adds event emission in `recvPacket` when `packet.sequence < nextSequenceRecv` for ordered channels and when `packetReceipt != null` for unordered channels 66 | - [\#845](https://github.com/cosmos/ibc/pull/845) Adds explanation about `onRecvPacket` callback returning an error in interchain accounts controller modules 67 | - [\#886](https://github.com/cosmos/ibc/pull/886) Makes `icacontroller-` prefix optional in ICA controller port identifier 68 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Interchain Standards 2 | License: Apache2.0 3 | 4 | Apache License 5 | Version 2.0, January 2004 6 | http://www.apache.org/licenses/ 7 | 8 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 9 | 10 | 1. Definitions. 11 | 12 | "License" shall mean the terms and conditions for use, reproduction, 13 | and distribution as defined by Sections 1 through 9 of this document. 14 | 15 | "Licensor" shall mean the copyright owner or entity authorized by 16 | the copyright owner that is granting the License. 17 | 18 | "Legal Entity" shall mean the union of the acting entity and all 19 | other entities that control, are controlled by, or are under common 20 | control with that entity. For the purposes of this definition, 21 | "control" means (i) the power, direct or indirect, to cause the 22 | direction or management of such entity, whether by contract or 23 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 24 | outstanding shares, or (iii) beneficial ownership of such entity. 25 | 26 | "You" (or "Your") shall mean an individual or Legal Entity 27 | exercising permissions granted by this License. 28 | 29 | "Source" form shall mean the preferred form for making modifications, 30 | including but not limited to software source code, documentation 31 | source, and configuration files. 32 | 33 | "Object" form shall mean any form resulting from mechanical 34 | transformation or translation of a Source form, including but 35 | not limited to compiled object code, generated documentation, 36 | and conversions to other media types. 37 | 38 | "Work" shall mean the work of authorship, whether in Source or 39 | Object form, made available under the License, as indicated by a 40 | copyright notice that is included in or attached to the work 41 | (an example is provided in the Appendix below). 42 | 43 | "Derivative Works" shall mean any work, whether in Source or Object 44 | form, that is based on (or derived from) the Work and for which the 45 | editorial revisions, annotations, elaborations, or other modifications 46 | represent, as a whole, an original work of authorship. For the purposes 47 | of this License, Derivative Works shall not include works that remain 48 | separable from, or merely link (or bind by name) to the interfaces of, 49 | the Work and Derivative Works thereof. 50 | 51 | "Contribution" shall mean any work of authorship, including 52 | the original version of the Work and any modifications or additions 53 | to that Work or Derivative Works thereof, that is intentionally 54 | submitted to Licensor for inclusion in the Work by the copyright owner 55 | or by an individual or Legal Entity authorized to submit on behalf of 56 | the copyright owner. For the purposes of this definition, "submitted" 57 | means any form of electronic, verbal, or written communication sent 58 | to the Licensor or its representatives, including but not limited to 59 | communication on electronic mailing lists, source code control systems, 60 | and issue tracking systems that are managed by, or on behalf of, the 61 | Licensor for the purpose of discussing and improving the Work, but 62 | excluding communication that is conspicuously marked or otherwise 63 | designated in writing by the copyright owner as "Not a Contribution." 64 | 65 | "Contributor" shall mean Licensor and any individual or Legal Entity 66 | on behalf of whom a Contribution has been received by Licensor and 67 | subsequently incorporated within the Work. 68 | 69 | 2. Grant of Copyright License. Subject to the terms and conditions of 70 | this License, each Contributor hereby grants to You a perpetual, 71 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 72 | copyright license to reproduce, prepare Derivative Works of, 73 | publicly display, publicly perform, sublicense, and distribute the 74 | Work and such Derivative Works in Source or Object form. 75 | 76 | 3. Grant of Patent License. Subject to the terms and conditions of 77 | this License, each Contributor hereby grants to You a perpetual, 78 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 79 | (except as stated in this section) patent license to make, have made, 80 | use, offer to sell, sell, import, and otherwise transfer the Work, 81 | where such license applies only to those patent claims licensable 82 | by such Contributor that are necessarily infringed by their 83 | Contribution(s) alone or by combination of their Contribution(s) 84 | with the Work to which such Contribution(s) was submitted. If You 85 | institute patent litigation against any entity (including a 86 | cross-claim or counterclaim in a lawsuit) alleging that the Work 87 | or a Contribution incorporated within the Work constitutes direct 88 | or contributory patent infringement, then any patent licenses 89 | granted to You under this License for that Work shall terminate 90 | as of the date such litigation is filed. 91 | 92 | 4. Redistribution. You may reproduce and distribute copies of the 93 | Work or Derivative Works thereof in any medium, with or without 94 | modifications, and in Source or Object form, provided that You 95 | meet the following conditions: 96 | 97 | (a) You must give any other recipients of the Work or 98 | Derivative Works a copy of this License; and 99 | 100 | (b) You must cause any modified files to carry prominent notices 101 | stating that You changed the files; and 102 | 103 | (c) You must retain, in the Source form of any Derivative Works 104 | that You distribute, all copyright, patent, trademark, and 105 | attribution notices from the Source form of the Work, 106 | excluding those notices that do not pertain to any part of 107 | the Derivative Works; and 108 | 109 | (d) If the Work includes a "NOTICE" text file as part of its 110 | distribution, then any Derivative Works that You distribute must 111 | include a readable copy of the attribution notices contained 112 | within such NOTICE file, excluding those notices that do not 113 | pertain to any part of the Derivative Works, in at least one 114 | of the following places: within a NOTICE text file distributed 115 | as part of the Derivative Works; within the Source form or 116 | documentation, if provided along with the Derivative Works; or, 117 | within a display generated by the Derivative Works, if and 118 | wherever such third-party notices normally appear. The contents 119 | of the NOTICE file are for informational purposes only and 120 | do not modify the License. You may add Your own attribution 121 | notices within Derivative Works that You distribute, alongside 122 | or as an addendum to the NOTICE text from the Work, provided 123 | that such additional attribution notices cannot be construed 124 | as modifying the License. 125 | 126 | You may add Your own copyright statement to Your modifications and 127 | may provide additional or different license terms and conditions 128 | for use, reproduction, or distribution of Your modifications, or 129 | for any such Derivative Works as a whole, provided Your use, 130 | reproduction, and distribution of the Work otherwise complies with 131 | the conditions stated in this License. 132 | 133 | 5. Submission of Contributions. Unless You explicitly state otherwise, 134 | any Contribution intentionally submitted for inclusion in the Work 135 | by You to the Licensor shall be under the terms and conditions of 136 | this License, without any additional terms or conditions. 137 | Notwithstanding the above, nothing herein shall supersede or modify 138 | the terms of any separate license agreement you may have executed 139 | with Licensor regarding such Contributions. 140 | 141 | 6. Trademarks. This License does not grant permission to use the trade 142 | names, trademarks, service marks, or product names of the Licensor, 143 | except as required for reasonable and customary use in describing the 144 | origin of the Work and reproducing the content of the NOTICE file. 145 | 146 | 7. Disclaimer of Warranty. Unless required by applicable law or 147 | agreed to in writing, Licensor provides the Work (and each 148 | Contributor provides its Contributions) on an "AS IS" BASIS, 149 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 150 | implied, including, without limitation, any warranties or conditions 151 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 152 | PARTICULAR PURPOSE. You are solely responsible for determining the 153 | appropriateness of using or redistributing the Work and assume any 154 | risks associated with Your exercise of permissions under this License. 155 | 156 | 8. Limitation of Liability. In no event and under no legal theory, 157 | whether in tort (including negligence), contract, or otherwise, 158 | unless required by applicable law (such as deliberate and grossly 159 | negligent acts) or agreed to in writing, shall any Contributor be 160 | liable to You for damages, including any direct, indirect, special, 161 | incidental, or consequential damages of any character arising as a 162 | result of this License or out of the use or inability to use the 163 | Work (including but not limited to damages for loss of goodwill, 164 | work stoppage, computer failure or malfunction, or any and all 165 | other commercial damages or losses), even if such Contributor 166 | has been advised of the possibility of such damages. 167 | 168 | 9. Accepting Warranty or Additional Liability. While redistributing 169 | the Work or Derivative Works thereof, You may choose to offer, 170 | and charge a fee for, acceptance of support, warranty, indemnity, 171 | or other liability obligations and/or rights consistent with this 172 | License. However, in accepting such obligations, You may act only 173 | on Your own behalf and on Your sole responsibility, not on behalf 174 | of any other Contributor, and only if You agree to indemnify, 175 | defend, and hold each Contributor harmless for any liability 176 | incurred by, or claims asserted against, such Contributor by reason 177 | of your accepting any such warranty or additional liability. 178 | 179 | END OF TERMS AND CONDITIONS 180 | 181 | APPENDIX: How to apply the Apache License to your work. 182 | 183 | To apply the Apache License to your work, attach the following 184 | boilerplate notice, with the fields enclosed by brackets "{}" 185 | replaced with your own identifying information. (Don't include 186 | the brackets!) The text should be enclosed in the appropriate 187 | comment syntax for the file format. We also recommend that a 188 | file or class name and description of purpose be included on the 189 | same "printed page" as the copyright notice for easier 190 | identification within third-party archives. 191 | 192 | Copyright 2019 All in Bits, Inc 193 | 194 | Licensed under the Apache License, Version 2.0 (the "License"); 195 | you may not use this file except in compliance with the License. 196 | You may obtain a copy of the License at 197 | 198 | http://www.apache.org/licenses/LICENSE-2.0 199 | 200 | Unless required by applicable law or agreed to in writing, software 201 | distributed under the License is distributed on an "AS IS" BASIS, 202 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 203 | See the License for the specific language governing permissions and 204 | limitations under the License. 205 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | #!/usr/bin/make -f 2 | 3 | ############################################################################### 4 | ### Linting ### 5 | ############################################################################### 6 | 7 | docs-lint: 8 | markdownlint-cli2 "**.md" 9 | 10 | docs-lint-fix: 11 | markdownlint-cli2-fix "**.md" 12 | 13 | .PHONY: docs-lint docs-lint-fix 14 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # IBC 2 | 3 | ![banner](./assets/interchain-standards.png) 4 | 5 | ## Synopsis 6 | 7 | This repository is the canonical location for development and documentation of the inter-blockchain communication protocol (IBC). 8 | 9 | It shall be used to consolidate design rationale, protocol semantics, and encoding descriptions for IBC, including both the core transport, authentication, & ordering layer (IBC/TAO) and the application layers describing packet encoding & processing semantics (IBC/APP). 10 | 11 | Contributions are welcome. See [CONTRIBUTING.md](meta/CONTRIBUTING.md) for contribution guidelines. 12 | 13 | ## What is IBC? 14 | 15 | 16 | For a high-level explanation of what IBC is and how it works, please read [this blog post](https://medium.com/the-interchain-foundation/eli5-what-is-ibc-def44d7b5b4c). 17 | 18 | ## Interchain Standards 19 | 20 | All standards at or past the "Draft" stage are listed here in order of their ICS numbers, sorted by category. 21 | 22 | ### Meta 23 | 24 | | Interchain Standard Number | Standard Title | Stage | Maintainer | 25 | | ---------------------------------------- | -------------------------- | ----- | ------------- | 26 | | [1](spec/ics-001-ics-standard/README.md) | ICS Specification Standard | N/A | Protocol team | 27 | 28 | ### Core Transport 29 | 30 | | Interchain Standard Number | Standard Title | Stage | Implementations | Maintainer | 31 | | ------------------------------------------------------------- | -------------------------- | --------- | --------------- | ------------- | 32 | | [2](spec/core/ics-002-client-semantics/README.md) | Client Semantics | Candidate | [ibc-go](https://github.com/cosmos/ibc-go), [ibc-rs](https://github.com/cosmos/ibc-rs) | Protocol team | 33 | | [3](spec/core/ics-003-connection-semantics/README.md) | Connection Semantics | Candidate | [ibc-go](https://github.com/cosmos/ibc-go), [ibc-rs](https://github.com/cosmos/ibc-rs) | Protocol team | 34 | | [4](spec/core/ics-004-channel-and-packet-semantics/README.md) | Channel & Packet Semantics | Candidate | [ibc-go](https://github.com/cosmos/ibc-go), [ibc-rs](https://github.com/cosmos/ibc-rs) | Protocol team | 35 | | [5](spec/core/ics-005-port-allocation/README.md) | Port Allocation | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | Protocol team | 36 | | [23](spec/core/ics-023-vector-commitments/README.md) | Vector Commitments | Candidate | [ibc-go](https://github.com/cosmos/ibc-go), [ibc-rs](https://github.com/cosmos/ibc-rs) | Protocol team | 37 | | [24](spec/core/ics-024-host-requirements/README.md) | Host Requirements | Candidate | [ibc-go](https://github.com/cosmos/ibc-go), [ibc-rs](https://github.com/cosmos/ibc-rs) | Protocol team | 38 | | [25](spec/core/ics-025-handler-interface/README.md) | Handler Interface | Candidate | [ibc-go](https://github.com/cosmos/ibc-go), [ibc-rs](https://github.com/cosmos/ibc-rs) | Protocol team | 39 | | [26](spec/core/ics-026-routing-module/README.md) | Routing Module | Candidate | [ibc-go](https://github.com/cosmos/ibc-go), [ibc-rs](https://github.com/cosmos/ibc-rs) | Protocol team | 40 | | [33](spec/core/ics-033-multi-hop/README.md) | Multi-hop Messaging | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | Protocol team | 41 | 42 | ### Light Clients 43 | 44 | | Interchain Standard Number | Standard Title | Stage | Implementations | Maintainer | 45 | | --------------------------------------------------------------- | -------------------------- | ----- | --------------- | ------------- | 46 | | [6](spec/client/ics-006-solo-machine-client/README.md) | Solo Machine Client | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/light-clients/06-solomachine) | Protocol team | 47 | | [7](spec/client/ics-007-tendermint-client/README.md) | Tendermint Client | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/light-clients/07-tendermint), [ibc-rs](https://github.com/cosmos/ibc-rs/tree/main/ibc-clients/ics07-tendermint) | Protocol team | 48 | | [8](spec/client/ics-008-wasm-client/README.md) | Wasm Client | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/light-clients/08-wasm), [ibc-rs](https://github.com/cosmos/ibc-rs/tree/main/ibc-clients/ics08-wasm) | Protocol team / [Composable Finance](https://www.github.com/ComposableFi) | 49 | | [9](spec/client/ics-009-loopback-cilent/README.md) | Loopback Client | Draft | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/light-clients/09-localhost) | Protocol team | 50 | | [10](spec/client/ics-010-grandpa-client/README.md) | GRANDPA Client | Draft | | [Octopus Network](https://oct.network) | 51 | 52 | ### Relayer 53 | 54 | | Interchain Standard Number | Standard Title | Stage | Implementations | Maintainer | 55 | | ---------------------------------------------------------------- | -------------------------- | ----- | --------------- | ------------- | 56 | | [18](spec/relayer/ics-018-relayer-algorithms/README.md) | Relayer Algorithms | Finalized | [go-relayer](https://github.com/cosmos/relayer), [rust-relayer](https://github.com/informalsystems/hermes), [ts-relayer](https://github.com/confio/ts-relayer) | Protocol team | 57 | 58 | ### App 59 | 60 | | Interchain Standard Number | Version | Standard Title | Stage | Implementations | Maintainer | 61 | | -------------------------------------------------------- | ------- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------ | 62 | | [20](spec/app/ics-020-fungible-token-transfer/README.md) | v1 | Fungible Token Transfer | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/transfer), [ibc-rs](https://github.com/cosmos/ibc-rs/tree/main/ibc-apps/ics20-transfer) | Protocol team | 63 | | [20](spec/app/ics-020-fungible-token-transfer/deprecated/README.md) | v2 | Fungible Token Transfer | DEPRECATED | | Protocol team | 64 | | [27](spec/app/ics-027-interchain-accounts/README.md) | v1 | Interchain Accounts | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/27-interchain-accounts) | Protocol team | 65 | | [28](spec/app/ics-028-cross-chain-validation/README.md) | v1 | Cross-Chain Validation | Candidate | [interchain-security](https://github.com/cosmos/interchain-security/tree/main) | Cosmos Hub team | 66 | | [29](spec/app/ics-029-fee-payment) | v1 | General Relayer Incentivization Mechanism | DEPRECATED | | Protocol team | 67 | | [30](spec/app/ics-030-middleware) | v1 | IBC Application Middleware | N/A | N/A | Protocol team | 68 | | [31](spec/app/ics-031-crosschain-queries) | v1 | Cross-Chain Queries | Draft | N/A | Protocol team | 69 | | [32](https://github.com/strangelove-ventures/async-icq) | v1 | Interchain Queries | Candidate | [async-icq](https://github.com/strangelove-ventures/async-icq) | [Strangelove Ventures](https://strange.love) | 70 | | [100](spec/app/ics-100-atomic-swap) | v1 | Interchain Atomic Swap | Candidate | [ibcswap](https://github.com/ibcswap/ibcswap) | [Side Labs](https://side.one) | 71 | | [721](spec/app/ics-721-nft-transfer) | v1 | Non-Fungible Token Transfer | Candidate | [nft-transfer](https://github.com/bianjieai/nft-transfer) | [IRIS Network](https://www.irisnet.org) | 72 | 73 | ## Translations 74 | 75 | The Interchain Standards are also translated into the following languages: 76 | 77 | - [Chinese](https://github.com/octopus-network/ibc-spec-cn) 78 | -------------------------------------------------------------------------------- /archive/README.md: -------------------------------------------------------------------------------- 1 | # IBC archive 2 | 3 | This directory contains previous versions of the IBC specification that have been archived for further reference. 4 | 5 | 1. [IBC v0.3.1](./v0_3_1_IBC.pdf) 6 | 1. [2020-05 IBC paper](./papers/2020-05/build/paper.pdf) 7 | -------------------------------------------------------------------------------- /archive/papers/2020-05/Makefile: -------------------------------------------------------------------------------- 1 | FILES = src/paper.md \ 2 | src/metadata.yaml 3 | 4 | OUTPUT = build 5 | 6 | FLAGS = --bibliography=src/bibliography.bib \ 7 | --csl=src/bibliography.csl \ 8 | --filter pandoc-include \ 9 | -s \ 10 | -f markdown 11 | 12 | FLAGS_PDF = --template=src/template.latex 13 | 14 | all: pdf 15 | 16 | pdf: 17 | pandoc -o $(OUTPUT)/paper.pdf $(FLAGS) $(FLAGS_PDF) $(FILES) 18 | 19 | wc: 20 | wc src/*.md 21 | 22 | spellcheck: 23 | find ./src -type f -name "*.md" -exec aspell -p ./aspell_dict -x -d en_GB -c {} \; 24 | 25 | clean: 26 | rm -rf build/* 27 | 28 | .PHONY: all pdf wc clean 29 | -------------------------------------------------------------------------------- /archive/papers/2020-05/README.md: -------------------------------------------------------------------------------- 1 | Drafting an IBC paper. See [draft](./build/paper.pdf). 2 | 3 | Submission options: 4 | 5 | - [CES CfP (May 2020)](https://cryptoeconomicsystems.pubpub.org/spring20-journalcfp) 6 | - Up to 15,000 words 7 | - A4 style, submitted as PDF 8 | - Exclusive submission only 9 | - Remove author names from paper 10 | - Pre-prints OK 11 | - Prior work: 12 | - 13 | - 14 | - 15 | -------------------------------------------------------------------------------- /archive/papers/2020-05/aspell_dict: -------------------------------------------------------------------------------- 1 | personal_ws-1.1 en 126 2 | Adi 3 | Aditya 4 | Aggarwal 5 | Agoric 6 | Anca 7 | Axner 8 | BFT 9 | Buchman 10 | ChanCloseConfirm 11 | ChanCloseInit 12 | ChanOpenAck 13 | ChanOpenConfirm 14 | ChanOpenInit 15 | ChanOpenTry 16 | ConnOpenAck 17 | ConnOpenConfirm 18 | ConnOpenInit 19 | ConnOpenTry 20 | DNS 21 | Datagram 22 | Dev 23 | Ethereum 24 | GmbH 25 | Hibbert 26 | HotStuff 27 | IAVL 28 | IBC 29 | INIT 30 | Jae 31 | Juwoon 32 | Kunze 33 | Kwon 34 | Manian 35 | Meher 36 | Merkle 37 | Merklized 38 | Nakamoto 39 | Ojha 40 | Polkadot's 41 | QUIC 42 | SDK 43 | Seredinschi 44 | Sripal 45 | TCP 46 | TRYOPEN 47 | Tendermint 48 | Tribble 49 | UDP 50 | UX 51 | WASM 52 | XCMP 53 | Yun 54 | Zaki 55 | Zamfir 56 | Zampolin 57 | Zarko 58 | backend 59 | blockchain 60 | blockchains 61 | bytestring 62 | channelOnB 63 | channelOnD 64 | computable 65 | counterintuitive 66 | counterparty 67 | cryptographic 68 | dataflow 69 | datagram 70 | datagrams 71 | datastream 72 | dba 73 | denom 74 | encodings 75 | escrowed 76 | escrowing 77 | exfiltration 78 | fungibility 79 | incentivisation 80 | instantiations 81 | interblockchain 82 | interchain 83 | interoperating 84 | interoperation 85 | introspectable 86 | lifecycle 87 | liveness 88 | loopback 89 | md 90 | mempools 91 | onecolumn 92 | pagebreak 93 | permissioned 94 | permissioning 95 | permissionless 96 | permissionlessly 97 | portOnB 98 | portOnD 99 | pseudocode 100 | recv 101 | relayer 102 | relayers 103 | ruleset 104 | sharded 105 | sig 106 | src 107 | stateful 108 | statefulness 109 | subprotocol 110 | subprotocols 111 | texttt 112 | thresholding 113 | tokenholder 114 | tokenise 115 | tokenised 116 | tokenising 117 | topologies 118 | transactional 119 | twocolumn 120 | unbonding 121 | unescrowed 122 | unescrows 123 | unreceived 124 | validator 125 | verifier 126 | vspace 127 | whitepaper 128 | -------------------------------------------------------------------------------- /archive/papers/2020-05/build/paper.pdf: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:b51ddc477e4947303c72a2cd591dcc5a4b438fadf585753c991f6fe29d8bcb03 3 | size 352921 4 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2016 Santos Gallegos 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/acknowledgements.md: -------------------------------------------------------------------------------- 1 | The original idea of IBC was first outlined in the Cosmos whitepaper [@cosmos_whitepaper], and realisation of the protocol is made possible in practice by the Byzantine-fault-tolerant consensus and efficient light client verification of Tendermint, introduced in *Tendermint: Consensus without Mining* [@tendermint_consensus_without_mining] and updated in *The latest gossip on BFT consensus* [@tendermint_latest_gossip]. An earlier version of the IBC specification [@ethan_frey_ibc_spec] was written by Ethan Frey. 2 | 3 | Many current and former employees of All in Bits (dba Tendermint Inc.), Agoric Systems, the Interchain Foundation, Informal Systems, and Interchain GmbH participated in brainstorming and reviews of the IBC protocol. Thanks are due in particular to Ethan Buchman, Jae Kwon, Ethan Frey, Juwoon Yun, Anca Zamfir, Zarko Milosevic, Zaki Manian, Aditya Sripal, Federico Kunze, Dean Tribble, Mark Miller, Brian Warner, Chris Hibbert, Michael FIG, Sunny Aggarwal, Dev Ojha, Colin Axner, and Jack Zampolin. Thanks also to Meher Roy at Chorus One. Thanks to Zaki Manian, Sam Hart, and Adi Seredinschi for reviewing this paper. 4 | 5 | This work was supported by the Interchain Foundation. 6 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/appendix-a.md: -------------------------------------------------------------------------------- 1 | ## Connection handshake 2 | 3 | ### Initiating a handshake 4 | 5 | \vspace{3mm} 6 | 7 | ```typescript 8 | function connOpenInit( 9 | identifier: Identifier, 10 | desiredCounterpartyConnectionIdentifier: Identifier, 11 | counterpartyPrefix: CommitmentPrefix, 12 | clientIdentifier: Identifier, 13 | counterpartyClientIdentifier: Identifier) { 14 | abortTransactionUnless(validateConnectionIdentifier(identifier)) 15 | abortTransactionUnless(provableStore.get(connectionPath(identifier)) == null) 16 | state = INIT 17 | connection = ConnectionEnd{state, desiredCounterpartyConnectionIdentifier, counterpartyPrefix, 18 | clientIdentifier, counterpartyClientIdentifier, getCompatibleVersions()} 19 | provableStore.set(connectionPath(identifier), connection) 20 | } 21 | ``` 22 | 23 | ### Responding to a handshake initiation 24 | 25 | \vspace{3mm} 26 | 27 | ```typescript 28 | function connOpenTry( 29 | desiredIdentifier: Identifier, 30 | counterpartyConnectionIdentifier: Identifier, 31 | counterpartyPrefix: CommitmentPrefix, 32 | counterpartyClientIdentifier: Identifier, 33 | clientIdentifier: Identifier, 34 | counterpartyVersions: string[], 35 | proofInit: CommitmentProof, 36 | proofConsensus: CommitmentProof, 37 | proofHeight: uint64, 38 | consensusHeight: uint64) { 39 | abortTransactionUnless(validateConnectionIdentifier(desiredIdentifier)) 40 | abortTransactionUnless(consensusHeight <= getCurrentHeight()) 41 | expectedConsensusState = getConsensusState(consensusHeight) 42 | expected = ConnectionEnd{INIT, desiredIdentifier, getCommitmentPrefix(), counterpartyClientIdentifier, 43 | clientIdentifier, counterpartyVersions} 44 | version = pickVersion(counterpartyVersions) 45 | connection = ConnectionEnd{TRYOPEN, counterpartyConnectionIdentifier, counterpartyPrefix, 46 | clientIdentifier, counterpartyClientIdentifier, version} 47 | abortTransactionUnless( 48 | connection.verifyConnectionState(proofHeight, proofInit, counterpartyConnectionIdentifier, expected)) 49 | abortTransactionUnless(connection.verifyClientConsensusState( 50 | proofHeight, proofConsensus, counterpartyClientIdentifier, consensusHeight, expectedConsensusState)) 51 | previous = provableStore.get(connectionPath(desiredIdentifier)) 52 | abortTransactionUnless( 53 | (previous === null) || 54 | (previous.state === INIT && 55 | previous.counterpartyConnectionIdentifier === counterpartyConnectionIdentifier && 56 | previous.counterpartyPrefix === counterpartyPrefix && 57 | previous.clientIdentifier === clientIdentifier && 58 | previous.counterpartyClientIdentifier === counterpartyClientIdentifier && 59 | previous.version === version)) 60 | identifier = desiredIdentifier 61 | provableStore.set(connectionPath(identifier), connection) 62 | } 63 | ``` 64 | 65 | ### Acknowledging the response 66 | 67 | \vspace{3mm} 68 | 69 | ```typescript 70 | function connOpenAck( 71 | identifier: Identifier, 72 | version: string, 73 | proofTry: CommitmentProof, 74 | proofConsensus: CommitmentProof, 75 | proofHeight: uint64, 76 | consensusHeight: uint64) { 77 | abortTransactionUnless(consensusHeight <= getCurrentHeight()) 78 | connection = provableStore.get(connectionPath(identifier)) 79 | abortTransactionUnless(connection.state === INIT || connection.state === TRYOPEN) 80 | expectedConsensusState = getConsensusState(consensusHeight) 81 | expected = ConnectionEnd{TRYOPEN, identifier, getCommitmentPrefix(), 82 | connection.counterpartyClientIdentifier, connection.clientIdentifier, 83 | version} 84 | abortTransactionUnless(connection.verifyConnectionState(proofHeight, proofTry, 85 | connection.counterpartyConnectionIdentifier, expected)) 86 | abortTransactionUnless(connection.verifyClientConsensusState( 87 | proofHeight, proofConsensus, connection.counterpartyClientIdentifier, 88 | consensusHeight, expectedConsensusState)) 89 | connection.state = OPEN 90 | abortTransactionUnless(getCompatibleVersions().indexOf(version) !== -1) 91 | connection.version = version 92 | provableStore.set(connectionPath(identifier), connection) 93 | } 94 | ``` 95 | 96 | ### Finalising the connection 97 | 98 | \vspace{3mm} 99 | 100 | ```typescript 101 | function connOpenConfirm( 102 | identifier: Identifier, 103 | proofAck: CommitmentProof, 104 | proofHeight: uint64) { 105 | connection = provableStore.get(connectionPath(identifier)) 106 | abortTransactionUnless(connection.state === TRYOPEN) 107 | expected = ConnectionEnd{OPEN, identifier, getCommitmentPrefix(), 108 | connection.counterpartyClientIdentifier, 109 | connection.clientIdentifier, connection.version} 110 | abortTransactionUnless(connection.verifyConnectionState( 111 | proofHeight, proofAck, connection.counterpartyConnectionIdentifier, expected)) 112 | connection.state = OPEN 113 | provableStore.set(connectionPath(identifier), connection) 114 | } 115 | ``` 116 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/appendix-b.md: -------------------------------------------------------------------------------- 1 | ## Channel handshake 2 | 3 | ### Initiating a handshake 4 | 5 | \vspace{3mm} 6 | 7 | ```typescript 8 | function chanOpenInit( 9 | order: ChannelOrder, 10 | connectionHops: [Identifier], 11 | portIdentifier: Identifier, 12 | channelIdentifier: Identifier, 13 | counterpartyPortIdentifier: Identifier, 14 | counterpartyChannelIdentifier: Identifier, 15 | version: string): CapabilityKey { 16 | abortTransactionUnless(validateChannelIdentifier(portIdentifier, channelIdentifier)) 17 | abortTransactionUnless(connectionHops.length === 1) 18 | abortTransactionUnless(provableStore.get(channelPath(portIdentifier, channelIdentifier)) === null) 19 | connection = provableStore.get(connectionPath(connectionHops[0])) 20 | abortTransactionUnless(connection !== null) 21 | abortTransactionUnless(authenticateCapability(portPath(portIdentifier), portCapability)) 22 | channel = ChannelEnd{INIT, order, counterpartyPortIdentifier, 23 | counterpartyChannelIdentifier, connectionHops, version} 24 | provableStore.set(channelPath(portIdentifier, channelIdentifier), channel) 25 | channelCapability = newCapability(channelCapabilityPath(portIdentifier, channelIdentifier)) 26 | provableStore.set(nextSequenceSendPath(portIdentifier, channelIdentifier), 1) 27 | provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), 1) 28 | provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), 1) 29 | return channelCapability 30 | } 31 | ``` 32 | 33 | ### Responding to a handshake initiation 34 | 35 | \vspace{3mm} 36 | 37 | ```typescript 38 | function chanOpenTry( 39 | order: ChannelOrder, 40 | connectionHops: [Identifier], 41 | portIdentifier: Identifier, 42 | channelIdentifier: Identifier, 43 | counterpartyPortIdentifier: Identifier, 44 | counterpartyChannelIdentifier: Identifier, 45 | version: string, 46 | counterpartyVersion: string, 47 | proofInit: CommitmentProof, 48 | proofHeight: uint64): CapabilityKey { 49 | abortTransactionUnless(validateChannelIdentifier(portIdentifier, channelIdentifier)) 50 | abortTransactionUnless(connectionHops.length === 1) 51 | previous = provableStore.get(channelPath(portIdentifier, channelIdentifier)) 52 | abortTransactionUnless( 53 | (previous === null) || 54 | (previous.state === INIT && 55 | previous.order === order && 56 | previous.counterpartyPortIdentifier === counterpartyPortIdentifier && 57 | previous.counterpartyChannelIdentifier === counterpartyChannelIdentifier && 58 | previous.connectionHops === connectionHops && 59 | previous.version === version) 60 | ) 61 | abortTransactionUnless(authenticateCapability(portPath(portIdentifier), portCapability)) 62 | connection = provableStore.get(connectionPath(connectionHops[0])) 63 | abortTransactionUnless(connection !== null) 64 | abortTransactionUnless(connection.state === OPEN) 65 | expected = ChannelEnd{INIT, order, portIdentifier, 66 | channelIdentifier, 67 | [connection.counterpartyConnectionIdentifier], 68 | counterpartyVersion} 69 | abortTransactionUnless(connection.verifyChannelState( 70 | proofHeight, 71 | proofInit, 72 | counterpartyPortIdentifier, 73 | counterpartyChannelIdentifier, 74 | expected 75 | )) 76 | channel = ChannelEnd{TRYOPEN, order, counterpartyPortIdentifier, 77 | counterpartyChannelIdentifier, connectionHops, version} 78 | provableStore.set(channelPath(portIdentifier, channelIdentifier), channel) 79 | channelCapability = newCapability(channelCapabilityPath(portIdentifier, channelIdentifier)) 80 | provableStore.set(nextSequenceSendPath(portIdentifier, channelIdentifier), 1) 81 | provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), 1) 82 | provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), 1) 83 | return channelCapability 84 | } 85 | ``` 86 | 87 | ### Acknowledging the response 88 | 89 | \vspace{3mm} 90 | 91 | ```typescript 92 | function chanOpenAck( 93 | portIdentifier: Identifier, 94 | channelIdentifier: Identifier, 95 | counterpartyVersion: string, 96 | proofTry: CommitmentProof, 97 | proofHeight: uint64) { 98 | channel = provableStore.get(channelPath(portIdentifier, channelIdentifier)) 99 | abortTransactionUnless(channel.state === INIT || channel.state === TRYOPEN) 100 | abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability)) 101 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 102 | abortTransactionUnless(connection !== null) 103 | abortTransactionUnless(connection.state === OPEN) 104 | expected = ChannelEnd{TRYOPEN, channel.order, portIdentifier, 105 | channelIdentifier, 106 | [connection.counterpartyConnectionIdentifier], 107 | counterpartyVersion} 108 | abortTransactionUnless(connection.verifyChannelState( 109 | proofHeight, 110 | proofTry, 111 | channel.counterpartyPortIdentifier, 112 | channel.counterpartyChannelIdentifier, 113 | expected 114 | )) 115 | channel.state = OPEN 116 | channel.version = counterpartyVersion 117 | provableStore.set(channelPath(portIdentifier, channelIdentifier), channel) 118 | } 119 | ``` 120 | 121 | ### Finalising a channel 122 | 123 | \vspace{3mm} 124 | 125 | ```typescript 126 | function chanOpenConfirm( 127 | portIdentifier: Identifier, 128 | channelIdentifier: Identifier, 129 | proofAck: CommitmentProof, 130 | proofHeight: uint64) { 131 | channel = provableStore.get(channelPath(portIdentifier, channelIdentifier)) 132 | abortTransactionUnless(channel !== null) 133 | abortTransactionUnless(channel.state === TRYOPEN) 134 | abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability)) 135 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 136 | abortTransactionUnless(connection !== null) 137 | abortTransactionUnless(connection.state === OPEN) 138 | expected = ChannelEnd{OPEN, channel.order, portIdentifier, 139 | channelIdentifier, 140 | [connection.counterpartyConnectionIdentifier], 141 | channel.version} 142 | abortTransactionUnless(connection.verifyChannelState( 143 | proofHeight, 144 | proofAck, 145 | channel.counterpartyPortIdentifier, 146 | channel.counterpartyChannelIdentifier, 147 | expected 148 | )) 149 | channel.state = OPEN 150 | provableStore.set(channelPath(portIdentifier, channelIdentifier), channel) 151 | } 152 | ``` 153 | 154 | ### Initiating channel closure 155 | 156 | \vspace{3mm} 157 | 158 | ```typescript 159 | function chanCloseInit( 160 | portIdentifier: Identifier, 161 | channelIdentifier: Identifier) { 162 | abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability)) 163 | channel = provableStore.get(channelPath(portIdentifier, channelIdentifier)) 164 | abortTransactionUnless(channel !== null) 165 | abortTransactionUnless(channel.state !== CLOSED) 166 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 167 | abortTransactionUnless(connection !== null) 168 | abortTransactionUnless(connection.state === OPEN) 169 | channel.state = CLOSED 170 | provableStore.set(channelPath(portIdentifier, channelIdentifier), channel) 171 | } 172 | ``` 173 | 174 | ### Confirming channel closure 175 | 176 | \vspace{3mm} 177 | 178 | ```typescript 179 | function chanCloseConfirm( 180 | portIdentifier: Identifier, 181 | channelIdentifier: Identifier, 182 | proofInit: CommitmentProof, 183 | proofHeight: uint64) { 184 | abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability)) 185 | channel = provableStore.get(channelPath(portIdentifier, channelIdentifier)) 186 | abortTransactionUnless(channel !== null) 187 | abortTransactionUnless(channel.state !== CLOSED) 188 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 189 | abortTransactionUnless(connection !== null) 190 | abortTransactionUnless(connection.state === OPEN) 191 | expected = ChannelEnd{CLOSED, channel.order, portIdentifier, 192 | channelIdentifier, 193 | [connection.counterpartyConnectionIdentifier], 194 | channel.version} 195 | abortTransactionUnless(connection.verifyChannelState( 196 | proofHeight, 197 | proofInit, 198 | channel.counterpartyPortIdentifier, 199 | channel.counterpartyChannelIdentifier, 200 | expected 201 | )) 202 | channel.state = CLOSED 203 | provableStore.set(channelPath(portIdentifier, channelIdentifier), channel) 204 | } 205 | ``` 206 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/appendix-c.md: -------------------------------------------------------------------------------- 1 | ## Packet Handling 2 | 3 | ### Sending a packet 4 | 5 | \vspace{3mm} 6 | 7 | ```typescript 8 | function sendPacket(packet: Packet) { 9 | channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel)) 10 | abortTransactionUnless(channel !== null) 11 | abortTransactionUnless(channel.state !== CLOSED) 12 | abortTransactionUnless(authenticateCapability( 13 | channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability)) 14 | abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier) 15 | abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier) 16 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 17 | abortTransactionUnless(connection !== null) 18 | latestClientHeight = provableStore.get(clientPath(connection.clientIdentifier)).latestClientHeight() 19 | abortTransactionUnless(packet.timeoutHeight === 0 || latestClientHeight < packet.timeoutHeight) 20 | nextSequenceSend = provableStore.get(nextSequenceSendPath(packet.sourcePort, packet.sourceChannel)) 21 | abortTransactionUnless(packet.sequence === nextSequenceSend) 22 | nextSequenceSend = nextSequenceSend + 1 23 | provableStore.set(nextSequenceSendPath(packet.sourcePort, packet.sourceChannel), nextSequenceSend) 24 | provableStore.set(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence), 25 | hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)) 26 | } 27 | ``` 28 | 29 | ### Receiving a packet 30 | 31 | \vspace{3mm} 32 | 33 | ```typescript 34 | function recvPacket( 35 | packet: OpaquePacket, 36 | proof: CommitmentProof, 37 | proofHeight: uint64, 38 | acknowledgement: bytes): Packet { 39 | channel = provableStore.get(channelPath(packet.destPort, packet.destChannel)) 40 | abortTransactionUnless(channel !== null) 41 | abortTransactionUnless(channel.state === OPEN) 42 | abortTransactionUnless( 43 | authenticateCapability(channelCapabilityPath(packet.destPort, packet.destChannel), capability)) 44 | abortTransactionUnless(packet.sourcePort === channel.counterpartyPortIdentifier) 45 | abortTransactionUnless(packet.sourceChannel === channel.counterpartyChannelIdentifier) 46 | abortTransactionUnless(provableStore.get(packetAcknowledgementPath(packet.destPort, 47 | packet.destChannel, packet.sequence) === null)) 48 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 49 | abortTransactionUnless(connection !== null) 50 | abortTransactionUnless(connection.state === OPEN) 51 | abortTransactionUnless(packet.timeoutHeight === 0 || getConsensusHeight() < packet.timeoutHeight) 52 | abortTransactionUnless(packet.timeoutTimestamp === 0 || currentTimestamp() < packet.timeoutTimestamp) 53 | abortTransactionUnless(connection.verifyPacketData( 54 | proofHeight, 55 | proof, 56 | packet.sourcePort, 57 | packet.sourceChannel, 58 | packet.sequence, 59 | concat(packet.data, packet.timeoutHeight, packet.timeoutTimestamp) 60 | )) 61 | if (acknowledgement.length > 0 || channel.order === UNORDERED) 62 | provableStore.set( 63 | packetAcknowledgementPath(packet.destPort, packet.destChannel, packet.sequence), 64 | hash(acknowledgement) 65 | ) 66 | if (channel.order === ORDERED) { 67 | nextSequenceRecv = provableStore.get(nextSequenceRecvPath(packet.destPort, packet.destChannel)) 68 | abortTransactionUnless(packet.sequence === nextSequenceRecv) 69 | nextSequenceRecv = nextSequenceRecv + 1 70 | provableStore.set(nextSequenceRecvPath(packet.destPort, packet.destChannel), nextSequenceRecv) 71 | } 72 | return packet 73 | } 74 | ``` 75 | 76 | ### Acknowledging a packet 77 | 78 | \vspace{3mm} 79 | 80 | ```typescript 81 | function acknowledgePacket( 82 | packet: OpaquePacket, 83 | acknowledgement: bytes, 84 | proof: CommitmentProof, 85 | proofHeight: uint64): Packet { 86 | channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel)) 87 | abortTransactionUnless(channel !== null) 88 | abortTransactionUnless(channel.state === OPEN) 89 | abortTransactionUnless(authenticateCapability( 90 | channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability)) 91 | abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier) 92 | abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier) 93 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 94 | abortTransactionUnless(connection !== null) 95 | abortTransactionUnless(connection.state === OPEN) 96 | abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, 97 | packet.sourceChannel, packet.sequence)) 98 | === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)) 99 | abortTransactionUnless(connection.verifyPacketAcknowledgement( 100 | proofHeight, 101 | proof, 102 | packet.destPort, 103 | packet.destChannel, 104 | packet.sequence, 105 | acknowledgement 106 | )) 107 | if (channel.order === ORDERED) { 108 | nextSequenceAck = provableStore.get(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel)) 109 | abortTransactionUnless(packet.sequence === nextSequenceAck) 110 | nextSequenceAck = nextSequenceAck + 1 111 | provableStore.set(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel), nextSequenceAck) 112 | } 113 | provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence)) 114 | return packet 115 | } 116 | ``` 117 | 118 | ### Handling a timed-out packet 119 | 120 | \vspace{3mm} 121 | 122 | ```typescript 123 | function timeoutPacket( 124 | packet: OpaquePacket, 125 | proof: CommitmentProof, 126 | proofHeight: uint64, 127 | nextSequenceRecv: Maybe): Packet { 128 | channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel)) 129 | abortTransactionUnless(channel !== null) 130 | abortTransactionUnless(channel.state === OPEN) 131 | abortTransactionUnless(authenticateCapability( 132 | channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability)) 133 | abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier) 134 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 135 | abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier) 136 | abortTransactionUnless( 137 | (packet.timeoutHeight > 0 && proofHeight >= packet.timeoutHeight) || 138 | (packet.timeoutTimestamp > 0 && 139 | connection.getTimestampAtHeight(proofHeight) > packet.timeoutTimestamp)) 140 | abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, 141 | packet.sourceChannel, packet.sequence)) 142 | === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)) 143 | if channel.order === ORDERED { 144 | abortTransactionUnless(nextSequenceRecv <= packet.sequence) 145 | abortTransactionUnless(connection.verifyNextSequenceRecv( 146 | proofHeight, 147 | proof, 148 | packet.destPort, 149 | packet.destChannel, 150 | nextSequenceRecv 151 | )) 152 | } else 153 | abortTransactionUnless(connection.verifyPacketAcknowledgementAbsence( 154 | proofHeight, 155 | proof, 156 | packet.destPort, 157 | packet.destChannel, 158 | packet.sequence 159 | )) 160 | provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence)) 161 | if channel.order === ORDERED { 162 | channel.state = CLOSED 163 | provableStore.set(channelPath(packet.sourcePort, packet.sourceChannel), channel) 164 | } 165 | return packet 166 | } 167 | ``` 168 | 169 | ### Cleaning up packet data 170 | 171 | \vspace{3mm} 172 | 173 | ```typescript 174 | function cleanupPacket( 175 | packet: OpaquePacket, 176 | proof: CommitmentProof, 177 | proofHeight: uint64, 178 | nextSequenceRecvOrAcknowledgement: Either): Packet { 179 | channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel)) 180 | abortTransactionUnless(channel !== null) 181 | abortTransactionUnless(channel.state === OPEN) 182 | abortTransactionUnless(authenticateCapability( 183 | channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability)) 184 | abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier) 185 | connection = provableStore.get(connectionPath(channel.connectionHops[0])) 186 | abortTransactionUnless(connection !== null) 187 | abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier) 188 | abortTransactionUnless(nextSequenceRecv > packet.sequence) 189 | abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, 190 | packet.sourceChannel, packet.sequence)) 191 | === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)) 192 | if channel.order === ORDERED 193 | abortTransactionUnless(connection.verifyNextSequenceRecv( 194 | proofHeight, 195 | proof, 196 | packet.destPort, 197 | packet.destChannel, 198 | nextSequenceRecvOrAcknowledgement 199 | )) 200 | else 201 | abortTransactionUnless(connection.verifyPacketAcknowledgement( 202 | proofHeight, 203 | proof, 204 | packet.destPort, 205 | packet.destChannel, 206 | packet.sequence, 207 | nextSequenceRecvOrAcknowledgement 208 | )) 209 | provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence)) 210 | return packet 211 | } 212 | ``` 213 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/bibliography.bib: -------------------------------------------------------------------------------- 1 | @misc{cosmos_whitepaper, 2 | title = {Cosmos: A Network of Distributed Ledgers}, 3 | timestamp = {2016-09-21T00:00:00Z}, 4 | urldate = {2020-05-25T00:00:00Z}, 5 | howpublished = {\url{https://cosmos.network/cosmos-whitepaper.pdf}}, 6 | author = {{Jae Kwon, Ethan Buchman}}, 7 | month = sep, 8 | year = {2016} 9 | } 10 | 11 | @misc{tendermint_consensus_without_mining, 12 | title = {Tendermint: Consensus without Mining}, 13 | timestamp = {}, 14 | urldate = {2020-05-25T00:00:00Z}, 15 | howpublished = {\url{https://tendermint.com/static/docs/tendermint.pdf}}, 16 | author = {{Jae Kwon}}, 17 | month = sep, 18 | year = {2014} 19 | } 20 | 21 | @misc{tendermint_latest_gossip, 22 | title = {The latest gossip on BFT consensus}, 23 | timestamp = {2019-10-22T00:00:00Z}, 24 | urldate = {2020-05-25T00:00:00Z}, 25 | howpublished = {\url{https://arxiv.org/pdf/1807.04938}}, 26 | author = {{Ethan Buchman, Jae Kwon, Zarko Milosevic}}, 27 | month = nov, 28 | year = {2019} 29 | } 30 | 31 | @misc{ethan_frey_ibc_spec, 32 | title = {IBC Protocol Specification v0.3.1}, 33 | timestamp = {2017-10-30T00:00:00Z}, 34 | urldate = {2020-05-25T00:00:00Z}, 35 | howpublished = {\url{https://github.com/cosmos/ics/blob/master/archive/v0_3_1_IBC.pdf}}, 36 | author = {{Ethan Frey}}, 37 | month = nov, 38 | year = {2017} 39 | } 40 | 41 | @misc{hard_problems_sharding_part_one, 42 | title = {The Authoritative Guide to Blockchain Sharding: Part 1}, 43 | timestamp = {2018-12-05T00:00:00Z}, 44 | urldate = {2020-05-25T00:00:00Z}, 45 | howpublished = {\url{https://medium.com/nearprotocol/the-authoritative-guide-to-blockchain-sharding-part-1-1b53ed31e060}}, 46 | author = {{Near Protocol}}, 47 | month = {dec}, 48 | year = {2018} 49 | } 50 | 51 | @misc{hard_problems_sharding_part_two, 52 | title = {The Authoritative Guide to Blockchain Sharding: Part 2}, 53 | timestamp = {2018-12-12T00:00:00Z}, 54 | urldate = {2020-05-25T00:00:00Z}, 55 | howpublished = {\url{https://medium.com/nearprotocol/unsolved-problems-in-blockchain-sharding-2327d6517f43}}, 56 | author = {{Near Protocol}}, 57 | month = {dec}, 58 | year = {2018} 59 | } 60 | 61 | @misc{ibc_cosmos_sdk, 62 | title = {The Cosmos SDK: x/ibc}, 63 | timestamp = {2020-05-25T00:00:00Z}, 64 | urldate = {2020-05-25T00:00:00Z}, 65 | howpublished = {\url{https://github.com/cosmos/cosmos-sdk/tree/master/x/ibc}}, 66 | author = {{Cosmos SDK Contributors}}, 67 | month = {may}, 68 | year = {2020} 69 | } 70 | 71 | @misc{ibc_rust, 72 | title = {Rust implementation of IBC modules and relayer}, 73 | timestamp = {2020-05-25T00:00:00Z}, 74 | urldate = {2020-05-25T00:00:00Z}, 75 | howpublished = {\url{https://github.com/informalsystems/ibc-rs}}, 76 | author = {{Informal Systems}}, 77 | month = {may}, 78 | year = {2020} 79 | } 80 | 81 | @misc{relayer_go, 82 | title = {Server-side IBC relayer}, 83 | timestamp = {2020-05-25T00:00:00Z}, 84 | urldate = {2020-05-25T00:00:00Z}, 85 | howpublished = {\url{https://github.com/iqlusioninc/relayer}}, 86 | author = {{Iqlusion}}, 87 | month = {may}, 88 | year = {2020} 89 | } 90 | 91 | @misc{game_of_zones, 92 | title = {Game of Zones}, 93 | timestamp = {2020-05-25T00:00:00Z}, 94 | urldate = {2020-05-25T00:00:00Z}, 95 | howpublished = {\url{https://goz.cosmosnetwork.dev/}}, 96 | author = {{GoZ Contributors}}, 97 | month = {may}, 98 | year = {2020} 99 | } 100 | 101 | @misc{map_of_zones, 102 | title = {Map of Zones}, 103 | timestamp = {2020-05-25T00:00:00Z}, 104 | urldate = {2020-05-25T00:00:00Z}, 105 | howpublished = {\url{https://mapofzones.com/}}, 106 | author = {{Bitquasar & Ztake}}, 107 | month = {may}, 108 | year = {2020} 109 | } 110 | 111 | @misc{grandpa_consensus, 112 | title = {GRANDPA Finality Gadget}, 113 | timestamp = {2020-05-02T00:00:00Z}, 114 | urldate = {2020-05-25T00:00:00Z}, 115 | howpublished = {\url{https://github.com/w3f/consensus/blob/master/pdf/grandpa.pdf}}, 116 | author = {{Alistair Stewart}}, 117 | month = {may}, 118 | year = {2020} 119 | } 120 | 121 | @misc{polkadot_xcmp, 122 | title = {Web3 Foundation Research: XCMP}, 123 | timestamp = {2020-05-01T00:00:00Z}, 124 | urldate = {2020-05-25T00:00:00Z}, 125 | howpublished = {\url{https://research.web3.foundation/en/latest/polkadot/XCMP.html}}, 126 | author = {{Alistair Stewart and Fatemeh Shirazi and Leon Groot Bruinderink}}, 127 | month = {may}, 128 | year = {2020} 129 | } 130 | 131 | @misc{hotstuff_consensus, 132 | urldate = {2020-05-25T00:00:00Z}, 133 | howpublished = {\url{https://arxiv.org/pdf/1803.05069}}, 134 | author = {Maofan Yin and Dahlia Malkhi and Michael K. Reiter and Guy Golan Gueta and Ittai Abraham}, 135 | title = {HotStuff: BFT Consensus in the Lens of Blockchain}, 136 | year = {2018}, 137 | eprint = {arXiv:1803.05069}, 138 | } 139 | 140 | @misc{iavl_plus_tree, 141 | urldate = {2020-05-25T00:00:00Z}, 142 | howpublished = {\url{https://github.com/tendermint/iavl}}, 143 | author = {Tendermint}, 144 | title = {IAVL+ Tree: A versioned, snapshottable (immutable) AVL+ tree for persistent data.}, 145 | year = {2020} 146 | } 147 | 148 | @misc{patricia_tree, 149 | urldate = {2020-05-25T00:00:00Z}, 150 | author = {Ethereum}, 151 | howpublished = {\url{https://github.com/ethereum/wiki/wiki/Patricia-Tree}}, 152 | title = {Ethereum Modified Merkle Patricia Trie Specification}, 153 | year = {2020} 154 | } 155 | 156 | @misc{object_capabilities, 157 | author = {Chip Morningstar}, 158 | howpublished = {\url{http://habitatchronicles.com/2017/05/what-are-capabilities/}}, 159 | title = {What Are Capabilities?}, 160 | year = {2017}, 161 | urldate = {2020-05-25T00:00:00Z} 162 | } 163 | 164 | @misc{coda_protocol, 165 | author = {Izaak Meckler and Evan Shapiro}, 166 | howpublished = {\url{https://cdn.codaprotocol.com/v2/static/coda-whitepaper-05-10-2018-0.pdf}}, 167 | title = {Coda: Decentralized cryptocurrency at scale}, 168 | year = {2018}, 169 | urldate = {2020-05-25T00:00:00Z} 170 | } 171 | 172 | @misc{substrate, 173 | author = {Parity Technologies}, 174 | howpublished = {\url{https://github.com/paritytech/substrate}}, 175 | title = {Substrate: The platform for blockchain innovators}, 176 | year = {2020}, 177 | urldate = {2020-05-25T00:00:00Z} 178 | } 179 | 180 | @misc{bitcoin, 181 | added-at = {2014-04-17T08:33:06.000+0200}, 182 | author = {Nakamoto, Satoshi}, 183 | biburl = {https://www.bibsonomy.org/bibtex/23db66df0fc9fa2b5033f096a901f1c36/ngnn}, 184 | interhash = {423c2cdff70ba0cd0bca55ebb164d770}, 185 | intrahash = {3db66df0fc9fa2b5033f096a901f1c36}, 186 | keywords = {imported}, 187 | timestamp = {2014-04-17T08:33:06.000+0200}, 188 | title = {Bitcoin: A peer-to-peer electronic cash system}, 189 | url = {http://www.bitcoin.org/bitcoin.pdf}, 190 | year = 2009 191 | } 192 | 193 | @misc{rfc793, 194 | series = {Request for Comments}, 195 | number = 793, 196 | howpublished = {RFC 793}, 197 | publisher = {RFC Editor}, 198 | doi = {10.17487/RFC0793}, 199 | url = {https://rfc-editor.org/rfc/rfc793.txt}, 200 | author = {}, 201 | title = {{Transmission Control Protocol}}, 202 | pagetotal = 91, 203 | year = 1981, 204 | month = sep, 205 | abstract = {}, 206 | } 207 | 208 | @misc{ethereum_2_cross_shard, 209 | title = {Ethereum Sharding Research Compendium: Cross-shard communication}, 210 | year = 2020, 211 | month = march, 212 | author = {Ethereum 2.0 Contributors}, 213 | howpublished = {\url{https://notes.ethereum.org/@serenity/H1PGqDhpm?type=view#Cross-shard-communication}} 214 | } 215 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/clients.md: -------------------------------------------------------------------------------- 1 | The *client* abstraction encapsulates the properties that consensus algorithms of ledgers implementing the interblockchain 2 | communication protocol are required to satisfy. These properties are necessary for efficient and safe 3 | state verification in the higher-level protocol abstractions. The algorithm utilised in IBC to verify the 4 | consensus transcript and state sub-components of another ledger is referred to as a "validity predicate", 5 | and pairing it with a state that the verifier assumes to be correct forms a "light client" (colloquially shortened to "client"). 6 | 7 | \vspace{3mm} 8 | 9 | ### Motivation 10 | 11 | \vspace{3mm} 12 | 13 | In the IBC protocol, an actor, which may be an end user, an off-ledger process, or ledger, 14 | needs to be able to verify updates to the state of another ledger 15 | which the other ledger's consensus algorithm has agreed upon, and reject any possible updates 16 | which the other ledger's consensus algorithm has not agreed upon. A light client is the algorithm 17 | with which an actor can do so. The client abstraction formalises this model's interface and requirements, 18 | so that the IBC protocol can easily integrate with new ledgers which are running new consensus algorithms 19 | as long as associated light client algorithms fulfilling the listed requirements are provided. 20 | 21 | Beyond the properties described in this specification, IBC does not impose any requirements on 22 | the internal operation of ledgers and their consensus algorithms. A ledger may consist of a 23 | single process signing operations with a private key, a quorum of processes signing in unison, 24 | many processes operating a Byzantine fault-tolerant consensus algorithm (a replicated, or distributed, ledger), or other configurations yet to be invented 25 | — from the perspective of IBC, a ledger is defined entirely by its light client validation and equivocation detection logic. 26 | Clients will generally not include validation of the state transition logic in general 27 | (as that would be equivalent to simply executing the other state machine), but may 28 | elect to validate parts of state transitions in particular cases, and can validate 29 | the entire state transition if doing so is asymptotically efficient, perhaps through compression using a SNARK [@coda_protocol]. 30 | 31 | Externally, however, the light client verification functions used by IBC clients 32 | must have *finality*, such that verified blocks (subject to the usual consensus safety assumptions), 33 | once verified, cannot be reverted. The safety of higher abstraction layers of the IBC protocol 34 | and guarantees provided to the applications using the protocol depend on this property of finality. 35 | 36 | In order to graft finality onto Nakamoto consensus algorithms, such as used in Bitcoin [@bitcoin], 37 | clients can act as thresholding views of internal, non-finalising clients. In the case where 38 | modules utilising the IBC protocol to interact with probabilistic-finality consensus algorithms 39 | which might require different finality thresholds for different applications, one write-only 40 | client could be created to track headers and many read-only clients with different finality 41 | thresholds (confirmation depths after which state roots are considered final) could use that same state. 42 | Of course, this will introduce different security assumptions than those required of full nodes running the consensus algorithm, 43 | and trade-offs which must be balanced by the user on the basis of their application-specific security needs. 44 | 45 | The client protocol is designed to support third-party introduction. Consider the general example: 46 | Alice, a module on a ledger, wants to introduce Bob, a second module on a second ledger who Alice knows (and who knows Alice), 47 | to Carol, a third module on a third ledger, who Alice knows but Bob does not. Alice must utilise 48 | an existing channel to Bob to communicate the canonically-serialisable validity predicate for 49 | Carol, with which Bob can then open a connection and channel so that Bob and Carol can talk directly. 50 | If necessary, Alice may also communicate to Carol the validity predicate for Bob, prior to Bob's 51 | connection attempt, so that Carol knows to accept the incoming request. 52 | 53 | Client interfaces are constructed so that custom validation logic can be provided safely 54 | to define a custom client at runtime, as long as the underlying ledger can provide an 55 | appropriate gas metering mechanism to charge for compute and storage. On a host ledger 56 | which supports WASM execution, for example, the validity predicate and equivocation predicate 57 | could be provided as executable WASM functions when the client instance is created. 58 | 59 | \vspace{3mm} 60 | 61 | ### Definitions 62 | 63 | \vspace{3mm} 64 | 65 | A *validity predicate* is an opaque function defined by a client type to verify headers depending on the current consensus state. Using the validity predicate should be far more computationally efficient than replaying the full consensus algorithm and state machine for the given parent header and the list of network messages. 66 | 67 | A *consensus state* is an opaque type representing the state of a validity predicate. 68 | The light client validity predicate algorithm in combination with a particular consensus state must be able to verify state updates agreed upon by the associated consensus algorithm. 69 | The consensus state must also be serialisable in a canonical fashion so that third parties, such as counterparty ledgers, 70 | can check that a particular ledger has stored a particular state. It must also be 71 | introspectable by the ledger which it is for, such that the ledger can look up its 72 | own consensus state at a past height and compare it to a stored consensus state in another ledger's client. 73 | 74 | A *commitment root* is an inexpensive way for downstream logic to verify whether key/value 75 | pairs are present or absent in a state at a particular height. Often this will be instantiated as the root of a Merkle tree. 76 | 77 | A *header* is an opaque data structure defined by a client type which provides information to update a consensus state. 78 | Headers can be submitted to an associated client to update the stored consensus state. They likely contain a height, a proof, 79 | a new commitment root, and possibly updates to the validity predicate. 80 | 81 | A *misbehaviour predicate* is an opaque function defined by a client type, used to check if data constitutes a violation of the consensus protocol. This might be two signed headers with different state roots but the same height, a signed header containing invalid state transitions, or other evidence of malfeasance as defined by the consensus algorithm. 82 | 83 | \vspace{3mm} 84 | 85 | ### Desired properties 86 | 87 | \vspace{3mm} 88 | 89 | Light clients must provide a secure algorithm to verify other ledgers' canonical headers, 90 | using the existing consensus state. The higher level abstractions will then be able to verify 91 | sub-components of the state with the commitment roots stored in the consensus state, which are 92 | guaranteed to have been committed by the other ledger's consensus algorithm. 93 | 94 | Validity predicates are expected to reflect the behaviour of the full nodes which are running the 95 | corresponding consensus algorithm. Given a consensus state and a list of messages, if a full node 96 | accepts a new header, then the light client must also accept it, and if a full node rejects it, 97 | then the light client must also reject it. 98 | 99 | Light clients are not replaying the whole message transcript, so it is possible under cases of 100 | consensus misbehaviour that the light clients' behaviour differs from the full nodes'. 101 | In this case, a misbehaviour proof which proves the divergence between the validity predicate 102 | and the full node can be generated and submitted to the ledger so that the ledger can safely deactivate the 103 | light client, invalidate past state roots, and await higher-level intervention. 104 | 105 | The validity of the validity predicate is dependent on the security model of the 106 | consensus algorithm. For example, the consensus algorithm could be BFT proof-of-authority 107 | with a trusted operator set, or BFT proof-of-stake with a tokenholder set, each of which 108 | have a defined threshold above which Byzantine behaviour may result in divergence. 109 | 110 | Clients may have time-sensitive validity predicates, such that if no header is provided for a period of time 111 | (e.g. an unbonding period of three weeks in a proof-of-stake system) it will no longer be possible to update the client. 112 | 113 | \vspace{3mm} 114 | 115 | ### State verification 116 | 117 | \vspace{3mm} 118 | 119 | Client types must define functions to authenticate internal state of the ledger which the client tracks. 120 | Internal implementation details may differ (for example, a loopback client could simply read directly from the state and require no proofs). 121 | Externally-facing clients will likely verify signature or vector commitment proofs. 122 | 123 | \vspace{3mm} 124 | 125 | ### Example client instantiations 126 | 127 | \vspace{3mm} 128 | 129 | #### Loopback 130 | 131 | A loopback client of a local ledger merely reads from the local state, to which it must have access. This is analogous to `localhost` or `127.0.0.1` in TCP/IP. 132 | 133 | \vspace{3mm} 134 | 135 | #### Simple signatures 136 | 137 | A client of a solo machine running a non-replicated ledger with a known public key checks signatures on messages sent by that local machine. 138 | Multi-signature or threshold signature schemes can also be used in such a fashion. 139 | 140 | \vspace{3mm} 141 | 142 | #### Proxy clients 143 | 144 | Proxy clients verify another (proxy) ledger's verification of the target ledger, by including in the 145 | proof first a proof of the client state on the proxy ledger, and then a secondary proof of the sub-state of 146 | the target ledger with respect to the client state on the proxy ledger. This allows the proxy client to 147 | avoid storing and tracking the consensus state of the target ledger itself, at the cost of adding 148 | security assumptions of proxy ledger correctness. 149 | 150 | \vspace{3mm} 151 | 152 | #### BFT consensus and verifiable state 153 | 154 | For the immediate application of interoperability between sovereign, fault-tolerant distributed ledgers, the most common and most useful client type will be light clients for instances of BFT consensus algorithms such as Tendermint [@tendermint_consensus_without_mining], GRANDPA [@grandpa_consensus], or HotStuff [@hotstuff_consensus], with ledgers utilising Merklized state trees such as an IAVL+ tree [@iavl_plus_tree] or a Merkle Patricia tree [@patricia_tree]. The client algorithm for such instances will utilise the BFT consensus algorithm's light client validity predicate and treat at minimum consensus equivocation (double-signing) as misbehaviour, along with other possible misbehaviour types specific to the proof-of-authority or proof-of-stake system involved. 155 | 156 | \vspace{3mm} 157 | 158 | ### Client lifecycle 159 | 160 | \vspace{3mm} 161 | 162 | #### Creation 163 | 164 | Clients can be created permissionlessly by anyone at any time by specifying an identifier, 165 | client type, and initial consensus state. 166 | 167 | \vspace{3mm} 168 | 169 | #### Update 170 | 171 | Updating a client is done by submitting a new header. When a new header is verified 172 | with the stored client state's validity predicate and consensus state, the client will 173 | update its internal state accordingly, possibly finalising commitment roots and 174 | updating the signature authority logic in the stored consensus state. 175 | 176 | If a client can no longer be updated (if, for example, the unbonding period has passed), 177 | it will no longer be possible to send any packets over connections and channels associated 178 | with that client, or timeout any packets in-flight (since the height and timestamp on the 179 | destination ledger can no longer be verified). Manual intervention must take place to 180 | reset the client state or migrate the connections and channels to another client. This 181 | cannot safely be done automatically, but ledgers implementing IBC could elect 182 | to allow governance mechanisms to perform these actions 183 | (perhaps even per-client/connection/channel with a controlling multi-signature or contract). 184 | 185 | \vspace{3mm} 186 | 187 | #### Misbehaviour 188 | 189 | If the client detects evidence of misbehaviour, the client can be take appropriate action, possibly invalidating 190 | previously valid commitment roots and preventing future updates. What precisely constitutes misbehaviour will 191 | depend on the consensus algorithm which the validity predicate is validating the output of. 192 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/connections.md: -------------------------------------------------------------------------------- 1 | The *connection* abstraction encapsulates two stateful objects (*connection ends*) on two separate ledgers, each associated with a light client of the other ledger, which together facilitate cross-ledger sub-state verification and packet relay (through channels). Connections are safely established in an unknown, dynamic topology using a handshake subprotocol. 2 | 3 | \vspace{3mm} 4 | 5 | ### Motivation 6 | 7 | \vspace{3mm} 8 | 9 | The IBC protocol provides *authorisation* and *ordering* semantics for packets: guarantees, respectively, that packets have been committed on the sending ledger (and according state transitions executed, such as escrowing tokens), and that they have been committed exactly once in a particular order and can be delivered exactly once in that same order. The *connection* abstraction in conjunction with the *client* abstraction defines the *authorisation* semantics of IBC. Ordering semantics are provided by channels. 10 | 11 | \vspace{3mm} 12 | 13 | ### Definitions 14 | 15 | \vspace{3mm} 16 | 17 | A *connection end* is state tracked for an end of a connection on one ledger, defined as follows: 18 | 19 | ```typescript 20 | enum ConnectionState { 21 | INIT, 22 | TRYOPEN, 23 | OPEN, 24 | } 25 | ``` 26 | 27 | ```typescript 28 | interface ConnectionEnd { 29 | state: ConnectionState 30 | counterpartyConnectionIdentifier: Identifier 31 | counterpartyPrefix: CommitmentPrefix 32 | clientIdentifier: Identifier 33 | counterpartyClientIdentifier: Identifier 34 | version: string 35 | } 36 | ``` 37 | 38 | - The `state` field describes the current state of the connection end. 39 | - The `counterpartyConnectionIdentifier` field identifies the connection end on the counterparty ledger associated with this connection. 40 | - The `counterpartyPrefix` field contains the prefix used for state verification on the counterparty ledger associated with this connection. 41 | - The `clientIdentifier` field identifies the client associated with this connection. 42 | - The `counterpartyClientIdentifier` field identifies the client on the counterparty ledger associated with this connection. 43 | - The `version` field is an opaque string which can be utilised to determine encodings or protocols for channels or packets utilising this connection. 44 | 45 | \vspace{3mm} 46 | 47 | ### Opening handshake 48 | 49 | \vspace{3mm} 50 | 51 | The opening handshake subprotocol allows each ledger to verify the identifier used to reference the connection on the other ledger, enabling modules on each ledger to reason about the reference on the other ledger. 52 | 53 | The opening handshake consists of four datagrams: `ConnOpenInit`, `ConnOpenTry`, `ConnOpenAck`, and `ConnOpenConfirm`. 54 | 55 | A correct protocol execution, between two ledgers `A` and `B`, with connection states formatted as `(A, B)`, flows as follows: 56 | 57 | | Datagram | Prior state | Posterior state | 58 | | ----------------- | ----------------- | ----------------- | 59 | | `ConnOpenInit` | `(-, -)` | `(INIT, -)` | 60 | | `ConnOpenTry` | `(INIT, none)` | `(INIT, TRYOPEN)` | 61 | | `ConnOpenAck` | `(INIT, TRYOPEN)` | `(OPEN, TRYOPEN)` | 62 | | `ConnOpenConfirm` | `(OPEN, TRYOPEN)` | `(OPEN, OPEN)` | 63 | 64 | At the end of an opening handshake between two ledgers implementing the subprotocol, the following properties hold: 65 | 66 | - Each ledger has each other's correct consensus state as originally specified by the initiating actor. 67 | - Each ledger has knowledge of and has agreed to its identifier on the other ledger. 68 | - Each ledger knows that the other ledger has agreed to the same data. 69 | 70 | Connection handshakes can safely be performed permissionlessly, modulo anti-spam measures (paying gas). 71 | 72 | `ConnOpenInit`, executed on ledger A, initialises a connection attempt on ledger A, specifying a pair of identifiers 73 | for the connection on both ledgers and a pair of identifiers for existing light clients (one for 74 | each ledger). ledger A stores a connection end object in its state. 75 | 76 | `ConnOpenTry`, executed on ledger B, relays notice of a connection attempt on ledger A to ledger B, 77 | providing the pair of connection identifiers, the pair of client identifiers, and a desired version. 78 | Ledger B verifies that these identifiers are valid, checks that the version is compatible, verifies 79 | a proof that ledger A has stored these identifiers, and verifies a proof that the light client ledger A 80 | is using to validate ledger B has the correct consensus state for ledger B. ledger B stores a connection 81 | end object in its state. 82 | 83 | `ConnOpenAck`, executed on ledger A, relays acceptance of a connection open attempt from ledger B back to ledger A, 84 | providing the identifier which can now be used to look up the connection end object. ledger A verifies 85 | that the version requested is compatible, verifies a proof that ledger B has stored the same identifiers 86 | ledger A has stored, and verifies a proof that the light client ledger B is using to validate ledger A has the 87 | correct consensus state for ledger A. 88 | 89 | `ConnOpenConfirm`, executed on ledger B, confirms opening of a connection on ledger A to ledger B. 90 | Ledger B simply checks that ledger A has executed `ConnOpenAck` and marked the connection as `OPEN`. 91 | Ledger B subsequently marks its end of the connection as `OPEN`. After execution of `ConnOpenConfirm` 92 | the connection is open on both ends and can be used immediately. 93 | 94 | \vspace{3mm} 95 | 96 | ### Versioning 97 | 98 | \vspace{3mm} 99 | 100 | During the handshake process, two ends of a connection come to agreement on a version bytestring associated 101 | with that connection. At the moment, the contents of this version bytestring are opaque to the IBC core protocol. 102 | In the future, it might be used to indicate what kinds of channels can utilise the connection in question, or 103 | what encoding formats channel-related datagrams will use. Host ledgers may utilise the version data 104 | to negotiate encodings, priorities, or connection-specific metadata related to custom logic on top of IBC. 105 | Host ledgers may also safely ignore the version data or specify an empty string. 106 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/fungible-token-transfer.md: -------------------------------------------------------------------------------- 1 | The section specifies packet data structure and state machine handling logic for the transfer of fungible tokens over an IBC channel between two modules on separate ledgers. The state machine logic presented allows for safe multi-ledger denomination handling with permissionless channel opening. This logic constitutes a "fungible token transfer bridge module", interfacing between the IBC routing module and an existing asset tracking module on the host ledger. 2 | 3 | \vspace{3mm} 4 | 5 | ### Motivation 6 | 7 | \vspace{3mm} 8 | 9 | Users of a set of ledgers connected over the IBC protocol might wish to utilise an asset issued on one ledger on another ledger, perhaps to make use of additional features such as exchange or privacy protection, while retaining fungibility with the original asset on the issuing ledger. This application-layer protocol allows for transferring fungible tokens between ledgers connected with IBC in a way which preserves asset fungibility, preserves asset ownership, limits the impact of Byzantine faults, and requires no additional permissioning. 10 | 11 | \vspace{3mm} 12 | 13 | ### Properties 14 | 15 | \vspace{3mm} 16 | 17 | - Preservation of fungibility (two-way peg) 18 | - Preservation of total supply (constant or inflationary on a single source ledger and module) 19 | - Permissionless token transfers, no need to whitelist connections, modules, or denominations 20 | - Symmetric (all ledgers implement the same logic) 21 | - Fault containment: prevents Byzantine-inflation of tokens originating on ledger A, as a result of ledger B's Byzantine behaviour (though any users who sent tokens to ledger B may be at risk) 22 | 23 | \vspace{3mm} 24 | 25 | ### Packet definition 26 | 27 | \vspace{3mm} 28 | 29 | Only one packet data type, `FungibleTokenPacketData`, which specifies the denomination, amount, sending account, receiving account, and whether the sending ledger is the source of the asset, is required: 30 | 31 | ```typescript 32 | interface FungibleTokenPacketData { 33 | denomination: string 34 | amount: uint256 35 | sender: string 36 | receiver: string 37 | } 38 | ``` 39 | 40 | The acknowledgement data type describes whether the transfer succeeded or failed, and the reason for failure (if any): 41 | 42 | ```typescript 43 | interface FungibleTokenPacketAcknowledgement { 44 | success: boolean 45 | error: Maybe 46 | } 47 | ``` 48 | 49 | \vspace{3mm} 50 | 51 | ### Packet handling semantics 52 | 53 | \vspace{3mm} 54 | 55 | The protocol logic is symmetric, so that denominations originating on either ledger can be converted to vouchers on the other, and then redeemed back again later. 56 | 57 | - When acting as the source ledger, the bridge module escrows an existing local asset denomination on the sending ledger and mints vouchers on the receiving ledger. 58 | - When acting as the sink ledger, the bridge module burns local vouchers on the sending ledgers and unescrows the local asset denomination on the receiving ledger. 59 | - When a packet times-out, local assets are unescrowed back to the sender or vouchers minted back to the sender appropriately. 60 | - Acknowledgement data is used to handle failures, such as invalid denominations or invalid destination accounts. Returning 61 | an acknowledgement of failure is preferable to aborting the transaction since it more easily enables the sending ledger 62 | to take appropriate action based on the nature of the failure. 63 | 64 | This implementation preserves both fungibility and supply. If tokens have been sent to the counterparty ledger, they can be redeemed back in the same denomination and amount on the source ledger. 65 | The combined supply of unlocked tokens of a particular on both ledgers is constant, since each send-receive packet pair locks and mints the same amount (although the source ledger of a particular 66 | asset could change the supply outside of the scope of this protocol). 67 | 68 | \vspace{3mm} 69 | 70 | ### Fault containment 71 | 72 | \vspace{3mm} 73 | 74 | Ledgers could fail to follow the fungible transfer token protocol outlined here in one of two ways: the full nodes running the consensus algorithm could diverge from the light client, or the ledger's state machine could incorrectly implement the escrow & voucher logic (whether inadvertently or intentionally). Consensus divergence should eventually result in evidence of misbehaviour which can be used to freeze the client, but may not immediately do so (and no guarantee can be made that such evidence would be submitted before more packets), so from the perspective of the protocol's goal of isolating faults these cases must be handled in the same way. No guarantees can be made about asset recovery — users electing to transfer tokens to a ledger take on the risk of that ledger failing — but containment logic can easily be implemented on the interface boundary by tracking incoming and outgoing supply of each asset, and ensuring that no ledger is allowed to redeem vouchers for more tokens than it had initially escrowed. In essence, particular channels can be treated as accounts, where a module on the other end of a channel cannot spend more than it has received. Since isolated Byzantine sub-graphs of a multi-ledger fungible token transfer system will be unable to transfer out any more tokens than they had initially received, this prevents any supply inflation of source assets, and ensures that users only take on the consensus risk of ledgers they intentionally connect to. 75 | 76 | \vspace{3mm} 77 | 78 | ### Multi-ledger transfer paths 79 | 80 | \vspace{3mm} 81 | 82 | This protocol does not directly handle the "diamond problem", where a user sends a token originating on ledger A to ledger B, then to ledger D, and wants to return it through the path `D -> C -> A` — since the supply is tracked as owned by ledger B (and the voucher denomination will be `"{portD}/{channelD}/{portB}/{channelB}/denom"`), ledger C cannot serve as the intermediary. This is necessary due to the fault containment desiderata outlined above. Complexities arising from long redemption paths may lead to the emergence of central ledgers in the network topology or automated markets to exchange assets with different redemption paths. 83 | 84 | In order to track all of the denominations moving around the network of ledgers in various paths, it may be helpful for a particular ledger to implement a registry which will track the "global" source ledger for each denomination. End-user service providers (such as wallet authors) may want to integrate such a registry or keep their own mapping of canonical source ledgers and human-readable names in order to improve UX. 85 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/host-requirements.md: -------------------------------------------------------------------------------- 1 | ### Module system 2 | 3 | \vspace{3mm} 4 | 5 | The host ledger must support a module system, whereby self-contained, potentially mutually distrusted packages of code can safely execute on the same ledger, control how and when they allow other modules to communicate with them, and be identified and manipulated by a controller module or execution environment. 6 | 7 | \vspace{3mm} 8 | 9 | ### Key/value Store 10 | 11 | \vspace{3mm} 12 | 13 | The host ledger must provide a key/value store interface allowing values to be read, written, and deleted. 14 | 15 | These functions must be permissioned to the IBC handler module so that only the IBC handler module can write or delete a certain subset of paths. 16 | This will likely be implemented as a sub-store (prefixed key-space) of a larger key/value store used by the entire ledger. 17 | 18 | Host ledgers must provide an instance of this interface which is provable, such that the light client algorithm for the host ledger 19 | can verify presence or absence of particular key-value pairs which have been written to it. 20 | 21 | This interface does not necessitate any particular storage backend or backend data layout. ledgers may elect to use a storage backend configured in accordance with their needs, as long as the store on top fulfils the specified interface and provides commitment proofs. 22 | 23 | \vspace{3mm} 24 | 25 | ### Consensus state introspection 26 | 27 | \vspace{3mm} 28 | 29 | Host ledgers must provide the ability to introspect their current height, current 30 | consensus state (as utilised by the host ledger's light client algorithm), and a bounded 31 | number of recent consensus states (e.g. past headers). These are used to prevent man-in-the-middle 32 | attacks during handshakes to set up connections with other ledgers — each ledger checks that the other 33 | ledger is in fact authenticating data using its consensus state. 34 | 35 | \vspace{3mm} 36 | 37 | ### Timestamp access 38 | 39 | \vspace{3mm} 40 | 41 | In order to support timestamp-based timeouts, host ledgers must provide a current Unix-style timestamp. 42 | Timeouts in subsequent headers must be non-decreasing. 43 | 44 | \vspace{3mm} 45 | 46 | ### Port system 47 | 48 | \vspace{3mm} 49 | 50 | Host ledgers must implement a port system, where the IBC handler can allow different modules in the host ledger to bind to uniquely named ports. Ports are identified by an identifier, and must be permissioned so that: 51 | 52 | - Once a module has bound to a port, no other modules can use that port until the module releases it 53 | - A single module can bind to multiple ports 54 | - Ports are allocated first-come first-serve 55 | - "Reserved" ports for known modules can be bound when the ledger is first started 56 | 57 | This permissioning can be implemented with unique references (object capabilities [@object_capabilities]) for each port, with source-based authentication(a la `msg.sender` in Ethereum contracts), or with some other method of access control, in any case enforced by the host ledger. 58 | 59 | Ports are not generally intended to be human-readable identifiers — just as DNS name resolution and standardised port numbers for particular applications exist to abstract away the details of IP addresses and ports from TCP/IP users, ledger name resolution and standardised ports for particular applications may be created in order to abstract away the details of ledger identification and port selection. Such an addressing system could easily be built on top of IBC itself, such that an initial connection to the addressing system over IBC would then enable name resolution for subsequent connections to other ledgers and applications. 60 | 61 | \vspace{3mm} 62 | 63 | ### Exception/rollback system 64 | 65 | \vspace{3mm} 66 | 67 | Host ledgers must support an exception or rollback system, whereby a transaction can abort execution and revert any previously made state changes (including state changes in other modules happening within the same transaction), excluding gas consumed and fee payments as appropriate. 68 | 69 | \vspace{3mm} 70 | 71 | ### Data availability 72 | 73 | \vspace{3mm} 74 | 75 | For deliver-or-timeout safety, host ledgers must have eventual data availability, such that any key/value pairs in state can be eventually retrieved by relayers. For exactly-once safety, data availability is not required. 76 | 77 | For liveness of packet relay, host ledgers must have bounded transactional liveness, such that incoming transactions are confirmed within a block height or timestamp bound (in particular, less than the timeouts assigned to the packets). 78 | 79 | IBC packet data, and other data which is not directly stored in the Merklized state but is relied upon by relayers, must be available to and efficiently computable by relayer processes. 80 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/introduction.md: -------------------------------------------------------------------------------- 1 | By virtue of their nature as replicated state machines across which deterministic execution and thus continued agreement on an exact deterministic ruleset must be maintained, individual distributed ledgers are limited in their throughput & flexibility, must trade off application-specific optimisations for general-purpose capabilities, and can only offer a single security model to applications built on top of them. In order to support the transaction throughput, application diversity, cost efficiency, and fault tolerance required to facilitate wide deployment of distributed ledger applications, execution and storage must be split across many independent ledgers which can run concurrently, upgrade independently, and each specialise in different ways, in a manner such that the ability of different applications to communicate with one another, essential for permissionless innovation and complex multi-part contracts, is maintained. 2 | 3 | One multi-ledger design direction is to shard a single logical ledger across separate consensus instances, referred to as "shards", which execute concurrently and store disjoint partitions of the state. In order to reason globally about safety and liveness, and in order to correctly route data and code between shards, these designs must take a "top-down approach" — constructing a particular network topology, usually a single root ledger and a star or tree of shards, and engineering protocol rules and incentives to enforce that topology. Message passing can then be implemented on top of such a sharded topology by systems such as Polkadot's XCMP [@polkadot_xcmp] and Ethereum 2.0's cross-shard communication [@ethereum_2_cross_shard]. This approach possesses advantages in simplicity and predictability, but faces hard technical problems in assuring the validity of state transitions [@hard_problems_sharding_part_two], requires the adherence of all shards to a single validator set (or randomly elected subset thereof) and a single virtual machine, and faces challenges in upgrading itself over time due to the necessity of reaching global consensus on alterations to the network topology or ledger ruleset. Additionally, such sharded systems are brittle: if the fault tolerance threshold is exceeded, the system needs to coordinate a global halt & restart, and possibly initiate complex state transition rollback procedures — it is not possible to safely isolate Byzantine portions of the network graph and continue operation. 4 | 5 | The *interblockchain communication protocol* (IBC) provides a mechanism by which separate, sovereign replicated ledgers can safely, voluntarily interact while sharing only a minimum requisite common interface. The protocol design approaches a differently formulated version of the scaling and interoperability problem: enabling safe, reliable interoperation of a network of heterogeneous distributed ledgers, arranged in an unknown topology, preserving data secrecy where possible, where the ledgers can diversify, develop, and rearrange independently of each other or of a particular imposed topology or ledger design. In a wide, dynamic network of interoperating ledgers, sporadic Byzantine faults are expected, so the protocol must also detect, mitigate, and contain the potential damage of Byzantine faults in accordance with the requirements of the applications and ledgers involved without requiring the use of additional trusted parties or global coordination. 6 | 7 | To facilitate this heterogeneous interoperation, the interblockchain communication protocol utilises a bottom-up approach, specifying the set of requirements, functions, and properties necessary to implement interoperation between two ledgers, and then specifying different ways in which multiple interoperating ledgers might be composed which preserve the requirements of higher-level protocols. IBC thus presumes nothing about and requires nothing of the overall network topology, and of the implementing ledgers requires only that a known, minimal set of functions with specified properties are available. Ledgers within IBC are defined as their light client consensus validation functions, thus expanding the range of what a "ledger" can be to include single machines and complex consensus algorithms alike. IBC implementations are expected to be co-resident with higher-level modules and protocols on the host ledger. Ledgers hosting IBC must provide a certain set of functions for consensus transcript verification and cryptographic commitment proof generation, and IBC packet relayers (off-ledger processes) are expected to have access to network protocols and physical data-links as required to read the state of one ledger and submit data to another. 8 | 9 | The data payloads in IBC packets are opaque to the protocol itself — modules on each ledger determine the semantics of the packets which are sent between them. For cross-ledger token transfer, packets could contain fungible token information, where assets are locked on one ledger to mint corresponding vouchers on another. For cross-ledger governance, packets could contain vote information, where accounts on one ledger could vote in the governance system of another. For cross-ledger account delegation, packets could contain transaction authorisation information, allowing an account on one ledger to be controlled by an account on another. For a cross-ledger decentralised exchange, packets could contain order intent information or trade settlement information, such that assets on different ledgers could be exchanged without leaving their host ledgers by transitory escrow and a sequence of packets. 10 | 11 | This bottom-up approach is quite similar to, and directly inspired by, the TCP/IP specification [@rfc793] for interoperability between hosts in packet-switched computer networks. Just as TCP/IP defines the protocol by which two hosts communicate, and higher-level protocols knit many bidirectional host-to-host links into complex topologies, IBC defines the protocol by which two ledgers communicate, and higher-level protocols knit many bidirectional ledger-to-ledger links into gestalt multi-ledger applications. Just as TCP/IP packets contain opaque payload data with semantics interpreted by the processes on each host, IBC packets contain opaque payload data with semantics interpreted by the modules on each ledger. Just as TCP/IP provides reliable, ordered data transmission between processes, allowing a process on one host to reason about the state of a process on another, IBC provides reliable, ordered data transmission between modules, allowing a module on one ledger to reason about the state of a module on another. 12 | 13 | This paper is intended as an overview of the abstractions defined by the IBC protocol and the mechanisms by which they are composed. We first outline the structure of the protocol, including scope, interfaces, and operational requirements. Subsequently, we detail the abstractions defined by the protocol, including modules, ports, clients, connections, channels, packets, and relayers, and describe the subprotocols for opening and closing handshakes, packet relay, edge-case handling, and relayer operations. After explaining the internal structure of the protocol, we define the interface by which applications can utilise IBC, and sketch an example application-level protocol for fungible token transfer. Finally, we recount testing and deployment efforts of the protocol thus far. Appendices include pseudocode for the connection handshake, channel handshake, and packet relay algorithms. 14 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/metadata.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'The Interblockchain Communication Protocol: An Overview' 3 | author: 4 | - name: Christopher Goes 5 | affiliation: Interchain GmbH 6 | location: Berlin, Germany 7 | email: cwgoes@interchain.berlin 8 | keywords: 9 | - ibc 10 | - interblockchain 11 | - dlt 12 | numbersections: yes 13 | lang: en 14 | babel-lang: english 15 | abstract: | 16 | The interblockchain communication protocol (IBC) is an end-to-end, connection-oriented, stateful protocol for reliable, ordered, and authenticated communication between modules on separate distributed ledgers. 17 | IBC is designed for interoperation between heterogeneous ledgers arranged in an unknown, dynamic topology, operating with varied consensus algorithms and state machines. The protocol realises this by specifying 18 | the sufficient set of data structures, abstractions, and semantics of a communication protocol which once implemented by participating ledgers will allow them to safely communicate. IBC is payload-agnostic 19 | and provides a cross-ledger asynchronous communication primitive which can be used as a constituent building block by a wide variety of applications. 20 | 21 | ... 22 | 23 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/paper.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | !include src/introduction.md 4 | 5 | # Protocol scope & properties 6 | 7 | !include src/structure.md 8 | 9 | # Host ledger requirements 10 | 11 | !include src/host-requirements.md 12 | 13 | # Protocol structure 14 | 15 | ## Clients 16 | 17 | !include src/clients.md 18 | 19 | ## Connections 20 | 21 | !include src/connections.md 22 | 23 | ## Channels 24 | 25 | !include src/channels.md 26 | 27 | ## Relayers 28 | 29 | !include src/relayers.md 30 | 31 | # Usage patterns 32 | 33 | !include src/usage-patterns.md 34 | 35 | # Example application-level module 36 | 37 | !include src/fungible-token-transfer.md 38 | 39 | # Testing & deployment 40 | 41 | !include src/testing-and-deployment.md 42 | 43 | # Acknowledgements 44 | 45 | !include src/acknowledgements.md 46 | 47 | \onecolumn 48 | 49 | # Appendices 50 | 51 | !include src/appendix-a.md 52 | 53 | !include src/appendix-b.md 54 | 55 | !include src/appendix-c.md 56 | 57 | \pagebreak 58 | 59 | \twocolumn 60 | 61 | # References 62 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/relayers.md: -------------------------------------------------------------------------------- 1 | Relayer algorithms are the "physical" connection layer of IBC — off-ledger processes responsible for relaying data between two ledgers running the IBC protocol by scanning the state of each ledger, constructing appropriate datagrams, and executing them on the opposite ledger as allowed by the protocol. 2 | 3 | \vspace{3mm} 4 | 5 | ### Motivation 6 | 7 | \vspace{3mm} 8 | 9 | In the IBC protocol, one ledger can only record the intention to send particular data to another ledger — it does not have direct access to a network transport layer. Physical datagram relay must be performed by off-ledger infrastructure with access to a transport layer such as TCP/IP. This standard defines the concept of a *relayer* algorithm, executable by an off-ledger process with the ability to query ledger state, to perform this relay. 10 | 11 | A *relayer* is an off-ledger process with the ability to read the state of and submit transactions to some set of ledgers utilising the IBC protocol. 12 | 13 | \vspace{3mm} 14 | 15 | ### Properties 16 | 17 | \vspace{3mm} 18 | 19 | - No exactly-once or deliver-or-timeout safety properties of IBC depend on relayer behaviour (Byzantine relayers are assumed) 20 | - Packet relay liveness properties of IBC depend only on the existence of at least one correct, live relayer 21 | - Relaying can safely be permissionless, all requisite verification is performed by the ledger itself 22 | - Requisite communication between the IBC user and the relayer is minimised 23 | - Provision for relayer incentivisation are not included in the core protocol, but are possible at the application layer 24 | 25 | \vspace{3mm} 26 | 27 | ### Basic relayer algorithm 28 | 29 | \vspace{3mm} 30 | 31 | The relayer algorithm is defined over a set of ledgers implementing the IBC protocol. Each relayer may not necessarily have access to read state from and write datagrams to all ledgers in the multi-ledger network (especially in the case of permissioned or private ledgers) — different relayers may relay between different subsets. 32 | 33 | Every so often, although no more frequently than once per block on either ledger, a relayer calculates the set of all valid datagrams to be relayed from one ledger to another based on the state of both ledgers. The relayer must possess prior knowledge of what subset of the IBC protocol is implemented by the ledgers in the set for which they are relaying (e.g. by reading the source code). Datagrams can be submitted individually as single transactions or atomically as a single transaction if the ledger supports it. 34 | 35 | Different relayers may relay between different ledgers — as long as each pair of ledgers has at least one correct and live relayer and the ledgers remain live, all packets flowing between ledgers in the network will eventually be relayed. 36 | 37 | \vspace{3mm} 38 | 39 | ### Packets, acknowledgements, timeouts 40 | 41 | \vspace{3mm} 42 | 43 | #### Relaying packets in an ordered channel 44 | 45 | Packets in an ordered channel can be relayed in either an event-based fashion or a query-based fashion. 46 | For the former, the relayer should watch the source ledger for events emitted whenever packets are sent, 47 | then compose the packet using the data in the event log. For the latter, the relayer should periodically 48 | query the send sequence on the source ledger, and keep the last sequence number relayed, so that any sequences 49 | in between the two are packets that need to be queried and then relayed. In either case, subsequently, the relayer process 50 | should check that the destination ledger has not yet received the packet by checking the receive sequence, and then relay it. 51 | 52 | \vspace{3mm} 53 | 54 | #### Relaying packets in an unordered channel 55 | 56 | Packets in an unordered channel can most easily be relayed in an event-based fashion. 57 | The relayer should watch the source ledger for events emitted whenever packets 58 | are send, then compose the packet using the data in the event log. Subsequently, 59 | the relayer should check whether the destination ledger has received the packet 60 | already by querying for the presence of an acknowledgement at the packet's sequence 61 | number, and if one is not yet present the relayer should relay the packet. 62 | 63 | \vspace{3mm} 64 | 65 | #### Relaying acknowledgements 66 | 67 | Acknowledgements can most easily be relayed in an event-based fashion. The relayer should 68 | watch the destination ledger for events emitted whenever packets are received and acknowledgements 69 | are written, then compose the acknowledgement using the data in the event log, 70 | check whether the packet commitment still exists on the source ledger (it will be 71 | deleted once the acknowledgement is relayed), and if so relay the acknowledgement to 72 | the source ledger. 73 | 74 | \vspace{3mm} 75 | 76 | #### Relaying timeouts 77 | 78 | Timeout relay is slightly more complex since there is no specific event emitted when 79 | a packet times-out — it is simply the case that the packet can no longer be relayed, 80 | since the timeout height or timestamp has passed on the destination ledger. The relayer 81 | process must elect to track a set of packets (which can be constructed by scanning event logs), 82 | and as soon as the height or timestamp of the destination ledger exceeds that of a tracked 83 | packet, check whether the packet commitment still exists on the source ledger (it will 84 | be deleted once the timeout is relayed), and if so relay a timeout to the source ledger. 85 | 86 | \vspace{3mm} 87 | 88 | #### Ordering constraints 89 | 90 | There are implicit ordering constraints imposed on the relayer process determining which datagrams must be submitted in what order. For example, a header must be submitted to finalise the stored consensus state and commitment root for a particular height in a light client before a packet can be relayed. The relayer process is responsible for frequently querying the state of the ledgers between which they are relaying in order to determine what must be relayed when. 91 | 92 | \vspace{3mm} 93 | 94 | #### Bundling 95 | 96 | If the host ledger supports it, the relayer process can bundle many datagrams into a single transaction, which will cause them to be executed in sequence, and amortise any overhead costs (e.g. signature checks for fee payment). 97 | 98 | \vspace{3mm} 99 | 100 | #### Race conditions 101 | 102 | Multiple relayers relaying between the same pair of modules and ledgers may attempt to relay the same packet (or submit the same header) at the same time. If two relayers do so, the first transaction will succeed and the second will fail. Out-of-band coordination between the relayers or between the actors who sent the original packets and the relayers is necessary to mitigate this. 103 | 104 | \vspace{3mm} 105 | 106 | #### Incentivisation 107 | 108 | The relay process must have access to accounts on both ledgers with sufficient balance to pay for transaction fees. Relayers may employ application-level methods to recoup these fees, such by including a small payment to themselves in the packet data. 109 | 110 | Any number of relayer processes may be safely run in parallel (and indeed, it is expected that separate relayers will serve separate subsets of the multi-ledger network). However, they may consume unnecessary fees if they submit the same proof multiple times, so some minimal coordination may be ideal (such as assigning particular relayers to particular packets or scanning mempools for pending transactions). 111 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/structure.md: -------------------------------------------------------------------------------- 1 | ## Scope 2 | 3 | IBC handles authentication, transport, and ordering of opaque data packets relayed between modules on separate ledgers — ledgers can be run on solo machines, replicated by many nodes running a consensus algorithm, or constructed by any process whose state can be verified. The protocol is defined between modules on two ledgers, but designed for safe simultaneous use between any number of modules on any number of ledgers connected in arbitrary topologies. 4 | 5 | ## Interfaces 6 | 7 | IBC sits between modules — smart contracts, other ledger components, or otherwise independently executed pieces of application logic on ledgers — on one side, and underlying consensus protocols, blockchains, and network infrastructure (e.g. TCP/IP), on the other side. 8 | 9 | IBC provides to modules a set of functions much like the functions which might be provided to a module for interacting with another module on the same ledger: sending data packets and receiving data packets on an established connection and channel, in addition to calls to manage the protocol state: opening and closing connections and channels, choosing connection, channel, and packet delivery options, and inspecting connection and channel status. 10 | 11 | IBC requires certain functionalities and properties of the underlying ledgers, primarily finality (or thresholding finality gadgets), cheaply-verifiable consensus transcripts (such that a light client algorithm can verify the results of the consensus process with much less computation & storage than a full node), and simple key/value store functionality. On the network side, IBC requires only eventual data delivery — no authentication, synchrony, or ordering properties are assumed. 12 | 13 | ## Operation 14 | 15 | The primary purpose of IBC is to provide reliable, authenticated, ordered communication between modules running on independent host ledgers. This requires protocol logic in the areas of data relay, data confidentiality and legibility, reliability, flow control, authentication, statefulness, and multiplexing. 16 | 17 | \vspace{3mm} 18 | 19 | ### Data relay 20 | 21 | \vspace{3mm} 22 | 23 | In the IBC architecture, modules are not directly sending messages to each other over networking infrastructure, but rather are creating messages to be sent which are then physically relayed from one ledger to another by monitoring "relayer processes". IBC assumes the existence of a set of relayer processes with access to an underlying network protocol stack (likely TCP/IP, UDP/IP, or QUIC/IP) and physical interconnect infrastructure. These relayer processes monitor a set of ledgers implementing the IBC protocol, continuously scanning the state of each ledger and requesting transaction execution on another ledger when outgoing packets have been committed. For correct operation and progress in a connection between two ledgers, IBC requires only that at least one correct and live relayer process exists which can relay between the ledgers. 24 | 25 | \vspace{3mm} 26 | 27 | ### Data confidentiality and legibility 28 | 29 | \vspace{3mm} 30 | 31 | The IBC protocol requires only that the minimum data necessary for correct operation of the IBC protocol be made available and legible (serialised in a standardised format) to relayer processes, and the ledger may elect to make that data available only to specific relayers. This data consists of consensus state, client, connection, channel, and packet information, and any auxiliary state structure necessary to construct proofs of inclusion or exclusion of particular key/value pairs in state. All data which must be proved to another ledger must also be legible; i.e., it must be serialised in a standardised format agreed upon by the two ledgers. 32 | 33 | \vspace{3mm} 34 | 35 | ### Reliability 36 | 37 | \vspace{3mm} 38 | 39 | The network layer and relayer processes may behave in arbitrary ways, dropping, reordering, or duplicating packets, purposely attempting to send invalid transactions, or otherwise acting in a Byzantine fashion, without compromising the safety or liveness of IBC. This is achieved by assigning a sequence number to each packet sent over an IBC channel, which is checked by the IBC handler (the part of the ledger implementing the IBC protocol) on the receiving ledger, and providing a method for the sending ledger to check that the receiving ledger has in fact received and handled a packet before sending more packets or taking further action. Cryptographic commitments are used to prevent datagram forgery: the sending ledger commits to outgoing packets, and the receiving ledger checks these commitments, so datagrams altered in transit by a relayer will be rejected. IBC also supports unordered channels, which do not enforce ordering of packet receives relative to sends but still enforce exactly-once delivery. 40 | 41 | \vspace{3mm} 42 | 43 | ### Flow control 44 | 45 | \vspace{3mm} 46 | 47 | IBC does not provide specific protocol-level provisions for compute-level or economic-level flow control. The underlying ledgers are expected to have compute throughput limiting devices and flow control mechanisms of their own such as gas markets. Application-level economic flow control — limiting the rate of particular packets according to their content — may be useful to ensure security properties and contain damage from Byzantine faults. For example, an application transferring value over an IBC channel might want to limit the rate of value transfer per block to limit damage from potential Byzantine behaviour. IBC provides facilities for modules to reject packets and leaves particulars up to the higher-level application protocols. 48 | 49 | \vspace{3mm} 50 | 51 | ### Authentication 52 | 53 | \vspace{3mm} 54 | 55 | All data sent over IBC are authenticated: a block finalised by the consensus algorithm of the sending ledger must commit to the outgoing packet via a cryptographic commitment, and the receiving ledger's IBC handler must verify both the consensus transcript and the cryptographic commitment proof that the datagram was sent before acting upon it. 56 | 57 | \vspace{3mm} 58 | 59 | ### Statefulness 60 | 61 | \vspace{3mm} 62 | 63 | Reliability, flow control, and authentication as described above require that IBC initialises and maintains certain status information for each datastream. This information is split between three abstractions: clients, connections, and channels. Each client object contains information about the consensus state of the counterparty ledger. Each connection object contains a specific pair of named identifiers agreed to by both ledgers in a handshake protocol, which uniquely identifies a connection between the two ledgers. Each channel, specific to a pair of modules, contains information concerning negotiated encoding and multiplexing options and state and sequence numbers. When two modules wish to communicate, they must locate an existing connection and channel between their two ledgers, or initialise a new connection and channel(s) if none yet exist. Initialising connections and channels requires a multi-step handshake which, once complete, ensures that only the two intended ledgers are connected, in the case of connections, and ensures that two modules are connected and that future datagrams relayed will be authenticated, encoded, and sequenced as desired, in the case of channels. 64 | 65 | \vspace{3mm} 66 | 67 | ### Multiplexing 68 | 69 | \vspace{3mm} 70 | 71 | To allow for many modules within a single host ledger to use an IBC connection simultaneously, IBC allows any number of channels to be associated with a single connection. Each channel uniquely identifies a datastream over which packets can be sent in order (in the case of an ordered channel), and always exactly once, to a destination module on the receiving ledger. Channels are usually expected to be associated with a single module on each ledger, but one-to-many and many-to-one channels are also possible. The number of channels per connection is unbounded, facilitating concurrent throughput limited only by the throughput of the underlying ledgers with only a single connection and pair of clients necessary to track consensus information (and consensus transcript verification cost thus amortised across all channels using the connection). 72 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/template.latex: -------------------------------------------------------------------------------- 1 | \documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$babel-lang$,$endif$$if(papersize)$$papersize$paper,$endif$$for(classoption)$$classoption$$sep$,$endfor$,conference]{IEEEtran} 2 | $if(beamerarticle)$ 3 | \usepackage{beamerarticle} % needs to be loaded first 4 | $endif$ 5 | 6 | \usepackage{titlesec} 7 | \titleformat*{\subsection}{\sc} 8 | \titlespacing*{\paragraph}{0pt}{-0.5ex}{-3ex} 9 | 10 | \usepackage{graphicx} 11 | \usepackage{subcaption} 12 | \usepackage{listings} 13 | \lstdefinelanguage{JavaScript}{ 14 | basicstyle=\ttfamily\small, 15 | morekeywords=[1]{break, continue, delete, else, for, function, if, in, 16 | new, return, this, typeof, var, void, while, with}, 17 | % Literals, primitive types, and reference types. 18 | morekeywords=[2]{false, null, true, boolean, number, undefined, 19 | Array, Boolean, Date, Math, Number, String, Object}, 20 | % Built-ins. 21 | morekeywords=[3]{eval, parseInt, parseFloat, escape, unescape}, 22 | sensitive, 23 | morecomment=[s]{/*}{*/}, 24 | morecomment=[l]//, 25 | morecomment=[s]{/**}{*/}, % JavaDoc style comments 26 | morestring=[b]', 27 | morestring=[b]" 28 | }[keywords, comments, strings] 29 | 30 | 31 | 32 | $if(csl-refs)$ 33 | \newlength{\cslhangindent} 34 | \setlength{\cslhangindent}{1.5em} 35 | \newenvironment{cslreferences}% 36 | {$if(csl-hanging-indent)$\setlength{\parindent}{0pt}% 37 | \everypar{\setlength{\hangindent}{\cslhangindent}}\ignorespaces$endif$}% 38 | {\par} 39 | $endif$ 40 | $if(fontfamily)$ 41 | \usepackage[$for(fontfamilyoptions)$$fontfamilyoptions$$sep$,$endfor$]{$fontfamily$} 42 | $else$ 43 | \usepackage{lmodern} 44 | $endif$ 45 | $if(linestretch)$ 46 | \usepackage{setspace} 47 | \setstretch{$linestretch$} 48 | $endif$ 49 | \usepackage{amssymb,amsmath} 50 | \usepackage{ifxetex,ifluatex} 51 | \usepackage{fixltx2e} % provides \textsubscript 52 | \ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex 53 | \usepackage[$if(fontenc)$$fontenc$$else$T1$endif$]{fontenc} 54 | \usepackage[utf8]{inputenc} 55 | $if(euro)$ 56 | \usepackage{eurosym} 57 | $endif$ 58 | \else % if luatex or xelatex 59 | \ifxetex 60 | \usepackage{mathspec} 61 | \else 62 | \usepackage{fontspec} 63 | \fi 64 | \defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase} 65 | $for(fontfamilies)$ 66 | \newfontfamily{$fontfamilies.name$}[$fontfamilies.options$]{$fontfamilies.font$} 67 | $endfor$ 68 | $if(euro)$ 69 | \newcommand{\euro}{€} 70 | $endif$ 71 | $if(mainfont)$ 72 | \setmainfont[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$]{$mainfont$} 73 | $endif$ 74 | $if(sansfont)$ 75 | \setsansfont[$for(sansfontoptions)$$sansfontoptions$$sep$,$endfor$]{$sansfont$} 76 | $endif$ 77 | $if(monofont)$ 78 | \setmonofont[Mapping=tex-ansi$if(monofontoptions)$,$for(monofontoptions)$$monofontoptions$$sep$,$endfor$$endif$]{$monofont$} 79 | $endif$ 80 | $if(mathfont)$ 81 | \setmathfont(Digits,Latin,Greek)[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} 82 | $endif$ 83 | $if(CJKmainfont)$ 84 | \usepackage{xeCJK} 85 | \setCJKmainfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} 86 | $endif$ 87 | \fi 88 | % use upquote if available, for straight quotes in verbatim environments 89 | \IfFileExists{upquote.sty}{\usepackage{upquote}}{} 90 | % use microtype if available 91 | \IfFileExists{microtype.sty}{% 92 | \usepackage{microtype} 93 | \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts 94 | }{} 95 | $if(geometry)$ 96 | \usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry} 97 | $endif$ 98 | \usepackage[unicode=true]{hyperref} 99 | $if(colorlinks)$ 100 | \PassOptionsToPackage{usenames,dvipsnames}{color} % color is loaded by hyperref 101 | $endif$ 102 | \hypersetup{ 103 | $if(title-meta)$ 104 | pdftitle={$title-meta$}, 105 | $endif$ 106 | $if(author-meta)$ 107 | pdfauthor={$author-meta$}, 108 | $endif$ 109 | $if(keywords)$ 110 | pdfkeywords={$for(keywords)$$keywords$$sep$, $endfor$}, 111 | $endif$ 112 | $if(colorlinks)$ 113 | colorlinks=true, 114 | linkcolor=$if(linkcolor)$$linkcolor$$else$Maroon$endif$, 115 | citecolor=$if(citecolor)$$citecolor$$else$Blue$endif$, 116 | urlcolor=$if(urlcolor)$$urlcolor$$else$Blue$endif$, 117 | $else$ 118 | pdfborder={0 0 0}, 119 | $endif$ 120 | breaklinks=true} 121 | \urlstyle{same} % don't use monospace font for urls 122 | $if(lang)$ 123 | \ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex 124 | \usepackage[shorthands=off,$for(babel-otherlangs)$$babel-otherlangs$,$endfor$main=$babel-lang$]{babel} 125 | $if(babel-newcommands)$ 126 | $babel-newcommands$ 127 | $endif$ 128 | \else 129 | \usepackage{polyglossia} 130 | \setmainlanguage[$polyglossia-lang.options$]{$polyglossia-lang.name$} 131 | $for(polyglossia-otherlangs)$ 132 | \setotherlanguage[$polyglossia-otherlangs.options$]{$polyglossia-otherlangs.name$} 133 | $endfor$ 134 | \fi 135 | $endif$ 136 | $if(natbib)$ 137 | \usepackage{natbib} 138 | \bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} 139 | $endif$ 140 | $if(biblatex)$ 141 | \usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex} 142 | $for(bibliography)$ 143 | \addbibresource{$bibliography$} 144 | $endfor$ 145 | $endif$ 146 | $if(listings)$ 147 | \usepackage{listings} 148 | $endif$ 149 | $if(lhs)$ 150 | \lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} 151 | $endif$ 152 | $if(highlighting-macros)$ 153 | $highlighting-macros$ 154 | $endif$ 155 | $if(verbatim-in-note)$ 156 | \usepackage{fancyvrb} 157 | \VerbatimFootnotes % allows verbatim text in footnotes 158 | $endif$ 159 | $if(tables)$ 160 | \usepackage{longtable,booktabs} 161 | \usepackage{supertabular} 162 | \let\longtable\supertabular 163 | \let\endlongtable\endsupertabular 164 | \let\endhead\relax 165 | % Fix footnotes in tables (requires footnote package) 166 | \IfFileExists{footnote.sty}{\usepackage{footnote}\makesavenoteenv{long table}}{} 167 | $endif$ 168 | $if(graphics)$ 169 | \usepackage{graphicx,grffile} 170 | \makeatletter 171 | \def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} 172 | \def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} 173 | \makeatother 174 | % Scale images if necessary, so that they will not overflow the page 175 | % margins by default, and it is still possible to overwrite the defaults 176 | % using explicit options in \includegraphics[width, height, ...]{} 177 | \setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} 178 | $endif$ 179 | $if(links-as-notes)$ 180 | % Make links footnotes instead of hotlinks: 181 | \renewcommand{\href}[2]{#2\footnote{\url{#1}}} 182 | $endif$ 183 | $if(strikeout)$ 184 | \usepackage[normalem]{ulem} 185 | % avoid problems with \sout in headers with hyperref: 186 | \pdfstringdefDisableCommands{\renewcommand{\sout}{}} 187 | $endif$ 188 | $if(indent)$ 189 | $else$ 190 | \IfFileExists{parskip.sty}{% 191 | \usepackage{parskip} 192 | }{% else 193 | \setlength{\parindent}{0pt} 194 | \setlength{\parskip}{6pt plus 2pt minus 1pt} 195 | } 196 | $endif$ 197 | \setlength{\emergencystretch}{3em} % prevent overfull lines 198 | \providecommand{\tightlist}{% 199 | \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} 200 | $if(numbersections)$ 201 | \setcounter{secnumdepth}{$if(secnumdepth)$$secnumdepth$$else$5$endif$} 202 | $else$ 203 | \setcounter{secnumdepth}{0} 204 | $endif$ 205 | $if(subparagraph)$ 206 | $else$ 207 | % Redefines (sub)paragraphs to behave more like sections 208 | \ifx\paragraph\undefined\else 209 | \let\oldparagraph\paragraph 210 | \renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} 211 | \fi 212 | \ifx\subparagraph\undefined\else 213 | \let\oldsubparagraph\subparagraph 214 | \renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} 215 | \fi 216 | $endif$ 217 | $if(dir)$ 218 | \ifxetex 219 | % load bidi as late as possible as it modifies e.g. graphicx 220 | $if(latex-dir-rtl)$ 221 | \usepackage[RTLdocument]{bidi} 222 | $else$ 223 | \usepackage{bidi} 224 | $endif$ 225 | \fi 226 | \ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex 227 | \TeXXeTstate=1 228 | \newcommand{\RL}[1]{\beginR #1\endR} 229 | \newcommand{\LR}[1]{\beginL #1\endL} 230 | \newenvironment{RTL}{\beginR}{\endR} 231 | \newenvironment{LTR}{\beginL}{\endL} 232 | \fi 233 | $endif$ 234 | 235 | % set default figure placement to htbp 236 | \makeatletter 237 | \def\fps@figure{htbp} 238 | \makeatother 239 | 240 | $for(header-includes)$ 241 | $header-includes$ 242 | $endfor$ 243 | 244 | \newcommand*{\TitleFont}{% 245 | \usefont{\encodingdefault}{\rmdefault}{b}{n}% 246 | \fontsize{18}{20}% 247 | \selectfont} 248 | 249 | $if(title)$ 250 | \title{\TitleFont $title$$if(thanks)$\thanks{$thanks$}$endif$} 251 | $endif$ 252 | $if(subtitle)$ 253 | \providecommand{\subtitle}[1]{} 254 | \subtitle{$subtitle$} 255 | $endif$ 256 | 257 | $if(author)$ 258 | \author{ 259 | $for(author)$ 260 | \IEEEauthorblockN{$author.name$} 261 | \IEEEauthorblockA{% 262 | $author.affiliation$ \\ 263 | $author.location$ \\ 264 | $author.email$} 265 | $sep$ \and 266 | $endfor$ 267 | } 268 | $endif$ 269 | 270 | $if(institute)$ 271 | \providecommand{\institute}[1]{} 272 | \institute{$for(institute)$$institute$$sep$ \and $endfor$} 273 | $endif$ 274 | \date{$date$} 275 | 276 | \begin{document} 277 | $if(title)$ 278 | \maketitle 279 | $endif$ 280 | $if(abstract)$ 281 | \begin{abstract} 282 | $abstract$ 283 | \end{abstract} 284 | $endif$ 285 | 286 | $if(keywords)$ 287 | \begin{IEEEkeywords} 288 | $for(keywords)$ 289 | $keywords$$sep$; 290 | $endfor$ 291 | \end{IEEEkeywords} 292 | $endif$ 293 | 294 | $for(include-before)$ 295 | $include-before$ 296 | 297 | $endfor$ 298 | $if(toc)$ 299 | { 300 | $if(colorlinks)$ 301 | \hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$black$endif$} 302 | $endif$ 303 | \setcounter{tocdepth}{$toc-depth$} 304 | \tableofcontents 305 | } 306 | $endif$ 307 | $if(lot)$ 308 | \listoftables 309 | $endif$ 310 | $if(lof)$ 311 | \listoffigures 312 | $endif$ 313 | $body$ 314 | 315 | $if(natbib)$ 316 | $if(bibliography)$ 317 | $if(biblio-title)$ 318 | $if(book-class)$ 319 | \renewcommand\bibname{$biblio-title$} 320 | $else$ 321 | \renewcommand\refname{$biblio-title$} 322 | $endif$ 323 | $endif$ 324 | \bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} 325 | 326 | $endif$ 327 | $endif$ 328 | $if(biblatex)$ 329 | \printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$ 330 | 331 | $endif$ 332 | $for(include-after)$ 333 | $include-after$ 334 | 335 | $endfor$ 336 | \end{document} 337 | 338 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/testing-and-deployment.md: -------------------------------------------------------------------------------- 1 | A full version of the interblockchain protocol has been implemented in Go in the Cosmos SDK [@ibc_cosmos_sdk], an implementation is in progress in Rust [@ibc_rust], and implementations are planned for other languages in the future. An off-ledger relayer daemon has also been implemented in Go [@relayer_go]. Game of Zones [@game_of_zones], a live test of the initial software release, is currently in progress. Over one hundred simulated zones (separate consensus instances and ledgers) have been successfully linked together [@map_of_zones]. 2 | 3 | Production release and deployment to the Cosmos Network is planned for later this summer. As IBC is a permissionless, opt-in protocol, adoption will be dependent on ledgers voluntarily electing to support the specification, in full or in part. Adoption of IBC does not require connection to the Cosmos Hub, usage of any particular token, or even usage of any other piece of Cosmos software — IBC can be implemented on top of other state machine frameworks such as Substrate [@substrate], or by standalone ledgers using custom logic — adherence to the correct protocol is both necessary and sufficient for successful interoperation. 4 | -------------------------------------------------------------------------------- /archive/papers/2020-05/src/usage-patterns.md: -------------------------------------------------------------------------------- 1 | ## Call receiver 2 | 3 | Essential to the functionality of the IBC handler is an interface to other modules 4 | running on the same ledger, so that it can accept requests to send packets and can 5 | route incoming packets to modules. This interface should be as minimal as possible 6 | in order to reduce implementation complexity and requirements imposed on host ledgers. 7 | 8 | For this reason, the core IBC logic uses a receive-only call pattern that differs 9 | slightly from the intuitive dataflow. As one might expect, modules call into the IBC handler to create 10 | connections, channels, and send packets. However, instead of the IBC handler, upon receipt 11 | of a packet from another ledger, selecting and calling into the appropriate module, 12 | the module itself must call `recvPacket` on the IBC handler (likewise for accepting 13 | channel creation handshakes). When `recvPacket` is called, the IBC handler will check 14 | that the calling module is authorised to receive and process the packet (based on included proofs and 15 | known state of connections / channels), perform appropriate state updates (incrementing 16 | sequence numbers to prevent replay), and return control to the module or throw on error. 17 | The IBC handler never calls into modules directly. 18 | 19 | Although a bit counterintuitive to reason about at first, this pattern has a few notable advantages: 20 | 21 | - It minimises requirements of the host ledger, since the IBC handler need not understand how to call 22 | into other modules or store any references to them. 23 | - It avoids the necessity of managing a module lookup table in the handler state. 24 | - It avoids the necessity of dealing with module return data or failures. If a module does not want to 25 | receive a packet (perhaps having implemented additional authorisation on top), it simply never calls 26 | `recvPacket`. If the routing logic were implemented in the IBC handler, the handler would need to deal 27 | with the failure of the module, which is tricky to interpret. 28 | 29 | It also has one notable disadvantage: without an additional abstraction, the relayer logic becomes more complex, since off-ledger 30 | relayer processes will need to track the state of multiple modules to determine when packets 31 | can be submitted. 32 | 33 | For this reason, ledgers may implement an additional IBC "routing module" which exposes a call dispatch interface. 34 | 35 | ## Call dispatch 36 | 37 | For common relay patterns, an "IBC routing module" can be implemented which maintains a module dispatch table and simplifies the job of relayers. 38 | 39 | In the call dispatch pattern, datagrams (contained within transaction types defined by the host ledger) are relayed directly 40 | to the routing module, which then looks up the appropriate module (owning the channel and port to which the datagram was addressed) 41 | and calls an appropriate function (which must have been previously registered with the routing module). This allows modules to 42 | avoid handling datagrams directly, and makes it harder to accidentally screw-up the atomic state transition execution which must 43 | happen in conjunction with sending or receiving a packet (since the module never handles packets directly, but rather exposes 44 | functions which are called by the routing module upon receipt of a valid packet). 45 | 46 | Additionally, the routing module can implement default logic for handshake datagram handling (accepting incoming handshakes 47 | on behalf of modules), which is convenient for modules which do not need to implement their own custom logic. 48 | -------------------------------------------------------------------------------- /archive/v0_3_1_IBC.pdf: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:472a53104e4d9bc6a8abde8f851c951fab58e3db2bd4ade8c7c057adc42852c3 3 | size 899421 4 | -------------------------------------------------------------------------------- /assets/interchain-standards-image.jpg: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:948d72f8ce9f7758316c8ecd11c8045cf3a4918514b4077e2e37d8f5f4e1f301 3 | size 373917 4 | -------------------------------------------------------------------------------- /assets/interchain-standards.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:41af59f94412b6ba1db7afe6bc18efaa8c1415dab951ad91b5d5bb9527b3dcb6 3 | size 118722 4 | -------------------------------------------------------------------------------- /meta/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contribution Guidelines 2 | 3 | Thanks for your interest in contributing to IBC! Contributions are always welcome. 4 | 5 | Contributing to this repo can mean many things such as participating in discussion or proposing changes. To ensure a smooth workflow for all contributors, the general procedure for contributing has been established: 6 | 7 | - Feel free to [open](https://github.com/cosmos/ibc/issues/new) an issue to raise a question, explain a concern, or discuss a possible future feature, protocol change, or standard. 8 | - Make sure first that the issue does not already [exist](https://github.com/cosmos/ibc/issues). 9 | - Participate in thoughtful discussion on the issue. 10 | 11 | - If you would like to contribute in fixing / closing an issue: 12 | - If the issue is a proposal, ensure that the proposal has been accepted. 13 | - Ensure that nobody else has already begun working on this issue. If they have, make sure to contact them to collaborate. 14 | - If nobody has been assigned for the issue and you would like to work on it, make a comment on the issue to inform the community of your intentions to begin work. 15 | - Follow standard Github best practices: fork the repo, branch from the HEAD of `master`, make some commits, and submit a PR to `master`. 16 | For more details, see the [Pull Requests](#pull-requests) section below. 17 | - Be sure to submit the PR early in `Draft` mode, even if it's incomplete as this indicates to the community you're working on something and allows them to provide comments at an early stage. 18 | - When the PR is complete it can be marked `Ready for Review`. 19 | 20 | - If you would like to propose a new standard for inclusion in the IBC standards, please take a look at [PROCESS.md](./PROCESS.md) for a detailed description of the standardisation process. 21 | - To start a new standardisation document, copy the [template](../spec/ics-template.md) and open a PR. 22 | 23 | If you have any questions, you can usually find some IBC team members on the [Cosmos Discord](https://discord.gg/cosmosnetwork). 24 | 25 | ## Pull Requests 26 | 27 | To accommodate the review process we suggest that PRs are categorically broken up. 28 | Each PR should address only a single issue and **a single standard**. 29 | The PR name should be prefixed by the standard number, 30 | e.g., `ICS4: Some improvements` should contain only changes to [ICS 4](../spec/core/ics-004-channel-and-packet-semantics/README.md). 31 | If fixing an issue requires changes to multiple standards, create multiple PRs and mention the inter-dependencies. 32 | 33 | ### Process for reviewing PRs 34 | 35 | All PRs require an approval from at least two members of the [standardisation committee](./STANDARDS_COMMITTEE.md) before merge. 36 | The PRs submitted by one of the members of the standardisation committee require an approval from only one other member before merge. 37 | When reviewing PRs please use the following review explanations: 38 | 39 | - `Approval` through the GH UI means that you understand all the changes proposed in the PR. In addition: 40 | - You must also think through anything which ought to be included but is not. 41 | - You must think through any potential security issues or incentive-compatibility flaws introduced by the changes. 42 | - The changes must be consistent with the other IBC standards, especially the [core IBC standards](../README.md#core-transport). 43 | - The modified standard must be consistent with the description from [ICS 1](../spec/ics-001-ics-standard/README.md). 44 | - If you are only making "surface level" reviews, submit any notes as `Comments` without adding a review. 45 | 46 | ### PR Targeting 47 | 48 | Ensure that you base and target your PR on the `master` branch. 49 | 50 | ### Development Procedure 51 | 52 | - The latest state of development is on `master`. 53 | - Create a development branch either on `github.com/cosmos/ibc` or your fork (using `git remote add fork`). 54 | - To ensure a clear ownership of branches on the ibc repo, branches must be named with the convention `{moniker}/{issue#}-branch-name` 55 | - Before submitting a pull request, begin `git rebase` on top of `master`. 56 | **Since standards cannot be compiled, make sure that the changes in your PR remains consistent with the new commits on the `master` branch**. 57 | 58 | ### Pull Merge Procedure 59 | 60 | - Ensure all github requirements pass. 61 | - Squash and merge pull request. 62 | -------------------------------------------------------------------------------- /meta/PROCESS.md: -------------------------------------------------------------------------------- 1 | ## IBC Standardisation Process 2 | 3 | IBC standardisation will follow an adaptation of the [TC 39](https://tc39.github.io/process-document/) process used by the ECMAScript steering committee. 4 | 5 | ### Stage 1 - `Strawman` 6 | 7 | - ***Purpose***: Start the specification process 8 | - ***Entrance Criteria***: [Open an issue](https://github.com/cosmos/ibc/issues/new) on this repository with a short outline of your proposal and a specification name. 9 | - ***Acceptance Requirements***: No acceptance required to move to the next stage. Keep the issue around to track the specification status, and close it when the final specification is merged or the proposal abandoned. 10 | - ***Spec Quality***: Outline only. Link to any prior documentation, discussion, or reference materials. 11 | - ***Changes Expected Post-Acceptance***: N/A 12 | - ***Implementation Types Expected***: None required, but link to any existing 13 | 14 | ### Stage 2 - `Draft` 15 | 16 | - ***Purpose***: 17 | - Make the case for the addition of this specification to the IBC ecosystem 18 | - Describe the shape of a potential solution 19 | - Identify challenges to this proposal 20 | - ***Entrance Criteria***: 21 | - Prose outlining the problem or need and the general shape of a solution in a PR to a `./spec/{area}/ics-{{ .Spec.Number }}-{{ .Spec.Name }}/README.md` file in this repository. 22 | This file should contain: 23 | - List of expected projects & users within the Cosmos ecosystem who might make use of the specification along with any particular requirements they have 24 | - Discussion of key algorithms, abstractions, and semantics 25 | - High-level application interface outline, where applicable 26 | - Identification of potential design trade-offs and implementation challenges/complexity 27 | 28 | For a more detailed description of standard requirements, see [ICS 1](../spec/ics-001-ics-standard). 29 | 30 | For more details on submitting a PR, take a look at the [Pull Requests](./CONTRIBUTING.md#pull-requests) section in the contribution guidelines. 31 | - Identified `author(s)` who will advance the proposal in the header of the standard file 32 | - Any additional reference documentation or media in the `./spec/ics-{{ .Spec.Number }}-{{ .Spec.Name }}` directory 33 | - The specification team expects that this proposal will be finalised and eventually included in the IBC standard set. 34 | - ***Spec Quality***: 35 | - Follows the structure laid out in ICS 1 and provides a reasonable overview of the proposed addition. 36 | - ***Acceptance Requirements***: 37 | - The PR has received two approvals from members of the [core specification committee](./STANDARDS_COMMITTEE.md), at which point it can be merged into the IBC repository. 38 | - ***Changes Expected Post-Acceptance***: 39 | - Changes to details but not to the key concepts are expected after a standard enters draft stage. Implementers should work with the spec authors as work continues on spec development. 40 | - ***Implementation Types Expected***: 41 | - Tightly bounded demos, example repositories showing reproduction steps for issues fixed by proposal 42 | 43 | ### Stage 3 - `Candidate` 44 | 45 | - ***Purpose***: 46 | - Indicate that further refinement will require feedback from implementations and users 47 | - ***Entrance Criteria***: 48 | - Everything from stages 1 & 2 49 | - Complete specification text 50 | - At least one specification-compatible implementation exists 51 | - All relevant ecosystem stakeholders have been given a chance to review and provide feedback on the standard 52 | - The solution is complete and no further work is possible without implementation experience, significant usage and external feedback. 53 | - ***Spec Quality***: 54 | - Complete: all semantics, syntax and API are completed as described 55 | - ***Acceptance Requirements***: 56 | - The PR changing the stage to "candidate" has been approved by two members of the core specification team. 57 | - ***Changes Expected Post-Acceptance***: 58 | - Limited: only those deemed critical based on implementation experiences. 59 | - ***Implementation Types Expected***: 60 | - Specification-compliant 61 | 62 | ### Stage 4 - `Finalised` 63 | 64 | - ***Purpose***: 65 | - Indicate that the addition is included in the formal ICS standard set 66 | - ***Entrance Criteria***: 67 | - Everything from stages 1,2,3 68 | - At least two specification-compatible implementations exist, and they have been tested against each other 69 | - All relevant ecosystem stakeholders approve the specification (any holdout can block this stage) 70 | - Acceptance tests are written and merged into the relevant repositories 71 | - All files in the `./spec/ics-{{ .Spec.Number }}-{{ .Spec.Name}}/` directory are up to date and merged into the `cosmos/ics` repository 72 | - ***Acceptance Requirements***: 73 | - The PR changing the stage to "finalised" has been approved by representatives from all relevant ecosystem stakeholders, and all members of the core specification team. 74 | - ***Spec Quality***: 75 | - Final: All changes as a result of implementation experience are integrated 76 | - ***Changes Expected Post-Acceptance***: 77 | - Backward-compatible fixes or breaking changes that are supported by a backwards-compatibility preserving upgrade protocol 78 | - ***Implementation Types Expected***: 79 | - Shipping/Production 80 | 81 | ### Calls for implementation and feedback 82 | 83 | When an addition is accepted at the “candidate” (stage 3) maturity level, the committee is signifying that it believes design work is complete and further refinement will require implementation experience, significant usage and external feedback. 84 | -------------------------------------------------------------------------------- /meta/STANDARDS_COMMITTEE.md: -------------------------------------------------------------------------------- 1 | ## Standards Committee 2 | 3 | Currently, the core standardisation committee consists of: 4 | 5 | - Aditya Sripal (@adityasripal) 6 | - Gjermund Garaba (@gjermundgaraba) 7 | - Serdar Turkmenafsar (@srdtrk) 8 | 9 | A two-of-three quorum is needed to approve pull requests to this repository. 10 | -------------------------------------------------------------------------------- /spec/IBC_V2/core/ics-005-port-allocation/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 5 3 | title: Port Allocation 4 | stage: Draft 5 | required-by: 4 6 | category: IBC/TAO 7 | kind: interface 8 | version compatibility: ibc-go v10.0.0 9 | author: Aditya Sripal 10 | created: 2024-05-17 11 | --- 12 | 13 | ## Synopsis 14 | 15 | This standard specifies the port allocation system by which modules can bind to uniquely named ports allocated by the IBC handler. 16 | The port identifiers in the packet defines which application to route the packet callback to. The source portID is an identifier of the application sending the packet, thus it will also receive the `AcknowledgePacket` and `TimeoutPacket` callback. The destination portID is the identifier of the application receiving the packet and will receive the `ReceivePacket` callback. 17 | 18 | Modules may register multiple ports on a state machine and send from any of their registered ports to any arbitrary port on a remote state machine. Each port on a state machine must be mapped to a specific IBC module as defined by [ICS-26](../ics-026-application-callbacks/README.md). Thus the IBC application to portID mapping is one-to-many. 19 | 20 | NOTE: IBC v1 included a channel along with a channel handshake that explicitly associated a unique channel between two portIDs on counterparty chains. Thus, the portIDs on both sides were tightly coupled such that no other application other than the ones bound by the portIDs were allowed to send packets on the dedicated channel. IBC v2 removed the concept of a channel and all packet flow is between chains rather than being isolated module-module communication. Thus, an application on a sending chain is allowed to send a packet to ANY other application on a destination chain by identifying the application with the portIDs in the packet. Thus, it is now the responsibility of applications to restrict which applications are allowed to send packets to them by checking the portID in the callback and rejecting any packet that comes from an unauthorized application. 21 | 22 | ### Motivation 23 | 24 | The interblockchain communication protocol is designed to facilitate module-to-module communication, where modules are independent, possibly mutually distrusted, self-contained 25 | elements of code executing on sovereign ledgers. 26 | 27 | ## Technical Specification 28 | 29 | ### Registering a port 30 | 31 | The IBC handler MUST provide a way for applications to register their callbacks on a portID. 32 | 33 | ```typescript 34 | function registerPort(portId: Identifier, cbs: ICS26App) => void 35 | ``` 36 | 37 | RegisterPort Preconditions: 38 | 39 | - There is no other application that is registered on the port router for the given `portId`. 40 | 41 | RegisterPort Postconditions: 42 | 43 | - The ICS26 application is registered on the provided `portId`. 44 | - Any incoming packet flow message addressed to the `portId` is routed to the ICS26 application. Any outgoing packet flow message addressed by the `portId` MUST come from the ICS26 application 45 | 46 | ### Authenticating and Routing Packet Flow Messages 47 | 48 | Once an application is registered with a port, it is the port router's responsibility to properly route packet flow messages to the appropriate application identified by the portId in the payload. Similarly when the application sends packet flow messages to the port router, the router MUST ensure that the application is authenticated to send the packet flow message by checking if the payload portIDs are registered to the application. 49 | 50 | For packet flow messages on the packet sending chain (e.g. `SendPacket`, `AcknowledgePacket`, `TimeoutPacket`); the port router MUST do this authentication and routing using the packet payload's `sourcePortId`. 51 | 52 | For packet flow messages on the packet receiving chain (e.g. `RecvPacket` and optionally the asynchronous `WriteAcknowledgement`); the port router MUST do this authentication and routing using the packet payload's `destPortId`. 53 | 54 | [ICS-4](../ics-004-packet-semantics/PACKET_HANDLER.md) defines the packet flow messages and the expected behavior of their respected handlers. When the packet flow message arrives from the core ICS-4 handler to the application (e.g. `RecvPacket`, `AcknowledgePacket`, `TimeoutPacket`); then the portRouter acts as a router routing the message from the core handler to the ICS26 application. When the packet flow message arrives from the application to the core ICS-4 handler (e.g. `SendPacket`, or the optional `WriteAcknowledgement`); then the portRouter acts as an authenticator by checking that the calling application is registered as the owner of port they wish to send the message on before sending the message to the ICS-4 handler. 55 | 56 | NOTE: It is possible for implementations to change the order of execution flow so long as they still respect all the expected semantics and behavior defined in ICS-4. In this case, the port router's role as router or authenticator will change accordingly. 57 | -------------------------------------------------------------------------------- /spec/IBC_V2/core/ics-024-host-requirements/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 24 3 | title: Host State Machine Requirements 4 | stage: draft 5 | category: IBC/TAO 6 | kind: interface 7 | required-by: 4 8 | version compatibility: ibc-go v10.0.0 9 | author: Aditya Sripal 10 | created: 2024-08-21 11 | modified: 2024-08-21 12 | --- 13 | 14 | ## Synopsis 15 | 16 | This specification defines the minimal set of properties which must be fulfilled by a state machine hosting an implementation of the interblockchain communication protocol. IBC relies on a key-value provable store for cross-chain communication. In version 2 of the specification, the expected key-value storage will only be for the keys that are relevant for packet processing. 17 | 18 | ### Motivation 19 | 20 | IBC is designed to be a common standard which will be hosted by a variety of blockchains & state machines and must clearly define the requirements of the host. 21 | 22 | ### Definitions 23 | 24 | ### Desired Properties 25 | 26 | IBC should require as simple an interface from the underlying state machine as possible to maximise the ease of correct implementation. 27 | 28 | ## Technical Specification 29 | 30 | ### Module system 31 | 32 | The host state machine must support a module system, whereby self-contained, potentially mutually distrusted packages of code can safely execute on the same ledger, control how and when they allow other modules to communicate with them, and be identified and manipulated by a "master module" or execution environment. 33 | 34 | The IBC core handlers as defined in ICS-4 must have 35 | 36 | ### Paths, identifiers, separators 37 | 38 | An `Identifier` is a bytestring used as a key for an object stored in state, such as a packet commitment, acknowledgement, or receipt. 39 | 40 | Identifiers MUST be non-empty (of positive integer length). 41 | 42 | Identifiers MUST consist of characters in one of the following categories only: 43 | 44 | - Alphanumeric 45 | - `.`, `_`, `+`, `-`, `#` 46 | - `[`, `]`, `<`, `>` 47 | 48 | A `Path` is a bytestring used as the key for an object stored in state. Paths MUST contain only identifiers, constant bytestrings, and the separator `"/"`. 49 | 50 | Identifiers are not intended to be valuable resources — to prevent name squatting, minimum length requirements or pseudorandom generation MAY be implemented, but particular restrictions are not imposed by this specification. 51 | 52 | The separator `"/"` is used to separate and concatenate two identifiers or an identifier and a constant bytestring. Identifiers MUST NOT contain the `"/"` character, which prevents ambiguity. 53 | 54 | By default, identifiers have the following minimum and maximum lengths in characters: 55 | 56 | | Port identifier | Client identifier | 57 | | --------------- | ----------------- | 58 | | 2 - 128 | 2 - 64 | 59 | 60 | ### Key/value Store 61 | 62 | The host state machine MUST provide a key/value store interface 63 | with three functions that behave in the standard way: 64 | 65 | ```typescript 66 | type get = (path: Path) => Value | void 67 | ``` 68 | 69 | ```typescript 70 | type set = (path: Path, value: Value) => void 71 | ``` 72 | 73 | ```typescript 74 | type queryProof = (path: Path) => (CommitmentProof, Value) 75 | ``` 76 | 77 | `queryProof` will return a `Membership` proof if there exists a value for that path in the key/value store and a `NonMembership` proof if there is no value stored for the path. 78 | 79 | The host state machine SHOULD provide an interface for deleting 80 | a Path from the key/value store as well though it is not required: 81 | 82 | ```typescript 83 | type delete = (path: Path) => void 84 | ``` 85 | 86 | `Path` is as defined above. `Value` is an arbitrary bytestring encoding of a particular data structure. The specific Path and Values required to be written to the provable store are defined in [ICS-4](../ics-004-packet-semantics/PACKET.md). 87 | 88 | These functions MUST be permissioned to the IBC packet handler module (the implementation of which is described in [ICS-4](../ics-004-packet-semantics/PACKET_HANDLER.md)) only, so only the IBC handler module can `set` or `delete` the paths that can be read by `get`. 89 | 90 | In most cases, this will be implemented as a sub-store (prefixed key-space) of a larger key/value store used by the entire state machine. This is why ICS-2 defines a `counterpartyCommitmentPrefix` that is associated with the client. The IBC handler will prefix the `counterpartyCommitmentPrefix` to the ICS-4 standardized path before proof verification against a `ConsensusState` in the client. 91 | 92 | ### Provable Path-space 93 | 94 | IBC/TAO implementations MUST implement the following paths for the `provableStore` in the exact format specified. This is because counterparty IBC/TAO implementations will construct the paths according to this specification and send it to the light client to verify the IBC specified value stored under the IBC specified path. 95 | 96 | Future paths may be used in future versions of the protocol, so the entire key-space in the provable store MUST be reserved for the IBC handler. 97 | 98 | | Value | Path format | 99 | | -------------------------- | -------------------------------------------- | 100 | | Packet Commitment | {sourceClientId}0x1{bigEndianUint64Sequence} | 101 | | Packet Receipt | {destClientId}0x2{bigEndianUint64Sequence} | 102 | | Acknowledgement Commitment | {destClientId}0x3{bigEndianUint64Sequence} | 103 | 104 | IBC V2 only proves commitments related to packet handling, thus the commitments and how to construct them are specifed in [ICS-4](../ics-004-packet-semantics/PACKET.md). 105 | 106 | As mentioned above, the provable path space controlled by the IBC handler may be prefixed in a global provable key/value store. In this case, the prefix must be appended by the IBC handler before the proof is verified. 107 | 108 | The provable store MUST be capable of providing `MembershipProof` for a key/value pair that exists in the store. It MUST also be capable of providing a `NonMembership` proof for a key that does not exist in the store. 109 | 110 | In the case, the state machine does not support `NonMembership` proofs; a client may get around this restriction by associating a `SENTINEL_ABSENCE_VALUE` with meaning the key does not exist and treating a `MembershipProof` with a `SENTINEL_ABSENCE_VALUE` as a `NonMembershipProof`. In this case, the state machine is responsible for ensuring that there is a way to write a `SENTINEL_ABSENCE_VALUE` to the keys that IBC needs to prove nonmembership for and it MUST ensure that an actor cannot set the `SENTINEL_ABSENCE_VALUE` directly for a key accidentally. These requirements and how to implement them are outside the scope of this specification and remain the responsibility of the bespoke IBC implementation. 111 | 112 | ### Finality 113 | 114 | The state machine MUST make updates sequentially so that all state updates happen in order and can be associated with a unique `Height` in that order. Each state update at a height `h` MUST be eventually **finalized** at a finite timestamp `t` such that the order of state updates from the initial state up to `h` will never change after time `t`. 115 | 116 | IBC handlers will only accept packet-flow messages from state updates which are already deemed to be finalized. In cases where the finality property is probabilistically guaranteed, this probabilitic guarantee must be handled within the ICS-2 client in order to provide a final view of the remote state machine for the ICS-4 packet handler. 117 | 118 | ### Time 119 | 120 | As the state updates are applied to the state machine over time, the state update algorithm MUST itself have secure access to the current timestamp at which the state update is being applied. This is needed for IBC handlers to process timeouts correctly. 121 | 122 | If the state machine update mechanism does not itself provide a timestamp to the state machine handler, then there must be a time oracle updates as part of the state machine update itself. In this case, the security model of IBC will also include the security model of the time oracle. 123 | 124 | This timestamp for a state update MUST be monotonically increasing and it MUST be the greater than or equal to the timestamp that the counterparty client will return for the `ConsensusState` associated with that state update. 125 | 126 | ## Backwards Compatibility 127 | 128 | Not applicable. 129 | 130 | ## Forwards Compatibility 131 | 132 | Key/value store functionality and consensus state type are unlikely to change during operation of a single host state machine. 133 | 134 | `submitDatagram` can change over time as relayers should be able to update their processes. 135 | 136 | ## Example Implementations 137 | 138 | ## History 139 | 140 | Aug 21, 2024 - [Initial draft](https://github.com/cosmos/ibc/pull/1144) 141 | 142 | ## Copyright 143 | 144 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 145 | -------------------------------------------------------------------------------- /spec/app/ics-020-fungible-token-transfer/deprecated/forwarding-3-chains-failure.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:6dc4315071acba8f42f68d25ed6dbfe7c6590840e7156d1e9af7c80e8fd99667 3 | size 332488 4 | -------------------------------------------------------------------------------- /spec/app/ics-020-fungible-token-transfer/deprecated/forwarding-3-chains-success.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:8407e9b5f8cb8560d87a4500e2256eb9d4115169c4c431e2774ed843c66e5c79 3 | size 271912 4 | -------------------------------------------------------------------------------- /spec/app/ics-020-fungible-token-transfer/deprecated/source-and-sink-zones.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:b6d9f65c7b4453999fc5d8b277cbb30a3874fbfc161eb5b8a079ced5fb284c84 3 | size 228938 4 | -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 28 3 | title: Cross-Chain Validation 4 | stage: draft 5 | category: IBC/APP 6 | requires: 25, 26, 20 7 | author: Marius Poke , Aditya Sripal , Jovan Komatovic , Cezara Dragoi , Josef Widder 8 | created: 2022-06-27 9 | modified: 2022-12-02 10 | --- 11 | 12 | 13 | # Synopsis 14 | 15 | This standard document specifies packet data structure, state machine handling logic, and encoding details for Cross-Chain Validation (CCV). CCV is the specific IBC level protocol that enables *Interchain Security*, a Cosmos-specific category of *Shared Security*. 16 | 17 | At a high level, CCV enables a *provider chain* (e.g., the Cosmos Hub) to provide *security* to multiple *consumer chains*. This means that the validator sets on the consumer chains are chosen from the validator set of the provider chain (for more details, see the [Security Model](./overview_and_basic_concepts.md#security-model) section). 18 | 19 | The communication between the provider and the consumer chains is done through the IBC protocol over a *unique*, *ordered* channel (one for each consumer chain). 20 | 21 | > Throughout this document, we will use the terms chain and blockchain interchangeably. 22 | 23 | ## Contents 24 | 25 | - [Overview and Basic Concepts](./overview_and_basic_concepts.md) 26 | - [System Model and Properties](./system_model_and_properties.md) 27 | - [Technical Specification: Data Structures and Methods](./technical_specification.md) 28 | - [Data Structures](./data_structures.md) 29 | - [Methods](./methods.md) 30 | 31 | 39 | 40 | ## Example Implementations 41 | 42 | - Interchain Security [Go implementation](https://github.com/cosmos/interchain-security). 43 | 44 | 50 | 51 | ## History 52 | 53 | Jun 27, 2022 - Draft written 54 | 55 | Aug 3, 2022 - Revision of *Bond-Based Consumer Voting Power* property 56 | 57 | Aug 29, 2022 - Notify Staking module of matured unbondings in `EndBlock()` 58 | 59 | Dec 2, 2022 - Enable existing chains to become consumer chains 60 | 61 | Dec 7, 2022 - Add provider-based timeouts 62 | 63 | ## Copyright 64 | 65 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 66 | -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-distribution-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-distribution-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-evidence-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-evidence-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-height-mapping-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-height-mapping-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-init-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-init-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-mapping-intuition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-mapping-intuition.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-preccv-init-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-preccv-init-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-unbonding-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-unbonding-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-vsc-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/app/ics-028-cross-chain-validation/figures/ccv-vsc-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/technical_specification.md: -------------------------------------------------------------------------------- 1 | 2 | # CCV: Technical Specification 3 | 4 | [↑ Back to main document](./README.md) 5 | 6 | 7 | ## Outline 8 | 9 | - [Placing CCV within an ABCI Application](#placing-ccv-within-an-abci-application) 10 | - [Implemented Interfaces](#implemented-interfaces) 11 | - [Interfacing Other Modules](#interfacing-other-modules) 12 | - [Data Structures and Methods](#data-structures-and-methods) 13 | 14 | ## Placing CCV within an ABCI Application 15 | 16 | [↑ Back to Outline](#outline) 17 | 18 | Before describing the data structures and sub-protocols of the CCV protocol, we provide a short overview of the interfaces the CCV module implements and the interactions with the other ABCI application modules. 19 | 20 | ### Implemented Interfaces 21 | 22 | - CCV is an **ABCI application module**, which means it MUST implement the logic to handle some of the messages received from the consensus engine via ABCI, 23 | e.g., `InitChain`, `BeginBlock`, `EndBlock` (for more details, take a look at the [ABCI specification](https://github.com/tendermint/spec/tree/v0.7.1/spec/abci)). 24 | In this specification we define the following methods that handle messages that are of particular interest to the CCV protocol: 25 | - `InitGenesis()` -- Called when the chain is first started, on receiving an `InitChain` message from the consensus engine. 26 | This is also where the application can inform the underlying consensus engine of the initial validator set. 27 | - `BeginBlock()` -- Contains logic that is automatically triggered at the beginning of each block. 28 | - `EndBlock()` -- Contains logic that is automatically triggered at the end of each block. 29 | This is also where the application can inform the underlying consensus engine of changes in the validator set. 30 | 31 | - CCV is an **IBC module**, which means it MUST implement the module callbacks interface defined in [ICS 26](../../core/ics-026-routing-module/README.md#module-callback-interface). The interface consists of a set of callbacks for 32 | - channel opening handshake, which we describe in the [Initialization](./methods.md#initialization) section; 33 | - channel closing handshake, which we describe in the [Consumer Chain Removal](./methods.md#consumer-chain-removal) section; 34 | - and packet relay, which we describe in the [Packet Relay](./methods.md#packet-relay) section. 35 | 36 | ### Interfacing Other Modules 37 | 38 | - As an ABCI application module, the CCV module interacts with the underlying consensus engine through ABCI: 39 | - On the provider chain, 40 | - it initializes the application (e.g., binds to the expected IBC port) in the `InitGenesis()` method. 41 | - On the consumer chain, 42 | - it initializes the application (e.g., binds to the expected IBC port, creates a client of the provider chain) in the `InitGenesis()` method; 43 | - it provides the validator updates in the `EndBlock()` method. 44 | 45 | - As an IBC module, the CCV module interacts with Core IBC for functionalities regarding 46 | - port allocation ([ICS 5](../../core/ics-005-port-allocation)) via `portKeeper`; 47 | - channels and packet semantics ([ICS 4](../../core/ics-004-channel-and-packet-semantics)) via `channelKeeper`; 48 | - connection semantics ([ICS 3](../../core/ics-003-connection-semantics)) via `connectionKeeper`; 49 | - client semantics ([ICS 2](../../core/ics-002-client-semantics)) via `clientKeeper`. 50 | 51 | - The consumer CCV module interacts with the IBC Token Transfer module ([ICS 20](../ics-020-fungible-token-transfer/README.md)) via `transferKeeper`. 52 | 53 | - For the [Initialization sub-protocol](./methods.md#initialization), the provider CCV module interacts with a Governance module by handling governance proposals to add new consumer chains. 54 | If such proposals pass, then all validators on the provider chain MUST validate the consumer chain at spawn time; 55 | otherwise they get slashed. 56 | For an example of how governance proposals work, take a look at the [Governance module documentation](https://docs.cosmos.network/main/build/modules/gov) of Cosmos SDK. 57 | 58 | - The consumer pre-CCV module (i.e., the CCV module with `preCCV == true`) interacts with a Staking module on the consumer chain. 59 | Note that once `preCCV` is set to `false`, the Staking module MUST no longer provide validator updates to the underlying consensus engine. 60 | For an example of how staking works, take a look at the [Staking module documentation](https://docs.cosmos.network/main/build/modules/staking) of Cosmos SDK. 61 | The interaction is defined by the following interface: 62 | 63 | ```typescript 64 | interface StakingKeeper { 65 | // replace the validator set with valset 66 | ReplaceValset(valset: [ValidatorUpdate]) 67 | } 68 | ``` 69 | 70 | - The provider CCV module interacts with a Staking module on the provider chain. 71 | For an example of how staking works, take a look at the [Staking module documentation](https://docs.cosmos.network/main/build/modules/staking) of Cosmos SDK. 72 | The interaction is defined by the following interface: 73 | 74 | ```typescript 75 | interface StakingKeeper { 76 | // get UnbondingPeriod from the provider Staking module 77 | UnbondingTime(): Duration 78 | 79 | // get validator updates from the provider Staking module 80 | GetValidatorUpdates(): [ValidatorUpdate] 81 | 82 | // request the Staking module to put on hold 83 | // the completion of an unbonding operation 84 | PutUnbondingOnHold(id: uint64) 85 | 86 | // notify the Staking module of an unboding operation that 87 | // has matured from the perspective of the consumer chains 88 | UnbondingCanComplete(id: uint64) 89 | } 90 | ``` 91 | 92 | - The provider CCV module interacts with a Slashing module on the provider chain. 93 | For an example of how slashing works, take a look at the [Slashing module documentation](https://docs.cosmos.network/main/build/modules/slashing) of Cosmos SDK. 94 | The interaction is defined by the following interface: 95 | 96 | ```typescript 97 | interface SlashingKeeper { 98 | // query the Slashing module for the slashing factor, 99 | // which may be different for downtime infractions 100 | GetSlashFactor(downtime: Bool): int64 101 | 102 | // request the Slashing module to slash a validator 103 | Slash(valAddress: string, 104 | infractionHeight: int64, 105 | power: int64, 106 | slashFactor: int64) 107 | 108 | // query the Slashing module for the jailing time, 109 | // which may be different for downtime infractions 110 | GetJailTime(downtime: Bool): int64 111 | 112 | // request the Slashing module to jail a validator until time 113 | JailUntil(valAddress: string, time: uint64) 114 | } 115 | ``` 116 | 117 | - The following hook enables the provider CCV module to register operations to be execute when certain events occur within the provider Staking module: 118 | 119 | ```typescript 120 | // invoked by the Staking module after 121 | // initiating an unbonding operation 122 | function AfterUnbondingInitiated(opId: uint64); 123 | ``` 124 | 125 | - The consumer CCV module defines the following hooks that enable other modules to register operations to execute when certain events have occurred within CCV: 126 | 127 | ```typescript 128 | // invoked after a new validator is added to the validator set 129 | function AfterCCValidatorBonded(valAddress: string); 130 | 131 | // invoked after a validator is removed from the validator set 132 | function AfterCCValidatorBeginUnbonding(valAddress: string); 133 | ``` 134 | 135 | ## Data Structures and Methods 136 | 137 | [↑ Back to Outline](#outline) 138 | 139 | The remainder of this technical specification is split into [Data Structures](./data_structures.md) and [Methods](./methods.md). 140 | -------------------------------------------------------------------------------- /spec/app/ics-100-atomic-swap/ibcswap.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:9566375943632bf32b3c298b02b5d58829cf35c8740e9d03ba223c54bdcf4668 3 | size 82287 4 | -------------------------------------------------------------------------------- /spec/client/ics-009-loopback-cilent/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 9 3 | title: Loopback Client 4 | stage: draft 5 | category: IBC/TAO 6 | kind: instantiation 7 | author: Christopher Goes 8 | created: 2020-01-17 9 | modified: 2023-03-02 10 | requires: 2 11 | implements: 2 12 | --- 13 | 14 | ## Synopsis 15 | 16 | This specification describes a loopback client, designed to be used for interaction over the IBC interface with modules present on the same ledger. 17 | 18 | ### Motivation 19 | 20 | Loopback clients may be useful in cases where the calling module does not have prior knowledge of where precisely the destination module lives and would like to use the uniform IBC message-passing interface (similar to `127.0.0.1` in TCP/IP). 21 | 22 | ### Definitions 23 | 24 | Functions & terms are as defined in [ICS 2](../../core/ics-002-client-semantics). 25 | 26 | `ConnectionEnd` and `generateIdentifier` are as defined in [ICS 3](../../core/ics-003-connection-semantics) 27 | 28 | `getCommitmentPrefix` is as defined in [ICS 24](../../core/ics-024-host-requirements). 29 | 30 | `removePrefix` is as defined in [ICS 23](../../core/ics-023-vector-commitments). 31 | 32 | ### Desired Properties 33 | 34 | Intended client semantics should be preserved, and loopback abstractions should be negligible cost. 35 | 36 | ## Technical Specification 37 | 38 | ### Data Structures 39 | 40 | No consensus state, headers, or evidence data structures are required for a loopback client. The loopback client does not need to store the consensus state of a remote chain, since state verification does not require to check a Merkle proof against a previously validated commitment root. 41 | 42 | ```typescript 43 | type ConsensusState object 44 | 45 | type Header object 46 | 47 | type Misbehaviour object 48 | ``` 49 | 50 | ### Client state 51 | 52 | The loopback client state tracks the latest height of the local ledger. 53 | 54 | ```typescript 55 | interface ClientState { 56 | latestHeight: Height 57 | } 58 | ``` 59 | 60 | ### Height 61 | 62 | The height of a loopback client state consists of two `uint64`s: the revision number, and the height in the revision. 63 | 64 | ```typescript 65 | interface Height { 66 | revisionNumber: uint64 67 | revisionHeight: uint64 68 | } 69 | ``` 70 | 71 | ### Sentinel objects 72 | 73 | Similarly as in TCP/IP, where there exists a single loopback address, the protocol defines the existence of a single sentinel `ClientState` instance with the client identifier `09-localhost`. Creation of other loopback clients MUST be forbidden. 74 | 75 | Additionally, implementations **will** reserve a special connection identifier `connection-localhost` to be used by a single sentinel `ConnectionEnd` stored by default (i.e. at genesis or upgrade). The `clientIdentifier` and `counterpartyClientIdentifier` of the connection end both reference the sentinel `09-localhost` client identifier. The `counterpartyConnectionIdentifier` references the special connection identifier `connection-localhost`. The existence of a sentinel loopback connection end enables IBC applications to establish channels directly on top of the sentinel connection. Channel handshakes can then be initiated by supplying the loopback connection identifier (`connection-localhost`) in the `connectionHops` parameter of the `ChanOpenInit` datagram. 76 | 77 | Implementations **may** also allow the creation of more connections associated with the loopback client. These connections would then have a connection identifier as generated by `generateIdentifier`. 78 | 79 | ### Relayer messages 80 | 81 | Relayers supporting localhost packet flow must be adapted to submit messages from sending applications back to the originating chain. 82 | 83 | This would require first checking the underlying connection identifier on any channel-level messages. If the underlying connection identifier is `connection-localhost`, then the relayer must construct the message and send it back to the originating chain. The message MUST be constructed with a sentinel byte for the proof (`[]byte{0x01}`), since the loopback client does not need Merkle proofs of the state of a remote ledger; the proof height in the message may be zero, since it is ignored by the loopback client. 84 | 85 | Implementations **may** choose to implement loopback such that the next message in the handshake or packet flow is automatically called without relayer-driven transactions. However, implementers must take care to ensure that automatic message execution does not cause gas consumption issues. 86 | 87 | ### Client initialisation 88 | 89 | Loopback client initialisation requires the latest height of the local ledger. 90 | 91 | ```typescript 92 | function initialise(identifier: Identifier, clientState: ClientState, consensusState: ConsensusState) { 93 | assert(clientState.latestHeight > 0) 94 | assert(consensusState === nil) 95 | 96 | provableStore.set("clients/{identifier}/clientState", clientState) 97 | } 98 | ``` 99 | 100 | ### Validity predicate 101 | 102 | No validity checking is necessary in a loopback client; the function should never be called. 103 | 104 | ```typescript 105 | function verifyClientMessage(clientMsg: ClientMessage) { 106 | assert(false) 107 | } 108 | ``` 109 | 110 | ### Misbehaviour predicate 111 | 112 | No misbehaviour checking is necessary in a loopback client; the function should never be called. 113 | 114 | ```typescript 115 | function checkForMisbehaviour(clientMsg: clientMessage) => bool { 116 | return false 117 | } 118 | ``` 119 | 120 | ### Update state 121 | 122 | Function `updateState` will perform a regular update for the loopback client. The `clientState` will be updated with the latest height of the local ledger. This function should be called automatically at every height. 123 | 124 | ```typescript 125 | function updateState(clientMsg: clientMessage) { 126 | clientState = provableStore.get("clients/{clientMsg.identifier}/clientState") 127 | 128 | // retrieve the latest height from the local ledger 129 | height = getSelfHeight() 130 | clientState.latestHeight = height 131 | 132 | // save the client state 133 | provableStore.set("clients/{clientMsg.identifier}/clientState", clientState) 134 | } 135 | ``` 136 | 137 | ### Update state on misbehaviour 138 | 139 | Function `updateStateOnMisbehaviour` is unsupported by the loopback client and performs a no-op. 140 | 141 | ```typescript 142 | function updateStateOnMisbehaviour(clientMsg: clientMessage) { } 143 | ``` 144 | 145 | ### State verification functions 146 | 147 | State verification functions simply need to read state from the local ledger and compare with the bytes stored under the standardized key paths. The loopback client needs read-only access to the **entire IBC store** of the local ledger, and not only to its own client identifier-prefixed store. 148 | 149 | ```typescript 150 | function verifyMembership( 151 | clientState: ClientState, 152 | height: Height, 153 | delayTimePeriod: uint64, 154 | delayBlockPeriod: uint64, 155 | proof: CommitmentProof, 156 | path: CommitmentPath, 157 | value: []byte 158 | ): Error { 159 | // path is prefixed with the store prefix of the commitment proof 160 | // e.g. in ibc-go implementation this is "ibc" 161 | // since verification is done on the IBC store of the local ledger 162 | // the prefix needs to be removed from the path to retrieve the 163 | // correct key in the store 164 | unprefixedPath = removePrefix(getCommitmentPrefix(), path) 165 | 166 | // The complete (not only client identifier-prefixed) store is needed 167 | // to verify that a path has been set to a particular value 168 | if provableStore.get(unprefixedPath) !== value { 169 | return error 170 | } 171 | return nil 172 | } 173 | 174 | function verifyNonMembership( 175 | clientState: ClientState, 176 | height: Height, 177 | delayTimePeriod: uint64, 178 | delayBlockPeriod: uint64, 179 | proof: CommitmentProof, 180 | path: CommitmentPath 181 | ): Error { 182 | // path is prefixed with the store prefix of the commitment proof 183 | // e.g. in ibc-go implementation this is "ibc" 184 | // since verification is done on the IBC store of the local ledger 185 | // the prefix needs to be removed from the path to retrieve the 186 | // correct key in the store 187 | unprefixedPath = removePrefix(getCommitmentPrefix(), path) 188 | 189 | // The complete (not only client identifier-prefixed) store is needed 190 | // to verify that a path has not been set to a particular value 191 | if provableStore.get(unprefixedPath) !== nil { 192 | return error 193 | } 194 | return nil 195 | } 196 | ``` 197 | 198 | ### Properties & Invariants 199 | 200 | Semantics are as if this were a remote client of the local ledger. 201 | 202 | ## Backwards Compatibility 203 | 204 | Not applicable. 205 | 206 | ## Forwards Compatibility 207 | 208 | Not applicable. Alterations to the client algorithm will require a new client standard. 209 | 210 | ## Example Implementations 211 | 212 | - Implementation of ICS 09 in Go can be found in [ibc-go repository](https://github.com/cosmos/ibc-go). 213 | 214 | ## History 215 | 216 | January 17, 2020 - Initial version 217 | 218 | March 2, 2023 - Update after ICS 02 refactor and addition of sentinel objects. 219 | 220 | ## Copyright 221 | 222 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 223 | -------------------------------------------------------------------------------- /spec/core/ics-003-connection-semantics/client-validation-removal.md: -------------------------------------------------------------------------------- 1 | # Client Validation Removal 2 | 3 | The IBC protocol is no longer requiring that chains verify that the underlying counterparty client of a connection is a valid client of their consensus protocol. In order to understand the motivation for these changes, this document will describe why the validation existed in the first place, what challenges they introduced, and what the consequences are of removing them. 4 | 5 | ## Client Validation Motivation 6 | 7 | Client validation was initially included in the connection handshake handlers in order to ensure that both chains were talking to the correct counterparty, i.e. the connection was correctly configured such that both chains are talking to each other. This ensures that when a channel is built on top of that connection, and a packet is sent over that channel, only a single chain is capable of receiving the packet. 8 | 9 | IBC relies on locally unique identifiers for each chain's client, connection and channel identifiers. Thus, the identifiers, connection struct and channel struct are not unique to a chain. The only thing that uniquely identifies a chain is its consensus. Specifically, the tuple of `(height, chainID, validatorSet)` is unique for an honest chain. This tuple is committed to by the headers a validator set produces. Thus, if a chain A has a client with a consensus state that is committing to a tuple uniquely identifying chain B; then chain B can be sure that the client on chain A is a client of itself. Thus any connection on chain A built on top of that client is meant to connect to chain B. 10 | 11 | The IBC connection handshake used this fact to ensure that the connection handshake only completes for the chains that are directly pointing to one another. If a relayer misconfigured the connection handshake by choosing the wrong counterparty client identifer on `ConnOpenInit`, the handshake would fail on `ConnOpenAck` when the counterparty client is proven to not be a valid client of the initializing chain. Thus, misconfigured connection attempts are blocked from completing. When a connection moves to `OPEN`, we can be sure that only the two chains in question are connected to each other. 12 | 13 | Without this check, it is possible in very unlucky circumstances to have two chains that are validly connected to each other and also have misconfigured third-party chains that believe they are connected to a chain that is not connected back to them. For an example of this situation, see the attached [diagram](./client-validation-removal.png). In this case, the validly connected chains will have communication between them that follows IBC's correctness and integrity properties. However, the chains that are misconfigured may misinterpret messages sent to other chains as messages intended for them. In this case, the only connection ends that are affected are the misconfigured connection ends that do not correlate to a valid connection end on the intended counterparty. In order for this situation to arise, there would need to not only be relayer error, but also a coincidence in identifiers and handshake message timing. Thus, this is an unlikely situation to arise in practice and the only effect is invalid message processing on misconfigured connections and channel ends. 14 | 15 | ## Client Validation Problems 16 | 17 | While it is beneficial that misconfigured connection attempts are blocked from completing, the client validation in the connection handshake introduced a lot of problems for the upgradability and flexibility of the protocol. 18 | 19 | - Not all chains have the ability to introspect their own consensus, specifically their own consensus history which is required to validate a counterparty's previous consensus state. 20 | - Explicit verification of a counterparty client state and consensus state makes adding new implementions of the same consensus difficult since the validation of any new client implementations must be supported on the counterparty you want to use it with. Thus, the structure of `ClientState` and `ConsensusState` is very difficult to change without interchain coordination. 21 | - Similarly, the proofs rely on ICS24 paths for the `ClientState` and `ConsensusState`. Thus, changing the key paths to a more efficient representation is very difficult without interchain coordination. 22 | 23 | ## Social Consensus 24 | 25 | As mentioned above, the client validation in the connection handshake prevents the creation of `OPEN` misconfigured connections and channels. However, it does not prevent the creation of `OPEN` connections and channels that are opened to malicious chains. The way IBC handles these situations is to rely on social consensus. This can be in the form of explicit social consensus, i.e. governance approved clients, connections and channels; or implicit social consensus where IBC messages are permissionless but there exists an out-of-band consensus on which connection ID is the canonical connection that all users will use to communicate to an external chain. This out-of-band consensus can be reflected in chain registries and front ends that are reflected to end users to prevent them from unintentionally using the wrong channel. 26 | 27 | Thus, social consensus is already a key element of how IBC functions for end users. We can extend the use of this pre-existing social consensus to also prevent users from sending on misconfigured connection ends rather than enforcing validation in the protocol. By removing the validation, we vastly simplify the connection handshake protocol: removing two proof verifications in both `ConnOpenTry` and `ConnOpenAck`. Ledgers no longer need to track their own consensus in order to explicitly validate a counterparty's client. This gives much more freedom and flexibility to how clients are implemented and written into state. 28 | 29 | While removing client validation in the connection handshake does open the slight possibility of misconfigured but still usable channels, social consensus will be relied on going forward to ensure these misconfigured channels do not get usage. 30 | -------------------------------------------------------------------------------- /spec/core/ics-003-connection-semantics/client-validation-removal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/core/ics-003-connection-semantics/client-validation-removal.png -------------------------------------------------------------------------------- /spec/core/ics-003-connection-semantics/state.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:8d40cd540573c73768864743928f9d585bf8323b25482a3c751d3824b60fae26 3 | size 128671 4 | -------------------------------------------------------------------------------- /spec/core/ics-004-channel-and-packet-semantics/channel-state-machine.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:360ad503d12860b79a76315f571f3ec10f58944ea45dc8f01a90de59e11ed4ed 3 | size 183242 4 | -------------------------------------------------------------------------------- /spec/core/ics-004-channel-and-packet-semantics/channel-upgrade-flow.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:91d89716457fab0dfc4ee0eec09ab2fa107b8bb88fe4f2a65c86cbb79f4f84a1 3 | size 188799 4 | -------------------------------------------------------------------------------- /spec/core/ics-004-channel-and-packet-semantics/dataflow.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:463dfae8fc1533fe969990ba92aab977b62189fa8e5b078a13422c98aadcd917 3 | size 85401 4 | -------------------------------------------------------------------------------- /spec/core/ics-004-channel-and-packet-semantics/packet-state-machine.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:066aedd11b7d9ada5d2e74a18f132433225ff043d254e7290ef224a567d6894d 3 | size 157623 4 | -------------------------------------------------------------------------------- /spec/core/ics-004-channel-and-packet-semantics/packet-transit.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:39ea1bcd0fab59b52edb8ff4521592b9443919bcdac10e2a03a4ed73b8b3f018 3 | size 4702772 4 | -------------------------------------------------------------------------------- /spec/core/ics-005-port-allocation/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 5 3 | title: Port Allocation 4 | stage: Draft 5 | requires: 24 6 | required-by: 4 7 | category: IBC/TAO 8 | kind: interface 9 | version compatibility: ibc-go v7.0.0 10 | author: Christopher Goes 11 | created: 2019-06-20 12 | modified: 2019-08-25 13 | --- 14 | 15 | ## Synopsis 16 | 17 | This standard specifies the port allocation system by which modules can bind to uniquely named ports allocated by the IBC handler. 18 | Ports can then be used to open channels and can be transferred or later released by the module which originally bound to them. 19 | 20 | ### Motivation 21 | 22 | The interblockchain communication protocol is designed to facilitate module-to-module traffic, where modules are independent, possibly mutually distrusted, self-contained 23 | elements of code executing on sovereign ledgers. In order to provide the desired end-to-end semantics, the IBC handler must permission channels to particular modules. 24 | This specification defines the *port allocation and ownership* system which realises that model. 25 | 26 | Conventions may emerge as to what kind of module logic is bound to a particular port name, such as "bank" for fungible token handling or "staking" for interchain collateralisation. 27 | This is analogous to port 80's common use for HTTP servers — the protocol cannot enforce that particular module logic is actually bound to conventional ports, so 28 | users must check that themselves. Ephemeral ports with pseudorandom identifiers may be created for temporary protocol handling. 29 | 30 | Modules may bind to multiple ports and connect to multiple ports bound to by another module on a separate machine. Any number of (uniquely identified) channels can utilise a single 31 | port simultaneously. Channels are end-to-end between two ports, each of which must have been previously bound to by a module, which will then control that end of the channel. 32 | 33 | Optionally, the host state machine can elect to expose port binding only to a specially-permissioned module manager, 34 | by generating a capability key specifically for the ability to bind ports. The module manager 35 | can then control which ports modules can bind to with a custom rule-set, and transfer ports to modules only when it 36 | has validated the port name & module. This role can be played by the routing module (see [ICS 26](../ics-026-routing-module)). 37 | 38 | ### Definitions 39 | 40 | `Identifier`, `get`, `set`, and `delete` are defined as in [ICS 24](../ics-024-host-requirements). 41 | 42 | A *port* is a particular kind of identifier which is used to permission channel opening and usage to modules. 43 | 44 | A *module* is a sub-component of the host state machine independent of the IBC handler. Examples include Ethereum smart contracts and Cosmos SDK & Substrate modules. 45 | The IBC specification makes no assumptions of module functionality other than the ability of the host state machine to use object-capability or source authentication to permission ports to modules. 46 | 47 | ### Desired Properties 48 | 49 | - Once a module has bound to a port, no other modules can use that port until the module releases it 50 | - A module can, on its option, release a port or transfer it to another module 51 | - A single module can bind to multiple ports at once 52 | - Ports are allocated first-come first-serve, and "reserved" ports for known modules can be bound when the chain is first started 53 | 54 | As a helpful comparison, the following analogies to TCP are roughly accurate: 55 | 56 | | IBC Concept | TCP/IP Concept | Differences | 57 | | ----------------------- | ------------------------- | --------------------------------------------------------------------- | 58 | | IBC | TCP | Many, see the architecture documents describing IBC | 59 | | Port (e.g. "bank") | Port (e.g. 80) | No low-number reserved ports, ports are strings | 60 | | Module (e.g. "bank") | Application (e.g. Nginx) | Application-specific | 61 | | Client | - | No direct analogy, a bit like L2 routing and a bit like TLS | 62 | | Connection | - | No direct analogy, folded into connections in TCP | 63 | | Channel | Connection | Any number of channels can be opened to or from a port simultaneously | 64 | 65 | ## Technical Specification 66 | 67 | ### Data Structures 68 | 69 | The host state machine MUST support either object-capability reference or source authentication for modules. 70 | 71 | In the former object-capability case, the IBC handler must have the ability to generate *object-capabilities*, unique, opaque references 72 | which can be passed to a module and will not be duplicable by other modules. Two examples are store keys as used in the Cosmos SDK ([reference](https://github.com/cosmos/cosmos-sdk/blob/97eac176a5d533838333f7212cbbd79beb0754bc/store/types/store.go#L275)) 73 | and object references as used in Agoric's Javascript runtime ([reference](https://github.com/Agoric/SwingSet)). 74 | 75 | ```typescript 76 | type CapabilityKey object 77 | ``` 78 | 79 | `newCapability` must take a name and generate a unique capability key, such that the name is locally mapped to the capability key and can be used with `getCapability` later. 80 | 81 | ```typescript 82 | function newCapability(name: string): CapabilityKey { 83 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 84 | } 85 | ``` 86 | 87 | `authenticateCapability` must take a name & a capability and check whether the name is locally mapped to the provided capability. The name can be untrusted user input. 88 | 89 | ```typescript 90 | function authenticateCapability(name: string, capability: CapabilityKey): bool { 91 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 92 | } 93 | ``` 94 | 95 | `claimCapability` must take a name & a capability (provided by another module) and locally map the name to the capability, "claiming" it for future usage. 96 | 97 | ```typescript 98 | function claimCapability(name: string, capability: CapabilityKey) { 99 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 100 | } 101 | ``` 102 | 103 | `getCapability` must allow a module to lookup a capability which it has previously created or claimed by name. 104 | 105 | ```typescript 106 | function getCapability(name: string): CapabilityKey { 107 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 108 | } 109 | ``` 110 | 111 | `releaseCapability` must allow a module to release a capability which it owns. 112 | 113 | ```typescript 114 | function releaseCapability(capability: CapabilityKey) { 115 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 116 | } 117 | ``` 118 | 119 | In the latter source authentication case, the IBC handler must have the ability to securely read the *source identifier* of the calling module, 120 | a unique string for each module in the host state machine, which cannot be altered by the module or faked by another module. 121 | An example is smart contract addresses as used by Ethereum ([reference](https://ethereum.github.io/yellowpaper/paper.pdf)). 122 | 123 | ```typescript 124 | type SourceIdentifier string 125 | ``` 126 | 127 | ```typescript 128 | function callingModuleIdentifier(): SourceIdentifier { 129 | // provided by host state machine, e.g. contract address in Ethereum 130 | } 131 | ``` 132 | 133 | `newCapability`, `authenticateCapability`, `claimCapability`, `getCapability`, and `releaseCapability` are then implemented as follows: 134 | 135 | ```typescript 136 | function newCapability(name: string): CapabilityKey { 137 | return callingModuleIdentifier() 138 | } 139 | ``` 140 | 141 | ```typescript 142 | function authenticateCapability(name: string, capability: CapabilityKey) { 143 | return callingModuleIdentifier() === name 144 | } 145 | ``` 146 | 147 | ```typescript 148 | function claimCapability(name: string, capability: CapabilityKey) { 149 | // no-op 150 | } 151 | ``` 152 | 153 | ```typescript 154 | function getCapability(name: string): CapabilityKey { 155 | // not actually used 156 | return nil 157 | } 158 | ``` 159 | 160 | ```typescript 161 | function releaseCapability(capability: CapabilityKey) { 162 | // no-op 163 | } 164 | ``` 165 | 166 | #### Store paths 167 | 168 | `portPath` takes an `Identifier` and returns the store path under which the object-capability reference or owner module identifier associated with a port should be stored. 169 | 170 | ```typescript 171 | function portPath(id: Identifier): Path { 172 | return "ports/{id}" 173 | } 174 | ``` 175 | 176 | ### Sub-protocols 177 | 178 | #### Identifier validation 179 | 180 | Owner module identifier for ports are stored under a unique `Identifier` prefix. 181 | The validation function `validatePortIdentifier` MAY be provided. 182 | 183 | ```typescript 184 | type validatePortIdentifier = (id: Identifier) => boolean 185 | ``` 186 | 187 | If not provided, the default `validatePortIdentifier` function will always return `true`. 188 | 189 | #### Binding to a port 190 | 191 | The IBC handler MUST implement `bindPort`. `bindPort` binds to an unallocated port, failing if the port has already been allocated. 192 | 193 | If the host state machine does not implement a special module manager to control port allocation, `bindPort` SHOULD be available to all modules. If it does, `bindPort` SHOULD only be callable by the module manager. 194 | 195 | ```typescript 196 | function bindPort(id: Identifier): CapabilityKey { 197 | abortTransactionUnless(validatePortIdentifier(id)) 198 | abortTransactionUnless(getCapability(portPath(id)) === null) 199 | capability = newCapability(portPath(id)) 200 | return capability 201 | } 202 | ``` 203 | 204 | #### Transferring ownership of a port 205 | 206 | If the host state machine supports object-capabilities, no additional protocol is necessary, since the port reference is a bearer capability. 207 | 208 | #### Releasing a port 209 | 210 | The IBC handler MUST implement the `releasePort` function, which allows a module to release a port such that other modules may then bind to it. 211 | 212 | `releasePort` SHOULD be available to all modules. 213 | 214 | > Warning: releasing a port will allow other modules to bind to that port and possibly intercept incoming channel opening handshakes. Modules should release ports only when doing so is safe. 215 | 216 | ```typescript 217 | function releasePort(id: Identifier, capability: CapabilityKey) { 218 | abortTransactionUnless(authenticateCapability(portPath(id), capability)) 219 | releaseCapability(capability) 220 | } 221 | ``` 222 | 223 | ### Properties & Invariants 224 | 225 | - By default, port identifiers are first-come-first-serve: once a module has bound to a port, only that module can utilise the port until the module transfers or releases it. A module manager can implement custom logic which overrides this. 226 | 227 | ## Backwards Compatibility 228 | 229 | Not applicable. 230 | 231 | ## Forwards Compatibility 232 | 233 | Port binding is not a wire protocol, so interfaces can change independently on separate chains as long as the ownership semantics are unaffected. 234 | 235 | ## Example Implementations 236 | 237 | - Implementation of ICS 05 in Go can be found in [ibc-go repository](https://github.com/cosmos/ibc-go). 238 | - Implementation of ICS 05 in Rust can be found in [ibc-rs repository](https://github.com/cosmos/ibc-rs). 239 | 240 | ## History 241 | 242 | Jun 29, 2019 - Initial draft 243 | 244 | ## Copyright 245 | 246 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 247 | -------------------------------------------------------------------------------- /spec/core/ics-025-handler-interface/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 25 3 | title: Handler Interface 4 | stage: draft 5 | category: IBC/TAO 6 | kind: instantiation 7 | requires: 2, 3, 4, 23, 24 8 | version compatibility: ibc-go v7.0.0 9 | author: Christopher Goes 10 | created: 2019-04-23 11 | modified: 2019-08-25 12 | --- 13 | 14 | ## Synopsis 15 | 16 | This document describes the interface exposed by the standard IBC implementation (referred to as the IBC handler) to modules within the same state machine, and the implementation of that interface by the IBC handler. 17 | 18 | ### Motivation 19 | 20 | IBC is an inter-module communication protocol, designed to facilitate reliable, authenticated message passing between modules on separate blockchains. Modules should be able to reason about the interface they interact with and the requirements they must adhere to in order to utilise the interface safely. 21 | 22 | ### Definitions 23 | 24 | Associated definitions are as defined in referenced prior standards (where the functions are defined), where appropriate. 25 | 26 | ### Desired Properties 27 | 28 | - Creation of clients, connections, and channels should be as permissionless as possible. 29 | - The module set should be dynamic: chains should be able to add and destroy modules, which can themselves bind to and unbind from ports, at will with a persistent IBC handler. 30 | - Modules should be able to write their own more complex abstractions on top of IBC to provide additional semantics or guarantees. 31 | 32 | ## Technical Specification 33 | 34 | > Note: If the host state machine is utilising object capability authentication (see [ICS 005](../ics-005-port-allocation)), all functions utilising ports take an additional capability key parameter. 35 | 36 | ### Client lifecycle management 37 | 38 | By default, clients are unowned: any module may create a new client, query any existing client, update any existing client, and delete any existing client not in use. 39 | 40 | The handler interface exposes `createClient`, `updateClient`, `queryConsensusState`, `queryClientState`, and `submitMisbehaviourToClient` as defined in [ICS 2](../ics-002-client-semantics). 41 | 42 | ### Connection lifecycle management 43 | 44 | The handler interface exposes `connOpenInit`, `connOpenTry`, `connOpenAck`, `connOpenConfirm`, and `queryConnection`, as defined in [ICS 3](../ics-003-connection-semantics). 45 | 46 | The default IBC routing module SHALL allow external calls to `connOpenTry`, `connOpenAck`, and `connOpenConfirm`. 47 | 48 | ### Channel lifecycle management 49 | 50 | By default, channels are owned by the creating port, meaning only the module bound to that port is allowed to inspect, close, or send on the channel. A module can create any number of channels utilising the same port. 51 | 52 | The handler interface exposes `chanOpenInit`, `chanOpenTry`, `chanOpenAck`, `chanOpenConfirm`, `chanCloseInit`, `chanCloseConfirm`, and `queryChannel`, as defined in [ICS 4](../ics-004-channel-and-packet-semantics). 53 | 54 | The default IBC routing module SHALL allow external calls to `chanOpenTry`, `chanOpenAck`, `chanOpenConfirm`, and `chanCloseConfirm`. 55 | 56 | ### Packet relay 57 | 58 | Packets are permissioned by channel (only a port which owns a channel can send or receive on it). 59 | 60 | The handler interface exposes `sendPacket`, `recvPacket`, `acknowledgePacket`, `timeoutPacket`, and `timeoutOnClose` as defined in [ICS 4](../ics-004-channel-and-packet-semantics). 61 | 62 | The default IBC routing module SHALL allow external calls to `sendPacket`, `recvPacket`, `acknowledgePacket`, `timeoutPacket`, and `timeoutOnClose`. 63 | 64 | ### Properties & Invariants 65 | 66 | The IBC handler module interface as defined here inherits properties of functions as defined in their associated specifications. 67 | 68 | ## Backwards Compatibility 69 | 70 | Not applicable. 71 | 72 | ## Forwards Compatibility 73 | 74 | This interface MAY change when implemented on new chains (or upgrades to an existing chain) as long as the semantics remain the same. 75 | 76 | ## Example Implementations 77 | 78 | Coming soon. 79 | 80 | ## History 81 | 82 | Jun 9, 2019 - Draft written 83 | 84 | Aug 24, 2019 - Revisions, cleanup 85 | 86 | ## Copyright 87 | 88 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 89 | -------------------------------------------------------------------------------- /spec/core/ics-026-routing-module/UPGRADES.md: -------------------------------------------------------------------------------- 1 | # Application Upgrade Callbacks 2 | 3 | ## Synopsis 4 | 5 | This standard document specifies the interfaces and state machine logic that IBC applications must implement in order to enable existing channels to upgrade their applications after the initial channel handshake. 6 | 7 | ### Motivation 8 | 9 | As new features get added to IBC applications, chains may wish to take advantage of new application features without abandoning the accumulated state and network effect(s) of an already existing channel. The upgrade protocol proposed would allow applications to renegotiate an existing channel to take advantage of new features without having to create a new channel, thus preserving all existing application state while upgrading to new application logic. 10 | 11 | ### Desired Properties 12 | 13 | - Both applications MUST agree to the renegotiated application parameters. 14 | - Application state and logic on both chains SHOULD either be using the old parameters or the new parameters, but MUST NOT be in an in-between state, e.g., it MUST NOT be possible for an application to run v2 logic, while its counterparty is still running v1 logic. 15 | - The application upgrade protocol is atomic, i.e., 16 | - either it is unsuccessful and then the application MUST fall-back to the original application parameters; 17 | - or it is successful and then both applications MUST adopt the new application parameters and the applications must process packet data appropriately. 18 | - The application must be able to maintain several different supported versions such that one channel may be on version `v1` and another channel may be on version `v2` and the application can handle the channel state and logic accordingly depending on the application version for the respective channel. 19 | 20 | The application upgrade protocol MUST NOT modify the channel identifiers. 21 | 22 | ## Technical Specification 23 | 24 | In order to support channel upgrades, the application must implement the following interface: 25 | 26 | ```typescript 27 | interface ModuleUpgradeCallbacks { 28 | onChanUpgradeInit: onChanUpgradeInit, // read-only 29 | onChanUpgradeTry: onChanUpgradeTry, // read-only 30 | onChanUpgradeAck: onChanUpgradeAck, // read-only 31 | onChanUpgradeOpen: onChanUpgradeOpen 32 | } 33 | ``` 34 | 35 | ### **OnChanUpgradeInit** 36 | 37 | `onChanUpgradeInit` will verify that the upgrade parameters 38 | are valid and perform any custom `UpgradeInit` logic. 39 | It may return an error if the chosen parameters are invalid 40 | in which case the upgrade handshake is aborted. 41 | The callback is provided the new upgrade parameters. It may perform the necessary checks to ensure that it can support the new channel parameters. If upgrading the application from the previous parameters to the new parameters is not supported, it must return an error. 42 | 43 | `onChanUpgradeInit` may return a modified version to be stored in the upgrade. This may occur if the application needs to store some metadata in the version string as part of its channel negotiation. 44 | 45 | If an error is returned, then core IBC will abort the handshake. 46 | 47 | `onChanUpgradeInit` MUST NOT write any state changes as this will be done only once the upgrade is completed and confirmed to succeed on both sides 48 | 49 | ```typescript 50 | function onChanUpgradeInit( 51 | portIdentifier: Identifier, 52 | channelIdentifier: Identifier, 53 | proposedOrdering: ChannelOrder, 54 | proposedConnectionHops: [Identifier], 55 | proposedVersion: string) => (version: string, err: Error) { 56 | // defined by the module 57 | } (version: string) 58 | ``` 59 | 60 | ### **OnChanUpgradeTry** 61 | 62 | `onChanUpgradeTry` will verify the upgrade-chosen parameters from the counterparty. 63 | If the upgrade-chosen parameters are unsupported by the application, the callback must return an error to abort the handshake. 64 | The try callback may return a modified version, in case it needs to add some metadata to the version string. 65 | This will be stored as the final proposed version of the upgrade by core IBC. 66 | 67 | `onChanUpgradeTry` MUST NOT write any state changes as this will be done only once the upgrade is completed and confirmed to succeed on both sides. 68 | 69 | ```typescript 70 | function onChanUpgradeTry( 71 | portIdentifier: Identifier, 72 | channelIdentifier: Identifier, 73 | proposedOrdering: ChannelOrder, 74 | proposedConnectionHops: [Identifier], 75 | proposedVersion: string) => (version: string, err: Error) { 76 | // defined by the module 77 | } (version: string) 78 | ``` 79 | 80 | ### **OnChanUpgradeAck** 81 | 82 | `onChanUpgradeAck` will error if the counterparty selected version string 83 | is unsupported. If an error is returned by the callback, core IBC will abort the handshake. 84 | 85 | `onChanUpgradeAck` MUST NOT write any state changes as this will be done only once the upgrade is completed and confirmed to succeed on both sides. 86 | 87 | ```typescript 88 | function onChanUpgradeAck( 89 | portIdentifier: Identifier, 90 | channelIdentifier: Identifier, 91 | counterpartyVersion: string) => Error { 92 | // defined by the module 93 | } 94 | ``` 95 | 96 | ### **OnChanUpgradeOpen** 97 | 98 | `onChanUpgradeOpen` is called after the upgrade is complete and both sides are guaranteed to move to the new channel parameters. Thus, the application may now perform any state migrations necessary to start supporting packet processing according to the new channel parameters. 99 | 100 | ```typescript 101 | function onChanUpgradeOpen( 102 | portIdentifier: Identifier, 103 | channelIdentifier: Identifier) { 104 | // defined by the module 105 | } 106 | ``` 107 | -------------------------------------------------------------------------------- /spec/core/ics-033-multi-hop/proof_generation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/core/ics-033-multi-hop/proof_generation.png -------------------------------------------------------------------------------- /spec/core/ics-033-multi-hop/proof_query.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/core/ics-033-multi-hop/proof_query.png -------------------------------------------------------------------------------- /spec/core/ics-033-multi-hop/proof_query_algorithm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/core/ics-033-multi-hop/proof_query_algorithm.png -------------------------------------------------------------------------------- /spec/core/ics-033-multi-hop/proof_verification.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/core/ics-033-multi-hop/proof_verification.png -------------------------------------------------------------------------------- /spec/core/ics-033-multi-hop/relayer_calc_update_heights.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/core/ics-033-multi-hop/relayer_calc_update_heights.png -------------------------------------------------------------------------------- /spec/core/ics-033-multi-hop/relayer_query_proof_and_submit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cosmos/ibc/b66068167c00d3ad68de91fa64642a19676b7e64/spec/core/ics-033-multi-hop/relayer_query_proof_and_submit.png -------------------------------------------------------------------------------- /spec/ics-001-ics-standard/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 1 3 | title: ICS Specification Standard 4 | stage: draft 5 | category: meta 6 | kind: meta 7 | author: Christopher Goes 8 | created: 2019-02-12 9 | modified: 2019-08-25 10 | --- 11 | 12 | ## What is an ICS? 13 | 14 | An interchain standard (ICS) is a design document describing a particular protocol, 15 | standard, or feature expected to be of use to the Cosmos ecosystem. 16 | An ICS should list the desired properties of the standard, explain the design rationale, and 17 | provide a concise but comprehensive technical specification. The primary ICS author 18 | is responsible for pushing the proposal through the standardisation process, soliciting 19 | input and support from the community, and communicating with relevant stakeholders to 20 | ensure (social) consensus. 21 | 22 | The interchain standardisation process should be the primary vehicle for proposing 23 | ecosystem-wide protocols, changes, and features, and ICS documents should persist after 24 | consensus as a record of design decisions and an information repository for future implementers. 25 | 26 | Interchain standards should *not* be used for proposing changes to a particular blockchain 27 | (such as the Cosmos Hub), specifying implementation particulars (such as language-specific data structures), 28 | or debating governance proposals on existing Cosmos blockchains (although it is possible 29 | that individual blockchains in the Cosmos ecosystem may utilise their governance processes 30 | to approve or reject interchain standards). 31 | 32 | ## Components 33 | 34 | An ICS consists of a header, synopsis, specification, history log, and copyright notice. All top-level sections are required. 35 | References should be included inline as links, or tabulated at the bottom of the section if necessary. 36 | 37 | ### Header 38 | 39 | An ICS header contains metadata relevant to the ICS. 40 | 41 | #### Required fields 42 | 43 | `ics: #` - ICS number (assigned sequentially) 44 | 45 | `title` - ICS title (keep it short & sweet) 46 | 47 | `stage` - Current ICS stage, see [PROCESS.md](../../meta/PROCESS.md) for the list of possible stages. 48 | 49 | See [README.md](../../README.md) for a description of the ICS acceptance stages. 50 | 51 | `category` - ICS category, one of the following: 52 | 53 | - `meta` - A standard about the ICS process. 54 | - `IBC/TAO` - A standard about an inter-blockchain communication system core transport, authentication, and ordering layer protocol. 55 | - `IBC/APP` - A standard about an inter-blockchain communication system application layer protocol. 56 | 57 | `kind` - ICS kind, one of the following: 58 | 59 | - `meta` - A standard about the ICS process. 60 | - `interface` - A standard about the minimal set of interfaces that must be provided and properties that must be fulfilled by a state machine hosting an implementation of the inter-blockchain communication protocol. 61 | - `instantiation` - A standard about concrete implementation details that explains how the standard is realized in pseudocode or software components. 62 | 63 | `author` - ICS author(s) & contact information (in order of preference: email, GitHub handle, Twitter handle, other contact methods likely to elicit response). 64 | The first author is the primary "owner" of the ICS and is responsible for advancing it through the standardisation process. 65 | Subsequent author ordering should be in order of contribution amount. 66 | 67 | `created` - Date ICS was first created (`YYYY-MM-DD`) 68 | 69 | `modified` - Date ICS was last modified (`YYYY-MM-DD`) 70 | 71 | #### Optional fields 72 | 73 | `requires` - Other ICS standards, referenced by number, which are required or depended upon by this standard. 74 | 75 | `required-by` - Other ICS standards, referenced by number, which require or depend upon this standard. 76 | 77 | `replaces` - Another ICS standard replaced or supplanted by this standard, if applicable. 78 | 79 | `replaced-by` - Another ICS standard which replaces or supplants this standard, if applicable. 80 | 81 | `version compatibility` - List of versions of implementations compatible with the ICS standard. 82 | 83 | ### Synopsis 84 | 85 | Following the header, an ICS should include a brief (~200 word) synopsis providing a high-level 86 | description of and rationale for the specification. 87 | 88 | ### Specification 89 | 90 | The specification section is the main component of an ICS, and should contain protocol documentation, design rationale, 91 | required references, and technical details where appropriate. 92 | 93 | #### Sub-components 94 | 95 | The specification may have any or all of the following sub-components, as appropriate to the particular ICS. Included sub-components should be listed in the order specified here. 96 | 97 | - *Motivation* - A rationale for the existence of the proposed feature, or the proposed changes to an existing feature. 98 | - *Definitions* - A list of new terms or concepts utilised in this ICS or required to understand this ICS. Any terms not defined in the top-level "docs" folder must be defined here. 99 | - *Desired Properties* - A list of the desired properties or characteristics of the protocol or feature specified, and expected effects or failures when the properties are violated. 100 | - *Technical Specification* - All technical details of the proposed protocol including syntax, semantics, sub-protocols, data structures, algorithms, and pseudocode as appropriate. 101 | The technical specification should be detailed enough such that separate correct implementations of the specification without knowledge of each other are compatible. 102 | - *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions. 103 | - *Forwards Compatibility* - A discussion of compatibility (or lack thereof) with future possible or expected features or protocol versions. 104 | - *Example Implementations* - Concrete example implementations or descriptions of expected implementations to serve as the primary reference for implementers. 105 | - *Other Implementations* - A list of candidate or finalised implementations (external references, not inline). 106 | 107 | ### History 108 | 109 | An ICS should include a history section, listing any inspiring documents and a plaintext log of significant changes. 110 | 111 | See an example history section [below](#history-1). 112 | 113 | ### Copyright 114 | 115 | An ICS should include a copyright section waiving rights via [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 116 | 117 | ## Formatting 118 | 119 | ### General 120 | 121 | ICS specifications must be written in GitHub-flavoured Markdown. 122 | 123 | For a GitHub-flavoured Markdown cheat sheet, see [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). For a local Markdown renderer, see [here](https://github.com/joeyespo/grip). 124 | 125 | ### Language 126 | 127 | ICS specifications should be written in Simple English, avoiding obscure terminology and unnecessary jargon. For excellent examples of Simple English, please see the [Simple English Wikipedia](https://simple.wikipedia.org/wiki/Main_Page). 128 | 129 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in specifications are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). 130 | 131 | ### Pseudocode 132 | 133 | Pseudocode in specifications should be language-agnostic and formatted in a simple imperative standard, with line numbers, variables, simple conditional blocks, for loops, and 134 | English fragments where necessary to explain further functionality such as scheduling timeouts. LaTeX images should be avoided because they are difficult to review in diff form. 135 | 136 | Pseudocode for structs should be written in simple Typescript, as interfaces. 137 | 138 | Example pseudocode struct: 139 | 140 | ```typescript 141 | interface Connection { 142 | state: ConnectionState 143 | version: Version 144 | counterpartyIdentifier: Identifier 145 | consensusState: ConsensusState 146 | } 147 | ``` 148 | 149 | Pseudocode for algorithms should be written in simple Typescript, as functions. 150 | 151 | Example pseudocode algorithm: 152 | 153 | ```typescript 154 | function startRound(round) { 155 | round_p = round 156 | step_p = PROPOSE 157 | if (proposer(h_p, round_p) === p) { 158 | if (validValue_p !== nil) 159 | proposal = validValue_p 160 | else 161 | proposal = getValue() 162 | broadcast( {PROPOSAL, h_p, round_p, proposal, validRound} ) 163 | } else 164 | schedule(onTimeoutPropose(h_p, round_p), timeoutPropose(round_p)) 165 | } 166 | ``` 167 | 168 | ## History 169 | 170 | This specification was significantly inspired by and derived from Ethereum's [EIP 1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md), which 171 | was in turn derived from Bitcoin's BIP process and Python's PEP process. Antecedent authors are not responsible for any shortcomings of this ICS spec or 172 | the ICS process. Please direct all comments to the ICS repository maintainers. 173 | 174 | Mar 4, 2019 - Initial draft finished and submitted as a PR 175 | 176 | Mar 7, 2019 - Draft merged 177 | 178 | Apr 11, 2019 - Updates to pseudocode formatting, add definitions subsection 179 | 180 | Aug 17, 2019 - Clarifications to categories 181 | 182 | ## Copyright 183 | 184 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 185 | -------------------------------------------------------------------------------- /spec/ics-template.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: (number) 3 | title: (short title) 4 | stage: (current process stage) 5 | category: (ics category) 6 | kind: (ics kind) 7 | author: (primary & additional authors) 8 | created: (creation date) 9 | modified: (modification date) 10 | requires: (optional list of ics numbers) 11 | required-by: (optional list of ics numbers) 12 | implements: (optional list of ics numbers) 13 | version compatibility: (optional list of compatible implementations' releases) 14 | --- 15 | 16 | ## Synopsis 17 | 18 | (high-level description of and rationale for specification) 19 | 20 | ### Motivation 21 | 22 | (rationale for existence of standard) 23 | 24 | ### Definitions 25 | 26 | (definitions of any new terms not defined in common documentation) 27 | 28 | ### Desired Properties 29 | 30 | (desired characteristics / properties of protocol, effects if properties are violated) 31 | 32 | ## Technical Specification 33 | 34 | (main part of standard document - not all subsections are required) 35 | 36 | (detailed technical specification: syntax, semantics, sub-protocols, algorithms, data structures, etc) 37 | 38 | ### Data Structures 39 | 40 | (new data structures, if applicable) 41 | 42 | ### Sub-protocols 43 | 44 | (sub-protocols, if applicable) 45 | 46 | ### Properties & Invariants 47 | 48 | (properties & invariants maintained by the protocols specified, if applicable) 49 | 50 | ## Backwards Compatibility 51 | 52 | (discussion of compatibility or lack thereof with previous standards) 53 | 54 | ## Forwards Compatibility 55 | 56 | (discussion of compatibility or lack thereof with expected future standards) 57 | 58 | ## Example Implementations 59 | 60 | (links to or descriptions of concrete example implementations) 61 | 62 | ## History 63 | 64 | (changelog and notable inspirations / references) 65 | 66 | ## Copyright 67 | 68 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 69 | --------------------------------------------------------------------------------