Definitions Server

The Definitions Server provides centralized reference data for the trading platform. It disseminates system-wide definitions including country codes, currencies, trading venues, order routing destinations, time zones, exchange rates, compliance rule schemas, and trading schedules. By centralizing these definitions, the server ensures consistent metadata across all components of the system.

The Definitions Server integrates with the Service Locator for authentication and service registration. All reference data is loaded from YAML and CSV configuration files at startup.

Configuration

The Definitions Server is configured via a YAML file with two top-level sections (server and service_locator) plus several inline fields that specify reference data files and platform metadata. Below is the structure of the configuration file with example values:

server:
  # Primary network interface and port the Definitions Server binds to.
  interface: "0.0.0.0:20200"
  # List of addresses the server is reachable at (for registration with Service Locator).
  # Typically includes both public-facing and local addresses.
  addresses: ["198.51.100.5:20200", "10.0.0.5:20200"]

service_locator:
  # The address of the Service Locator (host:port).
  address: "10.0.0.5:20000"
  # The account username used by the Definitions Server to authenticate with the Service Locator.
  username: definitions_server
  # The password for the Definitions Server's Service Locator account.
  password: [REQUIRED]

# Minimum version of the Spire client required to connect.
minimum_spire_version: "1234"

# Name of the organization operating the platform.
organization: "Spire Trading Inc."

# Paths to reference data files.
time_zones: "time_zones.csv"
countries: "countries.yml"
currencies: "currencies.yml"
venues: "venues.yml"
destinations: "destinations.yml"

# Exchange rates between currency pairs.
exchange_rates:
  - symbol: "USD/CAD"
    rate: "1.35"

# NTP servers registered as time service endpoints.
ntp_pool: ["pool.ntp.org:123"]

A setup.py script is provided to generate the final config.yml from the config.default.yml template. The script also copies default reference data files if they do not already exist. Usage:

  --local 0.0.0.0           # Local interface (default: auto-detected IP)
  --world 198.51.100.5      # Global/public interface (optional)
  --address 10.0.0.5:20000  # Service Locator address (default: local_interface:20000)
  --password [REQUIRED]     # Service password for authentication

Reference Data Files

The Definitions Server loads reference data from the following files:

countries.yml

Defines country codes according to the ISO 3166 standard. A utility script (update_countries.sh) is provided to download and update country definitions from the official ISO 3166 data source. The script uses country_code_parser.py to parse the CSV data and generate the YAML file.

currencies.yml

Defines currencies including their codes, names, and decimal places.

venues.yml

Defines trading venues (exchanges and markets) including their country, time zone, and currency.

destinations.yml

Defines order routing destinations and their applicable venues. Preferred destinations specify default routing per venue.

time_zones.csv

Contains time zone database information in CSV format for accurate timestamp conversion across regions.

trading_schedule.yml

Defines market hours, holidays, and trading events.

Management

The Definitions Server is controlled using three operational scripts: start.sh, stop.sh, and check.sh.

start.sh

Exits immediately if the server is already running.
Creates a logs/ directory if necessary.
Moves any existing srv_*.log files into logs/.
Starts the DefinitionsServer process in the background.
Reads network interfaces from config.yml and waits until the server is listening on at least one configured address.

This ensures the server is fully initialized before the script exits.

stop.sh

Sends SIGINT to request a graceful shutdown.
Waits for termination using exponential backoff (up to 300 seconds).
Sends SIGKILL if the server fails to stop cleanly.
Appends a forced-termination message to the most recent log file (if applicable).

This guarantees consistent shutdown behavior across normal and exceptional conditions.

check.sh

The check.sh script verifies whether the server is currently running by inspecting the PID recorded in pid.lock and testing whether the associated process exists.

Logging

Upon startup, older log files are moved into the logs/ directory.

Navigation menu