# RPC Node Types Architecture

## Overview

RPC nodes 2500-2502 represent **different types** of RPC nodes, not redundant instances of the same type. Each node serves a specific purpose and cannot be used as a failover for another type.

---

## RPC Node Types

### Type 1: Public RPC Node (`config-rpc-public.toml`)
- **Purpose**: Public-facing RPC endpoints for dApps and external users
- **APIs**: ETH, NET, WEB3 (read-only)
- **Access**: Public (CORS enabled, host allowlist: "*")
- **Use Cases**: 
  - Public dApp connections
  - Blockchain explorers
  - External tooling access
  - General-purpose RPC queries

### Type 2: Core RPC Node (`config-rpc-core.toml`)
- **Purpose**: Internal/core infrastructure RPC endpoints
- **APIs**: May include ADMIN, DEBUG (if needed)
- **Access**: Restricted (internal network only)
- **Use Cases**:
  - Internal service connections
  - Core infrastructure tooling
  - Administrative operations
  - Restricted API access

### Type 3: Permissioned RPC Node (`config-rpc-perm.toml`)
- **Purpose**: Permissioned RPC with account-level access control
- **APIs**: Custom based on permissions
- **Access**: Permissioned (account-based allowlist)
- **Use Cases**:
  - Enterprise/private access
  - Permissioned dApps
  - Controlled API access

### Type 4/5: (Additional types as defined in your source project)
- **Purpose**: Additional specialized RPC node types
- **Use Cases**: Depends on specific requirements

---

## Current Deployment (2500-2502)

**RPC Node Type Mapping**:

| VMID | IP Address | Node Type | Config File | Purpose |
|------|------------|-----------|-------------|---------|
| 2500 | 192.168.11.250 | **Core** | `config-rpc-core.toml` | Internal/core infrastructure RPC endpoints |
| 2501 | 192.168.11.251 | **Permissioned** | `config-rpc-perm.toml` | Permissioned RPC (Requires Auth, select APIs) |
| 2502 | 192.168.11.252 | **Public** | `config-rpc-public.toml` | Public RPC (none or minimal APIs) |

**Notes**:
- These are 3 of 4 or 5 total RPC node types
- Additional RPC nodes will be added later for load balancing and High Availability/Failover
- Each type serves a distinct purpose and cannot substitute for another type

---

## nginx-proxy-manager Architecture (Corrected)

Since these are **different types**, not redundant instances, nginx-proxy-manager should route based on **request type/purpose**, not load balance:

### Recommended Architecture

```
Public Requests → nginx-proxy-manager → Public RPC Node (2502:8545)
Core/Internal Requests → nginx-proxy-manager → Core RPC Node (2500:8545)
Permissioned Requests → nginx-proxy-manager → Permissioned RPC Node (2501:8545)
```

**With Cloudflare Integration (VMID 102: cloudflared)**:
```
Internet → Cloudflare → cloudflared (VMID 102) → nginx-proxy-manager (VMID 105) → RPC Nodes
```

### nginx-proxy-manager Configuration

**Separate Proxy Hosts for Each Type**:

1. **Core RPC Proxy** (VMID 2500):
   - Domain: `rpc-core.besu.local` or `rpc-core.chainid138.local`
   - Forward to: `192.168.11.250:8545` (Core RPC node)
   - Purpose: Internal/core infrastructure RPC endpoints
   - Access: Restrict to internal network IPs
   - APIs: Full APIs (ADMIN, DEBUG, ETH, NET, WEB3, etc.)

2. **Permissioned RPC Proxy** (VMID 2501):
   - Domain: `rpc-perm.besu.local` or `rpc-perm.chainid138.local`
   - Forward to: `192.168.11.251:8545` (Permissioned RPC node)
   - Purpose: Permissioned RPC (Requires Auth, select APIs)
   - Access: Authentication/authorization required
   - APIs: Select APIs based on permissions

3. **Public RPC Proxy** (VMID 2502):
   - Domain: `rpc.besu.local` or `rpc-public.chainid138.local`
   - Forward to: `192.168.11.252:8545` (Public RPC node)
   - Purpose: Public RPC (none or minimal APIs)
   - Access: Public (with rate limiting recommended)
   - APIs: Minimal APIs (ETH, NET, WEB3 - read-only)

**Cloudflare Integration** (VMID 102: cloudflared):
- Cloudflare tunnels route through cloudflared (VMID 102) to nginx-proxy-manager (VMID 105)
- Provides DDoS protection, SSL termination, and global CDN
- See `docs/CLOUDFLARE_NGINX_INTEGRATION.md` for configuration details

