Token Voting

This documentation shows the build 3 which uses 1.4 protocol version. Currently, these are being audited. Even though, contracts are backwards compatible, we do NOT recommend using these latest versions in production until audit is finished.

Description

TokenVoting is a governance plugin developed and maintained by the Aragon core team. It enables decision-making in DAOs through proposals and token-based voting, where members’ influence is proportional to their token holdings or delegated voting power. Proposals succeed if they meet a configurable majority voting rule and other customizable parameters.

The plugin supports governance-ready ERC20 tokens (ERC20Votes) and can also deploy and mint new tokens that implement ERC20Votes. Additionally, it allows existing standard ERC20 tokens to be wrapped with governance capabilities using an ERC20Votes wrapper.

Proposal Lifecycle

Creation

Proposals can be created by users granted the CREATE_PROPOSAL_PERMISSION or those verified through the VotingPowerCondition, depending on the plugin’s configuration. Below are the essential operations of proposal creation:

  • Snapshot Block: Captures the state of the previous block (block.number - 1) at the time of creation.

  • Proposal Initialization: Instantiates a new proposal and records all relevant parameters, such as metadata, proposed actions, start and end dates, and voting settings.

  • Creator Voting: Allows proposal creators to cast their vote during the creation process, aligning their intent with the proposal.

Proposal creation settings:

  • Minimum Duration (minDuration): The shortest duration a proposal can remain open for voting.

  • Minimum Proposer Voting Power (minProposerVotingPower): The minimum voting power required to create a proposal.

Voting

Voters express their preferences through the vote function, which:

  • Verifies voter eligibility and records their vote.

  • Supports vote replacement (if enabled).

  • Allows early execution attempts if thresholds are met and the voter is eligible to execute the proposal.

Execution

Proposals can be executed by calling the execute function on the plugin, provided the following conditions are met:

  • Permission Verification: The execute function is guarded by the EXECUTE_PROPOSAL_PERMISSION, ensuring only authorized users can trigger the execution.

Typically, this permission is set to any address, allowing anyone to execute, but it can also be restricted to specific users or conditions if needed.

  • Threshold Verification: The plugin ensures that all thresholds (Support, Participation, and Approval) are satisfied, verifying the proposal’s success.

  • Action Passing: The plugin passes them to the associated DAO or to the configured executor, which is responsible for their execution.

  • Finalization: Once the actions are passed and executed, the plugin marks the proposal as executed.

Proposal execution settings:

  • Support Threshold (supportThreshold): The minimum ratio of "Yes" votes to total votes (Yes + No) required for a proposal to pass.

  • Minimum Participation (minParticipation): Ensures a percentage of total voting power participates for a proposal to be valid.

  • Minimum Approval Power (minApprovalPower): Specifies the minimum number of "Yes" votes required for a proposal to pass.

Voting Modes

The TokenVoting plugin supports three distinct voting modes, each designed to meet different governance needs. These modes cannot be enabled simultaneously because their logic and execution criteria conflict. DAOs must choose one mode based on their decision-making preferences.

  • Normal: Proposals succeed after the voting period ends if:

    • Support Criterion:
      \((1 - \texttt{supportThreshold}) \cdot N_\text{yes} > \texttt{supportThreshold} \cdot N_\text{no}\)
      The ratio of "Yes" votes to "No" votes must exceed the configured support threshold.

    • Participation Criterion:
      \(N_\text{yes} + N_\text{no} + N_\text{abstain} \geq \texttt{minVotingPower}\)
      The total voting power used in the proposal must meet the minimum participation requirement.

    • Approval Criterion:
      \(N_\text{yes} \geq \texttt{minApprovalPower}\)
      The number of "Yes" votes meets or exceeds the minApprovalPower.

  • Early Execution: Proposals in this mode can succeed before the voting period ends if the outcome is mathematically certain, even if all remaining votes are "No."

    • Worst-Case No Votes Formula:
      \(N_\text{no, worst-case} = N_\text{total} - N_\text{yes} - N_\text{abstain}\)
      Calculates the maximum possible "No" votes by assuming all remaining voting power is cast as "No."

    • Support Criterion for Early Execution:
      \((1 - \texttt{supportThreshold}) \cdot N_\text{yes} > \texttt{supportThreshold} \cdot N_\text{no, worst-case}\)
      Ensures "Yes" votes exceed the support threshold, even in the worst-case scenario of all remaining votes being "No."

  • Vote Replacement: Voters can update their preferences during the voting period. Only the latest vote is tallied.

Token Support

The TokenVoting plugin exclusively supports tokens that implement the ERC20Votes standard from OpenZeppelin (Learn more), which provides block-specific voting power snapshots and delegation capabilities.

For DAOs with existing non-governance tokens, these tokens can still be used with the plugin. Please refer to the Wrapped Token Setup section for details on how standard ERC20 tokens can be wrapped for governance.

Plugin Setup

  • Contracts: The TokenVotingSetup contains the TokenVoting plugin’s implementation and automatically deploys and prepares the following contracts:

    • TokenVoting Proxy: The ERC1967Proxy contract pointing to the plugin’s implementation.

    • VotingPowerCondition: A condition contract to determine if a user meets the minimum voting power or balance required to create a proposal.

    • Governance ERC20 Token: The plugin setup offers flexible options for DAOs to prepare tokens for governance, depending on their existing token situation:

      1. Existing Governance Tokens: If an ERC20Votes token is provided during setup, the plugin will use it directly.

      2. Token Deployment and Minting: If no token is provided, the setup deploys a new GovernanceERC20 token and mints an initial supply as specified by the user.

      3. Token Wrapping: For DAOs with a standard (non-governance) ERC20 token, the setup wraps it into a GovernanceWrappedERC20 token. This wrapper adds governance capabilities, enabling voting and delegation, while allowing deposits and withdrawals of the original token.

  • Permissions: The following permissions are set up by default by the TokenVotingSetup:

Permission ID Where (Granted By) Who (Granted To) Condition Functions

EXECUTE_PERMISSION_ID

DAO

Plugin

None

execute

UPDATE_VOTING_SETTINGS_PERMISSION_ID

Plugin

DAO

None

updateVotingSettings, updateMinApprovals

SET_TARGET_CONFIG_PERMISSION_ID

Plugin

DAO

None

setTargetConfig

SET_METADATA_PERMISSION_ID

Plugin

DAO

None

setMetadata

CREATE_PROPOSAL_PERMISSION_ID

Plugin

Any Address

VotingPowerCondition

createProposal

EXECUTE_PROPOSAL_PERMISSION_ID

Plugin

Any Address

None

execute

MINT_PERMISSION_ID

Associated Governance Token

DAO

None

mint

This setup ensures that the TokenVoting plugin is ready for operation immediately after installation, with all required contracts deployed and permissions configured.

Importing Existing Tokens →