Services Layer
The services layer offers integrations with external systems: blockchain RPC nodes, the OrderBook API, and the database.
API Service
Location: src/services/api.ts
The API service manages a REST API and Prometheus metrics endpoint.
Class: ApiService
Singleton service managing an Express server.
Endpoints
Root endpoint
Metrics
- GET
/metrics - Prometheus metrics
Health check
- GET
/health - Returns health status of all chains
- Response includes overall health and per-chain status
Configuration
- GET
/config - Returns current watch-tower configuration
- Shows chain IDs, contracts, deployment blocks, and filter policies
API endpoints
- GET
/api/version - Version information
- GET
/api/dump/:chainId - Dumps registry for specified chain ID
Usage
Configuration
Disable the API server using the --disable-api flag:
Configure the port:
Chain Service
Location: src/services/chain.ts
The chain service manages blockchain interactions and order monitoring for each network.
Class: ChainContext
Represents a single blockchain network being monitored.
Initialization
Warm-up Phase
The warm-up phase synchronizes historical blocks:
- Loads last processed block from database
- Fetches events from
deploymentBlock to current block
- Processes events in pages (configurable size)
- Updates registry with new programmatic orders
- Transitions to
IN_SYNC state
Block Watching
After warm-up, subscribes to new blocks:
For each new block:
- Fetches
ConditionalOrderCreated events
- Processes new programmatic orders
- Polls existing orders for discrete order creation
- Updates database atomically
Health Monitoring
Sync States
- SYNCING: Catching up with historical blocks
- IN_SYNC: Caught up, watching new blocks
- UNKNOWN: Watchdog timeout exceeded (may indicate RPC issues)
Provider Support
Supports both HTTP and WebSocket providers:
Storage Service
Location: src/services/storage.ts
The storage service provides database operations using LevelDB.
Class: DBService
Singleton service for database operations.
Configuration
Database options:
Usage
Default Location
Default database path: ./database
Configure the path:
ACID Guarantees
LevelDB provides:
- Atomicity: Batch operations are atomic
- Consistency: Schema validation on read/write
- Isolation: Single-threaded Node.js
- Durability: Writes are persisted to disk
Service Initialization Order
- DBService: Initialize database connection
- ApiService: Start REST API server (if enabled)
- ChainContext: Initialize per network
- Create provider
- Load registry from database
- Start chain monitoring
Service Shutdown
Graceful shutdown process:
Last modified on March 12, 2026