54 releases (major breaking)

38.0.0 Sep 26, 2024
37.0.0 Jul 18, 2024
36.0.0 Jul 12, 2024
35.0.0 Jun 24, 2024
2.0.0-alpha.5 Mar 24, 2020

#2 in #pallet

Download history 732/week @ 2024-08-26 502/week @ 2024-09-02 979/week @ 2024-09-09 1008/week @ 2024-09-16 1615/week @ 2024-09-23 1492/week @ 2024-09-30 857/week @ 2024-10-07 925/week @ 2024-10-14 1402/week @ 2024-10-21 1202/week @ 2024-10-28 1360/week @ 2024-11-04 21043/week @ 2024-11-11 25671/week @ 2024-11-18 28635/week @ 2024-11-25 23411/week @ 2024-12-02 28621/week @ 2024-12-09

107,606 downloads per month
Used in 24 crates (5 directly)

Apache-2.0

2.5MB
48K SLoC

Democracy Pallet

Overview

The Democracy pallet handles the administration of general stakeholder voting.

There are two different queues that a proposal can be added to before it becomes a referendum, 1) the proposal queue consisting of all public proposals and 2) the external queue consisting of a single proposal that originates from one of the external origins (such as a collective group).

Every launch period - a length defined in the runtime - the Democracy pallet launches a referendum from a proposal that it takes from either the proposal queue or the external queue in turn. Any token holder in the system can vote on referenda. The voting system uses time-lock voting by allowing the token holder to set their conviction behind a vote. The conviction will dictate the length of time the tokens will be locked, as well as the multiplier that scales the vote power.

Terminology

  • Enactment Period: The minimum period of locking and the period between a proposal being approved and enacted.
  • Lock Period: A period of time after proposal enactment that the tokens of winning voters will be locked.
  • Conviction: An indication of a voter's strength of belief in their vote. An increase of one in conviction indicates that a token holder is willing to lock their tokens for twice as many lock periods after enactment.
  • Vote: A value that can either be in approval ("Aye") or rejection ("Nay") of a particular referendum.
  • Proposal: A submission to the chain that represents an action that a proposer (either an account or an external origin) suggests that the system adopt.
  • Referendum: A proposal that is in the process of being voted on for either acceptance or rejection as a change to the system.
  • Delegation: The act of granting your voting power to the decisions of another account for up to a certain conviction.

Adaptive Quorum Biasing

A referendum can be either simple majority-carries in which 50%+1 of the votes decide the outcome or adaptive quorum biased. Adaptive quorum biasing makes the threshold for passing or rejecting a referendum higher or lower depending on how the referendum was originally proposed. There are two types of adaptive quorum biasing: 1) positive turnout bias makes a referendum require a super-majority to pass that decreases as turnout increases and 2) negative turnout bias makes a referendum require a super-majority to reject that decreases as turnout increases. Another way to think about the quorum biasing is that positive bias referendums will be rejected by default and negative bias referendums get passed by default.

Interface

Dispatchable Functions

Public

These calls can be made from any externally held account capable of creating a signed extrinsic.

Basic actions:

  • propose - Submits a sensitive action, represented as a hash. Requires a deposit.
  • second - Signals agreement with a proposal, moves it higher on the proposal queue, and requires a matching deposit to the original.
  • vote - Votes in a referendum, either the vote is "Aye" to enact the proposal or "Nay" to keep the status quo.
  • unvote - Cancel a previous vote, this must be done by the voter before the vote ends.
  • delegate - Delegates the voting power (tokens * conviction) to another account.
  • undelegate - Stops the delegation of voting power to another account.

Administration actions that can be done to any account:

  • reap_vote - Remove some account's expired votes.
  • unlock - Redetermine the account's balance lock, potentially making tokens available.

Preimage actions:

  • note_preimage - Registers the preimage for an upcoming proposal, requires a deposit that is returned once the proposal is enacted.
  • note_preimage_operational - same but provided by T::OperationalPreimageOrigin.
  • note_imminent_preimage - Registers the preimage for an upcoming proposal. Does not require a deposit, but the proposal must be in the dispatch queue.
  • note_imminent_preimage_operational - same but provided by T::OperationalPreimageOrigin.
  • reap_preimage - Removes the preimage for an expired proposal. Will only work under the condition that it's the same account that noted it and after the voting period, OR it's a different account after the enactment period.

Cancellation Origin

This call can only be made by the CancellationOrigin.

  • emergency_cancel - Schedules an emergency cancellation of a referendum. Can only happen once to a specific referendum.

ExternalOrigin

This call can only be made by the ExternalOrigin.

  • external_propose - Schedules a proposal to become a referendum once it is is legal for an externally proposed referendum.

External Majority Origin

This call can only be made by the ExternalMajorityOrigin.

  • external_propose_majority - Schedules a proposal to become a majority-carries referendum once it is legal for an externally proposed referendum.

External Default Origin

This call can only be made by the ExternalDefaultOrigin.

  • external_propose_default - Schedules a proposal to become a negative-turnout-bias referendum once it is legal for an externally proposed referendum.

Fast Track Origin

This call can only be made by the FastTrackOrigin.

  • fast_track - Schedules the current externally proposed proposal that is "majority-carries" to become a referendum immediately.

Veto Origin

This call can only be made by the VetoOrigin.

  • veto_external - Vetoes and blacklists the external proposal hash.

Root

  • cancel_referendum - Removes a referendum.
  • cancel_queued - Cancels a proposal that is queued for enactment.
  • clear_public_proposal - Removes all public proposals.

License: Apache-2.0

Release

Polkadot SDK stable2409

Dependencies

~17–32MB
~524K SLoC