DAO Voting Dashboard

[jonahkoh]

Off-chain + on-chain DAO voting dashboard for BNB Chain with signature-based voting, governance rules, and hybrid architecture.

Features
Core Functionality:

Off-chain gasless voting with SQLite database
Signature-based vote authentication using eth-account
Configurable governance rules (20% quorum, 50% approval threshold)
Mock on-chain integration with governance contracts
FastAPI REST API with 13+ endpoints
Jinja2 web dashboard for creating proposals and casting votes
Governance Engine:

Quorum checking (minimum participation requirement)
Approval threshold validation
Proposal lifecycle management (active → passed/rejected)
Vote tallying with support for FOR/AGAINST/ABSTAIN
Automated proposal closing based on end time
Blockchain Integration:

Web3.py connection to BNB Chain testnet
Cryptographic signature generation and verification
Mock governance contract with proposal and vote functions
Hybrid off-chain/on-chain design for gas optimization
Architecture
Off-Chain Layer (Fast, Free)
├── SQLite Database (proposals, votes)
├── Signature Verification (eth-account)
└── Governance Engine (quorum, threshold)

On-Chain Layer (Immutable, Decentralized)
├── Mock Governance Contract
├── Proposal Sync
└── Vote Verification

Test Results
✅ 39/39 core tests passing:

✅ Blockchain tests (7/7): Signature verification, Web3 connection, mock contract interactions
✅ Contract tests (16/16): Proposal creation, vote submission, finalization logic
✅ Governance tests (16/16): Quorum calculation, approval rates, outcome determination
Test Coverage:

Signature generation and verification with eth-account
Mock contract proposal lifecycle
Governance rule enforcement (quorum, threshold)
Edge cases (no votes, exact thresholds, multiple proposals)
API Endpoints
GET / - Web dashboard home
GET /health - Health check
POST /api/proposals - Create proposal
GET /api/proposals - List proposals
GET /api/proposals/{id} - Get proposal details
POST /api/proposals/{id}/vote - Cast vote
POST /api/proposals/{id}/close - Close proposal
GET /api/proposals/{id}/results - Get results
POST /api/proposals/{id}/sync - Sync to chain

Technical Stack
FastAPI - Modern async web framework
Web3.py 7.0+ - BNB Chain interaction
eth-account - Signature generation/verification
SQLite - Off-chain vote storage
Jinja2 - HTML templating
pytest - Testing framework
BNB Chain Integration
RPC: https://data-seed-prebsc-1-s1.bnbchain.org:8545/
Chain ID: 97 (BNB Smart Chain Testnet)
Signature-based authentication for gasless off-chain voting
Mock contract ABI with getProposal, createProposal, vote functions

Usage Example

Create proposal
POST /api/proposals
{
"title": "Allocate Treasury Funds",
"description": "Proposal to allocate 10,000 BNB",
"creator": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"duration_hours": 168
}

Cast vote with signature
POST /api/proposals/1/vote
{
"voter_address": "0x...",
"vote_choice": "for",
"private_key": "0x..." # Demo only - use wallet in production
}

Educational Value
Demonstrates:

Hybrid off-chain/on-chain governance architecture
Gas-free voting with cryptographic signatures
Quorum and threshold-based decision making
Web3.py integration with BNB Chain
FastAPI REST API design
Comprehensive testing with pytest