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.

Sign up for GitHub

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

docs(CIP-14): define proposed param values #96

Merged
merged 2 commits into from
Mar 13, 2024
Merged

docs(CIP-14): define proposed param values #96

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d4bf78
docs: define proposed param values
rootulp Mar 6, 2024
46dd758
chore: summary -> description
rootulp Mar 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 29 additions & 19 deletions cips/cip-14.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
cip: 14
title: ICS-27 Interchain Accounts
title: ICS-27 Interchain Accounts
description: Adding ICS-27 Interchain Accounts to Celestia to enable cross-chain account management
author: Susannah Evans <[email protected]> (@womensrights), Aidan Salzmann <[email protected]> (@asalzmann), Sam Pochyly <[email protected]> (@sampocs)
discussions-to: https://forum.celestia.org/t/moving-toward-safer-and-more-aligned-tia-liquid-staking/1422
Expand Down Expand Up @@ -28,39 +28,48 @@ By enabling ICA on an accelerated timeline, Celestia can enable battle-tested pr

## Specification

For context, both the host and controller module specification are described below; however, this proposal is to integrate only the host module. For the full technical specification, see the [ICS-27 spec](https://github.com/cosmos/ibc/tree/main/spec/app/ics-027-interchain-accounts) in the ibc protocol repository.
For context, both the host and controller module specification are described below; however, this proposal is to integrate only the host module. For the full technical specification, see the [ICS-27 spec](https://github.com/cosmos/ibc/tree/main/spec/app/ics-027-interchain-accounts) in the ibc protocol repository.

Adoption of the host module implies the addition of new parameters:

### Definitions
| Module.Parameter | Proposed value | Summary | Changeable via Governance |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
| icahost.HostEnabled | `true` | Controls a chains ability to service ICS-27 host specific logic. | False |
| icahost.AllowMessages | `["/ibc.applications.transfer.v1.MsgTransfer", "/cosmos.bank.v1beta1.MsgSend", "/cosmos.staking.v1beta1.MsgDelegate", "/cosmos.staking.v1beta1.MsgBeginRedelegate", "/cosmos.staking.v1beta1.MsgUndelegate", "/cosmos.staking.v1beta1.MsgCancelUnbondingDelegation", "/cosmos.distribution.v1beta1.MsgSetWithdrawAddress", "/cosmos.distribution.v1beta1.MsgWithdrawDelegatorReward", "/cosmos.distribution.v1beta1.MsgFundCommunityPool", "/cosmos.gov.v1.MsgVote"]` | Provides the ability for a chain to limit the types of messages or transactions that hosted interchain accounts are authorized to execute by defining an allowlist using the Protobuf message type URL format. | False |
Copy link
Collaborator

Choose a reason for hiding this comment

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

Thanks for the table!

False

Should this be False? Potentially there may be desire to add more in the future?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I expect more messages to be added to this list in the future but IMO this list should be expanded via the CIP process rather than on-chain governance.


### Definitions

- `Host Chain`: The chain where the interchain account is registered. The host chain listens for IBC packets from a controller chain which contain instructions (e.g. cosmos SDK messages) that the interchain account will execute.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Just realized a lot of this text is copied verbatim from the ICS27 spec in https://github.com/cosmos/ibc/tree/main/spec/app/ics-027-interchain-accounts . I think its good to have it here but maybe worth noting its a direct copy?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

can do!

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

On re-read ICS-27 is linked here so defer to the CIP authors if they want to cite it again.

- `Controller Chain`: The chain registering and controlling an account on a host chain. The controller chain sends IBC packets to the host chain to control the account.
- `Interchain Account`: An account on a host chain. An interchain account has all the capabilities of a normal account. However, rather than signing transactions with a private key, a controller chain will send IBC packets to the host chain which signals what transactions the interchain account must execute.
- `Interchain Account Owner`: An account on the controller chain. Every interchain account on a host chain has a respective owner account on the controller chain.
- `Interchain Account`: An account on a host chain. An interchain account has all the capabilities of a normal account. However, rather than signing transactions with a private key, a controller chain will send IBC packets to the host chain which signals what transactions the interchain account must execute.
- `Interchain Account Owner`: An account on the controller chain. Every interchain account on a host chain has a respective owner account on the controller chain.

The IBC handler interface & IBC relayer module interface are as defined in [ICS-25](../../core/ics-025-handler-interface) and [ICS-26](../../core/ics-026-routing-module), respectively.

### General design
### General design

A chain can utilize one or both parts of the interchain accounts protocol (*controlling* and *hosting*). A controller chain that registers accounts on other host chains (that support interchain accounts) does not necessarily have to allow other controller chains to register accounts on its chain, and vice versa.
A chain can utilize one or both parts of the interchain accounts protocol (*controlling* and *hosting*). A controller chain that registers accounts on other host chains (that support interchain accounts) does not necessarily have to allow other controller chains to register accounts on its chain, and vice versa.

This specification defines the general way to register an interchain account and send tx bytes to be executed on behalf of the owner account. The host chain is responsible for deserializing and executing the tx bytes and the controller chain must know how the host chain will handle the tx bytes in advance of sending a packet, thus this must be negotiated during channel creation.

### High level flow

#### Registering an Account

1. The controller chain binds a new IBC port for a given *interchain account owner*
2. The controller chain creates a new IBC channel for the associated account owner. Only the owner is authorized to send packets over the channel.
3. During the channel handshake, the host chain registers an *interchain account address* that is mapped to the account owner on the controller chain

#### Submitting Transactions

1. The controller chain serializes messages and sends them along the channel associated with the account
2. The host chain receives the IBC packet and deserializes the message
3. The host chain authenticates the transaction by retrieving the relevant address from the controller's portID, and confirming it matches the signer of the message
4. The host chain checks that each message type is whitelisted and executes the transaction

### Integration of host module

The interchain accounts module should be registered as an `AppModule` in the same way all SDK modules are registered on a chain, as well as an `IBCModule`.
The interchain accounts module should be registered as an `AppModule` in the same way all SDK modules are registered on a chain, as well as an `IBCModule`.

```go
// app.go
Expand All @@ -72,7 +81,7 @@ ModuleBasics = module.NewBasicManager(
...
)

...
...

// Add module account permissions for the Interchain Accounts module
// Only necessary for host chain functionality
Expand All @@ -85,7 +94,7 @@ maccPerms = map[string][]string{
...

// Add Interchain Accounts Keepers for each submodule used and the authentication module
// If a submodule is being statically disabled, the associated Keeper does not need to be added.
// If a submodule is being statically disabled, the associated Keeper does not need to be added.
type App struct {
...
ICAHostKeeper icahostkeeper.Keeper
Expand All @@ -101,7 +110,7 @@ keys := sdk.NewKVStoreKeys(
...
)

...
...

// Create the scoped keepers for the host submodule
scopedICAHostKeeper := app.CapabilityKeeper.ScopeToModule(icahosttypes.SubModuleName)
Expand All @@ -120,7 +129,7 @@ app.ICAHostKeeper = icahostkeeper.NewKeeper(
// Since only the host module is registered, nil is passed as the controller keeper
icaModule := ica.NewAppModule(nil, &app.ICAHostKeeper)

// Create a host IBC module
// Create a host IBC module
icaHostIBCModule := icahost.NewIBCModule(app.ICAHostKeeper)

// Register host route
Expand Down Expand Up @@ -166,22 +175,23 @@ func initParamsKeeper(appCodec codec.BinaryCodec, legacyAmino *codec.LegacyAmino
```

### Host module parameters
| Key | Type | Default Value |
|------------------------|----------|---------------|
| `HostEnabled` | bool | `true` |
| `AllowMessages` | []string | `["*"]` |

| Key | Type | Default Value |
|-----------------|----------|---------------|
| `HostEnabled` | bool | `true` |
| `AllowMessages` | []string | `["*"]` |

#### HostEnabled

The `HostEnabled` parameter controls a chain's ability to service ICS-27 host specific logic.
The `HostEnabled` parameter controls a chain's ability to service ICS-27 host specific logic.

#### AllowMessages

The `AllowMessages` parameter provides the ability for a chain to limit the types of messages or transactions that hosted interchain accounts are authorized to execute by defining an allowlist using the Protobuf message type URL format.

For example, a Cosmos SDK-based chain that elects to provide hosted Interchain Accounts with the ability of staking and unstaking will define its parameters as follows:

```
```json
"params": {
"host_enabled": true,
"allow_messages": ["/cosmos.staking.v1beta1.MsgDelegate", "/cosmos.staking.v1beta1.MsgUndelegate"]
Expand All @@ -190,7 +200,7 @@ For example, a Cosmos SDK-based chain that elects to provide hosted Interchain A

There is also a special wildcard `"*"` value which allows any type of message to be executed by the interchain account. This must be the only value in the `allow_messages` array.

```
```json
"params": {
"host_enabled": true,
"allow_messages": ["*"]
Expand Down
Loading