proxmox/rpc-translator-138/README.md

# RPC Translator Service for ChainID 138

A JSON-RPC proxy service that provides Thirdweb-compatible RPC endpoints for ChainID 138, with support for `eth_sendTransaction` through automatic signing via Web3Signer.

## Features

- **HTTP JSON-RPC** on port 9545
- **WebSocket JSON-RPC** on port 9546 with subscription support
- **Transaction Interception**: Automatically converts `eth_sendTransaction` → `eth_sendRawTransaction`
- **Web3Signer Integration**: Secure transaction signing via Web3Signer
- **Vault Integration**: Configuration and policy management via HashiCorp Vault
- **Redis Nonce Management**: Distributed nonce locking to prevent collisions in HA deployments
- **High Availability**: Designed to run on multiple VMIDs (2400-2402) with load balancing

## Architecture

```
Thirdweb Client
    ↓ (HTTPS :8545 or WSS :8546)
Existing Edge Routing (Cloudflare/Nginx)
    ↓ (to :9545/:9546)
Translator Service (VMIDs 2400-2402)
    ├─→ Besu HTTP/WS (passthrough for most methods)
    ├─→ Redis (nonce locks)
    ├─→ Web3Signer (transaction signing)
    └─→ Vault (configuration)
```

## Quick Start

### Prerequisites

- Node.js 18+ (or 20 LTS)
- Redis instance (VMID 106, IP 192.168.11.110)
- Web3Signer instance (VMID 107, IP 192.168.11.111)
- HashiCorp Vault (optional, VMID 108, IP 192.168.11.112)
- Proxmox node (r630-01) for supporting services deployment

### Deploy Supporting Services (LXC Containers)

**Quick deployment on Proxmox:**

```bash
# 1. Verify node readiness
./verify-node-ready.sh r630-01

# 2. Deploy containers
./deploy-supporting-services.sh r630-01

# 3. Start containers
pct start 106  # Redis
pct start 107  # Web3Signer
pct start 108  # Vault

# 4. Configure services (see DEPLOYMENT.md)
```

**For detailed instructions, see:**
- `LXC_DEPLOYMENT.md` - Complete LXC deployment guide
- `DEPLOYMENT.md` - Full deployment guide
- `DEPLOYMENT_CHECKLIST.md` - Step-by-step checklist

### Installation

**Using pnpm (recommended):**

```bash
cd rpc-translator-138
pnpm install
pnpm run build
```

**Or use the setup script:**

```bash
cd rpc-translator-138
./scripts/setup.sh
```

**Using npm:**

```bash
cd rpc-translator-138
npm install
npm run build
```

### Configuration

Copy `env.template` to `.env` and configure:

```bash
# Server
HTTP_PORT=9545
WS_PORT=9546

# Besu Upstream
BESU_HTTP_URLS=http://127.0.0.1:8545
BESU_WS_URLS=ws://127.0.0.1:8546
CHAIN_ID=138

# Web3Signer (VMID 107)
WEB3SIGNER_URL=http://192.168.11.111:9000

# Redis (VMID 106)
REDIS_HOST=192.168.11.110
REDIS_PORT=6379

# Vault (VMID 108, optional)
VAULT_ADDR=http://192.168.11.112:8200
VAULT_ROLE_ID=...
VAULT_SECRET_ID=...
```

### Running

**Development:**
```bash
pnpm run dev
# or: npm run dev
```

**Production:**
```bash
pnpm start
# or: npm start
```

## Deployment

See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed deployment instructions on Proxmox VMIDs 2400-2402.

## API

### HTTP Endpoint

**POST /** - JSON-RPC 2.0 endpoint

**GET /health** - Health check endpoint

Example:
```bash
curl -X POST http://localhost:9545 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'
```

### WebSocket Endpoint

**ws://localhost:9546** - JSON-RPC over WebSocket

Example:
```javascript
const ws = new WebSocket('ws://localhost:9546');
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  method: 'eth_subscribe',
  params: ['newHeads'],
  id: 1
}));
```

### Supported Methods

The translator supports both **public network** and **private network** Besu API methods.

**Public Network Methods** (all standard Ethereum methods):
- `eth_*` - All standard Ethereum JSON-RPC methods
- `net_*` - Network methods (`net_version`, `net_listening`, etc.)
- `web3_*` - Web3 utility methods
- `eth_subscribe`, `eth_unsubscribe` (WebSocket only)

**Private Network Methods** (enabled by default):
- `clique_*` - CLIQUE consensus methods (proof of authority)
- `ibft_*` - IBFT 2.0 consensus methods
- `qbft_*` - QBFT consensus methods
- `perm_*` - Permissioning methods (accounts/nodes allowlist)

**Intercepted Methods:**
- `eth_sendTransaction` - Automatically signed and converted to `eth_sendRawTransaction`

**Denied Methods** (for security):
- `admin_*` - Admin methods
- `debug_*` - Debug methods
- `txpool_*` - Transaction pool methods
- `miner_*` - Miner control methods

**Configuration:**
- Set `ALLOW_PRIVATE_NETWORK_METHODS=false` in `.env` to disable private network methods

For complete API documentation, see:
- [Besu Public Networks API](https://besu.hyperledger.org/public-networks/reference/api)
- [Besu Private Networks API](https://besu.hyperledger.org/private-networks/reference/api)
- `API_METHODS_SUPPORT.md` - Detailed method reference

## Security

- **Wallet Allowlist**: Only specified wallet addresses can send transactions
- **Fee/Gas Caps**: Maximum gas limits and gas prices enforced
- **Method Filtering**: Dangerous RPC methods are denied
- **Chain ID Validation**: All transactions must use ChainID 138

## Development

```bash
# Install dependencies
pnpm install
# or: npm install

# Build TypeScript
pnpm run build
# or: npm run build

# Run in development mode (with auto-reload)
pnpm run dev
# or: npm run dev

# Run tests (when implemented)
pnpm test
# or: npm test
```

## License

MIT