thief

Production-oriented baseline implementation of the system described in system-design.md.

Current Scope

• PostgreSQL as the default database
• Drizzle ORM for all data access
• Drizzle migrations for schema lifecycle
• Multi-chain scan flow (EVM / UTXO / Solana / TON / Sui)
• Pre-seeded chain presets: Ethereum, Optimism, Arbitrum One, Base, Polygon, BNB Chain, Avalanche C-Chain, Blast, Gnosis, HyperEVM, Monad, Bitcoin, Solana, TON, Sui
• Pre-seeded production token presets: EVM native + major ERC20/BEP20 stablecoins, Solana native + SPL stablecoins, and native assets for UTXO/TON/Sui
• UTXO sweep flow with signed raw transaction broadcast (WIF or mnemonic-derived key)
• Batched EVM scan via Multicall3 with fallback single calls
• Incremental scan skip when latest chain height has not advanced
• RPC pool protections: endpoint RPS token bucket + failure circuit breaker + cooldown
• Single application process model:
  • one process starts API + scheduler + (BullMQ mode) worker consumers
  • database migrations run automatically at startup
  • startup flow logs each phase (DB -> context -> server -> listener)
• HTTP API (Fastify) with API key + JWT authentication
• Role-based access control (read / operator / admin)
• Risk controller with score updates and restore endpoint
• Audit logs for operational actions
• Alert channels (webhook/slack/telegram/email placeholder)
• Business event alerts wired for sweep success/failure, account risk status transitions, and full-chain RPC outages
• API protection with IP allowlist and in-memory rate limiting
• Confirmation header guard for destructive admin operations
• BullMQ scheduler + Redis (default and only scheduler mode)
• Chain-sharded scan and sweep queues in BullMQ mode
• Exponential backoff retries + DLQ fallback for failed queue jobs
• Prometheus metrics endpoint (/metrics)
• EVM support (native + ERC-20)
• UTXO support (native sweep)
• Solana support (native + SPL scan/sweep)
• TON support (native scan/sweep)
• Sui support (native scan/sweep)

Setup

1. Install dependencies:

npm install

2. Create env file:

cp .env.example .env

3. Ensure PostgreSQL is running and DATABASE_URL points to a reachable database.

Optional local PostgreSQL via Docker:

docker compose -f docker/docker-compose.yml up -d

This compose file also starts Redis for BullMQ.

Build application container image:

docker build -f docker/Dockerfile .

4. Optional: generate new migration files when schema changes:

npm run db:generate

5. Configure BullMQ scheduler/worker settings:

# .env
SCAN_BATCH_SIZE=500
SCAN_RPC_CONCURRENCY=20
RPC_FAILURE_THRESHOLD=5
RPC_COOLDOWN_MS=300000
REDIS_URL=redis://127.0.0.1:6379
SCAN_QUEUE_NAME=sweeper-scan
SWEEP_QUEUE_NAME=sweeper-sweep
DLQ_QUEUE_NAME=sweeper-dlq
BULLMQ_SCAN_ATTEMPTS=5
BULLMQ_SWEEP_ATTEMPTS=5
BULLMQ_BACKOFF_MS=1000
BULLMQ_SCAN_WORKER_CONCURRENCY=1
BULLMQ_SWEEP_WORKER_CONCURRENCY=5

Runtime

Start the complete application:

npm run dev

Production start (after build):

npm run build
npm run start

The same process runs API + BullMQ scheduler + BullMQ workers automatically.

Queue model in BullMQ mode:

• scan queue per chain: <SCAN_QUEUE_NAME>-<chainId>
• sweep queue per chain: <SWEEP_QUEUE_NAME>-<chainId>
• shared DLQ: <DLQ_QUEUE_NAME>

HTTP API

The API is part of the same application process started by npm run dev / npm run start.

Swagger docs:

• UI: GET /docs
• OpenAPI JSON: GET /docs/json

Use either API key (x-api-key) or JWT (Authorization: Bearer <token>).

API key example (default in .env.example):

curl -H "x-api-key: change-me-in-production" http://127.0.0.1:3000/api/v1/scan/status

Issue a JWT (admin role required):

curl -X POST \
  -H "x-api-key: change-me-in-production" \
  -H "content-type: application/json" \
  -d '{"subject":"ops-bot","role":"operator","expiresIn":"1h"}' \
  http://127.0.0.1:3000/api/v1/auth/token

Main routes:

• GET /health
• GET /health/ready
• GET /health/live
• GET /metrics
• GET /api/v1/auth/me
• POST /api/v1/auth/token
• GET/POST /api/v1/chains
• GET/PATCH/DELETE /api/v1/chains/:id
• GET /api/v1/chains/:id/health
• GET/POST /api/v1/tokens
• GET/PATCH/DELETE /api/v1/tokens/:id
• GET/POST /api/v1/accounts
• GET/DELETE /api/v1/accounts/:id
• GET /api/v1/accounts/:id/addresses
• GET /api/v1/accounts/:id/risk
• POST /api/v1/accounts/:id/restore
• GET /api/v1/scan/status
• GET /api/v1/sweeps
• GET /api/v1/sweeps/:id
• POST /api/v1/sweeps/trigger
• GET /api/v1/sweeps/stats
• GET/POST /api/v1/alerts/channels
• PATCH/DELETE /api/v1/alerts/channels/:id
• POST /api/v1/alerts/test
• GET /api/v1/audit/logs

Role requirements:

• read: read-only endpoints (GET status/list/risk)
• operator: operational writes (POST chain/token/account/sweep)
• admin: security-sensitive writes (POST /api/v1/auth/token, restore/delete actions, audit log access)

Additional API controls:

• IP allowlist via API_IP_ALLOWLIST (* to allow all)
• in-memory rate limiting via API_RATE_LIMIT_WINDOW_MS and API_RATE_LIMIT_MAX
• destructive admin endpoints require x-confirm-action: <ADMIN_CONFIRM_TOKEN>

Scheduler behavior:

• BullMQ is the only scheduler mode
• scheduler starts automatically during application startup and begins periodic scans immediately
• failed jobs retry with exponential backoff; exhausted retries are copied to DLQ

Notes

• Solana account import/sweep currently supports private_key only.
• TON account import/sweep currently supports private_key as the default path.
• Sui currently supports native balance scan/sweep and private-key based account import.
• Default chain presets are created with enabled=true and placeholder collector addresses; update collector addresses before production use.
• Default scheduler configuration is seeded with BullMQ mode + DEFAULT_SCAN_INTERVAL_MS and auto-start enabled.
• Default alert channels are seeded in enabled mode (ops-webhook-critical, ops-slack-warning, ops-telegram-critical, ops-email-critical).