d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
master
proxmox/docs/06-besu/NODE_LIST_REQUIREMENTS.md
defiQUG fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details
docs: Ledger Live integration, contract deploy learnings, NEXT_STEPS updates 
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands
- CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround
- CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check
- NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere
- MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates
- LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 15:46:57 -08:00

5.8 KiB
Raw Permalink 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)
  • ⚠️ 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:

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