diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ed2d4d805..007770c185 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,3 +56,4 @@ Ref: https://keepachangelog.com/en/1.0.0/ ### Document Updates * (docs) [\#483](https://github.com/line/lbm-sdk/pull/483) update documents on x/stakingplus +* (docs) [\#490](https://github.com/line/lbm-sdk/pull/490) update documents on x/consortium diff --git a/x/README.md b/x/README.md index 2698f34a3b..8365fc1c79 100644 --- a/x/README.md +++ b/x/README.md @@ -11,6 +11,7 @@ Here are some production-grade modules that can be used in Cosmos SDK applicatio - [Authz](authz/spec/README.md) - Authorization for accounts to perform actions on behalf of other accounts. - [Bank](bank/spec/README.md) - Token transfer functionalities. - [Capability](capability/spec/README.md) - Object capability implementation. +- [Consortium](consortium/spec/README.md) - Consotrium related functionalities. - [Crisis](crisis/spec/README.md) - Halting the blockchain under certain circumstances (e.g. if an invariant is broken). - [Distribution](distribution/spec/README.md) - Fee distribution, and staking token provision distribution. - [Evidence](evidence/spec/README.md) - Evidence handling for double signing, misbehaviour, etc. diff --git a/x/consortium/spec/01_concepts.md b/x/consortium/spec/01_concepts.md new file mode 100644 index 0000000000..2c7e5f594e --- /dev/null +++ b/x/consortium/spec/01_concepts.md @@ -0,0 +1,56 @@ + + +# Concepts + +## Authorization + +The consortium module is designed to contain the authorization information. The other modules may deny its message based on the information of the consortium. As of now, the following modules are using the information: + +- **[Staking Plus](../../stakingplus/spec/README.md)** + - [Msg/CreateValidator](../../stakingplus/spec/03_messages.md#msgcreatevalidator) + +One can update the authorization, via proposals: + +- `UpdateValidatorAuthsProposal` to authorize `Msg/CreateValidator` + + +++ https://github.com/line/lbm-sdk/blob/v0.44.0-rc0/proto/lbm/consortium/v1/consortium.proto#L31-L40 + ```go + // UpdateValidatorAuthsProposal details a proposal to update validator auths on consortium. + message UpdateValidatorAuthsProposal { + option (gogoproto.equal) = false; + option (gogoproto.goproto_getters) = false; + option (gogoproto.goproto_stringer) = false; + + string title = 1; + string description = 2; + repeated ValidatorAuth auths = 3 [(gogoproto.moretags) = "yaml:\"auths\""]; + } + ``` + +## Disable the module + +One can disable the consortium module via `UpdateConsortiumParamsProposal`, setting its `params.enabled` to `false`. This process is irreversible, so one cannot re-enable the module. + ++++ https://github.com/line/lbm-sdk/blob/v0.44.0-rc0/proto/lbm/consortium/v1/consortium.proto#L20-L29 +```go +// UpdateConsortiumParamsProposal details a proposal to update params of cosortium module. +message UpdateConsortiumParamsProposal { + option (gogoproto.equal) = false; + option (gogoproto.goproto_getters) = false; + option (gogoproto.goproto_stringer) = false; + + string title = 1; + string description = 2; + Params params = 3; +} +``` + ++++ https://github.com/line/lbm-sdk/blob/v0.44.0-rc0/proto/lbm/consortium/v1/consortium.proto#L9-L12 +```go +// Params defines the parameters for the consortium module. +message Params { + bool enabled = 1 [(gogoproto.moretags) = "yaml:\"enabled\""]; +} +``` diff --git a/x/consortium/spec/02_state.md b/x/consortium/spec/02_state.md new file mode 100644 index 0000000000..25455d5dec --- /dev/null +++ b/x/consortium/spec/02_state.md @@ -0,0 +1,36 @@ + + +# State + +## Params + +As of now, the only parameter is on/off of the module. After turning off the module, the changes (might be breaking changes) applied on the other modules would not work, and the module cleans up its state. + +- Params: `0x00 -> PropocolBuffer(Params)` + ++++ https://github.com/line/lbm-sdk/blob/v0.44.0-rc0/proto/lbm/consortium/v1/consortium.proto#L9-L12 +```go +// Params defines the parameters for the consortium module. +message Params { + bool enabled = 1 [(gogoproto.moretags) = "yaml:\"enabled\""]; +} +``` + +## ValidatorAuth + +An operator must have been authorized before creating its validator node. `ValidatorAuth`s contain the authorization on the operators. One can authorize itself or other operator by the corresponding proposal, `lbm/consortium/v1/UpdateValidatorAuthsProposal`. + +Note that if the chain starts with an empty list of it in the genesis, the module authorizes all the operators included in the list of validators, read from the staking module. + +- ValidatorAuth: `0x01 -> ProtocolBuffer(ValidatorAuth)` + ++++ https://github.com/line/lbm-sdk/blob/v0.44.0-rc0/proto/lbm/consortium/v1/consortium.proto#L14-L18 +```go +// ValidatorAuth defines authorization info of a validator. +message ValidatorAuth { + string operator_address = 1 [(gogoproto.moretags) = "yaml:\"operator_address\""]; + bool creation_allowed = 2 [(gogoproto.moretags) = "yaml:\"creation_allowed\""]; +} +``` diff --git a/x/consortium/spec/03_events.md b/x/consortium/spec/03_events.md new file mode 100644 index 0000000000..84efcddbb0 --- /dev/null +++ b/x/consortium/spec/03_events.md @@ -0,0 +1,7 @@ + + +# Events + +The consortium module emits proto events defined in the Protobuf reference. TODO: use buf schema registry. diff --git a/x/consortium/spec/04_params.md b/x/consortium/spec/04_params.md new file mode 100644 index 0000000000..dc8e4c192c --- /dev/null +++ b/x/consortium/spec/04_params.md @@ -0,0 +1,13 @@ + + +# Parameters + +The consortium module contains the following parameters: + +| Key | Type | Example | +| ------- | ---- | --------- | +| enabled | bool | false [0] | + +* [0] The value of `enabled` cannot be switched from false to true. diff --git a/x/consortium/spec/README.md b/x/consortium/spec/README.md new file mode 100644 index 0000000000..fc261a83e8 --- /dev/null +++ b/x/consortium/spec/README.md @@ -0,0 +1,19 @@ + + +# `consortium` + +## Overview + +This module provides the functionalities related to the consortium. Also, one can turn off these functionalities irreversibly, through the corresponding proposal. Therefore, the users can ensure that no one can bring back these consortium-specific functionalities. + +## Contents + +1. **[Concepts](01_concepts.md)** +2. **[State](02_state.md)** +3. **[Events](03_events.md)** +4. **[Parameters](04_params.md)**