From 747be271557ce33f7ae75e9a6097cd91384148b0 Mon Sep 17 00:00:00 2001 From: Radha <86818441+DrW3RK@users.noreply.github.com> Date: Thu, 18 Jan 2024 22:24:13 +0800 Subject: [PATCH] Refine OpenGov doc (#5513) * Refine OpenGov doc * Move conviction voting section before Approval/Support section * Add a simple example to compute Approval and Support * Update docs/learn/learn-polkadot-opengov.md Co-authored-by: Filippo <110459737+filippoweb3@users.noreply.github.com> * Update docs/learn/learn-polkadot-opengov.md Co-authored-by: Filippo <110459737+filippoweb3@users.noreply.github.com> * Update docs/learn/learn-polkadot-opengov.md Co-authored-by: Filippo <110459737+filippoweb3@users.noreply.github.com> * Update docs/learn/learn-polkadot-opengov.md Co-authored-by: Filippo <110459737+filippoweb3@users.noreply.github.com> * apply filippo's feedback --------- Co-authored-by: Filippo <110459737+filippoweb3@users.noreply.github.com> --- docs/learn/learn-polkadot-opengov.md | 199 ++++++++++++++------------- 1 file changed, 107 insertions(+), 92 deletions(-) diff --git a/docs/learn/learn-polkadot-opengov.md b/docs/learn/learn-polkadot-opengov.md index dbd10c282f6b..bff30b3af3d2 100644 --- a/docs/learn/learn-polkadot-opengov.md +++ b/docs/learn/learn-polkadot-opengov.md @@ -328,6 +328,82 @@ approval, and a minimum [enactment](#enactment) periods will be predetermined on For detailed information about origin and tracks, and parameter values in Kusama, see [this page](./learn-polkadot-opengov-origins.md#origins-and-tracks-info). +### Voluntary Locking (Conviction Voting) + +{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} utilizes an idea called voluntary +locking that allows token holders to increase their voting power by declaring how long they are +willing to lock up their tokens; hence, the number of votes for each token holder will be calculated +by the following formula: + +``` +votes = tokens * conviction_multiplier +``` + +The conviction multiplier increases the vote multiplier by one every time the number of lock periods +double. + + + +The maximum number of "doublings" of the lock period is set to 6 (and thus 32 lock periods in +total), and one lock period equals +{{ polkadot: :polkadot }} +{{ kusama: :kusama }} +days. For additional information regarding the timeline of governance events, check out the +governance section on the +{{ polkadot: [Polkadot Parameters page](maintain-polkadot-parameters/#governance) :polkadot }}{{ kusama: [Kusama Parameters page](kusama-parameters/#governance) :kusama }}. + +:::info do votes stack? + +You can use the same number of tokens to vote on different referenda. Votes with conviction do not +stack. If you voted with 5 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} on Referenda A, B +and C with 2x conviction you would have 10 votes on all those referenda and 5 +{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} locked up only for the 2x conviction period +(i.e. {{ polkadot: two weeks :polkadot }}{{ kusama: two weeks :kusama }}), with the unlocking +countdown starting when the last referendum you voted on ends (assuming you are on the winning +side). If you voted with conviction on referendum and then a week later voted on another one with +the same conviction, the lock on your {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} will be +extended by a week (always assuming you are on the winning side). + +::: + +:::info Staked tokens can be used in governance + +While a token is locked, you can still use it for voting and [staking](./learn-staking.md). You are +only prohibited from transferring these tokens to another account. + +::: + +Votes are always "counted" at the same time (at the end of the voting period), no matter for how +long the tokens are locked. + +See below an example that shows how voluntary locking works. + +Peter: Votes `No` with +{{ polkadot: 10 DOT for a 32-week :polkadot }}{{ kusama: 1 KSM for a 32-week :kusama }} lock period +=> {{ polkadot: 10 x 6 = 60 Votes :polkadot }}{{ kusama: 1 x 6 = 6 Votes :kusama }} + +Logan: Votes `Yes` with +{{ polkadot: 20 DOT for one week :polkadot }}{{ kusama: 2 KSM for one week :kusama }} lock period => +{{ polkadot: 20 x 1 = 20 Votes :polkadot }}{{ kusama: 2 x 1 = 2 Votes :kusama }} + +Kevin: Votes `Yes` with +{{ polkadot: 15 DOT for a 2-week :polkadot }}{{ kusama: 1.5 KSM for a 2-week :kusama }} lock period +=> {{ polkadot: 15 x 2 = 30 Votes :polkadot }}{{ kusama: 1.5 x 2 = 3 Votes :kusama }} + +Even though combined both Logan and Kevin vote with more +{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} than Peter, the lock period for both of them +is less than Peter, leading to their voting power counting as less. + +:::info Conviction Voting Locks created during Gov 1 + +Conviction voting locks in Governance v1 will not be carried over to OpenGov. Voting with conviction +in OpenGov will create a new lock (as this will use the `convictionVoting` pallet), while any +existing lock under Governance v1 (using the deprecated `democracy` pallet) will be left to expire. +Delegations under Governance v1 will need to be re-issued under OpenGov. + +::: + + ### Approval and Support :::info Adaptive Quorum Biasing is deprecated @@ -345,12 +421,26 @@ Decision Period. Once the proposal exits the Lead-in Period and enters the Voting Period, to be approved, it must satisfy the approval and support criteria for the **Confirmation Period**. -- **Approval** is defined as the share of approval (_aye_ votes) vote-weight (after adjustment for - [conviction](#voluntary-locking)) against the total vote-weight (_aye_, _nay_, and _abstained_). +- **Approval** is defined as the share of [conviction](#voluntary-locking)-weighted _aye_ votes + against the conviction-weighted total of _aye_ and _nay_ votes. The code implementation can be viewed + [here](https://github.com/paritytech/polkadot-sdk/blob/f2fbba3be1d7deaf7cfc731cea00552c212ddfcf/substrate/frame/conviction-voting/src/types.rs#L77) - **Support** is the total number of _aye_ and _abstain_ votes (ignoring any adjustment for conviction) compared to the total possible votes ([active issuance](learn-DOT.md#token-issuance)) that could be made in the system. In case of _split_ votes, only _aye_ and _abstain_ will count. +For example, let us consider a hypothetical example where the total active issuance is {{ polkadot: 100 DOT :polkadot }}{{ kusama: 100 KSM :kusama }} +- An account A votes "Aye" with 10 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} with 4x conviction +- An account B votes "Nay" with 5 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} with 2x conviction +- An account C votes "abstain" with 20 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. (no conviction can be applied on "abstain" votes) + +In this scenario, only 35 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} from the total active issuance participated in voting on the +referendum. Now, let us calculate the Approval and Support values for that referendum. + +- Approval is calculated as (Aye') / (Aye' + Nay') where "Aye'" and "Nay'" are the votes after +the conviction multiplier is applied. Hence, Approval = (10 x 4) / (10 x 4 + 5 x 2) = 40/50 which is 80%. +- Support is calculated as (Aye + Abstain) / (total active issuance), where "Aye" and "Abstain" are the votes without the conviction multiplier. + Hence, Support = (10 + 20) / 100 which is 30%. + :::info Nay votes are not counted towards Support Support is a measure of voters who turned out either in favor of the referenda and who consciously @@ -364,25 +454,25 @@ to consider _nay_ votes. ::: -The figure above shows the followings: +The figure above shows the following: - Even if the approval threshold is reached (i.e. % of current approval is greater than the approval curve), the proposal only enters the confirmation period once the support threshold is also reached (i.e. % current support is greater than the underlying support curve). -- If the referendum meets the criteria for the confirmation period, then the proposal is approved - and scheduled for enactment. The Enactment Period can be specified when the referendum is proposed - but is also subject to a minimum value based on the Track. More powerful Tracks enforce a larger +- If the referendum meets the approval and support thresholds for the duration of the confirmation period, the proposal will be approved + and will be scheduled for enactment. Each track has a default minimum Enactment Period and the approved referendum needs to wait + till the end of it to be executed. Powerful Tracks like `Root` enforce a larger Enactment Period to ensure the network has ample time to prepare for any changes the proposal may - bring. + bring. The referendum proposers can also choose to set the enactment period to be higher than its default value. - A referendum may exit the confirmation period when the thresholds are no longer met, due to new _Nay_ votes or a change of existing _Aye_ or _Abstain_ votes to _Nay_ . Each time it exits, the - confirmation period resets. For example, if the confirmation period is 20 minutes and a referendum - enters it just for 5 min, the next time it enters, it must stay for 20 minutes (not 15 minutes). + confirmation period clock is reset. For example, if the confirmation period is 20 minutes and a referendum + enters it just for 5 min before exiting, the next time it enters, it must be confirming for 20 minutes (not 15 minutes). - During the decision period, if a referendum fails to meet the approval and support thresholds for the duration of the track-specific confirmation period, it fails and does not go to the enactment period (it may have to be resubmitted, see below). -- The current approval must be above 50% for a referendum to pass, and the approval curve never goes - below 50%. +- The approval curve starts with a value of 100% and gradually goes to 50%, but never below. Assuming all the active + token supply has voted on a proposal, the conviction vote weighted support should at least always be above 50% to pass. ![opengov-curves-pass](../assets/opengov-curves-nopass.png) @@ -391,11 +481,9 @@ votes. Different Origins' tracks have different Confirmation Periods and requirements for approval and support. For additional details on the various origins and tracks, check out -[this table](./learn-polkadot-opengov-origins.md#origins-and-tracks-info). Configuring the amount of -support and overall approval required for it to pass is now possible. With proposals that use less +[this table](./learn-polkadot-opengov-origins.md#origins-and-tracks-info). With proposals that use less privileged origins, it is far more reasonable to drop the required support to a more realistic -amount earlier than those which use highly privileged classes such as `Root`. Classes with more -significance can be made to require higher approval early on, to avoid controversy. +amount earlier than those which use highly privileged classes such as `Root`. ### Enactment @@ -406,8 +494,8 @@ v1. ::: -In Polkadot OpenGov, the proposer suggests the enactment period, but there are also minimums set for -each Origin Track. For example, root Origin approvals require a more extended period because of the +In Polkadot OpenGov, the proposer suggests the enactment period, but there are also a minimum set for +each Origin Track. For example, `root` Origin approvals require an extended period because of the importance of the changes they bring to the network. ## Voting on a Referendum @@ -415,7 +503,8 @@ importance of the changes they bring to the network. In Governance V1, voters could cast only an _aye_ or _nay_ vote. In Polkadot OpenGov, voters can additionally cast a _abstain_ and _split_ votes. [Vote splitting](./learn-guides-polkadot-opengov.md#voting-on-referenda) allows voters to allocate -different votes for _aye_, _nay_, and _abstain_. +different votes for _aye_, _nay_, and _abstain_. Voting with conviction is not possible when +abstaining or splitting the votes. :::info Only the last vote counts @@ -431,80 +520,6 @@ Note that to successfully cast votes you need to have the [existential deposit](./learn-accounts.md#existential-deposit-and-reaping) and some additional funds to pay for transaction fees. -### Voluntary Locking - -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} utilizes an idea called voluntary -locking that allows token holders to increase their voting power by declaring how long they are -willing to lock up their tokens; hence, the number of votes for each token holder will be calculated -by the following formula: - -``` -votes = tokens * conviction_multiplier -``` - -The conviction multiplier increases the vote multiplier by one every time the number of lock periods -double. - - - -The maximum number of "doublings" of the lock period is set to 6 (and thus 32 lock periods in -total), and one lock period equals -{{ polkadot: :polkadot }} -{{ kusama: :kusama }} -days. For additional information regarding the timeline of governance events, check out the -governance section on the -{{ polkadot: [Polkadot Parameters page](maintain-polkadot-parameters/#governance) :polkadot }}{{ kusama: [Kusama Parameters page](kusama-parameters/#governance) :kusama }}. - -:::info do votes stack? - -You can use the same number of tokens to vote on different referenda. Votes with conviction do not -stack. If you voted with 5 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} on Referenda A, B -and C with 2x conviction you would have 10 votes on all those referenda and 5 -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} locked up only for the 2x conviction period -(i.e. {{ polkadot: two weeks :polkadot }}{{ kusama: two weeks :kusama }}), with the unlocking -countdown starting when the last referendum you voted on ends (assuming you are on the winning -side). If you voted with conviction on referendum and then a week later voted on another one with -the same conviction, the lock on your {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} will be -extended by a week (always assuming you are on the winning side). - -::: - -:::info Staked tokens can be used in governance - -While a token is locked, you can still use it for voting and [staking](./learn-staking.md). You are -only prohibited from transferring these tokens to another account. - -::: - -Votes are always "counted" at the same time (at the end of the voting period), no matter for how -long the tokens are locked. - -See below an example that shows how voluntary locking works. - -Peter: Votes `No` with -{{ polkadot: 10 DOT for a 32-week :polkadot }}{{ kusama: 1 KSM for a 32-week :kusama }} lock period -=> {{ polkadot: 10 x 6 = 60 Votes :polkadot }}{{ kusama: 1 x 6 = 6 Votes :kusama }} - -Logan: Votes `Yes` with -{{ polkadot: 20 DOT for one week :polkadot }}{{ kusama: 2 KSM for one week :kusama }} lock period => -{{ polkadot: 20 x 1 = 20 Votes :polkadot }}{{ kusama: 2 x 1 = 2 Votes :kusama }} - -Kevin: Votes `Yes` with -{{ polkadot: 15 DOT for a 2-week :polkadot }}{{ kusama: 1.5 KSM for a 2-week :kusama }} lock period -=> {{ polkadot: 15 x 2 = 30 Votes :polkadot }}{{ kusama: 1.5 x 2 = 3 Votes :kusama }} - -Even though combined both Logan and Kevin vote with more -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} than Peter, the lock period for both of them -is less than Peter, leading to their voting power counting as less. - -:::info Conviction Voting Locks created during Gov 1 - -Conviction voting locks in Governance v1 will not be carried over to OpenGov. Voting with conviction -in OpenGov will create a new lock (as this will use the `convictionVoting` pallet), while any -existing lock under Governance v1 (using the deprecated `democracy` pallet) will be left to expire. -Delegations under Governance v1 will need to be re-issued under OpenGov. - -::: ### Multirole Delegation