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:

# 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):

cd rpc-translator-138
pnpm install
pnpm run build

Or use the setup script:

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

Using npm:

cd rpc-translator-138
npm install
npm run build

Configuration

Copy env.template to .env and configure:

# 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:

pnpm run dev
# or: npm run dev

Production:

pnpm start
# or: npm start

Deployment

See 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:

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:

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
• Besu Private Networks 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

# 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