module

package
v0.46.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 23, 2022 License: Apache-2.0 Imports: 16 Imported by: 11,839

Documentation

Overview

Package module contains application module patterns and associated "manager" functionality. The module pattern has been broken down by:

  • independent module functionality (AppModuleBasic)
  • inter-dependent module genesis functionality (AppModuleGenesis)
  • inter-dependent module simulation functionality (AppModuleSimulation)
  • inter-dependent module full functionality (AppModule)

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultMigrationsOrder added in v0.45.0 

func DefaultMigrationsOrder(modules []string) []string

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

Types

type AppModule 

type AppModule interface {
	AppModuleGenesis

	// registers
	RegisterInvariants(sdk.InvariantRegistry)

	// Deprecated: use RegisterServices
	Route() sdk.Route

	// Deprecated: use RegisterServices
	QuerierRoute() string

	// Deprecated: use RegisterServices
	LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier

	// RegisterServices allows a module to register services
	RegisterServices(Configurator)

	// 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

	// ABCI
	BeginBlock(sdk.Context, abci.RequestBeginBlock)
	EndBlock(sdk.Context, abci.RequestEndBlock) []abci.ValidatorUpdate
}

AppModule is the standard form for an application module

func NewGenesisOnlyAppModule 

func NewGenesisOnlyAppModule(amg AppModuleGenesis) AppModule

NewGenesisOnlyAppModule creates a new GenesisOnlyAppModule object

type AppModuleBasic 

type AppModuleBasic interface {
	Name() string
	RegisterLegacyAminoCodec(*codec.LegacyAmino)
	RegisterInterfaces(codectypes.InterfaceRegistry)

	DefaultGenesis(codec.JSONCodec) json.RawMessage
	ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage) error

	// client functionality
	RegisterGRPCGatewayRoutes(client.Context, *runtime.ServeMux)
	GetTxCmd() *cobra.Command
	GetQueryCmd() *cobra.Command
}

AppModuleBasic is the standard form for basic non-dependant elements of an application module.

type AppModuleGenesis 

type AppModuleGenesis interface {
	AppModuleBasic

	InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage) []abci.ValidatorUpdate
	ExportGenesis(sdk.Context, codec.JSONCodec) json.RawMessage
}

AppModuleGenesis is the standard form for an application module genesis functions

type AppModuleSimulation 

type AppModuleSimulation interface {
	// randomized genesis states
	GenerateGenesisState(input *SimulationState)

	// content functions used to simulate governance proposals
	ProposalContents(simState SimulationState) []simulation.WeightedProposalContent

	// randomized module parameters for param change proposals
	RandomizedParams(r *rand.Rand) []simulation.ParamChange

	// register a func to decode the each module's defined types from their corresponding store key
	RegisterStoreDecoder(sdk.StoreDecoderRegistry)

	// simulation operations (i.e msgs) with their respective weight
	WeightedOperations(simState SimulationState) []simulation.WeightedOperation
}

AppModuleSimulation defines the standard functions that every module should expose for the SDK blockchain simulator

type BasicManager 

type BasicManager map[string]AppModuleBasic

BasicManager is a collection of AppModuleBasic

func NewBasicManager 

func NewBasicManager(modules ...AppModuleBasic) BasicManager

NewBasicManager creates a new BasicManager object

func (BasicManager) AddQueryCommands 

func (bm BasicManager) AddQueryCommands(rootQueryCmd *cobra.Command)

AddQueryCommands adds all query commands to the rootQueryCmd.

TODO: Remove clientCtx argument. REF: https://github.com/cosmos/cosmos-sdk/issues/6571

func (BasicManager) AddTxCommands 

func (bm BasicManager) AddTxCommands(rootTxCmd *cobra.Command)

AddTxCommands adds all tx commands to the rootTxCmd.

TODO: Remove clientCtx argument. REF: https://github.com/cosmos/cosmos-sdk/issues/6571

func (BasicManager) DefaultGenesis 

func (bm BasicManager) DefaultGenesis(cdc codec.JSONCodec) map[string]json.RawMessage

DefaultGenesis provides default genesis information for all modules

func (BasicManager) RegisterGRPCGatewayRoutes added in v0.40.0 

func (bm BasicManager) RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers all module rest routes

func (BasicManager) RegisterInterfaces added in v0.40.0 

func (bm BasicManager) RegisterInterfaces(registry codectypes.InterfaceRegistry)

RegisterInterfaces registers all module interface types

func (BasicManager) RegisterLegacyAminoCodec added in v0.40.0 

func (bm BasicManager) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

RegisterLegacyAminoCodec registers all module codecs

func (BasicManager) ValidateGenesis 

