├── .github ├── CODEOWNERS └── workflows │ └── link-check.yml ├── archive ├── v0_3_1_IBC.pdf ├── papers │ └── 2020-05 │ │ ├── build │ │ └── paper.pdf │ │ ├── README.md │ │ ├── Makefile │ │ ├── src │ │ ├── paper.md │ │ ├── LICENSE │ │ ├── testing-and-deployment.md │ │ ├── metadata.yaml │ │ ├── acknowledgements.md │ │ ├── usage-patterns.md │ │ ├── host-requirements.md │ │ ├── appendix-a.md │ │ ├── connections.md │ │ ├── fungible-token-transfer.md │ │ ├── introduction.md │ │ ├── relayers.md │ │ ├── bibliography.bib │ │ ├── structure.md │ │ ├── appendix-b.md │ │ ├── appendix-c.md │ │ ├── template.latex │ │ ├── clients.md │ │ └── bibliography.csl │ │ └── aspell_dict └── README.md ├── assets └── interchain-standards-image.jpg ├── spec ├── app │ └── ics-028-cross-chain-validation │ │ ├── figures │ │ ├── ccv-init-overview.png │ │ ├── ccv-vsc-overview.png │ │ ├── ccv-evidence-overview.png │ │ ├── ccv-mapping-intuition.png │ │ ├── ccv-unbonding-overview.png │ │ ├── ccv-distribution-overview.png │ │ └── ccv-height-mapping-overview.png │ │ ├── README.md │ │ └── technical_specification.md ├── core │ ├── ics-003-connection-semantics │ │ └── state.png │ ├── ics-004-channel-and-packet-semantics │ │ ├── dataflow.png │ │ ├── packet-transit.png │ │ ├── channel-state-machine.png │ │ └── packet-state-machine.png │ ├── ics-025-handler-interface │ │ └── README.md │ ├── ics-026-routing-module │ │ └── UPGRADES.md │ ├── ics-005-port-allocation │ │ └── README.md │ └── ics-023-vector-commitments │ │ └── README.md ├── ics-template.md ├── client │ └── ics-009-loopback-client │ │ └── README.md └── ics-001-ics-standard │ └── README.md ├── .gitattributes ├── meta ├── STANDARDS_COMMITTEE.md ├── ROADMAP.md ├── CONTRIBUTING.md └── PROCESS.md ├── CHANGELOG.md ├── README.md └── LICENSE /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Default owners for repository 2 | # 2/n quorum required for merge 3 | 4 | * @mpoke @adityasripal @cwgoes @colin-axner -------------------------------------------------------------------------------- /archive/v0_3_1_IBC.pdf: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:472a53104e4d9bc6a8abde8f851c951fab58e3db2bd4ade8c7c057adc42852c3 3 | size 899421 4 | -------------------------------------------------------------------------------- /archive/papers/2020-05/build/paper.pdf: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:b51ddc477e4947303c72a2cd591dcc5a4b438fadf585753c991f6fe29d8bcb03 3 | size 352921 4 | -------------------------------------------------------------------------------- /assets/interchain-standards-image.jpg: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:948d72f8ce9f7758316c8ecd11c8045cf3a4918514b4077e2e37d8f5f4e1f301 3 | size 373917 4 | -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-init-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CoR/ibc/main/spec/app/ics-028-cross-chain-validation/figures/ccv-init-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-vsc-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CoR/ibc/main/spec/app/ics-028-cross-chain-validation/figures/ccv-vsc-overview.png -------------------------------------------------------------------------------- /.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 | -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-evidence-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CoR/ibc/main/spec/app/ics-028-cross-chain-validation/figures/ccv-evidence-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-mapping-intuition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CoR/ibc/main/spec/app/ics-028-cross-chain-validation/figures/ccv-mapping-intuition.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-unbonding-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CoR/ibc/main/spec/app/ics-028-cross-chain-validation/figures/ccv-unbonding-overview.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/app/ics-028-cross-chain-validation/figures/ccv-distribution-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CoR/ibc/main/spec/app/ics-028-cross-chain-validation/figures/ccv-distribution-overview.png -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/figures/ccv-height-mapping-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CoR/ibc/main/spec/app/ics-028-cross-chain-validation/figures/ccv-height-mapping-overview.png -------------------------------------------------------------------------------- /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-transit.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:39ea1bcd0fab59b52edb8ff4521592b9443919bcdac10e2a03a4ed73b8b3f018 3 | size 4702772 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/packet-state-machine.png: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:066aedd11b7d9ada5d2e74a18f132433225ff043d254e7290ef224a567d6894d 3 | size 157623 4 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /.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@v2 8 | - uses: gaurav-nelson/github-action-markdown-link-check@v1 9 | 10 | -------------------------------------------------------------------------------- /meta/STANDARDS_COMMITTEE.md: -------------------------------------------------------------------------------- 1 | ## Standards Committee 2 | 3 | Currently, the core standardisation committee consists of: 4 | - Aditya Sripal (@adityasripal) 5 | - Christopher Goes (@cwgoes) 6 | - Marius Poke (@mpoke) 7 | 8 | A two-of-three quorum is needed to approve pull requests to this repository. 9 | -------------------------------------------------------------------------------- /archive/papers/2020-05/README.md: -------------------------------------------------------------------------------- 1 | Drafting an IBC paper. See [draft](./build/paper.pdf). 2 | 3 | Submission options: 4 | - [CES CfP (May 2020)](https://cryptoeconomicsystems.pubpub.org/spring20-journalcfp) 5 | - Up to 15,000 words 6 | - A4 style, submitted as PDF 7 | - Exclusive submission only 8 | - Remove author names from paper 9 | - Pre-prints OK 10 | - Prior work: 11 | - https://assets.pubpub.org/asuzx3df/11581974880753.pdf 12 | - https://assets.pubpub.org/a7tcrzro/31581340169699.pdf 13 | - https://assets.pubpub.org/g84cchsz/11581340329396.pdf 14 | -------------------------------------------------------------------------------- /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/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 | 63 | 64 | -------------------------------------------------------------------------------- /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/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/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 heterogenous 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/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/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 | -------------------------------------------------------------------------------- /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 | --- 14 | 15 | ## Synopsis 16 | 17 | (high-level description of and rationale for specification) 18 | 19 | ### Motivation 20 | 21 | (rationale for existence of standard) 22 | 23 | ### Definitions 24 | 25 | (definitions of any new terms not defined in common documentation) 26 | 27 | ### Desired Properties 28 | 29 | (desired characteristics / properties of protocol, effects if properties are violated) 30 | 31 | ## Technical Specification 32 | 33 | (main part of standard document - not all subsections are required) 34 | 35 | (detailed technical specification: syntax, semantics, sub-protocols, algorithms, data structures, etc) 36 | 37 | ### Data Structures 38 | 39 | (new data structures, if applicable) 40 | 41 | ### Sub-protocols 42 | 43 | (sub-protocols, if applicable) 44 | 45 | ### Properties & Invariants 46 | 47 | (properties & invariants maintained by the protocols specified, if applicable) 48 | 49 | ## Backwards Compatibility 50 | 51 | (discussion of compatibility or lack thereof with previous standards) 52 | 53 | ## Forwards Compatibility 54 | 55 | (discussion of compatibility or lack thereof with expected future standards) 56 | 57 | ## Example Implementation 58 | 59 | (link to or description of concrete example implementation) 60 | 61 | ## Other Implementations 62 | 63 | (links to or descriptions of other implementations) 64 | 65 | ## History 66 | 67 | (changelog and notable inspirations / references) 68 | 69 | ## Copyright 70 | 71 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 72 | -------------------------------------------------------------------------------- /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-08-03 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 | - [Overview and Basic Concepts](./overview_and_basic_concepts.md) 25 | - [System Model and Properties](./system_model_and_properties.md) 26 | - [Technical Specification: Data Structures and Methods](./technical_specification.md) 27 | - [Data Structures](./data_structures.md) 28 | - [Methods](./methods.md) 29 | 30 | 39 | 40 | ## Example Implementation 41 | 42 | Interchain Security [Go implementation](https://github.com/cosmos/interchain-security). 43 | 44 | 45 | 51 | 52 | ## History 53 | 54 | Jun 27, 2022 - Draft written 55 | 56 | Aug 3, 2022 - Revision of *Bond-Based Consumer Voting Power* property 57 | 58 | ## Copyright 59 | 60 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 61 | -------------------------------------------------------------------------------- /meta/ROADMAP.md: -------------------------------------------------------------------------------- 1 | # Roadmap IBC specs 2 | 3 | _Lastest update: April 6th, 2022_ 4 | 5 | This document endeavours to inform the wider IBC community about plans and priorities for the specification work of IBC. This roadmap should be read as a high-level guide, rather than a commitment to schedules and deliverables. The degree of specificity is inversely proportional to the timeline. We will update this document periodically to reflect the status and plans. 6 | 7 | This roadmap reflects the major activities that the [standards committee](STANDARDS_COMMITTEE.md) is engaged with in the coming quarters. It is, by no means, a thorough reflection of all the specification work that is happening in the broad ecosystem, as many other parties work as well in specs that eventually end up in this repository. 8 | 9 | ## Q2 - 2022 10 | 11 | - Work on general readability improvements and inconsistency fixes in some of the specs ([ICS02](https://github.com/cosmos/ibc/blob/master/spec/core/ics-002-client-semantics/README.md), [ICS06](https://github.com/cosmos/ibc/blob/master/spec/client/ics-006-solo-machine-client/README.md), [ICS07](https://github.com/cosmos/ibc/blob/master/spec/client/ics-007-tendermint-client/README.md)). This is a first step on the long-term plan to make the specs easier to understand to qualified developers. 12 | - The [connection](https://github.com/cosmos/ibc/pull/621) and [channel](https://github.com/cosmos/ibc/pull/677) upgradability specs have been merged, but they need some small fixes. The spec team will also help with the planning of the implementation of channel upgradability in [ibc-go](https://github.com/cosmos/ibc-go). 13 | - Finish writing the spec for [ordered channels that support timeouts](https://github.com/cosmos/ibc/pull/636). 14 | - Start writing the spec to support state trees without absence proofs. 15 | - The implementation of [ICS29](https://github.com/cosmos/ibc/tree/master/spec/app/ics-029-fee-payment) in ibc-go will be finished in Q2 and the spec might need some updates to reflect the latest status. 16 | - Finish [ICS28](https://github.com/cosmos/ibc/pull/666) (Cross-chain validation) spec. 17 | - Review and possibly merge [ICS721](https://github.com/cosmos/ibc/pull/615) spec for NFT transfers. 18 | - Review and possibly merge the spec for [IBC queries](https://github.com/cosmos/ibc/pull/647). 19 | - Write and add to the repository a high level overview of what IBC is. This can be used as an entry point for newcomers to IBC to understand its general principles. -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | 37 | 38 | # Changelog 39 | 40 | ## [Unreleased] 41 | 42 | ### API-Breaking 43 | 44 | - [\#813](https://github.com/cosmos/ibc/pull/813) Breaks up `checkValidityAndUpdateState` into `verifyClientMessage` and `UpdateState` 45 | - [\#813](https://github.com/cosmos/ibc/pull/813) Breaks up `checkMisbehaviourAndUpdateState` into `checkForMisbehaviour` and `UpdateStateOnMisbehaviour` 46 | - [\#813](https://github.com/cosmos/ibc/pull/813) Removes `Header` and `Misbehaviour` interfaces for generic `ClientMessage` interface 47 | - [\#813](https://github.com/cosmos/ibc/pull/813) Removes specific verify functions from ClientState interface in exchange for generic `verifyMembership` and `verifyNonMembership` methods 48 | - [\#813](https://github.com/cosmos/ibc/pull/813) Adds `getTimeoutAtHeight` method to ClientState interface. 49 | 50 | ### Bug Fixes 51 | 52 | - [\#808](https://github.com/cosmos/ibc/pull/808) Fix channel sequence paths in ICS4 53 | 54 | ### Improvements 55 | 56 | - [\#802](https://github.com/cosmos/ibc/pull/802) Move `ClientState` to the `provableStore` and add `ClientState` validation in `connOpenTry` and `connOpenAck` 57 | - [\#803](https://github.com/cosmos/ibc/pull/803) Changed UpgradeState enums to match the opening handshake enum style. 58 | - [\#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 59 | - [\#806](https://github.com/cosmos/ibc/pull/806) Adds previous version to UpgradeInit and UpgradeTry callback arguments 60 | - [\#807](https://github.com/cosmos/ibc/pull/807) Upgrade keys will now prefix the channel path to align with the rest of ICS4 keys 61 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /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 | author: Christopher Goes 9 | created: 2019-04-23 10 | modified: 2019-08-25 11 | --- 12 | 13 | ## Synopsis 14 | 15 | 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. 16 | 17 | ### Motivation 18 | 19 | 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. 20 | 21 | ### Definitions 22 | 23 | Associated definitions are as defined in referenced prior standards (where the functions are defined), where appropriate. 24 | 25 | ### Desired Properties 26 | 27 | - Creation of clients, connections, and channels should be as permissionless as possible. 28 | - 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. 29 | - Modules should be able to write their own more complex abstractions on top of IBC to provide additional semantics or guarantees. 30 | 31 | ## Technical Specification 32 | 33 | > 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. 34 | 35 | ### Client lifecycle management 36 | 37 | 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. 38 | 39 | The handler interface exposes `createClient`, `updateClient`, `queryClientConsensusState`, `queryClient`, and `submitMisbehaviourToClient` as defined in [ICS 2](../ics-002-client-semantics). 40 | 41 | ### Connection lifecycle management 42 | 43 | The handler interface exposes `connOpenInit`, `connOpenTry`, `connOpenAck`, `connOpenConfirm`, and `queryConnection`, as defined in [ICS 3](../ics-003-connection-semantics). 44 | 45 | The default IBC routing module SHALL allow external calls to `connOpenTry`, `connOpenAck`, and `connOpenConfirm`. 46 | 47 | ### Channel lifecycle management 48 | 49 | 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. 50 | 51 | The handler interface exposes `chanOpenInit`, `chanOpenTry`, `chanOpenAck`, `chanOpenConfirm`, `chanCloseInit`, `chanCloseConfirm`, and `queryChannel`, as defined in [ICS 4](../ics-004-channel-and-packet-semantics). 52 | 53 | The default IBC routing module SHALL allow external calls to `chanOpenTry`, `chanOpenAck`, `chanOpenConfirm`, and `chanCloseConfirm`. 54 | 55 | ### Packet relay 56 | 57 | Packets are permissioned by channel (only a port which owns a channel can send or receive on it). 58 | 59 | The handler interface exposes `sendPacket`, `recvPacket`, `acknowledgePacket`, `timeoutPacket`, and `timeoutOnClose` as defined in [ICS 4](../ics-004-channel-and-packet-semantics). 60 | 61 | The default IBC routing module SHALL allow external calls to `sendPacket`, `recvPacket`, `acknowledgePacket`, `timeoutPacket`, and `timeoutOnClose`. 62 | 63 | ### Properties & Invariants 64 | 65 | The IBC handler module interface as defined here inherits properties of functions as defined in their associated specifications. 66 | 67 | ## Backwards Compatibility 68 | 69 | Not applicable. 70 | 71 | ## Forwards Compatibility 72 | 73 | This interface MAY change when implemented on new chains (or upgrades to an existing chain) as long as the semantics remain the same. 74 | 75 | ## Example Implementation 76 | 77 | Coming soon. 78 | 79 | ## Other Implementations 80 | 81 | Coming soon. 82 | 83 | ## History 84 | 85 | Jun 9, 2019 - Draft written 86 | 87 | Aug 24, 2019 - Revisions, cleanup 88 | 89 | ## Copyright 90 | 91 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 92 | -------------------------------------------------------------------------------- /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/rPFPxVJmUZ). 24 | 25 | ## Pull Requests 26 | 27 | To accommodate 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 | - `Approval` through the GH UI means that you understand all the changes proposed in the PR. In addition: 39 | - You must also think through anything which ought to be included but is not. 40 | - You must think through any potential security issues or incentive-compatibility flaws introduced by the changes. 41 | - The changes must be consistent with the other IBC standards, especially the [core IBC standards](../README.md#core). 42 | - The modified standard must be consistent with the description from [ICS 1](../spec/ics-001-ics-standard/README.md). 43 | - If you are only making "surface level" reviews, submit any notes as `Comments` without adding a review. 44 | 45 | ### PR Targeting 46 | 47 | Ensure that you base and target your PR on the `master` branch. 48 | 49 | ### Development Procedure 50 | 51 | - The latest state of development is on `master`. 52 | - Create a development branch either on `github.com/cosmos/ibc` or your fork (using `git remote add fork`). 53 | - To ensure a clear ownership of branches on the ibc repo, branches must be named with the convention `{moniker}/{issue#}-branch-name` 54 | - Before submitting a pull request, begin `git rebase` on top of `master`. 55 | **Since standards cannot be compiled, make sure that the changes in your PR remains consistent with the new commits on the `master` branch**. 56 | 57 | ### Pull Merge Procedure 58 | 59 | - Ensure all github requirements pass. 60 | - Squash and merge pull request. 61 | 62 | -------------------------------------------------------------------------------- /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/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 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # IBC 2 | 3 | ![banner](./assets/interchain-standards-image.jpg) 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 | See [ROADMAP.md](meta/ROADMAP.md) for a public up-to-date version of our roadmap. 14 | 15 | ## What is IBC? 16 | 17 | For a high-level explanation of what IBC is and how it works, please read [this blog post](https://blog.cosmos.network/eli5-what-is-ibc-a212f518715f). 18 | 19 | ## Interchain Standards 20 | 21 | All standards at or past the "Draft" stage are listed here in order of their ICS numbers, sorted by category. 22 | 23 | ### Meta 24 | 25 | | Interchain Standard Number | Standard Title | Stage | 26 | | ---------------------------------------- | -------------------------- | ----- | 27 | | [1](spec/ics-001-ics-standard/README.md) | ICS Specification Standard | N/A | 28 | 29 | ### Core 30 | 31 | | Interchain Standard Number | Standard Title | Stage | Implementations | 32 | | ------------------------------------------------------------- | -------------------------- | --------- | --------------- | 33 | | [2](spec/core/ics-002-client-semantics/README.md) | Client Semantics | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 34 | | [3](spec/core/ics-003-connection-semantics/README.md) | Connection Semantics | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 35 | | [4](spec/core/ics-004-channel-and-packet-semantics/README.md) | Channel & Packet Semantics | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 36 | | [5](spec/core/ics-005-port-allocation/README.md) | Port Allocation | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 37 | | [23](spec/core/ics-023-vector-commitments/README.md) | Vector Commitments | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 38 | | [24](spec/core/ics-024-host-requirements/README.md) | Host Requirements | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 39 | | [25](spec/core/ics-025-handler-interface/README.md) | Handler Interface | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 40 | | [26](spec/core/ics-026-routing-module/README.md) | Routing Module | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | 41 | 42 | ### Client 43 | 44 | | Interchain Standard Number | Standard Title | Stage | Implementations | 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) | 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) | 48 | | [8](spec/client/ics-008-wasm-client/README.md) | Wasm Client | Draft | | 49 | | [9](spec/client/ics-009-loopback-client/README.md) | Loopback Client | Draft | | 50 | | [10](spec/client/ics-010-grandpa-client/README.md) | GRANDPA Client | Draft | | 51 | 52 | ### Relayer 53 | 54 | | Interchain Standard Number | Standard Title | Stage | Implementations | 55 | | ---------------------------------------------------------------- | -------------------------- | ----- | --------------- | 56 | | [18](spec/relayer/ics-018-relayer-algorithms/README.md) | Relayer Algorithms | Finalised | [go-relayer](https://github.com/cosmos/relayer), [rust-relayer](https://github.com/informalsystems/ibc-rs), [ts-relayer](https://github.com/confio/ts-relayer) | 57 | 58 | ### App 59 | 60 | | Interchain Standard Number | Standard Title | Stage | Implementations | 61 | | -------------------------------------------------------- | ----------------------- | ----- | --------------- | 62 | | [20](spec/app/ics-020-fungible-token-transfer/README.md) | Fungible Token Transfer | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/transfer) | 63 | | [27](spec/app/ics-027-interchain-accounts/README.md) | Interchain Accounts | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/27-interchain-accounts) | 64 | | [28](spec/app/ics-028-cross-chain-validation/README.md) | Cross-Chain Validation | Draft | | 65 | | [29](spec/app/ics-029-fee-payment) | General Relayer Incentivisation Mechanism | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/29-fee) | 66 | | [30](spec/app/ics-030-middleware) | IBC Application Middleware | N/A | N/A | 67 | | [31](spec/app/ics-031-crosschain-queries) | Cross-Chain Queries | Draft | N/A | 68 | | [721](spec/app/ics-721-nft-transfer) | Non-Fungible Token Transfer | Candidate | [bianjieai](https://github.com/bianjieai/ibc-go/tree/ics-721-nft-transfer) | 69 | 70 | ## Translations 71 | 72 | The Interchain Standards are also translated into the following languages: 73 | 74 | - [Chinese](https://github.com/octopus-network/ibc-spec-cn) -------------------------------------------------------------------------------- /spec/client/ics-009-loopback-client/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: 2020-01-17 10 | requires: 2 11 | implements: 2 12 | --- 13 | 14 | ## Synopsis 15 | 16 | This specification describes a loop-back client, designed to be used for interaction over the IBC interface with modules present on the same ledger. 17 | 18 | ### Motivation 19 | 20 | Loop-back 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 | ### Desired Properties 27 | 28 | Intended client semantics should be preserved, and loop-back abstractions should be negligible cost. 29 | 30 | ## Technical Specification 31 | 32 | ### Data structures 33 | 34 | No client state, consensus state, headers, or evidence data structures are required for a loopback client. 35 | 36 | ```typescript 37 | type ClientState object 38 | 39 | type ConsensusState object 40 | 41 | type Header object 42 | 43 | type Misbehaviour object 44 | ``` 45 | 46 | ### Client initialisation 47 | 48 | No initialisation is necessary for a loopback client; an empty state is returned. 49 | 50 | ```typescript 51 | function initialise(): ClientState { 52 | return {} 53 | } 54 | ``` 55 | 56 | ### Validity predicate 57 | 58 | No validity checking is necessary in a loopback client; the function should never be called. 59 | 60 | ```typescript 61 | function checkValidityAndUpdateState( 62 | clientState: ClientState, 63 | header: Header) { 64 | assert(false) 65 | } 66 | ``` 67 | 68 | ### Misbehaviour predicate 69 | 70 | No misbehaviour checking is necessary in a loopback client; the function should never be called. 71 | 72 | ```typescript 73 | function checkMisbehaviourAndUpdateState( 74 | clientState: ClientState, 75 | misbehaviour: Misbehaviour) { 76 | return 77 | } 78 | ``` 79 | 80 | ### State verification functions 81 | 82 | Loop-back client state verification functions simply read the local state. Note that they will need (read-only) access to keys outside the client prefix. 83 | 84 | ```typescript 85 | function verifyClientConsensusState( 86 | clientState: ClientState, 87 | height: uint64, 88 | prefix: CommitmentPrefix, 89 | proof: CommitmentProof, 90 | clientIdentifier: Identifier, 91 | consensusState: ConsensusState) { 92 | path = applyPrefix(prefix, "consensusStates/{clientIdentifier}") 93 | assert(get(path) === consensusState) 94 | } 95 | 96 | function verifyConnectionState( 97 | clientState: ClientState, 98 | height: uint64, 99 | prefix: CommitmentPrefix, 100 | proof: CommitmentProof, 101 | connectionIdentifier: Identifier, 102 | connectionEnd: ConnectionEnd) { 103 | path = applyPrefix(prefix, "connection/{connectionIdentifier}") 104 | assert(get(path) === connectionEnd) 105 | } 106 | 107 | function verifyChannelState( 108 | clientState: ClientState, 109 | height: uint64, 110 | prefix: CommitmentPrefix, 111 | proof: CommitmentProof, 112 | portIdentifier: Identifier, 113 | channelIdentifier: Identifier, 114 | channelEnd: ChannelEnd) { 115 | path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}") 116 | assert(get(path) === channelEnd) 117 | } 118 | 119 | function verifyPacketData( 120 | clientState: ClientState, 121 | height: uint64, 122 | prefix: CommitmentPrefix, 123 | proof: CommitmentProof, 124 | portIdentifier: Identifier, 125 | channelIdentifier: Identifier, 126 | sequence: uint64, 127 | data: bytes) { 128 | path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/packets/{sequence}") 129 | assert(get(path) === commit(data)) 130 | } 131 | 132 | function verifyPacketAcknowledgement( 133 | clientState: ClientState, 134 | height: uint64, 135 | prefix: CommitmentPrefix, 136 | proof: CommitmentProof, 137 | portIdentifier: Identifier, 138 | channelIdentifier: Identifier, 139 | sequence: uint64, 140 | acknowledgement: bytes) { 141 | path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/acknowledgements/{sequence}") 142 | assert(get(path) === acknowledgement) 143 | } 144 | 145 | function verifyPacketReceiptAbsence( 146 | clientState: ClientState, 147 | height: uint64, 148 | prefix: CommitmentPrefix, 149 | proof: CommitmentProof, 150 | portIdentifier: Identifier, 151 | channelIdentifier: Identifier, 152 | sequence: uint64) { 153 | path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/receipts/{sequence}") 154 | assert(get(path) === nil) 155 | } 156 | 157 | function verifyNextSequenceRecv( 158 | clientState: ClientState, 159 | height: uint64, 160 | prefix: CommitmentPrefix, 161 | proof: CommitmentProof, 162 | portIdentifier: Identifier, 163 | channelIdentifier: Identifier, 164 | nextSequenceRecv: uint64) { 165 | path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/nextSequenceRecv") 166 | assert(get(path) === nextSequenceRecv) 167 | } 168 | ``` 169 | 170 | ### Properties & Invariants 171 | 172 | Semantics are as if this were a remote client of the local ledger. 173 | 174 | ## Backwards Compatibility 175 | 176 | Not applicable. 177 | 178 | ## Forwards Compatibility 179 | 180 | Not applicable. Alterations to the client algorithm will require a new client standard. 181 | 182 | ## Example Implementation 183 | 184 | Coming soon. 185 | 186 | ## Other Implementations 187 | 188 | None at present. 189 | 190 | ## History 191 | 192 | 2020-01-17 - Initial version 193 | 194 | ## Copyright 195 | 196 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 197 | -------------------------------------------------------------------------------- /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 | 43 | ```typescript 44 | interface FungibleTokenPacketAcknowledgement { 45 | success: boolean 46 | error: Maybe 47 | } 48 | ``` 49 | 50 | \vspace{3mm} 51 | 52 | ### Packet handling semantics 53 | 54 | \vspace{3mm} 55 | 56 | 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. 57 | 58 | - 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. 59 | - 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. 60 | - When a packet times-out, local assets are unescrowed back to the sender or vouchers minted back to the sender appropriately. 61 | - Acknowledgement data is used to handle failures, such as invalid denominations or invalid destination accounts. Returning 62 | an acknowledgement of failure is preferable to aborting the transaction since it more easily enables the sending ledger 63 | to take appropriate action based on the nature of the failure. 64 | 65 | 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. 66 | 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 67 | asset could change the supply outside of the scope of this protocol). 68 | 69 | \vspace{3mm} 70 | 71 | ### Fault containment 72 | 73 | \vspace{3mm} 74 | 75 | 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. 76 | 77 | \vspace{3mm} 78 | 79 | ### Multi-ledger transfer paths 80 | 81 | \vspace{3mm} 82 | 83 | 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. 84 | 85 | 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. 86 | -------------------------------------------------------------------------------- /spec/app/ics-028-cross-chain-validation/technical_specification.md: -------------------------------------------------------------------------------- 1 | 2 | # CCV: Technical Specification 3 | [↑ Back to main document](./README.md) 4 | 5 | 6 | ## Outline 7 | - [Placing CCV within an ABCI Application](#placing-ccv-within-an-abci-application) 8 | - [Implemented Interfaces](#implemented-interfaces) 9 | - [Interfacing Other Modules](#interfacing-other-modules) 10 | - [Data Structures and Methods](#data-structures-and-methods) 11 | 12 | ## Placing CCV within an ABCI Application 13 | [↑ Back to Outline](#outline) 14 | 15 | 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. 16 | 17 | ### Implemented Interfaces 18 | 19 | - 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, 20 | 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)). 21 | In this specification we define the following methods that handle messages that are of particular interest to the CCV protocol: 22 | - `InitGenesis()` -- Called when the chain is first started, on receiving an `InitChain` message from the consensus engine. 23 | This is also where the application can inform the underlying consensus engine of the initial validator set. 24 | - `BeginBlock()` -- Contains logic that is automatically triggered at the beginning of each block. 25 | - `EndBlock()` -- Contains logic that is automatically triggered at the end of each block. 26 | This is also where the application can inform the underlying consensus engine of changes in the validator set. 27 | 28 | - 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 29 | - channel opening handshake, which we describe in the [Initialization](./methods.md#initialization) section; 30 | - channel closing handshake, which we describe in the [Consumer Chain Removal](./methods.md#consumer-chain-removal) section; 31 | - and packet relay, which we describe in the [Packet Relay](./methods.md#packet-relay) section. 32 | 33 | ### Interfacing Other Modules 34 | 35 | - As an ABCI application module, the CCV module interacts with the underlying consensus engine through ABCI: 36 | - On the provider chain, 37 | - it initializes the application (e.g., binds to the expected IBC port) in the `InitGenesis()` method. 38 | - On the consumer chain, 39 | - it initializes the application (e.g., binds to the expected IBC port, creates a client of the provider chain) in the `InitGenesis()` method; 40 | - it provides the validator updates in the `EndBlock()` method. 41 | 42 | - As an IBC module, the CCV module interacts with Core IBC for functionalities regarding 43 | - port allocation ([ICS 5](../../core/ics-005-port-allocation)) via `portKeeper`; 44 | - channels and packet semantics ([ICS 4](../../core/ics-004-channel-and-packet-semantics)) via `channelKeeper`; 45 | - connection semantics ([ICS 3](../../core/ics-003-connection-semantics)) via `connectionKeeper`; 46 | - client semantics ([ICS 2](../../core/ics-002-client-semantics)) via `clientKeeper`. 47 | 48 | - The consumer CCV module interacts with the IBC Token Transfer module ([ICS 20](../ics-020-fungible-token-transfer/README.md)) via `transferKeeper`. 49 | 50 | - For the [Initialization sub-protocol](#initialization), the provider CCV module interacts with a Governance module by handling governance proposals to spawn new consumer chains. 51 | If such proposals pass, then all validators on the provider chain MUST validate the consumer chain at spawn time; 52 | otherwise they get slashed. 53 | For an example of how governance proposals work, take a look at the [Governance module documentation](https://docs.cosmos.network/v0.44/modules/gov/) of Cosmos SDK. 54 | 55 | - The provider CCV module interacts with a Staking module on the provider chain. 56 | For an example of how staking works, take a look at the [Staking module documentation](https://docs.cosmos.network/v0.44/modules/staking/) of Cosmos SDK. 57 | The interaction is defined by the following interface: 58 | ```typescript 59 | interface StakingKeeper { 60 | // get UnbondingPeriod from the provider Staking module 61 | UnbondingTime(): Duration 62 | 63 | // get validator updates from the provider Staking module 64 | GetValidatorUpdates(): [ValidatorUpdate] 65 | 66 | // request the Staking module to put on hold 67 | // the completion of an unbonding operation 68 | PutUnbondingOnHold(id: uint64) 69 | 70 | // notify the Staking module of an unboding operation that 71 | // has matured from the perspective of the consumer chains 72 | UnbondingCanComplete(id: uint64) 73 | } 74 | ``` 75 | 76 | - The provider CCV module interacts with a Slashing module on the provider chain. 77 | For an example of how slashing works, take a look at the [Slashing module documentation](https://docs.cosmos.network/v0.44/modules/slashing/) of Cosmos SDK. 78 | The interaction is defined by the following interface: 79 | ```typescript 80 | interface SlashingKeeper { 81 | // query the Slashing module for the slashing factor, 82 | // which may be different for downtime infractions 83 | GetSlashFactor(downtime: Bool): int64 84 | 85 | // request the Slashing module to slash a validator 86 | Slash(valAddress: string, 87 | infractionHeight: int64, 88 | power: int64, 89 | slashFactor: int64) 90 | 91 | // query the Slashing module for the jailing time, 92 | // which may be different for downtime infractions 93 | GetJailTime(downtime: Bool): int64 94 | 95 | // request the Slashing module to jail a validator until time 96 | JailUntil(valAddress: string, time: uint64) 97 | } 98 | ``` 99 | 100 | - The following hook enables the provider CCV module to register operations to be execute when certain events occur within the provider Staking module: 101 | ```typescript 102 | // invoked by the Staking module after 103 | // initiating an unbonding operation 104 | function AfterUnbondingInitiated(opId: uint64); 105 | ``` 106 | 107 | - The consumer CCV module defines the following hooks that enable other modules to register operations to execute when certain events have occurred within CCV: 108 | ```typescript 109 | // invoked after a new validator is added to the validator set 110 | function AfterCCValidatorBonded(valAddress: string); 111 | 112 | // invoked after a validator is removed from the validator set 113 | function AfterCCValidatorBeginUnbonding(valAddress: string); 114 | ``` 115 | 116 | ## Data Structures and Methods 117 | [↑ Back to Outline](#outline) 118 | 119 | The remainder of this technical specification is split into [Data Structures](./data_structures.md) and [Methods](./methods.md). 120 | 121 | -------------------------------------------------------------------------------- /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/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/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 | -------------------------------------------------------------------------------- /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 the 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 upgradng to new application logic. 10 | 11 | 12 | ### Desired Properties 13 | 14 | - Both applications MUST agree to the renegotiated application parameters. 15 | - 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. 16 | - The application upgrade protocol is atomic, i.e., 17 | - either it is unsuccessful and then the application MUST fall-back to the original application parameters; 18 | - or it is successful and then both applications MUST adopt the new application parameters and the applications must process packet data appropriately. 19 | - 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. 20 | 21 | The application upgrade protocol MUST NOT modify the channel identifiers. 22 | 23 | ## Technical Specification 24 | 25 | In order to support channel upgrades, the application must implement the following interface: 26 | 27 | ```typescript 28 | interface ModuleUpgradeCallbacks { 29 | onChanUpgradeInit: onChanUpgradeInit, 30 | onChanUpgradeTry: onChanUpgradeTry, 31 | onChanUpgradeAck: onChanUpgradeAck, 32 | onChanUpgradeConfirm: onChanUpgradeConfirm, 33 | onChanUpgradeRestore: onChanUpgradeRestore 34 | } 35 | ``` 36 | 37 | #### **OnChanUpgradeInit** 38 | 39 | `onChanUpgradeInit` will verify that the upgrade parameters 40 | are valid and perform any custom `UpgradeInit` logic. 41 | It may return an error if the chosen parameters are invalid 42 | in which case the upgrade handshake is aborted. 43 | The callback is provided both the previous version of the channel and the new proposed version. It may perform the necessary logic and state changes necessary to upgrade the channel from the previous version to the new version. If upgrading the application from the previous version to the new version is not supported, it must return an error. 44 | 45 | If an error is returned, then core IBC will revert any changes made by `onChanUpgradeInit` and abort the handshake. 46 | 47 | `onChanUpgradeInit` is also responsible for making sure that the application is recoverable to its pre-upgrade state. The application may either store any new metadata in separate paths, or store the previous metadata under a different path so it can be restored. 48 | 49 | ```typescript 50 | function onChanUpgradeInit( 51 | order: ChannelOrder, 52 | connectionHops: [Identifier], 53 | portIdentifier: Identifier, 54 | channelIdentifier: Identifier, 55 | counterpartyPortIdentifier: Identifier, 56 | counterpartyChannelIdentifier: Identifier, 57 | version: string, 58 | previousVersion: string) => (version: string, err: Error) { 59 | // defined by the module 60 | } 61 | ``` 62 | 63 | #### **OnChanUpgradeTry** 64 | 65 | `onChanUpgradeTry` will verify the upgrade-chosen parameters and perform custom `TRY` logic. 66 | If the upgrade-chosen parameters are invalid, the callback must return an error to abort the handshake. 67 | If the counterparty-chosen version is not compatible with this modules 68 | supported versions, the callback must return an error to abort the handshake. 69 | If the versions are compatible, the try callback must select the final version 70 | string and return it to core IBC. 71 | If upgrading from the previous version to the final new version is not supported, it must return an error. 72 | `onChanUpgradeTry` may also perform custom initialization logic. 73 | 74 | If an error is returned, then core IBC will revert any changes made by `onChanUpgradeTry` and abort the handshake. 75 | 76 | `onChanUpgradeTry` is also responsible for making sure that the application is recoverable to its pre-upgrade state. The application may either store any new metadata in separate paths, or store the previous metadata under a different path so it can be restored. 77 | 78 | ```typescript 79 | function onChanUpgradeTry( 80 | order: ChannelOrder, 81 | connectionHops: [Identifier], 82 | portIdentifier: Identifier, 83 | channelIdentifier: Identifier, 84 | counterpartyPortIdentifier: Identifier, 85 | counterpartyChannelIdentifier: Identifier, 86 | previousVersion: string, 87 | counterpartyVersion: string) => (version: string, err: Error) { 88 | // defined by the module 89 | } 90 | ``` 91 | 92 | #### **OnChanUpgradeAck** 93 | 94 | `onChanUpgradeAck` will error if the counterparty selected version string 95 | is invalid. If an error is returned by the callback, core IBC will revert any changes made by `onChanUpgradeAck` and abort the handshake. 96 | 97 | The `onChanUpgradeAck` callback may also perform custom ACK logic. 98 | 99 | After `onChanUpgradeAck` returns successfully, the application upgrade is complete on this end so any 100 | auxilliary data stored for the purposes of recovery is no longer needed and may be deleted. 101 | 102 | If the callback returns successfully, the application MUST have its state fully migrated to start processing packet data according to the new application parameters. 103 | 104 | ```typescript 105 | function onChanUpgradeAck( 106 | portIdentifier: Identifier, 107 | channelIdentifier: Identifier, 108 | counterpartyChannelIdentifier: Identifier, 109 | counterpartyVersion: string) { 110 | // defined by the module 111 | } => Error 112 | ``` 113 | 114 | #### **OnChanUpgradeConfirm** 115 | 116 | `onChanUpgradeConfirm` will perform custom CONFIRM logic. It MUST NOT error since the counterparty has already approved the handshake, and transitioned to using the new upgrade parameters. 117 | 118 | After `onChanUpgradeConfirm` returns, the application upgrade is complete so any 119 | auxilliary data stored for the purposes of recovery is no longer needed and may be deleted. 120 | 121 | The application MUST have its state fully migrated to start processing packet data according to the new application parameters by the time the callback returns. 122 | 123 | ```typescript 124 | function onChanUpgradeConfirm( 125 | portIdentifier: Identifier, 126 | channelIdentifier: Identifier) { 127 | // defined by the module 128 | } 129 | ``` 130 | 131 | #### **OnChanUpgradeRestore** 132 | 133 | `onChanUpgradeRestore` will be called on `cancelChannelUpgrade` and `timeoutChannelUpgrade` to restore the application to its pre-upgrade state. 134 | 135 | After the upgrade restore callback is returned, the application must have any application metadata back to its pre-upgrade state. Any temporary metadata stored for the purpose of transitioning to the upgraded state may be deleted. 136 | 137 | The application MUST have its state fully migrated to start processing packet data according to the original application parameters by the time the callback returns. 138 | 139 | ```typescript 140 | function onChanUpgradeRestore( 141 | portIdentifier: Identifier, 142 | channelIdentifier: Identifier) { 143 | // defined by the module 144 | } 145 | ``` -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /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 inter-chain 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 inter-chain 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 | Inter-chain 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 inter-chain 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 | - `meta` - A standard about the ICS process 53 | - `IBC/TAO` - A standard about an inter-blockchain communication system core transport, authentication, and ordering layer protocol. 54 | - `IBC/APP` - A standard about an inter-blockchain communication system application layer protocol. 55 | 56 | `author` - ICS author(s) & contact information (in order of preference: email, GitHub handle, Twitter handle, other contact methods likely to elicit response). 57 | The first author is the primary "owner" of the ICS and is responsible for advancing it through the standardisation process. 58 | Subsequent author ordering should be in order of contribution amount. 59 | 60 | `created` - Date ICS was first created (`YYYY-MM-DD`) 61 | 62 | `modified` - Date ICS was last modified (`YYYY-MM-DD`) 63 | 64 | #### Optional fields 65 | 66 | `requires` - Other ICS standards, referenced by number, which are required or depended upon by this standard. 67 | 68 | `required-by` - Other ICS standards, referenced by number, which require or depend upon this standard. 69 | 70 | `replaces` - Another ICS standard replaced or supplanted by this standard, if applicable. 71 | 72 | `replaced-by` - Another ICS standard which replaces or supplants this standard, if applicable. 73 | 74 | ### Synopsis 75 | 76 | Following the header, an ICS should include a brief (~200 word) synopsis providing a high-level 77 | description of and rationale for the specification. 78 | 79 | ### Specification 80 | 81 | The specification section is the main component of an ICS, and should contain protocol documentation, design rationale, 82 | required references, and technical details where appropriate. 83 | 84 | #### Sub-components 85 | 86 | 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. 87 | 88 | - *Motivation* - A rationale for the existence of the proposed feature, or the proposed changes to an existing feature. 89 | - *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. 90 | - *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. 91 | - *Technical Specification* - All technical details of the proposed protocol including syntax, semantics, sub-protocols, data structures, algorithms, and pseudocode as appropriate. 92 | The technical specification should be detailed enough such that separate correct implementations of the specification without knowledge of each other are compatible. 93 | - *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions. 94 | - *Forwards Compatibility* - A discussion of compatibility (or lack thereof) with future possible or expected features or protocol versions. 95 | - *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers. 96 | - *Other Implementations* - A list of candidate or finalised implementations (external references, not inline). 97 | 98 | ### History 99 | 100 | An ICS should include a history section, listing any inspiring documents and a plaintext log of significant changes. 101 | 102 | See an example history section [below](#history-1). 103 | 104 | ### Copyright 105 | 106 | An ICS should include a copyright section waiving rights via [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 107 | 108 | ## Formatting 109 | 110 | ### General 111 | 112 | ICS specifications must be written in GitHub-flavoured Markdown. 113 | 114 | 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). 115 | 116 | ### Language 117 | 118 | 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). 119 | 120 | 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). 121 | 122 | ### Pseudocode 123 | 124 | Pseudocode in specifications should be language-agnostic and formatted in a simple imperative standard, with line numbers, variables, simple conditional blocks, for loops, and 125 | 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. 126 | 127 | Pseudocode for structs should be written in simple Typescript, as interfaces. 128 | 129 | Example pseudocode struct: 130 | 131 | ```typescript 132 | interface Connection { 133 | state: ConnectionState 134 | version: Version 135 | counterpartyIdentifier: Identifier 136 | consensusState: ConsensusState 137 | } 138 | ``` 139 | 140 | Pseudocode for algorithms should be written in simple Typescript, as functions. 141 | 142 | Example pseudocode algorithm: 143 | 144 | ```typescript 145 | function startRound(round) { 146 | round_p = round 147 | step_p = PROPOSE 148 | if (proposer(h_p, round_p) === p) { 149 | if (validValue_p !== nil) 150 | proposal = validValue_p 151 | else 152 | proposal = getValue() 153 | broadcast( {PROPOSAL, h_p, round_p, proposal, validRound} ) 154 | } else 155 | schedule(onTimeoutPropose(h_p, round_p), timeoutPropose(round_p)) 156 | } 157 | ``` 158 | 159 | ## History 160 | 161 | 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 162 | 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 163 | the ICS process. Please direct all comments to the ICS repository maintainers. 164 | 165 | Mar 4, 2019 - Initial draft finished and submitted as a PR 166 | 167 | Mar 7, 2019 - Draft merged 168 | 169 | Apr 11, 2019 - Updates to pseudocode formatting, add definitions subsection 170 | 171 | Aug 17, 2019 - Clarifications to categories 172 | 173 | ## Copyright 174 | 175 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 176 | -------------------------------------------------------------------------------- /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/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 | -------------------------------------------------------------------------------- /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 | author: Christopher Goes 10 | created: 2019-06-20 11 | modified: 2019-08-25 12 | --- 13 | 14 | ## Synopsis 15 | 16 | This standard specifies the port allocation system by which modules can bind to uniquely named ports allocated by the IBC handler. 17 | Ports can then be used to open channels and can be transferred or later released by the module which originally bound to them. 18 | 19 | ### Motivation 20 | 21 | The interblockchain communication protocol is designed to facilitate module-to-module traffic, where modules are independent, possibly mutually distrusted, self-contained 22 | 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. 23 | This specification defines the *port allocation and ownership* system which realises that model. 24 | 25 | 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. 26 | 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 27 | users must check that themselves. Ephemeral ports with pseudorandom identifiers may be created for temporary protocol handling. 28 | 29 | 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 30 | 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. 31 | 32 | Optionally, the host state machine can elect to expose port binding only to a specially-permissioned module manager, 33 | by generating a capability key specifically for the ability to bind ports. The module manager 34 | can then control which ports modules can bind to with a custom rule-set, and transfer ports to modules only when it 35 | has validated the port name & module. This role can be played by the routing module (see [ICS 26](../ics-026-routing-module)). 36 | 37 | ### Definitions 38 | 39 | `Identifier`, `get`, `set`, and `delete` are defined as in [ICS 24](../ics-024-host-requirements). 40 | 41 | A *port* is a particular kind of identifier which is used to permission channel opening and usage to modules. 42 | 43 | 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. 44 | 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. 45 | 46 | ### Desired Properties 47 | 48 | - Once a module has bound to a port, no other modules can use that port until the module releases it 49 | - A module can, on its option, release a port or transfer it to another module 50 | - A single module can bind to multiple ports at once 51 | - Ports are allocated first-come first-serve, and "reserved" ports for known modules can be bound when the chain is first started 52 | 53 | As a helpful comparison, the following analogies to TCP are roughly accurate: 54 | 55 | | IBC Concept | TCP/IP Concept | Differences | 56 | | ----------------------- | ------------------------- | --------------------------------------------------------------------- | 57 | | IBC | TCP | Many, see the architecture documents describing IBC | 58 | | Port (e.g. "bank") | Port (e.g. 80) | No low-number reserved ports, ports are strings | 59 | | Module (e.g. "bank") | Application (e.g. Nginx) | Application-specific | 60 | | Client | - | No direct analogy, a bit like L2 routing and a bit like TLS | 61 | | Connection | - | No direct analogy, folded into connections in TCP | 62 | | Channel | Connection | Any number of channels can be opened to or from a port simultaneously | 63 | 64 | ## Technical Specification 65 | 66 | ### Data Structures 67 | 68 | The host state machine MUST support either object-capability reference or source authentication for modules. 69 | 70 | In the former object-capability case, the IBC handler must have the ability to generate *object-capabilities*, unique, opaque references 71 | 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)) 72 | and object references as used in Agoric's Javascript runtime ([reference](https://github.com/Agoric/SwingSet)). 73 | 74 | ```typescript 75 | type CapabilityKey object 76 | ``` 77 | 78 | `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. 79 | 80 | ```typescript 81 | function newCapability(name: string): CapabilityKey { 82 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 83 | } 84 | ``` 85 | 86 | `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. 87 | 88 | ```typescript 89 | function authenticateCapability(name: string, capability: CapabilityKey): bool { 90 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 91 | } 92 | ``` 93 | 94 | `claimCapability` must take a name & a capability (provided by another module) and locally map the name to the capability, "claiming" it for future usage. 95 | 96 | ```typescript 97 | function claimCapability(name: string, capability: CapabilityKey) { 98 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 99 | } 100 | ``` 101 | 102 | `getCapability` must allow a module to lookup a capability which it has previously created or claimed by name. 103 | 104 | ```typescript 105 | function getCapability(name: string): CapabilityKey { 106 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 107 | } 108 | ``` 109 | 110 | `releaseCapability` must allow a module to release a capability which it owns. 111 | 112 | ```typescript 113 | function releaseCapability(capability: CapabilityKey) { 114 | // provided by host state machine, e.g. ADR 3 / ScopedCapabilityKeeper in Cosmos SDK 115 | } 116 | ``` 117 | 118 | In the latter source authentication case, the IBC handler must have the ability to securely read the *source identifier* of the calling module, 119 | a unique string for each module in the host state machine, which cannot be altered by the module or faked by another module. 120 | An example is smart contract addresses as used by Ethereum ([reference](https://ethereum.github.io/yellowpaper/paper.pdf)). 121 | 122 | ```typescript 123 | type SourceIdentifier string 124 | ``` 125 | 126 | ```typescript 127 | function callingModuleIdentifier(): SourceIdentifier { 128 | // provided by host state machine, e.g. contract address in Ethereum 129 | } 130 | ``` 131 | 132 | `newCapability`, `authenticateCapability`, `claimCapability`, `getCapability`, and `releaseCapability` are then implemented as follows: 133 | 134 | ```typescript 135 | function newCapability(name: string): CapabilityKey { 136 | return callingModuleIdentifier() 137 | } 138 | ``` 139 | 140 | ```typescript 141 | function authenticateCapability(name: string, capability: CapabilityKey) { 142 | return callingModuleIdentifier() === name 143 | } 144 | ``` 145 | 146 | ```typescript 147 | function claimCapability(name: string, capability: CapabilityKey) { 148 | // no-op 149 | } 150 | ``` 151 | 152 | ```typescript 153 | function getCapability(name: string): CapabilityKey { 154 | // not actually used 155 | return nil 156 | } 157 | ``` 158 | 159 | ```typescript 160 | function releaseCapability(capability: CapabilityKey) { 161 | // no-op 162 | } 163 | ``` 164 | 165 | #### Store paths 166 | 167 | `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. 168 | 169 | ```typescript 170 | function portPath(id: Identifier): Path { 171 | return "ports/{id}" 172 | } 173 | ``` 174 | 175 | ### Sub-protocols 176 | 177 | #### Identifier validation 178 | 179 | Owner module identifier for ports are stored under a unique `Identifier` prefix. 180 | The validation function `validatePortIdentifier` MAY be provided. 181 | 182 | ```typescript 183 | type validatePortIdentifier = (id: Identifier) => boolean 184 | ``` 185 | 186 | If not provided, the default `validatePortIdentifier` function will always return `true`. 187 | 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(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 Implementation 236 | 237 | Coming soon. 238 | 239 | ## Other Implementations 240 | 241 | Coming soon. 242 | 243 | ## History 244 | 245 | Jun 29, 2019 - Initial draft 246 | 247 | ## Copyright 248 | 249 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 250 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /spec/core/ics-023-vector-commitments/README.md: -------------------------------------------------------------------------------- 1 | --- 2 | ics: 23 3 | title: Vector Commitments 4 | stage: draft 5 | required-by: 2, 24 6 | category: IBC/TAO 7 | kind: interface 8 | author: Christopher Goes 9 | created: 2019-04-16 10 | modified: 2019-08-25 11 | --- 12 | 13 | ## Synopsis 14 | 15 | A *vector commitment* is a construction that produces a constant-size, binding commitment to an indexed vector of elements and short membership and/or non-membership proofs for any indices & elements in the vector. 16 | This specification enumerates the functions and properties required of commitment constructions used in the IBC protocol. In particular, commitments utilised in IBC are required to be *positionally binding*: they must be able to prove existence or 17 | nonexistence of values at specific positions (indices). 18 | 19 | ### Motivation 20 | 21 | In order to provide a guarantee of a particular state transition having occurred on one chain which can be verified on another chain, IBC requires an efficient cryptographic construction to prove inclusion or non-inclusion of particular values at particular paths in state. 22 | 23 | ### Definitions 24 | 25 | The *manager* of a vector commitment is the actor with the ability and responsibility to add or remove items from the commitment. Generally this will be the state machine of a blockchain. 26 | 27 | The *prover* is the actor responsible for generating proofs of inclusion or non-inclusion of particular elements. Generally this will be a relayer (see [ICS 18](../../relayer/ics-018-relayer-algorithms)). 28 | 29 | The *verifier* is the actor who checks proofs in order to verify that the manager of the commitment did or did not add a particular element. Generally this will be an IBC handler (module implementing IBC) running on another chain. 30 | 31 | Commitments are instantiated with particular *path* and *value* types, which are assumed to be arbitrary serialisable data. 32 | 33 | A *negligible function* is a function that grows more slowly than the reciprocal of every positive polynomial, as defined [here](https://en.wikipedia.org/wiki/Negligible_function). 34 | 35 | ### Desired Properties 36 | 37 | This document only defines desired properties, not a concrete implementation — see "Properties" below. 38 | 39 | ## Technical Specification 40 | 41 | Below we define a behaviour and an overview of datatypes. For data type definition look at [confio/ics23](https://github.com/confio/ics23/blob/master/proofs.proto) repository. 42 | 43 | 44 | ### Datatypes 45 | 46 | A commitment construction MUST specify the following datatypes, which are otherwise opaque (need not be introspected) but MUST be serialisable: 47 | 48 | #### Commitment State 49 | 50 | A `CommitmentState` is the full state of the commitment, which will be stored by the manager. 51 | 52 | ```typescript 53 | type CommitmentState = object 54 | ``` 55 | 56 | #### Commitment Root 57 | 58 | A `CommitmentRoot` commits to a particular commitment state and should be constant-size. 59 | 60 | In certain commitment constructions with constant-size states, `CommitmentState` and `CommitmentRoot` may be the same type. 61 | 62 | ```typescript 63 | type CommitmentRoot = object 64 | ``` 65 | 66 | #### Commitment Path 67 | 68 | A `CommitmentPath` is the path used to verify commitment proofs, which can be an arbitrary structured object (defined by a commitment type). It must be computed by `applyPrefix` (defined below). 69 | 70 | ```typescript 71 | type CommitmentPath = object 72 | ``` 73 | 74 | #### Prefix 75 | 76 | A `CommitmentPrefix` defines a store prefix of the commitment proof. It is applied to the path before the path is passed to the proof verification functions. 77 | 78 | ```typescript 79 | type CommitmentPrefix = object 80 | ``` 81 | 82 | The function `applyPrefix` constructs a new commitment path from the arguments. It interprets the path argument in the context of the prefix argument. 83 | 84 | For two `(prefix, path)` tuples, `applyPrefix(prefix, path)` MUST return the same key only if the tuple elements are equal. 85 | 86 | `applyPrefix` MUST be implemented per `Path`, as `Path` can have different concrete structures. `applyPrefix` MAY accept multiple `CommitmentPrefix` types. 87 | 88 | The `CommitmentPath` returned by `applyPrefix` does not need to be serialisable (e.g. it might be a list of tree node identifiers), but it does need an equality comparison. 89 | 90 | ```typescript 91 | type applyPrefix = (prefix: CommitmentPrefix, path: Path) => CommitmentPath 92 | ``` 93 | 94 | #### Proof 95 | 96 | A `CommitmentProof` demonstrates membership or non-membership for an element or set of elements, verifiable in conjunction with a known commitment root. Proofs should be succinct. 97 | 98 | ```typescript 99 | type CommitmentProof = object 100 | ``` 101 | 102 | ### Required functions 103 | 104 | A commitment construction MUST provide the following functions, defined over paths as serialisable objects and values as byte arrays: 105 | 106 | ```typescript 107 | type Path = string 108 | 109 | type Value = []byte 110 | ``` 111 | 112 | #### Initialisation 113 | 114 | The `generate` function initialises the state of the commitment from an initial (possibly empty) map of paths to values. 115 | 116 | ```typescript 117 | type generate = (initial: Map) => CommitmentState 118 | ``` 119 | 120 | #### Root calculation 121 | 122 | The `calculateRoot` function calculates a constant-size commitment to the commitment state which can be used to verify proofs. 123 | 124 | ```typescript 125 | type calculateRoot = (state: CommitmentState) => CommitmentRoot 126 | ``` 127 | 128 | #### Adding & removing elements 129 | 130 | The `set` function sets a path to a value in the commitment. 131 | 132 | ```typescript 133 | type set = (state: CommitmentState, path: Path, value: Value) => CommitmentState 134 | ``` 135 | 136 | The `remove` function removes a path and associated value from a commitment. 137 | 138 | ```typescript 139 | type remove = (state: CommitmentState, path: Path) => CommitmentState 140 | ``` 141 | 142 | #### Proof generation 143 | 144 | The `createMembershipProof` function generates a proof that a particular commitment path has been set to a particular value in a commitment. 145 | 146 | ```typescript 147 | type createMembershipProof = (state: CommitmentState, path: CommitmentPath, value: Value) => CommitmentProof 148 | ``` 149 | 150 | The `createNonMembershipProof` function generates a proof that a commitment path has not been set to any value in a commitment. 151 | 152 | ```typescript 153 | type createNonMembershipProof = (state: CommitmentState, path: CommitmentPath) => CommitmentProof 154 | ``` 155 | 156 | #### Proof verification 157 | 158 | The `verifyMembership` function verifies a proof that a path has been set to a particular value in a commitment. 159 | 160 | ```typescript 161 | type verifyMembership = (root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath, value: Value) => boolean 162 | ``` 163 | 164 | The `verifyNonMembership` function verifies a proof that a path has not been set to any value in a commitment. 165 | 166 | ```typescript 167 | type verifyNonMembership = (root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath) => boolean 168 | ``` 169 | 170 | ### Optional functions 171 | 172 | A commitment construction MAY provide the following functions: 173 | 174 | The `batchVerifyMembership` function verifies a proof that many paths have been set to specific values in a commitment. 175 | 176 | ```typescript 177 | type batchVerifyMembership = (root: CommitmentRoot, proof: CommitmentProof, items: Map) => boolean 178 | ``` 179 | 180 | The `batchVerifyNonMembership` function verifies a proof that many paths have not been set to any value in a commitment. 181 | 182 | ```typescript 183 | type batchVerifyNonMembership = (root: CommitmentRoot, proof: CommitmentProof, paths: Set) => boolean 184 | ``` 185 | 186 | If defined, these functions MUST produce the same result as the conjunctive union of `verifyMembership` and `verifyNonMembership` respectively (efficiency may vary): 187 | 188 | ```typescript 189 | batchVerifyMembership(root, proof, items) === 190 | all(items.map((item) => verifyMembership(root, proof, item.path, item.value))) 191 | ``` 192 | 193 | ```typescript 194 | batchVerifyNonMembership(root, proof, items) === 195 | all(items.map((item) => verifyNonMembership(root, proof, item.path))) 196 | ``` 197 | 198 | If batch verification is possible and more efficient than individual verification of one proof per element, a commitment construction SHOULD define batch verification functions. 199 | 200 | ### Properties & Invariants 201 | 202 | Commitments MUST be *complete*, *sound*, and *position binding*. These properties are defined with respect to a security parameter `k`, which MUST be agreed upon by the manager, prover, and verifier (and often will be constant for the commitment algorithm). 203 | 204 | #### Completeness 205 | 206 | Commitment proofs MUST be *complete*: path => value mappings which have been added to the commitment can always be proved to have been included, and paths which have not been included can always be proved to have been excluded, except with probability negligible in `k`. 207 | 208 | For any prefix `prefix` and any path `path` last set to a value `value` in the commitment `acc`, 209 | 210 | ```typescript 211 | root = getRoot(acc) 212 | proof = createMembershipProof(acc, applyPrefix(prefix, path), value) 213 | ``` 214 | 215 | ``` 216 | Probability(verifyMembership(root, proof, applyPrefix(prefix, path), value) === false) negligible in k 217 | ``` 218 | 219 | For any prefix `prefix` and any path `path` not set in the commitment `acc`, for all values of `proof` and all values of `value`, 220 | 221 | ```typescript 222 | root = getRoot(acc) 223 | proof = createNonMembershipProof(acc, applyPrefix(prefix, path)) 224 | ``` 225 | 226 | ``` 227 | Probability(verifyNonMembership(root, proof, applyPrefix(prefix, path)) === false) negligible in k 228 | ``` 229 | 230 | #### Soundness 231 | 232 | Commitment proofs MUST be *sound*: path => value mappings which have not been added to the commitment cannot be proved to have been included, or paths which have been added to the commitment excluded, except with probability negligible in a configurable security parameter `k`. 233 | 234 | For any prefix `prefix` and any path `path` last set to a value `value` in the commitment `acc`, for all values of `proof`, 235 | 236 | ``` 237 | Probability(verifyNonMembership(root, proof, applyPrefix(prefix, path)) === true) negligible in k 238 | ``` 239 | 240 | For any prefix `prefix` and any path `path` not set in the commitment `acc`, for all values of `proof` and all values of `value`, 241 | 242 | ``` 243 | Probability(verifyMembership(root, proof, applyPrefix(prefix, path), value) === true) negligible in k 244 | ``` 245 | 246 | #### Position binding 247 | 248 | Commitment proofs MUST be *position binding*: a given commitment path can only map to one value, and a commitment proof cannot prove that the same path opens to a different value except with probability negligible in k. 249 | 250 | For any prefix `prefix` and any path `path` set in the commitment `acc`, there is one `value` for which: 251 | 252 | ```typescript 253 | root = getRoot(acc) 254 | proof = createMembershipProof(acc, applyPrefix(prefix, path), value) 255 | ``` 256 | 257 | ``` 258 | Probability(verifyMembership(root, proof, applyPrefix(prefix, path), value) === false) negligible in k 259 | ``` 260 | 261 | For all other values `otherValue` where `value !== otherValue`, for all values of `proof`, 262 | 263 | ``` 264 | Probability(verifyMembership(root, proof, applyPrefix(prefix, path), otherValue) === true) negligible in k 265 | ``` 266 | 267 | ## Backwards Compatibility 268 | 269 | Not applicable. 270 | 271 | ## Forwards Compatibility 272 | 273 | Commitment algorithms are expected to be fixed. New algorithms can be introduced by versioning connections and channels. 274 | 275 | ## Example Implementation 276 | 277 | Coming soon. 278 | 279 | ## Other Implementations 280 | 281 | Coming soon. 282 | 283 | ## History 284 | 285 | Security definitions are mostly sourced from these papers (and simplified somewhat): 286 | - [Vector Commitments and their Applications](https://eprint.iacr.org/2011/495.pdf) 287 | - [Commitments with Applications to Anonymity-Preserving Revocation](https://eprint.iacr.org/2017/043.pdf) 288 | - [Batching Techniques for Commitments with Applications to IOPs and Stateless Blockchains](https://eprint.iacr.org/2018/1188.pdf) 289 | 290 | Thanks to Dev Ojha for extensive comments on this specification. 291 | 292 | Apr 25, 2019 - Draft submitted 293 | 294 | ## Copyright 295 | 296 | All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). 297 | -------------------------------------------------------------------------------- /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/bibliography.csl: -------------------------------------------------------------------------------- 1 | 2 | --------------------------------------------------------------------------------