appmodulev2

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jan 6, 2025 License: Apache-2.0 Imports: 12 Imported by: 22

Documentation

Overview

Package appmodule defines what is needed for a module to be used in the Cosmos SDK (runtime/v2). If you are looking at integrating dependency injection into your module please see depinject appconfig documentation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterMsgHandler 

func RegisterMsgHandler[Req, Resp any, PReq transaction.GenericMsg[Req], PResp transaction.GenericMsg[Resp]](
	router MsgRouter,
	handler func(ctx context.Context, msg PReq) (msgResp PResp, err error),
)

RegisterMsgHandler is a helper function that modules can use to not lose type safety when registering handlers to the MsgRouter and Query Router. Example usage: ```go 

func (h Handlers) Mint(ctx context.Context, req *types.MsgMint) (*types.MsgMintResponse, error) {
      ... msg logic ...
}

func (h Handlers) QueryBalance(ctx context.Context, req *types.QueryBalanceRequest) (*types.QueryBalanceResponse, error) {
      ... query logic ...
}

func (m Module) RegisterMsgHandlers(router appmodule.MsgRouter) {
	handlers := keeper.NewHandlers(m.keeper)
    err := appmodule.RegisterHandler(router, handlers.MsgMint)
}

func (m Module) RegisterQueryHandlers(router appmodule.QueryRouter) {
	handlers := keeper.NewHandlers(m.keeper)
    err := appmodule.RegisterHandler(router, handlers.QueryBalance)
}

```

func RegisterMsgPreHandler 

func RegisterMsgPreHandler[Req transaction.Msg](
	router PreMsgRouter,
	msgName string,
	handler func(ctx context.Context, msg Req) error,
)

RegisterMsgPreHandler is a helper function that modules can use to not lose type safety when registering PreMsgHandler to the PreMsgRouter. Example usage: ```go 

func (h Handlers) BeforeSend(ctx context.Context, req *types.MsgSend) error {
      ... before send logic ...
}

func (m Module) RegisterPreMsgHandlers(router appmodule.PreMsgRouter) {
	handlers := keeper.NewHandlers(m.keeper)
    appmodule.RegisterMsgPreHandler(router, gogoproto.MessageName(types.MsgSend{}), handlers.BeforeSend)
}

```

func RegisterPostMsgHandler 

func RegisterPostMsgHandler[Req, Resp transaction.Msg](
	router PostMsgRouter,
	msgName string,
	handler func(ctx context.Context, msg Req, msgResp Resp) error,
)

RegisterPostMsgHandler is a helper function that modules can use to not lose type safety when registering handlers to the PostMsgRouter. Example usage: ```go 

func (h Handlers) AfterSend(ctx context.Context, req *types.MsgSend, resp *types.MsgSendResponse) error {
      ... query logic ...
}

func (m Module) RegisterPostMsgHandlers(router appmodule.PostMsgRouter) {
	handlers := keeper.NewHandlers(m.keeper)
    appmodule.RegisterPostMsgHandler(router, gogoproto.MessageName(types.MsgSend{}), handlers.AfterSend)
}

```

Types

type AppModule 

type AppModule interface {
	// IsAppModule is a dummy method to tag a struct as implementing an AppModule.
	IsAppModule()

	// IsOnePerModuleType is a dummy method to help depinject resolve modules.
	IsOnePerModuleType()
}

AppModule is a tag interface for app module implementations to use as a basis for extension interfaces. It provides no functionality itself, but is the type that all valid app modules should provide so that they can be identified by other modules (usually via depinject) as app modules.

type Environment 

type Environment struct {
	Logger log.Logger

	BranchService      branch.Service
	EventService       event.Service
	GasService         gas.Service
	HeaderService      header.Service
	QueryRouterService router.Service
	MsgRouterService   router.Service
	TransactionService transaction.Service

	KVStoreService  store.KVStoreService
	MemStoreService store.MemoryStoreService
}

Environment is used to get all services to their respective module. Contract: All fields of environment are always populated by runtime.

type GenesisDecoder 

type GenesisDecoder interface {
	DecodeGenesisJSON(data json.RawMessage) ([]json.RawMessage, error)
}

GenesisDecoder is an alternative to the InitGenesis method. It is implemented by the genutil module to decode genTxs.

