proxmox/docs/archive/configuration/THIRDWEB_RPC_SETUP.md

# ThirdWeb RPC Node Setup Guide

This guide explains how to set up RPC node LXC containers optimized for ThirdWeb integration.

## Overview

ThirdWeb RPC nodes are Besu RPC nodes configured specifically for ThirdWeb SDK and dApp integration. They provide:
- Standard JSON-RPC endpoints (ETH, NET, WEB3)
- WebSocket support for real-time subscriptions
- CORS enabled for web applications
- Optimized transaction pool settings
- Extended API support (DEBUG, TRACE) for development

## Container Specifications

| VMID | Hostname | IP Address | Memory | CPU | Disk | Purpose |
|------|----------|------------|--------|-----|------|---------|
| 2400 | thirdweb-rpc-1 | 192.168.11.240 | 16GB | 4 cores | 200GB | Primary RPC Node |
| 2401 | thirdweb-rpc-2 | 192.168.11.241 | 16GB | 4 cores | 200GB | Secondary RPC Node |
| 2402 | thirdweb-rpc-3 | 192.168.11.242 | 16GB | 4 cores | 200GB | Tertiary RPC Node |

**Note**: VMIDs align with IP addresses - VMID 2400 = 192.168.11.240, etc.

## Quick Start

### 1. Run the Setup Script

```bash
cd /home/intlc/projects/proxmox
./scripts/setup-thirdweb-rpc-nodes.sh
```

Or with non-interactive mode:

```bash
NON_INTERACTIVE=1 ./scripts/setup-thirdweb-rpc-nodes.sh
```

### 2. Verify Containers

```bash
# Check container status
ssh root@192.168.11.10 "pct list | grep -E '240[0-2]'"

# Check Besu service status
ssh root@192.168.11.10 "pct exec 2400 -- systemctl status besu-rpc.service"
```

### 3. Test RPC Endpoints

```bash
# Test HTTP RPC
curl -X POST http://192.168.11.240:8545 \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Test WebSocket (using wscat or similar)
wscat -c ws://192.168.11.240:8546
```

## Configuration Details

### ThirdWeb-Optimized Settings

The configuration (`config-rpc-thirdweb.toml`) includes:

- **Extended APIs**: ETH, NET, WEB3, DEBUG, TRACE
- **WebSocket Support**: Enabled on port 8546
- **CORS**: Enabled for all origins (`*`)
- **Transaction Pool**: Increased to 16,384 for high-volume operations
- **P2P Peers**: Increased to 50 for better connectivity
- **Timeout**: Extended to 60 seconds for complex operations

### Key Differences from Standard RPC

| Setting | Standard RPC | ThirdWeb RPC |
|---------|-------------|--------------|
| APIs | ETH, NET, WEB3 | ETH, NET, WEB3, DEBUG, TRACE |
| WebSocket | Optional | Enabled |
| TX Pool Size | 8,192 | 16,384 |
| Max Peers | 25 | 50 |
| RPC Timeout | Default (30s) | 60s |

## ThirdWeb Integration

### Using with ThirdWeb SDK

Configure ThirdWeb to use your custom RPC endpoint:

```javascript
import { ThirdwebSDK } from "@thirdweb-dev/sdk";

// HTTP RPC endpoint
const sdk = new ThirdwebSDK("http://192.168.11.240:8545", {
  supportedChains: [138], // Your ChainID
});

// Or with WebSocket for subscriptions
const sdk = new ThirdwebSDK("ws://192.168.11.240:8546", {
  supportedChains: [138],
});
```

### Environment Variables

```bash
# .env file
THIRDWEB_RPC_URL=http://192.168.11.240:8545
THIRDWEB_RPC_WS_URL=ws://192.168.11.240:8546
CHAIN_ID=138
```

### ThirdWeb Dashboard Configuration

1. Go to ThirdWeb Dashboard → Settings → Networks
2. Add Custom Network:
   - **Network Name**: ChainID 138 (Custom)
   - **RPC URL**: `http://192.168.11.240:8545`
   - **Chain ID**: `138`
   - **Currency Symbol**: Your token symbol
   - **Block Explorer**: (Optional) Your explorer URL

## Maintenance

### Start/Stop Services

```bash
# Start Besu service
ssh root@192.168.11.10 "pct exec 2400 -- systemctl start besu-rpc.service"

# Stop Besu service
ssh root@192.168.11.10 "pct exec 2400 -- systemctl stop besu-rpc.service"

# Restart Besu service
ssh root@192.168.11.10 "pct exec 2400 -- systemctl restart besu-rpc.service"
```

### View Logs

```bash
# View recent logs
ssh root@192.168.11.10 "pct exec 2400 -- journalctl -u besu-rpc.service -n 100"

# Follow logs in real-time
ssh root@192.168.11.10 "pct exec 2400 -- journalctl -u besu-rpc.service -f"
```

### Monitor Performance

```bash
# Check metrics endpoint
curl http://192.168.11.240:9545/metrics

# Check container resource usage
ssh root@192.168.11.10 "pct exec 2400 -- top -bn1 | grep -E 'CPU|Mem'"
```

## Troubleshooting

### Container Not Starting

```bash
# Check container status
ssh root@192.168.11.10 "pct status 2400"

# Check container logs
ssh root@192.168.11.10 "pct config 2400"

# Start container manually
ssh root@192.168.11.10 "pct start 2400"
```

### Besu Service Not Running

```bash
# Check service status
ssh root@192.168.11.10 "pct exec 2400 -- systemctl status besu-rpc.service"

# Check configuration
ssh root@192.168.11.10 "pct exec 2400 -- cat /etc/besu/config-rpc-thirdweb.toml"

# Verify Besu installation
ssh root@192.168.11.10 "pct exec 2400 -- /opt/besu/bin/besu --version"
```

### RPC Endpoint Not Responding

```bash
# Test connectivity
ping -c 3 192.168.11.240

# Test port accessibility
nc -zv 192.168.11.240 8545

# Check firewall rules
ssh root@192.168.11.10 "iptables -L -n | grep 8545"
```

## Load Balancing

For production use, consider setting up load balancing across the three RPC nodes:

### Nginx Load Balancer Example

```nginx
upstream thirdweb_rpc {
    least_conn;
    server 192.168.11.240:8545;
    server 192.168.11.241:8545;
    server 192.168.11.242:8545;
}

server {
    listen 80;
    server_name rpc.thirdweb.yourdomain.com;

    location / {
        proxy_pass http://thirdweb_rpc;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Increase timeout for ThirdWeb operations
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}
```

## Cloudflare Tunnel Integration

To expose RPC endpoints publicly via Cloudflare Tunnel:

```yaml
# cloudflared config
ingress:
  - hostname: rpc-thirdweb.d-bis.org
    service: http://192.168.11.240:8545
  - hostname: rpc-thirdweb-2.d-bis.org
    service: http://192.168.11.241:8545
  - hostname: rpc-thirdweb-3.d-bis.org
    service: http://192.168.11.242:8545
```

## Additional Resources

- [ThirdWeb Documentation](https://portal.thirdweb.com/)
- [Besu RPC API Documentation](https://besu.hyperledger.org/en/stable/Reference/API-Methods/)
- [JSON-RPC Specification](https://ethereum.org/en/developers/docs/apis/json-rpc/)

## Support

For issues or questions:
1. Check logs: `pct exec <VMID> -- journalctl -u besu-rpc.service -f`
2. Verify configuration: `pct exec <VMID> -- cat /etc/besu/config-rpc-thirdweb.toml`
3. Test connectivity: `curl -X POST http://<IP>:8545 -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'`