# RPC Configuration Analysis

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

---

**Date**: 2026-01-17  
**Purpose**: Analyze RPC configuration files for consolidation opportunities

---

## Overview

This document analyzes all 13 RPC configuration files to identify similarities, differences, and consolidation opportunities.

---

## RPC Configuration Files

### Current RPC Configs (13 files)

1. `config-rpc-core.toml` - Core/Admin RPC (full admin APIs)
2. `config-rpc-public.toml` - Public RPC (minimal read-only APIs)
3. `config-rpc-perm.toml` - Permissioned RPC (standard APIs with account permissioning)
4. `config-rpc-thirdweb.toml` - ThirdWeb RPC (ThirdWeb-compatible APIs)
5. `config-rpc-4.toml` - Permissioned RPC (identity 0x8a)
6. `config-rpc-putu-1.toml` - Putu's RPC (identity 0x1)
7. `config-rpc-putu-8a.toml` - Putu's RPC (identity 0x8a)
8. `config-rpc-luis-1.toml` - Luis's RPC (identity 0x1)
9. `config-rpc-luis-8a.toml` - Luis's RPC (identity 0x8a)
10. `config-member.toml` - Member nodes (RPC enabled)
11. `config-rpc.toml` (template) - General RPC template
12. `config-rpc-core.toml` (template) - Core RPC template
13. `config-rpc-4.toml` (template) - RPC-4 template

---

## Common Options (All RPC Configs)

These options are **identical** across all RPC configurations:

| Option | Value | Notes |
|--------|-------|-------|
| `network-id` | `138` | All on same network |
| `p2p-port` | `30303` | Standard P2P port |
| `rpc-http-port` | `8545` | Standard HTTP-RPC port |
| `rpc-ws-port` | `8546` | Standard WS-RPC port (if enabled) |
| `metrics-port` | `9545` | Prometheus metrics port |
| `sync-mode` | `"FULL"` | All use full sync |
| `logging` | `"WARN"` | Minimal logging (optimized) |
| `miner-enabled` | `false` | RPC nodes don't mine |
| `privacy-enabled` | `false` | No privacy features |
| `metrics-enabled` | `true` | All enable metrics |
| `permissions-nodes-config-file-enabled` | `true` | All use node permissioning |

---

## Variable Options (Differences)

### 1. RPC API Sets

| Config Type | HTTP APIs | WS APIs | Use Case |
|-------------|-----------|---------|----------|
| **Core** | `["ETH","NET","WEB3","TXPOOL","QBFT","ADMIN","DEBUG","TRACE"]` | `["ETH","NET","WEB3","TXPOOL","QBFT","ADMIN"]` | Internal/admin operations |
| **Public** | `["ETH","NET","WEB3"]` | `disabled` | Public read-only access |
| **Permissioned** | `["ETH","NET","WEB3","TXPOOL","QBFT"]` | `["ETH","NET","WEB3","TXPOOL","QBFT"]` | Application access |
| **ThirdWeb** | `["ETH","NET","WEB3","DEBUG","TRACE"]` | `["ETH","NET","WEB3"]` | ThirdWeb SDK compatibility |

**Analysis**: API sets vary by use case. Consolidation would require parameterization.

---

### 2. CORS Configuration

| Config Type | CORS Origins | Rationale |
|-------------|--------------|-----------|
| **Core** | `["http://192.168.11.0/24","http://localhost","http://127.0.0.1"]` | Internal network only |
| **Public** | `["*"]` | Public access |
| **Permissioned** | `["*"]` | Application access |
| **ThirdWeb** | `["*"]` | Public SDK access |
| **Putu/Luis** | `["*"]` | External application access |

**Analysis**: CORS varies by access model. Core RPC uses specific origins (hardened), others use wildcard.

---

### 3. WebSocket Configuration

| Config Type | WS Enabled | Port | APIs |
|-------------|------------|------|------|
| **Core** | ✅ Yes | 8546 | Full admin APIs |
| **Public** | ❌ No | - | Public doesn't need WS |
| **Permissioned** | ✅ Yes | 8546 | Standard APIs |
| **ThirdWeb** | ✅ Yes | 8546 | Standard APIs (recommended for ThirdWeb) |
| **Putu/Luis** | ✅ Yes | 8546 | Standard APIs |

**Analysis**: Public RPC is the only one without WebSocket. Others all use WS.

---

### 4. Discovery Configuration

| Config Type | Discovery Enabled | Rationale |
|-------------|-------------------|-----------|
| **Core** | ❌ No | Internal only, no public routing |
| **Public** | ✅ Yes | Public access needs discovery |
| **Permissioned** | ✅ Yes | Application access |
| **ThirdWeb** | ✅ Yes | Redundancy |
| **Putu/Luis** | ❌ No | Prevent Ethereum mainnet connection |

