cosmos / ibc

Interchain Standards (ICS) for the Cosmos network & interchain ecosystem.

IBC

Synopsis

This repository is the canonical location for development and documentation of the inter-blockchain communication protocol (IBC).

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).

Contributions are welcome. See CONTRIBUTING.md for contribution guidelines.

What is IBC?

For a high-level explanation of what IBC is and how it works, please read this blog post.

Interchain Standards

All standards at or past the "Draft" stage are listed here in order of their ICS numbers, sorted by category.

Meta

Interchain Standard Number	Standard Title	Stage	Maintainer
1	ICS Specification Standard	N/A	Protocol team

Core Transport

Interchain Standard Number	Standard Title	Stage	Implementations	Maintainer
2	Client Semantics	Candidate	ibc-go, ibc-rs	Protocol team
3	Connection Semantics	Candidate	ibc-go, ibc-rs	Protocol team
4	Channel & Packet Semantics	Candidate	ibc-go, ibc-rs	Protocol team
5	Port Allocation	Candidate	ibc-go	Protocol team
23	Vector Commitments	Candidate	ibc-go, ibc-rs	Protocol team
24	Host Requirements	Candidate	ibc-go, ibc-rs	Protocol team
25	Handler Interface	Candidate	ibc-go, ibc-rs	Protocol team
26	Routing Module	Candidate	ibc-go, ibc-rs	Protocol team
33	Multi-hop Messaging	Candidate	ibc-go	Protocol team

Light Clients

Interchain Standard Number	Standard Title	Stage	Implementations	Maintainer
6	Solo Machine Client	Candidate	ibc-go	Protocol team
7	Tendermint Client	Candidate	ibc-go, ibc-rs	Protocol team
8	Wasm Client	Candidate	ibc-go, ibc-rs	Protocol team / Composable Finance
9	Loopback Client	Draft	ibc-go	Protocol team
10	GRANDPA Client	Draft		Octopus Network

Relayer

Interchain Standard Number	Standard Title	Stage	Implementations	Maintainer
18	Relayer Algorithms	Finalized	go-relayer, rust-relayer, ts-relayer	Protocol team

App

Interchain Standard Number	Version	Standard Title	Stage	Implementations	Maintainer
20	v2	Fungible Token Transfer	Candidate	ibc-go	Protocol team
20	v1	Fungible Token Transfer	Candidate	ibc-go, ibc-rs	Protocol team
27	v1	Interchain Accounts	Candidate	ibc-go	Protocol team
28	v1	Cross-Chain Validation	Candidate	interchain-security	Cosmos Hub team
29	v1	General Relayer Incentivization Mechanism	Candidate	ibc-go	Protocol team
30	v1	IBC Application Middleware	N/A	N/A	Protocol team
31	v1	Cross-Chain Queries	Draft	N/A	Protocol team
32	v1	Interchain Queries	Candidate	async-icq	Strangelove Ventures
100	v1	Interchain Atomic Swap	Candidate	ibcswap	Side Labs
721	v1	Non-Fungible Token Transfer	Candidate	nft-transfer	IRIS Network

Translations

The Interchain Standards are also translated into the following languages:

• Chinese

ibc's Issues

IBC as layered-interchangeable-protocol-stack

I think it will help to conceptualize IBC as a layered protocol stack (similar to the IP in this sense).

Layers:

