Merge branch 'main' into main

Author: Alex | Interchain Labs

docs/architecture/adr-016-validator-consensus-key-rotation.md

@@ -9,42 +9,42 @@
 
 Validator consensus key rotation feature has been discussed and requested for a long time, for the sake of safer validator key management policy (e.g. https://github.com/tendermint/tendermint/issues/1136). So, we suggest one of the simplest form of validator consensus key rotation implementation mostly onto Cosmos SDK.
 
-We don't need to make any update on consensus logic in Tendermint because Tendermint does not have any mapping information of consensus key and validator operator key, meaning that from Tendermint point of view, a consensus key rotation of a validator is simply a replacement of a consensus key to another.
+We don't need to make any update on consensus logic in Tendermint because Tendermint does not have any mapping information of consensus key and validator operator key, meaning that from Tendermint's point of view, a consensus key rotation of a validator is simply a replacement of a consensus key to another.
 
-Also, it should be noted that this ADR includes only the simplest form of consensus key rotation without considering multiple consensus keys concept. Such multiple consensus keys concept shall remain a long term goal of Tendermint and Cosmos SDK.
+Also, it should be noted that this ADR includes only the simplest form of consensus key rotation without considering the multiple consensus keys concept. Such multiple consensus keys concept shall remain a long term goal of Tendermint and Cosmos SDK.
 
 ## Decision
 
 ### Pseudo procedure for consensus key rotation
 
 * create new random consensus key.
-* create and broadcast a transaction with a `MsgRotateConsPubKey` that states the new consensus key is now coupled with the validator operator with signature from the validator's operator key.
+* create and broadcast a transaction with a `MsgRotateConsPubKey` that states the new consensus key is now coupled with the validator operator with a signature from the validator's operator key.
 * old consensus key becomes unable to participate on consensus immediately after the update of key mapping state on-chain.
 * start validating with new consensus key.
-* validators using HSM and KMS should update the consensus key in HSM to use the new rotated key after the height `h` when `MsgRotateConsPubKey` committed to the blockchain.
+* validators using HSM and KMS should update the consensus key in HSM to use the new rotated key after the height `h` when `MsgRotateConsPubKey` is committed to the blockchain.
 
 ### Considerations
 
 * consensus key mapping information management strategy
     * store history of each key mapping changes in the kvstore.
-    * the state machine can search corresponding consensus key paired with given validator operator for any arbitrary height in a recent unbonding period.
+    * the state machine can search corresponding consensus key paired with the given validator operator for any arbitrary height in a recent unbonding period.
     * the state machine does not need any historical mapping information which is past more than unbonding period.
 * key rotation costs related to LCD and IBC
-    * LCD and IBC will have traffic/computation burden when there exists frequent power changes
+    * LCD and IBC will have a traffic/computation burden when there exists frequent power changes
     * In current Tendermint design, consensus key rotations are seen as power changes from LCD or IBC perspective
-    * Therefore, to minimize unnecessary frequent key rotation behavior, we limited maximum number of rotation in recent unbonding period and also applied exponentially increasing rotation fee
+    * Therefore, to minimize unnecessary frequent key rotation behavior, we limited the maximum number of rotation in recent unbonding period and also applied exponentially increasing rotation fee
 * limits
     * a validator cannot rotate its consensus key more than `MaxConsPubKeyRotations` time for any unbonding period, to prevent spam.
     * 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)
 * 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 given height.
+    * 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
     * tendermint already has ability to change a consensus key by ABCI communication(`ValidatorUpdate`).
     * validator consensus key update can be done via creating new + delete old by change the power to zero.
-    * therefore, we expect we even do not need to change tendermint codebase at all to implement this feature.
+    * therefore, we expect we do not even need to change Tendermint codebase at all to implement this feature.
 * new genesis parameters in `staking` module
     * `MaxConsPubKeyRotations` : maximum number of rotation can be executed by a validator in recent unbonding period. default value 10 is suggested(11th key rotation will be rejected)
     * `InitialKeyRotationFee` : the initial key rotation fee when no key rotation has happened in recent unbonding period. default value 1atom is suggested(1atom fee for the first key rotation in recent unbonding period)
@@ -108,12 +108,12 @@ Proposed
 
 ### Positive
 
-* Validators can immediately or periodically rotate their consensus key to have better security policy
+* Validators can immediately or periodically rotate their consensus key to have a better security policy
 * improved security against Long-Range attacks (https://nearprotocol.com/blog/long-range-attacks-and-a-new-fork-choice-rule) given a validator throws away the old consensus key(s)
 
 ### Negative
 
-* Slash module needs more computation because it needs to lookup corresponding consensus key of validators for each height
+* Slash module needs more computation because it needs to look up the corresponding consensus key of validators for each height
 * frequent key rotations will make light client bisection less efficient
 
 ### Neutral

docs/architecture/adr-019-protobuf-state-encoding.md

@@ -28,7 +28,7 @@ From the Amino docs:
 
 Amino also aims to have the following goals (not a complete list):
 
-* Binary bytes must be decode-able with a schema.
+* Binary bytes must be decodable with a schema.
 * Schema must be upgradeable.
 * The encoder and decoder logic must be reasonably simple.
 
@@ -65,7 +65,7 @@ will provide two concrete implementations of the `Marshaler` interface: `AminoCo
 * `AminoCodec`: Uses Amino for both binary and JSON encoding.
 * `ProtoCodec`: Uses Protobuf for both binary and JSON encoding.
 
-Modules will use whichever codec that is instantiated in the app. By default, the Cosmos SDK's `simapp`
+Modules will use whichever codec is instantiated in the app. By default, the Cosmos SDK's `simapp`
 instantiates a `ProtoCodec` as the concrete implementation of `Marshaler`, inside the `MakeTestEncodingConfig`
 function. This can be easily overwritten by app developers if they so desire.
 
@@ -144,7 +144,7 @@ above, apps can still choose to use `oneof` to encode state and transactions
 but it is not the recommended approach. If apps do choose to use `oneof`s
 instead of `Any` they will likely lose compatibility with client apps that
 support multiple chains. Thus developers should think carefully about whether
-they care more about what is possibly a pre-mature optimization or end-user
+they care more about what is possibly a premature optimization or end-user
 and client developer UX.
 
 ### Safe usage of `Any`
@@ -169,7 +169,7 @@ type InterfaceRegistry interface {
     //   registry.RegisterInterface("cosmos_sdk.Msg", (*sdk.Msg)(nil))
     RegisterInterface(protoName string, iface interface{})
 
-    // RegisterImplementations registers impls as a concrete implementations of
+    // RegisterImplementations registers impls as concrete implementations of
     // the interface iface
     // Ex:
     //  registry.RegisterImplementations((*sdk.Msg)(nil), &MsgSend{}, &MsgMultiSend{})
@@ -226,7 +226,7 @@ every module that implements it in order to populate the `InterfaceRegistry`.
 
 ### Using `Any` to encode state
 
-The Cosmos SDK will provide support methods `MarshalInterface` and `UnmarshalInterface` to hide a complexity of wrapping interface types into `Any` and allow easy serialization.
+The Cosmos SDK will provide support methods `MarshalInterface` and `UnmarshalInterface` to hide the complexity of wrapping interface types into `Any` and allow easy serialization.
 
 ```go
 import "github.com/cosmos/cosmos-sdk/codec"
@@ -245,7 +245,7 @@ func UnmarshalEvidence(cdc codec.BinaryCodec, bz []byte) (eviexported.Evidence,
 
 ### Using `Any` in `sdk.Msg`s
 
-A similar concept is to be applied for messages that contain interfaces fields.
+A similar concept is to be applied for messages that contain interface fields.
 For example, we can define `MsgSubmitEvidence` as follows where `Evidence` is
 an interface:
 
@@ -333,7 +333,7 @@ For a more complete comparison to alternative protocols, see [here](https://code
 ### Cap'n Proto
 
 While [Cap’n Proto](https://capnproto.org/) does seem like an advantageous alternative to Protobuf
-due to it's native support for interfaces/generics and built in canonicalization, it does lack the
+due to its native support for interfaces/generics and built-in canonicalization, it does lack the
 rich client ecosystem compared to Protobuf and is a bit less mature.
 
 ### FlatBuffers
@@ -342,7 +342,7 @@ rich client ecosystem compared to Protobuf and is a bit less mature.
 primary difference being that FlatBuffers does not need a parsing/unpacking step to a secondary
 representation before you can access data, often coupled with per-object memory allocation.
 
-However, it would require great efforts into research and full understanding the scope of the migration
+However, it would require great efforts into research and a full understanding the scope of the migration
 and path forward -- which isn't immediately clear. In addition, FlatBuffers aren't designed for
 untrusted inputs.
 

docs/architecture/adr-020-protobuf-transaction-encoding.md

@@ -44,18 +44,18 @@ approach to the approach described below.
 ### Transactions
 
 Since interface values are encoded with `google.protobuf.Any` in state (see [ADR 019](adr-019-protobuf-state-encoding.md)),
-`sdk.Msg`s are encoding with `Any` in transactions.
+`sdk.Msg`s are encoded with `Any` in transactions.
 
 One of the main goals of using `Any` to encode interface values is to have a
 core set of types which is reused by apps so that
 clients can safely be compatible with as many chains as possible.
 
 It is one of the goals of this specification to provide a flexible cross-chain transaction
-format that can serve a wide variety of use cases without breaking client
+format that can serve a wide variety of use cases without breaking the client
 compatibility.
 
 In order to facilitate signing, transactions are separated into `TxBody`,
-which will be re-used by `SignDoc` below, and `signatures`:
+which will be reused by `SignDoc` below, and `signatures`:
 
 ```protobuf
 // types/types.proto
@@ -173,7 +173,7 @@ All of the signing modes below aim to provide the following guarantees:
 * **Predictable Gas**: if I am signing a transaction where I am paying a fee,
   the final gas is fully dependent on what I am signing
 
-These guarantees give the maximum amount confidence to message signers that
+These guarantees give the maximum amount of confidence to message signers that
 manipulation of `Tx`s by intermediaries can't result in any meaningful changes.
 
 #### `SIGN_MODE_DIRECT`
@@ -228,7 +228,7 @@ Signature verifiers do:
 
 In order to support legacy wallets and exchanges, Amino JSON will be temporarily
 supported transaction signing. Once wallets and exchanges have had a
-chance to upgrade to protobuf based signing, this option will be disabled. In
+chance to upgrade to protobuf-based signing, this option will be disabled. In
 the meantime, it is foreseen that disabling the current Amino signing would cause
 too much breakage to be feasible. Note that this is mainly a requirement of the
 Cosmos Hub and other chains may choose to disable Amino signing immediately.
@@ -260,7 +260,7 @@ by `SIGN_MODE_TEXTUAL` when it is implemented.
 
 ### Unknown Field Filtering
 
-Unknown fields in protobuf messages should generally be rejected by transaction
+Unknown fields in protobuf messages should generally be rejected by the transaction
 processors because:
 
 * important data may be present in the unknown fields, that if ignored, will
@@ -415,7 +415,7 @@ To generate a signature in `SIGN_MODE_DIRECT_AUX` these steps would be followed:
         // PublicKey is included in SignDocAux :
         // 1. as a special case for multisig public keys. For multisig public keys,
         // the signer should use the top-level multisig public key they are signing
-        // against, not their own public key. This is to prevent against a form
+        // against, not their own public key. This is to prevent a form
         // of malleability where a signature could be taken out of context of the
         // multisig key that was intended to be signed for
         // 2. to guard against scenario where configuration information is encoded
@@ -431,7 +431,7 @@ To generate a signature in `SIGN_MODE_DIRECT_AUX` these steps would be followed:
     ```
 
 2. Sign the encoded `SignDocAux` bytes
-3. Send their signature and `SignerInfo` to primary signer who will then
+3. Send their signature and `SignerInfo` to the primary signer who will then
    sign and broadcast the final transaction (with `SIGN_MODE_DIRECT` and `AuthInfo`
    added) once enough signatures have been collected
 

docs/architecture/adr-021-protobuf-query-encoding.md

@@ -50,7 +50,7 @@ provide query methods that expose these interfaces via `google.protobuf.Any`.
 There is a concern on the transaction level that the overhead of `Any` is too
 high to justify its usage. However for queries this is not a concern, and
 providing generic module-level queries that use `Any` does not preclude apps
-from also providing app-level queries that return use the app-level `oneof`s.
+from also providing app-level queries that return using the app-level `oneof`s.
 
 A hypothetical example for the `gov` module would look something like:
 
@@ -205,7 +205,7 @@ type QueryClient interface {
 ```
 
 Via a small patch to gogo protobuf ([gogo/protobuf#675](https://github.com/gogo/protobuf/pull/675))
-we have tweaked the grpc codegen to use an interface rather than concrete type
+we have tweaked the grpc codegen to use an interface rather than a concrete type
 for the generated client struct. This allows us to also reuse the GRPC infrastructure
 for ABCI client queries.
 

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

@@ -27,7 +27,7 @@ It will also make `OutOfGas` case and `default` case one of the middlewares.
 
 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 node's state machine execution
+to crash the node and reboot it once the problem is solved. That behaviour 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.
 
@@ -37,8 +37,8 @@ in order to customize it.
 
 #### Overview
 
-Instead of hardcoding custom error handling into BaseApp we suggest using set of middlewares which can be customized
-externally and will allow developers use as many custom error handlers as they want. Implementation with tests
+Instead of hardcoding custom error handling into BaseApp we suggest using a set of middlewares which can be customized
+externally and will allow developers to use as many custom error handlers as they want. Implementation with tests
 can be found [here](https://github.com/cosmos/cosmos-sdk/pull/6053).
 
 #### Implementation details
@@ -52,9 +52,9 @@ New `RecoveryHandler` type added. `recoveryObj` input argument is an object retu
 type RecoveryHandler func(recoveryObj interface{}) error
 ```
 
-Handler should type assert (or other methods) an object to define if object should be handled.
-`nil` should be returned if input object can't be handled by that `RecoveryHandler` (not a handler's target type).
-Not `nil` error should be returned if input object was handled and middleware chain execution should be stopped.
+Handler should type assert (or other methods) an object to define if the object should be handled.
+`nil` should be returned if the input object can't be handled by that `RecoveryHandler` (not a handler's target type).
+Not `nil` error should be returned if the input object was handled and the middleware chain execution should be stopped.
 
 An example:
 
@@ -196,11 +196,11 @@ This method would prepend handlers to an existing chain.
 
 ### Positive
 
-* Developers of Cosmos SDK based projects can add custom panic handlers to:
+* Developers of Cosmos SDK-based projects can add custom panic handlers to:
     * add error context for custom panic sources (panic inside of custom keepers);
     * emit `panic()`: passthrough recovery object to the Tendermint core;
     * other necessary handling;
-* Developers can use standard Cosmos SDK `BaseApp` implementation, rather that rewriting it in their projects;
+* Developers can use standard Cosmos SDK `BaseApp` implementation, rather than rewriting it in their projects;
 * Proposed solution doesn't break the current "standard" `runTx()` flow;
 
 ### Negative

docs/architecture/adr-023-protobuf-naming.md

@@ -135,14 +135,14 @@ stable package (i.e. `v1` or `v2`) should be preferred
 * a package _should_ be marked as `alpha` _if and only if_ there are active discussions to remove
 or significantly alter the package in the near future
 * a package _should_ be marked as `beta` _if and only if_ there is an active discussion to
-significantly refactor/rework the functionality in the near future but not remove it
+significantly refactor/rework the functionality in the near future but do not remove it
 * modules _can and should_ have types in both stable (i.e. `v1` or `v2`) and unstable (`alpha` or `beta`) packages.
 
 _`alpha` and `beta` should not be used to avoid responsibility for maintaining compatibility._
 Whenever code is released into the wild, especially on a blockchain, there is a high cost to changing things. In some
 cases, for instance with immutable smart contracts, a breaking change may be impossible to fix.
 
-When marking something as `alpha` or `beta`, maintainers should ask the questions:
+When marking something as `alpha` or `beta`, maintainers should ask the following questions:
 
 * what is the cost of asking others to change their code vs the benefit of us maintaining the optionality to change it?
 * what is the plan for moving this to `v1` and how will that affect users?
@@ -174,7 +174,7 @@ or `.v3`.
 
 #### Adopt a short, unique top-level package name
 
-Top-level packages should adopt a short name that is known to not collide with
+Top-level packages should adopt a short name that is known not to collide with
 other names in common usage within the Cosmos ecosystem. In the near future, a
 registry should be created to reserve and index top-level package names used
 within the Cosmos ecosystem. Because the Cosmos SDK is intended to provide
@@ -200,7 +200,7 @@ go package names, i.e. the `cosmos.bank` protobuf package will still live in
 
 ### Message Naming
 
-Message type names should be as as concise possible without losing clarity. `sdk.Msg`
+Message type names should be as concise as possible without losing clarity. `sdk.Msg`
 types which are used in transactions will retain the `Msg` prefix as that provides
 helpful context.