func (bm BasicManager) ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage) error

ValidateGenesis performs genesis state validation for all modules

type Configurator added in v0.40.0 

type Configurator interface {
	// MsgServer returns a grpc.Server instance which allows registering services
	// that will handle TxBody.messages in transactions. These Msg's WILL NOT
	// be exposed as gRPC services.
	MsgServer() grpc.Server

	// QueryServer returns a grpc.Server instance which allows registering services
	// that will be exposed as gRPC services as well as ABCI query handlers.
	QueryServer() grpc.Server

	// RegisterMigration registers an in-place store migration for a module. The
	// handler is a migration script to perform in-place migrations from version
	// `fromVersion` to version `fromVersion+1`.
	//
	// EACH TIME a module's ConsensusVersion increments, a new migration MUST
	// be registered using this function. If a migration handler is missing for
	// a particular function, the upgrade logic (see RunMigrations function)
	// will panic. If the ConsensusVersion bump does not introduce any store
	// changes, then a no-op function must be registered here.
	RegisterMigration(moduleName string, fromVersion uint64, handler MigrationHandler) error
}

Configurator provides the hooks to allow modules to configure and register their services in the RegisterServices method. It is designed to eventually support module object capabilities isolation as described in https://github.com/cosmos/cosmos-sdk/issues/7093

func NewConfigurator added in v0.40.0 

func NewConfigurator(cdc codec.Codec, msgServer grpc.Server, queryServer grpc.Server) Configurator

NewConfigurator returns a new Configurator instance

type GenesisOnlyAppModule 

type GenesisOnlyAppModule struct {
	AppModuleGenesis
}

GenesisOnlyAppModule is an AppModule that only has import/export functionality

func (GenesisOnlyAppModule) BeginBlock 

func (gam GenesisOnlyAppModule) BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock)

BeginBlock returns an empty module begin-block

func (GenesisOnlyAppModule) ConsensusVersion added in v0.43.0 

func (gam GenesisOnlyAppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

func (GenesisOnlyAppModule) EndBlock 

func (GenesisOnlyAppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock returns an empty module end-block

func (GenesisOnlyAppModule) LegacyQuerierHandler added in v0.40.0 

func (gam GenesisOnlyAppModule) LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns an empty module querier

func (GenesisOnlyAppModule) QuerierRoute 

func (GenesisOnlyAppModule) QuerierRoute() string

QuerierRoute returns an empty module querier route

func (GenesisOnlyAppModule) RegisterInvariants 

func (GenesisOnlyAppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants is a placeholder function register no invariants

func (GenesisOnlyAppModule) RegisterServices added in v0.40.0 

func (gam GenesisOnlyAppModule) RegisterServices(Configurator)

RegisterServices registers all services.

func (GenesisOnlyAppModule) Route 

func (GenesisOnlyAppModule) Route() sdk.Route

Route empty module message route

type Manager 

type Manager struct {
	Modules            map[string]AppModule
	OrderInitGenesis   []string
	OrderExportGenesis []string
	OrderBeginBlockers []string
	OrderEndBlockers   []string
	OrderMigrations    []string
}

Manager defines a module manager that provides the high level utility for managing and executing operations for a group of modules

func NewManager 

func NewManager(modules ...AppModule) *Manager

NewManager creates a new Manager object

func (*Manager) BeginBlock 

func (m *Manager) BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock) abci.ResponseBeginBlock

BeginBlock performs begin block functionality for all modules. It creates a child context with an event manager to aggregate events emitted from all modules.

func (*Manager) EndBlock 

func (m *Manager) EndBlock(ctx sdk.Context, req abci.RequestEndBlock) abci.ResponseEndBlock

EndBlock performs end block functionality for all modules. It creates a child context with an event manager to aggregate events emitted from all modules.

func (*Manager) ExportGenesis 

func (m *Manager) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) map[string]json.RawMessage

ExportGenesis performs export genesis functionality for modules

func (*Manager) GetVersionMap added in v0.43.0 

func (m *Manager) GetVersionMap() VersionMap

GetVersionMap gets consensus version from all modules

func (*Manager) InitGenesis 

func (m *Manager) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage) abci.ResponseInitChain

InitGenesis performs init genesis functionality for modules. Exactly one module must return a non-empty validator set update to correctly initialize the chain.

func (*Manager) ModuleNames added in v0.45.0 

func (m *Manager) ModuleNames() []string

ModuleNames returns list of all module names, without any particular order.

func (*Manager) RegisterInvariants 

func (m *Manager) RegisterInvariants(ir sdk.InvariantRegistry)

RegisterInvariants registers all module invariants

func (*Manager) RegisterRoutes 

