Backend Architecture
Event listening, real-time liquidation opportunity detection, and auction coordination services
The Reforge backend is an event-driven microservices architecture built with Node.js, TypeScript, Fastify, Redis, and PostgreSQL. It continuously ingests on-chain events, computes liquidation opportunities, and orchestrates discrete auction lifecycles.
Service Pipeline & Dataflow
Core Backend Stack
| Technology | Category | Purpose |
|---|---|---|
| Fastify & TypeScript | API Framework | Ultra-low latency HTTP API router with strict JSON schema validation and zero-overhead routing. |
| Redis & BullMQ | Task Queue | High-throughput in-memory job queues managing parallel auction events, delayed jobs, and retries. |
| viem & WebSocket RPC | Blockchain Client | Lightweight, type-safe EVM interaction library maintaining persistent WebSocket subscriptions to Anvil/Sepolia. |
| PostgreSQL & Drizzle ORM | Data Persistence | Relational persistence for historical auctions, searcher telemetry, gas costs, and experimental metrics. |
Codebase Directory Structure
The backend source tree is organized into modular domain services:
Detailed Service Responsibilities
1. Blockchain Listener (block-listener.ts)
Subscribes to new block headers via WebSocket RPC. Emits internal block:new events with gas base fee estimates and block timestamp data.
2. Opportunity Engine (opportunity.service.ts)
Maintains an in-memory registry of open borrower positions. Upon receiving a new block or price oracle update, it recomputes health factors using the mathematical model:
HF = (Σ Collateral_i × Price_i × LiquidationThreshold_i) / (Σ Debt_j × Price_j)If HF < 1.00, it dispatches a high-priority liquidation job to the BullMQ queue.
3. Auction Engine (auction.service.ts & scoring.service.ts)
Orchestrates the lifecycle of discrete batch auctions:
- Auction Open: Emits auction parameters and opens the bidding window (1–2 blocks).
- Bid Collection: Collects sealed bids with liquidator routing parameters and slippage bounds.
- NEV Evaluation: Scores all submissions according to Net Economic Value:
NEV = Gross Liquidation Value - Gas Cost - DEX Slippage Cost - Settlement: Automatically submits the winning bid settlement transaction on-chain.