# Proposal: Refactor to Proof-of-Authority (PoA) Blockchain Architecture

## Summary

Migrate from a simple in-memory blockchain to a distributed Proof-of-Authority (PoA) blockchain network with multiple validator nodes, a bootnode for peer discovery, and a centralized API server for voter registration and vote submission.

**Change ID**: `refactor-poa-blockchain-architecture`

**Status**: Proposed

**Priority**: High

**Complexity**: High

---

## Business Context

### Problem Statement

Current system uses a simple in-memory blockchain stored in a single FastAPI backend process. This approach has limitations:

1. **No Distribution**: Blockchain stored only in memory on one server - no redundancy
2. **No Consensus**: No mechanism to agree on canonical chain across multiple nodes
3. **Centralized Trust**: Single point of failure - if backend crashes, blockchain is lost
4. **No Verification**: Other parties cannot verify the blockchain independently

### Desired Outcome

Implement a true distributed blockchain network where:
- **Multiple validators** can independently verify votes are recorded correctly
- **Peer discovery** allows new validators to join the network automatically
- **Consensus mechanism** ensures all validators agree on the canonical chain
- **Decentralized verification** - anyone can run a validator to verify election integrity
- **Production-ready** - meets regulatory requirements for transparent, auditable elections

---

## Solution Architecture

### High-Level Design

```
┌─────────────────────────────────────────────────────────────────┐
│                     Docker Network (evoting_network)             │
└─────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ↓                    ↓                    ↓
    ┌─────────┐         ┌─────────┐         ┌─────────┐
    │ Bootnode│         │Validator│         │Validator│
    │(8546)   │◄───────►│   #1    │◄───────►│   #2    │
    │         │         │ (30303) │         │ (30304) │
    └─────────┘         └────┬────┘         └────┬────┘
         │                   │                    │
         └───────────────────┼────────────────────┘
                             │
                             ↓
                    ┌──────────────────┐
                    │   API Server     │
                    │  (FastAPI/8000)  │
                    │- Registration    │
                    │- Vote Submission │
                    │- Results Query   │
                    └────────┬─────────┘
                             │
              ┌──────────────┴──────────────┐
              ↓                             ↓
         ┌─────────┐            ┌──────────────────┐
         │ Database│            │   Frontend UI    │
         │MariaDB  │            │  (Next.js/3000)  │
         │(3306)   │            │                  │
         └─────────┘            └──────────────────┘
```

### Components

#### 1. Bootnode Service (Port 8546)
- **Role**: Peer discovery - helps nodes find each other on the network
- **Technology**: Geth-based (lightweight mode) or custom P2P service
- **Responsibility**:
  - Maintain list of known peers
  - Respond to peer discovery requests
  - Help new nodes bootstrap into the network
- **Data**: Peer information (IP, port, node ID)

#### 2. Validator Nodes (Ports 30303+)
- **Role**: Run the blockchain client, validate blocks, maintain consensus
- **Quantity**: 3 validators (configurable)
- **Technology**: Custom PoA client in Python (FastAPI + custom consensus)
- **Responsibilities**:
  - Maintain local copy of blockchain
  - Validate incoming blocks
  - Participate in PoA consensus
  - Respond to vote verification requests
  - Sync state with peer validators
- **Consensus**: Proof-of-Authority - designated validators sign blocks
  - Only authorized validators can create new blocks
  - Validators must have their public key in genesis block
  - Simple majority consensus (2 of 3 validators must accept)

#### 3. API Server (Port 8000)
- **Role**: Frontend/Registration Authority - handles voter registration and vote submission
- **Technology**: FastAPI (existing backend)
- **Responsibilities**:
  - Voter registration and authentication
  - Issue JWT tokens for authenticated voters
  - Accept encrypted votes from voters
  - Submit votes to validator network via JSON-RPC
  - Query results from validators
  - Serve web interface
- **Note**: Does NOT run a full blockchain node - delegates to validators

#### 4. Database (Port 3306)
- **Role**: Persistent storage for voter data and election metadata
- **Technology**: MariaDB/MySQL (existing)
- **Data**:
  - Voter credentials and profiles
  - Election definitions and candidates
  - Vote metadata (voter_id, election_id, timestamp, ballot_hash)
  - **Note**: Actual encrypted votes stored on blockchain, not in DB

