Definitions Server

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 that defines network interfaces, Service Locator integration, and paths to reference data files. 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_service
  
  # The password for the Definitions Server's Service Locator account.
  password: admin_password

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

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

# NTP pool servers for time synchronization.
ntp_pool: ["0.pool.ntp.org:123",
           "1.pool.ntp.org:123",
           "2.pool.ntp.org:123",
           "3.pool.ntp.org:123"]

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

# Exchange rate definitions.
exchange_rates:
  - symbol: USD/CAD
    rate: 1.33
  - symbol: USD/AUD
    rate: 1.49
  - symbol: AUD/CAD
    rate: 0.89
  - symbol: HKD/CAD
    rate: 0.17
...

Reference Data Files

The Definitions Server loads reference data from the following files:

countries.yml

Defines country codes according to ISO 3166 standard:

---
countries:
  - name: Canada
    two_letter_code: CA
    three_letter_code: CAN
    code: 124
  - name: United States
    two_letter_code: US
    three_letter_code: USA
    code: 840
...

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 currency codes, symbols, and identifiers:

---
currencies:
  - code: CAD
    sign: $
    id: 124
  - code: USD
    sign: $
    id: 840
...

venues.yml

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

---
venues:
  - venue: XTSE
    country_code: CA
    time_zone: Eastern_Time
    currency: CAD
    description: Toronto Stock Exchange
    display_name: TSX
  - venue: XASX
    country_code: AU
    time_zone: Australian_Eastern_Standard_Time
    currency: AUD
    description: Australian Stock Market
    display_name: ASX
...

destinations.yml

Defines order routing destinations and their applicable venues:

---
destinations:
  - id: TSX
    description: Toronto Stock Exchange
    venues:
      - XTSE
      - XTSX
  - id: NEOE
    description: Aequitas NEO Exchange
    venues:
      - NEOE
      - XCNQ
      - XTSE
      - XTSX

# Preferred destinations specify default routing per venue
preferred_destinations:
  - venue: XTSE
    destination: TSX
  - venue: NEOE
    destination: NEOE

# Manual order entry destination
manual_order_entry:
  id: MOE
  description: Manual Order Entry
  venues:
    - NEOE
    - XASX
    - XCNQ
    - XTSE
    - XTSX
...

date_time_zonespec.csv

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

trading_schedules.yml

Defines market hours, holidays, and trading events:

---
trading_schedules:
  # Define closed days by weekday
  - venues: [XASX]
    time:
      weekdays: [Sat, Sun]
  
  # Define specific holiday dates
  - venues: [XASX]
    dates: [2020-01-01, 2020-04-10, 2020-12-25]
  
  # Define trading session times
  - venues: XASX
    events:
      - type: PRE_OPEN
        time: 7:00
      - type: OPEN
        time: 10:00
      - type: CLOSE
        time: 16:00
...

Installation & Setup

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.

The script supports the following arguments:

python setup.py
  --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

Operations

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

Log files are generated in the format:

srv_YYYYMMDD_HH_MM_SS.log

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

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.

If the server is not running, it prints:

DefinitionsServer is not running.

start.sh

The start.sh script:

• 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
• Writes the PID to pid.lock
• 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

The stop.sh script:

• Reads the PID from pid.lock
• 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)
• Removes the pid.lock file

This guarantees consistent shutdown behavior across normal and exceptional conditions.