proxmox/docs/06-besu/NODE_LIST_REQUIREMENTS.md

# Node List Requirements - static-nodes.json and permissioned-nodes.json

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**Date**: 2025-01-18  
**Status**: ✅ **REQUIREMENTS DEFINED**

---

## Critical Requirements

### 1. Each RPC Node Must Be Unique

✅ **Requirement**: Each RPC node must have a unique enode identifier (node ID).  
✅ **Verification**: No duplicate node IDs allowed in the list.

### 2. Matching IP Address

✅ **Requirement**: Each enode must contain the correct IP address that matches the node's actual IP.  
⚠️ **Important**: The IP in the enode must match the node's `p2p-host` configuration.

**Example**:
```json
"enode://6cdc892fa09afa2b05c21cc9a1193a86cf0d195ce81b02a270d8bb987f78ca98ad90d907670796c90fc6e4eaf3b4cae6c0c15871e2564de063beceb4bbfc6532@192.168.11.211:30303"
```
- Node ID: `6cdc892fa09afa2b05c21cc9a1193a86cf0d195ce81b02a270d8bb987f78ca98ad90d907670796c90fc6e4eaf3b4cae6c0c15871e2564de063beceb4bbfc6532`
- IP: `192.168.11.211` ✅ Must match node's actual IP

### 3. All Nodes Must Be in static-nodes.json

✅ **Requirement**: Every node (validators, sentries, RPC nodes) must be listed in `static-nodes.json` on **ALL nodes**.  
✅ **Purpose**: Ensures initial peer discovery and connection.

**File Location**: `/var/lib/besu/static-nodes.json` (on each Besu node)

### 4. All Nodes Must Be in permissioned-nodes.json

✅ **Requirement**: Every node must also be listed in `permissioned-nodes.json` (or `permissions-nodes.toml`) on **ALL nodes**.  
✅ **Purpose**: Node permissioning requires all nodes to be in the allowlist.

**File Location**: `/var/lib/besu/permissions/permissioned-nodes.json` (on each Besu node)

---

## Current Status

### static-nodes.json

**Location**: `smom-dbis-138/config/static-nodes.json`

**Current Count**: 15 enodes

**Contents**:
- ✅ 5 Validator nodes (1000-1004)
- ✅ 1 RPC node at 192.168.11.211 (VMID 2101)
- ✅ 1 RPC node at 192.168.11.241 (VMID 2401)
- Historical note: this count predates the current 37-node fleet and the RPC renumbering.
- ⚠️ Contains some unknown IPs (221, 232-238) - need verification

### permissioned-nodes.json

**Location**: `smom-dbis-138-proxmox/config/permissioned-nodes.json`

**Status**: ✅ **UPDATED** - Now matches static-nodes.json (15 enodes)

---

## Expected Complete Node List

### Validators (5 nodes)

| VMID | IP Address | Status |
|------|------------|--------|
| 1000 | 192.168.11.100 | ✅ In list |
| 1001 | 192.168.11.101 | ✅ In list |
| 1002 | 192.168.11.102 | ✅ In list |
| 1003 | 192.168.11.103 | ✅ In list |
| 1004 | 192.168.11.104 | ✅ In list |

### Sentries (4 nodes)

| VMID | IP Address | Status |
|------|------------|--------|
| 1500 | 192.168.11.150 | ⚠️ Need to verify |
| 1501 | 192.168.11.151 | ⚠️ Need to verify |
| 1502 | 192.168.11.152 | ⚠️ Need to verify |
| 1503 | 192.168.11.153 | ⚠️ Need to verify |

### RPC Nodes (21 nodes expected)

| VMID | IP Address | Status |
|------|------------|--------|
| 2101 | 192.168.11.211 | ✅ Present |
| 2102 | 192.168.11.212 | ✅ Present |
| 2103 | 192.168.11.217 | ✅ Present |
| 2201 | 192.168.11.221 | ✅ Present |
| 2301 | 192.168.11.232 | ✅ Present |
| 2303 | 192.168.11.233 | ✅ Present |
| 2304 | 192.168.11.234 | ✅ Present |
| 2305 | 192.168.11.235 | ✅ Present |
| 2306 | 192.168.11.236 | ✅ Present |
| 2307 | 192.168.11.237 | ✅ Present |
| 2308 | 192.168.11.238 | ✅ Present |
| 2400 | 192.168.11.240 | ✅ Present |
| 2401 | 192.168.11.241 | ✅ Present |
| 2402 | 192.168.11.242 | ✅ Present |
| 2403 | 192.168.11.243 | ✅ Present |
| 2420 | 192.168.11.172 | ✅ Present |
| 2430 | 192.168.11.173 | ✅ Present |
| 2440 | 192.168.11.174 | ✅ Present |
| 2460 | 192.168.11.246 | ✅ Present |
| 2470 | 192.168.11.247 | ✅ Present |
| 2480 | 192.168.11.248 | ✅ Present |

---

## Verification Script

**Script**: `scripts/besu/verify-and-update-node-lists.sh`

**Purpose**:
1. Verify no duplicate enodes
2. Verify IP addresses match
3. Ensure static-nodes.json and permissioned-nodes.json match
4. Report missing nodes

**Usage**:
```bash
./scripts/besu/verify-and-update-node-lists.sh
```

---

## Collection Script

**Script**: `scripts/besu/collect-all-node-enodes.sh`

**Purpose**: Query all running nodes via `admin_nodeInfo` RPC to collect their enodes.

**Usage**:
```bash
./scripts/besu/collect-all-node-enodes.sh
```

**Note**: Requires nodes to have ADMIN API enabled and be running.

---

## Deployment Checklist

### Step 1: Collect All Enodes
- [ ] Run `collect-all-node-enodes.sh` to get enodes from all running nodes
- [ ] Verify each enode has correct IP address
- [ ] Verify no duplicate node IDs

### Step 2: Update Configuration Files
- [ ] Update `static-nodes.json` with complete list
- [ ] Update `permissioned-nodes.json` to match `static-nodes.json`
- [ ] Verify both files are identical (except file location)

### Step 3: Deploy to All Nodes
- [ ] Deploy `static-nodes.json` to `/var/lib/besu/static-nodes.json` on all nodes
- [ ] Deploy `permissioned-nodes.json` to `/var/lib/besu/permissions/permissioned-nodes.json` on all nodes
- [ ] Verify file permissions and ownership

### Step 4: Verify p2p-host Configuration
- [ ] Ensure each node's `p2p-host` in config matches the IP in its enode
- [ ] Fix any `p2p-host="0.0.0.0"` to the actual IP address

### Step 5: Restart and Verify
- [ ] Restart Besu services on all nodes
- [ ] Verify peer connections after restart
- [ ] Check that all expected peers are connected

---

## Critical Notes

1. **Both files must be identical**: `static-nodes.json` and `permissioned-nodes.json` must contain the same list of enodes.

2. **IP address must match**: The IP in each enode must match the node's actual IP address and `p2p-host` configuration.

3. **All nodes need both files**: Every node in the network must have the complete list in both files.

4. **p2p-host configuration**: Nodes with `p2p-host="0.0.0.0"` will generate enodes with `@0.0.0.0:30303`, which won't work for peer connections. Must use actual IP.

---

**Status**: ⏳ **COLLECTION AND VERIFICATION IN PROGRESS**