diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 62810ca82e0d..ff96995e028a 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -164,7 +164,7 @@ jobs: sed -i.bak "/$(echo $filename | sed 's/\//\\\//g')/d" coverage.txt done if: env.GIT_DIFF - - uses: codecov/codecov-action@v1.5.2 + - uses: codecov/codecov-action@v2.0.2 with: file: ./coverage.txt if: env.GIT_DIFF diff --git a/.gitignore b/.gitignore index 83d56ddf8e75..14e117b3bad6 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ docs/_build docs/tutorial docs/node_modules docs/modules +docs/run-node/cosmovisor.md dist tools-stamp buf-stamp diff --git a/CHANGELOG.md b/CHANGELOG.md index b618605a2a7f..361c850ea172 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -74,6 +74,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ ### Improvements * (cli) [\#9593](https://github.com/cosmos/cosmos-sdk/pull/9593) Check if chain-id is blank before verifying signatures in multisign and error. +* (cli) [\#9717](https://github.com/cosmos/cosmos-sdk/pull/9717) Added CLI flag `--output json/text` to `tx` cli commands. ### Bug Fixes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 788c58d6f68e..a7610a0f0ad1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,58 +72,57 @@ of how these are written refer to the current [ADRs](https://github.com/cosmos/c ## Pull Requests -PRs should be categorically broken up based on the type of changes being made (i.e. `fix`, `feat`, -`refactor`, `docs`, etc.). The *type* must be included in the PR title as a prefix (e.g. -`fix: `). This ensures that all changes committed to the base branch follow the +PRs should be categorically broken up based on the type of changes being made (for example, `fix`, `feat`, +`refactor`, `docs`, and so on). The *type* must be included in the PR title as a prefix (for example, +`fix: `). This convention ensures that all changes that are committed to the base branch follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. Additionally, each PR should only address a single issue. ### Pull Request Templates -There are currently three PR templates. The [default template](./.github/PULL_REQUEST_TEMPLATE.md) is for types `fix`, `feat`, and `refactor`. We also have a [docs template](./.github/PULL_REQUEST_TEMPLATE/docs.md) for documentation changes and an [other template](./.github/PULL_REQUEST_TEMPLATE/other.md) for changes that do not affect production code. When previewing a PR before it has been opened, you can change the template by adding one of the following parameters to the url: +There are three PR templates. The [default template](./.github/PULL_REQUEST_TEMPLATE.md) is for types `fix`, `feat`, and `refactor`. We also have a [docs template](./.github/PULL_REQUEST_TEMPLATE/docs.md) for documentation changes and an [other template](./.github/PULL_REQUEST_TEMPLATE/other.md) for changes that do not affect production code. When previewing a PR before it has been opened, you can change the template by adding one of the following parameters to the url: - `template=docs.md` - `template=other.md` ### Requesting Reviews -In order to accomodate the review process, the author of the PR must complete the author checklist +In order to accommodate the review process, the author of the PR must complete the author checklist to the best of their abilities before marking the PR as "Ready for Review". If you would like to receive early feedback on the PR, open the PR as a "Draft" and leave a comment in the PR indicating that you would like early feedback and tagging whoever you would like to receive feedback from. ### Reviewing Pull Requests -All PRs require at least two reviews before they can be merged (one review might be acceptable in -the case of minor changes to [docs](./.github/PULL_REQUEST_TEMPLATE/docs.md) or [other](./.github/PULL_REQUEST_TEMPLATE/other.md) changes that do not affect production code). Each PR template has a -reviewers checklist that must be completed before the PR can be merged. Each reviewer is responsible +All PRs require at least two review approvals before they can be merged (one review might be acceptable in +the case of minor changes to [docs](./.github/PULL_REQUEST_TEMPLATE/docs.md) or [other](./.github/PULL_REQUEST_TEMPLATE/other.md) changes that do not affect production code). Each PR template has a reviewers checklist that must be completed before the PR can be merged. Each reviewer is responsible for all checked items unless they have indicated otherwise by leaving their handle next to specific -items. In addition, please use the following review explanations: +items. In addition, use the following review explanations: - `LGTM` without an explicit approval means that the changes look good, but you haven't thoroughly reviewed the reviewer checklist items. -- `Approval` means that you have completed some or all of the reviewer checklist items. If you only reviewed selected items, you have added your handle next to the items that you have reviewed. In addition, please follow these guidelines: +- `Approval` means that you have completed some or all of the reviewer checklist items. If you only reviewed selected items, you must add your handle next to the items that you have reviewed. In addition, follow these guidelines: - You must also think through anything which ought to be included but is not - You must think through whether any added code could be partially combined (DRYed) with existing code - You must think through any potential security issues or incentive-compatibility flaws introduced by the changes - Naming must be consistent with conventions and the rest of the codebase - - Code must live in a reasonable location, considering dependency structures (e.g. not importing testing modules in production code, or including example code modules in production code). - - If you approve of the PR, you are responsible for any issues mentioned here and any issues that should have been addressed after thoroughly reviewing the reviewer checklist items in the pull request template. -- If you sat down with the PR submitter and did a pairing review please note that in the `Approval`, or your PR comments. + - Code must live in a reasonable location, considering dependency structures (for example, not importing testing modules in production code, or including example code modules in production code). + - If you approve the PR, you are responsible for any issues mentioned here and any issues that should have been addressed after thoroughly reviewing the reviewer checklist items in the pull request template. +- If you sat down with the PR submitter and did a pairing review, add this information in the `Approval` or your PR comments. - If you are only making "surface level" reviews, submit any notes as `Comments` without adding a review. ### Updating Documentation If you open a PR on the Cosmos SDK, it is mandatory to update the relevant documentation in `/docs`. -- If your change relates to the core SDK (baseapp, store, ...), please update the `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders. -- If your changes relate to the core of the CLI (not specifically to module's CLI/Rest), please modify the `docs/run-node/` folder. -- If your changes relate to a module, please update the module's spec in `x/moduleName/docs/spec/`. +- If your change relates to the core SDK (baseapp, store, ...), be sure to update the content in `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders. +- If your changes relate to the core of the CLI (not specifically to module's CLI/Rest), then modify the content in the `docs/run-node/` folder. +- If your changes relate to a module, then be sure to update the module's spec in `x/moduleName/docs/spec/`. When writing documentation, follow the [Documentation Writing Guidelines](./docs/DOC_WRITING_GUIDELINES.md). ## Forking -Please note that Go requires code to live under absolute paths, which complicates forking. +Go requires code to live under absolute paths, and this requirement complicates forking. While my fork lives at `https://github.com/rigeyrigerige/cosmos-sdk`, the code should never exist at `$GOPATH/src/github.com/rigeyrigerige/cosmos-sdk`. Instead, we use `git remote` to add the fork as a new remote for the original repo, diff --git a/client/flags/flags.go b/client/flags/flags.go index 80c3e792256a..c4faad1b035a 100644 --- a/client/flags/flags.go +++ b/client/flags/flags.go @@ -93,6 +93,7 @@ func AddQueryFlagsToCmd(cmd *cobra.Command) { // AddTxFlagsToCmd adds common flags to a module tx command. func AddTxFlagsToCmd(cmd *cobra.Command) { + cmd.Flags().StringP(tmcli.OutputFlag, "o", "json", "Output format (text|json)") cmd.Flags().String(FlagKeyringDir, "", "The client Keyring directory; if omitted, the default 'home' directory will be used") cmd.Flags().String(FlagFrom, "", "Name or address of private key with which to sign") cmd.Flags().Uint64P(FlagAccountNumber, "a", 0, "The account number of the signing account (offline mode only)") diff --git a/cosmovisor/README.md b/cosmovisor/README.md index 33becafcb9e6..e263966a49a0 100644 --- a/cosmovisor/README.md +++ b/cosmovisor/README.md @@ -39,7 +39,7 @@ All arguments passed to `cosmovisor` will be passed to the application binary (a └── $DAEMON_NAME ``` -The `cosmovisor/` directory incudes 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 URI-encoded name of the upgrade as specified in the upgrade module plan. +The `cosmovisor/` directory incudes 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 URI-encoded name of the upgrade as specified in the upgrade module plan. 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/.gaiad`) or the data directory specified with the `--home` flag. `$DAEMON_HOME` is independent of the data directory and can be set to any location. If you set `$DAEMON_HOME` to the same directory as the data directory, you will end up with a configuation like the following: @@ -90,7 +90,7 @@ https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d 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. +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: @@ -106,7 +106,13 @@ You can also use `sha512sum` if you would prefer to use longer hashes, or `md5su 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. -First compile the `simd` binary: +First, check out the latest `v0.42` release: + +``` +git checkout v0.42.7 +``` + +Compile the `simd` binary: ``` make build @@ -186,7 +192,7 @@ app.UpgradeKeeper = upgradekeeper.NewKeeper(skipUpgradeHeights, keys[upgradetype After that line, add the following: - ```go +```go app.UpgradeKeeper.SetUpgradeHandler("test1", func(ctx sdk.Context, plan upgradetypes.Plan) { // Add some coins to a random account addr, err := sdk.AccAddressFromBech32("cosmos18cgkqduwuh253twzmhedesw3l7v3fm37sppt58") diff --git a/docs/basics/accounts.md b/docs/basics/accounts.md index b8bcb76aef77..d57f80955cd1 100644 --- a/docs/basics/accounts.md +++ b/docs/basics/accounts.md @@ -70,12 +70,11 @@ The Cosmos SDK supports the following digital key schemes for creating digital s - `secp256r1`, as implemented in the [SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/secp256r1/pubkey.go), - `tm-ed25519`, as implemented in the [SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation. -| | Address length | Public key length | Used for transaction | Used for consensus | -| | in bytes | in bytes | authentication | (tendermint) | -|--------------+----------------+-------------------+----------------------+--------------------| -| `secp256k1` | 20 | 33 | yes | no | -| `secp256r1` | 32 | 33 | yes | no | -| `tm-ed25519` | -- not used -- | 32 | no | yes | +| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) | +|:------------:|:-----------------------:|:--------------------------:|:-----------------------------------:|:-------------------------------:| +| `secp256k1` | 20 | 33 | yes | no | +| `secp256r1` | 32 | 33 | yes | no | +| `tm-ed25519` | -- not used -- | 32 | no | yes | ## Addresses diff --git a/docs/basics/app-anatomy.md b/docs/basics/app-anatomy.md index 0373d24aafa5..d25720279399 100644 --- a/docs/basics/app-anatomy.md +++ b/docs/basics/app-anatomy.md @@ -135,7 +135,7 @@ See an example of a `MakeTestEncodingConfig` from `simapp`: Modules must implement [interfaces](../building-modules/module-manager.md#application-module-interfaces) defined in the Cosmos SDK, [`AppModuleBasic`](../building-modules/module-manager.md#appmodulebasic) and [`AppModule`](../building-modules/module-manager.md#appmodule). The former implements basic non-dependant elements of the module, such as the `codec`, while the latter handles the bulk of the module methods (including methods that require references to other modules' `keeper`s). Both the `AppModule` and `AppModuleBasic` types are defined in a file called `./module.go`. -`AppModule` exposes a collection of useful methods on the module that facilitates the composition of modules into a coherent application. These methods are are called from the `module manager`(../building-modules/module-manager.md#manager), which manages the application's collection of modules. +`AppModule` exposes a collection of useful methods on the module that facilitates the composition of modules into a coherent application. These methods are called from the `module manager`(../building-modules/module-manager.md#manager), which manages the application's collection of modules. ### `Msg` Services diff --git a/docs/core/grpc_rest.md b/docs/core/grpc_rest.md index 721eb5991dc4..d962e43907f0 100644 --- a/docs/core/grpc_rest.md +++ b/docs/core/grpc_rest.md @@ -34,11 +34,13 @@ Please see [issue #8392](https://github.com/cosmos/cosmos-sdk/issues/8392) for m Cosmos SDK v0.40 introduced Protobuf as the main [encoding](./encoding) library, and this brings a wide range of Protobuf-based tools that can be plugged into the SDK. One such tool is [gRPC](https://grpc.io), a modern open source high performance RPC framework that has decent client support in several languages. -Each module exposes [`Msg` and `Query` Protobuf services](../building-modules/messages-and-queries.md) to define state transitions and state queries. These services are hooked up to gRPC via the following function inside the application: +Each module exposes a [Protobuf `Query` service](../building-modules/messages-and-queries.md#queries) that defines state queries. The `Query` services and a transaction service used to broadcast transactions are hooked up to the gRPC server via the following function inside the application: - ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-rc0/server/types/app.go#L39-L41 -The `grpc.Server` is a concrete gRPC server, which spawns and serves any gRPC requests. This server can be configured inside `~/.simapp/config/app.toml`: +Note: It is not possible to expose any [Protobuf `Msg` service](../building-modules/messages-and-queries.md#messages) endpoints via gRPC. Transactions must be generated and signed using the CLI or programatically before they can be broadcasted using gRPC. See [Generating, Signing, and Broadcasting Transactions](../run-node/txs.html) for more information. + +The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC query requests and a broadcast transaction request. This server can be configured inside `~/.simapp/config/app.toml`: - `grpc.enable = true|false` field defines if the gRPC server should be enabled. Defaults to `true`. - `grpc.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`) the server should bind to. Defaults to `0.0.0.0:9090`. @@ -65,7 +67,7 @@ All routes are configured under the following fields in `~/.simapp/config/app.to If, for various reasons, you cannot use gRPC (for example, you are building a web application, and browsers don't support HTTP2 on which gRPC is built), then the SDK offers REST routes via gRPC-gateway. -[gRPC-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) is a tool to expose gRPC endpoints as REST endpoints. For each RPC endpoint defined in a Protobuf service, the SDK offers a REST equivalent. For instance, querying a balance could be done via the `/cosmos.bank.v1beta1.QueryAllBalances` gRPC endpoint, or alternatively via the gRPC-gateway `"/cosmos/bank/v1beta1/balances/{address}"` REST endpoint: both will return the same result. For each RPC method defined in a Protobuf service, the corresponding REST endpoint is defined as an option: +[gRPC-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) is a tool to expose gRPC endpoints as REST endpoints. For each gRPC endpoint defined in a Protobuf `Query` service, the SDK offers a REST equivalent. For instance, querying a balance could be done via the `/cosmos.bank.v1beta1.QueryAllBalances` gRPC endpoint, or alternatively via the gRPC-gateway `"/cosmos/bank/v1beta1/balances/{address}"` REST endpoint: both will return the same result. For each RPC method defined in a Protobuf `Query` service, the corresponding REST endpoint is defined as an option: +++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/proto/cosmos/bank/v1beta1/query.proto#L19-L22 @@ -73,7 +75,7 @@ For application developers, gRPC-gateway REST routes needs to be wired up to the ### Legacy REST API Routes -The REST routes present in Cosmos SDK v0.39 and earlier are marked as deprecated via a [HTTP deprecation header](https://tools.ietf.org/id/draft-dalal-deprecation-header-01.html). They are still maintained to keep backwards compatibility, but will be removed in v0.41. For updating from Legacy REST routes to new gRPC-gateway REST routes, please refer to our [migration guide](../migrations/rest.md). +The REST routes present in Cosmos SDK v0.39 and earlier are marked as deprecated via a [HTTP deprecation header](https://tools.ietf.org/id/draft-dalal-deprecation-header-01.html). They are still maintained to keep backwards compatibility, but will be removed in v0.44. For updating from Legacy REST routes to new gRPC-gateway REST routes, please refer to our [migration guide](../migrations/rest.md). For application developers, Legacy REST API routes needs to be wired up to the REST server, this is done by calling the `RegisterRESTRoutes` function on the ModuleManager. diff --git a/docs/ibc/integration.md b/docs/ibc/integration.md index ec48126fd40c..b3837acd4f80 100644 --- a/docs/ibc/integration.md +++ b/docs/ibc/integration.md @@ -206,7 +206,7 @@ connection handhake. The IBC module also has [`BeginBlock`](https://github.com/cosmos/ibc-go/blob/main/modules/core/02-client/abci.go) logic as well. This is optional as it is only required if your application uses the [localhost -client](https://github.com/cosmos/ics/blob/master/spec/ics-009-loopback-client) to connect two +client](https://github.com/cosmos/ibc/tree/master/spec/client/ics-009-loopback-client) to connect two different modules from the same chain. ::: tip diff --git a/docs/ibc/overview.md b/docs/ibc/overview.md index e6662ce9bb94..7226ce6c1575 100644 --- a/docs/ibc/overview.md +++ b/docs/ibc/overview.md @@ -1,4 +1,6 @@ - + # IBC Overview diff --git a/docs/post.sh b/docs/post.sh index 2662dd1a31f1..af7c9a0fb0ae 100755 --- a/docs/post.sh +++ b/docs/post.sh @@ -1,3 +1,4 @@ #!/usr/bin/env bash rm -rf modules +rm -rf run-node/cosmovisor.md diff --git a/docs/pre.sh b/docs/pre.sh index 46b1db77d4f0..495fd912ef27 100755 --- a/docs/pre.sh +++ b/docs/pre.sh @@ -10,3 +10,5 @@ for D in ../x/*; do done cat ../x/README.md | sed 's/\.\/x/\/modules/g' | sed 's/spec\/README.md//g' | sed 's/\.\.\/docs\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./modules/README.md + +cp ../cosmovisor/README.md ./run-node/cosmovisor.md diff --git a/docs/run-node/cosmovisor.md b/docs/run-node/cosmovisor.md deleted file mode 100644 index fb4d57402b8a..000000000000 --- a/docs/run-node/cosmovisor.md +++ /dev/null @@ -1,224 +0,0 @@ - - -# Cosmosvisor Quick Start - -`cosmovisor` is a small process manager around Cosmos SDK binaries that monitors the governance module via stdout to see if there's a chain upgrade proposal coming in. If it see a proposal that gets approved it can be run manually or automatically to download the new code, stop the node, run the migration script, replace the node binary, and start with the new genesis file. - -## Installation - -Run: - -`go get github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor` - -## Command Line Arguments And Environment Variables - -All arguments passed to the `cosmovisor` program will be passed to the current daemon binary (as a subprocess). -It will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. Because of that, it cannot accept -any command line arguments, nor print anything to output (unless it terminates unexpectedly before executing a -binary). - -`cosmovisor` reads its configuration from environment variables: - -* `DAEMON_HOME` is the location where upgrade binaries should be kept (e.g. `$HOME/.gaiad` or `$HOME/.xrnd`). -* `DAEMON_NAME` is the name of the binary itself (eg. `xrnd`, `gaiad`, `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). -* `DAEMON_RESTART_AFTER_UPGRADE` (*optional*) if set to `true` it will restart the sub-process with the same -command line arguments and flags (but new binary) after a successful upgrade. By default, `cosmovisor` dies -afterwards and allows the supervisor to restart it if needed. Note that this will not auto-restart the child -if there was an error. -* `DAEMON_LOG_BUFFER_SIZE` (*optional*) is the buffer size for cosmovisor to scan log. If not set, it will use the default [64](https://github.com/golang/go/blob/2217e89ba326875470a856cd0da79f3ec9a896b8/src/bufio/scan.go#L80). (e.g. set to `256` or `512`) It is to avoid scanning stuck in case of long line of the log. - -## Data Folder Layout - -`$DAEMON_HOME/cosmovisor` is expected to belong completely to `cosmovisor` and -subprocesses that are controlled by it. The folder content is organised as follows: - -``` -. -├── current -> genesis or upgrades/ -├── genesis -│   └── bin -│   └── $DAEMON_NAME -└── upgrades - └── - └── bin - └── $DAEMON_NAME -``` - -Each version of the Cosmos SDK application is stored under either `genesis` or `upgrades/`, which holds `bin/$DAEMON_NAME` -along with any other needed files such as auxiliary client programs or libraries. `current` is a symbolic link to the currently -active folder (so `current/bin/$DAEMON_NAME` is the currently active binary). - -*Note: the `name` variable in `upgrades/` holds the URI-encoded name of the upgrade as specified in the upgrade module plan.* - -Please note that `$DAEMON_HOME/cosmovisor` just stores the *binaries* and associated *program code*. -The `cosmovisor` binary can be stored in any typical location (eg `/usr/local/bin`). The actual blockchain -program will store it's data under their default data directory (e.g. `$HOME/.gaiad`) which is independent of -the `$DAEMON_HOME`. You can choose to set `$DAEMON_HOME` to the actual binary's home directory and then end up -with a configuation like the following, but this is left as a choice to the system admininstrator for best -directory layout: - -``` -.gaiad -├── config -├── data -└── cosmovisor -``` - -## Usage - -The system administrator admin is responsible for: - -* installing the `cosmovisor` binary and configure the host's init system (e.g. `systemd`, `launchd`, etc) along with the environmental variables appropriately; -* installing the `genesis` folder manually; -* installing the `upgrades/` folders manually. - -`cosmovisor` will set the `current` link to point to `genesis` at first start (when no `current` link exists) and handles -binaries switch overs at the correct points in time, so that the system administrator can prepare days in advance and relax at upgrade time. - -Note that blockchain applications that wish to support upgrades may package up a genesis `cosmovisor` tarball with this information, -just as they prepare the genesis binary tarball. In fact, they may offer a tarball will all upgrades up to current point for easy download -for those who wish to sync a fullnode from start. - -The `DAEMON` specific code and operations (e.g. tendermint config, the application db, syncing blocks, etc) are performed as normal. -Application binaries' directives such as command-line flags and environment variables work normally. - -## Auto-Download - -Generally, the system requires that the system administrator place all relevant binaries -on the disk before the upgrade happens. However, for people who don't need such -control and want an easier setup (maybe they are syncing a non-validating fullnode -and want to do little maintenance), there is another option. - -If you set `DAEMON_ALLOW_DOWNLOAD_BINARIES=on` then when an upgrade is triggered and no local binary -can be found, the `cosmovisor` will attempt to download and install the binary itself. -The plan stored in the upgrade module has an info field for arbitrary json. -This info is expected to be outputed on the halt log message. There are two -valid format to specify a download in such a message: - -1. Store an os/architecture -> binary URI map in the upgrade plan info field -as JSON under the `"binaries"` key, eg: - -```json -{ - "binaries": { - "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" - } -} -``` - -2. Store a link to a file that contains all information in the above format (eg. if you want -to specify lots of binaries, changelog info, etc without filling up the blockchain). - -e.g. `https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e` - -This file contained in the link will be retrieved by [go-getter](https://github.com/hashicorp/go-getter) -and the `"binaries"` field will be parsed as above. - -If there is no local binary, `DAEMON_ALLOW_DOWNLOAD_BINARIES=on`, and we can access a canonical url for the new binary, -then the `cosmovisor` will download it with [go-getter](https://github.com/hashicorp/go-getter) and -unpack it into the `upgrades/` folder to be run as if we installed it 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 (so these download links should be -a zip of all data in the `bin` directory). - -To properly create a checksum on linux, you can use the `sha256sum` utility. e.g. -`sha256sum ./testdata/repo/zip_directory/autod.zip` -which should return `29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7`. -You can also use `sha512sum` if you like longer hashes, or `md5sum` if you like to use broken hashes. -Make sure to set the hash algorithm properly in the checksum argument to the url. - -## Example: simd - -The following instructions provide a demonstration of `cosmovisor`'s integration with the `simd` application -shipped along the Cosmos SDK's source code. - -First compile `simd`: - -``` -cd cosmos-sdk/ -make build -``` - -Create a new key and setup the `simd` node: - -``` -rm -rf $HOME/.simapp -./build/simd keys --keyring-backend=test add validator -./build/simd init testing --chain-id test -./build/simd add-genesis-account --keyring-backend=test $(./build/simd keys --keyring-backend=test show validator -a) 1000000000stake,1000000000validatortoken -./build/simd gentx --keyring-backend test --chain-id test validator 100000stake -./build/simd collect-gentxs -``` - -Set the required environment variables: - -``` -export DAEMON_NAME=simd # binary name -export DAEMON_HOME=$HOME/.simapp # daemon's home directory -``` - -Create the `cosmovisor`’s genesis folders and deploy the binary: - -``` -mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin -cp ./build/simd $DAEMON_HOME/cosmovisor/genesis/bin -``` - -For the sake of this demonstration, we would amend `voting_params.voting_period` in `.simapp/config/genesis.json` to a reduced time ~5 minutes (300s) and eventually launch `cosmosvisor`: - -``` -cosmovisor start -``` - -Submit a software upgrade proposal: - -``` -./build/simd tx gov submit-proposal software-upgrade test1 --title "upgrade-demo" --description "upgrade" --from validator --upgrade-height 100 --deposit 10000000stake --chain-id test --keyring-backend test -y -``` - -Query the proposal to ensure it was correctly broadcast and added to a block: - -``` -./build/simd query gov proposal 1 -``` - -Submit a `Yes` vote for the upgrade proposal: - -``` -./build/simd tx gov vote 1 yes --from validator --keyring-backend test --chain-id test -y -``` - -For the sake of this demonstration, we will hardcode a modification in `simapp` to simulate a code change. -In `simapp/app.go`, find the line containing the upgrade Keeper initialisation, it should look like -`app.UpgradeKeeper = upgradekeeper.NewKeeper(skipUpgradeHeights, keys[upgradetypes.StoreKey], appCodec, homePath)`. -After that line, add the following snippet: - - ``` - app.UpgradeKeeper.SetUpgradeHandler("test1", func(ctx sdk.Context, plan upgradetypes.Plan) { - // Add some coins to a random account - addr, err := sdk.AccAddressFromBech32("cosmos18cgkqduwuh253twzmhedesw3l7v3fm37sppt58") - if err != nil { - panic(err) - } - err = app.BankKeeper.AddCoins(ctx, addr, sdk.Coins{sdk.Coin{Denom: "stake", Amount: sdk.NewInt(345600000)}}) - if err != nil { - panic(err) - } - }) -``` - -Now recompile a new binary and place it in `$DAEMON_HOME/cosmosvisor/upgrades/test1/bin`: - -``` -make build -cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/test1/bin -``` - -The upgrade will occur automatically at height 100. diff --git a/docs/run-node/txs.md b/docs/run-node/txs.md index 0441a27cdc9f..85e0488e74eb 100644 --- a/docs/run-node/txs.md +++ b/docs/run-node/txs.md @@ -324,6 +324,21 @@ func simulateTx() error { } ``` +## Using gRPC + +It is not possible to generate or sign a transaction using gRPC, only to broadcast one. + +### Broadcasting a Transaction + +Broadcasting a transaction using the gRPC endpoint can be done by sending a `BroadcastTx` request as follows, where the `txBytes` are the protobuf-encoded bytes of a signed transaction: + +```bash +grpcurl -plaintext \ + -d '{"tx_bytes":"{{txBytes}}","mode":"BROADCAST_MODE_SYNC"}' \ + localhost:9090 \ + cosmos.tx.v1beta1.Service/BroadcastTx +``` + ## Using REST It is not possible to generate or sign a transaction using REST, only to broadcast one. @@ -334,8 +349,8 @@ Broadcasting a transaction using the REST endpoint (served by `gRPC-gateway`) ca ```bash curl -X POST \ - -H "Content-Type: application/json" - -d'{"tx_bytes":"{{txBytes}}","mode":"BROADCAST_MODE_SYNC"}' + -H "Content-Type: application/json" \ + -d'{"tx_bytes":"{{txBytes}}","mode":"BROADCAST_MODE_SYNC"}' \ localhost:1317/cosmos/tx/v1beta1/txs ```