From 9da011d21bcd93025066adca19733ad0cc096a3f Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 00:18:49 +0000 Subject: [PATCH 01/13] docs: add params.md --- x/consortium/spec/07_params.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 x/consortium/spec/07_params.md diff --git a/x/consortium/spec/07_params.md b/x/consortium/spec/07_params.md new file mode 100644 index 0000000000..8a80945738 --- /dev/null +++ b/x/consortium/spec/07_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. From 86a47fe6b5762eb0b8a408cfd59eb347084d8228 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 01:51:00 +0000 Subject: [PATCH 02/13] docs: add events.md --- x/consortium/spec/06_events.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 x/consortium/spec/06_events.md diff --git a/x/consortium/spec/06_events.md b/x/consortium/spec/06_events.md new file mode 100644 index 0000000000..99ab8ded1b --- /dev/null +++ b/x/consortium/spec/06_events.md @@ -0,0 +1,7 @@ + + +# Events + +The consortium module emits proto events defined in the Protobuf reference. TODO: use buf schema registry. From 1fca0f2726a17e281b0a5450c92a9bfff60042a0 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 07:32:30 +0000 Subject: [PATCH 03/13] docs: rename documents --- x/consortium/spec/{06_events.md => 03_events.md} | 0 x/consortium/spec/{07_params.md => 04_params.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename x/consortium/spec/{06_events.md => 03_events.md} (100%) rename x/consortium/spec/{07_params.md => 04_params.md} (100%) diff --git a/x/consortium/spec/06_events.md b/x/consortium/spec/03_events.md similarity index 100% rename from x/consortium/spec/06_events.md rename to x/consortium/spec/03_events.md diff --git a/x/consortium/spec/07_params.md b/x/consortium/spec/04_params.md similarity index 100% rename from x/consortium/spec/07_params.md rename to x/consortium/spec/04_params.md From 793771c22ec6c26e78d3762179cf15b68505a933 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 07:35:00 +0000 Subject: [PATCH 04/13] docs: add README.md --- x/consortium/spec/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 x/consortium/spec/README.md diff --git a/x/consortium/spec/README.md b/x/consortium/spec/README.md new file mode 100644 index 0000000000..3c52e5fae4 --- /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 the functionalities irreversibly, through the corresponding proposal. Therefore, the users can ensure that no one 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)** From 0a4fbaf4380bb199206995080f518424c02d7611 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 08:06:42 +0000 Subject: [PATCH 05/13] docs: add state.md --- x/consortium/spec/02_state.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 x/consortium/spec/02_state.md diff --git a/x/consortium/spec/02_state.md b/x/consortium/spec/02_state.md new file mode 100644 index 0000000000..be25e024b9 --- /dev/null +++ b/x/consortium/spec/02_state.md @@ -0,0 +1,23 @@ + + +# 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 + +## 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 From 10c3b95d36a81d49ae40914e8f5e1d3ae3399698 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 08:09:31 +0000 Subject: [PATCH 06/13] docs: rename the files and modify the orders --- x/consortium/spec/03_events.md | 2 +- x/consortium/spec/04_params.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/x/consortium/spec/03_events.md b/x/consortium/spec/03_events.md index 99ab8ded1b..84efcddbb0 100644 --- a/x/consortium/spec/03_events.md +++ b/x/consortium/spec/03_events.md @@ -1,5 +1,5 @@ # Events diff --git a/x/consortium/spec/04_params.md b/x/consortium/spec/04_params.md index 8a80945738..dc8e4c192c 100644 --- a/x/consortium/spec/04_params.md +++ b/x/consortium/spec/04_params.md @@ -1,5 +1,5 @@ # Parameters From 8a1c51fa8ac8c42a00f3415aeb2823613b29ed94 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 08:53:06 +0000 Subject: [PATCH 07/13] docs: add concepts.md --- x/consortium/spec/01_concepts.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 x/consortium/spec/01_concepts.md diff --git a/x/consortium/spec/01_concepts.md b/x/consortium/spec/01_concepts.md new file mode 100644 index 0000000000..69fd23034c --- /dev/null +++ b/x/consortium/spec/01_concepts.md @@ -0,0 +1,25 @@ + + +# 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 + +## Shutdown + +One can shutdown 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 ++++ https://github.com/line/lbm-sdk/blob/v0.44.0-rc0/proto/lbm/consortium/v1/consortium.proto#L9-L12 From 3713d37d807e855c6c301ae0d3e00abb297ae52f Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 08:59:46 +0000 Subject: [PATCH 08/13] docs: typo --- x/consortium/spec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/consortium/spec/README.md b/x/consortium/spec/README.md index 3c52e5fae4..fc261a83e8 100644 --- a/x/consortium/spec/README.md +++ b/x/consortium/spec/README.md @@ -9,7 +9,7 @@ parent: ## Overview -This module provides the functionalities related to the consortium. Also, one can turn off the functionalities irreversibly, through the corresponding proposal. Therefore, the users can ensure that no one bring back these consortium-specific functionalities. +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 From db8292c3c9880f09ae8d012c61107aca0db3fae4 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 09:03:04 +0000 Subject: [PATCH 09/13] docs: insert codes --- x/consortium/spec/01_concepts.md | 33 +++++++++++++++++++++++++++++++- x/consortium/spec/02_state.md | 13 +++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/x/consortium/spec/01_concepts.md b/x/consortium/spec/01_concepts.md index 69fd23034c..eca39edde4 100644 --- a/x/consortium/spec/01_concepts.md +++ b/x/consortium/spec/01_concepts.md @@ -15,11 +15,42 @@ 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 + +++ 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\""]; + } + ``` ## Shutdown One can shutdown 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 index be25e024b9..25455d5dec 100644 --- a/x/consortium/spec/02_state.md +++ b/x/consortium/spec/02_state.md @@ -11,6 +11,12 @@ As of now, the only parameter is on/off of the module. After turning off the mod - 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 @@ -21,3 +27,10 @@ Note that if the chain starts with an empty list of it in the genesis, the modul - 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\""]; +} +``` From 3e62cc2ef6494dbf1532b8ab957378bd2c954809 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 09:15:57 +0000 Subject: [PATCH 10/13] docs: update CHANGELOG.md --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b5ad3db45..06327dcb0f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -54,3 +54,5 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (ci) [\#469](https://github.com/line/lbm-sdk/pull/469) publish docker image on tag push ### Document Updates + +* (docs) [\#490](https://github.com/line/lbm-sdk/pull/490) update documents on x/consortium From a6d2155d3b7d383cf3547e4218f21d53873ef256 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Wed, 30 Mar 2022 09:38:41 +0000 Subject: [PATCH 11/13] docs: add an entry to the common README.md --- x/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/x/README.md b/x/README.md index 3be56a3de6..7645f6f15c 100644 --- a/x/README.md +++ b/x/README.md @@ -10,6 +10,7 @@ Here are some production-grade modules that can be used in Cosmos SDK applicatio - [Auth](auth/spec/README.md) - Authentication of accounts and transactions for Cosmos SDK application. - [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. From a4488a1a10f3b10677f7b4720f69dcb729ae50c3 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Thu, 7 Apr 2022 08:04:02 +0900 Subject: [PATCH 12/13] Update x/consortium/spec/01_concepts.md Co-authored-by: zemyblue --- x/consortium/spec/01_concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/consortium/spec/01_concepts.md b/x/consortium/spec/01_concepts.md index eca39edde4..2b2b9b6f6b 100644 --- a/x/consortium/spec/01_concepts.md +++ b/x/consortium/spec/01_concepts.md @@ -29,7 +29,7 @@ One can update the authorization, via proposals: } ``` -## Shutdown +## Disable the module One can shutdown the consortium module via `UpdateConsortiumParamsProposal`, setting its `params.enabled` to `false`. This process is irreversible, so one cannot re-enable the module. From e67608a8c88eb9e2614253022e6857583505d10a Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Thu, 7 Apr 2022 08:04:11 +0900 Subject: [PATCH 13/13] Update x/consortium/spec/01_concepts.md --- x/consortium/spec/01_concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/consortium/spec/01_concepts.md b/x/consortium/spec/01_concepts.md index 2b2b9b6f6b..2c7e5f594e 100644 --- a/x/consortium/spec/01_concepts.md +++ b/x/consortium/spec/01_concepts.md @@ -31,7 +31,7 @@ One can update the authorization, via proposals: ## Disable the module -One can shutdown the consortium module via `UpdateConsortiumParamsProposal`, setting its `params.enabled` to `false`. This process is irreversible, so one cannot re-enable 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