[Feature] Implement DAO-style governance voting for protocol-level decisions and pool parameter changes

[Sendi0011]

Getting Started

1. Fork the repository: https://github.com/JointSave-org/Joint_Save
2. Clone your fork:

git clone https://github.com/<your-username>/Joint_Save.git
cd Joint_Save

3. Create a new branch:

git checkout -b feat/dao-governance-voting

---

Overview

JointSave currently has no mechanism for pool members to collectively decide on pool parameters (e.g., changing deposit amounts, extending deadlines, or modifying penalty rules). All administrative decisions are made unilaterally by the pool creator/admin. This creates a single point of failure and does not reflect how real-world savings groups operate — where decisions are made collectively.

The roadmap (Phase 3) lists "DAO Governance — Community-driven protocol improvements" but no foundation exists. The factory contract has no governance extensions. The frontend has no voting UI.

This issue implements a lightweight on-chain governance system that allows pool members to propose and vote on parameter changes, with execution only occurring when a configurable quorum is met.

Requirements

Smart Contract Changes

• New contract: smartcontract/governance/
  • Storage:
    • proposals: Map<Bytes, Proposal> where Proposal contains:
      • proposer: Address
      • proposal_type: ProposalType (enum: ChangeDepositAmount, ExtendDeadline, AddPenalty, RemovePenalty, ChangeQuorum, Custom)
      • parameters: Map<String, Bytes> (serialized proposal-specific params)
      • votes_for: Vec<Address>
      • votes_against: Vec<Address>
      • status: ProposalStatus (enum: Active, Passed, Executed, Expired, Rejected)
      • created_at: u64
      • expires_at: u64 (48 hours default)
      • execution_result: Option<Vec<u8>>
    • voting_quorum: u32 (percentage of total members, e.g., 51 means 51%)
    • pool_contract: Address (the pool this governance contract is attached to)
  • Functions:
    • create_proposal(member, proposal_type, parameters) -> proposal_id — only pool members can create; max 3 active proposals per pool
    • vote(proposer, proposal_id, in_favor: bool) — one vote per member per proposal; cannot vote on own proposal
    • execute_proposal(executor, proposal_id) — only succeeds if votes_for >= quorum percentage of total members AND proposal is not expired; executes the parameter change on the target pool contract via CPI
    • get_proposal(proposal_id) -> Proposal
    • get_active_proposals(pool_contract) -> Vec<Proposal>
    • get_voting_quorum() -> u32

Pool Contract Integration

• Add a new function to all three pool contracts: apply_governance_proposal(admin, proposal_type, parameters) — admin-only but designed to be called via CPI from the governance contract
• The governance contract stores the pool contract address and can invoke apply_governance_proposal via env.invoke_contract()
• Existing pool parameters that become governable:
  • deposit_amount (flexible pools)
  • round_duration (rotational pools)
  • penalty_percentage

Frontend Changes

• New component: frontend/components/governance/proposal-list.tsx
  • Lists all active and recent proposals for a pool
  • Shows proposal type, proposer, vote counts, time remaining
  • Color-coded status badges (Active=blue, Passed=green, Executed=gray, Expired=orange, Rejected=red)
• New component: frontend/components/governance/create-proposal-dialog.tsx
  • Modal dialog accessible from group detail page (admin section or governance tab)
  • Dropdown for proposal type
  • Dynamic form fields based on selected type (e.g., "New Deposit Amount" shows amount input)
  • Character limit on proposal description (500 chars)
• New component: frontend/components/governance/vote-card.tsx
  • Shows proposal details with "Vote For" and "Vote Against" buttons
  • Visual progress bar showing votes toward quorum
  • Disable vote buttons if user already voted or is the proposer
  • "Execute" button visible only when quorum is met and user is admin
• New tab or section in group detail page: "Governance" tab (visible when governance contract is deployed for the pool)
• New hook: frontend/hooks/useGovernance.ts
  • Fetches proposals, vote status, and quorum info for a pool
  • createProposal(), vote(), executeProposal() mutations
  • Realtime vote count updates via Supabase Realtime subscription on a new governance_votes table

Database Changes

• New table governance_votes (off-chain mirror for realtime):
  • proposal_id (text)
  • pool_id (text)
  • voter_address (text)
  • vote (boolean)
  • created_at (timestamptz)
  • RLS: members of the pool can read; authenticated users can insert their own

Acceptance Criteria

