# RPC Node Types: Detailed Comparison

## Overview

This document provides a detailed comparison of the three RPC node types deployed in the Besu network (VMIDs 2500-2502).

---

## Quick Reference

| Aspect | Core RPC (2500) | Permissioned RPC (2501) | Public RPC (2502) |
|--------|-----------------|-------------------------|-------------------|
| **VMID** | 2500 | 2501 | 2502 |
| **Config File** | `config-rpc-core.toml` | `config-rpc-perm.toml` | `config-rpc-public.toml` |
| **IP Address** | 192.168.11.250 | 192.168.11.251 | 192.168.11.252 |
| **Primary Purpose** | Internal/core infrastructure | Permissioned access | Public dApp access |
| **Access Level** | Internal network only | Authenticated users | Public (rate limited) |
| **API Scope** | Full (including ADMIN/DEBUG) | Selective (based on permissions) | Minimal (read-only) |

---

## 1. Core RPC Node (VMID 2500)

### Purpose
Internal/core infrastructure RPC endpoints for system-level operations and administrative tasks.

### Configuration File
- **Source**: `config/config-rpc-core.toml` or `config/nodes/rpc-1/config-rpc-core.toml`
- **Destination**: `/etc/besu/config-rpc-core.toml`
- **Service**: `besu-rpc.service` (updated to use correct config file)

### APIs Enabled
- **ETH**: Ethereum protocol methods (full access)
- **NET**: Network information (full access)
- **WEB3**: Web3 client version (full access)
- **ADMIN**: Administrative methods (enabled)
- **DEBUG**: Debug/trace methods (enabled, if configured)
- **CLIQUE**: Consensus methods (if applicable)
- **IBFT**: Consensus methods (if applicable)
- **QBFT**: Consensus methods (if applicable)
- **PERM**: Permissioning methods (if applicable)
- **PLUGINS**: Plugin methods (if applicable)
- **TXPOOL**: Transaction pool methods (if applicable)
- **TRACE**: Tracing methods (if configured)

### Access Controls
- **Host Allowlist**: Restricted to internal network IPs (e.g., `192.168.11.0/24`)
- **CORS Origins**: Restricted or disabled
- **Authentication**: Internal network access (firewall-based)
- **Rate Limiting**: Usually not required (internal use)

### Use Cases
1. **Internal Service Connections**
   - Core infrastructure services connecting to blockchain
   - Internal monitoring and analytics tools
   - Administrative dashboards

2. **Administrative Operations**
   - Node management and configuration
   - Debugging and troubleshooting
   - Performance monitoring and analysis

3. **System Integration**
   - Backend services requiring full API access
   - Internal dApps with elevated permissions
   - Development and testing environments

### Security Considerations
- Should **NOT** be exposed to the public internet
- Use firewall rules to restrict access to internal network
- Monitor access logs for unauthorized attempts
- Consider VPN or bastion host for remote administrative access

### nginx-proxy-manager Configuration
- **Domain**: `rpc-core.besu.local`, `rpc-core.chainid138.local`
- **Forward To**: `192.168.11.250:8545`
- **Access Control**: Restrict to internal network IPs
- **SSL**: Optional (internal network)

---

## 2. Permissioned RPC Node (VMID 2501)

### Purpose
Permissioned RPC access with account-level authentication and selective API access based on user permissions.

### Configuration File
- **Source**: `config/config-rpc-perm.toml` or `config/nodes/rpc-2/config-rpc-perm.toml`
- **Destination**: `/etc/besu/config-rpc-perm.toml`
- **Service**: `besu-rpc.service` (updated to use correct config file)

### APIs Enabled
- **ETH**: Ethereum protocol methods (selective, based on permissions)
- **NET**: Network information (selective)
- **WEB3**: Web3 client version (typically enabled)
- **ADMIN**: Usually disabled (administrative access via Core RPC)
- **DEBUG**: Usually disabled (debug access via Core RPC)
- **Other APIs**: Enabled based on permission configuration

### Access Controls
- **Host Allowlist**: May be restricted or open (authentication handles access)
- **CORS Origins**: Configured based on allowed origins
- **Authentication**: Required (account-based or API key)
- **Authorization**: Permission-based API access
- **Rate Limiting**: Recommended (per user/account)

### Permission Configuration
Typically uses:
- **Account Permissioning**: `permissions-accounts.toml` enabled
- **Account Allowlist**: Only authorized accounts can access
- **API Permissions**: Specific APIs enabled per account/user group

### Use Cases
1. **Enterprise Access**
   - Enterprise customers requiring authenticated access
   - Private dApps with user authentication
   - Corporate blockchain integration

2. **Controlled API Access**
   - Services requiring specific API subsets
   - Multi-tenant applications with permission isolation
   - B2B integrations with access agreements

3. **Compliance Requirements**
   - Regulated environments requiring access control
   - Audit trails for API access
   - KYC/AML compliant access

### Security Considerations
- Implement strong authentication (API keys, OAuth, etc.)
- Use account permissioning (`permissions-accounts.toml`)
- Monitor and log all API access
- Implement rate limiting per account/user
- Regular access review and revocation

### nginx-proxy-manager Configuration
- **Domain**: `rpc-perm.besu.local`, `rpc-perm.chainid138.local`
- **Forward To**: `192.168.11.251:8545`
- **Access Control**: Configure authentication/authorization middleware
- **SSL**: Required (HTTPS/TLS)

---

## 3. Public RPC Node (VMID 2502)

### Purpose
Public-facing RPC endpoints for dApps and external users with minimal, read-only API access.

### Configuration File
- **Source**: `config/config-rpc-public.toml` or `config/nodes/rpc-3/config-rpc-public.toml`
- **Destination**: `/etc/besu/config-rpc-public.toml`
- **Service**: `besu-rpc.service` (updated to use correct config file)

### APIs Enabled
- **ETH**: Ethereum protocol methods (read-only subset)
  - `eth_blockNumber`
  - `eth_getBalance`
  - `eth_getTransactionCount`
  - `eth_call`
  - `eth_getCode`
  - `eth_getBlockByNumber`
  - `eth_getBlockByHash`
  - `eth_getTransactionByHash`
  - `eth_getTransactionReceipt`
  - Read-only methods only (NO `eth_sendRawTransaction`)
- **NET**: Network information (read-only)
  - `net_version`
  - `net_peerCount`
  - `net_listening`
- **WEB3**: Web3 client version
  - `web3_clientVersion`
- **ADMIN**: Disabled (security)
- **DEBUG**: Disabled (security)
- **Other APIs**: Disabled (security)

### Access Controls
- **Host Allowlist**: `["*"]` (public access)
- **CORS Origins**: `["*"]` or specific domains
- **Authentication**: None (public access)
- **Rate Limiting**: Required (protect against abuse)

### Use Cases
1. **Public dApp Connections**
   - Public-facing decentralized applications
   - Wallet integrations
   - Browser-based dApps

2. **Blockchain Explorers**
   - Public block explorers
   - Transaction lookup services
   - Address balance queries

3. **External Tooling**
   - Public API access for developers
   - Third-party integrations
   - General-purpose blockchain queries

### Security Considerations
- **No write operations** (transactions must be signed and sent via other means)
- Implement aggressive rate limiting (prevent DDoS)
- Monitor for abuse patterns
- Use Cloudflare or similar DDoS protection
- Consider IP-based blocking for abusive users
- Regular security audits

### nginx-proxy-manager Configuration
- **Domain**: `rpc.besu.local`, `rpc-public.chainid138.local`, `rpc.chainid138.local`
- **Forward To**: `192.168.11.252:8545`
- **Access Control**: Public (with rate limiting)
- **SSL**: Required (HTTPS/TLS)
- **DDoS Protection**: Enable Cloudflare protection
- **Rate Limiting**: Configure aggressive limits

---

## API Comparison Matrix

| API Method | Core RPC | Permissioned RPC | Public RPC |
|------------|----------|------------------|------------|
| `eth_blockNumber` | ✅ | ✅ | ✅ |
| `eth_getBalance` | ✅ | ✅ | ✅ |
| `eth_call` | ✅ | ✅ (conditional) | ✅ |
| `eth_sendRawTransaction` | ✅ | ✅ (conditional) | ❌ |
| `eth_getTransactionReceipt` | ✅ | ✅ | ✅ |
| `debug_traceTransaction` | ✅ | ❌ | ❌ |
| `admin_peers` | ✅ | ❌ | ❌ |
| `admin_nodeInfo` | ✅ | ❌ | ❌ |
| `txpool_content` | ✅ | ❌ | ❌ |

---

## When to Use Each Type

### Use Core RPC (2500) When:
- ✅ Building internal services
- ✅ Need administrative/debug APIs
- ✅ Internal network access is acceptable
- ✅ Full API access required
- ✅ System-level operations

### Use Permissioned RPC (2501) When:
- ✅ Building enterprise applications
- ✅ Require user authentication
- ✅ Need selective API access per user
- ✅ Compliance/audit requirements
- ✅ B2B integrations

### Use Public RPC (2502) When:
- ✅ Building public dApps
- ✅ Public read-only access needed
- ✅ Wallet integrations
- ✅ Public blockchain explorers
- ✅ General-purpose queries

---

## Network Topology

```
Internet
  ↓
Cloudflare (DDoS Protection, SSL)
  ↓
cloudflared (VMID 102)
  ↓
nginx-proxy-manager (VMID 105)
  ↓
  ├─→ Core RPC (2500) ← Internal Services
  ├─→ Permissioned RPC (2501) ← Authenticated Users
  └─→ Public RPC (2502) ← Public dApps
```

---

## Configuration File Locations

### Source Project Structure
```
smom-dbis-138/
└── config/
    ├── config-rpc-core.toml        # Core RPC config
    ├── config-rpc-perm.toml        # Permissioned RPC config
    ├── config-rpc-public.toml      # Public RPC config
    └── nodes/
        ├── rpc-1/
        │   └── config-rpc-core.toml (or config.toml)
        ├── rpc-2/
        │   └── config-rpc-perm.toml (or config.toml)
        └── rpc-3/
            └── config-rpc-public.toml (or config.toml)
```

### Container Locations
- **Core RPC**: `/etc/besu/config-rpc-core.toml`
- **Permissioned RPC**: `/etc/besu/config-rpc-perm.toml`
- **Public RPC**: `/etc/besu/config-rpc-public.toml`

---

## Deployment Notes

1. **Systemd Service Update**: The `copy-besu-config-with-nodes.sh` script automatically updates the systemd service file to use the correct config file for each RPC node type.

2. **Service File Location**: `/etc/systemd/system/besu-rpc.service` (same for all RPC types)

3. **Service Command**: Each service uses `--config-file=$BESU_CONFIG/config-rpc-{type}.toml` based on the node type.

4. **Validation**: The validation script checks for the correct config file per VMID:
   - 2500: `config-rpc-core.toml`
   - 2501: `config-rpc-perm.toml`
   - 2502: `config-rpc-public.toml`

---

## References

- **RPC Node Types Architecture**: `docs/RPC_NODE_TYPES_ARCHITECTURE.md`
- **Cloudflare/Nginx Integration**: `docs/CLOUDFLARE_NGINX_INTEGRATION.md`
- **Nginx Architecture**: `docs/NGINX_ARCHITECTURE_RPC.md`
- **Besu Documentation**: https://besu.hyperledger.org/

