From 100a22dfbde8aa1323d537d902da1ca05209a182 Mon Sep 17 00:00:00 2001 From: Julian Toledano Date: Thu, 24 Oct 2024 14:17:01 +0200 Subject: [PATCH 1/4] update: encoding, grpc_rest and cli --- docs/learn/advanced/05-encoding.md | 16 ++++++------ docs/learn/advanced/06-grpc_rest.md | 8 +++--- docs/learn/advanced/07-cli.md | 38 ++++++++++++++--------------- 3 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/learn/advanced/05-encoding.md b/docs/learn/advanced/05-encoding.md index 13703f892ecb..ba1772b4305d 100644 --- a/docs/learn/advanced/05-encoding.md +++ b/docs/learn/advanced/05-encoding.md @@ -16,7 +16,7 @@ While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, ## Encoding -The Cosmos SDK supports two wire encoding protocols. Binary encoding is fulfilled by [Protocol +The Cosmos SDK supports two wire encoding protocols. Binary encoding is fulfilled by [Protocol Buffers](https://protobuf.dev/), specifically the [gogoprotobuf](https://github.com/cosmos/gogoproto/) implementation, which is a subset of [Proto3](https://protobuf.dev/programming-guides/proto3/) with an extension for @@ -34,14 +34,14 @@ tree. For storage encoding, module developers are encouraged to use Protobuf encoding for their types but may choose any encoding schema they like. The -[collections](../../build/packages/02-collections.md) package automatically handles encoding and +[collections](https://github.com/cosmos/cosmos-sdk/blob/collections/v0.4.0/collections/README.md) package automatically handles encoding and decoding of state for you. -In the `codec` package, there exists two core interfaces, `BinaryCodec` and `JSONCodec`, +In the `codec` package, there exist 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. -The `ProtoCodec`, where both binary and JSON serialization is handled via Protobuf. This means +The `ProtoCodec`, where both binary and JSON serialization are handled via Protobuf. This means that modules may use Protobuf encoding, but the types must implement `ProtoMarshaler`. If modules wish to avoid implementing this interface for their types, this is autogenerated via [buf](https://buf.build/) @@ -75,7 +75,7 @@ the consensus engine accepts only transactions in the form of raw bytes. * The `TxDecoder` object performs the decoding. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/types/tx_msg.go#L91-L95 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/types/tx_msg.go#L117-L121 ``` A standard implementation of both these objects can be found in the [`auth/tx` module](https://docs.cosmos.network/main/build/modules/auth#transactions): @@ -104,7 +104,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](https://docs.cosmos.network/main/build/modules/auth/vesting), 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? ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/account.go#L15-L32 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/types/account.go#L15-L32 ``` 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: @@ -143,7 +143,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.50.0-alpha.0/x/auth/keeper/keeper.go#L240-L243). +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.52.0-beta.2/x/auth/keeper/keeper.go#L262-L264). The reverse operation of retrieving the concrete Go type from inside an `Any`, called "unpacking", is done with the `GetCachedValue()` on `Any`. @@ -192,7 +192,7 @@ The above `Profile` example is a fictive example used for educational purposes. A real-life example of encoding the pubkey as `Any` inside the Validator struct in x/staking is shown in the following example: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/types/validator.go#L41-L64 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/x/staking/types/validator.go#L43-L63 ``` #### `Any`'s TypeURL diff --git a/docs/learn/advanced/06-grpc_rest.md b/docs/learn/advanced/06-grpc_rest.md index a46f0e0a9461..1f91b9f69cb9 100644 --- a/docs/learn/advanced/06-grpc_rest.md +++ b/docs/learn/advanced/06-grpc_rest.md @@ -26,12 +26,12 @@ All endpoints are defaulted to localhost and must be modified to be exposed to t ## gRPC Server -In the Cosmos SDK, Protobuf is the main [encoding](https://docs.cosmos.network/main/learn/advanced/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. +In the Cosmos SDK, Protobuf is the main [encoding](./05-encoding.md) 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](../../build/building-modules/02-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: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L46-L48 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/server/types/app.go#L45-L47 ``` Note: It is not possible to expose any [Protobuf `Msg` service](../../build/building-modules/02-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](https://docs.cosmos.network/main/user/run-node/txs) for more information. @@ -66,7 +66,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: ```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/bank/v1beta1/query.proto#L23-L30 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/x/bank/proto/cosmos/bank/v1beta1/query.proto#L23-L30 ``` 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. @@ -78,7 +78,7 @@ 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 false 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.50.0-alpha.0/scripts/protoc-swagger-gen.sh) is a good place to start. +The Cosmos SDK's [Swagger generation script](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/scripts/protoc-swagger-gen.sh) is a good place to start. ## CometBFT RPC diff --git a/docs/learn/advanced/07-cli.md b/docs/learn/advanced/07-cli.md index 409effef6801..a490d6202b0d 100644 --- a/docs/learn/advanced/07-cli.md +++ b/docs/learn/advanced/07-cli.md @@ -37,13 +37,13 @@ The `main.go` file needs to have a `main()` function that creates a root command * **setting configurations** by reading in configuration files (e.g. the Cosmos SDK config file). * **adding any flags** to it, such as `--chain-id`. -* **instantiating the `codec`** by injecting the application codecs. The [`codec`](https://docs.cosmos.network/main/learn/advanced/encoding) 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. +* **instantiating the `codec`** by injecting the application codecs. The [`codec`](./05-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://pkg.go.dev/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/main.go#L12-L24 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/main.go#L14-L20 ``` 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. @@ -57,16 +57,16 @@ 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`](./03-node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`. -* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.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.50.0-alpha.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](https://docs.cosmos.network/main/user/run-node/keyring). +* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/tree/v0.52.0-beta.2/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/tree/v0.52.0-beta.2/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](https://docs.cosmos.network/main/user/run-node/keyring). * **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI CometBFT application and provides the CLI framework (based on [cobra](https://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. -Learn more [here](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server). +Learn more [here](https://github.com/cosmos/cosmos-sdk/tree/v0.52.0-beta.2/server). * [**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. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L47-L130 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/root_di.go#L32-L97 ``` :::tip @@ -79,19 +79,19 @@ Read more about [AutoCLI](https://docs.cosmos.network/main/core/autocli) in its Here's an example code to override default `app.toml` template. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L144-L199 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/config.go#L71-L125 ``` -The `initAppConfig()` also allows overriding the default Cosmos SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/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. +The `initAppConfig()` also allows overriding the default Cosmos SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/server/config/config.go). 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. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L164-L180 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/config.go#L41-L57 ``` By default the app uses CometBFT app config template from Cosmos SDK, which can also be over-written via `initCometBFTConfig()`. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L132-L142 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/config.go#L13-L26 ``` Those custom templates and config must be provided to the `server.InterceptConfigsPreRunHandler` command in the `PersistentPreRunE` function of the root command. See [configuration](#configurations) section for more details. @@ -99,13 +99,13 @@ Those custom templates and config must be provided to the `server.InterceptConfi Additionally, like the `app.toml` and `config.toml`, the `client.toml` config can be extended or over-written by the user thanks to the `client.CreateClientConfig` function. This is useful for setting default values for the client without having to pass a flag. For example, the Cosmos SDK sets the default `keyring-backend` to `os` but the chain developer might instead want to always set it to `file` by default. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/bb23e920676096b9fd2d2196daec389ad7f8192e/simapp/simd/cmd/root_v2.go#L78-L82 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/root_di.go#L69-L73 ``` Creating the custom template can be done in a `initClientConfig()` function. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/bb23e920676096b9fd2d2196daec389ad7f8192e/simapp/simd/cmd/config.go#L24-L64 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/config.go#L59-L66 ``` 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. @@ -115,19 +115,19 @@ The root-level `status` and `keys` subcommands are common across most applicatio [Transactions](./01-transactions.md) are objects wrapping [`Msg`s](../../build/building-modules/02-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`: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L222-L229 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/commands.go#L50-L58 ``` This `txCommand` function adds all the transaction available to end-users for the application. This typically includes: * **Sign command** from the [`auth`](https://docs.cosmos.network/main/build/modules/auth) 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](../../build/building-modules/09-module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#basic-manager) `AddTxCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). +* **All [module transaction commands](../../build/building-modules/09-module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#module-manager) `AddTxCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). Here is an example of a `txCommand` aggregating these subcommands from the `simapp` application: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L270-L292 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/commands.go#L92-L114 ``` :::tip @@ -140,7 +140,7 @@ Read more about [AutoCLI](https://docs.cosmos.network/main/core/autocli) in its [**Queries**](../../build/building-modules/02-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`: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L222-L229 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/commands.go#L50-L58 ``` This `queryCommand` function adds all the queries available to end-users for the application. This typically includes: @@ -149,12 +149,12 @@ This `queryCommand` function adds all the queries available to end-users for the * **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address. * **Validator command** from the Cosmos SDK rpc client tools, which displays the validator set of a given height. * **Block command** from the Cosmos SDK RPC client tools, which displays the block data for a given height. -* **All [module query commands](../../build/building-modules/09-module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#basic-manager) `AddQueryCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). +* **All [module query commands](../../build/building-modules/09-module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#module-manager) `AddQueryCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). Here is an example of a `queryCommand` aggregating subcommands from the `simapp` application: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L249-L268 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/commands.go#L70-L90 ``` :::tip @@ -168,7 +168,7 @@ Flags are used to modify commands; developers can include them in a `flags.go` f A *persistent* flag (as opposed to a *local* flag) added to a command transcends all of its children: subcommands will inherit the configured values for these flags. Additionally, all flags have default values when they are added to commands; some toggle an option off but others are empty values that the user needs to override to create valid commands. A flag can be explicitly marked as *required* so that an error is automatically thrown if the user does not provide a value, but it is also acceptable to handle unexpected missing flags differently. -Flags are added to commands directly (generally in the [module's CLI file](../../build/building-modules/09-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. +Flags are added to commands directly (generally in the [module's CLI file](../../build/building-modules/09-module-interfaces.md#transaction-commands) 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. ## Environment variables @@ -198,7 +198,7 @@ It is vital that the root command of an application uses `PersistentPreRun()` co Here is an example of an `PersistentPreRun()` function from `simapp`: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L81-L120 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/simapp/simd/cmd/root_di.go#L54-L84 ``` The `SetCmdClientContextHandler` call reads persistent flags via `ReadPersistentCommandFlags` which creates a `client.Context` and sets that on the root command's `Context`. From 3d640e75bc4279554e8b85b7b26705bfbf9d7349 Mon Sep 17 00:00:00 2001 From: Julian Toledano Date: Fri, 25 Oct 2024 13:16:39 +0200 Subject: [PATCH 2/4] add: events, telemetry, runtx --- docs/learn/advanced/00-baseapp.md | 4 ++-- docs/learn/advanced/08-events.md | 28 +++++++++++----------- docs/learn/advanced/09-telemetry.md | 2 +- docs/learn/advanced/11-runtx_middleware.md | 14 ++++++----- 4 files changed, 25 insertions(+), 23 deletions(-) diff --git a/docs/learn/advanced/00-baseapp.md b/docs/learn/advanced/00-baseapp.md index 95f1fc9b5b93..e30bb4a9a0e4 100644 --- a/docs/learn/advanced/00-baseapp.md +++ b/docs/learn/advanced/00-baseapp.md @@ -462,7 +462,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/baseapp/abci.go#L894 * Run the application's [`preBlocker()`](../beginner/00-app-anatomy.md#preblocker), which mainly runs the [`PreBlocker()`](../../build/building-modules/06-preblock-beginblock-endblock.md#preblocker) method of each of the modules. -#### BeginBlock +#### BeginBlock * Initialize [`finalizeBlockState`](#state-updates) with the latest header using the `req abci.RequestFinalizeBlock` passed as parameter via the `setState` function. @@ -518,7 +518,7 @@ Each transaction returns a response to the underlying consensus engine of type [ * `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`events`](./08-events.md) for more. * `Codespace (string)`: Namespace for the Code. -#### EndBlock +#### EndBlock EndBlock is run after transaction execution completes. It allows developers to have logic be executed at the end of each block. In the Cosmos SDK, the bulk EndBlock() method is to run the application's EndBlocker(), which mainly runs the EndBlocker() method of each of the application's modules. diff --git a/docs/learn/advanced/08-events.md b/docs/learn/advanced/08-events.md index 0c5772e325a6..d41f3dda42a9 100644 --- a/docs/learn/advanced/08-events.md +++ b/docs/learn/advanced/08-events.md @@ -20,14 +20,13 @@ Events are implemented in the Cosmos SDK as an alias of the ABCI `Event` type an take the form of: `{eventType}.{attributeKey}={attributeValue}`. ```protobuf reference -https://github.com/cometbft/cometbft/blob/v0.37.0/proto/tendermint/abci/types.proto#L334-L343 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/proto/cosmos/streaming/v1/grpc.proto#L49-L53 ``` An Event contains: * A `type` to categorize the Event at a high-level; for example, the Cosmos SDK uses the `"message"` type to filter Events by `Msg`s. * A list of `attributes` are key-value pairs that give more information about the categorized Event. For example, for the `"message"` type, we can filter Events by key-value pairs using `message.action={some_action}`, `message.module={some_module}` or `message.sender={some_sender}`. -* A `msg_index` to identify which messages relate to the same transaction :::tip To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value. @@ -46,18 +45,18 @@ Lastly, Events are returned to the underlying consensus engine in the response o * [`BeginBlock`](./00-baseapp.md#beginblock) * [`EndBlock`](./00-baseapp.md#endblock) * [`CheckTx`](./00-baseapp.md#checktx) -* [`Transaction Execution`](./00-baseapp.md#transactionexecution) +* [`Transaction Execution`](./00-baseapp.md#transaction-execution) ### Examples The following examples show how to query Events using the Cosmos SDK. -| Event | Description | -| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `tx.height=23` | Query all transactions at height 23 | -| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../../build/building-modules/03-msg-services.md). Note the `'`s around the value. | -| `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | -| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../build/modules/staking/README.md). | +| Event | Description | +| ------------------------------------------------ |-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `tx.height=23` | Query all transactions at height 23 | +| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../../build/building-modules/03-msg-services.md). Note the `'`s around the value. | +| `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | +| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../../x/staking/README.md#events). | ## EventManager @@ -66,7 +65,7 @@ Internally, the `EventManager` tracks a list of Events for the entire execution (i.e. transaction execution, `BeginBlock`, `EndBlock`). ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/events.go#L19-L26 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/types/events.go#L18-L25 ``` The `EventManager` comes with a set of useful methods to manage Events. The method @@ -74,18 +73,19 @@ that is used most by module and application developers is `EmitTypedEvent` or `E an Event in the `EventManager`. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/events.go#L53-L62 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/types/events.go#L62-L86 ``` -Module developers should handle Event emission via the `EventManager#EmitTypedEvent` or `EventManager#EmitEvent` in each message -`Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via +Module developers should handle Event emission via the `EventManager#EmitTypedEvent` or `EventManager#EmitEvent` in each +message `Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via the [`Context`](./02-context.md), where Event should be already registered, and emitted like this: +Note: it is preferred to use `EmitTypedEvent` over `EmitEvent` as the latter has been deprecated. **Typed events:** ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/group/keeper/msg_server.go#L95-L97 +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/x/group/keeper/msg_server.go#L94-L96 ``` **Legacy events:** diff --git a/docs/learn/advanced/09-telemetry.md b/docs/learn/advanced/09-telemetry.md index 9690d9b590ea..185f793778e8 100644 --- a/docs/learn/advanced/09-telemetry.md +++ b/docs/learn/advanced/09-telemetry.md @@ -19,7 +19,7 @@ To query active metrics (see retention note above) you have to enable API server If telemetry is enabled via configuration, a single global metrics collector is registered via the [go-metrics](https://github.com/hashicorp/go-metrics) library. This allows emitting and collecting -metrics through simple [API](https://github.com/cosmos/cosmos-sdk/blob/v0.50.10/telemetry/wrapper.go). Example: +metrics through simple [API](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/telemetry/wrapper.go). Example: ```go func EndBlocker(ctx sdk.Context, k keeper.Keeper) { diff --git a/docs/learn/advanced/11-runtx_middleware.md b/docs/learn/advanced/11-runtx_middleware.md index 975877e26e3f..195abf92ccf8 100644 --- a/docs/learn/advanced/11-runtx_middleware.md +++ b/docs/learn/advanced/11-runtx_middleware.md @@ -8,13 +8,13 @@ sidebar_position: 1 Depending on the panic type different handler is used, for instance the default one prints an error log message. Recovery middleware is used to add custom panic recovery for Cosmos SDK application developers. -More context can found in the corresponding [ADR-022](../../architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go). +More context can found in the corresponding [ADR-022](../../architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/baseapp/recovery.go). ## Interface ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go#L14-L17 -``` +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/baseapp/recovery.go#L14-L17 +// ``` `recoveryObj` is a return value for `recover()` function from the `buildin` Go package. @@ -25,13 +25,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go#L1 ## Custom RecoveryHandler register -`BaseApp.AddRunTxRecoveryHandler(handlers ...RecoveryHandler)` +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/baseapp/baseapp.go#L549-L554 +``` BaseApp method adds recovery middleware to the default recovery chain. ## Example -Lets assume we want to emit the "Consensus failure" chain state if some particular error occurred. +Let's assume we want to emit the "Consensus failure" chain state if some particular error occurred. We have a module keeper that panics: @@ -45,7 +47,7 @@ func (k FooKeeper) Do(obj interface{}) { } ``` -By default that panic would be recovered and an error message will be printed to log. To override that behaviour we should register a custom RecoveryHandler: +By default, that panic would be recovered and an error message will be printed to log. To override that behaviour we should register a custom RecoveryHandler: ```go // Cosmos SDK application constructor From 4916e66eaace4a2cda60a8ffe6f6c4054b54a517 Mon Sep 17 00:00:00 2001 From: Julian Toledano Date: Fri, 25 Oct 2024 13:35:18 +0200 Subject: [PATCH 3/4] rabbit enhancements --- docs/learn/advanced/08-events.md | 12 ++++++------ docs/learn/advanced/09-telemetry.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/learn/advanced/08-events.md b/docs/learn/advanced/08-events.md index d41f3dda42a9..bffc0aa21725 100644 --- a/docs/learn/advanced/08-events.md +++ b/docs/learn/advanced/08-events.md @@ -51,12 +51,12 @@ Lastly, Events are returned to the underlying consensus engine in the response o The following examples show how to query Events using the Cosmos SDK. -| Event | Description | -| ------------------------------------------------ |-----------------------------------------------------------------------------------------------------------------------------------------------------| -| `tx.height=23` | Query all transactions at height 23 | -| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../../build/building-modules/03-msg-services.md). Note the `'`s around the value. | -| `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | -| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../../x/staking/README.md#events). | +| Event | Description | +| ------------------------------------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------| +| `tx.height=23` | Query all transactions at height 23 | +| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing an x/bank `Send` [Service `Msg`](../../build/building-modules/03-msg-services.md). Note the `'`s around the value. | +| `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | +| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../../x/staking/README.md#events). | ## EventManager diff --git a/docs/learn/advanced/09-telemetry.md b/docs/learn/advanced/09-telemetry.md index 185f793778e8..d1b745b1db05 100644 --- a/docs/learn/advanced/09-telemetry.md +++ b/docs/learn/advanced/09-telemetry.md @@ -19,7 +19,7 @@ To query active metrics (see retention note above) you have to enable API server If telemetry is enabled via configuration, a single global metrics collector is registered via the [go-metrics](https://github.com/hashicorp/go-metrics) library. This allows emitting and collecting -metrics through simple [API](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/telemetry/wrapper.go). Example: +metrics through a simple [API](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/telemetry/wrapper.go). Example: ```go func EndBlocker(ctx sdk.Context, k keeper.Keeper) { From b7d71cf0c8dab882b0f818e7bb485f1c8dc42a82 Mon Sep 17 00:00:00 2001 From: Julian Toledano Date: Fri, 25 Oct 2024 16:07:44 +0200 Subject: [PATCH 4/4] fix: revert links --- docs/learn/advanced/05-encoding.md | 2 +- docs/learn/advanced/08-events.md | 2 +- docs/learn/advanced/11-runtx_middleware.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/learn/advanced/05-encoding.md b/docs/learn/advanced/05-encoding.md index ba1772b4305d..db4b86cfb76e 100644 --- a/docs/learn/advanced/05-encoding.md +++ b/docs/learn/advanced/05-encoding.md @@ -34,7 +34,7 @@ tree. For storage encoding, module developers are encouraged to use Protobuf encoding for their types but may choose any encoding schema they like. The -[collections](https://github.com/cosmos/cosmos-sdk/blob/collections/v0.4.0/collections/README.md) package automatically handles encoding and +[collections](../../build/packages/02-collections.md) package automatically handles encoding and decoding of state for you. In the `codec` package, there exist two core interfaces, `BinaryCodec` and `JSONCodec`, diff --git a/docs/learn/advanced/08-events.md b/docs/learn/advanced/08-events.md index bffc0aa21725..cea128dac93e 100644 --- a/docs/learn/advanced/08-events.md +++ b/docs/learn/advanced/08-events.md @@ -56,7 +56,7 @@ The following examples show how to query Events using the Cosmos SDK. | `tx.height=23` | Query all transactions at height 23 | | `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing an x/bank `Send` [Service `Msg`](../../build/building-modules/03-msg-services.md). Note the `'`s around the value. | | `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | -| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../../x/staking/README.md#events). | +| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../build/modules/staking/README.md). | ## EventManager diff --git a/docs/learn/advanced/11-runtx_middleware.md b/docs/learn/advanced/11-runtx_middleware.md index 195abf92ccf8..309978d2371c 100644 --- a/docs/learn/advanced/11-runtx_middleware.md +++ b/docs/learn/advanced/11-runtx_middleware.md @@ -14,7 +14,7 @@ More context can found in the corresponding [ADR-022](../../architecture/adr-022 ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/baseapp/recovery.go#L14-L17 -// ``` +``` `recoveryObj` is a return value for `recover()` function from the `buildin` Go package.