From 41559c02928d1eb4ccb751eb0261f8247f1e9cfe Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:29:50 +0000 Subject: [PATCH 01/11] docs: add documents on staking plus module --- x/stakingplus/spec/01_state.md | 7 ++++++ x/stakingplus/spec/02_state_transitions.md | 7 ++++++ x/stakingplus/spec/03_messages.md | 22 ++++++++++++++++ x/stakingplus/spec/04_begin_block.md | 7 ++++++ x/stakingplus/spec/05_end_block.md | 7 ++++++ x/stakingplus/spec/06_hooks.md | 7 ++++++ x/stakingplus/spec/07_events.md | 7 ++++++ x/stakingplus/spec/08_params.md | 7 ++++++ x/stakingplus/spec/README.md | 29 ++++++++++++++++++++++ 9 files changed, 100 insertions(+) create mode 100644 x/stakingplus/spec/01_state.md create mode 100644 x/stakingplus/spec/02_state_transitions.md create mode 100644 x/stakingplus/spec/03_messages.md create mode 100644 x/stakingplus/spec/04_begin_block.md create mode 100644 x/stakingplus/spec/05_end_block.md create mode 100644 x/stakingplus/spec/06_hooks.md create mode 100644 x/stakingplus/spec/07_events.md create mode 100644 x/stakingplus/spec/08_params.md create mode 100644 x/stakingplus/spec/README.md diff --git a/x/stakingplus/spec/01_state.md b/x/stakingplus/spec/01_state.md new file mode 100644 index 0000000000..20c5d795f6 --- /dev/null +++ b/x/stakingplus/spec/01_state.md @@ -0,0 +1,7 @@ + + +# State + +There is no difference in state with that of Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/01_state.md) for more information. diff --git a/x/stakingplus/spec/02_state_transitions.md b/x/stakingplus/spec/02_state_transitions.md new file mode 100644 index 0000000000..8c970a7a41 --- /dev/null +++ b/x/stakingplus/spec/02_state_transitions.md @@ -0,0 +1,7 @@ + + +# State Transitions + +There is no difference in state trasitions with that of Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/02_state_transitions.md) for more information. diff --git a/x/stakingplus/spec/03_messages.md b/x/stakingplus/spec/03_messages.md new file mode 100644 index 0000000000..6dc4e5ba32 --- /dev/null +++ b/x/stakingplus/spec/03_messages.md @@ -0,0 +1,22 @@ + + +# Messages + +In this section we describe only the changes introduced by LBM-SDK. Refer to the [original document](../../staking/03_messages.md) for more information. + +## Msg/CreateValidator + +A validator is created using the `Msg/CreateValidator` service message. + ++++ https://github.com/line/lbm-sdk/blob/main/proto/lbm/staking/v1/tx.proto#L16-L17 + ++++ https://github.com/line/lbm-sdk/blob/main/proto/lbm/staking/v1/tx.proto#L36-L51 + +This service message is expected to fail if: + +- one of the conditions described in the staking module of the Cosmos-SDK is met. +- the operator address is not registered on x/foundation through the corresponding proposal. + +The other [statements](../../staking/03_messages.md#Msg/CreateValidator) on this message in the exising document are still valid. diff --git a/x/stakingplus/spec/04_begin_block.md b/x/stakingplus/spec/04_begin_block.md new file mode 100644 index 0000000000..015d30d8a9 --- /dev/null +++ b/x/stakingplus/spec/04_begin_block.md @@ -0,0 +1,7 @@ + + +# Begin-Block + +There is no difference in begin-block with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/04_begin_block.md) for more information. diff --git a/x/stakingplus/spec/05_end_block.md b/x/stakingplus/spec/05_end_block.md new file mode 100644 index 0000000000..6d0c28330c --- /dev/null +++ b/x/stakingplus/spec/05_end_block.md @@ -0,0 +1,7 @@ + + +# End-Block + +There is no difference in end-block with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/05_end_block.md) for more information. diff --git a/x/stakingplus/spec/06_hooks.md b/x/stakingplus/spec/06_hooks.md new file mode 100644 index 0000000000..f17db5ddf7 --- /dev/null +++ b/x/stakingplus/spec/06_hooks.md @@ -0,0 +1,7 @@ + + +# Hooks + +There is no difference in hooks with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/06_hooks.md) for more information. diff --git a/x/stakingplus/spec/07_events.md b/x/stakingplus/spec/07_events.md new file mode 100644 index 0000000000..d7315815e7 --- /dev/null +++ b/x/stakingplus/spec/07_events.md @@ -0,0 +1,7 @@ + + +# Events + +There is no difference in events with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/07_events.md) for more information. diff --git a/x/stakingplus/spec/08_params.md b/x/stakingplus/spec/08_params.md new file mode 100644 index 0000000000..d30578370b --- /dev/null +++ b/x/stakingplus/spec/08_params.md @@ -0,0 +1,7 @@ + + +# Parameters + +There is no difference in parameters with that Staking module of the Cosmos-SDK. Refer to the [original document](../staking/08_params.md) for more information. diff --git a/x/stakingplus/spec/README.md b/x/stakingplus/spec/README.md new file mode 100644 index 0000000000..11b3ab0e11 --- /dev/null +++ b/x/stakingplus/spec/README.md @@ -0,0 +1,29 @@ + + +# `stakingplus` + +## Abstract + +This paper specifies the Staking Plus module of the LBM-SDK, which extends existing [Staking module](../../staking/README.md) of the Cosmos-SDK. + +The module enables LBM-SDK based blockchain to support an advanced Proof-of-Stake system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system. + +This module is almost identical to the previous Staking module of the Cosmos-SDK, but introduces some breaking changes. For example, you must have x/foundation GrantProposal passed before sending x/stakingplus MsgCreateValidator, or the message would fail. + +## Contents + +1. **[State](01_state.md)** +2. **[State Transitions](02_state_transitions.md)** +3. **[Messages](03_messages.md)** + - [Msg/CreateValidator](03_messages.md#msgcreatevalidator) +4. **[Begin-Block](04_begin_block.md)** +5. **[End-Block ](05_end_block.md)** +6. **[Hooks](06_hooks.md)** +7. **[Events](07_events.md)** + - [Handlers](07_events.md#handlers) +8. **[Parameters](08_params.md)** From 744a15846522505396c7de13e856fb205c09284d Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:32:17 +0000 Subject: [PATCH 02/11] 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..66b47fc3e2 100644 --- a/x/README.md +++ b/x/README.md @@ -20,6 +20,7 @@ Here are some production-grade modules that can be used in Cosmos SDK applicatio - [Params](params/spec/README.md) - Globally available parameter store. - [Slashing](slashing/spec/README.md) - Validator punishment mechanisms. - [Staking](staking/spec/README.md) - Proof-of-Stake layer for public blockchains. +- [Staking Plus](stakingplus/spec/README.md) - Modified version of staking. - [Upgrade](upgrade/spec/README.md) - Software upgrades handling and coordination. To learn more about the process of building modules, visit the [building modules reference documentation](../docs/building-modules/README.md). From 84b93ea5cfce99c0226f7220b294a161c0cf529c Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:35:09 +0000 Subject: [PATCH 03/11] docs: fix documentation paths --- x/stakingplus/spec/01_state.md | 2 +- x/stakingplus/spec/02_state_transitions.md | 2 +- x/stakingplus/spec/03_messages.md | 4 ++-- x/stakingplus/spec/04_begin_block.md | 2 +- x/stakingplus/spec/05_end_block.md | 2 +- x/stakingplus/spec/06_hooks.md | 2 +- x/stakingplus/spec/07_events.md | 2 +- x/stakingplus/spec/08_params.md | 2 +- x/stakingplus/spec/README.md | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/x/stakingplus/spec/01_state.md b/x/stakingplus/spec/01_state.md index 20c5d795f6..2964f3268f 100644 --- a/x/stakingplus/spec/01_state.md +++ b/x/stakingplus/spec/01_state.md @@ -4,4 +4,4 @@ order: 1 # State -There is no difference in state with that of Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/01_state.md) for more information. +There is no difference in state with that of Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/spec/01_state.md) for more information. diff --git a/x/stakingplus/spec/02_state_transitions.md b/x/stakingplus/spec/02_state_transitions.md index 8c970a7a41..67d4722346 100644 --- a/x/stakingplus/spec/02_state_transitions.md +++ b/x/stakingplus/spec/02_state_transitions.md @@ -4,4 +4,4 @@ order: 2 # State Transitions -There is no difference in state trasitions with that of Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/02_state_transitions.md) for more information. +There is no difference in state trasitions with that of Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/spec/02_state_transitions.md) for more information. diff --git a/x/stakingplus/spec/03_messages.md b/x/stakingplus/spec/03_messages.md index 6dc4e5ba32..e04aebdaf6 100644 --- a/x/stakingplus/spec/03_messages.md +++ b/x/stakingplus/spec/03_messages.md @@ -4,7 +4,7 @@ order: 3 # Messages -In this section we describe only the changes introduced by LBM-SDK. Refer to the [original document](../../staking/03_messages.md) for more information. +In this section we describe only the changes introduced by LBM-SDK. Refer to the [original document](../../staking/spec/03_messages.md) for more information. ## Msg/CreateValidator @@ -19,4 +19,4 @@ This service message is expected to fail if: - one of the conditions described in the staking module of the Cosmos-SDK is met. - the operator address is not registered on x/foundation through the corresponding proposal. -The other [statements](../../staking/03_messages.md#Msg/CreateValidator) on this message in the exising document are still valid. +The other [statements](../../staking/spec/03_messages.md#Msg/CreateValidator) on this message in the exising document are still valid. diff --git a/x/stakingplus/spec/04_begin_block.md b/x/stakingplus/spec/04_begin_block.md index 015d30d8a9..e18353b6c7 100644 --- a/x/stakingplus/spec/04_begin_block.md +++ b/x/stakingplus/spec/04_begin_block.md @@ -4,4 +4,4 @@ order: 4 # Begin-Block -There is no difference in begin-block with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/04_begin_block.md) for more information. +There is no difference in begin-block with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/spec/04_begin_block.md) for more information. diff --git a/x/stakingplus/spec/05_end_block.md b/x/stakingplus/spec/05_end_block.md index 6d0c28330c..8742811019 100644 --- a/x/stakingplus/spec/05_end_block.md +++ b/x/stakingplus/spec/05_end_block.md @@ -4,4 +4,4 @@ order: 4 # End-Block -There is no difference in end-block with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/05_end_block.md) for more information. +There is no difference in end-block with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/spec/05_end_block.md) for more information. diff --git a/x/stakingplus/spec/06_hooks.md b/x/stakingplus/spec/06_hooks.md index f17db5ddf7..f0ddd0630e 100644 --- a/x/stakingplus/spec/06_hooks.md +++ b/x/stakingplus/spec/06_hooks.md @@ -4,4 +4,4 @@ order: 5 # Hooks -There is no difference in hooks with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/06_hooks.md) for more information. +There is no difference in hooks with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/spec/06_hooks.md) for more information. diff --git a/x/stakingplus/spec/07_events.md b/x/stakingplus/spec/07_events.md index d7315815e7..e533db8391 100644 --- a/x/stakingplus/spec/07_events.md +++ b/x/stakingplus/spec/07_events.md @@ -4,4 +4,4 @@ order: 6 # Events -There is no difference in events with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/07_events.md) for more information. +There is no difference in events with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/spec/07_events.md) for more information. diff --git a/x/stakingplus/spec/08_params.md b/x/stakingplus/spec/08_params.md index d30578370b..212a7fb1f5 100644 --- a/x/stakingplus/spec/08_params.md +++ b/x/stakingplus/spec/08_params.md @@ -4,4 +4,4 @@ order: 8 # Parameters -There is no difference in parameters with that Staking module of the Cosmos-SDK. Refer to the [original document](../staking/08_params.md) for more information. +There is no difference in parameters with that Staking module of the Cosmos-SDK. Refer to the [original document](../staking/spec/08_params.md) for more information. diff --git a/x/stakingplus/spec/README.md b/x/stakingplus/spec/README.md index 11b3ab0e11..1a186c483f 100644 --- a/x/stakingplus/spec/README.md +++ b/x/stakingplus/spec/README.md @@ -9,7 +9,7 @@ parent: ## Abstract -This paper specifies the Staking Plus module of the LBM-SDK, which extends existing [Staking module](../../staking/README.md) of the Cosmos-SDK. +This paper specifies the Staking Plus module of the LBM-SDK, which extends existing [Staking module](../../staking/spec/README.md) of the Cosmos-SDK. The module enables LBM-SDK based blockchain to support an advanced Proof-of-Stake system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system. From 15ecca5544f72154b4dcca6224ac87a0fb1256a8 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:36:30 +0000 Subject: [PATCH 04/11] docs: use legacy proposal on the documents --- x/stakingplus/spec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/stakingplus/spec/README.md b/x/stakingplus/spec/README.md index 1a186c483f..a886397660 100644 --- a/x/stakingplus/spec/README.md +++ b/x/stakingplus/spec/README.md @@ -13,7 +13,7 @@ This paper specifies the Staking Plus module of the LBM-SDK, which extends exist The module enables LBM-SDK based blockchain to support an advanced Proof-of-Stake system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system. -This module is almost identical to the previous Staking module of the Cosmos-SDK, but introduces some breaking changes. For example, you must have x/foundation GrantProposal passed before sending x/stakingplus MsgCreateValidator, or the message would fail. +This module is almost identical to the previous Staking module of the Cosmos-SDK, but introduces some breaking changes. For example, you must have x/consortium UpdateValidatorAuthsProposal passed before sending x/stakingplus MsgCreateValidator, or the message would fail. ## Contents From 62022d756e7556f45a806ebb1fc7010c63330e4d Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:38:54 +0000 Subject: [PATCH 05/11] docs: update code lines --- x/stakingplus/spec/03_messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/stakingplus/spec/03_messages.md b/x/stakingplus/spec/03_messages.md index e04aebdaf6..b9b0790fd1 100644 --- a/x/stakingplus/spec/03_messages.md +++ b/x/stakingplus/spec/03_messages.md @@ -12,7 +12,7 @@ A validator is created using the `Msg/CreateValidator` service message. +++ https://github.com/line/lbm-sdk/blob/main/proto/lbm/staking/v1/tx.proto#L16-L17 -+++ https://github.com/line/lbm-sdk/blob/main/proto/lbm/staking/v1/tx.proto#L36-L51 ++++ https://github.com/line/lbm-sdk/blob/main/proto/lbm/staking/v1/tx.proto#L35-L51 This service message is expected to fail if: From 6ea5edc4dc02bfee360bbd758dba4d89cf2a91db Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:41:10 +0000 Subject: [PATCH 06/11] docs: remove an entry "handlers" from README.md --- x/stakingplus/spec/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/x/stakingplus/spec/README.md b/x/stakingplus/spec/README.md index a886397660..9ba410c263 100644 --- a/x/stakingplus/spec/README.md +++ b/x/stakingplus/spec/README.md @@ -25,5 +25,4 @@ This module is almost identical to the previous Staking module of the Cosmos-SDK 5. **[End-Block ](05_end_block.md)** 6. **[Hooks](06_hooks.md)** 7. **[Events](07_events.md)** - - [Handlers](07_events.md#handlers) 8. **[Parameters](08_params.md)** From af1f0a431e7b2888138d0ea2ddf7d853ef8a710c Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:41:54 +0000 Subject: [PATCH 07/11] docs: fix the documentation path --- x/stakingplus/spec/08_params.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/stakingplus/spec/08_params.md b/x/stakingplus/spec/08_params.md index 212a7fb1f5..0277fb605c 100644 --- a/x/stakingplus/spec/08_params.md +++ b/x/stakingplus/spec/08_params.md @@ -4,4 +4,4 @@ order: 8 # Parameters -There is no difference in parameters with that Staking module of the Cosmos-SDK. Refer to the [original document](../staking/spec/08_params.md) for more information. +There is no difference in parameters with that Staking module of the Cosmos-SDK. Refer to the [original document](../../staking/spec/08_params.md) for more information. From a6863c481f493f354055c741543294c626c65f79 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:45:23 +0000 Subject: [PATCH 08/11] docs: use the legacy module name --- x/stakingplus/spec/03_messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/stakingplus/spec/03_messages.md b/x/stakingplus/spec/03_messages.md index b9b0790fd1..2f81240c04 100644 --- a/x/stakingplus/spec/03_messages.md +++ b/x/stakingplus/spec/03_messages.md @@ -17,6 +17,6 @@ A validator is created using the `Msg/CreateValidator` service message. This service message is expected to fail if: - one of the conditions described in the staking module of the Cosmos-SDK is met. -- the operator address is not registered on x/foundation through the corresponding proposal. +- the operator address is not registered on x/consortium through the corresponding proposal. The other [statements](../../staking/spec/03_messages.md#Msg/CreateValidator) on this message in the exising document are still valid. From bdd04fdbea6ab1c1d56c802c301cd23ea0754696 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:47:22 +0000 Subject: [PATCH 09/11] docs: use the proposal name --- x/stakingplus/spec/03_messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/stakingplus/spec/03_messages.md b/x/stakingplus/spec/03_messages.md index 2f81240c04..4918946360 100644 --- a/x/stakingplus/spec/03_messages.md +++ b/x/stakingplus/spec/03_messages.md @@ -17,6 +17,6 @@ A validator is created using the `Msg/CreateValidator` service message. This service message is expected to fail if: - one of the conditions described in the staking module of the Cosmos-SDK is met. -- the operator address is not registered on x/consortium through the corresponding proposal. +- the operator address is not registered on x/consortium through UpdateValidatorAuthsProposal. TODO: add a ref to x/consortium spec file. The other [statements](../../staking/spec/03_messages.md#Msg/CreateValidator) on this message in the exising document are still valid. From 8158a0a55e2cd2abf13e687c11d3a87d6fae510a Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:50:04 +0000 Subject: [PATCH 10/11] docs: fix a ref --- x/stakingplus/spec/03_messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/stakingplus/spec/03_messages.md b/x/stakingplus/spec/03_messages.md index 4918946360..1f816feefd 100644 --- a/x/stakingplus/spec/03_messages.md +++ b/x/stakingplus/spec/03_messages.md @@ -19,4 +19,4 @@ This service message is expected to fail if: - one of the conditions described in the staking module of the Cosmos-SDK is met. - the operator address is not registered on x/consortium through UpdateValidatorAuthsProposal. TODO: add a ref to x/consortium spec file. -The other [statements](../../staking/spec/03_messages.md#Msg/CreateValidator) on this message in the exising document are still valid. +The other [statements](../../staking/spec/03_messages.md#msgcreatevalidator) on this message in the exising document are still valid. From 49c2590f1fb1f8c4595f58973c62e806fa522241 Mon Sep 17 00:00:00 2001 From: Youngtaek Yoon Date: Tue, 29 Mar 2022 02:55:39 +0000 Subject: [PATCH 11/11] docs: update CHANGELOG.md --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10bc105abe..d59383e1c2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,3 +53,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) [\#483](https://github.com/line/lbm-sdk/pull/483) update documents on x/stakingplus