chore: Sync docs from cosmos-sdk/docs

Author: tac0turtle

docs/build/abci/01-prepare-proposal.md

@@ -26,7 +26,7 @@ The Cosmos SDK defines the `DefaultProposalHandler` type, which provides applica
 `PrepareProposal` and `ProcessProposal` handlers. If you decide to implement your
 own `PrepareProposal` handler, you must ensure that the transactions
 selected DO NOT exceed the maximum block gas (if set) and the maximum bytes provided
-by `req.MaxBytes`.
+by `req.MaxTxBytes`.
 
 ```go reference
 https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/baseapp/abci_utils.go

docs/build/abci/03-vote-extensions.md

@@ -8,10 +8,10 @@ defined in ABCI++.
 ## Extend Vote
 
 ABCI 2.0 (colloquially called ABCI++) allows an application to extend a pre-commit vote with arbitrary data. This process does NOT have to be deterministic, and the data returned can be unique to the
-validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/abci.go#L32):
+validator process. The Cosmos SDK defines [`sdk.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/abci.go#L32):
 
 ```go
-type ExtendVoteHandler func(Context, *abci.ExtendVoteRequest) (*abci.ExtendVoteResponse, error)
+type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error)
 ```
 
 An application can set this handler in `app.go` via the `baseapp.SetExtendVoteHandler`
