Voting Module Documentation

Overview

The Voting module provides functionality for decentralized voting within the Synnq ecosystem. It allows users to submit proposals, vote on them, and finalize the results. This module ensures that only eligible participants can vote and that each vote is accurately recorded and counted. The state of each proposal is tracked from submission through to final approval or rejection.

Components and Responsibilities

1. Proposal Submission

The Voting module allows users to submit proposals for consideration by the network. A proposal includes details such as the proposer’s identity, a description, and the duration for which voting will be open.

• Submit Proposal: Creates a new proposal with an assigned ID, initializes its state to Pending, and sets the voting deadline based on the current time and the provided voting period.

2. Voting on Proposals

Users can cast their vote on a proposal. Votes can either be in favor or against the proposal. The module ensures that each wallet can only vote once on a particular proposal.

• Vote on Proposal: Allows a user to vote on a proposal. The module checks that the voter hasn’t already voted and records the vote, updating the proposal’s vote count accordingly.
• Check if Already Voted: Verifies if a specific wallet address has already voted on a particular proposal to prevent double voting.

3. Proposal Finalization

After the voting period ends, the proposal’s outcome is determined based on the number of votes for and against it. The proposal is then marked as either Approved or Rejected.

• Finalize Proposals: Iterates over all proposals, checking whether their voting deadline has passed. For each proposal, if the voting period has ended, it determines the outcome based on the vote counts and updates the proposal’s state accordingly.

4. State Management

The module tracks the state of each proposal using a defined VoteState enum, which can be Pending, Approved, or Rejected. This ensures clarity in the current status of each proposal and allows for easy querying and display of results.

• Vote State Enum: Defines the possible states of a proposal (Pending, Approved, Rejected).

Use Cases and Workflows

Submitting a Proposal

1. Proposal Creation:

   • A user submits a proposal with a description and a specified voting period.
   • The module assigns a unique ID to the proposal, calculates the voting deadline, and stores the proposal in the storage system.

2. Logging and Feedback:

   • The submission is logged, and the user is provided with the proposal ID for reference.

Voting on a Proposal

1. Eligibility Check:

   • When a user attempts to vote, the module first verifies if the user’s wallet has already voted on the proposal.
   • If the wallet has already voted, the vote is rejected with an appropriate error message.

2. Recording the Vote:

   • If the user is eligible, the vote is recorded. The proposal’s votes_for or votes_against count is updated based on the vote.
   • The voter’s wallet address is added to a voted_wallets set to prevent duplicate voting.

3. Storage and Logging:

   • The updated proposal is saved back to storage, and the action is logged for auditing purposes.

Finalizing Proposals

1. Checking Deadlines:

   • The module periodically checks all pending proposals to see if their voting deadlines have passed.

2. Determining Outcome:

   • For each proposal where the voting period has ended, the module compares the votes_for and votes_against counts.
   • The proposal is then marked as Approved if it received more votes in favor, or Rejected if it received more votes against.

3. Updating Proposal State:

   • The final state of each proposal is updated in the storage system, and the finalization action is logged.

Error Handling and Logging

The Voting module includes error handling to manage scenarios such as invalid private keys, duplicate voting attempts, and attempts to vote on non-existent proposals. All significant actions, including proposal submissions, voting, and finalization, are logged to ensure transparency and traceability.