module

package
v0.52.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Dec 18, 2024 License: Apache-2.0 Imports: 31 Imported by: 12,394

Documentation

Overview

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

  • 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 of modules can be accessed through a non instantiated AppModule.

Lastly the interface for genesis functionality (HasGenesis & HasABCIGenesis) 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 {
	Name() string

	appmodulev2.AppModule
}

AppModule is the form for an application module. Most of its functionality has been moved to extension interfaces. Deprecated: use appmodule.AppModule with a combination of extension interfaces instead.

func CoreAppModuleAdaptor added in v0.50.0 

func CoreAppModuleAdaptor(name string, module appmodule.AppModule) AppModule

CoreAppModuleAdaptor wraps the core API module as an AppModule that this version of the SDK can use.

type AppModuleBasic deprecated 

type AppModuleBasic interface {
	HasGRPCGateway
	HasAminoCodec
}

Deprecated: use the embed extension interfaces instead, when needed.

type AppModuleSimulation 

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

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

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

type Configurator deprecated added in v0.40.0 

type Configurator interface {
	grpc.Server

	// Error returns the last error encountered during RegisterService.
	Error() error

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

	// Register registers an in-place store migration for a module.
	// It permits to register modules migrations that have migrated to serverv2 but still be compatible with baseapp.
	Register(moduleName string, fromVersion uint64, handler appmodule.MigrationHandler) error
}

Deprecated: The Configurator is deprecated. Preferably use core services for registering msg/query server and migrations.

func NewConfigurator added in v0.40.0 

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

NewConfigurator returns a new Configurator instance

type HasABCIEndBlock added in v0.50.0 

type HasABCIEndBlock interface {
	AppModule
	EndBlock(context.Context) ([]ValidatorUpdate, error)
}

HasABCIEndBlock is the interface for modules that need to run code at the end of the block.

type HasABCIGenesis added in v0.50.0 

type HasABCIGenesis = appmodulev2.HasABCIGenesis

HasABCIGenesis is the extension interface for stateful genesis methods which returns validator updates.

type HasAminoCodec 

type HasAminoCodec interface {
	RegisterLegacyAminoCodec(registry.AminoRegistrar)
}

HasAminoCodec is the interface for modules that have amino codec registration. Deprecated: modules should not need to register their own amino codecs.

type HasGRPCGateway 

type HasGRPCGateway interface {
	RegisterGRPCGatewayRoutes(client.Context, *runtime.ServeMux)
}

HasGRPCGateway is the interface for modules to register their gRPC gateway routes.

type HasGenesis added in v0.47.0 

type HasGenesis = appmodulev2.HasGenesis

HasGenesis is the extension interface for stateful genesis methods. Prefer directly importing appmodulev2 or appmodule instead of using this alias.

type HasGenesisBasics added in v0.47.0 

type HasGenesisBasics = appmodule.HasGenesisBasics

HasGenesisBasics is the legacy interface for stateless genesis methods.

type HasInvariants added in v0.47.0 

type HasInvariants interface {
	// RegisterInvariants registers module invariants.
	RegisterInvariants(sdk.InvariantRegistry)
}

HasInvariants is the interface for registering invariants.

type HasLegacyProposalContents 

type HasLegacyProposalContents interface {
	// ProposalContents content functions used to simulate governance proposals
	ProposalContents(simState SimulationState) []simulation.WeightedProposalContent //nolint:staticcheck // legacy v1beta1 governance
}

HasLegacyProposalContents defines the contents that can be used to simulate legacy governance (v1beta1) proposals Deprecated replaced by HasProposalMsgsX

type HasLegacyProposalMsgs 

type HasLegacyProposalMsgs interface {
	// ProposalMsgs msg functions used to simulate governance proposals
	ProposalMsgs(simState SimulationState) []simulation.WeightedProposalMsg
}

HasLegacyProposalMsgs defines the messages that can be used to simulate governance (v1) proposals Deprecated replaced by HasProposalMsgsX

type HasLegacyWeightedOperations 

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

type HasServices added in v0.47.0 

type HasServices interface {
	// RegisterServices allows a module to register services.
	RegisterServices(Configurator)
}

HasServices is the interface for modules to register services.

type Manager 

type Manager struct {
	Modules                  map[string]appmodule.AppModule
	OrderInitGenesis         []string
	OrderExportGenesis       []string
	OrderPreBlockers         []string
	OrderBeginBlockers       []string
	OrderEndBlockers         []string
	OrderPrepareCheckStaters []string
	OrderPrecommiters        []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. Deprecated: Use NewManagerFromMap instead.

func NewManagerFromMap added in v0.47.0 

func NewManagerFromMap(moduleMap map[string]appmodule.AppModule) *Manager

NewManagerFromMap creates a new Manager object from a map of module names to module implementations.

func (*Manager) AddQueryCommands 

func (m *Manager) AddQueryCommands(rootQueryCmd *cobra.Command)

AddQueryCommands adds all query commands to the rootQueryCmd.

func (*Manager) AddTxCommands 

func (m *Manager) AddTxCommands(rootTxCmd *cobra.Command)

AddTxCommands adds all tx commands to the rootTxCmd.

func (*Manager) BeginBlock 

func (m *Manager) BeginBlock(ctx sdk.Context) (sdk.BeginBlock, error)

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

func (m *Manager) DefaultGenesis() map[string]json.RawMessage

DefaultGenesis provides default genesis information for all modules

func (*Manager) EndBlock 

func (m *Manager) EndBlock(ctx sdk.Context) (sdk.EndBlock, error)

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) (map[string]json.RawMessage, error)

