proxmox/docs/04-configuration/RPC_CONFIG_ANALYSIS.md

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