chore: Sync docs from cosmos-sdk/docs

Author: tac0turtle

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

@@ -11,7 +11,7 @@ ABCI 2.0 (colloquially called ABCI++) allows an application to extend a pre-comm
 validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/abci.go#L32):
 
 ```go
-type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error)
+type ExtendVoteHandler func(Context, *abci.ExtendVoteRequest) (*abci.ExtendVoteResponse, 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.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error)
+type VerifyVoteExtensionHandler func(Context, *abci.VerifyVoteExtensionRequest) (*abci.VerifyVoteExtensionResponse, error)
 ```
 
 An application can set this handler in `app.go` via the `baseapp.SetVerifyVoteExtensionHandler`
@@ -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.RequestFinalizeBlock) error {
+app.SetPreBlocker(func(ctx sdk.Context, req *abci.FinalizeBlockRequest) 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

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

@@ -23,7 +23,7 @@ We propose middleware-solution, which could help developers implement the follow
 * call panic for specific error cases;
 
 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)).
+`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

docs/build/architecture/adr-032-typed-events.md

@@ -22,7 +22,7 @@ Currently in the Cosmos SDK, events are defined in the handlers for each message
 
 Currently in the Cosmos SDK, events are defined in the handlers for each message, meaning each module doesn't have a cannonical set of types for each event. Above all else this makes these events difficult to consume as it requires a great deal of raw string matching and parsing. This proposal focuses on updating the events to use **typed events** defined in each module such that emiting and subscribing to events will be much easier. This workflow comes from the experience of the Akash Network team.
 
-[Our platform](http://github.com/ovrclk/akash) requires a number of programatic on chain interactions both on the provider (datacenter - to bid on new orders and listen for leases created) and user (application developer - to send the app manifest to the provider) side. In addition the Akash team is now maintaining the IBC [`relayer`](https://github.com/ovrclk/relayer), another very event driven process. In working on these core pieces of infrastructure, and integrating lessons learned from Kubernetes developement, our team has developed a standard method for defining and consuming typed events in Cosmos SDK modules. We have found that it is extremely useful in building this type of event driven application.
+[Our platform](http://github.com/ovrclk/akash) requires a number of programatic on chain interactions both on the provider (datacenter - to bid on new orders and listen for leases created) and user (application developer - to send the app manifest to the provider) side. In addition the Akash team is now maintaining the IBC [`relayer`](https://github.com/ovrclk/relayer), another very event driven process. In working on these core pieces of infrastructure, and integrating lessons learned from Kubernetes development, our team has developed a standard method for defining and consuming typed events in Cosmos SDK modules. We have found that it is extremely useful in building this type of event driven application.
 
 As the Cosmos SDK gets used more extensively for apps like `peggy`, other peg zones, IBC, DeFi, etc... there will be an exploding demand for event driven applications to support new features desired by users. We propose upstreaming our findings into the Cosmos SDK to enable all Cosmos SDK applications to quickly and easily build event driven apps to aid their core application. Wallets, exchanges, explorers, and defi protocols all stand to benefit from this work.
 

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

@@ -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.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error
+	ListenFinalizeBlock(ctx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error
 	// ListenCommit updates the steaming service with the latest Commit messages and state changes
-	ListenCommit(ctx context.Context, res abci.ResponseCommit, changeSet []*StoreKVPair) error
+	ListenCommit(ctx context.Context, res abci.CommitResponse, 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.RequestFinalizeBlock) abci.ResponseFinalizeBlock {
+func (app *BaseApp) FinalizeBlock(req abci.FinalizeBlockRequest) abci.FinalizeBlockResponse {
 
-    var abciRes abci.ResponseFinalizeBlock
+    var abciRes abci.FinalizeBlockResponse
     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.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) {
+                go func(req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) {
                     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.RequestFinalizeBlock) abci.ResponseFi
 ```
 
 ```go
-func (app *BaseApp) Commit() abci.ResponseCommit {
+func (app *BaseApp) Commit() abci.CommitResponse {
 
     ...
 
-    res := abci.ResponseCommit{
+    res := abci.CommitResponse{
         Data:         commitID.Hash,
         RetainHeight: retainHeight,
     }
@@ -314,7 +314,7 @@ func (app *BaseApp) Commit() abci.ResponseCommit {
         blockHeight := ctx.BlockHeight()
         changeSet := app.cms.PopStateCache()
         if app.abciListenersAsync {
-            go func(res abci.ResponseCommit, changeSet []store.StoreKVPair) {
+            go func(res abci.CommitResponse, 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.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error {
+func (m *GRPCClient) ListenFinalizeBlock(goCtx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) 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.ResponseCommit, changeSet []store.StoreKVPair) error {
+func (m *GRPCClient) ListenCommit(goCtx context.Context, res abci.CommitResponse, 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.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error {
+func (m *ABCIListenerPlugin) ListenFinalizeBlock(ctx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error {
     // send data to external system
 }
 
-func (m *ABCIListenerPlugin) ListenCommit(ctx context.Context, res abci.ResponseCommit, changeSet []store.StoreKVPair) error {
+func (m *ABCIListenerPlugin) ListenCommit(ctx context.Context, res abci.CommitResponse, changeSet []store.StoreKVPair) error {
     // send data to external system
 }
 

docs/build/architecture/adr-040-storage-and-smt-state-commitments.md

@@ -92,16 +92,16 @@ A new database snapshot will be created in every `EndBlocker` and identified by
 NOTE: `Commit` must be called exactly once per block. Otherwise we risk going out of sync for the version number and block height.
 NOTE: For the Cosmos SDK storage, we may consider splitting that interface into `Committer` and `PruningCommitter` - only the multiroot should implement `PruningCommitter` (cache and prefix store don't need pruning).
 
-Number of historical versions for `abci.RequestQuery` and state sync snapshots is part of a node configuration, not a chain configuration (configuration implied by the blockchain consensus). A configuration should allow to specify number of past blocks and number of past blocks modulo some number (eg: 100 past blocks and one snapshot every 100 blocks for past 2000 blocks). Archival nodes can keep all past versions.
+Number of historical versions for `abci.QueryRequest` and state sync snapshots is part of a node configuration, not a chain configuration (configuration implied by the blockchain consensus). A configuration should allow to specify number of past blocks and number of past blocks modulo some number (eg: 100 past blocks and one snapshot every 100 blocks for past 2000 blocks). Archival nodes can keep all past versions.
 
 Pruning old snapshots is effectively done by a database. Whenever we update a record in `SC`, SMT won't update nodes - instead it creates new nodes on the update path, without removing the old one. Since we are snapshotting each block, we need to change that mechanism to immediately remove orphaned nodes from the database. This is a safe operation - snapshots will keep track of the records and make it available when accessing past versions.
 
 To manage the active snapshots we will either use a DB _max number of snapshots_ option (if available), or we will remove DB snapshots in the `EndBlocker`. The latter option can be done efficiently by identifying snapshots with block height and calling a store function to remove past versions.
 
 #### Accessing old state versions
 
-One of the functional requirements is to access old state. This is done through `abci.RequestQuery` structure.  The version is specified by a block height (so we query for an object by a key `K` at block height `H`). The number of old versions supported for `abci.RequestQuery` is configurable. Accessing an old state is done by using available snapshots.
-`abci.RequestQuery` doesn't need old state of `SC` unless the `prove=true` parameter is set. The SMT merkle proof must be included in the `abci.ResponseQuery` only if both `SC` and `SS` have a snapshot for requested version.
+One of the functional requirements is to access old state. This is done through `abci.QueryRequest` structure.  The version is specified by a block height (so we query for an object by a key `K` at block height `H`). The number of old versions supported for `abci.QueryRequest` is configurable. Accessing an old state is done by using available snapshots.
+`abci.QueryRequest` doesn't need old state of `SC` unless the `prove=true` parameter is set. The SMT merkle proof must be included in the `abci.QueryResponse` only if both `SC` and `SS` have a snapshot for requested version.
 
 Moreover, Cosmos SDK could provide a way to directly access a historical state. However, a state machine shouldn't do that - since the number of snapshots is configurable, it would lead to nondeterministic execution.
 

docs/build/architecture/adr-047-extend-upgrade-plan.md

@@ -95,6 +95,7 @@ All fields in the `UpgradeInstructions` are optional.
   | `30`             | `pre-upgrade` command was executed but failed. This fails the entire upgrade.                                       |
   | `31`             | `pre-upgrade` command was executed but failed. But the command is retried until exit code `1` or `30` are returned. |
   If defined, then the app supervisors (e.g. Cosmovisor) MUST NOT run `app pre-run`.
+
 * `post_run` is a command to run after the upgraded chain has been started. If defined, this command MUST be only executed at most once by an upgrading node.
   The output and exit code SHOULD be logged but SHOULD NOT affect the running of the upgraded chain.
   The working directory this command runs from MUST be `{DAEMON_HOME}/cosmovisor/{upgrade name}`.

docs/build/architecture/adr-050-sign-mode-textual-annex1.md

@@ -195,6 +195,7 @@ Messages that have a custom encoding, including `google.protobuf.Timestamp`, `go
 #### Examples
 
 Message header screen is stripped, one-level of indentation removed:
