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.
crodriguezvega 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
womensrights marked this conversation as resolved.
Show resolved Hide resolved

- *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.
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved

- *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.
crodriguezvega 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
womensrights marked this conversation as resolved.
Show resolved Hide resolved

- *Whitelisiting 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 coontrolled remotely
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.

- Enable different account types, to be coontrolled remotely 
+ Enable different account types, to be controlled remotely

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
- Enable different account types, to be coontrolled remotely
Enable different account types, to be controlled remotely

- To facilitate performant cross-chain account management for accounts created on a per user basis
crodriguezvega 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.
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved

### 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.
crodriguezvega 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.
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved

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

## Features

### 1 - Configuration

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

### 2 - Registration

| ID | Description | Verification | Status |
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved
| -- | ----------- | ------------ | ------ |
| 2.01 | The controller of the interchain account must have authority over the account on the host chain to execute messages | ------------ | ------ |
crodriguezvega 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 |
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved
| -- | ----------- | ------------ | ------ |
| 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 | ------------ | ------ |
crodriguezvega 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 acknowledgement | ------------ | ------ |
Copy link
Contributor

Choose a reason for hiding this comment

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

Ensure consistency in the spelling of "acknowledgment".

- in the acknowledgement
+ in the acknowledgment

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
| 3.07 | A user can perform module safe queries through a host chain account and return the result in the acknowledgement | ------------ | ------ |
| 3.07 | A user can perform module safe queries through a host chain account and return the result in the acknowledgment | ------------ | ------ |


### 4 - Host execution

| ID | Description | Verification | Status |
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved
| -- | ----------- | ------------ | ------ |
| 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 |
crodriguezvega marked this conversation as resolved.
Show resolved Hide resolved
| -- | ----------- | ------------ | ------ |
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