proxmox/docs/01-getting-started/CHAIN138_QUICK_START.md

ChainID 138 Configuration - Quick Start Guide

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Quick reference for configuring Besu nodes for ChainID 138

---

🚀 Quick Start

Step 1: Run Main Configuration

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

What it does:

• Collects enodes from all Besu nodes
• Generates static-nodes.json and permissioned-nodes.json
• Deploys to all containers (including new: 1504, 2503)
• Configures discovery settings
• Restarts Besu services

Expected time: 5-10 minutes

---

Step 2: Verify Configuration

./scripts/verify-chain138-config.sh

What it checks:

• Files exist and are readable
• Discovery settings are correct
• Peer connections are working

---

📋 Node List

VMID	Hostname	Role	Discovery
1000-1004	besu-validator-*	Validator	Enabled
1500-1504	besu-sentry-*	Sentry	Enabled
2500	besu-rpc-core	RPC Core	Disabled
2501	besu-rpc-perm	RPC Permissioned	Enabled
2502	besu-rpc-public	RPC Public	Enabled
2503	besu-rpc-4	RPC Permissioned	Disabled

---

🔧 Manual Steps (if needed)

Check Configuration Files

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

Check Discovery Setting

# For RPC nodes that should have discovery disabled (2500, 2503)
pct exec 2503 -- grep discovery-enabled /etc/besu/*.toml

Check Peer Count

# Via RPC
curl -X POST http://<RPC_IP>:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

Restart Besu Service

pct exec <VMID> -- systemctl restart besu*.service
pct exec <VMID> -- systemctl status besu*.service

---

🐛 Troubleshooting

Issue: Node not connecting to peers

1. Check files exist:

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

2. Check file ownership:

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

3. Check 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 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

Issue: Permission denied errors

# Fix ownership
pct exec <VMID> -- chown -R besu:besu /var/lib/besu
pct exec <VMID> -- chmod 644 /var/lib/besu/static-nodes.json
pct exec <VMID> -- chmod 644 /var/lib/besu/permissions/permissioned-nodes.json

---

📚 Scripts Reference

Script	Purpose
configure-besu-chain138-nodes.sh	Main configuration script
setup-new-chain138-containers.sh	Quick setup for new containers
verify-chain138-config.sh	Verify configuration

---

📖 Full Documentation

• Complete Guide: CHAIN138_BESU_CONFIGURATION.md
• Summary: CHAIN138_CONFIGURATION_SUMMARY.md

---

✅ Checklist

• Run main configuration script
• Verify all nodes have configuration files
• Check discovery settings (disabled for 2500, 2503)
• Verify peer connections
• Test RPC endpoints
• Check service status on all nodes

---

🆘 Support

If you encounter issues:

1. Check logs: pct exec <VMID> -- journalctl -u besu*.service -n 50
2. Run verification: ./scripts/verify-chain138-config.sh
3. Review documentation: CHAIN138_BESU_CONFIGURATION.md