Skip to content

Commit

Permalink
Refine OpenGov doc (#5513)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>

* Update docs/learn/learn-polkadot-opengov.md

Co-authored-by: Filippo <[email protected]>

* Update docs/learn/learn-polkadot-opengov.md

Co-authored-by: Filippo <[email protected]>

* Update docs/learn/learn-polkadot-opengov.md

Co-authored-by: Filippo <[email protected]>

* apply filippo's feedback

---------

Co-authored-by: Filippo <[email protected]>
  • Loading branch information
@DrW3RK @filippoweb3
DrW3RK and filippoweb3 authored Jan 18, 2024
1 parent f8ae1ad commit 747be27
Showing 1 changed file with 107 additions and 92 deletions.
199 changes: 107 additions & 92 deletions docs/learn/learn-polkadot-opengov.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<VLTable />

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: <RPC network="kusama" path="consts.convictionVoting.voteLockingPeriod" defaultValue={100800} filter="blocksToDays"/> :polkadot }}
{{ kusama: <RPC network="kusama" path="consts.convictionVoting.voteLockingPeriod" defaultValue={100800} filter="blocksToDays"/> :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
Expand All @@ -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
Expand All @@ -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)

Expand All @@ -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

Expand All @@ -406,16 +494,17 @@ 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

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

Expand All @@ -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.

<VLTable />

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: <RPC network="kusama" path="consts.convictionVoting.voteLockingPeriod" defaultValue={100800} filter="blocksToDays"/> :polkadot }}
{{ kusama: <RPC network="kusama" path="consts.convictionVoting.voteLockingPeriod" defaultValue={100800} filter="blocksToDays"/> :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

Expand Down

0 comments on commit 747be27

Please sign in to comment.