From 71903058eebdab00aff6f28e81d123d656b3601e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?colin=20axn=C3=A9r?= <25233464+colin-axner@users.noreply.github.com> Date: Wed, 2 Nov 2022 18:37:12 +0100 Subject: [PATCH] chore: add potential use cases documentation for ica (#2594) ## Description will fix ordering after #2561 is merged, so review that first closes: #2472 --- Before we can merge this PR, please make sure that all the following items have been checked off. If any of the checklist items are not applicable, please leave them but write a little note why. - [ ] Targeted PR against correct branch (see [CONTRIBUTING.md](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#pr-targeting)) - [ ] Linked to Github issue with discussion and accepted design OR link to spec that describes this work. - [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/building-modules/10-structure.md). - [ ] Wrote unit and integration [tests](https://github.com/cosmos/ibc-go/blob/master/CONTRIBUTING.md#testing) - [ ] Updated relevant documentation (`docs/`) or specification (`x//spec/`) - [ ] Added relevant `godoc` [comments](https://blog.golang.org/godoc-documenting-go-code). - [ ] Added a relevant changelog entry to the `Unreleased` section in `CHANGELOG.md` - [ ] Re-reviewed `Files changed` in the Github PR explorer - [ ] Review `Codecov Report` in the comment section below once CI passes --- docs/.vuepress/config.js | 5 +++ .../interchain-accounts/active-channels.md | 4 +-- docs/apps/interchain-accounts/auth-modules.md | 2 +- docs/apps/interchain-accounts/development.md | 36 +++++++++++++++++++ 4 files changed, 44 insertions(+), 3 deletions(-) create mode 100644 docs/apps/interchain-accounts/development.md 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).