Deployment Guide — QuantumDEX

Prerequisites

Required

Node.js 18+ (LTS)
pnpm 8+
Rust 1.75+ (for ThiChain node)
Docker + Docker Compose
Git

Accounts / Keys

ThiChain deployer wallet (THI for gas)
Hetzner account (for VPS)
Cloudflare account (DNS + Tunnel)
Optional: Etherscan-compatible API key for verification

Environment Setup

# Clone repository
git clone https://github.com/qubismic/quantumdex
cd quantumdex

# Install dependencies
pnpm install

# Copy environment template
cp LAYER_3_DEFI_SUITE/quantum-dex/.env.example \
   LAYER_3_DEFI_SUITE/quantum-dex/.env

Environment Variables

# .env
THICHAIN_LOCAL_URL=http://localhost:8545
THICHAIN_TESTNET_URL=https://testnet-rpc.thichain.io
THICHAIN_MAINNET_URL=https://rpc.thichain.io

DEPLOYER_PRIVATE_KEY=0x...   # Never commit this

DHARMIC_VALIDATOR_ADDRESS=0x0423
KARMA_ORACLE_ADDRESS=0x0421
CONSCIOUSNESS_AI_ADDRESS=0x0420

# Mock mode (no live chain required)
THICHAIN_MOCK_MODE=true

Mock Mode: Set THICHAIN_MOCK_MODE=true to develop without a live ThiChain connection. Switch to real RPC by setting THICHAIN_MOCK_MODE=false and providing a valid THICHAIN_*_URL.

Local 3-Node Testnet

# Start local ThiChain network (Docker Compose)
docker compose -f docker-compose.testnet.yml up -d

# Verify nodes are running
docker compose ps
# Expected: thichain-node-0, thichain-node-1, thichain-node-2 (Up)

# Check block production
curl http://localhost:8545 -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
# Expected: increasing block number every ~2 seconds

Deploy to Local Network

cd LAYER_3_DEFI_SUITE/quantum-dex
npx hardhat run scripts/deploy.ts --network thichain_local

Public Testnet Deployment

# Fund deployer wallet via faucet
# https://faucet.thichain.io
# (Request THI testnet tokens — Chain ID 420421)

# Deploy to testnet
npx hardhat run scripts/deploy-testnet.ts --network thichain_testnet

# Expected output:
# Deploying QuantumFactory...   ✓ 0x1234...
# Deploying QuantumRouter...    ✓ 0xabcd...
# Deploying QuantumPerps...     ✓ 0x5678...
# Deploying QuantumBridge...    ✓ 0xef01...
# Deploying VotingEscrow...     ✓ 0x2345...
# Deploying QuantumGovernor...  ✓ 0x6789...
# All contracts deployed and configured ✓

Chain ID Check: The deploy script validates REQUIRED_CHAIN_ID = 420421 before proceeding. Deployment to wrong chain is blocked automatically.

Mainnet Deployment

Pre-Mainnet Checklist: External security audit must be completed before mainnet deployment. Run npx hardhat run scripts/security-check.ts to confirm all checks pass.

# Mainnet deployment (Chain ID: 420420)
npx hardhat run scripts/deploy-mainnet.ts --network thichain_mainnet

# Multi-sig required for governance contracts
# TimelockController must be configured with
# minimum delay of 172800 seconds (48 hours)

Contract Verification

# Verify on Blockscout (ThiChain testnet explorer)
npx hardhat verify --network thichain_testnet \
  CONTRACT_ADDRESS \
  "constructor_arg_1" \
  "constructor_arg_2"

# Or verify all at once
npx hardhat run scripts/verify-all.ts --network thichain_testnet

Post-Deploy Configuration

# 1. Seed initial liquidity (recommended minimum per pair)
npx hardhat run scripts/seed-liquidity.ts --network thichain_testnet

# 2. Configure karma fee tiers
# (automatically read from KarmaOracle precompile — no manual config needed)

# 3. Create first governance proposal (optional)
npx hardhat run scripts/create-proposal.ts --network thichain_testnet

# 4. Run integration test suite against live deployment
DEPLOYMENT_NETWORK=thichain_testnet npx vitest run tests/integration/

BRG-05: Bridge ↔ DeFi end-to-end integration tests are pending testnet availability. Run npx vitest run tests/bridge-defi-e2e/ after both bridge and DEX are deployed to the same testnet.