Governance: Add VoteTipping option (#2826)

* spl-governance: Add VoteTipping option

This allows two new tipping styles in addition to the previous "Strict"
mode:
- Early: Where a yes majority above the yes vote threshold will
  complete the vote, even if below 50% of total possible votes.
- Disabled: Where votes never complete early.

* address review nits

Author: ckamm

governance/chat/program/tests/program_test/mod.rs

@@ -184,7 +184,7 @@ impl GovernanceChatProgramTest {
             min_transaction_hold_up_time: 10,
             max_voting_time: 10,
             vote_threshold_percentage: VoteThresholdPercentage::YesVote(60),
-            vote_weight_source: spl_governance::state::enums::VoteWeightSource::Deposit,
+            vote_tipping: spl_governance::state::enums::VoteTipping::Strict,
             proposal_cool_off_time: 0,
         };
 

governance/program/src/state/enums.rs

@@ -122,16 +122,26 @@ pub enum VoteThresholdPercentage {
     Quorum(u8),
 }
 
-/// The source of voter weights used to vote on proposals
+/// The type of vote tipping to use on a Proposal.
+///
+/// Vote tipping means that under some conditions voting will complete early.
 #[repr(C)]
 #[derive(Clone, Debug, PartialEq, BorshDeserialize, BorshSerialize, BorshSchema)]
-pub enum VoteWeightSource {
-    /// Governing token deposits into the Realm are used as voter weights
-    Deposit,
-    /// Governing token account snapshots as of the time a proposal entered voting state are used as voter weights
-    /// Note: Snapshot source is not supported in the current version
-    /// Support for account snapshots are required in solana and/or arweave as a prerequisite
-    Snapshot,
+pub enum VoteTipping {
+    /// Tip when there is no way for another option to win and the vote threshold
+    /// has been reached. This ignores voters withdrawing their votes.
+    ///
+    /// Currently only supported for the "yes" option in single choice votes.
+    Strict,
+
+    /// Tip when an option reaches the vote threshold and has more vote weight
+    /// than any other options.
+    ///
+    /// Currently only supported for the "yes" option in single choice votes.
+    Early,
+
+    /// Never tip the vote early.
+    Disabled,
 }
 
 /// The status of instruction execution

governance/program/src/state/governance.rs

@@ -3,7 +3,7 @@
 use crate::{
     error::GovernanceError,
     state::{
-        enums::{GovernanceAccountType, VoteThresholdPercentage, VoteWeightSource},
+        enums::{GovernanceAccountType, VoteThresholdPercentage, VoteTipping},
         realm::assert_is_valid_realm,
     },
 };
@@ -34,9 +34,8 @@ pub struct GovernanceConfig {
     /// Time limit in seconds for proposal to be open for voting
     pub max_voting_time: u32,
 
-    /// The source of vote weight for voters
-    /// Note: In the current version only token deposits are accepted as vote weight
-    pub vote_weight_source: VoteWeightSource,
+    /// Conditions under which a vote will complete early
+    pub vote_tipping: VoteTipping,
 
     /// The time period in seconds within which a Proposal can be still cancelled after being voted on
     /// Once cool off time expires Proposal can't be cancelled any longer and becomes a law
@@ -288,10 +287,6 @@ pub fn assert_is_valid_governance_config(
         }
     }
 
-    if governance_config.vote_weight_source != VoteWeightSource::Deposit {
-        return Err(GovernanceError::VoteWeightSourceNotSupported.into());
-    }
-
     if governance_config.proposal_cool_off_time > 0 {
         return Err(GovernanceError::ProposalCoolOffTimeNotSupported.into());
     }

governance/program/src/state/proposal.rs

@@ -25,7 +25,7 @@ use crate::{
     state::{
         enums::{
             GovernanceAccountType, InstructionExecutionFlags, MintMaxVoteWeightSource,
-            ProposalState, TransactionExecutionStatus, VoteThresholdPercentage,
+            ProposalState, TransactionExecutionStatus, VoteThresholdPercentage, VoteTipping,
         },
         governance::GovernanceConfig,
         proposal_transaction::ProposalTransactionV2,
@@ -542,13 +542,33 @@ impl ProposalV2 {
             get_min_vote_threshold_weight(&config.vote_threshold_percentage, max_vote_weight)
                 .unwrap();
 
-        if yes_vote_weight >= min_vote_threshold_weight
-            && yes_vote_weight > (max_vote_weight.saturating_sub(yes_vote_weight))
-        {
-            yes_option.vote_result = OptionVoteResult::Succeeded;
-            return Some(ProposalState::Succeeded);
-        } else if deny_vote_weight > (max_vote_weight.saturating_sub(min_vote_threshold_weight))
-            || deny_vote_weight >= (max_vote_weight.saturating_sub(deny_vote_weight))
+        match config.vote_tipping {
+            VoteTipping::Disabled => {}
+            VoteTipping::Strict => {
+                if yes_vote_weight >= min_vote_threshold_weight
+                    && yes_vote_weight > (max_vote_weight.saturating_sub(yes_vote_weight))
+                {
+                    yes_option.vote_result = OptionVoteResult::Succeeded;
+                    return Some(ProposalState::Succeeded);
+                }
+            }
+            VoteTipping::Early => {
+                if yes_vote_weight >= min_vote_threshold_weight
+                    && yes_vote_weight > deny_vote_weight
+                {
+                    yes_option.vote_result = OptionVoteResult::Succeeded;
+                    return Some(ProposalState::Succeeded);
+                }
+            }
+        }
+
+        // If vote tipping isn't disabled entirely, allow a vote to complete as
+        // "defeated" if there is no possible way of reaching majority or the
+        // min_vote_threshold_weight for another option. This tipping is always
+        // strict, there's no equivalent to "early" tipping for deny votes.
+        if config.vote_tipping != VoteTipping::Disabled
+            && (deny_vote_weight > (max_vote_weight.saturating_sub(min_vote_threshold_weight))
+                || deny_vote_weight >= (max_vote_weight.saturating_sub(deny_vote_weight)))
         {
             yes_option.vote_result = OptionVoteResult::Defeated;
             return Some(ProposalState::Defeated);
@@ -929,7 +949,7 @@ mod test {
     use solana_program::clock::Epoch;
 
     use crate::state::{
-        enums::{MintMaxVoteWeightSource, VoteThresholdPercentage, VoteWeightSource},
+        enums::{MintMaxVoteWeightSource, VoteThresholdPercentage},
         legacy::ProposalV1,
         realm::RealmConfig,
         vote_record::VoteChoice,
@@ -1036,7 +1056,7 @@ mod test {
             min_transaction_hold_up_time: 10,
             max_voting_time: 5,
             vote_threshold_percentage: VoteThresholdPercentage::YesVote(60),
-            vote_weight_source: VoteWeightSource::Deposit,
+            vote_tipping: VoteTipping::Strict,
             proposal_cool_off_time: 0,
         }
     }