fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands - CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround - CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check - NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere - MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates - LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference Co-authored-by: Cursor <cursoragent@cursor.com>
397 lines
12 KiB
Markdown
397 lines
12 KiB
Markdown
# 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
|