params

README

---

sidebar_position: 1

x/params

Note: The Params module has been deprecated in favour of each module housing its own parameters.

Abstract

Package params provides a globally available parameter store.

There are two main types, Keeper and Subspace. Subspace is an isolated namespace for a paramstore, where keys are prefixed by preconfigured spacename. Keeper has a permission to access all existing spaces.

Subspace can be used by the individual keepers, which need a private parameter store that the other keepers cannot modify. The params Keeper can be used to add a route to x/gov router in order to modify any parameter in case a proposal passes.

The following contents explains how to use params module for master and user modules.

Contents

• Keeper
• Subspace
  • Key
  • KeyTable
  • ParamSet

Keeper

In the app initialization stage, subspaces can be allocated for other modules' keeper using Keeper.Subspace and are stored in Keeper.spaces. Then, those modules can have a reference to their specific parameter store through Keeper.GetSubspace.

Example:

type ExampleKeeper struct {
	paramSpace paramtypes.Subspace
}

func (k ExampleKeeper) SetParams(ctx sdk.Context, params types.Params) {
	k.paramSpace.SetParamSet(ctx, &params)
}

Subspace

Subspace is a prefixed subspace of the parameter store. Each module which uses the parameter store will take a Subspace to isolate permission to access.

Key

Parameter keys are human readable alphanumeric strings. A parameter for the key "ExampleParameter" is stored under []byte("SubspaceName" + "/" + "ExampleParameter"), where "SubspaceName" is the name of the subspace.

Subkeys are secondary parameter keys those are used along with a primary parameter key. Subkeys can be used for grouping or dynamic parameter key generation during runtime.

KeyTable

All of the parameter keys that will be used should be registered at the compile time. KeyTable is essentially a map[string]attribute, where the string is a parameter key.

Currently, attribute consists of a reflect.Type, which indicates the parameter type to check that provided key and value are compatible and registered, as well as a function ValueValidatorFn to validate values.

Only primary keys have to be registered on the KeyTable. Subkeys inherit the attribute of the primary key.

ParamSet

Modules often define parameters as a proto message. The generated struct can implement ParamSet interface to be used with the following methods:

• KeyTable.RegisterParamSet(): registers all parameters in the struct
• Subspace.{Get, Set}ParamSet(): Get to & Set from the struct

The implementer should be a pointer in order to use GetParamSet().

Documentation

Overview

Package params provides a namespaced module parameter store.

There are two core components, Keeper and Subspace. Subspace is an isolated namespace for a parameter store, where keys are prefixed by pre-configured subspace names which modules provide. The Keeper has a permission to access all existing subspaces.

Subspace can be used by the individual keepers, which need a private parameter store that the other keepers cannot modify.

Basic Usage:

1. Declare constant module parameter keys and the globally unique Subspace name:

const (
	ModuleSubspace = "mymodule"
)

const (
	KeyParameter1 = "myparameter1"
	KeyParameter2 = "myparameter2"
)

2. Define parameters as proto message and define the validation functions:

message MyParams {
	int64 my_param1 = 1;
	bool my_param2 = 2;
}

func validateMyParam1(i interface{}) error {
	_, ok := i.(int64)
	if !ok {
		return fmt.Errorf("invalid parameter type: %T", i)
	}

	// validate (if necessary)...

	return nil
}

func validateMyParam2(i interface{}) error {
	_, ok := i.(bool)
	if !ok {
		return fmt.Errorf("invalid parameter type: %T", i)
	}

	// validate (if necessary)...

	return nil
}

3. Implement the params.ParamSet interface:

func (p *MyParams) ParamSetPairs() params.ParamSetPairs {
	return params.ParamSetPairs{
		params.NewParamSetPair(KeyParameter1, &p.MyParam1, validateMyParam1),
		params.NewParamSetPair(KeyParameter2, &p.MyParam2, validateMyParam2),
	}
}

func ParamKeyTable() params.KeyTable {
	return params.NewKeyTable().RegisterParamSet(&MyParams{})
}

4. Have the module accept a Subspace in the constructor and set the KeyTable (if necessary):

func NewKeeper(..., paramSpace params.Subspace, ...) Keeper {
	// set KeyTable if it has not already been set
	if !paramSpace.HasKeyTable() {
		paramSpace = paramSpace.WithKeyTable(ParamKeyTable())
	}

	return Keeper {
		// ...
		paramSpace: paramSpace,
	}
}

Now we have access to the module's parameters that are namespaced using the keys defined:

func InitGenesis(ctx sdk.Context, k Keeper, gs GenesisState) {
	// ...
	k.SetParams(ctx, gs.Params)
}

func (k Keeper) SetParams(ctx sdk.Context, params Params) {
	k.paramSpace.SetParamSet(ctx, &params)
}

func (k Keeper) GetParams(ctx sdk.Context) (params Params) {
	k.paramSpace.GetParamSet(ctx, &params)
	return params
}

func (k Keeper) MyParam1(ctx sdk.Context) (res int64) {
	k.paramSpace.Get(ctx, KeyParameter1, &res)
	return res
}

func (k Keeper) MyParam2(ctx sdk.Context) (res bool) {
	k.paramSpace.Get(ctx, KeyParameter2, &res)
	return res
}

NOTE: Any call to SetParamSet will panic or any call to Update will error if any given parameter value is invalid based on the registered value validation function.

Index

• Constants
• func NewParamChangeProposalHandler(k keeper.Keeper) govtypes.Handler
• func ProvideSubspace(in SubspaceInputs) types.Subspace
• type AppModule
  • func NewAppModule(k keeper.Keeper) AppModule
  • func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions
  • func (AppModule) ConsensusVersion() uint64
  • func (AppModule) GenerateGenesisState(simState *module.SimulationState)
  • func (am AppModule) IsAppModule()
  • func (am AppModule) IsOnePerModuleType()
  • func (AppModule) Name() string
  • func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)
  • func (AppModule) RegisterInterfaces(registrar registry.InterfaceRegistrar)
  • func (AppModule) RegisterLegacyAminoCodec(registrar registry.AminoRegistrar)
  • func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error
  • func (AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)
• type ModuleInputs
• type ModuleOutputs
  • func ProvideModule(in ModuleInputs) ModuleOutputs
• type SubspaceInputs

Constants

const ConsensusVersion = 1

ConsensusVersion defines the current x/params module consensus version.

Functions

func NewParamChangeProposalHandler

func NewParamChangeProposalHandler(k keeper.Keeper) govtypes.Handler

NewParamChangeProposalHandler creates a new governance Handler for a ParamChangeProposal

func ProvideSubspace

func ProvideSubspace(in SubspaceInputs) types.Subspace

Types

type AppModule

type AppModule struct {
	// contains filtered or unexported fields
}

AppModule implements an application module for the distribution module.

func NewAppModule

func NewAppModule(k keeper.Keeper) AppModule

NewAppModule creates a new AppModule object

func (AppModule) AutoCLIOptions

func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions

AutoCLIOptions implements the autocli.HasAutoCLIConfig interface.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements HasConsensusVersion

func (AppModule) GenerateGenesisState

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState performs a no-op.

func (AppModule) IsAppModule

func (am AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) Name

func (AppModule) Name() string

Name returns the params module's name. Deprecated: kept for legacy reasons.

func (AppModule) RegisterGRPCGatewayRoutes

func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the params module.

func (AppModule) RegisterInterfaces

func (AppModule) RegisterInterfaces(registrar registry.InterfaceRegistrar)

RegisterInterfaces registers the module's interface types

func (AppModule) RegisterLegacyAminoCodec

func (AppModule) RegisterLegacyAminoCodec(registrar registry.AminoRegistrar)

RegisterLegacyAminoCodec registers the params module's types on the given LegacyAmino codec.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error

RegisterServices registers module services.

func (AppModule) RegisterStoreDecoder

func (AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)

RegisterStoreDecoder doesn't register any type.

type ModuleInputs

type ModuleInputs struct {
	depinject.In

	KvStoreKey        *store.KVStoreKey
	TransientStoreKey *store.TransientStoreKey
	Cdc               codec.Codec
	LegacyAmino       *codec.LegacyAmino
}

type ModuleOutputs

type ModuleOutputs struct {
	depinject.Out

	ParamsKeeper keeper.Keeper
	Module       appmodule.AppModule
	GovHandler   govv1beta1.HandlerRoute
}

func ProvideModule

func ProvideModule(in ModuleInputs) ModuleOutputs

type SubspaceInputs

type SubspaceInputs struct {
	depinject.In

	Key       depinject.ModuleKey
	Keeper    keeper.Keeper
	KeyTables map[string]types.KeyTable
}