diff --git a/docs/build/abci/00-introduction.md b/docs/build/abci/00-introduction.md index 25ccc8413..6b7cd8ec3 100644 --- a/docs/build/abci/00-introduction.md +++ b/docs/build/abci/00-introduction.md @@ -2,7 +2,7 @@ ## What is ABCI? -ABCI, Application Blockchain Interface is the interface between CometBFT and the application. More information about ABCI can be found in the specs [here](https://docs.cometbft.com/v0.38/spec/abci/). Within the release of ABCI 2.0 for the 0.38 CometBFT release there were additional methods introduced. +ABCI, Application Blockchain Interface is the interface between CometBFT and the application. More information about ABCI can be found in the specs [here](https://docs.cometbft.com/v1.0/spec/abci/). Within the release of ABCI 2.0 for the 0.38 CometBFT release there were additional methods introduced. The 5 methods introduced during ABCI 2.0 (compared to ABCI v0) are: @@ -41,7 +41,7 @@ If vote extensions are enabled, `ExtendVote` will be called on every validator a `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. -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). +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/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed). `VerifyVoteExtensions` MUST be deterministic. diff --git a/docs/build/abci/03-vote-extensions.md b/docs/build/abci/03-vote-extensions.md index 6ce737f4d..59b00c898 100644 --- a/docs/build/abci/03-vote-extensions.md +++ b/docs/build/abci/03-vote-extensions.md @@ -11,21 +11,21 @@ ABCI2.0 (colloquially called ABCI++) allows an application to extend a pre-commi validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/types/abci.go#L26-L27): ```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` `BaseApp` option function. The `sdk.ExtendVoteHandler`, if defined, is called during the `ExtendVote` ABCI method. Note, if an application decides to implement `baseapp.ExtendVoteHandler`, it MUST return a non-nil `VoteExtension`. However, the vote -extension can be empty. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#extendvote) +extension can be empty. See [here](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#extendvote) for more details. There are many decentralized censorship-resistant use cases for vote extensions. For example, a validator may want to submit prices for a price oracle or encryption shares for an encrypted transaction mempool. Note, an application should be careful to consider the size of the vote extensions as they could increase latency in block -production. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/docs/qa/CometBFT-QA-38.md#vote-extensions-testbed) +production. See [here](https://docs.cometbft.com/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed) for more details. Click [here](https://docs.cosmos.network/main/build/abci/vote-extensions) if you would like a walkthrough of how to implement vote extensions. @@ -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` @@ -46,10 +46,10 @@ An application can set this handler in `app.go` via the `baseapp.SetVerifyVoteEx during the `VerifyVoteExtension` ABCI method. If an application defines a vote extension handler, it should also define a verification handler. Note, not all validators will share the same view of what vote extensions they verify depending -on how votes are propagated. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#verifyvoteextension) +on how votes are propagated. See [here](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#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 ([see vote extension testbed](https://docs.cometbft.com/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed)), so we highly recommend a size validation in `VerifyVoteExtensions`. ## Vote Extension Propagation diff --git a/docs/build/architecture/PROCESS.md b/docs/build/architecture/PROCESS.md index a237d0c65..8c5900120 100644 --- a/docs/build/architecture/PROCESS.md +++ b/docs/build/architecture/PROCESS.md @@ -49,7 +49,7 @@ DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED b * `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. * `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. * `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. -* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. +* `SUPERSEDED by ADR-xxx`: ADR which has been superseded by a new ADR. * `ABANDONED`: the ADR is no longer pursued by the original authors. ## Language used in ADR diff --git a/docs/build/architecture/adr-034-account-rekeying.md b/docs/build/architecture/adr-034-account-rekeying.md index 53fef6cf8..951c30f6f 100644 --- a/docs/build/architecture/adr-034-account-rekeying.md +++ b/docs/build/architecture/adr-034-account-rekeying.md @@ -68,7 +68,7 @@ Breaks the current assumed relationship between address and pubkeys as H(pubkey) ### Neutral -* While the purpose of this is intended to allow the owner of an account to update to a new pubkey they own, this could technically also be used to transfer ownership of an account to a new owner. For example, this could be use used to sell a staked position without unbonding or an account that has vesting tokens. However, the friction of this is very high as this would essentially have to be done as a very specific OTC trade. Furthermore, additional constraints could be added to prevent accouns with Vesting tokens to use this feature. +* While the purpose of this is intended to allow the owner of an account to update to a new pubkey they own, this could technically also be used to transfer ownership of an account to a new owner. For example, this could be use used to sell a staked position without unbonding or an account that has vesting tokens. However, the friction of this is very high as this would essentially have to be done as a very specific OTC trade. Furthermore, additional constraints could be added to prevent accounts with Vesting tokens to use this feature. * Will require that PubKeys for an account are included in the genesis exports. ## References diff --git a/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md b/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md index 03bcb7819..8ca8952bf 100644 --- a/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md +++ b/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md @@ -92,7 +92,7 @@ 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. @@ -100,8 +100,8 @@ To manage the active snapshots we will either use a DB _max number of snapshots_ #### 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. diff --git a/docs/build/architecture/adr-043-nft-module.md b/docs/build/architecture/adr-043-nft-module.md index 87b4dbb5e..85d439f7e 100644 --- a/docs/build/architecture/adr-043-nft-module.md +++ b/docs/build/architecture/adr-043-nft-module.md @@ -156,7 +156,7 @@ message MsgSend { string class_id = 1; string id = 2; string sender = 3; - string reveiver = 4; + string receiver = 4; } message MsgSendResponse {} ``` diff --git a/docs/build/architecture/adr-050-sign-mode-textual.md b/docs/build/architecture/adr-050-sign-mode-textual.md index 6432489aa..8eec8e42b 100644 --- a/docs/build/architecture/adr-050-sign-mode-textual.md +++ b/docs/build/architecture/adr-050-sign-mode-textual.md @@ -285,7 +285,7 @@ Moreover, the renderer must provide 2 functions: one for formatting from Protobu ### Require signing over the `TxBody` and `AuthInfo` raw bytes -Recall that the transaction bytes merklelized on chain are the Protobuf binary serialization of [TxRaw](hhttps://buf.build/cosmos/cosmos-sdk/docs/main:cosmos.tx.v1beta1#cosmos.tx.v1beta1.TxRaw), which contains the `body_bytes` and `auth_info_bytes`. Moreover, the transaction hash is defined as the SHA256 hash of the `TxRaw` bytes. We require that the user signs over these bytes in SIGN_MODE_TEXTUAL, more specifically over the following string: +Recall that the transaction bytes merklelized on chain are the Protobuf binary serialization of [TxRaw](https://buf.build/cosmos/cosmos-sdk/docs/main:cosmos.tx.v1beta1#cosmos.tx.v1beta1.TxRaw), which contains the `body_bytes` and `auth_info_bytes`. Moreover, the transaction hash is defined as the SHA256 hash of the `TxRaw` bytes. We require that the user signs over these bytes in SIGN_MODE_TEXTUAL, more specifically over the following string: ``` *Hash of raw bytes: diff --git a/docs/build/architecture/adr-060-abci-1.0.md b/docs/build/architecture/adr-060-abci-1.0.md index 3f29be784..d2d93a89e 100644 --- a/docs/build/architecture/adr-060-abci-1.0.md +++ b/docs/build/architecture/adr-060-abci-1.0.md @@ -169,7 +169,7 @@ Instead, we will define an additional ABCI interface method on the existing or `EndBlock`. This new interface method will be defined as follows: ```go -ProcessProposal(sdk.Context, abci.RequestProcessProposal) error {} +ProcessProposal(sdk.Context, abci.ProcessProposalRequest) error {} ``` Note, we must call `ProcessProposal` with a new internal branched state on the diff --git a/docs/build/architecture/adr-062-collections-state-layer.md b/docs/build/architecture/adr-062-collections-state-layer.md index 31854d138..8d3a7b61c 100644 --- a/docs/build/architecture/adr-062-collections-state-layer.md +++ b/docs/build/architecture/adr-062-collections-state-layer.md @@ -78,7 +78,7 @@ These default implementations also offer safety around proper lexicographic orde Examples of the collections API can be found here: - introduction: https://github.com/NibiruChain/collections/tree/main/examples -- usage in nibiru: [x/oracle](https://github.com/NibiruChain/nibiru/blob/master/x/oracle/keeper/keeper.go#L32), [x/perp](https://github.com/NibiruChain/nibiru/blob/main/x/perp/v2/keeper/keeper.go) +- usage in nibiru: [x/oracle](https://github.com/NibiruChain/nibiru/blob/master/x/oracle/keeper/keeper.go#L32), [x/epoch](https://github.com/NibiruChain/nibiru/blob/4566d9f6d22807abbd78c01454664d64f6e108e0/x/epochs/keeper/epoch.go) - cosmos-sdk's x/staking migrated: https://github.com/testinginprod/cosmos-sdk/pull/22 diff --git a/docs/build/architecture/adr-063-core-module-api.md b/docs/build/architecture/adr-063-core-module-api.md index 1615a590e..74212b298 100644 --- a/docs/build/architecture/adr-063-core-module-api.md +++ b/docs/build/architecture/adr-063-core-module-api.md @@ -199,7 +199,7 @@ func NewKeeper(logger log.Logger) Keeper { Modules will provide their core services to the runtime module via extension interfaces built on top of the `cosmossdk.io/core/appmodule.AppModule` tag interface. This tag interface requires only two empty methods which -allow `depinject` to identify implementors as `depinject.OnePerModule` types and as app module implementations: +allow `depinject` to identify implementers as `depinject.OnePerModule` types and as app module implementations: ```go type AppModule interface { @@ -330,7 +330,7 @@ Header Service defines a way to get header information about a block. This infor ```go type Service interface { - GetHeaderInfo(context.Context) Info + HeaderInfo(context.Context) Info } type Info struct { @@ -463,6 +463,7 @@ module manager and follow the Cosmos SDK's existing [0-based versioning](https:/ versioning as well as runtime modularity, new officially supported runtime modules will be created under the `cosmossdk.io/runtime` prefix. For each supported consensus engine a semantically-versioned go module should be created with a runtime implementation for that consensus engine. For example: + * `cosmossdk.io/runtime/comet` * `cosmossdk.io/runtime/comet/v2` * `cosmossdk.io/runtime/rollkit` diff --git a/docs/build/architecture/adr-064-abci-2.0.md b/docs/build/architecture/adr-064-abci-2.0.md index 80383f83d..7d9f270f0 100644 --- a/docs/build/architecture/adr-064-abci-2.0.md +++ b/docs/build/architecture/adr-064-abci-2.0.md @@ -103,7 +103,7 @@ vote extensions. We propose the following new handlers for applications to implement: ```go -type ExtendVoteHandler func(sdk.Context, abci.RequestExtendVote) abci.ResponseExtendVote +type ExtendVoteHandler func(sdk.Context, abci.ExtendVoteRequest) abci.ExtendVoteResponse type VerifyVoteExtensionHandler func(sdk.Context, abci.RequestVerifyVoteExtension) abci.ResponseVerifyVoteExtension ``` @@ -144,7 +144,7 @@ type VoteExtensionHandler struct { // ExtendVoteHandler can do something with h.mk and possibly h.state to create // a vote extension, such as fetching a series of prices for supported assets. -func (h VoteExtensionHandler) ExtendVoteHandler(ctx sdk.Context, req abci.RequestExtendVote) abci.ResponseExtendVote { +func (h VoteExtensionHandler) ExtendVoteHandler(ctx sdk.Context, req abci.ExtendVoteRequest) abci.ExtendVoteResponse { prices := GetPrices(ctx, h.mk.Assets()) bz, err := EncodePrices(h.cdc, prices) if err != nil { @@ -156,7 +156,7 @@ func (h VoteExtensionHandler) ExtendVoteHandler(ctx sdk.Context, req abci.Reques // NOTE: Vote extensions can be overridden since we can timeout in a round. SetPrices(h.state, req, bz) - return abci.ResponseExtendVote{VoteExtension: bz} + return abci.ExtendVoteResponse{VoteExtension: bz} } // VerifyVoteExtensionHandler can do something with h.state and req to verify @@ -401,7 +401,7 @@ in both `BeginBlock` and `EndBlock` events`. ### Upgrading -CometBFT defines a consensus parameter, [`VoteExtensionsEnableHeight`](https://github.com/cometbft/cometbft/blob/v0.38.0-alpha.1/spec/abci/abci%2B%2B_app_requirements.md#abciparamsvoteextensionsenableheight), +CometBFT defines a consensus parameter, [`VoteExtensionsEnableHeight`](https://docs.cometbft.com/v1.0/spec/abci/abci++_app_requirements#featureparamsvoteextensionsenableheight), which specifies the height at which vote extensions are enabled and **required**. If the value is set to zero, which is the default, then vote extensions are disabled and an application is not required to implement and use vote extensions. diff --git a/docs/build/architecture/adr-067-simulator-v2.md b/docs/build/architecture/adr-067-simulator-v2.md index ae27f01e2..ba3be1229 100644 --- a/docs/build/architecture/adr-067-simulator-v2.md +++ b/docs/build/architecture/adr-067-simulator-v2.md @@ -118,10 +118,10 @@ func (s *Simulator) SimulateBlock() { rProposer := s.SelectRandomProposer() rTxs := s.SelectTxs() - prepareResp, err := s.app.PrepareProposal(&abci.RequestPrepareProposal{Txs: rTxs}) + prepareResp, err := s.app.PrepareProposal(&abci.PrepareProposalRequest{Txs: rTxs}) // handle error - processResp, err := s.app.ProcessProposal(&abci.RequestProcessProposal{ + processResp, err := s.app.ProcessProposal(&abci.ProcessProposalRequest{ Txs: prepareResp.Txs, // ... }) diff --git a/docs/build/building-apps/01-app-go-v2.md b/docs/build/building-apps/01-app-go-v2.md index d77899d26..a0f1b815c 100644 --- a/docs/build/building-apps/01-app-go-v2.md +++ b/docs/build/building-apps/01-app-go-v2.md @@ -7,13 +7,13 @@ sidebar_position: 1 :::note Synopsis The Cosmos SDK allows much easier wiring of an `app.go` thanks to App Wiring and [`depinject`](../packages/01-depinject.md). -Learn more about the rationale of App Wiring in [ADR-057](../architecture/adr-057-app-wiring.md). +Learn more about the rationale of App Wiring in [ADR-057](../../architecture/adr-057-app-wiring.md). ::: :::note Pre-requisite Readings -* [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md) +* [ADR 057: App Wiring](../../architecture/adr-057-app-wiring.md) * [Depinject Documentation](../packages/01-depinject.md) * [Modules depinject-ready](../building-modules/15-depinject.md) diff --git a/docs/build/building-apps/02-app-mempool.md b/docs/build/building-apps/02-app-mempool.md index e5b4d7ae6..d91593f2f 100644 --- a/docs/build/building-apps/02-app-mempool.md +++ b/docs/build/building-apps/02-app-mempool.md @@ -10,7 +10,7 @@ This sections describes how the app-side mempool can be used and replaced. Since `v0.47` the application has its own mempool to allow much more granular block building than previous versions. This change was enabled by -[ABCI 1.0](https://github.com/cometbft/cometbft/blob/v0.37.0/spec/abci). +[ABCI 1.0](https://docs.cometbft.com/v0.37/spec/abci/). Notably it introduces the `PrepareProposal` and `ProcessProposal` steps of ABCI++. For more information please see [here](../abci/00-introduction.md) :::note Pre-requisite Readings diff --git a/docs/build/building-apps/03-app-upgrade.md b/docs/build/building-apps/03-app-upgrade.md index d5a88c5d7..ebaddb3f7 100644 --- a/docs/build/building-apps/03-app-upgrade.md +++ b/docs/build/building-apps/03-app-upgrade.md @@ -52,9 +52,9 @@ be a matter of minutes and not even require them to be awake at that time. ## Integrating With An App -::tip +:::tip The following is not required for users using `depinject` / app v2, 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 keeper's PreBlocker method: diff --git a/docs/build/building-apps/04-security-part-1.md b/docs/build/building-apps/04-security-part-1.md index 53a85afc1..bdda5c1e2 100644 --- a/docs/build/building-apps/04-security-part-1.md +++ b/docs/build/building-apps/04-security-part-1.md @@ -203,7 +203,7 @@ Due to [challenges with how Cosmos SDK gas estimation works](https://github.com/ If the chain increases gas usage in ways that are not included in simulation logic, this could break many clients at chain upgrade time until they increase their gas multipliers. -The specific area to pay attention to on this front is the `simulate` parameter in the `AnteHander` API. An example that could cause issues might look like the following: +The specific area to pay attention to on this front is the `simulate` parameter in the `AnteHandler` API. An example that could cause issues might look like the following: ```go func (mfd MyMemPoolDecorator) AnteHandle(ctx sdk.Context, tx sdk.Tx, simulate bool, next sdk.AnteHandler) (newCtx sdk.Context, err error) { @@ -252,8 +252,8 @@ The following are NOT in the state-machine scope: * Errors (assuming use of Go-native errors) * ABCI 2.0 `PrepareProposal` * ABCI 2.0 `ExtendVote` -* `AnteHander`s in any mode other than `execModeFinalize` -* `PostHander`s in any mode other than `execModeFinalize` +* `AnteHandler`s in any mode other than `execModeFinalize` +* `PostHandler`s in any mode other than `execModeFinalize` ### Key Malleability and Prefix Iteration Attack Example diff --git a/docs/build/building-modules/00-intro.md b/docs/build/building-modules/00-intro.md index 9547efa70..b055dfd1e 100644 --- a/docs/build/building-modules/00-intro.md +++ b/docs/build/building-modules/00-intro.md @@ -23,49 +23,21 @@ On top of this core, the Cosmos SDK enables developers to build modules that imp Cosmos SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../../learn/advanced/04-store.md), as well as a subset of [message types](./02-messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../../learn/advanced/00-baseapp.md), to a module Protobuf [`Msg` service](./03-msg-services.md) that defines them. -```text - + - | - | Transaction relayed from the full-node's consensus engine - | to the node's application via DeliverTx - | - | - | - +---------------------v--------------------------+ - | APPLICATION | - | | - | Using baseapp's methods: Decode the Tx, | - | extract and route the message(s) | - | | - +---------------------+--------------------------+ - | - | - | - +---------------------------+ - | - | - | - | Message routed to the correct - | module to be processed - | - | -+----------------+ +---------------+ +----------------+ +------v----------+ -| | | | | | | | -| AUTH MODULE | | BANK MODULE | | STAKING MODULE | | GOV MODULE | -| | | | | | | | -| | | | | | | Handles message,| -| | | | | | | Updates state | -| | | | | | | | -+----------------+ +---------------+ +----------------+ +------+----------+ - | - | - | - | - +--------------------------+ - | - | Return result to the underlying consensus engine (e.g. CometBFT) - | (0=Ok, 1=Err) - v +```mermaid +flowchart TD + A[Transaction relayed from the full-node's consensus engine to the node's application via DeliverTx] + A --> B[APPLICATION] + B --> C["Using baseapp's methods: Decode the Tx, extract and route the message(s)"] + C --> D[Message routed to the correct module to be processed] + D --> E[AUTH MODULE] + D --> F[BANK MODULE] + D --> G[STAKING MODULE] + D --> H[GOV MODULE] + H --> I[Handles message, Updates state] + E --> I + F --> I + G --> I + I --> J["Return result to the underlying consensus engine (e.g. CometBFT) (0=Ok, 1=Err)"] ``` As a result of this architecture, building a Cosmos SDK application usually revolves around writing modules to implement the specialized logic of the application and composing them with existing modules to complete the application. Developers will generally work on modules that implement logic needed for their specific use case that do not exist yet, and will use existing modules for more generic functionalities like staking, accounts, or token management. diff --git a/docs/build/building-modules/01-module-manager.md b/docs/build/building-modules/01-module-manager.md index e0ab0e54f..56868af4a 100644 --- a/docs/build/building-modules/01-module-manager.md +++ b/docs/build/building-modules/01-module-manager.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Module Manager :::note Synopsis -Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../../learn/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`PreBlocker`](../../learn/beginner/00-app-anatomy#preblocker) and [`BeginBlocker` and `EndBlocker`](../../learn/beginner/00-app-anatomy.md#begingblocker-and-endblocker). +Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../../learn/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`PreBlocker`](https://docs.cosmos.network/main/learn/beginner/app-anatomy) and [`BeginBlocker` and `EndBlocker`](https://docs.cosmos.network/main/learn/beginner/app-anatomy). ::: :::note Pre-requisite Readings @@ -27,15 +27,15 @@ For legacy reason modules can still implement interfaces from the SDK `module` p 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: + + * (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. -* [`module.HasGenesis`](#modulehasgenesis) for inter-dependent genesis-related module functionalities. -* [`module.HasABCIGenesis`](#modulehasabcigenesis) for inter-dependent genesis-related module functionalities. -* [`appmodule.HasGenesis` / `module.HasGenesis`](#appmodulehasgenesis): The extension interface for stateful genesis methods. +* (legacy) [`module.HasGenesis`](#modulehasgenesis) for inter-dependent genesis-related module functionalities. +* (legacy) [`module.HasABCIGenesis`](#modulehasabcigenesis) for inter-dependent genesis-related module functionalities. * [`appmodule.HasPreBlocker`](#haspreblocker): The extension interface that contains information about the `AppModule` and `PreBlock`. * [`appmodule.HasBeginBlocker`](#hasbeginblocker): The extension interface that contains information about the `AppModule` and `BeginBlock`. * [`appmodule.HasEndBlocker`](#hasendblocker): The extension interface that contains information about the `AppModule` and `EndBlock`. @@ -46,31 +46,34 @@ The above interfaces are mostly embedding smaller interfaces (extension interfac * (legacy) [`module.HasInvariants`](#hasinvariants): The extension interface for registering invariants. * (legacy) [`module.HasConsensusVersion`](#hasconsensusversion): The extension interface for declaring a module consensus version. -The `AppModuleBasic` interface exists to define independent methods of the module, i.e. those that do not depend on other modules in the application. This allows for the construction of the basic application structure early in the application definition, generally in the `init()` function of the [main application file](../../learn/beginner/00-app-anatomy.md#core-application-file). - The `AppModule` interface exists to define inter-dependent module methods. Many modules need to interact with other modules, typically through [`keeper`s](./06-keeper.md), which means there is a need for an interface where modules list their `keeper`s and other methods that require a reference to another module's object. `AppModule` interface extension, such as `HasBeginBlocker` and `HasEndBlocker`, also enables the module manager to set the order of execution between module's methods like `BeginBlock` and `EndBlock`, which is important in cases where the order of execution between modules matters in the context of the application. The usage of extension interfaces allows modules to define only the functionalities they need. For example, a module that does not need an `EndBlock` does not need to define the `HasEndBlocker` interface and thus the `EndBlock` method. `AppModule` and `AppModuleGenesis` are voluntarily small interfaces, that can take advantage of the `Module` patterns without having to define many placeholder functions. -### `AppModuleBasic` +### `HasAminoCodec` -:::note -Use `module.CoreAppModuleBasicAdaptor` instead for creating an `AppModuleBasic` from an `appmodule.AppModule`. -::: +```go reference +// TODO +``` + +* `RegisterLegacyAminoCodec(*codec.LegacyAmino)`: Registers the `amino` codec for the module, which is used to marshal and unmarshal structs to/from `[]byte` in order to persist them in the module's `KVStore`. -The `AppModuleBasic` interface defines the independent methods modules need to implement. +### `HasRegisterInterfaces` ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go#L56-L66 +// TODO ``` -Let us go through the methods: - -* `RegisterLegacyAminoCodec(*codec.LegacyAmino)`: Registers the `amino` codec for the module, which is used to marshal and unmarshal structs to/from `[]byte` in order to persist them in the module's `KVStore`. * `RegisterInterfaces(codectypes.InterfaceRegistry)`: Registers a module's interface types and their concrete implementations as `proto.Message`. + +### `HasGRPCGateway` + +```go reference +// TODO +``` + * `RegisterGRPCGatewayRoutes(client.Context, *runtime.ServeMux)`: Registers gRPC routes for the module. -All the `AppModuleBasic` of an application are managed by the [`BasicManager`](#basicmanager). ### `HasName` @@ -83,7 +86,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go ### Genesis :::tip -For easily creating an `AppModule` that only has genesis functionalities, use `module.GenesisOnlyAppModule`. +For easily creating an `AppModule` that only has genesis functionalities, implement `module.HasGenesis/HasABCIGenesis` and `module.HasName`. ::: #### `module.HasGenesisBasics` @@ -113,16 +116,6 @@ https://github.com/cosmos/cosmos-sdk/blob/6ce2505/types/module/module.go#L184-L1 https://github.com/cosmos/cosmos-sdk/blob/6ce2505/types/module/module.go#L191-L196 ``` -#### `appmodule.HasGenesis` - -:::warning -`appmodule.HasGenesis` is experimental and should be considered unstable, it is recommended to not use this interface at this time. -::: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/6ce2505/core/appmodule/genesis.go#L8-L25 -``` - ### `AppModule` The `AppModule` interface defines a module. Modules can declare their functionalities by implementing extensions interfaces. @@ -238,49 +231,24 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/core/appmodule/module. ### Implementing the Application Module Interfaces +// TODO reword! + Typically, the various application module interfaces are implemented in a file called `module.go`, located in the module's folder (e.g. `./x/module/module.go`). -Almost every module needs to implement the `AppModuleBasic` and `AppModule` interfaces. If the module is only used for genesis, it will implement `AppModuleGenesis` instead of `AppModule`. The concrete type that implements the interface can add parameters that are required for the implementation of the various methods of the interface. For example, the `Route()` function often calls a `NewMsgServerImpl(k keeper)` function defined in `keeper/msg_server.go` and therefore needs to pass the module's [`keeper`](./06-keeper.md) as a parameter. +Almost every module needs to implement the `AppModule` interfaces. If the module is only used for genesis, it will implement `AppModuleGenesis` instead of `AppModule`. The concrete type that implements the interface can add parameters that are required for the implementation of the various methods of the interface. For example, the `Route()` function often calls a `NewMsgServerImpl(k keeper)` function defined in `keeper/msg_server.go` and therefore needs to pass the module's [`keeper`](./06-keeper.md) as a parameter. ```go // example type AppModule struct { - AppModuleBasic keeper Keeper } ``` In the example above, you can see that the `AppModule` concrete type references an `AppModuleBasic`, and not an `AppModuleGenesis`. That is because `AppModuleGenesis` only needs to be implemented in modules that focus on genesis-related functionalities. In most modules, the concrete `AppModule` type will have a reference to an `AppModuleBasic` and implement the two added methods of `AppModuleGenesis` directly in the `AppModule` type. -If no parameter is required (which is often the case for `AppModuleBasic`), just declare an empty concrete type like so: - -```go -type AppModuleBasic struct{} -``` - -## Module Managers - -Module managers are used to manage collections of `AppModuleBasic` and `AppModule`. - -### `BasicManager` +## Module Manager -The `BasicManager` is a structure that lists all the `AppModuleBasic` of an application: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go#L82 -``` - -It implements the following methods: - -* `NewBasicManager(modules ...AppModuleBasic)`: Constructor function. It takes a list of the application's `AppModuleBasic` and builds a new `BasicManager`. This function is generally called in the `init()` function of [`app.go`](../../learn/beginner/00-app-anatomy.md#core-application-file) to quickly initialize the independent elements of the application's modules (click [here](https://github.com/cosmos/gaia/blob/main/app/app.go#L59-L74) to see an example). -* `NewBasicManagerFromManager(manager *Manager, customModuleBasics map[string]AppModuleBasic)`: Constructor function. It creates a new `BasicManager` from a `Manager`. The `BasicManager` will contain all `AppModuleBasic` from the `AppModule` manager using `CoreAppModuleBasicAdaptor` whenever possible. Module's `AppModuleBasic` can be overridden by passing a custom AppModuleBasic map -* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../../learn/advanced/05-encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../../learn/beginner/00-app-anatomy.md#constructor). -* `RegisterInterfaces(registry codectypes.InterfaceRegistry)`: Registers interface types and implementations of each of the application's `AppModuleBasic`. -* `DefaultGenesis(cdc codec.JSONCodec)`: Provides default genesis information for modules in the application by calling the [`DefaultGenesis(cdc codec.JSONCodec)`](./08-genesis.md#defaultgenesis) function of each module. It only calls the modules that implements the `HasGenesisBasics` interfaces. -* `ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage)`: Validates the genesis information modules by calling the [`ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`](./08-genesis.md#validategenesis) function of modules implementing the `HasGenesisBasics` interface. -* `RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)`: Registers gRPC routes for modules. -* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands (defined as `GetTxCmd() *cobra.Command`) to the application's [`rootTxCommand`](../../learn/advanced/07-cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../learn/advanced/07-cli.md). -* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands (defined as `GetQueryCmd() *cobra.Command`) to the application's [`rootQueryCommand`](../../learn/advanced/07-cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../learn/advanced/07-cli.md). +The module manager is used to manage collections of `appmodule.AppModule` and `AppModule` and all the extensions interfaces. ### `Manager` @@ -304,14 +272,19 @@ The module manager is used throughout the application whenever an action on a co * `SetOrderMigrations(moduleNames ...string)`: Sets the order of migrations to be run. If not set then migrations will be run with an order defined in `DefaultMigrationsOrder`. * `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./07-invariants.md) of module implementing the `HasInvariants` interface. * `RegisterServices(cfg Configurator)`: Registers the services of modules implementing the `HasServices` interface. -* `InitGenesis(ctx context.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.ResponseInitChain` to the underlying consensus engine, which can contain validator updates. -* `ExportGenesis(ctx context.Context, cdc codec.JSONCodec)`: Calls the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required. -* `ExportGenesisForModules(ctx context.Context, cdc codec.JSONCodec, modulesToExport []string)`: Behaves the same as `ExportGenesis`, except takes a list of modules to export. +* `InitGenesis(ctx context.Context, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.InitChainResponse` to the underlying consensus engine, which can contain validator updates. +* `ExportGenesis(ctx context.Context)`: Calls the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required. +* `ExportGenesisForModules(ctx context.Context, modulesToExport []string)`: Behaves the same as `ExportGenesis`, except takes a list of modules to export. * `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../../learn/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./06-beginblock-endblock.md) function of each modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../../learn/advanced/02-context.md) with an event manager to aggregate [events](../../learn/advanced/08-events.md) emitted from each modules. * `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../../learn/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./06-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../learn/advanced/02-context.md) with an event manager to aggregate [events](../../learn/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../../learn/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./06-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndBlock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../learn/advanced/02-context.md) with an event manager to aggregate [events](../../learn/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `Precommit(ctx context.Context)`: During [`Commit`](../../learn/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../../learn/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../learn/advanced/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../../learn/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../../learn/advanced/00-baseapp.md#state-updates). * `PrepareCheckState(ctx context.Context)`: During [`Commit`](../../learn/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../../learn/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../learn/advanced/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../../learn/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../../learn/advanced/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../../learn/advanced/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block. +* (Optional) `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../../learn/advanced/05-encoding.md#amino) of each of the application module. This function is usually called early on in the [application's construction](../../learn/beginner/00-app-anatomy.md#constructor). +* `RegisterInterfaces(registry codectypes.InterfaceRegistry)`: Registers interface types and implementations of each of the application's `AppModule`. +* (Optional) `RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)`: Registers gRPC routes for modules. +* `DefaultGenesis(cdc codec.JSONCodec)`: Provides default genesis information for modules in the application by calling the [`DefaultGenesis(cdc codec.JSONCodec)`](./08-genesis.md#defaultgenesis) function of each module. It only calls the modules that implements the `HasGenesisBasics` interfaces. +* `ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage)`: Validates the genesis information modules by calling the [`ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`](./08-genesis.md#validategenesis) function of modules implementing the `HasGenesisBasics` interface. Here's an example of a concrete integration within an `simapp`: diff --git a/docs/build/building-modules/02-messages-and-queries.md b/docs/build/building-modules/02-messages-and-queries.md index 0751c96d6..5c97401b9 100644 --- a/docs/build/building-modules/02-messages-and-queries.md +++ b/docs/build/building-modules/02-messages-and-queries.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.RequestQuery)` to return the full `abci.ResponseQuery` with inclusion Merkle proofs. +Store queries query directly for store keys. They use `clientCtx.QueryABCI(req abci.QueryRequest)` to return the full `abci.QueryResponse` with inclusion Merkle proofs. See following examples: diff --git a/docs/build/building-modules/03-msg-services.md b/docs/build/building-modules/03-msg-services.md index c5ded4b1d..83f8f6e70 100644 --- a/docs/build/building-modules/03-msg-services.md +++ b/docs/build/building-modules/03-msg-services.md @@ -19,7 +19,7 @@ A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messa Each module should define a Protobuf `Msg` service, which will be responsible for processing requests (implementing `sdk.Msg`) and returning responses. -As further described in [ADR 031](../architecture/adr-031-msg-service.md), this approach has the advantage of clearly specifying return types and generating server and client code. +As further described in [ADR 031](../../architecture/adr-031-msg-service.md), this approach has the advantage of clearly specifying return types and generating server and client code. Protobuf generates a `MsgServer` interface based on a definition of `Msg` service. It is the role of the module developer to implement this interface, by implementing the state transition logic that should happen upon receival of each `sdk.Msg`. As an example, here is the generated `MsgServer` interface for `x/bank`, which exposes two `sdk.Msg`s: diff --git a/docs/build/building-modules/05-protobuf-annotations.md b/docs/build/building-modules/05-protobuf-annotations.md index fe212f726..9843a6339 100644 --- a/docs/build/building-modules/05-protobuf-annotations.md +++ b/docs/build/building-modules/05-protobuf-annotations.md @@ -58,7 +58,7 @@ Example of Int scalar: https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/gov/v1/gov.proto#L137 ``` -There are a few options for what can be provided as a scalar: cosmos.AddressString, cosmos.ValidatorAddressString, cosmos.ConsensusAddressString, cosmos.Int, cosmos.Dec. +There are a few options for what can be provided as a scalar: `cosmos.AddressString`, `cosmos.ValidatorAddressString`, `cosmos.ConsensusAddressString`, `cosmos.Int`, `cosmos.Dec`. ## Implements_Interface @@ -68,9 +68,21 @@ Implement interface is used to provide information to client tooling like [teles option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; ``` +## Method,Field,Message Added In + +`method_added_in`, `field_added_in` and `message_added_in` are annotations to denotate to clients that a field has been supported in a later version. This is useful when new methods or fields are added in later versions and that the client needs to be aware of what it can call. + +The annotation should be worded as follow: + +```proto +option (cosmos_proto.method_added_in) = "cosmos-sdk v0.50.1"; +option (cosmos_proto.method_added_in) = "x/epochs v1.0.0"; +option (cosmos_proto.method_added_in) = "simapp v24.0.0"; +``` + ## Amino -The amino codec was removed in 0.50.0, this means there is not a need register `legacyAminoCodec`. To replace the amino codec, Amino protobuf annotations are used to provide information to the amino codec on how to encode and decode protobuf messages. +The amino codec was removed in `v0.50+`, this means there is not a need register `legacyAminoCodec`. To replace the amino codec, Amino protobuf annotations are used to provide information to the amino codec on how to encode and decode protobuf messages. :::note Amino annotations are only used for backwards compatibility with amino. New modules are not required use amino annotations. diff --git a/docs/build/building-modules/11-structure.md b/docs/build/building-modules/11-structure.md index ca0eede56..678c740db 100644 --- a/docs/build/building-modules/11-structure.md +++ b/docs/build/building-modules/11-structure.md @@ -83,7 +83,7 @@ x/{module_name} * `abci.go`: The module's `BeginBlocker` and `EndBlocker` implementations (this file is only required if `BeginBlocker` and/or `EndBlocker` need to be defined). * `autocli.go`: The module [autocli](https://docs.cosmos.network/main/core/autocli) options. * `simulation/`: The module's [simulation](./14-simulator.md) package defines functions used by the blockchain simulator application (`simapp`). -* `README.md`: The module's specification documents outlining important concepts, state storage structure, and message and event type definitions. Learn more how to write module specs in the [spec guidelines](../spec/SPEC_MODULE.md). +* `README.md`: The module's specification documents outlining important concepts, state storage structure, and message and event type definitions. Learn more how to write module specs in the [spec guidelines](../../spec/SPEC_MODULE.md). * The root directory includes type definitions for messages, events, and genesis state, including the type definitions generated by Protocol Buffers. * `codec.go`: The module's registry methods for interface types. * `errors.go`: The module's sentinel errors. diff --git a/docs/build/building-modules/13-upgrade.md b/docs/build/building-modules/13-upgrade.md index fc3dc384b..5cdce2b44 100644 --- a/docs/build/building-modules/13-upgrade.md +++ b/docs/build/building-modules/13-upgrade.md @@ -62,4 +62,4 @@ func (m Migrator) Migrate1to2(ctx sdk.Context) error { } ``` -To see example code of changes that were implemented in a migration of balance keys, check out [migrateBalanceKeys](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/migrations/v2/store.go#L55-L76). For context, this code introduced migrations of the bank store that updated addresses to be prefixed by their length in bytes as outlined in [ADR-028](../architecture/adr-028-public-key-addresses.md). +To see example code of changes that were implemented in a migration of balance keys, check out [migrateBalanceKeys](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/migrations/v2/store.go#L55-L76). For context, this code introduced migrations of the bank store that updated addresses to be prefixed by their length in bytes as outlined in [ADR-028](../../architecture/adr-028-public-key-addresses.md). diff --git a/docs/build/migrations/02-upgrading.md b/docs/build/migrations/02-upgrading.md index 6126ce607..491299c8f 100644 --- a/docs/build/migrations/02-upgrading.md +++ b/docs/build/migrations/02-upgrading.md @@ -9,6 +9,7 @@ Note, always read the **SimApp** section for more information on application wir In this section we describe the changes made in Cosmos SDK' SimApp. **These changes are directly applicable to your application wiring.** +Please read this section first, but for an exhaustive list of changes, refer to the [CHANGELOG](./simapp/CHANGELOG.md). #### Client (`root.go`) @@ -61,6 +62,10 @@ For non depinject users, simply call `RegisterLegacyAminoCodec` and `RegisterInt Additionally, thanks to the genesis simplification, as explained in [the genesis interface update](#genesis-interface), the module manager `InitGenesis` and `ExportGenesis` methods do not require the codec anymore. +##### GRPC-WEB + +Grpc-web embedded client has been removed from the server. If you would like to use grpc-web, you can use the [envoy proxy](https://www.envoyproxy.io/docs/envoy/latest/start/start). + ##### AnteHandlers The `GasConsumptionDecorator` and `IncreaseSequenceDecorator` have been merged with the SigVerificationDecorator, so you'll @@ -141,6 +146,23 @@ used as a TTL for the transaction and is used to provide replay protection. See [ADR-070](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-070-unordered-transactions.md) for more details. +### Depinject `app_config.go` / `app.yml` + +With the introduction of [environment in modules](#core-api), depinject automatically creates the environment for all modules. +Learn more about environment [here](https://example.com) . Given the fields of environment, this means runtime creates a kv store service for all modules by default. +It can happen that some modules do not have a store necessary (such as `x/auth/tx` for instance). In this case, the store creation should be skipped in `app_config.go`: + +```diff +InitGenesis: []string{ + "..." +}, ++ // SkipStoreKeys is an optional list of store keys to skip when constructing the ++ // module's keeper. This is useful when a module does not have a store key. ++ SkipStoreKeys: []string{ ++ "tx", ++ }, +``` + ### Protobuf The `cosmossdk.io/api/tendermint` package has been removed as CometBFT now publishes its protos to `buf.build/tendermint` and `buf.build/cometbft`. @@ -154,35 +176,25 @@ The `codectypes.Any` has moved to `github.com/cosmos/gogoproto/types/any`. Modul #### `**all**` -##### Simulation - -`MsgSimulatorFn` has been updated to return an error. Its context argument has been removed, and an address.Codec has -been added to avoid the use of the Accounts.String() method. - -```diff --type MsgSimulatorFn func(r *rand.Rand, ctx sdk.Context, accs []Account) sdk.Msg -+type MsgSimulatorFn func(r *rand.Rand, accs []Account, cdc address.Codec) (sdk.Msg, error) -``` - ##### Core API Core API has been introduced for modules since v0.47. With the deprecation of `sdk.Context`, we strongly recommend to use the `cosmossdk.io/core/appmodule` interfaces for the modules. This will allow the modules to work out of the box with server/v2 and baseapp, as well as limit their dependencies on the SDK. -Additionally, the `appmodule.Environment` interface is introduced to fetch different services from the application. +Additionally, the `appmodule.Environment` struct is introduced to fetch different services from the application. This should be used as an alternative to using `sdk.UnwrapContext(ctx)` to fetch the services. -It needs to be passed into a module at instantiation. +It needs to be passed into a module at instantiation (or depinject will inject the correct environment). `x/circuit` is used as an example: ```go -app.CircuitKeeper = circuitkeeper.NewKeeper(runtime.NewEnvironment((keys[circuittypes.StoreKey])), appCodec, authtypes.NewModuleAddress(govtypes.ModuleName).String(), app.AuthKeeper.AddressCodec()) +app.CircuitKeeper = circuitkeeper.NewKeeper(runtime.NewEnvironment(runtime.NewKVStoreService(keys[circuittypes.StoreKey]), logger.With(log.ModuleKey, "x/circuit")), appCodec, authtypes.NewModuleAddress(govtypes.ModuleName).String(), app.AuthKeeper.AddressCodec()) ``` If your module requires a message server or query server, it should be passed in the environment as well. ```diff -govKeeper := govkeeper.NewKeeper(appCodec, runtime.NewKVStoreService(keys[govtypes.StoreKey]), app.AuthKeeper, app.BankKeeper,app.StakingKeeper, app.PoolKeeper, app.MsgServiceRouter(), govConfig, authtypes.NewModuleAddress(govtypes.ModuleName).String()) -+govKeeper := govkeeper.NewKeeper(appCodec, runtime.NewEnvironment(runtime.NewKVStoreService(keys[govtypes.StoreKey]), logger, runtime.EnvWithRouterService(app.GRPCQueryRouter(), app.MsgServiceRouter())), app.AuthKeeper, app.BankKeeper, app.StakingKeeper, app.PoolKeeper, govConfig, authtypes.NewModuleAddress(govtypes.ModuleName).String()) ++govKeeper := govkeeper.NewKeeper(appCodec, runtime.NewEnvironment(runtime.NewKVStoreService(keys[govtypes.StoreKey]), logger.With(log.ModuleKey, "x/circuit"), runtime.EnvWithMsgRouterService(app.MsgServiceRouter()), runtime.EnvWithQueryRouterService(app.GRPCQueryRouter())), app.AuthKeeper, app.BankKeeper, app.StakingKeeper, app.PoolKeeper, govConfig, authtypes.NewModuleAddress(govtypes.ModuleName).String()) ``` The signature of the extension interface `HasRegisterInterfaces` has been changed to accept a `cosmossdk.io/core/registry.InterfaceRegistrar` instead of a `codec.InterfaceRegistry`. `HasRegisterInterfaces` is now a part of `cosmossdk.io/core/appmodule`. Modules should update their `HasRegisterInterfaces` implementation to accept a `cosmossdk.io/core/registry.InterfaceRegistrar` interface. @@ -192,7 +204,24 @@ The signature of the extension interface `HasRegisterInterfaces` has been change +func (AppModule) RegisterInterfaces(registry registry.InterfaceRegistrar) { ``` -##### Dependency Injection +The signature of the extension interface `HasAminoCodec` has been changed to accept a `cosmossdk.io/core/legacy.Amino` instead of a `codec.LegacyAmino`. Modules should update their `HasAminoCodec` implementation to accept a `cosmossdk.io/core/legacy.Amino` interface. + +```diff +-func (AppModule) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino) { ++func (AppModule) RegisterLegacyAminoCodec(cdc legacy.Amino) { +``` + +##### Simulation + +`MsgSimulatorFn` has been updated to return an error. Its context argument has been removed, and an address.Codec has +been added to avoid the use of the Accounts.String() method. + +```diff +-type MsgSimulatorFn func(r *rand.Rand, ctx sdk.Context, accs []Account) sdk.Msg ++type MsgSimulatorFn func(r *rand.Rand, accs []Account, cdc address.Codec) (sdk.Msg, error) +``` + +##### Depinject Previously `cosmossdk.io/core` held functions `Invoke`, `Provide` and `Register` were moved to `cosmossdk.io/depinject/appconfig`. All modules using dependency injection must update their imports. diff --git a/docs/build/packages/02-collections.md b/docs/build/packages/02-collections.md index 28d55c81c..09c6870ba 100644 --- a/docs/build/packages/02-collections.md +++ b/docs/build/packages/02-collections.md @@ -193,7 +193,7 @@ We already know the first three arguments of the ``NewMap`` function. The fourth parameter is our `KeyCodec`, we know that the ``Map`` has `string` as key so we pass it a `KeyCodec` that handles strings as keys. -The fifth parameter is our `ValueCodec`, we know that the `Map` as a `uint64` as value so we pass it a `ValueCodec` that handles uint64. +The fifth parameter is our `ValueCodec`, we know that the `Map` has a `uint64` as value so we pass it a `ValueCodec` that handles uint64. Collections already comes with all the required implementations for golang primitive types. @@ -587,7 +587,7 @@ Let's analyse each method in the example and how it makes use of the `Iterate` a In `GetAllAccounts` we pass to our `Iterate` a nil `Ranger`. This means that the returned `Iterator` will include all the existing keys within the collection. -Then we use some the `Values` method from the returned `Iterator` API to collect all the values into a slice. +Then we use the `Values` method from the returned `Iterator` API to collect all the values into a slice. `Iterator` offers other methods such as `Keys()` to collect only the keys and not the values and `KeyValues` to collect all the keys and values. @@ -602,7 +602,7 @@ we instruct it to report us results in reverse order through `Descending` Then we pass the range instruction to `Iterate` and get an `Iterator`, which will contain only the results we specified in the range. -Then we use again th `Values` method of the `Iterator` to collect all the results. +Then we use again the `Values` method of the `Iterator` to collect all the results. `collections.Range` also offers a `Prefix` API which is not applicable to all keys types, for example uint64 cannot be prefix because it is of constant size, but a `string` key @@ -777,7 +777,7 @@ We use the `collections.Join` function to generate the composite key. `collections.Pair` contains the two keys we have joined, it also exposes two methods: `K1` to fetch the 1st part of the key and `K2` to fetch the second part. -As always, we use the `collections.Map.Set` method to map the composite key to our value (`math.Int`in this case) +As always, we use the `collections.Map.Set` method to map the composite key to our value (`math.Int` in this case) #### GetBalance @@ -860,7 +860,7 @@ Then we can see in our `AccountIndexes` struct the `Number` field is defined as: ``` Where the first type parameter is `uint64`, which is the field type of our index. -The second type parameter is the primary key `sdk.AccAddress` +The second type parameter is the primary key `sdk.AccAddress`. And the third type parameter is the actual object we're storing `authtypes.BaseAccount`. Then we create a `NewAccountIndexes` function that instantiates and returns the `AccountsIndexes` struct. diff --git a/docs/build/spec/_ics/ics-030-signed-messages.md b/docs/build/spec/_ics/ics-030-signed-messages.md index ce4e273e6..6ea8ccfaa 100644 --- a/docs/build/spec/_ics/ics-030-signed-messages.md +++ b/docs/build/spec/_ics/ics-030-signed-messages.md @@ -87,7 +87,7 @@ to the Cosmos chain identifier. The user-agent should **refuse** signing if the `@chain_id` field does not match the currently active chain! The `@type` field must equal the constant `"message"`. The `@type` field corresponds to the type of structure the user will be signing in an application. For now, a user is only -allowed to sign bytes of valid ASCII text ([see here](https://github.com/cometbft/cometbft/blob/v0.37.0/libs/strings/string.go#L35-L64)). +allowed to sign bytes of valid ASCII text ([see here](https://github.com/cometbft/cometbft/blob/v0.38.0/libs/strings/string.go#L57-L67)). However, this will change and evolve to support additional application-specific structures that are human-readable and machine-verifiable. diff --git a/docs/build/spec/fee_distribution/f1_fee_distr.tex b/docs/build/spec/fee_distribution/f1_fee_distr.tex index 4bcfc7718..6f230a286 100644 --- a/docs/build/spec/fee_distribution/f1_fee_distr.tex +++ b/docs/build/spec/fee_distribution/f1_fee_distr.tex @@ -237,7 +237,7 @@ \section{TO DOs} \item Mention storage optimization for how to prune slashing entries in the uniform inflation and iteration over slashing case \item Add equation numbers \item perhaps re-organize so that the no iteration - \item Section on decimal precision considerations (would unums help?), and mitigating errors in calculation with floats and decimals. -- This probably belongs in a corrollary markdown file in the implementation + \item Section on decimal precision considerations (would unums help?), and mitigating errors in calculation with floats and decimals. -- This probably belongs in a corollary markdown file in the implementation \item Consider indicating that the withdraw action need not be a tx type and could instead happen 'transparently' when more coins are needed, if a chain desired this for UX / p2p efficiency. \end{itemize} diff --git a/docs/build/spec/store/README.md b/docs/build/spec/store/README.md index bd665aa49..706ee4d6c 100644 --- a/docs/build/spec/store/README.md +++ b/docs/build/spec/store/README.md @@ -156,7 +156,7 @@ state from each `KVStore` to disk and returning an application state Merkle root Queries can be performed to return state data along with associated state commitment proofs for both previous heights/versions and the current state root. Queries are routed based on store name, i.e. a module, along with other parameters -which are defined in `abci.RequestQuery`. +which are defined in `abci.QueryRequest`. The `rootmulti.Store` also provides primitives for pruning data at a given height/version from state storage. When a height is committed, the `rootmulti.Store` diff --git a/docs/build/spec/store/interblock-cache.md b/docs/build/spec/store/interblock-cache.md index 8741dad03..afe070761 100644 --- a/docs/build/spec/store/interblock-cache.md +++ b/docs/build/spec/store/interblock-cache.md @@ -278,7 +278,7 @@ func CacheWrap( ### Implementation details -The inter-block cache implementation uses a fixed-sized adaptive replacement cache (ARC) as cache. [The ARC implementation](https://github.com/hashicorp/golang-lru/blob/master/arc.go) is thread-safe. ARC is an enhancement over the standard LRU cache in that tracks both frequency and recency of use. This avoids a burst in access to new entries from evicting the frequently used older entries. It adds some additional tracking overhead to a standard LRU cache, computationally it is roughly `2x` the cost, and the extra memory overhead is linear with the size of the cache. The default cache size is `1000`. +The inter-block cache implementation uses a fixed-sized adaptive replacement cache (ARC) as cache. [The ARC implementation](https://github.com/hashicorp/golang-lru/blob/main/arc/arc.go) is thread-safe. ARC is an enhancement over the standard LRU cache in that tracks both frequency and recency of use. This avoids a burst in access to new entries from evicting the frequently used older entries. It adds some additional tracking overhead to a standard LRU cache, computationally it is roughly `2x` the cost, and the extra memory overhead is linear with the size of the cache. The default cache size is `1000`. ## History diff --git a/docs/build/tooling/00-protobuf.md b/docs/build/tooling/00-protobuf.md index 69d78f331..3780435b1 100644 --- a/docs/build/tooling/00-protobuf.md +++ b/docs/build/tooling/00-protobuf.md @@ -78,7 +78,7 @@ Example of how to define `gen` files can be found [here](https://docs.buf.build/ #### `buf.gen.swagger.yaml` -`buf.gen.swagger.yaml` generates the swagger documentation for the query and messages of the chain. This will only define the REST API end points that were defined in the query and msg servers. You can find examples of this [here](https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/bank/v1beta1/query.proto#L19) +`buf.gen.swagger.yaml` generates the swagger documentation for the query and messages of the chain. This will only define the REST API end points that were defined in the query and msg servers. You can find examples of this [here](https://github.com/cosmos/cosmos-sdk/blob/main/x/bank/proto/cosmos/bank/v1beta1/query.proto) ```go reference https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.swagger.yaml#L1-L6 diff --git a/docs/build/tooling/03-hubl.md b/docs/build/tooling/03-hubl.md index 6d04fb778..9088abfd0 100644 --- a/docs/build/tooling/03-hubl.md +++ b/docs/build/tooling/03-hubl.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Hubl `Hubl` is a tool that allows you to query any Cosmos SDK based blockchain. -It takes advantage of the new [AutoCLI](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/client/v2@v2.0.0-20220916140313-c5245716b516/cli) feature of the Cosmos SDK. +It takes advantage of the new [AutoCLI](https://docs.cosmos.network/main/learn/advanced/autocli) feature of the Cosmos SDK. ## Installation diff --git a/docs/learn/advanced/00-baseapp.md b/docs/learn/advanced/00-baseapp.md index d4d31ed50..f19c13299 100644 --- a/docs/learn/advanced/00-baseapp.md +++ b/docs/learn/advanced/00-baseapp.md @@ -99,7 +99,7 @@ Finally, a few more important parameters: * `minGasPrices`: This parameter defines the minimum gas prices accepted by the node. This is a **local** parameter, meaning each full-node can set a different `minGasPrices`. It is used in the `AnteHandler` during [`CheckTx`](#checktx), mainly as a spam protection mechanism. The transaction - enters the [mempool](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#mempool-methods) + enters the [mempool](https://docs.cometbft.com/v1.0/explanation/core/mempool) only if the gas prices of the transaction are greater than one of the minimum gas price in `minGasPrices` (e.g. if `minGasPrices == 1uatom,1photon`, the `gas-price` of the transaction must be greater than `1uatom` OR `1photon`). @@ -230,7 +230,7 @@ Just like the `msgServiceRouter`, the `grpcQueryRouter` is initialized with all ## Main ABCI 2.0 Messages -The [Application-Blockchain Interface](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md) (ABCI) is a generic interface that connects a state-machine with a consensus engine to form a functional full-node. It can be wrapped in any language, and needs to be implemented by each application-specific blockchain built on top of an ABCI-compatible consensus engine like CometBFT. +The [Application-Blockchain Interface](https://docs.cometbft.com/v1.0/spec/abci/abci++_basic_concepts#overview-and-basic-concepts) (ABCI) is a generic interface that connects a state-machine with a consensus engine to form a functional full-node. It can be wrapped in any language, and needs to be implemented by each application-specific blockchain built on top of an ABCI-compatible consensus engine like CometBFT. The consensus engine handles two main tasks: @@ -264,13 +264,9 @@ Note that, unlike `CheckTx()`, `PrepareProposal` process `sdk.Msg`s, so it can d It's important to note that `PrepareProposal` complements the `ProcessProposal` method which is executed after this method. The combination of these two methods means that it is possible to guarantee that no invalid transactions are ever committed. Furthermore, such a setup can give rise to other interesting use cases such as Oracles, threshold decryption and more. -`PrepareProposal` returns a response to the underlying consensus engine of type [`abci.ResponseCheckTx`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#processproposal). The response contains: - -* `Code (uint32)`: Response Code. `0` if successful. -* `Data ([]byte)`: Result bytes, if any. -* `Log (string):` The output of the application's logger. May be non-deterministic. -* `Info (string):` Additional information. May be non-deterministic. +`PrepareProposal` returns a response to the underlying consensus engine of type [`abci.PrepareProposalResponse`](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#prepareproposal). The response contains: +* `Txs ([][]byte)`: List of transactions which will form a block ### Process Proposal @@ -291,13 +287,19 @@ CometBFT calls it when it receives a proposal and the CometBFT algorithm has not However, developers must exercise greater caution when using these methods. Incorrectly coding these methods could affect liveness as CometBFT is unable to receive 2/3 valid precommits to finalize a block. -`ProcessProposal` returns a response to the underlying consensus engine of type [`abci.ResponseCheckTx`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#processproposal). The response contains: +`ProcessProposal` returns a response to the underlying consensus engine of type [`abci.ProcessProposalResponse`](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#processproposal). The response contains: + +* `Status (ProposalStatus)`: Status of the proposal processing -* `Code (uint32)`: Response Code. `0` if successful. -* `Data ([]byte)`: Result bytes, if any. -* `Log (string):` The output of the application's logger. May be non-deterministic. -* `Info (string):` Additional information. May be non-deterministic. +where `ProposalStatus` can be one of the following status value: +``` +enum ProposalStatus { +UNKNOWN = 0; // Unknown status. Returning this from the application is always an error. +ACCEPT = 1; // Status that signals that the application finds the proposal valid. +REJECT = 2; // Status that signals that the application finds the proposal invalid. +} +``` ### CheckTx @@ -338,7 +340,7 @@ be rejected. In any case, the sender's account will not actually pay the fees un is actually included in a block, because `checkState` never gets committed to the main state. The `checkState` is reset to the latest state of the main state each time a blocks gets [committed](#commit). -`CheckTx` returns a response to the underlying consensus engine of type [`abci.ResponseCheckTx`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#checktx). +`CheckTx` returns a response to the underlying consensus engine of type [`abci.CheckTxResponse`](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#checktx). The response contains: * `Code (uint32)`: Response Code. `0` if successful. @@ -352,7 +354,7 @@ The response contains: https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/ante/basic.go#L102 ``` -* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./08-events.md) for more. +* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`events`](./08-events.md) for more. * `Codespace (string)`: Namespace for the Code. #### RecheckTx @@ -426,9 +428,9 @@ Note, when `PostHandler`s fail, the state from `runMsgs` is also reverted, effec ### InitChain -The [`InitChain` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#method-overview) is sent from the underlying CometBFT engine when the chain is first started. It is mainly used to **initialize** parameters and state like: +The [`InitChain` ABCI message](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#initchain) is sent from the underlying CometBFT engine when the chain is first started. It is mainly used to **initialize** parameters and state like: -* [Consensus Parameters](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#consensus-parameters) via `setConsensusParams`. +* [Consensus Parameters](https://docs.cometbft.com/v1.0/spec/abci/abci++_app_requirements#consensus-parameters) via `setConsensusParams`. * [`checkState` and `finalizeBlockState`](#state-updates) via `setState`. * The [block gas meter](../beginner/04-gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions. @@ -437,7 +439,7 @@ Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls th ### FinalizeBlock -The [`FinalizeBlock` ABCI message](https://github.com/cometbft/cometbft/blob/v0.38.x/spec/abci/abci++_basic_concepts.md#method-overview) is sent from the underlying CometBFT engine when a block proposal created by the correct proposer is received. The previous `BeginBlock, DeliverTx and Endblock` calls are private methods on the BaseApp struct. +The [`FinalizeBlock` ABCI message](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#finalizeblock) is sent from the underlying CometBFT engine when a block proposal created by the correct proposer is received. The previous `BeginBlock, DeliverTx and Endblock` calls are private methods on the BaseApp struct. ```go reference @@ -460,7 +462,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci.go#L623 * Initialize the [block gas meter](../beginner/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. * Run the application's [`beginBlocker()`](../beginner/00-app-anatomy.md#beginblocker-and-endblocker), which mainly runs the [`BeginBlocker()`](../../build/building-modules/06-beginblock-endblock.md#beginblock) method of each of the modules. -* Set the [`VoteInfos`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./02-context.md) so that it can be used during transaction execution and EndBlock. +* Set the [`VoteInfos`](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./02-context.md) so that it can be used during transaction execution and EndBlock. #### Transaction Execution @@ -485,7 +487,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/types/gas.go#L23 At any point, if `GasConsumed > GasWanted`, the function returns with `Code != 0` and the execution fails. -Each transactions returns a response to the underlying consensus engine of type [`abci.ExecTxResult`](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci%2B%2B_methods.md#exectxresult). The response contains: +Each transaction returns a response to the underlying consensus engine of type [`abci.ExecTxResult`](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#exectxresult). The response contains: * `Code (uint32)`: Response Code. `0` if successful. * `Data ([]byte)`: Result bytes, if any. @@ -493,7 +495,7 @@ Each transactions returns a response to the underlying consensus engine of type * `Info (string):` Additional information. May be non-deterministic. * `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction. * `GasUsed (int64)`: Amount of gas consumed by transaction. During transaction execution, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction, and by adding gas each time a read/write to the store occurs. -* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./08-events.md) for more. +* `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`events`](./08-events.md) for more. * `Codespace (string)`: Namespace for the Code. #### EndBlock @@ -506,7 +508,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/baseapp.go#L74 ### Commit -The [`Commit` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#method-overview) is sent from the underlying CometBFT engine after the full-node has received _precommits_ from 2/3+ of validators (weighted by voting power). On the `BaseApp` end, the `Commit(res abci.ResponseCommit)` function is implemented to commit all the valid state transitions that occurred during `FinalizeBlock` and to reset state for the next block. +The [`Commit` ABCI message](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#commit) is sent from the underlying CometBFT engine after the full-node has received _precommits_ from 2/3+ of validators (weighted by voting power). On the `BaseApp` end, the `Commit(res abci.CommitResponse)` function is implemented to commit all the valid state transitions that occurred during `FinalizeBlock` and to reset state for the next block. To commit state-transitions, the `Commit` function calls the `Write()` function on `finalizeBlockState.ms`, where `finalizeBlockState.ms` is a branched multistore of the main store `app.cms`. Then, the `Commit` function sets `checkState` to the latest header (obtained from `finalizeBlockState.ctx.BlockHeader`) and `finalizeBlockState` to `nil`. @@ -514,13 +516,13 @@ Finally, `Commit` returns the hash of the commitment of `app.cms` back to the un ### Info -The [`Info` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#info-methods) is a simple query from the underlying consensus engine, notably used to sync the latter with the application during a handshake that happens on startup. When called, the `Info(res abci.ResponseInfo)` function from `BaseApp` will return the application's name, version and the hash of the last commit of `app.cms`. +The [`Info` ABCI message](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#info) is a simple query from the underlying consensus engine, notably used to sync the latter with the application during a handshake that happens on startup. When called, the `Info(res abci.InfoResponse)` function from `BaseApp` will return the application's name, version and the hash of the last commit of `app.cms`. ### Query -The [`Query` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#info-methods) is used to serve queries received from the underlying consensus engine, including queries received via RPC like CometBFT RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../../build/building-modules/04-query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#query). +The [`Query` ABCI message](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#query) is used to serve queries received from the underlying consensus engine, including queries received via RPC like CometBFT RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../../build/building-modules/04-query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#query). -Each CometBFT `query` comes with a `path`, which is a `string` which denotes what to query. If the `path` matches a gRPC fully-qualified service method, then `BaseApp` will defer the query to the `grpcQueryRouter` and let it handle it like explained [above](#grpc-query-router). Otherwise, the `path` represents a query that is not (yet) handled by the gRPC router. `BaseApp` splits the `path` string with the `/` delimiter. By convention, the first element of the split string (`split[0]`) contains the category of `query` (`app`, `p2p`, `store` or `custom` ). The `BaseApp` implementation of the `Query(req abci.RequestQuery)` method is a simple dispatcher serving these 4 main categories of queries: +Each CometBFT `query` comes with a `path`, which is a `string` which denotes what to query. If the `path` matches a gRPC fully-qualified service method, then `BaseApp` will defer the query to the `grpcQueryRouter` and let it handle it like explained [above](#grpc-query-router). Otherwise, the `path` represents a query that is not (yet) handled by the gRPC router. `BaseApp` splits the `path` string with the `/` delimiter. By convention, the first element of the split string (`split[0]`) contains the category of `query` (`app`, `p2p`, `store` or `custom` ). The `BaseApp` implementation of the `Query(req abci.QueryRequest)` method is a simple dispatcher serving these 4 main categories of queries: * Application-related queries like querying the application's version, which are served via the `handleQueryApp` method. * Direct queries to the multistore, which are served by the `handlerQueryStore` method. These direct queries are different from custom queries which go through `app.queryRouter`, and are mainly used by third-party service provider like block explorers. diff --git a/docs/learn/advanced/01-transactions.md b/docs/learn/advanced/01-transactions.md index 8f9d4ebb3..a8b60ff09 100644 --- a/docs/learn/advanced/01-transactions.md +++ b/docs/learn/advanced/01-transactions.md @@ -33,9 +33,9 @@ It contains the following methods: * **GetMsgs:** unwraps the transaction and returns a list of contained `sdk.Msg`s - one transaction may have one or multiple messages, which are defined by module developers. * **ValidateBasic:** lightweight, [_stateless_](../beginner/01-tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./00-baseapp.md#checktx) and [`DeliverTx`](./00-baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth) module's `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. When [`runTx`](./00-baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself. - :::note - This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../beginner/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. - ::: +:::note +This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../beginner/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. +::: As a developer, you should rarely manipulate `Tx` directly, as `Tx` is really an intermediate type used for transaction generation. Instead, developers should prefer the `TxBuilder` interface, which you can learn more about [below](#transaction-generation). @@ -51,7 +51,7 @@ The most used implementation of the `Tx` interface is the Protobuf `Tx` message, https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L13-L26 ``` -Because Protobuf serialization is not deterministic, the Cosmos SDK uses an additional `TxRaw` type to denote the pinned bytes over which a transaction is signed. Any user can generate a valid `body` and `auth_info` for a transaction, and serialize these two messages using Protobuf. `TxRaw` then pins the user's exact binary representation of `body` and `auth_info`, called respectively `body_bytes` and `auth_info_bytes`. The document that is signed by all signers of the transaction is `SignDoc` (deterministically serialized using [ADR-027](../../build/architecture/adr-027-deterministic-protobuf-serialization.md)): +Because Protobuf serialization is not deterministic, the Cosmos SDK uses an additional `TxRaw` type to denote the pinned bytes over which a transaction is signed. Any user can generate a valid `body` and `auth_info` for a transaction, and serialize these two messages using Protobuf. `TxRaw` then pins the user's exact binary representation of `body` and `auth_info`, called respectively `body_bytes` and `auth_info_bytes`. The document that is signed by all signers of the transaction is `SignDoc` (deterministically serialized using [ADR-027](../../architecture/adr-027-deterministic-protobuf-serialization.md)): ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L48-L65 @@ -100,7 +100,7 @@ There are also _expert_ screens, which will only be displayed if the user has ch Data is formatted using a set of `ValueRenderer` which the SDK provides defaults for all the known messages and value types. Chain developers can also opt to implement their own `ValueRenderer` for a type/message if they'd like to display information differently. -If you wish to learn more, please refer to [ADR-050](../../build/architecture/adr-050-sign-mode-textual.md). +If you wish to learn more, please refer to [ADR-050](../../architecture/adr-050-sign-mode-textual.md). #### Custom Sign modes @@ -119,7 +119,7 @@ The next paragraphs will describe each of these components, in this order. ### Messages :::tip -Module `sdk.Msg`s are not to be confused with [ABCI Messages](https://docs.cometbft.com/v0.37/spec/abci/) which define interactions between the CometBFT and application layers. +Module `sdk.Msg`s are not to be confused with [ABCI Messages](https://docs.cometbft.com/v1.0/spec/abci/) which define interactions between the CometBFT and application layers. ::: **Messages** (or `sdk.Msg`s) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the messages for their module by adding methods to the Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md), and also implement the corresponding `MsgServer`. @@ -203,4 +203,4 @@ An example can be seen [here](https://docs.cosmos.network/main/user/run-node/txs #### CometBFT RPC -The three methods presented above are actually higher abstractions over the CometBFT RPC `/broadcast_tx_{async,sync,commit}` endpoints, documented [here](https://docs.cometbft.com/v0.37/core/rpc). This means that you can use the CometBFT RPC endpoints directly to broadcast the transaction, if you wish so. +The three methods presented above are actually higher abstractions over the CometBFT RPC `/broadcast_tx_{async,sync,commit}` endpoints, documented [here](https://docs.cometbft.com/v1.0/explanation/core/rpc). This means that you can use the CometBFT RPC endpoints directly to broadcast the transaction, if you wish so. diff --git a/docs/learn/advanced/02-context.md b/docs/learn/advanced/02-context.md index 2303f49db..73315e3de 100644 --- a/docs/learn/advanced/02-context.md +++ b/docs/learn/advanced/02-context.md @@ -25,16 +25,16 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/context.go#L41-L * **Base Context:** The base type is a Go [Context](https://pkg.go.dev/context), which is explained further in the [Go Context Package](#go-context-package) section below. * **Multistore:** Every application's `BaseApp` contains a [`CommitMultiStore`](./04-store.md#multistore) which is provided when a `Context` is created. Calling the `KVStore()` and `TransientStore()` methods allows modules to fetch their respective [`KVStore`](./04-store.md#base-layer-kvstores) using their unique `StoreKey`. -* **Header:** The [header](https://docs.cometbft.com/v0.37/spec/core/data_structures#header) is a Blockchain type. It carries important information about the state of the blockchain, such as block height and proposer of the current block. +* **Header:** The [header](https://docs.cometbft.com/v1.0/spec/core/data_structures#header) is a Blockchain type. It carries important information about the state of the blockchain, such as block height and proposer of the current block. * **Header Hash:** The current block header hash, obtained during `abci.FinalizeBlock`. * **Chain ID:** The unique identification number of the blockchain a block pertains to. * **Transaction Bytes:** The `[]byte` representation of a transaction being processed using the context. Every transaction is processed by various parts of the Cosmos SDK and consensus engine (e.g. CometBFT) throughout its [lifecycle](../beginner/01-tx-lifecycle.md), some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](https://docs.cosmos.network/main/learn/advanced/encoding) such as [Amino](https://docs.cosmos.network/main/learn/advanced/encoding). -* **Logger:** A `logger` from the CometBFT libraries. Learn more about logs [here](https://docs.cometbft.com/v0.37/core/configuration). Modules call this method to create their own unique module-specific logger. -* **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://docs.cometbft.com/v0.38/spec/abci/abci++_methods#voteinfo), which includes the name of a validator and a boolean indicating whether they have signed the block. +* **Logger:** A `logger` from the CometBFT libraries. Learn more about logs [here](https://docs.cometbft.com/v1.0/references/config/config.toml#log_level). Modules call this method to create their own unique module-specific logger. +* **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#voteinfo), which includes the name of a validator and a boolean indicating whether they have signed the block. * **Gas Meters:** Specifically, a [`gasMeter`](../beginner/04-gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../beginner/04-gas-fees.md#block-gas-meter) for the entire block it belongs to. Users specify how much in fees they wish to pay for the execution of their transaction; these gas meters keep track of how much [gas](../beginner/04-gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts. * **CheckTx Mode:** A boolean value indicating whether a transaction should be processed in `CheckTx` or `DeliverTx` mode. * **Min Gas Price:** The minimum [gas](../beginner/04-gas-fees.md) price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore **not be used in any functions used in sequences leading to state-transitions**. -* **Consensus Params:** The ABCI type [Consensus Parameters](https://docs.cometbft.com/v0.38/spec/abci/abci++_methods#consensusparams), which specify certain limits for the blockchain, such as maximum gas for a block. +* **Consensus Params:** The ABCI type [Consensus Parameters](https://docs.cometbft.com/v1.0/spec/abci/abci++_app_requirements#consensus-parameters), which specify certain limits for the blockchain, such as maximum gas for a block. * **Event Manager:** The event manager allows any caller with access to a `Context` to emit [`Events`](./08-events.md). Modules may define module specific `Events` by defining various `Types` and `Attributes` or use the common definitions found in `types/`. Clients can subscribe or query for these `Events`. These `Events` are collected throughout `FinalizeBlock` and are returned to CometBFT for indexing. * **Priority:** The transaction priority, only relevant in `CheckTx`. diff --git a/docs/learn/advanced/03-node.md b/docs/learn/advanced/03-node.md index 0de51434d..b4a4236a0 100644 --- a/docs/learn/advanced/03-node.md +++ b/docs/learn/advanced/03-node.md @@ -81,7 +81,7 @@ Then, the instance of `app` is used to instantiate a new CometBFT node: https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/start.go#L341-L378 ``` -The CometBFT node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://github.com/cometbft/cometbft/blob/v0.37.0/abci/types/application.go#L9-L35) (given that `app` extends [`baseapp`](./00-baseapp.md)). As part of the `node.New` method, CometBFT makes sure that the height of the application (i.e. number of blocks since genesis) is equal to the height of the CometBFT node. The difference between these two heights should always be negative or null. If it is strictly negative, `node.New` will replay blocks until the height of the application reaches the height of the CometBFT node. Finally, if the height of the application is `0`, the CometBFT node will call [`InitChain`](./00-baseapp.md#initchain) on the application to initialize the state from the genesis file. +The CometBFT node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://pkg.go.dev/github.com/cometbft/cometbft/abci/types#Application) (given that `app` extends [`baseapp`](./00-baseapp.md)). As part of the `node.New` method, CometBFT makes sure that the height of the application (i.e. number of blocks since genesis) is equal to the height of the CometBFT node. The difference between these two heights should always be negative or null. If it is strictly negative, `node.New` will replay blocks until the height of the application reaches the height of the CometBFT node. Finally, if the height of the application is `0`, the CometBFT node will call [`InitChain`](./00-baseapp.md#initchain) on the application to initialize the state from the genesis file. Once the CometBFT node is instantiated and in sync with the application, the node can be started: diff --git a/docs/learn/advanced/04-store.md b/docs/learn/advanced/04-store.md index 570281f60..3a9b11476 100644 --- a/docs/learn/advanced/04-store.md +++ b/docs/learn/advanced/04-store.md @@ -18,44 +18,17 @@ A store is a data structure that holds the state of the application. The Cosmos SDK comes with a large set of stores to persist the state of applications. By default, the main store of Cosmos SDK applications is a `multistore`, i.e. a store of stores. Developers can add any number of key-value stores to the multistore, depending on their application needs. The multistore exists to support the modularity of the Cosmos SDK, as it lets each module declare and manage their own subset of the state. Key-value stores in the multistore can only be accessed with a specific capability `key`, which is typically held in the [`keeper`](../../build/building-modules/06-keeper.md) of the module that declared the store. -```text -+-----------------------------------------------------+ -| | -| +--------------------------------------------+ | -| | | | -| | KVStore 1 - Manage by keeper of Module 1 | -| | | | -| +--------------------------------------------+ | -| | -| +--------------------------------------------+ | -| | | | -| | KVStore 2 - Manage by keeper of Module 2 | | -| | | | -| +--------------------------------------------+ | -| | -| +--------------------------------------------+ | -| | | | -| | KVStore 3 - Manage by keeper of Module 2 | | -| | | | -| +--------------------------------------------+ | -| | -| +--------------------------------------------+ | -| | | | -| | KVStore 4 - Manage by keeper of Module 3 | | -| | | | -| +--------------------------------------------+ | -| | -| +--------------------------------------------+ | -| | | | -| | KVStore 5 - Manage by keeper of Module 4 | | -| | | | -| +--------------------------------------------+ | -| | -| Main Multistore | -| | -+-----------------------------------------------------+ - - Application's State +```mermaid +flowchart TB + subgraph MainMultistore["Main Multistore"] + KVStore1["KVStore 1 - Managed by keeper of Module 1"] + KVStore2["KVStore 2 - Managed by keeper of Module 2"] + KVStore3["KVStore 3 - Managed by keeper of Module 2"] + KVStore4["KVStore 4 - Managed by keeper of Module 3"] + KVStore5["KVStore 5 - Managed by keeper of Module 4"] + end + + MainMultistore --> ApplicationState["Application's State"] ``` ### Store Interface diff --git a/docs/learn/advanced/05-encoding.md b/docs/learn/advanced/05-encoding.md index b4d9bc2c6..8e2ed85d5 100644 --- a/docs/learn/advanced/05-encoding.md +++ b/docs/learn/advanced/05-encoding.md @@ -59,7 +59,7 @@ Modules are encouraged to utilize Protobuf encoding for their respective types. In addition to [following official Protocol Buffer guidelines](https://developers.google.com/protocol-buffers/docs/proto3#simple), we recommend using these annotations in .proto files when dealing with interfaces: -* use `cosmos_proto.accepts_interface` to annote `Any` fields that accept interfaces +* use `cosmos_proto.accepts_interface` to annotate `Any` fields that accept interfaces * pass the same fully qualified name as `protoName` to `InterfaceRegistry.RegisterInterface` * example: `(cosmos_proto.accepts_interface) = "cosmos.gov.v1beta1.Content"` (and not just `Content`) * annotate interface implementations with `cosmos_proto.implements_interface` @@ -93,7 +93,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/decoder.go https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/encoder.go ``` -See [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. +See [ADR-020](../../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. ### Interface Encoding and Usage of `Any` @@ -114,7 +114,7 @@ In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, t https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/account.go#L15-L32 ``` -In [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: +In [ADR-019](../../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: ```protobuf message Profile { @@ -183,7 +183,7 @@ func (p *Profile) UnpackInterfaces(unpacker codectypes.AnyUnpacker) error { The `UnpackInterfaces` gets called recursively on all structs implementing this method, to allow all `Any`s to have their `GetCachedValue()` correctly populated. -For more information about interface encoding, and especially on `UnpackInterfaces` and how the `Any`'s `type_url` gets resolved using the `InterfaceRegistry`, please refer to [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md). +For more information about interface encoding, and especially on `UnpackInterfaces` and how the `Any`'s `type_url` gets resolved using the `InterfaceRegistry`, please refer to [ADR-019](../../architecture/adr-019-protobuf-state-encoding.md). #### `Any` Encoding in the Cosmos SDK @@ -248,7 +248,7 @@ Protobuf types can be defined to encode: #### Naming and conventions We encourage developers to follow industry guidelines: [Protocol Buffers style guide](https://developers.google.com/protocol-buffers/docs/style) -and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../../build/architecture/adr-023-protobuf-naming.md) +and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../../architecture/adr-023-protobuf-naming.md) ### How to update modules to protobuf encoding diff --git a/docs/learn/advanced/06-grpc_rest.md b/docs/learn/advanced/06-grpc_rest.md index 180e57792..a46f0e0a9 100644 --- a/docs/learn/advanced/06-grpc_rest.md +++ b/docs/learn/advanced/06-grpc_rest.md @@ -17,7 +17,7 @@ Each node exposes the following endpoints for users to interact with a node, eac * the CometBFT RPC endpoint (default port: `26657`). :::tip -The node also exposes some other endpoints, such as the CometBFT P2P endpoint, or the [Prometheus endpoint](https://docs.cometbft.com/v0.37/core/metrics), which are not directly related to the Cosmos SDK. Please refer to the [CometBFT documentation](https://docs.cometbft.com/v0.37/core/configuration) for more information about these endpoints. +The node also exposes some other endpoints, such as the CometBFT P2P endpoint, or the [Prometheus endpoint](https://docs.cometbft.com/v1.0/explanation/core/metrics), which are not directly related to the Cosmos SDK. Please refer to the [CometBFT Configuration Manual](https://docs.cometbft.com/v1.0/references/config/) for more information about how to configure these CometBFT endpoints. ::: :::note @@ -82,7 +82,7 @@ The Cosmos SDK's [Swagger generation script](https://github.com/cosmos/cosmos-sd ## CometBFT RPC -Independently from the Cosmos SDK, CometBFT also exposes a RPC server. This RPC server can be configured by tuning parameters under the `rpc` table in the `~/.simapp/config/config.toml`, the default listening address is `tcp://localhost:26657`. An OpenAPI specification of all CometBFT RPC endpoints is available [here](https://docs.cometbft.com/main/rpc/). +Independently from the Cosmos SDK, CometBFT also exposes a RPC server. This RPC server can be configured by tuning parameters under the `rpc` table in the `~/.simapp/config/config.toml`, the default listening address is `tcp://localhost:26657`. An OpenAPI specification of all CometBFT RPC endpoints is available [here](https://docs.cometbft.com/v1.0/rpc/). Some CometBFT RPC endpoints are directly related to the Cosmos SDK: diff --git a/docs/learn/advanced/08-events.md b/docs/learn/advanced/08-events.md index 56cc18879..0c5772e32 100644 --- a/docs/learn/advanced/08-events.md +++ b/docs/learn/advanced/08-events.md @@ -4,13 +4,13 @@ sidebar_position: 1 # Events :::note Synopsis -`Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. +`Events` are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. ::: :::note Pre-requisite Readings * [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) -* [CometBFT Documentation on Events](https://docs.cometbft.com/v0.37/spec/abci/abci++_basic_concepts#events) +* [CometBFT Documentation on Events](https://docs.cometbft.com/v1.0/spec/abci/abci++_basic_concepts#events) ::: @@ -33,7 +33,7 @@ An Event contains: To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value. ::: -_Typed Events_ are Protobuf-defined [messages](../../build/architecture/adr-032-typed-events.md) used by the Cosmos SDK +_Typed Events_ are Protobuf-defined [messages](../../architecture/adr-032-typed-events.md) used by the Cosmos SDK for emitting and querying Events. They are defined in a `event.proto` file, on a **per-module basis** and are read as `proto.Message`. _Legacy Events_ are defined on a **per-module basis** in the module's `/types/events.go` file. They are triggered from the module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) @@ -103,7 +103,7 @@ view on how to typically implement Events and use the `EventManager` in modules. ## Subscribing to Events -You can use CometBFT's [Websocket](https://docs.cometbft.com/v0.37/core/subscription) to subscribe to Events by calling the `subscribe` RPC method: +You can use CometBFT's [Websocket](https://docs.cometbft.com/v1.0/explanation/core/subscription) to subscribe to Events by calling the `subscribe` RPC method: ```json { diff --git a/docs/learn/advanced/11-runtx_middleware.md b/docs/learn/advanced/11-runtx_middleware.md index a454ee382..975877e26 100644 --- a/docs/learn/advanced/11-runtx_middleware.md +++ b/docs/learn/advanced/11-runtx_middleware.md @@ -8,7 +8,7 @@ sidebar_position: 1 Depending on the panic type different handler is used, for instance the default one prints an error log message. Recovery middleware is used to add custom panic recovery for Cosmos SDK application developers. -More context can found in the corresponding [ADR-022](../../build/architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go). +More context can found in the corresponding [ADR-022](../../architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go). ## Interface diff --git a/docs/learn/advanced/15-upgrade.md b/docs/learn/advanced/15-upgrade.md index 5d56f2b59..55cd8b052 100644 --- a/docs/learn/advanced/15-upgrade.md +++ b/docs/learn/advanced/15-upgrade.md @@ -103,7 +103,7 @@ if upgradeInfo.Name == "my-plan" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo. When starting a new chain, the consensus version of each module MUST be saved to state during the application's genesis. To save the consensus version, add the following line to the `InitChainer` method in `app.go`: ```diff -func (app *MyApp) InitChainer(ctx sdk.Context, req abci.RequestInitChain) abci.ResponseInitChain { +func (app *MyApp) InitChainer(ctx sdk.Context, req abci.InitChainRequest) abci.InitChainResponse { ... + app.UpgradeKeeper.SetModuleVersionMap(ctx, app.mm.GetVersionMap()) ... diff --git a/docs/learn/advanced/16-config.md b/docs/learn/advanced/16-config.md index 03aa55a21..954c36abb 100644 --- a/docs/learn/advanced/16-config.md +++ b/docs/learn/advanced/16-config.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Configuration -This documentation refers to the app.toml, if you'd like to read about the config.toml please visit [CometBFT docs](https://docs.cometbft.com/v0.37/). +This documentation refers to the `app.toml`, if you'd like to learn more about CometBFT configuration (`config.toml`) please visit the [CometBFT Configuration Manual](https://docs.cometbft.com/v1.0/references/config/). ```python reference diff --git a/docs/learn/advanced/17-autocli.md b/docs/learn/advanced/17-autocli.md index 895f0a1c5..50d1684c2 100644 --- a/docs/learn/advanced/17-autocli.md +++ b/docs/learn/advanced/17-autocli.md @@ -114,7 +114,7 @@ err := autoCliOpts.EnhanceRootCommand(rootCmd) ## Signing `autocli` supports signing transactions with the keyring. -The [`cosmos.msg.v1.signer` protobuf annotation](https://github.com/cosmos/cosmos-sdk/blob/9dd34510e27376005e7e7ff3628eab9dbc8ad6dc/docs/build/building-modules/05-protobuf-annotations.md#L9) defines the signer field of the message. +The [`cosmos.msg.v1.signer` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) defines the signer field of the message. This field is automatically filled when using the `--from` flag or defining the signer as a positional argument. :::warning @@ -199,6 +199,19 @@ https://github.com/cosmos/cosmos-sdk/blob/fa4d87ef7e6d87aaccc94c337ffd2fe90fcb7a If not set to true, `AutoCLI` will not generate commands for the module if there are already commands registered for the module (when `GetTxCmd()` or `GetQueryCmd()` are defined). +### Skip a command + +AutoCLI automatically skips unsupported commands when [`cosmos_proto.method_added_in` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) is present. + +Additionally, a command can be manually skipped using the `autocliv1.RpcCommandOptions`: + +```go +*autocliv1.RpcCommandOptions{ + RpcMethod: "Params", // The name of the gRPC service + Skip: true, +} +``` + ### Use AutoCLI for non module commands It is possible to use `AutoCLI` for non module commands. The trick is still to implement the `appmodule.Module` interface and append it to the `appOptions.ModuleOptions` map. @@ -220,14 +233,16 @@ For more information on `hubl`, including how to configure a new chain and query # Off-Chain Off-chain functionalities allow you to sign and verify files with two commands: -+ `sign-file` for signing a file. -+ `verify-file` for verifying a previously signed file. + +* `sign-file` for signing a file. +* `verify-file` for verifying a previously signed file. Signing a file will result in a Tx with a `MsgSignArbitraryData` as described in the [Off-chain CIP](https://github.com/cosmos/cips/blob/main/cips/cip-X.md). ## Sign a file To sign a file `sign-file` command offers some helpful flags: + ```text --encoding string Choose an encoding method for the file content to be added as msg data (no-encoding|base64|hex) (default "no-encoding") --indent string Choose an indent for the tx (default " ") @@ -237,8 +252,10 @@ To sign a file `sign-file` command offers some helpful flags: ``` The `encoding` flag lets you choose how the contents of the file should be encoded. For example: -+ `simd off-chain sign-file alice myFile.json` - + ```json + +* `simd off-chain sign-file alice myFile.json` + + * ```json { "@type": "/offchain.MsgSignArbitraryData", "appDomain": "simd", @@ -246,8 +263,10 @@ The `encoding` flag lets you choose how the contents of the file should be encod "data": "Hello World!\n" } ``` -+ `simd off-chain sign-file alice myFile.json --encoding base64` - + ```json + +* `simd off-chain sign-file alice myFile.json --encoding base64` + + * ```json { "@type": "/offchain.MsgSignArbitraryData", "appDomain": "simd", @@ -255,8 +274,10 @@ The `encoding` flag lets you choose how the contents of the file should be encod "data": "SGVsbG8gV29ybGQhCg==" } ``` -+ `simd off-chain sign-file alice myFile.json --encoding hex` - + ```json + +* `simd off-chain sign-file alice myFile.json --encoding hex` + + * ```json { "@type": "/offchain.MsgSignArbitraryData", "appDomain": "simd", diff --git a/docs/learn/beginner/00-app-anatomy.md b/docs/learn/beginner/00-app-anatomy.md index 15e055ff4..ce1479547 100644 --- a/docs/learn/beginner/00-app-anatomy.md +++ b/docs/learn/beginner/00-app-anatomy.md @@ -50,7 +50,7 @@ In general, the core of the state-machine is defined in a file called `app.go`. The first thing defined in `app.go` is the `type` of the application. It is generally comprised of the following parts: -* **A reference to [`baseapp`](../advanced/00-baseapp.md).** The custom application defined in `app.go` is an extension of `baseapp`. When a transaction is relayed by CometBFT to the application, `app` uses `baseapp`'s methods to route them to the appropriate module. `baseapp` implements most of the core logic for the application, including all the [ABCI methods](https://docs.cometbft.com/v0.37/spec/abci/) and the [routing logic](../advanced/00-baseapp.md#routing). +* **A reference to [`baseapp`](../advanced/00-baseapp.md).** The custom application defined in `app.go` is an extension of `baseapp`. When a transaction is relayed by CometBFT to the application, `app` uses `baseapp`'s methods to route them to the appropriate module. `baseapp` implements most of the core logic for the application, including all the [ABCI methods](https://docs.cometbft.com/v1.0/spec/abci/) and the [routing logic](../advanced/00-baseapp.md#routing). * **A list of store keys**. The [store](../advanced/04-store.md), which contains the entire state, is implemented as a [`multistore`](../advanced/04-store.md#multistore) (i.e. a store of stores) in the Cosmos SDK. Each module uses one or multiple stores in the multistore to persist their part of the state. These stores can be accessed with specific keys that are declared in the `app` type. These keys, along with the `keepers`, are at the heart of the [object-capabilities model](../advanced/10-ocap.md) of the Cosmos SDK. * **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../../build/building-modules/06-keeper.md), which handles reads and writes for this module's store(s). The `keeper`'s methods of one module can be called from other modules (if authorized), which is why they are declared in the application's type and exported as interfaces to other modules so that the latter can only access the authorized functions. * **A reference to an [`appCodec`](../advanced/05-encoding.md).** The application's `appCodec` is used to serialize and deserialize data structures in order to store them, as stores can only persist `[]bytes`. The default codec is [Protocol Buffers](../advanced/05-encoding.md). @@ -146,8 +146,8 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/params/encoding Here are descriptions of what each of the four fields means: * `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces that are encoded and decoded (we also say "unpacked") using [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto). `Any` could be thought as a struct that contains a `type_url` (name of a concrete type implementing the interface) and a `value` (its encoded bytes). `InterfaceRegistry` provides a mechanism for registering interfaces and implementations that can be safely unpacked from `Any`. Each application module implements the `RegisterInterfaces` method that can be used to register the module's own interfaces and implementations. - * You can read more about `Any` in [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md). - * To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/cosmos/gogoproto). By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/cosmos/gogoproto/types) uses [global type registration](https://github.com/cosmos/gogoproto/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could register a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md). + * You can read more about `Any` in [ADR-019](../../architecture/adr-019-protobuf-state-encoding.md). + * To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/cosmos/gogoproto). By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/cosmos/gogoproto/types) uses [global type registration](https://github.com/cosmos/gogoproto/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could register a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../../architecture/adr-019-protobuf-state-encoding.md). * `Codec`: The default codec used throughout the Cosmos SDK. It is composed of a `BinaryCodec` used to encode and decode state, and a `JSONCodec` used to output data to the users (for example, in the [CLI](#cli)). By default, the SDK uses Protobuf as `Codec`. * `TxConfig`: `TxConfig` defines an interface a client can utilize to generate an application-defined concrete transaction type. Currently, the SDK handles two transaction types: `SIGN_MODE_DIRECT` (which uses Protobuf binary as over-the-wire encoding) and `SIGN_MODE_LEGACY_AMINO_JSON` (which depends on Amino). Read more about transactions [here](../advanced/01-transactions.md). * `Amino`: Some legacy parts of the Cosmos SDK still use Amino for backwards-compatibility. Each module exposes a `RegisterLegacyAmino` method to register the module's specific types within Amino. This `Amino` codec should not be used by app developers anymore, and will be removed in future releases. @@ -272,6 +272,6 @@ The following is the `go.mod` of the [Cosmos Hub](https://github.com/cosmos/gaia https://github.com/cosmos/gaia/blob/26ae7c2/go.mod#L1-L28 ``` -For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`appd`](#node-client) and [`appd`](#application-interface). +For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`Node Client`](#node-client) and [`Application Interface`](#application-interface). Here is an example of the [Cosmos Hub Makefile](https://github.com/cosmos/gaia/blob/main/Makefile). diff --git a/docs/learn/beginner/01-tx-lifecycle.md b/docs/learn/beginner/01-tx-lifecycle.md index 949add247..133f17300 100644 --- a/docs/learn/beginner/01-tx-lifecycle.md +++ b/docs/learn/beginner/01-tx-lifecycle.md @@ -55,9 +55,9 @@ The command-line is an easy way to interact with an application, but `Tx` can al ## Addition to Mempool -Each full-node (running CometBFT) that receives a `Tx` sends an [ABCI message](https://docs.cometbft.com/v0.38/spec/p2p/legacy-docs/messages/), -`CheckTx`, to the application layer to check for validity, and receives an `abci.ResponseCheckTx`. If the `Tx` passes the checks, it is held in the node's -[**Mempool**](https://docs.cometbft.com/v0.37/spec/p2p/legacy-docs/messages/mempool/), an in-memory pool of transactions unique to each node, pending inclusion in a block - honest nodes discard a `Tx` if it is found to be invalid. Prior to consensus, nodes continuously check incoming transactions and gossip them to their peers. +Each full-node (running CometBFT) that receives a `Tx` sends an [ABCI message](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#checktx) +`abci.CheckTxRequest` to the application layer to check for validity, and receives an `abci.CheckTxResponse`. If the `Tx` passes the checks, it is held in the node's +[**Mempool**](https://docs.cometbft.com/v1.0/explanation/core/mempool/), an in-memory pool of transactions unique to each node, pending inclusion in a block - honest nodes discard a `Tx` if it is found to be invalid. Prior to consensus, nodes continuously check incoming transactions and gossip them to their peers. ### Types of Checks @@ -149,7 +149,7 @@ Consensus, the process through which validator nodes come to agreement on which accept, happens in **rounds**. Each round begins with a proposer creating a block of the most recent transactions and ends with **validators**, special full-nodes with voting power responsible for consensus, agreeing to accept the block or go with a `nil` block instead. Validator nodes -execute the consensus algorithm, such as [CometBFT](https://docs.cometbft.com/v0.37/spec/consensus/), +execute the consensus algorithm adopted in [CometBFT](https://docs.cometbft.com/v1.0/spec/consensus/), confirming the transactions using ABCI requests to the application, in order to come to this agreement. The first step of consensus is the **block proposal**. One proposer amongst the validators is chosen @@ -164,45 +164,45 @@ As mentioned throughout the documentation `BeginBlock`, `ExecuteTx` and `EndBloc Although every full-node operates individually and locally, the outcome is always consistent and unequivocal. This is because the state changes brought about by the messages are predictable, and the transactions are specifically sequenced in the proposed block. ```text - -------------------------- - | Receive Block Proposal | - -------------------------- - | - v - ------------------------- - | FinalizeBlock | - ------------------------- - | - v - ------------------- - | BeginBlock | - ------------------- - | - v - -------------------- - | ExecuteTx(tx0) | - | ExecuteTx(tx1) | - | ExecuteTx(tx2) | - | ExecuteTx(tx3) | - | . | - | . | - | . | - ------------------- - | - v - -------------------- - | EndBlock | - -------------------- - | - v - ----------------------- - | Consensus | - ----------------------- - | - v - ----------------------- - | Commit | - ----------------------- + -------------------------- + | Receive Block Proposal | + -------------------------- + | + v + ------------------------- + | FinalizeBlock | + ------------------------- + | + v + ------------------- + | BeginBlock | + ------------------- + | + v + -------------------- + | ExecuteTx(tx0) | + | ExecuteTx(tx1) | + | ExecuteTx(tx2) | + | ExecuteTx(tx3) | + | . | + | . | + | . | + ------------------- + | + v + -------------------- + | EndBlock | + -------------------- + | + v + ------------------------- + | Consensus | + ------------------------- + | + v + ------------------------- + | Commit | + ------------------------- ``` ### Transaction Execution diff --git a/docs/learn/beginner/02-query-lifecycle.md b/docs/learn/beginner/02-query-lifecycle.md index 0eda8d988..4fbaf7ce4 100644 --- a/docs/learn/beginner/02-query-lifecycle.md +++ b/docs/learn/beginner/02-query-lifecycle.md @@ -122,7 +122,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/query.go#L79-L1 With a call to `ABCIQueryWithOptions()`, `MyQuery` is received by a [full-node](../advanced/05-encoding.md) which then processes the request. Note that, while the RPC is made to the consensus engine (e.g. CometBFT) of a full-node, queries are not part of consensus and so are not broadcasted to the rest of the network, as they do not require anything the network needs to agree upon. -Read more about ABCI Clients and CometBFT RPC in the [CometBFT documentation](https://docs.cometbft.com/v0.37/spec/rpc/). +Read more about ABCI Clients and CometBFT RPC in the [CometBFT documentation](https://docs.cometbft.com/v1.0/spec/rpc/). ## Application Query Handling @@ -134,7 +134,7 @@ Once a result is received from the querier, `baseapp` begins the process of retu ## Response -Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci.ResponseQuery`](https://docs.cometbft.com/v0.38/spec/abci/abci++_app_requirements#query) type. The `client.Context` `Query()` routine receives the response. +Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci.QueryResponse`](https://docs.cometbft.com/v1.0/spec/abci/abci++_app_requirements#query) type. The `client.Context` `Query()` routine receives the response. ### CLI Response diff --git a/docs/learn/beginner/03-accounts.md b/docs/learn/beginner/03-accounts.md index 12f929c88..5dccbf2f7 100644 --- a/docs/learn/beginner/03-accounts.md +++ b/docs/learn/beginner/03-accounts.md @@ -152,7 +152,7 @@ The default implementation of `Keyring` comes from the third-party [`99designs/k A few notes on the `Keyring` methods: -* `Sign(uid string, msg []byte) ([]byte, types.PubKey, error)` strictly deals with the signature of the `msg` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../../build/architecture/adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../advanced/00-baseapp.md#antehandler). +* `Sign(uid string, msg []byte) ([]byte, types.PubKey, error)` strictly deals with the signature of the `msg` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../../architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../../architecture/adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../advanced/00-baseapp.md#antehandler). ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L50-L66 diff --git a/docs/learn/beginner/04-gas-fees.md b/docs/learn/beginner/04-gas-fees.md index eb429b610..086523b5a 100644 --- a/docs/learn/beginner/04-gas-fees.md +++ b/docs/learn/beginner/04-gas-fees.md @@ -56,21 +56,25 @@ Gas consumption can be done manually, generally by the module developer in the [ ### Block Gas Meter -`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. By default, Cosmos SDK applications use the default consensus parameters provided by CometBFT: +`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. -```go reference -https://github.com/cometbft/cometbft/blob/v0.37.0/types/params.go#L66-L105 +During the genesis phase, gas consumption is unlimited to accommodate initialisation transactions. + +```go +app.finalizeBlockState.SetContext(app.finalizeBlockState.Context().WithBlockGasMeter(storetypes.NewInfiniteGasMeter())) ``` -When a new [transaction](../advanced/01-transactions.md) is being processed via `FinalizeBlock`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, the transaction fails and returned to the consensus engine as a failed transaction. This can happen even with the first transaction in a block, as `FinalizeBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `FinalizeBlock`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction: +Following the genesis block, the block gas meter is set to a finite value by the SDK. This transition is facilitated by the consensus engine (e.g., CometBFT) calling the `RequestFinalizeBlock` function, which in turn triggers the SDK's `FinalizeBlock` method. Within `FinalizeBlock`, `internalFinalizeBlock` is executed, performing necessary state updates and function executions. The block gas meter, initialised each with a finite limit, is then incorporated into the context for transaction execution, ensuring gas consumption does not exceed the block's gas limit and is reset at the end of each block. + +Modules within the Cosmos SDK can consume block gas at any point during their execution by utilising the `ctx`. This gas consumption primarily occurs during state read/write operations and transaction processing. The block gas meter, accessible via `ctx.BlockGasMeter()`, monitors the total gas usage within a block, enforcing the gas limit to prevent excessive computation. This ensures that gas limits are adhered to on a per-block basis, starting from the first block post-genesis. ```go -ctx.BlockGasMeter().ConsumeGas( - ctx.GasMeter().GasConsumedToLimit(), - "block gas meter", -) +gasMeter := app.getBlockGasMeter(app.finalizeBlockState.Context()) +app.finalizeBlockState.SetContext(app.finalizeBlockState.Context().WithBlockGasMeter(gasMeter)) ``` +This above shows the general mechanism for setting the block gas meter with a finite limit based on the block's consensus parameters. + ## AnteHandler The `AnteHandler` is run for every transaction during `CheckTx` and `FinalizeBlock`, before a Protobuf `Msg` service method for each `sdk.Msg` in the transaction. diff --git a/docs/learn/intro/01-why-app-specific.md b/docs/learn/intro/01-why-app-specific.md index 0f0c1c64e..53042aade 100644 --- a/docs/learn/intro/01-why-app-specific.md +++ b/docs/learn/intro/01-why-app-specific.md @@ -46,7 +46,7 @@ Application-Specific Blockchains are designed to address these shortcomings. Application-specific blockchains give maximum flexibility to developers: -* In Cosmos blockchains, the state-machine is typically connected to the underlying consensus engine via an interface called the [ABCI](https://docs.cometbft.com/v0.37/spec/abci/). This interface can be wrapped in any programming language, meaning developers can build their state-machine in the programming language of their choice. +* In Cosmos blockchains, the state-machine is typically connected to the underlying consensus engine via an interface called the [ABCI](https://docs.cometbft.com/v1.0/spec/abci/) (Application Blockchain Interface). This interface can be wrapped in any programming language, meaning developers can build their state-machine in the programming language of their choice. * Developers can choose among multiple frameworks to build their state-machine. The most widely used today is the Cosmos SDK, but others exist (e.g. [Lotion](https://github.com/nomic-io/lotion), [Weave](https://github.com/iov-one/weave), ...). Typically the choice will be made based on the programming language they want to use (Cosmos SDK and Weave are in Golang, Lotion is in Javascript, ...). * The ABCI also allows developers to swap the consensus engine of their application-specific blockchain. Today, only CometBFT is production-ready, but in the future other consensus engines are expected to emerge. diff --git a/docs/learn/intro/02-sdk-app-architecture.md b/docs/learn/intro/02-sdk-app-architecture.md index c2ff7bbf6..1dcd54a78 100644 --- a/docs/learn/intro/02-sdk-app-architecture.md +++ b/docs/learn/intro/02-sdk-app-architecture.md @@ -36,7 +36,7 @@ The Cosmos SDK gives developers maximum flexibility to define the state of their ## CometBFT -Thanks to the Cosmos SDK, developers just have to define the state machine, and [*CometBFT*](https://docs.cometbft.com/v0.37/introduction/what-is-cometbft) will handle replication over the network for them. +Thanks to the Cosmos SDK, developers just have to define the state machine, and [*CometBFT*](https://docs.cometbft.com/v1.0/explanation/introduction/) will handle replication over the network for them. ```text ^ +-------------------------------+ ^ @@ -54,13 +54,13 @@ Blockchain node | | Consensus | | v +-------------------------------+ v ``` -[CometBFT](https://docs.cometbft.com/v0.37/introduction/what-is-cometbft) is an application-agnostic engine that is responsible for handling the *networking* and *consensus* layers of a blockchain. In practice, this means that CometBFT is responsible for propagating and ordering transaction bytes. CometBFT relies on an eponymous Byzantine-Fault-Tolerant (BFT) algorithm to reach consensus on the order of transactions. +[CometBFT](https://docs.cometbft.com/v1.0/explanation/introduction/) is an application-agnostic engine that is responsible for handling the *networking* and *consensus* layers of a blockchain. In practice, this means that CometBFT is responsible for propagating and ordering transaction bytes. CometBFT relies on an eponymous Byzantine-Fault-Tolerant (BFT) algorithm to reach consensus on the order of transactions. -The CometBFT [consensus algorithm](https://docs.cometbft.com/v0.37/introduction/what-is-cometbft#consensus-overview) works with a set of special nodes called *Validators*. Validators are responsible for adding blocks of transactions to the blockchain. At any given block, there is a validator set V. A validator in V is chosen by the algorithm to be the proposer of the next block. This block is considered valid if more than two thirds of V signed a `prevote` and a `precommit` on it, and if all the transactions that it contains are valid. The validator set can be changed by rules written in the state-machine. +The [consensus algorithm adopted by CometBFT](https://docs.cometbft.com/v1.0/explanation/introduction/#consensus-overview) works with a set of special nodes called *Validators*. Validators are responsible for adding blocks of transactions to the blockchain. At any given block, there is a validator set V. A validator in V is chosen by the algorithm to be the proposer of the next block. This block is considered valid if more than two thirds of V signed a `prevote` and a `precommit` on it, and if all the transactions that it contains are valid. The validator set can be changed by rules written in the state-machine. ## ABCI -CometBFT passes transactions to the application through an interface called the [ABCI](https://docs.cometbft.com/v0.37/spec/abci/), which the application must implement. +CometBFT passes transactions to the application through an interface called the [ABCI](https://docs.cometbft.com/v1.0/spec/abci/), which the application must implement. ```text +---------------------+ @@ -84,10 +84,10 @@ Note that **CometBFT only handles transaction bytes**. It has no knowledge of wh Here are the most important messages of the ABCI: -* `CheckTx`: When a transaction is received by CometBFT, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`](../beginner/04-gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.cometbft.com/v0.37/spec/p2p/legacy-docs/messages/mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. -* `DeliverTx`: When a [valid block](https://docs.cometbft.com/v0.37/spec/core/data_structures#block) is received by CometBFT, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../../build/building-modules/03-msg-services.md) RPC for each message in the transaction. +* `CheckTx`: When a transaction is received by CometBFT, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`](../beginner/04-gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.cometbft.com/v1.0/explanation/core/mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. +* `DeliverTx`: When a [valid block](https://docs.cometbft.com/v1.0/spec/core/data_structures#block) is received by CometBFT, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../../build/building-modules/03-msg-services.md) RPC for each message in the transaction. * `BeginBlock`/`EndBlock`: These messages are executed at the beginning and the end of each block, whether the block contains transactions or not. It is useful to trigger automatic execution of logic. Proceed with caution though, as computationally expensive loops could slow down your blockchain, or even freeze it if the loop is infinite. -Find a more detailed view of the ABCI methods from the [CometBFT docs](https://docs.cometbft.com/v0.37/spec/abci/). +Find a more detailed view of the ABCI methods from the [CometBFT docs](https://docs.cometbft.com/v1.0/spec/abci/). Any application built on CometBFT needs to implement the ABCI interface in order to communicate with the underlying local CometBFT engine. Fortunately, you do not have to implement the ABCI interface. The Cosmos SDK provides a boilerplate implementation of it in the form of [baseapp](./03-sdk-design.md#baseapp). diff --git a/docs/learn/learn.md b/docs/learn/learn.md index af624fa30..b8f64821a 100644 --- a/docs/learn/learn.md +++ b/docs/learn/learn.md @@ -8,4 +8,4 @@ laying the groundwork for understanding blockchain development. In this section * [Beginner](./beginner/00-app-anatomy.md) - Start your journey with beginner-friendly resources in the Cosmos SDK's "Learn" section, providing a gentle entry point for newcomers to blockchain development. Here we focus on a little more detail, covering the Anatomy of a Cosmos SDK Application, Transaction Lifecycles, Accounts and lastly, Gas and Fees. * [Advanced](./advanced/00-baseapp.md) - Level up your Cosmos SDK expertise with advanced topics, tailored for experienced -developers diving into intricate blockchain application development. We cover the Cosmos SDK on a lower level as we dive into the core of the SDK with BaseApp, Transactions, Context, Node Client (Daemon), Store, Encoding, gRPC, REST, and CometBFT Endpoints, CLI, Events, Telementry, Object-Capability Model, RunTx recovery middleware, Cosmos Blockchain Simulator, Protobuf Documentation, In-Place Store Migrations, Configuration and AutoCLI. +developers diving into intricate blockchain application development. We cover the Cosmos SDK on a lower level as we dive into the core of the SDK with BaseApp, Transactions, Context, Node Client (Daemon), Store, Encoding, gRPC, REST, and CometBFT Endpoints, CLI, Events, Telemetry, Object-Capability Model, RunTx recovery middleware, Cosmos Blockchain Simulator, Protobuf Documentation, In-Place Store Migrations, Configuration and AutoCLI. diff --git a/docs/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md b/docs/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md index f14541925..a68a6e159 100644 --- a/docs/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md +++ b/docs/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md @@ -2,10 +2,12 @@ ## Table of Contents -* [Getting Started](#overview-of-the-project) -* [Understanding Front-Running](01-understanding-front-running) -* [Mitigating Front-running with Vote Extensions](02-mitigating-front-running-with-vote-extensions) -* [Demo of Mitigating Front-Running](03-demo-of-mitigating-front-running) +- [Getting Started](#overview-of-the-project) +- [Understanding Front-Running](./01-understanding-frontrunning.md) +- [Mitigating Front-running with Vote Extensions](./02-mitigating-front-running-with-vote-extesions.md) +- [Demo of Mitigating Front-Running](./03-demo-of-mitigating-front-running.md) + +## Getting Started ### Overview of the Project diff --git a/openapi/swagger.yaml b/openapi/swagger.yaml index 173676b0b..a3b70bb65 100644 --- a/openapi/swagger.yaml +++ b/openapi/swagger.yaml @@ -29488,7 +29488,7 @@ paths: - Query /cosmos/feegrant/v1beta1/allowance/{granter}/{grantee}: get: - summary: Allowance returns granted allwance to the grantee by the granter. + summary: Allowance returns granted allowance to the grantee by the granter. operationId: Allowance responses: '200': @@ -58575,7 +58575,7 @@ definitions: gas to be used by the transaction. The ratio yields an effective "gasprice", - which must be above some miminum to be accepted into the mempool. + which must be above some minimum to be accepted into the mempool. cosmos.tx.v1beta1.GetBlockWithTxsResponse: type: object properties: diff --git a/versioned_docs/version-0.50/build/building-apps/03-app-upgrade.md b/versioned_docs/version-0.50/build/building-apps/03-app-upgrade.md index d5a88c5d7..ebaddb3f7 100644 --- a/versioned_docs/version-0.50/build/building-apps/03-app-upgrade.md +++ b/versioned_docs/version-0.50/build/building-apps/03-app-upgrade.md @@ -52,9 +52,9 @@ be a matter of minutes and not even require them to be awake at that time. ## Integrating With An App -::tip +:::tip The following is not required for users using `depinject` / app v2, 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 keeper's PreBlocker method: diff --git a/versioned_docs/version-0.50/build/building-modules/05-protobuf-annotations.md b/versioned_docs/version-0.50/build/building-modules/05-protobuf-annotations.md index 3621e1048..5240112e9 100644 --- a/versioned_docs/version-0.50/build/building-modules/05-protobuf-annotations.md +++ b/versioned_docs/version-0.50/build/building-modules/05-protobuf-annotations.md @@ -52,7 +52,7 @@ Example of Int scalar: https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/proto/cosmos/gov/v1/gov.proto#L137 ``` -There are a few options for what can be provided as a scalar: cosmos.AddressString, cosmos.ValidatorAddressString, cosmos.ConsensusAddressString, cosmos.Int, cosmos.Dec. +There are a few options for what can be provided as a scalar: `cosmos.AddressString`, `cosmos.ValidatorAddressString`, `cosmos.ConsensusAddressString`, `cosmos.Int`, `cosmos.Dec`. ## Implements_Interface @@ -62,9 +62,21 @@ Implement interface is used to provide information to client tooling like [teles option (cosmos_proto.implements_interface) = "cosmos.auth.v1beta1.AccountI"; ``` +## Method,Field,Message Added In + +`method_added_in`, `field_added_in` and `message_added_in` are annotations to denotate to clients that a field has been supported in a later version. This is useful when new methods or fields are added in later versions and that the client needs to be aware of what it can call. + +The annotation should be worded as follow: + +```proto +option (cosmos_proto.method_added_in) = "cosmos-sdk v0.50.1"; +option (cosmos_proto.method_added_in) = "x/epochs v1.0.0"; +option (cosmos_proto.method_added_in) = "simapp v24.0.0"; +``` + ## Amino -The amino codec was removed in 0.50.0, this means there is not a need register `legacyAminoCodec`. To replace the amino codec, Amino protobuf annotations are used to provide information to the amino codec on how to encode and decode protobuf messages. +The amino codec was removed in `v0.50+`, this means there is not a need register `legacyAminoCodec`. To replace the amino codec, Amino protobuf annotations are used to provide information to the amino codec on how to encode and decode protobuf messages. :::note Amino annotations are only used for backwards compatibility with amino. New modules are not required use amino annotations. diff --git a/versioned_docs/version-0.50/learn/advanced/01-transactions.md b/versioned_docs/version-0.50/learn/advanced/01-transactions.md index c2d779a83..900d8b3fe 100644 --- a/versioned_docs/version-0.50/learn/advanced/01-transactions.md +++ b/versioned_docs/version-0.50/learn/advanced/01-transactions.md @@ -33,9 +33,9 @@ It contains the following methods: * **GetMsgs:** unwraps the transaction and returns a list of contained `sdk.Msg`s - one transaction may have one or multiple messages, which are defined by module developers. * **ValidateBasic:** lightweight, [_stateless_](../beginner/01-tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./00-baseapp.md#checktx) and [`DeliverTx`](./00-baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth) module's `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. When [`runTx`](./00-baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself. - :::note - This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../beginner/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. - ::: +:::note +This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../beginner/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. +::: As a developer, you should rarely manipulate `Tx` directly, as `Tx` is really an intermediate type used for transaction generation. Instead, developers should prefer the `TxBuilder` interface, which you can learn more about [below](#transaction-generation). diff --git a/versioned_docs/version-0.50/learn/advanced/05-encoding.md b/versioned_docs/version-0.50/learn/advanced/05-encoding.md index 0178884b2..c7da94bf9 100644 --- a/versioned_docs/version-0.50/learn/advanced/05-encoding.md +++ b/versioned_docs/version-0.50/learn/advanced/05-encoding.md @@ -93,7 +93,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/decoder.go https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/encoder.go ``` -See [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. +See [ADR-020](../../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. ### Interface Encoding and Usage of `Any` @@ -114,7 +114,7 @@ In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, t https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/account.go#L15-L32 ``` -In [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: +In [ADR-019](../../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: ```protobuf message Profile { @@ -183,7 +183,7 @@ func (p *Profile) UnpackInterfaces(unpacker codectypes.AnyUnpacker) error { The `UnpackInterfaces` gets called recursively on all structs implementing this method, to allow all `Any`s to have their `GetCachedValue()` correctly populated. -For more information about interface encoding, and especially on `UnpackInterfaces` and how the `Any`'s `type_url` gets resolved using the `InterfaceRegistry`, please refer to [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md). +For more information about interface encoding, and especially on `UnpackInterfaces` and how the `Any`'s `type_url` gets resolved using the `InterfaceRegistry`, please refer to [ADR-019](../../architecture/adr-019-protobuf-state-encoding.md). #### `Any` Encoding in the Cosmos SDK @@ -248,7 +248,7 @@ Protobuf types can be defined to encode: #### Naming and conventions We encourage developers to follow industry guidelines: [Protocol Buffers style guide](https://developers.google.com/protocol-buffers/docs/style) -and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../../build/architecture/adr-023-protobuf-naming.md) +and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../../architecture/adr-023-protobuf-naming.md) ### How to update modules to protobuf encoding diff --git a/versioned_docs/version-0.50/learn/advanced/17-autocli.md b/versioned_docs/version-0.50/learn/advanced/17-autocli.md index b61c6b2de..ea917ce20 100644 --- a/versioned_docs/version-0.50/learn/advanced/17-autocli.md +++ b/versioned_docs/version-0.50/learn/advanced/17-autocli.md @@ -114,7 +114,7 @@ err := autoCliOpts.EnhanceRootCommand(rootCmd) ## Signing `autocli` supports signing transactions with the keyring. -The [`cosmos.msg.v1.signer` protobuf annotation](https://github.com/cosmos/cosmos-sdk/blob/9dd34510e27376005e7e7ff3628eab9dbc8ad6dc/docs/build/building-modules/05-protobuf-annotations.md#L9) defines the signer field of the message. +The [`cosmos.msg.v1.signer` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) defines the signer field of the message. This field is automatically filled when using the `--from` flag or defining the signer as a positional argument. :::warning @@ -194,6 +194,19 @@ https://github.com/cosmos/cosmos-sdk/blob/fa4d87ef7e6d87aaccc94c337ffd2fe90fcb7a If not set to true, `AutoCLI` will not generate commands for the module if there are already commands registered for the module (when `GetTxCmd()` or `GetTxCmd()` are defined). +### Skip a command + +AutoCLI automatically skips unsupported commands when [`cosmos_proto.method_added_in` protobuf annotation](https://docs.cosmos.network/main/build/building-modules/protobuf-annotations) is present. + +Additionally, a command can be manually skipped using the `autocliv1.RpcCommandOptions`: + +```go +*autocliv1.RpcCommandOptions{ + RpcMethod: "Params", // The name of the gRPC service + Skip: true, +} +``` + ### Use AutoCLI for non module commands It is possible to use `AutoCLI` for non module commands. The trick is still to implement the `appmodule.Module` interface and append it to the `appOptions.ModuleOptions` map. diff --git a/versioned_docs/version-0.50/learn/beginner/00-app-anatomy.md b/versioned_docs/version-0.50/learn/beginner/00-app-anatomy.md index 0d9ae4036..07f656db2 100644 --- a/versioned_docs/version-0.50/learn/beginner/00-app-anatomy.md +++ b/versioned_docs/version-0.50/learn/beginner/00-app-anatomy.md @@ -274,6 +274,6 @@ The following is the `go.mod` of the [Cosmos Hub](https://github.com/cosmos/gaia https://github.com/cosmos/gaia/blob/26ae7c2/go.mod#L1-L28 ``` -For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`appd`](#node-client) and [`appd`](#application-interface). +For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`Node Client`](#node-client) and [`Application Interface`](#application-interface). Here is an example of the [Cosmos Hub Makefile](https://github.com/cosmos/gaia/blob/main/Makefile). diff --git a/versioned_docs/version-0.50/learn/beginner/01-tx-lifecycle.md b/versioned_docs/version-0.50/learn/beginner/01-tx-lifecycle.md index 1fddabdda..2f86f168a 100644 --- a/versioned_docs/version-0.50/learn/beginner/01-tx-lifecycle.md +++ b/versioned_docs/version-0.50/learn/beginner/01-tx-lifecycle.md @@ -164,45 +164,45 @@ As mentioned throughout the documentation `BeginBlock`, `ExecuteTx` and `EndBloc Although every full-node operates individually and locally, the outcome is always consistent and unequivocal. This is because the state changes brought about by the messages are predictable, and the transactions are specifically sequenced in the proposed block. ```text - ----------------------- - |Receive Block Proposal| - ----------------------- - | - v - ------------------------- - | FinalizeBlock | - | - v - ------------------- - | BeginBlock | - ------------------- - | - v - -------------------- - | ExecuteTx(tx0) | - | ExecuteTx(tx1) | - | ExecuteTx(tx2) | - | ExecuteTx(tx3) | - | . | - | . | - | . | - ------------------- - | - v - -------------------- - | EndBlock | - -------------------- - ------------------------- - | - v - ----------------------- - | Consensus | - ----------------------- - | - v - ----------------------- - | Commit | - ----------------------- + -------------------------- + | Receive Block Proposal | + -------------------------- + | + v + ------------------------- + | FinalizeBlock | + ------------------------- + | + v + ------------------- + | BeginBlock | + ------------------- + | + v + -------------------- + | ExecuteTx(tx0) | + | ExecuteTx(tx1) | + | ExecuteTx(tx2) | + | ExecuteTx(tx3) | + | . | + | . | + | . | + ------------------- + | + v + -------------------- + | EndBlock | + -------------------- + | + v + ------------------------- + | Consensus | + ------------------------- + | + v + ------------------------- + | Commit | + ------------------------- ``` ### Transaction Execution diff --git a/versioned_docs/version-0.50/learn/beginner/04-gas-fees.md b/versioned_docs/version-0.50/learn/beginner/04-gas-fees.md index 2e04af462..4def021ea 100644 --- a/versioned_docs/version-0.50/learn/beginner/04-gas-fees.md +++ b/versioned_docs/version-0.50/learn/beginner/04-gas-fees.md @@ -56,21 +56,25 @@ Gas consumption can be done manually, generally by the module developer in the [ ### Block Gas Meter -`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. By default, Cosmos SDK applications use the default consensus parameters provided by CometBFT: +`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. -```go reference -https://github.com/cometbft/cometbft/blob/v0.37.0/types/params.go#L66-L105 +During the genesis phase, gas consumption is unlimited to accommodate initialisation transactions. + +```go +app.finalizeBlockState.SetContext(app.finalizeBlockState.Context().WithBlockGasMeter(storetypes.NewInfiniteGasMeter())) ``` -When a new [transaction](../advanced/01-transactions.md) is being processed via `FinalizeBlock`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, the transaction fails and returned to the consensus engine as a failed transaction. This can happen even with the first transaction in a block, as `FinalizeBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `FinalizeBlock`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction: +Following the genesis block, the block gas meter is set to a finite value by the SDK. This transition is facilitated by the consensus engine (e.g., CometBFT) calling the `RequestFinalizeBlock` function, which in turn triggers the SDK's `FinalizeBlock` method. Within `FinalizeBlock`, `internalFinalizeBlock` is executed, performing necessary state updates and function executions. The block gas meter, initialised each with a finite limit, is then incorporated into the context for transaction execution, ensuring gas consumption does not exceed the block's gas limit and is reset at the end of each block. + +Modules within the Cosmos SDK can consume block gas at any point during their execution by utilising the `ctx`. This gas consumption primarily occurs during state read/write operations and transaction processing. The block gas meter, accessible via `ctx.BlockGasMeter()`, monitors the total gas usage within a block, enforcing the gas limit to prevent excessive computation. This ensures that gas limits are adhered to on a per-block basis, starting from the first block post-genesis. ```go -ctx.BlockGasMeter().ConsumeGas( - ctx.GasMeter().GasConsumedToLimit(), - "block gas meter", -) +gasMeter := app.getBlockGasMeter(app.finalizeBlockState.Context()) +app.finalizeBlockState.SetContext(app.finalizeBlockState.Context().WithBlockGasMeter(gasMeter)) ``` +This above shows the general mechanism for setting the block gas meter with a finite limit based on the block's consensus parameters. + ## AnteHandler The `AnteHandler` is run for every transaction during `CheckTx` and `FinalizeBlock`, before a Protobuf `Msg` service method for each `sdk.Msg` in the transaction.