@@ -38,7 +38,7 @@ other validators when validating their pre-commits. For a given vote extension,
 this process MUST be deterministic. The Cosmos SDK defines [`sdk.VerifyVoteExtensionHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/types/abci.go#L29-L31):
 
 ```go
-type VerifyVoteExtensionHandler func(Context, *abci.VerifyVoteExtensionRequest) (*abci.VerifyVoteExtensionResponse, error)
+type VerifyVoteExtensionHandler func(Context, *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error)
 ```
 
 An application can set this handler in `app.go` via the `baseapp.SetVerifyVoteExtensionHandler`
@@ -49,7 +49,7 @@ validators will share the same view of what vote extensions they verify dependin
 on how votes are propagated. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#verifyvoteextension)
 for more details.
 
-Additionally, please keep in mind that performance can be degraded if vote extensions are too big (https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed), so we highly recommend a size validation in `VerifyVoteExtensions`.
+Additionally, please keep in mind that performance can be degraded if vote extensions are too big (https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed), so we highly recommend a size validation in `ValidateVoteExtensions`.
 
 
 ## Vote Extension Propagation
@@ -78,7 +78,7 @@ will be available to the application during the subsequent `FinalizeBlock` call.
 An example of how a pre-FinalizeBlock hook could look like is shown below:
 
 ```go
-app.SetPreBlocker(func(ctx sdk.Context, req *abci.FinalizeBlockRequest) error {
+app.SetPreBlocker(func(ctx sdk.Context, req *abci.RequestFinalizeBlock) (*sdk.ResponsePreBlock, error) {
     allVEs := []VE{} // store all parsed vote extensions here
     for _, tx := range req.Txs {
         // define a custom function that tries to parse the tx as a vote extension
@@ -95,10 +95,10 @@ app.SetPreBlocker(func(ctx sdk.Context, req *abci.FinalizeBlockRequest) error {
     result := compute(allVEs)
     err := storeVEResult(ctx, result)
     if err != nil {
-        return err
+        return nil, err
     }
 
-    return nil
+    return &sdk.ResponsePreBlock{}, nil
 })
 
 ```

docs/build/abci/04-checktx.md

@@ -20,17 +20,15 @@ https://github.com/cosmos/cosmos-sdk/blob/31c604762a434c7b676b6a89897ecbd7c4653a
 
 ## CheckTx Handler
 
-`CheckTxHandler` allows users to extend the logic of `CheckTx`. `CheckTxHandler` is called by passing context and the transaction bytes received through ABCI. It is required that the handler returns deterministic results given the same transaction bytes. 
-
-:::note
-we return the raw decoded transaction here to avoid decoding it twice.
-:::
+`CheckTxHandler` allows applications to extend the logic of `CheckTx`. It is invoked with the ABCI request and a `RunTx` function that executes the standard `CheckTx` pipeline (ante handlers, gas accounting and mempool interaction). The implementation of `CheckTxHandler` MUST be deterministic for a given `RequestCheckTx`.
 
 ```go
-type CheckTxHandler func(ctx sdk.Context, tx []byte) (Tx, error)
+type CheckTxHandler func(RunTx, *abci.RequestCheckTx) (*abci.ResponseCheckTx, error)
 ```
 
-Setting a custom `CheckTxHandler` is optional. It can be done from your app.go file:
+The provided `RunTx` function does not override ante handlers and does not allow changing the execution mode; it simply runs the transaction through the normal `CheckTx` path and returns the result that can be used to construct a `ResponseCheckTx`.
+
+Setting a custom `CheckTxHandler` is optional. It can be done from your `app.go` file by setting the handler on `BaseApp`:
 
 ```go
 func NewSimApp(
@@ -41,10 +39,16 @@ func NewSimApp(
 	appOpts servertypes.AppOptions,
 	baseAppOptions ...func(*baseapp.BaseApp),
 ) *SimApp {
-  ...
-  // Create ChecktxHandler
-  checktxHandler := abci.NewCustomCheckTxHandler(...)
-  app.SetCheckTxHandler(checktxHandler)
-  ...
+	 ...
+	 checkTxOpt := func(app *baseapp.BaseApp) {
+	 	app.SetCheckTxHandler(func(runTx sdk.RunTx, req *abci.RequestCheckTx) (*abci.ResponseCheckTx, error) {
+	 		// custom pre- or post-processing logic can be added here
+	 		return runTx(req.Tx, nil)
+	 	})
+	 }
+	 baseAppOptions = append(baseAppOptions, checkTxOpt)
+	 ...
 }
 ```
+
+When `RequestCheckTx.Type` is `abci.CheckTxType_New`, the transaction is evaluated for admission into the mempool; when it is `abci.CheckTxType_Recheck`, the existing mempool transaction is re-evaluated and may be removed if it no longer passes validation. Successful `CheckTx` executions update an internal CheckTx state, which is reset when a block is committed.

docs/build/architecture/adr-006-secret-store-replacement.md

@@ -15,7 +15,7 @@ This is not desirable for a number of reasons. Perhaps the biggest reason is ins
 
 All modern desktop computers OS (Ubuntu, Debian, MacOS, Windows) provide a built-in secret store that is designed to allow applications to store information that is isolated from all other applications and requires passphrase entry to access the data.
 
-We are seeking solution that provides a common abstraction layer to the many different backends and reasonable fallback for minimal platforms that don’t provide a native secret store.
+We are seeking a solution that provides a common abstraction layer to the many different backends and reasonable fallback for minimal platforms that don’t provide a native secret store.
 
 ## Decision
 

docs/build/architecture/adr-013-metrics.md

@@ -10,13 +10,13 @@ Proposed
 
 ## Context
 
-Telemetry is paramount into debugging and understanding what the application is doing and how it is
+Telemetry is paramount to debugging and understanding what the application is doing and how it is
 performing. We aim to expose metrics from modules and other core parts of the Cosmos SDK.
 
 In addition, we should aim to support multiple configurable sinks that an operator may choose from.
 By default, when telemetry is enabled, the application should track and expose metrics that are
 stored in-memory. The operator may choose to enable additional sinks, where we support only
-[Prometheus](https://prometheus.io/) for now, as it's battle-tested, simple to setup, open source,
+[Prometheus](https://prometheus.io/) for now, as it's battle-tested, simple to set up, open source,
 and is rich with ecosystem tooling.
 
 We must also aim to integrate metrics into the Cosmos SDK in the most seamless way possible such that
@@ -41,7 +41,7 @@ We will add an additional configuration block to `app.toml` that defines telemet
 service-name = {{ .Telemetry.ServiceName }}
 
 # Enabled enables the application telemetry functionality. When enabled,
-# an in-memory sink is also enabled by default. Operators may also enabled
+# an in-memory sink is also enabled by default. Operators may also enable
 # other sinks such as Prometheus.
 enabled = {{ .Telemetry.Enabled }}
 

docs/build/architecture/adr-022-custom-panic-handling.md

@@ -26,8 +26,8 @@ It will also make `OutOfGas` case and `default` case one of the middlewares.
 `Default` case wraps recovery object to an error and logs it ([example middleware implementation](#recovery-middleware)).
 
 Our project has a sidecar service running alongside the blockchain node (smart contracts virtual machine). It is
-essential that node <-> sidecar connectivity stays stable for TXs processing. So when the communication breaks we need
-to crash the node and reboot it once the problem is solved. That behaviour makes the node's state machine execution
+essential that node <-> sidecar connectivity stays stable for TXs processing. So when the communication breaks, we need
+to crash the node and reboot it once the problem is solved. That behavior makes the node's state machine execution
 deterministic. As all keeper panics are caught by runTx's `defer()` handler, we have to adjust the BaseApp code
 in order to customize it.
 
@@ -97,7 +97,7 @@ Function receives a `recoveryObj` object and returns:
 * (next `recoveryMiddleware`, `nil`) if object wasn't handled (not a target type) by `RecoveryHandler`;
 * (`nil`, not nil `error`) if input object was handled and other middlewares in the chain should not be executed;
 * (`nil`, `nil`) in case of invalid behavior. Panic recovery might not have been properly handled;
-this can be avoided by always using a `default` as a rightmost middleware in the chain (always returns an `error`');
+this can be avoided by always using a `default` as a rightmost middleware in the chain (always returns an `error`);
 
 `OutOfGas` middleware example:
 
@@ -153,7 +153,7 @@ That way we can create a middleware chain which is executed from left to right,
 
 ##### BaseApp changes
 
-The `default` middleware chain must exist in a `BaseApp` object. `Baseapp` modifications:
+The `default` middleware chain must exist in a `BaseApp` object. `BaseApp` modifications:
 
 ```go
 type BaseApp struct {

docs/build/architecture/adr-030-authz-module.md

@@ -25,7 +25,7 @@ The concrete use cases which motivated this module include:
 delegated stake
 * "sub-keys" functionality, as originally proposed in [\#4480](https://github.com/cosmos/cosmos-sdk/issues/4480) which
 is a term used to describe the functionality provided by this module together with
-the `fee_grant` module from [ADR 029](./adr-029-fee-grant-module.md) and the [group module](https://github.com/cosmos/cosmos-sdk/tree/main/x/group).
+the `fee_grant` module from [ADR 029](./adr-029-fee-grant-module.md) and the [group module](https://github.com/cosmos/cosmos-sdk/tree/main/contrib/x/group).
 
 The "sub-keys" functionality roughly refers to the ability for one account to grant some subset of its capabilities to
 other accounts with possibly less robust, but easier to use security measures. For instance, a master account representing

docs/build/architecture/adr-038-state-listening.md

@@ -7,7 +7,7 @@
 * 10/14/2022:
     * Add `ListenCommit`, flatten the state writes in a block to a single batch.
     * Remove listeners from cache stores, should only listen to `rootmulti.Store`.
-    * Remove `HaltAppOnDeliveryError()`, the errors are propagated by default, the implementations should return nil if they don't want to propagate errors.
+    * Remove `HaltAppOnDeliveryError()`, the errors are propagated by default, the implementations should return nil if don't want to propagate errors.
 * 26/05/2023: Update with ABCI 2.0
 
 ## Status
@@ -20,7 +20,7 @@ This ADR defines a set of changes to enable listening to state changes of indivi
 
 ## Context
 
-Currently, KVStore data can be remotely accessed through [Queries](https://docs.cosmos.network/main/build/building-modules/messages-and-queries#queries)
+Currently, KVStore data can be remotely accessed through [Queries](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules/messages-and-queries.md#queries)
 which proceed either through Tendermint and the ABCI, or through the gRPC server.
 In addition to these request/response queries, it would be beneficial to have a means of listening to state changes as they occur in real time.
 
@@ -40,7 +40,7 @@ type MemoryListener struct {
 	stateCache []StoreKVPair
 }
 
-// NewMemoryListener creates a listener that accumulates the state writes in memory.
+// NewMemoryListener creates a listener that accumulate the state writes in memory.
 func NewMemoryListener() *MemoryListener {
 	return &MemoryListener{}
 }
@@ -114,7 +114,7 @@ func (s *Store) Delete(key []byte) {
 
 ### MultiStore interface updates
 
-We will update the `CommitMultiStore` interface to allow us to wrap a `MemoryListener` to a specific `KVStore`.
+We will update the `CommitMultiStore` interface to allow us to wrap a `Memorylistener` to a specific `KVStore`.
 Note that the `MemoryListener` will be attached internally by the concrete `rootmulti` implementation.
 
 ```go
@@ -224,9 +224,9 @@ so that the service can group the state changes with the ABCI requests.
 // ABCIListener is the interface that we're exposing as a streaming service.
 type ABCIListener interface {
 	// ListenFinalizeBlock updates the streaming service with the latest FinalizeBlock messages
-	ListenFinalizeBlock(ctx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error
-	// ListenCommit updates the streaming service with the latest Commit messages and state changes
-	ListenCommit(ctx context.Context, res abci.CommitResponse, changeSet []*StoreKVPair) error
+	ListenFinalizeBlock(ctx context.Context, req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error
+	// ListenCommit updates the steaming service with the latest Commit messages and state changes
+	ListenCommit(ctx context.Context, res abci.ResponseCommit, changeSet []*StoreKVPair) error
 }
 ```
 
@@ -267,16 +267,16 @@ We will modify the `FinalizeBlock` and `Commit` methods to pass ABCI requests an
 to any streaming service hooks registered with the `BaseApp`.
 
 ```go
-func (app *BaseApp) FinalizeBlock(req abci.FinalizeBlockRequest) abci.FinalizeBlockResponse {
+func (app *BaseApp) FinalizeBlock(req abci.RequestFinalizeBlock) abci.ResponseFinalizeBlock {
 
-    var abciRes abci.FinalizeBlockResponse
+    var abciRes abci.ResponseFinalizeBlock
     defer func() {
         // call the streaming service hook with the FinalizeBlock messages
         for _, abciListener := range app.abciListeners {
             ctx := app.finalizeState.ctx
             blockHeight := ctx.BlockHeight()
             if app.abciListenersAsync {
-                go func(req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) {
+                go func(req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) {
                     if err := app.abciListener.FinalizeBlock(blockHeight, req, res); err != nil {
                         app.logger.Error("FinalizeBlock listening hook failed", "height", blockHeight, "err", err)
                     }
@@ -299,11 +299,11 @@ func (app *BaseApp) FinalizeBlock(req abci.FinalizeBlockRequest) abci.FinalizeBl
 ```
 
 ```go
-func (app *BaseApp) Commit() abci.CommitResponse {
+func (app *BaseApp) Commit() abci.ResponseCommit {
 
     ...
 
-    res := abci.CommitResponse{
+    res := abci.ResponseCommit{
         Data:         commitID.Hash,
         RetainHeight: retainHeight,
     }
@@ -314,7 +314,7 @@ func (app *BaseApp) Commit() abci.CommitResponse {
         blockHeight := ctx.BlockHeight()
         changeSet := app.cms.PopStateCache()
         if app.abciListenersAsync {
-            go func(res abci.CommitResponse, changeSet []store.StoreKVPair) {
+            go func(res abci.ResponseCommit, changeSet []store.StoreKVPair) {
                 if err := app.abciListener.ListenCommit(ctx, res, changeSet); err != nil {
                     app.logger.Error("ListenCommit listening hook failed", "height", blockHeight, "err", err)
                 }
@@ -433,13 +433,13 @@ type GRPCClient struct {
     client ABCIListenerServiceClient
 }
 
-func (m *GRPCClient) ListenFinalizeBlock(goCtx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error {
+func (m *GRPCClient) ListenFinalizeBlock(goCtx context.Context, req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error {
     ctx := sdk.UnwrapSDKContext(goCtx)
     _, err := m.client.ListenDeliverTx(ctx, &ListenDeliverTxRequest{BlockHeight: ctx.BlockHeight(), Req: req, Res: res})
     return err
 }
 
-func (m *GRPCClient) ListenCommit(goCtx context.Context, res abci.CommitResponse, changeSet []store.StoreKVPair) error {
+func (m *GRPCClient) ListenCommit(goCtx context.Context, res abci.ResponseCommit, changeSet []store.StoreKVPair) error {
     ctx := sdk.UnwrapSDKContext(goCtx)
     _, err := m.client.ListenCommit(ctx, &ListenCommitRequest{BlockHeight: ctx.BlockHeight(), Res: res, ChangeSet: changeSet})
     return err
@@ -471,11 +471,11 @@ And the pre-compiled Go plugin `Impl`(*this is only used for plugins that are wr
 // ABCIListener is the implementation of the baseapp.ABCIListener interface
 type ABCIListener struct{}
 
-func (m *ABCIListenerPlugin) ListenFinalizeBlock(ctx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error {
+func (m *ABCIListenerPlugin) ListenFinalizeBlock(ctx context.Context, req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error {
     // send data to external system
 }
 
-func (m *ABCIListenerPlugin) ListenCommit(ctx context.Context, res abci.CommitResponse, changeSet []store.StoreKVPair) error {
+func (m *ABCIListenerPlugin) ListenCommit(ctx context.Context, res abci.ResponseCommit, changeSet []store.StoreKVPair) error {
     // send data to external system
 }
 
@@ -529,7 +529,7 @@ func NewStreamingPlugin(name string, logLevel string) (interface{}, error) {
 
 We propose a `RegisterStreamingPlugin` function for the App to register `NewStreamingPlugin`s with the App's BaseApp.
 Streaming plugins can be of `Any` type; therefore, the function takes in an interface vs a concrete type.
-For example, we could have plugins of `ABCIListener`, `WasmListener` or `IBCListener`. Note that `RegisterStreamingPlugin` function
+For example, we could have plugins of `ABCIListener`, `WasmListener` or `IBCListener`. Note that `RegisterStreamingPluing` function
 is helper function and not a requirement. Plugin registration can easily be moved from the App to the BaseApp directly.
 
 ```go
@@ -720,5 +720,5 @@ These changes will provide a means of subscribing to KVStore state changes in re
 
 ### Neutral
 
-* Introduces additional—but optional—complexity to configuring and running a cosmos application
+* Introduces additional- but optional- complexity to configuring and running a cosmos application
 * If an application developer opts to use these features to expose data, they need to be aware of the ramifications/risks of that data exposure as it pertains to the specifics of their application