CIA/e-voting-system/POA_QUICK_START.md

# PoA Network Quick Start Guide

## Starting the System

### 1. Build and Start All Services

```bash
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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
docker compose down
```

### Clean Up Everything (including volumes)

```bash
docker compose down -v
```

### Rebuild Services

```bash
docker compose up -d --build
```

---

## Monitoring

### Watch Block Creation in Real-Time

```bash
# 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

```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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

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

### List All Peers

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

### Get Latest Block

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

### Count Total Votes

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

---

## Debugging

### Enable Debug Logging

In `validator/validator.py`:
```python
logger.setLevel(logging.DEBUG)  # or logging.INFO
```

Rebuild:
```bash
docker compose up -d --build validator-1
```

### Inspect Container

```bash
# 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