# RPC Template Types Reference

This document describes the different RPC configuration template types used in the deployment.

## RPC Template Types

### 1. `config-rpc-public.toml` (Primary)

**Location**: 
- Source: `config/config-rpc-public.toml` (in source project)
- Destination: `/etc/besu/config-rpc-public.toml` (on RPC nodes)

**Purpose**: Public-facing RPC node configuration with full RPC API access

**Characteristics**:
- HTTP RPC enabled on port 8545
- WebSocket RPC enabled on port 8546
- Public API access (CORS enabled, host allowlist: "*")
- Read-only APIs: `ETH`, `NET`, `WEB3`
- Metrics enabled on port 9545
- Full sync mode
- Discovery enabled
- P2P enabled on port 30303

**Used For**: 
- Public RPC endpoints
- dApp connections
- External tooling access
- Blockchain explorers

**Scripts That Use It**:
- `besu-rpc-install.sh` - Creates template at installation
- `copy-besu-config.sh` - Copies from source project (primary)
- `copy-besu-config-with-nodes.sh` - Copies from source project or nodes/ directories

---

### 2. `config-rpc-core.toml` (Alternative/Fallback)

**Location**: 
- Source: `config/config-rpc-core.toml` (in source project)
- Destination: `/etc/besu/config-rpc-public.toml` (on RPC nodes - renamed during copy)

**Purpose**: Alternative RPC configuration, typically with more restricted access

**Characteristics**:
- Similar to `config-rpc-public.toml` but may have different security settings
- Used as fallback if `config-rpc-public.toml` is not found
- Renamed to `config-rpc-public.toml` when copied to containers

**Used For**: 
- Internal RPC nodes with restricted access
- Core infrastructure RPC endpoints
- Alternative configuration option

**Scripts That Use It**:
- `copy-besu-config.sh` - Fallback if `config-rpc-public.toml` not found
- `copy-besu-config-with-nodes.sh` - Checks both types

---

### 2b. `config-rpc-perm.toml` (Permissioned RPC)

**Location**: 
- Source: `config/config-rpc-perm.toml` (in source project)
- Destination: Not currently used in deployment scripts (would need to be manually copied)

**Purpose**: Permissioned RPC configuration with account permissioning enabled

**Characteristics**:
- May have account permissioning enabled
- Different access controls than public RPC
- Currently not automatically deployed by scripts

**Used For**: 
- Permissioned RPC endpoints
- Account-restricted access
- Enhanced security configurations

**Scripts That Use It**:
- Currently not used in deployment scripts
- Available in source project for manual configuration if needed

**Note**: This file exists in the source project but is not currently integrated into the deployment scripts. To use it, you would need to manually copy it or modify the deployment scripts.

---

### 3. Template from Install Script (Fallback)

**Location**: 
- Source: Created by `besu-rpc-install.sh` at `/etc/besu/config-rpc-public.toml.template`
- Destination: `/etc/besu/config-rpc-public.toml` (copied if no source config found)

**Purpose**: Default template created during Besu installation

**Characteristics**:
- Basic RPC configuration
- Public access enabled
- Full API access
- Created automatically during installation

**Used For**: 
- Fallback if no source configuration is provided
- Initial setup before configuration copy

**Scripts That Use It**:
- `besu-rpc-install.sh` - Creates the template
- `copy-besu-config.sh` - Uses as last resort fallback

---

## Template Selection Priority

The deployment scripts use the following priority order:

1. **Primary**: `config/config-rpc-public.toml` from source project
2. **Alternative**: `config/config-rpc-core.toml` from source project (renamed to `config-rpc-public.toml`)
3. **Node-Specific**: `config/nodes/rpc-*/config.toml` (if using nodes/ structure)
4. **Fallback**: Template from install script (`config-rpc-public.toml.template`)

**Note**: `config-rpc-perm.toml` exists in the source project but is **not currently used** by deployment scripts. It's available for manual configuration if permissioned RPC is needed.

---

## Script Behavior

### `copy-besu-config.sh`

