From 1b1dbf8ab722e4689e14a5a2a1fc433b69bc155e Mon Sep 17 00:00:00 2001 From: Marie Gauthier Date: Fri, 15 Jan 2021 14:30:17 +0100 Subject: [PATCH] x/params docs general audit & cleanup (#8295) * Update doc.go * Update spec/ * More updates * Update README Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> --- x/params/doc.go | 21 ++++++++++----------- x/params/spec/01_keeper.md | 18 +++++------------- x/params/spec/02_subspace.md | 16 +++++++--------- x/params/spec/README.md | 5 ++--- 4 files changed, 24 insertions(+), 36 deletions(-) diff --git a/x/params/doc.go b/x/params/doc.go index 68ab4dee0..2a79b0fd5 100644 --- a/x/params/doc.go +++ b/x/params/doc.go @@ -6,9 +6,8 @@ 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, who needs a private parameter store -that the other keeper cannot modify. Keeper can be used by the Governance keeper, -who need to modify any parameter in case of the proposal passes. +Subspace can be used by the individual keepers, which need a private parameter store +that the other keepers cannot modify. Basic Usage: @@ -23,11 +22,11 @@ Basic Usage: KeyParameter2 = "myparameter2" ) -2. Create a concrete parameter struct and define the validation functions: +2. Define parameters as proto message and define the validation functions: - type MyParams struct { - MyParam1 int64 `json:"my_param1" yaml:"my_param1"` - MyParam2 bool `json:"my_param2" yaml:"my_param2"` + message MyParams { + int64 my_param1 = 1; + bool my_param2 = 2; } func validateMyParam1(i interface{}) error { @@ -56,12 +55,12 @@ Basic Usage: func (p *MyParams) ParamSetPairs() params.ParamSetPairs { return params.ParamSetPairs{ - {KeyParameter1, &p.MyParam1, validateMyParam1}, - {KeyParameter2, &p.MyParam2, validateMyParam2}, + params.NewParamSetPair(KeyParameter1, &p.MyParam1, validateMyParam1), + params.NewParamSetPair(KeyParameter2, &p.MyParam2, validateMyParam2), } } - func paramKeyTable() params.KeyTable { + func ParamKeyTable() params.KeyTable { return params.NewKeyTable().RegisterParamSet(&MyParams{}) } @@ -70,7 +69,7 @@ Basic Usage: func NewKeeper(..., paramSpace params.Subspace, ...) Keeper { // set KeyTable if it has not already been set if !paramSpace.HasKeyTable() { - paramSpace = paramSpace.WithKeyTable(paramKeyTable()) + paramSpace = paramSpace.WithKeyTable(ParamKeyTable()) } return Keeper { diff --git a/x/params/spec/01_keeper.md b/x/params/spec/01_keeper.md index 8cf7e2a53..fa97ec5b3 100644 --- a/x/params/spec/01_keeper.md +++ b/x/params/spec/01_keeper.md @@ -4,24 +4,16 @@ order: 1 # Keeper -In the app initialization stage, `Keeper.Subspace(Paramspace)` is passed to the -user modules, and the subspaces are stored in `Keeper.spaces`. Later it can be -retrieved with `Keeper.GetSubspace`, so the keepers holding `Keeper` can access -to any subspace. For example, Gov module can take `Keeper` as its argument and -modify parameter of any subspace when a `ParameterChangeProposal` is accepted. +In the app initialization stage, [subspaces](02_subspace.md) 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: ```go -type MasterKeeper struct { - pk params.Keeper +type ExampleKeeper struct { + paramSpace paramtypes.Subspace } -func (k MasterKeeper) SetParam(ctx sdk.Context, space string, key string, param interface{}) { - space, ok := k.ps.GetSubspace(space) - if !ok { - return - } - space.Set(ctx, key, param) +func (k ExampleKeeper) SetParams(ctx sdk.Context, params types.Params) { + k.paramSpace.SetParamSet(ctx, ¶ms) } ``` diff --git a/x/params/spec/02_subspace.md b/x/params/spec/02_subspace.md index 5e36eaf49..e6ffa760d 100644 --- a/x/params/spec/02_subspace.md +++ b/x/params/spec/02_subspace.md @@ -4,8 +4,8 @@ order: 2 # Subspace -`Subspace` is a prefixed subspace of the parameter store. Each module who use the -parameter store will take a `Subspace`, not the `Keeper`, to isolate permission to access. +`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 @@ -21,20 +21,18 @@ Subkeys can be used for grouping or dynamic parameter key generation during runt 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` only consists of `reflect.Type`, which indicates the parameter -type. It is needed even if the state machine has no error, because the paraeter -can be modified externally, for example via the governance. +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 a struct of parameters. Instead of calling methods with -each of those parameters, when the struct implements `ParamSet`, it can be used -with the following methods: +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 implementor should be a pointer in order to use `GetParamSet()` +The implementor should be a pointer in order to use `GetParamSet()`. diff --git a/x/params/spec/README.md b/x/params/spec/README.md index c84ad6e5b..4a136cce5 100644 --- a/x/params/spec/README.md +++ b/x/params/spec/README.md @@ -15,9 +15,8 @@ There are two main types, Keeper and Subspace. Subspace is an isolated namespace 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, who needs a private parameter store -that the other keeper cannot modify. Keeper can be used by the Governance keeper, -who need to modify any parameter in case of the proposal passes. +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.