GhostRoute — Developer Reference

Build Requirements

Dependency	Version	Purpose
Qt 6	≥ 6.4	Widgets, Network, Concurrent
libsodium	≥ 1.0.18	Ed25519 keypair, signing, memzero
nlohmann/json	≥ 3.10	Xray config JSON generation
CMake	≥ 3.21	Build system
Xray-core binary	≥ 1.8	Runtime proxy engine

# Ubuntu/Debian
sudo apt install qt6-base-dev libsodium-dev nlohmann-json3-dev cmake

# macOS (Homebrew)
brew install qt6 libsodium nlohmann-json cmake

# Build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Project Structure

GhostRoute/
├── CMakeLists.txt
├── src/
│   ├── main.cpp                        # Entry point
│   ├── crypto/
│   │   ├── IdentityManager.cpp         # Ed25519 keypair lifecycle
│   │   └── ChallengeResponse.cpp       # Server auth handshake
│   ├── network/
│   │   ├── XrayController.cpp          # QProcess management for xray
│   │   ├── ConfigBuilder.cpp           # Xray JSON template generation
│   │   └── TrafficMonitor.cpp          # Speed stats polling
│   ├── billing/
│   │   ├── BillingManager.cpp          # Subscription status + payment
│   │   └── PaymentGateway.cpp          # Platform-specific payment URLs
│   └── ui/
│       ├── MainWindow.cpp              # Top-level window
│       ├── ConnectButton.cpp           # Animated circular toggle
│       ├── StatsWidget.cpp             # Traffic sparklines
│       └── MaskBackground.cpp          # Painted Guy Fawkes background
├── include/                            # Matching headers
├── xray-configs/
│   ├── free_tier_template.json         # Reference: VLESS+Reality
│   └── premium_smart_routing_template.json  # Reference: +Hysteria2
└── resources/
    └── resources.qrc

Identity & Auth Flow

First launch:
  sodium_init()
  crypto_sign_ed25519_keypair() → store in QSettings (base64)
  public key hex → user's permanent anonymous ID

Every launch:
  Load keypair from QSettings
  GET /api/v1/auth/challenge  {pubkey}
  ← {challenge: "random_nonce"}
  sign(challenge, secretKey) → signature
  POST /api/v1/auth/verify    {pubkey, challenge, signature}
  ← {session_token, status}

Server never receives the secret key.

Smart Routing Decision Tree

Inbound traffic (SOCKS5 port 10808)
        │
        ▼
  Xray sniffing (TLS ClientHello → SNI extraction)
        │
        ├─ domain:private / localhost ──────────────► direct
        │
        ├─ youtube.com / googlevideo.com / netflix
        │  twitch / spotify / vimeo / CDNs ─────────► Hysteria2 (UDP)
        │                                              Server 2: fast path
        │
        └─ everything else ──────────────────────────► VLESS+Reality (TCP)
                                                       Server 1: stealth

Backend API Contract (your server implementation)

POST /api/v1/auth/challenge

Request: { "pubkey": "0x..." } Response: { "challenge": "random_hex_nonce_32bytes" }

POST /api/v1/auth/verify

Request: { "pubkey": "0x...", "challenge": "...", "signature": "hex_sig" } Response: { "ok": true, "session_token": "...", "status": "free|premium" }

GET /api/v1/status?pubkey=0x...

Response:

{
  "status": "premium",
  "expires_at": "2026-07-01T00:00:00Z",
  "plan": "monthly"
}

POST /api/v1/buy

Request: { "pubkey": "0x...", "method": "cryptobot|p2p_rub|xmr|ltc" } Response: { "order_id": "...", "payment_url": "...", "amount_usd": 5.99 }

POST /api/v1/activate

Request: { "pubkey": "0x...", "promo_code": "PREM-XXXX-YYYY" } Response: same as /status

Webhook (from payment providers → your backend)

Your backend receives webhooks from CryptoBot/AAIO/ChangeNOW. On payment confirmation: set is_premium=true, expires_at=now+30days for the pubkey linked to that order_id.

Payment Provider Integration Notes

Provider	Region	Currency	Anonymous?	API Docs
@CryptoBot	RU/CIS/🌍	USDT/LTC/BTC	✅ Yes	https://help.crypt.bot/crypto-pay
AAIO	RU/CIS	RUB→crypto	Partial	https://aaio.so/api
CryptoCloud	RU/CIS	RUB→crypto	Partial	https://cryptocloud.plus
ChangeNOW	🌍 Global	XMR/any	✅ Yes	https://changenow.io/api
FixedFloat	🌍 Global	XMR/LTC	✅ Yes	https://fixedfloat.com/api

Xray Binary Distribution

Xray-core is Apache 2.0 licensed. Options:

• Bundle the binary in your installer (most user-friendly)
• Download on first launch from official release: https://github.com/XTLS/Xray-core/releases
• Verify SHA256 of downloaded binary before execution

Next Steps

1. TrafficMonitor — poll Xray's stats API (/stats/query) over a local HTTP endpoint for real-time bandwidth numbers
2. SeedNodeManager — fetch/decrypt server lists from DNS TXT / Telegram channel / blockchain
3. SplitTunnelManager — WinDivert (Windows) / iptables cgroup (Linux) for per-app routing
4. FingerprintProxy — local SOCKS5 layer with Canvas/WebGL/AudioContext spoofing
5. Settings page — server management, kill switch, auto-connect on launch