• Pool members can create proposals with different types and parameter sets
• Members can vote For or Against exactly once per proposal
• Proposals automatically expire after 48 hours
• Execution only succeeds when quorum percentage of members have voted For
• Executed proposals apply parameter changes to the target pool contract via CPI
• Max 3 active proposals enforced per pool
• Frontend renders proposal list, create dialog, and vote cards correctly
• Vote counts update in realtime without page refresh
• Governance tab only appears for pools with a governance contract attached
• Mobile: voting UI is fully responsive and touch-friendly

[Ajibose]

Here's a draft:

I'd like to work on this.

For the contract, proposals stored as Map<Bytes, Proposal> with the fields specified, and quorum checked as a percentage of total pool members rather than a fixed vote count, so the threshold scales correctly as pool membership changes. create_proposal enforces the max-3-active-per-pool cap by counting existing Active status proposals for that pool before allowing a new one. vote needs a check that the caller hasn't already voted and isn't the proposer, and execute_proposal recomputes votes_for against current total member count at execution time rather than trusting a stale percentage, since membership could shift between proposal creation and execution.

For pool integration, apply_governance_proposal on each pool contract stays admin-gated but is invoked by the governance contract via env.invoke_contract(), so the governance contract effectively acts as the admin caller for approved changes. I'd map each ProposalType (deposit amount, round duration, penalty percentage) to the specific parameter update it triggers on the target pool, validating the parameter values make sense for that pool type before applying, so an executed proposal can't push an invalid state onto the pool contract.

On the frontend, useGovernance centralizes fetching proposals and quorum info plus the create/vote/execute mutations, with the Supabase Realtime subscription on governance_votes driving live vote count updates without needing a manual refresh. The vote card's button states (disabled if already voted or is proposer, execute only visible when quorum's met and caller is admin) all derive from that hook's data rather than being recomputed separately in each component.

For the DB, governance_votes mirrors on-chain votes for realtime display, with RLS scoped so pool members can read but each user can only insert their own vote row, matching the on-chain one-vote-per-member rule at the display layer too.

For tests, I'd cover: max-3-active-proposal enforcement, double-voting rejection, proposer-can't-vote-on-own-proposal, expiry after 48 hours, execution succeeding only at quorum and failing below it, and the CPI actually updating the target pool's parameter correctly.

[Promise278]

Hi team, I'd like to work on this issue — implementing DAO governance voting for JointSave.

Proposed technical approach:

1. Governance Smart Contract
   I'll build the new smartcontract/governance/ contract with the Proposal struct and ProposalType/ProposalStatus enums as specified. Key design decisions:

Use Map<Bytes, Proposal> keyed by a deterministic proposal ID (e.g., hash of pool_contract + proposer + created_at) to avoid collisions
Store votes_for/votes_against as Vec

for auditability, but check length against quorum at execution time rather than recalculating on every vote (gas efficiency)
Enforce the "max 3 active proposals per pool" rule by filtering get_active_proposals(pool_contract) for Active status before allowing create_proposal
expires_at computed as created_at + 48h at creation time; a proposal is checked for expiry lazily (on vote/execute calls) rather than requiring a cron/keeper, to keep this lightweight

2. Pool Contract Integration

Add apply_governance_proposal(admin, proposal_type, parameters) to all three pool contracts, gated so it only accepts calls where admin matches the governance contract's registered address for that pool (to prevent arbitrary CPI calls spoofing governance)
Governance contract holds pool_contract: Address and invokes via env.invoke_contract(), passing the proposal's parameters map through to the target function
Map each ProposalType to its corresponding pool parameter update path (deposit_amount, round_duration, penalty_percentage) with type-safe deserialization of parameters

3. Frontend

useGovernance.ts hook wraps proposal fetch, vote, and execute mutations, plus a Supabase Realtime subscription on governance_votes for live vote count updates
proposal-list.tsx, create-proposal-dialog.tsx, and vote-card.tsx built as independent, composable components so the Governance tab can render conditionally based on whether a governance contract is attached to the pool
Dynamic form fields in the create-proposal dialog driven by a config map (proposal type → required fields), so adding new proposal types later doesn't require touching the dialog's core logic
Vote buttons disabled client-side for proposer/already-voted, but final enforcement always happens on-chain (client-side is UX only, not a security boundary)

4. Database

governance_votes table with RLS: pool members can SELECT, authenticated users can INSERT only their own voter_address row — this mirrors on-chain state for fast reads without requiring a chain query on every page load

5. Testing

cargo test coverage for: quorum edge cases (exact threshold, just below/above), double-voting prevention, proposer self-vote rejection, expiry boundary conditions, max-active-proposal enforcement, and CPI execution success/failure paths
Vitest coverage for hook logic and component rendering states (loading, empty, active, executed, expired)
Target ≥90% line/branch coverage on all new code per contribution standards

[DevSolex]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.

[DevSolex]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.