Ballot System Smart Contract

A secure and flexible ballot system implemented on the Stacks blockchain using Clarity smart contract language.

Overview

This smart contract enables decentralized ballot creation and management with weighted participant influence, customizable ballot durations, and automated result calculation. It supports up to 10 choices per ballot and includes comprehensive access controls.

Features

• Flexible Ballot Creation: Create ballots with custom subjects, descriptions, and up to 10 choices
• Weighted Participation: Assign different influence levels to participants (default: 1)
• Time-Based Ballots: Set custom duration using block heights
• Threshold Requirements: Minimum participation requirements for valid results
• Automated Results: Automatic winner determination when ballots conclude
• Access Control: Role-based permissions for ballot management
• Duplicate Prevention: Ensures one ballot per participant per ballot

Core Functions

Public Functions

launch-ballot

Creates a new ballot with specified parameters.

(launch-ballot subject details choices duration threshold-count)

• subject: Ballot title (max 256 characters)
• details: Detailed description (max 1024 characters)
• choices: List of up to 10 choice options (max 64 characters each)
• duration: Ballot duration in blocks
• threshold-count: Minimum total ballots required for validity

cast-ballot

Allows participants to cast their ballot for a specific choice.

(cast-ballot ballot-id choice-idx)

• ballot-id: Unique identifier of the ballot
• choice-idx: Index of the chosen option (0-9)

conclude-ballot

Finalizes a ballot and calculates results after the ballot period ends.

(conclude-ballot ballot-id)

set-participant-influence

Sets the ballot influence/weight for a participant (admin only).

(set-participant-influence participant influence)

cancel-ballot

Cancels an active ballot (initiator or admin only).

(cancel-ballot ballot-id)

transfer-admin-rights

Transfers system administration rights (current admin only).

(transfer-admin-rights new-admin)

Read-Only Functions

• get-ballot-counter(): Returns total number of ballots created
• get-ballot-info(ballot-id): Retrieves complete ballot information
• get-participant-ballot(ballot-id, participant): Gets participant's ballot choice
• get-choice-tally(ballot-id, choice-idx): Returns tally for specific choice
• get-participant-influence(participant): Gets participant's ballot weight
• get-ballot-outcome(ballot-id): Retrieves finalized ballot results
• has-participant-voted(ballot-id, participant): Checks if participant has voted
• is-ballot-active(ballot-id): Checks if ballot is currently accepting ballots

Data Structures

Ballots Map

Stores complete ballot information including subject, details, choices, timing, and status.

Ballots Cast Map

Records each participant's ballot choice with ballot ID and participant address.

Choice Tallies Map

Maintains running tallies for each choice option in each ballot.

Participant Influence Map

Stores custom influence weights for participants (default: 1).

Ballot Outcomes Map

Stores finalized results including winner, tallies, and total participation.

Error Codes

• ERR-ACCESS-DENIED (100): Insufficient permissions
• ERR-DUPLICATE-BALLOT (101): Participant already voted
• ERR-BALLOT-NOT-EXISTS (102): Ballot ID not found
• ERR-BALLOT-EXPIRED (103): Ballot period has ended
• ERR-BALLOT-STILL-ACTIVE (104): Cannot conclude active ballot
• ERR-INVALID-CHOICE (105): Choice index out of range
• ERR-FORBIDDEN-CALLER (106): Unauthorized function caller
• ERR-THRESHOLD-NOT-REACHED (107): Minimum participation not met
• ERR-NO-CHOICES-PROVIDED (108): Empty choices list provided
• ERR-INVALID-INFLUENCE (109): Invalid participant influence value

Usage Example

;; Launch a ballot
(contract-call? .ballot-system launch-ballot 
  u"Should we upgrade the protocol?" 
  u"Vote on whether to implement the new protocol upgrade"
  (list u"Yes" u"No" u"Abstain")
  u1000  ;; 1000 blocks duration
  u10)   ;; minimum 10 total ballots

;; Cast a ballot (choice 0 = "Yes")
(contract-call? .ballot-system cast-ballot u0 u0)

;; Conclude ballot after period ends
(contract-call? .ballot-system conclude-ballot u0)

Security Features

• Single Ballot Per Participant: Prevents duplicate ballots through mapping checks
• Time-Based Validation: Ballots only accept participation during active periods
• Access Control: Admin-only functions for system management
• Threshold Validation: Ensures minimum participation for legitimate results
• Input Validation: Comprehensive error handling and parameter validation