proxmox/docs/archive/configuration/CHAIN138_CONFIGURATION_SUMMARY.md

ChainID 138 Configuration - Implementation Summary

Overview

This document summarizes the implementation of Besu node configuration for ChainID 138, including the new containers (1504: besu-sentry-5, 2503: besu-rpc-4) and the access control matrix for Ali, Luis, and Putu.

---

What Was Created

1. Main Configuration Script

File: scripts/configure-besu-chain138-nodes.sh

Purpose: Comprehensive script that:

• Collects enodes from all Besu nodes (validators, sentries, RPC)
• Generates static-nodes.json and permissioned-nodes.json
• Deploys configurations to all Besu containers
• Configures discovery settings (disabled for RPC nodes that report chainID 0x1 to MetaMask for wallet compatibility)
• Restarts Besu services

Usage:

./scripts/configure-besu-chain138-nodes.sh

2. Quick Setup Script for New Containers

File: scripts/setup-new-chain138-containers.sh

Purpose: Quick setup script specifically for new containers (1504, 2503) that:

• Runs the main configuration script
• Verifies new containers are properly configured
• Checks discovery settings

Usage:

./scripts/setup-new-chain138-containers.sh

3. Configuration Templates

Files:

• smom-dbis-138/config/config-rpc-4.toml - RPC node 4 configuration (discovery disabled)
• smom-dbis-138-proxmox/templates/besu-configs/config-rpc-4.toml - Template version

Key Features:

• Discovery disabled (prevents connection to Ethereum mainnet while reporting chainID 0x1 to MetaMask for wallet compatibility)
• Correct file paths for static-nodes.json and permissioned-nodes.json
• Permissioned access configuration

4. Updated Configuration Templates

Updated Files:

• smom-dbis-138/config/config-rpc-core.toml
• smom-dbis-138/config/config-rpc-perm.toml
• smom-dbis-138-proxmox/templates/besu-configs/config-rpc-core.toml
• smom-dbis-138-proxmox/templates/besu-configs/config-rpc.toml
• smom-dbis-138-proxmox/templates/besu-configs/config-sentry.toml

Changes:

• Updated paths to use /var/lib/besu/static-nodes.json
• Updated paths to use /var/lib/besu/permissions/permissioned-nodes.json
• Ensured consistency across all templates

5. Documentation

Files:

• docs/CHAIN138_BESU_CONFIGURATION.md - Comprehensive configuration guide
• docs/CHAIN138_CONFIGURATION_SUMMARY.md - This summary

---

Node Allocation

Containers

VMID	Hostname	Role	ChainID	Discovery	Identity	JWT Auth
1504	besu-sentry-5	Sentry	138	Enabled	N/A	✅ Required
2503	besu-rpc-4	RPC (Permissioned)	138	Disabled	0x8a	✅ Required
2504	besu-rpc-4	RPC (Permissioned)	138	Disabled	0x1	✅ Required
2505	besu-rpc-luis	RPC (Permissioned)	138	Disabled	0x8a	✅ Required
2506	besu-rpc-luis	RPC (Permissioned)	138	Disabled	0x1	✅ Required
2507	besu-rpc-putu	RPC (Permissioned)	138	Disabled	0x8a	✅ Required
2508	besu-rpc-putu	RPC (Permissioned)	138	Disabled	0x1	✅ Required
6201	firefly-2	Firefly	138	N/A	N/A	✅ Required

All Besu Nodes for ChainID 138

• Validators: 1000-1004 (5 nodes)
• Sentries: 1500-1504 (5 nodes, including new 1504)
• RPC Nodes: 2500-2508 (9 nodes, including new 2503-2508)

---

Access Control Matrix

Ali (Dedicated Physical Proxmox Host)

✅ Full Access:

• Entire Proxmox host (root)
• Besu Sentry Node (1504)
• RPC Nodes (2503 with 0x8a, 2504 with 0x1)
• Hyperledger Firefly (6201)
• Independent networking, keys, firewall rules
• JWT authentication configured

Luis (RPC-Only Access)

✅ Limited Access:

• RPC Nodes (2505 with 0x8a, 2506 with 0x1)
• Access via reverse proxy / firewall-restricted RPC ports
• JWT authentication required

❌ No Access:

