Skip to main content

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

  • GET / - Returns “Moooo!”

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:
  1. Loads last processed block from database
  2. Fetches events from deploymentBlock to current block
  3. Processes events in pages (configurable size)
  4. Updates registry with new programmatic orders
  5. Transitions to IN_SYNC state

Block Watching

After warm-up, subscribes to new blocks:
For each new block:
  1. Fetches ConditionalOrderCreated events
  2. Processes new programmatic orders
  3. Polls existing orders for discrete order creation
  4. 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

  1. DBService: Initialize database connection
  2. ApiService: Start REST API server (if enabled)
  3. ChainContext: Initialize per network
    • Create provider
    • Load registry from database
    • Start chain monitoring

Service Shutdown

Graceful shutdown process:
Last modified on March 12, 2026