Skip to main content
Version: v9.0.x

Overview

Synopsis

Learn about IBC, its components, and its use cases.

What is the Inter-Blockchain Communication Protocol (IBC)?​

This document serves as a guide for developers who want to write their own Inter-Blockchain Communication Protocol (IBC) applications for custom use cases.

IBC applications must be written as self-contained modules.

Due to the modular design of the IBC Protocol, IBC application developers do not need to be concerned with the low-level details of clients, connections, and proof verification.

This brief explanation of the lower levels of the stack gives application developers a broad understanding of the IBC Protocol. Abstraction layer details for channels and ports are most relevant for application developers and describe how to define custom packets and IBCModule callbacks.

The requirements to have your module interact over IBC are:

  • Bind to a port or ports.
  • Define your packet data.
  • Use the default acknowledgment struct provided by core IBC or optionally define a custom acknowledgment struct.
  • Standardize an encoding of the packet data.
  • Implement the IBCModule interface.
  • Implement the UpgradableModule interface (optional).

Read on for a detailed explanation of how to write a self-contained IBC application module.

Components overview​

Clients​

IBC clients are on-chain light clients. Each light client is identified by a unique client ID. IBC clients track the consensus states of other blockchains, along with the proof spec necessary to properly verify proofs against the client's consensus state. A client can be associated with any number of connections to the counterparty chain. The client identifier is auto generated using the client type and the global client counter appended in the format: {client-type}-{N}.

A ClientState should contain chain specific and light client specific information necessary for verifying updates and upgrades to the IBC client. The ClientState may contain information such as chain ID, latest height, proof specs, unbonding periods or the status of the light client. The ClientState should not contain information that is specific to a given block at a certain height, this is the function of the ConsensusState. Each ConsensusState should be associated with a unique block and should be referenced using a height. IBC clients are given a client identifier prefixed store to store their associated client state and consensus states along with any metadata associated with the consensus states. Consensus states are stored using their associated height.

The supported IBC clients are:

IBC client heights​

IBC Client Heights are represented by the struct:

type Height struct {
  RevisionNumber uint64
  RevisionHeight uint64
}

The RevisionNumber represents the revision of the chain that the height is representing. A revision typically represents a continuous, monotonically increasing range of block-heights. The RevisionHeight represents the height of the chain within the given revision.

On any reset of the RevisionHeight—for example, when hard-forking a Tendermint chain, the RevisionNumber will get incremented. This allows IBC clients to distinguish between a block height n of a previous revision of the chain (at revision p) and block-height n of the current revision of the chain (at revision e).

Heights that share the same revision number can be compared by simply comparing their respective RevisionHeights. Heights that do not share the same revision number will only be compared using their respective RevisionNumbers. Thus a height h with revision number e+1 will always be greater than a height g with revision number e, REGARDLESS of the difference in revision heights.

For example:

Height{RevisionNumber: 3, RevisionHeight: 0} > Height{RevisionNumber: 2, RevisionHeight: 100000000000}

When a Tendermint chain is running a particular revision, relayers can simply submit headers and proofs with the revision number given by the chain's chainID, and the revision height given by the Tendermint block height. When a chain updates using a hard-fork and resets its block-height, it is responsible for updating its chainID to increment the revision number. IBC Tendermint clients then verifies the revision number against their chainID and treat the RevisionHeight as the Tendermint block-height.

Tendermint chains wishing to use revisions to maintain persistent IBC connections even across height-resetting upgrades must format their chainIDs in the following manner: {chainID}-{revision_number}. On any height-resetting upgrade, the chainID MUST be updated with a higher revision number than the previous value.

For example:

  • Before upgrade chainID: gaiamainnet-3
  • After upgrade chainID: gaiamainnet-4

Clients that do not require revisions, such as the 06-solomachine client, can simply hardcode 0 into the revision number whenever they need to return an IBC height when implementing IBC interfaces and use the RevisionHeight exclusively.

Other client types can implement their own logic to verify the IBC heights that relayers provide in their Update, Misbehavior, and Verify functions respectively.

The IBC interfaces expect an ibcexported.Height interface, however all clients must use the concrete implementation provided in 02-client/types and reproduced above.

Connections​

Connections encapsulate two ConnectionEnd objects on two separate blockchains. Each ConnectionEnd is associated with a client of the other blockchain (for example, the counterparty blockchain). The connection handshake is responsible for verifying that the light clients on each chain are correct for their respective counterparties. Connections, once established, are responsible for facilitating all cross-chain verifications of IBC state. A connection can be associated with any number of channels.

The connection handshake is a 4-step handshake. Briefly, if a given chain A wants to open a connection with chain B using already established light clients on both chains:

  1. chain A sends a ConnectionOpenInit message to signal a connection initialization attempt with chain B.
  2. chain B sends a ConnectionOpenTry message to try opening the connection on chain A.
  3. chain A sends a ConnectionOpenAck message to mark its connection end state as open.
  4. chain B sends a ConnectionOpenConfirm message to mark its connection end state as open.

Time delayed connections​

Connections can be opened with a time delay by setting the delay_period field (in nanoseconds) in the MsgConnectionOpenInit. The time delay is used to require that the underlying light clients have been updated to a certain height before commitment verification can be performed.

delayPeriod is used in conjunction with the max_expected_time_per_block parameter of the connection submodule to determine the blockDelay, which is number of blocks that the connection must be delayed by.

When commitment verification is performed, the connection submodule will pass delayPeriod and blockDelay to the light client. It is up to the light client to determine whether the light client has been updated to the required height. Only the following light clients in ibc-go support time delayed connections:

  • 07-tendermint
  • 08-wasm (passed to the contact)

Proofs and paths​

In IBC, blockchains do not directly pass messages to each other over the network. Instead, to communicate, a blockchain commits some state to a specifically defined path that is reserved for a specific message type and a specific counterparty. For example, for storing a specific connectionEnd as part of a handshake or a packet intended to be relayed to a module on the counterparty chain. A relayer process monitors for updates to these paths and relays messages by submitting the data stored under the path and a proof to the counterparty chain.

Proofs are passed from core IBC to light clients as bytes. It is up to light client implementations to interpret these bytes appropriately.

Ports​

An IBC module can bind to any number of ports. Each port must be identified by a unique portID. Since IBC is designed to be secure with mutually distrusted modules operating on the same ledger, binding a port returns a dynamic object capability. In order to take action on a particular port (for example, an open channel with its port ID), a module must provide the dynamic object capability to the IBC handler. This requirement prevents a malicious module from opening channels with ports it does not own. Thus, IBC modules are responsible for claiming the capability that is returned on BindPort.

Channels​

An IBC channel can be established between two IBC ports. Currently, a port is exclusively owned by a single module. IBC packets are sent over channels. Just as IP packets contain the destination IP address and IP port, and the source IP address and source IP port, IBC packets contain the destination port ID and channel ID, and the source port ID and channel ID. This packet structure enables IBC to correctly route packets to the destination module while allowing modules receiving packets to know the sender module.

A channel can be ORDERED, where packets from a sending module must be processed by the receiving module in the order they were sent. Or a channel can be UNORDERED, where packets from a sending module are processed in the order they arrive (might be in a different order than they were sent).

Modules can choose which channels they wish to communicate over with, thus IBC expects modules to implement callbacks that are called during the channel handshake. These callbacks can do custom channel initialization logic. If any callback returns an error, the channel handshake fails. Thus, by returning errors on callbacks, modules can programmatically reject and accept channels.

The channel handshake is a 4-step handshake. Briefly, if a given chain A wants to open a channel with chain B using an already established connection:

  1. chain A sends a ChanOpenInit message to signal a channel initialization attempt with chain B.
  2. chain B sends a ChanOpenTry message to try opening the channel on chain A.
  3. chain A sends a ChanOpenAck message to mark its channel end status as open.
  4. chain B sends a ChanOpenConfirm message to mark its channel end status as open.

If all handshake steps are successful, the channel is opened on both sides. At each step in the handshake, the module associated with the ChannelEnd executes its callback. So on ChanOpenInit, the module on chain A executes its callback OnChanOpenInit.

The channel identifier is auto derived in the format: channel-{N} where N is the next sequence to be used.

Closing channels​

Closing a channel occurs in 2 handshake steps as defined in ICS 04. Once a channel is closed, it cannot be reopened. The channel handshake steps are:

ChanCloseInit closes a channel on the executing chain if