• Besu Sentry nodes
• Firefly nodes
• Ali's RPC nodes (2503, 2504)
• Putu's RPC nodes (2507, 2508)
• Proxmox infrastructure
• Node key material

Putu (RPC-Only Access)

✅ Limited Access:

• RPC Nodes (2507 with 0x8a, 2508 with 0x1)
• Access via reverse proxy / firewall-restricted RPC ports
• JWT authentication required

❌ No Access:

• Besu Sentry nodes
• Firefly nodes
• Ali's RPC nodes (2503, 2504)
• Luis's RPC nodes (2505, 2506)
• Proxmox infrastructure
• Node key material

---

Configuration Files

File Locations

On each Besu container:

/var/lib/besu/static-nodes.json
/var/lib/besu/permissions/permissioned-nodes.json

File Format

Both files use JSON array format:

[
  "enode://<PUBKEY>@<IP>:30303",
  ...
]

Important: All Besu nodes must have the same content in both files.

---

Discovery Settings

Discovery Disabled

• 2500 (besu-rpc-core) - Strict local/permissioned control
• 2503-2508 (All new RPC nodes) - Reports chainID 0x1 to MetaMask for wallet compatibility, discovery disabled to prevent actual mainnet connection

Discovery Enabled

• 1000-1004 (Validators)
• 1500-1504 (Sentries, including new 1504)
• 2501 (besu-rpc-perm)
• 2502 (besu-rpc-public)

Note: Even with discovery enabled, nodes must respect permissioned-nodes.json allowlist.

---

Quick Start

1. Run Main Configuration

cd /home/intlc/projects/proxmox
./scripts/configure-besu-chain138-nodes.sh

This will:

1. Collect enodes from all nodes
2. Generate configuration files
3. Deploy to all containers
4. Configure discovery
5. Restart services

2. Verify Configuration

# Check peer count
curl -X POST http://192.168.11.253:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

# Check discovery setting (should be false for 2503)
pct exec 2503 -- grep discovery-enabled /etc/besu/*.toml

3. Check Service Status

# Check all Besu services
for vmid in 1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 2500 2501 2502 2503 2504 2505 2506 2507 2508; do
  echo "VMID $vmid:"
  pct exec $vmid -- systemctl status besu*.service --no-pager | head -3
done

---

Troubleshooting

Issue: Node Not Connecting

1. Verify files exist:

   pct exec <VMID> -- ls -la /var/lib/besu/static-nodes.json
   pct exec <VMID> -- ls -la /var/lib/besu/permissions/permissioned-nodes.json
   

2. Check file ownership:

   pct exec <VMID> -- chown -R besu:besu /var/lib/besu
   

3. Verify network connectivity:

   pct exec <VMID> -- ping <PEER_IP>
   

Understanding: RPC Nodes Reporting chainID 0x1 to MetaMask

Note: This is intentional behavior for wallet compatibility. RPC nodes (2503-2508) report chainID = 0x1 (Ethereum mainnet) to MetaMask wallets to work around MetaMask's technical limitations for regulated financial entities.

How it works:

• Nodes are connected to ChainID 138 (private network)
• Nodes report chainID 0x1 to MetaMask (wallet compatibility)
• Discovery is disabled to prevent actual connection to Ethereum mainnet
• MetaMask works with the private network while thinking it's mainnet

If discovery needs to be disabled (should already be configured):

for vmid in 2503 2504 2505 2506 2507 2508; do
  pct exec $vmid -- sed -i 's/^discovery-enabled=.*/discovery-enabled=false/' /etc/besu/*.toml
  pct exec $vmid -- systemctl restart besu*.service
done

---

Next Steps

1. Run Configuration: Execute configure-besu-chain138-nodes.sh
2. Verify Peers: Check peer connections on all nodes
3. Test RPC Access: Verify Luis/Putu can access RPC node 2503
4. Monitor Logs: Watch for any connection issues
5. Update Firewall: Ensure port 30303 is open between nodes

---

Related Files

• Main config script: scripts/configure-besu-chain138-nodes.sh
• Quick setup: scripts/setup-new-chain138-containers.sh
• Documentation: docs/CHAIN138_BESU_CONFIGURATION.md
• RPC-4 config: smom-dbis-138/config/config-rpc-4.toml

---

Support

For detailed information, see:

• ChainID 138 Besu Configuration Guide
• Besu Allowlist Runbook