func (m *Manager) RegisterRoutes(router sdk.Router, queryRouter sdk.QueryRouter, legacyQuerierCdc *codec.LegacyAmino)

RegisterRoutes registers all module routes and module querier routes

func (*Manager) RegisterServices added in v0.40.0 

func (m *Manager) RegisterServices(cfg Configurator)

RegisterServices registers all module services

func (Manager) RunMigrations added in v0.43.0 

func (m Manager) RunMigrations(ctx sdk.Context, cfg Configurator, fromVM VersionMap) (VersionMap, error)

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.
  • if the module does not exist in the `fromVM` (which means that it's a new module, 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.

Migrations are run in an order defined by `Manager.OrderMigrations` or (if not set) defined by `DefaultMigrationsOrder` function.

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
    // before this upgrade, `v, exists := fromVM["foo"]; exists == false`, and RunMigration will by default
    // 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.

func (*Manager) SetOrderBeginBlockers 

func (m *Manager) SetOrderBeginBlockers(moduleNames ...string)

SetOrderBeginBlockers sets the order of set begin-blocker calls

func (*Manager) SetOrderEndBlockers 

func (m *Manager) SetOrderEndBlockers(moduleNames ...string)

SetOrderEndBlockers sets the order of set end-blocker calls

func (*Manager) SetOrderExportGenesis 

func (m *Manager) SetOrderExportGenesis(moduleNames ...string)

SetOrderExportGenesis sets the order of export genesis calls

func (*Manager) SetOrderInitGenesis 

func (m *Manager) SetOrderInitGenesis(moduleNames ...string)

SetOrderInitGenesis sets the order of init genesis calls

func (*Manager) SetOrderMigrations added in v0.45.0 

func (m *Manager) SetOrderMigrations(moduleNames ...string)

SetOrderMigrations sets the order of migrations to be run. If not set then migrations will be run with an order defined in `DefaultMigrationsOrder`.

type MigrationHandler added in v0.43.0 

type MigrationHandler func(sdk.Context) error

MigrationHandler is the migration function that each module registers.

type SimulationManager 

type SimulationManager struct {
	Modules       []AppModuleSimulation    // array of app modules; we use an array for deterministic simulation tests
	StoreDecoders sdk.StoreDecoderRegistry // functions to decode the key-value pairs from each module's store
}

SimulationManager defines a simulation manager that provides the high level utility for managing and executing simulation functionalities for a group of modules

func NewSimulationManager 

func NewSimulationManager(modules ...AppModuleSimulation) *SimulationManager

NewSimulationManager creates a new SimulationManager object

CONTRACT: All the modules provided must be also registered on the module Manager

func (*SimulationManager) GenerateGenesisStates 

func (sm *SimulationManager) GenerateGenesisStates(simState *SimulationState)

GenerateGenesisStates generates a randomized GenesisState for each of the registered modules

func (*SimulationManager) GenerateParamChanges 

func (sm *SimulationManager) GenerateParamChanges(seed int64) (paramChanges []simulation.ParamChange)

GenerateParamChanges generates randomized contents for creating params change proposal transactions

func (*SimulationManager) GetProposalContents 

func (sm *SimulationManager) GetProposalContents(simState SimulationState) []simulation.WeightedProposalContent

GetProposalContents returns each module's proposal content generator function with their default operation weight and key.

func (*SimulationManager) RegisterStoreDecoders 

func (sm *SimulationManager) RegisterStoreDecoders()

RegisterStoreDecoders registers each of the modules' store decoders into a map

func (*SimulationManager) WeightedOperations 

func (sm *SimulationManager) WeightedOperations(simState SimulationState) []simulation.WeightedOperation

WeightedOperations returns all the modules' weighted operations of an application

type SimulationState 

type SimulationState struct {
	AppParams    simulation.AppParams
	Cdc          codec.JSONCodec                      // application codec
	Rand         *rand.Rand                           // random number
	GenState     map[string]json.RawMessage           // genesis state
	Accounts     []simulation.Account                 // simulation accounts
	InitialStake sdkmath.Int                          // initial coins per account
	NumBonded    int64                                // number of initially bonded accounts
	GenTimestamp time.Time                            // genesis timestamp
	UnbondTime   time.Duration                        // staking unbond time stored to use it as the slashing maximum evidence duration
	ParamChanges []simulation.ParamChange             // simulated parameter changes from modules
	Contents     []simulation.WeightedProposalContent // proposal content generator functions with their default weight and app sim key
}

SimulationState is the input parameters used on each of the module's randomized GenesisState generator function

type VersionMap added in v0.43.0 

type VersionMap map[string]uint64

VersionMap is a map of moduleName -> version

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.