Order Types & Validation

The instructions your engine will support, and how FIX 4.4 encodes them:

• Limit (OrdType 40=2) and market (40=1). A market order has no price, so it can never rest.
• Day (TimeInForce 59=0): rests until the end of the trading session.
• Good-till-cancelled, GTC (59=1): rests until cancelled (venues often purge them eventually).
• Immediate-or-cancel, IOC (59=3): trade whatever crosses right now, cancel the remainder. Never rests.
• Fill-or-kill, FOK (59=4): trade the entire quantity right now, or nothing at all. Never rests, never partially fills.
• Good-till-date, GTD (59=6): rests until a stated time.
• Post-only (also called add-liquidity-only; in FIX, ExecInst 18=6, "participate don't initiate"): the order may only rest. If it would trade on arrival, the venue rejects it — or, on some venues, reprices it one tick away from the opposite side.

Some combinations are meaningless: a market order cannot be Day or GTC (it can never rest), post-only cannot be IOC or FOK (an order that must rest cannot also be forbidden from resting). Your types should make those combinations impossible to construct, not merely rejected later.

FOK is all-or-nothing, and partially executing then rolling back is not an option: trades are facts the moment they are emitted. So the engine first answers a read-only question — is there at least qty available at prices that cross my limit? — and only if the answer is yes does it run the normal matching loop.

Three properties make the check right:

• It walks levels, not orders. Each level already knows its aggregate quantity (week 6), so the check costs one step per price level, however many orders each holds.
• It stops early. Count down from the requested quantity and stop at the first level that covers what is left. A small FOK against a deep book should touch one or two levels.
• It cannot overflow. Summing level quantities can exceed u64::MAX on adversarial input; subtracting from what you still need cannot.

Writing it as fn fok_feasible(&self, …) is the parse-don't-validate idea applied to code: the &self receiver is a compiler-checked promise that the check has no side effects. And because one thread owns the book, nothing can change between the check and the sweep, so check-then-act is atomic for free. On a sharded or multi-threaded design that guarantee would cost you a lock or a transaction.

use std::collections::BTreeMap;

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Side {
    Buy,
    Sell,
}

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct Killed;

/// Aggregated book: price → total resting quantity at that price.
/// Invariant: no level holds 0.
#[derive(Clone, Default, PartialEq, Eq, Debug)]
pub struct LevelBook {
    pub bids: BTreeMap<i64, u64>,
    pub asks: BTreeMap<i64, u64>,
}

impl LevelBook {
    /// Could an order for `qty` at `limit` fill completely right now?
    /// Buy: asks at prices ≤ limit. Sell: bids at prices ≥ limit.
    /// `&self` means the type system guarantees the check cannot mutate the
    /// book. Stop walking as soon as you know the answer — and do not let a
    /// sum of large levels overflow.
    pub fn fok_feasible(&self, side: Side, limit: i64, qty: u64) -> bool {
        todo!()
    }

    /// Fill-or-kill. If feasible, take liquidity best price first and return
    /// the (price, qty) taken per level, removing levels that empty.
    /// Otherwise return Err(Killed) and leave the book exactly as it was.
    pub fn execute_fok(&mut self, side: Side, limit: i64, qty: u64) -> Result<Vec<(i64, u64)>, Killed> {
        todo!()
    }
}

Three newtypes carry most of the weight:

• Price(i64): a fixed-point count of some small unit, guaranteed to be a multiple of the instrument's tick. The only constructors are parsers that check.
• Qty(NonZeroU64): a quantity that cannot be zero, which also makes Option<Qty> the same size as Qty thanks to the niche.
• OrderId(u64): so you cannot pass a quantity as an id by swapping two arguments.

With #[repr(transparent)] they cost nothing at runtime. What they buy is that the engine's signature, fn submit(&mut self, order: ValidOrder, …), cannot be called with an off-tick price or a zero quantity, because no such ValidOrder can exist.

Why not floats. Every price on the wire is a decimal string or a scaled integer. Converting through f64 loses exactness in ways that are easy to miss in tests: (4.35 * 100.0) as i64 is 434, not 435, and (19.99 * 100.0) as i64 is 1998. Parse the digits directly into an integer and you never have to reason about rounding again.

One more design point: positivity is an instrument property, not a universal law. The drill requires prices above zero, as for an equity. Futures spreads, and occasionally outright futures (the May 2020 WTI crude contract settled at −$37.63 a barrel), trade at negative prices, so a futures venue's Price must be signed and its validation must come from per-instrument reference data.

use std::fmt;

/// Prices are fixed-point integers: 1 unit = 10^-DECIMALS of the currency.
pub const DECIMALS: u32 = 4;
pub const SCALE: i64 = 10_000; // 10^DECIMALS

/// The instrument's minimum price increment, in units (100 = 0.01).
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct TickSize(pub i64);

