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**:
```bash
./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**:
```bash
./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:
```json
[
  "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

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

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

```bash
# 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:
   ```bash
   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:
   ```bash
   pct exec <VMID> -- chown -R besu:besu /var/lib/besu
   ```

3. Verify 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 (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):**

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

---

## 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](../../06-besu/CHAIN138_BESU_CONFIGURATION.md)
- [Besu Allowlist Runbook](../../06-besu/BESU_ALLOWLIST_RUNBOOK.md)