Kamal: Created page with "= Definitions Server = The Definitions Server provides centralized reference data for the trading platform. It disseminates system-wide definitions including country codes, cu..."

2025-12-01T22:03:44Z

Created page with "= Definitions Server = The Definitions Server provides centralized reference data for the trading platform. It disseminates system-wide definitions including country codes, cu..."

New page

= 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:

<pre>
---
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
...
</pre>

== Reference Data Files ==
The Definitions Server loads reference data from the following files:

=== countries.yml ===
Defines country codes according to ISO 3166 standard:
<pre>
---
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
...
</pre>

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

=== currencies.yml ===
Defines currency codes, symbols, and identifiers:
<pre>
---
currencies:
- code: CAD
sign: $
id: 124
- code: USD
sign: $
id: 840
...
</pre>

=== venues.yml ===
Defines trading venues (exchanges and markets) including their country, time zone, and currency:
<pre>
---
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
...
</pre>

=== destinations.yml ===
Defines order routing destinations and their applicable venues:
<pre>
---
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
...
</pre>

=== 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:
<pre>
---
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
...
</pre>

== Installation & Setup ==
A <code>setup.py</code> script is provided to generate the final <code>config.yml</code> from the <code>config.default.yml</code> template. The script also copies default reference data files if they do not already exist.

The script supports the following arguments:

<pre>
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
</pre>

== Operations ==
The Definitions Server is controlled using three operational scripts: <code>start.sh</code>, <code>stop.sh</code>, and <code>check.sh</code>.

Log files are generated in the format:
<pre>
srv_YYYYMMDD_HH_MM_SS.log
</pre>

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

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

If the server is not running, it prints:
<pre>
DefinitionsServer is not running.
</pre>

=== start.sh ===
The <code>start.sh</code> script:
* Exits immediately if the server is already running
* Creates a <code>logs/</code> directory if necessary
* Moves any existing <code>srv_*.log</code> files into <code>logs/</code>
* Starts the <code>DefinitionsServer</code> process in the background
* Writes the PID to <code>pid.lock</code>
* Reads network interfaces from <code>config.yml</code> 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 <code>stop.sh</code> script:
* Reads the PID from <code>pid.lock</code>
* Sends <code>SIGINT</code> to request a graceful shutdown
* Waits for termination using exponential backoff (up to 300 seconds)
* Sends <code>SIGKILL</code> if the server fails to stop cleanly
* Appends a forced-termination message to the most recent log file (if applicable)
* Removes the <code>pid.lock</code> file

This guarantees consistent shutdown behavior across normal and exceptional conditions.

Definitions Server - Revision history

Kamal: Created page with "= Definitions Server = The Definitions Server provides centralized reference data for the trading platform. It disseminates system-wide definitions including country codes, cu..."