DEPLOY_DEVNET_GUIDE.md

# Devnet Deployment Guide

This guide covers deploying all components to Solana devnet for testing.

## Prerequisites

- Solana CLI installed and configured for devnet
- PostgreSQL database running
- Redis server running
- Python 3.9+
- Rust and Cargo (for Solana program)
- CMake (for C++ workers)

## 1. Catacomb Underwriter Service (133x Scaling)

**Location:** `catacomb-underwriter-service/`

**Steps:**
```bash
cd catacomb-underwriter-service

# Create .env from example
cp .env.example .env

# Edit .env with your devnet credentials:
# - DATABASE_URL (PostgreSQL)
# - REDIS_URL (Redis)
# - STRIPE_SECRET_KEY (test mode: sk_test_*)
# - STRIPE_PUBLISHABLE_KEY (test mode: pk_test_*)
# - SECRET_KEY

# Install dependencies
pip install -r requirements.txt

# Initialize database
python -c "from database import get_database_manager; db = get_database_manager(); db.initialize_schema()"

# Start service
python underwriter_app.py
```

**Devnet Configuration:**
- Solana RPC: `https://api.devnet.solana.com`
- Stripe: Test mode keys
- Port: 5002

**Test Endpoints:**
- `GET http://localhost:5002/api/scaling/health`
- `GET http://localhost:5002/api/scaling/metrics`
- `GET http://localhost:5002/api/loadbalancer/metrics`

## 2. C++ Gate.io WebSocket Workers

**Location:** `cpp-trading-trainer/`

**Steps:**
```bash
cd cpp-trading-trainer

# Build workers
mkdir -p build
cd build
cmake ..
make gateio_worker_manager
cd ..

# Start aggregation server (port 5003)
python aggregation_server.py &

# Start workers
./build/gateio_worker_manager "BTC_USDT,ETH_USDT,SOL_USDT" "1m"
```

**Test Endpoints:**
- `GET http://localhost:5003/api/status`
- `GET http://localhost:5003/api/symbols`
- `GET http://localhost:5003/api/candles/BTC_USDT?limit=10`
- `GET http://localhost:5003/api/stream` (SSE)

## 3. ShadowPool Solana Program

**Location:** `shadowpool/`

**Steps:**
```bash
cd shadowpool

# Configure Solana CLI for devnet
solana config set --url https://api.devnet.solana.com

# Airdrop devnet SOL
solana airdrop 2

# Build program
cargo build-bpf

# Deploy program
solana program deploy target/deploy/shadowpool.so

# Save the program ID for client configuration
```

**Program Features:**
- Pool-native token (Token ≡ Pool Share)
- Lambda-stabilized shadow liquidity
- Anti-fake rules (ambiguity, distortion limits)
- Shadow rebase mechanism

**Program Fields:**
- `shadow_root: [u8; 32]` - Merkle root of shadow projection
- `projection_hash: [u8; 32]` - Hash of projection
- `shadow_liquidity_bps: u16` - Liquidity score in basis points
- `ambiguity_bps: u16` - Ambiguity penalty
- `distortion_bps: u16` - Distortion penalty
- `shadow_index_q64: u128` - Shadow index (Q64 fixed-point)
- `lambda_coefficient: u64` - Lambda coefficient

## 4. Proof-of-Shadow-Liquidity Components

**Components to Deploy:**
- LiquidDB (off-chain manifold storage)
- IPFS (for Merkle tree storage)
- Manifold projection service
- Shadow rebase instruction handlers

**Steps:**
```bash
# Deploy LiquidDB (PostgreSQL)
createdb liquiddb_devnet
psql liquiddb_devnet < schema.sql

# Start IPFS daemon
ipfs daemon

# Configure manifold projection service
# (implementation depends on your embedding model)
```

## Environment Variables Summary

**Catacomb Underwriter (.env):**
```
SOLANA_RPC_URL=https://api.devnet.solana.com
STRIPE_SECRET_KEY=sk_test_*
STRIPE_PUBLISHABLE_KEY=pk_test_*
DATABASE_URL=postgresql://user:pass@localhost:5432/catacomb_devnet
REDIS_URL=redis://localhost:6379/0
REDIS_HOSTS=localhost
REDIS_MAX_CONNECTIONS=500
NUM_WORKERS=133
ENABLE_AUTO_SCALING=true
```

**ShadowPool (Solana):**
- Network: Devnet
- Program ID: (after deployment)
- Authority: Your devnet keypair

## Testing

**Test Underwriter Service:**
```bash
curl http://localhost:5002/api/scaling/health
curl http://localhost:5002/api/scaling/metrics
```

**Test Gate.io Workers:**
```bash
curl http://localhost:5003/api/status
curl http://localhost:5003/api/symbols
```

**Test ShadowPool:**
```bash
solana program show <PROGRAM_ID>
solana logs <PROGRAM_ID>
```

## Troubleshooting

**Cargo lock file version error:**
```bash
rm Cargo.lock
cargo update
cargo build-bpf
```

**Redis not running:**
```bash
redis-server
```

**PostgreSQL not running:**
```bash
# macOS
brew services start postgresql

# Linux
sudo systemctl start postgresql
```

**Solana airdrop failed:**
```bash
# Request more SOL
solana airdrop 2
```

## Next Steps After Devnet Testing

1. Verify all components work together
2. Test shadow rebase mechanism
3. Test lambda coefficient calculations
4. Test anti-fake rules
5. Test 133x scaling under load
6. Document any issues
7. Prepare for mainnet deployment with real credentials