db/heromodels/src/models/governance

Governance Model

The governance model provides a robust framework for managing decentralized governance processes, including proposals, voting, and activity tracking.

Core Components

1. Proposal

The central element of the governance model. A Proposal represents a formal suggestion submitted to the community for a vote.

• title & description: The substance of the proposal.
• creator_id: The ID of the user who submitted the proposal.
• status: The current state of the proposal (e.g., Draft, Active, Approved), defined by the ProposalStatus enum.
• options: A Vec<VoteOption> defining the choices voters can select (e.g., "For", "Against", "Abstain").
• vote_start_date & vote_end_date: Timestamps that define the voting period.

2. Ballot

Represents a single vote cast by a user on a specific Proposal.

• user_id: The ID of the voter.
• vote_option_id: The specific VoteOption the user selected.
• shares_count: The voting power or weight of the vote.
• comment: An optional comment from the voter.

3. GovernanceActivity

A detailed record of every significant event that occurs within the governance system. This is crucial for transparency and auditing.

• activity_type: The type of event that occurred (e.g., ProposalCreated, VoteCast), defined by the ActivityType enum.
• actor_id & actor_name: Who performed the action.
• target_id & target_type: The object the action was performed on (e.g., a Proposal).
• title & description: A summary of the activity.

4. AttachedFile

A simple struct to link external documents or files to a proposal, such as technical specifications or legal drafts.

Enums

The model includes several enums to manage the state of proposals, voting, and activities:

• ProposalStatus: Tracks the lifecycle of a proposal (Draft, Active, Approved, Rejected).
• VoteEventStatus: Tracks the status of the voting period (Upcoming, Open, Closed).
• ActivityType: Categorizes different governance actions.
• ActivityStatus: Tracks the status of a recorded activity (Pending, Completed, Failed).

Usage

use heromodels::models::governance::{Proposal, Ballot, VoteOption, ProposalStatus};
use chrono::Utc;

// 1. Create a new proposal
let mut proposal = Proposal::new(
    None, // ID is managed by the database
    "user-123".to_string(),
    "Alice".to_string(),
    "Adopt New Logo".to_string(),
    "Proposal to update the community logo.".to_string(),
    ProposalStatus::Draft,
    vec![],
    None
);

// 2. Add voting options
proposal = proposal.add_option(1, "Approve New Logo", None);
proposal = proposal.add_option(2, "Reject New Logo", None);

// 3. An eligible user casts a vote
// This would typically be done by finding the proposal and then calling cast_vote.
let proposal_after_vote = proposal.cast_vote(
    None, // Ballot ID
    456,  // Voter's user_id
    1,    // Voting for option 1
    100   // With 100 shares/votes
);