docs: tooling (backport #22049) (#22058)

Co-authored-by: Julien Robert <julien@rbrt.fr>

Author: mergify[bot]

client/v2/README.md

@@ -2,7 +2,9 @@
 sidebar_position: 1
 ---
 
-# AutoCLI
+# Client/v2
+
+## AutoCLI
 
 :::note Synopsis
 This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included.
@@ -14,9 +16,9 @@ This document details how to build CLI and REST interfaces for a module. Example
 
 :::
 
-The `autocli` (also known as `client/v2`) package is a [Go library](https://pkg.go.dev/cosmossdk.io/client/v2/autocli) for generating CLI (command line interface) interfaces for Cosmos SDK-based applications. It provides a simple way to add CLI commands to your application by generating them automatically based on your gRPC service definitions. Autocli generates CLI commands and flags directly from your protobuf messages, including options, input parameters, and output parameters. This means that you can easily add a CLI interface to your application without having to manually create and manage commands.
+The `autocli` (also known as `client/v2/autocli`) package is a [Go library](https://pkg.go.dev/cosmossdk.io/client/v2/autocli) for generating CLI (command line interface) interfaces for Cosmos SDK-based applications. It provides a simple way to add CLI commands to your application by generating them automatically based on your gRPC service definitions. Autocli generates CLI commands and flags directly from your protobuf messages, including options, input parameters, and output parameters. This means that you can easily add a CLI interface to your application without having to manually create and manage commands.
 
-## Overview
+### Overview
 
 `autocli` generates CLI commands and flags for each method defined in your gRPC service. By default, it generates commands for each gRPC services. The commands are named based on the name of the service method.
 
@@ -32,7 +34,7 @@ For instance, `autocli` would generate a command named `my-method` for the `MyMe
 
 It is possible to customize the generation of transactions and queries by defining options for each service.
 
-## Application Wiring
+### Application Wiring
 
 Here are the steps to use AutoCLI:
 
@@ -73,7 +75,7 @@ if err := rootCmd.Execute(); err != nil {
 }
 ```
 
-### Keyring
+#### Keyring
 
 `autocli` uses a keyring for key name resolving names and signing transactions.
 
@@ -100,7 +102,7 @@ keyring.NewAutoCLIKeyring(kb)
 
 :::
 
-## Signing
+### Signing
 
 `autocli` supports signing transactions with the keyring.
 The [`cosmos.msg.v1.signer` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) defines the signer field of the message.
@@ -110,7 +112,7 @@ This field is automatically filled when using the `--from` flag or defining the
 AutoCLI currently supports only one signer per transaction.
 :::
 
-## Module wiring & Customization
+### Module wiring & Customization
 
 The `AutoCLIOptions()` method on your module allows to specify custom commands, sub-commands or flags for each service, as it was a `cobra.Command` instance, within the `RpcCommandOptions` struct. Defining such options will customize the behavior of the `autocli` command generation, which by default generates a command for each method in your gRPC service.
 
@@ -131,31 +133,7 @@ AutoCLI can create a gov proposal of any tx by simply setting the `GovProposal`
 Users can however use the `--no-proposal` flag to disable the proposal creation (which is useful if the authority isn't the gov module on a chain).
 :::
 
-### Conventions for the `Use` field in Cobra
-
-According to the [Cobra documentation](https://pkg.go.dev/github.com/spf13/cobra#Command) the following conventions should be followed for the `Use` field in Cobra commands:
-
-1. **Required arguments**:
-   * Should not be enclosed in brackets. They can be enclosed in angle brackets `< >` for clarity.
-   * Example: `command <required_argument>`
-
-2. **Optional arguments**:
-   * Should be enclosed in square brackets `[ ]`.
-   * Example: `command [optional_argument]`
-
-3. **Alternative (mutually exclusive) arguments**:
-   * Should be enclosed in curly braces `{ }`.
-   * Example: `command {-a | -b}` for required alternatives.
-   * Example: `command [-a | -b]` for optional alternatives.
-
-4. **Multiple arguments**:
-   * Indicated with `...` after the argument.
-   * Example: `command argument...`
-
-5. **Combination of options**:
-   * Example: `command [-F file | -D dir]... [-f format] profile`
-
-### Specifying Subcommands
+#### Specifying Subcommands
 
 By default, `autocli` generates a command for each method in your gRPC service. However, you can specify subcommands to group related commands together. To specify subcommands, use the `autocliv1.ServiceCommandDescriptor` struct.
 
@@ -165,7 +143,7 @@ This example shows how to use the `autocliv1.ServiceCommandDescriptor` struct to
 https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-beta.0/x/gov/autocli.go#L94-L97
 ```
 
-### Positional Arguments
+#### Positional Arguments
 
 By default `autocli` generates a flag for each field in your protobuf message. However, you can choose to use positional arguments instead of flags for certain fields.
 
@@ -183,7 +161,7 @@ Then the command can be used as follows, instead of having to specify the `--add
 <appd> query auth account cosmos1abcd...xyz
 ```
 
-### Customising Flag Names
+#### Customising Flag Names
 
 By default, `autocli` generates flag names based on the names of the fields in your protobuf message. However, you can customise the flag names by providing a `FlagOptions`. This parameter allows you to specify custom names for flags based on the names of the message fields.
 
@@ -200,7 +178,7 @@ autocliv1.RpcCommandOptions{
 
 `FlagsOptions` is defined like sub commands in the `AutoCLIOptions()` method on your module.
 
-### Combining AutoCLI with Other Commands Within A Module
+#### Combining AutoCLI with Other Commands Within A Module
 
 AutoCLI can be used alongside other commands within a module. For example, the `gov` module uses AutoCLI to generate commands for the `query` subcommand, but also defines custom commands for the `proposer` subcommands.
 
@@ -212,7 +190,7 @@ https://github.com/cosmos/cosmos-sdk/blob/fa4d87ef7e6d87aaccc94c337ffd2fe90fcb7a
 
 If not set to true, `AutoCLI` will not generate commands for the module if there are already commands registered for the module (when `GetTxCmd()` or `GetQueryCmd()` are defined).
 
-### Skip a command
+#### Skip a command
 
 AutoCLI automatically skips unsupported commands when [`cosmos_proto.method_added_in` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) is present.
 
@@ -225,7 +203,7 @@ Additionally, a command can be manually skipped using the `autocliv1.RpcCommandO
 }
 ```
 
-### Use AutoCLI for non module commands
+#### Use AutoCLI for non module commands
 
 It is possible to use `AutoCLI` for non module commands. The trick is still to implement the `appmodule.Module` interface and append it to the `appOptions.ModuleOptions` map.
 
@@ -235,7 +213,31 @@ For example, here is how the SDK does it for `cometbft` gRPC commands:
 https://github.com/cosmos/cosmos-sdk/blob/main/client/grpc/cmtservice/autocli.go#L52-L71
 ```
 
-## Summary
+#### Conventions for the `Use` field in Cobra
+
+According to the [Cobra documentation](https://pkg.go.dev/github.com/spf13/cobra#Command) the following conventions should be followed for the `Use` field in Cobra commands:
+
+1. **Required arguments**:
+   * Should not be enclosed in brackets. They can be enclosed in angle brackets `< >` for clarity.
+   * Example: `command <required_argument>`
+
+2. **Optional arguments**:
+   * Should be enclosed in square brackets `[ ]`.
+   * Example: `command [optional_argument]`
+
+3. **Alternative (mutually exclusive) arguments**:
+   * Should be enclosed in curly braces `{ }`.
+   * Example: `command {-a | -b}` for required alternatives.
+   * Example: `command [-a | -b]` for optional alternatives.
+
+4. **Multiple arguments**:
+   * Indicated with `...` after the argument.
+   * Example: `command argument...`
+
+5. **Combination of options**:
+   * Example: `command [-F file | -D dir]... [-f format] profile`
+
+### Summary
 
 `autocli` lets you generate CLI to your Cosmos SDK-based applications without any cobra boilerplate. It allows you to easily generate CLI commands and flags from your protobuf messages, and provides many options for customising the behavior of your CLI application.
 
@@ -245,7 +247,7 @@ For more information on `hubl`, including how to configure a new chain and query
 
 # Off-Chain
 
-Off-chain functionalities allow you to sign and verify files with two commands:
+Off-chain is a `client/v2` package providing functionalities for allowing to sign and verify files with two commands:
 
 * `sign-file` for signing a file.
 * `verify-file` for verifying a previously signed file.
@@ -275,6 +277,7 @@ The `encoding` flag lets you choose how the contents of the file should be encod
         "signer":  "cosmos1x33fy6rusfprkntvjsfregss7rvsvyy4lkwrqu",
         "data":  "Hello World!\n"
       }
+
      ```
 
 * `simd off-chain sign-file alice myFile.json --encoding base64`
@@ -286,6 +289,7 @@ The `encoding` flag lets you choose how the contents of the file should be encod
         "signer":  "cosmos1x33fy6rusfprkntvjsfregss7rvsvyy4lkwrqu",
         "data":  "SGVsbG8gV29ybGQhCg=="
       }
+
      ```
 
 * `simd off-chain sign-file alice myFile.json --encoding hex`

docs/build/tooling/00-protobuf.md

@@ -4,21 +4,17 @@ sidebar_position: 1
 
 # Protocol Buffers
 
-It is known that Cosmos SDK uses protocol buffers extensively, this document is meant to provide a guide on how it is used in the cosmos-sdk.
+Cosmos SDK uses protocol buffers extensively, this document is meant to provide a guide on how it is used in the cosmos-sdk.
 
-To generate the proto file, the Cosmos SDK uses a docker image, this image is provided to all to use as well. The latest version is `ghcr.io/cosmos/proto-builder:0.12.x`
+To generate the proto file, the Cosmos SDK uses a docker image, this image is provided to all to use as well. The latest version is `ghcr.io/cosmos/proto-builder:0.15.x`
 
 Below is the example of the Cosmos SDK's commands for generating, linting, and formatting protobuf files that can be reused in any applications makefile. 
 
 ```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/Makefile#L411-L432
+https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/scripts/build/protobuf.mk#L1-L10
 ```
 
-The script used to generate the protobuf files can be found in the `scripts/` directory. 
-
-```shell reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/scripts/protocgen.sh
-```
+The [`protocgen.sh`](https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/scripts/protocgen.sh) script used to generate the protobuf files via buf can be found in the `scripts/` directory.
 
 ## Buf
 
@@ -36,7 +32,9 @@ https://github.com/cosmos/cosmos-sdk/blob/main/buf.work.yaml#L6-L9
 
 ### Proto Directory
 
-Next is the `proto/` directory where all of our protobuf files live. In here there are many different buf files defined each serving a different purpose. 
+The `proto/` directory where all of global protobuf files live.
+In here there are many different buf files defined each serving a different purpose. 
+Modules proto files are defined in their respective module directories (in the SDK `x/{moduleName}/proto`).
 
 ```bash
 ├── README.md
@@ -50,8 +48,6 @@ Next is the `proto/` directory where all of our protobuf files live. In here the
 └── tendermint
 ```
 
-The above diagram all the files and directories within the Cosmos SDK `proto/` directory. 
-
 #### `buf.gen.gogo.yaml`
 
 `buf.gen.gogo.yaml` defines how the protobuf files should be generated for use with in the module. This file uses [gogoproto](https://github.com/gogo/protobuf), a separate generator from the google go-proto generator that makes working with various objects more ergonomic, and it has more performant encode and decode steps
@@ -60,10 +56,6 @@ The above diagram all the files and directories within the Cosmos SDK `proto/` d
 https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.gogo.yaml#L1-L9
 ```
 
-:::tip
-Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code)
-:::
-
 #### `buf.gen.pulsar.yaml`
 
 `buf.gen.pulsar.yaml` defines how protobuf files should be generated using the [new golang apiv2 of protobuf](https://go.dev/blog/protobuf-apiv2). This generator is used instead of the google go-proto generator because it has some extra helpers for Cosmos SDK applications and will have more performant encode and decode than the google go-proto generator. You can follow the development of this generator [here](https://github.com/cosmos/cosmos-proto). 
@@ -72,10 +64,6 @@ Example of how to define `gen` files can be found [here](https://docs.buf.build/
 https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.pulsar.yaml#L1-L18
 ```
 
-:::tip
-Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code)
-:::
-
 #### `buf.gen.swagger.yaml`
 
 `buf.gen.swagger.yaml` generates the swagger documentation for the query and messages of the chain. This will only define the REST API end points that were defined in the query and msg servers. You can find examples of this [here](https://github.com/cosmos/cosmos-sdk/blob/main/x/bank/proto/cosmos/bank/v1beta1/query.proto)
@@ -84,10 +72,6 @@ Example of how to define `gen` files can be found [here](https://docs.buf.build/
 https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.swagger.yaml#L1-L6
 ```
 
-:::tip
-Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code)
-:::
-
 #### `buf.lock`
 
 This is an autogenerated file based off the dependencies required by the `.gen` files. There is no need to copy the current one. If you depend on cosmos-sdk proto definitions a new entry for the Cosmos SDK will need to be provided. The dependency you will need to use is `buf.build/cosmos/cosmos-sdk`.
@@ -100,14 +84,11 @@ https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.lock#L1-L16
 
 `buf.yaml` defines the [name of your package](https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.yaml#L3), which [breakage checker](https://buf.build/docs/tutorials/getting-started-with-buf-cli#detect-breaking-changes) to use and how to [lint your protobuf files](https://buf.build/docs/tutorials/getting-started-with-buf-cli#lint-your-api). 
 
+It is advised to use a tagged version of the buf modules corresponding to the version of the Cosmos SDK being are used. 
+
 ```go reference
 https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.yaml#L1-L24
 ```
 
 We use a variety of linters for the Cosmos SDK protobuf files. The repo also checks this in ci. 
-
 A reference to the github actions can be found [here](https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/proto.yml#L1-L32)
-
-```go reference
-https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/proto.yml#L1-L32
-```

simapp/upgrades.go

@@ -15,12 +15,12 @@ import (
 )
 
 // UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade
-// from v0.50.x to v0.51.x
+// from v0.50.x to v0.52.x
 //
 // NOTE: This upgrade defines a reference implementation of what an upgrade
 // could look like when an application is migrating from Cosmos SDK version
-// v0.50.x to v0.51.x.
-const UpgradeName = "v050-to-v051"
+// v0.59.x to v0.52.x.
+const UpgradeName = "v050-to-v052"
 
 func (app SimApp) RegisterUpgradeHandlers() {
 	app.UpgradeKeeper.SetUpgradeHandler(

simapp/v2/upgrades.go

@@ -12,12 +12,12 @@ import (
 )
 
 // UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade
-// from v0.50.x to v0.51.x
+// from v0.50.x to v2
 //
 // NOTE: This upgrade defines a reference implementation of what an upgrade
 // could look like when an application is migrating from Cosmos SDK version
-// v0.50.x to v0.51.x.
-const UpgradeName = "v050-to-v051"
+// v0.50.x to v2.
+const UpgradeName = "v050-to-v2"
 
 func (app *SimApp[T]) RegisterUpgradeHandlers() {
 	app.UpgradeKeeper.SetUpgradeHandler(

tools/confix/README.md

@@ -23,7 +23,7 @@ import "cosmossdk.io/tools/confix/cmd"
 Find the following line:
 
 ```go
-initRootCmd(rootCmd, encodingConfig)
+initRootCmd(rootCmd, moduleManager)
 ```
 
 After that line, add the following:
@@ -39,10 +39,10 @@ An implementation example can be found in `simapp`.
 
 The command will be available as `simd config`.
 
-```tip
+:::tip
 Using confix directly in the application can have less features than using it standalone.
 This is because confix is versioned with the SDK, while `latest` is the standalone version.
-```
+:::
 
 ### Using Confix Standalone
 
@@ -138,7 +138,7 @@ confix view ~/.simapp/config/client.toml # views the current app client conf
 
 ### Maintainer
 
-At each SDK modification of the default configuration, add the default SDK config under `data/v0.XX-app.toml`.
+At each SDK modification of the default configuration, add the default SDK config under `data/vXX-app.toml`.
 This allows users to use the tool standalone.
 
 ### Compatibility
@@ -149,7 +149,8 @@ The recommended standalone version is `latest`, which is using the latest develo
 | ----------- | -------------- |
 | v0.50       | v0.1.x         |
 | v0.52       | v0.2.x         |
+| v2          | v0.2.x         |
 
 ## Credits
 
-This project is based on the [CometBFT RFC 019](https://github.com/cometbft/cometbft/blob/5013bc3f4a6d64dcc2bf02ccc002ebc9881c62e4/docs/rfc/rfc-019-config-version.md) and their own implementation of [confix](https://github.com/cometbft/cometbft/blob/v0.36.x/scripts/confix/confix.go).
+This project is based on the [CometBFT RFC 019](https://github.com/cometbft/cometbft/blob/5013bc3f4a6d64dcc2bf02ccc002ebc9881c62e4/docs/rfc/rfc-019-config-version.md) and their never released own implementation of [confix](https://github.com/cometbft/cometbft/blob/v0.36.x/scripts/confix/confix.go).