diff --git a/docs/build/architecture/adr-003-dynamic-capability-store.md b/docs/build/architecture/adr-003-dynamic-capability-store.md index 89f0c9967..ce8aa8963 100644 --- a/docs/build/architecture/adr-003-dynamic-capability-store.md +++ b/docs/build/architecture/adr-003-dynamic-capability-store.md @@ -34,8 +34,8 @@ chain is running. The `CapabilityKeeper` will include a persistent `KVStore`, a `MemoryStore`, and an in-memory map. The persistent `KVStore` tracks which capability is owned by which modules. -The `MemoryStore` stores a forward mapping that map from module name, capability tuples to capability names and -a reverse mapping that map from module name, capability name to the capability index. +The `MemoryStore` stores a forward mapping that maps from module name, capability tuples to capability names and +a reverse mapping that maps from module name, capability name to the capability index. Since we cannot marshal the capability into a `KVStore` and unmarshal without changing the memory location of the capability, the reverse mapping in the KVStore will simply map to an index. This index can then be used as a key in the ephemeral go-map to retrieve the capability at the original memory location. @@ -277,7 +277,7 @@ ck.InitialiseAndSeal(initialContext) #### Creating, passing, claiming and using capabilities -Consider the case where `mod1` wants to create a capability, associate it with a resource (e.g. an IBC channel) by name, then pass it to `mod2` which will use it later: +Consider the case where `mod1` wants to create a capability, associate it with a resource (e.g. an IBC channel) by name, and then pass it to `mod2` which will use it later: Module 1 would have the following code: @@ -327,12 +327,12 @@ Proposed. ### Positive * Dynamic capability support. -* Allows CapabilityKeeper to return same capability pointer from go-map while reverting any writes to the persistent `KVStore` and in-memory `MemoryStore` on tx failure. +* Allows CapabilityKeeper to return the same capability pointer from go-map while reverting any writes to the persistent `KVStore` and in-memory `MemoryStore` on tx failure. ### Negative * Requires an additional keeper. -* Some overlap with existing `StoreKey` system (in the future they could be combined, since this is a superset functionality-wise). +* Some overlap with the existing `StoreKey` system (in the future they could be combined, since this is a superset functionality-wise). * Requires an extra level of indirection in the reverse mapping, since MemoryStore must map to index which must then be used as key in a go map to retrieve the actual capability ### Neutral diff --git a/docs/build/architecture/adr-010-modular-antehandler.md b/docs/build/architecture/adr-010-modular-antehandler.md index 4eb5b8855..4fa6e4f2c 100644 --- a/docs/build/architecture/adr-010-modular-antehandler.md +++ b/docs/build/architecture/adr-010-modular-antehandler.md @@ -29,7 +29,7 @@ Pros: Cons: 1. Improves granularity but still cannot get more granular than a per-module basis. e.g. If auth's `AnteHandle` function is in charge of validating memo and signatures, users cannot swap the signature-checking functionality while keeping the rest of auth's `AnteHandle` functionality. -2. Module AnteHandler are run one after the other. There is no way for one AnteHandler to wrap or "decorate" another. +2. Module AnteHandlers are run one after the other. There is no way for one AnteHandler to wrap or "decorate" another. ### Decorator Pattern @@ -157,7 +157,7 @@ app.SetAnteHandler(mm.GetAnteHandler()) #### Custom Workflow -This is an example workflow for a user that wants to implement custom antehandler logic. In this example, the user wants to implement custom signature verification and change the order of antehandler so that validate memo runs before signature verification. +This is an example workflow for a user who wants to implement custom antehandler logic. In this example, the user wants to implement custom signature verification and change the order of antehandler so that validate memo runs before signature verification. ##### User Code @@ -192,7 +192,7 @@ In addition, this approach will not break any core Cosmos SDK API's. Since we pr Allow Decorator interface that can be chained together to create a Cosmos SDK AnteHandler. -This allows users to choose between implementing an AnteHandler by themselves and setting it in the baseapp, or use the decorator pattern to chain their custom decorators with the Cosmos SDK provided decorators in the order they wish. +This allows users to choose between implementing an AnteHandler by themselves and setting it in the baseapp, or using the decorator pattern to chain their custom decorators with the Cosmos SDK provided decorators in the order they wish. ```go // An AnteDecorator wraps an AnteHandler, and can do pre- and post-processing on the next AnteHandler diff --git a/docs/build/architecture/adr-012-state-accessors.md b/docs/build/architecture/adr-012-state-accessors.md index 93600000f..49a9ba1fd 100644 --- a/docs/build/architecture/adr-012-state-accessors.md +++ b/docs/build/architecture/adr-012-state-accessors.md @@ -15,7 +15,7 @@ value and finally unmarshal. Usually this is done by declaring `Keeper.GetXXX` a which are repetitive and hard to maintain. Second, this makes it harder to align with the object capability theorem: the right to access the -state is defined as a `StoreKey`, which gives full access on the entire Merkle tree, so a module cannot +state is defined as a `StoreKey`, which gives full access to the entire Merkle tree, so a module cannot send the access right to a specific key-value pair (or a set of key-value pairs) to another module safely. Finally, because the getter/setter functions are defined as methods of a module's `Keeper`, the reviewers diff --git a/docs/build/architecture/adr-013-metrics.md b/docs/build/architecture/adr-013-metrics.md index b0808d462..e2bce3a04 100644 --- a/docs/build/architecture/adr-013-metrics.md +++ b/docs/build/architecture/adr-013-metrics.md @@ -10,7 +10,7 @@ Proposed ## Context -Telemetry is paramount into debugging and understanding what the application is doing and how it is +Telemetry is paramount in 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. @@ -148,7 +148,7 @@ func (k BaseKeeper) MintCoins(ctx sdk.Context, moduleName string, amt sdk.Coins) ### Positive -* Exposure into the performance and behavior of an application +* Exposure to the performance and behavior of an application ### Negative diff --git a/docs/build/architecture/adr-016-validator-consensus-key-rotation.md b/docs/build/architecture/adr-016-validator-consensus-key-rotation.md index 7085f033c..998627a43 100644 --- a/docs/build/architecture/adr-016-validator-consensus-key-rotation.md +++ b/docs/build/architecture/adr-016-validator-consensus-key-rotation.md @@ -7,7 +7,7 @@ ## Context -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. +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 forms 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. @@ -21,33 +21,33 @@ Also, it should be noted that this ADR includes only the simplest form of consen * 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. * 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. + * store history of each key mapping change in the kvstore. + * 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 * 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 rotations in recent unbonding period and also applied an exponentially increasing rotation fee * limits * rotations are limited to 1 time in an unbonding window. In future rewrites of the staking module it could be made to happen more times than 1 - * parameters can be decided by governance and stored in genesis file. + * parameters can be decided by governance and stored in the genesis file. * key rotation fee * a validator should pay `KeyRotationFee` to rotate the consensus key which is calculated as below * `KeyRotationFee` = (max(`VotingPowerPercentage`, 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 a 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. * 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) + * `MaxConsPubKeyRotations` : maximum number of rotations can be executed by a validator in the 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 the recent unbonding period. default value 1atom is suggested(1atom fee for the first key rotation in recent unbonding period) ### Workflow @@ -64,7 +64,7 @@ Also, it should be noted that this ADR includes only the simplest form of consen 3. `handleMsgRotateConsPubKey` gets `MsgRotateConsPubKey`, calls `RotateConsPubKey` with emits event 4. `RotateConsPubKey` * checks if `NewPubKey` is not duplicated on `ValidatorsByConsAddr` - * checks if the validator is does not exceed parameter `MaxConsPubKeyRotations` by iterating `ConsPubKeyRotationHistory` + * checks if the validator does not exceed parameter `MaxConsPubKeyRotations` by iterating `ConsPubKeyRotationHistory` * checks if the signing account has enough balance to pay `KeyRotationFee` * pays `KeyRotationFee` to community fund * overwrites `NewPubKey` in `validator.ConsPubKey` @@ -81,7 +81,7 @@ Also, it should be noted that this ADR includes only the simplest form of consen } ``` -5. `ApplyAndReturnValidatorSetUpdates` checks if there is `ConsPubKeyRotationHistory` with `ConsPubKeyRotationHistory.RotatedHeight == ctx.BlockHeight()` and if so, generates 2 `ValidatorUpdate` , one for a remove validator and one for create new validator +5. `ApplyAndReturnValidatorSetUpdates` checks if there is `ConsPubKeyRotationHistory` with `ConsPubKeyRotationHistory.RotatedHeight == ctx.BlockHeight()` and if so, generates 2 `ValidatorUpdate` , one for a remove validator and one for create a new validator ```go abci.ValidatorUpdate{ diff --git a/docs/build/building-modules/16-testing.md b/docs/build/building-modules/16-testing.md index 65ed52a8a..6b9441bbe 100644 --- a/docs/build/building-modules/16-testing.md +++ b/docs/build/building-modules/16-testing.md @@ -104,7 +104,7 @@ System tests are at the top of the [test pyramid](https://martinfowler.com/artic They test the whole application flow as black box, from the user perspective. They are located under [`/tests/systemtests`](https://github.com/cosmos/cosmos-sdk/tree/main/tests/systemtests). For that, the SDK is using the `simapp` binary, but you should use your own binary. -More details about system test can be found in [building-apps](https://docs.cosmos.network/main/build/building-apps/06-system-tests.md) +More details about system test can be found in [building-apps](https://docs.cosmos.network/main/build/building-apps/system-tests) ## Learn More