Architecture
System Overview
Components
Velo RGS (Remote Game Server)
The core game server, built in Rust with the Axum framework and Tokio async runtime.
| Component | Technology | Purpose |
|---|---|---|
| HTTP Server | Axum | REST API and WebSocket endpoints |
| Pricing Engine | Custom Rust | 5-stage calibrated pricing pipeline |
| Round Manager | Tokio tasks | Round lifecycle (active → locked → settled) |
| Oracle Router | WebSocket | Dual price feeds (Binance + Coinbase) with failover |
| Settlement | Pyth Network | Verifiable on-chain price proofs |
| Wallet Provider | velo-wallet crate | Abstraction layer for all money operations |
| Reconciliation | REST API | Round + transaction queries for operator auditing |
Wallet Integration
The RGS uses a WalletProvider trait that abstracts all balance operations. Two implementations ship out of the box:
| Mode | Implementation | When Used |
|---|---|---|
| B2B Production | SeamlessWalletClient | Live — sends HMAC-signed HTTP requests to your wallet API |
| Sandbox | SandboxWallet | Certification testing — in-memory balances with configurable error injection |
| Demo | DemoWallet | Development/demo — operates against local demo_players DB table |
The mode is selected automatically based on environment:
OPERATOR_WALLET_URLset → SeamlessWalletClient (B2B mode)WALLET_MODE=sandbox→ SandboxWallet (certification mode)DATABASE_URLset → DemoWallet (demo mode)
Oracle Router
Dual-feed architecture with automatic failover:
- Primary: Binance WebSocket (always connected)
- Secondary: Coinbase WebSocket (hot standby)
- Cross-validation: warns if feeds diverge >0.5%
- Failover: primary stale >2s → switch to secondary
- Failback: primary healthy for 10s → switch back
- All-down: both stale >10s → pause game
Pricing Pipeline
Odds are computed once per second through this pipeline:
- Drifted Brownian Bridge — Path-conditioned probability using 10s subsampled price history
- Isotonic Calibration — 200-breakpoint monotonic mapping trained on 3 years of BTC data
- Trend Persistence — Momentum adjustment based on empirical BTC trend continuation rates (5 magnitude buckets × 14 time windows)
- House Edge — 5% flat margin applied symmetrically
Volatility is estimated from a 360-candle rolling window of Binance 1-minute klines, refreshed every 60 seconds.
Round Lifecycle
Rounds are clock-aligned to :X0:00 and :X5:00 UTC (e.g., 14:00, 14:05, 14:10...):
ACTIVE ──────────► LOCKED ──► SETTLED
(4m50s) (10s) │
│ │ │ Pyth settlement
│ Bets accepted │ │ Wallet credits
│ Odds updating │ No bets │- Active (0:00–4:50): Bets accepted, odds update every second
- Locked (4:50–5:00): Last 10 seconds — no new bets, odds still visible
- Settled (5:00): Pyth oracle price fetched, result determined, wallets credited
Game Constants
| Constant | Value | Description |
|---|---|---|
| Round duration | 5 minutes | Clock-aligned |
| Lock buffer | 10 seconds | Before round end |
| Max stake | $1,000 | Per bet |
| Max payout | $50,000 | Per bet |
| Max odds | 1000x | Tail bet cap |
| Cashout spread | 3% | Early exit spread |
| House margin | 5% | Flat symmetric |
Infrastructure
Hosted on Google Cloud Platform:
| Service | GCP Component | Purpose |
|---|---|---|
| Compute | Cloud Run | Auto-scaling containers |
| Database | Cloud SQL (PostgreSQL) | Rounds, bets, players, sessions |
| Frontend | Firebase Hosting | Static game frontend |
| Analytics (planned) | BigQuery | Long-term audit trail and compliance analytics |