From 9cb638a39ddbc4056bc815e4616b2259c6ae7ed8 Mon Sep 17 00:00:00 2001 From: tac0turtle <24299864+tac0turtle@users.noreply.github.com> Date: Fri, 3 May 2024 12:02:43 +0000 Subject: [PATCH] chore: Sync docs from cosmos-sdk/docs --- docs/build/abci/00-introduction.md | 4 +- docs/build/abci/03-vote-extensions.md | 12 +-- docs/build/architecture/PROCESS.md | 2 +- .../architecture/adr-034-account-rekeying.md | 2 +- docs/build/architecture/adr-043-nft-module.md | 2 +- .../architecture/adr-050-sign-mode-textual.md | 2 +- .../adr-062-collections-state-layer.md | 2 +- .../architecture/adr-063-core-module-api.md | 5 +- docs/build/architecture/adr-064-abci-2.0.md | 2 +- docs/build/building-apps/02-app-mempool.md | 2 +- .../building-modules/01-module-manager.md | 95 +++++++------------ .../05-protobuf-annotations.md | 16 +++- docs/build/migrations/02-upgrading.md | 32 ++++--- .../spec/_ics/ics-030-signed-messages.md | 2 +- .../spec/fee_distribution/f1_fee_distr.tex | 2 +- docs/build/tooling/00-protobuf.md | 2 +- docs/build/tooling/03-hubl.md | 2 +- docs/learn/advanced/00-baseapp.md | 46 ++++----- docs/learn/advanced/01-transactions.md | 8 +- docs/learn/advanced/02-context.md | 8 +- docs/learn/advanced/03-node.md | 2 +- docs/learn/advanced/05-encoding.md | 10 +- docs/learn/advanced/06-grpc_rest.md | 4 +- docs/learn/advanced/08-events.md | 6 +- docs/learn/advanced/11-runtx_middleware.md | 2 +- docs/learn/advanced/15-upgrade.md | 2 +- docs/learn/advanced/16-config.md | 2 +- docs/learn/advanced/17-autocli.md | 39 ++++++-- docs/learn/beginner/00-app-anatomy.md | 6 +- docs/learn/beginner/01-tx-lifecycle.md | 8 +- docs/learn/beginner/02-query-lifecycle.md | 4 +- docs/learn/beginner/03-accounts.md | 2 +- docs/learn/beginner/04-gas-fees.md | 20 ++-- docs/learn/intro/01-why-app-specific.md | 2 +- docs/learn/intro/02-sdk-app-architecture.md | 14 +-- .../00-getting-started.md | 10 +- openapi/swagger.yaml | 4 +- .../05-protobuf-annotations.md | 16 +++- .../learn/advanced/05-encoding.md | 8 +- .../version-0.50/learn/advanced/17-autocli.md | 15 ++- .../learn/beginner/04-gas-fees.md | 20 ++-- 41 files changed, 246 insertions(+), 198 deletions(-) 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-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-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..6909df7cd 100644 --- a/docs/build/architecture/adr-064-abci-2.0.md +++ b/docs/build/architecture/adr-064-abci-2.0.md @@ -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/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-modules/01-module-manager.md b/docs/build/building-modules/01-module-manager.md index e0ab0e54f..bce8cea7f 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.ResponseInitChain` 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/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/migrations/02-upgrading.md b/docs/build/migrations/02-upgrading.md index 6126ce607..84374275e 100644 --- a/docs/build/migrations/02-upgrading.md +++ b/docs/build/migrations/02-upgrading.md @@ -61,6 +61,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 @@ -154,35 +158,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.EnvWithRouterService(app.GRPCQueryRouter(), app.MsgServiceRouter())), 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,6 +186,16 @@ The signature of the extension interface `HasRegisterInterfaces` has been change +func (AppModule) RegisterInterfaces(registry registry.InterfaceRegistrar) { ``` +##### 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) +``` + ##### Dependency Injection Previously `cosmossdk.io/core` held functions `Invoke`, `Provide` and `Register` were moved to `cosmossdk.io/depinject/appconfig`. 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/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..3b75f4287 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. @@ -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. @@ -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,11 +516,11 @@ 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: diff --git a/docs/learn/advanced/01-transactions.md b/docs/learn/advanced/01-transactions.md index 8f9d4ebb3..849f14c23 100644 --- a/docs/learn/advanced/01-transactions.md +++ b/docs/learn/advanced/01-transactions.md @@ -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/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..2b8d754ac 100644 --- a/docs/learn/advanced/08-events.md +++ b/docs/learn/advanced/08-events.md @@ -10,7 +10,7 @@ sidebar_position: 1 :::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..1414bae25 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. diff --git a/docs/learn/beginner/01-tx-lifecycle.md b/docs/learn/beginner/01-tx-lifecycle.md index 949add247..f3813a4c0 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 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/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-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/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/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.