vega-frontend-monorepo/specs/3001-VOTE-vote.md

Vote

Background: Governance spec and docs.

There are a few things that can be governed on Vega...

• Network parameters (variables used by the network)
• Markets (creation and changes to existing)
• Assets (creation on changes to existing)
• "Freeform", which has no affect on the network but can be used to to measure token holders views

To make proposal: a user will require an amount of the Governance token associated with their key.

To vote: a user will require associated Governance tokens (or in the case of market change proposals they could have an active liquidity provision).

Each vote has a weight behind it based on the number of associate tokens or the liquidity provision's equity like share at the point in time that the vote closes.

Each proposal type will have a majority required (vote weight in favour) and a participation required (the turn out for the vote needs to be sufficient to be valid).

A proposal has a life cycle and various statuses to track it's progress. proposals that accept votes can have a few different statuses. A short hand is used in these ACs:

• Open = Accepting votes (includes waitingForNodeVote)
• To enact = passed but not yet enacted (`pending)
• Closed = was accepting votes but deadline has passed (e.g. passed, rejected etc)
• Failed = did not get to the point of accepting votes.

list of proposals

When looking for a particular proposal or wanting to see what proposals are open, soon to enact or closed, I...

• must see link to details on how governance works in docs (3001-VOTE-001)
• must see link(s) to make proposals (3001-VOTE-002)
• must if there are no proposals, see that there have been no proposals since the last chain checkpoint restore (3001-VOTE-003)
• must see open proposals (and ones due for enactment) distinct from others (e.g grouped by "open", "to enact" "closed") (note: freeform proposals do not enact so should be shown as "closed" when "passed") (3001-VOTE-004)
• should see proposals sorted with the ones closest to enactment first (within each group)
• must see a history of all "closed" proposals (3001-VOTE-006)
• can search for a proposal by:
  • should be able to search by proposal ID
  • should be able to search by public key of the proposer
  • should be abel to search by market ID/name/code (ID may be the same as proposal ID)
  • should be able to search by asset name/symbol
  • should be able to search by network parameter
  • should be able to search by content of proposal description
• must see how long is left to vote (3001-VOTE-018)
• must see colourful / shouty things that prompt me to vote urgently on things "CLOSING SOON" (3001-VOTE-019)
• must see the current voting status and whether it will pass (3001-VOTE-020)
• must see the current participation and whether it will pass (3001-VOTE-021)

for each proposal:

• must see the proposal ID (3001-VOTE-008)
• must see who the proposer is (e.g. their public address) (3001-VOTE-009)
• must see the type of proposal (3001-VOTE-007)
• must see the proposal title (3001-VOTE-097)
• should see a summary of what the type of proposed change is, without looking at details (network, new market etc)
  • for network parameters: should see what parameter is being changed and new value
  • for network parameters: could see what the current values are for that parameter
  • for network parameters: could see if there are other open proposals for the same parameter
  • for new markets: should see the type of market (e.g. Future)
  • for new markets: could see the type trading mode of the market (e.g. auction, continuous)
  • for new markets: should see the name of the new market
  • for new markets: should see the code of the new market
  • for new markets: should see the settlement asset of the new market (not just asset ID but asset Symbol)
  • for new markets: could see a summary of the oracle used for settlement
  • for market changes: should see the name of the market being changed
  • for market changes: should see a summary of what parameters are being changed
  • for market changes: should see a the proposed values for parameters
  • for market changes: should see a the current values for that parameter
  • for market changes: could see if there are other open proposals for the same market
  • for new assets: must see the name of the new asset (3001-VOTE-026)
  • for new assets: must see the code of the new asset (3001-VOTE-027)
  • for new assets: must see the source of the new asset (e.g. ERC20) (3001-VOTE-028)
  • for new assets (if source is ERC20): must see contract address (3001-VOTE-095)
  • for new assets (if source is ERC20): must see if the Asset has been whitelisted on the bridge (3001-VOTE-096)
  • for asset changes: must see name of asset being changed (3001-VOTE-029)
  • for asset changes: must see the parameter(s) being changed (3001-VOTE-030)
  • for asset changes; must see the new value for the parameters being changed (3001-VOTE-031)
  • for asset changes: could see if there are other open proposals for the same parameter(s)
  • for asset changes: should see the current values for these parameters
  • for freeform: must see a summary of the proposal (suggest the first x characters of the proposal blob)
• must see the proposal status e.g. passed, open, waiting for node to vote) (3001-VOTE-035)
  • for new asset proposals: must see if an asset has not yet been whitelisted on the bridge (3001-VOTE-036)
• must see the proposal's terms in JSON (3001-VOTE-010)
• for open proposals: must see a summary of how the vote count stands and if it looks like proposal will pass or not (note some of these are repeated in more details in the details section) (3001-VOTE-037)
  • if the proposal failed (had the status of "failed", because it was an invalid on submission) they should not appear in the list (instead the proposer will see this after submission)
  • if the proposal looks like it will fail due to insufficient participation: should see "participation not reached"
  • else if: proposal looks like it might fail due to insufficient majority (and is not a market change proposal): should see "Majority not reached"
  • else if (is a market change proposal) and is likely to pass because of liquidity providers vote: should see "set to pass by Liquidity provider vote"
  • else if: proposal is likely to pass: should see "set to pass"
  • must see when (date/time) voting closes on proposal (3001-VOTE-043)
• for (non-freefrom) proposals that have passed but not enacted: must see when they will enact (3001-VOTE-044)
• for (non-freefrom) proposals that have passed but not enacted: should see when (date/time) voting closed
• for (non-freeform) proposals that enacted: must see when they enacted (3001-VOTE-046)
• for freeform proposals that have passed: must see when they passed (3001-VOTE-047)
• for proposals that did not pass due to lack of participation: must see "Participation not reached" (3001-VOTE-048)
• for proposals that did not pass due to lack of majority: must see "Majority not reached" (3001-VOTE-049)
• for proposals that did not pass due to failure: must see "Failed" (3001-VOTE-050)
• for proposals that I (connected Vega key) have voted on: should see my vote (for or against)

...so I can see select one to view and vote, or view outcome.

Details of a proposal

When looking at a particular proposal, I...

• see the same details in the list of proposals and:

• must have option to see raw JSON of proposal (3001-VOTE-052)

• should display the proposed change details displayed in a human readable format (e.g. with market id, shown along with that market name)

• must see the rationale title (3001-VOTE-054)

• must see the full rationale description if there is one (3001-VOTE-055)

• must see rationale description rendered with markdown (3001-VOTE-101)

For open proposals:

• must show a summary of vote status (base on the current total amount associated tokens, note this could change before the vote ends) (3001-VOTE-057)
• must see if the token vote has met a required participation threshold (3001-VOTE-058)
• must see the sum of tokens that have voted so far (3001-VOTE-059)
• must see sum of tokens that have voted as a percentage of total voted (3001-VOTE-011)
• should see what the participation threshold is for this proposal (note this is set per proposal once the proposal hits the chain based on the current network params, incase a proposal is set to enact that changes threshold)
• must see if the Token vote has met the required majority threshold (3001-VOTE-062)
• must see the sum of tokens that have voted in favour of the proposal (3001-VOTE-064)
• should see sum of tokens that have votes in favour of proposal as percentage of total associated
• should see what the majority threshold is for this proposal (note this is see per proposal, incase a proposal is set to enact that changes threshold)

For open market change proposals, all of the above and:

• must show a summary of vote status (base on the current equality like share, note this could change before the vote ends) (3001-VOTE-067)
• must see if the equity like share vote has met the required participation threshold (3001-VOTE-068)
• must see the equity like share % that has voted so far (3001-VOTE-069)
• should see what the equity like share threshold is for this proposal (note this is see per proposal, incase a proposal is set to enact that changes threshold)
• must see if the equity like share vote has met the required majority threshold (3001-VOTE-071)
• must see the equity like share as percentage that has voted in favour of the proposal (3001-VOTE-072)
• must see what the majority threshold is for this proposal (note this is see per proposal, incase a proposal is set to enact that changes threshold) (3001-VOTE-073)

For update market proposals:

• As a liquidity provider, must be able to participate in a liquidity vote on an update market proposal, when the token vote has not reached required participation level in time (3001-VOTE-015)
• must be able to to understand why a liquidity vote has been incurred (3001-VOTE-016)
• must be able to to understand that the result in the end may differ (as the outcome of the vote is based on the number of tokens held by the voters at time of vote close) (3001-VOTE-017)

For closed market change proposals, all of the above and:

• must see all of above but values at time of vote close (3001-VOTE-074)

... so I can see what I am voting for and the status of the vote.

Can vote on an open proposals

When looking to vote on the proposal, I...

• must see an option to connect to a Vega wallet/key (3001-VOTE-075)
• must be connected to a Vega wallet/key (3001-VOTE-076)
  • must see sum of tokens I have associated (3001-VOTE-100)
  • should see what percentage of the total associated tokens I hold
    • must, if I have 0 tokens, see link to associate (3001-VOTE-012)
  • must see my current vote for, against, or not voted (3001-VOTE-079)
  • must see option to vote for or against (3001-VOTE-080)
    • must trigger a transaction that needs to be confirmed in users wallet (3001-VOTE-013)
    • must see that I need to confirm the transaction in my wallet to continue (3001-VOTE-014)
  • must see option to change my vote (vote again in same or different direction) (3001-VOTE-090)

For open market change proposals, all of the above and:

• must see your equity like share on the market you are voting on (3001-VOTE-092)

for both:

• must see feedback of my vote Vega transaction (3001-VOTE-093)

...so that I can cast my vote and see the impact it might have.