From d4d1cc56695444029f8911be67981f1ba57a6687 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Mon, 26 Jun 2023 18:45:40 +0200 Subject: [PATCH] docs: improve upgrading.md and changelog for autocli changes --- CHANGELOG.md | 1 + UPGRADING.md | 82 +++++++++++++++++++++++++++------------------------- 2 files changed, 44 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 269c13c8c77a..e1d1e2c8fff2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -291,6 +291,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ ### CLI Breaking Changes +* (cli) The majority of Cosmos SDK modules now use [AutoCLI](https://docs.cosmos.network/main/building-modules/autocli) for their queries. Allowing for a more consistent CLI experience between modules and CLI and gRPC. These changes led to no changes in UX but a [small change in CLI outputs for some commands returning a JSON or a YAML](https://github.com/cosmos/cosmos-sdk/issues/16651). * (cli) [#15826](https://github.com/cosmos/cosmos-sdk/pull/15826) Remove ` q account` command. Use ` q auth account` instead. * (x/staking) [#14864](https://github.com/cosmos/cosmos-sdk/pull/14864) `create-validator` CLI command now takes a json file as an arg instead of having a bunch of required flags to it. * (cli) [#14659](https://github.com/cosmos/cosmos-sdk/pull/14659) ` q block ` is removed as it just output json. The new command allows either height/hash and is ` q block --type=height|hash `. diff --git a/UPGRADING.md b/UPGRADING.md index 0d025db81303..0ba194b304c1 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -51,16 +51,6 @@ allows an application to define handlers for these methods via `ExtendVoteHandle and `VerifyVoteExtensionHandler` respectively. Please see [here](https://docs.cosmos.network/v0.50/building-apps/vote-extensions) for more info. -### Configuration - -A new tool have been created for migrating configuration of the SDK. Use the following command to migrate your configuration: - -```bash -simd config migrate v0.50 -``` - -More information about [confix](https://docs.cosmos.network/main/tooling/confix). - #### Events The log section of `abci.TxResult` is not populated in the case of successful @@ -72,6 +62,16 @@ transaction. an added attribute, `mode=BeginBlock|EndBlock`, to identify if the event belongs to `BeginBlock` or `EndBlock`. +### Config files + +A new tool has been created for migrating configuration of the SDK. Use the following command to migrate your configuration: + +```bash +simd config migrate v0.50 +``` + +More information about [confix](https://docs.cosmos.network/main/tooling/confix) and how to add it in your application binary in the [documentation](https://docs.cosmos.network/main/tooling/confix). + #### gRPC-Web gRPC-Web is now listening to the same address as the gRPC Gateway API server (default: `localhost:1317`). @@ -82,13 +82,15 @@ Use `confix` to clean-up your `app.toml`. A nginx (or alike) reverse-proxy can b ClevelDB, BoltDB and BadgerDB are not supported anymore. To migrate from a unsupported database to a supported database please use the database migration tool. +**TODO: talk about db migration tool.** + ### Protobuf With the deprecation of the amino JSON codec defined in [cosmos/gogoproto](https://github.com/cosmos/gogoproto) in favor of the protoreflect powered x/tx/aminojson codec, module developers are encouraged verify that their messages have the correct protobuf annotations to deterministically produce identical output from both codecs. For core SDK types equivalence is asserted by generative testing of [SignableTypes](https://github.com/cosmos/cosmos-sdk/blob/76f0d101530ed78befc95506ab473c771d0d8a8c/tests/integration/rapidgen/rapidgen.go#L106) in [TestAminoJSON_Equivalence](https://github.com/cosmos/cosmos-sdk/blob/76f0d101530ed78befc95506ab473c771d0d8a8c/tests/integration/aminojson/aminojson_test.go#L90). -TODO: summarize proto annotation requirements. +**TODO: summarize proto annotation requirements.** #### Stringer @@ -97,14 +99,14 @@ The `gogoproto.goproto_stringer = false` annotation has been removed from most p ### SimApp - +In this section we describe the changes made in Cosmos SDK' SimApp. +These changes are directly applicable to your application wiring. #### Module Assertions -Previously, all modules were required to be set in `OrderBeginBlockers`, `OrderEndBlockers` and `OrderInitGenesis / OrderExportGenesis` in `app.go` / `app_config.go`. -This is no longer the case, the assertion has been loosened to only require modules implementing, respectively, the `module.BeginBlockAppModule`, `module.EndBlockAppModule` and `module.HasGenesis` interfaces. +Previously, all modules were required to be set in `OrderBeginBlockers`, `OrderEndBlockers` and `OrderInitGenesis / OrderExportGenesis` in `app.go` / `app_config.go`. This is no longer the case, the assertion has been loosened to only require modules implementing, respectively, the `module.BeginBlockAppModule`, `module.EndBlockAppModule` and `module.HasGenesis` interfaces. -#### Modules Keepers +#### Module wiring The following modules `NewKeeper` function now take a `KVStoreService` instead of a `StoreKey`: @@ -122,6 +124,8 @@ The following modules `NewKeeper` function now take a `KVStoreService` instead o * `x/slashing` * `x/upgrade` +**Users using `depinject` / app v2 do not need any changes, this is abstracted for them.** + Users manually wiring their chain need to use the `runtime.NewKVStoreService` method to create a `KVStoreService` from a `StoreKey`: ```diff @@ -133,27 +137,9 @@ app.ConsensusParamsKeeper = consensusparamkeeper.NewKeeper( ) ``` -The following modules' `Keeper` methods now take in a `context.Context` instead of `sdk.Context`. Any module that has an interfaces for them (like "expected keepers") will need to update and re-generate mocks if needed: - -* `x/authz` -* `x/bank` -* `x/mint` -* `x/crisis` -* `x/distribution` -* `x/evidence` -* `x/gov` -* `x/slashing` -* `x/upgrade` - -**Users using depinject do not need any changes, this is automatically done for them.** - #### Logger -The following modules `NewKeeper` function now take a `log.Logger`: - -* `x/bank` - -`depinject` users must now supply the logger through the main `depinject.Supply` function instead of passing it to `appBuilder.Build`. +`depinject` / app v2 users must now supply a logger through the main `depinject.Supply` function instead of passing it to `appBuilder.Build`. ```diff appConfig = depinject.Configs( @@ -170,14 +156,14 @@ appConfig = depinject.Configs( + app.App = appBuilder.Build(db, traceStore, baseAppOptions...) ``` -User manually wiring their chain need to add the logger argument when creating the keeper. +User manually wiring their chain need to add the logger argument when creating the `x/bank` keeper. #### Module Basics Previously, the `ModuleBasics` was a global variable that was used to register all modules's `AppModuleBasic` implementation. The global variable has been removed and the basic module manager can be now created from the module manager. -This is automatically done for depinject users, however for supplying different app module implementation, pass them via `depinject.Supply` in the main `AppConfig` (`app_config.go`): +This is automatically done for `depinject` / app v2 users, however for supplying different app module implementation, pass them via `depinject.Supply` in the main `AppConfig` (`app_config.go`): ```go depinject.Supply( @@ -197,9 +183,14 @@ Users manually wiring their chain need to use the new `module.NewBasicManagerFro ### Packages +#### Math + +References to `types/math.go` which contained aliases for math types aliasing the `cosmossdk.io/math` package have been removed. +Import directly the `cosmossdk.io/math` package instead. + #### Store -References to `types/store.go` which contained aliases for store types have been remapped to point to appropriate store/types, hence the `types/store.go` file is no longer needed and has been removed. +References to `types/store.go` which contained aliases for store types have been remapped to point to appropriate `store/types`, hence the `types/store.go` file is no longer needed and has been removed. ##### Extract Store to a standalone module @@ -218,7 +209,19 @@ The return type of the interface method `TxConfig.SignModeHandler()` has been ch The `sdk.Msg` interface has been updated to not require the implementation of the `ValidateBasic` method. It is now recommended to validate message directly in the message server. When the validation is performed in the message server, the `ValidateBasic` method on a message is no longer required and can be removed. -Messages no longer need to implement the `LegacyMsg` interface and implementations of `GetSignBytes` can be deleted. Because of this change, global legacy Amino codec definitions and their registration in `init()` can safely be removed as well. +Messages no longer need to implement the `LegacyMsg` interface and implementations of `GetSignBytes` can be deleted. Because of this change, global legacy Amino codec definitions and their registration in `init()` can safely be removed as well. + +The following modules' `Keeper` methods now take in a `context.Context` instead of `sdk.Context`. Any module that has an interfaces for them (like "expected keepers") will need to update and re-generate mocks if needed: + +* `x/authz` +* `x/bank` +* `x/mint` +* `x/crisis` +* `x/distribution` +* `x/evidence` +* `x/gov` +* `x/slashing` +* `x/upgrade` #### `x/auth` @@ -226,7 +229,7 @@ For ante handler construction via `ante.NewAnteHandler`, the field `ante.Handler #### `x/capability` -Capability was moved to [IBC-GO](https://github.com/cosmos/ibc-go). IBC V8 will contain the necessary changes to incorporate the new module location +Capability has been moved to [IBC-GO](https://github.com/cosmos/ibc-go). IBC v8 will contain the necessary changes to incorporate the new module location. #### `x/gov` @@ -257,6 +260,7 @@ All the evidence imports are now renamed to use `cosmossdk.io/x/evidence` instea ##### Extract nft to a standalone module The `x/nft` module is extracted to have a separate go.mod file which allows it to be a standalone module. +All the evidence imports are now renamed to use `cosmossdk.io/x/nft` instead of `github.com/cosmos/cosmos-sdk/x/nft` across the SDK. #### x/feegrant