CIA/e-voting-system/.claude/POA_QUICK_START.md

PoA Network Quick Start Guide

Starting the System

1. Build and Start All Services

cd /home/sorti/projects/CIA/e-voting-system

# Build and start (first time)
docker compose up -d --build

# Or just start (if already built)
docker compose up -d

2. Wait for Services to Be Ready

# Check status
docker compose ps

# Expected output:
# CONTAINER ID  IMAGE              STATUS              PORTS
# ...           bootnode           Up (healthy)        8546->8546
# ...           validator-1        Up (healthy)        8001->8001, 30303->30303
# ...           validator-2        Up (healthy)        8002->8002, 30304->30304
# ...           validator-3        Up (healthy)        8003->8003, 30305->30305
# ...           backend            Up (healthy)        8000->8000
# ...           frontend           Up (healthy)        3000->3000

3. Verify All Services Are Running

# Bootnode
curl http://localhost:8546/health

# Validators
curl http://localhost:8001/health
curl http://localhost:8002/health
curl http://localhost:8003/health

# Backend
curl http://localhost:8000/health

# Frontend
curl http://localhost:3000

---

Testing the PoA Network

1. Check Bootnode Peer Registry

curl http://localhost:8546/peers

# Should show all 3 validators registered
# {
#   "total_peers": 3,
#   "peers": [
#     {"node_id": "validator-1", "ip": "validator-1", "p2p_port": 30303, "rpc_port": 8001},
#     {"node_id": "validator-2", "ip": "validator-2", "p2p_port": 30304, "rpc_port": 8002},
#     {"node_id": "validator-3", "ip": "validator-3", "p2p_port": 30305, "rpc_port": 8003}
#   ]
# }

2. Check Validator Status

# Check validator-1
curl http://localhost:8001/health

# {
#   "status": "healthy",
#   "node_id": "validator-1",
#   "chain_length": 1,
#   "pending_transactions": 0,
#   "timestamp": "2025-11-07T15:30:00"
# }

3. Check Peer Connections

# Validator-1 peers
curl http://localhost:8001/peers

# Should show validator-2 and validator-3 as peers
# {
#   "node_id": "validator-1",
#   "peers": ["validator-2", "validator-3"],
#   "peer_count": 2
# }

4. Submit a Test Vote

# Create a test vote JSON
cat > /tmp/vote.json << 'EOF'
{
  "voter_id": "test-voter-1",
  "election_id": 1,
  "encrypted_vote": "0x1234567890abcdef",
  "ballot_hash": "0xabcdef1234567890",
  "proof": "0x..."
}
EOF

# Convert to hex
VOTE_HEX=$(jq -r '. | @json' /tmp/vote.json | od -An -tx1 | tr -d ' \n')

# Submit via JSON-RPC
curl -X POST http://localhost:8001/rpc \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"method\": \"eth_sendTransaction\",
    \"params\": [{
      \"data\": \"0x${VOTE_HEX}\"
    }],
    \"id\": 1
  }"

# Should return transaction hash
# {
#   "jsonrpc": "2.0",
#   "result": "0x...",
#   "id": 1
# }

5. Check Blockchain

# Get full blockchain from validator-1
curl http://localhost:8001/blockchain | jq

# Should show genesis block and any created blocks
# {
#   "blocks": [
#     {
#       "index": 0,
#       "prev_hash": "0x0000...",
#       "timestamp": 1699360000,
#       "transactions": [],
#       "validator": "genesis",
#       "block_hash": "0x...",
#       "signature": "genesis"
#     },
#     {
#       "index": 1,
#       "prev_hash": "0x...",
#       "timestamp": 1699360010,
#       "transactions": [...],
#       "validator": "validator-2",
#       "block_hash": "0x...",
#       "signature": "0x..."
#     }
#   ],
#   "verification": {
#     "chain_valid": true,
#     "total_blocks": 2,
#     "total_votes": 1
#   }
# }

6. Verify All Validators Have Same Blockchain

