ibc-go v6: Changes to Interchain Accounts and How It Impacts Your Chain

TL;DR

• The lack of a default underlying app (previously called the ‘authentication module’), and the need to separate application and authentication concerns were recognised as primary reasons for the slow adoption of ICS-27 Interchain Accounts (ICA).
• ibc-go v6.0.0 release will include changes to ICA that makes integrating the controller chain functionality easier. See ADR 009 for more information.
• Changes include adding a MsgServer to the controller submodule — allowing any generic SDK authentication module (x/gov, x/group, x/auth) to act as the underlying application.
• The controller submodule now claims the channel capability instead of the underlying app and passes ‘nil’ to the underlying app.
• ICA use cases for x/gov, x/group and individual accounts (x/auth) are supported by default.
• Once application callbacks are implemented (see ADR 008), all use cases for ICA will be supported by the MsgServer without the need for an underlying app.
• Existing APIs (RegisterInterchainAccount/SendTx) will gradually be phased out in future releases. Existing underlying apps will continue to be supported until then.

Glossary of terms

Controller chain
Chain that registers and controls an interchain account on the host chain

Host chain
Chain where the interchain account is registered

Interchain account
An account on a host chain with all the capabilities of a normal account

Base/underlying app
Custom IBC application module on the controller chain, that uses the ICA module to register/manage an interchain account using custom logic. Note that this was previously referred to as the ‘authentication module’.

Introduction

Interchain Accounts (ICA) has been one of the most important IBC feature releases in 2022. By allowing a chain to securely control an account on another chain, ICA delivers Interchain composability. It enables applications to go beyond the scope of their own domain and to extend cross-chain — paving the way for Interchain native products.

While we’ve witnessed multiple projects enabling host chain functionality, despite ICA having launched in March this year, use of controller chains is still quite limited.

Stride recently launched a controller chain, while the Cosmos Hub, Neutron, Osmosis, Secret, Persistence, Axelar, Quicksilver and others are still actively working on implementing the controller submodule.

We believe that the lack of controller chains have been because:

• We did not develop a standardized authentication module* which created a bottleneck for chains looking to integrate the controller submodule
• We did not have a clear understanding of all the use cases ICA would facilitate
• We expected more chains to want to design custom authentication for ICA
• Coupling ICA authentication and application logic was a misdesign

These were the primary reasons that led to modifying ICA. Our goal has been to improve the feature to accommodate all use-cases, simplify the developer UX, and maintain backwards compatibility with ongoing work that teams have been doing around underlying application development.

The purpose of this blog post is to communicate why we made the modifications, what those modifications are, and how it provides a better solution for chains looking to utilize ICA. If your chain has been developing an underlying app, the FAQ section below will provide clarity on how the changes impact your team.

*Note: the term ‘authentication module’ — previously used to describe a custom IBC application module on the controller chain used to register/manage an interchain account using its custom logic — is being deprecated. It will instead be referred to as the ‘underlying app’ or ‘base app’ from now onwards.

Why we decided to make the changes to Interchain Accounts

Over the past few months, we spoke to multiple Cosmos chains to understand their intended use cases and pain points with ICA. After gathering their feedback, these were some of the key points that we learned:

1. Gov/group use-cases: not only did chains want individual accounts to be able to use ICA, but also for generic Cosmos SDK authentication modules such as x/gov and x/group to be able to register an interchain account and send messages.
   An example use case with gov: the Cosmos Hub (controller), upon governance authorization, sends some of its inflationary rewards to Osmosis (host), to provide liquidity and purchase ATOM GAMM shares, which are then sent back to the Hub in one flow.
2. Need for application callbacks: while the original design of IBC allows for core IBC to make callbacks to an IBC application, it does not allow for a module/smart contract to call into an IBC application to retrieve packet information such as Ack/Timeout.
   For example, a user sends tokens to a DEX. Upon confirmation of successful packet send, the user might want to programmatically perform another action using ICA such as swapping the tokens and sending it back to the source chain.
   To enable this, the ICA controller submodule needs to be able to call into the transfer module. ADR 008 addresses this issue and is an important step towards decoupling ICS-27 application and authentication logic.
   Shoutout to Ethan Frey for bringing this to our attention. ADR 008 was directly motivated by his feedback.

How the new ICA design differs from the old

In the original architecture of ICA, a chain needed at least one underlying app to act as a controller chain. By calling RegisterInterchainAccount, the underlying app can create an interchain account, and SendTx allows it to send an IBC packet (which is authenticated on the host and executed as a local transaction).

Figure 1: original design of ICA

But with the release of SDK v0.46.0, the x/gov, x/group, and x/auth modules now support arbitrary message passing using SDK’s MessageServiceRouter (used to route an sdk.Msg to the corresponding module’s MsgService), and allows the chain to execute any sdk.Msg upon governance/end-user authorization.

As part of the ICA modifications, a new MsgServer was added to the controller submodule which exposes the following two RPC endpoints:

1. RegisterInterchainAccount
2. SendTx

These two endpoints serve to provide the existing functionality of RegisterInterchainAccount and SendTx, respectively. Note that the latter mentioned APIs will become the legacy version with the release of v6.0.0.

This change effectively means that any SDK module such as gov/group/auth can now register an interchain account and send packets on its behalf.

