73 lines
5.6 KiB
Markdown
73 lines
5.6 KiB
Markdown
# Proto Definitions
|
|
|
|
This directory contains the Protobuf definitions that describe the entire messaging contract of the exchange system. Every message your components must accept, respond to, or emit is defined here.
|
|
|
|
These files are the **contract your implementation must satisfy** — system tests will connect to your components over TCP and exchange exactly these messages.
|
|
|
|
## Where to start
|
|
|
|
Begin with **`common.proto`**. It contains the `MessageType` enum, which is the single authoritative index of every message in the system. The enum is grouped by module (Auth, Admin, Info, Order Book, Execution, Risk), giving you a map of the whole system before you dive into any individual file. It also defines the shared types that appear everywhere else: `Instrument`, `Side`, and the auth `LoginRequest`/`LoginResponse` pair.
|
|
|
|
## File-by-file overview
|
|
|
|
### `common.proto`
|
|
The foundation. Defines:
|
|
- `MessageType` — a numbered enum of every request/response/notification in the system, grouped by subsystem.
|
|
- `Instrument` — the data model for a tradeable instrument (symbol, description, currency, multiplier).
|
|
- `Side` — the `BUY`/`SELL` enum used across order-related messages.
|
|
- `LoginRequest` / `LoginResponse` — the authentication handshake your components must perform with every connecting client before serving any other message.
|
|
|
|
User information is provided via a static JSON data file (see `users_data_schema.json`) whose path is supplied in each component's config as `dataFilePath`. Components that require authentication must read this file at startup to validate login credentials.
|
|
|
|
Read this first to orient yourself. Every other file imports it.
|
|
|
|
### `admin.proto`
|
|
The administration interface your exchange must expose to let the system be bootstrapped before trading begins.
|
|
|
|
- `CreateInstrumentRequest/Response` — your exchange must accept requests to list a new tradeable instrument, create an order book for it, and return the assigned `order_book_id`.
|
|
|
|
### `info.proto`
|
|
The market data feed your exchange must maintain and push to subscribed clients.
|
|
|
|
- `OnInstrument` — your exchange must push this to every client on connection (for all existing instruments) and again whenever a new instrument is created.
|
|
- `OrderBookSubscribeRequest/Response` — clients may subscribe to a specific instrument's order book in one of two modes. Your exchange must honour the chosen type and push updates accordingly:
|
|
- `TOP_OF_BOOK` — push `OnTopOfBook` whenever the best bid or ask changes.
|
|
- `PRICE_DEPTH_BOOK` — push `OnPriceDepthBook` with the full visible depth on every change.
|
|
- `OnTrade` — your exchange must broadcast this to all subscribed clients whenever a trade occurs, showing price, quantity, and which side was the aggressor.
|
|
|
|
### `order_book.proto`
|
|
The core of the exchange: the matching engine. This component stores resting orders, matches them when prices cross, and is the authoritative source of order book state.
|
|
|
|
It has two responsibilities:
|
|
|
|
**State broadcast** — pushed to all connected clients upon login (current state) and on every subsequent change:
|
|
- `OnOrderInserted` — broadcast when a new order enters the book, including any trades it immediately triggered.
|
|
- `OnOrderCancelled` — broadcast when an order is removed from the book.
|
|
- `OnTrade` — broadcast when a match occurs, carrying both the buy and sell `order_id`s and full trade details.
|
|
|
|
**Request/response** — your order book component must accept these from other internal services:
|
|
- `InsertOrderRequest/Response` — place a limit order identified by `order_book_id`. Your component must assign an `order_id`, record the timestamp, attempt to match, and return the result.
|
|
- `CancelOrderRequest/Response` — cancel a resting order by `order_book_id` and `order_id`. Your component must confirm the cancellation timestamp and remaining quantity at the time of removal.
|
|
|
|
### `execution.proto`
|
|
The client-facing execution interface your exchange must expose to trading clients. It is a higher-level entry point into the order book: clients address orders by `instrument_symbol` (human-readable) rather than `order_book_id` (internal numeric ID), so this component is responsible for the translation.
|
|
|
|
- `InsertOrderRequest/Response` — accept a limit order from a client, resolve the instrument to its order book, forward it, and return the result (order ID, timestamp, fills).
|
|
- `CancelOrderRequest/Response` — accept a cancellation request from a client and forward it to the appropriate order book.
|
|
- `OnTrade` — your exchange must send this **privately** to the specific client whose order was involved in a trade, reporting their `order_id`, side, and whether they were the aggressor.
|
|
|
|
### `risk_limits.proto`
|
|
The risk management component your exchange must implement to enforce guardrails on all trading activity. Before an order reaches the order book, risk limits must be checked.
|
|
|
|
Limits operate at two scopes:
|
|
|
|
**User-level** (`UserRiskLimits`):
|
|
- `max_outstanding_quantity` — caps the total quantity a user may have resting across all instruments simultaneously.
|
|
- `message_rate_rolling_limit` — caps the number of order/cancellation messages a user may send within a rolling time window.
|
|
|
|
**Instrument-level** (`InstrumentRiskLimits`):
|
|
- `max_outstanding_quantity` / `max_outstanding_amount` — caps how much of a single instrument a user may have resting at one time.
|
|
- `order_quantity_rolling_limit` / `order_amount_rolling_limit` — rolling-window caps on order flow per instrument.
|
|
|
|
Each scope has a symmetric `Get.../Set...` request/response pair. Your component must persist these limits and enforce them on every incoming order.
|