github.com/Finschia/finschia-sdk@v0.48.1/x/params/doc.go (about)

     1  /*
     2  Package params provides a namespaced module parameter store.
     3  
     4  There are two core components, Keeper and Subspace. Subspace is an isolated
     5  namespace for a parameter store, where keys are prefixed by pre-configured
     6  subspace names which modules provide. The Keeper has a permission to access all
     7  existing subspaces.
     8  
     9  Subspace can be used by the individual keepers, which need a private parameter store
    10  that the other keepers cannot modify.
    11  
    12  Basic Usage:
    13  
    14  1. Declare constant module parameter keys and the globally unique Subspace name:
    15  
    16  	const (
    17  		ModuleSubspace = "mymodule"
    18  	)
    19  
    20  	const (
    21  		KeyParameter1 = "myparameter1"
    22  		KeyParameter2 = "myparameter2"
    23  	)
    24  
    25  2. Define parameters as proto message and define the validation functions:
    26  
    27  	message MyParams {
    28  		int64 my_param1 = 1;
    29  		bool my_param2 = 2;
    30  	}
    31  
    32  	func validateMyParam1(i interface{}) error {
    33  		_, ok := i.(int64)
    34  		if !ok {
    35  			return fmt.Errorf("invalid parameter type: %T", i)
    36  		}
    37  
    38  		// validate (if necessary)...
    39  
    40  		return nil
    41  	}
    42  
    43  	func validateMyParam2(i interface{}) error {
    44  		_, ok := i.(bool)
    45  		if !ok {
    46  			return fmt.Errorf("invalid parameter type: %T", i)
    47  		}
    48  
    49  		// validate (if necessary)...
    50  
    51  		return nil
    52  	}
    53  
    54  3. Implement the params.ParamSet interface:
    55  
    56  	func (p *MyParams) ParamSetPairs() params.ParamSetPairs {
    57  		return params.ParamSetPairs{
    58  			params.NewParamSetPair(KeyParameter1, &p.MyParam1, validateMyParam1),
    59  			params.NewParamSetPair(KeyParameter2, &p.MyParam2, validateMyParam2),
    60  		}
    61  	}
    62  
    63  	func ParamKeyTable() params.KeyTable {
    64  		return params.NewKeyTable().RegisterParamSet(&MyParams{})
    65  	}
    66  
    67  4. Have the module accept a Subspace in the constructor and set the KeyTable (if necessary):
    68  
    69  	func NewKeeper(..., paramSpace params.Subspace, ...) Keeper {
    70  		// set KeyTable if it has not already been set
    71  		if !paramSpace.HasKeyTable() {
    72  			paramSpace = paramSpace.WithKeyTable(ParamKeyTable())
    73  		}
    74  
    75  		return Keeper {
    76  			// ...
    77  			paramSpace: paramSpace,
    78  		}
    79  	}
    80  
    81  Now we have access to the module's parameters that are namespaced using the keys defined:
    82  
    83  	func InitGenesis(ctx sdk.Context, k Keeper, gs GenesisState) {
    84  		// ...
    85  		k.SetParams(ctx, gs.Params)
    86  	}
    87  
    88  	func (k Keeper) SetParams(ctx sdk.Context, params Params) {
    89  		k.paramSpace.SetParamSet(ctx, &params)
    90  	}
    91  
    92  	func (k Keeper) GetParams(ctx sdk.Context) (params Params) {
    93  		k.paramSpace.GetParamSet(ctx, &params)
    94  		return params
    95  	}
    96  
    97  	func (k Keeper) MyParam1(ctx sdk.Context) (res int64) {
    98  		k.paramSpace.Get(ctx, KeyParameter1, &res)
    99  		return res
   100  	}
   101  
   102  	func (k Keeper) MyParam2(ctx sdk.Context) (res bool) {
   103  		k.paramSpace.Get(ctx, KeyParameter2, &res)
   104  		return res
   105  	}
   106  
   107  NOTE: Any call to SetParamSet will panic or any call to Update will error if any
   108  given parameter value is invalid based on the registered value validation function.
   109  */
   110  package params