#### 5. Frontend UI (Port 3000)
- **Role**: User interface for voting
- **Technology**: Next.js (existing)
- **Interaction**:
  - Register via API Server
  - Login to get JWT token
  - Submit vote via API Server
  - Query results via API Server
  - View blockchain verification via API Server

---

## Technical Details

### PoA Consensus Mechanism

**Key Features**:
- Authorized set of validators defined in genesis block
- Each validator has a private key and public key stored securely
- Validator creates block by:
  1. Collecting pending votes from vote pool
  2. Computing block hash
  3. Signing block with their private key
  4. Broadcasting to network
- Other validators verify:
  1. Block hash is valid
  2. Signature is valid (matches authorized validator)
  3. Block extends previous block
  4. No double-spending of votes
- Block accepted when majority (2/3) of validators acknowledge it

### Data Flow: Vote Submission

```
1. Voter fills registration form on UI
   │
2. Frontend POSTs to API Server (/api/auth/register)
   │
3. API Server:
   - Validates voter data
   - Creates voter record in database
   - Returns JWT token
   │
4. Voter logs in and submits vote
   │
5. Frontend encrypts vote (ElGamal) + generates ZKP
   │
6. Frontend POSTs encrypted vote to API Server (/api/votes/submit)
   │
7. API Server:
   - Validates voter JWT
   - Checks voter hasn't already voted
   - Calls validator node via JSON-RPC: eth_sendTransaction
   │
8. Vote submitted to blockchain:
   - Validator node receives vote
   - Creates pending block with vote
   - Broadcasts to peer validators
   - Other validators verify and sign
   - Block is committed to chain
   │
9. API Server queries validator for confirmation:
   - eth_getTransactionReceipt
   - eth_blockNumber
   │
10. Returns vote confirmation to frontend
```

### Vote Storage on Blockchain

Each block contains:
```json
{
  "index": 0,
  "prev_hash": "0x000...",
  "timestamp": 1699360000,
  "transactions": [
    {
      "voter_id": "anon-tx-abc123",
      "election_id": 1,
      "encrypted_vote": "0x7f3a...",
      "ballot_hash": "0x9f2b...",
      "proof": "0xabcd...",
      "timestamp": 1699360001
    }
  ],
  "block_hash": "0xdeadbeef...",
  "validator": "0x1234567...",
  "signature": "0x5678..."
}
```

---

## Implementation Phases

### Phase 1: Bootnode Service (Peer Discovery)
- Create lightweight bootnode
- Simple HTTP endpoint for peer discovery
- Track active validator nodes
- **Deliverable**: Working bootnode that validators can register with

### Phase 2: Validator Node Service (Blockchain Client)
- Implement PoA consensus logic
- Block creation and validation
- Peer synchronization
- JSON-RPC interface for API Server communication
- **Deliverable**: 3 validator containers that form a chain

### Phase 3: API Server Integration
- Connect existing API Server to validator network
- Implement JSON-RPC calls for vote submission
- Query validator for results
- **Deliverable**: Votes submitted to blockchain via validator network

### Phase 4: Testing & Documentation
- Test complete voting workflow
- Verify blockchain integrity across validators
- Document deployment and operation
- **Deliverable**: Working distributed blockchain voting system

---

## Technology Choices

### Why Proof-of-Authority?
- **Suitable for this use case**: Small number of known, trusted validators
- **Simpler than PoW**: No energy waste, instant finality
- **Simpler than PoS**: No stake or locking mechanisms needed
- **Fast consensus**: Validators can reach agreement quickly
- **Transparent**: Validator set is public and known

### Why Not Geth/Ethereum?
- **Could use Geth**, but overkill for this use case
- **Learning value**: Building custom PoA teaches blockchain fundamentals
- **Lightweight**: Custom implementation is simpler and more understandable
- **Control**: Full control over consensus rules and behavior

### Why Custom P2P Network?
- **Isolation**: Run entirely on private Docker network
- **Simplicity**: Don't need complex protocol (libp2p)
- **Control**: Define exactly what peers need to communicate