type Handler 

type Handler struct {
	// Func defines the actual handler, the function that runs a request and returns a response.
	// Can be query handler or msg handler.
	Func HandlerFunc
	// MakeMsg instantiates the type of the request, can be used in decoding contexts.
	MakeMsg func() transaction.Msg
	// MakeMsgResp instantiates a new response, can be used in decoding contexts.
	MakeMsgResp func() transaction.Msg
}

Handler defines a handler descriptor.

type HandlerFunc 

type HandlerFunc = func(ctx context.Context, msg transaction.Msg) (msgResp transaction.Msg, err error)

HandlerFunc handles the state transition of the provided message.

type HasABCIGenesis 

type HasABCIGenesis interface {
	AppModule

	DefaultGenesis() json.RawMessage
	ValidateGenesis(data json.RawMessage) error
	InitGenesis(ctx context.Context, data json.RawMessage) ([]ValidatorUpdate, error)
	ExportGenesis(ctx context.Context) (json.RawMessage, error)
}

HasABCIGenesis defines a custom genesis handling API implementation for ABCI. (stateful genesis methods which returns validator updates) Most modules should not implement this interface.

type HasBeginBlocker 

type HasBeginBlocker interface {
	AppModule

	// BeginBlock is a method that will be run before transactions are processed in
	// a block.
	BeginBlock(context.Context) error
}

HasBeginBlocker is the extension interface that modules should implement to run custom logic before transaction processing in a block.

type HasConsensusVersion 

type HasConsensusVersion interface {
	// 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
}

HasConsensusVersion is the interface for declaring a module consensus version.

type HasEndBlocker 

type HasEndBlocker interface {
	AppModule

	// EndBlock is a method that will be run after transactions are processed in
	// a block.
	EndBlock(context.Context) error
}

HasEndBlocker is the extension interface that modules should implement to run custom logic after transaction processing in a block.

type HasGenesis 

type HasGenesis interface {
	AppModule

	DefaultGenesis() json.RawMessage
	ValidateGenesis(data json.RawMessage) error
	InitGenesis(ctx context.Context, data json.RawMessage) error
	ExportGenesis(ctx context.Context) (json.RawMessage, error)
}

HasGenesis defines a custom genesis handling API implementation. WARNING: this API is meant as a short-term solution to allow for the migration of existing modules to the new app module API. It is intended to be replaced by an automatic genesis with collections/orm.

type HasMigrations 

type HasMigrations interface {
	AppModule
	HasConsensusVersion

	// RegisterMigrations registers the module's migrations with the app's migrator.
	RegisterMigrations(MigrationRegistrar) error
}

HasMigrations is implemented by a module which upgrades or has upgraded to a new consensus version.

type HasMsgHandlers 

type HasMsgHandlers interface {
	RegisterMsgHandlers(router MsgRouter)
}

HasMsgHandlers is an interface that modules must implement if they want to register Handlers.

type HasPostMsgHandlers 

type HasPostMsgHandlers interface {
	RegisterPostMsgHandlers(router PostMsgRouter)
}

HasPostMsgHandlers is an interface that modules must implement if they want to register PostMsgHandlers.

type HasPreBlocker 

type HasPreBlocker interface {
	AppModule
	// PreBlock is method that will be run before BeginBlock.
	PreBlock(context.Context) error
}

HasPreBlocker is the extension interface that modules should implement to run custom logic before BeginBlock.

type HasPreMsgHandlers 

type HasPreMsgHandlers interface {
	RegisterPreMsgHandlers(router PreMsgRouter)
}

HasPreMsgHandlers is an interface that modules must implement if they want to register PreMsgHandlers.

type HasQueryHandlers 

type HasQueryHandlers interface {
	RegisterQueryHandlers(router QueryRouter)
}

HasQueryHandlers is an interface that modules must implement if they want to register QueryHandlers.

type HasRegisterInterfaces 

type HasRegisterInterfaces interface {
	RegisterInterfaces(registry.InterfaceRegistrar)
}

HasRegisterInterfaces is the interface for modules to register their msg types.

type HasTxValidator 

