Skip to main content
Version: Next

PreBlocker, BeginBlocker and EndBlocker

Synopsis

PreBlocker, BeginBlocker and EndBlocker are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the BeginBlock and EndBlock inside within ABCI FinalizeBlock

Pre-requisite Readings

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.
danger

Modules are required to get the consensus params from the consensus module. Consensus params located in sdk.Context were deprecated and should be treated as unsafe. sdk.Context is deprecated due to it being a global state within the entire state machine, it has been replaced with appmodule.Environment.

BeginBlocker and EndBlocker​

BeginBlocker and EndBlocker are a way for module developers to add automatic execution of logic to their module. This is a powerful tool that should be used carefully, as complex automatic functions can slow down or even halt the chain.

In 0.47.0, PrepareProposal and ProcessProposal were added that allow app developers to do arbitrary work at those phases, but they do not influence the work that will be done in BeginBlock, nor are they accessible from modules.

When needed, BeginBlocker and EndBlocker are implemented as part of the HasBeginBlocker, HasABCIEndBlocker and EndBlocker interfaces. This means either can be left-out if not required. The BeginBlock and EndBlock methods of the interface implemented in module.go generally defer to BeginBlocker and EndBlocker methods respectively, which are usually implemented in abci.go.

The actual implementation of BeginBlocker and EndBlocker in abci.go are very similar to that of a Msg service:

  • They generally use the keeper and ctx to retrieve information about the latest state.
  • If needed, they use the keeper and ctx to trigger state-transitions.
  • If needed, they can emit events via the environments's EventManager.

A specific method (UpdateValidators) is available to return validator updates to the underlying consensus engine in the form of an []appmodule.ValidatorUpdates. This is the preferred way to implement custom validator changes (in v1).

It is possible for developers to define the order of execution between the BeginBlocker/EndBlocker functions of each of their application's modules via the module's manager SetOrderBeginBlocker/SetOrderEndBlocker methods. For more on the module manager, click here.

Implementation​

A module must implement those core interface to make use of the PreBlocker, BeginBlocker or EndBlocker capabilities:

https://github.com/cosmos/cosmos-sdk/blob/core/v1.0.0-alpha.4/core/appmodule/v2/module.go#L22-L48

See an example implementation of BeginBlocker from the distribution module:

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/distribution/keeper/abci.go#L13-L40

and an example of EndBlocker from the gov module:

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/gov/keeper/abci.go#L22

and an example implementation of EndBlocker with validator updates from the staking module:

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/x/staking/keeper/abci.go#L12-L17