defi-arbitrage/PROXMOX_DEPLOYMENT.md

Proxmox VE Deployment Guide - Deal Orchestration Tool

Overview

This document describes how the Deal Orchestration Tool (arbitrage module) is deployed and runs within the Proxmox VE infrastructure as part of the DBIS Core Banking System.

Deployment Architecture

Container Assignment

The arbitrage orchestration service runs within the DBIS Core API containers:

Service	VMID	Hostname	IP Address	Role
Primary API	10150	dbis-api-primary	192.168.11.150	Main API + Arbitrage Orchestrator
Secondary API	10151	dbis-api-secondary	192.168.11.156	HA API + Arbitrage Orchestrator

Container Specifications

• Memory: 8 GB (8192 MB)
• CPU Cores: 4
• Disk: 100 GB
• OS Template: ubuntu-22.04-standard
• Network: Bridge vmbr0
• Unprivileged: Yes
• Features: nesting=1, keyctl=1

Integration with DBIS Core

Service Architecture

┌─────────────────────────────────────────┐
│  Proxmox VE Host (192.168.11.10)      │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │ LXC Container: dbis-api-primary  │ │
│  │ VMID: 10150                       │ │
│  │ IP: 192.168.11.150                │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ DBIS Core API Server        │  │ │
│  │  │ (Node.js/Express)           │  │ │
│  │  │ Port: 3000                  │  │ │
│  │  └──────────────────────────────┘  │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Deal Orchestrator Service   │  │ │
│  │  │ (Arbitrage Module)           │  │ │
│  │  │ - Step Execution            │  │ │
│  │  │ - Risk Control              │  │ │
│  │  │ - Redemption Testing        │  │ │
│  │  └──────────────────────────────┘  │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Database Connection         │  │ │
│  │  │ (Prisma ORM)                │  │ │
│  │  │ → PostgreSQL (VMID 10100)   │  │ │
│  │  └──────────────────────────────┘  │ │
│  │                                    │ │
│  │  ┌──────────────────────────────┐  │ │
│  │  │ Blockchain RPC Client        │  │ │
│  │  │ → ChainID 138 RPC Nodes     │  │ │
│  │  │ (VMID 2500-2502)            │  │ │
│  │  └──────────────────────────────┘  │ │
│  └───────────────────────────────────┘ │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │ LXC Container: dbis-api-secondary│ │
│  │ VMID: 10151                       │ │
│  │ IP: 192.168.11.156                │ │
│  │ (Same structure as primary)       │ │
│  └───────────────────────────────────┘ │
└─────────────────────────────────────────┘

Deployment Steps

1. Prerequisites

• Proxmox VE host with LXC support
• DBIS Core containers already deployed (see DEPLOYMENT_PLAN.md)
• PostgreSQL database running (VMID 10100)
• ChainID 138 RPC nodes accessible (VMID 2500-2502)

2. Install Dependencies

SSH into the API container and install Node.js dependencies:

# SSH to Proxmox host
ssh root@192.168.11.10

# Enter API container
pct enter 10150

# Navigate to project
cd /opt/dbis-core

# Install dependencies (if not already done)
pnpm install

# Build the project
pnpm build

3. Configure Environment

Set environment variables in the container:

# In container 10150
nano /opt/dbis-core/.env

Required variables:

# Database
DATABASE_URL="postgresql://user:pass@192.168.11.100:5432/dbis_core"

# ChainID 138 RPC
CHAIN_138_RPC_URL="http://192.168.11.250:8545"
CHAIN_138_RPC_URL_BACKUP="http://192.168.11.251:8545"

# Risk Parameters (optional, defaults in config.ts)
MAX_LTV=0.30
MAX_USDTZ_EXPOSURE=0.25
USDTZ_DISCOUNT_RATE=0.40

# Logging
LOG_LEVEL="info"

4. Run as Service

Create a systemd service for the arbitrage orchestrator:

# In container 10150
cat > /etc/systemd/system/dbis-arbitrage.service << 'EOF'
[Unit]
Description=DBIS Deal Orchestration Service
After=network.target postgresql.service

[Service]
Type=simple
User=dbis
WorkingDirectory=/opt/dbis-core
Environment=NODE_ENV=production
ExecStart=/usr/bin/node dist/src/core/defi/arbitrage/cli.js execute \
  --totalEthValue 10000000 \
  --participantBankId BANK001 \
  --moduleId MODULE001
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
systemctl enable dbis-arbitrage
systemctl start dbis-arbitrage

5. Integration with API Server

The arbitrage service can also be called via the DBIS Core API:

// In your API route handler
import { dealOrchestratorService } from '@/core/defi/arbitrage';

app.post('/api/deals/execute', async (req, res) => {
  const result = await dealOrchestratorService.executeDeal({
    totalEthValue: req.body.totalEthValue,
    participantBankId: req.body.participantBankId,
    moduleId: req.body.moduleId,
  });
  
  res.json(result);
});

Network Configuration

Internal Network (Container-to-Container)

• Database: 192.168.11.100:5432 (PostgreSQL)
• Redis: 192.168.11.120:6379 (Cache)
• RPC Nodes: 192.168.11.250-252:8545 (ChainID 138)

External Network (Blockchain)

• ChainID 138: Public blockchain network
• Smart Contracts: Deployed on ChainID 138
• RPC Endpoints: Accessible via internal RPC nodes

Monitoring

Logs

# View service logs
journalctl -u dbis-arbitrage -f

# View application logs
tail -f /opt/dbis-core/logs/arbitrage.log

Health Checks

The service exposes health endpoints (if integrated with API):

# Check service status
curl http://192.168.11.150:3000/api/health/arbitrage

# Check deal status
curl http://192.168.11.150:3000/api/deals/{dealId}/status

High Availability

Primary/Secondary Setup

• Primary (10150): Active arbitrage execution
• Secondary (10151): Standby for failover
• Load Balancer: Routes requests between containers

Failover

If primary container fails:

1. Load balancer detects failure
2. Routes traffic to secondary (10151)
3. Secondary takes over deal execution
4. Database state is shared (PostgreSQL replication)

Security Considerations

Container Isolation

• Unprivileged containers: Reduced security risk
• Network isolation: Containers on private bridge
• Resource limits: CPU and memory caps enforced

Key Management

• Private keys: Stored in secure key management service
• API credentials: Environment variables (not in code)
• Database credentials: Rotated regularly

Troubleshooting

Container Access

# SSH to Proxmox host
ssh root@192.168.11.10

# Enter container
pct enter 10150

# Check service status
systemctl status dbis-arbitrage

# View logs
journalctl -u dbis-arbitrage -n 100

Common Issues

1. Database Connection Failed

   • Verify PostgreSQL container (10100) is running
   • Check network connectivity: ping 192.168.11.100
   • Verify DATABASE_URL in .env

2. RPC Connection Failed

   • Verify RPC nodes (2500-2502) are running
   • Check RPC endpoint URLs
   • Test: curl http://192.168.11.250:8545

3. Service Won't Start

   • Check logs: journalctl -u dbis-arbitrage
   • Verify dependencies: pnpm install
   • Check file permissions

References

• DBIS Core Deployment Plan
• Arbitrage Module README
• Proxmox Container Creation Script