|
| 1 | +# IBC <!-- omit in toc --> |
| 2 | + |
| 3 | +- [Definitions](#definitions) |
| 4 | + - ["host"](#host) |
| 5 | + - ["light client"](#light-client) |
| 6 | +- [Overview](#overview) |
| 7 | +- [IBC Module](#ibc-module) |
| 8 | + - [Node Configuration](#node-configuration) |
| 9 | + - [Persistence](#persistence) |
| 10 | +- [Components](#components) |
| 11 | + - [ICS-24 Host Requirements](#ics-24-host-requirements) |
| 12 | + |
| 13 | +## Definitions |
| 14 | + |
| 15 | +### "host" |
| 16 | + |
| 17 | +An IBC host refers to the node (host machine) that is running the IBC module. Relayers will interact with the hosts on each chain in order to call any IBC related functions. The IBC host is responsible for storing and interfacing with the IBC state and handling any IBC related transactions. |
| 18 | + |
| 19 | +### "light client" |
| 20 | + |
| 21 | +An IBC light client refers to a consensus state verification algorithm. This is different from the traditional meaning of the term. An IBC light client will be only used for state verification and will lack many of the other features commonly found in traditional light clients. |
| 22 | + |
| 23 | +## Overview |
| 24 | + |
| 25 | + |
| 26 | + |
| 27 | +Inter-Blockchain Communication (IBC) is a protocol that enables trustless communication between two chains. It allows these chains to interact by relaying IBC packets. The process involves two IBC-enabled chains, referred to as **chain A** and **chain B**, each running a light client for the other chain on their network. |
| 28 | + |
| 29 | +To transfer native tokens from **chain A** to **chain B**, certain prerequisites must be met. First, a connection between the two chains must be established. Then, a channel and port need to be opened on this connection. Additionally, a light client for the opposing chain should be set up on both ends of the connection. Finally, a relayer is required to facilitate the actual transfer of the packet. |
| 30 | + |
| 31 | +Once these components are in place, **chain A** can commit an IBC packet to its state, which contains transaction information. It also generates a proof that specifies the inclusion of the packet in the state at a particular height. The relayer submits this proof to **chain B**, where it is verified. If the proof is valid, **chain B** can respond accordingly, such as by sending an IBC token from **chain A** to the designated address on **chain B**. |
| 32 | + |
| 33 | +## IBC Module |
| 34 | + |
| 35 | +Pocket's IBC module is split into numerous components detailed below. The overall module layout is as follows: |
| 36 | + |
| 37 | +**Note:** Not all of the different ICS components have been fully implemented yet, this is a work in progress. |
| 38 | + |
| 39 | +```mermaid |
| 40 | +flowchart TB |
| 41 | + subgraph IBC[IBC Module] |
| 42 | + subgraph 23[ICS-23] |
| 43 | + VC[Vector Commitments] |
| 44 | + end |
| 45 | + subgraph 24[ICS-24] |
| 46 | + HR[Host Requirements] |
| 47 | + end |
| 48 | + subgraph I[IBC Interface] |
| 49 | + IF[ICS-25 Handler Interface] |
| 50 | + IR[ICS-26 Routing Module] |
| 51 | + end |
| 52 | + end |
| 53 | + subgraph 2[ICS-02] |
| 54 | + CL[Client Semantics] |
| 55 | + end |
| 56 | + subgraph 3[ICS-03] |
| 57 | + CO[Connection Semantics] |
| 58 | + end |
| 59 | + subgraph 5[ICS-05] |
| 60 | + PA[Port Allocation] |
| 61 | + end |
| 62 | + subgraph 4[ICS-04] |
| 63 | + CP[Channel & Packet Semantics] |
| 64 | + end |
| 65 | + subgraph 20[ICS-20] |
| 66 | + FT[Fungible Token Transfer] |
| 67 | + end |
| 68 | + IBC ---> 2 |
| 69 | + IBC ---> 3 |
| 70 | + IBC ---> 5 |
| 71 | + IBC ---> 4 |
| 72 | + IBC ---> 20 |
| 73 | +``` |
| 74 | + |
| 75 | +### Node Configuration |
| 76 | + |
| 77 | +Part of the node configurations relating to the IBC module is as follows: |
| 78 | + |
| 79 | +```json |
| 80 | +"ibc": { |
| 81 | + "enabled": bool, |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +If a node enables the IBC module, and is a validator, then the IBC module will automatically create an IBC host on startup. As the host defines the connections, channels and ports - which must stay persistent, the node should be a validator with little risk of suddenly closing any of these while open. Any tokens transferred over a connection/channel/port are unique to that combination they can only be returned over the same combination. |
| 86 | + |
| 87 | +**If the channel is to close without warning then tokens will be unable to be returned to their source. It is for this reason that only validators are able to become IBC hosts.** |
| 88 | + |
| 89 | +INVESTIGATE(M7): Look into on-chain POKT slashing/incentive conditions based on the QoS of an IBC host. |
| 90 | + |
| 91 | +_Note_: Connections, Channels and Ports in IBC are not the same as networking connections, channels and ports. They are stored in the chain state and are used by relayers to signify where each IBC packet should go when being relayed. When closing a channel the IBC host must submit to the state a `ChanCloseInit` IBC packet. If this happens without warning, the funds transferred on this channel will become unrecoverable. |
| 92 | + |
| 93 | +### Persistence |
| 94 | + |
| 95 | +[ICS24][ics24] defines the IBC stores and these must be a part of the Pocket networks consensus state. As such the `ibcTree` is defined as one of the state trees used to generate the root hash. This tree contains the relevant information the hosts/relayers need to be able to use IBC, in accordance with ICS-24 and the other ICS components. |
| 96 | + |
| 97 | +TODO([#854](https://github.com/pokt-network/pocket/issues/854)): Add a local cache for changes to the state for use in the event of the node crashing. |
| 98 | + |
| 99 | +## Components |
| 100 | + |
| 101 | +The [IBC specification][ibc-spec] details numerous Interchain Standards (ICSs) that together form the IBC protocol. The following gives an overview of the different components implemented in Pocket's IBC module. |
| 102 | + |
| 103 | +### ICS-24 Host Requirements |
| 104 | + |
| 105 | +[ICS-24][ics24] defines the requirements for a host chain to be IBC compatible. This includes the definition of a store system to hold IBC related data in a provable (and also a private) fashion. This implementation uses the [SMT][smt] rather than the IAVL tree used by `cosmos-sdk` for its provable stores. ICS-24 also defines the Event Logging system that is used to store and query IBC related events for the relayers to read packet data and timeouts, as only the proofs of these are stored in the chain state. |
| 106 | + |
| 107 | +See: [ICS-24](./ics24.md) for more details on the specifics of the ICS-24 implementation for Pocket. |
| 108 | + |
| 109 | +[ibc-spec]: https://github.com/cosmos/ibc |
| 110 | +[ics24]: https://github.com/cosmos/ibc/blob/main/spec/core/ics-024-host-requirements/README.md |
| 111 | +[smt]: https://github.com/pokt-network/smt |
0 commit comments