/// A validated price: strictly positive and a whole number of ticks. The
/// field is private — `parse` and `from_ticks` are the only ways to get one.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
pub struct Price(i64);

/// When several problems apply, report the first in this order.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum PriceError {
    /// The input is "".
    Empty,
    /// Anything but ASCII digits with at most one '.', which must have a
    /// digit on both sides ("12", "12.5"). No sign, spaces or exponent.
    Malformed,
    /// More than DECIMALS digits after the '.', even if they are zeros.
    TooPrecise,
    /// Does not fit in i64 units.
    Overflow,
    /// Zero (or, for from_ticks, negative).
    NotPositive,
    /// Not a multiple of the tick size.
    OffTick,
}

impl Price {
    /// Parse a decimal price string into units — integers only, never f64.
    pub fn parse(s: &str, tick: TickSize) -> Result<Price, PriceError> {
        todo!()
    }

    /// `ticks` whole ticks. Overflow / NotPositive as for parse.
    pub fn from_ticks(ticks: i64, tick: TickSize) -> Result<Price, PriceError> {
        todo!()
    }

    pub fn units(self) -> i64 {
        self.0
    }

    pub fn ticks(self, tick: TickSize) -> i64 {
        todo!()
    }
}

impl fmt::Display for Price {
    /// Always DECIMALS fractional digits: 1_012_500 units → "101.2500".
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        todo!()
    }
}

Validation is not one function; it is a pipeline whose stages need different information:

1. Syntax and session (gateway): the message parses, required fields are present, the session is logged on, the client's order id is not a duplicate. Needs nothing but the message and the session.
2. Reference data (gateway or engine entry): the instrument exists and is open for trading; the price is a multiple of its tick; the quantity is a multiple of its lot size and within its maximum order size. Needs per-instrument static data.
3. Account risk (week 15): position, notional and rate limits. Needs per-account state.
4. Book-dependent checks (engine): the price is inside the band around the reference price; a post-only order would not cross; an FOK is feasible. Needs the current book and is therefore the engine's job.

Stages 1 and 2 are where parsing produces your newtypes, and by stage 4 the engine only sees well-typed orders.

Price bands stop fat-finger orders from sweeping a book. A static band is a fixed percentage around a reference price (the previous close or an auction price); a dynamic band moves with the last trade. US equities' Limit Up-Limit Down plan, for example, sets percentage bands (5% for the most liquid stocks, wider for others) around a reference price averaged over the preceding five minutes. In the repo's engine, a limit order outside the band is rejected (PriceBand), and the band is dynamic: it is measured from the last trade, or from a configured reference price before the first trade. Market orders have no price to check and are not band-limited. Letting a market order trade only up to the band edge is a common venue choice, though venues differ in the details.

Reject reasons must be typed and specific: OffTick, OffLot, QtyTooLarge, OutsideBand, WouldCross, DuplicateId, UnknownOrder, InstrumentHalted. They map onto FIX's OrdRejReason (tag 103) for new orders and CxlRejReason (tag 102) for cancels, but internally an enum with data (OutsideBand { limit, low, high }) is far more useful in logs and tests than a code and a string. The repo's types::RejectReason spells them InvalidTick, InvalidLot, PriceBand, WouldTake, DuplicateOrderId, UnknownOrder and Halted (plus ZeroQuantity, FokUnfillable, NoLiquidity, InvalidReduce and Risk(..)), and keeps them as plain variants without data (on the wire, a reject reason is a single code byte).

Post-only is the market maker's instruction: "I am quoting, I never want to pay the taker fee or trade by accident." On arrival the engine checks whether the order would cross the opposite best price. If it would, the venue either rejects it or slides it to one tick behind the opposite touch. Either way it must not trade.

A flag-based order type lets you write things the engine cannot meaningfully execute:

struct NewOrder { price: Option<i64>, tif: Tif, post_only: bool /* ... */ }
// Market + GTC? Post-only + IOC? Post-only market? All representable.

An enum makes them impossible:

enum OrderKind {
    Limit { price: Price, tif: LimitTif },   // LimitTif: Day | Gtc | Gtd(..)
    Ioc { price: Price },                    // limit IOC; remainder cancelled
    Fok { price: Price },                    // all or nothing
    PostOnly { price: Price, tif: LimitTif },
    Market { protection: Option<Price> },    // never rests
}

Each variant carries exactly the data that makes sense for it, and the engine's match is exhaustive: adding a new type later is a compile error at every place that needs a decision.

Validation code is mostly edge cases, so test it as a table: one row per input, one expected outcome per row, including every reject reason and every boundary (tick multiple exactly at the band edge, quantity equal to the maximum, FOK quantity exactly equal to the available liquidity). Then test the interactions the table cannot express: an IOC that partially fills then cancels, a FOK that is killed and leaves the book byte-for-byte unchanged, a post-only that would rest exactly at the opposite best price (it would cross; it must not trade).