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

2026-05-27T19:51:39Z

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

New page

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 (<code>server</code> and <code>service_locator</code>) plus several inline fields that specify reference data files and platform metadata. 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_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"]
</pre>

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. Usage:

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

== 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 (<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 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: <code>start.sh</code>, <code>stop.sh</code>, and <code>check.sh</code>.

=== start.sh ===

* 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.
* 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 ===

* 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).

This guarantees consistent shutdown behavior across normal and exceptional conditions.

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

== Logging ==

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

Definitions Server - Revision history

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