# Get blockchain from all 3 validators
HASH1=$(curl -s http://localhost:8001/blockchain | jq -r '.blocks[-1].block_hash')
HASH2=$(curl -s http://localhost:8002/blockchain | jq -r '.blocks[-1].block_hash')
HASH3=$(curl -s http://localhost:8003/blockchain | jq -r '.blocks[-1].block_hash')

echo "Validator-1 latest block: $HASH1"
echo "Validator-2 latest block: $HASH2"
echo "Validator-3 latest block: $HASH3"

# All should be identical (consensus reached)

---

Docker Commands

View Logs

# Bootnode logs
docker compose logs bootnode

# Validator logs
docker compose logs validator-1
docker compose logs validator-2
docker compose logs validator-3

# Follow logs in real-time
docker compose logs -f validator-1

Stop the System

docker compose down

Clean Up Everything (including volumes)

docker compose down -v

Rebuild Services

docker compose up -d --build

---

Monitoring

Watch Block Creation in Real-Time

# Terminal 1: Follow validator-1 logs
docker compose logs -f validator-1 | grep "Block"

# Terminal 2: Submit multiple votes
for i in {1..10}; do
  # Submit vote (see section 4 above)
  sleep 1
done

# You should see blocks being created every 5 seconds:
# validator-1_1 | Block 1 created successfully
# validator-2_1 | Block 1 accepted and propagated
# validator-3_1 | Block 1 accepted and propagated
# validator-2_1 | Block 2 created successfully
# etc.

Monitor Peer Synchronization

# Check all validators have same chain length
watch -n 1 'echo "Validator-1: $(curl -s http://localhost:8001/health | jq .chain_length)"; echo "Validator-2: $(curl -s http://localhost:8002/health | jq .chain_length)"; echo "Validator-3: $(curl -s http://localhost:8003/health | jq .chain_length)"'

---

Common Issues

Services Won't Start

Problem: Docker compose fails to build

Solution:

# Clean build
docker compose down -v
docker compose up -d --build

# Check for errors
docker compose logs

Validators Can't Find Bootnode

Problem: Validators fail to register with bootnode

Solution:

# Verify bootnode is running
curl http://localhost:8546/health

# Check validator logs
docker compose logs validator-1 | tail -20

# Restart validators
docker compose restart validator-1 validator-2 validator-3

Validators Not Reaching Consensus

Problem: Different validators have different blockchains

Solution:

# Check peer connections
curl http://localhost:8001/peers

# If peers list is empty, validators can't find each other
# Restart validators to trigger peer discovery
docker compose restart validator-1 validator-2 validator-3

# Wait 30 seconds for reconnection
sleep 30

# Verify consensus
curl http://localhost:8001/blockchain | jq '.verification.chain_valid'
curl http://localhost:8002/blockchain | jq '.verification.chain_valid'
curl http://localhost:8003/blockchain | jq '.verification.chain_valid'
# All should return true

No Blocks Being Created

Problem: Blockchain stays at genesis block

Possible Causes:

1. No transactions submitted
2. Block creation interval is too long
3. No validator is eligible (round-robin timing)

Solution:

# Submit test votes (see section 4 above)

# Check pending transactions
curl http://localhost:8001/health | jq '.pending_transactions'

# Monitor block creation
docker compose logs -f validator-1 | grep "creating block"

---

Next Phase: API Integration

Once the PoA network is working:

1. Update Backend to submit votes to validators

   • Create BlockchainClient class
   • Update POST /api/votes/submit
   • Update GET /api/votes/results

2. Test Complete Voting Workflow

   • Register voter
   • Login
   • Submit vote
   • Confirm on blockchain
   • View results

3. Update Frontend

   • Show transaction hash
   • Display confirmation status
   • Add blockchain viewer

---

Performance Metrics

Metric	Value
Block creation interval	5 seconds
Transactions per block	32 (configurable)
Throughput	~6.4 votes/second
Confirmation time	5-10 seconds
Network propagation	< 500ms
Bootstrap time	~30 seconds

---

Architecture Quick Reference

PoA Network Architecture:

Bootnode (8546)
    │
    ├─ Peer Registry
    │  └─ [validator-1, validator-2, validator-3]
    │
    └─ Discovery
       └─ Validators query for peers

Validators (8001-8003):
    ├─ Blockchain
    │  └─ [Genesis, Block1, Block2, ...]
    ├─ PoA Consensus
    │  └─ Round-robin block creation
    ├─ Transaction Pool
    │  └─ Pending votes waiting for block
    ├─ P2P Network
    │  └─ Gossip blocks and transactions
    └─ JSON-RPC Interface
       └─ eth_sendTransaction, eth_getTransactionReceipt, etc.

Connections:
- Validators ↔ Bootnode (registration & discovery)
- Validators ↔ Validators (P2P block gossip)
- Backend ↔ Validators (JSON-RPC voting)

---

Useful Commands for Development

Get Blockchain Stats

curl http://localhost:8001/blockchain | jq '.verification'

List All Peers

curl http://localhost:8546/peers | jq '.peers[] | .node_id'

Get Latest Block

curl http://localhost:8001/blockchain | jq '.blocks[-1]'

Count Total Votes

curl http://localhost:8001/blockchain | jq '.verification.total_votes'

---

Debugging

Enable Debug Logging

In validator/validator.py:

logger.setLevel(logging.DEBUG)  # or logging.INFO

Rebuild:

docker compose up -d --build validator-1

Inspect Container

# Get container ID
docker ps | grep validator-1

# Exec into container
docker exec -it <container_id> /bin/bash

# Check running processes
ps aux

# Check network connectivity
ping validator-2
curl http://bootnode:8546/health

---

Success Indicators

When everything is working correctly, you should see:

✅ All 3 validators showing "healthy" status ✅ Bootnode shows all 3 validators registered ✅ Each validator's peers list shows 2 other validators ✅ All validators have identical blockchain ✅ chain_valid is true on all validators ✅ Blocks created approximately every 5 seconds (when transactions pending) ✅ New blocks propagate to all validators within 500ms

---

Next Steps

1. Test the network with the quick start steps above
2. Monitor logs to see consensus in action
3. Proceed to Phase 3 - API integration with backend