ExportGenesis performs export genesis functionality for modules

func (*Manager) ExportGenesisForModules added in v0.47.0 

func (m *Manager) ExportGenesisForModules(ctx sdk.Context, modulesToExport []string) (map[string]json.RawMessage, error)

ExportGenesisForModules performs export genesis functionality for modules

func (*Manager) GetVersionMap added in v0.43.0 

func (m *Manager) GetVersionMap() appmodule.VersionMap

GetVersionMap gets consensus version from all modules

func (*Manager) InitGenesis 

func (m *Manager) InitGenesis(ctx sdk.Context, genesisData map[string]json.RawMessage) (*abci.InitChainResponse, error)

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) PreBlock added in v0.50.0 

func (m *Manager) PreBlock(ctx sdk.Context) error

PreBlock performs begin block functionality for upgrade module. It takes the current context as a parameter and returns a boolean value indicating whether the migration was successfully executed or not.

func (*Manager) Precommit added in v0.50.0 

func (m *Manager) Precommit(ctx sdk.Context) error

Precommit performs precommit functionality for all modules.

func (*Manager) PrepareCheckState added in v0.50.0 

func (m *Manager) PrepareCheckState(ctx sdk.Context) error

PrepareCheckState performs functionality for preparing the check state for all modules.

func (*Manager) RegisterGRPCGatewayRoutes 

func (m *Manager) RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers all module rest routes

func (*Manager) RegisterInterfaces 

func (m *Manager) RegisterInterfaces(registrar registry.InterfaceRegistrar)

RegisterInterfaces registers all module interface types

func (*Manager) RegisterInvariants 

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

RegisterInvariants registers all module invariants

func (*Manager) RegisterLegacyAminoCodec 

func (m *Manager) RegisterLegacyAminoCodec(registrar registry.AminoRegistrar)

RegisterLegacyAminoCodec registers all module codecs

func (*Manager) RegisterServices added in v0.40.0 

func (m *Manager) RegisterServices(cfg Configurator) error

RegisterServices registers all module services

func (Manager) RunMigrations added in v0.43.0 

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

RunMigrations performs in-place store migrations for all modules. This function MUST be called inside 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 context.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 context.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 https://docs.cosmos.network/main/core/upgrade 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`.

func (*Manager) SetOrderPreBlockers added in v0.50.0 

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

SetOrderPreBlockers sets the order of set pre-blocker calls

func (*Manager) SetOrderPrecommiters added in v0.50.0 

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

SetOrderPrecommiters sets the order of set precommiter calls

func (*Manager) SetOrderPrepareCheckStaters added in v0.50.0 

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

SetOrderPrepareCheckStaters sets the order of set prepare-check-stater calls

func (*Manager) ValidateGenesis 

func (m *Manager) ValidateGenesis(genesisData map[string]json.RawMessage) error

ValidateGenesis performs genesis state validation for all modules

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 simulation.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 NewSimulationManagerFromAppModules added in v0.45.5 

func NewSimulationManagerFromAppModules(modules map[string]appmodule.AppModule, overrideModules map[string]AppModuleSimulation) *SimulationManager

NewSimulationManagerFromAppModules creates a new SimulationManager object.

First it sets any SimulationModule provided by overrideModules, and ignores any AppModule with the same moduleName. Then it attempts to cast every provided AppModule into an AppModuleSimulation. If the cast succeeds, its included, otherwise it is excluded.

func (*SimulationManager) GenerateGenesisStates 

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

GenerateGenesisStates generates a randomized GenesisState for each of the registered modules

func (*SimulationManager) GetProposalContents deprecated 

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

Deprecated: Use GetProposalMsgs instead. 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

type SimulationState 

type SimulationState struct {
	AppParams         simulation.AppParams
	Cdc               codec.JSONCodec                // application codec
	AddressCodec      address.Codec                  // address codec
	ValidatorCodec    address.Codec                  // validator address codec
	TxConfig          client.TxConfig                // Shared TxConfig; this is expensive to create and stateless, so create it once up front.
	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
	BondDenom         string                         // denom to be used as default
	GenTimestamp      time.Time                      // genesis timestamp
	UnbondTime        time.Duration                  // staking unbond time stored to use it as the slashing maximum evidence duration
	LegacyParamChange []simulation.LegacyParamChange // simulated parameter changes from modules
}

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

type ValidatorUpdate 

type ValidatorUpdate = appmodulev2.ValidatorUpdate

ValidatorUpdate is the type for validator updates.

type VersionMap added in v0.43.0 

type VersionMap appmodule.VersionMap

VersionMap is a map of moduleName -> version

Source Files

View all Source files

Directories

Path Synopsis

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.