Mukan Erkin Törük
6852832fe8
Some checks failed
CodeQL / Analyze (push) Waiting to run
Docker Build & Push Simapp (main) / docker-build (push) Waiting to run
golangci-lint / lint (push) Waiting to run
Tests / Code Coverage / build (amd64) (push) Waiting to run
Tests / Code Coverage / build (arm64) (push) Waiting to run
Tests / Code Coverage / unit-tests (map[additional-args:-tags="test_e2e" name:e2e path:./e2e]) (push) Waiting to run
Tests / Code Coverage / unit-tests (map[name:08-wasm path:./modules/light-clients/08-wasm]) (push) Waiting to run
Tests / Code Coverage / unit-tests (map[name:ibc-go path:.]) (push) Waiting to run
Deploy to GitHub Pages / Deploy to GitHub Pages (push) Has been cancelled
Buf-Push / push (push) Has been cancelled
221 lines
12 KiB
Markdown
221 lines
12 KiB
Markdown
---
|
|
title: IBC-Go v7 to v8
|
|
sidebar_label: IBC-Go v7 to v8
|
|
sidebar_position: 11
|
|
slug: /migrations/v7-to-v8
|
|
---
|
|
|
|
# Migrating from v7 to v8
|
|
|
|
This guide provides instructions for migrating to version `v8.0.0` of ibc-go.
|
|
|
|
There are four sections based on the four potential user groups of this document:
|
|
|
|
- [Migrating from v7 to v8](#migrating-from-v7-to-v8)
|
|
- [Chains](#chains)
|
|
- [Cosmos SDK v0.50 upgrade](#cosmos-sdk-v050-upgrade)
|
|
- [Authority](#authority)
|
|
- [Testing package](#testing-package)
|
|
- [Params migration](#params-migration)
|
|
- [Governance V1 migration](#governance-v1-migration)
|
|
- [Transfer migration](#transfer-migration)
|
|
- [IBC Apps](#ibc-apps)
|
|
- [ICS20 - Transfer](#ics20---transfer)
|
|
- [ICS27 - Interchain Accounts](#ics27---interchain-accounts)
|
|
- [Relayers](#relayers)
|
|
- [IBC Light Clients](#ibc-light-clients)
|
|
|
|
**Note:** ibc-go supports golang semantic versioning and therefore all imports must be updated on major version releases.
|
|
|
|
## Chains
|
|
|
|
The type of the `PortKeeper` field of the IBC keeper have been changed to `*portkeeper.Keeper`:
|
|
|
|
```diff
|
|
// Keeper defines each ICS keeper for IBC
|
|
type Keeper struct {
|
|
// implements gRPC QueryServer interface
|
|
types.QueryServer
|
|
|
|
cdc codec.BinaryCodec
|
|
|
|
ClientKeeper clientkeeper.Keeper
|
|
ConnectionKeeper connectionkeeper.Keeper
|
|
ChannelKeeper channelkeeper.Keeper
|
|
- PortKeeper portkeeper.Keeper
|
|
+ PortKeeper *portkeeper.Keeper
|
|
Router *porttypes.Router
|
|
|
|
authority string
|
|
}
|
|
```
|
|
|
|
See [this PR](https://github.com/cosmos/ibc-go/pull/4703/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a) for the changes required in `app.go`.
|
|
|
|
An extra parameter `totalEscrowed` of type `sdk.Coins` has been added to transfer module's [`NewGenesisState` function](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/types/genesis.go#L10). This parameter specifies the total amount of tokens that are in the module's escrow accounts.
|
|
|
|
### Cosmos SDK v0.50 upgrade
|
|
|
|
Version `v8.0.0` of ibc-go upgrades to Cosmos SDK v0.50. Please follow the [Cosmos SDK v0.50 upgrading guide](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/UPGRADING.md) to account for its API breaking changes.
|
|
|
|
### Authority
|
|
|
|
An authority identifier (e.g. an address) needs to be passed in the `NewKeeper` functions of the following keepers:
|
|
|
|
- You must pass the `authority` to the ica/host keeper (implemented in [#3520](https://github.com/cosmos/ibc-go/pull/3520)). See [diff](https://github.com/cosmos/ibc-go/pull/3520/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):
|
|
|
|
```diff
|
|
// app.go
|
|
|
|
// ICA Host keeper
|
|
app.ICAHostKeeper = icahostkeeper.NewKeeper(
|
|
appCodec, keys[icahosttypes.StoreKey], app.GetSubspace(icahosttypes.SubModuleName),
|
|
app.IBCFeeKeeper, // use ics29 fee as ics4Wrapper in middleware stack
|
|
app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
|
|
app.AccountKeeper, scopedICAHostKeeper, app.MsgServiceRouter(),
|
|
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
|
|
)
|
|
```
|
|
|
|
- You must pass the `authority` to the ica/controller keeper (implemented in [#3590](https://github.com/cosmos/ibc-go/pull/3590)). See [diff](https://github.com/cosmos/ibc-go/pull/3590/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):
|
|
|
|
```diff
|
|
// app.go
|
|
|
|
// ICA Controller keeper
|
|
app.ICAControllerKeeper = icacontrollerkeeper.NewKeeper(
|
|
appCodec, keys[icacontrollertypes.StoreKey], app.GetSubspace(icacontrollertypes.SubModuleName),
|
|
app.IBCFeeKeeper, // use ics29 fee as ics4Wrapper in middleware stack
|
|
app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
|
|
scopedICAControllerKeeper, app.MsgServiceRouter(),
|
|
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
|
|
)
|
|
```
|
|
|
|
- You must pass the `authority` to the ibctransfer keeper (implemented in [#3553](https://github.com/cosmos/ibc-go/pull/3553)). See [diff](https://github.com/cosmos/ibc-go/pull/3553/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):
|
|
|
|
```diff
|
|
// app.go
|
|
|
|
// Create Transfer Keeper and pass IBCFeeKeeper as expected Channel and PortKeeper
|
|
// since fee middleware will wrap the IBCKeeper for underlying application.
|
|
app.TransferKeeper = ibctransferkeeper.NewKeeper(
|
|
appCodec, keys[ibctransfertypes.StoreKey], app.GetSubspace(ibctransfertypes.ModuleName),
|
|
app.IBCFeeKeeper, // ISC4 Wrapper: fee IBC middleware
|
|
app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
|
|
app.AccountKeeper, app.BankKeeper, scopedTransferKeeper,
|
|
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
|
|
)
|
|
```
|
|
|
|
- You should pass the `authority` to the IBC keeper (implemented in [#3640](https://github.com/cosmos/ibc-go/pull/3640) and [#3650](https://github.com/cosmos/ibc-go/pull/3650)). See [diff](https://github.com/cosmos/ibc-go/pull/3640/files#diff-d18972debee5e64f16e40807b2ae112ddbe609504a93ea5e1c80a5d489c3a08a):
|
|
|
|
```diff
|
|
// app.go
|
|
|
|
// IBC Keepers
|
|
app.IBCKeeper = ibckeeper.NewKeeper(
|
|
appCodec,
|
|
keys[ibcexported.StoreKey],
|
|
app.GetSubspace(ibcexported.ModuleName),
|
|
app.StakingKeeper,
|
|
app.UpgradeKeeper,
|
|
scopedIBCKeeper,
|
|
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
|
|
)
|
|
```
|
|
|
|
The authority determines the transaction signer allowed to execute certain messages (e.g. `MsgUpdateParams`).
|
|
|
|
### Testing package
|
|
|
|
- The function `SetupWithGenesisAccounts` has been removed.
|
|
- The function [`RelayPacketWithResults`](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/path.go#L66) has been added. This function returns the result of the packet receive transaction, the acknowledgement written on the receiving chain, an error if a relay step fails or the packet commitment does not exist on either chain.
|
|
|
|
### Params migration
|
|
|
|
Params are now self managed in the following submodules:
|
|
|
|
- ica/controller [#3590](https://github.com/cosmos/ibc-go/pull/3590)
|
|
- ica/host [#3520](https://github.com/cosmos/ibc-go/pull/3520)
|
|
- ibc/connection [#3650](https://github.com/cosmos/ibc-go/pull/3650)
|
|
- ibc/client [#3640](https://github.com/cosmos/ibc-go/pull/3640)
|
|
- ibc/transfer [#3553](https://github.com/cosmos/ibc-go/pull/3553)
|
|
|
|
Each module has a corresponding `MsgUpdateParams` message with a `Params` which can be specified in full to update the modules' `Params`.
|
|
|
|
Legacy params subspaces must still be initialised in app.go in order to successfully migrate from `x/params`` to the new self-contained approach. See reference [this](https://github.com/cosmos/ibc-go/blob/v8.0.0/testing/simapp/app.go#L1007-L1012) for reference.
|
|
|
|
For new chains which do not rely on migration of parameters from `x/params`, an expected interface has been added for each module. This allows chain developers to provide `nil` as the `legacySubspace` argument to `NewKeeper` functions.
|
|
|
|
### Governance V1 migration
|
|
|
|
Proposals have been migrated to [gov v1 messages](https://docs.cosmos.network/v0.50/modules/gov#messages) (see [#4620](https://github.com/cosmos/ibc-go/pull/4620)). The proposal `ClientUpdateProposal` has been deprecated and [`MsgRecoverClient`](https://github.com/cosmos/ibc-go/blob/v8.0.0/proto/ibc/core/client/v1/tx.proto#L121-L134) should be used instead. Likewise, the proposal `UpgradeProposal` has been deprecated and [`MsgIBCSoftwareUpgrade`](https://github.com/cosmos/ibc-go/blob/v8.0.0/proto/ibc/core/client/v1/tx.proto#L139-L154) should be used instead. Both proposals will be removed in the next major release.
|
|
|
|
`MsgRecoverClient` and `MsgIBCSoftwareUpgrade` will only be allowed to be executed if the signer is the authority designated at the time of instantiating the IBC keeper. So please make sure that the correct authority is provided to the IBC keeper.
|
|
|
|
Remove the `UpgradeProposalHandler` and `UpdateClientProposalHandler` from the `BasicModuleManager`:
|
|
|
|
```diff
|
|
app.BasicModuleManager = module.NewBasicManagerFromManager(
|
|
app.ModuleManager,
|
|
map[string]module.AppModuleBasic{
|
|
genutiltypes.ModuleName: genutil.NewAppModuleBasic(genutiltypes.DefaultMessageValidator),
|
|
govtypes.ModuleName: gov.NewAppModuleBasic(
|
|
[]govclient.ProposalHandler{
|
|
paramsclient.ProposalHandler,
|
|
- ibcclientclient.UpdateClientProposalHandler,
|
|
- ibcclientclient.UpgradeProposalHandler,
|
|
},
|
|
),
|
|
})
|
|
```
|
|
|
|
Support for in-flight legacy recover client proposals (i.e. `ClientUpdateProposal`) will be made for v8, but chains should use `MsgRecoverClient` only afterwards to avoid in-flight client recovery failing when upgrading to v9. See [this issue](https://github.com/cosmos/ibc-go/issues/4721) for more information.
|
|
|
|
Please note that ibc-go offers facilities to test an ibc-go upgrade:
|
|
|
|
- All e2e tests of the repository can be [run with custom Docker chain images](https://github.com/cosmos/ibc-go/blob/c5bac5e03a0eae449b9efe0d312258115c1a1e85/e2e/README.md#running-tests-with-custom-images).
|
|
- An [importable workflow](https://github.com/cosmos/ibc-go/blob/c5bac5e03a0eae449b9efe0d312258115c1a1e85/e2e/README.md#importable-workflow) that can be used from any other repository to test chain upgrades.
|
|
|
|
### Transfer migration
|
|
|
|
An [automatic migration handler](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/module.go#L136) is configured in the transfer module to set the [denomination metadata](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/proto/cosmos/bank/v1beta1/bank.proto#L96-L125) for the IBC denominations of all vouchers minted by the transfer module.
|
|
|
|
## IBC Apps
|
|
|
|
### ICS20 - Transfer
|
|
|
|
- The function `IsBound` has been renamed to [`hasCapability`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/transfer/keeper/keeper.go#L98) and made unexported.
|
|
|
|
### ICS27 - Interchain Accounts
|
|
|
|
- Functions [`SerializeCosmosTx`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/types/codec.go#L32) and [`DeserializeCosmosTx`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/types/codec.go#L76) now accept an extra parameter `encoding` of type `string` that specifies the format in which the transaction messages are marshaled. Both [protobuf and proto3 JSON formats](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/types/metadata.go#L14-L17) are supported.
|
|
- The function `IsBound` of controller submodule has been renamed to [`hasCapability`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/controller/keeper/keeper.go#L111) and made unexported.
|
|
- The function `IsBound` of host submodule has been renamed to [`hasCapability`](https://github.com/cosmos/ibc-go/blob/v8.0.0/modules/apps/27-interchain-accounts/host/keeper/keeper.go#L94) and made unexported.
|
|
|
|
## Relayers
|
|
|
|
- Getter functions in `MsgChannelOpenInitResponse`, `MsgChannelOpenTryResponse`, `MsgTransferResponse`, `MsgRegisterInterchainAccountResponse` and `MsgSendTxResponse` have been removed. The fields can be accessed directly.
|
|
- `channeltypes.EventTypeTimeoutPacketOnClose` (where `channeltypes` is an import alias for `"github.com/cosmos/ibc-go/v8/modules/core/04-channel"`) has been removed, since core IBC does not emit any event with this key.
|
|
- Attribute with key `counterparty_connection_id` has been removed from event with key `connectiontypes.EventTypeConnectionOpenInit` (where `connectiontypes` is an import alias for `"github.com/cosmos/ibc-go/v8/modules/core/03-connection/types"`) and attribute with key `counterparty_channel_id` has been removed from event with key `channeltypes.EventTypeChannelOpenInit` (where `channeltypes` is an import alias for `"github.com/cosmos/ibc-go/v8/modules/core/04-channel"`) since both (counterparty connection ID and counterparty channel ID) are empty on `ConnectionOpenInit` and `ChannelOpenInit` respectively.
|
|
- As part of the migration to [governance V1 messages](#governance-v1-migration) the following changes in events have been made:
|
|
|
|
```diff
|
|
// IBC client events vars
|
|
var (
|
|
EventTypeCreateClient = "create_client"
|
|
EventTypeUpdateClient = "update_client"
|
|
EventTypeUpgradeClient = "upgrade_client"
|
|
EventTypeSubmitMisbehaviour = "client_misbehaviour"
|
|
- EventTypeUpdateClientProposal = "update_client_proposal"
|
|
- EventTypeUpgradeClientProposal = "upgrade_client_proposal"
|
|
+ EventTypeRecoverClient = "recover_client"
|
|
+ EventTypeScheduleIBCSoftwareUpgrade = "schedule_ibc_software_upgrade"
|
|
EventTypeUpgradeChain = "upgrade_chain"
|
|
)
|
|
```
|
|
|
|
## IBC Light Clients
|
|
|
|
- Functions `Pretty` and `String` of type `MerklePath` have been [removed](https://github.com/cosmos/ibc-go/pull/4459/files#diff-dd94ec1dde9b047c0cdfba204e30dad74a81de202e3b09ac5b42f493153811af).
|