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

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

User information is provided via a static JSON data file (see `users_data_schema.json` in the project root) 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.

### `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.