e-Participatory Budgeting (e-PB) System

Blockchain-based e-Participatory Budgeting system with an integrated token economy for conflict management arising from corruption investigations. Built as a proof-of-concept for Estonia's e-PB system.

Tech Stack

Layer	Technology
Blockchain	Solidity 0.8.28, OpenZeppelin v5, Hardhat
Backend	Node.js, Express, TypeScript, ethers.js v6
Frontend	Next.js 14 (App Router), React 18, Tailwind CSS, Recharts
Storage	IPFS via Pinata (mock in-memory store for PoC)
Identity	Simulated Estonian e-ID (Isikukood) verification
Wallet	MetaMask (Hardhat local network, chain ID 31337)
Containerization	Docker, Docker Compose
Token Standard	ERC-20 (ePBU utility token), ERC-20 non-transferable (Governance), ERC-721 Soulbound (Reputation)

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                      Frontend (Next.js 14)                        │
│  Home │ Register │ Ideas │ Voting │ Feedback │ Rewards & Transit  │
│  Fund Tracking │ Disputes │ Metrics │ Admin Panel                 │
├──────────────────────────────────────────────────────────────────┤
│                      Backend (Express + TypeScript)                │
│  Auth │ PB Lifecycle │ Fund Tracking │ Disputes │ Redemption      │
│  Metrics │ Admin │ Token Rewards (mintReward)                     │
├──────────────────────────────────────────────────────────────────┤
│                     Smart Contracts (Solidity)                     │
│  ePBUtilityToken │ GovernanceToken │ ReputationSBT                │
│  CitizenRegistry │ PBLifecycle │ FundAllocation                   │
│  DisputeRegistry │ MediationEngine │ ArbitrationDAO               │
│  TokenRedemption                                                  │
├──────────────────────────────────────────────────────────────────┤
│                    Hardhat Local Network (31337)                   │
└──────────────────────────────────────────────────────────────────┘

Smart Contracts

Contract	Purpose
ePBUtilityToken	ERC-20 participation reward token (SUBMIT=10, DISCUSS=5, VOTE=5, FEEDBACK=3, DISPUTE=50 ePBU)
GovernanceToken	Non-transferable ERC-20 for arbitration voting weight
ReputationSBT	Soulbound ERC-721 badges for milestones
CitizenRegistry	Role-based access with simulated Estonian e-ID (Isikukood)
PBLifecycle	7-stage PB process management
FundAllocation	Milestone-based fund release with audit trail
DisputeRegistry	Dispute filing with token staking and evidence
MediationEngine	Automated first-pass resolution
ArbitrationDAO	DAO-based arbitration with whistleblower rewards
TokenRedemption	Redeem ePBU tokens for public transport discount vouchers

Municipalities

The system supports 5 Estonian municipalities:

• Tallinn
• Tartu
• Rapla
• Saue
• Lääne-Nigula

User Roles

Role	Access
Citizen	Submit ideas, discuss, vote, give feedback, redeem rewards
City Council	Start/advance PB cycles, manage ideas, create projects
Expert Evaluator	Score and evaluate submitted ideas
Auditor	Monitor fund allocation and milestone approvals
Mediator	Manage and resolve disputes

All roles require Estonian ID (Isikukood) verification.

ePBU Token Reward System

Citizens earn ePBU tokens for participating:

Action	Reward
Submit idea	10 ePBU
Post comment	5 ePBU
Cast vote	5 ePBU
Give feedback	3 ePBU
Validated dispute	50 ePBU

Token Redemption (Public Transport Discounts)

Earned tokens can be redeemed for ISIC-style discounts on Estonian regional transport:

Route	Cost	Discount
Tallinn-Tartu Express (single)	15 ePBU	50% off
Tallinn-Tartu Express (10-trip pass)	100 ePBU	50% off
Tallinn-Parnu Regional (single)	12 ePBU	50% off
Tartu-Viljandi Local (single)	8 ePBU	50% off
Tallinn City Transport (1-day pass)	20 ePBU	Free

Setup & Run

Option 1: Docker (recommended)

git clone https://github.com/mustafa-1367/epb-system.git
cd epb-system/epb-system
docker compose up --build

This starts all 3 services automatically:

• Hardhat node on port 8545 (compiles + deploys 10 contracts)
• Backend API on port 3001
• Frontend on port 3000

Open http://localhost:3000 in your browser.

Option 2: Manual Setup

Prerequisites

• Node.js 18+
• MetaMask browser extension

1. Smart Contracts

cd epb-system
npm install

# Compile contracts
npx hardhat compile

# Run tests
npx hardhat test

# Start local node
npx hardhat node

# Deploy (in another terminal)
npx hardhat run deploy/deploy.ts --network localhost

2. Backend

cd backend
npm install
npm run dev

3. Frontend

cd frontend
npm install
npm run dev

Visit http://localhost:3000

4. MetaMask Setup

1. Add Hardhat network: RPC http://127.0.0.1:8545, Chain ID 31337
2. Import Hardhat test accounts using private keys from the Hardhat node output

Run Evaluation Simulation

npx hardhat run simulation/evaluate.ts --network hardhat

Runs a full PB cycle with 55 citizens and 5 corruption scenarios.

PB Lifecycle Stages

1. Budget Determination - Municipality sets total PB budget
2. Idea Submission - Citizens submit proposals (earn 10 ePBU)
3. Public Discussion - Comment and like/unlike ideas (earn 5 ePBU)
4. Expert Evaluation - Committee of experts score ideas (-100 to 100)
5. Voting - Citizens vote, max 3 per cycle (earn 5 ePBU)
6. Implementation - Milestone-based fund release with audit trail
7. Feedback - Citizens rate implemented proposals (earn 3 ePBU)

Conflict Resolution Flow

Dispute Filed (stake ePBU tokens)
    │
    ▼
MediationEngine (automated rules check)
    │
    ├── Auto-resolved → RESOLVED
    │
    ├── Committee vote (≥2/3 supermajority)
    │       ├── Validated → RESOLVED + stake returned + 50 ePBU reward
    │       ├── Rejected → RESOLVED + stake slashed
    │       └── Deadlocked → ESCALATED
    │
    └── ArbitrationDAO (5 random arbitrators)
            ├── Validated → penalties executed + whistleblower reward
            ├── Rejected → stake slashed
            └── Deadlocked → full DAO vote

Evaluation Metrics

The simulation measures:

• Detection rate: % of corruption scenarios detected
• Resolution time: Time from filing to resolution
• Participation rate: Actions per citizen
• Token distribution fairness: Gini coefficient
• Fund tracking accuracy: Blockchain provides 100% accuracy
• Transparency index: Composite score (event coverage, fund traceability, dispute resolution, participation openness)

Project Structure

epb-system/
├── contracts/           # 10 Solidity smart contracts
├── test/                # Hardhat tests
├── deploy/              # Deployment scripts
├── simulation/          # Evaluation simulation
├── docker/              # Docker configuration
│   ├── hardhat/         # Blockchain node container
│   ├── backend/         # API server container
│   └── frontend/        # Web app container
├── docker-compose.yml   # One-command deployment
├── backend/
│   └── src/
│       ├── routes/      # API endpoints (auth, pb, disputes, redemption, admin, metrics)
│       ├── services/    # Blockchain service (ethers.js)
│       ├── middleware/   # Auth middleware
│       └── utils/       # IPFS utilities
└── frontend/
    └── src/
        ├── app/         # Next.js pages (13 routes)
        ├── components/  # UI + feature components
        ├── context/     # Role & verification contexts
        ├── hooks/       # Wallet hook (MetaMask)
        └── lib/         # API client + utilities

License

ISC