From 23e56dd7f8848600713ce3ce964859e08eb8e100 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Federico=20Kunze=20K=C3=BCllmer?= <31522760+fedekunze@users.noreply.github.com> Date: Wed, 11 May 2022 12:28:37 +0200 Subject: [PATCH] docs: v4 upgrade documentation (#599) * docs: add v4 documentation * update upgrade guide * fix lint --- .gitignore | 3 +++ docs/.vuepress/config.js | 2 +- docs/developers/explorers.md | 23 +++++++++------- docs/validators/mainnet.md | 2 +- docs/validators/testnet.md | 2 +- docs/validators/upgrades/overview.md | 39 ++++++++++++++++++++++++---- docs/validators/upgrades/upgrades.md | 32 +++++++++++++---------- 7 files changed, 72 insertions(+), 31 deletions(-) diff --git a/.gitignore b/.gitignore index 254263341a..dc86154bb8 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,9 @@ docs/_build docs/tutorial docs/node_modules docs/modules +docs/cosmos-sdk +docs/ethermint +docs/ibc-go dist tools-stamp docs-tools-stamp diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index edc6aee3dc..218574f904 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -62,7 +62,7 @@ module.exports = { rpc_url_local: 'http://localhost:8545/', chain_id: '9001', testnet_chain_id: '9000', - latest_version: 'v3.0.0-beta1', + latest_version: 'v4.0.1', version_number: '2', testnet_version_number: '4', testnet_evm_explorer_url: 'https://evm.evmos.dev', diff --git a/docs/developers/explorers.md b/docs/developers/explorers.md index d0285d8c32..38948642c2 100644 --- a/docs/developers/explorers.md +++ b/docs/developers/explorers.md @@ -19,19 +19,22 @@ Below is a list of public block explorers that support Evmos Mainnet and Testnet :::: tabs ::: tab Mainnet -| | Category | URL | -| -------------------- | -------- | ---------------------- | -| Blockscout | `evm` | [evm.evmos.org](https://evm.evmos.org/) | -| Mintscan | `cosmos` | [explorer.evmos.org](https://explorer.evmos.org/) | +| | Category | URL | +| --------- | -------- | ------------------------------------------------------ | +| BigDipper | `cosmos` | [evmos.bigdipper.live/](https://evmos.bigdipper.live/) | + +| Blockscout | `evm` | [evm.evmos.org](https://evm.evmos.org/) | +| M--------n | `------` | [----------------------------------------------) | | ATOMScan | `cosmos` | [atomscan.com/evmos](https://atomscan.com/evmos) | ::: ::: tab Testnet -| | Category | URL | -| -------------------- | -------- | ---------------------- | -| BigDipper | `cosmos` | [testnet.bigdipper.live](https://testnet.evmos.bigdipper.live/) | -| Blockscout | `evm` | [evm.evmos.dev](https://evm.evmos.dev/) | -| Evmostats | `cosmos` | [evm.evmos.dev](https://testnet.evmostats.io/) | -| Mintscan | `cosmos` | [mintscan.io/evmos/](https://www.mintscan.io/evmos/) | +| | Category | URL | +| --------- | -------- | --------------------------------------------------------------- | +| BigDipper | `cosmos` | [testnet.bigdipper.live](https://testnet.evmos.bigdipper.live/) | + +| Blockscout | `evm` | [evm.evmos.dev](https://evm.evmos.dev/) | +| E--------s | `------` | [----------------------------------------------------------------------------) | +| Mintscan | `cosmos` | [testnet.mintscan.io/evmos-testnet](https://testnet.mintscan.io/evmos-testnet) | ::: :::: diff --git a/docs/validators/mainnet.md b/docs/validators/mainnet.md index b6dc87a469..af45d32369 100644 --- a/docs/validators/mainnet.md +++ b/docs/validators/mainnet.md @@ -20,7 +20,7 @@ You need to set the **genesis file** and **seeds**. If you need more information | Chain ID | Description | Site | Version | Status | | -------------- | --------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ | ------- | -| `evmos_9001-2` | Evmos Mainnet 2 | [Evmos](https://github.com/tharsis/mainnet/tree/main/evmos_9001-2) | [`v3.0.x`](https://github.com/tharsis/evmos/releases) | `Live` | +| `evmos_9001-2` | Evmos Mainnet 2 | [Evmos](https://github.com/tharsis/mainnet/tree/main/evmos_9001-2) | [`v4.0.1`](https://github.com/tharsis/evmos/releases/v4.0.1) | `Live` | | `evmos_9001-1` | Evmos Mainnet 1 | [Evmos](https://github.com/tharsis/mainnet/tree/main/evmos_9001-1) | [`v2.0.1`](https://github.com/tharsis/evmos/releases/v2.0.1) | `Stale` | ## Install `evmosd` diff --git a/docs/validators/testnet.md b/docs/validators/testnet.md index b6d05e0b2a..90601ded8c 100644 --- a/docs/validators/testnet.md +++ b/docs/validators/testnet.md @@ -12,7 +12,7 @@ You specify the network you want to join by setting the **genesis file** and **s | Testnet Chain ID | Description | Site | Version | Status | | ---------------- | --------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------- | -| `evmos_9000-4` | Evmos_9000-4 Testnet | [Evmos 9000-4](https://github.com/tharsis/testnets/tree/main/evmos_9000-4) | [`v3.0.0`](https://github.com/tharsis/evmos/releases/tag/v3.0.0) | `Live` | +| `evmos_9000-4` | Evmos_9000-4 Testnet | [Evmos 9000-4](https://github.com/tharsis/testnets/tree/main/evmos_9000-4) | [`v4.0.1`](https://github.com/tharsis/evmos/releases/v4.0.1) | `Live` | | `evmos_9000-3` | Evmos_9000-3 Testnet | [Evmos 9000-3](https://github.com/tharsis/testnets/tree/main/evmos_9000-3) | [`v1.0.0-beta1`](https://github.com/tharsis/evmos/releases/tag/v1.0.0-beta1) | `Stale` | | `evmos_9000-2` | Olympus Mons Incentivized Testnet | [Olympus Mons](https://github.com/tharsis/testnets/tree/main/olympus_mons) | [`v0.3.x`](https://github.com/tharsis/evmos/releases) | `Stale` | | `evmos_9000-1` | Arsia Mons Testnet | [Arsia Mons](https://github.com/tharsis/testnets/tree/main/arsia_mons) | [`v0.1.x`](https://github.com/tharsis/evmos/releases) | `Stale` | diff --git a/docs/validators/upgrades/overview.md b/docs/validators/upgrades/overview.md index 3fa291d7d5..d7b7880d0e 100644 --- a/docs/validators/upgrades/overview.md +++ b/docs/validators/upgrades/overview.md @@ -18,14 +18,43 @@ Additionally, validators can choose how to manage the upgrade according to their - **Automatic or Manual Upgrades**: Validator can run the `cosmovisor` process to automatically perform the upgrade or do it manually. -## Planned and Unplanned Upgrades +## Planned and Forks Upgrades -Planned upgrades are coordinated scheduled upgrades that use the [upgrade module](https://docs.cosmos.network/main/modules/upgrade/) logic. This facilitates smoothly upgrading Evmos to a new (breaking) software version as it automatically handles the state migration for the +### Planned Upgrades + +Planned upgrades are coordinated scheduled upgrades that use the [upgrade module](https://docs.evmos.org/modules/upgrade/) logic. This facilitates smoothly upgrading Evmos to a new (breaking) software version as it automatically handles the state migration for the new release. + +#### Governance Proposal + +Governance Proposals are a mechanism for coordinating an upgrade at a given height or time using an [`SoftwareProposal`](https://docs.evmos.org/modules/upgrade/01_concepts.html#proposal). + +::: tip +All governance proposals, including software upgrades, need to wait for the voting period to conclude before the upgrade can be executed. Consider this duration when submitting a software upgrade proposal. +::: + +If the proposal passes, the upgrade `Plan`, which targets a specific upgrade logic to migrate the state, is persisted to the blockchain state and scheduled at the given upgrade height. The upgrade can be delayed or expedited by updating the `Plan.Height` in a new proposal. + +#### Hard Forks + +A special type of planned upgrades are hard forks. Hard Forks, as opposed to [Governance Proposal}(#governance-proposal), don't require waiting for the full voting +period. This makes them ideal for coordinating security vulnerabilities and patches. + +The upgrade (fork) block height is set in the `BeginBlock` of the application (i.e before the transactions are processed for the block). Once the blockchain reaches that height, it automatically schedules an upgrade `Plan` for the same height and then triggers the upgrade process. After upgrading, the block operations (`BeginBlock`, transaction processing and state `Commit`) continue normally. + +::: tip +In order to execute an upgrade hard fork, a [patch version](#patch-versions) needs to first be released with the `BeginBlock` upgrade scheduling logic. After a +2/3 of the validators upgrade to the new patch version, their nodes will automatically halt and upgrade the binary. +::: + +### Unplanned Upgrades Unplanned upgrades are upgrades where all the validators need to gracefully halt and shut down their nodes at exactly the same point in the process. This can be done by setting the `--halt-height` flag when running the `evmosd start` command. If there are breaking changes during an unplanned upgrade (see below), validators will need to migrate the state and genesis before restarting their nodes. +::: tip +The main consideration with unplanned upgrades is that the genesis state needs to be exported and the blockchain data needs to be [reset](#data-reset-upgrades). This mainly affects infrastructure providers, tools and clients like block explorers and clients, which have to use archival nodes to serve queries for the pre-upgrade heights. +::: + ### Breaking and Non-Breaking Upgrades Upgrades can be categorized as breaking or non-breaking according to the Semantic versioning ([Semver](https://semver.org/)) of the corresponding software [release version](https://github.com/tharsis/evmos/releases) (*i.e* `vX.Y.Z`): @@ -34,7 +63,7 @@ Upgrades can be categorized as breaking or non-breaking according to the Semanti - **Minor version (`Y`)**: new backward compatible features. These can be also be state machine breaking. - **Patch version (`Z`)**: backwards compatible bug fixes, small refactors and improvements. -#### Major Upgrades +#### Major Versions If the new version you are upgrading to has breaking changes, you will have to: @@ -46,14 +75,14 @@ This needs to be done to prevent [double signing or halting the chain during con To upgrade the genesis file, you can either fetch it from a trusted source or export it locally using the `evmosd export` command. -#### Minor Upgrades +#### Minor Versions If the new version you are upgrading to has breaking changes, you will have to: 1. Migrate the state (if applicable) 2. Restart node -#### Patch Upgrades +#### Patch Versions In order to update a patch: diff --git a/docs/validators/upgrades/upgrades.md b/docs/validators/upgrades/upgrades.md index 513f6a8677..7e60209b3e 100644 --- a/docs/validators/upgrades/upgrades.md +++ b/docs/validators/upgrades/upgrades.md @@ -6,19 +6,25 @@ order: 4 Check the details and requirements for each mainnet and testnet upgrade. {synopsis} -## Mainnet Upgrades +:::: tabs +::: tab Mainnet -| Version | Planned | Breaking | Data Reset | Manual Upgrade Only | -| -------------------------------------------------------------------------- | :-----: | :------: | :--------: | :-----------------: | -| [`v3.0.0`](https://github.com/tharsis/evmos/releases/tag/v3.0.0) | ❌ | ✅ | ✅ | ✅ | -| [`v2.0.1`](https://github.com/tharsis/evmos/releases/tag/v2.0.1) | ❌ | ❌ | ❌ | ❌ | -| [`v2.0.0`](https://github.com/tharsis/evmos/releases/tag/v2.0.0) | ✅ | ✅ | ❌ | ❌ | -| [`v1.0.0`](https://github.com/tharsis/evmos/releases/tag/v1.0.0) (genesis) | `N/A` | `N/A` | `N/A` | ❌ | +| Version | Planned | Breaking | Data Reset | Manual Upgrade Only | Upgrade Height | +| -------------------------------------------------------------------------- | :-----: | :------: | :--------: | :-----------------: | ------------------------------------------------------ | +| [`v4.0.1`](https://github.com/tharsis/evmos/releases/tag/v4.0.1) | ❌ | ✅ | ❌ | ❌ | [257,850](https://www.mintscan.io/evmos/blocks/257850) | +| [`v3.0.0`](https://github.com/tharsis/evmos/releases/tag/v3.0.0) | ❌ | ✅ | ✅ | ✅ | [58,701](https://www.mintscan.io/evmos/blocks/58701) | +| [`v2.0.1`](https://github.com/tharsis/evmos/releases/tag/v2.0.1) | ❌ | ❌ | ❌ | ❌ | [58,700](https://www.mintscan.io/evmos/blocks/58700) | +| [`v2.0.0`](https://github.com/tharsis/evmos/releases/tag/v2.0.0) | ✅ | ✅ | ❌ | ❌ | [58,700](https://www.mintscan.io/evmos/blocks/58700) | +| [`v1.0.0`](https://github.com/tharsis/evmos/releases/tag/v1.0.0) (genesis) | `N/A` | `N/A` | `N/A` | ❌ | [1](https://www.mintscan.io/evmos/blocks/1) | -## Testnet Upgrades +::: +::: tab Testnet -| Version | Planned | Breaking | Data Reset | Manual Upgrade Only | -| -------------------------------------------------------------------------------------- | :-----: | :------: | :--------: | :-----------------: | -| [`v3.0.0`](https://github.com/tharsis/evmos/releases/tag/v3.0.0) | ✅ | ✅ | ❌ | ❌ | -| [`v3.0.0-beta1`](https://github.com/tharsis/evmos/releases/tag/v3.0.0-beta1) | ❌ | ✅ | ✅ | ✅ | -| [`v1.0.0-beta1`](https://github.com/tharsis/evmos/releases/tag/v1.0.0-beta1) (genesis) | `N/A` | `N/A` | `N/A` | ❌ | +| Version | Planned | Breaking | Data Reset | Manual Upgrade Only | Upgrade Height | +| -------------------------------------------------------------------------------------- | :-----: | :------: | :--------: | :-----------------: | --------------------------------------------------------------------- | +| [`v4.0.1`](https://github.com/tharsis/evmos/releases/tag/v4.0.1) | ✅ | ✅ | ❌ | ❌ | [1,200,000](https://testnet.mintscan.io/evmos-testnet/blocks/1200000) | +| [`v3.0.0`](https://github.com/tharsis/evmos/releases/tag/v3.0.0) | ✅ | ✅ | ❌ | ❌ | | +| [`v3.0.0-beta1`](https://github.com/tharsis/evmos/releases/tag/v3.0.0-beta1) | ❌ | ✅ | ✅ | ✅ | | +| [`v1.0.0-beta1`](https://github.com/tharsis/evmos/releases/tag/v1.0.0-beta1) (genesis) | `N/A` | `N/A` | `N/A` | ❌ | [1](https://testnet.mintscan.io/evmos-testnet/blocks/1) | +::: +::::