sekmet / substrate-ibc

An IBC implementation on Substrate

Substrate IBC Pallet (work in progress)

This project is funded by Interchain Foundation.

Purpose

This pallet implements the standard IBC protocol.

The goal of this pallet is to allow the blockchains built on Substrate to gain the ability to interact with other chains in a trustless way via IBC protocol.

This project is currently in an early stage and will eventually be submitted to upstream.

The pallet implements the chain specific logic of ICS spec, and is integrated with ibc-rs, which implements the generic cross-chain logic in ICS spec.

The chain specific logic of the modules in ICS spec implemented:

• ics-002-client-semantics
• ics-003-connection-semantics
• ics-004-channel-and-packet-semantics
• ics-005-port-allocation
• ics-010-grandpa-client
• ics-018-relayer-algorithms
• ics-023-vector-commitments
• ics-024-host-requirements
• ics-025-handler-interface
• ics-026-routing-module

Here is a demo for showing how to utilize this pallet, which initializes a series of steps for cross-chain communication, from client creation to sending packet data.

Design Overview

The ibc pallet is integrated with the modules in ibc-rs, which implements the ibc spec and leave the chain specific logics, which are named ???Readers and ???Keepers, to the ibc pallet.

List of Readers and Keepers of on-chain storage:

• ClientReader & ClientKeeper
• ConnectionReader & ConnectionKeeper
• ChannelReader & ChannelKeeper

Installation

Thie section describe the modification of your substrate chain needed to integrate pallet ibc.

Cargo.toml

Specify some versions of ibc relevant crate

[patch.crates-io]
tendermint              = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" }
tendermint-rpc          = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" }
tendermint-proto        = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" }
tendermint-light-client = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" }
tendermint-light-client-verifier = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" }
tendermint-testgen      = { git = "https://github.com/informalsystems/tendermint-rs", branch = "v0.23.x" }

#for libp2p
libp2p-noise 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-yamux 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-core 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-websocket 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-wasm-ext 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-uds 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-tcp 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-swarm-derive 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-swarm 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-request-response 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-relay 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-pnet 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-plaintext 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-ping 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-mplex 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-mdns 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-kad 					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-identify					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-gossipsub					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-floodsub					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-dns					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }
libp2p-deflate					= { git = "https://github.com/octopus-network/rust-libp2p.git", branch = "feature/dep-ibc-rs" }

Runtime's Cargo.toml

To add this pallet to your runtime, include the following to your runtime's Cargo.toml file:

pallet-ibc = { git = "https://github.com/octopus-network/substrate-ibc", branch = "master", default-features = false}

and update your runtime's std feature to include this pallet:

std = [
    # --snip--
    "pallet-ibc/std",
]

Runtime lib.rs

A custom structure that implements the pallet_ibc::ModuleCallbacks must be defined to dispatch messages to receiving module.

pub struct ModuleCallbacksImpl;

impl pallet_ibc::ModuleCallbacks for ModuleCallbacksImpl {}

impl pallet_ibc::Config for Runtime {
    type Event = Event;
    type ModuleCallbacks = ModuleCallbacksImpl;
    type TimeProvider = pallet_timestamp::Pallet<Runtime>;
}

You should include it in your construct_runtime! macro:

Ibc: pallet_ibc::{Pallet, Call, Storage, Event<T>},

Genesis Configuration

This pallet does not have any genesis configuration.

How to Interact with the Pallet

The Hermes (IBC Relayer CLI) offers commands to send reqeusts to pallet ibc to trigger the standard ibc communications defined in ibc spce. Hermes Command List.

Reference Docs

You can view the reference docs for this pallet by running:

cargo doc --open

or by visiting this site: https://docs.rs/pallet-ibc