---

## High Availability Considerations

### ❌ NO Failover Between Types
You **cannot** failover from one type to another because:
- Different APIs exposed
- Different access controls
- Different use cases
- Clients expect specific functionality

### ✅ HA Options (If Needed)

**Option 1: Deploy Multiple Instances of Same Type**
- If you need HA for Public RPC, deploy multiple Public RPC nodes (e.g., 2500, 2503)
- Then nginx-proxy-manager can load balance between them
- Same for Core RPC (2501, 2504) and Permissioned RPC (2502, 2505)

**Option 2: Accept Single-Instance Risk**
- For non-critical types, accept single instance
- Only deploy HA for critical types (e.g., Public RPC)

**Option 3: Different VMID Ranges for Same Types**
- Public RPC: 2500-2502 (if all 3 are public)
- Core RPC: 2503-2504 (2 instances)
- Permissioned RPC: 2505 (1 instance)

---

## Future Expansion

**Additional RPC Nodes for HA/Load Balancing**:
- Additional instances of existing types (Core, Permissioned, Public) will be deployed
- Load balancing and failover will be configured within each type
- VMID ranges: 2503+ (within the 2500-3499 RPC range)

**Example Future Configuration**:
- Core RPC: 2500, 2503, 2504 (3 instances for HA)
- Permissioned RPC: 2501, 2505 (2 instances for HA)
- Public RPC: 2502, 2506, 2507 (3 instances for HA/load distribution)

---

## Updated Recommendation

### If RPC Nodes 2500-2502 are Different Types:

**nginx-proxy-manager should route by type**, not load balance:

1. **Configure separate proxy hosts** for each type
2. **Route requests based on domain/subdomain** to appropriate node
3. **No load balancing** (since they're different types)
4. **SSL termination** for all types
5. **Access control** based on type (internal vs public)

### Benefits:
- ✅ Proper routing to correct node type
- ✅ SSL termination
- ✅ Centralized management
- ✅ Access control per type
- ✅ Clear separation of concerns

### NOT Appropriate:
- ❌ Load balancing across different types
- ❌ Failover from one type to another
- ❌ Treating them as redundant instances

---

## Next Steps

1. ✅ **RPC node types identified**: 
   - 2500 → Core (`config-rpc-core.toml`)
   - 2501 → Permissioned (`config-rpc-perm.toml`)
   - 2502 → Public (`config-rpc-public.toml`)

2. **Update deployment scripts**: Ensure each node gets the correct config file type
   - Update `scripts/copy-besu-config-with-nodes.sh` to map VMID to correct config file
   - Ensure node-specific configs in `config/nodes/rpc-*/` are properly identified

3. **Configure nginx-proxy-manager (VMID 105)**: Set up type-based routing
   - Core RPC: `rpc-core.*` → 192.168.11.250:8545
   - Permissioned RPC: `rpc-perm.*` → 192.168.11.251:8545
   - Public RPC: `rpc.*` or `rpc-public.*` → 192.168.11.252:8545

4. **Configure Cloudflare Integration**: Set up cloudflared (VMID 102) to route through nginx-proxy-manager
   - See `docs/CLOUDFLARE_NGINX_INTEGRATION.md` for details


---

## Script Updates Required

---

## Related Documentation

- **[RPC_TEMPLATE_TYPES.md](RPC_TEMPLATE_TYPES.md)** ⭐⭐⭐ - RPC template types reference
- **[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
- **[CLOUDFLARE_NGINX_INTEGRATION.md](CLOUDFLARE_NGINX_INTEGRATION.md)** - Cloudflare + NGINX integration
- **[../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

### Updated: `scripts/copy-besu-config-with-nodes.sh`

The script has been updated to map each VMID to its specific RPC type and config file:

```bash
# RPC Node Type Mapping
2500 → core    → config-rpc-core.toml
2501 → perm    → config-rpc-perm.toml
2502 → public  → config-rpc-public.toml
```

**File Detection Priority** (for each RPC node):
1. Node-specific config: `config/nodes/rpc-N/config.toml` (if nodes/ structure exists)
2. Node-specific type config: `config/nodes/rpc-N/config-rpc-{type}.toml`
3. Flat structure: `config/config-rpc-{type}.toml`
4. Fallback (backwards compatibility): May use alternative config if exact type not found

