Merge pull request #268 from Mimah97/feature/quorum-bps-governance

feat(niffyinsure): configurable quorum_bps with per-claim snapshot

Author: jhayniffy

contracts/niffyinsure/src/claim.rs

@@ -88,6 +88,50 @@ fn push_status_transition(
     }
 }
 
+// ── Participation quorum (see also `types` lifecycle docs) ───────────────────
+//
+// Let `E` = eligible voters (snapshot length at `file_claim`), `C` = cast ballots =
+// `approve_votes + reject_votes`, `Q` = quorum basis points **for this claim**
+// (instance `quorum_bps` copied into persistent `ClaimQuorumBps(claim_id)` at filing).
+// Admin changes to instance `quorum_bps` do **not** alter `Q` for claims already in
+// `Processing`.
+//
+// Required minimum cast votes:
+//   R = ceil(E * Q / 10_000)  →  R = (E * Q + 9_999) / 10_000  (u32; E = 0 ⇒ R = 0)
+//
+// **Quorum met** iff `C >= R`. If met, outcome is **plurality**: Approved when
+// `approve_votes > reject_votes`, else Rejected (insurer wins ties).
+// If the voting deadline passes with `C < R`, the claim is **Rejected** (no quorum).
+fn required_cast_for_quorum(eligible: u32, quorum_bps: u32) -> u32 {
+    if eligible == 0 {
+        return 0;
+    }
+    let numer = (eligible as u64).saturating_mul(quorum_bps as u64);
+    numer.div_ceil(10_000) as u32
+}
+
+fn participation_quorum_met(cast_votes: u32, eligible: u32, quorum_bps: u32) -> bool {
+    cast_votes >= required_cast_for_quorum(eligible, quorum_bps)
+}
+
+/// If participation quorum is satisfied, returns Some(Approved|Rejected) by plurality.
+fn resolve_plurality_if_quorum_met(
+    approve_votes: u32,
+    reject_votes: u32,
+    cast_votes: u32,
+    eligible: u32,
+    quorum_bps: u32,
+) -> Option<ClaimStatus> {
+    if !participation_quorum_met(cast_votes, eligible, quorum_bps) {
+        return None;
+    }
+    if approve_votes > reject_votes {
+        Some(ClaimStatus::Approved)
+    } else {
+        Some(ClaimStatus::Rejected)
+    }
+}
+
 // ── Events ────────────────────────────────────────────────────────────────────
 
 #[contractevent(topics = ["niffyinsure", "claim_filed"])]
