From b480d5619e711d2200a73e6ed62951c8a3925803 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Tue, 31 May 2022 09:24:13 -0400 Subject: [PATCH] docs: updates outdated docs (#12014) (#12094) (cherry picked from commit b0756f24bb46e1ab13a31193f86dcc22c815f795) Co-authored-by: Julien Robert --- README.md | 2 +- RELEASE_PROCESS.md | 4 +- SECURITY.md | 2 +- docs/.vuepress/config.js | 6 +- docs/DOCS_README.md | 2 +- docs/README.md | 2 +- .../adr-010-modular-antehandler.md | 2 +- .../adr-019-protobuf-state-encoding.md | 2 +- .../adr-022-custom-panic-handling.md | 2 +- ...27-deterministic-protobuf-serialization.md | 2 +- .../adr-033-protobuf-inter-module-comm.md | 4 +- docs/architecture/adr-043-nft-module.md | 2 +- docs/basics/accounts.md | 20 +- docs/basics/app-anatomy.md | 43 +-- docs/basics/gas-fees.md | 8 +- docs/basics/query-lifecycle.md | 32 +-- docs/building-modules/beginblock-endblock.md | 6 +- docs/building-modules/errors.md | 16 +- docs/building-modules/genesis.md | 12 +- docs/building-modules/invariants.md | 22 +- docs/building-modules/keeper.md | 6 +- docs/building-modules/messages-and-queries.md | 24 +- docs/building-modules/module-interfaces.md | 30 +-- docs/building-modules/module-manager.md | 15 +- docs/building-modules/msg-services.md | 44 +--- docs/building-modules/query-services.md | 10 +- docs/building-modules/simulator.md | 10 +- docs/building-modules/upgrade.md | 6 +- docs/core/baseapp.md | 16 +- docs/core/cli.md | 42 +-- docs/core/context.md | 12 +- docs/core/encoding.md | 22 +- docs/core/events.md | 50 ++-- docs/core/grpc_rest.md | 21 +- docs/core/node.md | 21 +- docs/core/ocap.md | 5 +- docs/core/simulation.md | 14 +- docs/core/store.md | 58 ++-- docs/core/tips.md | 8 +- docs/core/transactions.md | 18 +- docs/core/upgrade.md | 6 +- docs/intro/sdk-design.md | 6 +- docs/ko/README.md | 2 +- docs/migrations/README.md | 6 +- docs/migrations/chain-upgrade-guide-044.md | 249 ------------------ docs/migrations/rest.md | 85 ------ docs/ru/README.md | 2 +- docs/run-node/interact-node.md | 6 +- docs/run-node/keyring.md | 2 +- docs/run-node/rosetta.md | 2 +- docs/run-node/run-node.md | 6 +- docs/run-node/txs.md | 4 +- docs/versions | 1 + docs/zh/README.md | 2 +- snapshots/README.md | 25 +- store/README.md | 2 +- store/streaming/README.md | 2 +- types/address.go | 3 +- types/address/README.md | 2 +- types/kv/list.go | 2 +- x/auth/spec/03_antehandlers.md | 2 +- x/auth/spec/05_vesting.md | 12 +- x/authz/spec/01_concepts.md | 16 +- x/authz/spec/03_messages.md | 6 +- x/authz/spec/README.md | 2 +- x/bank/migrations/v042/types.go | 2 +- x/bank/spec/03_messages.md | 5 +- x/capability/spec/README.md | 2 +- x/crisis/spec/02_messages.md | 2 +- x/distribution/spec/02_state.md | 2 +- x/distribution/spec/04_messages.md | 4 +- x/epoching/spec/03_to_improve.md | 2 +- x/evidence/spec/README.md | 2 +- x/feegrant/spec/01_concepts.md | 18 +- x/feegrant/spec/02_state.md | 2 +- x/feegrant/spec/03_messages.md | 4 +- x/feegrant/spec/README.md | 2 +- x/genutil/client/cli/validate_genesis.go | 2 +- x/gov/spec/01_concepts.md | 6 +- x/gov/spec/02_state.md | 10 +- x/gov/spec/03_messages.md | 6 +- x/group/internal/orm/spec/01_table.md | 19 +- .../internal/orm/spec/02_secondary_index.md | 8 +- .../orm/spec/03_iterator_pagination.md | 8 +- x/mint/spec/02_state.md | 4 +- x/slashing/spec/02_state.md | 2 +- x/staking/spec/01_state.md | 20 +- x/staking/spec/03_messages.md | 38 +-- x/upgrade/doc.go | 6 +- 89 files changed, 433 insertions(+), 819 deletions(-) delete mode 100644 docs/migrations/chain-upgrade-guide-044.md delete mode 100644 docs/migrations/rest.md diff --git a/README.md b/README.md index 1462fa2eee04..c00ce7ee656c 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ parent: License: Apache-2.0 - GoDoc + GoDoc Go report card diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 76b9156d47da..340664a6d350 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -127,7 +127,7 @@ To smoothen the update to the latest stable release, the SDK includes a set of C ### What does not qualify as SRU * State machine changes. -* Breaking changes in Protobuf definitions, as specified in [ADR-044](./docs/architecture/adr-044-protobuf-updates-guidelines.md). +* Breaking changes in Protobuf definitions, as specified in [ADR-044](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-044-protobuf-updates-guidelines.md). * Changes that introduces API breakages (e.g. public functions and interfaces removal/renaming). * Client-breaking changes in gRPC and HTTP request and response types. * CLI-breaking changes. @@ -149,7 +149,7 @@ Pull requests that fix bugs and add features that fall in the following categori As rule of thumb, the following changes will **NOT** be automatically accepted into stable point-releases: * **State machine changes**. -* **Protobug-breaking changes**, as specified in [ADR-044](./docs/architecture/adr-044-protobuf-updates- guidelines.md). +* **Protobug-breaking changes**, as specified in [ADR-044](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-044-protobuf-updates- guidelines.md). * **Client-breaking changes**, i.e. changes that prevent gRPC, HTTP and RPC clients to continue interacting with the node without any change. * **API-breaking changes**, i.e. changes that prevent client applications to _build without modifications_ to the client application's source code. * **CLI-breaking changes**, i.e. changes that require usage changes for CLI users. diff --git a/SECURITY.md b/SECURITY.md index c6bc9179b35f..0f6563573c85 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -13,7 +13,7 @@ this [blog post](https://blog.cosmos.network/bug-bounty-program-for-tendermint-c The following is a list of examples of the kinds of bugs we're most interested in for the Cosmos SDK. See [here](https://github.com/tendermint/tendermint/blob/master/SECURITY.md) for vulnerabilities we are interested -in for Tendermint and other lower-level libraries (eg. [IAVL](https://github.com/tendermint/iavl)). +in for Tendermint and other lower-level libraries (eg. [IAVL](https://github.com/cosmos/iavl)). ### Core packages diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b2bfc1d0602c..26454e7e7d2e 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -46,6 +46,10 @@ module.exports = { "label": "v0.45", "key": "v0.45" }, + { + "label": "v0.46", + "key": "v0.46" + }, { "label": "main", "key": "main" @@ -76,7 +80,7 @@ module.exports = { }, { title: "SDK API Reference", - path: "https://godoc.org/github.com/cosmos/cosmos-sdk" + path: "https://pkg.go.dev/github.com/cosmos/cosmos-sdk" }, { title: "REST API Spec", diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index 6439571f7820..644292b81fff 100644 --- a/docs/DOCS_README.md +++ b/docs/DOCS_README.md @@ -103,7 +103,7 @@ We are using [Algolia](https://www.algolia.com) to power full-text search. This ## Consistency Because the build processes are identical (as is the information contained herein), this file should be kept in sync as -much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/v0.34.0/docs/DOCS_README.md). +much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/master/docs/DOCS_README.md). ### Update and Build the RPC docs diff --git a/docs/README.md b/docs/README.md index 35ee1daf20c0..dad6bc92fd48 100644 --- a/docs/README.md +++ b/docs/README.md @@ -64,7 +64,7 @@ aside: false * **[Module Directory](../x/)**: Cosmos SDK module implementations and their respective documentation. * **[Specifications](./spec/)**: Specifications of modules and other parts of the Cosmos SDK. -* **[Cosmos SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK. +* **[Cosmos SDK API Reference](https://pkg.go.dev/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK. * **[REST and RPC Endpoints](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node. * **[Rosetta API](./run-node/rosetta.md)**: Rosetta API integration. diff --git a/docs/architecture/adr-010-modular-antehandler.md b/docs/architecture/adr-010-modular-antehandler.md index 1558afab8ed3..386af1a77575 100644 --- a/docs/architecture/adr-010-modular-antehandler.md +++ b/docs/architecture/adr-010-modular-antehandler.md @@ -19,7 +19,7 @@ For example, let's say a user wants to implement some custom signature verificat ### Per-Module AnteHandler -One approach is to use the [ModuleManager](https://godoc.org/github.com/cosmos/cosmos-sdk/types/module) and have each module implement its own antehandler if it requires custom antehandler logic. The ModuleManager can then be passed in an AnteHandler order in the same way it has an order for BeginBlockers and EndBlockers. The ModuleManager returns a single AnteHandler function that will take in a tx and run each module's `AnteHandle` in the specified order. The module manager's AnteHandler is set as the baseapp's AnteHandler. +One approach is to use the [ModuleManager](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/types/module) and have each module implement its own antehandler if it requires custom antehandler logic. The ModuleManager can then be passed in an AnteHandler order in the same way it has an order for BeginBlockers and EndBlockers. The ModuleManager returns a single AnteHandler function that will take in a tx and run each module's `AnteHandle` in the specified order. The module manager's AnteHandler is set as the baseapp's AnteHandler. Pros: diff --git a/docs/architecture/adr-019-protobuf-state-encoding.md b/docs/architecture/adr-019-protobuf-state-encoding.md index f3b6148764cb..1d20145ae7a1 100644 --- a/docs/architecture/adr-019-protobuf-state-encoding.md +++ b/docs/architecture/adr-019-protobuf-state-encoding.md @@ -149,7 +149,7 @@ and client developer UX. ### Safe usage of `Any` -By default, the [gogo protobuf implementation of `Any`](https://godoc.org/github.com/gogo/protobuf/types) +By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/gogo/protobuf/types) uses [global type registration]( https://github.com/gogo/protobuf/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete go types. This introduces a vulnerability where any malicious module diff --git a/docs/architecture/adr-022-custom-panic-handling.md b/docs/architecture/adr-022-custom-panic-handling.md index 645b9eb4fe5c..6ed7b6246ae4 100644 --- a/docs/architecture/adr-022-custom-panic-handling.md +++ b/docs/architecture/adr-022-custom-panic-handling.md @@ -215,4 +215,4 @@ This method would prepend handlers to an existing chain. ## References * [PR-6053 with proposed solution](https://github.com/cosmos/cosmos-sdk/pull/6053) -* [Similar solution. ADR-010 Modular AnteHandler](https://github.com/cosmos/cosmos-sdk/blob/v0.38.3/docs/architecture/adr-010-modular-antehandler.md) +* [Similar solution. ADR-010 Modular AnteHandler](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-010-modular-antehandler.md) diff --git a/docs/architecture/adr-027-deterministic-protobuf-serialization.md b/docs/architecture/adr-027-deterministic-protobuf-serialization.md index e75b142001c5..a4602c2641d6 100644 --- a/docs/architecture/adr-027-deterministic-protobuf-serialization.md +++ b/docs/architecture/adr-027-deterministic-protobuf-serialization.md @@ -31,7 +31,7 @@ the same serialization of a `SignDoc` as defined in serialization. Currently, for block signatures we are using a workaround: we create a new [TxRaw](https://github.com/cosmos/cosmos-sdk/blob/9e85e81e0e8140067dd893421290c191529c148c/proto/cosmos/tx/v1beta1/tx.proto#L30) -instance (as defined in [adr-020-protobuf-transaction-encoding](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-020-protobuf-transaction-encoding.md#transactions)) +instance (as defined in [adr-020-protobuf-transaction-encoding](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-020-protobuf-transaction-encoding.md#transactions)) by converting all [Tx](https://github.com/cosmos/cosmos-sdk/blob/9e85e81e0e8140067dd893421290c191529c148c/proto/cosmos/tx/v1beta1/tx.proto#L13) fields to bytes on the client side. This adds an additional manual step when sending and signing transactions. diff --git a/docs/architecture/adr-033-protobuf-inter-module-comm.md b/docs/architecture/adr-033-protobuf-inter-module-comm.md index f6bb881b9bd5..09b650a61e7c 100644 --- a/docs/architecture/adr-033-protobuf-inter-module-comm.md +++ b/docs/architecture/adr-033-protobuf-inter-module-comm.md @@ -165,7 +165,7 @@ corresponding "public key". From the [ADR 028](./adr-028-public-key-addresses.md or derived accounts that can be used for different pools (ex. staking pools) or managed accounts (ex. group accounts). We can also think of module sub-accounts as similar to derived keys - there is a root key and then some derivation path. `ModuleID` is a simple struct which contains the module name and optional "derivation" path, -and forms its address based on the `AddressHash` method from [the ADR-028](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-028-public-key-addresses.md): +and forms its address based on the `AddressHash` method from [the ADR-028](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-028-public-key-addresses.md): ```go type ModuleID struct { @@ -330,7 +330,7 @@ ADR. ### Authorization By default, the inter-module router requires that messages are sent by the first signer returned by `GetSigners`. The -inter-module router should also accept authorization middleware such as that provided by [ADR 030](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-030-authz-module.md). +inter-module router should also accept authorization middleware such as that provided by [ADR 030](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-030-authz-module.md). This middleware will allow accounts to otherwise specific module accounts to perform actions on their behalf. Authorization middleware should take into account the need to grant certain modules effectively "admin" privileges to other modules. This will be addressed in separate ADRs or updates to this ADR. diff --git a/docs/architecture/adr-043-nft-module.md b/docs/architecture/adr-043-nft-module.md index 2779ff2deb8e..7d4498bf843c 100644 --- a/docs/architecture/adr-043-nft-module.md +++ b/docs/architecture/adr-043-nft-module.md @@ -337,4 +337,4 @@ Other networks in the Cosmos ecosystem could design and implement their own NFT * Initial discussion: https://github.com/cosmos/cosmos-sdk/discussions/9065 * x/nft: initialize module: https://github.com/cosmos/cosmos-sdk/pull/9174 -* [ADR 033](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-033-protobuf-inter-module-comm.md) +* [ADR 033](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-033-protobuf-inter-module-comm.md) diff --git a/docs/basics/accounts.md b/docs/basics/accounts.md index da3251dc4e59..dde895cce219 100644 --- a/docs/basics/accounts.md +++ b/docs/basics/accounts.md @@ -66,9 +66,9 @@ In the node, all data is stored using Protocol Buffers serialization. The Cosmos SDK supports the following digital key schemes for creating digital signatures: -* `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/secp256k1/secp256k1.go). -* `secp256r1`, as implemented in the [Cosmos 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 [Cosmos 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. +* `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keys/secp256k1/secp256k1.go). +* `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keys/secp256r1/pubkey.go), +* `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation. | | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) | | :----------: | :---------------------: | :------------------------: | :---------------------------------: | :-----------------------------: | @@ -88,9 +88,9 @@ Each account is identified using `Address` which is a sequence of bytes derived These types implement the `Address` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L71-L90 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/address.go#L108-L125 -Address construction algorithm is defined in [ADR-28](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-028-public-key-addresses.md). +Address construction algorithm is defined in [ADR-28](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-028-public-key-addresses.md). Here is the standard way to obtain an account address from a `pub` public key: ```go @@ -101,7 +101,7 @@ Of note, the `Marshal()` and `Bytes()` method both return the same raw `[]byte` For user interaction, addresses are formatted using [Bech32](https://en.bitcoin.it/wiki/Bech32) and implemented by the `String` method. The Bech32 method is the only supported format to use when interacting with a blockchain. The Bech32 human-readable part (Bech32 prefix) is used to denote an address type. Example: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L230-L244 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/address.go#L272-L286 | | Address Bech32 Prefix | | ------------------ | --------------------- | @@ -113,7 +113,7 @@ For user interaction, addresses are formatted using [Bech32](https://en.bitcoin. Public keys in Cosmos SDK are defined by `cryptotypes.PubKey` interface. Since public keys are saved in a store, `cryptotypes.PubKey` extends the `proto.Message` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/types/types.go#L8-L17 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/types/types.go#L8-L17 A compressed format is used for `secp256k1` and `secp256r1` serialization. @@ -123,15 +123,15 @@ A compressed format is used for `secp256k1` and `secp256r1` serialization. This prefix is followed by the `x`-coordinate. Public Keys are not used to reference accounts (or users) and in general are not used when composing transaction messages (with few exceptions: `MsgCreateValidator`, `Validator` and `Multisig` messages). -For user interactions, `PubKey` is formatted using Protobufs JSON ([ProtoMarshalJSON](https://github.com/cosmos/cosmos-sdk/blob/release/v0.42.x/codec/json.go#L12) function). Example: +For user interactions, `PubKey` is formatted using Protobufs JSON ([ProtoMarshalJSON](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/codec/json.go#L14-L34) function). Example: -+++ https://github.com/cosmos/cosmos-sdk/blob/7568b66/crypto/keyring/output.go#L23-L39 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keyring/output.go#L23-L39 ## Keyring A `Keyring` is an object that stores and manages accounts. In the Cosmos SDK, a `Keyring` implementation follows the `Keyring` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keyring/keyring.go#L53-L101 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keyring/keyring.go#L54-L101 The default implementation of `Keyring` comes from the third-party [`99designs/keyring`](https://github.com/99designs/keyring) library. diff --git a/docs/basics/app-anatomy.md b/docs/basics/app-anatomy.md index f589ee76c7ea..91a01b8ad23d 100644 --- a/docs/basics/app-anatomy.md +++ b/docs/basics/app-anatomy.md @@ -85,17 +85,17 @@ See an example of application constructor from `simapp`: ### InitChainer -The `InitChainer` is a function that initializes the state of the application from a genesis file (i.e. token balances of genesis accounts). It is called when the application receives the `InitChain` message from the Tendermint engine, which happens when the node is started at `appBlockHeight == 0` (i.e. on genesis). The application must set the `InitChainer` in its [constructor](#constructor-function) via the [`SetInitChainer`](https://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetInitChainer) method. +The `InitChainer` is a function that initializes the state of the application from a genesis file (i.e. token balances of genesis accounts). It is called when the application receives the `InitChain` message from the Tendermint engine, which happens when the node is started at `appBlockHeight == 0` (i.e. on genesis). The application must set the `InitChainer` in its [constructor](#constructor-function) via the [`SetInitChainer`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetInitChainer) method. In general, the `InitChainer` is mostly composed of the [`InitGenesis`](../building-modules/genesis.md#initgenesis) function of each of the application's modules. This is done by calling the `InitGenesis` function of the module manager, which in turn will call the `InitGenesis` function of each of the modules it contains. Note that the order in which the modules' `InitGenesis` functions must be called has to be set in the module manager using the [module manager's](../building-modules/module-manager.md) `SetOrderInitGenesis` method. This is done in the [application's constructor](#application-constructor), and the `SetOrderInitGenesis` has to be called before the `SetInitChainer`. See an example of an `InitChainer` from `simapp`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L464-L471 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/app.go#L524-L532 ### BeginBlocker and EndBlocker -The Cosmos SDK offers developers the possibility to implement automatic execution of code as part of their application. This is implemented through two function called `BeginBlocker` and `EndBlocker`. They are called when the application receives respectively the `BeginBlock` and `EndBlock` messages from the Tendermint engine, which happens at the beginning and at the end of each block. The application must set the `BeginBlocker` and `EndBlocker` in its [constructor](#constructor-function) via the [`SetBeginBlocker`](https://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetBeginBlocker) and [`SetEndBlocker`](https://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetEndBlocker) methods. +The Cosmos SDK offers developers the possibility to implement automatic execution of code as part of their application. This is implemented through two function called `BeginBlocker` and `EndBlocker`. They are called when the application receives respectively the `BeginBlock` and `EndBlock` messages from the Tendermint engine, which happens at the beginning and at the end of each block. The application must set the `BeginBlocker` and `EndBlocker` in its [constructor](#constructor-function) via the [`SetBeginBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetBeginBlocker) and [`SetEndBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetEndBlocker) methods. In general, the `BeginBlocker` and `EndBlocker` functions are mostly composed of the [`BeginBlock` and `EndBlock`](../building-modules/beginblock-endblock.md) functions of each of the application's modules. This is done by calling the `BeginBlock` and `EndBlock` functions of the module manager, which in turn will call the `BeginBlock` and `EndBlock` functions of each of the modules it contains. Note that the order in which the modules' `BeginBlock` and `EndBlock` functions must be called has to be set in the module manager using the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods respectively. This is done via the [module manager](../building-modules/module-manager.md) in the [application's constructor](#application-constructor), and the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods have to be called before the `SetBeginBlocker` and `SetEndBlocker` functions. @@ -103,37 +103,38 @@ As a sidenote, it is important to remember that application-specific blockchains See an example of `BeginBlocker` and `EndBlocker` functions from `simapp` -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L454-L462 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/app.go#L514-L522 ### Register Codec The `EncodingConfig` structure is the last important part of the `app.go` file. The goal of this structure is to define the codecs that will be used throughout the app. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/params/encoding.go#L9-L16 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/params/encoding.go#L9-L16 Here are descriptions of what each of the four fields means: * `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces that are encoded and decoded (we also say "unpacked") using [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto). `Any` could be thought as a struct that contains a `type_url` (name of a concrete type implementing the interface) and a `value` (its encoded bytes). `InterfaceRegistry` provides a mechanism for registering interfaces and implementations that can be safely unpacked from `Any`. Each of the application's modules implements the `RegisterInterfaces` method that can be used to register the module's own interfaces and implementations. * You can read more about Any in [ADR-19](../architecture/adr-019-protobuf-state-encoding.md#usage-of-any-to-encode-interfaces). - * To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/gogo/protobuf). By default, the [gogo protobuf implementation of `Any`](https://godoc.org/github.com/gogo/protobuf/types) uses [global type registration](https://github.com/gogo/protobuf/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could register a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../architecture/adr-019-protobuf-state-encoding.md). -* `Marshaler`: the default codec used throughout the Cosmos SDK. It is composed of a `BinaryCodec` used to encode and decode state, and a `JSONCodec` used to output data to the users (for example in the [CLI](#cli)). By default, the SDK uses Protobuf as `Marshaler`. + * To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/gogo/protobuf). By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/gogo/protobuf/types) uses [global type registration](https://github.com/gogo/protobuf/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could register a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../architecture/adr-019-protobuf-state-encoding.md). +* `Codec`: the default codec used throughout the Cosmos SDK. It is composed of a `BinaryCodec` used to encode and decode state, and a `JSONCodec` used to output data to the users (for example in the [CLI](#cli)). By default, the SDK uses Protobuf as `Codec`. * `TxConfig`: `TxConfig` defines an interface a client can utilize to generate an application-defined concrete transaction type. Currently, the SDK handles two transaction types: `SIGN_MODE_DIRECT` (which uses Protobuf binary as over-the-wire encoding) and `SIGN_MODE_LEGACY_AMINO_JSON` (which depends on Amino). Read more about transactions [here](../core/transactions.md). * `Amino`: Some legacy parts of the Cosmos SDK still use Amino for backwards-compatibility. Each module exposes a `RegisterLegacyAmino` method to register the module's specific types within Amino. This `Amino` codec should not be used by app developers anymore, and will be removed in future releases. -The Cosmos SDK exposes a `MakeTestEncodingConfig` function used to create a `EncodingConfig` for the app constructor (`NewApp`). It uses Protobuf as a default `Marshaler`. -NOTE: this function is marked deprecated and should only be used to create an app or in tests. We are working on refactoring codec management in a post Stargate release. +The Cosmos SDK exposes a `MakeTestEncodingConfig` function used to create a `EncodingConfig` for the app constructor (`NewApp`). It uses Protobuf as a default `Codec`. + +NOTE: This function is deprecated and should only be used to create an app or in tests. See an example of a `MakeTestEncodingConfig` from `simapp`: -+++ https://github.com/cosmos/cosmos-sdk/blob/590358652cc1cbc13872ea1659187e073ea38e75/simapp/encoding.go#L8-L19 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/encoding.go#L8-L19 ## Modules -[Modules](../building-modules/intro.md) are the heart and soul of Cosmos SDK applications. They can be considered as state-machines nested within the state-machine. When a transaction is relayed from the underlying Tendermint engine via the ABCI to the application, it is routed by [`baseapp`](../core/baseapp.md) to the appropriate module in order to be processed. This paradigm enables developers to easily build complex state-machines, as most of the modules they need often already exist. For developers, most of the work involved in building a Cosmos SDK application revolves around building custom modules required by their application that do not exist yet, and integrating them with modules that do already exist into one coherent application. In the application directory, the standard practice is to store modules in the `x/` folder (not to be confused with the Cosmos SDK's `x/` folder, which contains already-built modules). +[Modules](../building-modules/intro.md) are the heart and soul of Cosmos SDK applications. They can be considered as state-machines nested within the state-machine. When a transaction is relayed from the underlying Tendermint engine via the ABCI to the application, it is routed by [`baseapp`](../core/baseapp.md) to the appropriate module in order to be processed. This paradigm enables developers to easily build complex state-machines, as most of the modules they need often already exist. **For developers, most of the work involved in building a Cosmos SDK application revolves around building custom modules required by their application that do not exist yet, and integrating them with modules that do already exist into one coherent application**. In the application directory, the standard practice is to store modules in the `x/` folder (not to be confused with the Cosmos SDK's `x/` folder, which contains already-built modules). ### Application Module Interface -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-dependent 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`. +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-dependent 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, by convention, 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 called from the [`module manager`](../building-modules/module-manager.md#manager), which manages the application's collection of modules. @@ -154,7 +155,7 @@ For a more details look at a transaction [lifecycle](./tx-lifecycle.md). Module developers create custom `Msg` services when they build their own module. The general practice is to define the `Msg` Protobuf service in a `tx.proto` file. For example, the `x/bank` module defines a service with two methods to transfer tokens: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/bank/v1beta1/tx.proto#L10-L17 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L12-L19 Service methods use `keeper` in order to update the module state. @@ -162,7 +163,7 @@ Each module should also implement the `RegisterServices` method as part of the [ ### gRPC `Query` Services -gRPC `Query` services are introduced in the v0.40 Stargate release. They allow users to query the state using [gRPC](https://grpc.io). They are enabled by default, and can be configured under the `grpc.enable` and `grpc.address` fields inside [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml). +gRPC `Query` services allows users to query the state using [gRPC](https://grpc.io). They are enabled by default, and can be configured under the `grpc.enable` and `grpc.address` fields inside [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml). gRPC `Query` services are defined in the module's Protobuf definition files, specifically inside `query.proto`. The `query.proto` definition file exposes a single `Query` [Protobuf service](https://developers.google.com/protocol-buffers/docs/proto#services). Each gRPC query endpoint corresponds to a service method, starting with the `rpc` keyword, inside the `Query` service. @@ -222,9 +223,9 @@ The main interface is the [Command-Line Interface](../core/cli.md). The CLI of a * **Query commands** are added by calling the `queryCmd` function. This function returns a Cobra command that contains the query commands defined in each of the application's modules (passed as an array of `sdk.ModuleClients` from the `main()` function), as well as some other lower level query commands such as block or validator queries. Query command are called by using the command `appd query [query]` of the CLI. * **Transaction commands** are added by calling the `txCmd` function. Similar to `queryCmd`, the function returns a Cobra command that contains the tx commands defined in each of the application's modules, as well as lower level tx commands like transaction signing or broadcasting. Tx commands are called by using the command `appd tx [tx]` of the CLI. -See an example of an application's main command-line file from the [nameservice tutorial](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice) +See an example of an application's main command-line file from the [Cosmos Hub](https://github.com/cosmos/gaia) -+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/cmd/nscli/main.go ++++ https://github.com/cosmos/gaia/blob/Theta-main/cmd/gaiad/cmd/root.go#L39-L77 ## Dependencies and Makefile @@ -240,13 +241,15 @@ replace google.golang.org/grpc => google.golang.org/grpc v1.33.2 Please see [issue #8392](https://github.com/cosmos/cosmos-sdk/issues/8392) for more info. ::: -This section is optional, as developers are free to choose their dependency manager and project building method. That said, the current most used framework for versioning control is [`go.mod`](https://github.com/golang/go/wiki/Modules). It ensures each of the libraries used throughout the application are imported with the correct version. See an example from the [nameservice tutorial](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice): +This section is optional, as developers are free to choose their dependency manager and project building method. That said, the current most used framework for versioning control is [`go.mod`](https://github.com/golang/go/wiki/Modules). It ensures each of the libraries used throughout the application are imported with the correct version. + +Below, the `go.mod` of the [Cosmos Hub](https://github.com/cosmos/gaia) is provided as an example. -+++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/go.mod#L1-L18 ++++ https://github.com/cosmos/gaia/blob/Theta-main/go.mod#L1-L20 -For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`appd`](#node-client) and [`appd`](#application-interface). See an example of Makefile from the [nameservice tutorial](https://tutorials.cosmos.network/nameservice/tutorial/00-intro.html) +For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`appd`](#node-client) and [`appd`](#application-interface). -+++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/Makefile +Here is an example of the [Cosmos Hub Makefile](https://github.com/cosmos/gaia/blob/Theta-main/Makefile). ## Next {hide} diff --git a/docs/basics/gas-fees.md b/docs/basics/gas-fees.md index 4b011be614bf..b49bc8a97a98 100644 --- a/docs/basics/gas-fees.md +++ b/docs/basics/gas-fees.md @@ -21,14 +21,16 @@ In the Cosmos SDK, `gas` is a special unit that is used to track the consumption In the Cosmos SDK, `gas` is a simple alias for `uint64`, and is managed by an object called a _gas meter_. Gas meters implement the `GasMeter` interface -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L34-L43 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/gas.go#L40-L51 where: * `GasConsumed()` returns the amount of gas that was consumed by the gas meter instance. * `GasConsumedToLimit()` returns the amount of gas that was consumed by gas meter instance, or the limit if it is reached. +* `GasRemaining()` returns the gas left in the GasMeter. * `Limit()` returns the limit of the gas meter instance. `0` if the gas meter is infinite. * `ConsumeGas(amount Gas, descriptor string)` consumes the amount of `gas` provided. If the `gas` overflows, it panics with the `descriptor` message. If the gas meter is not infinite, it panics if `gas` consumed goes above the limit. +* `RefundGas()` deducts the given amount from the gas consumed. This functionality enables refunding gas to the transaction or block gas pools so that EVM-compatible chains can fully support the go-ethereum StateDB interface. * `IsPastLimit()` returns `true` if the amount of gas consumed by the gas meter instance is strictly above the limit, `false` otherwise. * `IsOutOfGas()` returns `true` if the amount of gas consumed by the gas meter instance is above or equal to the limit, `false` otherwise. @@ -38,7 +40,7 @@ The gas meter is generally held in [`ctx`](../core/context.md), and consuming ga ctx.GasMeter().ConsumeGas(amount, "description") ``` -By default, the Cosmos SDK makes use of two different gas meters, the [main gas meter](#main-gas-metter[) and the [block gas meter](#block-gas-meter). +By default, the Cosmos SDK makes use of two different gas meters, the [main gas meter](#main-gas-metter) and the [block gas meter](#block-gas-meter). ### Main Gas Meter @@ -50,7 +52,7 @@ Gas consumption can be done manually, generally by the module developer in the [ `ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`BeginBlock`](../core/baseapp.md#beginblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. By default, Cosmos SDK applications use the default consensus parameters provided by Tendermint: -+++ https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/types/params.go#L34-L41 ++++ https://github.com/tendermint/tendermint/blob/v0.35.4/types/params.go#L78-L117 When a new [transaction](../core/transactions.md) is being processed via `DeliverTx`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, `DeliverTx` returns immediately. This can happen even with the first transaction in a block, as `BeginBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `DeliverTx`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction: diff --git a/docs/basics/query-lifecycle.md b/docs/basics/query-lifecycle.md index 1e0221caa7b5..80b492f57542 100644 --- a/docs/basics/query-lifecycle.md +++ b/docs/basics/query-lifecycle.md @@ -36,21 +36,7 @@ To provide values such as `--node` (the full-node the CLI connects to), the user The CLI understands a specific set of commands, defined in a hierarchical structure by the application developer: from the [root command](../core/cli.md#root-command) (`simd`), the type of command (`Myquery`), the module that contains the command (`staking`), and command itself (`delegations`). Thus, the CLI knows exactly which module handles this command and directly passes the call there. -### gRPC - -::: warning -A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the Cosmos SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`. - -To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`: - -```go -replace google.golang.org/grpc => google.golang.org/grpc v1.33.2 -``` - -Please see [issue #8392](https://github.com/cosmos/cosmos-sdk/issues/8392) for more info. -::: - -Another interface through which users can make queries, introduced in Cosmos SDK v0.40, is [gRPC](https://grpc.io) requests to a [gRPC server](../core/grpc_rest.md#grpc-server). The endpoints are defined as [Protocol Buffers](https://developers.google.com/protocol-buffers) service methods inside `.proto` files, written in Protobuf's own language-agnostic interface definition language (IDL). The Protobuf ecosystem developed tools for code-generation from `*.proto` files into various languages. These tools allow to build gRPC clients easily. +Another interface through which users can make queries is [gRPC](https://grpc.io) requests to a [gRPC server](../core/grpc_rest.md#grpc-server). The endpoints are defined as [Protocol Buffers](https://developers.google.com/protocol-buffers) service methods inside `.proto` files, written in Protobuf's own language-agnostic interface definition language (IDL). The Protobuf ecosystem developed tools for code-generation from `*.proto` files into various languages. These tools allow to build gRPC clients easily. One such tool is [grpcurl](https://github.com/fullstorydev/grpcurl), and a gRPC request for `MyQuery` using this client looks like: @@ -83,15 +69,15 @@ The examples above show how an external user can interact with a node by queryin The first thing that is created in the execution of a CLI command is a `client.Context`. A `client.Context` is an object that stores all the data needed to process a request on the user side. In particular, a `client.Context` stores the following: * **Codec**: The [encoder/decoder](../core/encoding.md) used by the application, used to marshal the parameters and query before making the Tendermint RPC request and unmarshal the returned response into a JSON object. The default codec used by the CLI is Protobuf. -* **Account Decoder**: The account decoder from the [`auth`](../..//x/auth/spec/README.md) module, which translates `[]byte`s into accounts. +* **Account Decoder**: The account decoder from the [`auth`](../../x/auth/spec/README.md) module, which translates `[]byte`s into accounts. * **RPC Client**: The Tendermint RPC Client, or node, to which the request will be relayed to. * **Keyring**: A [Key Manager](../basics/accounts.md#keyring) used to sign transactions and handle other operations with keys. -* **Output Writer**: A [Writer](https://golang.org/pkg/io/#Writer) used to output the response. +* **Output Writer**: A [Writer](https://pkg.go.dev/io/#Writer) used to output the response. * **Configurations**: The flags configured by the user for this command, including `--height`, specifying the height of the blockchain to query and `--indent`, which indicates to add an indent to the JSON response. The `client.Context` also contains various functions such as `Query()` which retrieves the RPC Client and makes an ABCI call to relay a query to a full-node. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L20-L50 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/context.go#L25-L63 The `client.Context`'s primary role is to store data used during interactions with the end-user and provide methods to interact with this data - it is used before and after the query is processed by the full-node. Specifically, in handling `MyQuery`, the `client.Context` is utilized to encode the query parameters, retrieve the full-node, and write the output. Prior to being relayed to a full-node, the query needs to be encoded into a `[]byte` form, as full-nodes are application-agnostic and do not understand specific types. The full-node (RPC Client) itself is retrieved using the `client.Context`, which knows which node the user CLI is connected to. The query is relayed to this full-node to be processed. Finally, the `client.Context` contains a `Writer` to write output when the response is returned. These steps are further described in later sections. @@ -105,25 +91,25 @@ In our case (querying an address's delegations), `MyQuery` contains an [address] Here is what the code looks like for the CLI command: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L324-L327 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/client/cli/query.go#L323-L326 #### gRPC Query Client Creation The Cosmos SDK leverages code generated from Protobuf services to make queries. The `staking` module's `MyQuery` service generates a `queryClient`, which the CLI will use to make queries. Here is the relevant code: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L318-L342 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/client/cli/query.go#L317-L341 Under the hood, the `client.Context` has a `Query()` function used to retrieve the pre-configured node and relay a query to it; the function takes the query fully-qualified service method name as path (in our case: `/cosmos.staking.v1beta1.Query/Delegations`), and arguments as parameters. It first retrieves the RPC Client (called the [**node**](../core/node.md)) configured by the user to relay this query to, and creates the `ABCIQueryOptions` (parameters formatted for the ABCI call). The node is then used to make the ABCI call, `ABCIQueryWithOptions()`. Here is what the code looks like: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/query.go#L65-L91 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/query.go#L80-L114 ## RPC With a call to `ABCIQueryWithOptions()`, `MyQuery` is received by a [full-node](../core/encoding.md) which will then process the request. Note that, while the RPC is made to the consensus engine (e.g. Tendermint Core) of a full-node, queries are not part of consensus and will not be broadcasted to the rest of the network, as they do not require anything the network needs to agree upon. -Read more about ABCI Clients and Tendermint RPC in the Tendermint documentation [here](https://docs.tendermint.com/master/rpc/). +Read more about ABCI Clients and Tendermint RPC in the [Tendermint documentation](https://docs.tendermint.com/master/rpc/). ## Application Query Handling @@ -143,7 +129,7 @@ Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci The application [`codec`](../core/encoding.md) is used to unmarshal the response to a JSON and the `client.Context` prints the output to the command line, applying any configurations such as the output type (text, JSON or YAML). -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L248-L283 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/context.go#L315-L343 And that's a wrap! The result of the query is outputted to the console by the CLI. diff --git a/docs/building-modules/beginblock-endblock.md b/docs/building-modules/beginblock-endblock.md index 2eff43ba0ee1..e324018fc2ab 100644 --- a/docs/building-modules/beginblock-endblock.md +++ b/docs/building-modules/beginblock-endblock.md @@ -26,13 +26,13 @@ A specificity of the `EndBlocker` is that it can return validator updates to the It is possible for developers to define the order of execution between the `BeginBlocker`/`EndBlocker` functions of each of their application's modules via the module's manager `SetOrderBeginBlocker`/`SetOrderEndBlocker` methods. For more on the module manager, click [here](./module-manager.md#manager). -See an example implementation of `BeginBlocker` from the `distr` module: +See an example implementation of `BeginBlocker` from the `distribution` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/distribution/abci.go#L14-L38 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/distribution/abci.go#L14-L38 and an example implementation of `EndBlocker` from the `staking` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/staking/abci.go#L22-L27 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/abci.go#L22-L27 ## Next {hide} diff --git a/docs/building-modules/errors.md b/docs/building-modules/errors.md index 0a7990b7686c..9e7b970fc43b 100644 --- a/docs/building-modules/errors.md +++ b/docs/building-modules/errors.md @@ -13,12 +13,12 @@ execution context. ## Registration -Modules should define and register their custom errors in `x/{module}/errors.go`. Registration -of errors is handled via the `types/errors` package. +Modules should define and register their custom errors in `x/{module}/errors.go`. +Registration of errors is handled via the [`errors` package](https://github.com/cosmos/cosmos-sdk/blob/main/errors/errors.go). Example: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0/x/distribution/types/errors.go#L1-L21 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/distribution/types/errors.go#L1-L21 Each custom module error must provide the codespace, which is typically the module name (e.g. "distribution") and is unique per module, and a uint32 code. Together, the codespace and code @@ -28,7 +28,7 @@ necessarily have to be. The only restrictions on error codes are the following: * Must be greater than one, as a code value of one is reserved for internal errors. * Must be unique within the module. -Note, the Cosmos SDK provides a core set of *common* errors. These errors are defined in `types/errors/errors.go`. +Note, the Cosmos SDK provides a core set of *common* errors. These errors are defined in [`types/errors/errors.go`](https://github.com/cosmos/cosmos-sdk/blob/main/types/errors/errors.go). ## Wrapping @@ -38,13 +38,13 @@ execution. Example: -+++ https://github.com/cosmos/cosmos-sdk/blob/b2d48a9e815fe534a7faeec6ca2adb0874252b81/x/bank/keeper/keeper.go#L85-L122 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/keeper/keeper.go#L143-L184 -Regardless if an error is wrapped or not, the Cosmos SDK's `errors` package provides an API to determine if +Regardless if an error is wrapped or not, the Cosmos SDK's `errors` package provides a function to determine if an error is of a particular kind via `Is`. ## ABCI If a module error is registered, the Cosmos SDK `errors` package allows ABCI information to be extracted -through the `ABCIInfo` API. The package also provides `ResponseCheckTx` and `ResponseDeliverTx` as -auxiliary APIs to automatically get `CheckTx` and `DeliverTx` responses from an error. +through the `ABCIInfo` function. The package also provides `ResponseCheckTx` and `ResponseDeliverTx` as +auxiliary functions to automatically get `CheckTx` and `DeliverTx` responses from an error. diff --git a/docs/building-modules/genesis.md b/docs/building-modules/genesis.md index f06115cc389e..9e9c57738544 100644 --- a/docs/building-modules/genesis.md +++ b/docs/building-modules/genesis.md @@ -17,7 +17,7 @@ The subset of the genesis state defined from a given module is generally defined See an example of `GenesisState` protobuf message definition from the `auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/a9547b54ffac9729fe1393651126ddfc0d236cff/proto/cosmos/auth/v1beta1/genesis.proto ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/auth/v1beta1/genesis.proto Next we present the main genesis-related methods that need to be implemented by module developers in order for their module to be used in Cosmos SDK applications. @@ -25,13 +25,13 @@ Next we present the main genesis-related methods that need to be implemented by The `DefaultGenesis()` method is a simple method that calls the constructor function for `GenesisState` with the default value for each parameter. See an example from the `auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/module.go#L48-L52 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/module.go#L45-L49 ### `ValidateGenesis` -The `ValidateGenesis(genesisState GenesisState)` method is called to verify that the provided `genesisState` is correct. It should perform validity checks on each of the parameters listed in `GenesisState`. See an example from the `auth` module: +The `ValidateGenesis(data GenesisState)` method is called to verify that the provided `genesisState` is correct. It should perform validity checks on each of the parameters listed in `GenesisState`. See an example from the `auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/types/genesis.go#L57-L70 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/types/genesis.go#L61-L74 ## Other Genesis Methods @@ -45,7 +45,7 @@ The [module manager](./module-manager.md#manager) of the application is responsi See an example of `InitGenesis` from the `auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L13-L28 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/keeper/genesis.go#L8-L27 ### `ExportGenesis` @@ -53,7 +53,7 @@ The `ExportGenesis` method is executed whenever an export of the state is made. See an example of `ExportGenesis` from the `auth` module. -+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L31-L42 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/keeper/genesis.go#L29-L41 ## Next {hide} diff --git a/docs/building-modules/invariants.md b/docs/building-modules/invariants.md index 3614bbc0a4df..0cbb0adac05d 100644 --- a/docs/building-modules/invariants.md +++ b/docs/building-modules/invariants.md @@ -14,11 +14,11 @@ An invariant is a property of the application that should always be true. In the An `Invariant` is a function that checks for a particular invariant within a module. Module `Invariant`s must follow the `Invariant` type: -+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L9 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/invariant.go#L9 The `string` return value is the invariant message, which can be used when printing logs, and the `bool` return value is the actual result of the invariant check. -In practice, each module implements `Invariant`s in a `./keeper/invariants.go` file within the module's folder. The standard is to implement one `Invariant` function per logical grouping of invariants with the following model: +In practice, each module implements `Invariant`s in a `keeper/invariants.go` file within the module's folder. The standard is to implement one `Invariant` function per logical grouping of invariants with the following model: ```go // Example for an Invariant that checks balance-related invariants @@ -51,17 +51,9 @@ func AllInvariants(k Keeper) sdk.Invariant { Finally, module developers need to implement the `RegisterInvariants` method as part of the [`AppModule` interface](./module-manager.md#appmodule). Indeed, the `RegisterInvariants` method of the module, implemented in the `module/module.go` file, typically only defers the call to a `RegisterInvariants` method implemented in the `keeper/invariants.go` file. The `RegisterInvariants` method registers a route for each `Invariant` function in the [`InvariantRegistry`](#invariant-registry): -```go -// RegisterInvariants registers all staking invariants -func RegisterInvariants(ir sdk.InvariantRegistry, k Keeper) { - ir.RegisterRoute(types.ModuleName, "module-accounts", - BalanceInvariants(k)) - ir.RegisterRoute(types.ModuleName, "nonnegative-power", - DepositsInvariant(k)) -} -``` ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/keeper/invariants.go#L12-L21 -For more, see an example of [`Invariant`s implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/staking/keeper/invariants.go). +For more, see an example of [`Invariant`s implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/keeper/invariants.go). ## Invariant Registry @@ -69,17 +61,17 @@ The `InvariantRegistry` is a registry where the `Invariant`s of all the modules At its core, the `InvariantRegistry` is defined in the Cosmos SDK as an interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L14-L17 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/invariant.go#L14-L17 Typically, this interface is implemented in the `keeper` of a specific module. The most used implementation of an `InvariantRegistry` can be found in the `crisis` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/crisis/keeper/keeper.go#L50-L54 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/crisis/keeper/keeper.go#L49-L53 The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../basics/app-anatomy.md#constructor-function). `Invariant`s can be checked manually via [`message`s](./messages-and-queries.md), but most often they are checked automatically at the end of each block. Here is an example from the `crisis` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/crisis/abci.go#L7-L14 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/crisis/abci.go#L12-L21 In both cases, if one of the `Invariant`s returns false, the `InvariantRegistry` can trigger special logic (e.g. have the application panic and print the `Invariant`s message in the log). diff --git a/docs/building-modules/keeper.md b/docs/building-modules/keeper.md index d00bf76b5d63..78712a91b3d7 100644 --- a/docs/building-modules/keeper.md +++ b/docs/building-modules/keeper.md @@ -34,7 +34,7 @@ type Keeper struct { For example, here is the type definition of the `keeper` from the `staking` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/3bafd8255a502e5a9cee07391cf8261538245dfd/x/staking/keeper/keeper.go#L23-L33 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/keeper/keeper.go#L21-L29 Let us go through the different parameters: @@ -72,13 +72,13 @@ and the method will go through the following steps: 2. Marshal `value` to `[]byte` using the codec `cdc`. 3. Set the encoded value in the store at location `key` using the `Set(key []byte, value []byte)` method of the store. -For more, see an example of `keeper`'s [methods implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/3bafd8255a502e5a9cee07391cf8261538245dfd/x/staking/keeper/keeper.go). +For more, see an example of `keeper`'s [methods implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/keeper/keeper.go). The [module `KVStore`](../core/store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys. This is an example from the `auth` module to iterate accounts: -+++ https://github.com/cosmos/cosmos-sdk/blob/bf8809ef9840b4f5369887a38d8345e2380a567f/x/auth/keeper/account.go#L70-L83 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/keeper/account.go#L76-L90 ## Next {hide} diff --git a/docs/building-modules/messages-and-queries.md b/docs/building-modules/messages-and-queries.md index 11e92fe30738..6e075bf422e4 100644 --- a/docs/building-modules/messages-and-queries.md +++ b/docs/building-modules/messages-and-queries.md @@ -18,11 +18,11 @@ When a transaction is relayed from the underlying consensus engine to the Cosmos ### `Msg` Services -Starting from v0.40, defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../core/encoding.md#faq)). It must have an RPC service method defined for each message in the module. +Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../core/encoding.md#faq)). It must have an RPC service method defined for each message in the module. See an example of a `Msg` service definition from `x/bank` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L10-L17 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L12-L19 Each `Msg` service method must have exactly one argument, which must implement the `sdk.Msg` interface, and a Protobuf response. The naming convention is to call the RPC argument `Msg` and the RPC response `MsgResponse`. For example: @@ -49,7 +49,7 @@ Amino `LegacyMsg`s can be defined as protobuf messages. The messages definition A `LegacyMsg` is typically accompanied by a standard constructor function, that is called from one of the [module's interface](./module-interfaces.md). `message`s also need to implement the `sdk.Msg` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/4a1b2fba43b1052ca162b3a1e0b6db6db9c26656/types/tx_msg.go#L10-L33 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/tx_msg.go#L10-L22 It extends `proto.Message` and contains the following methods: @@ -59,23 +59,25 @@ It extends `proto.Message` and contains the following methods: * `GetSignBytes() []byte`: Return the canonical byte representation of the message. Used to generate a signature. * `GetSigners() []AccAddress`: Return the list of signers. The Cosmos SDK will make sure that each `message` contained in a transaction is signed by all the signers listed in the list returned by this method. ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/migrations/legacytx/stdsign.go#L20-L36 + See an example implementation of a `message` from the `gov` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/gov/types/msgs.go#L77-L125 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/gov/types/v1/msgs.go#L106-L138 ## Queries -A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `queryrouter` so that it can be processed by the module's query service (./query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../basics/query-lifecycle.md). +A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `QueryRouter` so that it can be processed by the module's query service (./query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../basics/query-lifecycle.md). ### gRPC Queries -Starting from v0.40, the preferred way to define queries is by using [Protobuf services](https://developers.google.com/protocol-buffers/docs/proto#services). A `Query` service should be created per module in `query.proto`. This service lists endpoints starting with `rpc`. +Queries should be defined using [Protobuf services](https://developers.google.com/protocol-buffers/docs/proto#services). A `Query` service should be created per module in `query.proto`. This service lists endpoints starting with `rpc`. Here's an example of such a `Query` service definition: -+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/auth/v1beta1/query.proto#L12-L23 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/auth/v1beta1/query.proto#L13-L59 -As `proto.Message`s, generated `Response` types implement by default `String()` method of [`fmt.Stringer`](https://golang.org/pkg/fmt/#Stringer). +As `proto.Message`s, generated `Response` types implement by default `String()` method of [`fmt.Stringer`](https://pkg.go.dev/fmt#Stringer). A `RegisterQueryServer` method is also generated and should be used to register the module's query server in the `RegisterServices` method from the [`AppModule` interface](./module-manager.md#appmodule). @@ -98,7 +100,7 @@ The `path` for each `query` must be defined by the module developer in the modul * A [`querier`](./query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../core/baseapp.md#query-routing). * [Query commands](./module-interfaces.md#query-commands) in the module's CLI file, where the `path` for each `query` is specified. -* `query` return types. Typically defined in a file `types/querier.go`, they specify the result type of each of the module's `queries`. These custom types must implement the `String()` method of [`fmt.Stringer`](https://golang.org/pkg/fmt/#Stringer). +* `query` return types. Typically defined in a file `types/querier.go`, they specify the result type of each of the module's `queries`. These custom types must implement the `String()` method of [`fmt.Stringer`](https://pkg.go.dev/fmt#Stringer). ### Store Queries @@ -106,9 +108,7 @@ Store queries query directly for store keys. They use `clientCtx.QueryABCI(req a See following examples: -+++ https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/x/ibc/core/client/query.go#L36-L46 - -+++ https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/baseapp/abci.go#L722-L749 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/baseapp/abci.go#L756-L777 ## Next {hide} diff --git a/docs/building-modules/module-interfaces.md b/docs/building-modules/module-interfaces.md index c4fe187a9758..91dca7a53d50 100644 --- a/docs/building-modules/module-interfaces.md +++ b/docs/building-modules/module-interfaces.md @@ -16,19 +16,19 @@ One of the main interfaces for an application is the [command-line interface](.. ### Transaction Commands - In order to create messages that trigger state changes, end-users must create [transactions](../core/transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages. +In order to create messages that trigger state changes, end-users must create [transactions](../core/transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages. - Transaction commands typically have their own `tx.go` file that lives within the module's `./client/cli` folder. The commands are specified in getter functions and the name of the function should include the name of the command. +Transaction commands typically have their own `tx.go` file that lives within the module's `./client/cli` folder. The commands are specified in getter functions and the name of the function should include the name of the command. Here is an example from the `x/bank` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L28-L63 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/client/cli/tx.go#L35-L71 In the example, `NewSendTxCmd()` creates and returns the transaction command for a transaction that wraps and delivers `MsgSend`. `MsgSend` is the message used to send tokens from one account to another. In general, the getter function does the following: -* **Constructs the command:** Read the [Cobra Documentation](https://godoc.org/github.com/spf13/cobra) for more detailed information on how to create commands. +* **Constructs the command:** Read the [Cobra Documentation](https://pkg.go.dev/github.com/spf13/cobra) for more detailed information on how to create commands. * **Use:** Specifies the format of the user input required to invoke the command. In the example above, `send` is the name of the transaction command and `[from_key_or_address]`, `[to_address]`, and `[amount]` are the arguments. * **Args:** The number of arguments the user provides. In this case, there are exactly three: `[from_key_or_address]`, `[to_address]`, and `[amount]`. * **Short and Long:** Descriptions for the command. A `Short` description is expected. A `Long` description can be used to provide additional information that is displayed when a user adds the `--help` flag. @@ -42,23 +42,23 @@ In general, the getter function does the following: Each module must implement `NewTxCmd()`, which aggregates all of the transaction commands of the module. Here is an example from the `x/bank` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L13-L26 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/client/cli/tx.go#L17-L33 Each module must also implement the `GetTxCmd()` method for `AppModuleBasic` that simply returns `NewTxCmd()`. This allows the root command to easily aggregate all of the transaction commands for each module. Here is an example: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/module.go#L75-L78 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/module.go#L70-L73 ### Query Commands [Queries](./messages-and-queries.md#queries) allow users to gather information about the application or network state; they are routed by the application and processed by the module in which they are defined. Query commands typically have their own `query.go` file in the module's `./client/cli` folder. Like transaction commands, they are specified in getter functions. Here is an example of a query command from the `x/auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L75-L105 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/client/cli/query.go#L83-L125 In the example, `GetAccountCmd()` creates and returns a query command that returns the state of an account based on the provided account address. In general, the getter function does the following: -* **Constructs the command:** Read the [Cobra Documentation](https://godoc.org/github.com/spf13/cobra) for more detailed information on how to create commands. +* **Constructs the command:** Read the [Cobra Documentation](https://pkg.go.dev/github.com/spf13/cobra) for more detailed information on how to create commands. * **Use:** Specifies the format of the user input required to invoke the command. In the example above, `account` is the name of the query command and `[address]` is the argument. * **Args:** The number of arguments the user provides. In this case, there is exactly one: `[address]`. * **Short and Long:** Descriptions for the command. A `Short` description is expected. A `Long` description can be used to provide additional information that is displayed when a user adds the `--help` flag. @@ -72,11 +72,11 @@ In general, the getter function does the following: Each module must implement `GetQueryCmd()`, which aggregates all of the query commands of the module. Here is an example from the `x/auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L25-L42 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/client/cli/query.go#L25-L42 Each module must also implement the `GetQueryCmd()` method for `AppModuleBasic` that returns the `GetQueryCmd()` function. This allows for the root command to easily aggregate all of the query commands for each module. Here is an example: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L80-L83 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/client/cli/query.go#L32-L50 ### Flags @@ -102,13 +102,13 @@ For more detailed information on creating flags, visit the [Cobra Documentation] As mentioned in [transaction commands](#transaction-commands), there is a set of flags that all transaction commands must add. This is done with the `AddTxFlagsToCmd` method defined in the Cosmos SDK's `./client/flags` package. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L94-L120 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/flags/flags.go#L103-L131 Since `AddTxFlagsToCmd(cmd *cobra.Command)` includes all of the basic flags required for a transaction command, module developers may choose not to add any of their own (specifying arguments instead may often be more appropriate). Similarly, there is a `AddQueryFlagsToCmd(cmd *cobra.Command)` to add common flags to a module query command. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L85-L92 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/flags/flags.go#L92-L101 ## gRPC @@ -120,15 +120,15 @@ In order to do that, modules must implement `RegisterGRPCGatewayRoutes(clientCtx Here's an example from the `x/auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L68-L73 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/module.go#L61-L66 ## gRPC-gateway REST -Applications need to support web services that use HTTP requests (e.g. a web wallet like [Keplr](https://keplr.xyz)). [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) translates REST calls into gRPC calls, which might be useful for clients that do not use gRPC. +Applications need to support web services that use HTTP requests (e.g. a web wallet like [Keplr](https://keplr.app)). [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) translates REST calls into gRPC calls, which might be useful for clients that do not use gRPC. Modules that want to expose REST queries should add `google.api.http` annotations to their `rpc` methods, such as in the example below from the `x/auth` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/auth/v1beta1/query.proto#L13-L29 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/auth/v1beta1/query.proto#L13-L59 gRPC gateway is started in-process along with the application and Tendermint. It can be enabled or disabled by setting gRPC Configuration `enable` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml). diff --git a/docs/building-modules/module-manager.md b/docs/building-modules/module-manager.md index b3e4094e711a..edcab0388ea2 100644 --- a/docs/building-modules/module-manager.md +++ b/docs/building-modules/module-manager.md @@ -29,7 +29,7 @@ are only used for genesis can take advantage of the `Module` patterns without ha The `AppModuleBasic` interface defines the independent methods modules need to implement. -+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L49-L63 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/module/module.go#L47-L60 Let us go through the methods: @@ -48,7 +48,7 @@ All the `AppModuleBasic` of an application are managed by the [`BasicManager`](# The `AppModuleGenesis` interface is a simple embedding of the `AppModuleBasic` interface with two added methods. -+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L152-L158 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/module/module.go#L140-L146 Let us go through the two added methods: @@ -61,14 +61,14 @@ It does not have its own manager, and exists separately from [`AppModule`](#appm The `AppModule` interface defines the inter-dependent methods that modules need to implement. -+++ https://github.com/cosmos/cosmos-sdk/blob/b4cce159bcc6a32ac78245c6866dd87c73f3720d/types/module/module.go#L160-L182 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/module/module.go#L148-L176 `AppModule`s are managed by the [module manager](#manager). This interface embeds the `AppModuleGenesis` interface so that the manager can access all the independent and genesis inter-dependent methods of the module. This means that a concrete type implementing the `AppModule` interface must either implement all the methods of `AppModuleGenesis` (and by extension `AppModuleBasic`), or include a concrete type that does as parameter. Let us go through the methods of `AppModule`: * `RegisterInvariants(sdk.InvariantRegistry)`: Registers the [`invariants`](./invariants.md) of the module. If an invariant deviates from its predicted value, the [`InvariantRegistry`](./invariants.md#registry) triggers appropriate logic (most often the chain will be halted). -* `Route()`: Returns the route for [`message`s](./messages-and-queries.md#messages) to be routed to the module by [`BaseApp`](../core/baseapp.md#message-routing). +* `Route()` (deprecated): Returns the route for [`message`s](./messages-and-queries.md#messages) to be routed to the module by [`BaseApp`](../core/baseapp.md#message-routing). * `QuerierRoute()` (deprecated): Returns the name of the module's query route, for [`queries`](./messages-and-queries.md#queries) to be routes to the module by [`BaseApp`](../core/baseapp.md#query-routing). * `LegacyQuerierHandler(*codec.LegacyAmino)` (deprecated): Returns a [`querier`](./query-services.md#legacy-queriers) given the query `path`, in order to process the `query`. * `RegisterServices(Configurator)`: Allows a module to register services. @@ -105,7 +105,7 @@ Module managers are used to manage collections of `AppModuleBasic` and `AppModul The `BasicManager` is a structure that lists all the `AppModuleBasic` of an application: -+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L65-L66 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/module/module.go#L62-L72 It implements the following methods: @@ -122,7 +122,7 @@ It implements the following methods: The `Manager` is a structure that holds all the `AppModule` of an application, and defines the order of execution between several key components of these modules: -+++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L223-L231 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/module/module.go#L216-L225 The module manager is used throughout the application whenever an action on a collection of modules is required. It implements the following methods: @@ -133,6 +133,7 @@ The module manager is used throughout the application whenever an action on a co * `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function). * `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function). * `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function). +* `SetOrderMigrations(moduleNames ...string)`: Sets the order of migrations to be run. If not set then migrations will be run with an order defined in `DefaultMigrationsOrder`. * `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./invariants.md) of each module. * `RegisterRoutes(router sdk.Router, queryRouter sdk.QueryRouter, legacyQuerierCdc *codec.LegacyAmino)`: Registers legacy [`Msg`](./messages-and-queries.md#messages) and [`querier`](./query-services.md#legacy-queriers) routes. * `RegisterServices(cfg Configurator)`: Registers all module services. @@ -143,7 +144,7 @@ The module manager is used throughout the application whenever an action on a co Here's an example of a concrete integration within an application: -+++ https://github.com/cosmos/cosmos-sdk/blob/2323f1ac0e9a69a0da6b43693061036134193464/simapp/app.go#L315-L362 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/app.go#L342-L409 ## Next {hide} diff --git a/docs/building-modules/msg-services.md b/docs/building-modules/msg-services.md index f28adab4ec87..37cd45cb9144 100644 --- a/docs/building-modules/msg-services.md +++ b/docs/building-modules/msg-services.md @@ -19,7 +19,7 @@ As further described in [ADR 031](../architecture/adr-031-msg-service.md), this Protobuf generates a `MsgServer` interface based on a definition of `Msg` service. It is the role of the module developer to implement this interface, by implementing the state transition logic that should happen upon receival of each `sdk.Msg`. As an example, here is the generated `MsgServer` interface for `x/bank`, which exposes two `sdk.Msg`s: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/bank/types/tx.pb.go#L285-L291 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/types/tx.pb.go#L288-L294 When possible, the existing module's [`Keeper`](keeper.md) should implement `MsgServer`, otherwise a `msgServer` struct that embeds the `Keeper` can be created, typically in `./keeper/msg_server.go`: @@ -33,7 +33,7 @@ When possible, the existing module's [`Keeper`](keeper.md) should implement `Msg ### Validation -Before a `msgServer` method is executed, the message's [`ValidateBasic()`](../basics/tx-lifecycle.md#ValidateBasic) method has already been called. Since `msg.ValidateBasic()` performs only the most basic checks, this stage must perform all other validation (both *stateful* and *stateless*) to make sure the `message` is valid. Checks performed in the `msgServer` method can be more expensive and the signer is charged gas for these operations. +Before a `msgServer` method is executed, the message's [`ValidateBasic()`](../basics/tx-lifecycle.md#ValidateBasic) method has already been called. Since `msg.ValidateBasic()` performs only the most basic checks, this stage must perform all other validation (both *stateful* and *stateless*) to make sure the `message` is valid. Checks performed in the `msgServer` method can be more expensive and the signer is charged gas for these operations. For example, a `msgServer` method for a `transfer` message might check that the sending account has enough funds to actually perform the transfer. It is recommended to implement all validation checks in a separate function that passes state values as arguments. This implementation simplifies testing. As expected, expensive validation functions charge additional gas. Example: @@ -77,57 +77,23 @@ These events are relayed back to the underlying consensus engine and can be used The invoked `msgServer` method returns a `proto.Message` response and an `error`. These return values are then wrapped into an `*sdk.Result` or an `error` using `sdk.WrapServiceResult(ctx sdk.Context, res proto.Message, err error)`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/baseapp/msg_service_router.go#L104-L104 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/baseapp/msg_service_router.go#L127 This method takes care of marshaling the `res` parameter to protobuf and attaching any events on the `ctx.EventManager()` to the `sdk.Result`. -+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/base/abci/v1beta1/abci.proto#L81-L95 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/base/abci/v1beta1/abci.proto#L88-L109 This diagram shows a typical structure of a Protobuf `Msg` service, and how the message propagates through the module. ![Transaction flow](../uml/svg/transaction_flow.svg) -## Amino `LegacyMsg`s - -### `handler` type - -The `handler` type defined in the Cosmos SDK will be deprecated in favor of [`Msg` Services](#implementation-of-a-module-msg-service). - -Here is the typical structure of a `handler` function: - -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/types/handler.go#L4-L4 - -Let us break it down: - -* The [`LegacyMsg`](./messages-and-queries.md#messages) is the actual object being processed. -* The [`Context`](../core/context.md) contains all the necessary information needed to process the `msg`, as well as a branch of the latest state. If the `msg` is successfully processed, the branched version of the state contained in the `ctx` will be written to the main state (branch). -* The `*Result` returned to `BaseApp` contains (among other things) information on the execution of the `handler` and [events](../core/events.md). - -Module `handler`s are typically implemented in a `./handler.go` file inside the module's folder. The [module manager](./module-manager.md) is used to add the module's `handler`s to the -[application's `router`](../core/baseapp.md#message-routing) via the `Route()` method. Typically, -the manager's `Route()` method simply constructs a Route that calls a `NewHandler()` method defined in `handler.go`. - -+++ https://github.com/cosmos/cosmos-sdk/blob/228728cce2af8d494c8b4e996d011492139b04ab/x/gov/module.go#L143-L146 - -### Implementation - -`NewHandler` function dispatches a `LegacyMsg` to appropriate handler function, usually by using a switch statement: - -+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/handler.go#L13-L29 - -First, `NewHandler` function sets a new `EventManager` to the context to isolate events per `msg`. -Then, a simple switch calls the appropriate `handler` based on the `LegacyMsg` type. - -In this regard, `handler`s functions need to be implemented for each module `LegacyMsg`. This will also involve manual handler registration of `LegacyMsg` types. -`handler`s functions should return a `*Result` and an `error`. - ## Telemetry New [telemetry metrics](../core/telemetry.md) can be created from `msgServer` methods when handling messages. This is an example from the `x/auth/vesting` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/auth/vesting/msg_server.go#L73-L85 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/vesting/msg_server.go#L73-L85 ## Next {hide} diff --git a/docs/building-modules/query-services.md b/docs/building-modules/query-services.md index beae1013ca02..4618480a6d99 100644 --- a/docs/building-modules/query-services.md +++ b/docs/building-modules/query-services.md @@ -15,14 +15,14 @@ A Protobuf Query service processes [`queries`](./messages-and-queries.md#queries The `querier` type defined in the Cosmos SDK will be deprecated in favor of [gRPC Services](#grpc-service). It specifies the typical structure of a `querier` function: -+++ https://github.com/cosmos/cosmos-sdk/blob/9a183ffbcc0163c8deb71c7fd5f8089a83e58f05/types/queryable.go#L9 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/queryable.go#L9 Let us break it down: +* The [`Context`](../core/context.md) contains all the necessary information needed to process the `query`, as well as a branch of the latest state. It is primarily used by the [`keeper`](./keeper.md) to access the state. * The `path` is an array of `string`s that contains the type of the query, and that can also contain `query` arguments. See [`queries`](./messages-and-queries.md#queries) for more information. * The `req` itself is primarily used to retrieve arguments if they are too large to fit in the `path`. This is done using the `Data` field of `req`. -* The [`Context`](../core/context.md) contains all the necessary information needed to process the `query`, as well as a branch of the latest state. It is primarily used by the [`keeper`](./keeper.md) to access the state. -* The result `res` returned to `BaseApp`, marshalled using the application's [`codec`](../core/encoding.md). +* The result in `[]byte` returned to `BaseApp`, marshalled using the application's [`codec`](../core/encoding.md). ## Implementation of a module query service @@ -43,7 +43,7 @@ from the store. Therefore, the Cosmos SDK provides a function `sdk.UnwrapSDKCont Here's an example implementation for the bank module: -+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/keeper/grpc_query.go ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/keeper/grpc_query.go ### Legacy Queriers @@ -70,7 +70,7 @@ This simple switch returns a `querier` function specific to the type of the rece The `querier` functions themselves are pretty straightforward. They generally fetch a value or values from the state using the [`keeper`](./keeper.md). Then, they marshall the value(s) using the [`codec`](../core/encoding.md) and return the `[]byte` obtained as result. -For a deeper look at `querier`s, see this [example implementation of a `querier` function](https://github.com/cosmos/cosmos-sdk/blob/7f59723d889b69ca19966167f0b3a7fec7a39e53/x/gov/keeper/querier.go) from the bank module. +For a deeper look at `querier`s, see this [example implementation of a `querier` function](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/gov/keeper/querier.go) from the bank module. ## Next {hide} diff --git a/docs/building-modules/simulator.md b/docs/building-modules/simulator.md index c9db04a710af..4c2196dad75c 100644 --- a/docs/building-modules/simulator.md +++ b/docs/building-modules/simulator.md @@ -32,7 +32,7 @@ for the key-value pairs from the stores to be decoded (_i.e_ unmarshalled) to their corresponding types. In particular, it matches the key to a concrete type and then unmarshals the value from the `KVPair` to the type provided. -You can use the example [here](https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/x/distribution/simulation/decoder.go) from the distribution module to implement your store decoders. +You can use the example [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/distribution/simulation/decoder.go) from the distribution module to implement your store decoders. ### Randomized genesis @@ -43,13 +43,13 @@ Once the module genesis parameter are generated randomly (or with the key and values defined in a `params` file), they are marshaled to JSON format and added to the app genesis JSON to use it on the simulations. -You can check an example on how to create the randomized genesis [here](https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/x/staking/simulation/genesis.go). +You can check an example on how to create the randomized genesis [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/simulation/genesis.go). ### Randomized parameter changes The simulator is able to test parameter changes at random. The simulator package from each module must contain a `RandomizedParams` func that will simulate parameter changes of the module throughout the simulations lifespan. -You can see how an example of what is needed to fully test parameter changes [here](https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/x/staking/simulation/params.go) +You can see how an example of what is needed to fully test parameter changes [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/simulation/params.go) ### Random weighted operations @@ -62,7 +62,7 @@ Operations on the simulation are simulated using the full [transaction cycle](.. Shown below is how weights are set: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/simulation/operations.go#L18-L68 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/simulation/operations.go#L17-L75 As you can see, the weights are predefined in this case. Options exist to override this behavior with different weights. One option is to use `*rand.Rand` to define a random weight for the operation, or you can inject your own predefined weights. @@ -82,7 +82,7 @@ them to be used on the parameters. Now that all the required functions are defined, we need to integrate them into the module pattern within the `module.go`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/x/distribution/module.go ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/distribution/module.go ## App Simulator manager diff --git a/docs/building-modules/upgrade.md b/docs/building-modules/upgrade.md index fc57ec46a1e5..863066ca798d 100644 --- a/docs/building-modules/upgrade.md +++ b/docs/building-modules/upgrade.md @@ -4,7 +4,7 @@ order: 13 # Upgrading Modules -[In-Place Store Migrations](../core/upgrade.html) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. {synopsis} +[In-Place Store Migrations](../core/upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. {synopsis} ## Prerequisite Readings @@ -41,7 +41,7 @@ func (am AppModule) RegisterServices(cfg module.Configurator) { Since these migrations are functions that need access to a Keeper's store, use a wrapper around the keepers called `Migrator` as shown in this example: -+++ https://github.com/cosmos/cosmos-sdk/blob/6ac8898fec9bd7ea2c1e5c79e0ed0c3f827beb55/x/bank/keeper/migrations.go#L8-L21 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/keeper/migrations.go#L9-L27 ## Writing Migration Scripts @@ -54,4 +54,4 @@ func (m Migrator) Migrate1to2(ctx sdk.Context) error { } ``` -To see example code of changes that were implemented in a migration of balance keys, check out [migrateBalanceKeys](https://github.com/cosmos/cosmos-sdk/blob/36f68eb9e041e20a5bb47e216ac5eb8b91f95471/x/bank/legacy/v043/store.go#L41-L62). For context, this code introduced migrations of the bank store that updated addresses to be prefixed by their length in bytes as outlined in [ADR-028](../architecture/adr-028-public-key-addresses.md). +To see example code of changes that were implemented in a migration of balance keys, check out [migrateBalanceKeys](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/migrations/v043/store.go#L50-L71). For context, this code introduced migrations of the bank store that updated addresses to be prefixed by their length in bytes as outlined in [ADR-028](../architecture/adr-028-public-key-addresses.md). diff --git a/docs/core/baseapp.md b/docs/core/baseapp.md index 5d61f137428c..0144cbeeb36f 100644 --- a/docs/core/baseapp.md +++ b/docs/core/baseapp.md @@ -67,7 +67,7 @@ First, the important parameters that are initialized during the bootstrapping of * [gRPC Query Router](#grpc-query-router): The `grpcQueryRouter` facilitates the routing of gRPC queries to the appropriate module for it to be processed. These queries are not ABCI messages themselves, but they are relayed to the relevant module's gRPC `Query` service. -* [`TxDecoder`](https://godoc.org/github.com/cosmos/cosmos-sdk/types#TxDecoder): It is used to decode +* [`TxDecoder`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/types#TxDecoder): It is used to decode raw transaction bytes relayed by the underlying Tendermint engine. * [`ParamStore`](#paramstore): The parameter store used to get and set application consensus parameters. * [`AnteHandler`](#antehandler): This handler is used to handle signature verification, fee payment, @@ -112,7 +112,7 @@ func NewBaseApp( ``` The `BaseApp` constructor function is pretty straightforward. The only thing worth noting is the -possibility to provide additional [`options`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/options.go) +possibility to provide additional [`options`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/baseapp/options.go) to the `BaseApp`, which will execute them in order. The `options` are generally `setter` functions for important parameters, like `SetPruning()` to set pruning options or `SetMinGasPrices()` to set the node's `min-gas-prices`. @@ -193,7 +193,7 @@ When messages and queries are received by the application, they must be routed t [`sdk.Msg`s](#../building-modules/messages-and-queries.md#messages) need to be routed after they are extracted from transactions, which are sent from the underlying Tendermint engine via the [`CheckTx`](#checktx) and [`DeliverTx`](#delivertx) ABCI messages. To do so, `BaseApp` holds a `msgServiceRouter` which maps fully-qualified service methods (`string`, defined in each module's Protobuf `Msg` service) to the appropriate module's `MsgServer` implementation. -The [default `msgServiceRouter` included in `BaseApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/msg_service_router.go) is stateless. However, some applications may want to make use of more stateful routing mechanisms such as allowing governance to disable certain routes or point them to new modules for upgrade purposes. For this reason, the `sdk.Context` is also passed into each [route handler inside `msgServiceRouter`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/msg_service_router.go#L31-L32). For a stateless router that doesn't want to make use of this, you can just ignore the `ctx`. +The [default `msgServiceRouter` included in `BaseApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/baseapp/msg_service_router.go) is stateless. However, some applications may want to make use of more stateful routing mechanisms such as allowing governance to disable certain routes or point them to new modules for upgrade purposes. For this reason, the `sdk.Context` is also passed into each [route handler inside `msgServiceRouter`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/baseapp/msg_service_router.go#L31-L32). For a stateless router that doesn't want to make use of this, you can just ignore the `ctx`. The application's `msgServiceRouter` is initialized with all the routes using the application's [module manager](../building-modules/module-manager.md#manager) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/app-anatomy.md#constructor-function). @@ -263,7 +263,7 @@ The response contains: * `Info (string):` Additional information. May be non-deterministic. * `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction. * `GasUsed (int64)`: Amount of gas consumed by transaction. During `CheckTx`, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction. Next is an example: - +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/ante/basic.go#L104-L105 + +++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/ante/basic.go#L95-L95 * `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more. * `Codespace (string)`: Namespace for the Code. @@ -316,7 +316,7 @@ After that, `RunTx()` calls `ValidateBasic()` on each `sdk.Msg`in the `Tx`, whic Then, the [`anteHandler`](#antehandler) of the application is run (if it exists). In preparation of this step, both the `checkState`/`deliverState`'s `context` and `context`'s `CacheMultiStore` are branched using the `cacheTxContext()` function. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.45.4/baseapp/baseapp.go#L651-L657 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/baseapp/baseapp.go#L647-L654 This allows `RunTx` not to commit the changes made to the state during the execution of `anteHandler` if it ends up failing. It also prevents the module implementing the `anteHandler` from writing to state, which is an important part of the [object-capabilities](./ocap.md) of the Cosmos SDK. @@ -326,7 +326,7 @@ Finally, the [`RunMsgs()`](#runmsgs) function is called to process the `sdk.Msg` The `AnteHandler` is a special handler that implements the `AnteHandler` interface and is used to authenticate the transaction before the transaction's internal messages are processed. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.45.4/types/handler.go#L6-L8 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/handler.go#L6-L8 The `AnteHandler` is theoretically optional, but still a very important component of public blockchain networks. It serves 3 primary purposes: @@ -334,7 +334,7 @@ The `AnteHandler` is theoretically optional, but still a very important componen * Perform preliminary _stateful_ validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees. * Play a role in the incentivisation of stakeholders via the collection of transaction fees. -`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../basics/app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/ante/ante.go). +`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../basics/app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/ante/ante.go). Click [here](../basics/gas-fees.md#antehandler) for more on the `anteHandler`. @@ -372,7 +372,7 @@ Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls th The [`BeginBlock` ABCI message](https://docs.tendermint.com/master/spec/abci/abci.html#beginblock) is sent from the underlying Tendermint engine when a block proposal created by the correct proposer is received, before [`DeliverTx`](#delivertx) is run for each transaction in the block. It allows developers to have logic be executed at the beginning of each block. In the Cosmos SDK, the `BeginBlock(req abci.RequestBeginBlock)` method does the following: * Initialize [`deliverState`](#state-updates) with the latest header using the `req abci.RequestBeginBlock` passed as parameter via the `setDeliverState` function. - +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/baseapp/baseapp.go#L387-L397 + +++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/baseapp/baseapp.go#L386-L396 This function also resets the [main gas meter](../basics/gas-fees.md#main-gas-meter). * Initialize the [block gas meter](../basics/gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. * Run the application's [`beginBlocker()`](../basics/app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/beginblock-endblock.md#beginblock) method of each of the application's modules. diff --git a/docs/core/cli.md b/docs/core/cli.md index 9e11d9da0c4d..f85e3d3071a8 100644 --- a/docs/core/cli.md +++ b/docs/core/cli.md @@ -38,9 +38,9 @@ The `main.go` file needs to have a `main()` function that creates a root command * **instantiating the `codec`** by calling the application's `MakeCodec()` function (called `MakeTestEncodingConfig` in `simapp`). The [`codec`](../core/encoding.md) is used to encode and decode data structures for the application - stores can only persist `[]byte`s so the developer must define a serialization format for their data structures or use the default, Protobuf. * **adding subcommand** for all the possible user interactions, including [transaction commands](#transaction-commands) and [query commands](#query-commands). -The `main()` function finally creates an executor and [execute](https://godoc.org/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application: +The `main()` function finally creates an executor and [execute](https://pkg.go.dev/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/main.go#L12-L24 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/main.go#L12-L24 The rest of the document will detail what needs to be implemented for each step and include smaller portions of code from the `simapp` CLI files. @@ -53,50 +53,50 @@ Every application CLI first constructs a root command, then adds functionality b The root command (called `rootCmd`) is what the user first types into the command line to indicate which application they wish to interact with. The string used to invoke the command (the "Use" field) is typically the name of the application suffixed with `-d`, e.g. `simd` or `gaiad`. The root command typically includes the following commands to support basic functionality in the application. * **Status** command from the Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`. -* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys) from the Cosmos SDK client tools, which includes a collection of subcommands for using the key functions in the Cosmos SDK crypto tools, including adding a new key and saving it to the keyring, listing all public keys stored in the keyring, and deleting a key. For example, users can type `simd keys add ` to add a new key and save an encrypted copy to the keyring, using the flag `--recover` to recover a private key from a seed phrase or the flag `--multisig` to group multiple keys together to create a multisig key. For full details on the `add` key command, see the code [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../run-node/keyring.md). -* **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on [cobra](github.com/spf13/cobra)) necessary to fully bootstrap an application. The package exposes two core functions: `StartCmd` and `ExportCmd` which creates commands to start the application and export state respectively. Click [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/server) to learn more. +* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/keys) from the Cosmos SDK client tools, which includes a collection of subcommands for using the key functions in the Cosmos SDK crypto tools, including adding a new key and saving it to the keyring, listing all public keys stored in the keyring, and deleting a key. For example, users can type `simd keys add ` to add a new key and save an encrypted copy to the keyring, using the flag `--recover` to recover a private key from a seed phrase or the flag `--multisig` to group multiple keys together to create a multisig key. For full details on the `add` key command, see the code [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../run-node/keyring.md). +* **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on [cobra](github.com/spf13/cobra)) necessary to fully bootstrap an application. The package exposes two core functions: `StartCmd` and `ExportCmd` which creates commands to start the application and export state respectively. Click [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/server) to learn more. * [**Transaction**](#transaction-commands) commands. * [**Query**](#query-commands) commands. Next is an example `rootCmd` function from the `simapp` application. It instantiates the root command, adds a [_persistent_ flag](#flags) and `PreRun` function to be run before every execution, and adds all of the necessary subcommands. -+++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L37-L150 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L39-L85 `rootCmd` has a function called `initAppConfig()` which is useful for setting the application's custom configs. By default app uses Tendermint app config template from Cosmos SDK, which can be over-written via `initAppConfig()`. Here's an example code to override default `app.toml` template. -+++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L84-L117 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L99-L153 -The `initAppConfig()` also allows overriding the default Cosmos SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/server/config/config.go#L199). One example is the `min-gas-prices` config, which defines the minimum gas prices a validator is willing to accept for processing a transaction. By default, the Cosmos SDK sets this parameter to `""` (empty string), which forces all validators to tweak their own `app.toml` and set a non-empty value, or else the node will halt on startup. This might not be the best UX for validators, so the chain developer can set a default `app.toml` value for validators inside this `initAppConfig()` function. +The `initAppConfig()` also allows overriding the default Cosmos SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/server/config/config.go#L235). One example is the `min-gas-prices` config, which defines the minimum gas prices a validator is willing to accept for processing a transaction. By default, the Cosmos SDK sets this parameter to `""` (empty string), which forces all validators to tweak their own `app.toml` and set a non-empty value, or else the node will halt on startup. This might not be the best UX for validators, so the chain developer can set a default `app.toml` value for validators inside this `initAppConfig()` function. -+++ https://github.com/cosmos/cosmos-sdk/blob/aa9b055ddb46aacd4737335a92d0b8a82d577341/simapp/simd/cmd/root.go#L101-L116 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L119-L134 The root-level `status` and `keys` subcommands are common across most applications and do not interact with application state. The bulk of an application's functionality - what users can actually _do_ with it - is enabled by its `tx` and `query` commands. ### Transaction Commands -[Transactions](./transactions.md) are objects wrapping [`Msg`s](../building-modules/messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCmd` is generally added to the `rootCmd`: +[Transactions](./transactions.md) are objects wrapping [`Msg`s](../building-modules/messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCommand` is generally added to the `rootCmd`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L175-L181 -This `txCmd` function adds all the transaction available to end-users for the application. This typically includes: +This `txCommand` function adds all the transaction available to end-users for the application. This typically includes: * **Sign command** from the [`auth`](../../x/auth/spec/README.md) module that signs messages in a transaction. To enable multisig, add the `auth` module's `MultiSign` command. Since every transaction requires some sort of signature in order to be valid, the signing command is necessary for every application. * **Broadcast command** from the Cosmos SDK client tools, to broadcast transactions. * **All [module transaction commands](../building-modules/module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddTxCommands()` function. -Here is an example of a `txCmd` aggregating these subcommands from the `simapp` application: +Here is an example of a `txCommand` aggregating these subcommands from the `simapp` application: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L123-L149 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L215-L240 ### Query Commands -[**Queries**](../building-modules/messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of transactions using the CLI interface, a function `txCmd` is generally added to the `rootCmd`: +[**Queries**](../building-modules/messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of queries using the CLI interface, a function `queryCommand` is generally added to the `rootCmd`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L175-L181 -This `queryCmd` function adds all the queries available to end-users for the application. This typically includes: +This `queryCommand` function adds all the queries available to end-users for the application. This typically includes: * **QueryTx** and/or other transaction query commands] from the `auth` module which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block. * **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address. @@ -104,9 +104,9 @@ This `queryCmd` function adds all the queries available to end-users for the app * **Block command** from the Cosmos SDK rpc client tools, which displays the block data for a given height. * **All [module query commands](../building-modules/module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddQueryCommands()` function. -Here is an example of a `queryCmd` aggregating subcommands from the `simapp` application: +Here is an example of a `queryCommand` aggregating subcommands from the `simapp` application: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L99-L121 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L191-L213 ## Flags @@ -116,7 +116,7 @@ A _persistent_ flag (as opposed to a _local_ flag) added to a command transcends Flags are added to commands directly (generally in the [module's CLI file](../building-modules/module-interfaces.md#flags) where module commands are defined) and no flag except for the `rootCmd` persistent flags has to be added at application level. It is common to add a _persistent_ flag for `--chain-id`, the unique identifier of the blockchain the application pertains to, to the root command. Adding this flag can be done in the `main()` function. Adding this flag makes sense as the chain ID should not be changing across commands in this application CLI. Here is an example from the `simapp` application: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L118-L119 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L210-L210 ## Environment variables @@ -143,9 +143,9 @@ gaia tx ... --from= It is vital that the root command of an application uses `PersistentPreRun()` cobra command property for executing the command, so all child commands have access to the server and client contexts. These contexts are set as their default values initially and maybe modified, scoped to the command, in their respective `PersistentPreRun()` functions. Note that the `client.Context` is typically pre-populated with "default" values that may be useful for all commands to inherit and override if necessary. -Here is an example of an `PersistentPreRun()` function from `simapp``: +Here is an example of an `PersistentPreRun()` function from `simapp`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L54-L60 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L56-L79 The `SetCmdClientContextHandler` call reads persistent flags via `ReadPersistentCommandFlags` which creates a `client.Context` and sets that on the root command's `Context`. diff --git a/docs/core/context.md b/docs/core/context.md index 39344a9f68d7..9994839c03b7 100644 --- a/docs/core/context.md +++ b/docs/core/context.md @@ -13,13 +13,14 @@ The `context` is a data structure intended to be passed from function to functio ## Context Definition -The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://golang.org/pkg/context) as its base, and has many additional types within its definition that are specific to the Cosmos SDK. The `Context` is integral to transaction processing in that it allows modules to easily access their respective [store](./store.md#base-layer-kvstores) in the [`multistore`](./store.md#multistore) and retrieve transactional context such as the block header and gas meter. +The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://pkg.go.dev/context) as its base, and has many additional types within its definition that are specific to the Cosmos SDK. The `Context` is integral to transaction processing in that it allows modules to easily access their respective [store](./store.md#base-layer-kvstores) in the [`multistore`](./store.md#multistore) and retrieve transactional context such as the block header and gas meter. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/context.go#L16-L39 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/context.go#L17-L42 -* **Context:** The base type is a Go [Context](https://golang.org/pkg/context), which is explained further in the [Go Context Package](#go-context-package) section below. +* **Base Context:** The base type is a Go [Context](https://pkg.go.dev/context), which is explained further in the [Go Context Package](#go-context-package) section below. * **Multistore:** Every application's `BaseApp` contains a [`CommitMultiStore`](./store.md#multistore) which is provided when a `Context` is created. Calling the `KVStore()` and `TransientStore()` methods allows modules to fetch their respective [`KVStore`](./store.md#base-layer-kvstores) using their unique `StoreKey`. * **Header:** The [header](https://docs.tendermint.com/master/spec/core/data_structures.html#header) is a Blockchain type. It carries important information about the state of the blockchain, such as block height and proposer of the current block. +* **Header Hash:** The current block header hash, obtained during `abci.RequestBeginBlock`. * **Chain ID:** The unique identification number of the blockchain a block pertains to. * **Transaction Bytes:** The `[]byte` representation of a transaction being processed using the context. Every transaction is processed by various parts of the Cosmos SDK and consensus engine (e.g. Tendermint) throughout its [lifecycle](../basics/tx-lifecycle.md), some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./encoding.md) such as [Amino](./encoding.md). * **Logger:** A `logger` from the Tendermint libraries. Learn more about logs [here](https://docs.tendermint.com/master/nodes/logging.html). Modules call this method to create their own unique module-specific logger. @@ -30,6 +31,7 @@ The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [` * **Consensus Params:** The ABCI type [Consensus Parameters](https://docs.tendermint.com/master/spec/abci/apps.html#consensus-parameters), which specify certain limits for the blockchain, such as maximum gas for a block. * **Event Manager:** The event manager allows any caller with access to a `Context` to emit [`Events`](./events.md). Modules may define module specific `Events` by defining various `Types` and `Attributes` or use the common definitions found in `types/`. Clients can subscribe or query for these `Events`. These `Events` are collected throughout `DeliverTx`, `BeginBlock`, and `EndBlock` and are returned to Tendermint for indexing. For example: +* **Priority:** The transaction priority, only relevant in `CheckTx`. ```go ctx.EventManager().EmitEvent(sdk.NewEvent( @@ -40,7 +42,7 @@ ctx.EventManager().EmitEvent(sdk.NewEvent( ## Go Context Package -A basic `Context` is defined in the [Golang Context Package](https://golang.org/pkg/context). A `Context` +A basic `Context` is defined in the [Golang Context Package](https://pkg.go.dev/context). A `Context` is an immutable data structure that carries request-scoped data across APIs and processes. Contexts are also designed to enable concurrency and to be used in goroutines. @@ -51,7 +53,7 @@ to create a child context from its parent using a `With` function. For example: childCtx = parentCtx.WithBlockHeader(header) ``` -The [Golang Context Package](https://golang.org/pkg/context) documentation instructs developers to +The [Golang Context Package](https://pkg.go.dev/context) documentation instructs developers to explicitly pass a context `ctx` as the first argument of a process. ## Store branching diff --git a/docs/core/encoding.md b/docs/core/encoding.md index ed90202b3abe..968640145b79 100644 --- a/docs/core/encoding.md +++ b/docs/core/encoding.md @@ -34,11 +34,11 @@ is used for business logic in the state-machine where they may convert back-n-fo Note, the Amino-based types may slowly be phased-out in the future, so developers should take note to use the protobuf message definitions where possible. -In the `codec` package, there exists two core interfaces, `Marshaler` and `ProtoMarshaler`, +In the `codec` package, there exists two core interfaces, `BinaryCodec` and `JSONCodec`, where the former encapsulates the current Amino interface except it operates on types implementing the latter instead of generic `interface{}` types. -In addition, there exists two implementations of `Marshaler`. The first being +In addition, there exists two implementations of `Codec`. The first being `AminoCodec`, where both binary and JSON serialization is handled via Amino. The second being `ProtoCodec`, where both binary and JSON serialization is handled via Protobuf. @@ -109,13 +109,13 @@ the consensus engine accepts only transactions in the form of raw bytes. * The `TxEncoder` object performs the encoding. * The `TxDecoder` object performs the decoding. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/types/tx_msg.go#L83-L87 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/tx_msg.go#L72-L76 A standard implementation of both these objects can be found in the [`auth` module](../../x/auth/spec/README.md): -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/decoder.go ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/tx/decoder.go -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/encoder.go ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/tx/encoder.go See [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. @@ -134,7 +134,7 @@ message Profile { In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../../x/auth/spec/05_vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface? -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/types/account.go#L307-L330 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/types/account.go#L301-L324 In [ADR-019](../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: @@ -172,7 +172,7 @@ bz, err := cdc.Marshal(profile) jsonBz, err := cdc.MarshalJSON(profile) ``` -To summarize, to encode an interface, you must 1/ pack the interface into an `Any` and 2/ marshal the `Any`. For convenience, the Cosmos SDK provides a `MarshalInterface` method to bundle these two steps. Have a look at [a real-life example in the x/auth module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/keeper/keeper.go#L218-L221). +To summarize, to encode an interface, you must 1/ pack the interface into an `Any` and 2/ marshal the `Any`. For convenience, the Cosmos SDK provides a `MarshalInterface` method to bundle these two steps. Have a look at [a real-life example in the x/auth module](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/keeper/keeper.go#L230-L233). The reverse operation of retrieving the concrete Go type from inside an `Any`, called "unpacking", is done with the `GetCachedValue()` on `Any`. @@ -216,11 +216,11 @@ The above `Profile` example is a fictive example used for educational purposes. * the `AccountI` interface for encodinig different types of accounts (similar to the above example) in the x/auth query responses, * the `Evidencei` interface for encoding different types of evidences in the x/evidence module, * the `AuthorizationI` interface for encoding different types of x/authz authorizations, -* the [`Validator`](https://github.com/cosmos/cosmos-sdk/blob/v0.42.5/x/staking/types/staking.pb.go#L306-L337) struct that contains information about a validator. +* the [`Validator`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/types/staking.pb.go#L306-L339) struct that contains information about a validator. A real-life example of encoding the pubkey as `Any` inside the Validator struct in x/staking is shown in the following example: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/types/validator.go#L40-L61 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/types/validator.go#L40-L61 ## FAQ @@ -262,9 +262,9 @@ message MsgSubmitEvidence { The Cosmos SDK `codec.Codec` interface provides support methods `MarshalInterface` and `UnmarshalInterface` to easy encoding of state to `Any`. -Module should register interfaces using `InterfaceRegistry` which provides a mechanism for registering interfaces: `RegisterInterface(protoName string, iface interface{})` and implementations: `RegisterImplementations(iface interface{}, impls ...proto.Message)` that can be safely unpacked from Any, similarly to type registration with Amino: +Module should register interfaces using `InterfaceRegistry` which provides a mechanism for registering interfaces: `RegisterInterface(protoName string, iface interface{}, impls ...proto.Message)` and implementations: `RegisterImplementations(iface interface{}, impls ...proto.Message)` that can be safely unpacked from Any, similarly to type registration with Amino: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/codec/types/interface_registry.go#L25-L66 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/codec/types/interface_registry.go#L25-L55 In addition, an `UnpackInterfaces` phase should be introduced to deserialization to unpack interfaces before they're needed. Protobuf types that contain a protobuf `Any` either directly or via one of their members should implement the `UnpackInterfacesMessage` interface: diff --git a/docs/core/events.md b/docs/core/events.md index 616f9c6541e3..63893e1fb5b9 100644 --- a/docs/core/events.md +++ b/docs/core/events.md @@ -11,12 +11,12 @@ order: 9 * [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq} * [Tendermint Documentation on Events](https://docs.tendermint.com/master/spec/abci/abci.html#events) {prereq} -## Events +## Typed Events Events are implemented in the Cosmos SDK as an alias of the ABCI `Event` type and take the form of: `{eventType}.{attributeKey}={attributeValue}`. -+++ https://github.com/tendermint/tendermint/blob/v0.34.8/proto/tendermint/abci/types.proto#L304-L313 ++++ https://github.com/tendermint/tendermint/blob/v0.35.4/proto/tendermint/abci/types.proto#L273-L279 An Event contains: @@ -27,12 +27,14 @@ An Event contains: To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value. ::: -Events, the `type` and `attributes` are defined on a **per-module basis** in the module's -`/types/events.go` file, and triggered from the module's Protobuf [`Msg` service](../building-modules/msg-services.md) -by using the [`EventManager`](#eventmanager). In addition, each module documents its Events under -`spec/xx_events.md`. +_Typed Events_ are Protobuf-defined [messages](../architecture/adr-032-typed-events.md) used by the Cosmos SDK +for emitting and querying Events. They are defined in a `event.proto` file, on a **per-module basis**. +They are triggered from the module's Protobuf [`Msg` service](../building-modules/msg-services.md) +by using the [`EventManager`](#eventmanager), where they are read as `proto.Message`. -Events are returned to the underlying consensus engine in the response of the following ABCI messages: +In addition, each module documents its Events under `spec/xx_events.md`. + +Lastly, Events are returned to the underlying consensus engine in the response of the following ABCI messages: * [`BeginBlock`](./baseapp.md#beginblock) * [`EndBlock`](./baseapp.md#endblock) @@ -57,23 +59,19 @@ In Cosmos SDK applications, Events are managed by an abstraction called the `Eve Internally, the `EventManager` tracks a list of Events for the entire execution flow of a transaction or `BeginBlock`/`EndBlock`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L17-L25 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/events.go#L17-L25 The `EventManager` comes with a set of useful methods to manage Events. The method -that is used most by module and application developers is `EmitEvent` that tracks +that is used most by module and application developers is `EmitTypedEvent` that tracks an Event in the `EventManager`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L33-L37 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/events.go#L50-L59 -Module developers should handle Event emission via the `EventManager#EmitEvent` in each message +Module developers should handle Event emission via the `EventManager#EmitTypedEvent` in each message `Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via -the [`Context`](./context.md), where Event emission generally follows this pattern: +the [`Context`](./context.md), where Event should be already registered, and emitted like this: -```go -ctx.EventManager().EmitEvent( - sdk.NewEvent(eventType, sdk.NewAttribute(attributeKey, attributeValue)), -) -``` ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/keeper/msg_server.go#L89-L92 Module's `handler` function should also set a new `EventManager` to the `context` to isolate emitted Events per `message`: @@ -109,9 +107,11 @@ The main `eventCategory` you can subscribe to are: * `ValidatorSetUpdates`: Contains validator set updates for the block. These Events are triggered from the `state` package after a block is committed. You can get the -full list of Event categories [on the Tendermint Godoc page](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants). +full list of Event categories [on the Tendermint Go documentation](https://pkg.go.dev/github.com/tendermint/tendermint/types#pkg-constants). -The `type` and `attribute` value of the `query` allow you to filter the specific Event you are looking for. For example, a `transfer` transaction triggers an Event of type `Transfer` and has `Recipient` and `Sender` as `attributes` (as defined in the [`events.go` file of the `bank` module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/bank/types/events.go)). Subscribing to this Event would be done like so: +The `type` and `attribute` value of the `query` allow you to filter the specific Event you are looking for. For example, a `Mint` transaction triggers an Event of type `EventMint` and has an `Id` and an `Owner` as `attributes` (as defined in the [`events.proto` file of the `NFT` module](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/nft/v1beta1/event.proto#L14-L19)). + +Subscribing to this Event would be done like so: ```json { @@ -119,18 +119,20 @@ The `type` and `attribute` value of the `query` allow you to filter the specific "method": "subscribe", "id": "0", "params": { - "query": "tm.event='Tx' AND transfer.sender='senderAddress'" + "query": "tm.event='Tx' AND mint.owner='ownerAddress'" } } ``` -where `senderAddress` is an address following the [`AccAddress`](../basics/accounts.md#addresses) format. +where `ownerAddress` is an address following the [`AccAddress`](../basics/accounts.md#addresses) format. + +## Events (Deprecated) -## Typed Events (coming soon) +Previously, the Cosmos SDK supported emitting Events that were defined in `types/events.go`. It is the responsibility of the module developer to define Event types and Event attributes. Except in the `spec/XX_events.md` file, these Event types and attributes are unfortunately not easily discoverable, -As previously described, Events are defined on a per-module basis. It is the responsibility of the module developer to define Event types and Event attributes. Except in the `spec/XX_events.md` file, these Event types and attributes are unfortunately not easily discoverable, so the Cosmos SDK proposes to use Protobuf-defined [Typed Events](../architecture/adr-032-typed-events.md) for emitting and querying Events. +This is why this methods as been deprecated, and replaced by _[Typed Events](#typed-events). -The Typed Events proposal has not yet been fully implemented. Documentation is not yet available. +To learn more about the previous way of defining events, please refer to the [previous SDK documentation](https://docs.cosmos.network/v0.45/core/events.html#events-2). ## Next {hide} diff --git a/docs/core/grpc_rest.md b/docs/core/grpc_rest.md index f37c1f397a4a..afbeb9c6fbc1 100644 --- a/docs/core/grpc_rest.md +++ b/docs/core/grpc_rest.md @@ -20,23 +20,11 @@ The node also exposes some other endpoints, such as the Tendermint P2P endpoint, ## gRPC Server -::: warning -A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the Cosmos SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`. - -To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`: - -```go -replace google.golang.org/grpc => google.golang.org/grpc v1.33.2 -``` - -Please see [issue #8392](https://github.com/cosmos/cosmos-sdk/issues/8392) for more info. -::: - -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 Cosmos 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. +In the Cosmos SDK, Protobuf is the main [encoding](./encoding) library. This brings a wide range of Protobuf-based tools that can be plugged into the Cosmos 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 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 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/server/types/app.go#L45-L47 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 programmatically before they can be broadcasted using gRPC. See [Generating, Signing, and Broadcasting Transactions](../run-node/txs.html) for more information. @@ -69,7 +57,7 @@ If, for various reasons, you cannot use gRPC (for example, you are building a we [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 Cosmos 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 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/bank/v1beta1/query.proto#L19-L22 For application developers, gRPC-gateway REST routes needs to be wired up to the REST server, this is done by calling the `RegisterGRPCGatewayRoutes` function on the ModuleManager. @@ -79,7 +67,8 @@ A [Swagger](https://swagger.io/) (or OpenAPIv2) specification file is exposed un Enabling the `/swagger` endpoint is configurable inside `~/.simapp/config/app.toml` via the `api.swagger` field, which is set to true by default. -For application developers, you may want to generate your own Swagger definitions based on your custom modules. The Cosmos SDK's [Swagger generation script](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/scripts/protoc-swagger-gen.sh) is a good place to start. +For application developers, you may want to generate your own Swagger definitions based on your custom modules. +The Cosmos SDK's [Swagger generation script](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/scripts/protoc-swagger-gen.sh) is a good place to start. ## Tendermint RPC diff --git a/docs/core/node.md b/docs/core/node.md index a4b8c3bd5f0f..698fbf984dfe 100644 --- a/docs/core/node.md +++ b/docs/core/node.md @@ -16,17 +16,17 @@ The full-node client of any Cosmos SDK application is built by running a `main` In general, developers will implement the `main.go` function with the following structure: -* First, an [`appCodec`](./encoding.md) is instantiated for the application. +* First, an [`encodingCodec`](./encoding.md) is instantiated for the application. * Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../basics/accounts.md#addresses). - +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/config.go#L13-L24 + +++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/config.go#L14-L29 * Using [cobra](https://github.com/spf13/cobra), the root command of the full-node client is created. After that, all the custom commands of the application are added using the `AddCommand()` method of `rootCmd`. * Add default server commands to `rootCmd` using the `server.AddCommands()` method. These commands are separated from the ones added above since they are standard and defined at Cosmos SDK level. They should be shared by all Cosmos SDK-based applications. They include the most important command: the [`start` command](#start-command). * Prepare and execute the `executor`. - +++ https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/libs/cli/setup.go#L74-L78 + +++ https://github.com/tendermint/tendermint/blob/v0.35.4/libs/cli/setup.go#L74-L78 See an example of `main` function from the `simapp` application, the Cosmos SDK's application for demo purposes: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/main.go ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/main.go ## `start` command @@ -46,24 +46,25 @@ The flow of the `start` command is pretty straightforward. First, it retrieves t With the `db`, the `start` command creates a new instance of the application using an `appCreator` function: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L227-L228 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/server/start.go#L209-L209 Note that an `appCreator` is a function that fulfills the `AppCreator` signature: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50 + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/server/types/app.go#L57-L59 In practice, the [constructor of the application](../basics/app-anatomy.md#constructor-function) is passed as the `appCreator`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/cmd/root.go#L170-L215 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/simd/cmd/root.go#L246-L295 Then, the instance of `app` is used to instantiate a new Tendermint node: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L235-L244 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/server/start.go#L291-L294 -The Tendermint node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://github.com/tendermint/tendermint/blob/v0.34.0/abci/types/application.go#L7-L32) (given that `app` extends [`baseapp`](./baseapp.md)). As part of the `NewNode` method, Tendermint makes sure that the height of the application (i.e. number of blocks since genesis) is equal to the height of the Tendermint node. The difference between these two heights should always be negative or null. If it is strictly negative, `NewNode` will replay blocks until the height of the application reaches the height of the Tendermint node. Finally, if the height of the application is `0`, the Tendermint node will call [`InitChain`](./baseapp.md#initchain) on the application to initialize the state from the genesis file. +The Tendermint node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://github.com/tendermint/tendermint/blob/v0.35.4/abci/types/application.go#L7-L32) (given that `app` extends [`baseapp`](./baseapp.md)). As part of the `node.New` method, Tendermint makes sure that the height of the application (i.e. number of blocks since genesis) is equal to the height of the Tendermint node. The difference between these two heights should always be negative or null. If it is strictly negative, `node.New` will replay blocks until the height of the application reaches the height of the Tendermint node. Finally, if the height of the application is `0`, the Tendermint node will call [`InitChain`](./baseapp.md#initchain) on the application to initialize the state from the genesis file. Once the Tendermint node is instantiated and in sync with the application, the node can be started: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L250-L252 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/server/start.go#L296-L298 Upon starting, the node will bootstrap its RPC and P2P server and start dialing peers. During handshake with its peers, if the node realizes they are ahead, it will query all the blocks sequentially in order to catch up. Then, it will wait for new block proposals and block signatures from validators in order to make progress. diff --git a/docs/core/ocap.md b/docs/core/ocap.md index a365fd106ec2..c4dec3106376 100644 --- a/docs/core/ocap.md +++ b/docs/core/ocap.md @@ -65,10 +65,9 @@ value. The preferred method signature should take a copy instead. sumValue := externalModule.ComputeSumValue(*account) ``` -In the Cosmos SDK, you can see the application of this principle in the -gaia app. +In the Cosmos SDK, you can see the application of this principle in simapp. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.4/simapp/app.go#L249-L273 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/app.go#L258-L283 The following diagram shows the current dependencies between keepers. diff --git a/docs/core/simulation.md b/docs/core/simulation.md index 5f13e820d7fd..02befbeacf93 100644 --- a/docs/core/simulation.md +++ b/docs/core/simulation.md @@ -7,8 +7,8 @@ order: 13 The Cosmos SDK offers a full fledged simulation framework to fuzz test every message defined by a module. -On the Cosmos SDK, this functionality is provided by the[`SimApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/app.go), which is a -`Baseapp` application that is used for running the [`simulation`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/simulation) module. +On the Cosmos SDK, this functionality is provided by the[`SimApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/app.go), which is a +`Baseapp` application that is used for running the [`simulation`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/simulation) module. This module defines all the simulation logic as well as the operations for randomized parameters like accounts, balances etc. @@ -35,13 +35,13 @@ failure type: inconsistencies between the stores. * `AppSimulationAfterImport`: Queues two simulations together. The first one provides the app state (_i.e_ genesis) to the second. Useful to test software upgrades or hard-forks from a live chain. * `AppStateDeterminism`: Checks that all the nodes return the same values, in the same order. -* `BenchmarkInvariants`: Analysis of the performance of running all modules' invariants (_i.e_ sequentially runs a [benchmark](https://golang.org/pkg/testing/#hdr-Benchmarks) test). An invariant checks for +* `BenchmarkInvariants`: Analysis of the performance of running all modules' invariants (_i.e_ sequentially runs a [benchmark](https://pkg.go.dev/testing/#hdr-Benchmarks) test). An invariant checks for differences between the values that are on the store and the passive tracker. Eg: total coins held by accounts vs total supply tracker. * `FullAppSimulation`: General simulation mode. Runs the chain and the specified operations for a given number of blocks. Tests that there're no `panics` on the simulation. It does also run invariant checks on every `Period` but they are not benchmarked. Each simulation must receive a set of inputs (_i.e_ flags) such as the number of blocks that the simulation is run, seed, block size, etc. -Check the full list of flags [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/config.go#L32-L55). +Check the full list of flags [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/config.go#L32-L55). ## Simulator Modes @@ -53,7 +53,7 @@ In addition to the various inputs and commands, the simulator runs in three mode This mode is helpful for running simulations on a known state such as a live network export where a new (mostly likely breaking) version of the application needs to be tested. 3. From a `params.json` file where the initial state is pseudo-randomly generated but the module and simulation parameters can be provided manually. This allows for a more controlled and deterministic simulation setup while allowing the state space to still be pseudo-randomly simulated. - The list of available parameters are listed [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/simulation/params.go#L44-L52). + The list of available parameters are listed [here](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/config.go#L33-L57). ::: tip These modes are not mutually exclusive. So you can for example run a randomly @@ -63,7 +63,7 @@ generated genesis state (`1`) with manually generated simulation params (`3`). ## Usage This is a general example of how simulations are run. For more specific examples -check the Cosmos SDK [Makefile](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/Makefile#L251-L287). +check the Cosmos SDK [Makefile](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/Makefile#L263-L299). ```bash $ go test -mod=readonly github.com/cosmos/cosmos-sdk/simapp \ @@ -90,7 +90,7 @@ Here are some suggestions when encountering a simulation failure: * Run invariants on every operation with `-SimulateEveryOperation`. _Note_: this will slow down your simulation **a lot**. * Try adding logs to operations that are not logged. You will have to define a - [Logger](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/keeper/keeper.go#L66-L69) on your `Keeper`. + [Logger](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/keeper/keeper.go#L60-L63) on your `Keeper`. ## Use simulation in your Cosmos SDK-based application diff --git a/docs/core/store.md b/docs/core/store.md index e7ff13e68765..b9f649b7f05a 100644 --- a/docs/core/store.md +++ b/docs/core/store.md @@ -58,11 +58,11 @@ The Cosmos SDK comes with a large set of stores to persist the state of applicat At its very core, a Cosmos SDK `store` is an object that holds a `CacheWrapper` and has a `GetStoreType()` method: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L15-L18 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/store.go#L16-L19 The `GetStoreType` is a simple method that returns the type of store, whereas a `CacheWrapper` is a simple interface that implements store read caching and write branching through `Write` method: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L240-L264 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/store.go#L247-L277 Branching and cache is used ubiquitously in the Cosmos SDK and required to be implemented on every store type. A storage branch creates an isolated, ephemeral branch of a store that can be passed around and updated without affecting the main underlying store. This is used to trigger temporary state-transitions that may be reverted later should an error occur. Read more about it in [context](./context.md#Store-branching) @@ -70,11 +70,11 @@ Branching and cache is used ubiquitously in the Cosmos SDK and required to be im A commit store is a store that has the ability to commit changes made to the underlying tree or db. The Cosmos SDK differentiates simple stores from commit stores by extending the basic store interfaces with a `Committer`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L29-L33 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/store.go#L30-L34 The `Committer` is an interface that defines methods to persist changes to disk: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L20-L27 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/store.go#L21-L28 The `CommitID` is a deterministic commit of the state tree. Its hash is returned to the underlying consensus engine and stored in the block header. Note that commit store interfaces exist for various purposes, one of which is to make sure not every object can commit the store. As part of the [object-capabilities model](./ocap.md) of the Cosmos SDK, only `baseapp` should have the ability to commit stores. For example, this is the reason why the `ctx.KVStore()` method by which modules typically access stores returns a `KVStore` and not a `CommitKVStore`. @@ -86,7 +86,7 @@ The Cosmos SDK comes with many types of stores, the most used being [`CommitMult Each Cosmos SDK application holds a multistore at its root to persist its state. The multistore is a store of `KVStores` that follows the `Multistore` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L104-L133 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/store.go#L97-L133 If tracing is enabled, then branching the multistore will firstly wrap all the underlying `KVStore` in [`TraceKv.Store`](#tracekv-store). @@ -94,19 +94,19 @@ If tracing is enabled, then branching the multistore will firstly wrap all the u The main type of `Multistore` used in the Cosmos SDK is `CommitMultiStore`, which is an extension of the `Multistore` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L141-L184 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/store.go#L141-L187 As for concrete implementation, the [`rootMulti.Store`] is the go-to implementation of the `CommitMultiStore` interface. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/rootmulti/store.go#L43-L61 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/rootmulti/store.go#L38-L61 The `rootMulti.Store` is a base-layer multistore built around a `db` on top of which multiple `KVStores` can be mounted, and is the default multistore store used in [`baseapp`](./baseapp.md). ### CacheMultiStore -Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/store/cachemulti/store.go) is used. +Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/cachemulti/store.go) is used. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachemulti/store.go#L17-L28 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/cachemulti/store.go#L20-L36 `cachemulti.Store` branches all substores (creates a virtual store for each substore) in its constructor and hold them in `Store.stores`. Moreover caches all read queries. `Store.GetKVStore()` returns the store from `Store.stores`, and `Store.Write()` recursively calls `CacheWrap.Write()` on all the substores. @@ -120,31 +120,31 @@ Individual `KVStore`s are used by modules to manage a subset of the global state `CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../basics/app-anatomy.md#core-application-file). In the same file, the `key` is also passed to the module's `keeper` that is responsible for managing the store. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L189-L219 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/store.go#L192-L226 -Apart from the traditional `Get` and `Set` methods, a `KVStore` must provide an `Iterator(start, end)` method which returns an `Iterator` object. It is used to iterate over a range of keys, typically keys that share a common prefix. Below is an example from the bank's module keeper, used to iterate over all account balances: +Apart from the traditional `Get` and `Set` methods, that a `KVStore` must implement via the `BasicKVStore` interface; a `KVStore` must provide an `Iterator(start, end)` method which returns an `Iterator` object. It is used to iterate over a range of keys, typically keys that share a common prefix. Below is an example from the bank's module keeper, used to iterate over all account balances: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/bank/keeper/view.go#L115-L134 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/keeper/view.go#L114-L132 ### `IAVL` Store The default implementation of `KVStore` and `CommitKVStore` used in `baseapp` is the `iavl.Store`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/iavl/store.go#L37-L40 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/iavl/store.go#L37-L40 -`iavl` stores are based around an [IAVL Tree](https://github.com/tendermint/iavl), a self-balancing binary tree which guarantees that: +`iavl` stores are based around an [IAVL Tree](https://github.com/cosmos/iavl), a self-balancing binary tree which guarantees that: * `Get` and `Set` operations are O(log n), where n is the number of elements in the tree. * Iteration efficiently returns the sorted elements within the range. * Each tree version is immutable and can be retrieved even after a commit (depending on the pruning settings). -The documentation on the IAVL Tree is located [here](https://github.com/cosmos/iavl/blob/v0.15.0-rc5/docs/overview.md). +The documentation on the IAVL Tree is located [here](https://github.com/cosmos/iavl/blob/master/docs/overview.md). ### `DbAdapter` Store `dbadapter.Store` is a adapter for `dbm.DB` making it fulfilling the `KVStore` interface. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/dbadapter/store.go#L13-L16 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/dbadapter/store.go#L14-L17 `dbadapter.Store` embeds `dbm.DB`, meaning most of the `KVStore` interface functions are implemented. The other functions (mostly miscellaneous) are manually implemented. This store is primarily used within [Transient Stores](#transient-stores) @@ -152,17 +152,17 @@ The documentation on the IAVL Tree is located [here](https://github.com/cosmos/i `Transient.Store` is a base-layer `KVStore` which is automatically discarded at the end of the block. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/transient/store.go#L13-L16 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/transient/store.go#L16-L19 `Transient.Store` is a `dbadapter.Store` with a `dbm.NewMemDB()`. All `KVStore` methods are reused. When `Store.Commit()` is called, a new `dbadapter.Store` is assigned, discarding previous reference and making it garbage collected. This type of store is useful to persist information that is only relevant per-block. One example would be to store parameter changes (i.e. a bool set to `true` if a parameter changed in a block). -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/params/types/subspace.go#L20-L30 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/params/types/subspace.go#L21-L31 Transient stores are typically accessed via the [`context`](./context.md) via the `TransientStore()` method: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L232-L235 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/context.go#L264-L267 ## KVStore Wrappers @@ -170,7 +170,7 @@ Transient stores are typically accessed via the [`context`](./context.md) via th `cachekv.Store` is a wrapper `KVStore` which provides buffered writing / cached reading functionalities over the underlying `KVStore`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachekv/store.go#L27-L34 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/cachekv/store.go#L27-L35 This is the type used whenever an IAVL Store needs to be branched to create an isolated store (typically when we need to mutate a state that might be reverted later). @@ -188,27 +188,27 @@ This is the type used whenever an IAVL Store needs to be branched to create an i ### `GasKv` Store -Cosmos SDK applications use [`gas`](../basics/gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications. +Cosmos SDK applications use [`gas`](../basics/gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/gaskv/store.go#L13-L19 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/gaskv/store.go#L11-L17 When methods of the parent `KVStore` are called, `GasKv.Store` automatically consumes appropriate amount of gas depending on the `Store.gasConfig`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L153-L162 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/gas.go#L219-L228 By default, all `KVStores` are wrapped in `GasKv.Stores` when retrieved. This is done in the `KVStore()` method of the [`context`](./context.md): -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L227-L230 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/context.go#L259-L262 In this case, the default gas configuration is used: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L164-L175 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/types/gas.go#L230-L241 ### `TraceKv` Store `tracekv.Store` is a wrapper `KVStore` which provides operation tracing functionalities over the underlying `KVStore`. It is applied automatically by the Cosmos SDK on all `KVStore` if tracing is enabled on the parent `MultiStore`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/tracekv/store.go#L20-L43 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/tracekv/store.go#L20-L43 When each `KVStore` methods are called, `tracekv.Store` automatically logs `traceOperation` to the `Store.writer`. `traceOperation.Metadata` is filled with `Store.context` when it is not nil. `TraceContext` is a `map[string]interface{}`. @@ -216,7 +216,7 @@ When each `KVStore` methods are called, `tracekv.Store` automatically logs `trac `prefix.Store` is a wrapper `KVStore` which provides automatic key-prefixing functionalities over the underlying `KVStore`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/prefix/store.go#L15-L21 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/prefix/store.go#L16-L22 When `Store.{Get, Set}()` is called, the store forwards the call to its parent, with the key prefixed with the `Store.prefix`. @@ -226,9 +226,9 @@ When `Store.Iterator()` is called, it does not simply prefix the `Store.prefix`, `listenkv.Store` is a wrapper `KVStore` which provides state listening capabilities over the underlying `KVStore`. It is applied automatically by the Cosmos SDK on any `KVStore` whose `StoreKey` is specified during state streaming configuration. -Additional information about state streaming configuration can be found in the [store/streaming/README.md](https://github.com/cosmos/cosmos-sdk/tree/v0.46.0-alpha2/store/streaming). +Additional information about state streaming configuration can be found in the [store/streaming/README.md](https://github.com/cosmos/cosmos-sdk/tree/v0.46.0-rc1/store/streaming). -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.44.1/store/listenkv/store.go#L11-L18 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/store/listenkv/store.go#L11-L18 When `KVStore.Set` or `KVStore.Delete` methods are called, `listenkv.Store` automatically writes the operations to the set of `Store.listeners`. diff --git a/docs/core/tips.md b/docs/core/tips.md index a76c3564b758..2165f4bbcd38 100644 --- a/docs/core/tips.md +++ b/docs/core/tips.md @@ -26,15 +26,15 @@ The transaction tips flow happens in multiple steps. 2. The tipper drafts a transaction to be executed on the chain A. It can include chain A `Msg`s. However, instead of creating a normal transaction, they create the following `AuxSignerData` document: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta1/proto/cosmos/tx/v1beta1/tx.proto#L230-L249 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L230-L249 where we have defined `SignDocDirectAux` as: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta1/proto/cosmos/tx/v1beta1/tx.proto#L67-L93 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L67-L93 where `Tip` is defined as -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta1/proto/cosmos/tx/v1beta1/tx.proto#L219-L228 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L219-L228 Notice that this document doesn't sign over the final chain A fees. Instead, it includes a `Tip` field. It also doesn't include the whole `AuthInfo` object as in `SIGN_MODE_DIRECT`, only the minimum information needed by the tipper @@ -135,7 +135,7 @@ For both commands, the flag `--sign-mode=amino-json` is still available for hard ## Programmatic Usage -For the tipper, the SDK exposes a new transaction builder, the `AuxTxBuilder`, for generating an `AuxSignerData`. The API of `AuxTxBuilder` is defined [in `client/tx`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta1/client/tx/aux_builder.go#L16), and can be used as follows: +For the tipper, the SDK exposes a new transaction builder, the `AuxTxBuilder`, for generating an `AuxSignerData`. The API of `AuxTxBuilder` is defined [in `client/tx`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/tx/aux_builder.go#L16), and can be used as follows: ```go // Note: there's no need to use clientCtx.TxConfig anymore. diff --git a/docs/core/transactions.md b/docs/core/transactions.md index 66f3cd9a7efa..a0aabc3acee5 100644 --- a/docs/core/transactions.md +++ b/docs/core/transactions.md @@ -37,11 +37,11 @@ Every message in a transaction must be signed by the addresses specified by its The most used implementation of the `Tx` interface is the Protobuf `Tx` message, which is used in `SIGN_MODE_DIRECT`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L13-L26 Because Protobuf serialization is not deterministic, the Cosmos SDK uses an additional `TxRaw` type to denote the pinned bytes over which a transaction is signed. Any user can generate a valid `body` and `auth_info` for a transaction, and serialize these two messages using Protobuf. `TxRaw` then pins the user's exact binary representation of `body` and `auth_info`, called respectively `body_bytes` and `auth_info_bytes`. The document that is signed by all signers of the transaction is `SignDoc` (deterministically serialized using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md)): -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L47-L64 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L48-L65 Once signed by all signers, the `body_bytes`, `auth_info_bytes` and `signatures` are gathered into `TxRaw`, whose serialized bytes are broadcasted over the network. @@ -49,7 +49,7 @@ Once signed by all signers, the `body_bytes`, `auth_info_bytes` and `signatures` The legacy implementation of the `Tx` interface is the `StdTx` struct from `x/auth`: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdtx.go#L120-L130 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/migrations/legacytx/stdtx.go#L82-L92 The document signed by all signers is `StdSignDoc`: @@ -106,7 +106,7 @@ While messages contain the information for state transition logic, a transaction The `TxBuilder` interface contains data closely related with the generation of transactions, which an end-user can freely set to generate the desired transaction: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L32-L45 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/tx_config.go#L33-L50 * `Msg`s, the array of [messages](#messages) included in the transaction. * `GasLimit`, option chosen by the users for how to calculate how much gas they will need to pay. @@ -117,12 +117,12 @@ The `TxBuilder` interface contains data closely related with the generation of t As there are currently two sign modes for signing transactions, there are also two implementations of `TxBuilder`: -* [wrapper](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/tx/builder.go#L19-L33) for creating transactions for `SIGN_MODE_DIRECT`, -* [StdTxBuilder](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdtx_builder.go#L14-L20) for `SIGN_MODE_LEGACY_AMINO_JSON`. +* [wrapper](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/tx/builder.go#L18-L34) for creating transactions for `SIGN_MODE_DIRECT`, +* [StdTxBuilder](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/migrations/legacytx/stdtx_builder.go#L15-L21) for `SIGN_MODE_LEGACY_AMINO_JSON`. However, the two implementation of `TxBuilder` should be hidden away from end-users, as they should prefer using the overarching `TxConfig` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L21-L30 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/tx_config.go#L22-L31 `TxConfig` is an app-wide configuration for managing transactions. Most importantly, it holds the information about whether to sign each transaction with `SIGN_MODE_DIRECT` or `SIGN_MODE_LEGACY_AMINO_JSON`. By calling `txBuilder := txConfig.NewTxBuilder()`, a new `TxBuilder` will be created with the appropriate sign mode. @@ -152,9 +152,9 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake #### gRPC -[gRPC](https://grpc.io) is introduced in Cosmos SDK 0.40 as the main component for the Cosmos SDK's RPC layer. The principal usage of gRPC is in the context of modules' [`Query` services](../building-modules). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service: +[gRPC](https://grpc.io) is the main component for the Cosmos SDK's RPC layer. Its principal usage is in the context of modules' [`Query` services](../building-modules). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/service.proto ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/tx/v1beta1/service.proto The `Tx` service exposes a handful of utility functions, such as simulating a transaction or querying a transaction, and also one method to broadcast transactions. diff --git a/docs/core/upgrade.md b/docs/core/upgrade.md index 836a3236a9b6..bcccd4717227 100644 --- a/docs/core/upgrade.md +++ b/docs/core/upgrade.md @@ -10,11 +10,11 @@ Read and understand all the in-place store migration documentation before you ru Upgrade your app modules smoothly with custom in-place store migration logic. {synopsis} -The Cosmos SDK uses two methods to perform upgrades. +The Cosmos SDK uses two methods to perform upgrades: -* Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. See [Chain Upgrade Guide to v0.42](https://docs.cosmos.network/v0.42/migrations/chain-upgrade-guide-040.html). +* Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. -* Version v0.44 and later can perform upgrades in place to significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/upgrade.md) to set up your application modules to take advantage of in-place upgrades. +* Perform upgrades in place, which significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/upgrade.md) to set up your application modules to take advantage of in-place upgrades. This document provides steps to use the In-Place Store Migrations upgrade method. diff --git a/docs/intro/sdk-design.md b/docs/intro/sdk-design.md index afcbade1833d..e9f61be4e470 100644 --- a/docs/intro/sdk-design.md +++ b/docs/intro/sdk-design.md @@ -15,9 +15,11 @@ Here is a simplified view of how transactions are handled by an application buil ## `baseapp` -`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`](../basics/app-anatomy.md#core-application-file). See an example of this from the Cosmos SDK application tutorial: +`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`](../basics/app-anatomy.md#core-application-file). -+++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/app.go#L72-L92 +Here is an example of this from `simapp`, the Cosmos SDK demonstration app: + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/simapp/app.go#L154-L193 The goal of `baseapp` is to provide a secure interface between the store and the extensible state machine while defining as little about the state machine as possible (staying true to the ABCI). diff --git a/docs/ko/README.md b/docs/ko/README.md index d93846331483..387ae45dd494 100755 --- a/docs/ko/README.md +++ b/docs/ko/README.md @@ -1,3 +1,3 @@ # Cosmos SDK Documentation (Korean) -A Korean translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md#internationalization). A `v0.39` version of the documentation can be found [here](https://docs.cosmos.network/v0.39/kr/). +A Korean translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/main/docs/DOCS_README.md#internationalization). diff --git a/docs/migrations/README.md b/docs/migrations/README.md index 4b9f85863479..b5e08ec462f4 100644 --- a/docs/migrations/README.md +++ b/docs/migrations/README.md @@ -8,6 +8,6 @@ parent: This document contains all the migration guides to update your app and modules to the current Cosmos SDK. -1. [Chain Upgrade Guide to v0.44](./chain-upgrade-guide-044.md) -1. Chain Upgrade Guide to v0.45: no migration is required. See [Release Notes](https://github.com/cosmos/cosmos-sdk/blob/v0.45.0/RELEASE_NOTES.md) and [changelog](https://github.com/cosmos/cosmos-sdk/blob/v0.45.0/CHANGELOG.md) for the list of API and State Machine breaking changes. -1. [REST Endpoints Migration](./rest.md) +1. Chain Upgrade Guide to v0.46: + * See [UPGRADING.md (TODO)](https://github.com/cosmos/cosmos-sdk/blob/main/UPGRADING.md) for breaking changes and deprecations upgrade instructions. + * See [Release Notes](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/RELEASE_NOTES.md) and [changelog](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/CHANGELOG.md) for the exhaustive list of API and State Machine breaking changes. diff --git a/docs/migrations/chain-upgrade-guide-044.md b/docs/migrations/chain-upgrade-guide-044.md deleted file mode 100644 index 4e8adf01fba4..000000000000 --- a/docs/migrations/chain-upgrade-guide-044.md +++ /dev/null @@ -1,249 +0,0 @@ - - -# Chain Upgrade Guide to v0.44 - -This document provides guidelines for a chain upgrade from v0.42 to v0.44 and an example of the upgrade process using `simapp`. {synopsis} - -::: tip -You must upgrade to Stargate v0.42 before upgrading to v0.44. If you have not done so, please see [Chain Upgrade Guide to v0.42](/v0.42/migrations/chain-upgrade-guide-040.html). Please note, v0.43 was discontinued shortly after being released and all chains should upgrade directly to v0.44 from v0.42. -::: - -## Prerequisite Readings - -* [Upgrading Modules](../building-modules/upgrade.html) {prereq} -* [In-Place Store Migrations](../core/upgrade.html) {prereq} -* [Cosmovisor](../run-node/cosmovisor.html) {prereq} - -Cosmos SDK v0.44 introduces a new way of handling chain upgrades that no longer requires exporting state to JSON, making the necesssary changes, and then creating a new chain with the modified JSON as the new genesis file. - -The IBC module for the Cosmos SDK has moved to its [own repository](https://github.com/cosmos/ibc-go) for v0.42 and later versions. If you are using IBC, make sure to also go through the [IBC migration docs](https://github.com/cosmos/ibc-go/blob/main/docs/migrations/ibc-migration-043.md). - -Instead of starting a new chain, the upgrade binary will read the existing database and perform in-place store migrations. This new way of handling chain upgrades can be used alongside [Cosmovisor](../run-node/cosmovisor.html) to make the upgrade process seamless. - -## In-Place Store Migrations - -We recommend using [In-Place Store Migrations](../core/upgrade.html) to upgrade your chain from v0.42 to v0.44. The first step is to make sure all your modules follow the [Module Upgrade Guide](../building-modules/upgrade.html). The second step is to add an [upgrade handler](../core/upgrade.html#running-migrations) to `app.go`. - -In this document, we'll provide an example of what the upgrade handler looks like for a chain upgrading module versions for the first time. It's critical to note that the initial consensus version of each module must be set to `1` rather than `0` or else the upgrade handler will re-initialize each module. - -In addition to migrating existing modules, the upgrade handler also performs store upgrades for new modules. In the example below, we'll be adding store migrations for two new modules made available in v0.44: `x/authz` and `x/feegrant`. - -## Using Cosmovisor - -We recommend validators use [Cosmovisor](../run-node/cosmovisor.html), which is a process manager for running application binaries. For security reasons, we recommend validators build their own upgrade binaries rather than enabling the auto-download option. Validators may still choose to use the auto-download option if the necessary security guarantees are in place (i.e. the URL provided in the upgrade proposal for the downloadable upgrade binary includes a proper checksum). - -::: tip -If validators would like to enable the auto-download option, and they are currently running an application using Cosmos SDK `v0.42`, they will need to use Cosmovisor [`v0.1`](https://github.com/cosmos/cosmos-sdk/releases/tag/cosmovisor%2Fv0.1.0). Later versions of Cosmovisor do not support Cosmos SDK `v0.42` or earlier if the auto-download option is enabled. -::: - -Validators can use the auto-restart option to prevent unnecessary downtime during the upgrade process. The auto-restart option will automatically restart the chain with the upgrade binary once the chain has halted at the proposed upgrade height. With the auto-restart option, validators can prepare the upgrade binary in advance and then relax at the time of the upgrade. - -## Migrating app.toml - -With the update to `v0.44`, new server configuration options have been added to `app.toml`. The updates include new configuration sections for Rosetta and gRPC Web as well as a new configuration option for State Sync. Check out the default [`app.toml`](https://github.com/cosmos/cosmos-sdk/blob/release/v0.44.x/server/config/toml.go) file in the latest version of `v0.44` for more information. - -## Example: Simapp Upgrade - -The following example will walk through the upgrade process using `simapp` as our blockchain application. We will be upgrading `simapp` from v0.42 to v0.44. We will be building the upgrade binary ourselves and enabling the auto-restart option. - -::: tip -In the following example, we start a new chain from `v0.42`. The binary for this version will be the genesis binary. For validators using Cosmovisor for the first time on an existing chain, either the binary for the current version of the chain should be used as the genesis binary (i.e. the starting binary) or validators should update the `current` symbolic link to point to the upgrade directory. For more information, see [Cosmovisor](../run-node/cosmovisor.html). -::: - -### Initial Setup - -From within the `cosmos-sdk` repository, check out the latest `v0.42.x` release: - -```sh -git checkout release/v0.42.x -``` - -Build the `simd` binary for the latest `v0.42.x` release (the genesis binary): - -```sh -make build -``` - -Reset `~/.simapp` (never do this in a production environment): - -```sh -./build/simd unsafe-reset-all -``` - -Configure the `simd` binary for testing: - -```sh -./build/simd config chain-id test -./build/simd config keyring-backend test -./build/simd config broadcast-mode block -``` - -Initialize the node and overwrite any previous genesis file (never do this in a production environment): - - - -```sh -./build/simd init test --chain-id test --overwrite -``` - -Set the minimum gas price to `0stake` in `~/.simapp/config/app.toml`: - -```sh -minimum-gas-prices = "0stake" -``` - -For the purpose of this demonstration, change `voting_period` in `genesis.json` to a reduced time of 20 seconds (`20s`): - -```sh -cat <<< $(jq '.app_state.gov.voting_params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json -``` - -Create a new key for the validator, then add a genesis account and transaction: - - - - -```sh -./build/simd keys add validator -./build/simd add-genesis-account validator 5000000000stake --keyring-backend test -./build/simd gentx validator 1000000stake --chain-id test -./build/simd collect-gentxs -``` - -Now that our node is initialized and we are ready to start a new `simapp` chain, let's set up `cosmovisor` and the genesis binary. - -### Cosmovisor Setup - -Install the `cosmovisor` binary: - -```sh -go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v0.1.0 -``` - -::: tip -If you are using go `v1.15` or earlier, you will need to change out of the `cosmos-sdk` directory, run `go get` instead of `go install`, and then change back into the `cosmos-sdk` repository. -::: - -Set the required environment variables: - -```sh -export DAEMON_NAME=simd -export DAEMON_HOME=$HOME/.simapp -``` - -Set the optional environment variable to trigger an automatic restart: - -```sh -export DAEMON_RESTART_AFTER_UPGRADE=true -``` - -Create the folder for the genesis binary and copy the `v0.42.x` binary: - -```sh -mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin -cp ./build/simd $DAEMON_HOME/cosmovisor/genesis/bin -``` - -Now that `cosmovisor` is installed and the genesis binary has been added, let's add the upgrade handler to `simapp/app.go` and prepare the upgrade binary. - -### Chain Upgrade - - - -Check out `release/v0.44.x`: - -```sh -git checkout release/v0.44.x -``` - -Add the following to `simapp/app.go` inside `NewSimApp` and after `app.UpgradeKeeper`: - -```go - app.registerUpgradeHandlers() -``` - -Add the following to `simapp/app.go` after `NewSimApp` (to learn more about the upgrade handler, see the [In-Place Store Migrations](../core/upgrade.html)): - -```go -func (app *SimApp) registerUpgradeHandlers() { - app.UpgradeKeeper.SetUpgradeHandler("v0.44", func(ctx sdk.Context, plan upgradetypes.Plan, _ module.VersionMap) (module.VersionMap, error) { - // 1st-time running in-store migrations, using 1 as fromVersion to - // avoid running InitGenesis. - fromVM := map[string]uint64{ - "auth": 1, - "bank": 1, - "capability": 1, - "crisis": 1, - "distribution": 1, - "evidence": 1, - "gov": 1, - "mint": 1, - "params": 1, - "slashing": 1, - "staking": 1, - "upgrade": 1, - "vesting": 1, - "ibc": 1, - "genutil": 1, - "transfer": 1, - } - - return app.mm.RunMigrations(ctx, app.configurator, fromVM) - }) - - upgradeInfo, err := app.UpgradeKeeper.ReadUpgradeInfoFromDisk() - if err != nil { - panic(err) - } - - if upgradeInfo.Name == "v0.44" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) { - storeUpgrades := storetypes.StoreUpgrades{ - Added: []string{"authz", "feegrant"}, - } - - // configure store loader that checks if version == upgradeHeight and applies store upgrades - app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades)) - } -} -``` - -Add `storetypes` to imports: - -```go - storetypes "github.com/cosmos/cosmos-sdk/store/types" -``` - -Build the `simd` binary for `v0.44.x` (the upgrade binary): - -```sh -make build -``` - -Create the folder for the upgrade binary and copy the `v0.44.x` binary: - -```sh -mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v0.44/bin -cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/v0.44/bin -``` - -Now that we have added the upgrade handler and prepared the upgrade binary, we are ready to start `cosmovisor` and simulate the upgrade proposal process. - -### Upgrade Proposal - -Start the node using `cosmovisor`: - -```sh -cosmovisor start -``` - -Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other): - -```sh -./build/simd tx gov submit-proposal software-upgrade v0.44 --title upgrade --description upgrade --upgrade-height 20 --from validator --yes -./build/simd tx gov deposit 1 10000000stake --from validator --yes -./build/simd tx gov vote 1 yes --from validator --yes -``` - -Confirm the chain automatically upgrades at height 20. diff --git a/docs/migrations/rest.md b/docs/migrations/rest.md deleted file mode 100644 index 9a65a3d95c70..000000000000 --- a/docs/migrations/rest.md +++ /dev/null @@ -1,85 +0,0 @@ - - -# REST Endpoints Migration - -Migrate to gRPC-Gateway REST endpoints. Legacy REST endpoints were marked as deprecated in v0.40 and will be removed in v0.45. {synopsis} - -::: warning -Two Legacy REST endpoints (`POST /txs` and `POST /txs/encode`) were removed ahead of schedule in v0.44 due to a security vulnerability. -::: - -## Legacy REST Endpoints - -Cosmos SDK versions v0.39 and earlier registered REST endpoints using a package called `gorilla/mux`. These REST endpoints were marked as deprecated in v0.40 and have since been referred to as legacy REST endpoints. Legacy REST endpoints will be officially removed in v0.45. - -## gRPC-Gateway REST Endpoints - -Following the Protocol Buffers migration in v0.40, Cosmos SDK has been set to take advantage of a vast number of gRPC tools and solutions. v0.40 introduced new REST endpoints generated from [gRPC `Query` services](../building-modules/query-services.md) using [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/). These new REST endpoints are referred to as gRPC-Gateway REST endpoints. - -## Migrating to New REST Endpoints - -| Legacy REST Endpoint | Description | New gRPC-gateway REST Endpoint | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| `GET /txs/{hash}` | Query tx by hash | `GET /cosmos/tx/v1beta1/txs/{hash}` | -| `GET /txs` | Query tx by events | `GET /cosmos/tx/v1beta1/txs` | -| `POST /txs` | Broadcast tx | `POST /cosmos/tx/v1beta1/txs` | -| `POST /txs/encode` | Encodes an Amino JSON tx to an Amino binary tx | N/A, use Protobuf directly | -| `POST /txs/decode` | Decodes an Amino binary tx into an Amino JSON tx | N/A, use Protobuf directly | -| `POST /bank/*` | Create unsigned `Msg`s for bank tx | N/A, use Protobuf directly | -| `GET /bank/balances/{address}` | Get the balance of an address | `GET /cosmos/bank/v1beta1/balances/{address}` | -| `GET /bank/total` | Get the total supply of all coins | `GET /cosmos/bank/v1beta1/supply` | -| `GET /bank/total/{denom}` | Get the total supply of one coin | `GET /cosmos/bank/v1beta1/supply/{denom}` | -| `POST /distribution/delegators/{delegatorAddr}/rewards` | Withdraw all delegator rewards | N/A, use Protobuf directly | -| `POST /distribution/*` | Create unsigned `Msg`s for distribution | N/A, use Protobuf directly | -| `GET /distribution/delegators/{delegatorAddr}/rewards` | Get the total rewards balance from all delegations | `GET /cosmos/distribution/v1beta1/v1beta1/delegators/{delegator_address}/rewards` | -| `GET /distribution/delegators/{delegatorAddr}/rewards/{validatorAddr}` | Query a delegation reward | `GET /cosmos/distribution/v1beta1/delegators/{delegatorAddr}/rewards/{validatorAddr}` | -| `GET /distribution/delegators/{delegatorAddr}/withdraw_address` | Get the rewards withdrawal address | `GET /cosmos/distribution/v1beta1/delegators/{delegatorAddr}/withdraw_address` | -| `GET /distribution/validators/{validatorAddr}` | Validator distribution information | N/A | -| `GET /distribution/validators/{validatorAddr}/rewards` | Commission and outstanding rewards of a single a validator | `GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/commission`
`GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/outstanding_rewards` | -| `GET /distribution/validators/{validatorAddr}/outstanding_rewards` | Outstanding rewards of a single validator | `GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/outstanding_rewards` | -| `GET /distribution/parameters` | Get the current distribution parameter values | `GET /cosmos/distribution/v1beta1/params` | -| `GET /distribution/community_pool` | Get the amount held in the community pool | `GET /cosmos/distribution/v1beta1/community_pool` | -| `GET /evidence/{evidence-hash}` | Get evidence by hash | `GET /cosmos/evidence/v1beta1/evidence/{evidence_hash}` | -| `GET /evidence` | Get all evidence | `GET /cosmos/evidence/v1beta1/evidence` | -| `POST /gov/*` | Create unsigned `Msg`s for gov | N/A, use Protobuf directly | -| `GET /gov/parameters/{type}` | Get government parameters | `GET /cosmos/gov/v1beta1/params/{type}` | -| `GET /gov/proposals` | Get all proposals | `GET /cosmos/gov/v1beta1/proposals` | -| `GET /gov/proposals/{proposal-id}` | Get proposal by id | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}` | -| `GET /gov/proposals/{proposal-id}/proposer` | Get proposer of a proposal | N/A, use Query tx by events endpoint | -| `GET /gov/proposals/{proposal-id}/deposits` | Get deposits of a proposal | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/deposits` | -| `GET /gov/proposals/{proposal-id}/deposits/{depositor}` | Get depositor a of deposit | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/deposits/{depositor}` | -| `GET /gov/proposals/{proposal-id}/tally` | Get tally of a proposal | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/tally` | -| `GET /gov/proposals/{proposal-id}/votes` | Get votes of a proposal | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/votes` | -| `GET /gov/proposals/{proposal-id}/votes/{vote}` | Get a particular vote | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/votes/{vote}` | -| `GET /minting/parameters` | Get parameters for minting | `GET /cosmos/minting/v1beta1/params` | -| `GET /minting/inflation` | Get minting inflation | `GET /cosmos/minting/v1beta1/inflation` | -| `GET /minting/annual-provisions` | Get minting annual provisions | `GET /cosmos/minting/v1beta1/annual_provisions` | -| `POST /slashing/*` | Create unsigned `Msg`s for slashing | N/A, use Protobuf directly | -| `GET /slashing/validators/{validatorPubKey}/signing_info` | Get validator signing info | `GET /cosmos/slashing/v1beta1/signing_infos/{cons_address}` (Use consensus address instead of pubkey) | -| `GET /slashing/signing_infos` | Get all signing infos | `GET /cosmos/slashing/v1beta1/signing_infos` | -| `GET /slashing/parameters` | Get slashing parameters | `GET /cosmos/slashing/v1beta1/params` | -| `POST /staking/*` | Create unsigned `Msg`s for staking | N/A, use Protobuf directly | -| `GET /staking/delegators/{delegatorAddr}/delegations` | Get all delegations from a delegator | `GET /cosmos/staking/v1beta1/delegations/{delegatorAddr}` | -| `GET /staking/delegators/{delegatorAddr}/unbonding_delegations` | Get all unbonding delegations from a delegator | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations` | -| `GET /staking/delegators/{delegatorAddr}/txs` | Get all staking txs (i.e msgs) from a delegator | Removed | -| `GET /staking/delegators/{delegatorAddr}/validators` | Query all validators that a delegator is bonded to | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators` | -| `GET /staking/delegators/{delegatorAddr}/validators/{validatorAddr}` | Query a validator that a delegator is bonded to | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators/{validatorAddr}` | -| `GET /staking/delegators/{delegatorAddr}/delegations/{validatorAddr}` | Query a delegation between a delegator and a validator | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations/{delegatorAddr}` | -| `GET /staking/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}` | Query all unbonding delegations between a delegator and a validator | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}` | -| `GET /staking/redelegations` | Query redelegations | `GET /cosmos/staking/v1beta1/v1beta1/delegators/{delegator_addr}/redelegations` | -| `GET /staking/validators` | Get all validators | `GET /cosmos/staking/v1beta1/validators` | -| `GET /staking/validators/{validatorAddr}` | Get a single validator info | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}` | -| `GET /staking/validators/{validatorAddr}/delegations` | Get all delegations to a validator | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations` | -| `GET /staking/validators/{validatorAddr}/unbonding_delegations` | Get all unbonding delegations from a validator | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/unbonding_delegations` | -| `GET /staking/historical_info/{height}` | Get HistoricalInfo at a given height | `GET /cosmos/staking/v1beta1/historical_info/{height}` | -| `GET /staking/pool` | Get the current state of the staking pool | `GET /cosmos/staking/v1beta1/pool` | -| `GET /staking/parameters` | Get the current staking parameter values | `GET /cosmos/staking/v1beta1/params` | -| `POST /upgrade/*` | Create unsigned `Msg`s for upgrade | N/A, use Protobuf directly | -| `GET /upgrade/current` | Get the current plan | `GET /cosmos/upgrade/v1beta1/current_plan` | -| `GET /upgrade/applied_plan/{name}` | Get a previously applied plan | `GET /cosmos/upgrade/v1beta1/applied/{name}` | - -## Migrating to gRPC - -Instead of hitting REST endpoints as described above, the Cosmos SDK also exposes a gRPC server. Any client can use gRPC instead of REST to interact with the node. An overview of different ways to communicate with a node can be found [here](../core/grpc_rest.md), and a concrete tutorial for setting up a gRPC client can be found [here](../run-node/txs.md#programmatically-with-go). diff --git a/docs/ru/README.md b/docs/ru/README.md index e6906b2b89b3..fa21b98e8474 100755 --- a/docs/ru/README.md +++ b/docs/ru/README.md @@ -1,3 +1,3 @@ # Cosmos SDK Documentation (Russian) -A Russian translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md#internationalization). A `v0.39` version of the documentation can be found [here](https://github.com/cosmos/cosmos-sdk/tree/v0.39.3/docs/ru). +A Russian translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/main/docs/DOCS_README.md#internationalization). diff --git a/docs/run-node/interact-node.md b/docs/run-node/interact-node.md index 13cfb86d5369..0daf04e51c5c 100644 --- a/docs/run-node/interact-node.md +++ b/docs/run-node/interact-node.md @@ -109,16 +109,16 @@ Assuming the state at that block has not yet been pruned by the node, this query The following snippet shows how to query the state using gRPC inside a Go program. The idea is to create a gRPC connection, and use the Protobuf-generated client code to query the gRPC server. -#### Install cosmos sdk +#### Install Cosmos SDK Add below line to `go.mod` to replace protobuf, read more [#8469](https://github.com/cosmos/cosmos-sdk/issues/8469) -``` +```go replace github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1 ``` ```bash -$ go get github.com/cosmos/cosmos-sdk@main +go get github.com/cosmos/cosmos-sdk@main ``` ```go diff --git a/docs/run-node/keyring.md b/docs/run-node/keyring.md index 5197c382b71c..8506ef4c04b4 100644 --- a/docs/run-node/keyring.md +++ b/docs/run-node/keyring.md @@ -110,7 +110,7 @@ The `memory` backend stores keys in memory. The keys are immediately deleted aft Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets. ::: -Applications developed using the Cosmos SDK come with the `keys` subcommand. For the purpose of this tutorial, we're running the `simd` CLI, which is an application built using the Cosmos SDK for testing and educational purposes. For more information, see [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc3/simapp). +Applications developed using the Cosmos SDK come with the `keys` subcommand. For the purpose of this tutorial, we're running the `simd` CLI, which is an application built using the Cosmos SDK for testing and educational purposes. For more information, see [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). You can use `simd keys` for help about the keys command and `simd keys [command] --help` for more information about a particular subcommand. diff --git a/docs/run-node/rosetta.md b/docs/run-node/rosetta.md index c1a6a5cc93a4..e3d94492f00d 100644 --- a/docs/run-node/rosetta.md +++ b/docs/run-node/rosetta.md @@ -28,7 +28,7 @@ After that line, add the following: ```go rootCmd.AddCommand( - server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Marshaler) + server.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Codec) ) ``` diff --git a/docs/run-node/run-node.md b/docs/run-node/run-node.md index 6f70b490d628..4a1c63206f32 100644 --- a/docs/run-node/run-node.md +++ b/docs/run-node/run-node.md @@ -4,7 +4,7 @@ order: 2 # Running a Node -Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc3/simapp), and its corresponding CLI binary `simd`. {synopsis} +Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp), and its corresponding CLI binary `simd`. {synopsis} ## Pre-requisite Readings @@ -67,7 +67,7 @@ Now that you have created a local account, go ahead and grant it some `stake` to simd add-genesis-account $MY_VALIDATOR_ADDRESS 100000000000stake ``` -Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is is a 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc3/simapp). For your own chain with its own staking denom, that token identifier should be used instead. +Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is is a 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). For your own chain with its own staking denom, that token identifier should be used instead. Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../intro/sdk-app-architecture.md#tendermint)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`: @@ -123,7 +123,7 @@ You should see blocks come in. The previous command allow you to run a single node. This is enough for the next section on interacting with this node, but you may wish to run multiple nodes at the same time, and see how consensus happens between them. -The naive way would be to run the same commands again in separate terminal windows. This is possible, however in the Cosmos SDK, we leverage the power of [Docker Compose](https://docs.docker.com/compose/) to run a localnet. If you need inspiration on how to set up your own localnet with Docker Compose, you can have a look at the Cosmos SDK's [`docker-compose.yml`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/docker-compose.yml). +The naive way would be to run the same commands again in separate terminal windows. This is possible, however in the Cosmos SDK, we leverage the power of [Docker Compose](https://docs.docker.com/compose/) to run a localnet. If you need inspiration on how to set up your own localnet with Docker Compose, you can have a look at the Cosmos SDK's [`docker-compose.yml`](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/docker-compose.yml). ## Next {hide} diff --git a/docs/run-node/txs.md b/docs/run-node/txs.md index e5796a533e41..9674d32f4eed 100644 --- a/docs/run-node/txs.md +++ b/docs/run-node/txs.md @@ -144,7 +144,7 @@ priv2, _, addr2 := testdata.KeyTestPubAddr() priv3, _, addr3 := testdata.KeyTestPubAddr() ``` -Populating the `TxBuilder` can be done via its [methods](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/client/tx_config.go#L32-L45): +Populating the `TxBuilder` can be done via its [methods](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/tx_config.go#L33-L50): ```go import ( @@ -177,7 +177,7 @@ At this point, `TxBuilder`'s underlying transaction is ready to be signed. ### Signing a Transaction -We set encoding config to use Protobuf, which will use `SIGN_MODE_DIRECT` by default. As per [ADR-020](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/docs/architecture/adr-020-protobuf-transaction-encoding.md), each signer needs to sign the `SignerInfo`s of all other signers. This means that we need to perform two steps sequentially: +We set encoding config to use Protobuf, which will use `SIGN_MODE_DIRECT` by default. As per [ADR-020](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-020-protobuf-transaction-encoding.md), each signer needs to sign the `SignerInfo`s of all other signers. This means that we need to perform two steps sequentially: * for each signer, populate the signer's `SignerInfo` inside `TxBuilder`, * once all `SignerInfo`s are populated, for each signer, sign the `SignDoc` (the payload to be signed). diff --git a/docs/versions b/docs/versions index 23488cf36132..6fdd15d21b83 100644 --- a/docs/versions +++ b/docs/versions @@ -1,4 +1,5 @@ release/v0.44.x v0.44 release/v0.45.x v0.45 +release/v0.46.x v0.46 main master main main diff --git a/docs/zh/README.md b/docs/zh/README.md index 5cd44487a6f7..095fa073d031 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -1,3 +1,3 @@ # Cosmos SDK Documentation (Chinese) -A Chinese translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOCS_README.md#internationalization). A `v0.39` version of the documentation can be found [here](https://docs.cosmos.network/v0.39/cn/). +A Chinese translation of the Cosmos SDK documentation is not available for this version. If you would like to help with translating, please see [Internationalization](https://github.com/cosmos/cosmos-sdk/blob/main/docs/DOCS_README.md#internationalization). diff --git a/snapshots/README.md b/snapshots/README.md index db0247a61673..1c80f05d5633 100644 --- a/snapshots/README.md +++ b/snapshots/README.md @@ -69,9 +69,10 @@ the snapshot that was triggered at height `900` **just finishes**. Then, we can Let's now assume that all conditions stay the same but the snapshot at height 900 is **not complete yet**. Then, we cannot prune it to avoid deleting a height that is still being snapshotted. Therefore, we keep track of this height until the snapshot is complete. The height 900 will be pruned at the first height h that satisfied the following conditions: -- the snapshot is complete -- h is a multiple of `pruning-interval` -- snapshot height is less than h - `pruning-keep-recent` + +* the snapshot is complete +* h is a multiple of `pruning-interval` +* snapshot height is less than h - `pruning-keep-recent` Note that in both examples, if we let current height = C, and previous height P = C - 1, then for every height h that is: @@ -86,14 +87,14 @@ to determine which heights are to be pruned (959 - 50 - 10 = 899-909 = 959 - 50) ## Configuration -- `state-sync.snapshot-interval` - * the interval at which to take snapshots. - * the value of 0 disables snapshots. - * if pruning is enabled, it is done after a snapshot is complete for the heights that are multiples of this interval. +* `state-sync.snapshot-interval` + * the interval at which to take snapshots. + * the value of 0 disables snapshots. + * if pruning is enabled, it is done after a snapshot is complete for the heights that are multiples of this interval. -- `state-sync.snapshot-keep-recent`: - * the number of recent snapshots to keep. - * 0 means keep all. +* `state-sync.snapshot-keep-recent`: + * the number of recent snapshots to keep. + * 0 means keep all. ## Snapshot Metadata @@ -180,14 +181,14 @@ Snapshots are generated by `rootmulti.Store.Snapshot()` as follows: 1. Iterate over each IAVL store in lexicographical order by store name. 2. Emit a `SnapshotStoreItem` containing the store name. 3. Start an IAVL export for the store using - [`iavl.ImmutableTree.Export()`](https://pkg.go.dev/github.com/tendermint/iavl#ImmutableTree.Export). + [`iavl.ImmutableTree.Export()`](https://pkg.go.dev/github.com/cosmos/iavl#ImmutableTree.Export). 4. Iterate over each IAVL node. 5. Emit a `SnapshotIAVLItem` for the IAVL node. 2. Pass the serialized Protobuf output stream to a zlib compression writer. 3. Split the zlib output stream into chunks at exactly every 10th megabyte. Snapshots are restored via `rootmulti.Store.Restore()` as the inverse of the above, using -[`iavl.MutableTree.Import()`](https://pkg.go.dev/github.com/tendermint/iavl#MutableTree.Import) +[`iavl.MutableTree.Import()`](https://pkg.go.dev/github.com/cosmos/iavl#MutableTree.Import) to reconstruct each IAVL tree. ## Snapshot Storage diff --git a/store/README.md b/store/README.md index 3b1c81a0595a..115f9816be93 100644 --- a/store/README.md +++ b/store/README.md @@ -56,7 +56,7 @@ type Store struct { 2. Iteration efficiently returns the sorted elements within the range 3. Each tree version is immutable and can be retrieved even after a commit(depending on the pruning settings) -Specification and implementation of IAVL tree can be found in https://github.com/tendermint/iavl. +Specification and implementation of IAVL tree can be found in https://github.com/cosmos/iavl. ## GasKV diff --git a/store/streaming/README.md b/store/streaming/README.md index 46e343416a52..3118ceed9834 100644 --- a/store/streaming/README.md +++ b/store/streaming/README.md @@ -1,7 +1,7 @@ # State Streaming Service This package contains the constructors for the `StreamingService`s used to write state changes out from individual KVStores to a -file or stream, as described in [ADR-038](../../docs/architecture/adr-038-state-listening.md) and defined in [types/streaming.go](../../baseapp/streaming.go). +file or stream, as described in [ADR-038](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-038-state-listening.md) and defined in [types/streaming.go](https://github.com/cosmos/cosmos-sdk/blob/main/baseapp/streaming.go). The child directories contain the implementations for specific output destinations. Currently, a `StreamingService` implementation that writes state changes out to files is supported, in the future support for additional diff --git a/types/address.go b/types/address.go index 5fd3fa051b32..3da2bffdfd38 100644 --- a/types/address.go +++ b/types/address.go @@ -117,9 +117,8 @@ type Address interface { } // Ensure that different address types implement the interface -var _ Address = AccAddress{} - var ( + _ Address = AccAddress{} _ Address = ValAddress{} _ Address = ConsAddress{} ) diff --git a/types/address/README.md b/types/address/README.md index 92c092e04680..473838090eea 100644 --- a/types/address/README.md +++ b/types/address/README.md @@ -4,4 +4,4 @@ This package defines Cosmos SDK address-related functions. ## References -* [ADR-028](../../docs/architecture/adr-028-public-key-addresses.md) +* [ADR-028](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-028-public-key-addresses.md) diff --git a/types/kv/list.go b/types/kv/list.go index 9e928c84912b..2b0793d343cd 100644 --- a/types/kv/list.go +++ b/types/kv/list.go @@ -1,6 +1,6 @@ package kv -// This code was copied from golang.org/pkg/container/list, but specially adapted +// This code was copied from pkg.go.dev/container/list, but specially adapted // for use with kv.Pair to avoid the type assertion CPU expense of using Value with // an interface, per https://github.com/cosmos/cosmos-sdk/issues/8810 // diff --git a/x/auth/spec/03_antehandlers.md b/x/auth/spec/03_antehandlers.md index b695d8597dc5..3227d8dff276 100644 --- a/x/auth/spec/03_antehandlers.md +++ b/x/auth/spec/03_antehandlers.md @@ -5,7 +5,7 @@ order: 3 # AnteHandlers The `x/auth` module presently has no transaction handlers of its own, but does expose the special `AnteHandler`, used for performing basic validity checks on a transaction, such that it could be thrown out of the mempool. -The `AnteHandler` can be seen as a set of decorators that check transactions within the current context, per [ADR 010](https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/docs/architecture/adr-010-modular-antehandler.md). +The `AnteHandler` can be seen as a set of decorators that check transactions within the current context, per [ADR 010](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-010-modular-antehandler.md). Note that the `AnteHandler` is called on both `CheckTx` and `DeliverTx`, as Tendermint proposers presently have the ability to include in their proposed block transactions which fail `CheckTx`. diff --git a/x/auth/spec/05_vesting.md b/x/auth/spec/05_vesting.md index ec3b3a76086a..2108c658c6a6 100644 --- a/x/auth/spec/05_vesting.md +++ b/x/auth/spec/05_vesting.md @@ -100,19 +100,19 @@ type VestingAccount interface { ### BaseVestingAccount -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L10-L33 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/vesting/v1beta1/vesting.proto#L10-L24 ### ContinuousVestingAccount -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L35-L43 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/vesting/v1beta1/vesting.proto#L26-L34 ### DelayedVestingAccount -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L45-L53 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/vesting/v1beta1/vesting.proto#L36-L44 ### Period -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L56-L62 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/vesting/v1beta1/vesting.proto#L46-L53 ```go // Stores all vesting periods passed as part of a PeriodicVestingAccount @@ -122,7 +122,7 @@ type Periods []Period ### PeriodicVestingAccount -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L64-L73 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/vesting/v1beta1/vesting.proto#L55-L64 In order to facilitate less ad-hoc type checking and assertions and to support flexibility in account balance usage, the existing `x/bank` `ViewKeeper` interface @@ -142,7 +142,7 @@ type ViewKeeper interface { ### PermanentLockedAccount -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L78-L83 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/vesting/v1beta1/vesting.proto#L55-L64 ## Vesting Account Specification diff --git a/x/authz/spec/01_concepts.md b/x/authz/spec/01_concepts.md index 9fa522ae5c10..ffe810b599bf 100644 --- a/x/authz/spec/01_concepts.md +++ b/x/authz/spec/01_concepts.md @@ -7,14 +7,14 @@ order: 1 ## Authorization and Grant The `x/authz` module defines interfaces and messages grant authorizations to perform actions -on behalf of one account to other accounts. The design is defined in the [ADR 030](../../../docs/architecture/adr-030-authz-module.md). +on behalf of one account to other accounts. The design is defined in the [ADR 030](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-030-authz-module.md). A *grant* is an allowance to execute a Msg by the grantee on behalf of the granter. Authorization is an interface that must be implemented by a concrete authorization logic to validate and execute grants. Authorizations are extensible and can be defined for any Msg service method even outside of the module where the Msg method is defined. See the `SendAuthorization` example in the next section for more details. **Note:** The authz module is different from the [auth (authentication)](../modules/auth/) module that is responsible for specifying the base transaction and account types. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/authorizations.go#L11-L25 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/authz/authorizations.go#L11-L25 ## Built-in Authorizations @@ -24,9 +24,9 @@ The Cosmos SDK `x/authz` module comes with following authorization types: `GenericAuthorization` implements the `Authorization` interface that gives unrestricted permission to execute the provided Msg on behalf of granter's account. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L14-L19 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/authz/v1beta1/authz.proto#L13-L20 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/generic_authorization.go#L18-L31 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/authz/generic_authorization.go#L16-L29 * `msg` stores Msg type URL. @@ -34,9 +34,9 @@ The Cosmos SDK `x/authz` module comes with following authorization types: `SendAuthorization` implements the `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg. It takes a (positive) `SpendLimit` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/bank/v1beta1/authz.proto#L10-L19 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/bank/v1beta1/authz.proto#L10-L19 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/types/send_authorization.go#L25-L40 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/bank/types/send_authorization.go#L23-L38 * `spend_limit` keeps track of how many coins are left in the authorization. @@ -44,9 +44,9 @@ The Cosmos SDK `x/authz` module comes with following authorization types: `StakeAuthorization` implements the `Authorization` interface for messages in the [staking module](https://docs.cosmos.network/v0.44/modules/staking/). It takes an `AuthorizationType` to specify whether you want to authorise delegating, undelegating or redelegating (i.e. these have to be authorised seperately). It also takes a required `MaxTokens` that keeps track of a limit to the amount of tokens that can be delegated/undelegated/redelegated. If left empty, the amount is unlimited. Additionally, this Msg takes an `AllowList` or a `DenyList`, which allows you to select which validators you allow or deny grantees to stake with. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/staking/v1beta1/authz.proto#L11-L31 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/authz.proto#L10-L33 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/staking/types/authz.go#L18-L38 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/staking/types/authz.go#L15-L35 ## Gas diff --git a/x/authz/spec/03_messages.md b/x/authz/spec/03_messages.md index 8afdcf187c4d..2dfca9c7c6c9 100644 --- a/x/authz/spec/03_messages.md +++ b/x/authz/spec/03_messages.md @@ -11,7 +11,7 @@ In this section we describe the processing of messages for the authz module. An authorization grant is created using the `MsgGrant` message. If there is already a grant for the `(granter, grantee, Authorization)` triple, then the new grant overwrites the previous one. To update or extend an existing grant, a new grant with the same `(granter, grantee, Authorization)` triple should be created. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L32-L37 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L32-L41 The message handling should fail if: @@ -24,7 +24,7 @@ The message handling should fail if: A grant can be removed with the `MsgRevoke` message. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L60-L64 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L66-L72 The message handling should fail if: @@ -37,7 +37,7 @@ NOTE: The `MsgExec` message removes a grant if the grant has expired. When a grantee wants to execute a transaction on behalf of a granter, they must send `MsgExec`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L47-L53 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L51-L59 The message handling should fail if: diff --git a/x/authz/spec/README.md b/x/authz/spec/README.md index 3eda2ae6ab8c..ac73d76dba3a 100644 --- a/x/authz/spec/README.md +++ b/x/authz/spec/README.md @@ -11,7 +11,7 @@ parent: ## Abstract -`x/authz` is an implementation of a Cosmos SDK module, per [ADR 30](../../../docs/architecture/adr-030-authz-module.md), that allows +`x/authz` is an implementation of a Cosmos SDK module, per [ADR 30](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-030-authz-module.md), that allows granting arbitrary privileges from one account (the granter) to another account (the grantee). Authorizations must be granted for a particular Msg service method one by one using an implementation of the `Authorization` interface. 1. **[Concept](01_concepts.md)** diff --git a/x/bank/migrations/v042/types.go b/x/bank/migrations/v042/types.go index bbfba526e9b3..ae24a0ebe9f4 100644 --- a/x/bank/migrations/v042/types.go +++ b/x/bank/migrations/v042/types.go @@ -49,7 +49,7 @@ func AddressFromBalancesStore(key []byte) sdk.AccAddress { // SupplyI defines an inflationary supply interface for modules that handle // token supply. // It is copy-pasted from: -// https://github.com/cosmos/cosmos-sdk/blob/v042.3/x/bank/exported/exported.go +// https://github.com/cosmos/cosmos-sdk/blob/v0.42.3/x/bank/exported/exported.go // where we stripped off the unnecessary methods. // // It is used in the migration script, because we save this interface as an Any diff --git a/x/bank/spec/03_messages.md b/x/bank/spec/03_messages.md index 6e2913d34d76..a6d2379458cf 100644 --- a/x/bank/spec/03_messages.md +++ b/x/bank/spec/03_messages.md @@ -7,7 +7,8 @@ order: 3 ## MsgSend Send coins from one address to another. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L19-L28 + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L21-L32 The message will fail under the following conditions: @@ -17,7 +18,7 @@ The message will fail under the following conditions: ## MsgMultiSend Send coins from and to a series of different address. If any of the receiving addresses do not correspond to an existing account, a new account is created. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L33-L39 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L37-L45 The message will fail under the following conditions: diff --git a/x/capability/spec/README.md b/x/capability/spec/README.md index db5289df5bc2..96a2dcbd9726 100644 --- a/x/capability/spec/README.md +++ b/x/capability/spec/README.md @@ -9,7 +9,7 @@ parent: ## Overview -`x/capability` is an implementation of a Cosmos SDK module, per [ADR 003](./../../../docs/architecture/adr-003-dynamic-capability-store.md), +`x/capability` is an implementation of a Cosmos SDK module, per [ADR 003](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-003-dynamic-capability-store.md), that allows for provisioning, tracking, and authenticating multi-owner capabilities at runtime. diff --git a/x/crisis/spec/02_messages.md b/x/crisis/spec/02_messages.md index 7df7a62bb1e9..ca3b650f5ef0 100644 --- a/x/crisis/spec/02_messages.md +++ b/x/crisis/spec/02_messages.md @@ -11,7 +11,7 @@ corresponding updates to the state. Blockchain invariants can be checked using the `MsgVerifyInvariant` message. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/crisis/v1beta1/tx.proto#L14-L22 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/crisis/v1beta1/tx.proto#L16-L26 This message is expected to fail if: diff --git a/x/distribution/spec/02_state.md b/x/distribution/spec/02_state.md index 2e91b52f4437..e914ce25364d 100644 --- a/x/distribution/spec/02_state.md +++ b/x/distribution/spec/02_state.md @@ -27,7 +27,7 @@ type DecCoin struct { } ``` -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/distribution.proto#L94-L101 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/distribution/v1beta1/distribution.proto#L92-L96 ## Validator Distribution diff --git a/x/distribution/spec/04_messages.md b/x/distribution/spec/04_messages.md index b9b0b9d32e23..87d608842e5b 100644 --- a/x/distribution/spec/04_messages.md +++ b/x/distribution/spec/04_messages.md @@ -13,7 +13,7 @@ The withdraw address cannot be any of the module accounts. These accounts are bl Response: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L29-L37 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L31-L41 ```go func (k Keeper) SetWithdrawAddr(ctx sdk.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error @@ -63,7 +63,7 @@ The final calculated stake is equivalent to the actual staked coins in the deleg Response: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L46-L56 ## WithdrawValidatorCommission diff --git a/x/epoching/spec/03_to_improve.md b/x/epoching/spec/03_to_improve.md index 4794faafc292..7215629769d0 100644 --- a/x/epoching/spec/03_to_improve.md +++ b/x/epoching/spec/03_to_improve.md @@ -35,7 +35,7 @@ In this case, unbonding should start instantly. // — the simulator should check that the sum of all the queued delegations always equals the amount kept track in the data // — Staking/Slashing/Distribution module params are being modified by governance based on vote result instantly. We should test the effect. // — — Should test to see what would happen if max_validators is changed though, in the middle of an epoch -// — we should define some new invariants that help check that everything is working smoothly with these new changes for 3 modules e.g. https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/keeper/invariants.go +// — we should define some new invariants that help check that everything is working smoothly with these new changes for 3 modules e.g. https://github.com/cosmos/cosmos-sdk/blob/main/x/staking/keeper/invariants.go // — — Within Epoch, ValidationPower = ValidationPower - SlashAmount // — — When epoch actions queue is empty, EpochDelegationPool balance should be zero // — we should count all the delegation changes that happen during the epoch, and then make sure that the resulting change at the end of the epoch is actually correct diff --git a/x/evidence/spec/README.md b/x/evidence/spec/README.md index dd72780164e7..a6b3d92054d1 100644 --- a/x/evidence/spec/README.md +++ b/x/evidence/spec/README.md @@ -20,7 +20,7 @@ parent: ## Abstract -`x/evidence` is an implementation of a Cosmos SDK module, per [ADR 009](./../../../docs/architecture/adr-009-evidence-module.md), +`x/evidence` is an implementation of a Cosmos SDK module, per [ADR 009](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-009-evidence-module.md), that allows for the submission and handling of arbitrary evidence of misbehavior such as equivocation and counterfactual signing. diff --git a/x/feegrant/spec/01_concepts.md b/x/feegrant/spec/01_concepts.md index 523ff3e94fe0..85510bf0c898 100644 --- a/x/feegrant/spec/01_concepts.md +++ b/x/feegrant/spec/01_concepts.md @@ -8,11 +8,11 @@ order: 1 `Grant` is stored in the KVStore to record a grant with full context. Every grant will contain `granter`, `grantee` and what kind of `allowance` is granted. `granter` is an account address who is giving permission to `grantee` (the beneficiary account address) to pay for some or all of `grantee`'s transaction fees. `allowance` defines what kind of fee allowance (`BasicAllowance` or `PeriodicAllowance`, see below) is granted to `grantee`. `allowance` accepts an interface which implements `FeeAllowanceI`, encoded as `Any` type. There can be only one existing fee grant allowed for a `grantee` and `granter`, self grants are not allowed. -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L75-L81 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L76-L77 `FeeAllowanceI` looks like: -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/fees.go#L9-L32 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/feegrant/fees.go#L9-L32 ## Fee Allowance types @@ -26,7 +26,7 @@ There are two types of fee allowances present at the moment: `BasicAllowance` is permission for `grantee` to use fee from a `granter`'s account. If any of the `spend_limit` or `expiration` reaches its limit, the grant will be removed from the state. -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L13-L26 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L13-L26 * `spend_limit` is the limit of coins that are allowed to be used from the `granter` account. If it is empty, it assumes there's no spend limit, `grantee` can use any number of available tokens from `granter` account address before the expiration. @@ -38,7 +38,7 @@ There are two types of fee allowances present at the moment: `PeriodicAllowance` is a repeating fee allowance for the mentioned period, we can mention when the grant can expire as well as when a period can reset. We can also define the maximum number of coins that can be used in a mentioned period of time. -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L28-L73 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L29-L54 * `basic` is the instance of `BasicAllowance` which is optional for periodic fee allowance. If empty, the grant will have no `expiration` and no `spend_limit`. @@ -54,7 +54,7 @@ There are two types of fee allowances present at the moment: `AllowedMsgAllowance` is a fee allowance, it can be any of `BasicFeeAllowance`, `PeriodicAllowance` but restricted only to the allowed messages mentioned by the granter. -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L55-L65 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L56-L66 * `allowance` is either `BasicAllowance` or `PeriodicAllowance`. @@ -64,13 +64,13 @@ There are two types of fee allowances present at the moment: `feegrant` module introduces a `FeeGranter` flag for CLI for the sake of executing transactions with fee granter. When this flag is set, `clientCtx` will append the granter account address for transactions generated through CLI. -+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/cmd.go#L224-L235 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/cmd.go#L236-L246 -+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/tx/tx.go#L120 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/client/tx/tx.go#L109-L109 -+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/x/auth/tx/builder.go#L268-L277 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/auth/tx/builder.go#L270-L279 -+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/tx/v1beta1/tx.proto#L160-L181 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L196-L217 Example cmd: diff --git a/x/feegrant/spec/02_state.md b/x/feegrant/spec/02_state.md index 0c5b9177d1f9..3ff4d8c49c0d 100644 --- a/x/feegrant/spec/02_state.md +++ b/x/feegrant/spec/02_state.md @@ -12,7 +12,7 @@ Fee allowance grants are stored in the state as follows: * Grant: `0x00 | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> ProtocolBuffer(Grant)` -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/feegrant.pb.go#L221-L229 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/feegrant/feegrant.pb.go#L221-L229 ## FeeAllowanceQueue diff --git a/x/feegrant/spec/03_messages.md b/x/feegrant/spec/03_messages.md index 602dd2b7125a..a4d09619afd7 100644 --- a/x/feegrant/spec/03_messages.md +++ b/x/feegrant/spec/03_messages.md @@ -8,10 +8,10 @@ order: 3 A fee allowance grant will be created with the `MsgGrantAllowance` message. -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L22-L33 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/feegrant/v1beta1/tx.proto#L23-L36 ## Msg/RevokeAllowance An allowed grant fee allowance can be removed with the `MsgRevokeAllowance` message. -+++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L38-L45 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/feegrant/v1beta1/tx.proto#L41-L50 diff --git a/x/feegrant/spec/README.md b/x/feegrant/spec/README.md index b8f646f4d991..8f08a51aeb3a 100644 --- a/x/feegrant/spec/README.md +++ b/x/feegrant/spec/README.md @@ -9,7 +9,7 @@ parent: ## Abstract -This document specifies the fee grant module. For the full ADR, please see [Fee Grant ADR-029](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/docs/architecture/adr-029-fee-grant-module.md). +This document specifies the fee grant module. For the full ADR, please see [Fee Grant ADR-029](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-029-fee-grant-module.md). This module allows accounts to grant fee allowances and to use fees from their accounts. Grantees can execute any transaction without the need to maintain sufficient fees. diff --git a/x/genutil/client/cli/validate_genesis.go b/x/genutil/client/cli/validate_genesis.go index 6c8e27dda8e0..519a5ae01f94 100644 --- a/x/genutil/client/cli/validate_genesis.go +++ b/x/genutil/client/cli/validate_genesis.go @@ -12,7 +12,7 @@ import ( "github.com/cosmos/cosmos-sdk/types/module" ) -const chainUpgradeGuide = "https://docs.cosmos.network/master/migrations/chain-upgrade-guide-040.html" +const chainUpgradeGuide = "https://github.com/cosmos/cosmos-sdk/blob/main/UPGRADING.md" // ValidateGenesisCmd takes a genesis file, and makes sure that it is valid. func ValidateGenesisCmd(mbm module.BasicManager) *cobra.Command { diff --git a/x/gov/spec/01_concepts.md b/x/gov/spec/01_concepts.md index 7223e94a5343..df858b690961 100644 --- a/x/gov/spec/01_concepts.md +++ b/x/gov/spec/01_concepts.md @@ -118,15 +118,15 @@ option that casts a `NoWithVeto` vote._ ### Weighted Votes -[ADR-037](../../../docs/architecture/adr-037-gov-split-vote.md) introduces the weighted vote feature which allows a staker to split their votes into several voting options. For example, it could use 70% of its voting power to vote Yes and 30% of its voting power to vote No. +[ADR-037](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-037-gov-split-vote.md) introduces the weighted vote feature which allows a staker to split their votes into several voting options. For example, it could use 70% of its voting power to vote Yes and 30% of its voting power to vote No. Often times the entity owning that address might not be a single individual. For example, a company might have different stakeholders who want to vote differently, and so it makes sense to allow them to split their voting power. Currently, it is not possible for them to do "passthrough voting" and giving their users voting rights over their tokens. However, with this system, exchanges can poll their users for voting preferences, and then vote on-chain proportionally to the results of the poll. To represent weighted vote on chain, we use the following Protobuf message. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L32-L40 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1beta1/gov.proto#L33-L43 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L126-L137 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1beta1/gov.proto#L136-L150 For a weighted vote to be valid, the `options` field must not contain duplicate vote options, and the sum of weights of all options must be equal to 1. diff --git a/x/gov/spec/02_state.md b/x/gov/spec/02_state.md index f7032a368bc8..78af0fe5615e 100644 --- a/x/gov/spec/02_state.md +++ b/x/gov/spec/02_state.md @@ -12,7 +12,7 @@ to resolve and then execute if the proposal passes. `Proposal`'s are identified unique id and contains a series of timestamps: `submit_time`, `deposit_end_time`, `voting_start_time`, `voting_end_time` which track the lifecycle of a proposal -+++ https://github.com/cosmos/cosmos-sdk/blob/5bde3686c4538ce53356af6e9fe40b34e4ce4a06/proto/cosmos/gov/v1/gov.proto#L42-L59 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/gov.proto#L42-L59 A proposal will generally require more than just a set of messages to explain its purpose but need some greater justification and allow a means for interested participants @@ -58,15 +58,15 @@ parameter set has to be created and the previous one rendered inactive. ### DepositParams -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L127-L145 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/gov.proto#L102-L112 ### VotingParams -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L147-L156 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/gov.proto#L114-L118 ### TallyParams -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L158-L183 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/gov.proto#L120-L132 Parameters are stored in a global `GlobalParams` KVStore. @@ -104,7 +104,7 @@ const ( ## Deposit -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L43-L53 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/gov.proto#L34-L40 ## ValidatorGovInfo diff --git a/x/gov/spec/03_messages.md b/x/gov/spec/03_messages.md index 7edc617f0f86..405931da5070 100644 --- a/x/gov/spec/03_messages.md +++ b/x/gov/spec/03_messages.md @@ -9,7 +9,7 @@ order: 3 Proposals can be submitted by any account via a `MsgSubmitProposal` transaction. -+++ https://github.com/cosmos/cosmos-sdk/blob/5bde3686c4538ce53356af6e9fe40b34e4ce4a06/proto/cosmos/gov/v1/tx.proto#L33-L43 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/tx.proto#L33-L43 All `sdk.Msgs` passed into the `messages` field of a `MsgSubmitProposal` message must be registered in the app's `MsgServiceRouter`. Each of these messages must @@ -78,7 +78,7 @@ Once a proposal is submitted, if `Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send `MsgDeposit` transactions to increase the proposal's deposit. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L61-L72 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/tx.proto#L90-L97 **State modifications:** @@ -144,7 +144,7 @@ Once `ActiveParam.MinDeposit` is reached, voting period starts. From there, bonded Atom holders are able to send `MsgVote` transactions to cast their vote on the proposal. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L46-L56 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/gov/v1/tx.proto#L64-L72 **State modifications:** diff --git a/x/group/internal/orm/spec/01_table.md b/x/group/internal/orm/spec/01_table.md index 4c456b1f59cc..28352ba2e5c5 100644 --- a/x/group/internal/orm/spec/01_table.md +++ b/x/group/internal/orm/spec/01_table.md @@ -2,17 +2,16 @@ A table can be built given a `codec.ProtoMarshaler` model type, a prefix to access the underlying prefix store used to store table data as well as a `Codec` for marshalling/unmarshalling. -+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/table.go#L24-L30 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/table.go#L30-L36 In the prefix store, entities should be stored by an unique identifier called `RowID` which can be based either on an `uint64` auto-increment counter, string or dynamic size bytes. Regular CRUD operations can be performed on a table, these methods take a `sdk.KVStore` as parameter to get the table prefix store. The `table` struct does not: -- enforce uniqueness of the `RowID` -- enforce prefix uniqueness of keys, i.e. not allowing one key to be a prefix - of another -- optimize Gas usage conditions +* enforce uniqueness of the `RowID` +* enforce prefix uniqueness of keys, i.e. not allowing one key to be a prefix of another +* optimize Gas usage conditions The `table` struct is private, so that we only have custom tables built on top of it, that do satisfy these requirements. @@ -22,7 +21,7 @@ The `table` struct is private, so that we only have custom tables built on top o `AutoUInt64Table` is a table type with an auto incrementing `uint64` ID. -+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/auto_uint64.go#L11-L14 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/auto_uint64.go#L15-L18 It's based on the `Sequence` struct which is a persistent unique key generator based on a counter encoded using 8 byte big endian. @@ -34,7 +33,7 @@ It's based on the `Sequence` struct which is a persistent unique key generator b The model provided for creating a `PrimaryKeyTable` should implement the `PrimaryKeyed` interface: -+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/primary_key.go#L28-L41 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/primary_key.go#L30-L44 `PrimaryKeyFields()` method returns the list of key parts for a given object. The primary key parts can be []byte, string, and `uint64` types. @@ -43,6 +42,6 @@ The primary key parts can be []byte, string, and `uint64` types. Key parts, except the last part, follow these rules: -- []byte is encoded with a single byte length prefix (which means the max []byte length is 255) -- strings are null-terminated -- `uint64` are encoded using 8 byte big endian. +* []byte is encoded with a single byte length prefix (which means the max []byte length is 255) +* strings are null-terminated +* `uint64` are encoded using 8 byte big endian. diff --git a/x/group/internal/orm/spec/02_secondary_index.md b/x/group/internal/orm/spec/02_secondary_index.md index fd25a606f571..7111bf69b2cf 100644 --- a/x/group/internal/orm/spec/02_secondary_index.md +++ b/x/group/internal/orm/spec/02_secondary_index.md @@ -2,19 +2,19 @@ Secondary indexes can be used on `Indexable` [tables](01_table.md). Indeed, those tables implement the `Indexable` interface that provides a set of functions that can be called by indexes to register and interact with the tables, like callback functions that are called on entries creation, update or deletion to create, update or remove corresponding entries in the table secondary indexes. -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L88-L92 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/types.go#L88-L93 ## MultiKeyIndex A `MultiKeyIndex` is an index where multiple entries can point to the same underlying object. -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L25-L31 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/index.go#L26-L32 Internally, it uses an `Indexer` that manages the persistence of the index based on searchable keys and create/update/delete operations. -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L15-L19 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/index.go#L15-L20 -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/indexer.go#L15-L18 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/indexer.go#L15-L19 The currently used implementation of an `indexer`, `Indexer`, relies on an `IndexerFunc` that should be provided when instantiating the index. Based on the source object, this function returns one or multiple index keys as `[]interface{}`. Such secondary index keys should be bytes, string or `uint64` in order to be handled properly by the [key codec](01_table.md#key-codec) which defines specific encoding for those types. In the index prefix store, the keys are built based on the source object's `RowID` and its secondary index key(s) using the key codec and the values are set as empty bytes. diff --git a/x/group/internal/orm/spec/03_iterator_pagination.md b/x/group/internal/orm/spec/03_iterator_pagination.md index ac0839623321..4205d9e8b484 100644 --- a/x/group/internal/orm/spec/03_iterator_pagination.md +++ b/x/group/internal/orm/spec/03_iterator_pagination.md @@ -6,15 +6,15 @@ Both [tables](01_table.md) and [secondary indexes](02_secondary_index.md) suppor An `Iterator` allows iteration through a sequence of key value pairs. -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L77-L83 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/types.go#L77-L85 Tables rely on a `typeSafeIterator` that is used by `PrefixScan` and `ReversePrefixScan` `table` methods to iterate through a range of `RowID`s. -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/table.go#235-L239 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/table.go#L285-L290 Secondary indexes rely on an `indexIterator` that can strip the `RowID` from the full index key in order to get the underlying value in the table prefix store. -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L227-L232 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/index.go#L232-L238 Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`). @@ -23,6 +23,6 @@ Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`). The `Paginate` function does pagination given an [`Iterator`](#iterator) and a `query.PageRequest`, and returns a `query.PageResponse`. It unmarshals the results into the provided dest interface that should be a pointer to a slice of models. -+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/iterator.go#L117-L216 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/x/group/internal/orm/iterator.go#L102-L220 Secondary indexes have a `GetPaginated` method that returns an `Iterator` for the given searched secondary index key, starting from the `query.PageRequest` key if provided. It's important to note that this `query.PageRequest` key should be a `RowID` (that could have been returned by a previous paginated request). The returned `Iterator` can then be used with the `Paginate` function and the same `query.PageRequest`. diff --git a/x/mint/spec/02_state.md b/x/mint/spec/02_state.md index b5acd5264846..2fa04b1ef876 100644 --- a/x/mint/spec/02_state.md +++ b/x/mint/spec/02_state.md @@ -10,7 +10,7 @@ The minter is a space for holding current inflation information. * Minter: `0x00 -> ProtocolBuffer(minter)` -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L8-L19 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L9-L23 ## Params @@ -18,4 +18,4 @@ Minting params are held in the global params store. * Params: `mint/params -> legacy_amino(params)` -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L21-L53 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L25-L57 diff --git a/x/slashing/spec/02_state.md b/x/slashing/spec/02_state.md index a0298b57499e..50aa0e14100e 100644 --- a/x/slashing/spec/02_state.md +++ b/x/slashing/spec/02_state.md @@ -48,4 +48,4 @@ bonded validator. The `SignedBlocksWindow` parameter defines the size The information stored for tracking validator liveness is as follows: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/slashing/v1beta1/slashing.proto#L11-L33 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/slashing/v1beta1/slashing.proto#L12-L33 diff --git a/x/staking/spec/01_state.md b/x/staking/spec/01_state.md index 8d66cb98a005..fb3c1825bfcd 100644 --- a/x/staking/spec/01_state.md +++ b/x/staking/spec/01_state.md @@ -20,9 +20,7 @@ Store entries prefixed with "Last" must remain unchanged until EndBlock. Params is a module-wide configuration structure that stores system parameters and defines overall functioning of the staking module. -* Params: `Paramsspace("staking") -> legacy_amino(params)` - -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.1/proto/cosmos/staking/v1beta1/staking.proto#L230-L241 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L285-L306 ## Validator @@ -75,9 +73,9 @@ is updated during the validator set update process which takes place in [`EndBlo Each validator's state is stored in a `Validator` struct: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L65-L99 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L78-L127 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L24-L63 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L24-L76 ## Delegation @@ -91,7 +89,7 @@ funds are held in a `Delegation` data structure. It is owned by one delegator, and is associated with the shares for one validator. The sender of the transaction is the owner of the bond. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L159-L170 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L187-L205 ### Delegator Shares @@ -130,7 +128,7 @@ slashed. A UnbondingDelegation object is created every time an unbonding is initiated. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L172-L198 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L207-L220 ## Redelegation @@ -158,7 +156,7 @@ A redelegation object is created every time a redelegation occurs. To prevent * and, the (re)delegator is attempting to create a _new_ redelegation where the source validator for this new redelegation is `Validator X`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L200-L228 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L245-L283 ## Queues @@ -180,7 +178,7 @@ delegations queue is kept. * UnbondingDelegation: `0x41 | format(time) -> []DVPair` -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L123-L133 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L151-L161 ### RedelegationQueue @@ -189,7 +187,7 @@ kept. * RedelegationQueue: `0x42 | format(time) -> []DVVTriplet` -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L140-L152 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L168-L179 ### ValidatorQueue @@ -208,7 +206,7 @@ that multiple validators exist in the queue at the same location. HistoricalInfo objects are stored and pruned at each block such that the staking keeper persists the `n` most recent historical info defined by staking module parameter: `HistoricalEntries`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L15-L22 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L15-L22 At each BeginBlock, the staking keeper will persist the current Header and the Validators that committed the current block in a `HistoricalInfo` object. The Validators are sorted on their address to ensure that diff --git a/x/staking/spec/03_messages.md b/x/staking/spec/03_messages.md index a9ef8d05a99a..a0222d36dfeb 100644 --- a/x/staking/spec/03_messages.md +++ b/x/staking/spec/03_messages.md @@ -11,9 +11,9 @@ In this section we describe the processing of the staking messages and the corre A validator is created using the `MsgCreateValidator` message. The validator must be created with an initial delegation from the operator. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L16-L17 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L18-L19 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L35-L51 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L43-L65 This message is expected to fail if: @@ -36,9 +36,9 @@ in the first end-block. The `Description`, `CommissionRate` of a validator can be updated using the `MsgEditValidator` message. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L19-L20 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L21-L22 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L56-L76 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L70-L88 This message is expected to fail if: @@ -55,9 +55,9 @@ Within this message the delegator provides coins, and in return receives some amount of their validator's (newly created) delegator-shares that are assigned to `Delegation.Shares`. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L22-L24 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L24-L26 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L93-L104 This message is expected to fail if: @@ -87,13 +87,13 @@ will not be added to the power index until it is unjailed. The `MsgUndelegate` message allows delegators to undelegate their tokens from validator. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L30-L32 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L32-L34 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L128-L139 This message returns a response containing the completion time of the undelegation: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L123-L126 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L128-L144 This message is expected to fail if: @@ -117,24 +117,24 @@ When this message is processed the following actions occur: ![Unbond sequence](../../../docs/uml/svg/unbond_sequence.svg) ## MsgCancelUnbondingDelegation -The `MsgCancelUnbondingDelegation` message allows delegators to cancel the `unbondingDelegation` entry and deleagate back to a previous validator. - -+++ https://github.com/cosmos/cosmos-sdk/blob/28243eb41c16ecfc95631ac2bb266dd28ed5c317/proto/cosmos/staking/v1beta1/tx.proto#L36-L38 -+++ https://github.com/cosmos/cosmos-sdk/blob/28243eb41c16ecfc95631ac2bb266dd28ed5c317/proto/cosmos/staking/v1beta1/tx.proto#L144-L154 +The `MsgCancelUnbondingDelegation` message allows delegators to cancel the `unbondingDelegation` entry and deleagate back to a previous validator. -+++ https://github.com/cosmos/cosmos-sdk/blob/28243eb41c16ecfc95631ac2bb266dd28ed5c317/proto/cosmos/staking/v1beta1/tx.proto#L156-L157 ++++ hhttps://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L36-L40 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L146-L165 This message is expected to fail if: + * the `unbondingDelegation` entry is already processed. * the `cancel unbonding delegation` amount is greater than the `unbondingDelegation` entry balance. * the `cancel unbonding delegation` height doesn't exists in the `unbondingDelegationQueue` of the delegator. When this message is processed the following actions occur: + * if the `unbondingDelegation` Entry balance is zero - * in this condition `unbondingDelegation` entry will be removed from `unbondingDelegationQueue`. - * otherwise `unbondingDelegationQueue` will be updated with new `unbondingDelegation` entry balance and initial balance + * in this condition `unbondingDelegation` entry will be removed from `unbondingDelegationQueue`. + * otherwise `unbondingDelegationQueue` will be updated with new `unbondingDelegation` entry balance and initial balance * the validator's `DelegatorShares` and the delegation's `Shares` are both increased by the message `Amount`. ## MsgBeginRedelegate @@ -143,13 +143,13 @@ The redelegation command allows delegators to instantly switch validators. Once the unbonding period has passed, the redelegation is automatically completed in the EndBlocker. -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L26-L28 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L28-L30 -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L95-L105 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L109-L121 This message returns a response containing the completion time of the redelegation: -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L107-L110 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L123-L126 This message is expected to fail if: diff --git a/x/upgrade/doc.go b/x/upgrade/doc.go index b9d696914f94..b66fe38c1db0 100644 --- a/x/upgrade/doc.go +++ b/x/upgrade/doc.go @@ -30,7 +30,7 @@ and gracefully exit. Generally the application binary will restart on exit, but then will execute this BeginBlocker again and exit, causing a restart loop. Either the operator can manually install the new software, or you can make use of an external watcher daemon to possibly download and then switch binaries, -also potentially doing a backup. An example of such a daemon is https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc5/cosmovisor +also potentially doing a backup. An example of such a daemon is https://github.com/cosmos/cosmos-sdk/tree/main/cosmovisor described below under "Automation". When the binary restarts with the upgraded version (here v0.40.0), it will detect we have registered the @@ -106,10 +106,10 @@ to lose connectivity with the exiting nodes, thus this module prefers to just ha Automation and Plan.Info -We have deprecated calling out to scripts, instead with propose https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc5/cosmovisor +We have deprecated calling out to scripts, instead with propose https://github.com/cosmos/cosmos-sdk/tree/main/cosmovisor as a model for a watcher daemon that can launch simd as a subprocess and then read the upgrade log message to swap binaries as needed. You can pass in information into Plan.Info according to the format -specified here https://github.com/cosmos/cosmos-sdk/tree/v0.40.0-rc5/cosmovisor/README.md#auto-download . +specified here https://github.com/cosmos/cosmos-sdk/tree/main/cosmovisor/README.md#auto-download . This will allow a properly configured cosmsod daemon to auto-download new binaries and auto-upgrade. As noted there, this is intended more for full nodes than validators.