docs: update to v0.44 migration (#10070)
## Description <!-- Add a description of the changes that this PR introduces and the files that are the most critical to review. --> This pull request updates the migration documentation to v0.44. Also, this pull request alongside #10069 closes #9998. --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct `docs:` prefix in the PR title - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] provided a link to the relevant issue or specification - [x] followed the [documentation writing guidelines](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOC_WRITING_GUIDELINES.md) - [x] reviewed "Files changed" and left comments if necessary - [x] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct `docs:` prefix in the PR title - [ ] confirmed all author checklist items have been addressed - [ ] confirmed that this PR only changes documentation - [ ] reviewed content for consistency - [ ] reviewed content for thoroughness - [ ] reviewed content for spelling and grammar - [ ] tested instructions (if applicable)
This commit is contained in:
Ryan Christoffersen
GitHub
parent
744c85b8fa
commit
37dbfeca6b
|
|
@ -14,7 +14,7 @@ The Cosmos SDK uses two methods to perform upgrades.
|
|||
|
||||
- Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. See [Chain Upgrade Guide to v0.42](https://docs.cosmos.network/v0.42/migrations/chain-upgrade-guide-040.html).
|
||||
|
||||
- Version v0.43 and later can perform upgrades in place to significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/upgrade.md) to set up your application modules to take advantage of in-place upgrades.
|
||||
- Version v0.44 and later can perform upgrades in place to significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/upgrade.md) to set up your application modules to take advantage of in-place upgrades.
|
||||
|
||||
This document provides steps to use the In-Place Store Migrations upgrade method.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,10 +6,7 @@ parent:
|
|||
|
||||
# Migrations
|
||||
|
||||
This folder contains all the migration guides to update your app and modules to Cosmos v0.40 Stargate.
|
||||
This folder contains all the migration guides to update your app and modules to Cosmos SDK v0.44.
|
||||
|
||||
1. [App and Modules Migration](./app_and_modules.md)
|
||||
1. [Pre Upgrade](./pre-upgrade.md)
|
||||
1. [Chain Upgrade Guide to v0.40](./chain-upgrade-guide-040.md)
|
||||
1. [REST Endpoints Migration](./rest.md)
|
||||
1. [Keyring Migration](./keyring.md)
|
||||
1. [Chain Upgrade Guide to v0.44](./chain-upgrade-guide-044.md)
|
||||
2. [REST Endpoints Migration](./rest.md)
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
order: 1
|
||||
-->
|
||||
|
||||
# Chain Upgrade Guide to v0.43
|
||||
# Chain Upgrade Guide to v0.44
|
||||
|
||||
This document provides guidelines for a chain upgrade from v0.42 to v0.43 and an example of the upgrade process using `simapp`. {synopsis}
|
||||
This document provides guidelines for a chain upgrade from v0.42 to v0.44 and an example of the upgrade process using `simapp`. {synopsis}
|
||||
|
||||
::: tip
|
||||
You must upgrade to Stargate v0.42 before upgrading to v0.43. If you have not done so, please see [Chain Upgrade Guide to v0.42](/v0.42/migrations/chain-upgrade-guide-040.html).
|
||||
You must upgrade to Stargate v0.42 before upgrading to v0.44. If you have not done so, please see [Chain Upgrade Guide to v0.42](/v0.42/migrations/chain-upgrade-guide-040.html). Please note, v0.43 was discontinued shortly after being released and all chains should upgrade directly to v0.44 from v0.42.
|
||||
:::
|
||||
|
||||
## Prerequisite Readings
|
||||
|
|
@ -16,17 +16,17 @@ You must upgrade to Stargate v0.42 before upgrading to v0.43. If you have not do
|
|||
- [In-Place Store Migrations](../core/upgrade.html) {prereq}
|
||||
- [Cosmovisor](../run-node/cosmovisor.html) {prereq}
|
||||
|
||||
Cosmos SDK v0.43 introduces a new way of handling chain upgrades that no longer requires exporting state to JSON, making the necesssary changes, and then creating a new chain with the modified JSON as the new genesis file.
|
||||
Cosmos SDK v0.44 introduces a new way of handling chain upgrades that no longer requires exporting state to JSON, making the necesssary changes, and then creating a new chain with the modified JSON as the new genesis file.
|
||||
|
||||
Instead of starting a new chain, the upgrade binary will read the existing database and perform in-place store migrations. This new way of handling chain upgrades can be used alongside [Cosmovisor](../run-node/cosmovisor.html) to make the upgrade process seamless.
|
||||
|
||||
## In-Place Store Migrations
|
||||
|
||||
We recommend using [In-Place Store Migrations](../core/upgrade.html) to upgrade your chain from v0.42 to v0.43. The first step is to make sure all your modules follow the [Module Upgrade Guide](../building-modules/upgrade.html). The second step is to add an [upgrade handler](../core/upgrade.html#running-migrations) to `app.go`.
|
||||
We recommend using [In-Place Store Migrations](../core/upgrade.html) to upgrade your chain from v0.42 to v0.44. The first step is to make sure all your modules follow the [Module Upgrade Guide](../building-modules/upgrade.html). The second step is to add an [upgrade handler](../core/upgrade.html#running-migrations) to `app.go`.
|
||||
|
||||
In this document, we'll provide an example of what the upgrade handler looks like for a chain upgrading module versions for the first time. It's critical to note that the initial consensus version of each module must be set to `1` rather than `0` or else the upgrade handler will re-initialize each module.
|
||||
|
||||
In addition to migrating existing modules, the upgrade handler also performs store upgrades for new modules. In the example below, we'll be adding store migrations for two new modules made available in v0.43: `x/authz` and `x/feegrant`.
|
||||
In addition to migrating existing modules, the upgrade handler also performs store upgrades for new modules. In the example below, we'll be adding store migrations for two new modules made available in v0.44: `x/authz` and `x/feegrant`.
|
||||
|
||||
## Using Cosmovisor
|
||||
|
||||
|
|
@ -40,11 +40,11 @@ Validators can use the auto-restart option to prevent unnecessary downtime durin
|
|||
|
||||
## Migrating app.toml
|
||||
|
||||
With the update to `v0.43`, new server configuration options have been added to `app.toml`. The updates include new configuration sections for Rosetta and gRPC Web as well as a new configuration option for State Sync. Check out the default [`app.toml`](https://github.com/cosmos/cosmos-sdk/blob/release/v0.43.x/server/config/toml.go) file in the latest version of `v0.43` for more information.
|
||||
With the update to `v0.44`, new server configuration options have been added to `app.toml`. The updates include new configuration sections for Rosetta and gRPC Web as well as a new configuration option for State Sync. Check out the default [`app.toml`](https://github.com/cosmos/cosmos-sdk/blob/release/v0.44.x/server/config/toml.go) file in the latest version of `v0.44` for more information.
|
||||
|
||||
## Example: Simapp Upgrade
|
||||
|
||||
The following example will walk through the upgrade process using `simapp` as our blockchain application. We will be upgrading `simapp` from v0.42 to v0.43. We will be building the upgrade binary ourselves and enabling the auto-restart option.
|
||||
The following example will walk through the upgrade process using `simapp` as our blockchain application. We will be upgrading `simapp` from v0.42 to v0.44. We will be building the upgrade binary ourselves and enabling the auto-restart option.
|
||||
|
||||
::: tip
|
||||
In the following example, we start a new chain from `v0.42`. The binary for this version will be the genesis binary. For validators using Cosmovisor for the first time on an existing chain, either the binary for the current version of the chain should be used as the genesis binary (i.e. the starting binary) or validators should update the `current` symbolic link to point to the upgrade directory. For more information, see [Cosmovisor](../run-node/cosmovisor.html).
|
||||
|
|
@ -148,12 +148,12 @@ Now that `cosmovisor` is installed and the genesis binary has been added, let's
|
|||
|
||||
### Chain Upgrade
|
||||
|
||||
<!-- TODO: update example to use v0.43.x -->
|
||||
<!-- TODO: update example to use v0.44.x -->
|
||||
|
||||
Check out `release/v0.43.x`:
|
||||
Check out `release/v0.44.x`:
|
||||
|
||||
```
|
||||
git checkout release/v0.43.x
|
||||
git checkout release/v0.44.x
|
||||
```
|
||||
|
||||
Add the following to `simapp/app.go` inside `NewSimApp` and after `app.UpgradeKeeper`:
|
||||
|
|
@ -166,7 +166,7 @@ Add the following to `simapp/app.go` after `NewSimApp` (to learn more about the
|
|||
|
||||
```go
|
||||
func (app *SimApp) registerUpgradeHandlers() {
|
||||
app.UpgradeKeeper.SetUpgradeHandler("v0.43", func(ctx sdk.Context, plan upgradetypes.Plan, _ module.VersionMap) (module.VersionMap, error) {
|
||||
app.UpgradeKeeper.SetUpgradeHandler("v0.44", func(ctx sdk.Context, plan upgradetypes.Plan, _ module.VersionMap) (module.VersionMap, error) {
|
||||
// 1st-time running in-store migrations, using 1 as fromVersion to
|
||||
// avoid running InitGenesis.
|
||||
fromVM := map[string]uint64{
|
||||
|
|
@ -196,7 +196,7 @@ func (app *SimApp) registerUpgradeHandlers() {
|
|||
panic(err)
|
||||
}
|
||||
|
||||
if upgradeInfo.Name == "v0.43" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) {
|
||||
if upgradeInfo.Name == "v0.44" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) {
|
||||
storeUpgrades := storetypes.StoreUpgrades{
|
||||
Added: []string{"authz", "feegrant"},
|
||||
}
|
||||
|
|
@ -213,17 +213,17 @@ Add `storetypes` to imports:
|
|||
storetypes "github.com/cosmos/cosmos-sdk/store/types"
|
||||
```
|
||||
|
||||
Build the `simd` binary for `v0.43.x` (the upgrade binary):
|
||||
Build the `simd` binary for `v0.44.x` (the upgrade binary):
|
||||
|
||||
```
|
||||
make build
|
||||
```
|
||||
|
||||
Create the folder for the upgrade binary and copy the `v0.43.x` binary:
|
||||
Create the folder for the upgrade binary and copy the `v0.44.x` binary:
|
||||
|
||||
```
|
||||
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v0.43/bin
|
||||
cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/v0.43/bin
|
||||
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v0.44/bin
|
||||
cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/v0.44/bin
|
||||
```
|
||||
|
||||
Now that we have added the upgrade handler and prepared the upgrade binary, we are ready to start `cosmovisor` and simulate the upgrade proposal process.
|
||||
|
|
@ -239,7 +239,7 @@ cosmovisor start
|
|||
Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other):
|
||||
|
||||
```
|
||||
./build/simd tx gov submit-proposal software-upgrade v0.43 --title upgrade --description upgrade --upgrade-height 20 --from validator --yes
|
||||
./build/simd tx gov submit-proposal software-upgrade v0.44 --title upgrade --description upgrade --upgrade-height 20 --from validator --yes
|
||||
./build/simd tx gov deposit 1 10000000stake --from validator --yes
|
||||
./build/simd tx gov vote 1 yes --from validator --yes
|
||||
```
|
||||
|
|
@ -4,11 +4,15 @@ order: 2
|
|||
|
||||
# REST Endpoints Migration
|
||||
|
||||
Migrate to gRPC-Gateway REST endpoints. Legacy REST endpoints were marked as deprecated in v0.40 and removed in v0.44. {synopsis}
|
||||
Migrate to gRPC-Gateway REST endpoints. Legacy REST endpoints were marked as deprecated in v0.40 and will be removed in v0.45. {synopsis}
|
||||
|
||||
::: warning
|
||||
Two Legacy REST endpoints (`POST /txs` and `POST /txs/encode`) were removed ahead of schedule in v0.44 due to a security vulnerability.
|
||||
:::
|
||||
|
||||
## Legacy REST Endpoints
|
||||
|
||||
Cosmos SDK versions v0.39 and earlier registered REST endpoints using a package called `gorilla/mux`. These REST endpoints were marked as deprecated in v0.40 and have since been referred to as legacy REST endpoints. Legacy REST endpoints were officially removed in v0.44.
|
||||
Cosmos SDK versions v0.39 and earlier registered REST endpoints using a package called `gorilla/mux`. These REST endpoints were marked as deprecated in v0.40 and have since been referred to as legacy REST endpoints. Legacy REST endpoints will be officially removed in v0.45.
|
||||
|
||||
## gRPC-Gateway REST Endpoints
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue