# 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) - ⚠️ Missing some expected RPC nodes (2400, 2402, 2500-2502, 2505-2508) - ⚠️ 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 (13 nodes expected) | VMID | IP Address | Status | |------|------------|--------| | 2101 | 192.168.11.211 | ✅ In list | | 2400 | 192.168.11.240 | ❌ Missing | | 2401 | 192.168.11.241 | ✅ In list | | 2402 | 192.168.11.242 | ❌ Missing | | 2500 | 192.168.11.250 | ❌ Missing | | 2501 | 192.168.11.251 | ❌ Missing | | 2502 | 192.168.11.252 | ❌ Missing | | 2505 | 192.168.11.201 | ❌ Missing | | 2506 | 192.168.11.202 | ❌ Missing | | 2507 | 192.168.11.203 | ❌ Missing | | 2508 | 192.168.11.204 | ❌ Missing | **Unknown IPs in list** (need verification): - 192.168.11.221 - 192.168.11.232 - 192.168.11.233 - 192.168.11.234 - 192.168.11.235 - 192.168.11.236 - 192.168.11.237 - 192.168.11.238 --- ## 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**