2019-05-16 08:25:32 -07:00
/ *
2019-06-05 16:26:17 -07:00
Package module contains application module patterns and associated "manager" functionality .
2019-05-16 08:25:32 -07:00
The module pattern has been broken down by :
- independent module functionality ( AppModuleBasic )
2019-06-05 16:26:17 -07:00
- inter - dependent module genesis functionality ( AppModuleGenesis )
2019-08-13 15:16:03 -07:00
- inter - dependent module simulation functionality ( AppModuleSimulation )
2019-06-05 16:26:17 -07:00
- inter - dependent module full functionality ( AppModule )
2019-05-16 08:25:32 -07:00
inter - dependent module functionality is module functionality which somehow
depends on other modules , typically through the module keeper . Many of the
module keepers are dependent on each other , thus in order to access the full
set of module functionality we need to define all the keepers / params - store / keys
etc . This full set of advanced functionality is defined by the AppModule interface .
Independent module functions are separated to allow for the construction of the
basic application structures required early on in the application definition
and used to enable the definition of full module functionality later in the
process . This separation is necessary , however we still want to allow for a
high level pattern for modules to follow - for instance , such that we don ' t
have to manually register all of the codecs for all the modules . This basic
procedure as well as other basic patterns are handled through the use of
2019-06-05 16:26:17 -07:00
BasicManager .
Lastly the interface for genesis functionality ( AppModuleGenesis ) has been
separated out from full module functionality ( AppModule ) so that modules which
are only used for genesis can take advantage of the Module patterns without
needlessly defining many placeholder functions
2019-05-16 08:25:32 -07:00
* /
2019-06-05 16:26:17 -07:00
package module
2019-05-16 08:25:32 -07:00
import (
"encoding/json"
2021-10-05 05:02:51 -07:00
"fmt"
2021-09-28 08:20:43 -07:00
"sort"
2019-05-16 08:25:32 -07:00
2019-06-05 16:26:17 -07:00
"github.com/gorilla/mux"
2020-10-29 04:37:46 -07:00
"github.com/grpc-ecosystem/grpc-gateway/runtime"
2019-05-16 08:25:32 -07:00
"github.com/spf13/cobra"
abci "github.com/tendermint/tendermint/abci/types"
2020-06-01 05:46:03 -07:00
"github.com/cosmos/cosmos-sdk/client"
2019-06-05 16:26:17 -07:00
"github.com/cosmos/cosmos-sdk/codec"
2020-07-23 19:45:34 -07:00
codectypes "github.com/cosmos/cosmos-sdk/codec/types"
2019-06-05 16:26:17 -07:00
sdk "github.com/cosmos/cosmos-sdk/types"
2021-02-10 09:49:31 -08:00
sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
2019-06-05 16:26:17 -07:00
)
2019-05-16 08:25:32 -07:00
// AppModuleBasic is the standard form for basic non-dependant elements of an application module.
type AppModuleBasic interface {
Name ( ) string
2020-09-07 07:47:12 -07:00
RegisterLegacyAminoCodec ( * codec . LegacyAmino )
2020-07-23 19:45:34 -07:00
RegisterInterfaces ( codectypes . InterfaceRegistry )
2019-06-05 16:26:17 -07:00
2021-04-29 03:46:22 -07:00
DefaultGenesis ( codec . JSONCodec ) json . RawMessage
ValidateGenesis ( codec . JSONCodec , client . TxEncodingConfig , json . RawMessage ) error
2019-06-05 16:26:17 -07:00
// client functionality
2020-06-01 05:46:03 -07:00
RegisterRESTRoutes ( client . Context , * mux . Router )
2020-10-28 04:39:49 -07:00
RegisterGRPCGatewayRoutes ( client . Context , * runtime . ServeMux )
2020-07-21 08:28:43 -07:00
GetTxCmd ( ) * cobra . Command
GetQueryCmd ( ) * cobra . Command
2019-05-16 08:25:32 -07:00
}
2019-08-13 15:16:03 -07:00
// BasicManager is a collection of AppModuleBasic
2019-06-05 16:26:17 -07:00
type BasicManager map [ string ] AppModuleBasic
2019-05-16 08:25:32 -07:00
2019-08-13 15:16:03 -07:00
// NewBasicManager creates a new BasicManager object
2019-06-05 16:26:17 -07:00
func NewBasicManager ( modules ... AppModuleBasic ) BasicManager {
moduleMap := make ( map [ string ] AppModuleBasic )
for _ , module := range modules {
moduleMap [ module . Name ( ) ] = module
}
return moduleMap
2019-05-16 08:25:32 -07:00
}
2020-09-07 07:47:12 -07:00
// RegisterLegacyAminoCodec registers all module codecs
func ( bm BasicManager ) RegisterLegacyAminoCodec ( cdc * codec . LegacyAmino ) {
2019-06-05 16:26:17 -07:00
for _ , b := range bm {
2020-09-07 07:47:12 -07:00
b . RegisterLegacyAminoCodec ( cdc )
2019-05-16 08:25:32 -07:00
}
}
2020-07-23 19:45:34 -07:00
// RegisterInterfaces registers all module interface types
func ( bm BasicManager ) RegisterInterfaces ( registry codectypes . InterfaceRegistry ) {
for _ , m := range bm {
m . RegisterInterfaces ( registry )
}
}
2019-08-13 15:16:03 -07:00
// DefaultGenesis provides default genesis information for all modules
2021-04-29 03:46:22 -07:00
func ( bm BasicManager ) DefaultGenesis ( cdc codec . JSONCodec ) map [ string ] json . RawMessage {
2019-05-16 08:25:32 -07:00
genesis := make ( map [ string ] json . RawMessage )
2019-06-05 16:26:17 -07:00
for _ , b := range bm {
2020-02-18 04:50:13 -08:00
genesis [ b . Name ( ) ] = b . DefaultGenesis ( cdc )
2019-05-16 08:25:32 -07:00
}
2020-02-18 04:50:13 -08:00
2019-05-16 08:25:32 -07:00
return genesis
}
2019-08-13 15:16:03 -07:00
// ValidateGenesis performs genesis state validation for all modules
2021-04-29 03:46:22 -07:00
func ( bm BasicManager ) ValidateGenesis ( cdc codec . JSONCodec , txEncCfg client . TxEncodingConfig , genesis map [ string ] json . RawMessage ) error {
2019-06-05 16:26:17 -07:00
for _ , b := range bm {
2020-07-25 01:10:04 -07:00
if err := b . ValidateGenesis ( cdc , txEncCfg , genesis [ b . Name ( ) ] ) ; err != nil {
2019-05-16 08:25:32 -07:00
return err
}
}
2020-02-18 04:50:13 -08:00
2019-05-16 08:25:32 -07:00
return nil
}
2019-08-13 15:16:03 -07:00
// RegisterRESTRoutes registers all module rest routes
2020-06-01 05:46:03 -07:00
func ( bm BasicManager ) RegisterRESTRoutes ( clientCtx client . Context , rtr * mux . Router ) {
2019-06-05 16:26:17 -07:00
for _ , b := range bm {
2020-06-01 05:46:03 -07:00
b . RegisterRESTRoutes ( clientCtx , rtr )
2019-06-05 16:26:17 -07:00
}
}
2020-10-28 04:39:49 -07:00
// RegisterGRPCGatewayRoutes registers all module rest routes
func ( bm BasicManager ) RegisterGRPCGatewayRoutes ( clientCtx client . Context , rtr * runtime . ServeMux ) {
2020-08-25 08:44:13 -07:00
for _ , b := range bm {
2020-10-28 04:39:49 -07:00
b . RegisterGRPCGatewayRoutes ( clientCtx , rtr )
2020-08-25 08:44:13 -07:00
}
}
2020-07-02 06:02:28 -07:00
// AddTxCommands adds all tx commands to the rootTxCmd.
//
// TODO: Remove clientCtx argument.
// REF: https://github.com/cosmos/cosmos-sdk/issues/6571
2020-07-21 08:28:43 -07:00
func ( bm BasicManager ) AddTxCommands ( rootTxCmd * cobra . Command ) {
2019-06-05 16:26:17 -07:00
for _ , b := range bm {
2020-07-21 08:28:43 -07:00
if cmd := b . GetTxCmd ( ) ; cmd != nil {
2019-06-05 16:26:17 -07:00
rootTxCmd . AddCommand ( cmd )
}
}
}
2020-07-02 06:02:28 -07:00
// AddQueryCommands adds all query commands to the rootQueryCmd.
//
// TODO: Remove clientCtx argument.
// REF: https://github.com/cosmos/cosmos-sdk/issues/6571
2020-07-21 08:28:43 -07:00
func ( bm BasicManager ) AddQueryCommands ( rootQueryCmd * cobra . Command ) {
2019-06-05 16:26:17 -07:00
for _ , b := range bm {
2020-07-21 08:28:43 -07:00
if cmd := b . GetQueryCmd ( ) ; cmd != nil {
2019-06-05 16:26:17 -07:00
rootQueryCmd . AddCommand ( cmd )
}
}
}
2019-05-16 08:25:32 -07:00
// AppModuleGenesis is the standard form for an application module genesis functions
type AppModuleGenesis interface {
AppModuleBasic
2020-02-18 04:50:13 -08:00
2021-04-29 03:46:22 -07:00
InitGenesis ( sdk . Context , codec . JSONCodec , json . RawMessage ) [ ] abci . ValidatorUpdate
ExportGenesis ( sdk . Context , codec . JSONCodec ) json . RawMessage
2019-05-16 08:25:32 -07:00
}
// AppModule is the standard form for an application module
type AppModule interface {
AppModuleGenesis
// registers
2019-06-06 13:32:38 -07:00
RegisterInvariants ( sdk . InvariantRegistry )
2019-05-16 08:25:32 -07:00
2020-11-17 12:41:43 -08:00
// Deprecated: use RegisterServices
2020-06-11 08:37:23 -07:00
Route ( ) sdk . Route
2020-09-08 09:09:50 -07:00
2020-11-17 12:41:43 -08:00
// Deprecated: use RegisterServices
2019-05-16 08:25:32 -07:00
QuerierRoute ( ) string
2020-09-08 09:09:50 -07:00
2020-11-17 12:41:43 -08:00
// Deprecated: use RegisterServices
2020-08-26 02:39:38 -07:00
LegacyQuerierHandler ( * codec . LegacyAmino ) sdk . Querier
2020-09-08 09:09:50 -07:00
2020-10-12 09:31:51 -07:00
// RegisterServices allows a module to register services
RegisterServices ( Configurator )
2019-05-16 08:25:32 -07:00
2021-02-10 09:49:31 -08:00
// ConsensusVersion is a sequence number for state-breaking change of the
// module. It should be incremented on each consensus-breaking change
// introduced by the module. To avoid wrong/empty versions, the initial version
// should be set to 1.
ConsensusVersion ( ) uint64
2019-08-13 15:16:03 -07:00
// ABCI
2019-06-26 09:03:25 -07:00
BeginBlock ( sdk . Context , abci . RequestBeginBlock )
EndBlock ( sdk . Context , abci . RequestEndBlock ) [ ] abci . ValidatorUpdate
2019-05-16 08:25:32 -07:00
}
2019-08-13 15:16:03 -07:00
// GenesisOnlyAppModule is an AppModule that only has import/export functionality
2019-05-16 08:25:32 -07:00
type GenesisOnlyAppModule struct {
AppModuleGenesis
}
// NewGenesisOnlyAppModule creates a new GenesisOnlyAppModule object
func NewGenesisOnlyAppModule ( amg AppModuleGenesis ) AppModule {
return GenesisOnlyAppModule {
AppModuleGenesis : amg ,
}
}
2019-08-13 15:16:03 -07:00
// RegisterInvariants is a placeholder function register no invariants
2019-06-06 13:32:38 -07:00
func ( GenesisOnlyAppModule ) RegisterInvariants ( _ sdk . InvariantRegistry ) { }
2019-05-16 08:25:32 -07:00
2019-08-13 15:16:03 -07:00
// Route empty module message route
2020-06-11 08:37:23 -07:00
func ( GenesisOnlyAppModule ) Route ( ) sdk . Route { return sdk . Route { } }
2019-05-16 08:25:32 -07:00
2019-08-13 15:16:03 -07:00
// QuerierRoute returns an empty module querier route
2019-05-16 08:25:32 -07:00
func ( GenesisOnlyAppModule ) QuerierRoute ( ) string { return "" }
2020-07-24 12:04:29 -07:00
// LegacyQuerierHandler returns an empty module querier
2020-08-26 02:39:38 -07:00
func ( gam GenesisOnlyAppModule ) LegacyQuerierHandler ( * codec . LegacyAmino ) sdk . Querier { return nil }
2019-05-16 08:25:32 -07:00
2020-10-12 09:31:51 -07:00
// RegisterServices registers all services.
func ( gam GenesisOnlyAppModule ) RegisterServices ( Configurator ) { }
2020-06-06 00:59:57 -07:00
2021-02-10 09:49:31 -08:00
// ConsensusVersion implements AppModule/ConsensusVersion.
func ( gam GenesisOnlyAppModule ) ConsensusVersion ( ) uint64 { return 1 }
2019-08-13 15:16:03 -07:00
// BeginBlock returns an empty module begin-block
2019-06-26 09:03:25 -07:00
func ( gam GenesisOnlyAppModule ) BeginBlock ( ctx sdk . Context , req abci . RequestBeginBlock ) { }
2019-05-16 08:25:32 -07:00
2019-08-13 15:16:03 -07:00
// EndBlock returns an empty module end-block
2019-06-26 09:03:25 -07:00
func ( GenesisOnlyAppModule ) EndBlock ( _ sdk . Context , _ abci . RequestEndBlock ) [ ] abci . ValidatorUpdate {
return [ ] abci . ValidatorUpdate { }
2019-05-16 08:25:32 -07:00
}
2019-08-13 15:16:03 -07:00
// Manager defines a module manager that provides the high level utility for managing and executing
2019-05-16 08:25:32 -07:00
// operations for a group of modules
2019-06-05 16:26:17 -07:00
type Manager struct {
2019-05-16 08:25:32 -07:00
Modules map [ string ] AppModule
OrderInitGenesis [ ] string
OrderExportGenesis [ ] string
OrderBeginBlockers [ ] string
OrderEndBlockers [ ] string
2022-01-05 14:32:10 -08:00
OrderMigrations [ ] string
2019-05-16 08:25:32 -07:00
}
2019-08-13 15:16:03 -07:00
// NewManager creates a new Manager object
2019-06-05 16:26:17 -07:00
func NewManager ( modules ... AppModule ) * Manager {
2019-05-16 08:25:32 -07:00
moduleMap := make ( map [ string ] AppModule )
2019-09-17 09:13:26 -07:00
modulesStr := make ( [ ] string , 0 , len ( modules ) )
2019-05-16 08:25:32 -07:00
for _ , module := range modules {
moduleMap [ module . Name ( ) ] = module
modulesStr = append ( modulesStr , module . Name ( ) )
}
2019-06-05 16:26:17 -07:00
return & Manager {
2019-05-16 08:25:32 -07:00
Modules : moduleMap ,
OrderInitGenesis : modulesStr ,
OrderExportGenesis : modulesStr ,
OrderBeginBlockers : modulesStr ,
OrderEndBlockers : modulesStr ,
}
}
2019-08-13 15:16:03 -07:00
// SetOrderInitGenesis sets the order of init genesis calls
2019-06-05 16:26:17 -07:00
func ( m * Manager ) SetOrderInitGenesis ( moduleNames ... string ) {
2022-01-05 14:32:10 -08:00
m . assertNoForgottenModules ( "SetOrderInitGenesis" , moduleNames )
2019-06-05 16:26:17 -07:00
m . OrderInitGenesis = moduleNames
2019-05-16 08:25:32 -07:00
}
2019-08-13 15:16:03 -07:00
// SetOrderExportGenesis sets the order of export genesis calls
2019-06-05 16:26:17 -07:00
func ( m * Manager ) SetOrderExportGenesis ( moduleNames ... string ) {
2022-01-05 14:32:10 -08:00
m . assertNoForgottenModules ( "SetOrderExportGenesis" , moduleNames )
2019-06-05 16:26:17 -07:00
m . OrderExportGenesis = moduleNames
2019-05-16 08:25:32 -07:00
}
2019-08-13 15:16:03 -07:00
// SetOrderBeginBlockers sets the order of set begin-blocker calls
2019-06-05 16:26:17 -07:00
func ( m * Manager ) SetOrderBeginBlockers ( moduleNames ... string ) {
2022-01-05 14:32:10 -08:00
m . assertNoForgottenModules ( "SetOrderBeginBlockers" , moduleNames )
2019-06-05 16:26:17 -07:00
m . OrderBeginBlockers = moduleNames
2019-05-16 08:25:32 -07:00
}
2019-08-13 15:16:03 -07:00
// SetOrderEndBlockers sets the order of set end-blocker calls
2019-06-05 16:26:17 -07:00
func ( m * Manager ) SetOrderEndBlockers ( moduleNames ... string ) {
2022-01-05 14:32:10 -08:00
m . assertNoForgottenModules ( "SetOrderEndBlockers" , moduleNames )
2019-06-05 16:26:17 -07:00
m . OrderEndBlockers = moduleNames
2019-05-16 08:25:32 -07:00
}
2022-01-05 14:32:10 -08:00
// SetOrderMigrations sets the order of migrations to be run. If not set
// then migrations will be run with an order defined in `DefaultMigrationsOrder`.
func ( m * Manager ) SetOrderMigrations ( moduleNames ... string ) {
m . assertNoForgottenModules ( "SetOrderMigrations" , moduleNames )
m . OrderMigrations = moduleNames
}
2021-05-21 04:56:25 -07:00
// RegisterInvariants registers all module invariants
2019-06-06 13:32:38 -07:00
func ( m * Manager ) RegisterInvariants ( ir sdk . InvariantRegistry ) {
2019-06-05 16:26:17 -07:00
for _ , module := range m . Modules {
2019-06-06 13:32:38 -07:00
module . RegisterInvariants ( ir )
2019-05-16 08:25:32 -07:00
}
}
2019-08-13 15:16:03 -07:00
// RegisterRoutes registers all module routes and module querier routes
2020-08-26 02:39:38 -07:00
func ( m * Manager ) RegisterRoutes ( router sdk . Router , queryRouter sdk . QueryRouter , legacyQuerierCdc * codec . LegacyAmino ) {
2019-06-05 16:26:17 -07:00
for _ , module := range m . Modules {
2020-10-29 15:01:09 -07:00
if r := module . Route ( ) ; ! r . Empty ( ) {
router . AddRoute ( r )
2019-05-16 08:25:32 -07:00
}
2020-10-29 15:01:09 -07:00
if r := module . QuerierRoute ( ) ; r != "" {
queryRouter . AddRoute ( r , module . LegacyQuerierHandler ( legacyQuerierCdc ) )
2019-05-16 08:25:32 -07:00
}
}
}
2020-10-12 09:31:51 -07:00
// RegisterServices registers all module services
func ( m * Manager ) RegisterServices ( cfg Configurator ) {
2020-06-06 00:59:57 -07:00
for _ , module := range m . Modules {
2020-10-12 09:31:51 -07:00
module . RegisterServices ( cfg )
2020-06-06 00:59:57 -07:00
}
}
2021-10-05 05:02:51 -07:00
// InitGenesis performs init genesis functionality for modules. Exactly one
// module must return a non-empty validator set update to correctly initialize
// the chain.
2021-04-29 03:46:22 -07:00
func ( m * Manager ) InitGenesis ( ctx sdk . Context , cdc codec . JSONCodec , genesisData map [ string ] json . RawMessage ) abci . ResponseInitChain {
2019-05-16 08:25:32 -07:00
var validatorUpdates [ ] abci . ValidatorUpdate
2021-08-12 09:32:36 -07:00
ctx . Logger ( ) . Info ( "initializing blockchain state from genesis.json" )
2019-06-05 16:26:17 -07:00
for _ , moduleName := range m . OrderInitGenesis {
2019-05-16 08:25:32 -07:00
if genesisData [ moduleName ] == nil {
continue
}
2021-08-12 09:32:36 -07:00
ctx . Logger ( ) . Debug ( "running initialization for module" , "module" , moduleName )
2020-02-18 04:50:13 -08:00
moduleValUpdates := m . Modules [ moduleName ] . InitGenesis ( ctx , cdc , genesisData [ moduleName ] )
2019-05-16 08:25:32 -07:00
// use these validator updates if provided, the module manager assumes
// only one module will update the validator set
if len ( moduleValUpdates ) > 0 {
if len ( validatorUpdates ) > 0 {
panic ( "validator InitGenesis updates already set by a previous module" )
}
validatorUpdates = moduleValUpdates
}
}
2020-02-18 04:50:13 -08:00
2021-10-05 05:02:51 -07:00
// a chain must initialize with a non-empty validator set
if len ( validatorUpdates ) == 0 {
panic ( fmt . Sprintf ( "validator set is empty after InitGenesis, please ensure at least one validator is initialized with a delegation greater than or equal to the DefaultPowerReduction (%d)" , sdk . DefaultPowerReduction ) )
}
2019-05-16 08:25:32 -07:00
return abci . ResponseInitChain {
Validators : validatorUpdates ,
}
}
2019-08-13 15:16:03 -07:00
// ExportGenesis performs export genesis functionality for modules
2021-04-29 03:46:22 -07:00
func ( m * Manager ) ExportGenesis ( ctx sdk . Context , cdc codec . JSONCodec ) map [ string ] json . RawMessage {
2019-05-16 08:25:32 -07:00
genesisData := make ( map [ string ] json . RawMessage )
2019-06-05 16:26:17 -07:00
for _ , moduleName := range m . OrderExportGenesis {
2020-02-18 04:50:13 -08:00
genesisData [ moduleName ] = m . Modules [ moduleName ] . ExportGenesis ( ctx , cdc )
2019-05-16 08:25:32 -07:00
}
2020-02-18 04:50:13 -08:00
2019-05-16 08:25:32 -07:00
return genesisData
}
2022-01-05 14:32:10 -08:00
// assertNoForgottenModules checks that we didn't forget any modules in the
2021-12-10 09:35:31 -08:00
// SetOrder* functions.
2022-01-05 14:32:10 -08:00
func ( m * Manager ) assertNoForgottenModules ( setOrderFnName string , moduleNames [ ] string ) {
ms := make ( map [ string ] bool )
2021-12-10 09:35:31 -08:00
for _ , m := range moduleNames {
2022-01-05 14:32:10 -08:00
ms [ m ] = true
2021-12-10 09:35:31 -08:00
}
2022-01-05 14:32:10 -08:00
var missing [ ] string
for m := range m . Modules {
if ! ms [ m ] {
missing = append ( missing , m )
}
}
if len ( missing ) != 0 {
panic ( fmt . Sprintf (
"%s: all modules must be defined when setting SetOrderMigrations, missing: %v" , setOrderFnName , missing ) )
2021-12-10 09:35:31 -08:00
}
}
2021-02-10 09:49:31 -08:00
// MigrationHandler is the migration function that each module registers.
2021-02-25 02:43:31 -08:00
type MigrationHandler func ( sdk . Context ) error
2021-02-10 09:49:31 -08:00
2022-01-05 14:32:10 -08:00
// VersionMap is a map of moduleName -> version
2021-03-19 15:01:29 -07:00
type VersionMap map [ string ] uint64
2021-02-10 09:49:31 -08:00
2021-04-02 08:41:35 -07:00
// RunMigrations performs in-place store migrations for all modules. This
// function MUST be called insde an x/upgrade UpgradeHandler.
//
// Recall that in an upgrade handler, the `fromVM` VersionMap is retrieved from
// x/upgrade's store, and the function needs to return the target VersionMap
// that will in turn be persisted to the x/upgrade's store. In general,
// returning RunMigrations should be enough:
//
// Example:
// cfg := module.NewConfigurator(...)
// app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
// return app.mm.RunMigrations(ctx, cfg, fromVM)
// })
//
// Internally, RunMigrations will perform the following steps:
// - create an `updatedVM` VersionMap of module with their latest ConsensusVersion
// - make a diff of `fromVM` and `udpatedVM`, and for each module:
// - if the module's `fromVM` version is less than its `updatedVM` version,
// then run in-place store migrations for that module between those versions.
2021-04-13 12:00:04 -07:00
// - if the module does not exist in the `fromVM` (which means that it's a new module,
2021-04-02 08:41:35 -07:00
// because it was not in the previous x/upgrade's store), then run
// `InitGenesis` on that module.
// - return the `updatedVM` to be persisted in the x/upgrade's store.
//
2022-01-05 14:32:10 -08:00
// Migrations are run in an order defined by `Manager.OrderMigrations` or (if not set) defined by
// `DefaultMigrationsOrder` function.
//
2021-04-02 08:41:35 -07:00
// As an app developer, if you wish to skip running InitGenesis for your new
// module "foo", you need to manually pass a `fromVM` argument to this function
// foo's module version set to its latest ConsensusVersion. That way, the diff
// between the function's `fromVM` and `udpatedVM` will be empty, hence not
// running anything for foo.
//
// Example:
// cfg := module.NewConfigurator(...)
// app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
// // Assume "foo" is a new module.
// // `fromVM` is fetched from existing x/upgrade store. Since foo didn't exist
2021-04-13 12:00:04 -07:00
// // before this upgrade, `v, exists := fromVM["foo"]; exists == false`, and RunMigration will by default
2021-04-02 08:41:35 -07:00
// // run InitGenesis on foo.
// // To skip running foo's InitGenesis, you need set `fromVM`'s foo to its latest
// // consensus version:
// fromVM["foo"] = foo.AppModule{}.ConsensusVersion()
//
// return app.mm.RunMigrations(ctx, cfg, fromVM)
// })
//
// Please also refer to docs/core/upgrade.md for more information.
2021-03-19 15:01:29 -07:00
func ( m Manager ) RunMigrations ( ctx sdk . Context , cfg Configurator , fromVM VersionMap ) ( VersionMap , error ) {
2021-02-10 09:49:31 -08:00
c , ok := cfg . ( configurator )
if ! ok {
2021-03-19 15:01:29 -07:00
return nil , sdkerrors . Wrapf ( sdkerrors . ErrInvalidType , "expected %T, got %T" , configurator { } , cfg )
2021-02-10 09:49:31 -08:00
}
2022-01-05 14:32:10 -08:00
var modules = m . OrderMigrations
if modules == nil {
modules = DefaultMigrationsOrder ( m . ModuleNames ( ) )
2021-09-28 08:20:43 -07:00
}
2022-01-05 14:32:10 -08:00
updatedVM := VersionMap { }
for _ , moduleName := range modules {
2021-09-28 08:20:43 -07:00
module := m . Modules [ moduleName ]
2021-04-13 12:00:04 -07:00
fromVersion , exists := fromVM [ moduleName ]
2021-03-25 12:51:38 -07:00
toVersion := module . ConsensusVersion ( )
2021-10-22 03:56:08 -07:00
// We run migration if the module is specified in `fromVM`.
// Otherwise we run InitGenesis.
2021-04-02 08:41:35 -07:00
//
2021-10-22 03:56:08 -07:00
// The module won't exist in the fromVM in two cases:
2021-04-13 12:00:04 -07:00
// 1. A new module is added. In this case we run InitGenesis with an
2021-04-02 08:41:35 -07:00
// empty genesis state.
2021-10-22 03:56:08 -07:00
// 2. An existing chain is upgrading from version < 0.43 to v0.43+ for the first time.
// In this case, all modules have yet to be added to x/upgrade's VersionMap store.
2021-04-13 12:00:04 -07:00
if exists {
2021-03-25 12:51:38 -07:00
err := c . runModuleMigrations ( ctx , moduleName , fromVersion , toVersion )
if err != nil {
return nil , err
}
2021-04-02 08:41:35 -07:00
} else {
2021-12-14 03:06:06 -08:00
ctx . Logger ( ) . Info ( fmt . Sprintf ( "adding a new module: %s" , moduleName ) )
2021-10-22 03:56:08 -07:00
moduleValUpdates := module . InitGenesis ( ctx , c . cdc , module . DefaultGenesis ( c . cdc ) )
2021-04-02 08:41:35 -07:00
// The module manager assumes only one module will update the
2021-10-22 03:56:08 -07:00
// validator set, and it can't be a new module.
2021-04-02 08:41:35 -07:00
if len ( moduleValUpdates ) > 0 {
2021-10-22 03:56:08 -07:00
return nil , sdkerrors . Wrapf ( sdkerrors . ErrLogic , "validator InitGenesis update is already set by another module" )
2021-04-02 08:41:35 -07:00
}
2021-02-10 09:49:31 -08:00
}
2021-03-25 12:51:38 -07:00
updatedVM [ moduleName ] = toVersion
2021-02-10 09:49:31 -08:00
}
2021-03-19 15:01:29 -07:00
return updatedVM , nil
2021-02-10 09:49:31 -08:00
}
2019-06-26 09:03:25 -07:00
// BeginBlock performs begin block functionality for all modules. It creates a
// child context with an event manager to aggregate events emitted from all
// modules.
2019-06-05 16:26:17 -07:00
func ( m * Manager ) BeginBlock ( ctx sdk . Context , req abci . RequestBeginBlock ) abci . ResponseBeginBlock {
2019-06-26 09:03:25 -07:00
ctx = ctx . WithEventManager ( sdk . NewEventManager ( ) )
2019-06-05 16:26:17 -07:00
for _ , moduleName := range m . OrderBeginBlockers {
2019-06-26 09:03:25 -07:00
m . Modules [ moduleName ] . BeginBlock ( ctx , req )
2019-05-16 08:25:32 -07:00
}
return abci . ResponseBeginBlock {
2019-06-26 09:03:25 -07:00
Events : ctx . EventManager ( ) . ABCIEvents ( ) ,
2019-05-16 08:25:32 -07:00
}
}
2019-06-26 09:03:25 -07:00
// EndBlock performs end block functionality for all modules. It creates a
// child context with an event manager to aggregate events emitted from all
// modules.
2019-06-05 16:26:17 -07:00
func ( m * Manager ) EndBlock ( ctx sdk . Context , req abci . RequestEndBlock ) abci . ResponseEndBlock {
2019-06-26 09:03:25 -07:00
ctx = ctx . WithEventManager ( sdk . NewEventManager ( ) )
2019-05-16 08:25:32 -07:00
validatorUpdates := [ ] abci . ValidatorUpdate { }
2019-06-26 09:03:25 -07:00
2019-06-05 16:26:17 -07:00
for _ , moduleName := range m . OrderEndBlockers {
2019-06-26 09:03:25 -07:00
moduleValUpdates := m . Modules [ moduleName ] . EndBlock ( ctx , req )
2019-05-16 08:25:32 -07:00
// use these validator updates if provided, the module manager assumes
// only one module will update the validator set
if len ( moduleValUpdates ) > 0 {
if len ( validatorUpdates ) > 0 {
panic ( "validator EndBlock updates already set by a previous module" )
}
2019-06-26 09:03:25 -07:00
2019-05-16 08:25:32 -07:00
validatorUpdates = moduleValUpdates
}
}
return abci . ResponseEndBlock {
ValidatorUpdates : validatorUpdates ,
2019-06-26 09:03:25 -07:00
Events : ctx . EventManager ( ) . ABCIEvents ( ) ,
2019-05-16 08:25:32 -07:00
}
2019-08-15 06:54:10 -07:00
}
2021-03-19 15:01:29 -07:00
// GetVersionMap gets consensus version from all modules
func ( m * Manager ) GetVersionMap ( ) VersionMap {
vermap := make ( VersionMap )
for _ , v := range m . Modules {
version := v . ConsensusVersion ( )
name := v . Name ( )
vermap [ name ] = version
}
return vermap
}
2022-01-05 14:32:10 -08:00
// ModuleNames returns list of all module names, without any particular order.
func ( m * Manager ) ModuleNames ( ) [ ] string {
ms := make ( [ ] string , len ( m . Modules ) )
i := 0
for m := range m . Modules {
ms [ i ] = m
i ++
}
return ms
}
// DefaultMigrationsOrder returns a default migrations order: ascending alphabetical by module name,
// except x/auth which will run last, see:
// https://github.com/cosmos/cosmos-sdk/issues/10591
func DefaultMigrationsOrder ( modules [ ] string ) [ ] string {
const authName = "auth"
out := make ( [ ] string , 0 , len ( modules ) )
hasAuth := false
for _ , m := range modules {
if m == authName {
hasAuth = true
} else {
out = append ( out , m )
}
}
sort . Strings ( out )
if hasAuth {
out = append ( out , authName )
}
return out
}