# 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