+
 ```
 /cosmos.gov.v1.Vote
 > Proposal id: 4
@@ -210,6 +211,7 @@ Message header screen is stripped, one-level of indentation removed:
 ```
 
 Message with custom encoding:
+
 ```
 /cosmos.base.v1beta1.Coin
 > 10uatom
@@ -271,8 +273,9 @@ Examples:
 * The hexadecimal string is finally separated into groups of 4 digits, with a space `' '` as separator. If the bytes length is odd, the 2 remaining hexadecimal characters are at the end.
 
 The number 35 was chosen because it is the longest length where the hashed-and-prefixed representation is longer than the original data directly formatted, using the 3 rules above. More specifically:
-- a 35-byte array will have 70 hex characters, plus 17 space characters, resulting in 87 characters.
-- byte arrays starting from length 36 will be be hashed to 32 bytes, which is 64 hex characters plus 15 spaces, and with the `SHA-256=` prefix, it takes 87 characters.
+
+* a 35-byte array will have 70 hex characters, plus 17 space characters, resulting in 87 characters.
+* byte arrays starting from length 36 will be be hashed to 32 bytes, which is 64 hex characters plus 15 spaces, and with the `SHA-256=` prefix, it takes 87 characters.
 Also, secp256k1 public keys have length 33, so their Textual representation is not their hashed value, which we would like to avoid.
 
 Note: Data longer than 35 bytes are not rendered in a way that can be inverted. See ADR-050's [section about invertability](./adr-050-sign-mode-textual.md#invertible-rendering) for a discussion.

docs/build/architecture/adr-054-semver-compatible-modules.md

@@ -424,6 +424,7 @@ way that requires duplication and differing sets of design principles (protobuf
 while golang APIs would forbid it).
 
 Other downsides to this approach are:
+
 * no clear roadmap to supporting modules in other languages like Rust
 * doesn't get us any closer to proper object capability security (one of the goals of ADR 033)
 * ADR 033 needs to be done properly anyway for the set of use cases which do need it
@@ -447,6 +448,7 @@ languages, possibly executed within a WASM VM.
 
 To declare minor API revisions of proto files, we propose the following guidelines (which were already documented
 in [cosmos.app.v1alpha module options](../proto/cosmos/app/v1alpha1/module.proto)):
+
 * proto packages which are revised from their initial version (considered revision `0`) should include a `package`
 * comment in some .proto file containing the test `Revision N` at the start of a comment line where `N` is the current
 revision number.
@@ -522,6 +524,7 @@ func ProtoImage(protoImage []byte) Option {}
 ```
 
 This approach allows us to support several ways protobuf files might be generated:
