Module Genesis

Modules generally handle a subset of the state and, as such, they need to define the related subset of the genesis file as well as methods to initialize, verify and export it.

Pre-requisite Readings

• Module Manager
• Keepers

Type Definition

The subset of the genesis state defined from a given module is generally defined in a genesis.proto file (more info on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called GenesisState and contains all the module-related values that need to be initialized during the genesis process.

See an example of GenesisState protobuf message definition from the auth module:

Copy syntax = "proto3"; package cosmos.auth.v1beta1; import "google/protobuf/any.proto"; import "gogoproto/gogo.proto"; import "cosmos/auth/v1beta1/auth.proto"; option go_package = "github.com/cosmos/cosmos-sdk/x/auth/types"; // GenesisState defines the auth module's genesis state. message GenesisState { // params defines all the paramaters of the module. Params params = 1 [(gogoproto.nullable) = false]; // accounts are the accounts present at genesis. repeated google.protobuf.Any accounts = 2; }

Next we present the main genesis-related methods that need to be implemented by module developers in order for their module to be used in Cosmos SDK applications.

DefaultGenesis

The DefaultGenesis() method is a simple method that calls the constructor function for GenesisState with the default value for each parameter. See an example from the auth module:

Copy // DefaultGenesis returns default genesis state as raw bytes for the auth // module. func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage { return cdc.MustMarshalJSON(types.DefaultGenesisState()) }

ValidateGenesis

The ValidateGenesis(data GenesisState) method is called to verify that the provided genesisState is correct. It should perform validity checks on each of the parameters listed in GenesisState. See an example from the auth module:

Copy // ValidateGenesis performs basic validation of auth genesis data returning an // error for any failed validation criteria. func ValidateGenesis(data GenesisState) error { if err := data.Params.Validate(); err != nil { return err } genAccs, err := UnpackAccounts(data.Accounts) if err != nil { return err } return ValidateGenAccounts(genAccs) }

Other Genesis Methods

Other than the methods related directly to GenesisState, module developers are expected to implement two other methods as part of the AppModuleGenesis interface (only if the module needs to initialize a subset of state in genesis). These methods are InitGenesis and ExportGenesis.

InitGenesis

The InitGenesis method is executed during InitChain when the application is first started. Given a GenesisState, it initializes the subset of the state managed by the module by using the module's keeper setter function on each parameter within the GenesisState.

The module manager of the application is responsible for calling the InitGenesis method of each of the application's modules in order. This order is set by the application developer via the manager's SetOrderGenesisMethod, which is called in the application's constructor function.

See an example of InitGenesis from the auth module:

Copy // InitGenesis - Init store state from genesis data // // CONTRACT: old coins from the FeeCollectionKeeper need to be transferred through // a genesis port script to the new fee collector account func (ak AccountKeeper) InitGenesis(ctx sdk.Context, data types.GenesisState) { ak.SetParams(ctx, data.Params) accounts, err := types.UnpackAccounts(data.Accounts) if err != nil { panic(err) } accounts = types.SanitizeGenesisAccounts(accounts) for _, a := range accounts { acc := ak.NewAccount(ctx, a) ak.SetAccount(ctx, acc) } ak.GetModuleAccount(ctx, types.FeeCollectorName) }

ExportGenesis

The ExportGenesis method is executed whenever an export of the state is made. It takes the latest known version of the subset of the state managed by the module and creates a new GenesisState out of it. This is mainly used when the chain needs to be upgraded via a hard fork.

See an example of ExportGenesis from the auth module.

Copy // ExportGenesis returns a GenesisState for a given context and keeper func (ak AccountKeeper) ExportGenesis(ctx sdk.Context) *types.GenesisState { params := ak.GetParams(ctx) var genAccounts types.GenesisAccounts ak.IterateAccounts(ctx, func(account types.AccountI) bool { genAccount := account.(types.GenesisAccount) genAccounts = append(genAccounts, genAccount) return false }) return types.NewGenesisState(params, genAccounts) }

Next

Learn about modules interfaces