Skip to content

ARCHITECTURE-SUMMARY.md

Latest commit

 

History

History
202 lines (158 loc) · 7.76 KB

ARCHITECTURE-SUMMARY.md

File metadata and controls

202 lines (158 loc) · 7.76 KB

Liquid Democracy on Secret Network

Architecture Summary v1.0

Overview

A privacy-preserving Liquid Democracy platform built on Secret Network, enabling organizations to conduct secure, delegated voting with the following key features:

Feature Description
Vote Privacy Individual votes encrypted, only final results public
Delegation Members can delegate votes to trusted representatives
Override Delegators can review and override trustee votes in Confirmation phase
Schulze Voting Ranked-choice voting with Condorcet winner calculation

Tech Stack

Layer Technology
Frontend Next.js 14+, TypeScript, Tailwind CSS
Blockchain SDK SecretJS
Wallet Keplr, MetaMask
Smart Contracts Rust + Secret CosmWasm
Content Storage IPFS
Network Secret Network (testnet: pulsar-3, mainnet: secret-4)

System Components

Smart Contracts (6 total)

Contract Purpose
Registry Global config, contract deployment, admin management
Unit Organization management, member privileges
Area Topic/department containers with policies
Issue Issue lifecycle, initiatives, drafts, supporters
Voting Schulze ranked-choice voting, results calculation
Delegation Delegation chains at unit/area/issue levels

Frontend Pages

Page Function
Dashboard Member overview, active issues, delegations
Unit Management Admin: members, areas, policies
Area View Browse issues, create initiatives
Issue Detail View/create initiatives, drafts, support
Voting Cast ranked-choice ballot
Confirmation Review trustee votes, override if needed
Results Visualize voting outcomes

Issue Lifecycle (6 Phases)

┌─────────────┐    ┌─────────────┐    ┌──────────────┐
│  ADMISSION  │───>│ DISCUSSION  │───>│ VERIFICATION │
│  Gather     │    │  Refine     │    │   Confirm    │
│  Supporters │    │  Drafts     │    │   Support    │
└─────────────┘    └─────────────┘    └──────────────┘
                                              │
                                              v
┌─────────────┐    ┌─────────────┐    ┌──────────────┐
│   CLOSED    │<───│CONFIRMATION │<───│   VOTING     │
│  Results    │    │  Delegators │    │  Cast Ranked │
│  Final      │    │  Can Override│    │  Ballots     │
└─────────────┘    └─────────────┘    └──────────────┘

Phase Details

Phase Duration Key Actions
Admission Configurable Gather supporters to meet quorum threshold
Discussion Configurable Debate, refine drafts, add suggestions
Verification Configurable Final supporter confirmation
Voting Configurable Trustees and direct voters cast ranked ballots
Confirmation Configurable Delegators review trustee votes, can override
Closed Final Results published, winner determined

Finalized Design Decisions

Decision Choice Rationale
Delegation Privacy Private by default, optionally public User choice for accountability
Phase Transitions External relayer (primary) Reliable timing, user-triggered as backup
Content Moderation Off-chain reporting Keep blockchain for decisions only
Vote Weight Snapshot at Voting phase start Prevents manipulation, simpler
Multi-Unit Single deployment (multi-tenant) Simpler for MVP, can isolate later
Confirmation Phase ✅ Included in V1 Core LiquidFeedback feature for trust

Privacy Model

Data Visibility
Member privileges Public within unit
Draft content Public (stored on IPFS)
Supporter list Private until verification phase
Delegations Private by default (optionally public)
Individual votes Always private (encrypted)
Trustee votes Visible ONLY to their delegators, ONLY during Confirmation
Final results Public after Closed phase

Confirmation Phase - Vote Override Flow

The Confirmation phase ensures delegators can verify their trustee's vote:

VOTING PHASE                    CONFIRMATION PHASE              CLOSED
     │                                  │                          │
     │  Trustees cast votes             │  Delegators review       │  Results
     │  (includes delegated weight)     │  Can see trustee vote    │  finalized
     │                                  │  Can override if unhappy │
     v                                  v                          v
┌──────────┐                    ┌──────────────┐            ┌───────────┐
│ Vote     │ ──────────────────>│ Confirmation │ ──────────>│  Closed   │
│ Cast     │                    │ Period       │            │  Results  │
└──────────┘                    └──────────────┘            └───────────┘
                                       │
                                       │ Delegator queries:
                                       │ "How did my trustee vote?"
                                       │
                                       v
                                ┌──────────────┐
                                │ If unhappy:  │
                                │ OVERRIDE     │
                                │ Cast own vote│
                                └──────────────┘

MVP Implementation Roadmap

Phase 1: Core Infrastructure

  • Registry Contract development
  • Unit Contract with member management
  • Frontend with wallet connection (Keplr/MetaMask)
  • Contract deployment scripts

Phase 2: Governance Core

  • Area Contract with policy management
  • Issue Contract with phase state machine
  • Initiative/Draft creation
  • Supporter system with quorum checking

Phase 3: Voting System

  • Voting Contract with Schulze algorithm
  • Delegation Contract and chain resolution
  • Snapshot mechanism at voting start
  • Confirmation phase with override capability

Phase 4: Production Polish

  • Event indexer for fast queries
  • IPFS content integration
  • External relayer for phase transitions
  • Security audit

Diagrams

See /plans/diagrams/ folder for draw.io files:

  • system-overview.drawio - High-level system architecture
  • contract-hierarchy.drawio - Smart contract relationships
  • issue-lifecycle.drawio - Phase state machine
  • voting-flow.drawio - Vote casting and confirmation flow

Quick Reference: Key Interactions

Create Initiative

Frontend → Unit.CheckPrivilege → IPFS.Upload → Issue.CreateInitiative

Cast Vote (during Voting phase)

Frontend → Delegation.GetWeight → Voting.CastVote → (encrypted storage)

Override Vote (during Confirmation phase)

Frontend → Voting.GetTrusteeVote → (user reviews) → Voting.OverrideVote

Finalized: January 2026
⚡