# 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**