Skip to content

Latest commit

 

History

History
113 lines (73 loc) · 6.66 KB

UPGRADING.md

File metadata and controls

113 lines (73 loc) · 6.66 KB
Raw

Upgrading Cosmos SDK

This guide provides instructions for upgrading to specific versions of Cosmos SDK.

[Unreleased]

AppModule Interface

Remove Querier, Route and LegacyQuerier from the app module interface. This removes and fully deprecates all legacy queriers. All modules no longer support the REST API previously known as the LCD, and the sdk.Msg#Route method won't be used anymore.

SimApp

SimApp's app.go is using App Wiring, the dependency injection framework of the Cosmos SDK. This means that modules are injected directly into SimApp thanks to a configuration file. The old behavior is preserved and still can be used, without the dependency injection framework, as shows app_legacy.go.

The constructor, NewSimApp has been simplified:

  • NewSimApp does not take encoding parameters (encodingConfig) as input, instead the encoding parameters are injected (when using app wiring), or directly created in the constructor. Instead, we can instantiate SimApp for getting the encoding configuration.
  • NewSimApp now uses AppOptions for getting the home path (homePath) and the invariant checks period (invCheckPeriod). These were unnecessary given as arguments as they were already present in the AppOptions.

Encoding

simapp.MakeTestEncodingConfig() was deprecated and has been removed. Instead you can use the TestEncodingConfig from the types/module/testutil package. This means you can replace your usage of simapp.MakeTestEncodingConfig in tests to moduletestutil.MakeTestEncodingConfig, which takes a series of relevant AppModuleBasic as input (the module being tested and any potential dependencies).

v0.46.x

Client Changes

x/gov v1

The gov module has been greatly improved. The previous API has been moved to v1beta1 while the new implementation is called v1.

In order to submit a proposal with submit-proposal you now need to pass a proposal.json file. You can still use the old way by using submit-legacy-proposal. This is not recommended. More information can be found in the gov module client documentation.

Keyring

The keyring has been refactored in v0.46.

  • The Unsafe* interfaces have been removed from the keyring package. Please use interface casting if you wish to access those unsafe functions.
  • The keys' implementation has been refactored to be serialized as proto.
  • keyring.NewInMemory and keyring.New takes now a codec.Codec.
  • Take keyring.Record instead of Info as first argument in: * MkConsKeyOutput * MkValKeyOutput * MkAccKeyOutput
  • Rename: * SavePubKey to SaveOfflineKey and remove the algo argument. * NewMultiInfo, NewLedgerInfo to NewLegacyMultiInfo, newLegacyLedgerInfo respectively. * NewOfflineInfo to newLegacyOfflineInfo and move it to migration_test.go.

Go API Changes

The replace google.golang.org/grpc directive can be removed from the go.mod, it is no more required to block the version.

A few packages that were deprecated in the previous version are now removed.

For instance, the REST API, deprecated in v0.45, is now removed. If you have not migrated yet, please follow the instructions.

To improve clarity of the API, some renaming and improvements has been done:

Package Previous Current
simapp encodingConfig.Marshaler encodingConfig.Codec
simapp FundAccount, FundModuleAccount Functions moved to x/bank/testutil
types AccAddressFromHex AccAddressFromHexUnsafe
x/auth MempoolFeeDecorator Use DeductFeeDecorator instead
x/bank AddressFromBalancesStore AddressAndDenomFromBalancesStore
x/gov keeper.DeleteDeposits keeper.DeleteAndBurnDeposits
x/gov keeper.RefundDeposits keeper.RefundAndDeleteDeposits
x/{mod} package legacy package migrations

For the exhaustive list of API renaming, please refer to the CHANGELOG.

new packages

Additionally, new packages have been introduced in order to further split the codebase. Aliases are available for a new API breaking migration, but it is encouraged to migrate to this new packages:

  • errors should replace types/errors when registering errors or wrapping SDK errors.
  • math contains the Int or Uint types that are used in the SDK.

x/authz

  • authz.NewMsgGrant expiration is now a pointer. When nil is used, then no expiration will be set (grant won't expire).
  • authz.NewGrant takes a new argument: block time, to correctly validate expire time.

State Machine Changes

PostHandler

postHandler is like an antehandler, but is run after the runMsgs execution. It is in the same store branch that runMsgs, meaning that both runMsgs and postHandler. This allows to run a custom logic after the execution of the messages.

IAVL

v0.19.0 IAVL introduces a new "fast" index. This index represents the latest state of the IAVL laid out in a format that preserves data locality by key. As a result, it allows for faster queries and iterations since data can now be read in lexicographical order that is frequent for Cosmos-SDK chains.

The first time the chain is started after the upgrade, the aforementioned index is created. The creation process might take time and depends on the size of the latest state of the chain. For example, Osmosis takes around 15 minutes to rebuild the index.

While the index is being created, node operators can observe the following in the logs: "Upgrading IAVL storage for faster queries + execution on the live state. This may take a while". The store key is appended to the message. The message is printed for every module that has a non-transient store. As a result, it gives a good indication of the progress of the upgrade.

There is also downgrade and re-upgrade protection. If a node operator chooses to downgrade to IAVL pre-fast index, and then upgrade again, the index is rebuilt from scratch. This implementation detail should not be relevant in most cases. It was added as a safeguard against operator mistakes.