1. Consensus Primitives (#2)
2. Connection (#3)
3. Channel (#34)
4. Packet (#36)
5. Application (various)

The key insight is that lower layers (lower numbers) have no "knowledge" of higher layers - none of their security properties are dependent on those of higher layers, they rather provide primitives and security properties using which higher layers derive their primitives and security properties.

Furthermore, higher-layer protocols should:

• Only depend on the protocol one layer below them
  For example, channel semantics should not depend on the kind of lite client proof used.
• Explicitly enumerate the primitive set they require from that protocol
  Then it will be easy to instantiate variants of different layers while retaining security guarantees.

This may seem banal but I think it will end up being important that we keep the hierarchy strict.

Figure out best syntactical format for specifications and write meta-protocol

Per suggestion from @milosevic.

Also includes English guidelines ("natural compiler"):

• Define terms before usage
• Move motivation out of "Specification"
• Add top-level architecture document to define basic set of terms

Other notes

• Split handleDatagram into sub-functions (likewise for other functions)
• Keep pseudcode snippets short
• Try CoffeeScript/Golang snippets instead of Markdown
• Define pseudocode keywords in meta-spec
• Include proto3 encoding file
• Include state machine descriptions
• Express IBC as protocol between modules on blockchains
• First include definitions of communications channels
• "Requirements" section can only use previously defined terms
• Subprotocol definitions include concrete message types, processing behavior

Clear technical reports

• Paxos original paper
• TCP specification

Other ideas

• Executable spec for protocol conformance
• Standard / reference testsuite + fuzzer

Try this with ICS 2 / 3.

Include protobuf schemas for datastructure definitions

This will help with concrete understanding.

On protocol & implementation specifications

I think we should separate protocol specifications from implementation specifications.

What makes a spec one or the other?

Protocol specs outline the abstract logic required to implement a protocol, including algorithms, asymptotic complexity, protocol-layer invariants, guarantees, or requirements, and pseudocode descriptions of logic. Protocol specifications should be sufficiently precise for independent implementations of the specification to be compatible.

Example protocol specs:

• Algorithm pseudocode in the Tendermint paper (page 6)
• The signed message spec (except for one Golang struct definition, which should be removed)
• Tendermint versioning spec

Implementation specs describe the particular data structures and functions in a specific language which will be used to implement a previously defined protocol. They may include varying amounts of actual code, but generally concern themselves with logical clarity in the intended implementation language, proper abstraction design, practical efficiency considerations, etc.

Example implementation specs:

• SDK x/bank spec
• SDK x/gov spec

I think we should either reserve the ICS repo for protocol specs, and keep implementation specs in the implementation repositories (e.g. the Cosmos SDK), or at minimum keep implementation specs in a separate folder, so future users interested in implementing the protocol can find language-agnostic high-level documentation.

IBC reference implementation tracking issue

Reference implementations for IBC won't be developed in this repository, but they will be referenced in various ICS standards documents, so I think it makes sense to track them here.

I think we should aim to have two separate, wire-compatible, reference implementations of "minimum viable useful IBC" as defined in #26, including fungible token transfer.

One implementation will be in the Cosmos SDK, in Golang. I think that one should be developed first.

The second implementation is TBD. Possibly, it could be in Javascript as part of Lotion, although I'm a bit skeptical of Javascript's suitability as a reference implementation language. Likely Javascript would be a better choice for prototyping and testing new application-layer additions to IBC. I think one candidate is Rust, which would facilitate usage in Substrate and possibly future SDK/Tendermint incarnations in Rust.

I think we should complete & test both implementations before launching IBC on the Hub.

A public group to discuss all things IBC

I think we might want to have a public place for quick and dirty discussions of IBC proposals, process etc. Some of that already happens in a private Slack channel of Tendermint (i.e. #23 (comment)) which is fine now but not in the future when IBC specs are essential for non-tendermint blockchains.

ICS 11: IBC state optimizations / pruning

Primarily a port of the optimizations section of the original IBC spec.

Will cover:

• Conditions under which packets can be pruned
• Conditions under which channel data can be pruned
• Conditions under which connection data can be pruned
• Other possible state optimizations (storage rent, Merkle root tracking)

ICS ?: Merkle Operators

Merkle operators are [][]byte -> [][]byte functions, which act as generalized proofs. It is annoying to implement each of the implementation-specific Merkle proof for each of the chains, so we can reduce the existing/future implementation specific Merkle proofs into the Merkle operator format and then prove it on the other chains.

The proposed set of Merkle operators(cosmos/iavl#136):

• ConcatOp{prefix, suffix []byte}: concats prefix + input + suffix
• SHA256Op{}: sha256 hashes the input
• PrependLengthOp{}: prepend the input with its length
• ApplyOp{index []int, ops []Operator}: apply ops to the inputs parallelly

IAVLValueOp, IAVLAbsentOp, SimpleValueOp can be reduced into the first three operators with a preprocessing. IAVLRangeOp is not proven to be able to reduce yet, but I'm pretty sure it is possible with ApplyOp(key checking will be a bit tricky).

When a new chain using a new Merkle tree implementation comes into the network, they can simply register how does the new Merkle proof look like. It can be described as a simple regular expression, for example, IAVLValueOps have the format of SHA256 PrependLength Concat SHA256 (PrependLength Concat SHA256)*. So even a chain does not understand IAVLValueOp from its code, the knowledge can be provided from an external actor as a regular expression of Merkle operators, which makes the chain able to learn new proof formats on runtime.

ICS 18: Off-chain relayer algorithm

Partially a port of the original spec.

Will cover:

• Off-chain process relay algorithm
• Permissioning
• Fee payment mechanisms

ICS ?: Multi-hop routing

Datagram type for multi-hop routing and associated semantics, which we need to figure out how to properly abstract from the application layer where possible.

ICS 15: Cosmos Signed Messages

Ported from the spec in the SDK repository.

Suggested changes/alterations to that spec:

• Organize in ICS format
• More clearly describe requirements of hashing algorithm & signing algorithm (and maybe parameterize the specification over them)
• Investigate distinction between custom messages (more easily defined in the SDK than e.g. Ethereum) and signed messages, and what use we expect for each (block explorers? DEXs? validator authentication mechanisms?)
• Include specification for signing structured data using JSON schema
• Include options for domain specification / replay prevention (nonce, block height, timestamp)

ICS 22: Generalized probalistic-finality pegzone

Starting from the design here (unless we have any other prior designs or want to rethink this fundamentally), specify the algorithms, intermediate ledger's state machine, and probabilistic-finality ledger's smart contracts for a peg zone between a fast-finality chain and a probabilistic-finality chain, including specific security proofs for what happens in the case of deep chain re-organizations. Ideally defray some choices about finality thresholds to the end user choosing to send IBC transactions over the pegzone (I am not sure if this is possible).

ICS 2.a: IBC minimum viable Tendermint lite client

Will cover:

• Algorithm & data structures for minimum correct (probably not optimal) IBC lite client
• Encoding specification for proofs

ICS 13: Interchain Address Format

Will cover:

• New address type which is (ChainID, Address) that allows chains directly control an address on another chain

ICS 9: IBC timeouts

Primarily a port of https://github.com/cosmos/cosmos-sdk/tree/develop/docs/spec/ibc.

Will cover:

• IBC timeout semantics & safety
• Relevant IBC packet fields
• Algorithms for dealing with timeouts
• Packet fields used

Review/align with Agoric's VatTP and CapTP

The Agoric team has had a rough analog of IBC for decades. In my understanding, it is split between two layers as follows:

• VatTP - roughly the Tendermint side of IBC (light client authentication)
• CapTP - roughly the Application side of IBC (channels and packets)

We should review these and work towards alignment between them and IBC.

ICS 4: Channel & Packet Semantics

Primarily a port of the original IBC spec.

Will cover:

• Channel semantics
• Required data structures
• Standard encoding formats
• Pseudocode algorithms for packet handling

ICS ?: Relayer Query Endpoints

The chains need to expose endpoints to query packets, headers, evidence, etc., in a standard form for the relayers to connect easily without acknowledging about the internal consensus logic. The relayers should be able to connect to any node which is running a full node of an IBC chain and start relaying packets to another.

Formalize security properties of IBC in proof assistant

I think we should define IBC sufficiently rigorously that important security properties of the protocol can be checked in a proof assistant such as Idris, Coq, or Agda (there are likely other options too).

Some examples of the kinds of properties I think should be formalized:

• Packet replay prevention: given some set of chains correctly following the IBC protocol with arbitrary connections between them, and some correctly generated & authenticated IBC packet, prove that the packet can only be confirmed on one chain.
• Timeout semantics: given an IBC connection between two chains which may not necessarily make progress, prove that a packet is either committed (perhaps along with its receipt) on both chains or that a timeout can be submitted to the source chain.
• Masquerade prevention: given an IBC connection between two chains correctly following the IBC protocol, prove that a third malicious chain cannot masquerade (send packets from) as either of the two connected chains
• Byzantine fault handling: given a Byzantine fault committed by a validator set on one chain connected to a set of other chains, prove that this fault cannot affect chains which are not directly connected to the Byzantine chain (particularly w.r.t. multi-hop packet relay)

Open questions:

• What priority should this have? Should we try to formalize the protocol before implementing it or not?
• Which proof assistant is best (w.r.t. expressivity, ease of on-boarding, similarity to implementation)?
• How can we best provide proofs / primitives on top of which application-level security properties can be formalized?

ICS 16: Interchain collaterization protocol

Specification for simple delegated security over IBC ("slashing over IBC")

Will cover

• Packet types, semantics, encodings
• Provided security properties
• Requirements of validator set
• Required consensus integration

ICS 17: Nonfungible token transfer packet specification

Similar to #9, but for nonfungible (unique) tokens, perhaps with metadata.

LaTeX typesetting of algorithms

I think I have come up with a reasonable way of typesetting LaTeX structure definitions, procedures, and equations and embedding the generated images in Markdown in #32.

The generated images look something like this:

The LaTeX is reasonably easy to write and it makes for much cleaner algorithmic descriptions than are possible in vanilla GitHub Markdown. If others are in agreement, I would like to standardize the resulting LaTeX templates, styles, and Makefile to be used across all interchain standards which require such definitions.

Thoughts?

ICS 24: Host-blockchain state machine requirements & definitions

Requirements

• KV-store-like interface with Get(key) -> Value, Set(key, value)
• Introspection into current RootOfTrust
• Access to consensus height (incrementing counter)
• (possibly) Access to timestamp

Definitions

• Actor - end-user, smart contract, module, maybe more
• submitDatagram function

Some of this will move from ICS 3 (Connection Semantics).

cc @mossid Anything else which should live here?

IBC statement of purpose

Somewhere we should have a document outlining, at a high level, the purpose, design goals, and scope of IBC, and linking to the different subcomponents. This document should be designed to be read by someone who has some background in blockchains but none with Tendermint/Cosmos or IBC.

This isn't a technical specification, so I don't think it should go in this repository. Maybe it should be a page on the Cosmos or Interchain website - the closest kind of document to what I'm envisioning is the What is Cosmos page on the Cosmos Network website (which has a section on IBC, but not a comprehensive breakdown).

ICS ?: Transient Queue

Will cover:

• Requirements for non-persisting queue

ICS 5: IBC packet semantics & handling

Primarily ported from the original IBC spec.

Will cover:

• IBC packet semantics
• Required data structures
• Packet wire encoding

ICS 1: ICS specification standard

Standard organizational structure & typographical format for all ICS specifications.

Investigate bidirectional / unidirectional connections

• Can we construct a bidirectional connection from two unidirectional ones?
• How would the handshake work in that case?
• Will this simplify the protocol design?

ICS 12: IBC Byzantine recovery strategies

Primarily a port of the appendix in the original IBC spec - pretty speculative for now.

Will cover:

• Definitions of Byzantine events
• IBC-layer strategies for recovering from Byzantine events
• Application-layer strategies from recovering from Byzantine events
• Exception cases and recovery methods

ICS 2: IBC consensus verification requirements

Required functions & semantics of the underlying consensus algorithm / blockchain.

• Security assumptions of the underlying consensus

This ICS should be able to specify exactly the properties & functions a consensus algorithm must be able to provide in order to be compatible with the rest of the IBC protocol. Initially, these will be more or less chosen as the properties that Tendermint has - the most restrictive set we can choose while retaining the properties which are necessary for IBC - that way future possible consensus algorithms can determine what they would need to satisfy in order to support IBC.

ICS 19: Standard queue

Partially ported from the original spec.

Explain the expected economics of the network topology

Particularly why one might expect "hubs" (central sinks of trust) to emerge in the network, and what particular purposes they will serve.

ICS 6: IBC connection and channel versioning

Will cover:

• Ecosystem-level versioning protocol considerations
• Connection & channel versioning protocol for protocol changes on an open connection

ICS 21: Cross-chain access control delegation

Application-layer protocol enabling users to delegate control of an account on one chain to an account on another chain, where either an IBC proof-of-signature or an IBC proof-of-key and a separate signature by the proved key are used to authenticate transactions from the delegate-controlled account.

ICS ?: IBC Encoding Scheme

Will Cover:

• Requirements for the encoding schemes to encode packets, metadata, Merkle proofs, and any other IBC related data that has to be transferred between chains
• Initially supported encoding schemes, candidates: amino-binary, proto3, amino-json, abi
• Common wire format language to describe data types(optional)
• Interpreter between common wire format and concrete encoding schemes(optional)

Protocol specification inspiration & best practices

Inspiration

IETF specifications

• RFC 791 - Internet Protocol
• RFC 2818 - HTTP over TLS
• RFC 5246 - The Transport Layer Security Protocol

Cryptography

• Noise Protocol Specification

Blockchain

• Zerocash Paper
• Zcash Protocol Specification

IBC specification development ordering / tracking issue

Next round - specification clarification & VatTP integration, addressing review comments, 1.0.0.

See this milestone.

Post-MVP

• ICS-12: Byzantine recovery - #6
• ICS-14: Root-of-trust upgrade protocol - #11

Application-layer (independent)

• ICS-13: Interchain address format - #22
• ICS-20: Fungible token transfer - #9
• ICS-16: Delegated security - #27
• ICS-17: Nonfungible token transfer - #30

Storage / compute / availability tradeoffs in IBC

How much should we minimize storage at the expense of compute or availability?

There are many cases when we can safely store and prove commitments to values - e.g. roots-of-trust, packets, connection slots, etc. - instead of storing the actual values - but this costs a bit of compute (hash equality checks) and imposes a data availability requirement.

I don't know if the data availability requirement is really a problem, since data in IBC packets doesn't seem like it would need to be stored. Admittedly, this would require a bit more off-chain infrastructure to coordinate between packet submitters and relayers.

Possibly, using commitments instead of values could be useful, if the original data submitter wants only themselves to be able to subsequently prove something on another chain (modulo the usual validator-frontrunning concerns).

It's fairly easy to abstract the protocol over a "commitment" function, which could just be the identity function, for the purpose of safety proofs, so maybe we could make this decision later.

ICS 3: IBC connection lifecycle, protocol negotation handshake

Primarily a port of the connection section of the original IBC spec.

Will cover:

• IBC connection data structure
• Possible states of an IBC connection
• IBC connection management packet handling state machine
• Wire encoding formats for IBC connection management (metadata) packets
• Description of initial datagram ("OPENTRY")
• Description of response datagram ("OPENACK")
• Description of confirmation datagram ("OPENCONFIRM")
• Algorithms for handling all datagrams
• Format for option transmission from opening chain to destination chain

ICS 10: IBC chain naming convention

Will cover:

• IBC naming system requirements
• Suggested naming convention(s)

ICS 8: IBC consensus equivocation proof specification

Connection-level fraud. Will cover:

• Precise format & encoding of fraud proofs
• Slashing conditions / evidence handling

ICS 14: IBC consensus state upgrade protocol

Will cover:

• Protocol for altering IBC root-of-trust (can be enabled as an option in the negotiation handshake)

ICS ?: Equivocation & fraud watchtowers

In order to provide some additional assurance about the combined state of an application across a set of blockchains interconnected with IBC connections under the situation of Byzantine behavior by one or some of the blockchains' validator sets, I think it may be useful to introduce the concept of an IBC "watchtower" - a particular off-chain process responsible for monitoring blockchains in the network for provable equivocation / fraud and reporting it when detected to all relevant IBC connections, which can then take appropriate action (e.g. close the connection) to limit further impact (such as double-spending).

Likely these "watchtower" processes will need to be permissionless and incentivized by some reward to report Byzantine behavior. One concern is that submission of this evidence may be front-run by another watchtower who was just watching the IBC connections (to "steal" the reward). A commit-reveal scheme could possibly help, or some sort of limited permissioning on evidence submission (perhaps this becomes integrated with the delegated-security model).

I think "watchtowers" would be particularly useful in conjunction with conservative IBC connections which limited value flow as a function of time. Then, assuming the watchtowers respond within some t after Byzantine behavior (which could have double-spent assets on IBC connections), the possible damage could be capped proportional to the maximum value flow times the number of open connections times t.

This concept is a bit similar to "fishermen" in Polkadot. To be clear, IBC is not reliant on watchtowers for security in the same sense - the chains a user chooses to trust determine their risks - but I think we may find them useful nonetheless to provide additional assurances, especially if we implement additional kinds of fraud proofs.

ICS 20: IBC fungible token transfer packet specification

Will cover:

• Packet specification & encoding for fungible token transfer
• Required interfaces on each chain
• Provided application-layer security guarantees

IBC definitions

Just noting for clarity so we avoid using the same term to mean different things in different places.

Ledger / Chain

A ledger, or chain, is a distributed ledger (or "blockchain", although a strict chain of blocks may not be required) implementing part or all of the IBC specification as a component or module within its state machine.

Handler

An IBC handler is the module or subcomponent within the state machine of a ledger responsible for implementing the IBC specification by "handling" datagrams, performing the appropriate checks, proof verifications, and/or storage alterations, and routing valid packets to other parts of the state machine, as defined by the application-layer semantics.

Datagram

A datagram is an opaque data blob transmitted over some network, and handled by the top-level IBC handler implemented in the ledger's state machine. In some implementations, the datagram may be a field in a ledger-specific transaction or message data structure which also contains other information (e.g. a fee for spam prevention, nonce for replay prevention, type identifier to route to the IBC handler, etc.)

Connection

A connection is a persistent data structure on a particular ledger that contains information about the consensus state of another ledger. Updates to that consensus state change the state of the connection.

Channel

A channel is a persistent data structure on a particular ledger that contains metadata to facilitate packet ordering, exactly-once delivery, and replay prevention. Often it may make sense to reason about a "channel" across two chains (reasoning about subsets of state on both ledgers).

Packet

A packet is a particular data structure with sequence-related metadata (defined by the IBC specification) and an opaque value field (with semantics defined by the application layer).

ICS ?: IBC threat model & security assumptions

Primarily a port of the original IBC spec.

Will cover:

• Security assumptions of the underlying consensus
• Required slashing conditions / evidence handling
• Exceptional cases and possible recovery methods

IBC research compilation

Multi-chain routing & state transition atomicity

• Anonymous Multi-Hop Locks for BlockchainScalability and Interoperability.
  Analyzes LN but possibly relevant.

ICS ?: Liveness Violation Recovery

When a chain does not (or expected to not) produces block anymore(e.g. incompatible hard fork including 1/2 < vals < 2/3 fork, synchronized halt, etc.), then any packet(not datagram) sent to the chain after the event happened will be lost. A manual procedure to disconnect the connection and possibly recover the connection to the new chain is needed.

ICS ?: IBC protocol negotation handshake

Will cover:

• Description of initial packet ("OPENTRY")
• Description of response packet ("OPENACK")
• Description of confirmation packet ("OPENCONFIRM")
• Algorithms for handling all packets
• Format for option transmission from opening chain to destination chain

ICS 23: Standard accumulator

Define required functions and their properties for the kind of cryptographic accumulator which IBC state inclusion proofs will require. Any accumulator which instantiates these properties (e.g. Merkle tree proofs) could be used with IBC and provide the usual safety guarantees. Different accumulators will have different performance characteristics, proof sizes, verification times, and possibly trusted setup assumptions (e.g. an RSA accumulator).