docs: ADR 046 - Module Params (#10214)
ref: https://github.com/cosmos/cosmos-sdk/discussions/9913 --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] added `!` to the type prefix if API or client breaking change - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] provided a link to the relevant issue or specification - [x] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [x] updated the relevant documentation or specification - [x] reviewed "Files changed" and left comments if necessary - [x] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [x] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [x] confirmed `!` in the type prefix if API or client breaking change - [x] confirmed all author checklist items have been addressed - [x] reviewed state machine logic - [x] reviewed API design and naming - [x] reviewed documentation is accurate - [x] reviewed tests and test coverage - [ ] manually tested (if applicable)
This commit is contained in:
Aleksandr Bezobchuk
GitHub
parent
02e3919539
commit
3d8cac3a22
|
|
@ -81,3 +81,4 @@ When writing ADRs, follow the same best practices for writing RFCs. When writing
|
|||
### Draft
|
||||
|
||||
- [ADR 044: Guidelines for Updating Protobuf Definitions](./adr-044-protobuf-updates-guidelines.md)
|
||||
- [ADR 046: Module Params](./adr-046-module-params.md)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,184 @@
|
|||
# ADR 046: Module Params
|
||||
|
||||
## Changelog
|
||||
|
||||
- Sep 22, 2021: Initial Draft
|
||||
|
||||
## Status
|
||||
|
||||
DRAFT
|
||||
|
||||
## Abstract
|
||||
|
||||
This ADR describes an alternative approach to how Cosmos SDK modules use, interact,
|
||||
and store their respective parameters.
|
||||
|
||||
## Context
|
||||
|
||||
Currently, in the Cosmos SDK, modules that require the use of parameters use the
|
||||
`x/params` module. The `x/params` works by having modules define parameters,
|
||||
typically via a simple `Params` structure, and registering that structure in
|
||||
the `x/params` module via a unique `Subspace` that belongs to the respective
|
||||
registering module. The registering module then has unique access to its respective
|
||||
`Subspace`. Through this `Subspace`, the module can get and set its `Params`
|
||||
structure.
|
||||
|
||||
In addition, the Cosmos SDK's `x/gov` module has direct support for changing
|
||||
parameters on-chain via a `ParamChangeProposal` governance proposal type, where
|
||||
stakeholders can vote on suggested parameter changes.
|
||||
|
||||
There are various tradeoffs to using the `x/params` module to manage individual
|
||||
module parameters. Namely, managing parameters essentially comes for "free" in
|
||||
that developers only need to define the `Params` struct, the `Subspace`, and the
|
||||
various auxiliary functions, e.g. `ParamSetPairs`, on the `Params` type. However,
|
||||
there are some notable drawbacks. These drawbacks include the fact that parameters
|
||||
are serialized in state via JSON which is extremely slow. In addition, parameter
|
||||
changes via `ParamChangeProposal` governance proposals have no way of reading from
|
||||
or writing to state. In other words, it is currently not possible to have any
|
||||
state transitions in the application during an attempt to change param(s).
|
||||
|
||||
## Decision
|
||||
|
||||
We will build off of the alignment of `x/gov` and `x/authz` work per
|
||||
[#9810](https://github.com/cosmos/cosmos-sdk/pull/9810). Namely, module developers
|
||||
will create one or more unique parameter data structures that must be serialized
|
||||
to state. The Param data structures must implement `sdk.Msg` interface with respective
|
||||
Protobuf Msg service method which will validate and update the parameters with all
|
||||
necessary changes. The `x/gov` module via the work done in
|
||||
[#9810](https://github.com/cosmos/cosmos-sdk/pull/9810), will dispatch Param
|
||||
messages, which will be handled by Protobuf Msg services.
|
||||
|
||||
Note, it is up to developers to decide how to structure their parameters and
|
||||
the respective `sdk.Msg` messages. Consider the parameters currently defined in
|
||||
`x/auth` using the `x/params` module for parameter management:
|
||||
|
||||
```protobuf
|
||||
message Params {
|
||||
uint64 max_memo_characters = 1;
|
||||
uint64 tx_sig_limit = 2;
|
||||
uint64 tx_size_cost_per_byte = 3;
|
||||
uint64 sig_verify_cost_ed25519 = 4;
|
||||
uint64 sig_verify_cost_secp256k1 = 5;
|
||||
}
|
||||
```
|
||||
|
||||
Developers can choose to either create a unique data structure for every field in
|
||||
`Params` or they can create a single `Params` structure as outlined above in the
|
||||
case of `x/auth`.
|
||||
|
||||
In the former, `x/params`, approach, a `sdk.Msg` would need to be created for every single
|
||||
field along with a handler. This can become burdensome if there are a lot of
|
||||
parameter fields. In the latter case, there is only a single data structure and
|
||||
thus only a single message handler, however, the message handler might have to be
|
||||
more sophisticated in that it might need to understand what parameters are being
|
||||
changed vs what parameters are untouched.
|
||||
|
||||
Params change proposals are made using the `x/gov` module. Execution is done through
|
||||
`x/authz` authorization to the root `x/gov` module's account.
|
||||
|
||||
Continuing to use `x/auth`, we demonstrate a more complete example:
|
||||
|
||||
```go
|
||||
type Params struct {
|
||||
MaxMemoCharacters uint64
|
||||
TxSigLimit uint64
|
||||
TxSizeCostPerByte uint64
|
||||
SigVerifyCostED25519 uint64
|
||||
SigVerifyCostSecp256k1 uint64
|
||||
}
|
||||
|
||||
type MsgUpdateParams struct {
|
||||
MaxMemoCharacters uint64
|
||||
TxSigLimit uint64
|
||||
TxSizeCostPerByte uint64
|
||||
SigVerifyCostED25519 uint64
|
||||
SigVerifyCostSecp256k1 uint64
|
||||
}
|
||||
|
||||
type MsgUpdateParamsResponse struct {}
|
||||
|
||||
func (ms msgServer) UpdateParams(goCtx context.Context, msg *types.MsgUpdateParams) (*types.MsgUpdateParamsResponse, error) {
|
||||
ctx := sdk.UnwrapSDKContext(goCtx)
|
||||
|
||||
// verification logic...
|
||||
|
||||
// persist params
|
||||
params := ParamsFromMsg(msg)
|
||||
ms.SaveParams(ctx, params)
|
||||
|
||||
return &types.MsgUpdateParamsResponse{}, nil
|
||||
}
|
||||
|
||||
func ParamsFromMsg(msg *types.MsgUpdateParams) Params {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
A gRPC `Service` query should also be provided, for example:
|
||||
|
||||
```protobuf
|
||||
service Query {
|
||||
// ...
|
||||
|
||||
rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
|
||||
option (google.api.http).get = "/cosmos/<module>/v1beta1/params";
|
||||
}
|
||||
}
|
||||
|
||||
message QueryParamsResponse {
|
||||
Params params = 1 [(gogoproto.nullable) = false];
|
||||
}
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
As a result of implementing the module parameter methodology, we gain the ability
|
||||
for module parameter changes to be stateful and extensible to fit nearly every
|
||||
application's use case. We will be able to emit events (and trigger hooks registered
|
||||
to that events using the work proposed in [even hooks](https://github.com/cosmos/cosmos-sdk/discussions/9656)),
|
||||
call other Msg service methods or perform migration.
|
||||
In addition, there will be significant gains in performance when it comes to reading
|
||||
and writing parameters from and to state, especially if a specific set of parameters
|
||||
are read on a consistent basis.
|
||||
|
||||
However, this methodology will require developers to implement more types and
|
||||
Msg service metohds which can become burdensome if many parameters exist. In addition,
|
||||
developers are required to implement persistance logics of module parameters.
|
||||
However, this should be trivial.
|
||||
|
||||
### Backwards Compatibility
|
||||
|
||||
The new method for working with module parameters is naturally not backwards
|
||||
compatible with the existing `x/params` module. However, the `x/params` will
|
||||
remain in the Cosmos SDK and will be marked as deprecated with no additional
|
||||
functionality being added apart from potential bug fixes. Note, the `x/params`
|
||||
module may be removed entirely in a future release.
|
||||
|
||||
### Positive
|
||||
|
||||
- Module parameters are serialized more efficiently
|
||||
- Modules are able to react on parameters changes and perform additional actions.
|
||||
- Special events can be emitted, allowing hooks to be triggered.
|
||||
|
||||
### Negative
|
||||
|
||||
- Module parameters becomes slightly more burdensome for module developers:
|
||||
- Modules are now responsible for persisting and retrieving parameter state
|
||||
- Modules are now required to have unique message handlers to handle parameter
|
||||
changes per unique parameter data structure.
|
||||
|
||||
### Neutral
|
||||
|
||||
- Requires [#9810](https://github.com/cosmos/cosmos-sdk/pull/9810) to be reviewed
|
||||
and merged.
|
||||
|
||||
<!-- ## Further Discussions
|
||||
|
||||
While an ADR is in the DRAFT or PROPOSED stage, this section should contain a summary of issues to be solved in future iterations (usually referencing comments from a pull-request discussion).
|
||||
Later, this section can optionally list ideas or improvements the author or reviewers found during the analysis of this ADR. -->
|
||||
|
||||
## References
|
||||
|
||||
- https://github.com/cosmos/cosmos-sdk/pull/9810
|
||||
- https://github.com/cosmos/cosmos-sdk/issues/9438
|
||||
- https://github.com/cosmos/cosmos-sdk/discussions/9913
|
||||
Loading…
Reference in New Issue