```bash
# Priority 1: config-rpc-public.toml
RPC_CONFIG="$SOURCE_PROJECT/config/config-rpc-public.toml"

# Priority 2: config-rpc-core.toml (fallback)
if not found:
    RPC_CONFIG="$SOURCE_PROJECT/config/config-rpc-core.toml"
    # Copies as config-rpc-public.toml

# Priority 3: Install script template (last resort)
if not found:
    pct exec "$vmid" -- cp /etc/besu/config-validator.toml.template /etc/besu/config-rpc-public.toml
```

### `copy-besu-config-with-nodes.sh`

```bash
# For each RPC node:
# Priority 1: config/nodes/rpc-*/config.toml (if nodes/ structure exists)
# Priority 2: config/config-rpc-public.toml
# Priority 3: config/config-rpc-core.toml
for name in "config-rpc-public.toml" "config-rpc-core.toml"; do
    # Try to find in nodes/ directory or flat structure
done
```

---

## Configuration Differences

### `config-rpc-public.toml` (Typical)

```toml
# Public RPC Configuration
rpc-http-enabled=true
rpc-http-host="0.0.0.0"
rpc-http-port=8545
rpc-http-api=["ETH","NET","WEB3"]
rpc-http-cors-origins=["*"]
rpc-http-host-allowlist=["*"]

rpc-ws-enabled=true
rpc-ws-host="0.0.0.0"
rpc-ws-port=8546
rpc-ws-api=["ETH","NET","WEB3"]
rpc-ws-origins=["*"]
```

### `config-rpc-core.toml` (Typical)

```toml
# Core/Internal RPC Configuration
# May have:
# - Restricted host allowlist
# - Additional APIs enabled (ADMIN, DEBUG, etc.)
# - Different security settings
# - Internal network access only
```

---

## Location Summary

| Template Type | Source Location | Container Location | Priority | Status |
|--------------|----------------|-------------------|----------|--------|
| `config-rpc-public.toml` | `config/config-rpc-public.toml` | `/etc/besu/config-rpc-public.toml` | 1 | ✅ Active |
| `config-rpc-core.toml` | `config/config-rpc-core.toml` | `/etc/besu/config-rpc-public.toml` | 2 | ✅ Active (fallback) |
| `config-rpc-perm.toml` | `config/config-rpc-perm.toml` | (Manual copy) | N/A | ⚠️ Available but not used |
| Node-specific | `config/nodes/rpc-*/config.toml` | `/etc/besu/config-rpc-public.toml` | 1 (if nodes/ exists) | ✅ Active |
| Install template | Created by install script | `/etc/besu/config-rpc-public.toml.template` | 3 | ✅ Fallback |

---

## Validation

The comprehensive validation script (`validate-deployment-comprehensive.sh`) checks that:
- RPC nodes (2500-2502) have type-specific config files:
  - VMID 2500: `config-rpc-core.toml`
  - VMID 2501: `config-rpc-perm.toml`
  - VMID 2502: `config-rpc-public.toml`
- No incorrect config files exist on RPC nodes (e.g., validator or sentry configs)

---

## Current Usage

**Active Configuration**: 
- All RPC nodes (2500-2502) use type-specific config files (see `docs/RPC_NODE_TYPES_ARCHITECTURE.md`)
- Scripts check for both `config-rpc-public.toml` and `config-rpc-core.toml` from source project
- If neither exists, uses install script template as fallback

**Recommended**: 
- Use `config-rpc-public.toml` from source project
- `config-rpc-core.toml` is available as alternative if needed
- Both are copied as `config-rpc-public.toml` to containers

---

## Related Documentation

- **[RPC_NODE_TYPES_ARCHITECTURE.md](RPC_NODE_TYPES_ARCHITECTURE.md)** ⭐⭐⭐ - RPC node types architecture
- **[NGINX_ARCHITECTURE_RPC.md](NGINX_ARCHITECTURE_RPC.md)** ⭐⭐ - NGINX architecture for RPC
- **[RPC_2500_CONFIGURATION_SUMMARY.md](RPC_2500_CONFIGURATION_SUMMARY.md)** - RPC 2500 configuration
- **[../06-besu/BESU_NODES_FILE_REFERENCE.md](../06-besu/BESU_NODES_FILE_REFERENCE.md)** - Besu nodes file reference

---

**Last Updated:** 2025-01-20  
**Document Version:** 1.0  
**Review Cycle:** Quarterly

