diff --git a/docs/build/abci/03-vote-extensions.md b/docs/build/abci/03-vote-extensions.md index a57395e30..f3744660a 100644 --- a/docs/build/abci/03-vote-extensions.md +++ b/docs/build/abci/03-vote-extensions.md @@ -11,7 +11,7 @@ ABCI 2.0 (colloquially called ABCI++) allows an application to extend a pre-comm validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/abci.go#L32): ```go -type ExtendVoteHandler func(Context, *abci.ExtendVoteRequest) (*abci.ExtendVoteResponse, error) +type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) ``` An application can set this handler in `app.go` via the `baseapp.SetExtendVoteHandler` @@ -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.VerifyVoteExtensionRequest) (*abci.VerifyVoteExtensionResponse, error) +type VerifyVoteExtensionHandler func(Context, *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error) ``` An application can set this handler in `app.go` via the `baseapp.SetVerifyVoteExtensionHandler` @@ -78,7 +78,7 @@ will be available to the application during the subsequent `FinalizeBlock` call. An example of how a pre-FinalizeBlock hook could look like is shown below: ```go -app.SetPreBlocker(func(ctx sdk.Context, req *abci.FinalizeBlockRequest) error { +app.SetPreBlocker(func(ctx sdk.Context, req *abci.RequestFinalizeBlock) error { allVEs := []VE{} // store all parsed vote extensions here for _, tx := range req.Txs { // define a custom function that tries to parse the tx as a vote extension diff --git a/docs/build/architecture/adr-030-authz-module.md b/docs/build/architecture/adr-030-authz-module.md index e8b64f184..3eadaf314 100644 --- a/docs/build/architecture/adr-030-authz-module.md +++ b/docs/build/architecture/adr-030-authz-module.md @@ -25,7 +25,7 @@ The concrete use cases which motivated this module include: delegated stake * "sub-keys" functionality, as originally proposed in [\#4480](https://github.com/cosmos/cosmos-sdk/issues/4480) which is a term used to describe the functionality provided by this module together with -the `fee_grant` module from [ADR 029](./adr-029-fee-grant-module.md) and the [group module](https://github.com/cosmos/cosmos-sdk/tree/main/x/group). +the `fee_grant` module from [ADR 029](./adr-029-fee-grant-module.md) and the [group module](https://github.com/cosmos/cosmos-sdk/tree/main/contrib/x/group). The "sub-keys" functionality roughly refers to the ability for one account to grant some subset of its capabilities to other accounts with possibly less robust, but easier to use security measures. For instance, a master account representing diff --git a/docs/build/architecture/adr-038-state-listening.md b/docs/build/architecture/adr-038-state-listening.md index 63f2ec163..56541567e 100644 --- a/docs/build/architecture/adr-038-state-listening.md +++ b/docs/build/architecture/adr-038-state-listening.md @@ -7,7 +7,7 @@ * 10/14/2022: * Add `ListenCommit`, flatten the state writes in a block to a single batch. * Remove listeners from cache stores, should only listen to `rootmulti.Store`. - * Remove `HaltAppOnDeliveryError()`, the errors are propagated by default, the implementations should return nil if they don't want to propagate errors. + * Remove `HaltAppOnDeliveryError()`, the errors are propagated by default, the implementations should return nil if don't want to propagate errors. * 26/05/2023: Update with ABCI 2.0 ## Status @@ -20,7 +20,7 @@ This ADR defines a set of changes to enable listening to state changes of indivi ## Context -Currently, KVStore data can be remotely accessed through [Queries](https://docs.cosmos.network/main/build/building-modules/messages-and-queries#queries) +Currently, KVStore data can be remotely accessed through [Queries](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules/messages-and-queries.md#queries) which proceed either through Tendermint and the ABCI, or through the gRPC server. In addition to these request/response queries, it would be beneficial to have a means of listening to state changes as they occur in real time. @@ -40,7 +40,7 @@ type MemoryListener struct { stateCache []StoreKVPair } -// NewMemoryListener creates a listener that accumulates the state writes in memory. +// NewMemoryListener creates a listener that accumulate the state writes in memory. func NewMemoryListener() *MemoryListener { return &MemoryListener{} } @@ -114,7 +114,7 @@ func (s *Store) Delete(key []byte) { ### MultiStore interface updates -We will update the `CommitMultiStore` interface to allow us to wrap a `MemoryListener` to a specific `KVStore`. +We will update the `CommitMultiStore` interface to allow us to wrap a `Memorylistener` to a specific `KVStore`. Note that the `MemoryListener` will be attached internally by the concrete `rootmulti` implementation. ```go @@ -224,9 +224,9 @@ so that the service can group the state changes with the ABCI requests. // ABCIListener is the interface that we're exposing as a streaming service. type ABCIListener interface { // ListenFinalizeBlock updates the streaming service with the latest FinalizeBlock messages - ListenFinalizeBlock(ctx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error - // ListenCommit updates the streaming service with the latest Commit messages and state changes - ListenCommit(ctx context.Context, res abci.CommitResponse, changeSet []*StoreKVPair) error + ListenFinalizeBlock(ctx context.Context, req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error + // ListenCommit updates the steaming service with the latest Commit messages and state changes + ListenCommit(ctx context.Context, res abci.ResponseCommit, changeSet []*StoreKVPair) error } ``` @@ -267,16 +267,16 @@ We will modify the `FinalizeBlock` and `Commit` methods to pass ABCI requests an to any streaming service hooks registered with the `BaseApp`. ```go -func (app *BaseApp) FinalizeBlock(req abci.FinalizeBlockRequest) abci.FinalizeBlockResponse { +func (app *BaseApp) FinalizeBlock(req abci.RequestFinalizeBlock) abci.ResponseFinalizeBlock { - var abciRes abci.FinalizeBlockResponse + var abciRes abci.ResponseFinalizeBlock defer func() { // call the streaming service hook with the FinalizeBlock messages for _, abciListener := range app.abciListeners { ctx := app.finalizeState.ctx blockHeight := ctx.BlockHeight() if app.abciListenersAsync { - go func(req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) { + go func(req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) { if err := app.abciListener.FinalizeBlock(blockHeight, req, res); err != nil { app.logger.Error("FinalizeBlock listening hook failed", "height", blockHeight, "err", err) } @@ -299,11 +299,11 @@ func (app *BaseApp) FinalizeBlock(req abci.FinalizeBlockRequest) abci.FinalizeBl ``` ```go -func (app *BaseApp) Commit() abci.CommitResponse { +func (app *BaseApp) Commit() abci.ResponseCommit { ... - res := abci.CommitResponse{ + res := abci.ResponseCommit{ Data: commitID.Hash, RetainHeight: retainHeight, } @@ -314,7 +314,7 @@ func (app *BaseApp) Commit() abci.CommitResponse { blockHeight := ctx.BlockHeight() changeSet := app.cms.PopStateCache() if app.abciListenersAsync { - go func(res abci.CommitResponse, changeSet []store.StoreKVPair) { + go func(res abci.ResponseCommit, changeSet []store.StoreKVPair) { if err := app.abciListener.ListenCommit(ctx, res, changeSet); err != nil { app.logger.Error("ListenCommit listening hook failed", "height", blockHeight, "err", err) } @@ -433,13 +433,13 @@ type GRPCClient struct { client ABCIListenerServiceClient } -func (m *GRPCClient) ListenFinalizeBlock(goCtx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error { +func (m *GRPCClient) ListenFinalizeBlock(goCtx context.Context, req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error { ctx := sdk.UnwrapSDKContext(goCtx) _, err := m.client.ListenDeliverTx(ctx, &ListenDeliverTxRequest{BlockHeight: ctx.BlockHeight(), Req: req, Res: res}) return err } -func (m *GRPCClient) ListenCommit(goCtx context.Context, res abci.CommitResponse, changeSet []store.StoreKVPair) error { +func (m *GRPCClient) ListenCommit(goCtx context.Context, res abci.ResponseCommit, changeSet []store.StoreKVPair) error { ctx := sdk.UnwrapSDKContext(goCtx) _, err := m.client.ListenCommit(ctx, &ListenCommitRequest{BlockHeight: ctx.BlockHeight(), Res: res, ChangeSet: changeSet}) return err @@ -471,11 +471,11 @@ And the pre-compiled Go plugin `Impl`(*this is only used for plugins that are wr // ABCIListener is the implementation of the baseapp.ABCIListener interface type ABCIListener struct{} -func (m *ABCIListenerPlugin) ListenFinalizeBlock(ctx context.Context, req abci.FinalizeBlockRequest, res abci.FinalizeBlockResponse) error { +func (m *ABCIListenerPlugin) ListenFinalizeBlock(ctx context.Context, req abci.RequestFinalizeBlock, res abci.ResponseFinalizeBlock) error { // send data to external system } -func (m *ABCIListenerPlugin) ListenCommit(ctx context.Context, res abci.CommitResponse, changeSet []store.StoreKVPair) error { +func (m *ABCIListenerPlugin) ListenCommit(ctx context.Context, res abci.ResponseCommit, changeSet []store.StoreKVPair) error { // send data to external system } @@ -529,7 +529,7 @@ func NewStreamingPlugin(name string, logLevel string) (interface{}, error) { We propose a `RegisterStreamingPlugin` function for the App to register `NewStreamingPlugin`s with the App's BaseApp. Streaming plugins can be of `Any` type; therefore, the function takes in an interface vs a concrete type. -For example, we could have plugins of `ABCIListener`, `WasmListener` or `IBCListener`. Note that `RegisterStreamingPlugin` function +For example, we could have plugins of `ABCIListener`, `WasmListener` or `IBCListener`. Note that `RegisterStreamingPluing` function is helper function and not a requirement. Plugin registration can easily be moved from the App to the BaseApp directly. ```go @@ -720,5 +720,5 @@ These changes will provide a means of subscribing to KVStore state changes in re ### Neutral -* Introduces additional—but optional—complexity to configuring and running a cosmos application +* Introduces additional- but optional- complexity to configuring and running a cosmos application * If an application developer opts to use these features to expose data, they need to be aware of the ramifications/risks of that data exposure as it pertains to the specifics of their application diff --git a/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md b/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md index 6259e588f..3a7bc2dd5 100644 --- a/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md +++ b/docs/build/architecture/adr-040-storage-and-smt-state-commitments.md @@ -92,7 +92,7 @@ A new database snapshot will be created in every `EndBlocker` and identified by NOTE: `Commit` must be called exactly once per block. Otherwise we risk going out of sync for the version number and block height. NOTE: For the Cosmos SDK storage, we may consider splitting that interface into `Committer` and `PruningCommitter` - only the multiroot should implement `PruningCommitter` (cache and prefix store don't need pruning). -Number of historical versions for `abci.QueryRequest` and state sync snapshots is part of a node configuration, not a chain configuration (configuration implied by the blockchain consensus). A configuration should allow to specify number of past blocks and number of past blocks modulo some number (eg: 100 past blocks and one snapshot every 100 blocks for past 2000 blocks). Archival nodes can keep all past versions. +Number of historical versions for `abci.RequestQuery` and state sync snapshots is part of a node configuration, not a chain configuration (configuration implied by the blockchain consensus). A configuration should allow to specify number of past blocks and number of past blocks modulo some number (eg: 100 past blocks and one snapshot every 100 blocks for past 2000 blocks). Archival nodes can keep all past versions. Pruning old snapshots is effectively done by a database. Whenever we update a record in `SC`, SMT won't update nodes - instead it creates new nodes on the update path, without removing the old one. Since we are snapshotting each block, we need to change that mechanism to immediately remove orphaned nodes from the database. This is a safe operation - snapshots will keep track of the records and make it available when accessing past versions. @@ -100,8 +100,8 @@ To manage the active snapshots we will either use a DB _max number of snapshots_ #### Accessing old state versions -One of the functional requirements is to access old state. This is done through `abci.QueryRequest` structure. The version is specified by a block height (so we query for an object by a key `K` at block height `H`). The number of old versions supported for `abci.QueryRequest` is configurable. Accessing an old state is done by using available snapshots. -`abci.QueryRequest` doesn't need old state of `SC` unless the `prove=true` parameter is set. The SMT merkle proof must be included in the `abci.QueryResponse` only if both `SC` and `SS` have a snapshot for requested version. +One of the functional requirements is to access old state. This is done through `abci.RequestQuery` structure. The version is specified by a block height (so we query for an object by a key `K` at block height `H`). The number of old versions supported for `abci.RequestQuery` is configurable. Accessing an old state is done by using available snapshots. +`abci.RequestQuery` doesn't need old state of `SC` unless the `prove=true` parameter is set. The SMT merkle proof must be included in the `abci.ResponseQuery` only if both `SC` and `SS` have a snapshot for requested version. Moreover, Cosmos SDK could provide a way to directly access a historical state. However, a state machine shouldn't do that - since the number of snapshots is configurable, it would lead to nondeterministic execution. diff --git a/docs/build/architecture/adr-059-test-scopes.md b/docs/build/architecture/adr-059-test-scopes.md index 6fa387c20..36e1468e2 100644 --- a/docs/build/architecture/adr-059-test-scopes.md +++ b/docs/build/architecture/adr-059-test-scopes.md @@ -98,7 +98,7 @@ exercises [HandleEquivocationEvidence](https://github.com/cosmos/cosmos-sdk/blob keeper. Example 3 - Integration suite app configurations may also be specified via golang (not -YAML as above) [statically](https://github.com/cosmos/cosmos-sdk/blob/main/x/nft/testutil/app_config.go) or [dynamically](https://github.com/cosmos/cosmos-sdk/blob/8c23f6f957d1c0bedd314806d1ac65bea59b084c/tests/integration/bank/keeper/keeper_test.go#L129-L134). +YAML as above) [statically](https://github.com/cosmos/cosmos-sdk/blob/main/contrib/x/nft/testutil/app_config.go) or [dynamically](https://github.com/cosmos/cosmos-sdk/blob/8c23f6f957d1c0bedd314806d1ac65bea59b084c/tests/integration/bank/keeper/keeper_test.go#L129-L134). #### Limitations diff --git a/docs/build/architecture/adr-060-abci-1.0.md b/docs/build/architecture/adr-060-abci-1.0.md index 41e2230bc..01928e7b9 100644 --- a/docs/build/architecture/adr-060-abci-1.0.md +++ b/docs/build/architecture/adr-060-abci-1.0.md @@ -169,7 +169,7 @@ Instead, we will define an additional ABCI interface method on the existing or `EndBlock`. This new interface method will be defined as follows: ```go -ProcessProposal(sdk.Context, abci.ProcessProposalRequest) error {} +ProcessProposal(sdk.Context, abci.RequestProcessProposal) error {} ``` Note, we must call `ProcessProposal` with a new internal branched state on the diff --git a/docs/build/architecture/adr-063-core-module-api.md b/docs/build/architecture/adr-063-core-module-api.md index cb5bb02b3..57f92d4dc 100644 --- a/docs/build/architecture/adr-063-core-module-api.md +++ b/docs/build/architecture/adr-063-core-module-api.md @@ -192,8 +192,6 @@ func NewKeeper(logger log.Logger) Keeper { } ``` -``` - ### Core `AppModule` extension interfaces diff --git a/docs/build/architecture/adr-064-abci-2.0.md b/docs/build/architecture/adr-064-abci-2.0.md index 476896276..67187eb78 100644 --- a/docs/build/architecture/adr-064-abci-2.0.md +++ b/docs/build/architecture/adr-064-abci-2.0.md @@ -103,8 +103,8 @@ vote extensions. We propose the following new handlers for applications to implement: ```go -type ExtendVoteHandler func(sdk.Context, abci.ExtendVoteRequest) abci.ExtendVoteResponse -type VerifyVoteExtensionHandler func(sdk.Context, abci.VerifyVoteExtensionRequest) abci.VerifyVoteExtensionResponse +type ExtendVoteHandler func(sdk.Context, abci.RequestExtendVote) abci.ResponseExtendVote +type VerifyVoteExtensionHandler func(sdk.Context, abci.RequestVerifyVoteExtension) abci.ResponseVerifyVoteExtension ``` An ephemeral context and state will be supplied to both handlers. The @@ -144,7 +144,7 @@ type VoteExtensionHandler struct { // ExtendVoteHandler can do something with h.mk and possibly h.state to create // a vote extension, such as fetching a series of prices for supported assets. -func (h VoteExtensionHandler) ExtendVoteHandler(ctx sdk.Context, req abci.ExtendVoteRequest) abci.ExtendVoteResponse { +func (h VoteExtensionHandler) ExtendVoteHandler(ctx sdk.Context, req abci.RequestExtendVote) abci.ResponseExtendVote { prices := GetPrices(ctx, h.mk.Assets()) bz, err := EncodePrices(h.cdc, prices) if err != nil { @@ -156,22 +156,22 @@ func (h VoteExtensionHandler) ExtendVoteHandler(ctx sdk.Context, req abci.Extend // NOTE: Vote extensions can be overridden since we can timeout in a round. SetPrices(h.state, req, bz) - return abci.ExtendVoteResponse{VoteExtension: bz} + return abci.ResponseExtendVote{VoteExtension: bz} } // VerifyVoteExtensionHandler can do something with h.state and req to verify // the req.VoteExtension field, such as ensuring the provided oracle prices are // within some valid range of our prices. -func (h VoteExtensionHandler) VerifyVoteExtensionHandler(ctx sdk.Context, req abci.VerifyVoteExtensionRequest) abci.VerifyVoteExtensionResponse { +func (h VoteExtensionHandler) VerifyVoteExtensionHandler(ctx sdk.Context, req abci.RequestVerifyVoteExtension) abci.ResponseVerifyVoteExtension { prices, err := DecodePrices(h.cdc, req.VoteExtension) if err != nil { log("failed to decode vote extension", "err", err) - return abci.VerifyVoteExtensionResponse{Status: REJECT} + return abci.ResponseVerifyVoteExtension{Status: REJECT} } if err := ValidatePrices(h.state, req, prices); err != nil { log("failed to validate vote extension", "prices", prices, "err", err) - return abci.VerifyVoteExtensionResponse{Status: REJECT} + return abci.ResponseVerifyVoteExtension{Status: REJECT} } // store updated vote extensions at the given height @@ -179,7 +179,7 @@ func (h VoteExtensionHandler) VerifyVoteExtensionHandler(ctx sdk.Context, req ab // NOTE: Vote extensions can be overridden since we can timeout in a round. SetPrices(h.state, req, req.VoteExtension) - return abci.VerifyVoteExtensionResponse{Status: ACCEPT} + return abci.ResponseVerifyVoteExtension{Status: ACCEPT} } ``` @@ -301,7 +301,7 @@ during `ProcessProposal` because during replay, CometBFT will NOT call `ProcessP which would result in an incomplete state view. ```go -func (a MyApp) PreBlocker(ctx sdk.Context, req *abci.FinalizeBlockRequest) error { +func (a MyApp) PreBlocker(ctx sdk.Context, req *abci.RequestFinalizeBlock) error { voteExts := GetVoteExtensions(ctx, req.Txs) // Process and perform some compute on vote extensions, storing any resulting @@ -350,7 +350,7 @@ legacy ABCI types, e.g. `LegacyBeginBlockRequest` and `LegacyEndBlockRequest`. O we can come up with new types and names altogether. ```go -func (app *BaseApp) FinalizeBlock(req abci.FinalizeBlockRequest) (*abci.FinalizeBlockResponse, error) { +func (app *BaseApp) FinalizeBlock(req abci.RequestFinalizeBlock) (*abci.ResponseFinalizeBlock, error) { ctx := ... if app.preBlocker != nil { @@ -375,7 +375,7 @@ func (app *BaseApp) FinalizeBlock(req abci.FinalizeBlockRequest) (*abci.Finalize endBlockResp, err := app.endBlock(app.finalizeBlockState.ctx) appendBlockEventAttr(beginBlockResp.Events, "end_block") - return abci.FinalizeBlockResponse{ + return abci.ResponseFinalizeBlock{ TxResults: txExecResults, Events: joinEvents(beginBlockResp.Events, endBlockResp.Events), ValidatorUpdates: endBlockResp.ValidatorUpdates, diff --git a/docs/build/building-apps/04-vote-extensions.md b/docs/build/building-apps/04-vote-extensions.md index f20ebde66..976e21654 100644 --- a/docs/build/building-apps/04-vote-extensions.md +++ b/docs/build/building-apps/04-vote-extensions.md @@ -16,7 +16,7 @@ process does NOT have to be deterministic, and the data returned can be unique t validator process. The Cosmos SDK defines `baseapp.ExtendVoteHandler`: ```go -type ExtendVoteHandler func(Context, *abci.ExtendVoteRequest) (*abci.ExtendVoteResponse, error) +type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) ``` An application can set this handler in `app.go` via the `baseapp.SetExtendVoteHandler` @@ -77,7 +77,7 @@ will be available to the application during the subsequent `FinalizeBlock` call. An example of how a pre-FinalizeBlock hook could look is shown below: ```go -app.SetPreBlocker(func(ctx sdk.Context, req *abci.FinalizeBlockRequest) error { +app.SetPreBlocker(func(ctx sdk.Context, req *abci.RequestFinalizeBlock) error { allVEs := []VE{} // store all parsed vote extensions here for _, tx := range req.Txs { // define a custom function that tries to parse the tx as a vote extension diff --git a/docs/build/building-modules/01-module-manager.md b/docs/build/building-modules/01-module-manager.md index ee2a83a80..15a6e7243 100644 --- a/docs/build/building-modules/01-module-manager.md +++ b/docs/build/building-modules/01-module-manager.md @@ -302,7 +302,7 @@ 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.InitChainResponse` to the underlying consensus engine, which can contain validator updates. +* `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. * `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. diff --git a/docs/build/building-modules/02-messages-and-queries.md b/docs/build/building-modules/02-messages-and-queries.md index e6048c313..573c35cd7 100644 --- a/docs/build/building-modules/02-messages-and-queries.md +++ b/docs/build/building-modules/02-messages-and-queries.md @@ -39,15 +39,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/bank/v1be ### `sdk.Msg` Interface -`sdk.Msg` is an alias of `proto.Message`. +`sdk.Msg` is a alias of `proto.Message`. -To attach a `ValidateBasic()` method to a message then you must add methods to the type adhering to the `HasValidateBasic`. +To attach a `ValidateBasic()` method to a message then you must add methods to the type adhereing to the `HasValidateBasic`. ```go reference https://github.com/cosmos/cosmos-sdk/blob/9c1e8b247cd47b5d3decda6e86fbc3bc996ee5d7/types/tx_msg.go#L84-L88 ``` -In 0.50+ signers from the `GetSigners()` call are automated via a protobuf annotation. +In 0.50+ signers from the `GetSigners()` call is automated via a protobuf annotation. Read more about the signer field [here](./05-protobuf-annotations.md). @@ -120,7 +120,7 @@ where: * `queryType` is used by the module's [`querier`](./04-query-services.md#legacy-queriers) to map the `query` to the appropriate `querier function` within the module. * `args` are the actual arguments needed to process the `query`. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in the `Data` field of the request `req` instead of the `path`. -The `path` for each `query` must be defined by the module developer in the module's [command-line interface file](./09-module-interfaces.md#query-commands). Overall, there are 3 mains components module developers need to implement in order to make the subset of the state defined by their module queryable: +The `path` for each `query` must be defined by the module developer in the module's [command-line interface file](./09-module-interfaces.md#query-commands).Overall, there are 3 mains components module developers need to implement in order to make the subset of the state defined by their module queryable: * A [`querier`](./04-query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../../learn/advanced/00-baseapp.md#query-routing). * [Query commands](./09-module-interfaces.md#query-commands) in the module's CLI file, where the `path` for each `query` is specified. @@ -128,7 +128,7 @@ The `path` for each `query` must be defined by the module developer in the modul ### Store Queries -Store queries access store keys directly. They use `clientCtx.QueryABCI(req abci.QueryRequest)` to return the full `abci.QueryResponse` with inclusion Merkle proofs. +Store queries query directly for store keys. They use `clientCtx.QueryABCI(req abci.RequestQuery)` to return the full `abci.ResponseQuery` with inclusion Merkle proofs. See following examples: diff --git a/docs/build/building-modules/06-keeper.md b/docs/build/building-modules/06-keeper.md index f942750e5..f204d2945 100644 --- a/docs/build/building-modules/06-keeper.md +++ b/docs/build/building-modules/06-keeper.md @@ -18,7 +18,7 @@ sidebar_position: 1 The Cosmos SDK is a framework that makes it easy for developers to build complex decentralized applications from scratch, mainly by composing modules together. As the ecosystem of open-source modules for the Cosmos SDK expands, it will become increasingly likely that some of these modules contain vulnerabilities, as a result of the negligence or malice of their developers. -The Cosmos SDK adopts an [object-capabilities-based approach](../../docs/learn/advanced/10-ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../../learn/advanced/04-store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s). +The Cosmos SDK adopts an [object-capabilities-based approach](../../learn/advanced/10-ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../../learn/advanced/04-store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s). The core idea behind the object-capabilities approach is to only reveal what is necessary to get the work done. In practice, this means that instead of handling permissions of modules through access-control lists, module `keeper`s are passed a reference to the specific instance of the other modules' `keeper`s that they need to access (this is done in the [application's constructor function](../../learn/beginner/00-app-anatomy.md#constructor-function)). As a consequence, a module can only interact with the subset of state defined in another module via the methods exposed by the instance of the other module's `keeper`. This is a great way for developers to control the interactions that their own module can have with modules developed by external developers. diff --git a/docs/build/modules/README.md b/docs/build/modules/README.md index 12a128c3a..e7756f594 100644 --- a/docs/build/modules/README.md +++ b/docs/build/modules/README.md @@ -14,16 +14,15 @@ proof-of-stake capabilities and governance. * [Auth](./auth/README.md) - Authentication of accounts and transactions for Cosmos SDK applications. * [Bank](./bank/README.md) - Token transfer functionalities. -* [Circuit](./circuit/README.md) - Circuit breaker module for pausing messages. * [Consensus](./consensus/README.md) - Consensus module for modifying CometBFT's ABCI consensus params. * [Distribution](./distribution/README.md) - Fee distribution, and staking token provision distribution. -* [Evidence](./evidence/README.md) - Evidence handling for double signing, misbehaviour, etc. * [Governance](./gov/README.md) - On-chain proposals and voting. * [Genutil](./genutil/README.md) - Genesis utilities for the Cosmos SDK. * [Mint](./mint/README.md) - Creation of new units of staking token. * [Slashing](./slashing/README.md) - Validator punishment mechanisms. * [Staking](./staking/README.md) - Proof-of-Stake layer for public blockchains. * [Upgrade](./upgrade/README.md) - Software upgrades handling and coordination. +* [Evidence](./evidence/README.md) - Evidence handling for double signing, misbehaviour, etc. ## Supplementary Modules @@ -38,13 +37,13 @@ capabilities of your blockchain or further specialize it. ## Deprecated Modules -The following modules are deprecated. They will no longer be maintained and eventually will be removed -in an upcoming release of the Cosmos SDK per our [release process](https://github.com/cosmos/cosmos-sdk/blob/main/RELEASE_PROCESS.md). +The following modules are deprecated. They will no longer be maintained actively. -* [Crisis](./crisis/README.md) - _Deprecated_ halting the blockchain under certain circumstances (e.g. if an invariant is broken). +* [Crisis](../contrib/x/crisis/README.md) - _Deprecated_ halting the blockchain under certain circumstances (e.g. if an invariant is broken). * [Params](./params/README.md) - _Deprecated_ Globally available parameter store. -* [NFT](./nft/README.md) - _Deprecated_ NFT module implemented based on [ADR43](https://docs.cosmos.network/main/build/architecture/adr-043-nft-module). This module will be moved to the `cosmos-sdk-legacy` repo for use. -* [Group](./group/README.md) - _Deprecated_ Allows for the creation and management of on-chain multisig accounts. This module will be moved to the `cosmos-sdk-legacy` repo for legacy use. +* [NFT](../contrib/x/nft/README.md) - _Deprecated_ NFT module implemented based on [ADR43](https://docs.cosmos.network/main/build/architecture/adr-043-nft-module). +* [Group](../contrib/x/group/README.md) - _Deprecated_ Allows for the creation and management of on-chain multisig accounts. +* [Circuit](../contrib/x/circuit/README.md) _Deprecated_ - Circuit breaker module for pausing messages. To learn more about the process of building modules, visit the [building modules reference documentation](https://docs.cosmos.network/main/building-modules/intro). diff --git a/docs/build/modules/circuit/README.md b/docs/build/modules/circuit/README.md index 253ca497d..f3b753896 100644 --- a/docs/build/modules/circuit/README.md +++ b/docs/build/modules/circuit/README.md @@ -21,7 +21,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/baseapp/msg_service_router.go# ``` :::note -The `CircuitBreakerDecorator` works for most use cases, but [does not check the inner messages of a transaction](https://docs.cosmos.network/main/learn/beginner/tx-lifecycle#antehandler). This means some transactions (such as `x/authz` transactions or some `x/gov` transactions) may pass the ante handler. **This does not affect the circuit breaker** as the message router check will still fail the transaction. +The `CircuitBreakerDecorator` works for most use cases, but [does not check the inner messages of a transaction](https://docs.cosmos.network/main/learn/beginner/tx-lifecycle#antehandler). This some transactions (such as `x/authz` transactions or some `x/gov` transactions) may pass the ante handler. **This does not affect the circuit breaker** as the message router check will still fail the transaction. This tradeoff is to avoid introducing more dependencies in the `x/circuit` module. Chains can re-define the `CircuitBreakerDecorator` to check for inner messages if they wish to do so. ::: @@ -91,7 +91,7 @@ Reset is called by an authorized account to enable execution for a specific msgU ```protobuf // ResetCircuitBreaker resumes processing of Msg's in the state machine that - // have been paused using TripCircuitBreaker. + // have been been paused using TripCircuitBreaker. rpc ResetCircuitBreaker(MsgResetCircuitBreaker) returns (MsgResetCircuitBreakerResponse); ``` @@ -168,92 +168,3 @@ The circuit module emits the following events: * `DisableListPrefix` - `0x02` ## Client - list and describe CLI commands and gRPC and REST endpoints - -## Examples: Using Circuit Breaker CLI Commands - -This section provides practical examples for using the Circuit Breaker module through the command-line interface (CLI). These examples demonstrate how to authorize accounts, disable (trip) specific message types, and re-enable (reset) them when needed. - -### Querying Circuit Breaker Permissions - -Check an account's current circuit breaker permissions: - -```bash -# Query permissions for a specific account - query circuit account-permissions - -# Example: -simd query circuit account-permissions cosmos1... -``` - -Check which message types are currently disabled: - -```bash -# Query all disabled message types - query circuit disabled-list - -# Example: -simd query circuit disabled-list -``` - -### Authorizing an Account as Circuit Breaker - -Only a super-admin or the module authority (typically the governance module account) can grant circuit breaker permissions to other accounts: - -```bash -# Grant LEVEL_ALL_MSGS permission (can disable any message type) - tx circuit authorize --level=ALL_MSGS --from= --gas=auto --gas-adjustment=1.5 - -# Grant LEVEL_SOME_MSGS permission (can only disable specific message types) - tx circuit authorize --level=SOME_MSGS --limit-type-urls="/cosmos.bank.v1beta1.MsgSend,/cosmos.staking.v1beta1.MsgDelegate" --from= --gas=auto --gas-adjustment=1.5 - -# Grant LEVEL_SUPER_ADMIN permission (can disable messages and authorize other accounts) - tx circuit authorize --level=SUPER_ADMIN --from= --gas=auto --gas-adjustment=1.5 -``` - -### Disabling Message Processing (Trip) - -Disable specific message types to prevent their execution (requires authorization): - -```bash -# Disable a single message type - tx circuit trip --type-urls="/cosmos.bank.v1beta1.MsgSend" --from= --gas=auto --gas-adjustment=1.5 - -# Disable multiple message types - tx circuit trip --type-urls="/cosmos.bank.v1beta1.MsgSend,/cosmos.staking.v1beta1.MsgDelegate" --from= --gas=auto --gas-adjustment=1.5 - -# Disable all message types (emergency measure) - tx circuit trip --from= --gas=auto --gas-adjustment=1.5 -``` - -### Re-enabling Message Processing (Reset) - -Re-enable previously disabled message types (requires authorization): - -```bash -# Re-enable a single message type - tx circuit reset --type-urls="/cosmos.bank.v1beta1.MsgSend" --from= --gas=auto --gas-adjustment=1.5 - -# Re-enable multiple message types - tx circuit reset --type-urls="/cosmos.bank.v1beta1.MsgSend,/cosmos.staking.v1beta1.MsgDelegate" --from= --gas=auto --gas-adjustment=1.5 - -# Re-enable all disabled message types - tx circuit reset --from= --gas=auto --gas-adjustment=1.5 -``` - -### Usage in Emergency Scenarios - -In case of a critical vulnerability in a specific message type: - -1. Quickly disable the vulnerable message type: - - ```bash - tx circuit trip --type-urls="/cosmos.vulnerable.v1beta1.MsgVulnerable" --from= --gas=auto --gas-adjustment=1.5 - ``` - -2. After a fix is deployed, re-enable the message type: - - ```bash - tx circuit reset --type-urls="/cosmos.vulnerable.v1beta1.MsgVulnerable" --from= --gas=auto --gas-adjustment=1.5 - ``` - -This allows chains to surgically disable problematic functionality without halting the entire chain, providing time for developers to implement and deploy fixes. diff --git a/docs/build/modules/consensus/README.md b/docs/build/modules/consensus/README.md index 902280a6e..8c1f641a3 100644 --- a/docs/build/modules/consensus/README.md +++ b/docs/build/modules/consensus/README.md @@ -4,4 +4,84 @@ sidebar_position: 1 # `x/consensus` -Functionality to modify CometBFT's ABCI consensus params. +The consensus module provides functionality to modify CometBFT's ABCI consensus parameters on-chain through governance proposals. + +## Overview + +This module allows authorized entities (typically governance) to update critical consensus parameters that affect blockchain performance and security without requiring a hard fork. + +## Key Features + +- **Parameter Updates**: Modify consensus parameters through governance proposals +- **Authority Control**: Only authorized addresses can update parameters +- **Validation**: Comprehensive parameter validation before updates +- **ABCI Integration**: Direct integration with CometBFT consensus engine + +## Consensus Parameters + +The module manages the following CometBFT consensus parameters: + +### Block Parameters +- `MaxBytes`: Maximum block size in bytes +- `MaxGas`: Maximum gas per block + +### Evidence Parameters +- `MaxAgeNumBlocks`: Maximum age of evidence in blocks +- `MaxAgeDuration`: Maximum age of evidence in time +- `MaxBytes`: Maximum evidence size in bytes + +### Validator Parameters +- `PubKeyTypes`: Supported public key types for validators + +### ABCI Parameters +- `VoteExtensionsEnableHeight`: Height at which vote extensions are enabled + +## Usage + +### Governance Proposal + +To update consensus parameters, submit a governance proposal with `MsgUpdateParams`: + +```go +import ( + "time" + govtypes "github.com/cosmos/cosmos-sdk/x/gov/types" + authtypes "github.com/cosmos/cosmos-sdk/x/auth/types" +) + +msg := &types.MsgUpdateParams{ + Authority: authtypes.NewModuleAddress(govtypes.ModuleName).String(), // governance authority + Block: &types.BlockParams{ + MaxBytes: 22020096, + MaxGas: 10000000, + }, + Evidence: &types.EvidenceParams{ + MaxAgeNumBlocks: 100000, + MaxAgeDuration: 48 * time.Hour, + MaxBytes: 1048576, + }, + Validator: &types.ValidatorParams{ + PubKeyTypes: []string{"ed25519"}, + }, +} +``` + +### Query Parameters + +Retrieve current consensus parameters: + +```bash + q consensus params +``` + +## Architecture + +- **Keeper**: Manages parameter storage and validation +- **Types**: Defines message types and parameter structures +- **Module**: Integrates with the Cosmos SDK application lifecycle + +## Security + +- Only the designated authority can update parameters +- All parameter changes are validated before application +- Updates are subject to governance approval process diff --git a/docs/build/modules/crisis/README.md b/docs/build/modules/crisis/README.md index 631f9d857..e4e29d0a1 100644 --- a/docs/build/modules/crisis/README.md +++ b/docs/build/modules/crisis/README.md @@ -4,8 +4,6 @@ sidebar_position: 1 # `x/crisis` -NOTE: `x/crisis` is deprecated as of Cosmos SDK v0.53 and will be removed in the next release. - ## Overview The crisis module halts the blockchain under the circumstance that a blockchain @@ -66,7 +64,7 @@ The crisis module emits the following events: ### Handlers -#### MsgVerifyInvariant +#### MsgVerifyInvariance | Type | Attribute Key | Attribute Value | |-----------|---------------|------------------| diff --git a/docs/build/modules/genutil/README.md b/docs/build/modules/genutil/README.md index 34bc79d5c..45cb45355 100644 --- a/docs/build/modules/genutil/README.md +++ b/docs/build/modules/genutil/README.md @@ -16,7 +16,7 @@ The `genutil` package contains a variety of genesis utility functionalities for ## Genesis Genutil contains the data structure that defines an application genesis. -An application genesis consists of a consensus genesis (g.e. CometBFT genesis) and application related genesis data. +An application genesis consist of a consensus genesis (g.e. CometBFT genesis) and application related genesis data. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/x/genutil/types/genesis.go#L24-L34 diff --git a/docs/build/modules/gov/README.md b/docs/build/modules/gov/README.md index 7b10700c1..0a8118d88 100644 --- a/docs/build/modules/gov/README.md +++ b/docs/build/modules/gov/README.md @@ -2532,7 +2532,7 @@ The gov module has two locations for metadata where users can provide further co ### Proposal -Location: off-chain as json object stored on IPFS (mirrors [group proposal](../group/README.md#metadata)) +Location: off-chain as json object stored on IPFS (mirrors [group proposal](../../contrib/x/group/README.md#metadata)) ```json { @@ -2552,7 +2552,7 @@ In v0.46, the `authors` field is a comma-separated string. Frontends are encoura ### Vote -Location: on-chain as json within 255 character limit (mirrors [group vote](../group/README.md#metadata)) +Location: on-chain as json within 255 character limit (mirrors [group vote](../../contrib/x/group/README.md#metadata)) ```json { diff --git a/docs/build/modules/group/README.md b/docs/build/modules/group/README.md index 98fd7ba91..71d91ccb4 100644 --- a/docs/build/modules/group/README.md +++ b/docs/build/modules/group/README.md @@ -4,8 +4,6 @@ sidebar_position: 1 # `x/group` -⚠️ **DEPRECATED**: This package is deprecated and will be removed in the next major release. The `x/group` module will be moved to a separate repo `github.com/cosmos/cosmos-sdk-legacy`. - ## Abstract The following documents specify the group module. @@ -87,7 +85,7 @@ A decision policy is the mechanism by which members of a group can vote on proposals, as well as the rules that dictate whether a proposal should pass or not based on its tally outcome. -All decision policies generally would have a minimum execution period and a +All decision policies generally would have a mininum execution period and a maximum voting window. The minimum execution period is the minimum amount of time that must pass after submission in order for a proposal to potentially be executed, and it may be set to 0. The maximum voting window is the maximum time after submission that a proposal may @@ -103,7 +101,7 @@ custom decision policies, as long as they adhere to the `DecisionPolicy` interface: ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/x/group/types.go#L27-L45 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/group/types.go#L27-L45 ``` #### Threshold decision policy @@ -212,7 +210,7 @@ Proposals and votes are automatically pruned to avoid state bloat. Votes are pruned: * either after a successful tally, i.e. a tally whose result passes the decision - policy's rules, which can be triggered by a `Msg/Exec` or a + policy's rules, which can be trigged by a `Msg/Exec` or a `Msg/{SubmitProposal,Vote}` with the `Exec` field set, * or on `EndBlock` right after the proposal's voting period end. This applies to proposals with status `aborted` or `withdrawn` too. @@ -339,7 +337,7 @@ The metadata has a maximum length that is chosen by the app developer, and passed into the group keeper as a config. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L67-L80 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L67-L80 ``` It's expected to fail if @@ -352,7 +350,7 @@ It's expected to fail if Group members can be updated with the `UpdateGroupMembers`. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L88-L102 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L88-L102 ``` In the list of `MemberUpdates`, an existing member can be removed by setting its weight to 0. @@ -367,7 +365,7 @@ It's expected to fail if: The `UpdateGroupAdmin` can be used to update a group admin. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L107-L120 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L107-L120 ``` It's expected to fail if the signer is not the admin of the group. @@ -377,7 +375,7 @@ It's expected to fail if the signer is not the admin of the group. The `UpdateGroupMetadata` can be used to update a group metadata. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L125-L138 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L125-L138 ``` It's expected to fail if: @@ -390,7 +388,7 @@ It's expected to fail if: A new group policy can be created with the `MsgCreateGroupPolicy`, which has an admin address, a group id, a decision policy and some optional metadata. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L147-L165 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L147-L165 ``` It's expected to fail if: @@ -404,7 +402,7 @@ It's expected to fail if: A new group with policy can be created with the `MsgCreateGroupWithPolicy`, which has an admin address, a list of members, a decision policy, a `group_policy_as_admin` field to optionally set group and group policy admin with group policy address and some optional metadata for group and group policy. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L191-L215 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L191-L215 ``` It's expected to fail for the same reasons as `Msg/CreateGroup` and `Msg/CreateGroupPolicy`. @@ -414,7 +412,7 @@ It's expected to fail for the same reasons as `Msg/CreateGroup` and `Msg/CreateG The `UpdateGroupPolicyAdmin` can be used to update a group policy admin. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L173-L186 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L173-L186 ``` It's expected to fail if the signer is not the admin of the group policy. @@ -424,7 +422,7 @@ It's expected to fail if the signer is not the admin of the group policy. The `UpdateGroupPolicyDecisionPolicy` can be used to update a decision policy. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L226-L241 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L226-L241 ``` It's expected to fail if: @@ -437,7 +435,7 @@ It's expected to fail if: The `UpdateGroupPolicyMetadata` can be used to update a group policy metadata. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L246-L259 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L246-L259 ``` It's expected to fail if: @@ -451,7 +449,7 @@ A new proposal can be created with the `MsgSubmitProposal`, which has a group po An optional `Exec` value can be provided to try to execute the proposal immediately after proposal creation. Proposers signatures are considered as yes votes in this case. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L281-L315 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L281-L315 ``` It's expected to fail if: @@ -464,7 +462,7 @@ It's expected to fail if: A proposal can be withdrawn using `MsgWithdrawProposal` which has an `address` (can be either a proposer or the group policy admin) and a `proposal_id` (which has to be withdrawn). ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L323-L333 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L323-L333 ``` It's expected to fail if: @@ -478,7 +476,7 @@ A new vote can be created with the `MsgVote`, given a proposal id, a voter addre An optional `Exec` value can be provided to try to execute the proposal immediately after voting. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L338-L358 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L338-L358 ``` It's expected to fail if: @@ -491,7 +489,7 @@ It's expected to fail if: A proposal can be executed with the `MsgExec`. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L363-L373 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L363-L373 ``` The messages that are part of this proposal won't be executed if: @@ -504,7 +502,7 @@ The messages that are part of this proposal won't be executed if: The `MsgLeaveGroup` allows group member to leave a group. ```go reference -https://github.com/cosmos/cosmos-sdk/tree/release/v0.50.x/proto/cosmos/group/v1/tx.proto#L381-L391 +https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L381-L391 ``` It's expected to fail if: diff --git a/docs/build/modules/nft/README.md b/docs/build/modules/nft/README.md index 4348aaca3..34c1d4066 100644 --- a/docs/build/modules/nft/README.md +++ b/docs/build/modules/nft/README.md @@ -4,8 +4,6 @@ sidebar_position: 1 # `x/nft` -⚠️ **DEPRECATED**: This package is deprecated and will be removed in the next major release. The `x/nft` module will be moved to a separate repo `github.com/cosmos/cosmos-sdk-legacy`. - ## Contents ## Abstract diff --git a/docs/build/spec/store/README.md b/docs/build/spec/store/README.md index 3bf8b0e34..ec3573900 100644 --- a/docs/build/spec/store/README.md +++ b/docs/build/spec/store/README.md @@ -156,7 +156,7 @@ state from each `KVStore` to disk and returning an application state Merkle root Queries can be performed to return state data along with associated state commitment proofs for both previous heights/versions and the current state root. Queries are routed based on store name, i.e. a module, along with other parameters -which are defined in `abci.QueryRequest`. +which are defined in `abci.RequestQuery`. The `rootmulti.Store` also provides primitives for pruning data at a given height/version from state storage. When a height is committed, the `rootmulti.Store` diff --git a/docs/build/tooling/00-protobuf.md b/docs/build/tooling/00-protobuf.md index 128970c0c..5ab2cb984 100644 --- a/docs/build/tooling/00-protobuf.md +++ b/docs/build/tooling/00-protobuf.md @@ -111,3 +111,25 @@ A reference to the github actions can be found [here](https://github.com/cosmos/ ```go reference https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/proto.yml#L1-L32 ``` + +### Troubleshooting: proto generation (buf/protoc) + +- **`protoc: command not found` or plugin not found** + Prefer the Docker-based flow described on this page to avoid local toolchain drift: + ```sh + make proto-image && make proto-gen + ``` + This pins compatible `protoc` and plugins. If you do use a local toolchain, ensure your `$PATH` includes `$(go env GOPATH)/bin`. + +- **Buf import errors (e.g., `google/api/annotations.proto` not found)** + Verify that your project contains the required `buf.yaml` and `buf.gen*.yaml` files and that `deps` are present and correct. + In mono-repos, make sure any `third_party/proto` (or equivalent) directories are included and that `buf` configs point to them. + +- **Shell/CI differences** + Some environments handle shell options differently (e.g., `set -o pipefail`). Running the generation via the documented Docker image avoids these discrepancies. + +- **Version pinning** + Pin the proto-builder image to the recommended tag (e.g., `ghcr.io/cosmos/proto-builder:`) to prevent plugin/version mismatches. When in doubt, rebuild the image and regenerate: + ```sh + make clean proto-image proto-gen + ``` diff --git a/docs/build/tooling/01-cosmovisor.md b/docs/build/tooling/01-cosmovisor.md index 7c70611ff..67d37001f 100644 --- a/docs/build/tooling/01-cosmovisor.md +++ b/docs/build/tooling/01-cosmovisor.md @@ -45,7 +45,7 @@ Versions prior to v1.0.0 have a vulnerability that could lead to a DOS. Please u ## Contributing -Cosmovisor is part of the Cosmos SDK monorepo, but it's a separate module with it's own release schedule. +Cosmovisor is part of the Cosmos SDK monorepo, but it's a separate module with its own release schedule. Release branches have the following format `release/cosmovisor/vA.B.x`, where A and B are a number (e.g. `release/cosmovisor/v1.3.x`). Releases are tagged using the following format: `cosmovisor/vA.B.C`. @@ -84,7 +84,7 @@ The first argument passed to `cosmovisor` is the action for `cosmovisor` to take * `run` - Run the configured binary using the rest of the provided arguments. * `version` - Output the `cosmovisor` version and also run the binary with the `version` argument. * `config` - Display the current `cosmovisor` configuration, that means displaying the environment variables value that `cosmovisor` is using. -* `add-upgrade` - Add an upgrade manually to `cosmovisor`. This command allow you to easily add the binary corresponding to an upgrade in cosmovisor. +* `add-upgrade` - Add an upgrade manually to `cosmovisor`. This command allows you to easily add the binary corresponding to an upgrade in cosmovisor. All arguments passed to `cosmovisor run` will be passed to the application binary (as a subprocess). `cosmovisor` will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. For this reason, `cosmovisor run` cannot accept any command-line arguments other than those available to the application binary. @@ -105,7 +105,7 @@ All arguments passed to `cosmovisor run` will be passed to the application binar * `COSMOVISOR_COLOR_LOGS` (defaults to `true`). If set to true, this will colorise Cosmovisor logs (but not the underlying process). * `COSMOVISOR_TIMEFORMAT_LOGS` (defaults to `kitchen`). If set to a value (`layout|ansic|unixdate|rubydate|rfc822|rfc822z|rfc850|rfc1123|rfc1123z|rfc3339|rfc3339nano|kitchen`), this will add timestamp prefix to Cosmovisor logs (but not the underlying process). * `COSMOVISOR_CUSTOM_PREUPGRADE` (defaults to ``). If set, this will run $DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE prior to upgrade with the arguments [ upgrade.Name, upgrade.Height ]. Executes a custom script (separate and prior to the chain daemon pre-upgrade command) -* `COSMOVISOR_DISABLE_RECASE` (defaults to `false`). If set to true, the upgrade directory will expected to match the upgrade plan name without any case changes +* `COSMOVISOR_DISABLE_RECASE` (defaults to `false`). If set to true, the upgrade directory will be expected to match the upgrade plan name without any case changes ### Folder Layout @@ -200,9 +200,9 @@ Take this into consideration when using `--upgrade-height`. Generally, `cosmovisor` requires that the system administrator place all relevant binaries on disk before the upgrade happens. However, for people who don't need such control and want an automated setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option. -**NOTE: we don't recommend using auto-download** because it doesn't verify in advance if a binary is available. If there will be any issue with downloading a binary, the cosmovisor will stop and won't restart an App (which could lead to a chain halt). +**NOTE: we don't recommend using auto-download** because it doesn't verify in advance if a binary is available. If there will be any issue with downloading a binary, the cosmovisor will stop and won't restart the app (which could lead to a chain halt). -If `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `true`, and no local binary can be found when an upgrade is triggered, `cosmovisor` will attempt to download and install the binary itself based on the instructions in the `info` attribute in the `data/upgrade-info.json` file. The files is constructed by the x/upgrade module and contains data from the upgrade `Plan` object. The `Plan` has an info field that is expected to have one of the following two valid formats to specify a download: +If `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `true`, and no local binary can be found when an upgrade is triggered, `cosmovisor` will attempt to download and install the binary itself based on the instructions in the `info` attribute in the `data/upgrade-info.json` file. The file is constructed by the x/upgrade module and contains data from the upgrade `Plan` object. The `Plan` has an info field that is expected to have one of the following two valid formats to specify a download: 1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the `"binaries"` key. For example: diff --git a/docs/build/tooling/02-confix.md b/docs/build/tooling/02-confix.md index 00851ede1..ab91d3360 100644 --- a/docs/build/tooling/02-confix.md +++ b/docs/build/tooling/02-confix.md @@ -40,7 +40,7 @@ An implementation example can be found in `simapp`. The command will be available as `simd config`. :::tip -Using confix directly in the application can have less features than using it standalone. +Using confix directly in the application can have fewer features than using it standalone. This is because confix is versioned with the SDK, while `latest` is the standalone version. ::: @@ -126,7 +126,7 @@ confix diff v0.47 ~/.simapp/config/client.toml --client # gets the diff between ### View -View a configuration file, e.g: +View a configuration file, e.g.: ```shell simd config view client # views the current app client config diff --git a/docs/learn/advanced/00-baseapp.md b/docs/learn/advanced/00-baseapp.md index b24a570d7..8a3d3a7cf 100644 --- a/docs/learn/advanced/00-baseapp.md +++ b/docs/learn/advanced/00-baseapp.md @@ -257,14 +257,14 @@ Here is how the `PrepareProposal` function can be implemented: 1. Extract the `sdk.Msg`s from the transaction. 2. Perform _stateful_ checks by calling `Validate()` on each of the `sdk.Msg`'s. This is done after _stateless_ checks as _stateful_ checks are more computationally expensive. If `Validate()` fails, `PrepareProposal` returns before running further checks, which saves resources. -3. Perform any additional checks that are specific to the application, such as checking account balances, or ensuring that certain conditions are met before a transaction is proposed.hey are processed by the consensus engine, if necessary. +3. Perform any additional checks that are specific to the application, such as checking account balances, or ensuring that certain conditions are met before a transaction is proposed. They are processed by the consensus engine, if necessary. 4. Return the updated transactions to be processed by the consensus engine Note that, unlike `CheckTx()`, `PrepareProposal` process `sdk.Msg`s, so it can directly update the state. However, unlike `FinalizeBlock()`, it does not commit the state updates. It's important to exercise caution when using `PrepareProposal` as incorrect coding could affect the overall liveness of the network. 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.CheckTxResponse`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#processproposal). The response contains: +`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. @@ -291,7 +291,7 @@ 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.CheckTxResponse`](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.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. @@ -307,7 +307,7 @@ transaction is received by a full-node. The role of `CheckTx` is to guard the fu Unconfirmed transactions are relayed to peers only if they pass `CheckTx`. `CheckTx()` can perform both _stateful_ and _stateless_ checks, but developers should strive to -make the checks **lightweight** because gas fees are not charged for the resources (CPU, data load...) used during the `CheckTx`. +make the checks **lightweight** because gas fees are not charged for the resources (CPU, data load...) used during `CheckTx`. In the Cosmos SDK, after [decoding transactions](./05-encoding.md), `CheckTx()` is implemented to do the following checks: @@ -338,7 +338,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.CheckTxResponse`](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.ResponseCheckTx`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#checktx). The response contains: * `Code (uint32)`: Response Code. `0` if successful. @@ -368,11 +368,11 @@ This allows certain checks like signature verification can be skipped during `Ch ### RunTx -`RunTx` is called from `CheckTx`/`Finalizeblock` to handle the transaction, with `execModeCheck` or `execModeFinalize` as parameter to differentiate between the two modes of execution. Note that when `RunTx` receives a transaction, it has already been decoded. +`RunTx` is called from `CheckTx`/`FinalizeBlock` to handle the transaction, with `execModeCheck` or `execModeFinalize` as parameter to differentiate between the two modes of execution. Note that when `RunTx` receives a transaction, it has already been decoded. The first thing `RunTx` does upon being called is to retrieve the `context`'s `CacheMultiStore` by calling the `getContextForTx()` function with the appropriate mode (either `runTxModeCheck` or `execModeFinalize`). This `CacheMultiStore` is a branch of the main store, with cache functionality (for query requests), instantiated during `FinalizeBlock` for transaction execution and during the `Commit` of the previous block for `CheckTx`. After that, two `defer func()` are called for [`gas`](../beginner/04-gas-fees.md) management. They are executed when `runTx` returns and make sure `gas` is actually consumed, and will throw errors, if any. -After that, `RunTx()` calls `ValidateBasic()`, when available and for backward compatibility, on each `sdk.Msg`in the `Tx`, which runs preliminary _stateless_ validity checks. If any `sdk.Msg` fails to pass `ValidateBasic()`, `RunTx()` returns with an error. +After that, `RunTx()` calls `ValidateBasic()`, when available and for backward compatibility, on each `sdk.Msg` in the `Tx`, which runs preliminary _stateless_ validity checks. If any `sdk.Msg` fails to pass `ValidateBasic()`, `RunTx()` returns with an error. Then, the [`anteHandler`](#antehandler) of the application is run (if it exists). In preparation of this step, both the `checkState`/`finalizeBlockState`'s `context` and `context`'s `CacheMultiStore` are branched using the `cacheTxContext()` function. @@ -404,7 +404,7 @@ Click [here](../beginner/04-gas-fees.md#antehandler) for more on the `anteHandle ### RunMsgs -`RunMsgs` is called from `RunTx` with `runTxModeCheck` as parameter to check the existence of a route for each message the transaction, and with `execModeFinalize` to actually process the `sdk.Msg`s. +`RunMsgs` is called from `RunTx` with `runTxModeCheck` as parameter to check the existence of a route for each message in the transaction, and with `execModeFinalize` to actually process the `sdk.Msg`s. First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `type_url` of the Protobuf `Any` representing the `sdk.Msg`. Then, using the application's [`msgServiceRouter`](#msg-service-router), it checks for the existence of `Msg` service method related to that `type_url`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. Otherwise, if `mode == execModeFinalize`, the [`Msg` service](../../build/building-modules/03-msg-services.md) RPC is executed, before `RunMsgs` returns. @@ -432,12 +432,12 @@ The [`InitChain` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x * [`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. -Finally, the `InitChain(req abci.InitChainRequest)` method of `BaseApp` calls the [`initChainer()`](../beginner/00-app-anatomy.md#initchainer) of the application in order to initialize the main state of the application from the `genesis file` and, if defined, call the [`InitGenesis`](../../build/building-modules/08-genesis.md#initgenesis) function of each of the application's modules. +Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls the [`initChainer()`](../beginner/00-app-anatomy.md#initchainer) of the application in order to initialize the main state of the application from the `genesis file` and, if defined, call the [`InitGenesis`](../../build/building-modules/08-genesis.md#initgenesis) function of each of the application's modules. ### 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://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. In ABCI++, `FinalizeBlock` also returns the `app_hash` in its response, which represents the application state after processing all transactions in the block. ```go reference @@ -450,7 +450,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/baseapp/abci.go#L869 #### BeginBlock -* Initialize [`finalizeBlockState`](#state-updates) with the latest header using the `req abci.FinalizeBlockRequest` passed as parameter via the `setState` function. +* Initialize [`finalizeBlockState`](#state-updates) with the latest header using the `req abci.RequestFinalizeBlock` passed as parameter via the `setState` function. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/baseapp/baseapp.go#L746-L770 @@ -504,23 +504,25 @@ EndBlock is run after transaction execution completes. It allows developers to h https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/baseapp/baseapp.go#L811-L833 ``` +At the end of `FinalizeBlock`, the application returns a `ResponseFinalizeBlock` that includes the `app_hash` - the hash of the application state after all transactions in the block have been processed. This `app_hash` is computed from the `finalizeBlockState` and represents the state that will be committed when the block is finalized. The `app_hash` is made available earlier in the consensus process compared to the previous ABCI version, where it was only returned in `ResponseCommit`. + ### 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.CommitResponse)` 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://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. 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`. -Finally, `Commit` returns the hash of the commitment of `app.cms` back to the underlying consensus engine. This hash is used as a reference in the header of the next block. +Finally, the `app_hash` that was returned in `ResponseFinalizeBlock` is now used as a reference in the header of the next block, as it represents the committed state after all transactions in the current block have been processed. ### 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.InfoResponse)` 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://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`. ### 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). -Each CometBFT `query` comes with a `path`, which is a `string` which denotes what to query. If the `path` matches a gRPC fully-qualified service method, then `BaseApp` will defer the query to the `grpcQueryRouter` and let it handle it like explained [above](#grpc-query-router). Otherwise, the `path` represents a query that is not (yet) handled by the gRPC router. `BaseApp` splits the `path` string with the `/` delimiter. By convention, the first element of the split string (`split[0]`) contains the category of `query` (`app`, `p2p`, `store` or `custom` ). The `BaseApp` implementation of the `Query(req abci.QueryRequest)` method is a simple dispatcher serving these 4 main categories of queries: +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: * Application-related queries like querying the application's version, which are served via the `handleQueryApp` method. * Direct queries to the multistore, which are served by the `handlerQueryStore` method. These direct queries are different from custom queries which go through `app.queryRouter`, and are mainly used by third-party service provider like block explorers. diff --git a/docs/learn/advanced/01-transactions.md b/docs/learn/advanced/01-transactions.md index 725755637..965e8e8b6 100644 --- a/docs/learn/advanced/01-transactions.md +++ b/docs/learn/advanced/01-transactions.md @@ -99,7 +99,7 @@ If you wish to learn more, please refer to [ADR-050](../../build/architecture/ad #### Custom Sign modes -There is an opportunity to add your own custom sign mode to the Cosmos-SDK. While we can not accept the implementation of the sign mode to the repository, we can accept a pull request to add the custom signmode to the SignMode enum located [here](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/proto/cosmos/tx/signing/v1beta1/signing.proto#L17) +There is an opportunity to add your own custom sign mode to the Cosmos-SDK. While we cannot accept the implementation of the sign mode to the repository, we can accept a pull request to add the custom signmode to the SignMode enum located [here](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/proto/cosmos/tx/signing/v1beta1/signing.proto#L17) ## Transaction Process @@ -119,7 +119,7 @@ Module `sdk.Msg`s are not to be confused with [ABCI Messages](https://docs.comet **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`. -Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) RPC, defined inside each module's `tx.proto` file. A SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface. +Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) RPC, defined inside each module's `tx.proto` file. An SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface. This design puts more responsibility on module developers, allowing application developers to reuse common functionalities without having to implement state transition logic repetitively. To learn more about Protobuf `Msg` services and how to implement `MsgServer`, click [here](../../build/building-modules/03-msg-services.md). @@ -226,4 +226,4 @@ Senders must use a unique timestamp for each distinct transaction. The differenc These unique timestamps serve as a one-shot nonce, and their lifespan in state is short-lived. Upon transaction inclusion, an entry consisting of timeout timestamp and account address will be recorded to state. -Once the block time is passed the timeout timestamp value, the entry will be removed. This ensures that unordered nonces do not indefinitely fill up the chain's storage. +Once the block time passes the timeout timestamp value, the entry will be removed. This ensures that unordered nonces do not indefinitely fill up the chain's storage. diff --git a/docs/learn/advanced/02-context.md b/docs/learn/advanced/02-context.md index 578bb1f1b..1a6deb284 100644 --- a/docs/learn/advanced/02-context.md +++ b/docs/learn/advanced/02-context.md @@ -64,7 +64,7 @@ explicitly pass a context `ctx` as the first argument of a process. The `Context` contains a `MultiStore`, which allows for branching and caching functionality using `CacheMultiStore` (queries in `CacheMultiStore` are cached to avoid future round trips). -Each `KVStore` is branched in a safe and isolated ephemeral storage. Processes are free to write changes to +Each `KVStore` is branched into safe and isolated ephemeral storage. Processes are free to write changes to the `CacheMultiStore`. If a state-transition sequence is performed without issue, the store branch can be committed to the underlying store at the end of the sequence or disregard them if something goes wrong. The pattern of usage for a Context is as follows: diff --git a/docs/learn/advanced/03-node.md b/docs/learn/advanced/03-node.md index 375dedb06..980a6cc10 100644 --- a/docs/learn/advanced/03-node.md +++ b/docs/learn/advanced/03-node.md @@ -55,7 +55,7 @@ simd start As a reminder, the full-node is composed of three conceptual layers: the networking layer, the consensus layer and the application layer. The first two are generally bundled together in an entity called the consensus engine (CometBFT by default), while the third is the state-machine defined with the help of the Cosmos SDK. Currently, the Cosmos SDK uses CometBFT as the default consensus engine, meaning the start command is implemented to boot up a CometBFT node. -The flow of the `start` command is pretty straightforward. First, it retrieves the `config` from the `context` in order to open the `db` (a [`leveldb`](https://github.com/syndtr/goleveldb) instance by default). This `db` contains the latest known state of the application (empty if the application is started from the first time. +The flow of the `start` command is pretty straightforward. First, it retrieves the `config` from the `context` in order to open the `db` (a [`leveldb`](https://github.com/syndtr/goleveldb) instance by default). This `db` contains the latest known state of the application (empty if the application is started for the first time). With the `db`, the `start` command creates a new instance of the application using an `appCreator` function: @@ -89,7 +89,7 @@ Once the CometBFT node is instantiated and in sync with the application, the nod https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/server/start.go#L373-L374 ``` -Upon starting, the node will bootstrap its RPC and P2P server and start dialing peers. During handshake with its peers, if the node realizes they are ahead, it will query all the blocks sequentially in order to catch up. Then, it will wait for new block proposals and block signatures from validators in order to make progress. +Upon starting, the node will bootstrap its RPC and P2P server and start dialing peers. During the handshake with its peers, if the node realizes they are ahead, it will query all the blocks sequentially in order to catch up. Then, it will wait for new block proposals and block signatures from validators in order to make progress. ## Other commands diff --git a/docs/learn/advanced/04-store.md b/docs/learn/advanced/04-store.md index 860bb3d02..248d02e05 100644 --- a/docs/learn/advanced/04-store.md +++ b/docs/learn/advanced/04-store.md @@ -72,7 +72,7 @@ The `GetStoreType` is a simple method that returns the type of store, whereas a https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/store/types/store.go#L285-L317 ``` -Branching and cache is used ubiquitously in the Cosmos SDK and required to be implemented on every store type. A storage branch creates an isolated, ephemeral branch of a store that can be passed around and updated without affecting the main underlying store. This is used to trigger temporary state-transitions that may be reverted later should an error occur. Read more about it in [context](./02-context.md#Store-branching) +Branching and caching are used ubiquitously in the Cosmos SDK and required to be implemented on every store type. A storage branch creates an isolated, ephemeral branch of a store that can be passed around and updated without affecting the main underlying store. This is used to trigger temporary state-transitions that may be reverted later should an error occur. Read more about it in [context](./02-context.md#Store-branching) ### Commit Store diff --git a/docs/learn/advanced/05-encoding.md b/docs/learn/advanced/05-encoding.md index 3c7307417..e1cbf7c36 100644 --- a/docs/learn/advanced/05-encoding.md +++ b/docs/learn/advanced/05-encoding.md @@ -16,7 +16,7 @@ While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, ## Encoding -The Cosmos SDK utilizes two binary wire encoding protocols, [Amino](https://github.com/tendermint/go-amino/) which is an object encoding specification and [Protocol Buffers](https://developers.google.com/protocol-buffers), a subset of Proto3 with an extension for +The Cosmos SDK utilizes two binary wire encoding protocols: [Amino](https://github.com/tendermint/go-amino/) which is an object encoding specification and [Protocol Buffers](https://developers.google.com/protocol-buffers), a subset of Proto3 with an extension for interface support. See the [Proto3 spec](https://developers.google.com/protocol-buffers/docs/proto3) for more information on Proto3, which Amino is largely compatible with (but not with Proto2). @@ -38,7 +38,7 @@ is used for business logic in the state-machine where they may convert back-n-fo Note, the Amino-based types may slowly be phased-out in the future, so developers should take note to use the protobuf message definitions where possible. -In the `codec` package, there exists two core interfaces, `BinaryCodec` and `JSONCodec`, +In the `codec` package, there exist two core interfaces, `BinaryCodec` and `JSONCodec`, where the former encapsulates the current Amino interface except it operates on types implementing the latter instead of generic `interface{}` types. @@ -257,7 +257,7 @@ without any further customization. However, if a module type composes an interface, it must wrap it in the `sdk.Any` (from `/types` package) type. To do that, a module-level .proto file must use [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto) for respective message type interface types. -For example, in the `x/evidence` module defines an `Evidence` interface, which is used by the `MsgSubmitEvidence`. The structure definition must use `sdk.Any` to wrap the evidence file. In the proto file we define it as follows: +For example, the `x/evidence` module defines an `Evidence` interface, which is used by the `MsgSubmitEvidence`. The structure definition must use `sdk.Any` to wrap the evidence file. In the proto file we define it as follows: ```protobuf // proto/cosmos/evidence/v1beta1/tx.proto diff --git a/docs/learn/advanced/06-grpc_rest.md b/docs/learn/advanced/06-grpc_rest.md index d3ab827a7..a9c47db4e 100644 --- a/docs/learn/advanced/06-grpc_rest.md +++ b/docs/learn/advanced/06-grpc_rest.md @@ -69,7 +69,7 @@ If, for various reasons, you cannot use gRPC (for example, you are building a we https://github.com/cosmos/cosmos-sdk/blob/v0.53.0-rc.2/proto/cosmos/bank/v1beta1/query.proto#L23-L30 ``` -For application developers, gRPC-gateway REST routes needs to be wired up to the REST server, this is done by calling the `RegisterGRPCGatewayRoutes` function on the ModuleManager. +For application developers, gRPC-gateway REST routes need to be wired up to the REST server, this is done by calling the `RegisterGRPCGatewayRoutes` function on the ModuleManager. ### Swagger diff --git a/docs/learn/advanced/07-cli.md b/docs/learn/advanced/07-cli.md index cd9e34ded..ee18dfc52 100644 --- a/docs/learn/advanced/07-cli.md +++ b/docs/learn/advanced/07-cli.md @@ -38,7 +38,7 @@ The `main.go` file needs to have a `main()` function that creates a root command * **setting configurations** by reading in configuration files (e.g. the Cosmos SDK config file). * **adding any flags** to it, such as `--chain-id`. * **instantiating the `codec`** by injecting the application codecs. The [`codec`](./05-encoding.md) is used to encode and decode data structures for the application - stores can only persist `[]byte`s so the developer must define a serialization format for their data structures or use the default, Protobuf. -* **adding subcommand** for all the possible user interactions, including [transaction commands](#transaction-commands) and [query commands](#query-commands). +* **adding subcommands** for all the possible user interactions, including [transaction commands](#transaction-commands) and [query commands](#query-commands). The `main()` function finally creates an executor and [execute](https://pkg.go.dev/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application: @@ -145,7 +145,7 @@ Read more about [AutoCLI](https://docs.cosmos.network/main/core/autocli) in its ## Flags -Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their [`app.toml`](../../user/run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with. +Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them inside their [`app.toml`](../../user/run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with. A *persistent* flag (as opposed to a *local* flag) added to a command transcends all of its children: subcommands will inherit the configured values for these flags. Additionally, all flags have default values when they are added to commands; some toggle an option off but others are empty values that the user needs to override to create valid commands. A flag can be explicitly marked as *required* so that an error is automatically thrown if the user does not provide a value, but it is also acceptable to handle unexpected missing flags differently. @@ -153,7 +153,7 @@ Flags are added to commands directly (generally in the [module's CLI file](../.. ## Environment variables -Each flag is bound to its respective named environment variable. The name of the environment variable consist of two parts - capital case `basename` followed by flag name of the flag. `-` must be substituted with `_`. For example flag `--node` for application with basename `GAIA` is bound to `GAIA_NODE`. It allows reducing the amount of flags typed for routine operations. For example instead of: +Each flag is bound to its respective named environment variable. The name of the environment variable consists of two parts - capital case `basename` followed by flag name of the flag. `-` must be substituted with `_`. For example flag `--node` for application with basename `GAIA` is bound to `GAIA_NODE`. It allows reducing the amount of flags typed for routine operations. For example instead of: ```shell gaia --home=./ --node= --chain-id="testchain-1" --keyring-backend=test tx ... --from= diff --git a/docs/learn/advanced/08-events.md b/docs/learn/advanced/08-events.md index 52d026416..9a5d11956 100644 --- a/docs/learn/advanced/08-events.md +++ b/docs/learn/advanced/08-events.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Events :::note Synopsis -`Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. +`Event`s are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallets to track the execution of various messages and index transactions. ::: :::note Pre-requisite Readings @@ -26,7 +26,7 @@ https://github.com/cometbft/cometbft/blob/v0.37.0/proto/tendermint/abci/types.pr An Event contains: * A `type` to categorize the Event at a high-level; for example, the Cosmos SDK uses the `"message"` type to filter Events by `Msg`s. -* A list of `attributes` are key-value pairs that give more information about the categorized Event. For example, for the `"message"` type, we can filter Events by key-value pairs using `message.action={some_action}`, `message.module={some_module}` or `message.sender={some_sender}`. +* A list of `attributes` that are key-value pairs that give more information about the categorized Event. For example, for the `"message"` type, we can filter Events by key-value pairs using `message.action={some_action}`, `message.module={some_module}` or `message.sender={some_sender}`. * A `msg_index` to identify which messages relate to the same transaction :::tip @@ -39,7 +39,7 @@ _Legacy Events_ are defined on a **per-module basis** in the module's `/types/ev They are triggered from the module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) by using the [`EventManager`](#eventmanager). -In addition, each module documents its events under in the `Events` sections of its specs (x/{moduleName}/`README.md`). +In addition, each module documents its events in the `Events` sections of its specs (x/{moduleName}/`README.md`). Lastly, Events are returned to the underlying consensus engine in the response of the following ABCI messages: @@ -155,5 +155,5 @@ There are a few events that are automatically emitted for all messages, directly :::tip The module name is assumed by `baseapp` to be the second element of the message route: `"cosmos.bank.v1beta1.MsgSend" -> "bank"`. In case a module does not follow the standard message path, (e.g. IBC), it is advised to keep emitting the module name event. -`Baseapp` only emits that event if the module have not already done so. +`Baseapp` only emits that event if the module has not already done so. ::: diff --git a/docs/learn/advanced/09-telemetry.md b/docs/learn/advanced/09-telemetry.md index 14d1aa7c4..f437fabd1 100644 --- a/docs/learn/advanced/09-telemetry.md +++ b/docs/learn/advanced/09-telemetry.md @@ -13,7 +13,7 @@ their application through the use of the `telemetry` package. To enable telemetr The Cosmos SDK currently supports enabling in-memory and prometheus as telemetry sinks. In-memory sink is always attached (when the telemetry is enabled) with 10 second interval and 1 minute retention. This means that metrics will be aggregated over 10 seconds, and metrics will be kept alive for 1 minute. -To query active metrics (see retention note above) you have to enable API server (`api.enabled = true` in the app.toml). Single API endpoint is exposed: `http://localhost:1317/metrics?format={text|prometheus}`, the default being `text`. +To query active metrics (see retention note above) you have to enable API server (`api.enabled = true` in the app.toml). A single API endpoint is exposed: `http://localhost:1317/metrics?format={text|prometheus}`, the default being `text`. ## Emitting metrics diff --git a/docs/learn/advanced/11-runtx_middleware.md b/docs/learn/advanced/11-runtx_middleware.md index bb8c04aad..3a23c6ac9 100644 --- a/docs/learn/advanced/11-runtx_middleware.md +++ b/docs/learn/advanced/11-runtx_middleware.md @@ -4,11 +4,11 @@ sidebar_position: 1 # RunTx recovery middleware -`BaseApp.runTx()` function handles Go panics that might occur during transactions execution, for example, keeper has faced an invalid state and panicked. +`BaseApp.runTx()` function handles Go panics that might occur during transaction execution, for example, a keeper faces an invalid state and panics. 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.53.0-rc.2/baseapp/recovery.go). +More context can be 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.53.0-rc.2/baseapp/recovery.go). ## Interface @@ -45,7 +45,7 @@ func (k FooKeeper) Do(obj interface{}) { } ``` -By default that panic would be recovered and an error message will be printed to log. To override that behavior we should register a custom RecoveryHandler: +By default that panic would be recovered and an error message will be printed to the log. To override that behavior we should register a custom RecoveryHandler: ```go // Cosmos SDK application constructor diff --git a/docs/learn/advanced/12-simulation.md b/docs/learn/advanced/12-simulation.md index 709ce176c..2fb59545d 100644 --- a/docs/learn/advanced/12-simulation.md +++ b/docs/learn/advanced/12-simulation.md @@ -48,7 +48,7 @@ In addition to the various inputs and commands, the simulator runs in three mode 1. Completely random where the initial state, module parameters and simulation parameters are **pseudo-randomly generated**. 2. From a `genesis.json` file where the initial state and the module parameters are defined. - This mode is helpful for running simulations on a known state such as a live network export where a new (mostly likely breaking) version of the application needs to be tested. + This mode is helpful for running simulations on a known state such as a live network export where a new (most likely breaking) version of the application needs to be tested. 3. From a `params.json` file where the initial state is pseudo-randomly generated but the module and simulation parameters can be provided manually. This allows for a more controlled and deterministic simulation setup while allowing the state space to still be pseudo-randomly simulated. The list of available parameters are listed [here](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0-rc.2/x/simulation/client/cli/flags.go#L72-L90). diff --git a/docs/learn/advanced/15-upgrade.md b/docs/learn/advanced/15-upgrade.md index e2332bd1c..46c84d2be 100644 --- a/docs/learn/advanced/15-upgrade.md +++ b/docs/learn/advanced/15-upgrade.md @@ -48,7 +48,7 @@ Inside these functions, you must perform any upgrade logic to include in the pro ## Running Migrations -Migrations are run inside of an `UpgradeHandler` using `app.mm.RunMigrations(ctx, cfg, vm)`. The `UpgradeHandler` functions describe the functionality to occur during an upgrade. The `RunMigration` function loops through the `VersionMap` argument and runs the migration scripts for all versions that are less than the versions of the new binary app module. After the migrations are finished, a new `VersionMap` is returned to persist the upgraded module versions to state. +Migrations are run inside of an `UpgradeHandler` using `app.mm.RunMigrations(ctx, cfg, vm)`. The `UpgradeHandler` functions describe the functionality to occur during an upgrade. The `RunMigrations` function loops through the `VersionMap` argument and runs the migration scripts for all versions that are less than the versions of the new binary app module. After the migrations are finished, a new `VersionMap` is returned to persist the upgraded module versions to state. ```go cfg := module.NewConfigurator(...) @@ -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.InitChainRequest) abci.InitChainResponse { +func (app *MyApp) InitChainer(ctx sdk.Context, req abci.RequestInitChain) abci.ResponseInitChain { ... + app.UpgradeKeeper.SetModuleVersionMap(ctx, app.mm.GetVersionMap()) ... @@ -157,6 +157,6 @@ app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgrad You can sync a full node to an existing blockchain which has been upgraded using Cosmovisor -To successfully sync, you must start with the initial binary that the blockchain started with at genesis. If all Software Upgrade Plans contain binary instruction, then you can run Cosmovisor with auto-download option to automatically handle downloading and switching to the binaries associated with each sequential upgrade. Otherwise, you need to manually provide all binaries to Cosmovisor. +To successfully sync, you must start with the initial binary that the blockchain started with at genesis. If all Software Upgrade Plans contain binary instructions, then you can run Cosmovisor with auto-download option to automatically handle downloading and switching to the binaries associated with each sequential upgrade. Otherwise, you need to manually provide all binaries to Cosmovisor. To learn more about Cosmovisor, see the [Cosmovisor Quick Start](../../../../tools/cosmovisor/README.md). diff --git a/docs/learn/beginner/01-tx-lifecycle.md b/docs/learn/beginner/01-tx-lifecycle.md index b004b355b..b2e821e9f 100644 --- a/docs/learn/beginner/01-tx-lifecycle.md +++ b/docs/learn/beginner/01-tx-lifecycle.md @@ -71,9 +71,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.37/spec/p2p/legacy-docs/messages/), -`CheckTx`, 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/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/v0.37/spec/p2p/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/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. ### Types of Checks @@ -98,7 +98,7 @@ through several steps, beginning with decoding `Tx`. ### Decoding -When `Tx` is received by the application from the underlying consensus engine (e.g. CometBFT), it is still in its [encoded](../advanced/05-encoding.md) `[]byte` form and needs to be unmarshaled in order to be processed. Then, the [`runTx`](../advanced/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) function is called to run in `runTxModeCheck` mode, meaning the function runs all checks but exits before executing messages and writing state changes. +When `Tx` is received by the application from the underlying consensus engine (e.g. CometBFT ), it is still in its [encoded](../advanced/05-encoding.md) `[]byte` form and needs to be unmarshaled in order to be processed. Then, the [`runTx`](../advanced/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) function is called to run in `runTxModeCheck` mode, meaning the function runs all checks but exits before executing messages and writing state changes. ### ValidateBasic (deprecated) @@ -113,7 +113,7 @@ Read [RFC 001](https://docs.cosmos.network/main/rfc/rfc-001-tx-validation) for m ::: :::note -`BaseApp` still calls `ValidateBasic` on messages that implement that method for backwards compatibility. +`BaseApp` still calls `ValidateBasic` on messages that implements that method for backwards compatibility. ::: #### Guideline @@ -126,10 +126,10 @@ Read [RFC 001](https://docs.cosmos.network/main/rfc/rfc-001-tx-validation) for m A copy of the cached context is provided to the `AnteHandler`, which performs limited checks specified for the transaction type. Using a copy allows the `AnteHandler` to do stateful checks for `Tx` without modifying the last committed state, and revert back to the original if the execution fails. -For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/blob/main/x/auth/README.md) module `AnteHandler` checks and increments sequence numbers, checks signatures and account numbers, and deducts fees from the first signer of the transaction - all state changes are made using the `checkState`. +For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module `AnteHandler` checks and increments sequence numbers, checks signatures and account numbers, and deducts fees from the first signer of the transaction - all state changes are made using the `checkState`. :::warning -Ante handlers only run on a transaction. If a transaction embeds multiple messages (like some x/authz, x/gov transactions for instance), the ante handlers only have awareness of the outer message. Inner messages are mostly directly routed to the [message router](https://docs.cosmos.network/main/learn/advanced/baseapp#msg-service-router) and will skip the chain of ante handlers. Keep that in mind when designing your own ante handler. +Ante handlers only run on a transaction. If a transaction embed multiple messages (like some x/authz, x/gov transactions for instance), the ante handlers only have awareness of the outer message. Inner messages are mostly directly routed to the [message router](https://docs.cosmos.network/main/learn/advanced/baseapp#msg-service-router) and will skip the chain of ante handlers. Keep that in mind when designing your own ante handler. ::: ### Gas @@ -230,7 +230,7 @@ to during consensus. Under the hood, transaction execution is almost identical t Instead of using their `checkState`, full-nodes use `finalizeblock`: * **Decoding:** Since `FinalizeBlock` is an ABCI call, `Tx` is received in the encoded `[]byte` form. - Nodes first unmarshal the transaction, using the [`TxConfig`](./00-app-anatomy.md#register-codec) defined in the app, then call `runTx` in `execModeFinalize`, which is very similar to `CheckTx` but also executes and writes state changes. + Nodes first unmarshal the transaction, using the [`TxConfig`](./app-anatomy#register-codec) defined in the app, then call `runTx` in `execModeFinalize`, which is very similar to `CheckTx` but also executes and writes state changes. * **Checks and `AnteHandler`:** Full-nodes call `validateBasicMsgs` and `AnteHandler` again. This second check happens because they may not have seen the same transactions during the addition to Mempool stage diff --git a/docs/learn/beginner/02-query-lifecycle.md b/docs/learn/beginner/02-query-lifecycle.md index 4b11bfed6..c3d7eb1cc 100644 --- a/docs/learn/beginner/02-query-lifecycle.md +++ b/docs/learn/beginner/02-query-lifecycle.md @@ -17,7 +17,7 @@ This document describes the lifecycle of a query in a Cosmos SDK application, fr A [**query**](../../build/building-modules/02-messages-and-queries.md#queries) is a request for information made by end-users of applications through an interface and processed by a full-node. Users can query information about the network, the application itself, and application state directly from the application's stores or modules. Note that queries are different from [transactions](../advanced/01-transactions.md) (view the lifecycle [here](./01-tx-lifecycle.md)), particularly in that they do not require consensus to be processed (as they do not trigger state-transitions); they can be fully handled by one full-node. -For the purpose of explaining the query lifecycle, let's say the query, `MyQuery`, is requesting a list of delegations made by a certain delegator address in the application called `simapp`. As is to be expected, the [`staking`](../../../../x/staking/README.md) module handles this query. But first, there are a few ways `MyQuery` can be created by users. +For the purpose of explaining the query lifecycle, let's say the query, `MyQuery`, is requesting a list of delegations made by a certain delegator address in the application called `simapp`. As is to be expected, the [`staking`](../../build/modules/staking/README.md) module handles this query. But first, there are a few ways `MyQuery` can be created by users. ### CLI @@ -27,7 +27,7 @@ The main interface for an application is the command-line interface. Users conne simd query staking delegations ``` -This query command was defined by the [`staking`](../../../../x/staking/README.md) module developer and added to the list of subcommands by the application developer when creating the CLI. +This query command was defined by the [`staking`](../../build/modules/staking/README.md) module developer and added to the list of subcommands by the application developer when creating the CLI. Note that the general format is as follows: @@ -47,7 +47,7 @@ One such tool is [grpcurl](https://github.com/fullstorydev/grpcurl), and a gRPC ```bash grpcurl \ - -plaintext # We want results in plain text + -plaintext # We want results in plain test -import-path ./proto \ # Import these .proto files -proto ./proto/cosmos/staking/v1beta1/query.proto \ # Look into this .proto file for the Query protobuf service -d '{"address":"$MY_DELEGATOR"}' \ # Query arguments @@ -74,9 +74,9 @@ The preceding examples show how an external user can interact with a node by que The first thing that is created in the execution of a CLI command is a `client.Context`. A `client.Context` is an object that stores all the data needed to process a request on the user side. In particular, a `client.Context` stores the following: * **Codec**: The [encoder/decoder](../advanced/05-encoding.md) used by the application, used to marshal the parameters and query before making the CometBFT RPC request and unmarshal the returned response into a JSON object. The default codec used by the CLI is Protobuf. -* **Account Decoder**: The account decoder from the [`auth`](../../../../x/auth/README.md) module, which translates `[]byte`s into accounts. +* **Account Decoder**: The account decoder from the [`auth`](../../build/modules/auth/README.md) module, which translates `[]byte`s into accounts. * **RPC Client**: The CometBFT RPC Client, or node, to which requests are relayed. -* **Keyring**: A [Key Manager](../beginner/03-accounts.md#keyring) used to sign transactions and handle other operations with keys. +* **Keyring**: A [Key Manager]../beginner/03-accounts.md#keyring) used to sign transactions and handle other operations with keys. * **Output Writer**: A [Writer](https://pkg.go.dev/io/#Writer) used to output the response. * **Configurations**: The flags configured by the user for this command, including `--height`, specifying the height of the blockchain to query, and `--indent`, which indicates to add an indent to the JSON response. @@ -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.QueryResponse`](https://docs.cometbft.com/main/spec/abci/abci++_methods#query) type. The `client.Context` `Query()` routine receives the response and processes it. +Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci.ResponseQuery`](https://docs.cometbft.com/master/spec/abci/abci.html#query-2) type. The `client.Context` `Query()` routine receives the response and. ### CLI Response