diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index e616b323169..321c61add5d 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -217,6 +217,11 @@ module.exports = { directory: false, path: "/apps/interchain-accounts/parameters.html", }, + { + title: "Development Use Cases", + directory: false, + path: "/apps/interchain-accounts/development.html", + }, { title: "Active Channels", directory: false, diff --git a/docs/apps/interchain-accounts/active-channels.md b/docs/apps/interchain-accounts/active-channels.md index 92a16decfa6..bce6db92a9c 100644 --- a/docs/apps/interchain-accounts/active-channels.md +++ b/docs/apps/interchain-accounts/active-channels.md @@ -1,5 +1,5 @@ # Understanding Active Channels @@ -29,4 +29,4 @@ The following is a list of issues which will provide the infrastructure to make - [IBC Channel Upgrades](https://github.com/cosmos/ibc-go/issues/1599) - [Implement ORDERED_ALLOW_TIMEOUT logic in 04-channel](https://github.com/cosmos/ibc-go/issues/1661) - [Add ORDERED_ALLOW_TIMEOUT as supported ordering in 03-connection](https://github.com/cosmos/ibc-go/issues/1662) -- [Allow ICA channels to be opened as ORDERED_ALLOW_TIMEOUT](https://github.com/cosmos/ibc-go/issues/1663) \ No newline at end of file +- [Allow ICA channels to be opened as ORDERED_ALLOW_TIMEOUT](https://github.com/cosmos/ibc-go/issues/1663) diff --git a/docs/apps/interchain-accounts/auth-modules.md b/docs/apps/interchain-accounts/auth-modules.md index d945ec62068..65fb30010a3 100644 --- a/docs/apps/interchain-accounts/auth-modules.md +++ b/docs/apps/interchain-accounts/auth-modules.md @@ -1,5 +1,5 @@ # Building an authentication module diff --git a/docs/apps/interchain-accounts/development.md b/docs/apps/interchain-accounts/development.md new file mode 100644 index 00000000000..3d791a97405 --- /dev/null +++ b/docs/apps/interchain-accounts/development.md @@ -0,0 +1,36 @@ + + +# Development use cases + +The initial version of interchain accounts allowed for the controller module to be extended by providing it with an underlying application which would handle all packet callbacks. +That functionality is now being deprecated in favor of alternative approaches. +This document will outline potential use cases and redirect each use case to the appropriate documentation. + +## Custom authentication + +Interchain accounts may be associated with alternative types of authentication relative to the traditional public/private key signing. +If you wish to develop or use interchain accounts with a custom authentication module, we recommend you use ibc-go v6 or greater. + +The custom authentication module should interact with the controller module via the [MsgServer](./messages.md). + +## Redirection to a smart contract + +It may be desirable to allow smart contracts to control an interchain account. +To faciliate such an action, the controller module may be provided an underlying application which redirects to smart contract callers. +An improved design has been suggested in [ADR 008](https://github.com/cosmos/ibc-go/pull/1976) which performs this action via middleware. + +Implementors of this use case are recommended to follow the ADR 008 approach. +The underlying application may continue to be used as a short term solution for ADR 008 and the [legacy API](./auth-modules.md#registerinterchainaccount) should continue to be utilized in such situations. + +## Packet callbacks + +If a developer requires access to packet callbacks for their use case, then they having the following options: + +1. Write a smart contract which is connected via an ADR 008 or equivalent IBC application (recommended). +2. Use the controller's underlying application to implement packet callback logic. + +If the first case, the smart contract should use the [MsgServer](./messages.md). + +In the second case, the underlying application should use the [legacy API](./auth-modules.md#registerinterchainaccount).