From 2a784ce5ffdf8a7a75d3a98b95dcf4d0f36ce1a0 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Thu, 3 Oct 2024 07:05:39 +0200 Subject: [PATCH 1/3] docs: tooling (#22049) (cherry picked from commit 3a5a619e9d2e6e5fdfc5efaa57d42a346c0793fa) # Conflicts: # tools/cosmovisor/README.md --- client/v2/README.md | 82 +++--- docs/build/tooling/00-protobuf.md | 37 +-- simapp/upgrades.go | 6 +- simapp/v2/upgrades.go | 6 +- tools/confix/README.md | 11 +- tools/cosmovisor/README.md | 411 ++++++++++++++++++++++++++++++ 6 files changed, 475 insertions(+), 78 deletions(-) create mode 100644 tools/cosmovisor/README.md diff --git a/client/v2/README.md b/client/v2/README.md index 268798233fcd..b4c2666850ee 100644 --- a/client/v2/README.md +++ b/client/v2/README.md @@ -2,7 +2,9 @@ sidebar_position: 1 --- -# AutoCLI +# Client/v2 + +## AutoCLI :::note Synopsis This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included. @@ -14,9 +16,9 @@ This document details how to build CLI and REST interfaces for a module. Example ::: -The `autocli` (also known as `client/v2`) package is a [Go library](https://pkg.go.dev/cosmossdk.io/client/v2/autocli) for generating CLI (command line interface) interfaces for Cosmos SDK-based applications. It provides a simple way to add CLI commands to your application by generating them automatically based on your gRPC service definitions. Autocli generates CLI commands and flags directly from your protobuf messages, including options, input parameters, and output parameters. This means that you can easily add a CLI interface to your application without having to manually create and manage commands. +The `autocli` (also known as `client/v2/autocli`) package is a [Go library](https://pkg.go.dev/cosmossdk.io/client/v2/autocli) for generating CLI (command line interface) interfaces for Cosmos SDK-based applications. It provides a simple way to add CLI commands to your application by generating them automatically based on your gRPC service definitions. Autocli generates CLI commands and flags directly from your protobuf messages, including options, input parameters, and output parameters. This means that you can easily add a CLI interface to your application without having to manually create and manage commands. -## Overview +### Overview `autocli` generates CLI commands and flags for each method defined in your gRPC service. By default, it generates commands for each gRPC services. The commands are named based on the name of the service method. @@ -32,7 +34,7 @@ For instance, `autocli` would generate a command named `my-method` for the `MyMe It is possible to customize the generation of transactions and queries by defining options for each service. -## Application Wiring +### Application Wiring Here are the steps to use AutoCLI: @@ -73,7 +75,7 @@ if err := rootCmd.Execute(); err != nil { } ``` -### Keyring +#### Keyring `autocli` uses a keyring for key name resolving names and signing transactions. @@ -100,7 +102,7 @@ keyring.NewAutoCLIKeyring(kb) ::: -## Signing +### Signing `autocli` supports signing transactions with the keyring. The [`cosmos.msg.v1.signer` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) defines the signer field of the message. @@ -110,7 +112,7 @@ This field is automatically filled when using the `--from` flag or defining the AutoCLI currently supports only one signer per transaction. ::: -## Module wiring & Customization +### Module wiring & Customization The `AutoCLIOptions()` method on your module allows to specify custom commands, sub-commands or flags for each service, as it was a `cobra.Command` instance, within the `RpcCommandOptions` struct. Defining such options will customize the behavior of the `autocli` command generation, which by default generates a command for each method in your gRPC service. @@ -131,31 +133,7 @@ AutoCLI can create a gov proposal of any tx by simply setting the `GovProposal` Users can however use the `--no-proposal` flag to disable the proposal creation (which is useful if the authority isn't the gov module on a chain). ::: -### Conventions for the `Use` field in Cobra - -According to the [Cobra documentation](https://pkg.go.dev/github.com/spf13/cobra#Command) the following conventions should be followed for the `Use` field in Cobra commands: - -1. **Required arguments**: - * Should not be enclosed in brackets. They can be enclosed in angle brackets `< >` for clarity. - * Example: `command ` - -2. **Optional arguments**: - * Should be enclosed in square brackets `[ ]`. - * Example: `command [optional_argument]` - -3. **Alternative (mutually exclusive) arguments**: - * Should be enclosed in curly braces `{ }`. - * Example: `command {-a | -b}` for required alternatives. - * Example: `command [-a | -b]` for optional alternatives. - -4. **Multiple arguments**: - * Indicated with `...` after the argument. - * Example: `command argument...` - -5. **Combination of options**: - * Example: `command [-F file | -D dir]... [-f format] profile` - -### Specifying Subcommands +#### Specifying Subcommands By default, `autocli` generates a command for each method in your gRPC service. However, you can specify subcommands to group related commands together. To specify subcommands, use the `autocliv1.ServiceCommandDescriptor` struct. @@ -165,7 +143,7 @@ This example shows how to use the `autocliv1.ServiceCommandDescriptor` struct to https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-beta.0/x/gov/autocli.go#L94-L97 ``` -### Positional Arguments +#### Positional Arguments By default `autocli` generates a flag for each field in your protobuf message. However, you can choose to use positional arguments instead of flags for certain fields. @@ -183,7 +161,7 @@ Then the command can be used as follows, instead of having to specify the `--add query auth account cosmos1abcd...xyz ``` -### Customising Flag Names +#### Customising Flag Names By default, `autocli` generates flag names based on the names of the fields in your protobuf message. However, you can customise the flag names by providing a `FlagOptions`. This parameter allows you to specify custom names for flags based on the names of the message fields. @@ -200,7 +178,7 @@ autocliv1.RpcCommandOptions{ `FlagsOptions` is defined like sub commands in the `AutoCLIOptions()` method on your module. -### Combining AutoCLI with Other Commands Within A Module +#### Combining AutoCLI with Other Commands Within A Module AutoCLI can be used alongside other commands within a module. For example, the `gov` module uses AutoCLI to generate commands for the `query` subcommand, but also defines custom commands for the `proposer` subcommands. @@ -212,7 +190,7 @@ https://github.com/cosmos/cosmos-sdk/blob/fa4d87ef7e6d87aaccc94c337ffd2fe90fcb7a If not set to true, `AutoCLI` will not generate commands for the module if there are already commands registered for the module (when `GetTxCmd()` or `GetQueryCmd()` are defined). -### Skip a command +#### Skip a command AutoCLI automatically skips unsupported commands when [`cosmos_proto.method_added_in` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) is present. @@ -225,7 +203,7 @@ Additionally, a command can be manually skipped using the `autocliv1.RpcCommandO } ``` -### Use AutoCLI for non module commands +#### Use AutoCLI for non module commands It is possible to use `AutoCLI` for non module commands. The trick is still to implement the `appmodule.Module` interface and append it to the `appOptions.ModuleOptions` map. @@ -235,7 +213,31 @@ For example, here is how the SDK does it for `cometbft` gRPC commands: https://github.com/cosmos/cosmos-sdk/blob/main/client/grpc/cmtservice/autocli.go#L52-L71 ``` -## Summary +#### Conventions for the `Use` field in Cobra + +According to the [Cobra documentation](https://pkg.go.dev/github.com/spf13/cobra#Command) the following conventions should be followed for the `Use` field in Cobra commands: + +1. **Required arguments**: + * Should not be enclosed in brackets. They can be enclosed in angle brackets `< >` for clarity. + * Example: `command ` + +2. **Optional arguments**: + * Should be enclosed in square brackets `[ ]`. + * Example: `command [optional_argument]` + +3. **Alternative (mutually exclusive) arguments**: + * Should be enclosed in curly braces `{ }`. + * Example: `command {-a | -b}` for required alternatives. + * Example: `command [-a | -b]` for optional alternatives. + +4. **Multiple arguments**: + * Indicated with `...` after the argument. + * Example: `command argument...` + +5. **Combination of options**: + * Example: `command [-F file | -D dir]... [-f format] profile` + +### Summary `autocli` lets you generate CLI to your Cosmos SDK-based applications without any cobra boilerplate. It allows you to easily generate CLI commands and flags from your protobuf messages, and provides many options for customising the behavior of your CLI application. @@ -245,7 +247,7 @@ For more information on `hubl`, including how to configure a new chain and query # Off-Chain -Off-chain functionalities allow you to sign and verify files with two commands: +Off-chain is a `client/v2` package providing functionalities for allowing to sign and verify files with two commands: * `sign-file` for signing a file. * `verify-file` for verifying a previously signed file. @@ -275,6 +277,7 @@ The `encoding` flag lets you choose how the contents of the file should be encod "signer": "cosmos1x33fy6rusfprkntvjsfregss7rvsvyy4lkwrqu", "data": "Hello World!\n" } + ``` * `simd off-chain sign-file alice myFile.json --encoding base64` @@ -286,6 +289,7 @@ The `encoding` flag lets you choose how the contents of the file should be encod "signer": "cosmos1x33fy6rusfprkntvjsfregss7rvsvyy4lkwrqu", "data": "SGVsbG8gV29ybGQhCg==" } + ``` * `simd off-chain sign-file alice myFile.json --encoding hex` diff --git a/docs/build/tooling/00-protobuf.md b/docs/build/tooling/00-protobuf.md index d9a210a78577..849a7974eab7 100644 --- a/docs/build/tooling/00-protobuf.md +++ b/docs/build/tooling/00-protobuf.md @@ -4,21 +4,17 @@ sidebar_position: 1 # Protocol Buffers -It is known that Cosmos SDK uses protocol buffers extensively, this document is meant to provide a guide on how it is used in the cosmos-sdk. +Cosmos SDK uses protocol buffers extensively, this document is meant to provide a guide on how it is used in the cosmos-sdk. -To generate the proto file, the Cosmos SDK uses a docker image, this image is provided to all to use as well. The latest version is `ghcr.io/cosmos/proto-builder:0.12.x` +To generate the proto file, the Cosmos SDK uses a docker image, this image is provided to all to use as well. The latest version is `ghcr.io/cosmos/proto-builder:0.15.x` Below is the example of the Cosmos SDK's commands for generating, linting, and formatting protobuf files that can be reused in any applications makefile. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/Makefile#L411-L432 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/scripts/build/protobuf.mk#L1-L10 ``` -The script used to generate the protobuf files can be found in the `scripts/` directory. - -```shell reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/scripts/protocgen.sh -``` +The [`protocgen.sh`](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/scripts/protocgen.sh) script used to generate the protobuf files via buf can be found in the `scripts/` directory. ## Buf @@ -36,7 +32,9 @@ https://github.com/cosmos/cosmos-sdk/blob/main/buf.work.yaml#L6-L9 ### Proto Directory -Next is the `proto/` directory where all of our protobuf files live. In here there are many different buf files defined each serving a different purpose. +The `proto/` directory where all of global protobuf files live. +In here there are many different buf files defined each serving a different purpose. +Modules proto files are defined in their respective module directories (in the SDK `x/{moduleName}/proto`). ```bash ├── README.md @@ -50,8 +48,6 @@ Next is the `proto/` directory where all of our protobuf files live. In here the └── tendermint ``` -The above diagram all the files and directories within the Cosmos SDK `proto/` directory. - #### `buf.gen.gogo.yaml` `buf.gen.gogo.yaml` defines how the protobuf files should be generated for use with in the module. This file uses [gogoproto](https://github.com/gogo/protobuf), a separate generator from the google go-proto generator that makes working with various objects more ergonomic, and it has more performant encode and decode steps @@ -60,10 +56,6 @@ The above diagram all the files and directories within the Cosmos SDK `proto/` d https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.gogo.yaml#L1-L9 ``` -:::tip -Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code) -::: - #### `buf.gen.pulsar.yaml` `buf.gen.pulsar.yaml` defines how protobuf files should be generated using the [new golang apiv2 of protobuf](https://go.dev/blog/protobuf-apiv2). This generator is used instead of the google go-proto generator because it has some extra helpers for Cosmos SDK applications and will have more performant encode and decode than the google go-proto generator. You can follow the development of this generator [here](https://github.com/cosmos/cosmos-proto). @@ -72,10 +64,6 @@ Example of how to define `gen` files can be found [here](https://docs.buf.build/ https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.pulsar.yaml#L1-L18 ``` -:::tip -Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code) -::: - #### `buf.gen.swagger.yaml` `buf.gen.swagger.yaml` generates the swagger documentation for the query and messages of the chain. This will only define the REST API end points that were defined in the query and msg servers. You can find examples of this [here](https://github.com/cosmos/cosmos-sdk/blob/main/x/bank/proto/cosmos/bank/v1beta1/query.proto) @@ -84,10 +72,6 @@ Example of how to define `gen` files can be found [here](https://docs.buf.build/ https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.swagger.yaml#L1-L6 ``` -:::tip -Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code) -::: - #### `buf.lock` This is an autogenerated file based off the dependencies required by the `.gen` files. There is no need to copy the current one. If you depend on cosmos-sdk proto definitions a new entry for the Cosmos SDK will need to be provided. The dependency you will need to use is `buf.build/cosmos/cosmos-sdk`. @@ -100,14 +84,11 @@ https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.lock#L1-L16 `buf.yaml` defines the [name of your package](https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.yaml#L3), which [breakage checker](https://buf.build/docs/tutorials/getting-started-with-buf-cli#detect-breaking-changes) to use and how to [lint your protobuf files](https://buf.build/docs/tutorials/getting-started-with-buf-cli#lint-your-api). +It is advised to use a tagged version of the buf modules corresponding to the version of the Cosmos SDK being are used. + ```go reference https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.yaml#L1-L24 ``` We use a variety of linters for the Cosmos SDK protobuf files. The repo also checks this in ci. - A reference to the github actions can be found [here](https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/proto.yml#L1-L32) - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/proto.yml#L1-L32 -``` diff --git a/simapp/upgrades.go b/simapp/upgrades.go index 36079956cc64..151517ccdd9f 100644 --- a/simapp/upgrades.go +++ b/simapp/upgrades.go @@ -15,12 +15,12 @@ import ( ) // UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade -// from v0.50.x to v0.51.x +// from v0.52.x to v0.54.x // // NOTE: This upgrade defines a reference implementation of what an upgrade // could look like when an application is migrating from Cosmos SDK version -// v0.50.x to v0.51.x. -const UpgradeName = "v050-to-v051" +// v0.52.x to v0.54.x. +const UpgradeName = "v052-to-v054" func (app SimApp) RegisterUpgradeHandlers() { app.UpgradeKeeper.SetUpgradeHandler( diff --git a/simapp/v2/upgrades.go b/simapp/v2/upgrades.go index 35355b28c367..0c0adc2bed8a 100644 --- a/simapp/v2/upgrades.go +++ b/simapp/v2/upgrades.go @@ -12,12 +12,12 @@ import ( ) // UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade -// from v0.50.x to v0.51.x +// from v0.52.x to v2 // // NOTE: This upgrade defines a reference implementation of what an upgrade // could look like when an application is migrating from Cosmos SDK version -// v0.50.x to v0.51.x. -const UpgradeName = "v050-to-v051" +// v0.52.x to v2. +const UpgradeName = "v052-to-v2" func (app *SimApp[T]) RegisterUpgradeHandlers() { app.UpgradeKeeper.SetUpgradeHandler( diff --git a/tools/confix/README.md b/tools/confix/README.md index 64b2f49b3dc7..00851ede1923 100644 --- a/tools/confix/README.md +++ b/tools/confix/README.md @@ -23,7 +23,7 @@ import "cosmossdk.io/tools/confix/cmd" Find the following line: ```go -initRootCmd(rootCmd, encodingConfig) +initRootCmd(rootCmd, moduleManager) ``` After that line, add the following: @@ -39,10 +39,10 @@ An implementation example can be found in `simapp`. The command will be available as `simd config`. -```tip +:::tip Using confix directly in the application can have less features than using it standalone. This is because confix is versioned with the SDK, while `latest` is the standalone version. -``` +::: ### Using Confix Standalone @@ -138,7 +138,7 @@ confix view ~/.simapp/config/client.toml # views the current app client conf ### Maintainer -At each SDK modification of the default configuration, add the default SDK config under `data/v0.XX-app.toml`. +At each SDK modification of the default configuration, add the default SDK config under `data/vXX-app.toml`. This allows users to use the tool standalone. ### Compatibility @@ -149,7 +149,8 @@ The recommended standalone version is `latest`, which is using the latest develo | ----------- | -------------- | | v0.50 | v0.1.x | | v0.52 | v0.2.x | +| v2 | v0.2.x | ## Credits -This project is based on the [CometBFT RFC 019](https://github.com/cometbft/cometbft/blob/5013bc3f4a6d64dcc2bf02ccc002ebc9881c62e4/docs/rfc/rfc-019-config-version.md) and their own implementation of [confix](https://github.com/cometbft/cometbft/blob/v0.36.x/scripts/confix/confix.go). +This project is based on the [CometBFT RFC 019](https://github.com/cometbft/cometbft/blob/5013bc3f4a6d64dcc2bf02ccc002ebc9881c62e4/docs/rfc/rfc-019-config-version.md) and their never released own implementation of [confix](https://github.com/cometbft/cometbft/blob/v0.36.x/scripts/confix/confix.go). diff --git a/tools/cosmovisor/README.md b/tools/cosmovisor/README.md new file mode 100644 index 000000000000..3b5f722c5d1b --- /dev/null +++ b/tools/cosmovisor/README.md @@ -0,0 +1,411 @@ +--- +sidebar_position: 1 +--- + +# Cosmovisor + +`cosmovisor` is a process manager for Cosmos SDK application binaries that automates application binary switch at chain upgrades. +It polls the `upgrade-info.json` file that is created by the x/upgrade module at upgrade height, and then can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary. + +* [Design](#design) +* [Contributing](#contributing) +* [Setup](#setup) + * [Installation](#installation) + * [Command Line Arguments And Environment Variables](#command-line-arguments-and-environment-variables) + * [Folder Layout](#folder-layout) +* [Usage](#usage) + * [Initialization](#initialization) + * [Detecting Upgrades](#detecting-upgrades) + * [Adding Upgrade Binary](#adding-upgrade-binary) + * [Auto-Download](#auto-download) + * [Preparing for an Upgrade](#preparing-for-an-upgrade) +* [Example: SimApp Upgrade](#example-simapp-upgrade) + * [Chain Setup](#chain-setup) + * [Prepare Cosmovisor and Start the Chain](#prepare-cosmovisor-and-start-the-chain) + * [Update App](#update-app) + +## Design + +Cosmovisor is designed to be used as a wrapper for a `Cosmos SDK` app: + +* it will pass arguments to the associated app (configured by `DAEMON_NAME` env variable). + Running `cosmovisor run arg1 arg2 ....` will run `app arg1 arg2 ...`; +* it will manage an app by restarting and upgrading if needed; +* it is configured using environment variables, not positional arguments. + +*Note: If new versions of the application are not set up to run in-place store migrations, migrations will need to be run manually before restarting `cosmovisor` with the new binary. For this reason, we recommend applications adopt in-place store migrations.* + +:::tip +Only the latest version of cosmovisor is actively developed/maintained. +::: + +:::warning +Versions prior to v1.0.0 have a vulnerability that could lead to a DOS. Please upgrade to the latest version. +::: + +## Contributing + +Cosmovisor is part of the Cosmos SDK monorepo, but it's a separate module with it's own release schedule. + +Release branches have the following format `release/cosmovisor/vA.B.x`, where A and B are a number (e.g. `release/cosmovisor/v1.3.x`). Releases are tagged using the following format: `cosmovisor/vA.B.C`. + +## Setup + +### Installation + +You can download Cosmovisor from the [GitHub releases](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv1.5.0). + +To install the latest version of `cosmovisor`, run the following command: + +```shell +go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +``` + +To install a specific version, you can specify the version: + +```shell +go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.5.0 +``` + +Run `cosmovisor version` to check the cosmovisor version. + +Alternatively, for building from source, simply run `make cosmovisor`. The binary will be located in `tools/cosmovisor`. + +:::warning +Installing cosmovisor using `go install` will display the correct `cosmovisor` version. +Building from source (`make cosmovisor`) or installing `cosmovisor` by other means won't display the correct version. +::: + +### Command Line Arguments And Environment Variables + +The first argument passed to `cosmovisor` is the action for `cosmovisor` to take. Options are: + +* `help`, `--help`, or `-h` - Output `cosmovisor` help information and check your `cosmovisor` configuration. +* `run` - Run the configured binary using the rest of the provided arguments. +* `version` - Output the `cosmovisor` version and also run the binary with the `version` argument. +* `config` - Display the current `cosmovisor` configuration, that means displaying the environment variables value that `cosmovisor` is using. +* `add-upgrade` - Add an upgrade manually to `cosmovisor`. This command allow you to easily add the binary corresponding to an upgrade in cosmovisor. + +All arguments passed to `cosmovisor run` will be passed to the application binary (as a subprocess). `cosmovisor` will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. For this reason, `cosmovisor run` cannot accept any command-line arguments other than those available to the application binary. + +`cosmovisor` reads its configuration from environment variables, or its configuration file (use `--cosmovisor-config `): + +* `DAEMON_HOME` is the location where the `cosmovisor/` directory is kept that contains the genesis binary, the upgrade binaries, and any additional auxiliary files associated with each binary (e.g. `$HOME/.gaiad`, `$HOME/.regend`, `$HOME/.simd`, etc.). +* `DAEMON_NAME` is the name of the binary itself (e.g. `gaiad`, `regend`, `simd`, etc.). +* `DAEMON_ALLOW_DOWNLOAD_BINARIES` (*optional*), if set to `true`, will enable auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators). By default, `cosmovisor` will not auto-download new binaries. +* `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` (*optional*, default = `false`), if `true` cosmovisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If `false`, cosmovisor will not require a checksum to be provided, but still check the checksum if one is provided. +* `DAEMON_RESTART_AFTER_UPGRADE` (*optional*, default = `true`), if `true`, restarts the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (`false`), `cosmovisor` stops running after an upgrade and requires the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs. +* `DAEMON_RESTART_DELAY` (*optional*, default none), allow a node operator to define a delay between the node halt (for upgrade) and backup by the specified time. The value must be a duration (e.g. `1s`). +* `DAEMON_SHUTDOWN_GRACE` (*optional*, default none), if set, send interrupt to binary and wait the specified time to allow for cleanup/cache flush to disk before sending the kill signal. The value must be a duration (e.g. `1s`). +* `DAEMON_POLL_INTERVAL` (*optional*, default 300 milliseconds), is the interval length for polling the upgrade plan file. The value must be a duration (e.g. `1s`). +* `DAEMON_DATA_BACKUP_DIR` option to set a custom backup directory. If not set, `DAEMON_HOME` is used. +* `UNSAFE_SKIP_BACKUP` (defaults to `false`), if set to `true`, upgrades directly without performing a backup. Otherwise (`false`, default) backs up the data before trying the upgrade. The default value of false is useful and recommended in case of failures and when a backup needed to rollback. We recommend using the default backup option `UNSAFE_SKIP_BACKUP=false`. +* `DAEMON_PREUPGRADE_MAX_RETRIES` (defaults to `0`). The maximum number of times to call [`pre-upgrade`](https://docs.cosmos.network/main/build/building-apps/app-upgrade#pre-upgrade-handling) in the application after exit status of `31`. After the maximum number of retries, Cosmovisor fails the upgrade. +* `COSMOVISOR_DISABLE_LOGS` (defaults to `false`). If set to true, this will disable Cosmovisor logs (but not the underlying process) completely. This may be useful, for example, when a Cosmovisor subcommand you are executing returns a valid JSON you are then parsing, as logs added by Cosmovisor make this output not a valid JSON. +* `COSMOVISOR_COLOR_LOGS` (defaults to `true`). If set to true, this will colorise Cosmovisor logs (but not the underlying process). +* `COSMOVISOR_TIMEFORMAT_LOGS` (defaults to `kitchen`). If set to a value (`layout|ansic|unixdate|rubydate|rfc822|rfc822z|rfc850|rfc1123|rfc1123z|rfc3339|rfc3339nano|kitchen`), this will add timestamp prefix to Cosmovisor logs (but not the underlying process). +* `COSMOVISOR_CUSTOM_PREUPGRADE` (defaults to ``). If set, this will run $DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE prior to upgrade with the arguments [ upgrade.Name, upgrade.Height ]. Executes a custom script (separate and prior to the chain daemon pre-upgrade command) +* `COSMOVISOR_DISABLE_RECASE` (defaults to `false`). If set to true, the upgrade directory will expected to match the upgrade plan name without any case changes + +### Folder Layout + +`$DAEMON_HOME/cosmovisor` is expected to belong completely to `cosmovisor` and the subprocesses that are controlled by it. The folder content is organized as follows: + +```text +. +├── current -> genesis or upgrades/ +├── genesis +│   └── bin +│   └── $DAEMON_NAME +└── upgrades +│ └── +│ ├── bin +│ │   └── $DAEMON_NAME +│ └── upgrade-info.json +└── preupgrade.sh (optional) +``` + +The `cosmovisor/` directory includes a subdirectory for each version of the application (i.e. `genesis` or `upgrades/`). Within each subdirectory is the application binary (i.e. `bin/$DAEMON_NAME`) and any additional auxiliary files associated with each binary. `current` is a symbolic link to the currently active directory (i.e. `genesis` or `upgrades/`). The `name` variable in `upgrades/` is the lowercased URI-encoded name of the upgrade as specified in the upgrade module plan. Note that the upgrade name path are normalized to be lowercased: for instance, `MyUpgrade` is normalized to `myupgrade`, and its path is `upgrades/myupgrade`. + +Please note that `$DAEMON_HOME/cosmovisor` only stores the *application binaries*. The `cosmovisor` binary itself can be stored in any typical location (e.g. `/usr/local/bin`). The application will continue to store its data in the default data directory (e.g. `$HOME/.simapp`) or the data directory specified with the `--home` flag. `$DAEMON_HOME` is dependent of the data directory and must be set to the same directory as the data directory, you will end up with a configuration like the following: + +```text +.simapp +├── config +├── data +└── cosmovisor +``` + +## Usage + +The system administrator is responsible for: + +* installing the `cosmovisor` binary +* configuring the host's init system (e.g. `systemd`, `launchd`, etc.) +* appropriately setting the environmental variables +* creating the `/cosmovisor` directory +* creating the `/cosmovisor/genesis/bin` folder +* creating the `/cosmovisor/upgrades//bin` folders +* placing the different versions of the `` executable in the appropriate `bin` folders. + +`cosmovisor` will set the `current` link to point to `genesis` at first start (i.e. when no `current` link exists) and then handle switching binaries at the correct points in time so that the system administrator can prepare days in advance and relax at upgrade time. + +In order to support downloadable binaries, a tarball for each upgrade binary will need to be packaged up and made available through a canonical URL. Additionally, a tarball that includes the genesis binary and all available upgrade binaries can be packaged up and made available so that all the necessary binaries required to sync a fullnode from start can be easily downloaded. + +The `DAEMON` specific code and operations (e.g. cometBFT config, the application db, syncing blocks, etc.) all work as expected. The application binaries' directives such as command-line flags and environment variables also work as expected. + +### Initialization + +The `cosmovisor init ` command creates the folder structure required for using cosmovisor. + +It does the following: + +* creates the `/cosmovisor` folder if it doesn't yet exist +* creates the `/cosmovisor/genesis/bin` folder if it doesn't yet exist +* copies the provided executable file to `/cosmovisor/genesis/bin/` +* creates the `current` link, pointing to the `genesis` folder + +It uses the `DAEMON_HOME` and `DAEMON_NAME` environment variables for folder location and executable name. + +The `cosmovisor init` command is specifically for initializing cosmovisor, and should not be confused with a chain's `init` command (e.g. `cosmovisor run init`). + +### Detecting Upgrades + +`cosmovisor` is polling the `$DAEMON_HOME/data/upgrade-info.json` file for new upgrade instructions. The file is created by the x/upgrade module in `BeginBlocker` when an upgrade is detected and the blockchain reaches the upgrade height. +The following heuristic is applied to detect the upgrade: + +* When starting, `cosmovisor` doesn't know much about currently running upgrade, except the binary which is `current/bin/`. It tries to read the `current/update-info.json` file to get information about the current upgrade name. +* If neither `cosmovisor/current/upgrade-info.json` nor `data/upgrade-info.json` exist, then `cosmovisor` will wait for `data/upgrade-info.json` file to trigger an upgrade. +* If `cosmovisor/current/upgrade-info.json` doesn't exist but `data/upgrade-info.json` exists, then `cosmovisor` assumes that whatever is in `data/upgrade-info.json` is a valid upgrade request. In this case `cosmovisor` tries immediately to make an upgrade according to the `name` attribute in `data/upgrade-info.json`. +* Otherwise, `cosmovisor` waits for changes in `upgrade-info.json`. As soon as a new upgrade name is recorded in the file, `cosmovisor` will trigger an upgrade mechanism. + +When the upgrade mechanism is triggered, `cosmovisor` will: + +1. if `DAEMON_ALLOW_DOWNLOAD_BINARIES` is enabled, start by auto-downloading a new binary into `cosmovisor//bin` (where `` is the `upgrade-info.json:name` attribute); +2. update the `current` symbolic link to point to the new directory and save `data/upgrade-info.json` to `cosmovisor/current/upgrade-info.json`. + +### Adding Upgrade Binary + +`cosmovisor` has an `add-upgrade` command that allows to easily link a binary to an upgrade. It creates a new folder in `cosmovisor/upgrades/` and copies the provided executable file to `cosmovisor/upgrades//bin/`. + +Using the `--upgrade-height` flag allows to specify at which height the binary should be switched, without going via a gorvernance proposal. +This enables support for an emergency coordinated upgrades where the binary must be switched at a specific height, but there is no time to go through a governance proposal. + +:::warning +`--upgrade-height` creates an `upgrade-info.json` file. This means if a chain upgrade via governance proposal is executed before the specified height with `--upgrade-height`, the governance proposal will overwrite the `upgrade-info.json` plan created by `add-upgrade --upgrade-height `. +Take this into consideration when using `--upgrade-height`. +::: + +### Auto-Download + +Generally, `cosmovisor` requires that the system administrator place all relevant binaries on disk before the upgrade happens. However, for people who don't need such control and want an automated setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option. + +**NOTE: we don't recommend using auto-download** because it doesn't verify in advance if a binary is available. If there will be any issue with downloading a binary, the cosmovisor will stop and won't restart an App (which could lead to a chain halt). + +If `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `true`, and no local binary can be found when an upgrade is triggered, `cosmovisor` will attempt to download and install the binary itself based on the instructions in the `info` attribute in the `data/upgrade-info.json` file. The files is constructed by the x/upgrade module and contains data from the upgrade `Plan` object. The `Plan` has an info field that is expected to have one of the following two valid formats to specify a download: + +1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the `"binaries"` key. For example: + + ```json + { + "binaries": { + "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" + } + } + ``` + + You can include multiple binaries at once to ensure more than one environment will receive the correct binaries: + + ```json + { + "binaries": { + "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f", + "linux/arm64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f", + "darwin/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" + } + } + ``` + + When submitting this as a proposal ensure there are no spaces. An example command using `gaiad` could look like: + + ```shell + > gaiad tx upgrade software-upgrade Vega \ + --title Vega \ + --deposit 100uatom \ + --upgrade-height 7368420 \ + --upgrade-info '{"binaries":{"linux/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-amd64","linux/arm64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-arm64","darwin/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-darwin-amd64"}}' \ + --summary "upgrade to Vega" \ + --gas 400000 \ + --from user \ + --chain-id test \ + --home test/val2 \ + --node tcp://localhost:36657 \ + --yes + ``` + +2. Store a link to a file that contains all information in the above format (e.g. if you want to specify lots of binaries, changelog info, etc. without filling up the blockchain). For example: + + ```text + https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e + ``` + +When `cosmovisor` is triggered to download the new binary, `cosmovisor` will parse the `"binaries"` field, download the new binary with [go-getter](https://github.com/hashicorp/go-getter), and unpack the new binary in the `upgrades/` folder so that it can be run as if it was installed manually. + +Note that for this mechanism to provide strong security guarantees, all URLs should include a SHA 256/512 checksum. This ensures that no false binary is run, even if someone hacks the server or hijacks the DNS. `go-getter` will always ensure the downloaded file matches the checksum if it is provided. `go-getter` will also handle unpacking archives into directories (in this case the download link should point to a `zip` file of all data in the `bin` directory). + +To properly create a sha256 checksum on linux, you can use the `sha256sum` utility. For example: + +```shell +sha256sum ./testdata/repo/zip_directory/autod.zip +``` + +The result will look something like the following: `29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7`. + +You can also use `sha512sum` if you would prefer to use longer hashes, or `md5sum` if you would prefer to use broken hashes. Whichever you choose, make sure to set the hash algorithm properly in the checksum argument to the URL. + +### Preparing for an Upgrade + +To prepare for an upgrade, use the `prepare-upgrade` command: + +```shell +cosmovisor prepare-upgrade +``` + +This command performs the following actions: + +1. Retrieves upgrade information directly from the blockchain about the next scheduled upgrade. +2. Downloads the new binary specified in the upgrade plan. +3. Verifies the binary's checksum (if required by configuration). +4. Places the new binary in the appropriate directory for Cosmovisor to use during the upgrade. + +The `prepare-upgrade` command provides detailed logging throughout the process, including: + +* The name and height of the upcoming upgrade +* The URL from which the new binary is being downloaded +* Confirmation of successful download and verification +* The path where the new binary has been placed + +Example output: + +```bash +INFO Preparing for upgrade name=v1.0.0 height=1000000 +INFO Downloading upgrade binary url=https://example.com/binary/v1.0.0?checksum=sha256:339911508de5e20b573ce902c500ee670589073485216bee8b045e853f24bce8 +INFO Upgrade preparation complete name=v1.0.0 height=1000000 +``` + +*Note: The current way of downloading manually and placing the binary at the right place would still work.* + +## Example: SimApp Upgrade + +The following instructions provide a demonstration of `cosmovisor` using the simulation application (`simapp`) shipped with the Cosmos SDK's source code. The following commands are to be run from within the `cosmos-sdk` repository. + +### Chain Setup + +Let's create a new chain using the `v0.47.4` version of simapp (the Cosmos SDK demo app): + +```shell +git checkout v0.47.4 +make build +``` + +Clean `~/.simapp` (never do this in a production environment): + +```shell +./build/simd tendermint unsafe-reset-all +``` + +Set up app config: + +```shell +./build/simd config chain-id test +./build/simd config keyring-backend test +./build/simd config broadcast-mode sync +``` + +Initialize the node and overwrite any previous genesis file (never do this in a production environment): + +```shell +./build/simd init test --chain-id test --overwrite +``` + +For the sake of this demonstration, amend `voting_period` in `genesis.json` to a reduced time of 20 seconds (`20s`): + +```shell +cat <<< $(jq '.app_state.gov.params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json +``` + +Create a validator, and setup genesis transaction: + +```shell +./build/simd keys add validator +./build/simd genesis add-genesis-account validator 1000000000stake --keyring-backend test +./build/simd genesis gentx validator 1000000stake --chain-id test +./build/simd genesis collect-gentxs +``` + +#### Prepare Cosmovisor and Start the Chain + +Set the required environment variables: + +```shell +export DAEMON_NAME=simd +export DAEMON_HOME=$HOME/.simapp +``` + +Set the optional environment variable to trigger an automatic app restart: + +```shell +export DAEMON_RESTART_AFTER_UPGRADE=true +``` + +Initialize cosmovisor with the current binary: + +```shell +cosmovisor init ./build/simd +``` + +Now you can run cosmovisor with simapp v0.47.4: + +```shell +cosmovisor run start +``` + +### Update App + +Update app to the latest version (e.g. v0.50.0). + +:::note + +Migration plans are defined using the `x/upgrade` module and described in [In-Place Store Migrations](https://github.com/cosmos/cosmos-sdk/blob/main/docs/learn/advanced/15-upgrade.md). Migrations can perform any deterministic state change. + +The migration plan to upgrade the simapp from v0.47 to v0.50 is defined in `simapp/upgrade.go`. + +::: + +Build the new version `simd` binary: + +```shell +make build +``` + +Add the new `simd` binary and the upgrade name: + +:::warning + +The migration name must match the one defined in the migration plan. + +::: + +```shell +cosmovisor add-upgrade v047-to-v050 ./build/simd +``` + +Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other): + +```shell +./build/simd tx upgrade software-upgrade v047-to-v050 --title upgrade --summary upgrade --upgrade-height 200 --upgrade-info "{}" --no-validate --from validator --yes +./build/simd tx gov deposit 1 10000000stake --from validator --yes +./build/simd tx gov vote 1 yes --from validator --yes +``` + +The upgrade will occur automatically at height 200. Note: you may need to change the upgrade height in the snippet above if your test play takes more time. From 135cdd343414f73006826ef12612d8e60322ffb4 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Thu, 3 Oct 2024 09:30:59 +0200 Subject: [PATCH 2/3] updates --- tools/cosmovisor/README.md | 411 ------------------------------------- 1 file changed, 411 deletions(-) delete mode 100644 tools/cosmovisor/README.md diff --git a/tools/cosmovisor/README.md b/tools/cosmovisor/README.md deleted file mode 100644 index 3b5f722c5d1b..000000000000 --- a/tools/cosmovisor/README.md +++ /dev/null @@ -1,411 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Cosmovisor - -`cosmovisor` is a process manager for Cosmos SDK application binaries that automates application binary switch at chain upgrades. -It polls the `upgrade-info.json` file that is created by the x/upgrade module at upgrade height, and then can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary. - -* [Design](#design) -* [Contributing](#contributing) -* [Setup](#setup) - * [Installation](#installation) - * [Command Line Arguments And Environment Variables](#command-line-arguments-and-environment-variables) - * [Folder Layout](#folder-layout) -* [Usage](#usage) - * [Initialization](#initialization) - * [Detecting Upgrades](#detecting-upgrades) - * [Adding Upgrade Binary](#adding-upgrade-binary) - * [Auto-Download](#auto-download) - * [Preparing for an Upgrade](#preparing-for-an-upgrade) -* [Example: SimApp Upgrade](#example-simapp-upgrade) - * [Chain Setup](#chain-setup) - * [Prepare Cosmovisor and Start the Chain](#prepare-cosmovisor-and-start-the-chain) - * [Update App](#update-app) - -## Design - -Cosmovisor is designed to be used as a wrapper for a `Cosmos SDK` app: - -* it will pass arguments to the associated app (configured by `DAEMON_NAME` env variable). - Running `cosmovisor run arg1 arg2 ....` will run `app arg1 arg2 ...`; -* it will manage an app by restarting and upgrading if needed; -* it is configured using environment variables, not positional arguments. - -*Note: If new versions of the application are not set up to run in-place store migrations, migrations will need to be run manually before restarting `cosmovisor` with the new binary. For this reason, we recommend applications adopt in-place store migrations.* - -:::tip -Only the latest version of cosmovisor is actively developed/maintained. -::: - -:::warning -Versions prior to v1.0.0 have a vulnerability that could lead to a DOS. Please upgrade to the latest version. -::: - -## Contributing - -Cosmovisor is part of the Cosmos SDK monorepo, but it's a separate module with it's own release schedule. - -Release branches have the following format `release/cosmovisor/vA.B.x`, where A and B are a number (e.g. `release/cosmovisor/v1.3.x`). Releases are tagged using the following format: `cosmovisor/vA.B.C`. - -## Setup - -### Installation - -You can download Cosmovisor from the [GitHub releases](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv1.5.0). - -To install the latest version of `cosmovisor`, run the following command: - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest -``` - -To install a specific version, you can specify the version: - -```shell -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.5.0 -``` - -Run `cosmovisor version` to check the cosmovisor version. - -Alternatively, for building from source, simply run `make cosmovisor`. The binary will be located in `tools/cosmovisor`. - -:::warning -Installing cosmovisor using `go install` will display the correct `cosmovisor` version. -Building from source (`make cosmovisor`) or installing `cosmovisor` by other means won't display the correct version. -::: - -### Command Line Arguments And Environment Variables - -The first argument passed to `cosmovisor` is the action for `cosmovisor` to take. Options are: - -* `help`, `--help`, or `-h` - Output `cosmovisor` help information and check your `cosmovisor` configuration. -* `run` - Run the configured binary using the rest of the provided arguments. -* `version` - Output the `cosmovisor` version and also run the binary with the `version` argument. -* `config` - Display the current `cosmovisor` configuration, that means displaying the environment variables value that `cosmovisor` is using. -* `add-upgrade` - Add an upgrade manually to `cosmovisor`. This command allow you to easily add the binary corresponding to an upgrade in cosmovisor. - -All arguments passed to `cosmovisor run` will be passed to the application binary (as a subprocess). `cosmovisor` will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. For this reason, `cosmovisor run` cannot accept any command-line arguments other than those available to the application binary. - -`cosmovisor` reads its configuration from environment variables, or its configuration file (use `--cosmovisor-config `): - -* `DAEMON_HOME` is the location where the `cosmovisor/` directory is kept that contains the genesis binary, the upgrade binaries, and any additional auxiliary files associated with each binary (e.g. `$HOME/.gaiad`, `$HOME/.regend`, `$HOME/.simd`, etc.). -* `DAEMON_NAME` is the name of the binary itself (e.g. `gaiad`, `regend`, `simd`, etc.). -* `DAEMON_ALLOW_DOWNLOAD_BINARIES` (*optional*), if set to `true`, will enable auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators). By default, `cosmovisor` will not auto-download new binaries. -* `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` (*optional*, default = `false`), if `true` cosmovisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If `false`, cosmovisor will not require a checksum to be provided, but still check the checksum if one is provided. -* `DAEMON_RESTART_AFTER_UPGRADE` (*optional*, default = `true`), if `true`, restarts the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (`false`), `cosmovisor` stops running after an upgrade and requires the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs. -* `DAEMON_RESTART_DELAY` (*optional*, default none), allow a node operator to define a delay between the node halt (for upgrade) and backup by the specified time. The value must be a duration (e.g. `1s`). -* `DAEMON_SHUTDOWN_GRACE` (*optional*, default none), if set, send interrupt to binary and wait the specified time to allow for cleanup/cache flush to disk before sending the kill signal. The value must be a duration (e.g. `1s`). -* `DAEMON_POLL_INTERVAL` (*optional*, default 300 milliseconds), is the interval length for polling the upgrade plan file. The value must be a duration (e.g. `1s`). -* `DAEMON_DATA_BACKUP_DIR` option to set a custom backup directory. If not set, `DAEMON_HOME` is used. -* `UNSAFE_SKIP_BACKUP` (defaults to `false`), if set to `true`, upgrades directly without performing a backup. Otherwise (`false`, default) backs up the data before trying the upgrade. The default value of false is useful and recommended in case of failures and when a backup needed to rollback. We recommend using the default backup option `UNSAFE_SKIP_BACKUP=false`. -* `DAEMON_PREUPGRADE_MAX_RETRIES` (defaults to `0`). The maximum number of times to call [`pre-upgrade`](https://docs.cosmos.network/main/build/building-apps/app-upgrade#pre-upgrade-handling) in the application after exit status of `31`. After the maximum number of retries, Cosmovisor fails the upgrade. -* `COSMOVISOR_DISABLE_LOGS` (defaults to `false`). If set to true, this will disable Cosmovisor logs (but not the underlying process) completely. This may be useful, for example, when a Cosmovisor subcommand you are executing returns a valid JSON you are then parsing, as logs added by Cosmovisor make this output not a valid JSON. -* `COSMOVISOR_COLOR_LOGS` (defaults to `true`). If set to true, this will colorise Cosmovisor logs (but not the underlying process). -* `COSMOVISOR_TIMEFORMAT_LOGS` (defaults to `kitchen`). If set to a value (`layout|ansic|unixdate|rubydate|rfc822|rfc822z|rfc850|rfc1123|rfc1123z|rfc3339|rfc3339nano|kitchen`), this will add timestamp prefix to Cosmovisor logs (but not the underlying process). -* `COSMOVISOR_CUSTOM_PREUPGRADE` (defaults to ``). If set, this will run $DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE prior to upgrade with the arguments [ upgrade.Name, upgrade.Height ]. Executes a custom script (separate and prior to the chain daemon pre-upgrade command) -* `COSMOVISOR_DISABLE_RECASE` (defaults to `false`). If set to true, the upgrade directory will expected to match the upgrade plan name without any case changes - -### Folder Layout - -`$DAEMON_HOME/cosmovisor` is expected to belong completely to `cosmovisor` and the subprocesses that are controlled by it. The folder content is organized as follows: - -```text -. -├── current -> genesis or upgrades/ -├── genesis -│   └── bin -│   └── $DAEMON_NAME -└── upgrades -│ └── -│ ├── bin -│ │   └── $DAEMON_NAME -│ └── upgrade-info.json -└── preupgrade.sh (optional) -``` - -The `cosmovisor/` directory includes a subdirectory for each version of the application (i.e. `genesis` or `upgrades/`). Within each subdirectory is the application binary (i.e. `bin/$DAEMON_NAME`) and any additional auxiliary files associated with each binary. `current` is a symbolic link to the currently active directory (i.e. `genesis` or `upgrades/`). The `name` variable in `upgrades/` is the lowercased URI-encoded name of the upgrade as specified in the upgrade module plan. Note that the upgrade name path are normalized to be lowercased: for instance, `MyUpgrade` is normalized to `myupgrade`, and its path is `upgrades/myupgrade`. - -Please note that `$DAEMON_HOME/cosmovisor` only stores the *application binaries*. The `cosmovisor` binary itself can be stored in any typical location (e.g. `/usr/local/bin`). The application will continue to store its data in the default data directory (e.g. `$HOME/.simapp`) or the data directory specified with the `--home` flag. `$DAEMON_HOME` is dependent of the data directory and must be set to the same directory as the data directory, you will end up with a configuration like the following: - -```text -.simapp -├── config -├── data -└── cosmovisor -``` - -## Usage - -The system administrator is responsible for: - -* installing the `cosmovisor` binary -* configuring the host's init system (e.g. `systemd`, `launchd`, etc.) -* appropriately setting the environmental variables -* creating the `/cosmovisor` directory -* creating the `/cosmovisor/genesis/bin` folder -* creating the `/cosmovisor/upgrades//bin` folders -* placing the different versions of the `` executable in the appropriate `bin` folders. - -`cosmovisor` will set the `current` link to point to `genesis` at first start (i.e. when no `current` link exists) and then handle switching binaries at the correct points in time so that the system administrator can prepare days in advance and relax at upgrade time. - -In order to support downloadable binaries, a tarball for each upgrade binary will need to be packaged up and made available through a canonical URL. Additionally, a tarball that includes the genesis binary and all available upgrade binaries can be packaged up and made available so that all the necessary binaries required to sync a fullnode from start can be easily downloaded. - -The `DAEMON` specific code and operations (e.g. cometBFT config, the application db, syncing blocks, etc.) all work as expected. The application binaries' directives such as command-line flags and environment variables also work as expected. - -### Initialization - -The `cosmovisor init ` command creates the folder structure required for using cosmovisor. - -It does the following: - -* creates the `/cosmovisor` folder if it doesn't yet exist -* creates the `/cosmovisor/genesis/bin` folder if it doesn't yet exist -* copies the provided executable file to `/cosmovisor/genesis/bin/` -* creates the `current` link, pointing to the `genesis` folder - -It uses the `DAEMON_HOME` and `DAEMON_NAME` environment variables for folder location and executable name. - -The `cosmovisor init` command is specifically for initializing cosmovisor, and should not be confused with a chain's `init` command (e.g. `cosmovisor run init`). - -### Detecting Upgrades - -`cosmovisor` is polling the `$DAEMON_HOME/data/upgrade-info.json` file for new upgrade instructions. The file is created by the x/upgrade module in `BeginBlocker` when an upgrade is detected and the blockchain reaches the upgrade height. -The following heuristic is applied to detect the upgrade: - -* When starting, `cosmovisor` doesn't know much about currently running upgrade, except the binary which is `current/bin/`. It tries to read the `current/update-info.json` file to get information about the current upgrade name. -* If neither `cosmovisor/current/upgrade-info.json` nor `data/upgrade-info.json` exist, then `cosmovisor` will wait for `data/upgrade-info.json` file to trigger an upgrade. -* If `cosmovisor/current/upgrade-info.json` doesn't exist but `data/upgrade-info.json` exists, then `cosmovisor` assumes that whatever is in `data/upgrade-info.json` is a valid upgrade request. In this case `cosmovisor` tries immediately to make an upgrade according to the `name` attribute in `data/upgrade-info.json`. -* Otherwise, `cosmovisor` waits for changes in `upgrade-info.json`. As soon as a new upgrade name is recorded in the file, `cosmovisor` will trigger an upgrade mechanism. - -When the upgrade mechanism is triggered, `cosmovisor` will: - -1. if `DAEMON_ALLOW_DOWNLOAD_BINARIES` is enabled, start by auto-downloading a new binary into `cosmovisor//bin` (where `` is the `upgrade-info.json:name` attribute); -2. update the `current` symbolic link to point to the new directory and save `data/upgrade-info.json` to `cosmovisor/current/upgrade-info.json`. - -### Adding Upgrade Binary - -`cosmovisor` has an `add-upgrade` command that allows to easily link a binary to an upgrade. It creates a new folder in `cosmovisor/upgrades/` and copies the provided executable file to `cosmovisor/upgrades//bin/`. - -Using the `--upgrade-height` flag allows to specify at which height the binary should be switched, without going via a gorvernance proposal. -This enables support for an emergency coordinated upgrades where the binary must be switched at a specific height, but there is no time to go through a governance proposal. - -:::warning -`--upgrade-height` creates an `upgrade-info.json` file. This means if a chain upgrade via governance proposal is executed before the specified height with `--upgrade-height`, the governance proposal will overwrite the `upgrade-info.json` plan created by `add-upgrade --upgrade-height `. -Take this into consideration when using `--upgrade-height`. -::: - -### Auto-Download - -Generally, `cosmovisor` requires that the system administrator place all relevant binaries on disk before the upgrade happens. However, for people who don't need such control and want an automated setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option. - -**NOTE: we don't recommend using auto-download** because it doesn't verify in advance if a binary is available. If there will be any issue with downloading a binary, the cosmovisor will stop and won't restart an App (which could lead to a chain halt). - -If `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `true`, and no local binary can be found when an upgrade is triggered, `cosmovisor` will attempt to download and install the binary itself based on the instructions in the `info` attribute in the `data/upgrade-info.json` file. The files is constructed by the x/upgrade module and contains data from the upgrade `Plan` object. The `Plan` has an info field that is expected to have one of the following two valid formats to specify a download: - -1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the `"binaries"` key. For example: - - ```json - { - "binaries": { - "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" - } - } - ``` - - You can include multiple binaries at once to ensure more than one environment will receive the correct binaries: - - ```json - { - "binaries": { - "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f", - "linux/arm64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f", - "darwin/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" - } - } - ``` - - When submitting this as a proposal ensure there are no spaces. An example command using `gaiad` could look like: - - ```shell - > gaiad tx upgrade software-upgrade Vega \ - --title Vega \ - --deposit 100uatom \ - --upgrade-height 7368420 \ - --upgrade-info '{"binaries":{"linux/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-amd64","linux/arm64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-linux-arm64","darwin/amd64":"https://github.com/cosmos/gaia/releases/download/v6.0.0-rc1/gaiad-v6.0.0-rc1-darwin-amd64"}}' \ - --summary "upgrade to Vega" \ - --gas 400000 \ - --from user \ - --chain-id test \ - --home test/val2 \ - --node tcp://localhost:36657 \ - --yes - ``` - -2. Store a link to a file that contains all information in the above format (e.g. if you want to specify lots of binaries, changelog info, etc. without filling up the blockchain). For example: - - ```text - https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e - ``` - -When `cosmovisor` is triggered to download the new binary, `cosmovisor` will parse the `"binaries"` field, download the new binary with [go-getter](https://github.com/hashicorp/go-getter), and unpack the new binary in the `upgrades/` folder so that it can be run as if it was installed manually. - -Note that for this mechanism to provide strong security guarantees, all URLs should include a SHA 256/512 checksum. This ensures that no false binary is run, even if someone hacks the server or hijacks the DNS. `go-getter` will always ensure the downloaded file matches the checksum if it is provided. `go-getter` will also handle unpacking archives into directories (in this case the download link should point to a `zip` file of all data in the `bin` directory). - -To properly create a sha256 checksum on linux, you can use the `sha256sum` utility. For example: - -```shell -sha256sum ./testdata/repo/zip_directory/autod.zip -``` - -The result will look something like the following: `29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7`. - -You can also use `sha512sum` if you would prefer to use longer hashes, or `md5sum` if you would prefer to use broken hashes. Whichever you choose, make sure to set the hash algorithm properly in the checksum argument to the URL. - -### Preparing for an Upgrade - -To prepare for an upgrade, use the `prepare-upgrade` command: - -```shell -cosmovisor prepare-upgrade -``` - -This command performs the following actions: - -1. Retrieves upgrade information directly from the blockchain about the next scheduled upgrade. -2. Downloads the new binary specified in the upgrade plan. -3. Verifies the binary's checksum (if required by configuration). -4. Places the new binary in the appropriate directory for Cosmovisor to use during the upgrade. - -The `prepare-upgrade` command provides detailed logging throughout the process, including: - -* The name and height of the upcoming upgrade -* The URL from which the new binary is being downloaded -* Confirmation of successful download and verification -* The path where the new binary has been placed - -Example output: - -```bash -INFO Preparing for upgrade name=v1.0.0 height=1000000 -INFO Downloading upgrade binary url=https://example.com/binary/v1.0.0?checksum=sha256:339911508de5e20b573ce902c500ee670589073485216bee8b045e853f24bce8 -INFO Upgrade preparation complete name=v1.0.0 height=1000000 -``` - -*Note: The current way of downloading manually and placing the binary at the right place would still work.* - -## Example: SimApp Upgrade - -The following instructions provide a demonstration of `cosmovisor` using the simulation application (`simapp`) shipped with the Cosmos SDK's source code. The following commands are to be run from within the `cosmos-sdk` repository. - -### Chain Setup - -Let's create a new chain using the `v0.47.4` version of simapp (the Cosmos SDK demo app): - -```shell -git checkout v0.47.4 -make build -``` - -Clean `~/.simapp` (never do this in a production environment): - -```shell -./build/simd tendermint unsafe-reset-all -``` - -Set up app config: - -```shell -./build/simd config chain-id test -./build/simd config keyring-backend test -./build/simd config broadcast-mode sync -``` - -Initialize the node and overwrite any previous genesis file (never do this in a production environment): - -```shell -./build/simd init test --chain-id test --overwrite -``` - -For the sake of this demonstration, amend `voting_period` in `genesis.json` to a reduced time of 20 seconds (`20s`): - -```shell -cat <<< $(jq '.app_state.gov.params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json -``` - -Create a validator, and setup genesis transaction: - -```shell -./build/simd keys add validator -./build/simd genesis add-genesis-account validator 1000000000stake --keyring-backend test -./build/simd genesis gentx validator 1000000stake --chain-id test -./build/simd genesis collect-gentxs -``` - -#### Prepare Cosmovisor and Start the Chain - -Set the required environment variables: - -```shell -export DAEMON_NAME=simd -export DAEMON_HOME=$HOME/.simapp -``` - -Set the optional environment variable to trigger an automatic app restart: - -```shell -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Initialize cosmovisor with the current binary: - -```shell -cosmovisor init ./build/simd -``` - -Now you can run cosmovisor with simapp v0.47.4: - -```shell -cosmovisor run start -``` - -### Update App - -Update app to the latest version (e.g. v0.50.0). - -:::note - -Migration plans are defined using the `x/upgrade` module and described in [In-Place Store Migrations](https://github.com/cosmos/cosmos-sdk/blob/main/docs/learn/advanced/15-upgrade.md). Migrations can perform any deterministic state change. - -The migration plan to upgrade the simapp from v0.47 to v0.50 is defined in `simapp/upgrade.go`. - -::: - -Build the new version `simd` binary: - -```shell -make build -``` - -Add the new `simd` binary and the upgrade name: - -:::warning - -The migration name must match the one defined in the migration plan. - -::: - -```shell -cosmovisor add-upgrade v047-to-v050 ./build/simd -``` - -Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other): - -```shell -./build/simd tx upgrade software-upgrade v047-to-v050 --title upgrade --summary upgrade --upgrade-height 200 --upgrade-info "{}" --no-validate --from validator --yes -./build/simd tx gov deposit 1 10000000stake --from validator --yes -./build/simd tx gov vote 1 yes --from validator --yes -``` - -The upgrade will occur automatically at height 200. Note: you may need to change the upgrade height in the snippet above if your test play takes more time. From bfff91e5dfb6d6ec44faa3f52781633fc7093cd7 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Thu, 3 Oct 2024 09:32:03 +0200 Subject: [PATCH 3/3] updates --- simapp/upgrades.go | 6 +++--- simapp/v2/upgrades.go | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/simapp/upgrades.go b/simapp/upgrades.go index 151517ccdd9f..392d3b46cf72 100644 --- a/simapp/upgrades.go +++ b/simapp/upgrades.go @@ -15,12 +15,12 @@ import ( ) // UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade -// from v0.52.x to v0.54.x +// from v0.50.x to v0.52.x // // NOTE: This upgrade defines a reference implementation of what an upgrade // could look like when an application is migrating from Cosmos SDK version -// v0.52.x to v0.54.x. -const UpgradeName = "v052-to-v054" +// v0.59.x to v0.52.x. +const UpgradeName = "v050-to-v052" func (app SimApp) RegisterUpgradeHandlers() { app.UpgradeKeeper.SetUpgradeHandler( diff --git a/simapp/v2/upgrades.go b/simapp/v2/upgrades.go index 0c0adc2bed8a..862c46b21e92 100644 --- a/simapp/v2/upgrades.go +++ b/simapp/v2/upgrades.go @@ -12,12 +12,12 @@ import ( ) // UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade -// from v0.52.x to v2 +// from v0.50.x to v2 // // NOTE: This upgrade defines a reference implementation of what an upgrade // could look like when an application is migrating from Cosmos SDK version -// v0.52.x to v2. -const UpgradeName = "v052-to-v2" +// v0.50.x to v2. +const UpgradeName = "v050-to-v2" func (app *SimApp[T]) RegisterUpgradeHandlers() { app.UpgradeKeeper.SetUpgradeHandler(