From 382cbf1a08efecedb27dd2cddcb22be4ed338048 Mon Sep 17 00:00:00 2001 From: Mauro Lacy Date: Wed, 16 Dec 2020 14:00:06 +0100 Subject: [PATCH] Format / fix cw3 spec details --- packages/cw3/src/msg.rs | 4 ++-- packages/cw3/src/query.rs | 43 +++++++++++++++++++++------------------ 2 files changed, 25 insertions(+), 22 deletions(-) diff --git a/packages/cw3/src/msg.rs b/packages/cw3/src/msg.rs index cf07e4c84..31f946973 100644 --- a/packages/cw3/src/msg.rs +++ b/packages/cw3/src/msg.rs @@ -39,8 +39,8 @@ pub enum Vote { No, /// Marks participation but does not count towards the ratio of support / opposed Abstain, - /// Veto is generally to be treated as a no vote. Some implementations may allow certain - /// voters to be able to Veto, or them to be counted stronger then nos in some way. + /// Veto is generally to be treated as a No vote. Some implementations may allow certain + /// voters to be able to Veto, or them to be counted stronger than No in some way. Veto, } diff --git a/packages/cw3/src/query.rs b/packages/cw3/src/query.rs index 86c7e9c22..02ec33eb7 100644 --- a/packages/cw3/src/query.rs +++ b/packages/cw3/src/query.rs @@ -69,44 +69,47 @@ pub enum ThresholdResponse { /// A proposal of this type can pass early as soon as the needed weight of yes votes has been cast. AbsoluteCount { weight: u64, total_weight: u64 }, - /// Declares a percentage of the total weight that must cast yes votes in order for - /// a proposal to pass. As with `AbsoluteCount`, it only matters the sum of yes votes. + /// Declares a percentage of the total weight that must cast Yes votes, in order for + /// a proposal to pass. As with `AbsoluteCount`, Yes votes are the only ones that count. /// /// This is useful for similar circumstances as `AbsoluteCount`, where we have a relatively - /// small set of voters and participation is required. The advantage here is that if the - /// voting set (group) changes between proposals, the number of votes needed is adjusted - /// accordingly. + /// small set of voters, and participation is required. + /// It is understood that if the voting set (group) changes between different proposals that + /// refer to the same group, each proposal will work with a different set of voter weights + /// (the ones snapshotted at proposal creation), and the passing weight for each proposal + /// will be computed based on the absolute percentage, times the total weights of the members + /// at the time of each proposal creation. /// /// Example: we set `percentage` to 51%. Proposal 1 starts when there is a `total_weight` of 5. - /// This will require 3 weight of yes votes in order to pass. Later, the Proposal 2 starts but the + /// This will require 3 weight of Yes votes in order to pass. Later, the Proposal 2 starts but the /// `total_weight` of the group has increased to 9. That proposal will then automatically - /// require 5 yes of 9 to pass, rather than 3 yes of 9 as would be the case with `AbsoluteCount`. - /// - /// A proposal of this type can pass early as soon as the needed weight of yes votes has been cast. + /// require 5 Yes of 9 to pass, rather than 3 yes of 9 as would be the case with `AbsoluteCount`. AbsolutePercentage { percentage: Decimal, total_weight: u64, }, - /// Declares a `quorum` of the total votes that must participate in the election in order - /// for the vote to be considered at all. Within the votes that were cast, it requires `threshold` - /// in favor. That is calculated by ignoring the abstain votes (they count towards `quorum` - /// but do not influence `threshold`). That is, we calculate `yes / (yes + no + veto)` - /// and compare that with `threshold` to consider if the proposal was passed. + /// In addition to a `threshold`, declares a `quorum` of the total votes that must participate + /// in the election in order for the vote to be considered at all. Within the votes that + /// were cast, it requires `threshold` votes in favor. That is calculated by ignoring + /// the Abstain votes (they count towards `quorum`, but do not influence `threshold`). + /// That is, we calculate `Yes / (Yes + No + Veto)` and compare it with `threshold` to consider + /// if the proposal was passed. /// /// It is rather difficult for a proposal of this type to pass early. That can only happen if - /// the required quorum has been already met, and in the case if all remaining voters were - /// to vote no, the threshold would still be met. + /// the required quorum has been already met, and there are already enough Yes votes for the + /// proposal to pass. /// - /// 30% yes votes, 10% no votes, and 20% abstain would pass early if quorum <= 60% + /// 30% Yes votes, 10% No votes, and 20% Abstain would pass early if quorum <= 60% /// (who has cast votes) and if the threshold is <= 37.5% (the remaining 40% voting /// no => 30% yes + 50% no). Once the voting period has passed with no additional votes, /// that same proposal would be considered successful if quorum <= 60% and threshold <= 75% /// (percent in favor if we ignore abstain votes). /// - /// This type is more common in general elections where participation is expected to often - /// be low, and `AbsolutePercentage` would either be too restrictive to pass anything, - /// or allow low percentages to pass if there was high participation in one election. + /// This type is more common in general elections, where participation is often expected to + /// be low, and `AbsolutePercentage` would either be too high to pass anything, + /// or allow low percentages to pass, independently of if there was high participation in the + /// election or not. ThresholdQuora { threshold: Decimal, quorum: Decimal,