+
 * proto files generated internally to a module (use `ProtoFiles`)
 * the API module approach with pinned file descriptors (use `ProtoImage`)
 * gogo proto (use `GzippedProtoFiles`)

docs/build/architecture/adr-055-orm.md

@@ -64,6 +64,7 @@ A code generator is included with the ORM which creates type safe wrappers aroun
 implementation and is the recommended way for modules to use the ORM.
 
 The ORM tests provide a simplified bank module demonstration which illustrates:
+
 * [ORM proto options](https://github.com/cosmos/cosmos-sdk/blob/0d846ae2f0424b2eb640f6679a703b52d407813d/orm/internal/testpb/bank.proto)
 * [Generated Code](https://github.com/cosmos/cosmos-sdk/blob/0d846ae2f0424b2eb640f6679a703b52d407813d/orm/internal/testpb/bank.cosmos_orm.go)
 * [Example Usage in a Module Keeper](https://github.com/cosmos/cosmos-sdk/blob/0d846ae2f0424b2eb640f6679a703b52d407813d/orm/model/ormdb/module_test.go)

docs/build/architecture/adr-057-app-wiring.md

@@ -303,15 +303,17 @@ Code generation requires that all providers and invokers and their parameters ar
 
 When we start creating semantically versioned SDK modules that are in standalone go modules, a state machine breaking
 change to a module should be handled as follows:
-- the semantic major version should be incremented, and
-- a new semantically versioned module config protobuf type should be created.
+
+* the semantic major version should be incremented, and
+* a new semantically versioned module config protobuf type should be created.
 
 For instance, if we have the SDK module for bank in the go module `github.com/cosmos/cosmos-sdk/x/bank` with the module config type
 `cosmos.bank.module.v1.Module`, and we want to make a state machine breaking change to the module, we would:
-- create a new go module `github.com/cosmos/cosmos-sdk/x/bank/v2`,
-- with the module config protobuf type `cosmos.bank.module.v2.Module`.
 
-This _does not_ mean that we need to increment the protobuf API version for bank. Both modules can support
+* create a new go module `github.com/cosmos/cosmos-sdk/x/bank/v2`,
+* with the module config protobuf type `cosmos.bank.module.v2.Module`.
+
+This *does not* mean that we need to increment the protobuf API version for bank. Both modules can support
 `cosmos.bank.v1`, but `github.com/cosmos/cosmos-sdk/x/bank/v2` will be a separate go module with a separate module config type.
 
 This practice will eventually allow us to use appconfig to load new versions of a module via a configuration change.
@@ -320,7 +322,7 @@ Effectively, there should be a 1:1 correspondence between a semantically version
 versioned module config protobuf type, and major versioning bumps should occur whenever state machine breaking changes
 are made to a module.
 
-NOTE: SDK modules that are standalone go modules _should not_ adopt semantic versioning until the concerns described in
+NOTE: SDK modules that are standalone go modules *should not* adopt semantic versioning until the concerns described in
 [ADR 054: Module Semantic Versioning](./adr-054-semver-compatible-modules.md) are
 addressed. The short-term solution for this issue was left somewhat unresolved. However, the easiest tactic is
 likely to use a standalone API go module and follow the guidelines described in this comment: https://github.com/cosmos/cosmos-sdk/pull/11802#issuecomment-1406815181. For the time-being, it is recommended that