# 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

```bash
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

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

```bash
# 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

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

### Check Peer Count

```bash
# 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

```bash
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:**
   ```bash
   pct exec <VMID> -- ls -la /var/lib/besu/static-nodes.json
   ```

2. **Check file ownership:**
   ```bash
   pct exec <VMID> -- chown -R besu:besu /var/lib/besu
   ```

3. **Check network connectivity:**
   ```bash
   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):**

```bash
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

```bash
# 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](../06-besu/CHAIN138_BESU_CONFIGURATION.md)
- **Summary:** [CHAIN138_CONFIGURATION_SUMMARY.md](../archive/configuration/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](../06-besu/CHAIN138_BESU_CONFIGURATION.md)