# Besu Nodes File Reference

This document provides a comprehensive reference table mapping all Besu nodes to their container IDs, IP addresses, and the files required for each node type.

## Network Topology

This deployment follows a **production-grade validator ↔ sentry architecture** that isolates consensus from public networking and provides DDoS protection.

### Validator ↔ Sentry Topology (Logical Diagram)

```text
                         ┌──────────────────────────┐
                         │        External /         │
                         │     Internal Peers        │
                         │   (Other Networks /       │
                         │    RPC Consumers)         │
                         └────────────┬─────────────┘
                                      │
                          P2P (30303) │
                                      ▼
        ┌─────────────────────────────────────────────────┐
        │                    SENTRY LAYER                 │
        │   (Public-facing, peer-heavy, no consensus)     │
        │                                                 │
        │  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │
        │  │ besu-sentry │  │ besu-sentry │  │ besu-   │ │
        │  │     -2      │  │     -3      │  │ sentry- │ │
        │  │192.168.11.150 (DHCP)│  │192.168.11.151 (DHCP)│  │   4     │ │
        │  └──────┬──────┘  └──────┬──────┘  └────┬────┘ │
        │         │                 │               │    │
        │         └─────────┬───────┴───────┬───────┘    │
        └───────────────────┼───────────────┼────────────┘
                             │               │
                 Restricted P2P (30303) – static only
                             │               │
                             ▼               ▼
┌─────────────────────────────────────────────────────────────────┐
│                        VALIDATOR LAYER                           │
│        (Private, consensus-only, no public peering)              │
│                                                                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐│
│  │ besu-       │ │ besu-       │ │ besu-       │ │ besu-      ││
│  │ validator-1 │ │ validator-2 │ │ validator-3 │ │ validator- ││
│  │192.168.11.100 (DHCP)│ │192.168.11.101 (DHCP)│ │192.168.11.102 (DHCP)│ │    4       ││
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬─────┘│
│         │                 │               │               │     │
│         └────────────── QBFT / IBFT2 Consensus ───────────┘     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

                          ▲
                          │
                 Internal access only
                          │
        ┌──────────────────────────────────────────┐
        │               RPC LAYER                  │
        │        (Read / Write, No P2P)            │
        │                                          │
        │  besu-rpc-core   besu-rpc-perm   besu-rpc-public    │
        │  192.168.11.250   192.168.11.251   192.168.11.252    │
        │  HTTP 8545 / WS 8546                       │
        └──────────────────────────────────────────┘
```

### Topology Design Principles

#### 1. **Validators are Never Exposed**
- ❌ No public P2P connections
- ❌ No RPC endpoints exposed
- ✅ Only peer with **known sentry nodes** (via `static-nodes.json`)
- ✅ Appear in `genesis.json` validator set (if using static validators)
- ✅ Validator keys remain private and secure

#### 2. **Sentry Nodes Absorb Network Risk**
- ✅ Handle peer discovery and gossip
- ✅ Accept external connections
- ✅ Can be replaced or scaled **without touching consensus**
- ❌ Do **not** sign blocks (not validators)
- ✅ First line of defense against DDoS

#### 3. **RPC Nodes are Isolated**
- ✅ Serve dApps, indexers, and operational tooling
- ✅ Provide HTTP JSON-RPC (port 8545) and WebSocket (port 8546)
- ❌ Never participate in consensus
- ✅ Can peer with sentries or validators (internal only)
- ✅ Stateless and horizontally scalable

### Static Peering Rules

The topology enforces the following peering configuration:

| Node Type  | `static-nodes.json` Contains                    | Purpose                                    |
|------------|------------------------------------------------|--------------------------------------------|
| **Validators** | Sentries + other validators                    | Connect to network via sentries            |
| **Sentries**   | Validators + other sentries                    | Relay messages to/from validators          |
| **RPC Nodes**  | Sentries or validators (optional)              | Internal access to network state           |

### Why This Topology Is Production-Grade

✅ **DDoS-Resistant**: Validators are not publicly accessible  
✅ **Security**: Validator keys never exposed to public network  
✅ **Fault Isolation**: Sentry failures don't affect consensus  
✅ **Easy Validator Rotation**: Replace validators without network disruption  
✅ **Auditable Consensus Boundary**: Clear separation of concerns  
✅ **Matches Besu / ConsenSys Best Practice**: Industry-standard architecture  

## Container Information

| VMID | Hostname           | IP Address    | Node Type | Service Name          |
|------|--------------------|---------------|-----------|-----------------------|
| 1000 | besu-validator-1   | 192.168.11.100 (DHCP) | Validator | besu-validator        |
| 1001 | besu-validator-2   | 192.168.11.101 (DHCP) | Validator | besu-validator        |
| 1002 | besu-validator-3   | 192.168.11.102 (DHCP) | Validator | besu-validator        |
| 1003 | besu-validator-4   | 192.168.11.103 (DHCP) | Validator | besu-validator        |
| 1004 | besu-validator-5   | 192.168.11.104 (DHCP) | Validator | besu-validator        |
| 1500 | besu-sentry-1      | 192.168.11.150 (DHCP) | Sentry    | besu-sentry           |
| 1501 | besu-sentry-2      | 192.168.11.151 (DHCP) | Sentry    | besu-sentry           |
| 1502 | besu-sentry-3      | 192.168.11.152 (DHCP) | Sentry    | besu-sentry           |
| 1503 | besu-sentry-4      | 192.168.11.153 (DHCP) | Sentry    | besu-sentry           |
| 2500 | besu-rpc-core      | 192.168.11.250 (DHCP) | Core RPC | besu-rpc              |
| 2501 | besu-rpc-perm      | 192.168.11.251 (DHCP) | Permissioned RPC | besu-rpc              |
| 2502 | besu-rpc-public    | 192.168.11.252 (DHCP) | Public RPC | besu-rpc              |

## Required Files by Node Type

### Files Generated by Quorum Genesis Tool

The Quorum Genesis Tool typically generates the following files that are shared across all nodes:

#### Network-Wide Files (Same for All Nodes)

| File                        | Location              | Description                                    | Generated By          |
|-----------------------------|-----------------------|------------------------------------------------|-----------------------|
| `genesis.json`              | `/etc/besu/`          | Network genesis block configuration (QBFT settings, but **no validators** - uses dynamic validator management) | Quorum Genesis Tool   |
| `static-nodes.json`         | `/etc/besu/`          | List of static peer nodes (validators)         | Quorum Genesis Tool   |
| `permissions-nodes.toml`    | `/etc/besu/`          | Node allowlist (permissioned network)          | Quorum Genesis Tool   |
| `permissions-accounts.toml` | `/etc/besu/`          | Account allowlist (if using account permissioning) | Quorum Genesis Tool |

### Files Generated by Besu (Per-Node)

#### Validator Nodes (1000-1004)

| File                        | Location              | Description                                    | Generated By          |
|-----------------------------|-----------------------|------------------------------------------------|-----------------------|
| `config-validator.toml`     | `/etc/besu/`          | Besu configuration file (references validator key directory) | Deployment Script     |
| `nodekey`                   | `/data/besu/`         | Node private key (P2P identity)                | Besu (first run)      |
| `nodekey.pub`               | `/data/besu/`         | Node public key                                | Derived from nodekey  |
| `validator-keys/`           | `/keys/validators/`   | Validator signing keys (QBFT/IBFT). Contains `address.txt` with validator address (NOT in genesis) | Quorum Genesis Tool   |
| `database/`                 | `/data/besu/database/`| Blockchain database                            | Besu (runtime)        |

**Note**: Validator addresses are stored in `/keys/validators/validator-{N}/address.txt`, not in the genesis file. The genesis file uses dynamic validator management via validator contract.

#### Sentry Nodes (1500-1503)

| File                        | Location              | Description                                    | Generated By          |
|-----------------------------|-----------------------|------------------------------------------------|-----------------------|
| `config-sentry.toml`        | `/etc/besu/`          | Besu configuration file                        | Deployment Script     |
| `nodekey`                   | `/data/besu/`         | Node private key (P2P identity)                | Besu (first run)      |
| `nodekey.pub`               | `/data/besu/`         | Node public key                                | Derived from nodekey  |
| `database/`                 | `/data/besu/database/`| Blockchain database                            | Besu (runtime)        |

#### RPC Nodes (2500-2502)

**Note**: Each RPC node type uses a different configuration file:
- **VMID 2500 (Core)**: Uses `config-rpc-core.toml`
- **VMID 2501 (Permissioned)**: Uses `config-rpc-perm.toml`
- **VMID 2502 (Public)**: Uses `config-rpc-public.toml`

| File                        | Location              | Description                                    | Generated By          |
|-----------------------------|-----------------------|------------------------------------------------|-----------------------|
| `config-rpc-{type}.toml`    | `/etc/besu/`          | Besu configuration file (type-specific)        | Deployment Script     |
| `nodekey`                   | `/data/besu/`         | Node private key (P2P identity)                | Besu (first run)      |
| `nodekey.pub`               | `/data/besu/`         | Node public key                                | Derived from nodekey  |
| `database/`                 | `/data/besu/database/`| Blockchain database                            | Besu (runtime)        |

## Complete File Reference Table

### Validator Nodes (1000-1004)

| VMID | IP Address    | Required Files                                                                                                  |
|------|---------------|-----------------------------------------------------------------------------------------------------------------|
| 1000  | 192.168.11.100 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `permissions-accounts.toml`, `config-validator.toml`, `nodekey`, `validator-keys/` |
| 1001  | 192.168.11.101 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `permissions-accounts.toml`, `config-validator.toml`, `nodekey`, `validator-keys/` |
| 1002  | 192.168.11.102 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `permissions-accounts.toml`, `config-validator.toml`, `nodekey`, `validator-keys/` |
| 1003  | 192.168.11.103 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `permissions-accounts.toml`, `config-validator.toml`, `nodekey`, `validator-keys/` |
| 1004  | 192.168.11.104 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `permissions-accounts.toml`, `config-validator.toml`, `nodekey`, `validator-keys/` |

### Sentry Nodes (1500-1503)

| VMID | IP Address    | Required Files                                                                                                  |
|------|---------------|-----------------------------------------------------------------------------------------------------------------|
| 1500  | 192.168.11.150 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `config-sentry.toml`, `nodekey`                |
| 1501  | 192.168.11.151 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `config-sentry.toml`, `nodekey`                |
| 1502  | 192.168.11.152 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `config-sentry.toml`, `nodekey`                |
| 1503  | 192.168.11.153 (DHCP) | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `config-sentry.toml`, `nodekey`                |

### RPC Nodes (2500-2502)

| VMID | IP Address | Node Type | Required Files                                                                                                  |
|------|------------|-----------|-----------------------------------------------------------------------------------------------------------------|
| 2500  | 192.168.11.250 (DHCP) | **Core RPC** | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `config-rpc-core.toml`, `nodekey`            |
| 2501  | 192.168.11.251 (DHCP) | **Permissioned RPC** | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `config-rpc-perm.toml`, `nodekey`            |
| 2502  | 192.168.11.252 (DHCP) | **Public RPC** | `genesis.json`, `static-nodes.json`, `permissions-nodes.toml`, `config-rpc-public.toml`, `nodekey`            |

**Note**: Each RPC node type uses a different configuration file:
- **2500 (Core)**: Internal/core infrastructure RPC endpoints - uses `config-rpc-core.toml`
- **2501 (Permissioned)**: Permissioned RPC (Requires Auth, select APIs) - uses `config-rpc-perm.toml`
- **2502 (Public)**: Public RPC (none or minimal APIs) - uses `config-rpc-public.toml`

## File Locations Summary

### Configuration Directory: `/etc/besu/`
All configuration files are stored here:
- `genesis.json`
- `static-nodes.json`
- `permissions-nodes.toml`
- `permissions-accounts.toml` (validators only)
- `config-validator.toml` (validators)
- `config-sentry.toml` (sentries)
- `config-rpc-public.toml` (RPC nodes)

### Data Directory: `/data/besu/`
Runtime data and node keys:
- `nodekey` - Node private key (generated by Besu)
- `database/` - Blockchain database (created by Besu)

### Keys Directory: `/keys/validators/`
Validator signing keys (validators only):
- `validator-1/` - Validator 1 keys
- `validator-2/` - Validator 2 keys
- `validator-3/` - Validator 3 keys
- `validator-4/` - Validator 4 keys
- `validator-5/` - Validator 5 keys

## File Generation Sources

### Quorum Genesis Tool Generates:
1. **genesis.json** - Network genesis block with QBFT/IBFT configuration
2. **static-nodes.json** - List of validator enode URLs
3. **permissions-nodes.toml** - Node allowlist (can be JSON or TOML)
4. **permissions-accounts.toml** - Account allowlist (optional, for account permissioning)
5. **validator-keys/** - Validator signing keys (one directory per validator)

### Besu Generates:
1. **nodekey** - Automatically generated on first startup (if not provided)
2. **database/** - Blockchain database (created during sync)

### Deployment Scripts Generate:
1. **config-validator.toml** - Validator configuration
2. **config-sentry.toml** - Sentry configuration
3. **config-rpc-{type}.toml** - RPC node configuration (type-specific):
   - `config-rpc-core.toml` - Core RPC (VMID 2500)
   - `config-rpc-perm.toml` - Permissioned RPC (VMID 2501)
   - `config-rpc-public.toml` - Public RPC (VMID 2502)

## Enode URL Format

Each node's enode URL is derived from:
- **Node ID**: 128 hex characters from `nodekey` (public key)
- **IP Address**: Container IP address
- **Port**: Default P2P port 30303

Format: `enode://<128-char-node-id>@<ip-address>:30303`

Example: `enode://889ba317e10114a035ef82248a26125fbc00b1cd65fb29a2106584dddd025aa3dda14657bc423e5e8bf7d91a9858e85a@192.168.11.100 (DHCP):30303`

## Validator Configuration in Genesis File

**Answer: No, validators do NOT appear in the genesis file.**

This network uses **dynamic validator management** via a validator contract. The QBFT configuration in `genesis.json` contains:

```json
"qbft": {
    "blockperiodseconds": 2,
    "epochlength": 30000,
    "requesttimeoutseconds": 10
}
```

**Note**: There is no `validators` array in the `qbft` section of the genesis file.

### Validator Storage

Instead of being defined in the genesis file, validator addresses are:
1. **Stored in validator key directories**: `/keys/validators/validator-{N}/address.txt`
2. **Managed dynamically** via the validator contract during runtime
3. **Referenced in configuration files**: Each validator node references its key directory in `config-validator.toml`

This approach allows for:
- Dynamic addition/removal of validators without a hard fork
- Runtime validator set changes via smart contract
- More flexible validator management

### Validator Key Directory Structure

Each validator has a directory at `/keys/validators/validator-{N}/` containing:
- `key.pem` - Private key (PEM format)
- `pubkey.pem` - Public key (PEM format)
- `address.txt` - Validator address (hex format)
- `key.priv` - Private key (raw format)

## Network Configuration

- **Network ID**: 138
- **Consensus**: QBFT (Quorum Byzantine Fault Tolerance) with dynamic validators
- **P2P Port**: 30303 (all nodes)
- **RPC Port**: 8545 (RPC nodes only, validators have RPC disabled)
- **WebSocket Port**: 8546 (RPC nodes only)
- **Metrics Port**: 9545 (all nodes)

## File Permissions

All Besu files should be owned by the `besu` user:
```bash
chown -R besu:besu /etc/besu/
chown -R besu:besu /data/besu/
chown -R besu:besu /keys/validators/
```

## Quick Reference

### Check File Existence on Container
```bash
pct exec <vmid> -- ls -la /etc/besu/
pct exec <vmid> -- ls -la /data/besu/
pct exec <vmid> -- ls -la /keys/validators/  # validators only
```

### View Configuration
```bash
pct exec <vmid> -- cat /etc/besu/config-validator.toml  # validators
pct exec <vmid> -- cat /etc/besu/config-sentry.toml     # sentries
pct exec <vmid> -- cat /etc/besu/config-rpc-core.toml    # Core RPC (2500)
pct exec <vmid> -- cat /etc/besu/config-rpc-perm.toml    # Permissioned RPC (2501)
pct exec <vmid> -- cat /etc/besu/config-rpc-public.toml  # Public RPC (2502)
```

### View Genesis
```bash
pct exec <vmid> -- cat /etc/besu/genesis.json
```

### View Node Allowlist
```bash
pct exec <vmid> -- cat /etc/besu/permissions-nodes.toml
pct exec <vmid> -- cat /etc/besu/static-nodes.json
```

