CIA/e-voting-system/BLOCKCHAIN_QUICK_START.md

# Elections Blockchain - Quick Start

## What's New

Elections are now stored immutably on the blockchain with cryptographic security.

### Files Added/Modified

**New Files:**
- `backend/blockchain_elections.py` - Core blockchain implementation
- `backend/init_blockchain.py` - Blockchain initialization on startup
- `test_blockchain_election.py` - Test script to verify integration
- `BLOCKCHAIN_ELECTION_INTEGRATION.md` - Full technical documentation

**Modified Files:**
- `backend/services.py` - Added `ElectionService.create_election()` with blockchain recording
- `backend/main.py` - Added blockchain initialization on startup

## How It Works

### 1. Elections Created in Database

```python
# Via API or database init scripts
INSERT INTO elections (name, description, start_date, end_date, ...)
VALUES ('Election Présidentielle 2025', 'Vote pour la présidence', ...)
```

### 2. Automatically Recorded to Blockchain

When backend starts or election is created:
- Election data is read from database
- SHA-256 hash of candidates list is computed
- Block is created with previous block's hash (chain integrity)
- Block is signed with RSA-PSS signature
- Block is added to immutable chain

### 3. Can Be Verified On-Demand

```bash
# Check entire blockchain
curl http://localhost:8000/api/elections/blockchain

# Verify specific election
curl http://localhost:8000/api/elections/1/blockchain-verify
```

## Security Features

### ✓ Hash Chain Integrity
Each block references the hash of the previous block, creating an unbreakable chain. If any block is modified, the chain is broken.

### ✓ Candidate Verification
Each election includes a SHA-256 hash of all candidates at creation time. Candidates cannot be added/removed/modified without breaking the hash.

### ✓ RSA-PSS Signatures
Each block is signed for authentication. Signature validation ensures block wasn't created by an attacker.

### ✓ Tamper Detection
On every verification, the blockchain checks:
- Block hash matches its data
- Hash chain is unbroken
- Signature is valid

If any check fails, tampering is detected.

## Testing

### Quick Test

```bash
# Wait for backend to initialize (~30 seconds after start)
sleep 30

# Run test script
python3 test_blockchain_election.py

# Should output:
# ✓ All tests passed! Elections blockchain integration working correctly.
```

### Manual Testing

```bash
# 1. Get all elections in blockchain
curl http://localhost:8000/api/elections/blockchain | jq '.blocks'

# 2. Verify election 1
curl http://localhost:8000/api/elections/1/blockchain-verify | jq '.'

# 3. Check active elections (for comparison)
curl http://localhost:8000/api/elections/active | jq '.'

# 4. Debug all elections with time info
curl http://localhost:8000/api/elections/debug/all | jq '.elections'
```

## How to View Blockchain

### Via API

```bash
curl http://localhost:8000/api/elections/blockchain
```

Returns JSON with all blocks:
```json
{
  "blocks": [
    {
      "index": 0,
      "election_id": 1,
      "election_name": "Election Présidentielle 2025",
      "candidates_count": 4,
      "block_hash": "7f3e9c2b...",
      "signature": "8a2e1f3d...",
      ...
    }
  ],
  "verification": {
    "chain_valid": true,
    "total_blocks": 1
  }
}
```

### Via Frontend (Next Phase)

The blockchain visualization component exists at `frontend/components/blockchain-visualizer.tsx` and can be integrated into a dashboard page showing:
- Block explorer with expandable details
- Hash verification status
- Signature validation
- Chain integrity indicators
- Copy-to-clipboard for hashes

## Troubleshooting

### No Blocks in Blockchain

```bash
# Check database has elections
curl http://localhost:8000/api/elections/debug/all

# If elections exist but blockchain empty:
1. Restart backend: docker compose restart backend
2. Wait 30 seconds for initialization
3. Check logs: docker compose logs backend | grep blockchain
```

### Verification Fails

```bash
curl http://localhost:8000/api/elections/1/blockchain-verify

# If "verified": false, check:
# - "hash_valid": false → block data modified
# - "chain_valid": false → previous block modified
# - "signature_valid": false → signature missing or invalid
```

### Backend Won't Start

```bash
# Check logs
docker compose logs backend

# Look for:
# - Blockchain initialization errors
# - Database connection issues
# - Import errors (missing blockchain_elections module)

# Restart if needed
docker compose down
docker compose up -d backend
```

## API Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/elections/blockchain` | Get complete elections blockchain |
| GET | `/api/elections/{id}/blockchain-verify` | Verify election integrity |
| GET | `/api/elections/active` | Get active elections (comparison) |
| GET | `/api/elections/debug/all` | Debug all elections with time info |

## Files Reference

### Core Blockchain

**`backend/blockchain_elections.py`** (270 lines)
- `ElectionBlock` - Immutable block dataclass
- `ElectionsBlockchain` - Blockchain manager
- `record_election_to_blockchain()` - Public API to record election
- `verify_election_in_blockchain()` - Public API to verify election
- `get_elections_blockchain_data()` - Public API to get blockchain data

### Election Service

**`backend/services.py`** - ElectionService class
- `create_election()` - NEW: Creates election and records to blockchain
- `get_active_election()` - Get currently active election
- `get_election()` - Get election by ID

### Initialization

**`backend/init_blockchain.py`** (79 lines)
- `initialize_elections_blockchain()` - Called on startup
- Syncs existing database elections to blockchain
- Verifies blockchain integrity

**`backend/main.py`** - FastAPI app
- Calls `initialize_elections_blockchain()` on startup

### Routes

**`backend/routes/elections.py`** - Election endpoints
- `GET /api/elections/blockchain` - Returns elections blockchain data
- `GET /api/elections/{id}/blockchain-verify` - Returns verification report

## Next Steps

1. **Test the integration**: Run `python3 test_blockchain_election.py`
2. **View the blockchain**: Access `/api/elections/blockchain` endpoint
3. **Integrate with UI**: Create a page to display blockchain (component exists at `frontend/components/blockchain-visualizer.tsx`)
4. **Extend blockchain**: Add voter registration and vote records to blockchain for full audit trail

## Technical Details

See `BLOCKCHAIN_ELECTION_INTEGRATION.md` for:
- Detailed architecture explanation
- Hash chain security model
- Candidate verification mechanism
- Tamper detection process
- Database initialization flow
- Error handling and logging