**Analysis**: Discovery enabled for public/application access, disabled for internal/external-network-isolation.

---

### 5. Max Peers Configuration

| Config Type | Max Peers | Rationale |
|-------------|-----------|-----------|
| **Core** | `25` | Standard peer count |
| **Public** | `25` | Standard peer count |
| **Permissioned** | `25` | Standard peer count |
| **ThirdWeb** | `50` | Higher for better connectivity |
| **Putu/Luis** | `25` | Standard peer count |

**Analysis**: ThirdWeb uses higher peer count (50) for better connectivity. Others use standard (25).

---

### 6. Path Configuration

| Config Type | data-path | genesis-file | static-nodes-file |
|-------------|-----------|--------------|-------------------|
| **Core** | `/data/besu` | `/genesis/genesis.json` | `/var/lib/besu/static-nodes.json` |
| **Public** | `/data/besu` | `/genesis/genesis.json` | `/genesis/static-nodes.json` |
| **Permissioned** | `/data/besu` or `/var/lib/besu` | `/genesis/genesis.json` | `/var/lib/besu/static-nodes.json` |
| **ThirdWeb** | `/data/besu` | `/genesis/genesis.json` | `/genesis/static-nodes.json` |
| **Putu/Luis** | `/var/lib/besu` | `/genesis/genesis.json` | `/var/lib/besu/static-nodes.json` |

**Analysis**: Minor path variations. Could be standardized.

---

### 7. Account Permissioning

| Config Type | Account Permissioning Enabled | File Path |
|-------------|------------------------------|-----------|
| **Core** | ❌ No | N/A |
| **Public** | ❌ No | N/A |
| **Permissioned** | ✅ Yes | `/permissions/permissions-accounts.toml` |
| **Putu/Luis** | ✅ Yes | `/permissions/permissions-accounts.toml` |
| **ThirdWeb** | ❌ No | N/A |

**Analysis**: Account permissioning only used for permissioned RPC nodes.

---

## Configuration Groups

### Group 1: Core/Admin RPC
- **Files**: `config-rpc-core.toml`
- **Characteristics**:
  - Full admin APIs (`ADMIN`, `DEBUG`, `TRACE`)
  - Specific CORS origins (hardened)
  - Discovery disabled (internal only)
  - Unique: Most restricted access

### Group 2: Public RPC
- **Files**: `config-rpc-public.toml`
- **Characteristics**:
  - Minimal read-only APIs
  - WebSocket disabled
  - CORS wildcard (public access)
  - Discovery enabled
  - Unique: WebSocket disabled

### Group 3: Application RPC (Standard)
- **Files**: `config-rpc-perm.toml`, `config-rpc.toml` (template)
- **Characteristics**:
  - Standard APIs (`TXPOOL`, `QBFT`)
  - WebSocket enabled
  - CORS wildcard
  - Discovery enabled
  - Account permissioning (varies)

### Group 4: ThirdWeb RPC
- **Files**: `config-rpc-thirdweb.toml`
- **Characteristics**:
  - ThirdWeb APIs (`DEBUG`, `TRACE`)
  - Higher `max-peers=50`
  - `rpc-http-timeout=60`
  - Unique: Optimized for ThirdWeb SDK

### Group 5: Identity-Specific RPC (Putu/Luis)
- **Files**: `config-rpc-putu-*.toml`, `config-rpc-luis-*.toml`, `config-rpc-4.toml`
- **Characteristics**:
  - Standard APIs
  - Discovery disabled (prevent mainnet connection)
  - Account permissioning enabled
  - Identity-specific (0x1 or 0x8a)
  - Unique: Discovery disabled for network isolation

---

## Consolidation Opportunities

### Option 1: Parameterized Template Script

**Approach**: Create a script that generates RPC configs from a base template with parameters.

**Parameters Needed**:
- `RPC_TYPE` (core, public, perm, thirdweb, identity)
- `RPC_APIS` (API array)
- `CORS_ORIGINS` (CORS array)
- `WS_ENABLED` (boolean)
- `DISCOVERY_ENABLED` (boolean)
- `MAX_PEERS` (number)
- `ACCOUNT_PERM_ENABLED` (boolean)

**Pros**:
- ✅ Single source of truth
- ✅ Easier to maintain common options
- ✅ Consistent base configuration

**Cons**:
- ⚠️ Adds complexity (script + parameters)
- ⚠️ May obscure differences
- ⚠️ Requires parameter management

**Recommendation**: Consider if RPC configs grow or change frequently.

---

### Option 2: Base Template + Overrides

**Approach**: Maintain base template with node-specific overrides.

**Structure**:
```
config-rpc-base.toml  # Common options
config-rpc-core.toml  # Base + core-specific
config-rpc-public.toml  # Base + public-specific
```

**Pros**:
- ✅ Clear separation of common vs. specific
- ✅ Easy to see differences
- ✅ Maintainable

**Cons**:
- ⚠️ Requires merge logic (not native TOML)
- ⚠️ Two files per node type

**Recommendation**: Not recommended (TOML doesn't support includes).

---

### Option 3: Documentation-Based Consolidation

**Approach**: Document common patterns, keep configs separate but consistent.

**Pros**:
- ✅ No changes to existing structure
- ✅ Clear documentation of patterns
- ✅ Easy to maintain current workflow

**Cons**:
- ⚠️ Manual consistency maintenance
- ⚠️ Changes must be applied to multiple files

**Recommendation**: ✅ **Recommended** - Current approach is appropriate given differences.

---

## Consolidation Analysis

### Can Configs Be Consolidated?

**Answer**: **Partially, but not recommended**

**Reasoning**:
1. **API differences** are significant (minimal vs. admin vs. standard)
2. **CORS policies** vary by access model (hardened vs. public)
3. **Discovery settings** vary by network isolation needs
4. **Account permissioning** varies by use case
5. **Identity-specific configs** (Putu/Luis) have unique requirements

### What CAN Be Standardized

✅ **Path configuration**: Minor variations could be standardized  
✅ **Common options**: All share same network-id, ports, logging  
✅ **Template structure**: Consistent format and organization  

### What CANNOT Be Consolidated

❌ **API sets**: Different use cases require different APIs  
❌ **CORS policies**: Different access models require different CORS  
❌ **Discovery**: Network isolation requirements vary  
❌ **Account permissioning**: Only some nodes need it  

---

## Recommendations

### Current State Assessment

**Current Structure**: ✅ **Appropriate**

The 13 RPC config files serve distinct purposes:
- Core RPC: Internal admin operations (unique APIs, hardened CORS)
- Public RPC: Public read-only access (minimal APIs, no WS)
- Permissioned RPC: Application access (standard APIs, permissioning)
- ThirdWeb RPC: SDK optimization (higher peers, timeouts)
- Identity RPC: External integration (network isolation)

**Differences are justified** by use case requirements.

---

### Improvement Opportunities

#### 1. Path Standardization
**Recommendation**: Standardize paths across all RPC configs
- Use `/data/besu` for data-path (consistent)
- Use `/var/lib/besu/` for permissions/static-nodes (consistent)

**Impact**: Low effort, improves consistency

#### 2. Template Maintenance
**Recommendation**: Keep templates up-to-date with common options
- Update base template when common options change
- Ensure all configs derive from templates

**Impact**: Medium effort, prevents drift

#### 3. Configuration Generator (Future)
**Recommendation**: If RPC configs grow, consider parameterized generator
- Only if number of configs exceeds 20+
- Only if frequent changes to common options

**Impact**: High effort, only if scale requires it

---

## Configuration Template Structure

### Recommended Template Hierarchy

```
templates/besu-configs/
├── config-validator.toml     # Validator template
├── config-sentry.toml         # Sentry template
├── config-rpc-base.toml       # Base RPC template (if needed)
├── config-rpc-core.toml       # Core RPC template
├── config-rpc-public.toml     # Public RPC template
├── config-rpc-perm.toml       # Permissioned RPC template
└── config-rpc-thirdweb.toml   # ThirdWeb RPC template
```

**Note**: Identity-specific configs (Putu/Luis) should remain separate as they have unique requirements.

---

## Summary

### Configuration Count
- **Total RPC Configs**: 13 files
- **Template Files**: 4 templates
- **Source Configs**: 9 source files

### Consolidation Potential
- **Can Consolidate**: Paths (minor standardization)
- **Cannot Consolidate**: API sets, CORS, discovery, permissioning

### Recommendation
✅ **Maintain current structure** with path standardization improvements.

The current multi-config approach is appropriate because:
1. Each config serves a distinct purpose
2. Differences are justified by use cases
3. Consolidation would add complexity without significant benefit
4. Current structure is maintainable and clear

---

## Related Documentation

- `docs/04-configuration/BESU_CONFIGURATION_GUIDE.md` - Configuration reference
- `docs/04-configuration/BESU_PATH_REFERENCE.md` - Path structure
- `scripts/audit-besu-configs.sh` - Configuration audit tool

---

**Last Updated**: 2026-01-17  
**Status**: Analysis Complete