diff --git a/docs/docs/build/abci/00-introduction.md b/docs/docs/build/abci/00-introduction.md index cec8a74016..fa648be05d 100644 --- a/docs/docs/build/abci/00-introduction.md +++ b/docs/docs/build/abci/00-introduction.md @@ -19,7 +19,7 @@ The 5 methods introduced in ABCI 2.0 are: Based on validator voting power, CometBFT chooses a block proposer and calls `PrepareProposal` on the block proposer's application (Cosmos SDK). The selected block proposer is responsible for collecting outstanding transactions from the mempool, adhering to the application's specifications. The application can enforce custom transaction ordering and incorporate additional transactions, potentially generated from vote extensions in the previous block. -To perform this manipulation on the application side, a custom handler must be implemented. By default, the Cosmos SDK provides `PrepareProposalHandler`, used in conjunction with an application specific mempool. A custom handler can be written by application developer, if a noop handler provided, all transactions are considered valid. +To perform this manipulation on the application side, a custom handler must be implemented. By default, the Cosmos SDK provides `PrepareProposalHandler`, used in conjunction with an application specific mempool. A custom handler can be written by an application developer, if a noop handler is provided, all transactions are considered valid. Please note that vote extensions will only be available on the following height in which vote extensions are enabled. More information about vote extensions can be found [here](https://docs.cosmos.network/main/build/abci/vote-extensions). @@ -39,7 +39,7 @@ These methods allow applications to extend the voting process by requiring valid If vote extensions are enabled, `ExtendVote` will be called on every validator and each one will return its vote extension which is in practice a bunch of bytes. As mentioned above this data (vote extension) can only be retrieved in the next block height during `PrepareProposal`. Additionally, this data can be arbitrary, but in the provided tutorials, it serves as an oracle or proof of transactions in the mempool. Essentially, vote extensions are processed and injected as transactions. Examples of use-cases for vote extensions include prices for a price oracle or encryption shares for an encrypted transaction mempool. `ExtendVote` CAN be non-deterministic. -`VerifyVoteExtensions` is performed on every validator multiple times in order to verify other validators' vote extensions. This check is submitted to validate the integrity and validity of the vote extensions preventing malicious or invalid vote extensions. +`VerifyVoteExtensions` is performed on every validator multiple times in order to verify other validators' vote extensions. This check is performed to validate the integrity and validity of the vote extensions preventing malicious or invalid vote extensions. Additionally, applications must keep the vote extension data concise as it can degrade the performance of their chain, see testing results [here](https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed). diff --git a/docs/docs/build/abci/02-process-proposal.md b/docs/docs/build/abci/02-process-proposal.md index c1faf9f406..221aa66d45 100644 --- a/docs/docs/build/abci/02-process-proposal.md +++ b/docs/docs/build/abci/02-process-proposal.md @@ -7,7 +7,7 @@ default implementation of `PrepareProposal` runs basic validity checks on each transaction. Note, `ProcessProposal` MUST be deterministic. Non-deterministic behaviors will cause apphash mismatches. -This means if `ProcessProposal` panics or fails and we reject, all honest validator +This means that if `ProcessProposal` panics or fails and we reject, all honest validator processes should reject (i.e., prevote nil). If so, CometBFT will start a new round with a new block proposal and the same cycle will happen with `PrepareProposal` and `ProcessProposal` for the new proposal. diff --git a/docs/docs/build/building-apps/01-app-go-di.md b/docs/docs/build/building-apps/01-app-go-di.md index d425feb858..00ab7883de 100644 --- a/docs/docs/build/building-apps/01-app-go-di.md +++ b/docs/docs/build/building-apps/01-app-go-di.md @@ -6,7 +6,7 @@ sidebar_position: 1 :::note Synopsis -The Cosmos SDK allows much easier wiring of an `app.go` thanks to [runtime](./00-runtime.md) and app wiring. +The Cosmos SDK makes wiring of an `app.go` much easier thanks to [runtime](./00-runtime.md) and app wiring. Learn more about the rationale of App Wiring in [ADR-057](../../../architecture/adr-057-app-wiring.md). ::: @@ -40,7 +40,7 @@ The `app_config.go` file is the single place to configure all modules parameters 2. Configure the `runtime` module: - In this configuration, the order at which the modules are defined in PreBlockers, BeginBlocks, and EndBlockers is important. + In this configuration, the order in which the modules are defined in PreBlockers, BeginBlocks, and EndBlockers is important. They are named in the order they should be executed by the module manager. ```go reference @@ -67,7 +67,7 @@ See the complete `app_config.go` file for `SimApp` [here](https://github.com/cos :::tip The example above shows how to create an `AppConfig` using Go. However, it is also possible to create an `AppConfig` using YAML, or JSON. -The configuration can then be embed with `go:embed` and read with [`appconfig.LoadYAML`](https://pkg.go.dev/cosmossdk.io/core/appconfig#LoadYAML), or [`appconfig.LoadJSON`](https://pkg.go.dev/cosmossdk.io/core/appconfig#LoadJSON), in `app_di.go`. +The configuration can then be embedded with `go:embed` and read with [`appconfig.LoadYAML`](https://pkg.go.dev/cosmossdk.io/core/appconfig#LoadYAML), or [`appconfig.LoadJSON`](https://pkg.go.dev/cosmossdk.io/core/appconfig#LoadJSON), in `app_di.go`. ```go //go:embed app_config.yaml diff --git a/docs/docs/build/building-apps/02-app-mempool.md b/docs/docs/build/building-apps/02-app-mempool.md index c2256edffc..dbe6783ca0 100644 --- a/docs/docs/build/building-apps/02-app-mempool.md +++ b/docs/docs/build/building-apps/02-app-mempool.md @@ -48,7 +48,7 @@ which is FIFO-ordered by default. ### Sender Nonce Mempool -The nonce mempool is a mempool that keeps transactions from an sorted by nonce in order to avoid the issues with nonces. +The nonce mempool is a mempool that keeps transactions from a sender sorted by nonce in order to avoid the issues with nonces. It works by storing the transaction in a list sorted by the transaction nonce. When the proposer asks for transactions to be included in a block it randomly selects a sender and gets the first transaction in the list. It repeats this until the mempool is empty or the block is full. It is configurable with the following parameters: @@ -59,7 +59,7 @@ It is an integer value that sets the mempool in one of three modes, *bounded*, * * **negative**: Disabled, mempool does not insert new transaction and return early. * **zero**: Unbounded mempool has no transaction limit and will never fail with `ErrMempoolTxMaxCapacity`. -* **positive**: Bounded, it fails with `ErrMempoolTxMaxCapacity` when `maxTx` value is the same as `CountTx()` +* **positive**: Bounded, it fails with `ErrMempoolTxMaxCapacity` when the `maxTx` value is the same as `CountTx()` #### Seed @@ -82,13 +82,13 @@ It is an integer value that sets the mempool in one of three modes, *bounded*, * * **negative**: Disabled, mempool does not insert new transaction and return early. * **zero**: Unbounded mempool has no transaction limit and will never fail with `ErrMempoolTxMaxCapacity`. -* **positive**: Bounded, it fails with `ErrMempoolTxMaxCapacity` when `maxTx` value is the same as `CountTx()` +* **positive**: Bounded, it fails with `ErrMempoolTxMaxCapacity` when the `maxTx` value is the same as `CountTx()` #### Callback -The priority nonce mempool provides mempool options allowing the application sets callback(s). +The priority nonce mempool provides mempool options allowing the application to set callback(s). * **OnRead**: Set a callback to be called when a transaction is read from the mempool. -* **TxReplacement**: Sets a callback to be called when duplicated transaction nonce detected during mempool insert. Application can define a transaction replacement rule based on tx priority or certain transaction fields. +* **TxReplacement**: Sets a callback to be called when duplicate transaction nonce detected during mempool insert. Application can define a transaction replacement rule based on tx priority or certain transaction fields. More information on the SDK mempool implementation can be found in the [godocs](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/types/mempool). diff --git a/docs/docs/build/building-apps/03-app-upgrade.md b/docs/docs/build/building-apps/03-app-upgrade.md index 5c80ce93e4..541530a14d 100644 --- a/docs/docs/build/building-apps/03-app-upgrade.md +++ b/docs/docs/build/building-apps/03-app-upgrade.md @@ -22,13 +22,13 @@ This section is currently incomplete. Track the progress of this document [here] Let's assume we are running v0.38.0 of our software in our testnet and want to upgrade to v0.40.0. How would this look in practice? First, we want to finalize the v0.40.0 release candidate -and then install a specially named upgrade handler (eg. "testnet-v2" or even "v0.40.0"). An upgrade +and then install a specially named upgrade handler (e.g. "testnet-v2" or even "v0.40.0"). An upgrade handler should be defined in a new version of the software to define what migrations to run to migrate from the older version of the software. Naturally, this is app-specific rather -than module specific, and must be defined in `app.go`, even if it imports logic from various +than module-specific, and must be defined in `app.go`, even if it imports logic from various modules to perform the actions. You can register them with `upgradeKeeper.SetUpgradeHandler` during the app initialization (before starting the abci server), and they serve not only to -perform a migration, but also to identify if this is the old or new version (eg. presence of +perform a migration, but also to identify if this is the old or new version (e.g. presence of a handler registered for the named upgrade). Once the release candidate along with an appropriate upgrade handler is frozen, @@ -56,7 +56,7 @@ be a matter of minutes and not even require them to be awake at that time. The following is not required for users using `depinject`, this is abstracted for them. ::: -In addition to basic module wiring, setup the upgrade Keeper for the app and then define a `PreBlocker` that calls the upgrade +In addition to basic module wiring, set up the upgrade Keeper for the app and then define a `PreBlocker` that calls the upgrade keeper's PreBlocker method: ```go diff --git a/docs/docs/build/building-apps/04-vote-extensions.md b/docs/docs/build/building-apps/04-vote-extensions.md index a67b225ac2..f20ebde66c 100644 --- a/docs/docs/build/building-apps/04-vote-extensions.md +++ b/docs/docs/build/building-apps/04-vote-extensions.md @@ -74,7 +74,7 @@ hook to allow applications to recover vote extensions, perform any necessary computation on them, and then store the results in the cached store. These results 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: +An example of how a pre-FinalizeBlock hook could look is shown below: ```go app.SetPreBlocker(func(ctx sdk.Context, req *abci.FinalizeBlockRequest) error { diff --git a/docs/docs/build/building-apps/05-app-testnet.md b/docs/docs/build/building-apps/05-app-testnet.md index f79ae55197..a9fe93d90f 100644 --- a/docs/docs/build/building-apps/05-app-testnet.md +++ b/docs/docs/build/building-apps/05-app-testnet.md @@ -25,7 +25,7 @@ We will be breaking down the steps to create a testnet from mainnet state. #### Staking -When creating a testnet the important part is migrate the validator set from many validators to one or a few. This allows developers to spin up the chain without needing to replace validator keys. +When creating a testnet the important part is to migrate the validator set from many validators to one or a few. This allows developers to spin up the chain without needing to replace validator keys. ```go ctx := app.BaseApp.NewUncachedContext(true, tmproto.Header{}) diff --git a/docs/docs/build/building-modules/01-module-manager.md b/docs/docs/build/building-modules/01-module-manager.md index d2df034228..ee2a83a807 100644 --- a/docs/docs/build/building-modules/01-module-manager.md +++ b/docs/docs/build/building-modules/01-module-manager.md @@ -29,7 +29,7 @@ There are 2 main application module interfaces: * [`appmodule.AppModule` / `module.AppModule`](#appmodule) for inter-dependent module functionalities (except genesis-related functionalities). * (legacy) [`module.AppModuleBasic`](#appmodulebasic) for independent module functionalities. New modules can use `module.CoreAppModuleBasicAdaptor` instead. -The above interfaces are mostly embedding smaller interfaces (extension interfaces), that defines specific functionalities: +The above interfaces are mostly embedding smaller interfaces (extension interfaces), that define specific functionalities: * (legacy) `module.HasName`: Allows the module to provide its own name for legacy purposes. * (legacy) [`module.HasGenesisBasics`](#modulehasgenesisbasics): The legacy interface for stateless genesis methods. @@ -144,7 +144,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/module/module.go#L199-L2 ### `HasInvariants` -This interface defines one method. It allows to checks if a module can register invariants. +This interface defines one method. It allows checking if a module can register invariants. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/module/module.go#L211-L214 @@ -154,7 +154,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/module/module.go#L211-L2 ### `HasServices` -This interface defines one method. It allows to checks if a module can register invariants. +This interface defines one method. It allows checking if a module can register services. #### `appmodule.HasService` @@ -196,7 +196,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/core/appmodule/module.go#L73-L ### `HasEndBlocker` -The `HasEndBlocker` is an extension interface from `appmodule.AppModule`. All modules that have an `EndBlock` method implement this interface. If a module need to return validator set updates (staking), they can use `HasABCIEndBlock` +The `HasEndBlocker` is an extension interface from `appmodule.AppModule`. All modules that have an `EndBlock` method implement this interface. If a module needs to return validator set updates (staking), they can use `HasABCIEndBlock` ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/core/appmodule/module.go#L83-L89 diff --git a/docs/docs/build/building-modules/02-messages-and-queries.md b/docs/docs/build/building-modules/02-messages-and-queries.md index 6155da12ca..e6048c313a 100644 --- a/docs/docs/build/building-modules/02-messages-and-queries.md +++ b/docs/docs/build/building-modules/02-messages-and-queries.md @@ -47,7 +47,7 @@ To attach a `ValidateBasic()` method to a message then you must add methods to t https://github.com/cosmos/cosmos-sdk/blob/9c1e8b247cd47b5d3decda6e86fbc3bc996ee5d7/types/tx_msg.go#L84-L88 ``` -In 0.50+ signers from the `GetSigners()` call is automated via a protobuf annotation. +In 0.50+ signers from the `GetSigners()` call are automated via a protobuf annotation. Read more about the signer field [here](./05-protobuf-annotations.md). @@ -128,7 +128,7 @@ The `path` for each `query` must be defined by the module developer in the modul ### Store Queries -Store queries query directly for store keys. They use `clientCtx.QueryABCI(req abci.QueryRequest)` to return the full `abci.QueryResponse` with inclusion Merkle proofs. +Store queries access store keys directly. They use `clientCtx.QueryABCI(req abci.QueryRequest)` to return the full `abci.QueryResponse` with inclusion Merkle proofs. See following examples: diff --git a/docs/docs/build/building-modules/03-msg-services.md b/docs/docs/build/building-modules/03-msg-services.md index 602549178c..910d6f88df 100644 --- a/docs/docs/build/building-modules/03-msg-services.md +++ b/docs/docs/build/building-modules/03-msg-services.md @@ -33,7 +33,7 @@ When possible, the existing module's [`Keeper`](./06-keeper.md) should implement https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/keeper/msg_server.go#L17-L19 ``` -`msgServer` methods can retrieve the `context.Context` from the `context.Context` parameter method using the `sdk.UnwrapSDKContext`: +`msgServer` methods can retrieve the `sdk.Context` from the `context.Context` parameter using the `sdk.UnwrapSDKContext` method: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/keeper/msg_server.go#L56 @@ -75,7 +75,7 @@ Before returning, `msgServer` methods generally emit one or more [events](../../ ```go ctx.EventManager().EmitTypedEvent( - &group.EventABC{Key1: Value1, Key2, Value2}) + &group.EventABC{Key1: Value1, Key2: Value2}) ``` or the older `EmitEvent` function: