CIA/e-voting-system/openspec/changes/refactor-poa-blockchain-architecture/tasks.md

Implementation Tasks: PoA Blockchain Architecture

Phase 1: Bootnode Service

Task 1.1: Create Bootnode Project Structure

• Create bootnode/ directory
• Create bootnode/bootnode.py with FastAPI app
• Create bootnode/requirements.txt
• Create docker/Dockerfile.bootnode

Task 1.2: Implement Bootnode Service

• FastAPI endpoints:
  • GET /health - Health check
  • POST /register_peer - Register validator
  • GET /discover - Discover peers
  • GET /peers - List all peers
• In-memory peer registry (dict)
• Peer expiration/cleanup logic
• Error handling and logging

Task 1.3: Docker Integration for Bootnode

• Add bootnode service to docker-compose.yml
• Configure port 8546
• Add health check
• Configure logging

Task 1.4: Test Bootnode

• Unit test peer registration
• Unit test peer discovery
• Integration test with Docker
• Manual test with curl

Deliverable: Working bootnode that validators can discover

---

Phase 2: Validator Node Service

Task 2.1: Create Validator Project Structure

• Create validator/ directory
• Create validator/validator.py with PoA client
• Create validator/consensus.py with consensus logic
• Create validator/crypto.py with signing utilities
• Create validator/p2p.py with P2P communication
• Create validator/rpc.py with JSON-RPC interface
• Create validator/requirements.txt
• Create docker/Dockerfile.validator

Task 2.2: Implement Block Data Structure

• Define Block class with fields:
  • index
  • prev_hash
  • timestamp
  • transactions (list)
  • block_hash
  • validator (who created)
  • signature (of block_hash)
• Define Transaction structure for votes
• Implement block serialization/deserialization

Task 2.3: Implement Genesis Block

• Create genesis block factory
• Hardcode authorized validator list
• Generate genesis block hash
• Store in validator initialization

Task 2.4: Implement Block Creation (PoA)

• Implement should_create_block() - round-robin logic
• Implement create_block() method:
  • Take pending transactions
  • Calculate block hash
  • Sign with validator private key
  • Return signed block
• Implement pending transaction pool (queue)
• Start block creation task (every 5 seconds)

Task 2.5: Implement Block Validation

• Verify block hash is correct
• Verify signature is from authorized validator
• Verify prev_hash matches previous block
• Verify transactions are valid
• Verify block extends chain (no forks)
• Implement validate_block() method

Task 2.6: Implement Chain Management

• Store blockchain as list of blocks
• Implement chain immutability check
• Implement chain synchronization with peers
• Handle out-of-order blocks (buffer and retry)
• Implement fork resolution (longest valid chain)

Task 2.7: Implement P2P Network

• Create P2P message types:
  • peer_hello
  • sync_request
  • sync_response
  • new_block
  • new_transaction
• Implement P2P listen (asyncio server)
• Implement P2P client (connect to peers)
• Broadcast new blocks to peers
• Broadcast new transactions to peers
• Handle peer disconnections and reconnections

Task 2.8: Implement Bootnode Registration

• On startup, register with bootnode
• Discover other validators from bootnode
• Connect to discovered validators
• Periodic heartbeat to bootnode

Task 2.9: Implement Chain Synchronization

• On startup or after disconnect, sync with peers
• Request blocks from peer
• Validate received blocks
• Add to local chain if valid
• Request missing blocks if gap detected

Task 2.10: Implement JSON-RPC Interface

• eth_sendTransaction - submit vote
• eth_getTransactionReceipt - get vote confirmation
• eth_blockNumber - get latest block number
• eth_getBlockByNumber - get block by number
• eth_chainId - get chain ID

Task 2.11: Implement Cryptographic Operations

• Generate validator key pair (ECDSA or RSA)
• Load private key from environment
• Sign blocks with private key
• Verify signatures with public key
• Store public keys for all validators in genesis

Task 2.12: Docker Integration for Validators

• Create docker/Dockerfile.validator
• Add 3 validator services to docker-compose.yml
• Configure ports (8001-8003, 30303-30305)
• Configure environment variables (NODE_ID, PRIVATE_KEY, etc.)
• Add health checks
• Configure logging

Task 2.13: Test Validator Nodes

• Unit test block creation
• Unit test block validation
• Unit test signature verification
• Unit test JSON-RPC endpoints
• Integration test: 3 validators forming chain
• Integration test: block propagation through network
• Integration test: chain synchronization after disconnect
• Manual test with curl/Python client

Deliverable: 3 working validator nodes that reach consensus

---

Phase 3: API Server Integration

Task 3.1: Create Blockchain Client

• Implement BlockchainClient class
• Initialize with list of validator URLs
• Implement send_transaction() via JSON-RPC
• Implement get_transaction_receipt() via JSON-RPC
• Implement failover logic (try next validator if one fails)
• Implement retry logic with exponential backoff

Task 3.2: Update Vote Submission Endpoint

• Modify POST /api/votes/submit in backend/routes/votes.py
• Create blockchain client instance
• Format vote as transaction
• Call blockchain_client.send_transaction()
• Return transaction hash to frontend
• Handle blockchain submission errors gracefully

Task 3.3: Update Vote Status Endpoint

• Modify GET /api/votes/status to check blockchain
• Query validator for transaction receipt
• Return confirmation status to frontend
• Handle not-yet-confirmed transactions

Task 3.4: Create Results Aggregation

• Implement get_election_results() function
• Query all blocks from validator
• Sum votes by candidate
• Return results with blockchain verification

Task 3.5: Add Configuration

• Add validator URLs to environment variables
• Load from .env file
• Validate configuration on startup
• Log validator endpoints

Task 3.6: Update Docker Compose

• Add VALIDATOR_URLS to api-server service
• Add depends_on for validators
• Ensure api-server starts after validators are ready

Task 3.7: Test API Integration

• Unit test blockchain client
• Unit test vote submission with mocked validators
• Integration test: submit vote → blockchain → confirmation
• Integration test: query results from blockchain
• End-to-end test: registration → voting → results

Deliverable: API Server successfully submits votes to blockchain

---

Phase 4: Frontend Integration

Task 4.1: Update Voting Component

• Modify frontend/components/voting-interface.tsx
• Show transaction hash after submission
• Display "pending" status while waiting for block
• Poll for transaction receipt confirmation
• Display "confirmed" once vote is in block

Task 4.2: Add Transaction Tracking

• Create transaction history view
• Show transaction hash
• Show block number (once confirmed)
• Show blockchain proof

Task 4.3: Add Blockchain Verification UI

• Create blockchain viewer page
• Fetch and display blocks from validator
• Show vote transactions in each block
• Verify chain integrity (hash chain)
• Display validation status

Task 4.4: Update Results Page

• Modify results page to query blockchain
• Display vote counts from blockchain
• Show number of confirmed votes
• Display pending votes

Task 4.5: Test Frontend

• Manual test voting workflow
• Manual test transaction tracking
• Manual test blockchain verification
• Check error handling

Deliverable: Frontend displays transaction tracking and blockchain verification

---

Phase 5: Testing & Documentation

Task 5.1: Unit Tests

• Test bootnode peer registration
• Test validator block creation
• Test validator block validation
• Test validator signature verification
• Test blockchain client JSON-RPC calls
• Test API vote submission

Task 5.2: Integration Tests

• Test 3-validator network startup
• Test block creation and propagation
• Test chain synchronization
• Test complete voting workflow
• Test blockchain verification

Task 5.3: End-to-End Tests

• Docker: Full system startup
• Docker: All services healthy
• Docker: Register voter
• Docker: Submit vote
• Docker: Verify vote on blockchain
• Docker: Query results
• Docker: System shutdown

Task 5.4: Documentation

• Write deployment guide
• Write operational runbook
• Write troubleshooting guide
• Document configuration options
• Document performance characteristics
• Update project README

Task 5.5: Security Review

