Co-authored-by: mmsqe <mavis@crypto.com> Co-authored-by: Julien Robert <julien@rbrt.fr>
This commit is contained in:
mergify[bot]
co-authored by
mmsqe
Julien Robert
mmsqe
Julien Robert
parent
92d1d9a106
commit
4c083c6f23
@@ -92,3 +92,4 @@ When writing ADRs, follow the same best practices for writing RFCs. When writing
|
||||
* [ADR 044: Guidelines for Updating Protobuf Definitions](./adr-044-protobuf-updates-guidelines.md)
|
||||
* [ADR 047: Extend Upgrade Plan](./adr-047-extend-upgrade-plan.md)
|
||||
* [ADR 053: Go Module Refactoring](./adr-053-go-module-refactoring.md)
|
||||
* [ADR 068: Preblock](./adr-068-preblock.md)
|
||||
|
||||
@@ -280,6 +280,17 @@ type HasGenesis interface {
|
||||
}
|
||||
```
|
||||
|
||||
#### Pre Blockers
|
||||
|
||||
Modules that have functionality that runs before BeginBlock and should implement the has `HasPreBlocker` interfaces:
|
||||
|
||||
```go
|
||||
type HasPreBlocker interface {
|
||||
AppModule
|
||||
PreBlock(context.Context) error
|
||||
}
|
||||
```
|
||||
|
||||
#### Begin and End Blockers
|
||||
|
||||
Modules that have functionality that runs before transactions (begin blockers) or after transactions
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# ADR 068: Preblock
|
||||
|
||||
## Changelog
|
||||
|
||||
* Sept 13, 2023: Initial Draft
|
||||
|
||||
## Status
|
||||
|
||||
DRAFT
|
||||
|
||||
## Abstract
|
||||
|
||||
Introduce `PreBlock`, which runs before begin blocker other modules, and allows to modify consensus parameters, and the changes are visible to the following state machine logics.
|
||||
|
||||
## Context
|
||||
|
||||
When upgrading to sdk 0.47, the storage format for consensus parameters changed, but in the migration block, `ctx.ConsensusParams()` is always `nil`, because it fails to load the old format using new code, it's supposed to be migrated by the `x/upgrade` module first, but unfortunately, the migration happens in `BeginBlocker` handler, which runs after the `ctx` is initialized.
|
||||
When we try to solve this, we find the `x/upgrade` module can't modify the context to make the consensus parameters visible for the other modules, the context is passed by value, and sdk team want to keep it that way, that's good for isolations between modules.
|
||||
|
||||
## Alternatives
|
||||
|
||||
The first alternative solution introduced a `MigrateModuleManager`, which only includes the `x/upgrade` module right now, and baseapp will run their `BeginBlocker`s before the other modules, and reload context's consensus parameters in between.
|
||||
|
||||
## Decision
|
||||
|
||||
Suggested this new lifecycle method.
|
||||
|
||||
### `PreBlocker`
|
||||
|
||||
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 parameter in the finalize context:
|
||||
```
|
||||
app.finalizeBlockState.ctx = app.finalizeBlockState.ctx.WithConsensusParams(app.GetConsensusParams())
|
||||
```
|
||||
|
||||
The new ctx must be passed to all the other lifecycle methods.
|
||||
|
||||
|
||||
## Consequences
|
||||
|
||||
### Backwards Compatibility
|
||||
|
||||
### Positive
|
||||
|
||||
### Negative
|
||||
|
||||
### Neutral
|
||||
|
||||
## Further Discussions
|
||||
|
||||
## Test Cases
|
||||
|
||||
## References
|
||||
* [1] https://github.com/cosmos/cosmos-sdk/issues/16494
|
||||
* [2] https://github.com/cosmos/cosmos-sdk/pull/16583
|
||||
* [3] https://github.com/cosmos/cosmos-sdk/pull/17421
|
||||
+1
-1
@@ -37,7 +37,7 @@ The `app_config.go` file is the single place to configure all modules parameters
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L103-L167
|
||||
```
|
||||
|
||||
3. Configure the modules defined in the `BeginBlocker` and `EndBlocker` and the `tx` module:
|
||||
3. Configure the modules defined in the `PreBlocker`, `BeginBlocker` and `EndBlocker` and the `tx` module:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L112-L129
|
||||
|
||||
+18
@@ -50,6 +50,24 @@ the rest of the block as normal. Once 2/3 of the voting power has upgraded, the
|
||||
resume the consensus mechanism. If the majority of operators add a custom `do-upgrade` script, this should
|
||||
be a matter of minutes and not even require them to be awake at that time.
|
||||
|
||||
## Set PreBlocker
|
||||
|
||||
:::tip
|
||||
Users using `depinject` / app v2 do not need any changes, this is abstracted for them.
|
||||
:::
|
||||
|
||||
Call `SetPreBlocker` to run `PreBlock`:
|
||||
|
||||
```go
|
||||
app.SetPreBlocker(app.PreBlocker)
|
||||
```
|
||||
|
||||
```go
|
||||
func (app *SimApp) PreBlocker(ctx sdk.Context, req abci.RequestBeginBlock) (sdk.ResponsePreBlock, error) {
|
||||
return app.ModuleManager.PreBlock(ctx, req)
|
||||
}
|
||||
```
|
||||
|
||||
## Integrating With An App
|
||||
|
||||
Setup an upgrade Keeper for the app and then define a `BeginBlocker` that calls the upgrade
|
||||
|
||||
+12
-7
@@ -5,7 +5,7 @@ sidebar_position: 1
|
||||
# Module Manager
|
||||
|
||||
:::note Synopsis
|
||||
Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../../develop/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../../develop/beginner/00-app-anatomy.md#begingblocker-and-endblocker).
|
||||
Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../../develop/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`PreBlocker`](../../develop/beginner/00-app-anatomy#preblocker) and [`BeginBlocker` and `EndBlocker`](../../develop/beginner/00-app-anatomy.md#begingblocker-and-endblocker).
|
||||
:::
|
||||
|
||||
:::note Pre-requisite Readings
|
||||
@@ -36,6 +36,7 @@ The above interfaces are mostly embedding smaller interfaces (extension interfac
|
||||
* [`module.HasGenesis`](#modulehasgenesis) for inter-dependent genesis-related module functionalities.
|
||||
* [`module.HasABCIGenesis`](#modulehasabcigenesis) for inter-dependent genesis-related module functionalities.
|
||||
* [`appmodule.HasGenesis` / `module.HasGenesis`](#appmodulehasgenesis): The extension interface for stateful genesis methods.
|
||||
* [`appmodule.HasPreBlocker`](#haspreblocker): The extension interface that contains information about the `AppModule` and `PreBlock`.
|
||||
* [`appmodule.HasBeginBlocker`](#hasbeginblocker): The extension interface that contains information about the `AppModule` and `BeginBlock`.
|
||||
* [`appmodule.HasEndBlocker`](#hasendblocker): The extension interface that contains information about the `AppModule` and `EndBlock`.
|
||||
* [`appmodule.HasPrecommit`](#hasprecommit): The extension interface that contains information about the `AppModule` and `Precommit`.
|
||||
@@ -181,6 +182,10 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go
|
||||
|
||||
* `ConsensusVersion() uint64`: Returns the consensus version of the module.
|
||||
|
||||
### `HasPreBlocker`
|
||||
|
||||
The `HasPreBlocker` is an extension interface from `appmodule.AppModule`. All modules that have an `PreBlock` method implement this interface.
|
||||
|
||||
### `HasBeginBlocker`
|
||||
|
||||
The `HasBeginBlocker` is an extension interface from `appmodule.AppModule`. All modules that have an `BeginBlock` method implement this interface.
|
||||
@@ -291,6 +296,7 @@ The module manager is used throughout the application whenever an action on a co
|
||||
* `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function).
|
||||
To initialize modules successfully, module dependencies should be considered. For example, the `genutil` module must occur after `staking` module so that the pools are properly initialized with tokens from genesis accounts, the `genutils` module must also occur after `auth` so that it can access the params from auth, IBC's `capability` module should be initialized before all other modules so that it can initialize any capabilities.
|
||||
* `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function).
|
||||
* `SetOrderPreBlockers(moduleNames ...string)`: Sets the order in which the `PreBlock()` function of each module will be called before `BeginBlock()` of all modules. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function).
|
||||
* `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function).
|
||||
* `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function).
|
||||
* `SetOrderPrecommiters(moduleNames ...string)`: Sets the order in which the `Precommit()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function).
|
||||
@@ -301,12 +307,11 @@ The module manager is used throughout the application whenever an action on a co
|
||||
* `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`](.../../develop/advanced#beginblock) and, in turn, calls the [`BeginBlock`](./06-beginblock-endblock.md) function of all modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from modules.
|
||||
* `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](.../../develop/advanced#endblock) and, in turn, calls the [`EndBlock`](./06-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any).
|
||||
* `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](.../../develop/advanced#endblock) and, in turn, calls the [`EndBlock`](./06-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any).
|
||||
* `Precommit(ctx context.Context)`: During [`Commit`](.../../develop/advanced#commit), this function is called from `BaseApp` immediately before the [`deliverState`](.../../develop/advanced#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](.../../develop/advanced#state-updates).
|
||||
* `PrepareCheckState(ctx context.Context)`: During [`Commit`](.../../develop/advanced#commit), this function is called from `BaseApp` immediately after the [`deliverState`](.../../develop/advanced#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](.../../develop/advanced#state-updates). Writes to this state will be present in the [`checkState`](.../../develop/advanced#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block.
|
||||
* `RunMigrationBeginBlock(ctx sdk.Context) (bool, error)`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./06-beginblock-endblock.md) function of the upgrade module implementing the `HasBeginBlocker` interface. The function returns a boolean value indicating whether the migration was executed or not and an error if fails.
|
||||
* `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from each modules.
|
||||
* `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any).
|
||||
* `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any).
|
||||
* `Precommit(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../../develop/advanced/00-baseapp.md#state-updates).
|
||||
* `PrepareCheckState(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../../develop/advanced/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../../develop/advanced/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block.
|
||||
|
||||
Here's an example of a concrete integration within an `simapp`:
|
||||
|
||||
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# PreBlocker
|
||||
|
||||
:::note Synopsis
|
||||
`PreBlocker` is optional method module developers can implement in their module. They will be triggered before [`BeginBlock`](../../develop/advanced/00-baseapp.md#beginblock).
|
||||
:::
|
||||
|
||||
:::note Pre-requisite Readings
|
||||
|
||||
* [Module Manager](./01-module-manager.md)
|
||||
|
||||
:::
|
||||
|
||||
## PreBlocker
|
||||
|
||||
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 parameter in the deliver context:
|
||||
```
|
||||
app.finalizeBlockState.ctx = app.finalizeBlockState.ctx.WithConsensusParams(app.GetConsensusParams())
|
||||
```
|
||||
|
||||
The new ctx must be passed to all the other lifecycle methods.
|
||||
|
||||
<!-- TODO: leaving this here to update docs with core api changes -->
|
||||
@@ -78,8 +78,7 @@ First, the important parameters that are initialized during the bootstrapping of
|
||||
* [`AnteHandler`](#antehandler): This handler is used to handle signature verification, fee payment,
|
||||
and other pre-message execution checks when a transaction is received. It's executed during
|
||||
[`CheckTx/RecheckTx`](#checktx) and [`FinalizeBlock`](#finalizeblock).
|
||||
* [`InitChainer`](../beginner/00-app-anatomy.md#initchainer),
|
||||
[`BeginBlocker` and `EndBlocker`](../beginner/00-app-anatomy.md#beginblocker-and-endblocker): These are
|
||||
* [`InitChainer`](../beginner/00-app-anatomy.md#initchainer), [`PreBlocker`](../beginner/00-app-anatomy.md#preblocker), [`BeginBlocker` and `EndBlocker`](../beginner/00-app-anatomy.md#beginblocker-and-endblocker): These are
|
||||
the functions executed when the application receives the `InitChain` and `FinalizeBlock`
|
||||
ABCI messages from the underlying CometBFT engine.
|
||||
|
||||
@@ -444,6 +443,10 @@ The [`FinalizeBlock` ABCI message](https://github.com/cometbft/cometbft/blob/v0.
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci.go#L623
|
||||
```
|
||||
|
||||
#### PreBlock
|
||||
|
||||
* Run the application's [`preBlocker()`](../beginner/00-app-anatomy.md#preblocker), which mainly runs the [`PreBlocker()`](../building-modules/17-preblock.md#preblock) method of each of the modules.
|
||||
|
||||
#### BeginBlock
|
||||
|
||||
* Initialize [`finalizeBlockState`](#state-updates) with the latest header using the `req abci.RequestFinalizeBlock` passed as parameter via the `setState` function.
|
||||
@@ -454,8 +457,8 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci.go#L623
|
||||
|
||||
This function also resets the [main gas meter](../beginner/04-gas-fees.md#main-gas-meter).
|
||||
|
||||
* Initialize the [block gas meter](../basics/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters.
|
||||
* Run the application's [`beginBlocker()`](../basics/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/05-beginblock-endblock.md#beginblock) method of each of the application's modules.
|
||||
* Initialize the [block gas meter](../beginner/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters.
|
||||
* Run the application's [`beginBlocker()`](../beginner/00-app-anatomy.md#beginblocker-and-endblocker), which mainly runs the [`BeginBlocker()`](../../build/building-modules/05-beginblock-endblock.md#beginblock) method of each of the modules.
|
||||
* Set the [`VoteInfos`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./02-context.md) so that it can be used during transaction execution and EndBlock.
|
||||
|
||||
#### Transaction Execution
|
||||
|
||||
@@ -55,7 +55,7 @@ The first thing defined in `app.go` is the `type` of the application. It is gene
|
||||
* **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../../build/building-modules/06-keeper.md), which handles reads and writes for this module's store(s). The `keeper`'s methods of one module can be called from other modules (if authorized), which is why they are declared in the application's type and exported as interfaces to other modules so that the latter can only access the authorized functions.
|
||||
* **A reference to an [`appCodec`](../advanced/05-encoding.md).** The application's `appCodec` is used to serialize and deserialize data structures in order to store them, as stores can only persist `[]bytes`. The default codec is [Protocol Buffers](../advanced/05-encoding.md).
|
||||
* **A reference to a [`legacyAmino`](../advanced/05-encoding.md) codec.** Some parts of the Cosmos SDK have not been migrated to use the `appCodec` above, and are still hardcoded to use Amino. Other parts explicitly use Amino for backwards compatibility. For these reasons, the application still holds a reference to the legacy Amino codec. Please note that the Amino codec will be removed from the SDK in the upcoming releases.
|
||||
* **A reference to a [module manager](../../build/building-modules/01-module-manager.md#manager)** and a [basic module manager](../../build/building-modules/01-module-manager.md#basicmanager). The module manager is an object that contains a list of the application's modules. It facilitates operations related to these modules, like registering their [`Msg` service](../advanced/00-baseapp.md#msg-services) and [gRPC `Query` service](../advanced/00-baseapp.md#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker).
|
||||
* **A reference to a [module manager](../../build/building-modules/01-module-manager.md#manager)** and a [basic module manager](../../build/building-modules/01-module-manager.md#basicmanager). The module manager is an object that contains a list of the application's modules. It facilitates operations related to these modules, like registering their [`Msg` service](../advanced/00-baseapp.md#msg-services) and [gRPC `Query` service](../advanced/00-baseapp.md#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`PreBlocker`](#preblocker) and [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker).
|
||||
|
||||
See an example of application type definition from `simapp`, the Cosmos SDK's own app used for demo and testing purposes:
|
||||
|
||||
@@ -79,10 +79,11 @@ Here are the main actions performed by this function:
|
||||
* Instantiate the application's [module manager](../../build/building-modules/01-module-manager.md#manager) with the [`AppModule`](#application-module-interface) object of each of the application's modules.
|
||||
* With the module manager, initialize the application's [`Msg` services](../advanced/00-baseapp.md#msg-services), [gRPC `Query` services](../advanced/00-baseapp.md#grpc-query-services), [legacy `Msg` routes](../advanced/00-baseapp.md#routing), and [legacy query routes](../advanced/00-baseapp.md#query-routing). When a transaction is relayed to the application by CometBFT via the ABCI, it is routed to the appropriate module's [`Msg` service](#msg-services) using the routes defined here. Likewise, when a gRPC query request is received by the application, it is routed to the appropriate module's [`gRPC query service`](#grpc-query-services) using the gRPC routes defined here. The Cosmos SDK still supports legacy `Msg`s and legacy CometBFT queries, which are routed using the legacy `Msg` routes and the legacy query routes, respectively.
|
||||
* With the module manager, register the [application's modules' invariants](../../build/building-modules/07-invariants.md). Invariants are variables (e.g. total supply of a token) that are evaluated at the end of each block. The process of checking invariants is done via a special module called the [`InvariantsRegistry`](../../build/building-modules/07-invariants.md#invariant-registry). The value of the invariant should be equal to a predicted value defined in the module. Should the value be different than the predicted one, special logic defined in the invariant registry is triggered (usually the chain is halted). This is useful to make sure that no critical bug goes unnoticed, producing long-lasting effects that are hard to fix.
|
||||
* With the module manager, set the order of execution between the `InitGenesis`, `BeginBlocker`, and `EndBlocker` functions of each of the [application's modules](#application-module-interface). Note that not all modules implement these functions.
|
||||
* With the module manager, set the order of execution between the `InitGenesis`, `PreBlocker`, `BeginBlocker`, and `EndBlocker` functions of each of the [application's modules](#application-module-interface). Note that not all modules implement these functions.
|
||||
* Set the remaining application parameters:
|
||||
* [`InitChainer`](#initchainer): used to initialize the application when it is first started.
|
||||
* [`BeginBlocker`, `EndBlocker`](#beginblocker-and-endlbocker): called at the beginning and at the end of every block.
|
||||
* [`PreBlocker`](#preblocker): called before BeginBlock.
|
||||
* [`BeginBlocker`, `EndBlocker`](#beginblocker-and-endblocker): called at the beginning and at the end of every block.
|
||||
* [`anteHandler`](../advanced/00-baseapp.md#antehandler): used to handle fees and signature verification.
|
||||
* Mount the stores.
|
||||
* Return the application.
|
||||
@@ -107,6 +108,21 @@ See an example of an `InitChainer` from `simapp`:
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L626-L634
|
||||
```
|
||||
|
||||
### PreBlocker
|
||||
|
||||
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 parameter in the finalize context:
|
||||
|
||||
```go
|
||||
app.finalizeBlockState.ctx = app.finalizeBlockState.ctx.WithConsensusParams(app.GetConsensusParams())
|
||||
```
|
||||
|
||||
The new ctx must be passed to all the other lifecycle methods.
|
||||
|
||||
### BeginBlocker and EndBlocker
|
||||
|
||||
The Cosmos SDK offers developers the possibility to implement automatic execution of code as part of their application. This is implemented through two functions called `BeginBlocker` and `EndBlocker`. They are called when the application receives the `FinalizeBlock` messages from the CometBFT consensus engine, which happens respectively at the beginning and at the end of each block. The application must set the `BeginBlocker` and `EndBlocker` in its [constructor](#constructor-function) via the [`SetBeginBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetBeginBlocker) and [`SetEndBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetEndBlocker) methods.
|
||||
|
||||
Reference in New Issue
Block a user