Skip to content

Commit

Permalink
docs: tooling (#22049)
Browse files Browse the repository at this point in the history
  • Loading branch information
@julienrbrt
julienrbrt authored Oct 3, 2024
1 parent bf95c81 commit 3a5a619
Show file tree
Hide file tree
Showing 6 changed files with 71 additions and 86 deletions.
82 changes: 43 additions & 39 deletions client/v2/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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:

Expand Down Expand Up @@ -73,7 +75,7 @@ if err := rootCmd.Execute(); err != nil {
}
```

### Keyring
#### Keyring

`autocli` uses a keyring for key name resolving names and signing transactions.

Expand All @@ -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.
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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`
Expand All @@ -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`
Expand Down
37 changes: 9 additions & 28 deletions docs/build/tooling/00-protobuf.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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).
Expand All @@ -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)
Expand All @@ -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`.
Expand All @@ -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
```
6 changes: 3 additions & 3 deletions simapp/upgrades.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,12 @@ import (
)

// UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade
// from v0.50.x to v0.51.x
// from v0.52.x to v0.54.x
//
// NOTE: This upgrade defines a reference implementation of what an upgrade
// could look like when an application is migrating from Cosmos SDK version
// v0.50.x to v0.51.x.
const UpgradeName = "v050-to-v051"
// v0.52.x to v0.54.x.
const UpgradeName = "v052-to-v054"

func (app SimApp) RegisterUpgradeHandlers() {
app.UpgradeKeeper.SetUpgradeHandler(
Expand Down
6 changes: 3 additions & 3 deletions simapp/v2/upgrades.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,12 @@ import (
)

// UpgradeName defines the on-chain upgrade name for the sample SimApp upgrade
// from v0.50.x to v0.51.x
// from v0.52.x to v2
//
// NOTE: This upgrade defines a reference implementation of what an upgrade
// could look like when an application is migrating from Cosmos SDK version
// v0.50.x to v0.51.x.
const UpgradeName = "v050-to-v051"
// v0.52.x to v2.
const UpgradeName = "v052-to-v2"

func (app *SimApp[T]) RegisterUpgradeHandlers() {
app.UpgradeKeeper.SetUpgradeHandler(
Expand Down
11 changes: 6 additions & 5 deletions tools/confix/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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).
15 changes: 7 additions & 8 deletions tools/cosmovisor/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,21 @@ sidebar_position: 1
`cosmovisor` is a process manager for Cosmos SDK application binaries that automates application binary switch at chain upgrades.
It polls the `upgrade-info.json` file that is created by the x/upgrade module at upgrade height, and then can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.

* [Cosmovisor](#cosmovisor)
* [Design](#design)
* [Contributing](#contributing)
* [Setup](#setup)
* [Design](#design)
* [Contributing](#contributing)
* [Setup](#setup)
* [Installation](#installation)
* [Command Line Arguments And Environment Variables](#command-line-arguments-and-environment-variables)
* [Folder Layout](#folder-layout)
* [Usage](#usage)
* [Usage](#usage)
* [Initialization](#initialization)
* [Detecting Upgrades](#detecting-upgrades)
* [Adding Upgrade Binary](#adding-upgrade-binary)
* [Preparing for an Upgrade](#preparing-for-an-upgrade)
* [Auto-Download](#auto-download)
* [Example: SimApp Upgrade](#example-simapp-upgrade)
* [Preparing for an Upgrade](#preparing-for-an-upgrade)
* [Example: SimApp Upgrade](#example-simapp-upgrade)
* [Chain Setup](#chain-setup)
* [Prepare Cosmovisor and Start the Chain](#prepare-cosmovisor-and-start-the-chain)
* [Prepare Cosmovisor and Start the Chain](#prepare-cosmovisor-and-start-the-chain)
* [Update App](#update-app)

## Design
Expand Down

0 comments on commit 3a5a619

Please sign in to comment.