# Module Manager
Cosmos SDK modules need to implement the
AppModule interfaces, in order to be managed by the application's module manager. The module manager plays an important role in
query routing, and allows application developers to set the order of execution of a variety of functions like
# Pre-requisite Readings
# Application Module Interfaces
Application module interfaces exist to facilitate the composition of modules together to form a functional Cosmos SDK application. There are 3 main application module interfaces:
AppModuleBasicfor independent module functionalities.
AppModulefor inter-dependent module functionalities (except genesis-related functionalities).
AppModuleGenesisfor inter-dependent genesis-related module functionalities.
AppModuleBasic interface exists to define independent methods of the module, i.e. those that do not depend on other modules in the application. This allows for the construction of the basic application structure early in the application definition, generally in the
init() function of the main application file.
AppModule interface exists to define inter-dependent module methods. Many modules need to interact with other modules, typically through
keepers, which means there is a need for an interface where modules list their
keepers and other methods that require a reference to another module's object.
AppModule interface also enables the module manager to set the order of execution between module's methods like
EndBlock, which is important in cases where the order of execution between modules matters in the context of the application.
Lastly the interface for genesis functionality
AppModuleGenesis is separated out from full module functionality
AppModule so that modules which
are only used for genesis can take advantage of the
Module patterns without having to define many placeholder functions.
AppModuleBasic interface defines the independent methods modules need to implement.
Let us go through the methods:
Name(): Returns the name of the module as a
RegisterLegacyAminoCodec(*codec.LegacyAmino): Registers the
aminocodec for the module, which is used to marshal and unmarshal structs to/from
bytein order to persist them in the module's
RegisterInterfaces(codectypes.InterfaceRegistry): Registers a module's interface types and their concrete implementations as
DefaultGenesis(codec.JSONCodec): Returns a default
GenesisStatefor the module, marshalled to
json.RawMessage. The default
GenesisStateneed to be defined by the module developer and is primarily used for testing.
ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage): Used to validate the
GenesisStatedefined by a module, given in its
json.RawMessageform. It will usually unmarshall the
jsonbefore running a custom
ValidateGenesisfunction defined by the module developer.
RegisterGRPCGatewayRoutes(client.Context, *runtime.ServeMux): Registers gRPC routes for the module.
GetTxCmd(): Returns the root
Txcommand for the module. The subcommands of this root command are used by end-users to generate new transactions containing
messages defined in the module.
GetQueryCmd(): Return the root
querycommand for the module. The subcommands of this root command are used by end-users to generate new queries to the subset of the state defined by the module.
AppModuleBasic of an application are managed by the
AppModuleGenesis interface is a simple embedding of the
AppModuleBasic interface with two added methods.
Let us go through the two added methods:
InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage): Initializes the subset of the state managed by the module. It is called at genesis (i.e. when the chain is first started).
ExportGenesis(sdk.Context, codec.JSONCodec): Exports the latest subset of the state managed by the module to be used in a new genesis file.
ExportGenesisis called for each module when a new chain is started from the state of an existing chain.
It does not have its own manager, and exists separately from
AppModule only for modules that exist only to implement genesis functionalities, so that they can be managed without having to implement all of
AppModule's methods. If the module is not only used during genesis,
InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage) and
ExportGenesis(sdk.Context, codec.JSONCodec) will generally be defined as methods of the concrete type implementing the
AppModule interface defines the inter-dependent methods that modules need to implement.
AppModules are managed by the module manager. This interface embeds the
AppModuleGenesis interface so that the manager can access all the independent and genesis inter-dependent methods of the module. This means that a concrete type implementing the
AppModule interface must either implement all the methods of
AppModuleGenesis (and by extension
AppModuleBasic), or include a concrete type that does as parameter.
Let us go through the methods of
RegisterInvariants(sdk.InvariantRegistry): Registers the
invariantsof the module. If an invariant deviates from its predicted value, the
InvariantRegistrytriggers appropriate logic (most often the chain will be halted).
Route(): Returns the route for
messages to be routed to the module by
QuerierRoute()(deprecated): Returns the name of the module's query route, for
queriesto be routes to the module by
LegacyQuerierHandler(*codec.LegacyAmino)(deprecated): Returns a
queriergiven the query
path, in order to process the
RegisterServices(Configurator): Allows a module to register services.
BeginBlock(sdk.Context, abci.RequestBeginBlock): This method gives module developers the option to implement logic that is automatically triggered at the beginning of each block. Implement empty if no logic needs to be triggered at the beginning of each block for this module.
EndBlock(sdk.Context, abci.RequestEndBlock): This method gives module developers the option to implement logic that is automatically triggered at the end of each block. This is also where the module can inform the underlying consensus engine of validator set changes (e.g. the
stakingmodule). Implement empty if no logic needs to be triggered at the end of each block for this module.
# Implementing the Application Module Interfaces
Typically, the various application module interfaces are implemented in a file called
module.go, located in the module's folder (e.g.
Almost every module needs to implement the
AppModule interfaces. If the module is only used for genesis, it will implement
AppModuleGenesis instead of
AppModule. The concrete type that implements the interface can add parameters that are required for the implementation of the various methods of the interface. For example, the
Route() function often calls a
NewMsgServerImpl(k keeper) function defined in
keeper/msg_server.go and therefore needs to pass the module's
keeper as a parameter.
In the example above, you can see that the
AppModule concrete type references an
AppModuleBasic, and not an
AppModuleGenesis. That is because
AppModuleGenesis only needs to be implemented in modules that focus on genesis-related functionalities. In most modules, the concrete
AppModule type will have a reference to an
AppModuleBasic and implement the two added methods of
AppModuleGenesis directly in the
If no parameter is required (which is often the case for
AppModuleBasic), just declare an empty concrete type like so:
# Module Managers
Module managers are used to manage collections of
BasicManager is a structure that lists all the
AppModuleBasic of an application:
It implements the following methods:
NewBasicManager(modules ...AppModuleBasic): Constructor function. It takes a list of the application's
AppModuleBasicand builds a new
BasicManager. This function is generally called in the
app.goto quickly initialize the independent elements of the application's modules (click here (opens new window) to see an example).
RegisterLegacyAminoCodec(cdc *codec.LegacyAmino): Registers the
codec.LegacyAminos of each of the application's
AppModuleBasic. This function is usually called early on in the application's construction.
RegisterInterfaces(registry codectypes.InterfaceRegistry): Registers interface types and implementations of each of the application's
DefaultGenesis(cdc codec.JSONCodec): Provides default genesis information for modules in the application by calling the
DefaultGenesis(cdc codec.JSONCodec)function of each module. It is used to construct a default genesis file for the application.
ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage): Validates the genesis information modules by calling the
ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)function of each module.
RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux): Registers gRPC routes for modules.
AddTxCommands(rootTxCmd *cobra.Command): Adds modules' transaction commands to the application's
rootTxCommand. This function is usually called function from the
main.gofunction of the application's command-line interface.
AddQueryCommands(rootQueryCmd *cobra.Command): Adds modules' query commands to the application's
rootQueryCommand. This function is usually called function from the
main.gofunction of the application's command-line interface.
Manager is a structure that holds all the
AppModule of an application, and defines the order of execution between several key components of these modules:
The module manager is used throughout the application whenever an action on a collection of modules is required. It implements the following methods:
NewManager(modules ...AppModule): Constructor function. It takes a list of the application's
AppModules and builds a new
Manager. It is generally called from the application's main constructor function.
SetOrderInitGenesis(moduleNames ...string): Sets the order in which the
InitGenesisfunction of each module will be called when the application is first started. This function is generally called from the application's main constructor function.
To initialize modules successfully, module dependencies should be considered. For example, the
genutilmodule must occur after
stakingmodule so that the pools are properly initialized with tokens from genesis accounts, the
genutilsmodule must also occur after
authso that it can access the params from auth,
capabilitymodule should be initialized before all other modules so that it can initialize any capabilities.
SetOrderExportGenesis(moduleNames ...string): Sets the order in which the
ExportGenesisfunction of each module will be called in case of an export. This function is generally called from the application's main 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.
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.
RegisterInvariants(ir sdk.InvariantRegistry): Registers the invariants of each module.
RegisterServices(cfg Configurator): Registers all module services.
InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage): Calls the
InitGenesisfunction of each module when the application is first started, in the order defined in
OrderInitGenesis. Returns an
abci.ResponseInitChainto the underlying consensus engine, which can contain validator updates.
ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec): Calls the
ExportGenesisfunction 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.
BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock): At the beginning of each block, this function is called from
BaseAppand, in turn, calls the
BeginBlockfunction of each module, in the order defined in
OrderBeginBlockers. It creates a child context with an event manager to aggregate events emitted from all modules. The function returns an
abci.ResponseBeginBlockwhich contains the aforementioned events.
EndBlock(ctx sdk.Context, req abci.RequestEndBlock): At the end of each block, this function is called from
BaseAppand, in turn, calls the
EndBlockfunction of each module, in the order defined in
OrderEndBlockers. It creates a child context with an event manager to aggregate events emitted from all modules. The function returns an
abci.ResponseEndBlockwhich contains the aforementioned events, as well as validator set updates (if any).
Here's an example of a concrete integration within an application:
Learn more about