d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b7eebb87b33ea4af3efe689c5a0469df4a134313
proxmox/docs/06-besu/NODE_LIST_REQUIREMENTS.md
defiQUG dbd517b279 Sync workspace: config, docs, scripts, CI, operator rules, and submodule pointers. 
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains
- Omit embedded publish git dirs and empty placeholders from index

Made-with: Cursor
2026-04-12 06:12:20 -07:00

6.0 KiB
Raw Blame History

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:

"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:

./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:

./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

Reference in New Issue View Git Blame Copy Permalink