Therefore, as part of the improvements made to ICA, the gov/group/auth modules will now act as the underlying apps by default. No additional code needs to be added in order to be compatible with these changes.

Figure 2: overview of ICA design after the changes

The new design renders the old middleware architecture of ICA (shown in Figure 3a) less useful — where the underlying app acted as the base application and the controller submodule functioned as middleware.

Figure 3a: middleware architecture | Figure 3b: middleware architecture with base app set to nil

Figure 3a: middleware architecture | Figure 3b: middleware architecture with base app set to nil

Teams implementing an underlying app with ibc-go v6.0.0 will effectively be writing middleware for a level above the controller submodule (as shown in Figure 3b). In this case, if you only require gov/group/auth to send ICA messages, then you can set the base application to ‘nil’ so that it won’t be called.

The addition of ADR 008 renders the base app unnecessary since gov/group/auth can now act as authentication mechanisms while also being able to make application callbacks to retrieve info on Ack/Timeout. Therefore, future versions of ibc-go might remove the base app entirely.

Note that in order to maintain backwards compatibility and avoid requiring underlying app developers to account for interchain accounts they did not register, a boolean mapping has been added to track the behavior of how an account was created.

In short:

- Using the legacy API means that the underlying app is used.

- Using the MsgServer means that the underlying app is not used.

See this issue for more information.

With respect to the security implications, while the security model of ICA under the old architecture was overly defensive, the new changes align the security properties with that of the Cosmos SDK.

Benefits of the new design

By minimizing disruption around existing underlying app development, the changes made to ICA will make it easier to become a controller chain because:

1. It simplifies interaction with the controller submodule and supports the use cases of gov, group and individual accounts by default.
2. It removes middleware logic which previously limited application possibilities (the middleware forced authentication and application logic to be bundled together).
3. Underlying apps are no longer required for ICA use cases where application callbacks are not needed.
4. Once ADR 008 is implemented, all use cases with application callbacks can be done using the MsgServer, without the need for an underlying app at all in the future.
5. Backwards compatible with underlying apps that use the legacy API.

ibc-go v6.0.0 will include the MsgServer with the new API. We plan to slowly phase out existing public APIs in future major releases while continuing to support underlying apps currently being developed.

Note: with the implementation of ADR 008, chains are encouraged to use the MsgServer (new API) with the application caller interface instead of the legacy API.

Upgrading from v5 to v6

The new MsgServer combined with application callbacks allow for more complicated use cases where the confirmation of a prior action is required before the next action can occur.

For example, take two chains NFTchain and DEXchain. A user pays tokens (in any denomination) to mint an NFT on NFTchain. The tokens are escrowed to the NFT module. The module then opens an ICA account on DEXchain. The escrowed tokens are sent from the NFT module to the DEXchain, and upon confirmation of successful transfer, the host account swaps the tokens for another token, and is automatically sent back to NFTchain.

If your chain has integrated the controller submodule and/or has an underlying app, then in order to upgrade from v5 to v6 you will need to call our migration function within your chain’s upgrade handler. Refer to this issue for information on upcoming migration docs.

Based on different use cases, the FAQ section below serves to provide more clarity as to how the changes impact your team. If your query has not been addressed, we encourage you to reach out to us on the IBC Gang channel on Discord.

FAQs

Q1. Our chain has been working on building an underlying app. How do the changes affect the work that we’ve been doing?

A. If your use case for ICA needs application callbacks, then refer to the answer for Q2.

If your use case for ICA does not need application callbacks, then refer to the answer for Q3.

Q2. Our chain has been working on an underlying app to use with gov/group. For our use cases we require application callbacks. How does this impact us?

A. You can continue to use the legacy API.

The only difference is in terms of how the channel capability is claimed. Instead of the underlying app, now the controller submodule will claim the channel capability and the underlying app attached to the controller should be passed as nil. To do the former, one would need to discard the capability provided in OnChanOpenInit and remove any associated logic. Essentially, you would need to remove any code which obtains the capability before calling SendTx. See this issue for more information.

Q3. Our chain has been working on an underlying app to use with gov/group. For our use cases we do not require application callbacks. How does this impact us?

A. For chains currently working on an underlying app with use cases that do not require application callbacks, this means that instead of calling into the old public APIs, you would change the code to message passing i.e., the underlying app would be composed with the SDK’s MessageServiceRouter and retrieve the handler based on the message type_url.

Q4. When will ADR 008 be ready?

A. There is currently no timeline as to when the app caller interface will be developed. Different application-specific chains might have different implementations.

Conclusion

ICA is one of the key pillars of Interchain composability. Projects within the ecosystem are still exploring the various applications that it enables. We expect that the new changes introduced will make it easier for different chains to integrate the controller chain functionality, and speed up the adoption of ICA, paving the way for novel use-cases yet to be seen. If you have any queries regarding the proposed changes, we encourage you to reach out to us. We look forward to feedback from the community.

About the Author:

Adi Ravi Raj works at Interchain GmbH and is the Protocol Analyst for the IBC team.

Shoutout to Susannah Evans, Colin Axner, Carlos Rodriguez and Thomas Dekeyser for the feedback and review.

Update: This blog was updated on 3 October 2022 to state that Stride recently launched a controller chain, and to update the list of projects actively working to implement the controller submodule.

If you’re a chain developer looking to build your custom IBC light client, and have any questions, comments or feedback on the above, feel free to reach out to us here.