ChanCloseInit can be initiated by any user by submitting a MsgChannelCloseInit transaction. Note that channels are automatically closed when a packet times out on an ORDERED channel. A timeout on an ORDERED channel skips the ChanCloseInit step and immediately closes the channel.

ChanCloseConfirm is a response to a counterparty channel executing ChanCloseInit. The channel on the executing chain closes if

  • the channel exists and is not already closed,
  • the connection the channel exists upon is OPEN,
  • the executing chain successfully verifies that the counterparty channel has been closed
  • the IBC module callback OnChanCloseConfirm returns nil.

Currently, none of the IBC applications provided in ibc-go support ChanCloseInit.

Packets​

Modules communicate with each other by sending packets over IBC channels. All IBC packets contain the destination portID and channelID along with the source portID and channelID. This packet structure allows modules to know the sender module of a given packet. IBC packets contain a sequence to optionally enforce ordering.

IBC packets also contain a TimeoutHeight and a TimeoutTimestamp that determine the deadline before the receiving module must process a packet.

Modules send custom application data to each other inside the Data []byte field of the IBC packet. Thus, packet data is opaque to IBC handlers. It is incumbent on a sender module to encode their application-specific packet information into the Data field of packets. The receiver module must decode that Data back to the original application data.

Receipts and timeouts​

Since IBC works over a distributed network and relies on potentially faulty relayers to relay messages between ledgers, IBC must handle the case where a packet does not get sent to its destination in a timely manner or at all. Packets must specify a non-zero value for timeout height (TimeoutHeight) or timeout timestamp (TimeoutTimestamp ) after which a packet can no longer be successfully received on the destination chain.

  • The timeoutHeight indicates a consensus height on the destination chain after which the packet is no longer to be processed, and instead counts as having timed-out.
  • The timeoutTimestamp indicates a timestamp on the destination chain after which the packet is no longer to be processed, and instead counts as having timed-out.

If the timeout passes without the packet being successfully received, the packet can no longer be received on the destination chain. The sending module can timeout the packet and take appropriate actions.

If the timeout is reached, then a proof of packet timeout can be submitted to the original chain. The original chain can then perform application-specific logic to timeout the packet, perhaps by rolling back the packet send changes (refunding senders any locked funds, etc).

  • In ORDERED channels, a timeout of a single packet in the channel causes the channel to close.

    • If packet sequence n times out, then a packet at sequence k > n cannot be received without violating the contract of ORDERED channels that packets are processed in the order that they are sent.
    • Since ORDERED channels enforce this invariant, a proof that sequence n has not been received on the destination chain by the specified timeout of packet n is sufficient to timeout packet n and close the channel.

  • In UNORDERED channels, the application-specific timeout logic for that packet is applied and the channel is not closed.

    • Packets can be received in any order.
    • IBC writes a packet receipt for each sequence received in the UNORDERED channel. This receipt does not contain information; it is simply a marker intended to signify that the UNORDERED channel has received a packet at the specified sequence.
    • To timeout a packet on an UNORDERED channel, a proof is required that a packet receipt does not exist for the packet's sequence by the specified timeout.

For this reason, most modules should use UNORDERED channels as they require fewer liveness guarantees to function effectively for users of that channel.

Acknowledgments​

Modules can also choose to write application-specific acknowledgments upon processing a packet. Acknowledgments can be done:

  • Synchronously on OnRecvPacket if the module processes packets as soon as they are received from IBC module.
  • Asynchronously if module processes packets at some later point after receiving the packet.

This acknowledgment data is opaque to IBC much like the packet Data and is treated by IBC as a simple byte string []byte. Receiver modules must encode their acknowledgment so that the sender module can decode it correctly. The encoding must be negotiated between the two parties during version negotiation in the channel handshake.

The acknowledgment can encode whether the packet processing succeeded or failed, along with additional information that allows the sender module to take appropriate action.

After the acknowledgment has been written by the receiving chain, a relayer relays the acknowledgment back to the original sender module.

The original sender module then executes application-specific acknowledgment logic using the contents of the acknowledgment.

  • After an acknowledgement fails, packet-send changes can be rolled back (for example, refunding senders in ICS 20).
  • After an acknowledgment is received successfully on the original sender on the chain, the corresponding packet commitment is deleted since it is no longer needed.

Further readings and specs​

If you want to learn more about IBC, check the following specifications: