chore: Sync docs from cosmos-sdk/docs

docs/build/building-apps/01-app-go-v2.md

@@ -7,13 +7,13 @@ sidebar_position: 1
 :::note Synopsis
 
 The Cosmos SDK allows much easier wiring of an `app.go` thanks to App Wiring and [`depinject`](../packages/01-depinject.md).
-Learn more about the rationale of App Wiring in [ADR-057](../../architecture/adr-057-app-wiring.md).
+Learn more about the rationale of App Wiring in [ADR-057](../architecture/adr-057-app-wiring.md).
 
 :::
 
 :::note Pre-requisite Readings
 
-* [ADR 057: App Wiring](../../architecture/adr-057-app-wiring.md)
+* [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md)
 * [Depinject Documentation](../packages/01-depinject.md)
 * [Modules depinject-ready](../building-modules/15-depinject.md)
 

docs/build/building-modules/02-messages-and-queries.md

@@ -25,7 +25,7 @@ When a transaction is relayed from the underlying consensus engine to the Cosmos
 Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../../learn/advanced/05-encoding.md#faq)). It must have an RPC service method defined for each message in the module.
 
 
-Each `Msg` service method must have exactly one argument, which must implement the `sdk.Msg` interface, and a Protobuf response. The naming convention is to call the RPC argument `Msg<service-rpc-name>` and the RPC response `Msg<service-rpc-name>Response`. For example:
+Each `Msg` service method must have exactly one argument, which must implement the `transaction.Msg` interface, and a Protobuf response. The naming convention is to call the RPC argument `Msg<service-rpc-name>` and the RPC response `Msg<service-rpc-name>Response`. For example:
 
 ```protobuf
   rpc Send(MsgSend) returns (MsgSendResponse);
@@ -34,14 +34,18 @@ Each `Msg` service method must have exactly one argument, which must implement t
 See an example of a `Msg` service definition from `x/bank` module:
 
 ```protobuf reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/bank/v1beta1/tx.proto#L13-L36
+https://github.com/cosmos/cosmos-sdk/blob/28fa3b8/x/bank/proto/cosmos/bank/v1beta1/tx.proto#L13-L41
 ```
 
-### `sdk.Msg` Interface
+### `transaction.Msg` Interface
 
-`sdk.Msg` is a alias of `proto.Message`. 
+`transaction.Msg` is an alias of `proto.Message`. 
 
-To attach a `ValidateBasic()` method to a message then you must add methods to the type adhereing to the `HasValidateBasic`.
+```go reference 
+https://github.com/cosmos/cosmos-sdk/blob/main/core/transaction/transaction.go#L8
+```
+
+To attach a `ValidateBasic()` method to a message, then you must add methods to the type adhereing to the `HasValidateBasic`.
 
 ```go reference
 https://github.com/cosmos/cosmos-sdk/blob/9c1e8b247cd47b5d3decda6e86fbc3bc996ee5d7/types/tx_msg.go#L84-L88
@@ -105,26 +109,6 @@ As `proto.Message`s, generated `Response` types implement by default `String()`
 
 A `RegisterQueryServer` method is also generated and should be used to register the module's query server in the `RegisterServices` method from the [`AppModule` interface](./01-module-manager.md#appmodule).
 
-### Legacy Queries
-
-Before the introduction of Protobuf and gRPC in the Cosmos SDK, there was usually no specific `query` object defined by module developers, contrary to `message`s. Instead, the Cosmos SDK took the simpler approach of using a simple `path` to define each `query`. The `path` contains the `query` type and all the arguments needed to process it. For most module queries, the `path` should look like the following:
-
-```text
-queryCategory/queryRoute/queryType/arg1/arg2/...
-```
-
-where:
-
-* `queryCategory` is the category of the `query`, typically `custom` for module queries. It is used to differentiate between different kinds of queries within `BaseApp`'s [`Query` method](../../learn/advanced/00-baseapp.md#query).
-* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../../learn/advanced/00-baseapp.md#query-routing) to map the `query` to its module. Usually, `queryRoute` should be the name of the module.
-* `queryType` is used by the module's [`querier`](./04-query-services.md#legacy-queriers) to map the `query` to the appropriate `querier function` within the module.
-* `args` are the actual arguments needed to process the `query`. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in the `Data` field of the request `req` instead of the `path`.
-
-The `path` for each `query` must be defined by the module developer in the module's [command-line interface file](./09-module-interfaces.md#query-commands).Overall, there are 3 mains components module developers need to implement in order to make the subset of the state defined by their module queryable:
-
-* A [`querier`](./04-query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../../learn/advanced/00-baseapp.md#query-routing).
-* [Query commands](./09-module-interfaces.md#query-commands) in the module's CLI file, where the `path` for each `query` is specified.
-* `query` return types. Typically defined in a file `types/querier.go`, they specify the result type of each of the module's `queries`. These custom types must implement the `String()` method of [`fmt.Stringer`](https://pkg.go.dev/fmt#Stringer).
 
 ### Store Queries
 

docs/build/building-modules/03-msg-services.md

@@ -19,27 +19,35 @@ A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messa
 
 Each module should define a Protobuf `Msg` service, which will be responsible for processing requests (implementing `sdk.Msg`) and returning responses.
 
-As further described in [ADR 031](../../architecture/adr-031-msg-service.md), this approach has the advantage of clearly specifying return types and generating server and client code.
+As further described in [ADR 031](../architecture/adr-031-msg-service.md), this approach has the advantage of clearly specifying return types and generating server and client code.
 
-Protobuf generates a `MsgServer` interface based on a definition of `Msg` service. It is the role of the module developer to implement this interface, by implementing the state transition logic that should happen upon receival of each `sdk.Msg`. As an example, here is the generated `MsgServer` interface for `x/bank`, which exposes two `sdk.Msg`s:
+Protobuf generates a `MsgServer` interface based on the definition of `Msg` service. It is the role of the module developer to implement this interface, by implementing the state transition logic that should happen upon receival of each `transaction.Msg`. As an example, here is the generated `MsgServer` interface for `x/bank`, which exposes two `transaction.Msg`s:
 
 ```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/types/tx.pb.go#L550-L568
+https://github.com/cosmos/cosmos-sdk/blob/28fa3b8/x/bank/types/tx.pb.go#L564-L579
 ```
 
 When possible, the existing module's [`Keeper`](./06-keeper.md) should implement `MsgServer`, otherwise a `msgServer` struct that embeds the `Keeper` can be created, typically in `./keeper/msg_server.go`:
 
 ```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/keeper/msg_server.go#L17-L19
+https://github.com/cosmos/cosmos-sdk/blob/28fa3b8/x/bank/keeper/msg_server.go#L16-L19
 ```
 
-`msgServer` methods can retrieve the `context.Context` from the `context.Context` parameter method using the `sdk.UnwrapSDKContext`:
+`msgServer` methods can retrieve the auxiliary information or services using the environment variable, it is always located in the keeper:
+
+Environment: 
+
+```go reference 
+https://github.com/cosmos/cosmos-sdk/blob/07151304e2ec6a185243d083f59a2d543253cb15/core/appmodule/v2/environment.go#L14-L29
+```
+
+Keeper Example: 
 
 ```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/keeper/msg_server.go#L56
+https://github.com/cosmos/cosmos-sdk/blob/07151304e2ec6a185243d083f59a2d543253cb15/x/bank/keeper/keeper.go#L56-L58
 ```
 
-`sdk.Msg` processing usually follows these 3 steps:
+`transaction.Msg` processing usually follows these 3 steps:
 
 ### Validation
 
@@ -71,14 +79,18 @@ After the validation is successful, the `msgServer` method uses the [`keeper`](.
 
 ### Events 
 
-Before returning, `msgServer` methods generally emit one or more [events](../../learn/advanced/08-events.md) by using the `EventManager` held in the `ctx`. Use the new `EmitTypedEvent` function that uses protobuf-based event types:
+Before returning, `msgServer` methods generally emit one or more [events](../../learn/advanced/08-events.md) by using the `EventManager` held in `environment`.
+
+There are two ways to emit events, typed events using protobuf or arbitrary key & values.
+
+Typed Events:
 
 ```go
 ctx.EventManager().EmitTypedEvent(
 	&group.EventABC{Key1: Value1,  Key2, Value2})
 ```
 
-or the older `EmitEvent` function: 
+Arbitrary Events: 
 
 ```go
 ctx.EventManager().EmitEvent(
@@ -98,15 +110,45 @@ The invoked `msgServer` method returns a `proto.Message` response and an `error`
 https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/msg_service_router.go#L160
 ```
 
-This method takes care of marshaling the `res` parameter to protobuf and attaching any events on the `ctx.EventManager()` to the `sdk.Result`.
+This method takes care of marshaling the `res` parameter to protobuf and attaching any events on the `EventManager()` to the `sdk.Result`.
 
 ```protobuf reference
 https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/base/abci/v1beta1/abci.proto#L93-L113
 ```
 
 This diagram shows a typical structure of a Protobuf `Msg` service, and how the message propagates through the module.
 
-![Transaction flow](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/transaction_flow.svg)
+```mermaid
+sequenceDiagram
+    participant User
+    participant baseApp
+    participant router
+    participant handler
+    participant msgServer
+    participant keeper
+    participant EventManager
+
+    User->>baseApp: Transaction Type<Tx>
+    baseApp->>router: Route(ctx, msgRoute)
+    router->>handler: handler
+    handler->>msgServer: Msg<Tx>(Context, Msg(..))
+    
+    alt addresses invalid, denominations wrong, etc.
+        msgServer->>handler: error
+        handler->>router: error
+        router->>baseApp: result, error code
+    else
+        msgServer->>keeper: perform action, update context
+        keeper->>msgServer: results, error code
+        msgServer->>EventManager: Emit relevant events
+        msgServer->>msgServer: maybe wrap results in more structure
+        msgServer->>handler: result, error code
+        handler->>router: result, error code
+        router->>baseApp: result, error code
+    end
+    
+    baseApp->>User: result, error code
+```
 
 ## Telemetry
 
@@ -117,3 +159,7 @@ This is an example from the `x/auth/vesting` module:
 ```go reference
 https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/vesting/msg_server.go#L76-L88
 ```
+
+:::Warning
+Telemetry adds a performance overhead to the chain. It is recommended to only use this in critical paths
+:::

docs/build/building-modules/06-beginblock-endblock.md

@@ -26,9 +26,9 @@ The actual implementation of `BeginBlocker` and `EndBlocker` in `abci.go` are ve
 
 * They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../../learn/advanced/02-context.md) to retrieve information about the latest state.
 * If needed, they use the `keeper` and `ctx` to trigger state-transitions.
-* If needed, they can emit [`events`](../../learn/advanced/08-events.md) via the `ctx`'s `EventManager`.
+* If needed, they can emit [`events`](../../learn/advanced/08-events.md) via the `environments`'s `EventManager`.
 
-A specific type of `EndBlocker` is available to return validator updates to the underlying consensus engine in the form of an [`[]abci.ValidatorUpdates`](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#endblock). This is the preferred way to implement custom validator changes.
+A specific method (`UpdateValidators`) is available to return validator updates to the underlying consensus engine in the form of an [`[]appmodule.ValidatorUpdates`](https://github.com/cosmos/cosmos-sdk/blob/07151304e2ec6a185243d083f59a2d543253cb15/core/appmodule/v2/module.go#L87-L101). This is the preferred way to implement custom validator changes.
 
 It is possible for developers to define the order of execution between the `BeginBlocker`/`EndBlocker` functions of each of their application's modules via the module's manager `SetOrderBeginBlocker`/`SetOrderEndBlocker` methods. For more on the module manager, click [here](./01-module-manager.md#manager).
 

docs/build/building-modules/06-keeper.md

@@ -47,46 +47,16 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/keepe
 Let us go through the different parameters:
 
 * An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in an `expected_keepers.go` file in the root of the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself.
-* `storeKey`s grant access to the store(s) of the [multistore](../../learn/advanced/04-store.md) managed by the module. They should always remain unexposed to external modules.
+* `KVStoreService`s grant access to the store(s) of the [multistore](../../learn/advanced/04-store.md) managed by the module. They should always remain unexposed to external modules.
 * `cdc` is the [codec](../../learn/advanced/05-encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces.
 * The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated.
 
 Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../../learn/beginner/00-app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them.
 
 ## Implementing Methods
 
-`Keeper`s primarily expose getter and setter methods for the store(s) managed by their module. These methods should remain as simple as possible and strictly be limited to getting or setting the requested value, as validity checks should have already been performed by the [`Msg` server](./03-msg-services.md) when `keeper`s' methods are called.
+`Keeper`s primarily expose methods for business logic, as validity checks should have already been performed by the [`Msg` server](./03-msg-services.md) when `keeper`s' methods are called.
 
-Typically, a *getter* method will have the following signature
-
-```go
-func (k Keeper) Get(ctx context.Context, key string) returnType
-```
-
-and the method will go through the following steps:
-
-1. Retrieve the appropriate store from the `ctx` using the `storeKey`. This is done through the `KVStore(storeKey sdk.StoreKey)` method of the `ctx`. Then it's preferred to use the `prefix.Store` to access only the desired limited subset of the store for convenience and safety.
-2. If it exists, get the `[]byte` value stored at location `[]byte(key)` using the `Get(key []byte)` method of the store.
-3. Unmarshall the retrieved value from `[]byte` to `returnType` using the codec `cdc`. Return the value.
-
-Similarly, a *setter* method will have the following signature
-
-```go
-func (k Keeper) Set(ctx context.Context, key string, value valueType)
-```
-
-and the method will go through the following steps:
-
-1. Retrieve the appropriate store from the `ctx` using the `storeKey`. This is done through the `KVStore(storeKey sdk.StoreKey)` method of the `ctx`. It's preferred to use the `prefix.Store` to access only the desired limited subset of the store for convenience and safety.
-2. Marshal `value` to `[]byte` using the codec `cdc`.
-3. Set the encoded value in the store at location `key` using the `Set(key []byte, value []byte)` method of the store.
-
-For more, see an example of `keeper`'s [methods implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/keeper.go).
-
-The [module `KVStore`](../../learn/advanced/04-store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys.
-
-This is an example from the `auth` module to iterate accounts:
-
-```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/keeper/account.go
-```
+<!-- markdown-link-check-disable -->
+State management is recommended to be done via [Collections](../packages/collections) 
+<!-- The above link is created via the script to generate docs  -->

docs/build/building-modules/07-invariants.md

@@ -4,6 +4,8 @@ sidebar_position: 1
 
 # Invariants
 
+<!-- TODO: figure what is the future of invariants -->
+
 :::note Synopsis
 An invariant is a property of the application that should always be true. In the context of the Cosmos SDK, an `Invariant` is a function that checks for a particular invariant. These functions are useful to detect bugs early on and act upon them to limit their potential consequences (e.g. by halting the chain). They are also useful in the development process of the application to detect bugs via simulations.
 :::

docs/build/building-modules/08-genesis.md

@@ -56,7 +56,7 @@ The [module manager](./01-module-manager.md#manager) of the application is respo
 See an example of `InitGenesis` from the `auth` module:
 
 ```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/keeper/genesis.go#L8-L35
+https://github.com/cosmos/cosmos-sdk/blob/452129d6aa45134f598f05be13f3fd961ff9734e/x/auth/keeper/genesis.go#L12-L43
 ```
 
 ### `ExportGenesis`
@@ -66,7 +66,7 @@ The `ExportGenesis` method is executed whenever an export of the state is made.
 See an example of `ExportGenesis` from the `auth` module.
 
 ```go reference
-https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/keeper/genesis.go#L37-L49
+https://github.com/cosmos/cosmos-sdk/blob/452129d6aa45134f598f05be13f3fd961ff9734e/x/auth/keeper/genesis.go#L45-L60
 ```
 
 ### GenesisTxHandler