@@ -259,6 +303,7 @@ pub fn file_claim(
     storage::set_claim(env, &claim);
     storage::set_open_claim(env, holder, policy_id, true);
     storage::snapshot_claim_voters(env, claim_id);
+    storage::set_claim_quorum_bps(env, claim_id, storage::get_quorum_bps(env));
     storage::set_last_claim_ledger(env, holder, now);
 
     let mut evidence_hashes: Vec<BytesN<32>> = Vec::new(env);
@@ -331,14 +376,21 @@ pub fn vote_on_claim(
         VoteOption::Reject => claim.reject_votes += 1,
     }
 
-    // Auto-finalize on majority.
-    let total = snapshot.len();
-    let majority = total / 2 + 1;
-    if claim.approve_votes >= majority {
-        claim.status = ClaimStatus::Approved;
-    } else if claim.reject_votes >= majority {
-        claim.status = ClaimStatus::Rejected;
-        claim.appeal_open_deadline_ledger = now.saturating_add(ledger::APPEAL_OPEN_WINDOW_LEDGERS);
+    let eligible = snapshot.len() as u32;
+    let cast = claim.approve_votes + claim.reject_votes;
+    let quorum_bps = storage::get_claim_quorum_bps(env, claim_id);
+    if let Some(res) = resolve_plurality_if_quorum_met(
+        claim.approve_votes,
+        claim.reject_votes,
+        cast,
+        eligible,
+        quorum_bps,
+    ) {
+        let rejected = res == ClaimStatus::Rejected;
+        claim.status = res;
+        if rejected {
+            claim.appeal_open_deadline_ledger = now.saturating_add(ledger::APPEAL_OPEN_WINDOW_LEDGERS);
+        }
     }
 
     if claim.status != status_before {
@@ -380,7 +432,8 @@ pub fn refresh_snapshot(env: &Env, claim_id: u64) -> Result<(), Error> {
 /// Finalize a claim after the voting deadline has passed.
 ///
 /// Window check: `now > claim.voting_deadline_ledger` (see `ledger::is_claim_past_voting_deadline`).
-/// Plurality wins; tie resolves to Rejected.
+/// Uses the **participation quorum** and per-claim `quorum_bps` snapshot (see module helpers).
+/// If quorum is met, plurality decides; if not, **Rejected** (no quorum).
 pub fn finalize_claim(env: &Env, claim_id: u64) -> Result<ClaimStatus, Error> {
     // Check pause: finalization is blocked if claims_paused is true
     storage::assert_claims_not_paused(env);
@@ -398,10 +451,20 @@ pub fn finalize_claim(env: &Env, claim_id: u64) -> Result<ClaimStatus, Error> {
 
     let status_before = claim.status.clone();
 
-    if claim.approve_votes > claim.reject_votes {
-        claim.status = ClaimStatus::Approved;
+    let voters = storage::get_claim_voters(env, claim_id);
+    let eligible = voters.len() as u32;
+    let cast = claim.approve_votes + claim.reject_votes;
+    let quorum_bps = storage::get_claim_quorum_bps(env, claim_id);
+
+    if participation_quorum_met(cast, eligible, quorum_bps) {
+        if claim.approve_votes > claim.reject_votes {
+            claim.status = ClaimStatus::Approved;
+        } else {
+            claim.status = ClaimStatus::Rejected;
+            claim.appeal_open_deadline_ledger = now.saturating_add(ledger::APPEAL_OPEN_WINDOW_LEDGERS);
+        }
     } else {
-        // Tie or reject plurality → Rejected (insurer wins tie).
+        // Below minimum participation — no quorum (insurer-favored default).
         claim.status = ClaimStatus::Rejected;
         claim.appeal_open_deadline_ledger = now.saturating_add(ledger::APPEAL_OPEN_WINDOW_LEDGERS);
     }

contracts/niffyinsure/src/events.rs

@@ -62,6 +62,10 @@
 //! ```
 //! - `allowed`: 1 = added to allowlist, 0 = removed
 //!
+//! ### quorum_updated — (contract `niffyinsure` topic namespace)
+//! On-chain topics: `["niffyinsure", "quorum_updated"]` with payload `{ old_bps, new_bps }`.
+//! Emitted by `admin_set_quorum_bps`. Does not alter `quorum_bps` already snapshotted on open claims.
+//!
 //! ### adm_prop — AdminProposedData
 //! topics: ("niffyins", "adm_prop", old_admin: Address, new_admin: Address)
 //! ```json

contracts/niffyinsure/src/lib.rs

@@ -51,6 +51,13 @@ struct VotingDurationUpdated {
     pub new_ledgers: u32,
 }
 
+#[contractevent(topics = ["niffyinsure", "quorum_updated"])]
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct QuorumUpdated {
+    pub old_bps: u32,
+    pub new_bps: u32,
+}
+
 #[contractevent(topics = ["niffyinsure", "pause_toggled"])]
 #[derive(Clone, Debug, Eq, PartialEq)]
 struct PauseToggled {
@@ -77,6 +84,7 @@ impl NiffyInsure {
         storage::set_multiplier_table(&env, &premium::default_multiplier_table(&env));
         storage::set_allowed_asset(&env, &token, true);
         storage::set_voting_duration_ledgers(&env, ledger::VOTE_WINDOW_LEDGERS);
+        storage::set_quorum_bps(&env, types::DEFAULT_QUORUM_BPS);
         Ok(())
     }
 
@@ -233,6 +241,31 @@ impl NiffyInsure {
         Ok(())
     }
 
+    /// Participation quorum in basis points (1–10_000). Applies to **new** claims only;
+    /// each claim stores a snapshot at `file_claim` so `Processing` claims keep their `quorum_bps`.
+    pub fn get_quorum_bps(env: Env) -> u32 {
+        storage::get_quorum_bps(&env)
+    }
+
+    /// Basis points snapshot for this claim (immutable after filing).
+    pub fn get_claim_quorum_bps(env: Env, claim_id: u64) -> u32 {
+        storage::get_claim_quorum_bps(&env, claim_id)
+    }
+
+    pub fn admin_set_quorum_bps(env: Env, quorum_bps: u32) -> Result<(), validate::Error> {
+        let admin = storage::get_admin(&env);
+        admin.require_auth();
+        validate::validate_quorum_bps(quorum_bps)?;
+        let old = storage::get_quorum_bps(&env);
+        storage::set_quorum_bps(&env, quorum_bps);
+        QuorumUpdated {
+            old_bps: old,
+            new_bps: quorum_bps,
+        }
+        .publish(&env);
+        Ok(())
+    }
+
     // ── Grace period ──────────────────────────────────────────────────────────
 
     /// Admin-only: set the grace period (in ledgers) after nominal expiry during

contracts/niffyinsure/src/storage.rs

@@ -76,8 +76,12 @@ pub enum DataKey {
     AppealVote(u64, Address),
     /// Configurable voting window in ledgers (set by admin via set_voting_duration_ledgers).
     VoteDurLedgers,
+    /// Participation quorum in basis points (1–10_000). New claims snapshot this at filing.
+    QuorumBps,
     /// Configurable grace period in ledgers after nominal expiry for late renewals.
     GracePeriodLedgers,
+    /// Per-claim snapshot of `QuorumBps` at `file_claim` time (immutable for that claim).
+    ClaimQuorumBps(u64),
 }
 
 // ── Instance bump ─────────────────────────────────────────────────────────────
@@ -173,6 +177,38 @@ pub fn get_voting_duration_ledgers(env: &Env) -> u32 {
         .unwrap_or(ledger::VOTE_WINDOW_LEDGERS)
 }
 
+// ── Claim voting quorum (instance + per-claim snapshot) ───────────────────────
+
+pub fn set_quorum_bps(env: &Env, bps: u32) {
+    env.storage().instance().set(&DataKey::QuorumBps, &bps);
+}
+
+/// Current instance quorum (basis points). Defaults to [`crate::types::DEFAULT_QUORUM_BPS`].
+pub fn get_quorum_bps(env: &Env) -> u32 {
+    env.storage()
+        .instance()
+        .get(&DataKey::QuorumBps)
+        .unwrap_or(crate::types::DEFAULT_QUORUM_BPS)
+}
+
+pub fn set_claim_quorum_bps(env: &Env, claim_id: u64, bps: u32) {
+    let key = DataKey::ClaimQuorumBps(claim_id);
+    env.storage().persistent().set(&key, &bps);
+    env.storage()
+        .persistent()
+        .extend_ttl(&key, PERSISTENT_TTL_THRESHOLD, PERSISTENT_TTL_EXTEND_TO);
+}
+
+/// Quorum basis points frozen for this claim at filing. Missing key ⇒ legacy claim:
+/// use [`crate::types::DEFAULT_QUORUM_BPS`] so admin quorum changes never retroactively
+/// alter `Processing` claims that predate per-claim snapshots.
+pub fn get_claim_quorum_bps(env: &Env, claim_id: u64) -> u32 {
+    env.storage()
+        .persistent()
+        .get(&DataKey::ClaimQuorumBps(claim_id))
+        .unwrap_or(crate::types::DEFAULT_QUORUM_BPS)
+}
+
 // ── Grace period (instance) ───────────────────────────────────────────────────
 
 pub fn set_grace_period_ledgers(env: &Env, ledgers: u32) {

contracts/niffyinsure/src/types.rs

@@ -58,6 +58,19 @@ pub use crate::ledger::{
 /// can be reversed by a successful appeal that decrements strikes back below it.
 pub const STRIKE_DEACTIVATION_THRESHOLD: u32 = 3;
 
+// ── Claim voting quorum (basis points) ────────────────────────────────────────
+
+/// Default participation quorum when instance `QuorumBps` is unset, and fallback for
+/// claims filed before per-claim quorum snapshots existed.
+pub const DEFAULT_QUORUM_BPS: u32 = 5000;
+
+/// Admin `quorum_bps` must satisfy `QUORUM_BPS_MIN <= quorum_bps <= QUORUM_BPS_MAX`.
+pub const QUORUM_BPS_MIN: u32 = 1;
+pub const QUORUM_BPS_MAX: u32 = 10_000;
+
+/// One full turn-out / 100% weight in bps (used in the quorum formula below).
+pub const QUORUM_BPS_DENOMINATOR: u32 = 10_000;
+
 // ── Enums ─────────────────────────────────────────────────────────────────────
 
 #[contracttype]
@@ -95,8 +108,8 @@ pub enum CoverageTier {
 /// Claim lifecycle state machine.
 ///
 /// Base-flow transitions:
-///   Processing  → Approved      (majority approve vote or deadline plurality)
-///   Processing  → Rejected      (majority reject vote or deadline plurality/tie)
+///   Processing  → Approved      (participation quorum met + more approve than reject votes cast)
+///   Processing  → Rejected      (participation quorum met + reject wins or tie; or deadline with no quorum)
 ///   Approved    → Paid          (admin calls process_claim)
 ///
 /// Appeal-flow transitions (requires Rejected status + open appeal window):

contracts/niffyinsure/src/validate.rs

@@ -62,6 +62,15 @@ pub enum Error {
     VoterSnapshotExpired = 51,
 }
 
+pub fn validate_quorum_bps(bps: u32) -> Result<(), Error> {
+    use crate::types::{QUORUM_BPS_MAX, QUORUM_BPS_MIN};
+    if !(QUORUM_BPS_MIN..=QUORUM_BPS_MAX).contains(&bps) {
+        // Reuse bounded-config error code (Soroban `contracterror` caps variant count).
+        return Err(Error::VotingDurationOutOfBounds);
+    }
+    Ok(())
+}
+
 pub fn check_policy(policy: &Policy) -> Result<(), Error> {
     if policy.coverage <= 0 {
         return Err(Error::ZeroCoverage);

contracts/niffyinsure/tests/claim_status_history.rs

@@ -156,11 +156,14 @@ fn status_history_finalize_reject_sequence() {
         &None,
     );
 
+    // 100% participation required so a 1–1 split does not auto-finalize before the deadline.
+    client.admin_set_quorum_bps(&10_000u32);
+
     let details = String::from_str(&env, "reject path");
     let ev = common::empty_evidence(&env);
     let claim_id = client.file_claim(&holder, &policy.policy_id, &50_000, &details, &ev);
 
-    // Split vote — no majority until deadline
+    // Split vote — quorum not met until deadline
     client.vote_on_claim(&voter1, &claim_id, &VoteOption::Approve);
     client.vote_on_claim(&voter2, &claim_id, &VoteOption::Reject);
 

contracts/niffyinsure/tests/e2e_workflow.rs

@@ -188,11 +188,14 @@ fn e2e_finalize_after_deadline() {
     );
     let policy_id = policy.policy_id;
 
+    // Require all eligible voters to cast before quorum counts (so one ballot stays Processing).
+    client.admin_set_quorum_bps(&10_000u32);
+
     let details = String::from_str(&env, "Claim for review");
     let ev = common::empty_evidence(&env);
     let claim_id = client.file_claim(&holder, &policy_id, &100_000, &details, &ev);
 
-    // Vote once (not enough for majority)
+    // Vote once — participation quorum not satisfied yet
     client.vote_on_claim(&voter1, &claim_id, &VoteOption::Approve);
 
     let claim = client.get_claim(&claim_id);
@@ -205,9 +208,9 @@ fn e2e_finalize_after_deadline() {
     // Finalize after deadline
     client.finalize_claim(&claim_id);
 
-    // Verify claim is Rejected (tie/partial = reject)
+    // Below required participation at deadline → no quorum → Rejected
     let claim = client.get_claim(&claim_id);
-    assert!(claim.status == ClaimStatus::Rejected || claim.status == ClaimStatus::Approved);
+    assert_eq!(claim.status, ClaimStatus::Rejected);
 }
 
 // ── Pause Behavior Tests ───────────────────────────────────────────────────────