From 2523200d0967fc21ba18af095404fe9767cd2434 Mon Sep 17 00:00:00 2001 From: MSalopek Date: Tue, 4 Jun 2024 15:37:28 +0200 Subject: [PATCH] docs: update versioning schemes (#3130) * docs: update versions on docs page * docs: resolve broken paths * docs: show warn on broken link (makes build pass) * wip: add v17 version * docs: manually set versions; reflect current route in selector * docs: cleanup docs - rm outdated; update versioning * docs: docusaurus configs * docs: setup redirect to /main; update configs --- docs/docs/changelogs/README.md | 6 - docs/docs/changelogs/_category_.json | 5 - docs/docs/changelogs/v15.1.0.md | 132 -- docs/docs/changelogs/v16.0.0.md | 57 - docs/docs/guidelines/_category_.json | 5 - docs/docs/guidelines/code-guidelines.md | 1354 ----------------- docs/docs/hub-tutorials/join-mainnet.md | 3 +- docs/docs/index.md | 15 +- docs/docs/migration/README.md | 15 - docs/docs/migration/_category_.json | 5 - docs/docs/migration/archive/README.md | 16 - .../archive/cosmoshub-2/_category_.json | 5 - .../archive/cosmoshub-2/cosmoshub-2.md | 225 --- .../archive/cosmoshub-3/_category_.json | 5 - .../archive/cosmoshub-3/cosmoshub-3.md | 383 ----- .../archive/cosmoshub-4/_category_.json | 5 - .../cosmoshub-4/cosmoshub-4-v10-upgrade.md | 296 ---- .../cosmoshub-4/cosmoshub-4-v11-upgrade.md | 276 ---- .../cosmoshub-4/cosmoshub-4-v12-upgrade.md | 283 ---- .../cosmoshub-4/cosmoshub-4-v13-upgrade.md | 276 ---- .../cosmoshub-4/cosmoshub-4-v14-upgrade.md | 244 --- .../cosmoshub-4/cosmoshub-4-v15-upgrade.md | 223 --- .../cosmoshub-4-v5-delta-upgrade.md | 151 -- .../cosmoshub-4-v6-vega-upgrade.md | 271 ---- .../cosmoshub-4-v7-Theta-upgrade.md | 274 ---- .../cosmoshub-4/cosmoshub-4-v8-Rho-upgrade.md | 296 ---- .../cosmoshub-4-v9-Lambda-upgrade.md | 296 ---- docs/docs/migration/latest.md | 200 --- docs/docs/validators/README.md | 12 +- docs/docusaurus.config.js | 39 +- docs/src/pages/index.js | 6 + docs/versions.json | 4 +- 32 files changed, 41 insertions(+), 5342 deletions(-) delete mode 100644 docs/docs/changelogs/README.md delete mode 100644 docs/docs/changelogs/_category_.json delete mode 100644 docs/docs/changelogs/v15.1.0.md delete mode 100644 docs/docs/changelogs/v16.0.0.md delete mode 100644 docs/docs/guidelines/_category_.json delete mode 100644 docs/docs/guidelines/code-guidelines.md delete mode 100644 docs/docs/migration/README.md delete mode 100644 docs/docs/migration/_category_.json delete mode 100644 docs/docs/migration/archive/README.md delete mode 100644 docs/docs/migration/archive/cosmoshub-2/_category_.json delete mode 100644 docs/docs/migration/archive/cosmoshub-2/cosmoshub-2.md delete mode 100644 docs/docs/migration/archive/cosmoshub-3/_category_.json delete mode 100644 docs/docs/migration/archive/cosmoshub-3/cosmoshub-3.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/_category_.json delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v10-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v11-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v12-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v13-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v14-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v15-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v5-delta-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v6-vega-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v7-Theta-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v8-Rho-upgrade.md delete mode 100644 docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v9-Lambda-upgrade.md delete mode 100644 docs/docs/migration/latest.md create mode 100644 docs/src/pages/index.js diff --git a/docs/docs/changelogs/README.md b/docs/docs/changelogs/README.md deleted file mode 100644 index 8da65c84f06..00000000000 --- a/docs/docs/changelogs/README.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Changelogs -order: 1 ---- - -This folder documents and clarifies important API and other changes introduced to the Cosmos Hub blockchain as a result of a software upgrade. Most changes are a result of updating cosmos-sdk, ibc-go and cometbft versions. diff --git a/docs/docs/changelogs/_category_.json b/docs/docs/changelogs/_category_.json deleted file mode 100644 index 2e6ba716c1b..00000000000 --- a/docs/docs/changelogs/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Changelogs", - "position": 16, - "link": { "type": "doc", "id": "changelogs/README" } -} \ No newline at end of file diff --git a/docs/docs/changelogs/v15.1.0.md b/docs/docs/changelogs/v15.1.0.md deleted file mode 100644 index 46808c78ec8..00000000000 --- a/docs/docs/changelogs/v15.1.0.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: v15.1.0 ---- - -This document outlines API breaking changes that were introduced in `gaia v15.1.0`. - -This release is based on cosmos-sdk `v0.47.x` and ibc-go `v7.x`. - -You can find the comprehensive API docs at: -* https://docs.cosmos.network/api - -Module reference manuals (with CLI instructions) can be found at: -* https://docs.cosmos.network/v0.47/build/modules - -Comprehensive list of changes: -* https://github.com/cosmos/gaia/blob/release/v15.1.x/CHANGELOG.md#api-breaking - -## Supported modules: -cosmos-sdk `v0.47.10-ics-lsm` -* x/auth -* x/authz -* x/bank -* x/capability -* x/consensus -* x/crisis -* x/distribution -* x/evidence -* x/feegrant -* x/gov -* x/mint -* x/params -* x/slashing -* x/staking (with LSM changes) -* x/upgrade - -ibc-go `v7.x` -* transfer -* ica (host) - -interchain-security/provider `v3.3.x` - -packetforward `v7.x` - -gaia -* x/globalfee `v15.x` -* x/metaprotocols `v15.x` - - -# Important changes -Changes are outlined compared to `gaiad <= v14.x` - -## Behaviour changes - -Starting `v15.1.0` all users must have at least `1 ATOM` staked in order to cast a vote on a governance proposal. - -Votes from accounts whose staked amounts are `< 1 ATOM` will be rejected. - -## REST/RPC Changes - -### DenomOwners - -The `DenomOwners` query is not supported on the Cosmos Hub chain. -* querying `.cosmos/bank/v1beta1/denom_owners/{denom}` always returns an empty result. - - -### Querying latest block - -`curl /blocks/latest` no longer works and returns `{"code":12,"message":"Not Implemented","details":[]}` - -The endpoint was moved to: `/cosmos/base/tendermint/v1beta1/blocks/latest` - - -# CLI Changes - -## Genesis commands - -`gaiad` no longer uses a custom genesis commands and instead relies on the commands defined in the [x/genutil module](https://docs.cosmos.network/v0.47/build/modules/genutil). - -These queries no longer work: -```shell -gaiad gentx -gaiad collect-gentx -gaiad validate-genesis -gaiad add-genesis-account -``` - -Use the `genesis` subcommands instead: -```shell -gaiad genesis gentx -gaiad genesis collect-gentx -gaiad genesis validate-genesis -gaiad genesis add-genesis-account -gaiad genesis migrate -``` - -## Governance commands - -Governance commands are aligned with cosmos-sdk v0.47.x [x/gov module](https://docs.cosmos.network/v0.47/build/modules/gov). - -### submit-legacy-proposal - -Some proposal types can be submitted using the `gaiad tx gov submit-legacy-proposal` command: -```sh -gaiad tx gov submit-legacy-proposal - -Available Commands: - cancel-software-upgrade Cancel the current software upgrade proposal - change-reward-denoms Submit a change reward denoms proposal - consumer-addition Submit a consumer addition proposal - consumer-removal Submit a consumer chain removal proposal - ibc-upgrade Submit an IBC upgrade proposal - param-change Submit a parameter change proposal - software-upgrade Submit a software upgrade proposal - update-client Submit an update IBC client proposal -``` - -Most cosmos-sdk modules no longer allow their parameters to be upgraded using a `param-change` proposal. Use the corresponding `MsgUpgradeParams` message instead and create a JSON file proposal using `draft-proposal` (listed below). - -List of proposals available for submission via `submit-legacy-proposal` will be further decreased in subsequent releases. - -More information is available in cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#submit-legacy-proposal). - -### draft-proposal - -`gaiad tx gov draft-proposal` command is available. You can use this command to create a draft proposal in JSON format. -* more information is available in the cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#draft-proposal) - -### submit-proposal - -`gaiad tx gov submit-proposal` command is available. Use `draft-proposal` (listed above) to create a proposal JSON and submit it as a transaction. - -More information is available in cosmos-sdk [x/gov docs](https://docs.cosmos.network/v0.47/build/modules/gov#submit-proposal) diff --git a/docs/docs/changelogs/v16.0.0.md b/docs/docs/changelogs/v16.0.0.md deleted file mode 100644 index b87b54c212a..00000000000 --- a/docs/docs/changelogs/v16.0.0.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: v16.0.0 -order: 1 ---- - -This document changes that were introduced in `gaia v16.0.0`. - -This release is based on cosmos-sdk `v0.47.x`, ibc-go `v7.x` and cometBFT `v0.37.5`. - -You can find the comprehensive API docs at: -* https://docs.cosmos.network/api - -Module reference manuals (with CLI instructions) can be found at: -* https://docs.cosmos.network/v0.47/build/modules - -Comprehensive list of changes: -* https://github.com/cosmos/gaia/blob/v16.0.0/CHANGELOG.md - -## Supported modules: -cosmos-sdk `v0.47.13-ics-lsm` -* x/auth -* x/authz -* x/bank -* x/capability -* x/consensus -* x/crisis -* x/distribution -* x/evidence -* x/feegrant -* x/gov -* x/mint -* x/params -* x/slashing -* x/staking (with LSM changes) -* x/upgrade - -ibc protocols -* transfer -* ica host -* ica controller -* interchain-security/provider `v4.1.0-lsm` - -ibc-middleware -* packetforward `v7.x` -* [ibcfee](https://ibc.cosmos.network/v7/middleware/ics29-fee/overview) `v7.x` -* [ibc-rate-limiting](https://github.com/Stride-Labs/ibc-rate-limiting) - -gaia -* x/globalfee -* x/metaprotocols - -# Important changes - -This version enables relayer incentivization for newly created IBC channels, adds ICA controller functionality and imposes limits on the amount of outgoing ATOM IBC transfers. - -With the upgrade of the ICS provider module, the amount of relayer traffic gets significantly reduced due to the introduction of epochs. With epochs, the ICS protocol aggregates validator set updates and sends them every 600 blocks (1 packet/hour) instead of every block. This feature is intended to reduce relayer costs and encourage relayer participation. - \ No newline at end of file diff --git a/docs/docs/guidelines/_category_.json b/docs/docs/guidelines/_category_.json deleted file mode 100644 index 038847f3037..00000000000 --- a/docs/docs/guidelines/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Guidelines", - "position": 13, - "link": { "type": "doc", "id": "guidelines/code-guidelines" } -} \ No newline at end of file diff --git a/docs/docs/guidelines/code-guidelines.md b/docs/docs/guidelines/code-guidelines.md deleted file mode 100644 index ad91137d258..00000000000 --- a/docs/docs/guidelines/code-guidelines.md +++ /dev/null @@ -1,1354 +0,0 @@ ---- -title: Contributing Guidelines -order: 1 ---- - -If you want to contribute to a project and improve it, your help is welcome. We want to make Gaia as good as it can be. Contributing is also a great way to learn more about blockchain technology and improve it. Please read this document and follow our guidelines to make the process as smooth as possible. We are happy to review your code but please ensure that you have a reasonable and clean pull request. - -This documents idiomatic conventions in the Go code that we follow for gaia development. A lot of these are general guidelines for Go, while others extend upon external resources: - -1. [Effective Go](https://golang.org/doc/effective_go.html) -2. [Go Common Mistakes](https://github.com/golang/go/wiki/CommonMistakes) -3. [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) - -## Maintainability - -From a maintainance, performance and security perspective, it is important to keep the footprint of the `gaiad` application as lean as possible. - -When adding any new feature, you must ensure that any libraries you wish to include are well maintained and have sufficient usage in the wider ecosystem. This is necessary to avoid having to rework the `gaiad` application at a later date, if a library is no longer maintained or is abandoned by its core contributors. - -In addition to the above, if any library is to be included, it is necessary to check that the version used does not have any known vunerabilities. As a developer working on a feature, before making a pull request, ensure that you run, along with the testing targets, the vulnerability checking target in the root of the gaia repository directory: - -```sh -make govulncheck -``` - -The above command will run the vulnerability checker that will detail any known issues for the library version that your using. If any issues are raised, or you have any concerns, please reach out to the core-developers who will be able to advise further. - -## Run tests - -- Run unit tests - -```shell -make test-unit -``` - -- Run the unit tests and output the coverage file (coverage.txt). - -```shell -make test-unit-cover -``` - -- Run the unit tests with the race condition flag on. - -```shell -make test-race -``` - -- Run end-to-end integration tests (Docker needed). - -```shell -make docker-build-hermes && \ -make docker-build-debug && \ -make test-e2e -``` - -## Guidelines - -These guidelines are the conventions that govern our code. These conventions cover far more than just source file formatting. Can `gofmt` and `goimports` handle that for us. - -The goal of this guide is to manage this complexity by describing in detail the Dos and Don'ts of writing Go code. These rules keep the code base manageable while allowing engineers to use Go language features productively. - -Try to avoid extensive methods and always test your code. All PRs should have at least 95% of code coverage. - -- Contributing - - [Maintainability](#maintainability) - - [Run tests](#run-tests) - - [Guidelines](#guidelines) - - [Project organization](#project-organization) - - [How to test this project locally](#how-to-test-this-project-locally) - - [Unit Tests](#unit-tests) - - [End-to-End Tests](#end-to-end-tests) - - [Upgrade Test](#upgrade-test) - - [Build current version and move into ./build:](#build-current-version-and-move-into-build) - - [Build gaia v9.0.0 and move into ./build:](#build-gaia-v900-and-move-into-build) - - [Go back to your previous working branch](#go-back-to-your-previous-working-branch) - - [Install cosmovisor](#install-cosmovisor) - - [Run the Chain](#run-the-chain) - - [Run the upgrade](#run-the-upgrade) - - [Monitor for success](#monitor-for-success) - - [Guidelines](#guidelines-1) - - [Line Length](#line-length) - - [Doc Comments](#doc-comments) - - [Declaring Empty Slices](#declaring-empty-slices) - - [Indent Error Flow](#indent-error-flow) - - [Unnecessary Else](#unnecessary-else) - - [Named Result Parameters](#named-result-parameters) - - [Package Comments](#package-comments) - - [Package Names](#package-names) - - [Function Names](#function-names) - - [Pointers](#pointers) - - [Receiver Names](#receiver-names) - - [Variable Names](#variable-names) - - [Zero-value Mutexes](#zero-value-mutexes) - - [Copy Slices and Maps at Boundaries](#copy-slices-and-maps-at-boundaries) - - [Receiving Slices and Maps](#receiving-slices-and-maps) - - [Returning Slices and Maps](#returning-slices-and-maps) - - [Errors](#errors) - - [Error Types](#error-types) - - [Error Wrapping](#error-wrapping) - - [Error Naming](#error-naming) - - [Handle Type Assertion Failures](#handle-type-assertion-failures) - - [Avoid Embedding Types in Public Structs](#avoid-embedding-types-in-public-structs) - - [Avoid `init()`](#avoid-init) - - [Performance](#performance) - - [Prefer strconv over fmt](#prefer-strconv-over-fmt) - - [Avoid string-to-byte conversion](#avoid-string-to-byte-conversion) - - [Prefer Specifying Container Capacity](#prefer-specifying-container-capacity) - - [Specifying Map Capacity Hints](#specifying-map-capacity-hints) - - [Specifying Slice Capacity](#specifying-slice-capacity) - - [Function Grouping and Ordering](#function-grouping-and-ordering) - - [Reduce Nesting](#reduce-nesting) - - [Writing Tests](#writing-tests) - - [Use Subtests](#use-subtests) - - [Avoid writing directly in the stdout](#avoid-writing-directly-in-the-stdout) - - [Avoid panic](#avoid-panic) - -## Project organization - -- /ante: Where the ante-handler logic is defined. - -- /app: Where the application is defined. - -- /client: OpenAPI/Swagger specs, JSON schema files, protocol definition files. - - /swagger-ui - -- /cmd/gaiad: Main applications for this project. - - cmd/ - - main.go - -- /contrib (scripts): Scripts to perform various build, install, analysis, etc operations. - - /devtools - - /generate_release_note - - /githooks - - /scripts - - /testnets - -- /docs: Gaia docs. - -- /pkg: Library code that's to be reusable. - - /address - - /genesis - -- /proto: Proto type definitions - -- /tests/e2e: Additional external test apps and test data. - -- /third_party/proto: External proto type definitions - -- /tools: Supporting tools for this project. - -- /x: Cosmos Modules. - -## How to test this project locally - -### Unit Tests - -Running unit tests locally should ensure that the tests inside of `/tests/e2e` are not run. These tests require active running docker containers. - -```sh -make test-unit -``` - -### End-to-End Tests - -To run the E2E tests you need to have an instance of Docker running. Then make sure you have the most recent version of the code built in the containers by running: - -```sh -make docker-build-debug -``` - -Then run the tests: - -```sh -make test-e2e -``` - -### Upgrade Test - -Instructions for running the upgrade test locally - -#### Build current version and move into ./build: -```sh -git checkout v8.0.0 -make build -cp ./build/gaiad ./build/gaiad8 -``` - -#### Build gaia v9.0.0 and move into ./build: -```sh -git checkout v9.0.0 -make build -cp ./build/gaiad ./build/gaiad9 -``` - -#### Go back to your previous working branch -```sh -git checkout - -``` - -#### Install cosmovisor -```sh -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v1.3.0 -``` - -#### Run the Chain - -This script prepares the chain and starts it using cosmovisor -```sh -./contrib/scripts/run-gaia-v8.sh -``` - -#### Run the upgrade -In another terminal window, run the script that waits 10 seconds for gaia to start then makes gov proposal to perform an upgrade at height 15 -```sh -./contrib/scripts/run-upgrade-commands.sh 15 -``` - -#### Monitor for success -In a third window run the upgrade monitoring script that will exit without error when the upgrade succeeds. -```sh -./contrib/scripts/test_upgrade.sh 20 5 16 localhost -``` - -This should show logs that demonstrate a successful upgrade by reaching block height 16. - -## Guidelines - -### Line Length - -Avoid uncomfortably long lines. Similarly, don't add line breaks to keep lines short when they are more readable long--for example if they are repetitive. The maximum line length is 120. If your line is over 120 characters, break it; - -### Doc Comments - -All top-level, exported names should have doc comments, as should non-trivial unexported type or function declarations. See https://go.dev/doc/effective_go#commentary for more information about commentary conventions. - -### Declaring Empty Slices - -When declaring an empty slice, prefer - -```go -var t []string -``` - -over - -```go -t := []string{} -``` - -The former declares a nil slice value, while the latter is non-nil but zero-length. They are functionally equivalent—their `len` and `cap` are both zero—but the nil slice is the preferred style. - -Note that there are limited circumstances where a non-nil but the zero-length slice is preferred, such as when encoding JSON objects (a `nil` slice encodes to `null`, while `[]string{}` encodes to the JSON array `[]`). - -When designing interfaces, avoid distinguishing between a nil slice and a non-nil, zero-length slice, as this can lead to subtle programming errors. It's also important to distinguish if a map key exists from whether its value is `zero`/`nil`/`false`. - -For more discussion about nil in Go see Francesc Campoy's talk [Understanding Nil](https://www.youtube.com/watch?v=ynoY2xz-F8s). - - -### Indent Error Flow - -Try to keep the normal code path at a minimal indentation and indent the error handling, dealing with it first. This improves the readability of the code by permitting visual scanning of the normal path quickly. For instance, don't write: - -```go -if err != nil { - // error handling -} else { - // normal code -} -``` - -Instead, write: - -```go -if err != nil { - // error handling - return // or continue, etc. -} -// normal code -``` - -### Unnecessary Else - -If a variable is set in both branches of an if, it can be replaced with a single if. - -- Bad - -```go -var a int -if b { - a = 100 -} else { - a = 10 -} -``` - -- Good - -```go -a := 10 -if b { - a = 100 -} -``` - -### Named Result Parameters - -Consider what it will look like in godoc. Named result parameters like: - -```go -func (n *Node) Parent1() (node *Node) {} -func (n *Node) Parent2() (node *Node, err error) {} -``` - -It will be repetitive in godoc; better to use: - -```go -func (n *Node) Parent1() *Node {} -func (n *Node) Parent2() (*Node, error) {} -``` - -On the other hand, adding names may be helpful in some contexts if a function returns two or three parameters of the same type or if the meaning of a result isn't clear from the context. Don't name result parameters just to avoid declaring a var inside the function; that trades off minor implementation brevity at the cost of unnecessary API verbosity. - -```go -func (f *Foo) Location() (float64, float64, error) -``` - -It is less clear than the: - -```go -// Location returns f's latitude and longitude. -// Negative values mean south and west, respectively. -func (f *Foo) Location() (lat, long float64, err error) -``` - -Naked returns are okay if the function is a handful of lines. Once it's a medium-sized function, be explicit with your return values. Corollary: it's not worth naming result parameters just because it enables you to use naked returns. Clarifying docs is always more important than saving a line or two in your function. - -Finally, it would help if you named a result parameter in some cases to change it in a deferred closure. That is always OK. - - -### Package Comments - -Package comments, like all comments to be presented by godoc, must appear adjacent to the package clause with no blank line. - -```go -/* -Package template implements data-driven templates for generating textual -output such as HTML. -.... -*/ -package template -``` - -For "package main" comments, other styles of comment are fine after the binary name (and it may be capitalized if it comes first). For example, for a `package main` in the directory `seedgen` you could write: - -```go -// Seedgen .. -package main -``` - -See https://go.dev/doc/effective_go#commentary for more information about commentary conventions. - -### Package Names - -All references to names in your package will be done using the package name so that you can omit that name from the identifiers. For example, if you are in package chubby, you don't need to type ChubbyFile, which clients will write as `chubby.ChubbyFile`. Instead, name the type `File`, which clients will write as `chubby.File`. Avoid meaningless package names like util, common, misc, API, types, and interfaces. See https://go.dev/doc/effective_go#package-names and https://go.dev/blog/package-names for more. - -When naming packages, choose a name that is: - -- All lowercase. No capitals or underscores. -- Does not need to be renamed using named imports at most call sites. -- Short and succinct. Remember that the name is identified in full at every call site. -- Not plural. For example, `net/url`, not `net/urls`. -- Not `common`, `util`, `shared`, or `lib`. These are bad, uninformative names. -- To distinguish SDK and Gaia with the same package name, add SDK or Gaia or the module name as the prefix. E.g.: `sdk/types`, `gaia/types` and `gaia/x/globalfee/types`, can use `sdktype`, `gaiatype`, `globalfeetype`. - -See also [Package Names] and [Style guideline for Go packages]. - -[Package Names]: https://blog.golang.org/package-names -[Style guideline for Go packages]: https://rakyll.org/style-packages/ - -### Function Names - -We follow the Go community's convention of using [MixedCaps for function names](https://golang.org/doc/effective_go.html#mixed-caps). An exception is made for test functions, which may contain underscores -for grouping related test cases, e.g., `TestMyFunction_WhatIsBeingTested`. - -## Pointers - -Try to avoid pointers if you don't need them. Don't pass pointers as function arguments to save a few bytes. If a function refers to its argument `x` only as `*x` throughout, then the argument shouldn't be a pointer. Common instances of this include passing a pointer to a string (`*string`) or a pointer to an interface value (`*io.Reader`). In both cases, the value itself is a fixed size and can be passed directly. This advice does not apply to large structs or even small structs that might grow. - -Choosing whether to use a value or pointer receiver on methods can be difficult, especially for new Go programmers. If in doubt, use a pointer, but there are times when a value receiver makes sense, usually for reasons of efficiency, such as for small unchanging structs or values of basic type. Some useful guidelines: - -* If the receiver is a map, func, or chan, don't use a pointer to them. If the receiver is a slice and the method doesn't reslice or reallocate the slice, don't use a pointer. -* If the method needs to mutate the receiver, the receiver must be a pointer. -* If the receiver is a struct that contains a sync.Mutex or similar synchronizing field, the receiver must be a pointer to avoid copying. -* A pointer receiver is more efficient if the receiver is a large struct or array. How large is large? Assume it's equivalent to passing all its elements as arguments to the method. If that feels too large, it's also too large for the receiver. -* Can functions or methods, either concurrently or when called from this method, mutate the receiver? A value type creates a copy of the receiver when the method is invoked, so outside updates will not be applied to this receiver. If changes must be visible in the original receiver, the receiver must be a pointer. -* If the receiver is a struct, array, or slice and any of its elements is a pointer to something that might be mutating, prefer a pointer receiver, as it will make the intention clearer to the reader. -* If the receiver is a small array or struct that is naturally a value type (for instance, something like the `time.Time` type), with no mutable fields and no pointers, or is just a simple basic type such as int or string, a value receiver makes sense. A value receiver can reduce the amount of garbage generated; if a value is passed to a value method, an on-stack copy can be used instead of allocating it to the heap. (The compiler tries to be smart about avoiding this allocation, but it can't always succeed.) Don't choose a value receiver type for this reason without profiling first. -* Don't mix receiver types. Choose either pointers or struct types for all available methods. -* Finally, when in doubt, use a pointer receiver. - -### Receiver Names - -The name of a method's receiver should be a reflection of its identity; often, a one or two-letter abbreviation of its type suffices (such as "c" or "cl" for "Client"). Don't use generic names such as "me", "this", or "self", identifiers typical of object-oriented languages that give the method a special meaning. In Go, the receiver of a method is just another parameter and, therefore, should be named accordingly. The name need not be as descriptive as that of a method argument, as its role is evident and serves no documentary purpose. It can be very short as it will appear on almost every line of every type of method; familiarity admits brevity. Be consistent, too: if you call the receiver "c" in one method, don't call it "cl" in another. - -eg: - -```go -func (s *IntegrationTestSuite) TestDecode() -``` - -### Variable Names - -Variable names in Go should be short rather than long. This is especially true for local variables with limited scope. Prefer `c` to `lineCount`. Prefer `i` to `sliceIndex`. - -The basic rule: the further from its declaration that a name is used, the more descriptive the name must be. For a method receiver, one or two letters are sufficient. Common variables such as loop indices and readers can be a single letter (`i', `r`). More unusual things and global variables need more descriptive names. - - -### Zero-value Mutexes - -The zero-value of `sync.Mutex` and `sync.RWMutex` is valid, so you rarely need a pointer to a mutex. - -- Bad - -```go -mu := new(sync.Mutex) -mu.Lock() -``` - -- Good - -```go -var mu sync.Mutex -mu.Lock() -``` - -If you use a struct by pointer, then the mutex should be a non-pointer field. Do not embed the mutex on the struct, even if the struct is not exported. - -- Bad - -```go -type SMap struct { - sync.Mutex - - data map[string]string -} - -func (m *SMap) Get(k string) string { - m.Lock() - defer m.Unlock() - - return m.data[k] -} -``` - -The `Mutex` field and the `Lock` and `Unlock` methods are unintentionally part of the exported API of `SMap`. - -- Good - -```go -type SMap struct { - mu sync.Mutex - - data map[string]string -} - -func (m *SMap) Get(k string) string { - m.mu.Lock() - defer m.mu.Unlock() - - return m.data[k] -} -``` - -### Copy Slices and Maps at Boundaries - -Slices and maps contain pointers to the underlying data, so be wary of scenarios when they need to be copied. - -#### Receiving Slices and Maps - -Remember that users can modify a map or slice you received as an argument if you store a reference to it. - -- Bad - -```go -func (d *Driver) SetTrips(trips []Trip) { - d.trips = trips -} - -trips := ... -d1.SetTrips(trips) - -// Did you mean to modify d1.trips? -trips[0] = ... -``` - -- Good - -```go -func (d *Driver) SetTrips(trips []Trip) { - d.trips = make([]Trip, len(trips)) - copy(d.trips, trips) -} - -trips := ... -d1.SetTrips(trips) - -// We can now modify trips[0] without affecting d1.trips. -trips[0] = ... -``` - -#### Returning Slices and Maps - -Similarly, be wary of user modifications to maps or slices exposing the internal state. - -- Bad - -```go -type Stats struct { - mu sync.Mutex - counters map[string]int -} - -// Snapshot returns the current stats. -func (s *Stats) Snapshot() map[string]int { - s.mu.Lock() - defer s.mu.Unlock() - - return s.counters -} - -// snapshot is no longer protected by the mutex, so any -// access to the snapshot is subject to data races. -snapshot := stats.Snapshot() -``` - -- Good - -```go -type Stats struct { - mu sync.Mutex - counters map[string]int -} - -func (s *Stats) Snapshot() map[string]int { - s.mu.Lock() - defer s.mu.Unlock() - - result := make(map[string]int, len(s.counters)) - for k, v := range s.counters { - result[k] = v - } - return result -} - -// Snapshot is now a copy. -snapshot := stats.Snapshot() -``` - -### Errors - -#### Error Types - -There are a few options for declaring errors. Consider the following before picking the option best suited for your use case. - -- Does the caller need to match the error to handle it? If yes, we must support the [`errors.Is`] or [`errors.As`] functions by declaring a top-level error variable or a custom type. -- Is the error message a static string, or is it a dynamic string that requires contextual information? We can use [`errors.New`], but for the latter, we must use [`fmt.Errorf`] or a custom error type. -- Are we propagating a new error returned by a downstream function? See the [section on error wrapping](#error-wrapping). - -[`errors.Is`]: https://golang.org/pkg/errors/#Is -[`errors.As`]: https://golang.org/pkg/errors/#As - -| Error matching? | Error Message | Guidance | -|-----------------|---------------|-------------------------------------| -| No | static | [`errors.New`] | -| No | dynamic | [`fmt.Errorf`] | -| Yes | static | top-level `var` with [`errors.New`] | -| Yes | dynamic | custom `error` type | - -[`errors.New`]: https://golang.org/pkg/errors/#New -[`fmt.Errorf`]: https://golang.org/pkg/fmt/#Errorf - -For example, use [`errors.New`] for an error with a static string. Export this error as a variable to support matching it with `errors.Is` if the caller needs to match and handle this error. - -- No error matching: - -```go -// package foo - -func Open() error { - return errors.New("could not open") -} - -// package bar - -if err := foo.Open(); err != nil { - //Can't handle the error. - panic("unknown error") -} -``` - -- Error matching - -```go -// package foo - -var ErrCouldNotOpen = errors.New("could not open") - -func Open() error { - return ErrCouldNotOpen -} - -// package bar - -if err := foo.Open(); err != nil { - if errors.Is(err, foo.ErrCouldNotOpen) { - // handle the error - } else { - panic("unknown error") - } -} -``` - -For an error with a dynamic string, use [`fmt.Errorf`] if the caller does not need to match it and a custom `error` if the caller does need to match it. - -- No error matching - -```go -// package foo - -func Open(file string) error { - return fmt.Errorf("file %q not found", file) -} - -// package bar - -if err := foo.Open("testfile.txt"); err != nil { - //Can't handle the error. - panic("unknown error") -} -``` - -- Error matching - -```go -// package foo - -type NotFoundError struct { - File string -} - -func (e *NotFoundError) Error() string { - return fmt.Sprintf("file %q not found", e.File) -} - -func Open(file string) error { - return &NotFoundError{File: file} -} - - -// package bar - -if err := foo.Open("testfile.txt"); err != nil { - var notFound *NotFoundError - if errors.As(err, ¬Found) { - // handle the error - } else { - panic("unknown error") - } -} -``` - -Note that if you export error variables or types from a package, they will become part of the public API of the package. - -#### Error Wrapping - -There are three main options for propagating errors if a call fails: - -- return the original error as-is -- add context with `fmt.Errorf` and the `%w` verb -- add context with `fmt.Errorf` and the `%v` verb - -Return the original error as-is if there is no additional context to add. This maintains the original error type and message. This is well suited for cases when the underlying error message has sufficient information to track down where it came from. - -Otherwise, add context to the error message where possible so that instead of a vague error such as "connection refused", you get more valuable errors such as "call service foo: connection refused". - -Use `fmt.Errorf` to add context to your errors, picking between the `%w` or `%v` verbs based on whether the caller should be able to match and extract the underlying cause. - -- Use `%w` if the caller should have access to the underlying error. This is a good default for most wrapped errors, but be aware that callers may begin to rely on this behavior. So for cases where the wrapped error is a known `var` or type, document and test it as part of your function's contract. -- Use `%v` to obfuscate the underlying error. Callers will be unable to match it, but you can switch to `%w` in the future if needed. - -When adding context to returned errors, keep the context succinct by avoiding phrases like "failed to", which state the obvious and pile up as the error percolates up through the stack: - -- Bad - -```go -s, err := store.New() -if err != nil { - return fmt.Errorf( - "failed to create a new store: %w", err) -} -``` - -``` -failed to x: failed to y: failed to create a new store: the error -``` - -- Good - -```go -s, err := store.New() -if err != nil { - return fmt.Errorf( - "new store: %w", err) -} -``` - -``` -x: y: new store: the error -``` - -However, once the error is sent to another system, it should be clear that the message is an error (e.g., an `err` tag or "Failed" prefix in logs). - -See also [Don't just check errors, handle them gracefully]. - -[`"pkg/errors".Cause`]: https://godoc.org/github.com/pkg/errors#Cause -[Don't just check errors, handle them gracefully]: https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully - -#### Error Naming - -For error values stored as global variables, use the prefix `Err` or `err` depending on whether they're exported. - -```go -var ( - // The following two errors are exported - // so that users of this package can match them - // with errors.Is. - - ErrBrokenLink = errors.New("link is broken") - ErrCouldNotOpen = errors.New("could not open") - - // This error is not exported because - // we don't want to make it part of our public API. - // We may still use it inside the package - // with errors.Is. - - errNotFound = errors.New("not found") -) -``` - -For custom error types, use the suffix `Error` instead. - -```go -// Similarly, this error is exported -// so that users of this package can match it -// with errors.As. - -type NotFoundError struct { - File string -} - -func (e *NotFoundError) Error() string { - return fmt.Sprintf("file %q not found", e.File) -} - -// And this error is not exported because -// we don't want to make it part of the public API. -// We can still use it inside the package -// with errors.As. - -type resolveError struct { - Path string -} - -func (e *resolveError) Error() string { - return fmt.Sprintf("resolve %q", e.Path) -} -``` - -### Handle Type Assertion Failures - -The single return value form of a [type assertion] will panic on an incorrect type. Therefore, always use the "comma ok" idiom. - -[type assertion]: https://golang.org/ref/spec#Type_assertions - -- Bad - -```go -t := i.(string) -``` - -- Good - -```go -t, ok := i.(string) -if !ok { - // handle the error gracefully -} -``` - - -### Avoid Embedding Types in Public Structs - -These embedded types leak implementation details, inhibit type evolution, and obscure documentation. - -Assuming you have implemented a variety of list types using a shared `AbstractList`, avoid embedding the `AbstractList` in your concrete list implementations. Instead, hand-write only the methods to your concrete list that will delegate to the abstract list. - -```go -type AbstractList struct {} - -// Add adds an entity to the list. -func (l *AbstractList) Add(e Entity) { - // ... -} - -// Remove removes an entity from the list. -func (l *AbstractList) Remove(e Entity) { - // ... -} -``` - -- Bad - -```go -// ConcreteList is a list of entities. -type ConcreteList struct { - *AbstractList -} -``` - -- Good - -```go -// ConcreteList is a list of entities. -type ConcreteList struct { - list *AbstractList -} - -// Add adds an entity to the list. -func (l *ConcreteList) Add(e Entity) { - l.list.Add(e) -} - -// Remove removes an entity from the list. -func (l *ConcreteList) Remove(e Entity) { - l.list.Remove(e) -} -``` - -Go allows [type embedding] as a compromise between inheritance and composition. The outer type gets implicit copies of the embedded type's methods. These methods, by default, delegate to the same method of the embedded instance. - -[type embedding]: https://golang.org/doc/effective_go.html#embedding - -The struct also gains a field by the same name as the type. So, if the embedded type is public, the field is public. To maintain backward compatibility, every future version of the outer type must keep the embedded type. An embedded type is rarely necessary. It is a convenience that helps you avoid writing tedious delegate methods. - -Even embedding a compatible AbstractList *interface* instead of the struct would offer the developer more flexibility to change in the future but still leak the detail that the concrete lists use an abstract implementation. - -- Bad - -```go -// AbstractList is a generalized implementation -// for various kinds of lists of entities. -type AbstractList interface { - Add(Entity) - Remove(Entity) -} - -// ConcreteList is a list of entities. -type ConcreteList struct { - AbstractList -} -``` - -- Good - -```go -// ConcreteList is a list of entities. -type ConcreteList struct { - list AbstractList -} - -// Add adds an entity to the list. -func (l *ConcreteList) Add(e Entity) { - l.list.Add(e) -} - -// Remove removes an entity from the list. -func (l *ConcreteList) Remove(e Entity) { - l.list.Remove(e) -} -``` - -Either with an embedded struct or an embedded interface, the embedded type places limits on the evolution of the type. - -- Adding methods to an embedded interface is a breaking change. -- Removing methods from an embedded struct is a breaking change. -- Removing the embedded type is a breaking change. -- Replacing the embedded type, even with an alternative that satisfies the same - interface, is a breaking change. - -Although writing these delegate methods is tedious, the additional effort hides an implementation detail, leaves more opportunities for change, and eliminates indirection for discovering the whole List interface in the documentation. - -### Avoid `init()` - -Avoid `init()` where possible. When `init()` is unavoidable or desirable, code should attempt to: - -1. Be completely deterministic, regardless of program environment or invocation. -2. Avoid depending on the ordering or side-effects of other `init()` functions. While the `init()` order is well-known, code can change, and thus relationships between `init()` functions can make code brittle and error-prone. -3. Avoid accessing or manipulating global or environment states, such as machine information, environment variables, working directory, program arguments/inputs, etc. -4. Avoid I/O, including filesystem, network, and system calls. - -Code that cannot satisfy these requirements likely belongs as a helper to be called as part of `main()` (or elsewhere in a program's lifecycle), or be written as part of `main()` itself. In particular, libraries intended to be used by other programs should take special care to be completely deterministic and not perform "init magic". - -- Bad - -```go -type Foo struct { - // ... -} - -var _defaultFoo Foo - -func init() { - _defaultFoo = Foo{ - // ... - } -} -``` - -```go -type Config struct { - // ... -} - -var _config Config - -func init() { - // Bad: based on current directory - cwd, _ := os.Getwd() - - // Bad: I/O - raw, _ := os.ReadFile( - path.Join(cwd, "config", "config.yaml"), - ) - - yaml.Unmarshal(raw, &_config) -} -``` - -- Good - -```go -var _defaultFoo = Foo{ - // ... -} - -// or, better, for testability: - -var _defaultFoo = defaultFoo() - -func defaultFoo() Foo { - return Foo{ - // ... - } -} -``` - -```go -type Config struct { - // ... -} - -func loadConfig() Config { - cwd, err := os.Getwd() - // handle err - - raw, err := os.ReadFile( - path.Join(cwd, "config", "config.yaml"), - ) - // handle err - - var config Config - yaml.Unmarshal(raw, &config) - - return config -} -``` - -Considering the above, some situations in which `init()` may be preferable or necessary might include: - -- Complex expressions that cannot be represented as single assignments. -- Pluggable hooks, such as `database/sql` dialects, encoding type registries, etc. -- Optimizations to [Google Cloud Functions] and other forms of deterministic precomputation. - - [Google Cloud Functions]: https://cloud.google.com/functions/docs/bestpractices/tips#use_global_variables_to_reuse_objects_in_future_invocations - -## Performance - -Performance-specific guidelines apply only to the hot path. - -#### Prefer strconv over fmt - -When converting primitives to/from strings, `strconv` is faster than `fmt`. - -- Bad - -```go -for i := 0; i < b.N; i++ { - s := fmt.Sprint(rand.Int()) -} -``` - -``` -BenchmarkFmtSprint-4 143 ns/op 2 allocs/op -``` - -- Good - -```go -for i := 0; i < b.N; i++ { - s := strconv.Itoa(rand.Int()) -} -``` - -``` -BenchmarkStrconv-4 64.2 ns/op 1 allocs/op -``` - -**avoid use "+" for string concatenation** - -#### Avoid string-to-byte conversion - -Do not create byte slices from a fixed string repeatedly. Instead, perform the conversion once and capture the result. - -- Bad - -```go -for i := 0; i < b.N; i++ { - w.Write([]byte("Hello world")) -} -``` - -``` -BenchmarkBad-4 50000000 22.2 ns/op -``` - -- Good - -```go -data := []byte("Hello world") -for i := 0; i < b.N; i++ { - w.Write(data) -} -``` - -``` -BenchmarkGood-4 500000000 3.25 ns/op -``` - -#### Prefer Specifying Container Capacity - -Specify container capacity where possible to allocate memory for the container up front. This minimizes subsequent allocations (copying and resizing the container) as elements are added. - -##### Specifying Map Capacity Hints - -Provide capacity hints when initializing maps with `make()` where possible. - -```go -make(map[T1]T2, hint) -``` - -Providing a capacity hint to `make()` tries to right-size the map at initialization time, which reduces the need for growing the map and allocations as elements are added to the map. - -Unlike slices, map capacity hints do not guarantee complete, preemptive allocation but are used to approximate the number of hashmap buckets required. Consequently, allocations may still occur when adding elements to the map, even up to the specified capacity. - -- Bad - -```go -m := make(map[string]os.FileInfo) - -files, _ := os.ReadDir("./files") -for _, f := range files { - m[f.Name()] = f -} -``` - -`m' is created without a size hint; there may be more allocations at assignment time. - -- Good - -```go - -files, _ := os.ReadDir("./files") - -m := make(map[string]os.DirEntry, len(files)) -for _, f := range files { - m[f.Name()] = f -} -``` - -`m' is created with a size hint; there may be fewer allocations at assignment time. - - -##### Specifying Slice Capacity - -Where possible, provide capacity hints when initializing slices with `make()`, particularly when appending. - -```go -make([]T, length, capacity) -``` - -Unlike maps, slice capacity is not a hint: the compiler will allocate enough memory for the capacity of the slice as provided to `make()`, which means that subsequent `append()` operations will incur zero allocations (until the length of the slice matches the capacity, after which any appends will require a resize to hold additional elements). - -- Bad - -```go -for n := 0; n < b.N; n++ { - data := make([]int, 0) - for k := 0; k < size; k++{ - data = append(data, k) - } -} -``` - -``` -BenchmarkBad-4 100000000 2.48s -``` - -- Good - -```go -for n := 0; n < b.N; n++ { - data := make([]int, 0, size) - for k := 0; k < size; k++{ - data = append(data, k) - } -} -``` - -``` -BenchmarkGood-4 100000000 0.21s -``` - -### Function Grouping and Ordering - -- Functions should be sorted in rough call order. -- The receiver should group functions in a file. - -Therefore, exported functions should appear first in a file, after `struct`, `const`, and `var` definitions. - -A `newXYZ()`/`NewXYZ()` may appear after the type is defined but before the rest of the methods on the receiver. - -Since the receiver groups functions, plain utility functions should appear toward the end of the file. - -- Bad - -```go -func (s *something) Cost() { - return calcCost(s.weights) -} - -type something struct{ ... } - -func calcCost(n []int) int {...} - -func (s *something) Stop() {...} - -func newSomething() *something { - return &something{} -} -``` - -- Good - -```go -type something struct{ ... } - -func newSomething() *something { - return &something{} -} - -func (s *something) Cost() { - return calcCost(s.weights) -} - -func (s *something) Stop() {...} - -func calcCost(n []int) int {...} -``` - -### Reduce Nesting - -Code should reduce nesting where possible by handling error cases/special conditions first and returning early or continuing the loop. Reduce the amount of code that is nested on multiple levels. - -- Bad - -```go -for _, v := range data { - if v.F1 == 1 { - v = process(v) - if err := v.Call(); err == nil { - v.Send() - } else { - return err - } - } else { - log.Printf("Invalid v: %v", v) - } -} -``` - -- Good - -```go -for _, v := range data { - if v.F1 != 1 { - log.Printf("Invalid v: %v", v) - continue - } - - v = process(v) - if err := v.Call(); err != nil { - return err - } - v.Send() -} -``` - -### Writing Tests - -Use table-driven tests with [subtests] to avoid duplicating code when the core -test logic is repetitive. - -[subtests]: https://blog.golang.org/subtests - -- Bad: - -```go -// func TestSplitHostPort(t *testing.T) - -host, port, err := net.SplitHostPort("192.0.2.0:8000") -require.NoError(t, err) -assert.Equal(t, "192.0.2.0", host) -assert.Equal(t, "8000", port) - -host, port, err = net.SplitHostPort("192.0.2.0:http") -require.NoError(t, err) -assert.Equal(t, "192.0.2.0", host) -assert.Equal(t, "http", port) - -host, port, err = net.SplitHostPort(":8000") -require.NoError(t, err) -assert.Equal(t, "", host) -assert.Equal(t, "8000", port) - -host, port, err = net.SplitHostPort("1:8") -require.NoError(t, err) -assert.Equal(t, "1", host) -assert.Equal(t, "8", port) -``` - -- Good: - -```go -// func TestSplitHostPort(t *testing.T) - -tests := []struct{ - give string - wantHost string - wantPort string -}{ - { - give: "192.0.2.0:8000", - wantHost: "192.0.2.0", - wantPort: "8000", - }, - { - give: "192.0.2.0:http", - wantHost: "192.0.2.0", - wantPort: "http", - }, - { - give: ":8000", - wantHost: "", - wantPort: "8000", - }, - { - give: "1:8", - wantHost: "1", - wantPort: "8", - }, -} - -for _, tt := range tests { - t.Run(tt.give, func(t *testing.T) { - host, port, err := net.SplitHostPort(tt.give) - require.NoError(t, err) - assert.Equal(t, tt.wantHost, host) - assert.Equal(t, tt.wantPort, port) - }) -} -``` - -Test tables make it easier to add context to error messages, reduce duplicate logic, and add new test cases. - -We follow the convention that the slice of structs is referred to as `tests` and each test case `tt`. Further, we encourage explicating the input and output values for each test case with `give` and `want` prefixes. - -```go -tests := []struct{ - give string - wantHost string - wantPort string -}{ - // ... -} - -for _, tt := range tests { - // ... -} -``` - -Parallel tests, like some specialized loops (for example, those that spawn goroutines or capture references as part of the loop body), must take care to explicitly assign loop variables within the loop's scope to ensure that they hold the expected values. - -```go -tests := []struct{ - give string - // ... -}{ - // ... -} - -for _, tt := range tests { - tt := tt // for t.Parallel - t.Run(tt.give, func(t *testing.T) { - t.Parallel() - // ... - }) -} -``` - -In the example above, we must declare a `tt` variable scoped to the loop iteration because of the use of `t.Parallel()` below. If we do not do that, most or all tests will receive an unexpected value for `tt` or a value that changes as they run. - -#### Use Subtests - -Always use subtest beside you are using or not table drive tests. This can reduce the scope of the tests and be more transparent and easy to maintain. Each small case of the tests should be a new subtest. - -### Avoid writing directly in the stdout - -Avoid writing logs directly to the stdout or stderr. Use a proper log package for it. -It's also easier to maintain. We don't need to find all prints and change the code if we need to change. - -### Avoid panic - -Avoid panic in simple and small methods; all errors should be handled on the top level and application, and we can decide if we will panic or not. -We can also create a proper panic recovery to close all states, open connection from the application, and graceful exit without breaking anything. diff --git a/docs/docs/hub-tutorials/join-mainnet.md b/docs/docs/hub-tutorials/join-mainnet.md index 8af9fff3075..dee910c5c8c 100644 --- a/docs/docs/hub-tutorials/join-mainnet.md +++ b/docs/docs/hub-tutorials/join-mainnet.md @@ -24,7 +24,8 @@ The chain-id of Cosmos Hub mainnet is `cosmoshub-4`. - use `gaia v14.1.x` between `18,262,000` and `19,639,600` - use `gaia v15.1.x` between `19,639,600` and `19,939,000` - use `gaia v15.2.x` between `19,939,000` and `20,440,500` -- use `gaia v16.x` from `20,440,500` +- use `gaia v16.x` from `20,440,500` and `20,739,800` +- use `gaia v17.1.x` from `20,739,800` **This guide includes full instructions for joining the mainnet either as an archive/full node or a pruned node.** diff --git a/docs/docs/index.md b/docs/docs/index.md index ca62c11d48a..2a40f4985d4 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -3,14 +3,12 @@ title: Introduction order: 1 sidebar_position: 1 --- -import { currentParams } from '@site/docs/governance/current-parameters.js'; -import { PlainVar } from '@site/src/js/Var'; :::tip -### **v16 Upgrade** -Cosmos Hub will be upgraded to [v16](https://github.com/cosmos/gaia/releases/tag/v16.0.0) at block height: **[20,440,500](https://www.mintscan.io/cosmos/blocks/20440500)** +### **v17 Upgrade** +Cosmos Hub will be upgraded to [v17.1.0](https://github.com/cosmos/gaia/releases/tag/v17.1.0) at block height: **[20,739,800](https://www.mintscan.io/cosmos/blocks/20739800)** -To upgrade from v15.2.0 check the [**upgrade guide**](./migration/latest.md) +To upgrade from v16.0.0 check the [**upgrade guide**](https://github.com/cosmos/gaia/blob/release/v17.1.x/UPGRADING.md) ::: ![Welcome to the Cosmos Hub](images/cosmos-hub-image.jpg) @@ -21,14 +19,14 @@ The Cosmos Hub is the first of [thousands of interconnected blockchains](https:/ ## The ATOM -Do you have ATOM tokens? With ATOM, you have the superpower to contribute to the security and governance of the Cosmos Hub. Delegate your ATOM to one or more of the validators on the Cosmos Hub blockchain to earn more ATOM through Proof-of-Stake. You can also vote with your ATOM to influence the future of the Cosmos Hub through on-chain governance proposals. +Do you have ATOM tokens? With ATOM, you have the superpower to contribute to the security and governance of the Cosmos Hub. Delegate your ATOM to one or more of the validators on the Cosmos Hub blockchain to earn more ATOM through Proof-of-Stake. You can also vote with your ATOM to influence the future of the Cosmos Hub through on-chain governance proposals. Learn more about [being a delegator](./delegators/delegator-faq.md), learn about [the security risks](./delegators/delegator-security.md), and start participating with one of the following wallets. ## Cosmos Hub Wallets :::warning -Do your own research and take precautions in regards to wallet security. Neither Tendermint Inc nor the Interchain Foundation is liable if you lose your funds using these third party wallets. +Do your own research and take precautions in regards to wallet security. Maintaining proper security practices is solely your responsibility when using third party wallets. ::: These community-maintained web and mobile wallets allow you to store & transfer ATOM, delegate ATOM to validators, and vote on on-chain governance proposals. Note that we do not endorse any of the wallets, they are listed for your convenience. @@ -74,7 +72,8 @@ These block explorers allow you to search, view and analyze Cosmos Hub data&mdas ## Running a full-node on the Cosmos Hub Mainnet In order to run a full-node for the Cosmos Hub mainnet, you must first [install `gaiad`](./getting-started/installation). Then, follow [the guide](./hub-tutorials/join-mainnet). -If you are looking to run a validator node, follow the [validator setup guide](./validators/validator-setup). +If you are looking to run a validator node, follow the [validator setup guide](./validators/valid +ator-setup). ## Join the Community diff --git a/docs/docs/migration/README.md b/docs/docs/migration/README.md deleted file mode 100644 index c307a2813ea..00000000000 --- a/docs/docs/migration/README.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -order: false -parent: - title: Upgrade Instructions ---- - - -# Upgrading - -To upgrade to the latest `cosmoshub-4` version check: -- [latest upgrade](./latest.md) - -To check archived migrations and historic `cosmoshub` versions check: -- [Upgrading from `cosmoshub-2` to `cosmoshub-3`](./archive/cosmoshub-2/cosmoshub-2.md) -- [Upgrading from `cosmoshub-3` to `cosmoshub-4`](./archive/cosmoshub-3/cosmoshub-3.md) diff --git a/docs/docs/migration/_category_.json b/docs/docs/migration/_category_.json deleted file mode 100644 index d2312acd858..00000000000 --- a/docs/docs/migration/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Upgrade Instructions", - "position": 17, - "link": { "type": "doc", "id": "migration/README" } -} \ No newline at end of file diff --git a/docs/docs/migration/archive/README.md b/docs/docs/migration/archive/README.md deleted file mode 100644 index f895ae0fba2..00000000000 --- a/docs/docs/migration/archive/README.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -order: false -parent: - title: Archived Instructions ---- - - -# Archive - -This directory houses archived Cosmos Hub major upgrade migration instructions. - -The migrations are not relevant for mainnet, but you may find them useful in case you are providing infrastructure for historic versions of the Cosmos Hub. - -To view archived migrations for old versions check: -- [Upgrading from `cosmoshub-2` to `cosmoshub-3`](./cosmoshub-2/cosmoshub-2.md) -- [Upgrading from `cosmoshub-3` to `cosmoshub-4`](./cosmoshub-3/cosmoshub-3.md) diff --git a/docs/docs/migration/archive/cosmoshub-2/_category_.json b/docs/docs/migration/archive/cosmoshub-2/_category_.json deleted file mode 100644 index 1715f0c42b5..00000000000 --- a/docs/docs/migration/archive/cosmoshub-2/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "CosmosHub-2", - "position": 1, - "link": null -} \ No newline at end of file diff --git a/docs/docs/migration/archive/cosmoshub-2/cosmoshub-2.md b/docs/docs/migration/archive/cosmoshub-2/cosmoshub-2.md deleted file mode 100644 index 001053683d7..00000000000 --- a/docs/docs/migration/archive/cosmoshub-2/cosmoshub-2.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: Cosmos Hub 2 Upgrade -order: 1 ---- - - - -The following document describes the necessary steps involved that full-node operators -must take in order to upgrade from `cosmoshub-2` to `cosmoshub-3`. The Tendermint team -will post an official updated genesis file, but it is recommended that validators -execute the following instructions in order to verify the resulting genesis file. - -There is a strong social consensus around proposal `Cosmos Hub 3 Upgrade Proposal E` -on `cosmoshub-2`. This indicates that the upgrade procedure should be performed -on `December 11, 2019 at or around 14:27 UTC` on block `2,902,000`. - -- [Cosmos Hub 2 Upgrade Instructions](#cosmos-hub-2-upgrade-instructions) - - [Preliminary](#preliminary) - - [Major Updates](#major-updates) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-service-providers) - -## Preliminary - -Many changes have occurred to the Cosmos SDK and the Gaia application since the latest -major upgrade (`cosmoshub-2`). These changes notably consist of many new features, -protocol changes, and application structural changes that favor developer ergonomics -and application development. - -First and foremost, the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/) and the -[Gaia](https://github.com/cosmos/gaia) application have been split into separate -repositories. This allows for both the Cosmos SDK and Gaia to evolve naturally -and independently. Thus, any future [releases](https://github.com/cosmos/gaia/releases) -of Gaia going forward, including this one, will be built and tagged from this -repository not the Cosmos SDK. - -Since the Cosmos SDK and Gaia have now been split into separate repositories, their -versioning will also naturally diverge. In an attempt to decrease community confusion and strive for -semantic versioning, the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/) will continue -on its current versioning path (i.e. v0.36.x ) and the [Gaia](https://github.com/cosmos/gaia) -application will become v2.0.x. - -__[Gaia](https://github.com/cosmos/gaia) application v2.0.3 is -what full node operators will upgrade to and run in this next major upgrade__. - -## Major Updates - -There are many notable features and changes in the upcoming release of the SDK. Many of these -are discussed at a high level in July's Cosmos development update found -[here](https://blog.cosmos.network/cosmos-development-update-july-2019-8df2ade5ba0a). - -Some of the biggest changes to take note on when upgrading as a developer or client are the following: - -- __Tagging/Events__: The entire system of what we used to call tags has been replaced by a more - robust and flexible system called events. Any client that depended on querying or subscribing to - tags should take note on the new format as old queries will not work and must be updated. More in - depth docs on the events system can be found [here](https://github.com/tendermint/tendermint/blob/master/rpc/core/events.go). - In addition, each module documents its own events in the specs (e.g. [slashing](https://github.com/cosmos/cosmos-sdk/blob/v0.36.0/docs/spec/slashing/06_events.md)). -- __Height Queries__: Both the CLI and REST clients now (re-)enable height queries via the - `--height` and `?height` arguments respectively. An important note to keep in mind are that height - queries against pruning nodes will return errors when a pruned height is queried against. When no - height is provided, the latest height will be used by default keeping current behavior intact. In - addition, many REST responses now wrap the query results in a new structure `{"height": ..., "result": ...}`. - That is, the height is now returned to the client for which the resource was queried at. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from a Tendermint developer -before resetting your validator. - -## Recovery - -Prior to exporting `cosmoshub-2` state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.gaia` directories. - -It is critically important to back-up the `.gaia/data/priv_validator_state.json` file after stopping your gaiad process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must downgrade back to -v0.34.6+ of the _Cosmos SDK_ and restore to their latest snapshot before restarting their nodes. - -## Upgrade Procedure - -__Note__: It is assumed you are currently operating a full-node running v0.34.6+ of the _Cosmos SDK_. - -- The version/commit hash of Gaia v2.0.3: `2f6783e298f25ff4e12cb84549777053ab88749a` -- The upgrade height as agreed upon by governance: __2,902,000__ -- You may obtain the canonical UTC timestamp of the exported block by any of the following methods: - - Block explorer - - Through manually querying an RPC node (e.g. `/block?height=2902000`) - - Through manually querying a Gaia REST client (e.g. `/blocks/2902000`) - -1. Verify you are currently running the correct version (v0.34.6+) of the _Cosmos SDK_: - - ```bash - $ gaiad version --long - cosmos-sdk: 0.34.6 - git commit: 80234baf91a15dd9a7df8dca38677b66b8d148c1 - vendor hash: f60176672270c09455c01e9d880079ba36130df4f5cd89df58b6701f50b13aad - build tags: netgo ledger - go version go1.12.2 linux/amd64 - ``` - -2. Export existing state from `cosmoshub-2`: - - __NOTE__: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating `cosmoshub-2`. See [Recovery](#recovery) for details on how to proceed. - - Before exporting state via the following command, the `gaiad` binary must be stopped! - - ```bash - gaiad export --for-zero-height --height=2902000 > cosmoshub_2_genesis_export.json - ``` - -3. Verify the SHA256 of the (sorted) exported genesis file: - - ```bash - $ jq -S -c -M '' cosmoshub_2_genesis_export.json | shasum -a 256 - [PLACEHOLDER] cosmoshub_2_genesis_export.json - ``` - -4. At this point you now have a valid exported genesis state! All further steps now require -v2.0.3 of [Gaia](https://github.com/cosmos/gaia). - - __NOTE__: Go [1.13+](https://golang.org/dl/) is required! - - ```bash - git clone https://github.com/cosmos/gaia.git && cd gaia && git checkout v2.0.3; make install - ``` - -1. Verify you are currently running the correct version (v2.0.3) of the _Gaia_: - - ```bash - $ gaiad version --long - name: gaia - server_name: gaiad - client_name: gaiacli - version: 2.0.3 - commit: 2f6783e298f25ff4e12cb84549777053ab88749a - build_tags: netgo,ledger - go: go version go1.13.3 darwin/amd64 - ``` - -2. Migrate exported state from the current v0.34.6+ version to the new v2.0.3 version: - - ```bash - gaiad migrate v0.36 cosmoshub_2_genesis_export.json --chain-id=cosmoshub-3 --genesis-time=[PLACEHOLDER]> genesis.json - ``` - - __NOTE__: The `migrate` command takes an input genesis state and migrates it to a targeted version. - Both v0.36 and v0.37 are compatible as far as state structure is concerned. - - Genesis time should be computed relative to the blocktime of `2,902,000`. The genesis time - shall be the blocktime of `2,902,000` + `60` minutes with the subseconds truncated. - - An example shell command(tested on OS X Mojave) to compute this values is: - - ```bash - curl https://stargate.cosmos.network:26657/block\?height\=2902000 | jq -r '.result["block_meta"]["header"]["time"]'|xargs -0 date -v +60M -j -f "%Y-%m-%dT%H:%M:%S" +"%Y-%m-%dT%H:%M:%SZ" - ``` - -3. Now we must update all parameters that have been agreed upon through governance. There is only a -single parameter, `max_validators`, that we're upgrading based on [proposal 10](https://www.mintscan.io/proposals/10) - - ```bash - cat genesis.json | jq '.app_state["staking"]["params"]["max_validators"]=125' > tmp_genesis.json && mv tmp_genesis.json genesis.json - ``` - -1. Verify the SHA256 of the final genesis JSON: - - ```bash - $ jq -S -c -M '' genesis.json | shasum -a 256 - [PLACEHOLDER] genesis.json - ``` - -2. Reset state: - - __NOTE__: Be sure you have a complete backed up state of your node before proceeding with this step. - See [Recovery](#recovery) for details on how to proceed. - - ```bash - gaiad unsafe-reset-all - ``` - -3. Move the new `genesis.json` to your `.gaia/config/` directory -4. Replace the `db_backend` on `.gaia/config/config.toml` to: - - ```toml - db_backend = "goleveldb" - ``` - -5. Note, if you have any application configuration in `gaiad.toml`, that file has now been renamed to `app.toml`: - - ```bash - mv .gaia/config/gaiad.toml .gaia/config/app.toml - ``` - -## Notes for Service Providers - -1. The transition from `cosmoshub-2` to `cosmoshub-3` contains an unusual amount of API breakage. - After this upgrade will maintain the CosmosSDK API stability guarantee to avoid breaking APIs for at - least 6 months and hopefully long. -2. Anyone running signing infrastructure(wallets and exchanges) should be conscious that the `type:` - field on `StdTx` will have changed from `"type":"auth/StdTx","value":...` to `"type":"cosmos-sdk/StdTx","value":...` -3. As mentioned in the notes and SDK CHANGELOG, many queries to cosmos cli are wrapped with `height` fields now. -4. We highly recommend standing up a [testnet](https://github.com/cosmos/gaia/blob/master/docs/deploy-testnet.md) - with the `gaia-2.0` release or joining the gaia-13006 testnet. More info for joining the testnet can be - found in the [riot validator room](https://riot.im/app/#/room/#cosmos-validators:matrix.org). -5. We expect that developers with iOS or Android based apps may have to notify their users of downtime - and ship an upgrade for cosmoshub-3 compatibility unless they have some kind of switch they can throw - for the new tx formats. Server side applications should experience briefer service interruptions and - be able to just spin up new nodes and migrate to the new apis. - - diff --git a/docs/docs/migration/archive/cosmoshub-3/_category_.json b/docs/docs/migration/archive/cosmoshub-3/_category_.json deleted file mode 100644 index 499b90abbd9..00000000000 --- a/docs/docs/migration/archive/cosmoshub-3/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "CosmosHub-3", - "position": 2, - "link": null -} \ No newline at end of file diff --git a/docs/docs/migration/archive/cosmoshub-3/cosmoshub-3.md b/docs/docs/migration/archive/cosmoshub-3/cosmoshub-3.md deleted file mode 100644 index 66ca65888cb..00000000000 --- a/docs/docs/migration/archive/cosmoshub-3/cosmoshub-3.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -title: Cosmos Hub 3 Upgrade -order: 1 ---- - - - -The following document describes the necessary steps involved that validators and full node operators -must take in order to upgrade from `cosmoshub-3` to `cosmoshub-4`. The Cosmos teams -will post an official `cosmoshub-4` genesis file, but it is recommended that validators -execute the following instructions in order to verify the resulting genesis file. - -There is a strong social consensus around proposal `Cosmos Hub 4 Upgrade Proposal` -on `cosmoshub-3`. Following proposals #[27](https://www.mintscan.io/cosmos/proposals/27), #[35](https://www.mintscan.io/cosmos/proposals/35) and #[36](https://www.mintscan.io/cosmos/proposals/36). -This indicates that the upgrade procedure should be performed on `February 18, 2021 at 06:00 UTC`. - -- [Summary](#summary) -- [Migrations](#migrations) -- [Preliminary](#preliminary) -- [Major Updates](#major-updates) -- [Risks](#risks) -- [Recovery](#recovery) -- [Upgrade Procedure](#upgrade-procedure) -- [Guidance for Full Node Operators](#guidance-for-full-node-operators) -- [Notes for Service Providers](#notes-for-service-providers) - -# Summary - -The Cosmoshub-3 will undergo a scheduled upgrade to Cosmoshub-4 on Feb 18, 2021 at 6 UTC. - -The following is a short summary of the upgrade steps: - 1. Stopping the running Gaia v2.0.x instance - 1. Backing up configs, data, and keys used for running Cosmoshub-3 - 1. Resetting state to clear the local Cosmoshub-3 state - 1. Copying the cosmoshub-4 genesis file to the Gaia config folder (either after migrating an existing cosmoshub-3 genesis export, or downloading the cosmoshub-4 genesis from the mainnet github) - 1. Installing the Gaia v4.0.x release - 1. Starting the Gaia v4.0.x instance to resume the Cosmos hub chain at a height of + 1. - -Specific instructions for validators are available in [Upgrade Procedure](#upgrade-procedure), -and specific instructions for full node operators are available in [Guidance for Full Node Operators](#guidance-for-full-node-operators). - -Upgrade coordination and support for validators will be available on the #validators-verified channel of the [Cosmos Discord](https://discord.gg/cosmosnetwork). - -The network upgrade can take the following potential pathways: - -1. Happy path: Validator successfully migrates the cosmoshub-3 genesis file to a cosmoshub-4 genesis file, and the validator can successfully start Gaia v4 with the cosmoshub-4 genesis within 1-2 hours of the scheduled upgrade. -1. Not-so-happy path: Validators have trouble migrating the cosmoshub-3 genesis to a cosmoshub-4 genesis, but can obtain the genesis file from the Cosmos mainnet github repo and can successfully start Gaia v4 within 1-2 hours of the scheduled upgrade. -1. Abort path: In the rare event that the team becomes aware of critical issues, which result in an unsuccessful migration within a few hours, the upgrade will be announced as aborted - on the #validators-verified channel of [Discord](https://discord.gg/cosmosnetwork), and validators will need to resume running cosmoshub-3 network without any updates or changes. - A new governance proposal for the upgrade will need to be issued and voted on by the community. - -# Migrations - -These chapters contain all the migration guides to update your app and modules to Cosmos v0.40 Stargate. - -If you’re running a block explorer, wallet, exchange, validator, or any other service (eg. custody provider) that depends upon the Cosmos Hub or Cosmos ecosystem, you’ll want to pay attention, because this upgrade will involve substantial changes. - -1. [App and Modules Migration](https://github.com/cosmos/cosmos-sdk/blob/master/docs/migrations/app_and_modules.md) -2. [REST Endpoints Migration](https://github.com/cosmos/cosmos-sdk/blob/master/docs/migrations/rest.md) -3. [Inter-Blockchain Communication (IBC)– cross-chain transactions](https://figment.io/resources/cosmos-stargate-upgrade-overview/#ibc) -4. [Protobuf Migration – blockchain performance & dev acceleration](https://figment.io/resources/cosmos-stargate-upgrade-overview/#proto) -5. [State Sync – minutes to sync new nodes](https://figment.io/resources/cosmos-stargate-upgrade-overview/#sync) -6. [Full-Featured Light Clients](https://figment.io/resources/cosmos-stargate-upgrade-overview/#light) -7. [Chain Upgrade Module – upgrade automation](https://figment.io/resources/cosmos-stargate-upgrade-overview/#upgrade) - -If you want to test the procedure before the update happens on 18th of February, please see this post accordingly: - - - -## Preliminary - -Many changes have occurred to the Cosmos SDK and the Gaia application since the latest -major upgrade (`cosmoshub-3`). These changes notably consist of many new features, -protocol changes, and application structural changes that favor developer ergonomics -and application development. - -First and foremost, [IBC](https://docs.cosmos.network/main/ibc/overview.html) following -the [Interchain Standads](https://github.com/cosmos/ics#ibc-quick-references) will be enabled. -This upgrade comes with several improvements in efficiency, node synchronization and following blockchain upgrades. -More details on the [Stargate Website](https://stargate.cosmos.network/). - -__[Gaia](https://github.com/cosmos/gaia) application v4.0.2 is -what full node operators will upgrade to and run in this next major upgrade__. -Following Cosmos SDK version v0.41.2 and Tendermint v0.34.7. - -Validators should expect that at least 16GB of RAM needs to be provisioned to process the first new block on cosmoshub-4. - -## Major Updates - -There are many notable features and changes in the upcoming release of the SDK. Many of these -are discussed at a high level -[here](https://github.com/cosmos/stargate). - -Some of the biggest changes to take note on when upgrading as a developer or client are the following: - -- __Protocol Buffers__: Initially the Cosmos SDK used Amino codecs for nearly all encoding and decoding. -In this version a major upgrade to Protocol Buffers have been integrated. It is expected that with Protocol Buffers -applications gain in speed, readability, convenience and interoperability with many programming languages. -[Read more](https://github.com/cosmos/cosmos-sdk/blob/master/docs/migrations/app_and_modules.md#protocol-buffers) -- __CLI__: The CLI and the daemon for a blockchain were separated in previous versions of the Cosmos SDK. This -led to a `gaiad` and `gaiacli` binary which were separated and could be used for different interactions with the -blockchain. Both of these have been merged into one `gaiad` which now supports the commands the `gaiacli` previously -supported. -- __Node Configuration__: Previously blockchain data and node configuration was stored in `~/.gaia/`, these will -now reside in `~/.gaia/`, if you use scripts that make use of the configuration or blockchain data, make sure to update the path. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from a Tendermint developer -before resetting your validator. - -## Recovery - -Prior to exporting `cosmoshub-3` state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.gaia` directory. - -It is critically important to back-up the `.gaia/data/priv_validator_state.json` file after stopping your gaiad process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must downgrade back to -gaia v2.0.15 with v0.37.15 of the _Cosmos SDK_ and restore to their latest snapshot before restarting their nodes. - -## Upgrade Procedure - -__Note__: It is assumed you are currently operating a full-node running gaia v2.0.15 with v0.37.15 of the _Cosmos SDK_. - -The version/commit hash of Gaia v2.0.15: `89cf7e6fc166eaabf47ad2755c443d455feda02e` - -1. Verify you are currently running the correct version (v2.0.15) of _gaiad_: - - ```bash - $ gaiad version --long - name: gaia - server_name: gaiad - client_name: gaiacli - version: 2.0.15 - commit: 89cf7e6fc166eaabf47ad2755c443d455feda02e - build_tags: netgo,ledger - go: go version go1.15 darwin/amd64 - ``` - -1. Make sure your chain halts at the right time and date: - February 18, 2021 at 06:00 UTC is in UNIX seconds: `1613628000` - - ```bash - perl -i -pe 's/^halt-time =.*/halt-time = 1613628000/' ~/.gaia/config/app.toml - ``` - -1. After the chain has halted, make a backup of your `.gaia` directory - - ```bash - mv ~/.gaia ./gaiad_backup - ``` - - __NOTE__: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating `cosmoshub-3`. See [Recovery](#recovery) for details on how to proceed. - -1. Export existing state from `cosmoshub-3`: - - Before exporting state via the following command, the `gaiad` binary must be stopped! - As a validator, you can see the last block height created in the - `~/.gaia/data/priv_validator_state.json` - or now residing in `gaiad_backup` when you made - a backup as in the last step - and obtain it with - - ```bash - cat ~/.gaia/data/priv_validator_state.json | jq '.height' - ``` - - ```bash - gaiad export --height= > cosmoshub_3_genesis_export.json - ``` - - _this might take a while, you can expect an hour for this step_ - -1. Verify the SHA256 of the (sorted) exported genesis file: - - Compare this value with other validators / full node operators of the network. - Going forward it will be important that all parties can create the same genesis file export. - - ```bash - $ jq -S -c -M '' cosmoshub_3_genesis_export.json | shasum -a 256 - [SHA256_VALUE] cosmoshub_3_genesis_export.json - ``` - -1. At this point you now have a valid exported genesis state! All further steps now require -v4.0.2 of [Gaia](https://github.com/cosmos/gaia). -Cross check your genesis hash with other peers (other validators) in the chat rooms. - - __NOTE__: Go [1.15+](https://golang.org/dl/) is required! - - ```bash - git clone https://github.com/cosmos/gaia.git && cd gaia && git checkout v4.0.2; make install - ``` - -1. Verify you are currently running the correct version (v4.0.2) of the _Gaia_: - - ```bash - name: gaia - server_name: gaiad - version: 4.0.2 - commit: 6d46572f3273423ad9562cf249a86ecc8206e207 - build_tags: netgo,ledger - ... - ``` - - The version/commit hash of Gaia v4.0.2: `6d46572f3273423ad9562cf249a86ecc8206e207` - -1. Migrate exported state from the current v2.0.15 version to the new v4.0.2 version: - - ```bash - gaiad migrate cosmoshub_3_genesis_export.json --chain-id=cosmoshub-4 --initial-height [last_cosmoshub-3_block+1] > genesis.json - ``` - - This will migrate our exported state into the required `genesis.json` file to start the cosmoshub-4. - -1. Verify the SHA256 of the final genesis JSON: - - ```bash - $ jq -S -c -M '' genesis.json | shasum -a 256 - [SHA256_VALUE] genesis.json - ``` - - Compare this value with other validators / full node operators of the network. - It is important that each party can reproduce the same genesis.json file from the steps accordingly. - -1. Reset state: - - __NOTE__: Be sure you have a complete backed up state of your node before proceeding with this step. - See [Recovery](#recovery) for details on how to proceed. - - ```bash - gaiad unsafe-reset-all - ``` - -1. Move the new `genesis.json` to your `.gaia/config/` directory - - ```bash - cp genesis.json ~/.gaia/config/ - ``` - -1. Start your blockchain - - ```bash - gaiad start - ``` - - Automated audits of the genesis state can take 30-120 min using the crisis module. This can be disabled by - `gaiad start --x-crisis-skip-assert-invariants`. - -# Guidance for Full Node Operators - -1. Verify you are currently running the correct version (v2.0.15) of _gaiad_: - - ```bash - $ gaiad version --long - name: gaia - server_name: gaiad - client_name: gaiacli - version: 2.0.15 - commit: 89cf7e6fc166eaabf47ad2755c443d455feda02e - build_tags: netgo,ledger - go: go version go1.15 darwin/amd64 - ``` - -1. Stop your Gaia v2.0.15 instance. - -1. After the chain has halted, make a backup of your `.gaia` directory - - ```bash - mv ~/.gaia ./gaiad_backup - ``` - - __NOTE__: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. That means the backup of `.gaia` should - only take place once the chain has halted at UNIX time `1613628000`. - In such a case, the chain will fallback - to continue operating `cosmoshub-3`. See [Recovery](#recovery) for details on how to proceed. - -1. Download the cosmoshub-4 genesis file from the [Cosmos Mainnet Github](https://github.com/cosmos/mainnet). - This file will be generated by a validator that is migrating from cosmoshub-3 to cosmoshub-4. - The cosmoshub-4 genesis file will be validated by community participants, and - the hash of the file will be shared on the #validators-verified channel of the [Cosmos Discord](https://discord.gg/cosmosnetwork). - -1. Install v4.0.2 of [Gaia](https://github.com/cosmos/gaia). - - __NOTE__: Go [1.15+](https://golang.org/dl/) is required! - - ```bash - git clone https://github.com/cosmos/gaia.git && cd gaia && git checkout v4.0.2; make install - ``` - -1. Verify you are currently running the correct version (v4.0.2) of the _Gaia_: - - ```bash - name: gaia - server_name: gaiad - version: 4.0.2 - commit: 6d46572f3273423ad9562cf249a86ecc8206e207 - build_tags: netgo,ledger - ... - ``` - - The version/commit hash of Gaia v4.0.2: `6d46572f3273423ad9562cf249a86ecc8206e207` - -1. Reset state: - - __NOTE__: Be sure you have a complete backed up state of your node before proceeding with this step. - See [Recovery](#recovery) for details on how to proceed. - - ```bash - gaiad unsafe-reset-all - ``` - -1. Move the new `genesis.json` to your `.gaia/config/` directory - - ```bash - cp genesis.json ~/.gaia/config/ - ``` - -1. Start your blockchain - - ```bash - gaiad start - ``` - - Automated audits of the genesis state can take 30-120 min using the crisis module. This can be disabled by - `gaiad start --x-crisis-skip-assert-invariants`. - -## Notes for Service Providers - -# REST server - -In case you have been running REST server with the command `gaiacli rest-server` previously, running this command will not be necessary anymore. -API server is now in-process with daemon and can be enabled/disabled by API configuration in your `.gaia/config/app.toml`: - -``` -[api] -# Enable defines if the API server should be enabled. -enable = false -# Swagger defines if swagger documentation should automatically be registered. -swagger = false -``` - -`swagger` setting refers to enabling/disabling swagger docs API, i.e, /swagger/ API endpoint. - -# gRPC Configuration - -gRPC configuration in your `.gaia/config/app.toml` - -```yaml -[grpc] -# Enable defines if the gRPC server should be enabled. -enable = true -# Address defines the gRPC server address to bind to. -address = "0.0.0.0:9090" -``` - -# State Sync - -State Sync Configuration in your `.gaia/config/app.toml` - -```yaml -# State sync snapshots allow other nodes to rapidly join the network without replaying historical -# blocks, instead downloading and applying a snapshot of the application state at a given height. -[state-sync] -# snapshot-interval specifies the block interval at which local state sync snapshots are -# taken (0 to disable). Must be a multiple of pruning-keep-every. -snapshot-interval = 0 -# snapshot-keep-recent specifies the number of recent snapshots to keep and serve (0 to keep all). -snapshot-keep-recent = 2 -``` - - diff --git a/docs/docs/migration/archive/cosmoshub-4/_category_.json b/docs/docs/migration/archive/cosmoshub-4/_category_.json deleted file mode 100644 index 02c391ea2cd..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "CosmosHub-4", - "position": 3, - "link": null -} \ No newline at end of file diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v10-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v10-upgrade.md deleted file mode 100644 index 89e56713cfd..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v10-upgrade.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Cosmos Hub 4, Gaia v10 Upgrade Instructions -order: 6 ---- - - -This document describes the steps for validators and full node operators, to upgrade successfully to the v10 release. The v10 upgrade is a mandatory maintenence release which updates the following core libraries: - -- Upgrading Comet BFT to [v0.34.28](https://github.com/cometbft/cometbft/releases/tag/v0.34.28) -- Upgrading Cosmos SDK to [v0.45.16-ics](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.45.16-ics) -- Upgrading IBC Go to [v4.4.0](https://github.com/cosmos/ibc-go/releases/tag/v4.4.0) -- Upgrading Golang to [Golang 1.20.x](https://go.dev/blog/go1.20), making it mandatory to build Gaia with **Golang v1.20.x** - -❗The **preferred binary** for **Mainnet release** is [v10.0.1](https://github.com/cosmos/gaia/releases/tag/v10.0.1), as that version includes a fix for the [IBC Huckleberry fix](https://forum.cosmos.network/t/ibc-security-advisory-huckleberry/10731). v10.0.0 does **NOT** include this fix. - -## Instructions - -- [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) -- [Upgrade date](#upgrade-date) -- [Chain-id will remain the same](#chain-id-will-remain-the-same) -- [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime, cosmoshub-4 (pre-v10 upgrade) is running Gaia v9.1.1](#current-runtime-cosmoshub-4-pre-v10-upgrade-is-running-gaia-v911) - - [Target runtime, cosmoshub-4 (post-v10 upgrade) will run Gaia v10.0.1](#target-runtime-cosmoshub-4-post-v10-upgrade-will-run-gaia-v1000) -- [Upgrade steps](#upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) - - [Preparation](#preparation-1) - - [Expected result](#expected-result) -- [Upgrade duration](#upgrade-duration) -- [Rollback plan](#rollback-plan) -- [Communications](#communications) -- [Risks](#risks) -- [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal #798](https://www.mintscan.io/cosmos/proposals/798) is the reference on-chain governance proposal for this upgrade, which is still in its voting period. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade date - -The upgrade will take place at a block height of `15816200`. The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://www.mintscan.io/cosmos/blocks/15816200) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade by cosmovisor](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v700-binary) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v10 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime, cosmoshub-4 (pre-v10 upgrade) is running Gaia v9.1.1 - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v9.1.1](https://github.com/cosmos/gaia/releases/v9.1.1). We anticipate that operators who are running on v9.1.1, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go `1.20`. - -### Target runtime, cosmoshub-4 (post-v10 upgrade) will run Gaia v10.0.1 - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v10.0.1](https://github.com/cosmos/gaia/releases/tag/v10.0.1). Operators _MUST_ use this version post-upgrade to remain connected to the network. - -## Upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/master/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure Gaia v10.0.1 is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v10.0.1), or building from source. Building from source requires **Golang 1.20**. - -Run Gaia v9.1.1 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v10" NEEDED at height: 15816200: upgrade to v10 and applying upgrade "v10" at height:15816200 -``` - -Stop the node, and switch the binary to Gaia v10.0.1 and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -:::warning -**Please Read Before Proceeding**
-Using Cosmovisor 1.2.0 and higher requires a lowercase naming convention for upgrade version directory. For Cosmovisor 1.1.0 and earlier, the upgrade version is not lowercased. -::: - -> **For Example:**
-> **Cosmovisor =< `1.1.0`: `/upgrades/v9-Lambda/bin/gaiad`**
-> **Cosmovisor >= `1.2.0`: `/upgrades/v9-lambda/bin/gaiad`**
- -| Cosmovisor Version | Binary Name in Path | -|--------------------|---------------------| -| 1.3 | v10 | -| 1.2 | v10 | -| 1.1 | v10 | -| 1.0 | v10 | - -### Manually preparing the binary - -##### Preparation - -Install the latest version of Cosmovisor (`1.3.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -**Verify Cosmovisor Version** -```shell -cosmovisor version -cosmovisor version: v1.3.0 -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v9.1.1 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v10.0.1, and move gaiad v10.0.1 to `$GAIA_HOME/cosmovisor/upgrades/v10/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v10/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v10/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v9.1.1 -└── upgrades - └── v10 - └── bin - └── gaiad #v10.0.1 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take 7 minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -### Auto-Downloading the Gaia binary - -**This method is not recommended!** - -#### Preparation - -Install the latest version of Cosmovisor (`1.3.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v9.1.1 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v9.1.1 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks can help decrease the upgrade time significantly. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v10" NEEDED at height: 15816200: upgrade to v10 and applying upgrade "v10" at height:15816200 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v10/bin` and download the Gaia v10.0.1 binary to this folder according to links in the `--info` field of the upgrade proposal. -This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. -- Users should run their node on v9.1.1 if they use the cosmovisor v1.3.0 with auto-download enabled for upgrade process. - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v9.1.1 binary using the following command: - -> gaiad start --unsafe-skip-upgrade 15816200 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v11-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v11-upgrade.md deleted file mode 100644 index de79d8ec034..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v11-upgrade.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: Cosmos Hub 4, Gaia v11 Upgrade Instructions -order: 7 ---- - - -This document describes the steps for validators and full node operators, to upgrade successfully to the Gaia v11 release. -For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v11.0.0) - -## Instructions - -- [Cosmos Hub 4, Gaia v11 Upgrade, Instructions](#cosmos-hub-4-gaia-v11-upgrade-instructions) - - [Instructions](#instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade date](#upgrade-date) - - [Chain-id will remain the same](#chain-id-will-remain-the-same) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime](#current-runtime) - - [Target runtime](#target-runtime) - - [Upgrade steps](#upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) - - [Preparation](#preparation-1) - - [Expected result](#expected-result) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal 804](https://www.mintscan.io/cosmos/proposals/804) is the reference on-chain governance proposal for this upgrade, which is still in its voting period. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade date - -The upgrade will take place at a block height of `16596000`. The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://www.mintscan.io/cosmos/blocks/16596000) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade using cosmovisor](#method-ii-upgrade-using-cosmovisor) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v11 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v10.0.2](https://github.com/cosmos/gaia/releases/v10.0.2). We anticipate that operators who are running on v10.0.x, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go `1.20`. - -### Target runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v11.0.0](https://github.com/cosmos/gaia/releases/tag/v11.0.0). Operators _**MUST**_ use this version post-upgrade to remain connected to the network. - -## Upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/master/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure Gaia v11.0.0 is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v11.0.0), or building from source. Building from source requires **Golang 1.20**. - -Run Gaia v10.0.x till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v11" NEEDED at height: 16596000: upgrade to v11 and applying upgrade "v11" at height:16596000 -``` - -Stop the node, and switch the binary to Gaia v11.0.0 and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -### Manually preparing the binary - -##### Preparation - -Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -**Verify Cosmovisor Version** -```shell -cosmovisor version -cosmovisor version: v1.5.0 -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v9.1.1 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v11.0.0, and move gaiad v11.0.0 to `$GAIA_HOME/cosmovisor/upgrades/v11/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v11/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v11/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v10.0.x -└── upgrades - └── v11 - └── bin - └── gaiad #v11.0.0 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take 7 minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -### Auto-Downloading the Gaia binary - -**This method is not recommended!** - -#### Preparation - -Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v10.0.x into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v10.0.x -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks can help decrease the upgrade time significantly. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v11" NEEDED at height: 16596000: upgrade to v11 and applying upgrade "v11" at height:16596000 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v11/bin` and download the Gaia v11.0.0 binary to this folder according to links in the `--info` field of the upgrade proposal. -This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. -- Users should run their node on v10.0.x if they use the cosmovisor v1.5.0 with auto-download enabled for upgrade process. - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v10.0.2 binary using the following command: - -> gaiad start --unsafe-skip-upgrade 16596000 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v12-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v12-upgrade.md deleted file mode 100644 index 1b93456e29d..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v12-upgrade.md +++ /dev/null @@ -1,283 +0,0 @@ ---- -title: Cosmos Hub 4, Gaia v12 Upgrade -order: 8 ---- - - -This document describes the steps for validators and full node operators, to upgrade successfully to the Gaia v12 release. -For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v12.0.0) - -## Instructions - -- [Cosmos Hub 4, Gaia v12 Upgrade, Instructions](#cosmos-hub-4-gaia-v12-upgrade-instructions) - - [Instructions](#instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Liquid Staking](#liquid-staking) - - [Upgrade date](#upgrade-date) - - [Chain-id will remain the same](#chain-id-will-remain-the-same) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime](#current-runtime) - - [Target runtime](#target-runtime) - - [Upgrade steps](#upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) - - [Preparation](#preparation-1) - - [Expected result](#expected-result) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal 821](https://www.mintscan.io/cosmos/proposals/821) is the reference on-chain governance proposal for this upgrade, which is still in its voting period. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Liquid Staking - -Validators please be aware that this release will include a new liquid staking module which has been included via the Cosmos SDK. Please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v12.0.0) for v12 for more information about this module. - -**IMPORTANT:** Inclusion of this module requires validators to set a validation-bond to be eligiable for Liquid Staked delegations. Please see the [Validator FAQ](/validators/validator-faq.html#liquid-staking-module) for more information. - -## Upgrade date - -The upgrade will take place at a block height of `16985500`. The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://www.mintscan.io/cosmos/blocks/16985500) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade using cosmovisor](#method-ii-upgrade-using-cosmovisor) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v12 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v11.0.0](https://github.com/cosmos/gaia/releases/v11.0.0). We anticipate that operators who are running on v11.0.x, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go `1.20`. - -### Target runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v12.0.0](https://github.com/cosmos/gaia/releases/tag/v12.0.0). Operators _**MUST**_ use this version post-upgrade to remain connected to the network. - -## Upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://pkg.go.dev/cosmossdk.io/tools/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure Gaia v12.0.0 is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v12.0.0), or building from source. Building from source requires **Golang 1.20**. - -Run Gaia v11.0.0 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v12" NEEDED at height: 16985500: upgrade to v12 and applying upgrade "v12" at height:16985500 -``` - -Stop the node, and switch the binary to Gaia v12.0.0 and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -### Manually preparing the binary - -##### Preparation - -Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -``` - -**Verify Cosmovisor Version** -```shell -cosmovisor version -cosmovisor version: v1.5.0 -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v11.0.0 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v12.0.0, and move gaiad v12.0.0 to `$GAIA_HOME/cosmovisor/upgrades/v12/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v12/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v12/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v11.0.x -└── upgrades - └── v12 - └── bin - └── gaiad #v12.0.0 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take 7 minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -### Auto-Downloading the Gaia binary - -**This method is not recommended!** - -#### Preparation - -Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v11.0.x into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v11.0.x -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks can help decrease the upgrade time significantly. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v12" NEEDED at height: 16985500: upgrade to v12 and applying upgrade "v12" at height:16985500 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v12/bin` and download the Gaia v12.0.0 binary to this folder according to links in the `--info` field of the upgrade proposal. -This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. -- Users should run their node on v11.0.x if they use the cosmovisor v1.5.0 with auto-download enabled for upgrade process. - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v11.0.0 binary using the following command: - -> gaiad start --unsafe-skip-upgrade 16985500 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v13-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v13-upgrade.md deleted file mode 100644 index 50b447e877f..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v13-upgrade.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: Cosmos Hub 4, Gaia v13 Upgrade -order: 8 ---- - - -This document describes the steps for validators and full node operators, to upgrade successfully to the Gaia v13 release. -For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v13.0.0) - -## Instructions - -- [Cosmos Hub 4, Gaia v13 Upgrade, Instructions](#cosmos-hub-4-gaia-v13-upgrade-instructions) - - [Instructions](#instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade date](#upgrade-date) - - [Chain-id will remain the same](#chain-id-will-remain-the-same) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime](#current-runtime) - - [Target runtime](#target-runtime) - - [Upgrade steps](#upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) - - [Preparation](#preparation-1) - - [Expected result](#expected-result) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal 825](https://www.mintscan.io/cosmos/proposals/825) is the reference on-chain governance proposal for this upgrade, which is still in its voting period. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade date - -The upgrade will take place at a block height of `17380000`. The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://www.mintscan.io/cosmos/blocks/17380000) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade using cosmovisor](#method-ii-upgrade-using-cosmovisor) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v13 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v12.0.0](https://github.com/cosmos/gaia/releases/v12.0.0). We anticipate that operators who are running on v11.0.x, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go `1.20`. - -### Target runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v13.0.0](https://github.com/cosmos/gaia/releases/tag/v13.0.0). Operators _**MUST**_ use this version post-upgrade to remain connected to the network. - -## Upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://pkg.go.dev/cosmossdk.io/tools/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure Gaia v13.0.0 is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v13.0.0), or building from source. Building from source requires **Golang 1.20.x**. - -Run Gaia v12.0.0 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v13" NEEDED at height: 17380000: upgrade to v13 and applying upgrade "v13" at height:17380000 -``` - -Stop the node, and switch the binary to Gaia v13.0.0 and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -### Manually preparing the binary - -##### Preparation - -Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -``` - -**Verify Cosmovisor Version** -```shell -cosmovisor version -cosmovisor version: v1.5.0 -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v12.0.0 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v13.0.0, and move gaiad v13.0.0 to `$GAIA_HOME/cosmovisor/upgrades/v13/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v13/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v13/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v12.0.x -└── upgrades - └── v13 - └── bin - └── gaiad #v13.0.0 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take a few minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -### Auto-Downloading the Gaia binary - -**This method is not recommended!** - -#### Preparation - -Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v12.0.x into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v12.0.x -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks can help decrease the upgrade time significantly. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v13" NEEDED at height: 17380000: upgrade to v13 and applying upgrade "v13" at height:17380000 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v13/bin` and download the Gaia v13.0.0 binary to this folder according to links in the `--info` field of the upgrade proposal. -This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. -- Users should run their node on v12.0.x if they use the cosmovisor v1.5.0 with auto-download enabled for upgrade process. - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v12.0.0 binary using the following command: - -> gaiad start --unsafe-skip-upgrade 17380000 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v14-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v14-upgrade.md deleted file mode 100644 index 92f87021e09..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v14-upgrade.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: Cosmos Hub 4, Gaia v14 Upgrade -order: 9 ---- - - -This document describes the steps for validators, full node operators and relayer operators, to upgrade successfully for the Gaia v14 release. - -For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v14.1.0) - -**Relayer Operators** for the Cosmos Hub and consumer chains, will also need to update to use [Hermes 1.7.3](https://github.com/informalsystems/hermes/releases/tag/v1.7.3) or higher, see [Relayer Operations](#relayer-operations) or more details. - -## Release Binary - -> Please note that the **v14.0.0** binary is depreceated and **ALL** validators **MUST** use the **v14.1.0** binary instead. - -## Instructions - -- [Cosmos Hub 4, Gaia v14 Upgrade, Instructions](#cosmos-hub-4-gaia-v14-upgrade-instructions) - - [Release Binary](#release-binary) - - [Instructions](#instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade date](#upgrade-date) - - [Chain-id will remain the same](#chain-id-will-remain-the-same) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime](#current-runtime) - - [Target runtime](#target-runtime) - - [Upgrade steps](#upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Relayer Operations](#relayer-operations) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal 854](https://www.mintscan.io/cosmos/proposals/854) is the reference on-chain governance proposal for this upgrade, which is still in its voting period. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade date - -The upgrade will take place at a block height of `18262000`. The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://www.mintscan.io/cosmos/blocks/18262000) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -System requirements for validator nodes can be found [here](../../../getting-started/system-requirements.md). - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade using cosmovisor](#method-ii-upgrade-using-cosmovisor) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v14 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v13.0.0](https://github.com/cosmos/gaia/releases/v13.0.0). We anticipate that operators who are running on v13.0.x, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go `1.20`. - -### Target runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run **[Gaia v14.1.0](https://github.com/cosmos/gaia/releases/tag/v14.1.0)**. Operators _**MUST**_ use this version post-upgrade to remain connected to the network. - -## Upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://pkg.go.dev/cosmossdk.io/tools/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure **Gaia v14.1.0** is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v13.0.0), or building from source. Building from source requires **Golang 1.20.x**. - -Run Gaia v13.0.0 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v14" NEEDED at height: 18262000: upgrade to v14 and applying upgrade "v14" at height:18262000 -``` - -Stop the node, and switch the binary to **Gaia v14.1.0** and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -### Manually preparing the binary - -##### Preparation - -Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -``` - -**Verify Cosmovisor Version** -```shell -cosmovisor version -cosmovisor version: v1.5.0 -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v13.0.0 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -Build Gaia **v14.1.0**, and move gaiad **v14.1.0** to `$GAIA_HOME/cosmovisor/upgrades/v14/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v14/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v14/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v13.0.x -└── upgrades - └── v14 - └── bin - └── gaiad #v14.1.0 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take a few minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -### Auto-Downloading the Gaia binary - -**This method is not recommended!** - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v13.0.x binary using the following command: - -> gaiad start --unsafe-skip-upgrade 18262000 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Relayer Operations - -The Gaia `v14.1.0` upgrade brings forth the cryptographic verification of equivocation feature from ICS `v2.4.0-lsm`. This important security enhancement empowers external agents to promptly submit evidence evidence of light client and double signing attacks observed on a consumer chain. Operators can seize the control of this feature using either the dedicated ICS CLI commands or unleash the power of the Hermes IBC relayer in “evidence” mode. - -This feature is supported by an updated [Hermes v1.7.3](https://github.com/informalsystems/hermes/releases/tag/v1.7.3). - -### **1. Hermes “evidence” mode** - -Ensure you have a well-configured Hermes `v1.7.3+` relayer effectively relaying packets between a consumer and a provider chain. The following command demonstrates how to run a Hermes instance in “evidence” mode to detect misbehaviors on a consumer chain. - -```sh -hermes evidence --chain -``` - -**Tip**: this command takes a `--check-past-blocks` option giving the possibility to look for older evidences (default is `100`). - -### **2. ICS CLI** - -The ICS provider module offers two commands for submitting evidence of misbehavior originating from a consumer chain. Here are two examples illustrating the process: - -To submit evidence of a double-vote: - -```sh -gaiad tx provider submit-consumer-double-voting [path/to/evidence.json] [path/to/infraction_header.json] --from node0 --home ../node0 --chain-id $CID -``` - -And for a light client attack: - -```sh -gaiad tx provider submit-consumer-misbehaviour [path/to/misbehaviour.json] --from node0 --home ../node0 --chain-id $CID -``` - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v15-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v15-upgrade.md deleted file mode 100644 index f6f9894a1e6..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v15-upgrade.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: Cosmos Hub 4, Gaia v15.1 Upgrade -order: 10 ---- - - -# Upgrading Gaia - -This guide provides instructions for upgrading Gaia from v14.2.x to v15.1.x. - -This document describes the steps for validators, full node operators and relayer operators, to upgrade successfully for the Gaia v15 release. - -For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v15.1.0) - -**Relayer Operators** for the Cosmos Hub and consumer chains, will also need to update to use [Hermes v1.8.0](https://github.com/informalsystems/hermes/releases/tag/v1.8.0) or higher. You may need to restart your relayer software after a major chain upgrade. - -## Release Binary - -Please use the correct release binary: `v15.1.0`. - -## Instructions - -- [Upgrading Gaia](#upgrading-gaia) - - [Release Binary](#release-binary) - - [Instructions](#instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade date](#upgrade-date) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirements](#system-requirements) - - [An Important Note for Node Operators](#an-important-note-for-node-operators) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime](#current-runtime) - - [Target runtime](#target-runtime) - - [Upgrade steps](#upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -Once a software upgrade governance proposal is submitted to the Cosmos Hub, both a reference to this proposal and an `UPGRADE_HEIGHT` are added to the [release notes](https://github.com/cosmos/gaia/releases/tag/v15.1.0). -If and when this proposal reaches consensus, the upgrade height will be used to halt the "old" chain binaries. You can check the proposal on one of the block explorers or using the `gaiad` CLI tool. -Neither core developers nor core funding entities control the governance. - -## Upgrade date - -The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date by checking the estimated time until the block is produced at one of the block explorers (e.g. https://www.mintscan.io/cosmos/blocks/`UPGRADE_HEIGHT`). - -## Preparing for the upgrade - -### System requirements - -#### An Important Note for Node Operators - -We recommend validators to temporarily upgrade their hardware before attempting the upgrade to offset any risk associated with migrating from cosmos-sdk v45 to v47. - -These are the recommended revised hardware requirements for the upgrade: - -- Minimum: 64GB RAM + 32GB swap -- Recommended: 128GB RAM -- **Bare minimum** 32GB RAM + 64GB swap - -Optimal CPU performance:  2.50GHz, 8 cores (eg Intel Xeon Gold 6248 or equivalent consumer grade processor). - -It is paramount that the operators set enough SWAP to cover all cases. SWAP partitions can be used to supplement the RAM requirement but they will increase the upgrade time. - -After the upgrade you can revert your hardware setting to the recommended system requirements for normal [day-to-day operations](../../../getting-started/system-requirements.md). - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade using cosmovisor](#method-ii-upgrade-using-cosmovisor) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v15 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v14.2.0](https://github.com/cosmos/gaia/releases/v14.2.0). We anticipate that operators who are running on v14.2.0, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary and if building from source, building with the appropriate `go` version. - -### Target runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run **[Gaia v15.1.0](https://github.com/cosmos/gaia/releases/tag/v15.1.0)**. Operators _**MUST**_ use this version post-upgrade to remain connected to the network. The new version requires `go v1.21` to build successfully. - -## Upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://pkg.go.dev/cosmossdk.io/tools/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure **Gaia v14.2.0** is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v14.2.0), or building from source. Check the required version to build this binary in the `Makefile`. - -Run Gaia v14.2.0 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v15" NEEDED at height: : upgrade to v15 and applying upgrade "v15" at height: -``` - -Stop the node, and switch the binary to **Gaia v15.1.0** and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -#### Manually preparing the binary - -##### Preparation - -- Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -cosmovisor version -# cosmovisor version: v1.5.0 -``` - -- Create a `cosmovisor` folder inside `$GAIA_HOME` and move Gaia `v14.2.0` into `$GAIA_HOME/cosmovisor/genesis/bin`: - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -- Build Gaia `v15.1.0`, and move gaiad `v15.1.0` to `$GAIA_HOME/cosmovisor/upgrades/v15/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v15/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v15/bin -``` - -At this moment, you should have the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad # old: v14.2.0 -└── upgrades - └── v15 - └── bin - └── gaiad # new: v15.1.0 -``` - -- Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -- Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -##### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take a few minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -#### Auto-Downloading the Gaia binary - -**This method is not recommended!** - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v14.2.0 binary using the following command: - -```shell -gaiad start --unsafe-skip-upgrade -``` - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v5-delta-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v5-delta-upgrade.md deleted file mode 100644 index ddc70af559c..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v5-delta-upgrade.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Cosmos Hub 4, v5-Delta Upgrade Instructions -order: 1 ---- - - -This document describes the steps for validator and full node operators for the successful execution of the [Delta Upgrade](https://github.com/cosmos/gaia/blob/main/docs/roadmap/cosmos-hub-roadmap-2.0.md#Delta-Upgrade), which adds the __Gravity DEX__ to the Cosmos Hub. - -TOC: - -- [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) -- [Upgrade will take place July 12, 2021](#upgrade-will-take-place-july-12-2021) -- [Chain-id will remain the same](#chain-id-will-remain-the-same) -- [Preparing for the upgrade](#preparing-for-the-upgrade) - - [Backups](#backups) - - [Testing](#testing) - - [Public testnet](#public-testnet) - - [Current runtime, cosmoshub-4 (pre-Delta upgrade) is running Gaia v4.2.1](#current-runtime-cosmoshub-4-pre-delta-upgrade-is-running-gaia-v421) - - [Target runtime, cosmoshub-4 (post-Delta upgrade) will run Gaia v5.0.0](#target-runtime-cosmoshub-4-post-delta-upgrade-will-run-gaia-v500) -- [Delta upgrade steps](#delta-upgrade-steps) -- [Upgrade duration](#upgrade-duration) -- [Rollback plan](#rollback-plan) -- [Communications](#communications) -- [Risks](#risks) -- [FAQ](#faq) - -## On-chain governance proposal attains consensus - -[Proposal #51](https://www.mintscan.io/cosmos/proposals/51) is the reference on-chain governance proposal for this upgrade, which has passed with overwhelming community support. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade will take place July 12, 2021 - -The upgrade will take place at a block height of `6910000`. At current block times (around 7s/block), this block height corresponds approximately to `Mon Jul 12 2021 11:00:00 GMT+0000`. This date/time is approximate as blocks are not generated at a constant interval. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, complete and detailed testing instructions are provided in the [gravity-dex-upgrade-test](https://github.com/b-harvest/gravity-dex-upgrade-test/) Github repository. This repository has been tested by members of the core Cosmos ecosystem, as well as ecosystem partners which include validators, exchanges, and service providers. - -### Public testnet - -Validator and full node operators that wish to test their systems on a public testnet are encouraged to join the Tendermint team's public testnet, described [here](https://github.com/b-harvest/gravity-dex-upgrade-test/#public-testnet-info). - -### Current runtime, cosmoshub-4 (pre-Delta upgrade) is running Gaia v4.2.1 - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v4.2.1](https://github.com/cosmos/gaia/releases/tag/v4.2.1). We anticipate that operators who are running earlier versions of Gaia, e.g., v4.2.x, will be able to upgrade successfully; however, this is untested and it is up to operators to ensure that their systems are capable of performing the upgrade. - -### Target runtime, cosmoshub-4 (post-Delta upgrade) will run Gaia v5.0.0 - -The Comsos Hub mainnet network, `cosmoshub-4`, will run [Gaia v5.0.0](https://github.com/cosmos/gaia/releases/tag/v5.0.0). Operators _MUST_ use this version post-upgrade to remain connected to the network. - -## Delta upgrade steps - -The following steps assume that an operator is running v4.2.1 (running an earlier version is untested). The upgrade has only been tested with v4.2.1 and these instructions follow this prerequisite. - -1. Prior to the upgrade, operators _MUST_ be running Gaia v4.2.1. -2. At the upgrade block height of [6910000](#Upgrade-will-take-place-July-12,-2021), the Gaia software will panic with a message similar to the below: - -> ERR UPGRADE "Gravity-DEX" NEEDED at height: 6910000: v5.0.0-4760cf1f1266accec7a107f440d46d9724c6fd08 -> -> panic: UPGRADE "Gravity-DEX" NEEDED at height: 6910000: v5.0.0-4760cf1f1266accec7a107f440d46d9724c6fd08 - -__IMPORTANT: PLEASE WAIT FOR THE BINARY TO HALT ON ITS OWN__. Do NOT shutdown the node yourself. If the node shuts down before the panic message, start the node and let it run until the panic stops the node for you. - -3. Important note to all validators: Although the upgrade path is essentially to replace the binary when the software panics and halts at the upgrade height, an important disaster recovery operation is to take a snapshot of your state after the halt and before starting v5.0.0. - -```bash -cp -r ~/.gaia ./gaia_backup -``` - -Note: use the home directory relevant to your node's Gaia configuration (if different from `~/.gaia`). - -4. Replace the Gaia v4.2.1 binary with the Gaia v5.0.0 binary -5. Start the Gaia v5.0.0 binary using the following command (also applying any additional flags and parameters to the binary needed by the operator, e.g., `--home $HOME`): - -> gaiad start --x-crisis-skip-assert-invariants - -IMPORTANT: The flag `--x-crisis-skip-assert-invariants` is optional and can be used to reduce memory and processing requirements while the in-place ugprade takes place before resuming connecting to the network. - -5. Wait until 2/3+ of voting power has upgraded for the network to start producing blocks -6. You can use the following commands to check peering status and state: - -> curl -s | grep n_peers -> -> curl -s localhost:26657/consensus_state | jq -r .result.round_state.height_vote_set[].prevotes_bit_array - -## Upgrade duration - -The upgrade may take several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v4.2.1 binary using the following command: - -> gaiad start --unsafe-skip-upgrade 6910000 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#validators-verified` channel of the Cosmos Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand - requests to join the `#validators-verified` channel can be sent to the `#validators-public` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## FAQ - -1. If I am a new operator and I want to join the network, what should I do? - -In order to join the cosmoshub-4 network after the Delta upgrade, you have two options: - -- Use a post-delta upgrade state snapshot, such as one provided by [quicksync](https://cosmos.quicksync.io/) and start a node using the gaia v5.0.0 binary. -- If not using a snapshot, or using a pre-delta upgrade snapshot, sync with the network using the gaia v4.2.1 binary until the upgrade height and panic, then switch the gaia binary for v5.0.0. - -2. Does the post-Delta upgrade introduce any changes of note? - -The core Cosmos SDK and Tendermint dependencies have only their minor versions bumped, so there are no significant changes of note to the API. - -The only integration points that would be affected would be anything that parses all Cosmos SDK messages. The additional messages are [here](https://github.com/Gravity-Devs/liquidity/blob/master/proto/tendermint/liquidity/v1beta1/tx.proto). - -3. Is Amino still supported in the post-Delta upgrade? - -Amino is still supported. Amino support is still present in the master branch of the Cosmos SDK. No upgrade to remove Amino is currently scheduled. - -4. Has the Gravity DEX module undergone a professional 3rd-party audit? - -Yes, the audit was led by Least Authority, and have released the [audit report](https://leastauthority.com/blog/audit-of-cosmos-sdk-liquidity-module-for-all-in-bits/). - -4. We have some self-healing node infrastructure in place. If the node starts failing when the chain halts, and we automatically spin up another 4.2.1 node with state from within the past couple of hours, is there a risk of it double signing transactions as it "catches up" to the point where block processing stops? - -When the network is halted, there is no risk of double-signing since no blocks are being produced. You only need to ensure that the self-healing infrastructure does not launch multiple validators when the network resumes block production. As well, if any new node is spun up while the chain is halted, live peers will continue to share historical blocks without producing new blocks. - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v6-vega-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v6-vega-upgrade.md deleted file mode 100644 index 8ae9c880247..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v6-vega-upgrade.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: Cosmos Hub 4, v6-Vega Upgrade Instructions -order: 2 ---- - - - -This document describes the steps for validator and full node operators for the successful execution of the [Vega Upgrade](https://github.com/cosmos/gaia/blob/main/docs/roadmap/cosmos-hub-roadmap-2.0.md#vega-upgrade-expected-q4-2021), which contains the following main new features: - -- [authz](https://github.com/cosmos/cosmos-sdk/tree/v0.44.3/x/authz/spec) and [feegrant modules](https://github.com/cosmos/cosmos-sdk/tree/v0.44.3/x/feegrant/spec) -- [packet-forward-middleware](https://github.com/strangelove-ventures/packet-forward-middleware) -- [IBC](https://github.com/cosmos/ibc-go) as a standalone module - -TOC: - -- [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) -- [Upgrade will take place December 14, 2021](#upgrade-will-take-place-december-14-2021) -- [Chain-id will remain the same](#chain-id-will-remain-the-same) -- [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime, cosmoshub-4 (pre-Vega upgrade) is running Gaia v5.0.0](#current-runtime-cosmoshub-4-pre-vega-upgrade-is-running-gaia-v500) - - [Target runtime, cosmoshub-4 (post-Vega upgrade) will run Gaia v6.0.4](#target-runtime-cosmoshub-4-post-vega-upgrade-will-run-gaia-v604) -- [Vega upgrade steps](#vega-upgrade-steps) - - [Method I: manual upgrade](#method-i-manual-upgrade) - - - [Method II: upgrade using Cosmovisor by manually preparing the Gaia v6.0.4 binary](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v604-binary) - - [Method III: upgrade using Cosmovisor by auto-downloading the Gaia v6.0.4 binary (not recommended!)](#method-iii-upgrade-using-cosmovisor-by-auto-downloading-the-gaia-v604-binary-not-recommended) -- [Upgrade duration](#upgrade-duration) -- [Rollback plan](#rollback-plan) -- [Communications](#communications) -- [Risks](#risks) -- [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal #59](https://www.mintscan.io/cosmos/proposals/59) is the reference on-chain governance proposal for this upgrade, which has passed with overwhelming community support. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade will take place December 14, 2021 - -The upgrade will take place at a block height of `8695000`. At the time of writing, and at current block times (around 7s/block), this block height corresponds approximately to `Tuesday, 14-Dec-21 14:49:50 UTC`. This date/time is approximate as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://chain-monitor.cros-nest.com/d/Upgrades/upgrades?var-chain_id=cosmoshub-4&orgId=1&refresh=1m) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade by cosmovisor](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v600-binary) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can join in our [Vega public-testnet](https://github.com/cosmos/vega-test/tree/master/public-testnet) or run a [Vega local testnet](https://github.com/cosmos/vega-test/tree/master/local-testnet). - -### Current runtime, cosmoshub-4 (pre-Vega upgrade) is running Gaia v5.0.0 - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v5.0.0](https://github.com/cosmos/gaia/releases/tag/v5.0.0). We anticipate that operators who are running on v5.0.x, will be able to upgrade successfully; however, this is untested and it is up to operators to ensure that their systems are capable of performing the upgrade. - -### Target runtime, cosmoshub-4 (post-Vega upgrade) will run Gaia v6.0.4 - -The Comsos Hub mainnet network, `cosmoshub-4`, will run [Gaia v6.0.4](https://github.com/cosmos/gaia/releases/tag/v6.0.4). Operators _MUST_ use this version post-upgrade to remain connected to the network. - -## Vega upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/master/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: manual upgrade - -Run Gaia v5.0.x till upgrade height, the node will panic: - -```shell -ERR UPGRADE "Vega" NEEDED at height: 8695000 - -panic: UPGRADE "Vega" NEEDED at height: 8695000 -``` - -Stop the node, and install Gaia v6.0.4 and re-start by `gaiad start`. - -It may take 20 min to a few hours until validators with a total sum voting power > 2/3 to complete their nodes upgrades. After that, the chain can continue to produce blocks. - -### Method II: upgrade using Cosmovisor by manually preparing the Gaia v6.0.4 binary - -#### Preparation - -Install the latest version of Cosmovisor: - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v5.0.0 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v6.0.4, and move gaiad v6.0.4 to `$GAIA_HOME/cosmovisor/upgrades/Vega/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/Vega/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/Vega/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v5.0.x -└── upgrades -└── Vega -└── bin - └── gaiad #v6.0.4 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME= $GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor start --x-crisis-skip-assert-invariants -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "Vega" NEEDED at height: 8695000: upgrade to Vega and applying upgrade "Vega" at height:8695000. -``` - - This may take 20 min to a few hours. - After this, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their nodes upgrades. - -### Method III: upgrade using Cosmovisor by auto-downloading the Gaia v6.0.4 binary (not recommended!) - -#### Preparation - -Install Cosmovisor v0.1 - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v0.1.0 -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v5.0.0 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v5.0.x -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME= $GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor start --x-crisis-skip-assert-invariants -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "Vega" NEEDED at height: 8695000: upgrade to Vega and applying upgrade "Vega" at height:8695000 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/Vega/bin` and download Gaia v6.0.4 binary to this folder according to links in the `--info` field of the upgrade proposal 59. -This may take 20 min to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -Auto-download the new binary is not recommended for the following reasons: - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If you want to have the highest guarantee you should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk you should take at your own discretion. -- For the Vega upgrade, Gaia will upgrade its dependency on Cosmos SDK v0.42 to Cosmos SDK v0.44, this will require [Cosmovisor v0.1](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv0.1.0). Later versions of Cosmovisor do not support Cosmos SDK v0.42 or earlier if the auto-download option is enabled. -- By using Cosmovisor v0.1 you might experience a [node hanging issue](https://github.com/cosmos/cosmos-sdk/issues/9875) when querying a result with a large output size. For example, `gaiad q gov proposals` will hang the node being queried, this issue will not appear for Cosmovisor versions newer than v0.1. - -## Upgrade duration - -The upgrade may take several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v5.0.x binary using the following command: - -> gaiad start --unsafe-skip-upgrade 8695000 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#validators-verified` channel of the Cosmos Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[cosmos/vega-test](https://github.com/cosmos/vega-test) - -[Delta upgrade instruction](https://github.com/cosmos/gaia/tree/main/docs/docs/migration/cosmoshub-4-delta-upgrade.md) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v7-Theta-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v7-Theta-upgrade.md deleted file mode 100644 index 990f4754e7f..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v7-Theta-upgrade.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: Cosmos Hub 4, v7-Theta Upgrade Instructions -order: 3 ---- - - -This document describes the steps for validator and full node operators for the successful execution of the [v7-Theta Upgrade](https://github.com/cosmos/gaia/blob/main/docs/roadmap/cosmos-hub-roadmap-2.0.md#v7-theta-upgrade-expected-q1-2022), which contains the following main new features/improvement: - -- [cosmos-sdk](https://github.com/cosmos/cosmos-sdk) to [v0.45.1](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.45.1). See [CHANGELOG.md](https://github.com/cosmos/cosmos-sdk/blob/v0.45.1/CHANGELOG.md#v0451---2022-02-03) for details. -- [ibc-go](https://github.com/cosmos/ibc-go) module to [v3.0.0](https://github.com/cosmos/ibc-go/releases/tag/v3.0.0). See [CHANGELOG.md](https://github.com/cosmos/ibc-go/blob/v3.0.0/CHANGELOG.md#v300---2022-03-15) for details. -- [interchain account](https://github.com/cosmos/ibc-go/tree/main/modules/apps/27-interchain-accounts) module (interchain-account module is part of ibc-go module). -- [liquidity](https://github.com/gravity-devs/liquidity) module to [v1.5.0](https://github.com/Gravity-Devs/liquidity/releases/tag/v1.5.0). See [CHANGELOG.md](https://github.com/Gravity-Devs/liquidity/blob/v1.5.0/CHANGELOG.md#v150---20220223) for details. -- [packet-forward-middleware](https://github.com/strangelove-ventures/packet-forward-middleware) module to [v2.1.1](https://github.com/strangelove-ventures/packet-forward-middleware/releases/tag/v2.1.1). -- Migration logs for upgrade process. - -TOC: - -- [Cosmos Hub 4, v7-Theta Upgrade, Instructions](#cosmos-hub-4-v7-theta-upgrade-instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade will take place April 12, 2022](#upgrade-will-take-place-april-12-2022) - - [Chain-id will remain the same](#chain-id-will-remain-the-same) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime, cosmoshub-4 (pre-v7-Theta upgrade) is running Gaia v6.0.x](#current-runtime-cosmoshub-4-pre-v7-theta-upgrade-is-running-gaia-v60x) - - [Target runtime, cosmoshub-4 (post-v7-Theta upgrade) will run Gaia v7.0.0](#target-runtime-cosmoshub-4-post-v7-theta-upgrade-will-run-gaia-v700) - - [v7-Theta upgrade steps](#v7-theta-upgrade-steps) - - [Method I: manual upgrade](#method-i-manual-upgrade) - - [Method II: upgrade using Cosmovisor by manually preparing the Gaia v7.0.0 binary](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v700-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Method III: upgrade using Cosmovisor by auto-downloading the Gaia v7.0.0 binary (not recommended!)](#method-iii-upgrade-using-cosmovisor-by-auto-downloading-the-gaia-v700-binary-not-recommended) - - [Preparation](#preparation-1) - - [Expected result](#expected-result) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal #65](https://www.mintscan.io/cosmos/proposals/65) is the reference on-chain governance proposal for this upgrade, which has passed with overwhelming community support. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade will take place April 12, 2022 - -The upgrade will take place at a block height of `10085397`. At the time of writing, and at current block times (around 7s/block), this block height corresponds approximately to `Tuesday, 12-April-21 16:14:40 UTC`. This date/time is approximate as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://chain-monitor.cros-nest.com/d/Upgrades/upgrades?var-chain_id=cosmoshub-4&orgId=1&refresh=1m) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade by cosmovisor](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v700-binary) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can join in our [v7-Theta public-testnet](https://github.com/cosmos/testnets/tree/master/v7-theta/public-testnet) or run a [v7-Theta local testnet](https://github.com/cosmos/testnets/tree/master/local/previous-local-testnets/v7-theta). - -### Current runtime, cosmoshub-4 (pre-v7-Theta upgrade) is running Gaia v6.0.x - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v6.0.4](https://github.com/cosmos/gaia/releases/v6.0.4). We anticipate that operators who are running on v6.0.x, will be able to upgrade successfully; however, this is untested and it is up to operators to ensure that their systems are capable of performing the upgrade. - -### Target runtime, cosmoshub-4 (post-v7-Theta upgrade) will run Gaia v7.0.0 - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v7.0.0](https://github.com/cosmos/gaia/releases/tag/v7.0.0). Operators _MUST_ use this version post-upgrade to remain connected to the network. - -## v7-Theta upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/master/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: manual upgrade - -Run Gaia v6.0.x till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v7-Theta" NEEDED at height: 10085397 - -panic: UPGRADE "v7-Theta" NEEDED at height: 10085397 -``` - -Stop the node, and install Gaia v7.0.0 and re-start by `gaiad start`. - -It may take 7 minutes to a few hours until validators with a total sum voting power > 2/3 to complete their nodes upgrades. After that, the chain can continue to produce blocks. - -### Method II: upgrade using Cosmovisor by manually preparing the Gaia v7.0.0 binary - -#### Preparation - -Install the latest version of Cosmovisor: - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v6.0.4 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v7.0.0, and move gaiad v7.0.0 to `$GAIA_HOME/cosmovisor/upgrades/v7-Theta/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v7-Theta/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v7-Theta/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v6.0.4 -└── upgrades - └── v7-Theta - └── bin - └── gaiad #v7.0.0 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME= $GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor start --x-crisis-skip-assert-invariants -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v7-Theta" NEEDED at height: 10085397: upgrade to v7-Theta and applying upgrade "v7-Theta" at height:10085397. -``` - - This may take 7 minutes to a few hours. - After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their nodes upgrades. - -### Method III: upgrade using Cosmovisor by auto-downloading the Gaia v7.0.0 binary (not recommended!) - -#### Preparation - -Install Cosmovisor v1.1.0 - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v6.0.4 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v6.0.4 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME= $GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor start --x-crisis-skip-assert-invariants -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v7-Theta" NEEDED at height: 10085397: upgrade to v7-Theta and applying upgrade "v7-Theta" at height:10085397 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v7-Theta/bin` and download Gaia v7.0.0 binary to this folder according to links in the `--info` field of the upgrade proposal 65. -This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. -- Users should use run node on v6.0.4 if they use the cosmovisor v1.1.0 with auto-download enabled for upgrade process. - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v6.0.x binary using the following command: - -> gaiad start --unsafe-skip-upgrade 10085397 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#validators-verified` channel of the Cosmos Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[cosmos/v7-Theta-test](https://github.com/cosmos/testnets/tree/master/v7-theta) -[join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v8-Rho-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v8-Rho-upgrade.md deleted file mode 100644 index 0960a15c3d1..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v8-Rho-upgrade.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Cosmos Hub 4, v8-Rho Upgrade Instructions -order: 4 ---- - - -This document describes the steps for validator and full node operators for the successful execution of the [v8-Rho Upgrade](https://github.com/cosmos/gaia/blob/main/docs/roadmap/cosmos-hub-roadmap-2.0.md#v8-rho-upgrade-expected-q1-2023), which contains the following main new features/improvement: - -- [ibc-go](https://github.com/cosmos/ibc-go) to [v3.4.0](https://github.com/cosmos/ibc-go/blob/v3.4.0/CHANGELOG.md) to fix a vulnerability in ICA. See [v3.4.0 CHANGELOG.md](https://github.com/cosmos/ibc-go/releases/tag/v3.4.0) and [v3.2.1 Release Notes](https://github.com/cosmos/ibc-go/releases/tag/v3.2.1) for details. -- [cosmos-sdk](https://github.com/cosmos/cosmos-sdk) to [v0.45.12](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.45.12). See [CHANGELOG.md](https://github.com/cosmos/cosmos-sdk/blob/release/v0.45.x/CHANGELOG.md) for details. -- [tendermint](https://github.com/tendermint/tendermint) to [0.34.24](https://github.com/tendermint/tendermint/tree/v0.34.24). See [CHANGELOG.md](https://github.com/tendermint/tendermint/blob/v0.34.24/CHANGELOG.md) for details. -- [liquidity](https://github.com/Gravity-Devs/liquidity) to [v1.5.3](https://github.com/Gravity-Devs/liquidity/releases/tag/v1.5.3). -- [packet-forwarding-middleware](https://github.com/strangelove-ventures/packet-forward-middleware) to [v3.1.1](https://github.com/strangelove-ventures/packet-forward-middleware/releases/tag/v3.1.1). -- [globalfee](https://github.com/cosmos/gaia/tree/main/x/globalfee) module. See [globalfee docs](https://github.com/cosmos/gaia/blob/main/docs/modules/globalfee.md) for more details. -- [#1845](https://github.com/cosmos/gaia/pull/1845) Add bech32-convert command to gaiad. -- [Add new fee decorator](https://github.com/cosmos/gaia/pull/1961) to change `MaxBypassMinFeeMsgGasUsage` so importers of x/globalfee can change `MaxGas`. -- [#1870](https://github.com/cosmos/gaia/issues/1870) Fix bank denom metadata in migration. See [#1892](https://github.com/cosmos/gaia/pull/1892) for more details. -- [#1976](https://github.com/cosmos/gaia/pull/1976) Fix Quicksilver ICA exploit in migration. See [the bug fix forum post](https://forum.cosmos.network/t/upcoming-interchain-accounts-bugfix-release/8911) for more details. -- [E2E tests](https://github.com/cosmos/gaia/tree/main/tests/e2e). The tests cover transactions/queries tests of different modules, including Bank, Distribution, Encode, Evidence, FeeGrant, Global Fee, Gov, IBC, packet forwarding middleware, Slashing, Staking, and Vesting module. -- [#1941](https://github.com/cosmos/gaia/pull/1941) Fix packet forward configuration for e2e tests. -- Use gaiad to swap out [Ignite](https://github.com/ignite/cli) in [liveness tests](https://github.com/cosmos/gaia/blob/main/.github/workflows/test.yml). - -TOC: - -- [Cosmos Hub 4, v8-Rho Upgrade, Instructions](#cosmos-hub-4-v8-rho-upgrade-instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade will take place Feb 16, 203](#upgrade-will-take-place-feb-16-2023) - - [Chain-id will remain the same](#chain-id-will-remain-the-same) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime, cosmoshub-4 (pre-v8-Rho upgrade) is running Gaia v7.0.x](#current-runtime-cosmoshub-4-pre-v7-theta-upgrade-is-running-gaia-v60x) - - [Target runtime, cosmoshub-4 (post-v8-Rho upgrade) will run Gaia v8.0.0](#target-runtime-cosmoshub-4-post-v8-rho-upgrade-will-run-gaia-v800) - - [v8-Rho upgrade steps](#v8-Rho-upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-gaia-v800-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia v8.0.0 binary (not recommended!)](#auto-downloading-the-gaia-v800-binary-not-recommended) - - [Preparation](#preparation-1) - - [Expected result](#expected-result) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal #97](https://www.mintscan.io/cosmos/proposals/97) is the reference on-chain governance proposal for this upgrade, which has passed with overwhelming community support. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade will take place Feb 16, 2023 - -The upgrade will take place at a block height of `14099412`. At the time of writing, and at current block times (around 7s/block), this block height corresponds approximately to `Thursday, 16-February-23 01:00:00 CET`. This date/time is approximate as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://chain-monitor.cros-nest.com/d/Upgrades/upgrades?var-chain_id=cosmoshub-4&orgId=1&refresh=1m) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade by cosmovisor](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v700-binary) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v8-Rho local testnet](https://github.com/cosmos/testnets/tree/master/local). - -### Current runtime, cosmoshub-4 (pre-v8-Rho upgrade) is running Gaia v7.1.1 - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v7.1.1](https://github.com/cosmos/gaia/releases/v7.1.1). We anticipate that operators who are running on v7.1.1, will be able to upgrade successfully; however, this is untested and it is up to operators to ensure that their systems are capable of performing the upgrade. - -### Target runtime, cosmoshub-4 (post-v8-Rho upgrade) will run Gaia v8.0.0 - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v8.0.0](https://github.com/cosmos/gaia/releases/tag/v8.0.0). Operators _MUST_ use this version post-upgrade to remain connected to the network. - -## v8-Rho upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/master/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Run Gaia v7.1.1 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v8-Rho" NEEDED at height: 14099412: upgrade to v7-Theta and applying upgrade "v8-Rho" at height:14099412 -``` - -Stop the node, and install Gaia v8.0.0 and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their nodes upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -> **Warning** **Please Read Before Proceeding**
-> **Using Cosmovisor 1.2.0 and higher requires a lowercase naming convention for upgrade version directory. For Cosmovisor 1.1.0 and earlier, the upgrade version is not lowercased.**
-> -> **For Example:**
-> **Cosmovisor =< `1.1.0`: `/upgrades/v8-Rho/bin/gaiad`**
-> **Cosmovisor >= `1.2.0`: `/upgrades/v8-rho/bin/gaiad`**
- -| Cosmovisor Version | Binary Name in Path | -|--------------------|---------------------| -| 1.3 | v8-rho | -| 1.2 | v8-rho | -| 1.1 | v8-Rho | -| 1.0 | v8-Rho | - -### _Manually preparing the Gaia v8.0.0 binary_ - -##### Preparation - -Install the latest version of Cosmovisor (`1.3.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -**Verify Cosmovisor Version** -```shell -cosmovisor version -cosmovisor version: v1.3.0 -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v7.1.1 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v8.0.0, and move gaiad v8.0.0 to `$GAIA_HOME/cosmovisor/upgrades/v8-rho/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v8-rho/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v8-rho/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v7.1.1 -└── upgrades - └── v8-rho - └── bin - └── gaiad #v8.0.0 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME= $GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor start --x-crisis-skip-assert-invariants -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take 7 minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their nodes upgrades. - -### _Auto-Downloading the Gaia v8.0.0 binary (not recommended!)_ -#### Preparation - -Install the latest version of Cosmovisor (`1.3.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v7.1.1 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v7.1.1 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME= $GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor start --x-crisis-skip-assert-invariants -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v8-Rho" NEEDED at height: 14099412: upgrade to v7-Theta and applying upgrade "v8-Rho" at height:14099412 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v8-rho/bin` and download the Gaia v8.0.0 binary to this folder according to links in the `--info` field of the upgrade proposal 97. -This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. -- Users should use run node on v7.1.1 if they use the cosmovisor v1.1.0 with auto-download enabled for upgrade process. - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v7.1.1 binary using the following command: - -> gaiad start --unsafe-skip-upgrade 14099412 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#validators-verified` channel of the Cosmos Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v9-Lambda-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v9-Lambda-upgrade.md deleted file mode 100644 index daf81a97877..00000000000 --- a/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v9-Lambda-upgrade.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Cosmos Hub 4, v9-Lambda Upgrade Instructions -order: 5 ---- - - -This document describes the steps for validator and full node operators for the successful execution of the [v9-Lambda Upgrade](https://github.com/cosmos/gaia/blob/main/docs/roadmap/cosmos-hub-roadmap-2.0.md#v9-lambda-upgrade-expected-q1-2023), which contains the following main new features/improvement: - -- [Interchain-Security](https://github.com/cosmos/interchain-security) [v1.0.0](https://github.com/cosmos/interchain-security/releases/tag/v1.0.0) provider module. See the [ICS Spec](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/README.md) for more details. -- [cosmos-sdk](https://github.com/cosmos/cosmos-sdk) to [v0.45.13-ics](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.45.13-ics). See [CHANGELOG.md](https://github.com/cosmos/cosmos-sdk/blob/releases/tag/v0.45.13-ics) for details. -- [ibc-go](https://github.com/cosmos/ibc-go) to [v4.2.0](https://github.com/cosmos/ibc-go/blob/release/v4.2.x/CHANGELOG.md). See [v4.2 Release Notes](https://github.com/cosmos/ibc-go/releases/tag/v4.2.0) for details. -- [tendermint](https://github.com/informalsystems/tendermint) to [0.34.26](https://github.com/informalsystems/tendermint/tree/v0.34.26). See [CHANGELOG.md](https://github.com/informalsystems/tendermint/blob/v0.34.26/CHANGELOG.md#v03426) for details. -- [packet-forward-middleware](https://github.com/strangelove-ventures/packet-forward-middleware) to [v4.0.4](https://github.com/strangelove-ventures/packet-forward-middleware/releases/tag/v4.0.4). -- [E2E ccv tests](https://github.com/cosmos/gaia/blob/main/tests/e2e/e2e_gov_test.go#L138). Tests covering new functionality introduced by the provider module to add and remove a consumer chain via governance proposal. -- [integration ccv tests](https://github.com/cosmos/gaia/blob/main/tests/ics/interchain_security_test.go). Imports Interchain-Security's `TestCCVTestSuite` and implements Gaia as the provider chain. - -TOC: - -- [Cosmos Hub 4, v9-Lambda Upgrade, Instructions](#cosmos-hub-4-v9-lambda-upgrade-instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade will take place March 15, 203](#upgrade-will-take-place-march-15-2023) - - [Chain-id will remain the same](#chain-id-will-remain-the-same) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirement](#system-requirement) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime, cosmoshub-4 (pre-v9-Lambda upgrade) is running Gaia v8.0.1](#current-runtime-cosmoshub-4-pre-v9-lambda-upgrade-is-running-gaia-v801) - - [Target runtime, cosmoshub-4 (post-v9-Lambda upgrade) will run Gaia v9.0.0](#target-runtime-cosmoshub-4-post-v9-lambda-upgrade-will-run-gaia-v900) - - [v9-Lambda upgrade steps](#v9-Lambda-upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-gaia-v900-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia v9.0.0 binary (not recommended!)](#auto-downloading-the-gaia-v900-binary-not-recommended) - - [Preparation](#preparation-1) - - [Expected result](#expected-result) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -[Proposal #187](https://www.mintscan.io/cosmos/proposals/187) is the reference on-chain governance proposal for this upgrade, which is still in its voting period. Neither core developers nor core funding entities control the governance, and this governance proposal has passed in a _fully decentralized_ way. - -## Upgrade will take place March 14-16, 2023 - -The upgrade will take place at a block height of `14470501`. The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date using this [live countdown](https://www.mintscan.io/cosmos/blocks/14470501) page. - -## Chain-id will remain the same - -The chain-id of the network will remain the same, `cosmoshub-4`. This is because an in-place migration of state will take place, i.e., this upgrade does not export any state. - -## Preparing for the upgrade - -### System requirement - -32GB RAM is recommended to ensure a smooth upgrade. - -If you have less than 32GB RAM, you might try creating a swapfile to swap an idle program onto the hard disk to free up memory. This can -allow your machine to run the binary than it could run in RAM alone. - -```shell -sudo fallocate -l 16G /swapfile -sudo chmod 600 /swapfile -sudo mkswap /swapfile -sudo swapon /swapfile -``` - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade by cosmovisor](#method-ii-upgrade-using-cosmovisor-by-manually-preparing-the-gaia-v700-binary) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v8-Rho local testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [v9-Lambda public-testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime, cosmoshub-4 (pre-v9-Lambda upgrade) is running Gaia v8.0.1 - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v8.0.1](https://github.com/cosmos/gaia/releases/v8.0.1). We anticipate that operators who are running on v8.0.1, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary, or if building from source, building with go `1.18`. - -### Target runtime, cosmoshub-4 (post-v9-Lambda upgrade) will run Gaia v9.0.0 - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run [Gaia v9.0.0](https://github.com/cosmos/gaia/releases/tag/v9.0.0). Operators _MUST_ use this version post-upgrade to remain connected to the network. - -## v9-Lambda upgrade steps - -There are 2 major ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/master/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure Gaia v9.0.0 is installed by either downloading a [compatable binary](https://github.com/cosmos/gaia/releases/tag/v9.0.0), or building from source. Building from source requires go 1.18. - -Run Gaia v8.0.1 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v9-Lambda" NEEDED at height: 14470501: upgrade to v9-Lambda and applying upgrade "v9-Lambda" at height:14470501 -``` - -Stop the node, and switch the binary to Gaia v9.0.0 and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -:::warning -**Please Read Before Proceeding**
-Using Cosmovisor 1.2.0 and higher requires a lowercase naming convention for upgrade version directory. For Cosmovisor 1.1.0 and earlier, the upgrade version is not lowercased. -::: - -> **For Example:**
-> **Cosmovisor =< `1.1.0`: `/upgrades/v9-Lambda/bin/gaiad`**
-> **Cosmovisor >= `1.2.0`: `/upgrades/v9-lambda/bin/gaiad`**
- -| Cosmovisor Version | Binary Name in Path | -|--------------------|---------------------| -| 1.3 | v9-lambda | -| 1.2 | v9-lambda | -| 1.1 | v9-Lambda | -| 1.0 | v9-Lambda | - - -### _Manually preparing the Gaia v9.0.0 binary_ - -##### Preparation - -Install the latest version of Cosmovisor (`1.3.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -**Verify Cosmovisor Version** -```shell -cosmovisor version -cosmovisor version: v1.3.0 -``` - -Create a cosmovisor folder: - -create a Cosmovisor folder inside `$GAIA_HOME` and move Gaia v8.0.1 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -```` - -build Gaia v9.0.0, and move gaiad v9.0.0 to `$GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin -``` - -Then you should get the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad #v8.0.1 -└── upgrades - └── v9-lambda - └── bin - └── gaiad #v9.0.0 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -#### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take 7 minutes to a few hours. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -### _Auto-Downloading the Gaia v9.0.0 binary (not recommended!)_ -#### Preparation - -Install the latest version of Cosmovisor (`1.3.0`): - -```shell -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest -``` - -Create a cosmovisor folder: - -create a cosmovisor folder inside gaia home and move gaiad v8.0.1 into `$GAIA_HOME/cosmovisor/genesis/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -```shell -. -├── current -> genesis or upgrades/ -└── genesis - └── bin - └── gaiad #v8.0.1 -``` - -Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -export DAEMON_ALLOW_DOWNLOAD_BINARIES=true -``` - -Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks can help decrease the upgrade time significantly. - -#### Expected result - -When the upgrade block height is reached, you can find the following information in the log: - -```shell -ERR UPGRADE "v9-Lambda" NEEDED at height: 14470501: upgrade to v9-Lambda and applying upgrade "v9-Lambda" at height:14470501 -``` - -Then the Cosmovisor will create `$GAIA_HOME/cosmovisor/upgrades/v9-lambda/bin` and download the Gaia v9.0.0 binary to this folder according to links in the `--info` field of the upgrade proposal 97. -This may take 7 minutes to a few hours, afterwards, the chain will continue to produce blocks once validators with a total sum voting power > 2/3 complete their nodes upgrades. - -_Please Note:_ - -- In general, auto-download comes with the risk that the verification of correct download is done automatically. If users want to have the highest guarantee users should confirm the check-sum manually. We hope more node operators will use the auto-download for this release but please be aware this is a risk and users should take at your own discretion. -- Users should use run node on v8.0.1 if they use the cosmovisor v1.3.0 with auto-download enabled for upgrade process. - -## Upgrade duration - -The upgrade may take a few minutes to several hours to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v8.0.1 binary using the following command: - -> gaiad start --unsafe-skip-upgrade 14470501 - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) - - diff --git a/docs/docs/migration/latest.md b/docs/docs/migration/latest.md deleted file mode 100644 index 72c63a952f4..00000000000 --- a/docs/docs/migration/latest.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: v16.0.0 Upgrade ---- - -# Upgrading Gaia - -This guide provides instructions for upgrading Gaia from v15.2.x to v16.0.0. - -This document describes the steps for validators, full node operators and relayer operators, to upgrade successfully for the Gaia v16 release. - -For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v16.0.0) - -**Relayer Operators** for the Cosmos Hub and consumer chains, will also need to update to use [Hermes v1.8.0](https://github.com/informalsystems/hermes/releases/tag/v1.8.0) or higher. You may need to restart your relayer software after a major chain upgrade. - -## Release Binary - -Please use the correct release binary: `v16.0.0`. - -## Instructions - -- [Upgrading Gaia](#upgrading-gaia) - - [Release Binary](#release-binary) - - [Instructions](#instructions) - - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) - - [Upgrade date](#upgrade-date) - - [Preparing for the upgrade](#preparing-for-the-upgrade) - - [System requirements](#system-requirements) - - [An Important Note for Node Operators](#an-important-note-for-node-operators) - - [Backups](#backups) - - [Testing](#testing) - - [Current runtime](#current-runtime) - - [Target runtime](#target-runtime) - - [Upgrade steps](#upgrade-steps) - - [Method I: Manual Upgrade](#method-i-manual-upgrade) - - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) - - [Manually preparing the binary](#manually-preparing-the-binary) - - [Preparation](#preparation) - - [Expected upgrade result](#expected-upgrade-result) - - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) - - [Upgrade duration](#upgrade-duration) - - [Rollback plan](#rollback-plan) - - [Communications](#communications) - - [Risks](#risks) - - [Reference](#reference) - -## On-chain governance proposal attains consensus - -Once a software upgrade governance proposal is submitted to the Cosmos Hub, both a reference to this proposal and an `UPGRADE_HEIGHT` are added to the [release notes](https://github.com/cosmos/gaia/releases/tag/v16.0.0). -If and when this proposal reaches consensus, the upgrade height will be used to halt the "old" chain binaries. You can check the proposal on one of the block explorers or using the `gaiad` CLI tool. - -## Upgrade date - -The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date by checking the estimated estimated time until the block is produced one of the block explorers (e.g. https://www.mintscan.io/cosmos/blocks/`UPGRADE_HEIGHT`). - -## Preparing for the upgrade - -### Backups - -Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. -If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade using cosmovisor](#method-ii-upgrade-using-cosmovisor) section. - -It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -### Testing - -For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v16 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). - -### Current runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v15.2.0](https://github.com/cosmos/gaia/releases/v15.2.0). We anticipate that operators who are running on v15.2.0, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary and if building from source, building with the appropriate `go` version. - -### Target runtime - -The Cosmos Hub mainnet network, `cosmoshub-4`, will run **[Gaia v16.0.0](https://github.com/cosmos/gaia/releases/tag/v16.0.0)**. Operators _**MUST**_ use this version post-upgrade to remain connected to the network. The new version requires `go v1.21` to build successfully. - -## Upgrade steps - -There are 2 ways to upgrade a node: - -- Manual upgrade -- Upgrade using [Cosmovisor](https://pkg.go.dev/cosmossdk.io/tools/cosmovisor) - - Either by manually preparing the new binary - - Or by using the auto-download functionality (this is not yet recommended) - -If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. - -### Method I: Manual Upgrade - -Make sure **Gaia v15.2.0** is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v15.2.0), or building from source. Check the required version to build this binary in the `Makefile`. - -Run Gaia v15.2.0 till upgrade height, the node will panic: - -```shell -ERR UPGRADE "v16" NEEDED at height: : upgrade to v16 and applying upgrade "v16" at height: -``` - -Stop the node, and switch the binary to **Gaia v16.0.0** and re-start by `gaiad start`. - -It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. - -### Method II: Upgrade using Cosmovisor - -#### Manually preparing the binary - -##### Preparation - -- Install the latest version of Cosmovisor (`1.5.0`): - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -cosmovisor version -# cosmovisor version: v1.5.0 -``` - -- Create a `cosmovisor` folder inside `$GAIA_HOME` and move Gaia `v15.2.0` into `$GAIA_HOME/cosmovisor/genesis/bin`: - -```shell -mkdir -p $GAIA_HOME/cosmovisor/genesis/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin -``` - -- Build Gaia `v16.0.0`, and move gaiad `v16.0.0` to `$GAIA_HOME/cosmovisor/upgrades/v16/bin` - -```shell -mkdir -p $GAIA_HOME/cosmovisor/upgrades/v16/bin -cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v16/bin -``` - -At this moment, you should have the following structure: - -```shell -. -├── current -> genesis or upgrades/ -├── genesis -│ └── bin -│ └── gaiad # old: v15.2.0 -└── upgrades - └── v16 - └── bin - └── gaiad # new: v16.0.0 -``` - -- Export the environmental variables: - -```shell -export DAEMON_NAME=gaiad -# please change to your own gaia home dir -# please note `DAEMON_HOME` has to be absolute path -export DAEMON_HOME=$GAIA_HOME -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -- Start the node: - -```shell -cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME -``` - -Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. - -##### Expected upgrade result - -When the upgrade block height is reached, Gaia will panic and stop: - -This may take a few minutes. -After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. - -#### Auto-Downloading the Gaia binary - -## Upgrade duration - -The upgrade may take a few minutes to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. - -## Rollback plan - -During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. - -Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v15.2.0 binary using the following command: - -```shell -gaiad start --unsafe-skip-upgrade -``` - -Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. - -Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. - -## Communications - -Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. - -## Reference - -[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) diff --git a/docs/docs/validators/README.md b/docs/docs/validators/README.md index 12825f1206f..578b9bf7a1d 100644 --- a/docs/docs/validators/README.md +++ b/docs/docs/validators/README.md @@ -5,10 +5,10 @@ order: 1 This folder contains documentation relevant to validators of the Cosmos Hub and other `gaia` blockchains. -- [Validator Overview](/validators/overview) -- [Setting Up a Validator for Cosmos Hub Mainnet](/validators/validator-setup) -- [Validator FAQ](/validators/validator-faq) -- [Validator Security Notice](/validators/security) +- [Validator Overview](./overview.mdx) +- [Setting Up a Validator for Cosmos Hub Mainnet](./validator-setup.md) +- [Validator FAQ](./validator-faq.md) +- [Validator Security Notice](./security.md) - Key Management Systems - - [Intro to KMS](/validators/kms) - - [KMS + Ledger](/validators/kms/kms_ledger) + - [Intro to KMS](./kms/kms.md) + - [KMS + Ledger](./kms/kms_ledger.md) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 6d1c252c1ae..87152e2daca 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -13,7 +13,7 @@ const algoliaIndexName = "cosmos_network"; const config = { title: "Cosmos Hub", tagline: "", - favicon: "/gaia/img/hub.svg", + favicon: "/img/hub.svg", // Set the production url of your site here url: "https://hub.cosmos.network", @@ -26,8 +26,8 @@ const config = { organizationName: "Cosmos", // Usually your GitHub org/user name. projectName: "Gaia", // Usually your repo name. - onBrokenLinks: "throw", - onBrokenMarkdownLinks: "throw", + onBrokenLinks: "warn", + onBrokenMarkdownLinks: "warn", trailingSlash: false, // Even if you don't use internalization, you can use this field to set useful @@ -53,13 +53,18 @@ const config = { docs: { routeBasePath: "/", sidebarPath: require.resolve("./sidebars.js"), - // lastVersion: "v15.2.0", + lastVersion: "v17.1.0", versions: { current: { - path: "/", - label: "main", + path: "main", + label: "Unreleased (main)", banner: "unreleased", }, + "v17.1.0": { + path: "v17.1.0", + label: "On chain (v17.1.0)", + banner: "none", + }, }, }, sitemap: { @@ -97,7 +102,7 @@ const config = { logo: { alt: "Cosmos Hub Logo", src: "img/hub.svg", - href: "https://hub.cosmos.network", + href: "/", target: "_self", }, items: [ @@ -131,19 +136,8 @@ const config = { { type: "docsVersionDropdown", position: "left", - dropdownActiveClassDisabled: true, // versions not yet migrated to docusaurus dropdownItemsAfter: [ - // { - // href: 'https://hub.cosmos.network/v11/', - // label: 'v11', - // target: '_self', - // }, - // { - // href: 'https://hub.cosmos.network/v10/', - // label: 'v10', - // target: '_self', - // }, { href: "https://github.com/cosmos/gaia/tree/legacy-docs", label: "Archive", @@ -159,7 +153,7 @@ const config = { { items: [ { - html: `Cosmos Logo`, + html: `Cosmos Logo`, }, ], }, @@ -260,7 +254,12 @@ const config = { { fromExtensions: ["html"], toExtensions: ["html"], - redirects: [], + redirects: [ + { + from: ["/"], + to: "/main", + }, + ], }, ], ], diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js new file mode 100644 index 00000000000..c3380f303a6 --- /dev/null +++ b/docs/src/pages/index.js @@ -0,0 +1,6 @@ +import React from "react"; +import { Redirect } from "react-router-dom"; + +export default function Home() { + return ; +} diff --git a/docs/versions.json b/docs/versions.json index cd3c389fb81..46964c5bda3 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,5 +1,3 @@ [ - "v15.2.0", - "v16.0.0", - "v17.0.0-rc0" + "v17.1.0" ] \ No newline at end of file