Rough Project Plan

[ebuchman]

Goal

Objective: Fully complete IBC handlers in rust that can easily be integrated into any Rust blockchain framework, including Orga, Penumbra, Anoma, Substrate, Near, Solana, etc.

Major Milestone: simple ABCI app ("basecoin") that supports IBC token transfer. We want to be able to run two instances of this chain and use hermes to transfer tokens between them.

Future major milestones include having our IBC handlers connect to the Cosmos Hub, having a more robust "baseapp" framework (whether Orga or something else), and integrating smart contracting languages like CosmWasm or even Makina

Draft Plan

Here's a draft plan broken into phases.

Phases 0-2: simplest ABCI app possible to be able to support IBC

• [x] Phase 0: dummy basecoin

  • in memory state map: account address (string) -> balance (int)
  • single tx type json encoded with three fields: sender, receiver, amount

• [x] Phase 1: Same as Phase 0 but with protobuf based txs using Cosmos SDK Tx structure

  • use the Cosmos-SDK tx/v1beta1/tx.proto message Tx, but ignore all auth/signatures (just get the Msg out)
  • use the bank/v1beta1/tx.proto MsgSend to get the from/to/amount
  • use the same in memory state map as Phase 0
  • should be able to use gaiad tx bank send --offline whatever to send txs

• [x] Phase 2: Add support for multiple coins

  • state map is now map [ address (string) -> map[ denom (string) -> amount (int) ] ]

  • everything else should be the same !

Phases 3-6: IBC integration into the ABCI app

• [x] Phase 3: Add support for IBC CreateClient and UpdateClient msgs
  • complete/import the ics02/ics07 machinery from ibc-rs
  • state will now need to be able to store clients (may need more generic state mechanism ? )
  • allow sending MsgCreateClient to create client on the chain and MsgUpdateClient to update it with latest headers
  • should be able to use hermes tx raw create/update-client and/or gaiad tx ibc ...
  • should be able to run two chains, manually create a client on each, and manually update them

NOTE: at some point we need to add GRPC support to get hermes working properly and not have to do commands manually - probably should do this sooner than later.

• [x] Phase 4: Add support for IBC Connection machinery

  • complete/import the ics03 machinery from ibc-rs
  • state will now need to be able to store connection ends
  • should now be able to manually complete connection handshake between two chains

• [x] Phase 5: Add support IBC Channel machinery

  • complete/import the ics04 machinery from ibc-rs
  • state will now need to be able to store channel ends and packet data
  • should now be able to manually complete channel handshakes between two chains and send packets

• [ ] Phase 6: Add support for IBC Token Transfer

  • complete/import the ics20 machinery from ibc-rs
  • should now be able to transfer tokens from one chain to the other

TADA!

---

• [ ] Phase 7: Get it working with the Cosmos Hub ....

• [ ] Phase 8: use a real app framework and make everything secure ...

OPEN QUESTION:

• what parts of ibc-rs are still incomplete and need to be filled in to get this working?
• are there parts we can still punt on ? eg. merkle tree verification
• what do we need the state to look like to make this work ?
• what do we need to expose to enable hermes to run against these two chains and do everything automatically (ie. grpc ? )

[adizere]

Below are a few pointers concerning phases 3-6.

For the interface chain <-> IBC module the dependencies are:

1. the chain/app has to implement the Ics26Context trait combo. This defines the dependencies of IBC module towards the basecoin chain/app.

   state will now need to be able to store clients (may need more generic state mechanism ? )

Agree. As part of implementing the Ics26Context trait, it will be necessary to have support for storing and reading all kinds of objects (e.g., the method store_consensus_state is part of trait ClientKeeper, and it requires the ability to store a AnyConsensusState).

It's relatively easy to understand which parts are necessary for each phase. For instance, for phase 3 (support for IBC clients), the critical sub-traits needed are ClientReader and ClientKeeper, while the other traits can be largely left unimplemented!().

2. to submit a tx to the IBC module (for example, for processing a MsgCreateClient that Hermes submitted via broadcast_tx_* to your app), your chain/app will need to call into the deliver.

As a result of calling this method, the IBC module will produce a response type of Vec<IbcEvent>, and this vector of events will most likely need to undergo some transformation before the app can return it to Hermes as a reply to broadcast_tx_*.

For the interface Hermes <> the app:

• Hermes expects three ports to be available to be able to initialize communication with any chain -- a websocket, the ABCI interface, and gRPC. Not all methods in these interfaces have to implemented, however, so most of them can be stubbed out. In particular for handling the creation of a client, this is the precise list of requirements:
  • for gRPC, this server implements all the methods that are needed.
  • for ABCI, see here
  • for websocket, Hermes will probably be OK if you only need to handle the subscription request (an example implementation), but this changed a bit recently so I'm not 100%.

Note: the code in the above links were originally written by a student as part of a project to build a mock gaia (https://github.com/CharlyCst/tendermock). I tried to maintain that project and was hoping to eventually bring pieces of it into ibc-rs. The project is interesting in its own right: It builds on testgen to generate realistic blocks, it was the first to integrate our IBC handlers, it has a IAVL store implementation and Hermes could use it as a library to improve testing/integration with ibc. Happy to dive into more detail here if useful.

---

what parts of ibc-rs are still incomplete and need to be filled in to get this working?

Except for the verification methods, for the IBC client (phase 3), I think most of it should be in place, since this was tested with tendermock (modulo client upgrade functionality). For the other phases, we only tested them with an in-process mock chain.

what do we need the state to look like to make this work ?

The mock chain struct implements most of the Ics26Context trait, and shows at a basic level everything that a chain would need to store to interact with the IBC module.

The tendermock experiment stored everything as a Vec<u8> (ref) and I found that difficult to understand and test. It was motivated by flexibility and was relatively easy to build confio/ics23 proofs, however, though I never tested the validity of these proofs against a real-world chain.

[ebuchman]

Wow Adi this is incredible, thank you! Tendermock looks way more valuable than I imagined, amazing work.

As a result of calling this method, the IBC module will produce a response type of Vec, and this vector of events will most likely need to undergo some transformation before the app can return it to Hermes as a reply to broadcasttx*.

Events will probably be one of the more fragile components, since I believe they're still under specified and we'll just have to copy exactly what the SDK does in returning the events for each tx type. Also note that hermes responds to events both from txs it sent and from those it didnt send. In either case so long as they're retuned correctly in the ResponseDeliverTx like they are in the Cosmos-SDK, hermes should be able to handle them.

for gRPC, this server implements all the methods that are needed.

This is amazing. Is it really everything ? I guess we just have to copy this and hook it up to our app state. But I wonder, why are all those staking endpoints needed?

for ABCI, see here

nice, but we won't need this, since we're going to use real tendermint here, so we'll have access to it's rpc

for websocket,

Same here, the websocket is also part of tendermint and leverages the event system so if we return the events correctly from the ABCI app we'll get the websocket out of the box :)

Of the three ports, only the grpc needs to be exposed by the ABCI app, the others are tendermint.

it was the first to integrate our IBC handlers, it has a IAVL store implementation

This is super useful and will probably save us a lot of work. Nice to see that the IAVL implementation is so simple and straight forward - I guess we can actually use this instead of a bunch of maps to store the app state, and then we can start connecting to the hub right away and would be able to transfer tokens between by end of phase 6 (!).

[adizere]

Yep, I'm glad we're putting tendermock to concrete use!

This is amazing. Is it really everything ? I guess we just have to copy this and hook it up to our app state. But I wonder, why are all those staking endpoints needed?

Only the params endpoint is necessary. All the others are unimplemented. Among the consensus params, the unbonding_period is essential because this is a field in the client state of any new client being created.

[hu55a1n1]

A comprehensive list of all that was required to implement Phase-3

High-level Components

• MT-safe KV store as described in ICS-024: Kev/Value Store
• IBC module with implementation of ClientKeeper and ClientReader traits.
• gRPC server stubs for Cosmos-SDK and IBC.
• gRPC endpoints for hermes' health check and other auth and staking related queries.
• Basic account subsystem (placeholder for auth module).

Traits

• ibc::ics02_client::context::{ClientKeeper::*, ClientReader::*}
• ibc::core::client::v1::query_server::Query::consensus_states
• cosmos::base::tendermint::v1beta1::service_server::Service::get_node_info
• cosmos::auth::v1beta1::query_server::Query::account
• cosmos::staking::v1beta1::query_server::Query::params

Observations and questions

• ICS-024's description of a KV-store requires that host stores implement get, set and delete functionality but ibc::core::client::v1::query_server::Query::consensus_states requires that stores are also able to inspect all keys that start with a specified prefix.
• The rationale for using gRPC to query consensus_states while using tendermint_abci::Application::query for other queries is unclear.
• cosmos::base::tendermint::v1beta1::VersionInfo contains fields that are specific to the cosmos-sdk go implementation.

[DaviRain-Su]

I recently discovered bascoin-rs, which is implementing a Rust version of the Cosmos SDK. It's absolutely amazing!

[plafer]

The project has turned more recently into a chain that uses ibc-rs, to give us better insights into how using the ibc-rs API feels, as well as run some integration tests before every release of ibc-rs. Unfortunately it is not on the roadmap to make a "Rust Cosmos SDK" of it

[DaviRain-Su]

Unfortunately it is not on the roadmap to make a "Rust Cosmos SDK" of it

I understand what you mean, but I'm really interested in using Rust to implement the Cosmos SDK.

[DaviRain-Su]

First Step : https://github.com/informalsystems/basecoin-rs/pull/110 make more like Cosmos Rust SDK