Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create ics27-multiplexed-requirements.md #6281

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
101 changes: 101 additions & 0 deletions docs/requirements/ics27-multiplexed-requirements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
<!-- More detailed information about the requirements engineering process can be found at https://github.com/cosmos/ibc-go/wiki/Requirements-engineering -->

# Business requirements

The Interchain Accounts feature has enabled control of an account on a host chain remotely from a controller chain. This has opened up many possibilities for more complex cross-chain workflows beyond token transfer alone, but the current architecture is not easy to use for the case where there are on the order of 1000s of host accounts controlled by many controllers. These requirements aim to alleviate current pain points and enhance the usability of the feature.
womensrights marked this conversation as resolved.
Show resolved Hide resolved

## Problem

The current pain points for existing ICA users are listed:

- *Account Flexibility* - Currently host accounts can only be of type `BaseAccount`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a comma after "listed" for better readability.

- The current pain points for existing ICA users are listed:
+ The current pain points for existing ICA users are listed:

Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.

Suggested change
- *Account Flexibility* - Currently host accounts can only be of type `BaseAccount`


- *Ordered Channels* - Timeouts and subsequent channel closures are time-consuming and difficult to manage

- *Scalability* - When there are many interchain accounts, and many channels (in the order of 1000s), relayers struggle with the number of queries on startup and performance is compromised. Additionally, account registration being linked to the channel means that multiple packet round trips are required before your host account can execute messages.

- *Workflows requiring tokens in ICA* - there are no atomic guarantees for a workflow containing multiple applications - i.e. a token transfer followed by an ICA message. The transfer could succeed and the ICA message fail, resulting in an incomplete workflow.
womensrights marked this conversation as resolved.
Show resolved Hide resolved

- *Lack of default callbacks* - users are still relying on custom auth modules for packet callbacks, the callbacks middleware solves this problem but is an add-on to the application rather than a default

*Whitelisting messages* - this devex is more complicated than having a blacklist
womensrights marked this conversation as resolved.
Show resolved Hide resolved

## Objectives

Enable different account types, to be controlled remotely
womensrights marked this conversation as resolved.
Show resolved Hide resolved
- To facilitate performant cross-chain account management for accounts created on a per-user basis

Check failure on line 26 in docs/requirements/ics27-multiplexed-requirements.md

View workflow job for this annotation

GitHub Actions / lint

Lists should be surrounded by blank lines

docs/requirements/ics27-multiplexed-requirements.md:26 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- To facilitate performant cro..."] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md032.md
womensrights marked this conversation as resolved.
Show resolved Hide resolved
- To streamline workflows using token transfer and interchain accounts in combination

## Scope

| Features | Release |
| --------- | ------- |
| Multi-plexed Interchain Accounts | ibc-go v10.0.0 |

# User requirements

## Use cases

Existing use cases have been detailed in ics27 and ics27 v2 requirements, some other notable use cases used in production are cross chain liquid staking, yield through leveraged lending and cross chain NFT minting.

### Liquid Staking

Chains such as Stride, Quicksilver and pStake control Interchain Accounts on a host chain to stake tokens on behalf of their users and mint representative liquid staking tokens so that users can transact with liquid tokens, rather than a locked staked asset but still earn staking rewards through autocompounding on the Interchain Account. More information on Stride's technical architecture can be found [here](https://github.com/Stride-Labs/stride/tree/main?tab=readme-ov-file#strides-technical-architecture).

### Leveraged Lending

Nolus enables users to borrow assets and use the inflation from staking rewards to repay the interest on the principle. e.g. a user could deposit 10 OSMO as collatoral for a 25 OSMO position. When a user opens a position, an Interchain Account is opened on Osmosis and the loan amount is sent to the account with management of the account through the Nolus chain.
womensrights marked this conversation as resolved.
Show resolved Hide resolved

### Cross-chain NFT minting

Nomos enable NFTs to be minted on Injective on host accounts controlled from the Xion chain, providing a single interface for users, enabling chain abstraction.

womensrights marked this conversation as resolved.
Show resolved Hide resolved
# Functional requirements

