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

Co-authored-by: Julián Toledano <[email protected]>
cosmos · Oct 25, 2024 · 3564de3 · 3564de3
1 parent d7eb09a
commit 3564de3
Show file tree

Hide file tree

Showing 7 changed files with 54 additions and 52 deletions.
diff --git 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/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
@@ -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/)
@@ -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
@@ -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