Skip to content

Commit

Permalink
docs: update "adding params"
Browse files Browse the repository at this point in the history
  • Loading branch information
bryanchriswhite committed Sep 26, 2024
1 parent 826f0bf commit e4cc6df
Showing 1 changed file with 87 additions and 2 deletions.
89 changes: 87 additions & 2 deletions docusaurus/docs/develop/developer_guide/adding_params.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,43 @@ https://github.com/ignite/cli/issues/3684#issuecomment-2299796210

## Step-by-Step Instructions

### 0. If the Module Doesn't Already Support a `MsgUpdateParam` Message

In order to support **individual parameter updates**, the module MUST have a `MsgUpdateParam` message.
If the module doesn't already support this message, it will need to be added.

### 0.1 Scaffold the `MsgUpdateParam` Message

```bash
ignite scaffold message update-param --module <module-name> --signer authority name as_type --response params
```

### 0.2 Update the `MsgUpdateParam` Message Fields

Update the `MsgUpdateParam` message fields in the module's `tx.proto` file to include the following comments and protobuf options:

```diff
+// MsgUpdateParam is the Msg/UpdateParam request type to update a single param.
message MsgUpdateParam {
option (cosmos.msg.v1.signer) = "authority";
- string authority = 1;
+
+ // authority is the address that controls the module (defaults to x/gov unless overwritten).
+ string authority = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+
string name = 2;
- string asType = 3;
+ oneof as_type {
+ // Add `as_<type>` fields for each type in this module's Params type; e.g.:
+ // int64 as_int64 = 3 [(gogoproto.jsontag) = "as_int64"];
+ // bytes as_bytes = 4 [(gogoproto.jsontag) = "as_bytes"];
+ // cosmos.base.v1beta1.Coin as_coin = 5 [(gogoproto.jsontag) = "as_coin"];
+ }
}

message MsgUpdateParamResponse {
```

### 1. Define the Parameter in the Protocol Buffers File

Open the appropriate `.proto` file for your module (e.g., `params.proto`) and define the new parameter.
Expand All @@ -56,9 +93,57 @@ message Params {
}
```

### 2 Update the Parameter Integration Tests
### 2 Update the Parameter Integration Tests

Integration tests which cover parameter updates utilize the `ModuleParamConfig`s defined in [`testutil/integration/params/param_configs.go`](https://github.com/pokt-network/poktroll/blob/main/testutil/integration/suites/param_configs.go) to dynamically (i.e. using reflection) construct and send parameter update messages in a test environment.
When adding parameters to a module, it is necessary to update that module's `ModuleParamConfig` to include the new parameter, othwerwise it will not be covered by the integration test suite.

### 2.1 If the Module Didn't Previously Support a `MsgUpdateParam` Message

Add `MsgUpdateParam` & `MsgUpdateParamResponse` to the module's `ModuleParamConfig#ParamsMsg`:

```diff
SomeModuleParamConfig = ModuleParamConfig{
ParamsMsgs: ModuleParamsMessages{
MsgUpdateParams: gatewaytypes.MsgUpdateParams{},
MsgUpdateParamsResponse: gatewaytypes.MsgUpdateParamsResponse{},
+ MsgUpdateParam: gatewaytypes.MsgUpdateParam{},
+ MsgUpdateParamResponse: gatewaytypes.MsgUpdateParamResponse{},
QueryParamsRequest: gatewaytypes.QueryParamsRequest{},
QueryParamsResponse: gatewaytypes.QueryParamsResponse{},
},
...
}
```

### 2.2 Add a valid param

// TODO_DOCUMENT(@bryanchriswhite, #826)
Update `ModuleParamConfig#ValidParams` to include a valid and non-default value for the new parameter.

```diff
SomeModuleParamConfig = ModuleParamConfig{
...
ValidParams: gatewaytypes.Params{
+ MinStake: &ValidActorMinStake,
},
...
}
```

### 2.3 Check for `as_<type>` on `MsgUpdateParam`

Ensure an `as_<type>` field exists on `MsgUpdateParam` corresponding to the type of the new parameter.
Below is an example of adding an `int64` type parameter to a new `MsgUpdateParam` message:

```diff
message MsgUpdateParam {
...
oneof as_type {
- // Add `as_<type>` fields for each type in this module's Params type; e.g.:
+ int64 as_int64 = 3 [(gogoproto.jsontag) = "as_int64"];
}
}
```

### 3. Update the Default Parameter Values

Expand Down

0 comments on commit e4cc6df

Please sign in to comment.