## Assumptions and dependencies

- Although having atomic transfer plus action workflows with Interchain Accounts is desirable, it is out of scope for these requirements, as a solution is applicable to applications beyond Interchain Accounts alone.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove trailing space at the end of the line.

- Although having atomic transfer plus action workflows with Interchain Accounts is desirable, it is out of scope for these requirements, as a solution is applicable to applications beyond Interchain Accounts alone. 
+ Although having atomic transfer plus action workflows with Interchain Accounts is desirable, it is out of scope for these requirements, as a solution is applicable to applications beyond Interchain Accounts alone.

Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.

Suggested change
- Although having atomic transfer plus action workflows with Interchain Accounts is desirable, it is out of scope for these requirements, as a solution is applicable to applications beyond Interchain Accounts alone.
Although having atomic transfer plus action workflows with Interchain Accounts is desirable, it is out of scope for these requirements, as a solution is applicable to applications beyond Interchain Accounts alone.

Migration of an existing Interchain Account using a prior version of Interchain Accounts that does not satisfy these requirements is not required.
womensrights marked this conversation as resolved.
Show resolved Hide resolved
- Assumes use of the `x/accounts` sdk module.

## Features

### 1 - Configuration

| ID | Description | Verification | Status |
| -- | ----------- | ------------ | ------ |
| 1.01 | The host chain should accept all message types by default and maintain a blacklist of message types it does not permit | ------------ | ------ |
womensrights marked this conversation as resolved.
Show resolved Hide resolved

### 2 - Registration

| ID | Description | Verification | Status |
| -- | ----------- | ------------ | ------ |
| 2.01 | The controller of the interchain account must have authority over the account on the host chain to execute messages | -- | ----------- | ------------ | ------ |

Check failure on line 73 in docs/requirements/ics27-multiplexed-requirements.md

View workflow job for this annotation

GitHub Actions / lint

Table column count

docs/requirements/ics27-multiplexed-requirements.md:73:145 MD056/table-column-count Table column count [Expected: 4; Actual: 6; Too many cells, extra data will be missing] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md056.md
womensrights marked this conversation as resolved.
Show resolved Hide resolved
| 2.02 | A registered interchain account can be any account type supported by `x/accounts` | ------------ | ------ |

### 3 - Control

| ID | Description | Verification | Status |
| -- | ----------- | ------------ | ------ |
| 3.01 | The channel type through which a controller sends transactions to the host should be unordered | ------------ | ------ |
| 3.02 | The message execution order should be determined at the packet level | ------------ | ------ |
| 3.03 | Many controllers can send messages to many host accounts through the same channel | ------------ | ------ |
| 3.04 | The controller of the interchain account should be able to receive information about the balance of the interchain account in the acknowledgment after a transaction was executed by the host | ------------ | ------ |
| 3.05 | The user of the controller should be able to receive all the information contained in the acknowledgment without implementing additional middleware on a per-user basis | ------------ | ------ |
womensrights marked this conversation as resolved.
Show resolved Hide resolved
| 3.06 | Callbacks on the packet lifecycle should be supported by default | ------------ | ------ |
| 3.07 | A user can perform module safe queries through a host chain account and return the result in the acknowledgment | ------------ | ------ |
womensrights marked this conversation as resolved.
Show resolved Hide resolved

### 4 - Host execution

| ID | Description | Verification | Status |
| -- | ----------- | ------------ | ------ |
| 4.01 | It should be possible to ensure a packet lifecycle from a different application completes before a message from a controller is executed | ------------ | ------ |
| 4.02 | It should be possible for a controller to authorise a host account to execute specific actions on a host chain without needing a packet round trip each time (e.g. auto-compounding) | ------------ | ------ |

# Non-functional requirements

## 5 - Performance

| ID | Description | Verification | Status |
| -- | ----------- | ------------ | ------ |
womensrights marked this conversation as resolved.
Show resolved Hide resolved
| 5.01 | The number of packet round trips to register an account, load the account with tokens and execute messages on the account should be minimised | ------------ | ------ |
Loading