# Besu Allowlist Quick Start Guide

**Complete runbook**: See `docs/BESU_ALLOWLIST_RUNBOOK.md` for detailed explanations.

---

## Quick Execution Order

### 1. Extract Enodes from All Nodes

**Option A: If RPC is enabled** (recommended for RPC nodes):

```bash
# For each node, extract enode via RPC
export RPC_URL="http://192.168.11.13:8545"
export NODE_IP="192.168.11.13"
bash scripts/besu-extract-enode-rpc.sh > enode-192.168.11.13.txt
```

**Option B: If RPC is disabled** (for validators):

```bash
# SSH to node or run locally on each node
export DATA_PATH="/data/besu"
export NODE_IP="192.168.11.13"
bash scripts/besu-extract-enode-nodekey.sh > enode-192.168.11.13.txt
```

### 2. Collect All Enodes (Automated)

Update the `NODES` array in `scripts/besu-collect-all-enodes.sh` with your node IPs, then:

```bash
bash scripts/besu-collect-all-enodes.sh
```

This creates a working directory (e.g., `besu-enodes-20241219-140600/`) with:
- `collected-enodes.txt` - All valid enodes
- `duplicates.txt` - Duplicate entries (if any)
- `invalid-enodes.txt` - Invalid entries (if any)

### 3. Generate Allowlist Files

```bash
# From the working directory created in step 2
bash scripts/besu-generate-allowlist.sh besu-enodes-*/collected-enodes.txt 192.168.11.13 192.168.11.14 192.168.11.15 192.168.11.16 192.168.11.18
```

This generates:
- `static-nodes.json` - Validators only (for QBFT)
- `permissions-nodes.toml` - All nodes (validators + sentries + RPC)

### 4. Validate Generated Files

```bash
bash scripts/besu-validate-allowlist.sh static-nodes.json permissions-nodes.toml
```

**Must show**: `✓ All enodes validated successfully`

### 5. Deploy to All Containers

```bash
bash scripts/besu-deploy-allowlist.sh static-nodes.json permissions-nodes.toml
```

### 6. Restart Besu Services

On Proxmox host (`192.168.11.10`):

```bash
for vmid in 106 107 108 109 110 111 112 113 114 115 116 117; do
    echo "Restarting container $vmid..."
    pct exec $vmid -- systemctl restart besu-validator 2>/dev/null || \
    pct exec $vmid -- systemctl restart besu-sentry 2>/dev/null || \
    pct exec $vmid -- systemctl restart besu-rpc 2>/dev/null || true
done
```

### 7. Verify Peer Connections

```bash
# Check all nodes
for ip in 192.168.11.{13,14,15,16,18,19,20,21,22,23,24,25}; do
    echo "=== Node $ip ==="
    bash scripts/besu-verify-peers.sh "http://${ip}:8545"
    echo ""
done
```

**Expected**: Each node should show multiple connected peers.

---

## Troubleshooting

### No Peers Connected

1. **Check firewall**: `nc -zv <peer-ip> 30303`
2. **Verify files deployed**: `pct exec <vmid> -- cat /etc/besu/static-nodes.json`
3. **Check Besu logs**: `pct exec <vmid> -- journalctl -u besu-validator -n 50`
4. **Verify RPC enabled**: `bash scripts/besu-verify-peers.sh http://<ip>:8545`

### Invalid Enode Errors

1. **Check node ID length**: Must be exactly 128 hex characters
2. **No padding**: Remove trailing zeros
3. **Correct IP**: Must match actual node IP
4. **Unique endpoints**: One enode per IP:PORT

### Duplicate Enodes

- One node = one enode ID
- Use the enode returned by that node's `admin_nodeInfo`
- Remove duplicates from allowlist

---

## File Locations

**On Proxmox containers**:
- `/etc/besu/static-nodes.json` - Validator enodes
- `/etc/besu/permissions-nodes.toml` - All node enodes
- `/etc/besu/config.toml` - Besu configuration

**Ownership**: Files must be owned by `besu:besu`

---

## Key Besu Configuration Flags

```bash
# Enable permissions
--permissions-nodes-config-file-enabled=true
--permissions-nodes-config-file=/etc/besu/permissions-nodes.toml

# Static nodes (for faster connection)
--static-nodes-file=/etc/besu/static-nodes.json

# Discovery (can be enabled with permissions)
--discovery-enabled=true

# RPC (must include ADMIN for verification)
--rpc-http-api=ETH,NET,ADMIN,QBFT
```

---

## Verification Checklist

- [ ] All enodes have 128-character node IDs
- [ ] No duplicate node IDs
- [ ] No duplicate IP:PORT endpoints
- [ ] Validator IPs correctly mapped
- [ ] Files deployed to all containers
- [ ] Files owned by `besu:besu`
- [ ] Besu services restarted
- [ ] Peers connecting successfully

---

For detailed explanations, see `docs/BESU_ALLOWLIST_RUNBOOK.md`.

