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,31 +20,34 @@ 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(
 	logger log.Logger,
 	db corestore.KVStoreWithBatch,
-	traceStore io.Writer,
 	loadLatest bool,
 	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-002-docs-structure.md

@@ -75,7 +75,7 @@ Accepted
 ### Neutral
 
 * We need to move a bunch of deprecated stuff to `/_attic` folder.
-* We need to integrate content in `docs/sdk/docs/core` in `concepts`.
+* We need to integrate content from `docs/sdk/docs/core` into `concepts`.
 * We need to move all the content that currently lives in `docs` and does not fit in new structure (like `lotion`, intro material, whitepaper) to the website repository.
 * Update `DOCS_README.md`
 

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,21 +10,21 @@ 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
 metrics may be added or removed at will and without much friction. To do this, we will use the
 [go-metrics](https://github.com/hashicorp/go-metrics) library.
 
 Finally, operators may enable telemetry along with specific configuration options. If enabled, metrics
-will be exposed via `/metrics?format={text|prometheus}` via the API server.
+will be exposed at `/metrics?format={text|prometheus}` via the API server.
 
 ## Decision
 
@@ -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-016-validator-consensus-key-rotation.md

@@ -38,7 +38,7 @@ Also, it should be noted that this ADR includes only the simplest form of consen
     * parameters can be decided by governance and stored in genesis file.
 * key rotation fee
     * a validator should pay `KeyRotationFee` to rotate the consensus key which is calculated as below
-    * `KeyRotationFee` = (max(`VotingPowerPercentage` *100, 1)* `InitialKeyRotationFee`) * 2^(number of rotations in `ConsPubKeyRotationHistory` in recent unbonding period)
+    * `KeyRotationFee` = (max(`VotingPowerPercentage` *100, 1)* `InitialKeyRotationFee`) * 2^(number of rotations in `ConsPubKeyRotationHistory` during a recent unbonding period)
 * evidence module
     * evidence module can search corresponding consensus key for any height from slashing keeper so that it can decide which consensus key is supposed to be used for the given height.
 * abci.ValidatorUpdate

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/enterprise/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