diff --git a/docs/build/abci/01-prepare-proposal.md b/docs/build/abci/01-prepare-proposal.md index b1c6eb8a5..b2d85c888 100644 --- a/docs/build/abci/01-prepare-proposal.md +++ b/docs/build/abci/01-prepare-proposal.md @@ -26,7 +26,7 @@ The Cosmos SDK defines the `DefaultProposalHandler` type, which provides applica `PrepareProposal` and `ProcessProposal` handlers. If you decide to implement your own `PrepareProposal` handler, you must ensure that the transactions selected DO NOT exceed the maximum block gas (if set) and the maximum bytes provided -by `req.MaxBytes`. +by `req.MaxTxBytes`. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/baseapp/abci_utils.go diff --git a/docs/build/abci/03-vote-extensions.md b/docs/build/abci/03-vote-extensions.md index a57395e30..900ab5fe0 100644 --- a/docs/build/abci/03-vote-extensions.md +++ b/docs/build/abci/03-vote-extensions.md @@ -8,10 +8,10 @@ defined in ABCI++. ## Extend Vote ABCI 2.0 (colloquially called ABCI++) allows an application to extend a pre-commit vote with arbitrary data. This process does NOT have to be deterministic, and the data returned can be unique to the -validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/types/abci.go#L32): +validator process. The Cosmos SDK defines [`sdk.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` @@ -49,7 +49,7 @@ validators will share the same view of what vote extensions they verify dependin on how votes are propagated. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#verifyvoteextension) for more details. -Additionally, please keep in mind that performance can be degraded if vote extensions are too big (https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed), so we highly recommend a size validation in `VerifyVoteExtensions`. +Additionally, please keep in mind that performance can be degraded if vote extensions are too big (https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed), so we highly recommend a size validation in `ValidateVoteExtensions`. ## Vote Extension Propagation @@ -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) (*sdk.ResponsePreBlock, 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 @@ -95,10 +95,10 @@ app.SetPreBlocker(func(ctx sdk.Context, req *abci.FinalizeBlockRequest) error { result := compute(allVEs) err := storeVEResult(ctx, result) if err != nil { - return err + return nil, err } - return nil + return &sdk.ResponsePreBlock{}, nil }) ``` diff --git a/docs/build/abci/04-checktx.md b/docs/build/abci/04-checktx.md index 081d6fd24..6deb7d781 100644 --- a/docs/build/abci/04-checktx.md +++ b/docs/build/abci/04-checktx.md @@ -20,17 +20,15 @@ https://github.com/cosmos/cosmos-sdk/blob/31c604762a434c7b676b6a89897ecbd7c4653a ## CheckTx Handler -`CheckTxHandler` allows users to extend the logic of `CheckTx`. `CheckTxHandler` is called by passing context and the transaction bytes received through ABCI. It is required that the handler returns deterministic results given the same transaction bytes. - -:::note -we return the raw decoded transaction here to avoid decoding it twice. -::: +`CheckTxHandler` allows applications to extend the logic of `CheckTx`. It is invoked with the ABCI request and a `RunTx` function that executes the standard `CheckTx` pipeline (ante handlers, gas accounting and mempool interaction). The implementation of `CheckTxHandler` MUST be deterministic for a given `RequestCheckTx`. ```go -type CheckTxHandler func(ctx sdk.Context, tx []byte) (Tx, error) +type CheckTxHandler func(RunTx, *abci.RequestCheckTx) (*abci.ResponseCheckTx, error) ``` -Setting a custom `CheckTxHandler` is optional. It can be done from your app.go file: +The provided `RunTx` function does not override ante handlers and does not allow changing the execution mode; it simply runs the transaction through the normal `CheckTx` path and returns the result that can be used to construct a `ResponseCheckTx`. + +Setting a custom `CheckTxHandler` is optional. It can be done from your `app.go` file by setting the handler on `BaseApp`: ```go func NewSimApp( @@ -41,10 +39,16 @@ func NewSimApp( appOpts servertypes.AppOptions, baseAppOptions ...func(*baseapp.BaseApp), ) *SimApp { - ... - // Create ChecktxHandler - checktxHandler := abci.NewCustomCheckTxHandler(...) - app.SetCheckTxHandler(checktxHandler) - ... + ... + checkTxOpt := func(app *baseapp.BaseApp) { + app.SetCheckTxHandler(func(runTx sdk.RunTx, req *abci.RequestCheckTx) (*abci.ResponseCheckTx, error) { + // custom pre- or post-processing logic can be added here + return runTx(req.Tx, nil) + }) + } + baseAppOptions = append(baseAppOptions, checkTxOpt) + ... } ``` + +When `RequestCheckTx.Type` is `abci.CheckTxType_New`, the transaction is evaluated for admission into the mempool; when it is `abci.CheckTxType_Recheck`, the existing mempool transaction is re-evaluated and may be removed if it no longer passes validation. Successful `CheckTx` executions update an internal CheckTx state, which is reset when a block is committed. diff --git a/docs/build/architecture/adr-006-secret-store-replacement.md b/docs/build/architecture/adr-006-secret-store-replacement.md index 500ba40ca..61b15fb35 100644 --- a/docs/build/architecture/adr-006-secret-store-replacement.md +++ b/docs/build/architecture/adr-006-secret-store-replacement.md @@ -15,7 +15,7 @@ This is not desirable for a number of reasons. Perhaps the biggest reason is ins All modern desktop computers OS (Ubuntu, Debian, MacOS, Windows) provide a built-in secret store that is designed to allow applications to store information that is isolated from all other applications and requires passphrase entry to access the data. -We are seeking solution that provides a common abstraction layer to the many different backends and reasonable fallback for minimal platforms that don’t provide a native secret store. +We are seeking a solution that provides a common abstraction layer to the many different backends and reasonable fallback for minimal platforms that don’t provide a native secret store. ## Decision diff --git a/docs/build/architecture/adr-013-metrics.md b/docs/build/architecture/adr-013-metrics.md index b0808d462..830fa754e 100644 --- a/docs/build/architecture/adr-013-metrics.md +++ b/docs/build/architecture/adr-013-metrics.md @@ -10,13 +10,13 @@ Proposed ## Context -Telemetry is paramount into debugging and understanding what the application is doing and how it is +Telemetry is paramount to debugging and understanding what the application is doing and how it is performing. We aim to expose metrics from modules and other core parts of the Cosmos SDK. In addition, we should aim to support multiple configurable sinks that an operator may choose from. By default, when telemetry is enabled, the application should track and expose metrics that are stored in-memory. The operator may choose to enable additional sinks, where we support only -[Prometheus](https://prometheus.io/) for now, as it's battle-tested, simple to setup, open source, +[Prometheus](https://prometheus.io/) for now, as it's battle-tested, simple to set up, open source, and is rich with ecosystem tooling. We must also aim to integrate metrics into the Cosmos SDK in the most seamless way possible such that @@ -41,7 +41,7 @@ We will add an additional configuration block to `app.toml` that defines telemet service-name = {{ .Telemetry.ServiceName }} # Enabled enables the application telemetry functionality. When enabled, -# an in-memory sink is also enabled by default. Operators may also enabled +# an in-memory sink is also enabled by default. Operators may also enable # other sinks such as Prometheus. enabled = {{ .Telemetry.Enabled }} diff --git a/docs/build/architecture/adr-022-custom-panic-handling.md b/docs/build/architecture/adr-022-custom-panic-handling.md index a99868b27..c64d4467c 100644 --- a/docs/build/architecture/adr-022-custom-panic-handling.md +++ b/docs/build/architecture/adr-022-custom-panic-handling.md @@ -26,8 +26,8 @@ It will also make `OutOfGas` case and `default` case one of the middlewares. `Default` case wraps recovery object to an error and logs it ([example middleware implementation](#recovery-middleware)). Our project has a sidecar service running alongside the blockchain node (smart contracts virtual machine). It is -essential that node <-> sidecar connectivity stays stable for TXs processing. So when the communication breaks we need -to crash the node and reboot it once the problem is solved. That behaviour makes the node's state machine execution +essential that node <-> sidecar connectivity stays stable for TXs processing. So when the communication breaks, we need +to crash the node and reboot it once the problem is solved. That behavior makes the node's state machine execution deterministic. As all keeper panics are caught by runTx's `defer()` handler, we have to adjust the BaseApp code in order to customize it. @@ -97,7 +97,7 @@ Function receives a `recoveryObj` object and returns: * (next `recoveryMiddleware`, `nil`) if object wasn't handled (not a target type) by `RecoveryHandler`; * (`nil`, not nil `error`) if input object was handled and other middlewares in the chain should not be executed; * (`nil`, `nil`) in case of invalid behavior. Panic recovery might not have been properly handled; -this can be avoided by always using a `default` as a rightmost middleware in the chain (always returns an `error`'); +this can be avoided by always using a `default` as a rightmost middleware in the chain (always returns an `error`); `OutOfGas` middleware example: @@ -153,7 +153,7 @@ That way we can create a middleware chain which is executed from left to right, ##### BaseApp changes -The `default` middleware chain must exist in a `BaseApp` object. `Baseapp` modifications: +The `default` middleware chain must exist in a `BaseApp` object. `BaseApp` modifications: ```go type BaseApp struct { 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..a2768ca7a 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. @@ -192,7 +192,7 @@ The presented workaround can be used until the IBC module is fully upgraded to s We consider a compression of prefix keys by creating a mapping from module key to an integer, and serializing the integer using varint coding. Varint coding assures that different values don't have common byte prefix. For Merkle Proofs we can't use prefix compression - so it should only apply for the `SS` keys. Moreover, the prefix compression should be only applied for the module namespace. More precisely: -* each module has it's own namespace; +* each module has its own namespace; * when accessing a module namespace we create a KVStore with embedded prefix; * that prefix will be compressed only when accessing and managing `SS`. @@ -279,7 +279,7 @@ We were discussing use case where modules can use a support database, which is n ## References * [IAVL What's Next?](https://github.com/cosmos/cosmos-sdk/issues/7100) -* [IAVL overview](https://docs.google.com/document/d/16Z_hW2rSAmoyMENO-RlAhQjAG3mSNKsQueMnKpmcBv0/edit#heading=h.yd2th7x3o1iv) of it's state v0.15 +* [IAVL overview](https://docs.google.com/document/d/16Z_hW2rSAmoyMENO-RlAhQjAG3mSNKsQueMnKpmcBv0/edit#heading=h.yd2th7x3o1iv) of its state v0.15 * [State commitments and storage report](https://paper.dropbox.com/published/State-commitments-and-storage-review--BDvA1MLwRtOx55KRihJ5xxLbBw-KeEB7eOd11pNrZvVtqUgL3h) * [Celestia (LazyLedger) SMT](https://github.com/lazyledger/smt) * Facebook Diem (Libra) SMT [design](https://developers.diem.com/papers/jellyfish-merkle-tree/2021-01-14.pdf) diff --git a/docs/build/architecture/adr-045-check-delivertx-middlewares.md b/docs/build/architecture/adr-045-check-delivertx-middlewares.md index f55c21598..33e8add76 100644 --- a/docs/build/architecture/adr-045-check-delivertx-middlewares.md +++ b/docs/build/architecture/adr-045-check-delivertx-middlewares.md @@ -30,7 +30,7 @@ The two following interfaces are the base of the middleware design, and are defi type Handler interface { CheckTx(ctx context.Context, req Request, checkReq RequestCheckTx) (Response, ResponseCheckTx, error) DeliverTx(ctx context.Context, req Request) (Response, error) - SimulateTx(ctx context.Context, req Request (Response, error) + SimulateTx(ctx context.Context, req Request) (Response, error) } type Middleware func(Handler) Handler diff --git a/docs/build/architecture/adr-048-consensus-fees.md b/docs/build/architecture/adr-048-consensus-fees.md index 6fbaeef6e..2dec11cf2 100644 --- a/docs/build/architecture/adr-048-consensus-fees.md +++ b/docs/build/architecture/adr-048-consensus-fees.md @@ -14,7 +14,7 @@ This ADR describes a flexible mechanism to maintain a consensus level gas prices ## Context -Currently, each validator configures it's own `minimal-gas-prices` in `app.yaml`. But setting a proper minimal gas price is critical to protect network from dos attack, and it's hard for all the validators to pick a sensible value, so we propose to maintain a gas price in consensus level. +Currently, each validator configures its own `minimal-gas-prices` in `app.yaml`. But setting a proper minimal gas price is critical to protect network from DoS attack, and it's hard for all the validators to pick a sensible value, so we propose to maintain a gas price in consensus level. Since tendermint 0.34.20 has supported mempool prioritization, we can take advantage of that to implement more sophisticated gas fee system. diff --git a/docs/build/architecture/adr-049-state-sync-hooks.md b/docs/build/architecture/adr-049-state-sync-hooks.md index 8b039d66f..d426cbe19 100644 --- a/docs/build/architecture/adr-049-state-sync-hooks.md +++ b/docs/build/architecture/adr-049-state-sync-hooks.md @@ -116,7 +116,7 @@ type ExtensionPayloadReader = func() ([]byte, error) type ExtensionPayloadWriter = func([]byte) error // ExtensionSnapshotter is an extension Snapshotter that is appended to the snapshot stream. -// ExtensionSnapshotter has an unique name and manages it's own internal formats. +// ExtensionSnapshotter has a unique name and manages its own internal formats. type ExtensionSnapshotter interface { // SnapshotName returns the name of snapshotter, it should be unique in the manager. SnapshotName() string 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..0178d4769 100644 --- a/docs/build/architecture/adr-060-abci-1.0.md +++ b/docs/build/architecture/adr-060-abci-1.0.md @@ -137,7 +137,7 @@ transactions entirely with other transactions. When evaluating transactions from `RequestPrepareProposal`, the application will ignore *ALL* transactions sent to it in the request and instead reap up to -`RequestPrepareProposal.max_tx_bytes` from it's own mempool. +`RequestPrepareProposal.max_tx_bytes` from its own mempool. Since an application can technically insert or inject transactions on `Insert` during `CheckTx` execution, it is recommended that applications ensure transaction @@ -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..cc9843195 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} } ``` @@ -286,7 +286,7 @@ decision based on the vote extensions. > nor the vote extension verification mechanism described above is required for > applications to implement. In other words, a proposer is not required to verify > and propagate vote extensions along with their signatures nor are proposers -> required to verify those signatures. An application can implement it's own +> required to verify those signatures. An application can implement its own > PKI mechanism and use that to sign and verify vote extensions. #### Vote Extension Persistence @@ -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/04-query-services.md b/docs/build/building-modules/04-query-services.md index a787a0c22..c2fbafa42 100644 --- a/docs/build/building-modules/04-query-services.md +++ b/docs/build/building-modules/04-query-services.md @@ -23,12 +23,12 @@ When defining a Protobuf `Query` service, a `QueryServer` interface is generated ```go type QueryServer interface { - QueryBalance(context.Context, *QueryBalanceParams) (*types.Coin, error) - QueryAllBalances(context.Context, *QueryAllBalancesParams) (*QueryAllBalancesResponse, error) + Balance(context.Context, *types.QueryBalanceRequest) (*types.QueryBalanceResponse, error) + AllBalances(context.Context, *types.QueryAllBalancesRequest) (*types.QueryAllBalancesResponse, error) } ``` -These custom queries methods should be implemented by a module's keeper, typically in `./keeper/grpc_query.go`. The first parameter of these methods is a generic `context.Context`. Therefore, the Cosmos SDK provides a function `sdk.UnwrapSDKContext` to retrieve the `context.Context` from the provided +These custom queries methods should be implemented by a module's keeper, typically in `./keeper/grpc_query.go`. The first parameter of these methods is a generic `context.Context`. Therefore, the Cosmos SDK provides a function `sdk.UnwrapSDKContext` to retrieve the `sdk.Context` from the provided `context.Context`. Here's an example implementation for the bank module: diff --git a/docs/build/building-modules/05-protobuf-annotations.md b/docs/build/building-modules/05-protobuf-annotations.md index 942b9a892..875715825 100644 --- a/docs/build/building-modules/05-protobuf-annotations.md +++ b/docs/build/building-modules/05-protobuf-annotations.md @@ -122,8 +122,19 @@ https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9 Encoding instructs the amino json marshaler how to encode certain fields that may differ from the standard encoding behaviour. The most common example of this is how `repeated cosmos.base.v1beta1.Coin` is encoded when using the amino json encoding format. The `legacy_coins` option tells the json marshaler [how to encode a null slice](https://github.com/cosmos/cosmos-sdk/blob/e8f28bf5db18b8d6b7e0d94b542ce4cf48fed9d6/x/tx/signing/aminojson/json_marshal.go#L65) of `cosmos.base.v1beta1.Coin`. +For a more generic option that works with any slice type, you can use `null_slice_as_empty`, which ensures that nil slices are encoded as empty arrays (`[]`) instead of `null`. This is useful for maintaining backward compatibility with legacy Amino JSON encoding where nil slices were serialized as empty arrays. + +Alternatively, you can use the exported `NullSliceAsEmptyEncoder` function directly in your code: + +```go +encoder := aminojson.NewEncoder(options) +encoder = encoder.DefineFieldEncoding("my_field", aminojson.NullSliceAsEmptyEncoder) +``` + ```proto (amino.encoding) = "legacy_coins", +// or for a more generic option: +(amino.encoding) = "null_slice_as_empty", ``` ```proto reference 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/building-modules/08-genesis.md b/docs/build/building-modules/08-genesis.md index 28ff911ba..a3f0a386e 100644 --- a/docs/build/building-modules/08-genesis.md +++ b/docs/build/building-modules/08-genesis.md @@ -51,7 +51,7 @@ Other than the methods related directly to `GenesisState`, module developers are The `InitGenesis` method is executed during [`InitChain`](../../learn/advanced/00-baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./06-keeper.md) setter function on each parameter within the `GenesisState`. -The [module manager](./01-module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../../learn/beginner/00-app-anatomy.md#constructor-function). +The [module manager](./01-module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderInitGenesis` method, which is called in the [application's constructor function](../../learn/beginner/00-app-anatomy.md#constructor-function). See an example of `InitGenesis` from the `auth` module: diff --git a/docs/build/building-modules/12-errors.md b/docs/build/building-modules/12-errors.md index 214ab70e8..f2e1137f3 100644 --- a/docs/build/building-modules/12-errors.md +++ b/docs/build/building-modules/12-errors.md @@ -52,5 +52,6 @@ an error is of a particular kind via `Is`. ## ABCI If a module error is registered, the Cosmos SDK `errors` package allows ABCI information to be extracted -through the `ABCIInfo` function. The package also provides `ResponseCheckTx` and `ResponseDeliverTx` as -auxiliary functions to automatically get `CheckTx` and `DeliverTx` responses from an error. +through the `ABCIInfo` function. In addition, the `types/errors` package provides helpers such as +`ResponseCheckTxWithEvents` and `ResponseExecTxResultWithEvents` to construct `CheckTx` and `ExecTxResult` +responses in the ABCI++ model, as well as `QueryResult` to build `ResponseQuery` values from an error. diff --git a/docs/build/building-modules/13-upgrade.md b/docs/build/building-modules/13-upgrade.md index 20c02e9f2..fa087df43 100644 --- a/docs/build/building-modules/13-upgrade.md +++ b/docs/build/building-modules/13-upgrade.md @@ -25,21 +25,28 @@ Consensus versions serve as state-breaking versions of app modules and must be i ## Registering Migrations -To register the functionality that takes place during a module upgrade, you must register which migrations you want to take place. +To register the functionality that takes place during a module upgrade, you must register the migrations that will be executed. -Migration registration takes place in the `Configurator` using the `RegisterMigration` method. The `AppModule` reference to the configurator is in the `RegisterServices` method. +Migration registration takes place in the `Configurator` using the `RegisterMigration` method. The `AppModule` reference to the configurator is in the `RegisterServices` method. Each time a module's `ConsensusVersion` is incremented, a new migration **must** be registered for that version. If the version bump does not introduce any store changes, a no-op migration handler must still be registered. If a required migration handler is missing for a version, `RunMigrations` will panic during an upgrade. You can register one or more migrations. If you register more than one migration script, list the migrations in increasing order and ensure there are enough migrations that lead to the desired consensus version. For example, to migrate to version 3 of a module, register separate migrations for version 1 and version 2 as shown in the following example: ```go func (am AppModule) RegisterServices(cfg module.Configurator) { // --snip-- - cfg.RegisterMigration(types.ModuleName, 1, func(ctx sdk.Context) error { + if err := cfg.RegisterMigration(types.ModuleName, 1, func(ctx sdk.Context) error { // Perform in-place store migrations from ConsensusVersion 1 to 2. - }) - cfg.RegisterMigration(types.ModuleName, 2, func(ctx sdk.Context) error { + return nil + }); err != nil { + // handle the error (for example, panic) + } + + if err := cfg.RegisterMigration(types.ModuleName, 2, func(ctx sdk.Context) error { // Perform in-place store migrations from ConsensusVersion 2 to 3. - }) + return nil + }); err != nil { + // handle the error (for example, panic) + } } ``` @@ -51,12 +58,12 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/keeper/migratio ## Writing Migration Scripts -To define the functionality that takes place during an upgrade, write a migration script and place the functions in a `migrations/` directory. For example, to write migration scripts for the bank module, place the functions in `x/bank/migrations/`. Use the recommended naming convention for these functions. For example, `v2bank` is the script that migrates the package `x/bank/migrations/v2`: +To define the functionality that takes place during an upgrade, write a migration script and place the functions in a `migrations/` directory. For example, to write migration scripts for the bank module, place the functions in `x/bank/migrations/`. Use the recommended naming convention for these functions. For example, the `v2` package in `x/bank/migrations/v2` contains the script that migrates the bank module store from version 1 to 2: ```go // Migrating bank module from version 1 to 2 func (m Migrator) Migrate1to2(ctx sdk.Context) error { - return v2bank.MigrateStore(ctx, m.keeper.storeKey) // v2bank is package `x/bank/migrations/v2`. + return v2.MigrateStore(ctx, m.keeper.storeService, m.keeper.cdc) // v2 is package `x/bank/migrations/v2`. } ``` diff --git a/docs/build/building-modules/15-depinject.md b/docs/build/building-modules/15-depinject.md index 64aa3711e..af945b0ab 100644 --- a/docs/build/building-modules/15-depinject.md +++ b/docs/build/building-modules/15-depinject.md @@ -6,11 +6,11 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Depinject Documentation](../packages/01-depinject.md) +* [Depinject Documentation](../building-apps/01-app-go-di.md) ::: -[`depinject`](../packages/01-depinject.md) is used to wire any module in `app.go`. +[`depinject`](../building-apps/01-app-go-di.md) is used to wire any module in `app.go`. All core modules are already configured to support dependency injection. To work with `depinject` a module must define its configuration and requirements so that `depinject` can provide the right dependencies. diff --git a/docs/build/building-modules/17-preblock.md b/docs/build/building-modules/17-preblock.md index 437224979..2e4b4698f 100644 --- a/docs/build/building-modules/17-preblock.md +++ b/docs/build/building-modules/17-preblock.md @@ -21,12 +21,14 @@ There are two semantics around the new lifecycle method: * It runs before the `BeginBlocker` of all modules * It can modify consensus parameters in storage, and signal the caller through the return value. -When it returns `ConsensusParamsChanged=true`, the caller must refresh the consensus parameters in the deliver context: +When it returns `ConsensusParamsChanged=true`, the caller must refresh the consensus parameters in the finalize context and update the block gas meter accordingly. Conceptually, this looks like: ``` -app.finalizeBlockState.ctx = app.finalizeBlockState.ctx.WithConsensusParams(app.GetConsensusParams()) +ctx = ctx.WithConsensusParams(app.GetConsensusParams(ctx)) +gasMeter := app.getBlockGasMeter(ctx) +ctx = ctx.WithBlockGasMeter(gasMeter) ``` -The new ctx must be passed to all the other lifecycle methods. +The new finalize context must then be used for all the other lifecycle methods in the block. diff --git a/docs/build/migrations/02-upgrade-reference.md b/docs/build/migrations/02-upgrade-reference.md index aaefe25ff..9382289a9 100644 --- a/docs/build/migrations/02-upgrade-reference.md +++ b/docs/build/migrations/02-upgrade-reference.md @@ -4,23 +4,79 @@ This document provides a quick reference for the upgrades from `v0.53.x` to `v0. Note, always read the **App Wiring Changes** section for more information on application wiring updates. -🚨Upgrading to v0.54.x will require a **coordinated** chain upgrade.🚨 +## TLDR -### TLDR +For a full list of changes, see the [Changelog](https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/CHANGELOG.md). -**The only major feature in Cosmos SDK v0.54.x is the upgrade from CometBFT v0.x.x to CometBFT v2.** +## x/gov -For a full list of changes, see the [Changelog](https://github.com/cosmos/cosmos-sdk/blob/release/v0.54.x/CHANGELOG.md). +### Keeper Initialization + +The `x/gov` module has been decoupled from `x/staking`. The `keeper.NewKeeper` constructor now requires a `CalculateVoteResultsAndVotingPowerFn` parameter instead of a `StakingKeeper`. + +**Before:** +```go +govKeeper := keeper.NewKeeper( + cdc, + storeService, + authKeeper, + bankKeeper, + stakingKeeper, // StakingKeeper parameter + distrKeeper, + router, + config, + authority, +) +``` + +**After:** +```go +govKeeper := keeper.NewKeeper( + cdc, + storeService, + authKeeper, + bankKeeper, + keeper.NewDefaultCalculateVoteResultsAndVotingPower(stakingKeeper), // Function parameter + distrKeeper, + router, + config, + authority, +) +``` + +For applications using depinject, the governance module now accepts an optional `CalculateVoteResultsAndVotingPowerFn`. If not provided, it will use the `StakingKeeper` (also optional) to create the default function. + +### GovHooks Interface + +The `AfterProposalSubmission` hook now includes the proposer address as a parameter. + +**Before:** +```go +func (h MyGovHooks) AfterProposalSubmission(ctx context.Context, proposalID uint64) error { + // implementation +} +``` + +**After:** +```go +func (h MyGovHooks) AfterProposalSubmission(ctx context.Context, proposalID uint64, proposerAddr sdk.AccAddress) error { + // implementation +} +``` + +## Adoption of OpenTelemetry and Deprecation of `github.com/hashicorp/go-metrics` + +Existing Cosmos SDK telemetry support is provided by `github.com/hashicorp/go-metrics` which is undermaintained and only supported metrics instrumentation. +OpenTelemetry provides an integrated solution for metrics, traces, and logging which is widely adopted and actively maintained. +The existing wrapper functions in the `telemetry` package required acquiring mutex locks and map lookups for every metric operation which is sub-optimal. OpenTelemetry's API uses atomic concurrency wherever possible and should introduce less performance overhead during metric collection. -#### Deprecation of `TimeoutCommit` +The [README.md](telemetry/README.md) in the `telemetry` package provides more details on usage, but below is a quick summary: +1. application developers should follow the official [go OpenTelemetry](https://pkg.go.dev/go.opentelemetry.io/otel) guidelines when instrumenting their applications. +2. node operators who want to configure OpenTelemetry exporters should set the `OTEL_EXPERIMENTAL_CONFIG_FILE` environment variable to the path of a yaml file which follows the OpenTelemetry declarative configuration format specified here: https://pkg.go.dev/go.opentelemetry.io/contrib/otelconf. As long as the `telemetry` package has been imported somewhere (it should already be imported if you are using the SDK), OpenTelemetry will be initialized automatically based on the configuration file. -CometBFT v2 has deprecated the use of `TimeoutCommit` for a new field, `NextBlockDelay`, that is part of the -`FinalizeBlockResponse` ABCI message that is returned to CometBFT via the SDK baseapp. More information from -the CometBFT repo can be found [here](https://github.com/cometbft/cometbft/blob/88ef3d267de491db98a654be0af6d791e8724ed0/spec/abci/abci%2B%2B_methods.md?plain=1#L689). +NOTE: the go implementation of [otelconf](https://pkg.go.dev/go.opentelemetry.io/contrib/otelconf) is still under development and we will update our usage of it as it matures. -For SDK application developers and node runners, this means that the `timeout_commit` value in the `config.toml` file -is still used if `NextBlockDelay` is 0 (its default value). This means that when upgrading to Cosmos SDK v0.54.x, if -the existing `timout_commit` values that validators have been using will be maintained and have the same behavior. +## Log v2 -For setting the field in your application, there is a new `baseapp` option, `SetNextBlockDelay` which can be passed to your application upon -initialization in `app.go`. Setting this value to any non-zero value will override anything that is set in validators' `config.toml`. +The log package has been bumped to v2 as new methods have been added to support tracer correlation with logs. Logs can be scraped with OpenTelemetry's [FileLog Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver). +You may have to make additional changes to your log backend to properly extract the trace_id, span_id, and trace_flags from the logs. \ No newline at end of file diff --git a/docs/build/migrations/03-upgrade-guide.md b/docs/build/migrations/03-upgrade-guide.md index 057911c64..d519678ba 100644 --- a/docs/build/migrations/03-upgrade-guide.md +++ b/docs/build/migrations/03-upgrade-guide.md @@ -301,7 +301,7 @@ app.EpochsKeeper = epochskeeper.NewKeeper( Set up hooks for the epochs keeper: -To learn how to write hooks for the epoch keeper, see the [x/epoch README](https://github.com/cosmos/cosmos-sdk/blob/main/x/epochs/README.md) +To learn how to write hooks for the epoch keeper, see the [x/epochs README](https://github.com/cosmos/cosmos-sdk/blob/main/x/epochs/README.md) ```go app.EpochsKeeper.SetHooks( diff --git a/docs/build/modules/README.md b/docs/build/modules/README.md index 12a128c3a..565d77abe 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 @@ -32,19 +31,19 @@ the core functionality of your blockchain. They can be thought of as ways to ex capabilities of your blockchain or further specialize it. * [Authz](./authz/README.md) - Authorization for accounts to perform actions on behalf of other accounts. -* [Epochs](./epochs/README.md) - Registration so SDK modules can have logic to be executed at the timed tickers. +* [Epochs](./epochs/README.md) - Registration so SDK modules can have logic to be executed on timed tickers. * [Feegrant](./feegrant/README.md) - Grant fee allowances for executing transactions. * [ProtocolPool](./protocolpool/README.md) - Extended management of community pool functionality. ## 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). @@ -61,3 +60,4 @@ The CosmWasm module enables smart contracts, learn more by going to their [docum ## EVM Read more about writing smart contracts with solidity at the official [`evm` documentation page](https://evm.cosmos.network/). + diff --git a/docs/build/modules/auth/README.md b/docs/build/modules/auth/README.md index bd9f18a37..56a2c420b 100644 --- a/docs/build/modules/auth/README.md +++ b/docs/build/modules/auth/README.md @@ -56,7 +56,7 @@ costs of gas in each token denomination they wish to support: `simd start ... --minimum-gas-prices=0.00001stake;0.05photinos` -When adding transactions to mempool or gossipping transactions, validators check +When adding transactions to mempool or gossiping transactions, validators check if the transaction's gas prices, which are determined by the provided fees, meet any of the validator's minimum gas prices. In other words, a transaction must provide a fee of at least one denomination that matches a validator's minimum @@ -190,34 +190,40 @@ all fields of all accounts, and to iterate over all stored accounts. // AccountKeeperI is the interface contract that x/auth's keeper implements. type AccountKeeperI interface { // Return a new account with the next account number and the specified address. Does not save the new account to the store. - NewAccountWithAddress(sdk.Context, sdk.AccAddress) types.AccountI + NewAccountWithAddress(context.Context, sdk.AccAddress) sdk.AccountI // Return a new account with the next account number. Does not save the new account to the store. - NewAccount(sdk.Context, types.AccountI) types.AccountI + NewAccount(context.Context, sdk.AccountI) sdk.AccountI // Check if an account exists in the store. - HasAccount(sdk.Context, sdk.AccAddress) bool + HasAccount(context.Context, sdk.AccAddress) bool // Retrieve an account from the store. - GetAccount(sdk.Context, sdk.AccAddress) types.AccountI + GetAccount(context.Context, sdk.AccAddress) sdk.AccountI // Set an account in the store. - SetAccount(sdk.Context, types.AccountI) + SetAccount(context.Context, sdk.AccountI) // Remove an account from the store. - RemoveAccount(sdk.Context, types.AccountI) + RemoveAccount(context.Context, sdk.AccountI) // Iterate over all accounts, calling the provided function. Stop iteration when it returns true. - IterateAccounts(sdk.Context, func(types.AccountI) bool) + IterateAccounts(context.Context, func(sdk.AccountI) bool) // Fetch the public key of an account at a specified address - GetPubKey(sdk.Context, sdk.AccAddress) (crypto.PubKey, error) + GetPubKey(context.Context, sdk.AccAddress) (cryptotypes.PubKey, error) // Fetch the sequence of an account at a specified address. - GetSequence(sdk.Context, sdk.AccAddress) (uint64, error) + GetSequence(context.Context, sdk.AccAddress) (uint64, error) // Fetch the next account number, and increment the internal counter. - NextAccountNumber(sdk.Context) uint64 + NextAccountNumber(context.Context) uint64 + + // GetModulePermissions fetches per-module account permissions + GetModulePermissions() map[string]types.PermissionsForAddress + + // AddressCodec returns the account address codec. + AddressCodec() address.Codec } ``` @@ -249,7 +255,7 @@ simd query auth --help #### account -The `account` command allow users to query for an account by it's address. +The `account` command allows users to query for an account by its address. ```bash simd query auth account [address] [flags] @@ -504,7 +510,7 @@ A user can query the `auth` module using gRPC endpoints. #### Account -The `account` endpoint allow users to query for an account by it's address. +The `account` endpoint allows users to query for an account by its address. ```bash cosmos.auth.v1beta1.Query/Account @@ -687,7 +693,7 @@ A user can query the `auth` module using REST endpoints. #### Account -The `account` endpoint allow users to query for an account by it's address. +The `account` endpoint allows users to query for an account by its address. ```bash /cosmos/auth/v1beta1/account?address={address} @@ -695,7 +701,7 @@ The `account` endpoint allow users to query for an account by it's address. #### Accounts -The `accounts` endpoint allow users to query all the available accounts. +The `accounts` endpoint allows users to query all the available accounts. ```bash /cosmos/auth/v1beta1/accounts @@ -703,7 +709,7 @@ The `accounts` endpoint allow users to query all the available accounts. #### Params -The `params` endpoint allow users to query the current auth parameters. +The `params` endpoint allows users to query the current auth parameters. ```bash /cosmos/auth/v1beta1/params diff --git a/docs/build/modules/authz/README.md b/docs/build/modules/authz/README.md index 3ec3c3664..7398765fb 100644 --- a/docs/build/modules/authz/README.md +++ b/docs/build/modules/authz/README.md @@ -116,7 +116,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1 We are maintaining a queue for authz pruning. Whenever a grant is created, an item will be added to `GrantQueue` with a key of expiration, granter, grantee. -In `EndBlock` (which runs for every block) we continuously check and prune the expired grants by forming a prefix key with current blocktime that passed the stored expiration in `GrantQueue`, we iterate through all the matched records from `GrantQueue` and delete them from the `GrantQueue` & `Grant`s store. +In `BeginBlock` (which runs for every block) we continuously check and prune the expired grants by forming a prefix key with current blocktime that passed the stored expiration in `GrantQueue`, we iterate through all the matched records from `GrantQueue` and delete them from the `GrantQueue` & `Grant`s store. ```go reference https://github.com/cosmos/cosmos-sdk/blob/5f4ddc6f80f9707320eec42182184207fff3833a/x/authz/keeper/keeper.go#L378-L403 diff --git a/docs/build/modules/bank/README.md b/docs/build/modules/bank/README.md index 62a781da6..a80a39794 100644 --- a/docs/build/modules/bank/README.md +++ b/docs/build/modules/bank/README.md @@ -125,7 +125,7 @@ aforementioned state: ## Params -The bank module stores it's params in state with the prefix of `0x05`, +The bank module stores its params in state with the prefix of `0x05`, it can be updated with governance or the address with authority. * Params: `0x05 | ProtocolBuffer(Params)` @@ -193,7 +193,8 @@ Restricted permission to mint per module could be achieved by using baseKeeper w // between accounts. type Keeper interface { SendKeeper - WithMintCoinsRestriction(MintingRestrictionFn) BaseKeeper + WithMintCoinsRestriction(types.MintingRestrictionFn) BaseKeeper + WithObjStoreKey(storetypes.StoreKey) BaseKeeper InitGenesis(context.Context, *types.GenesisState) ExportGenesis(context.Context) *types.GenesisState @@ -205,6 +206,7 @@ type Keeper interface { GetDenomMetaData(ctx context.Context, denom string) (types.Metadata, bool) HasDenomMetaData(ctx context.Context, denom string) bool SetDenomMetaData(ctx context.Context, denomMetaData types.Metadata) + GetAllDenomMetaData(ctx context.Context) []types.Metadata IterateAllDenomMetaData(ctx context.Context, cb func(types.Metadata) bool) SendCoinsFromModuleToAccount(ctx context.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error @@ -215,12 +217,15 @@ type Keeper interface { MintCoins(ctx context.Context, moduleName string, amt sdk.Coins) error BurnCoins(ctx context.Context, moduleName string, amt sdk.Coins) error + SendCoinsFromAccountToModuleVirtual(ctx context.Context, senderAddr sdk.AccAddress, recipientModule string, amt sdk.Coins) error + SendCoinsFromModuleToAccountVirtual(ctx context.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error + CreditVirtualAccounts(ctx context.Context) error + SendCoinsFromVirtual(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) error + SendCoinsToVirtual(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) error + DelegateCoins(ctx context.Context, delegatorAddr, moduleAccAddr sdk.AccAddress, amt sdk.Coins) error UndelegateCoins(ctx context.Context, moduleAccAddr, delegatorAddr sdk.AccAddress, amt sdk.Coins) error - // GetAuthority gets the address capable of executing governance proposal messages. Usually the gov module account. - GetAuthority() string - types.QueryServer } ``` @@ -236,8 +241,8 @@ accounts. The send keeper does not alter the total supply (mint or burn coins). type SendKeeper interface { ViewKeeper - AppendSendRestriction(restriction SendRestrictionFn) - PrependSendRestriction(restriction SendRestrictionFn) + AppendSendRestriction(restriction types.SendRestrictionFn) + PrependSendRestriction(restriction types.SendRestrictionFn) ClearSendRestriction() InputOutputCoins(ctx context.Context, input types.Input, outputs []types.Output) error @@ -247,9 +252,10 @@ type SendKeeper interface { SetParams(ctx context.Context, params types.Params) error IsSendEnabledDenom(ctx context.Context, denom string) bool + GetSendEnabledEntry(ctx context.Context, denom string) (types.SendEnabled, bool) SetSendEnabled(ctx context.Context, denom string, value bool) SetAllSendEnabled(ctx context.Context, sendEnableds []*types.SendEnabled) - DeleteSendEnabled(ctx context.Context, denom string) + DeleteSendEnabled(ctx context.Context, denoms ...string) IterateSendEnabledEntries(ctx context.Context, cb func(denom string, sendEnabled bool) (stop bool)) GetAllSendEnabledEntries(ctx context.Context) []types.SendEnabled @@ -257,6 +263,9 @@ type SendKeeper interface { IsSendEnabledCoins(ctx context.Context, coins ...sdk.Coin) error BlockedAddr(addr sdk.AccAddress) bool + GetBlockedAddresses() map[string]bool + + GetAuthority() string } ``` 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/distribution/README.md b/docs/build/modules/distribution/README.md index 0563c5d72..3d28c13c3 100644 --- a/docs/build/modules/distribution/README.md +++ b/docs/build/modules/distribution/README.md @@ -198,7 +198,7 @@ type ValidatorDistInfo struct { ### Delegation Distribution Each delegation distribution only needs to record the height at which it last -withdrew fees. Because a delegation must withdraw fees each time it's +withdrew fees. Because a delegation must withdraw fees each time its properties change (aka bonded tokens etc.) its properties will remain constant and the delegator's _accumulation_ factor can be calculated passively knowing only the height of the last withdrawal and its current properties. @@ -213,7 +213,7 @@ type DelegationDistInfo struct { ### Params -The distribution module stores it's params in state with the prefix of `0x09`, +The distribution module stores its params in state with the prefix of `0x09`, it can be updated with governance or the address with authority. * Params: `0x09 | ProtocolBuffer(Params)` @@ -595,10 +595,10 @@ The distribution module emits the following events: The distribution module contains the following parameters: -| Key | Type | Example | -| ------------------- | ------------ | -------------------------- | -| communitytax | string (dec) | "0.020000000000000000" [0] | -| withdrawaddrenabled | bool | true | +| Key | Type | Example | +| --------------------- | ------------ | -------------------------- | +| community_tax | string (dec) | "0.020000000000000000" [0] | +| withdraw_addr_enabled | bool | true | * [0] `communitytax` must be positive and cannot exceed 1.00. * `baseproposerreward` and `bonusproposerreward` were parameters that are deprecated in v0.47 and are not used. diff --git a/docs/build/modules/epochs/README.md b/docs/build/modules/epochs/README.md index d56970668..035e5a825 100644 --- a/docs/build/modules/epochs/README.md +++ b/docs/build/modules/epochs/README.md @@ -72,9 +72,9 @@ Epochs keeper module provides utility functions to manage epochs. ```go // the first block whose timestamp is after the duration is counted as the end of the epoch - AfterEpochEnd(ctx sdk.Context, epochIdentifier string, epochNumber int64) + AfterEpochEnd(ctx context.Context, epochIdentifier string, epochNumber int64) error // new epoch is next block of epoch end block - BeforeEpochStart(ctx sdk.Context, epochIdentifier string, epochNumber int64) + BeforeEpochStart(ctx context.Context, epochIdentifier string, epochNumber int64) error ``` ### How modules receive hooks @@ -87,14 +87,185 @@ modules so that they can be modified by governance. This is the standard dev UX of this: ```golang -func (k MyModuleKeeper) AfterEpochEnd(ctx sdk.Context, epochIdentifier string, epochNumber int64) { +func (k MyModuleKeeper) AfterEpochEnd(ctx context.Context, epochIdentifier string, epochNumber int64) error { params := k.GetParams(ctx) if epochIdentifier == params.DistrEpochIdentifier { // my logic } + return nil } ``` +### Wiring Hooks + +**Manual Wiring:** + +Import the following: + +```go +import ( + // ... + "github.com/cosmos/cosmos-sdk/x/epochs" + epochskeeper "github.com/cosmos/cosmos-sdk/x/epochs/keeper" + epochstypes "github.com/cosmos/cosmos-sdk/x/epochs/types" +) +``` + +Add the epochs keeper to your application struct: + +```go +EpochsKeeper *epochskeeper.Keeper +``` + +Add the store key: + +```go +keys := storetypes.NewKVStoreKeys( + // ... + epochstypes.StoreKey, +) +``` + +Instantiate the keeper: + +```go +epochsKeeper := epochskeeper.NewKeeper( + runtime.NewKVStoreService(keys[epochstypes.StoreKey]), + appCodec, +) + +app.EpochsKeeper = &epochsKeeper +``` + +Set up hooks for the epochs keeper: + +```go +app.EpochsKeeper.SetHooks( + epochstypes.NewMultiEpochHooks( + // insert epoch hooks receivers here + app.SomeOtherModule + ), +) +``` + +Add the epochs module to the module manager: + +```go +app.ModuleManager = module.NewManager( + // ... + epochs.NewAppModule(appCodec, app.EpochsKeeper), +) +``` + +Add entries for SetOrderBeginBlockers and SetOrderInitGenesis: + +```go +app.ModuleManager.SetOrderBeginBlockers( + // ... + epochstypes.ModuleName, +) +``` + +```go +app.ModuleManager.SetOrderInitGenesis( + // ... + epochstypes.ModuleName, +) +``` + +**DI Wiring:** + +First, set up the keeper for the application. + +Import the epochs keeper: + +```go +epochskeeper "github.com/cosmos/cosmos-sdk/x/epochs/keeper" +``` + +Add the keeper to your application struct: + +```go +EpochsKeeper *epochskeeper.Keeper +``` + +Add the keeper to the depinject system: + +```go +depinject.Inject( + appConfig, + &appBuilder, + &app.appCodec, + &app.legacyAmino, + &app.txConfig, + &app.interfaceRegistry, + // ... other modules + &app.EpochsKeeper, // NEW MODULE! +) +``` + +Next, set up configuration for the module. + +Import the following: + +```go +import ( + epochsmodulev1 "cosmossdk.io/api/cosmos/epochs/module/v1" + + _ "github.com/cosmos/cosmos-sdk/x/epochs" // import for side-effects + epochstypes "github.com/cosmos/cosmos-sdk/x/epochs/types" +) +``` + +Add an entry for BeginBlockers and InitGenesis: + +```go +BeginBlockers: []string{ + // ... + epochstypes.ModuleName, +}, +``` + +```go +InitGenesis: []string{ + // ... + epochstypes.ModuleName, +}, +``` + +Add an entry for epochs in the ModuleConfig: + +```go +{ + Name: epochstypes.ModuleName, + Config: appconfig.WrapAny(&epochsmodulev1.Module{}), +}, +``` + +depinject can automatically add your hooks to the epochs `Keeper`. For it do so, specify an output of your module with the type `epochtypes.EpochHooksWrapper`, ie: + +```go +type TestInputs struct { + depinject.In +} + +type TestOutputs struct { + depinject.Out + + Hooks types.EpochHooksWrapper +} + +func DummyProvider(in TestInputs) TestOutputs { + return TestOutputs{ + Hooks: types.EpochHooksWrapper{ + EpochHooks: testEpochHooks{}, + }, + } +} +``` + +for an example see [`depinject_test.go`](https://github.com/cosmos/cosmos-sdk/tree/main/x/epochs/depinject_test.go) + ### Panic isolation If a given epoch hook panics, its state update is reverted, but we keep diff --git a/docs/build/modules/feegrant/README.md b/docs/build/modules/feegrant/README.md index 0ac1c2985..379c0cd97 100644 --- a/docs/build/modules/feegrant/README.md +++ b/docs/build/modules/feegrant/README.md @@ -94,7 +94,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1be * `allowance` is either `BasicAllowance` or `PeriodicAllowance`. -* `allowed_messages` is array of messages allowed to execute the given allowance. +* `allowed_messages` is an array of messages allowed to execute the given allowance. ### FeeGranter flag 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..aa3b8fe40 100644 --- a/docs/build/modules/gov/README.md +++ b/docs/build/modules/gov/README.md @@ -10,14 +10,14 @@ This paper specifies the Governance module of the Cosmos SDK, which was first described in the [Cosmos Whitepaper](https://cosmos.network/about/whitepaper) in June 2016. -The module enables Cosmos SDK based blockchain to support an on-chain governance +The module enables Cosmos SDK-based blockchains to support an on-chain governance system. In this system, holders of the native staking token of the chain can vote on proposals on a 1 token 1 vote basis. Next is a list of features the module currently supports: * **Proposal submission:** Users can submit proposals with a deposit. Once the -minimum deposit is reached, the proposal enters voting period. The minimum deposit can be reached by collecting deposits from different users (including proposer) within deposit period. -* **Vote:** Participants can vote on proposals that reached MinDeposit and entered voting period. +minimum deposit is reached, the proposal enters the voting period. The minimum deposit can be reached by collecting deposits from different users (including proposer) within the deposit period. +* **Vote:** Participants can vote on proposals that reached MinDeposit and entered the voting period. * **Inheritance and penalties:** Delegators inherit their validator's vote if they don't vote themselves. * **Claiming deposit:** Users that deposited on proposals can recover their @@ -66,12 +66,12 @@ staking token of the chain. *Disclaimer: This is work in progress. Mechanisms are susceptible to change.* -The governance process is divided in a few steps that are outlined below: +The governance process is divided into a few steps that are outlined below: * **Proposal submission:** Proposal is submitted to the blockchain with a deposit. -* **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is - confirmed and vote opens. Bonded Atom holders can then send `TxGovVote` +* **Vote:** Once the deposit reaches a certain value (`MinDeposit`), the proposal is + confirmed and the vote opens. Bonded Atom holders can then send `TxGovVote` transactions to vote on the proposal. * **Execution** After a period of time, the votes are tallied and depending on the result, the messages in the proposal will be executed. @@ -166,7 +166,7 @@ proposal but accept the result of the vote. [ADR-037](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-037-gov-split-vote.md) introduces the weighted vote feature which allows a staker to split their votes into several voting options. For example, it could use 70% of its voting power to vote Yes and 30% of its voting power to vote No. -Often times the entity owning that address might not be a single individual. For example, a company might have different stakeholders who want to vote differently, and so it makes sense to allow them to split their voting power. Currently, it is not possible for them to do "passthrough voting" and giving their users voting rights over their tokens. However, with this system, exchanges can poll their users for voting preferences, and then vote on-chain proportionally to the results of the poll. +Oftentimes the entity owning that address might not be a single individual. For example, a company might have different stakeholders who want to vote differently, and so it makes sense to allow them to split their voting power. Currently, it is not possible for them to do "passthrough voting" and give their users voting rights over their tokens. However, with this system, exchanges can poll their users for voting preferences, and then vote on-chain proportionally to the results of the poll. To represent weighted vote on chain, we use the following Protobuf message. @@ -432,10 +432,13 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.pr This type is used in a temp map when tallying ```go - type ValidatorGovInfo struct { - Minus sdk.Dec - Vote Vote - } +type ValidatorGovInfo struct { + Address sdk.ValAddress // address of the validator operator + BondedTokens math.Int // Power of a Validator + DelegatorShares math.LegacyDec // Total outstanding delegator shares + DelegatorDeductions math.LegacyDec // Delegator deductions from validator's delegators voting independently + Vote WeightedVoteOptions // Vote of the validator +} ``` ## Stores @@ -686,14 +689,14 @@ The governance module contains the following parameters: | voting_period | string (time ns) | "172800000000000" (17280s) | | quorum | string (dec) | "0.334000000000000000" | | threshold | string (dec) | "0.500000000000000000" | -| veto | string (dec) | "0.334000000000000000" | -| expedited_threshold | string (time ns) | "0.667000000000000000" | -| expedited_voting_period | string (time ns) | "86400000000000" (8600s) | +| veto_threshold | string (dec) | "0.334000000000000000" | +| expedited_threshold | string (dec) | "0.667000000000000000" | +| expedited_voting_period | string (time ns) | "86400000000000" (86400s) | | expedited_min_deposit | array (coins) | [{"denom":"uatom","amount":"50000000"}] | -| burn_proposal_deposit_prevote | bool | false | +| burn_proposal_deposit_prevote | bool | false | | burn_vote_quorum | bool | false | | burn_vote_veto | bool | true | -| min_initial_deposit_ratio | string | "0.1" | +| min_initial_deposit_ratio | string | "0.1" | **NOTE**: The governance module contains parameters that are objects unlike other @@ -2532,7 +2535,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 +2555,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/mint/README.md b/docs/build/modules/mint/README.md index 89dab7704..d376cda26 100644 --- a/docs/build/modules/mint/README.md +++ b/docs/build/modules/mint/README.md @@ -160,7 +160,7 @@ inflation calculation logic is needed, this can be achieved by defining and passing a function that matches `InflationCalculationFn`'s signature. ```go -type InflationCalculationFn func(ctx sdk.Context, minter Minter, params Params, bondedRatio math.LegacyDec) math.LegacyDec +type InflationCalculationFn func(ctx context.Context, minter Minter, params Params, bondedRatio math.LegacyDec) math.LegacyDec ``` #### NextInflationRate 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/modules/params/README.md b/docs/build/modules/params/README.md index 10b47da44..3092cc964 100644 --- a/docs/build/modules/params/README.md +++ b/docs/build/modules/params/README.md @@ -11,13 +11,13 @@ NOTE: `x/params` is deprecated as of Cosmos SDK v0.53 and will be removed in the Package params provides a globally available parameter store. There are two main types, Keeper and Subspace. Subspace is an isolated namespace for a -paramstore, where keys are prefixed by preconfigured spacename. Keeper has a +paramstore, where keys are prefixed by a preconfigured space name. Keeper has a permission to access all existing spaces. Subspace can be used by the individual keepers, which need a private parameter store that the other keepers cannot modify. The params Keeper can be used to add a route to `x/gov` router in order to modify any parameter in case a proposal passes. -The following contents explains how to use params module for master and user modules. +The following sections explain how to use the params module for master and user modules. ## Contents diff --git a/docs/build/modules/protocolpool/README.md b/docs/build/modules/protocolpool/README.md index d88b1ee12..6a695375a 100644 --- a/docs/build/modules/protocolpool/README.md +++ b/docs/build/modules/protocolpool/README.md @@ -54,7 +54,7 @@ CommunityPoolSpend can be called by the module authority (default governance mod ### CreateContinuousFund CreateContinuousFund is a message used to initiate a continuous fund for a specific recipient. The proposed percentage of funds will be distributed only on withdraw request for the recipient. The fund distribution continues until expiry time is reached or continuous fund request is canceled. -NOTE: This feature is designed to work with the SDK's default bond denom. +NOTE: This feature is designed to work with the SDK's default bond denom. ```protobuf // CreateContinuousFund defines a method to distribute a percentage of funds to an address continuously. @@ -91,7 +91,7 @@ https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/proto/cosmos/protocolp ```go func (k Keeper) FundCommunityPool(ctx context.Context, amount sdk.Coins, sender sdk.AccAddress) error { - return k.bankKeeper.SendCoinsFromAccountToModule(ctx, sender, types.ModuleName, amount) + return k.bankKeeper.SendCoinsFromAccountToModule(ctx, sender, types.ModuleName, amount) } ``` @@ -110,7 +110,7 @@ The message will fail under the following conditions: ```go func (k Keeper) DistributeFromCommunityPool(ctx context.Context, amount sdk.Coins, receiveAddr sdk.AccAddress) error { - return k.bankKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, receiveAddr, amount) + return k.bankKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, receiveAddr, amount) } ``` @@ -138,7 +138,7 @@ https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/x/protocolpool/keeper/ ### MsgCancelContinuousFund -This message is used to cancel an existing continuous fund proposal for a specific recipient. Once canceled, the continuous fund will no longer distribute funds at each begin block, and the state object will be removed. +This message is used to cancel an existing continuous fund proposal for a specific recipient. Once canceled, the continuous fund will no longer distribute funds at each begin block, and the state object will be removed. ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/x/protocolpool/proto/cosmos/protocolpool/v1/tx.proto#L136-L161 diff --git a/docs/build/modules/slashing/README.md b/docs/build/modules/slashing/README.md index 5bf95b80f..3eb7ba1fe 100644 --- a/docs/build/modules/slashing/README.md +++ b/docs/build/modules/slashing/README.md @@ -148,7 +148,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/slashing/v1be ### Params -The slashing module stores it's params in state with the prefix of `0x00`, +The slashing module stores its params in state with the prefix of `0x00`, it can be updated with governance or the address with authority. * Params: `0x00 | ProtocolBuffer(Params)` diff --git a/docs/build/modules/staking/README.md b/docs/build/modules/staking/README.md index afed4beef..947f5dcf2 100644 --- a/docs/build/modules/staking/README.md +++ b/docs/build/modules/staking/README.md @@ -10,7 +10,7 @@ This paper specifies the Staking module of the Cosmos SDK that was first described in the [Cosmos Whitepaper](https://cosmos.network/about/whitepaper) in June 2016. -The module enables Cosmos SDK-based blockchain to support an advanced +The module enables Cosmos SDK-based blockchains to support an advanced Proof-of-Stake (PoS) system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system. @@ -837,11 +837,13 @@ following hooks can registered with staking: * called when a delegation is created * `BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error` * called when a delegation's shares are modified -* `AfterDelegationModified(Context, AccAddress, ValAddress) error` - * called when a delegation is created or modified * `BeforeDelegationRemoved(Context, AccAddress, ValAddress) error` * called when a delegation is removed -* `AfterUnbondingInitiated(Context, UnbondingID)` +* `AfterDelegationModified(Context, AccAddress, ValAddress) error` + * called when a delegation is created or modified +* `BeforeValidatorSlashed(Context, ValAddress, math.LegacyDec) error` + * called when a validator is about to be slashed +* `AfterUnbondingInitiated(Context, uint64) error` * called when an unbonding operation (validator unbonding, unbonding delegation, redelegation) was initiated diff --git a/docs/build/modules/upgrade/README.md b/docs/build/modules/upgrade/README.md index 0ff5ad01a..39d3a9768 100644 --- a/docs/build/modules/upgrade/README.md +++ b/docs/build/modules/upgrade/README.md @@ -37,7 +37,7 @@ A `Plan` is created once a (frozen) release candidate along with an appropriate `Handler` (see below) is agreed upon, where the `Name` of a `Plan` corresponds to a specific `Handler`. Typically, a `Plan` is created through a governance proposal process, where if voted upon and passed, will be scheduled. The `Info` of a `Plan` -may contain various metadata about the upgrade, typically application specific +may contain various metadata about the upgrade, typically application-specific upgrade info to be included on-chain such as a git commit that validators could automatically upgrade to. @@ -67,10 +67,10 @@ and not defined on a per-module basis. Registering a `Handler` is done via `Keeper#SetUpgradeHandler` in the application. ```go -type UpgradeHandler func(Context, Plan, VersionMap) (VersionMap, error) +type UpgradeHandler func(ctx context.Context, plan Plan, fromVM module.VersionMap) (module.VersionMap, error) ``` -During each `EndBlock` execution, the `x/upgrade` module checks if there exists a +During each `PreBlock` execution, the `x/upgrade` module checks if there exists a `Plan` that should execute (is scheduled at that height). If so, the corresponding `Handler` is executed. If the `Plan` is expected to execute but no `Handler` is registered or if the binary was upgraded too early, the node will gracefully panic and exit. @@ -79,7 +79,7 @@ or if the binary was upgraded too early, the node will gracefully panic and exit The `x/upgrade` module also facilitates store migrations as part of the upgrade. The `StoreLoader` sets the migrations that need to occur before the new binary can -successfully run the chain. This `StoreLoader` is also application specific and +successfully run the chain. This `StoreLoader` is also application-specific and not defined on a per-module basis. Registering this `StoreLoader` is done via `app#SetStoreLoader` in the application. @@ -89,10 +89,10 @@ func UpgradeStoreLoader (upgradeHeight int64, storeUpgrades *store.StoreUpgrades If there's a planned upgrade and the upgrade height is reached, the old binary writes `Plan` to the disk before panicking. -This information is critical to ensure the `StoreUpgrades` happens smoothly at correct height and +This information is critical to ensure the `StoreUpgrades` happens smoothly at the correct height and expected upgrade. It eliminates the chances for the new binary to execute `StoreUpgrades` multiple -times every time on restart. Also if there are multiple upgrades planned on same height, the `Name` -will ensure these `StoreUpgrades` takes place only in planned upgrade handler. +times every time on restart. Also if there are multiple upgrades planned on the same height, the `Name` +will ensure these `StoreUpgrades` take place only in the planned upgrade handler. ### Proposal @@ -504,7 +504,7 @@ cosmos.upgrade.v1beta1.Query/CurrentPlan Example: ```bash -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/CurrentPlan +grpcurl -plaintext localhost:9090 cosmos.upgrade.v1beta1.Query/CurrentPlan ``` Example Output: @@ -526,7 +526,7 @@ cosmos.upgrade.v1beta1.Query/ModuleVersions Example: ```bash -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/ModuleVersions +grpcurl -plaintext localhost:9090 cosmos.upgrade.v1beta1.Query/ModuleVersions ``` Example Output: diff --git a/docs/build/packages/02-collections.md b/docs/build/packages/02-collections.md index d8f9c17e2..e3abe5ea9 100644 --- a/docs/build/packages/02-collections.md +++ b/docs/build/packages/02-collections.md @@ -122,7 +122,7 @@ var ( #### Rules -``collections.NewPrefix`` accepts either `uint8`, `string` or `[]bytes` it's good practice to use an always increasing `uint8`for disk space efficiency. +``collections.NewPrefix`` accepts either `uint8`, `string` or `[]bytes` it's good practice to use an always increasing `uint8` for disk space efficiency. A collection **MUST NOT** share the same prefix as another collection in the same module, and a collection prefix **MUST NEVER** start with the same prefix as another, examples: @@ -397,7 +397,7 @@ func (k Keeper) RemoveValidator(ctx sdk.Context, validator sdk.ValAddress) error } ``` -The first difference we notice is that `KeySet` needs use to specify only one type parameter: the key (`sdk.ValAddress` in this case). +The first difference we notice is that `KeySet` needs us to specify only one type parameter: the key (`sdk.ValAddress` in this case). The second difference we notice is that `KeySet` in its `NewKeySet` function does not require us to specify a `ValueCodec` but only a `KeyCodec`. This is because a `KeySet` only saves keys and not values. @@ -605,7 +605,7 @@ we specified in the range. Then we use again the `Values` method of the `Iterator` to collect all the results. `collections.Range` also offers a `Prefix` API which is not applicable to all keys types, -for example uint64 cannot be prefix because it is of constant size, but a `string` key +for example uint64 cannot be prefixed because it is of constant size, but a `string` key can be prefixed. #### IterateAccounts @@ -648,7 +648,7 @@ Let's see now how we can work with composite keys using collections. ### Example -In our example we will show-case how we can use collections when we are dealing with balances, similar to bank, +In our example we will showcase how we can use collections when we are dealing with balances, similar to bank, a balance is a mapping between `(address, denom) => math.Int` the composite key in our case is `(address, denom)`. ## Instantiation of a composite key collection diff --git a/docs/build/rfc/rfc/rfc-001-tx-validation.md b/docs/build/rfc/rfc/rfc-001-tx-validation.md index 80dc8e1f2..7b8f0005a 100644 --- a/docs/build/rfc/rfc/rfc-001-tx-validation.md +++ b/docs/build/rfc/rfc/rfc-001-tx-validation.md @@ -22,4 +22,4 @@ We can and will still support the `ValidateBasic` function for users and provide ### Consequences -The consequence of updating the transaction flow is that transaction that may have failed before with the `ValidateBasic` flow will now be included in a block and the fees charged. +The consequence of updating the transaction flow is that transactions that may have failed before with the `ValidateBasic` flow will now be included in a block and the fees charged. diff --git a/docs/build/spec/SPEC_STANDARD.md b/docs/build/spec/SPEC_STANDARD.md index c08fbf046..8b9fec6ff 100644 --- a/docs/build/spec/SPEC_STANDARD.md +++ b/docs/build/spec/SPEC_STANDARD.md @@ -45,7 +45,7 @@ The section may have any or all of the following subsections, as appropriate to * *API* - A detailed description of the feature's API. * *Technical Details* - All technical details including syntax, diagrams, semantics, protocols, data structures, algorithms, and pseudocode as appropriate. The technical specification should be detailed enough such that separate correct implementations of the specification without knowledge of each other are compatible. * *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions. -* *Known Issues* - A list of known issues. This subsection is specially important for specifications of already in-use features. +* *Known Issues* - A list of known issues. This subsection is especially important for specifications of already in-use features. * *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers. ### History diff --git a/docs/build/spec/_ics/ics-030-signed-messages.md b/docs/build/spec/_ics/ics-030-signed-messages.md index a7c56715b..802eaef33 100644 --- a/docs/build/spec/_ics/ics-030-signed-messages.md +++ b/docs/build/spec/_ics/ics-030-signed-messages.md @@ -152,7 +152,7 @@ more complex structures, apart from just string messages, and still be able to know exactly what they are signing (opposed to signing a bunch of arbitrary bytes). Thus, in the future, the Cosmos signing message specification will be expected -to expand upon it's canonical JSON structure to include such functionality. +to expand upon its canonical JSON structure to include such functionality. ## API diff --git a/docs/build/spec/store/README.md b/docs/build/spec/store/README.md index 3bf8b0e34..79bb19359 100644 --- a/docs/build/spec/store/README.md +++ b/docs/build/spec/store/README.md @@ -1,6 +1,6 @@ # Store -The store package defines the interfaces, types and abstractions for Cosmos SDK +The store package defines the interfaces, types, and abstractions for Cosmos SDK modules to read and write to Merkleized state within a Cosmos SDK application. The store package provides many primitives for developers to use in order to work with both state storage and state commitment. Below we describe the various @@ -29,9 +29,9 @@ with, which also provides the basis of most state storage and commitment operati is the `KVStore`. The `KVStore` interface provides basic CRUD abilities and prefix-based iteration, including reverse iteration. -Typically, each module has it's own dedicated `KVStore` instance, which it can +Typically, each module has its own dedicated `KVStore` instance, which it can get access to via the `sdk.Context` and the use of a pointer-based named key -- -`KVStoreKey`. The `KVStoreKey` provides pseudo-OCAP. How a exactly a `KVStoreKey` +`KVStoreKey`. The `KVStoreKey` provides pseudo-OCAP. How exactly a `KVStoreKey` maps to a `KVStore` will be illustrated below through the `CommitMultiStore`. Note, a `KVStore` cannot directly commit state. Instead, a `KVStore` can be wrapped @@ -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` @@ -194,7 +194,7 @@ a `BaseApp` instance which internally has a reference to a `CommitMultiStore` that is implemented by a `rootmulti.Store`. The application then registers one or more `KVStoreKey` that pertain to a unique module and thus a `KVStore`. Through the use of an `sdk.Context` and a `KVStoreKey`, each module can get direct access -to it's respective `KVStore` instance. +to its respective `KVStore` instance. Example: @@ -227,7 +227,7 @@ func NewApp(...) Application { The `rootmulti.Store` itself can be cache-wrapped which returns an instance of a `cachemulti.Store`. For each block, `BaseApp` ensures that the proper abstractions are created on the `CommitMultiStore`, i.e. ensuring that the `rootmulti.Store` -is cached-wrapped and uses the resulting `cachemulti.Store` to be set on the +is cache-wrapped and uses the resulting `cachemulti.Store` to be set on the `sdk.Context` which is then used for block and transaction execution. As a result, all state mutations due to block and transaction execution are actually held ephemerally until `Commit()` is called by the ABCI client. This concept is further 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..6d29aae89 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 @@ -125,7 +125,7 @@ All arguments passed to `cosmovisor run` will be passed to the application binar └── preupgrade.sh (optional) ``` -The `cosmovisor/` directory includes a subdirectory for each version of the application (i.e. `genesis` or `upgrades/`). Within each subdirectory is the application binary (i.e. `bin/$DAEMON_NAME`) and any additional auxiliary files associated with each binary. `current` is a symbolic link to the currently active directory (i.e. `genesis` or `upgrades/`). The `name` variable in `upgrades/` is the lowercased URI-encoded name of the upgrade as specified in the upgrade module plan. Note that the upgrade name path are normalized to be lowercased: for instance, `MyUpgrade` is normalized to `myupgrade`, and its path is `upgrades/myupgrade`. +The `cosmovisor/` directory includes a subdirectory for each version of the application (i.e. `genesis` or `upgrades/`). Within each subdirectory is the application binary (i.e. `bin/$DAEMON_NAME`) and any additional auxiliary files associated with each binary. `current` is a symbolic link to the currently active directory (i.e. `genesis` or `upgrades/`). The `name` variable in `upgrades/` is the lowercased URI-encoded name of the upgrade as specified in the upgrade module plan. Note that upgrade name paths are normalized to lowercase: for instance, `MyUpgrade` is normalized to `myupgrade`, and its path is `upgrades/myupgrade`. Please note that `$DAEMON_HOME/cosmovisor` only stores the *application binaries*. The `cosmovisor` binary itself can be stored in any typical location (e.g. `/usr/local/bin`). The application will continue to store its data in the default data directory (e.g. `$HOME/.simapp`) or the data directory specified with the `--home` flag. `$DAEMON_HOME` is dependent of the data directory and must be set to the same directory as the data directory, you will end up with a configuration like the following: @@ -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..cc9b89993 100644 --- a/docs/learn/advanced/00-baseapp.md +++ b/docs/learn/advanced/00-baseapp.md @@ -234,10 +234,10 @@ The [Application-Blockchain Interface](https://github.com/cometbft/cometbft/blob The consensus engine handles two main tasks: -* The networking logic, which mainly consists in gossiping block parts, transactions and consensus votes. +* The networking logic, which mainly consists of gossiping block parts, transactions and consensus votes. * The consensus logic, which results in the deterministic ordering of transactions in the form of blocks. -It is **not** the role of the consensus engine to define the state or the validity of transactions. Generally, transactions are handled by the consensus engine in the form of `[]bytes`, and relayed to the application via the ABCI to be decoded and processed. At keys moments in the networking and consensus processes (e.g. beginning of a block, commit of a block, reception of an unconfirmed transaction, ...), the consensus engine emits ABCI messages for the state-machine to act on. +It is **not** the role of the consensus engine to define the state or the validity of transactions. Generally, transactions are handled by the consensus engine in the form of `[]bytes`, and relayed to the application via the ABCI to be decoded and processed. At key moments in the networking and consensus processes (e.g. beginning of a block, commit of a block, reception of an unconfirmed transaction, ...), the consensus engine emits ABCI messages for the state-machine to act on. Developers building on top of the Cosmos SDK need not implement the ABCI themselves, as `BaseApp` comes with a built-in implementation of the interface. Let us go through the main ABCI messages that `BaseApp` implements: @@ -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..d48a45582 100644 --- a/docs/learn/advanced/01-transactions.md +++ b/docs/learn/advanced/01-transactions.md @@ -83,7 +83,7 @@ need to sign over the fees: https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/proto/cosmos/tx/v1beta1/tx.proto#L68-L93 ``` -The use case is a multi-signer transaction, where one of the signers is appointed to gather all signatures, broadcast the signature and pay for fees, and the others only care about the transaction body. This generally allows for a better multi-signing UX. If Alice, Bob and Charlie are part of a 3-signer transaction, then Alice and Bob can both use `SIGN_MODE_DIRECT_AUX` to sign over the `TxBody` and their own signer info (no need an additional step to gather other signers' ones, like in `SIGN_MODE_DIRECT`), without specifying a fee in their SignDoc. Charlie can then gather both signatures from Alice and Bob, and +The use case is a multi-signer transaction, where one of the signers is appointed to gather all signatures, broadcast the signature and pay for fees, and the others only care about the transaction body. This generally allows for a better multi-signing UX. If Alice, Bob and Charlie are part of a 3-signer transaction, then Alice and Bob can both use `SIGN_MODE_DIRECT_AUX` to sign over the `TxBody` and their own signer info (no need for an additional step to gather other signers' ones, like in `SIGN_MODE_DIRECT`), without specifying a fee in their SignDoc. Charlie can then gather both signatures from Alice and Bob, and create the final transaction by appending a fee. Note that the fee payer of the transaction (in our case Charlie) must sign over the fees, so must use `SIGN_MODE_DIRECT` or `SIGN_MODE_LEGACY_AMINO_JSON`. @@ -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). @@ -128,7 +128,7 @@ While messages contain the information for state transition logic, a transaction ### Transaction Generation -The `TxBuilder` interface contains data closely related with the generation of transactions, which an end-user can set to generate the desired transaction: +The `TxBuilder` interface contains data closely related to the generation of transactions, which an end-user can set to generate the desired transaction: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/client/tx_config.go#L39-L57 @@ -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/00-app-anatomy.md b/docs/learn/beginner/00-app-anatomy.md index 988c7242a..1957666c5 100644 --- a/docs/learn/beginner/00-app-anatomy.md +++ b/docs/learn/beginner/00-app-anatomy.md @@ -147,7 +147,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/simapp/params/encoding.go#L9-L Here are descriptions of what each of the four fields means: -* `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces that are encoded and decoded (we also say "unpacked") using [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto). `Any` could be thought as a struct that contains a `type_url` (name of a concrete type implementing the interface) and a `value` (its encoded bytes). `InterfaceRegistry` provides a mechanism for registering interfaces and implementations that can be safely unpacked from `Any`. Each application module implements the `RegisterInterfaces` method that can be used to register the module's own interfaces and implementations. +* `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces that are encoded and decoded (we also say "unpacked") using [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto). `Any` could be thought of as a struct that contains a `type_url` (name of a concrete type implementing the interface) and a `value` (its encoded bytes). `InterfaceRegistry` provides a mechanism for registering interfaces and implementations that can be safely unpacked from `Any`. Each application module implements the `RegisterInterfaces` method that can be used to register the module's own interfaces and implementations. * You can read more about `Any` in [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md). * To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/cosmos/gogoproto). By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/cosmos/gogoproto/types) uses [global type registration](https://github.com/cosmos/gogoproto/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could register a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md). * `Codec`: The default codec used throughout the Cosmos SDK. It is composed of a `BinaryCodec` used to encode and decode state, and a `JSONCodec` used to output data to the users (for example, in the [CLI](#cli)). By default, the SDK uses Protobuf as `Codec`. @@ -255,7 +255,7 @@ The Cosmos SDK also provides a development endpoint to generate [Swagger](https: The main interface is the [Command-Line Interface](../advanced/07-cli.md). The CLI of a Cosmos SDK application is built by aggregating [CLI commands](#cli) defined in each of the modules used by the application. The CLI of an application is the same as the daemon (e.g. `appd`), and is defined in a file called `appd/main.go`. The file contains the following: * **A `main()` function**, which is executed to build the `appd` interface client. This function prepares each command and adds them to the `rootCmd` before building them. At the root of `appd`, the function adds generic commands like `status`, `keys`, and `config`, query commands, tx commands, and `rest-server`. -* **Query commands**, which are added by calling the `queryCmd` function. This function returns a Cobra command that contains the query commands defined in each of the application's modules (passed as an array of `sdk.ModuleClients` from the `main()` function), as well as some other lower level query commands such as block or validator queries. Query command are called by using the command `appd query [query]` of the CLI. +* **Query commands**, which are added by calling the `queryCmd` function. This function returns a Cobra command that contains the query commands defined in each of the application's modules (passed as an array of `sdk.ModuleClients` from the `main()` function), as well as some other lower level query commands such as block or validator queries. Query commands are called by using the command `appd query [query]` of the CLI. * **Transaction commands**, which are added by calling the `txCmd` function. Similar to `queryCmd`, the function returns a Cobra command that contains the tx commands defined in each of the application's modules, as well as lower level tx commands like transaction signing or broadcasting. Tx commands are called by using the command `appd tx [tx]` of the CLI. See an example of an application's main command-line file from the [Cosmos Hub](https://github.com/cosmos/gaia). diff --git a/docs/learn/beginner/01-tx-lifecycle.md b/docs/learn/beginner/01-tx-lifecycle.md index b004b355b..8f605c4f2 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 @@ -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,7 +126,7 @@ 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. @@ -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 @@ -246,7 +246,7 @@ Instead of using their `checkState`, full-nodes use `finalizeblock`: * **`Msg` service:** Protobuf `Msg` service is responsible for executing each message in the `Tx` and causes state transitions to persist in `finalizeBlockState`. -* **PostHandlers:** [`PostHandler`](../advanced/00-baseapp.md#posthandler)s run after the execution of the message. If they fail, the state change of `runMsgs`, as well of `PostHandlers`, are both reverted. +* **PostHandlers:** [`PostHandler`](../advanced/00-baseapp.md#posthandler)s run after the execution of the message. If they fail, the state change of `runMsgs`, as well as `PostHandlers`, are both reverted. * **Gas:** While a `Tx` is being delivered, a `GasMeter` is used to keep track of how much gas is being used; if execution completes, `GasUsed` is set and returned in the diff --git a/docs/learn/beginner/02-query-lifecycle.md b/docs/learn/beginner/02-query-lifecycle.md index 4b11bfed6..a30f075ce 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: @@ -74,7 +74,7 @@ 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. * **Output Writer**: A [Writer](https://pkg.go.dev/io/#Writer) used to output the response. @@ -96,21 +96,21 @@ At this point in the lifecycle, the user has created a CLI command with all of t In our case (querying an address's delegations), `MyQuery` contains an [address](./03-accounts.md#addresses) `delegatorAddress` as its only argument. However, the request can only contain `[]byte`s, as it is ultimately relayed to a consensus engine (e.g. CometBFT) of a full-node that has no inherent knowledge of the application types. Thus, the `codec` of `client.Context` is used to marshal the address. -Here is what the code looks like for the CLI command: +Here is what the Protobuf definition for this query looks like: -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/x/staking/client/cli/query.go#L315-L318 +```protobuf reference +https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/proto/cosmos/staking/v1beta1/query.proto#L240-L251 ``` #### gRPC Query Client Creation -The Cosmos SDK leverages code generated from Protobuf services to make queries. The `staking` module's `MyQuery` service generates a `queryClient`, which the CLI uses to make queries. Here is the relevant code: +The Cosmos SDK leverages code generated from Protobuf services to make queries. The `staking` module's query service generates a `QueryClient`, and the CLI uses AutoCLI configuration to expose it as the `simd query staking delegations` command. The mapping between the CLI command and the underlying RPC method is defined in the module's AutoCLI options: ```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/x/staking/client/cli/query.go#L308-L343 +https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/x/staking/autocli.go#L13-L81 ``` -Under the hood, the `client.Context` has a `Query()` function used to retrieve the pre-configured node and relay a query to it; the function takes the query fully-qualified service method name as path (in our case: `/cosmos.staking.v1beta1.Query/Delegations`), and arguments as parameters. It first retrieves the RPC Client (called the [**node**](../advanced/03-node.md)) configured by the user to relay this query to, and creates the `ABCIQueryOptions` (parameters formatted for the ABCI call). The node is then used to make the ABCI call, `ABCIQueryWithOptions()`. +Under the hood, the `client.Context` has a `Query()` function used to retrieve the pre-configured node and relay a query to it; the function takes the query fully-qualified service method name as path (in our case: `/cosmos.staking.v1beta1.Query/DelegatorDelegations`), and arguments as parameters. It first retrieves the RPC Client (called the [**node**](../advanced/03-node.md)) configured by the user to relay this query to, and creates the `ABCIQueryOptions` (parameters formatted for the ABCI call). The node is then used to make the ABCI call, `ABCIQueryWithOptions()`. Here is what the code looks like: @@ -128,13 +128,13 @@ Read more about ABCI Clients and CometBFT RPC in the [CometBFT documentation](ht When a query is received by the full-node after it has been relayed from the underlying consensus engine, it is at that point being handled within an environment that understands application-specific types and has a copy of the state. [`baseapp`](../advanced/00-baseapp.md) implements the ABCI [`Query()`](../advanced/00-baseapp.md#query) function and handles gRPC queries. The query route is parsed, and it matches the fully-qualified service method name of an existing service method (most likely in one of the modules), then `baseapp` relays the request to the relevant module. -Since `MyQuery` has a Protobuf fully-qualified service method name from the `staking` module (recall `/cosmos.staking.v1beta1.Query/Delegations`), `baseapp` first parses the path, then uses its own internal `GRPCQueryRouter` to retrieve the corresponding gRPC handler, and routes the query to the module. The gRPC handler is responsible for recognizing this query, retrieving the appropriate values from the application's stores, and returning a response. Read more about query services [here](../../build/building-modules/04-query-services.md). +Since `MyQuery` has a Protobuf fully-qualified service method name from the `staking` module (recall `/cosmos.staking.v1beta1.Query/DelegatorDelegations`), `baseapp` first parses the path, then uses its own internal `GRPCQueryRouter` to retrieve the corresponding gRPC handler, and routes the query to the module. The gRPC handler is responsible for recognizing this query, retrieving the appropriate values from the application's stores, and returning a response. Read more about query services [here](../../build/building-modules/04-query-services.md). Once a result is received from the querier, `baseapp` begins the process of returning a response to the user. ## 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. ### CLI Response diff --git a/docs/learn/beginner/03-accounts.md b/docs/learn/beginner/03-accounts.md index 150436b9d..28ddd5838 100644 --- a/docs/learn/beginner/03-accounts.md +++ b/docs/learn/beginner/03-accounts.md @@ -75,7 +75,7 @@ The Cosmos SDK supports the following digital key schemes for creating digital s * `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/crypto/keys/secp256r1/pubkey.go). * `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation. -| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (cometbft) | +| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (CometBFT) | | :----------: | :---------------------: | :------------------------: | :---------------------------------: | :-----------------------------: | | `secp256k1` | 20 | 33 | yes | no | | `secp256r1` | 32 | 33 | yes | no | @@ -152,7 +152,7 @@ The default implementation of `Keyring` comes from the third-party [`99designs/k A few notes on the `Keyring` methods: -* `Sign(uid string, msg []byte) ([]byte, types.PubKey, error)` strictly deals with the signature of the `msg` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../../build/architecture/adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../advanced/00-baseapp.md#antehandler). +* `Sign(uid string, msg []byte, signMode signing.SignMode) ([]byte, types.PubKey, error)` strictly deals with the signature of the `msg` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../../build/architecture/adr-027-deterministic-protobuf-serialization.md). The `signMode` parameter controls which signing mode is used (for example `SIGN_MODE_TEXTUAL` or `SIGN_MODE_LEGACY_AMINO_JSON`) and therefore how the `msg` bytes are produced. Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../advanced/00-baseapp.md#antehandler). ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/proto/cosmos/tx/v1beta1/tx.proto#L50-L67 @@ -167,7 +167,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/proto/cosmos/tx/v1beta1/tx.pro ### Create New Key Type -To create a new key type for using in keyring, `keyring.SignatureAlgo` interface must be fulfilled. +To create a new key type for use in the keyring, the `keyring.SignatureAlgo` interface must be fulfilled. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/crypto/keyring/signing_algorithms.go#L11-L16 @@ -194,7 +194,7 @@ First a new function to create a private key from a secret number is needed in t ```go // cosmos-sdk/crypto/keys/secp256r1/privkey.go -// NewPrivKeyFromSecret creates a private key derived for the secret number +// NewPrivKeyFromSecret creates a private key derived from the secret number // represented in big-endian. The `secret` must be a valid ECDSA field element. func NewPrivKeyFromSecret(secret []byte) (*PrivKey, error) { var d = new(big.Int).SetBytes(secret) diff --git a/docs/learn/beginner/04-gas-fees.md b/docs/learn/beginner/04-gas-fees.md index 5aea1238b..e0bfbd57c 100644 --- a/docs/learn/beginner/04-gas-fees.md +++ b/docs/learn/beginner/04-gas-fees.md @@ -16,10 +16,10 @@ This document describes the default strategies to handle gas and fees within a C ## Introduction to `Gas` and `Fees` -In the Cosmos SDK, `gas` is a special unit that is used to track the consumption of resources during execution. `gas` is typically consumed whenever read and writes are made to the store, but it can also be consumed if expensive computation needs to be done. It serves two main purposes: +In the Cosmos SDK, `gas` is a special unit that is used to track the consumption of resources during execution. `gas` is typically consumed whenever reads and writes are made to the store, but it can also be consumed if expensive computation needs to be done. It serves two main purposes: * Make sure blocks are not consuming too many resources and are finalized. This is implemented by default in the Cosmos SDK via the [block gas meter](#block-gas-meter). -* Prevent spam and abuse from end-user. To this end, `gas` consumed during [`message`](../../build/building-modules/02-messages-and-queries.md#messages) execution is typically priced, resulting in a `fee` (`fees = gas * gas-prices`). `fees` generally have to be paid by the sender of the `message`. Note that the Cosmos SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications implement `fee` mechanisms to prevent spam by using the [`AnteHandler`](#antehandler). +* Prevent spam and abuse by end-users. To this end, `gas` consumed during [`message`](../../build/building-modules/02-messages-and-queries.md#messages) execution is typically priced, resulting in a `fee` (`fees = gas * gas-prices`). `fees` generally have to be paid by the sender of the `message`. Note that the Cosmos SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications implement `fee` mechanisms to prevent spam by using the [`AnteHandler`](#antehandler). ## Gas Meter @@ -98,4 +98,4 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.53.0-rc.2/proto/cosmos/tx/v1beta1/t * Verify that the sender of the transaction has enough funds to cover for the `fees`. When the end-user generates a transaction, they must indicate 2 of the 3 following parameters (the third one being implicit): `fees`, `gas` and `gas-prices`. This signals how much they are willing to pay for nodes to execute their transaction. The provided `gas` value is stored in a parameter called `GasWanted` for later use. * Set `newCtx.GasMeter` to 0, with a limit of `GasWanted`. **This step is crucial**, as it not only makes sure the transaction cannot consume infinite gas, but also that `ctx.GasMeter` is reset in-between each transaction (`ctx` is set to `newCtx` after `anteHandler` is run, and the `anteHandler` is run each time a transaction executes). -As explained above, the `anteHandler` returns a maximum limit of `gas` the transaction can consume during execution called `GasWanted`. The actual amount consumed in the end is denominated `GasUsed`, and we must therefore have `GasUsed =< GasWanted`. Both `GasWanted` and `GasUsed` are relayed to the underlying consensus engine when [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock) returns. +As explained above, the `anteHandler` returns a maximum limit of `gas` the transaction can consume during execution called `GasWanted`. The actual amount consumed in the end is denominated `GasUsed`, and we must therefore have `GasUsed <= GasWanted`. Both `GasWanted` and `GasUsed` are relayed to the underlying consensus engine when [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock) returns. diff --git a/docs/learn/intro/00-overview.md b/docs/learn/intro/00-overview.md index f1e896f39..62a7332da 100644 --- a/docs/learn/intro/00-overview.md +++ b/docs/learn/intro/00-overview.md @@ -7,13 +7,13 @@ sidebar_position: 1 The [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is an open-source toolkit for building multi-asset public Proof-of-Stake (PoS) blockchains, like the Cosmos Hub, as well as permissioned Proof-of-Authority (PoA) blockchains. Blockchains built with the Cosmos SDK are generally referred to as **application-specific blockchains**. The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. -We further this modular approach by allowing developers to plug and play with different consensus engines this can range from the [CometBFT](https://github.com/cometbft/cometbft) or [Rollkit](https://rollkit.dev/). +We further this modular approach by allowing developers to plug and play with different consensus engines. This can range from the [CometBFT](https://github.com/cometbft/cometbft) or [Rollkit](https://rollkit.dev/). SDK-based blockchains have the choice to use the predefined modules or to build their own modules. What this means is that developers can build a blockchain that is tailored to their specific use case, without having to worry about the low-level details of building a blockchain from scratch. Predefined modules include staking, governance, and token issuance, among others. What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../advanced/10-ocap.md). -How you can look at this is if we imagine that the SDK is like a lego kit. You can choose to build the basic house from the instructions or you can choose to modify your house and add more floors, more doors, more windows. The choice is yours. +How you can look at this is if we imagine that the SDK is like a LEGO kit. You can choose to build the basic house from the instructions or you can choose to modify your house and add more floors, more doors, more windows. The choice is yours. ## What are Application-Specific Blockchains diff --git a/docs/learn/intro/01-why-app-specific.md b/docs/learn/intro/01-why-app-specific.md index df16c19af..bee2ae37e 100644 --- a/docs/learn/intro/01-why-app-specific.md +++ b/docs/learn/intro/01-why-app-specific.md @@ -32,7 +32,7 @@ Blockchain node | | Consensus | | Virtual-machine blockchains like Ethereum addressed the demand for more programmability back in 2014. At the time, the options available for building decentralized applications were quite limited. Most developers would build on top of the complex and limited Bitcoin scripting language, or fork the Bitcoin codebase which was hard to work with and customize. -Virtual-machine blockchains came in with a new value proposition. Their state-machine incorporates a virtual-machine that is able to interpret turing-complete programs called Smart Contracts. These Smart Contracts are very good for use cases like one-time events (e.g. ICOs), but they can fall short for building complex decentralized platforms. Here is why: +Virtual-machine blockchains came in with a new value proposition. Their state-machine incorporates a virtual-machine that is able to interpret Turing-complete programs called Smart Contracts. These Smart Contracts are very good for use cases like one-time events (e.g. ICOs), but they can fall short for building complex decentralized platforms. Here is why: * Smart Contracts are generally developed with specific programming languages that can be interpreted by the underlying virtual-machine. These programming languages are often immature and inherently limited by the constraints of the virtual-machine itself. For example, the Ethereum Virtual Machine does not allow developers to implement automatic execution of code. Developers are also limited to the account-based system of the EVM, and they can only choose from a limited set of functions for their cryptographic operations. These are examples, but they hint at the lack of **flexibility** that a smart contract environment often entails. * Smart Contracts are all run by the same virtual machine. This means that they compete for resources, which can severely restrain **performance**. And even if the state-machine were to be split in multiple subsets (e.g. via sharding), Smart Contracts would still need to be interpreted by a virtual machine, which would limit performance compared to a native application implemented at state-machine level (our benchmarks show an improvement on the order of 10x in performance when the virtual-machine is removed). diff --git a/docs/learn/intro/03-sdk-design.md b/docs/learn/intro/03-sdk-design.md index 6ecffbe02..3d93ae945 100644 --- a/docs/learn/intro/03-sdk-design.md +++ b/docs/learn/intro/03-sdk-design.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Main Components of the Cosmos SDK -The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of CometBFT. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./02-sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../advanced/04-store.md#multistore) to persist data and a [`router`](../advanced/00-baseapp.md#routing) to handle transactions. +The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of CometBFT. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./02-sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../advanced/04-store.md#multistore) to persist data and a [`router`](../advanced/00-baseapp.md#service-routers) to handle transactions. Here is a simplified view of how transactions are handled by an application built on top of the Cosmos SDK when transferred from CometBFT via `DeliverTx`: diff --git a/docs/user/run-node/06-run-production.md b/docs/user/run-node/06-run-production.md index 6eee48087..6cf957b40 100644 --- a/docs/user/run-node/06-run-production.md +++ b/docs/user/run-node/06-run-production.md @@ -40,10 +40,10 @@ Now when logging into the server, the non `root` user can be used. ### Go -1. Install the [Go](https://go.dev/doc/install) version preconized by the application. +1. Install the [Go](https://go.dev/doc/install) version recommended by the application. :::warning -In the past, validators [have had issues](https://github.com/cosmos/cosmos-sdk/issues/13976) when using different versions of Go. It is recommended that the whole validator set uses the version of Go that is preconized by the application. +In the past, validators [have had issues](https://github.com/cosmos/cosmos-sdk/issues/13976) when using different versions of Go. It is recommended that the whole validator set uses the version of Go that is recommended by the application. ::: ### Firewall