---

## Benefits

### For Users
- ✅ **Transparency**: Can verify votes recorded on blockchain
- ✅ **Auditability**: Complete chain of custody for each vote
- ✅ **Fairness**: No central authority can change results

### For System
- ✅ **Redundancy**: Multiple validators prevent single point of failure
- ✅ **Consensus**: Agreement across validators ensures accuracy
- ✅ **Scalability**: Easy to add more validators if needed
- ✅ **Regulatory Compliance**: Meets transparency requirements for elections

### For Project
- ✅ **Educational**: Demonstrates real blockchain implementation
- ✅ **Production-Ready**: True distributed system, not just prototype
- ✅ **Future-Proof**: Foundation for adding more features (e.g., multiparty computation)

---

## Risks & Mitigation

### Risk 1: Byzantine Validator
**Problem**: Validator signs invalid blocks or refuses to participate

**Mitigation**:
- Validator set is known and trusted
- Invalid blocks rejected by other validators
- Watchdog service monitors validator health
- Can remove misbehaving validator by governance (future work)

### Risk 2: Network Partition
**Problem**: Validators split into groups that can't communicate

**Mitigation**:
- Private Docker network prevents partition in single-host setup
- Each validator boots from bootnode to ensure connectivity
- Heartbeat mechanism detects disconnections
- Recovery: rejoin and resync on network restoration

### Risk 3: Byzantine Client (API Server)
**Problem**: API Server submits fraudulent votes to blockchain

**Mitigation**:
- Votes encrypted before reaching API Server
- Blockchain validates vote format and proof
- Any party can run a validator to verify votes
- Audit trail preserved on immutable blockchain

### Risk 4: Performance
**Problem**: Consensus bottleneck limits vote submission rate

**Mitigation**:
- 3-validator PoA can handle thousands of votes per second
- Optional: Increase validator count if needed
- Optional: Implement transaction batching

---

## Success Criteria

1. ✅ Bootnode operational - validators can discover each other
2. ✅ Validators form stable network - all 3 stay synchronized
3. ✅ Votes recorded on blockchain - each vote creates a block
4. ✅ Consensus working - validators agree on canonical chain
5. ✅ API Server integration - votes submitted and confirmed
6. ✅ Complete workflow - registration → voting → verification → results
7. ✅ Docker deployment - entire system deployable with `docker compose up`
8. ✅ Documentation - clear operational procedures for running and maintaining system

---

## Effort Estimate

| Phase | Task | Complexity | Effort |
|-------|------|-----------|--------|
| 1 | Bootnode service | Medium | 2-3 days |
| 2 | Validator node service | High | 5-7 days |
| 3 | API Server integration | Medium | 2-3 days |
| 4 | Testing & documentation | Medium | 2-3 days |
| **Total** | | **High** | **~12-16 days** |

---

## Dependencies

### External
- Docker & Docker Compose
- Python 3.12+
- Existing FastAPI backend
- Existing MariaDB database

### Internal
- ElGamal encryption (existing crypto module)
- Dilithium signatures (existing crypto module)
- Blockchain hashing (existing utilities)

---

## Scope & Constraints

### In Scope
- Bootnode for peer discovery
- 3 validator nodes with PoA consensus
- Custom blockchain client in Python
- JSON-RPC interface for API communication
- Docker Compose orchestration
- Complete voting workflow via distributed blockchain

### Out of Scope (Future Work)
- Geth/Ethereum compatibility
- Sharding or horizontal scaling
- Multiparty computation for secret sharing
- Zero-knowledge proof verification (already implemented)
- Governance mechanisms for validator management
- Persistent chain storage (database integration)

---

## Next Steps

1. **Review & Approval**: Get stakeholder approval for architecture
2. **Design**: Create detailed technical design document
3. **Implementation**: Build in phases with testing at each step
4. **Deployment**: Deploy to production with monitoring
5. **Documentation**: Create operational runbooks

---

## Related Documents

- `design.md` - Detailed technical design of PoA implementation
- `tasks.md` - Implementation checklist and dependencies
- `specs/` - Specification changes for blockchain architecture