type HasTxValidator[T transaction.Tx] interface {
	AppModule

	// TxValidator is a method that will be run on each transaction.
	// If an error is returned:
	// 	                          ,---.
	//                           /    |
	//                          /     |
	//  You shall not pass!    /      |
	//                        /       |
	//           \       ___,'        |
	//                 <  -'          :
	//                  `-.__..--'“-,_\_
	//                     |o/ <o>` :,.)_`>
	//                     :/ `     ||/)
	//                     (_.).__,-` |\
	//                     /( `.“   `| :
	//                     \'`-.)  `  ; ;
	//                     | `       /-<
	//                     |     `  /   `.
	//     ,-_-..____     /|  `    :__..-'\
	//    /,'-.__\\  “-./ :`      ;       \
	//    `\ `\  `\\  \ :  (   `  /  ,   `. \
	//      \` \   \\   |  | `   :  :     .\ \
	//       \ `\_  ))  :  ;     |  |      ): :
	//      (`-.-'\ ||  |\ \   ` ;  ;       | |
	//       \-_   `;;._   ( `  /  /_       | |
	//        `-.-.// ,'`-._\__/_,'         ; |
	//           \:: :     /     `     ,   /  |
	//            || |    (        ,' /   /   |
	//            ||                ,'   /    |
	TxValidator(ctx context.Context, tx T) error
}

HasTxValidator is the extension interface that modules should implement to run custom logic for validating transactions. It was previously known as AnteHandler/Decorator.

type HasUpdateValidators 

type HasUpdateValidators interface {
	AppModule

	UpdateValidators(ctx context.Context) ([]ValidatorUpdate, error)
}

HasUpdateValidators is an extension interface that contains information about the AppModule and UpdateValidators. It can be seen as the alternative of the Cosmos SDK' HasABCIEndBlocker. Both are still supported.

type MigrationHandler 

type MigrationHandler func(context.Context) error

MigrationHandler is the migration function that each module registers.

type MigrationRegistrar 

type MigrationRegistrar interface {
	// Register 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.
	Register(moduleName string, fromVersion uint64, handler MigrationHandler) error
}

MigrationRegistrar is the interface for registering in-place store migrations.

type MsgRouter 

type MsgRouter = interface {
	RegisterHandler(handler Handler)
}

MsgRouter is a router that allows you to register Handlers for specific message types.

type PostMsgHandler 

type PostMsgHandler = func(ctx context.Context, msg, msgResp transaction.Msg) error

PostMsgHandler runs after Handler, only if Handler does not error. If PostMsgHandler errors then the execution is reverted.

type PostMsgRouter 

type PostMsgRouter interface {
	// RegisterPostMsgHandler will register a specific message handler hooking after the execution of message with
	// the provided name.
	RegisterPostMsgHandler(msgName string, handler PostMsgHandler)
	// RegisterGlobalPostMsgHandler will register a global message handler hooking after the execution of any message.
	RegisterGlobalPostMsgHandler(handler PostMsgHandler)
}

PostMsgRouter is a router that allows you to register PostMsgHandlers for specific message types.

type PreMsgHandler 

type PreMsgHandler = func(ctx context.Context, msg transaction.Msg) error

PreMsgHandler is a handler that is executed before Handler. If it errors the execution reverts.

type PreMsgRouter 

type PreMsgRouter interface {
	// RegisterPreMsgHandler will register a specific message handler hooking into the message with
	// the provided name.
	RegisterPreMsgHandler(msgName string, handler PreMsgHandler)
	// RegisterGlobalPreMsgHandler will register a global message handler hooking into any message
	// being executed.
	RegisterGlobalPreMsgHandler(handler PreMsgHandler)
}

PreMsgRouter is a router that allows you to register PreMsgHandlers for specific message types.

type QueryRouter 

type QueryRouter = MsgRouter

QueryRouter is a router that allows you to register QueryHandlers for specific query types.

type TxValidator 

type TxValidator[T transaction.Tx] interface {
	ValidateTx(ctx context.Context, tx T) error
}

TxValidator represent the method that a TxValidator should implement. It was previously known as AnteHandler/Decorator.AnteHandle

type ValidatorUpdate 

type ValidatorUpdate struct {
	PubKey     []byte
	PubKeyType string
	Power      int64 // updated power of the validator
}

ValidatorUpdate defines a validator update.

type VersionMap 

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.