• Review key management
• Review signature verification
• Review vote encryption
• Review network communication (HTTPS/TLS)
• Identify potential vulnerabilities
• Document security assumptions

Deliverable: Complete tested system with documentation

---

Task Dependencies

Phase 1: Bootnode
  Task 1.1 → Task 1.2 → Task 1.3 → Task 1.4
    ↓ (Bootnode works)

Phase 2: Validators (depends on Bootnode)
  Task 2.1 → Task 2.2 → Task 2.3
    ↓
  Task 2.4 (parallel with 2.5, 2.6)
  Task 2.5 (parallel with 2.4, 2.6)
  Task 2.6 (parallel with 2.4, 2.5)
    ↓
  Task 2.7 → Task 2.8 → Task 2.9
    ↓
  Task 2.10 (parallel with 2.11)
  Task 2.11 (parallel with 2.10)
    ↓
  Task 2.12 → Task 2.13
    ↓ (Validators work)

Phase 3: API Integration (depends on Validators)
  Task 3.1 → Task 3.2 → Task 3.3
    ↓
  Task 3.4 (parallel with 3.5)
  Task 3.5 (parallel with 3.4)
    ↓
  Task 3.6 → Task 3.7
    ↓ (API integration works)

Phase 4: Frontend (depends on API Integration)
  Task 4.1 → Task 4.2 → Task 4.3 → Task 4.4 → Task 4.5
    ↓ (Frontend works)

Phase 5: Testing (depends on all phases)
  Task 5.1 (parallel with 5.2)
  Task 5.2 (parallel with 5.1)
    ↓
  Task 5.3 (depends on 5.1, 5.2)
    ↓
  Task 5.4 (parallel with 5.5)
  Task 5.5 (parallel with 5.4)

---

Success Criteria

Phase 1 Completion

• ✅ Bootnode responds to health checks
• ✅ Bootnode accepts peer registration
• ✅ Bootnode returns peer list
• ✅ Docker container starts and runs healthily

Phase 2 Completion

• ✅ All 3 validators start successfully
• ✅ Validators discover each other via bootnode
• ✅ Validators form consensus (same blockchain)
• ✅ Validators can create blocks (round-robin)
• ✅ Validators can receive and validate blocks
• ✅ JSON-RPC interface responds to requests
• ✅ All Docker containers healthy

Phase 3 Completion

• ✅ API Server can submit votes to validators
• ✅ Votes appear in blockchain blocks
• ✅ Transaction receipts confirm block inclusion
• ✅ API returns transaction hash to client
• ✅ Failover works if one validator is down
• ✅ All error cases handled gracefully

Phase 4 Completion

• ✅ Frontend shows transaction hash after vote
• ✅ Frontend displays "pending" while confirming
• ✅ Frontend displays "confirmed" once in block
• ✅ Blockchain viewer shows all blocks
• ✅ Blockchain viewer shows all votes
• ✅ Results page shows vote counts from blockchain

Phase 5 Completion

• ✅ All unit tests pass
• ✅ All integration tests pass
• ✅ All end-to-end tests pass
• ✅ Full voting workflow works
• ✅ Blockchain integrity verified
• ✅ Documentation complete
• ✅ Security review completed

---

Effort Estimates

Phase	Task	Effort
1	Bootnode	1-2 days
2	Validators	5-7 days
3	API Integration	2-3 days
4	Frontend	1-2 days
5	Testing & Docs	2-3 days
Total		12-17 days

---

Risk Mitigation

Risk: Complex P2P Protocol

Mitigation: Start simple with HTTP instead of custom TCP protocol

Risk: Byzantine Validator

Mitigation: 2-of-3 consensus with validator monitoring

Risk: Performance Issues

Mitigation: Implement performance testing at each phase

Risk: Missing Requirements

Mitigation: Review design at end of phase 2 before proceeding

---

Sign-Off Checklist

• Project manager approval
• Security team approval
• Architecture review complete
• Test plan approved
• Deployment plan approved
• Documentation plan approved