Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: learn/advance (backport #22367) #22370

Merged
merged 1 commit into from
Oct 25, 2024
Merged

docs: learn/advance (backport #22367) #22370

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/learn/advanced/00-baseapp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
14 changes: 7 additions & 7 deletions docs/learn/advanced/05-encoding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -37,11 +37,11 @@ but may choose any encoding schema they like. The
[collections](../../build/packages/02-collections.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/)
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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`.

Expand Down Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/learn/advanced/06-grpc_rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down
Loading
Loading