Engine & Code ⚡

/// Book side (spec §3.1): buys match highest price first, sells lowest first.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Side {
    /// Bid: price priority = higher first.
    Buy,
    /// Ask: price priority = lower first.
    Sell,
}

impl Side {
    /// The opposite book side.
    pub const fn opposite(self) -> Side {
        match self {
            Side::Buy => Side::Sell,
            Side::Sell => Side::Buy,
        }
    }
}

/// Order type (spec §2.1). A market order has no price, can never rest, and
/// MUST carry `tif ∈ {IOC, FOK}` (GTC market ⇒ reject `InvalidTif`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum OrderType {
    /// Limit order: `(side, price, qty, tif, flags, client_order_id)`.
    Limit,
    /// Market order: `(side, qty, tif ∈ {IOC, FOK}, flags, client_order_id)`.
    Market,
}

/// Time-in-force (spec §2.3).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TimeInForce {
    /// Good-till-canceled: match what crosses, remainder rests (spec §2.3).
    Gtc,
    /// Immediate-or-cancel: match now, cancel remainder
    /// (`OrderCanceled{reason: IocRemainder}`, spec §2.3).
    Ioc,
    /// Fill-or-kill: atomic feasibility check (spec §5.3); all-or-nothing,
    /// infeasible ⇒ `OrderCanceled{reason: FokUnfillable}` with no state
    /// change besides the event.
    Fok,
}

/// Order flags (spec §2.2). `post_only` is limit-only and rejected with IOC,
/// FOK, or market orders (`InvalidFlagCombination` / contradiction rules,
/// spec §2.2).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct OrderFlags {
    /// Post-only: if the order would take liquidity for ANY quantity it is
    /// rejected whole (`PostOnlyWouldCross`) — never re-priced, never
    /// partially posted (spec §2.2, E10/E11: the cross check precedes STP).
    pub post_only: bool,
    /// Reduce-only: may only decrease the account's net position; clamped at
    /// every position-changing event, auto-reduced (`OrderReduced`) or
    /// auto-canceled (`ReduceOnlyAuto`) as reducible amount shrinks
    /// (spec §2.2, E18).
    pub reduce_only: bool,
}

/// Self-trade-prevention policy (spec §7). Per-order parameter with a
/// chain-level default; all three are implemented and switchable.
///
/// Chain default: `CancelNewest` (the most queue-protective policy),
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum StpPolicy {
    /// Cancel the incoming taker remainder; resting order untouched; fills
    /// already executed stand (spec §7.1). **Chain default** (Q2).
    #[default]
    CancelNewest,
    /// Cancel the resting maker; the matching loop continues (spec §7.2).
    CancelOldest,
    /// Decrement both by `min(t, m)` with no fill, no fee, no trade print;
    /// emits `SelfTradeDecremented` (spec §7.3).
    Decrement,
}

/// Abstraction over price-level book operations used by the matching loop.
///
/// Implementations MUST be deterministic (spec D2): iteration orders are
/// fully specified — levels best-first, FIFO by `seq` within a level.
pub trait BookIndex {
    /// Best (highest) bid price, if any bids rest.
    fn best_bid(&self) -> Option<Price>;

    /// Best (lowest) ask price, if any asks rest.
    fn best_ask(&self) -> Option<Price>;

    /// Best price on `side` (`Buy` ⇒ best bid, `Sell` ⇒ best ask).
    fn best(&self, side: Side) -> Option<Price> {
        match side {
            Side::Buy => self.best_bid(),
            Side::Sell => self.best_ask(),
        }
    }

    /// Insert `order` at the tail of the FIFO at its price level on `side`,
    /// creating the level if absent. Returns the order's node handle.
    /// The order MUST be a restable limit order (`price` set).
    fn insert(&mut self, side: Side, price: Price, order: Order) -> u32;

    /// Remove the order with `handle` from `side`/`price`, returning it.
    /// Removes the level when it becomes empty.
    fn remove(&mut self, side: Side, price: Price, handle: u32) -> Order;

    /// Handle of the FIFO head (oldest `seq`) at `side`/`price`, if the
    /// level exists.
    fn level_head(&self, side: Side, price: Price) -> Option<u32>;

    /// Handle of the FIFO tail (newest `seq`) at `side`/`price`, if the
    /// level exists.
    fn level_tail(&self, side: Side, price: Price) -> Option<u32>;

    /// Aggregates for the level at `side`/`price`, if it exists.
    fn level_aggregates(&self, side: Side, price: Price) -> Option<LevelAggregates>;

    /// The next level on `side` strictly *worse* than `price` (for bids:
    /// next lower; for asks: next higher), if any.
    fn next_level_worse(&self, side: Side, price: Price) -> Option<Price>;

    /// Borrow the node behind `handle`.
    fn node(&self, handle: u32) -> &OrderNode;

    /// Decrease the remaining quantity of the order at `handle` by `dec`
    /// lots, keeping level aggregates consistent. Queue position is
    /// preserved (spec §3.1.3). Panics if `dec` exceeds remaining.
    fn decrease_remaining(&mut self, side: Side, price: Price, handle: u32, dec: Qty);

    /// Handle of the next order (later `seq`) after `handle` within its
    /// level, or `None` at the tail.
    fn next_in_level(&self, handle: u32) -> Option<u32>;

    /// Look up a resting order's location by id: `(side, price, handle)`.
    fn locate(&self, id: OrderId) -> Option<(Side, Price, u32)>;

    /// Total number of resting orders across both sides.
    fn order_count(&self) -> u32;

    /// All level prices on `side`, best-first (bids descending, asks
    /// ascending). Allocates; used by serialization/state-hash, not the hot
    /// matching path.
    fn levels_best_first(&self, side: Side) -> Vec<Price>;
}

fn match_loop(&mut self, incoming: &mut Order, budget: Option<u32>) -> (LoopExit, u32) {
        let opposite = incoming.side.opposite();
        let mut makers_touched: u32 = 0;

        while incoming.remaining.0 > 0 {
            let Some(best) = self.book.best(opposite) else {
                break; // empty book
            };
            if let Some(limit) = incoming.price {
                if !Self::crosses(incoming.side, limit, best) {
                    break; // no longer crosses
                }
            }
            if let Some(b) = budget {
                if makers_touched >= b {
                    break; // fill budget exhausted (spec §5.4)
                }
            }
            let head = self
                .book
                .level_head(opposite, best)
                .expect("best level must be non-empty");

            let (maker_id, maker_account, maker_remaining) = {
                let node = self.book.node(head);
                (node.order.id, node.order.account, node.order.remaining)
            };

            // STP (spec §7): incoming would fill against a resting order of
            // the same account — apply the incoming order's policy.
            if maker_account == incoming.account {
                match incoming.stp {
                    StpPolicy::CancelNewest => {
                        // §7.1: cancel the taker's remainder; fills already
                        // executed stand; resting order untouched (keeps its
                        // queue position).
                        self.emit(EventBody::OrderCanceled {
                            order_id: incoming.id,
                            reason: CancelReason::StpCancelNewest,
                            remaining_at_cancel: incoming.remaining,
                        });
                        return (LoopExit::TakerStpTerminated, makers_touched);
                    }
                    StpPolicy::CancelOldest => {
                        // §7.2: cancel the resting maker; the loop continues
                        // with the next FIFO order / next level.
                        let maker = self.book.remove(opposite, best, head);
                        self.untrack(&maker);
                        self.emit(EventBody::OrderCanceled {
                            order_id: maker.id,
                            reason: CancelReason::StpCancelOldest,
                            remaining_at_cancel: maker.remaining,
                        });
                        makers_touched += 1; // maker consumed (module doc)
                        continue;
                    }
                    StpPolicy::Decrement => {
                        // §7.3: decrement both by d = min(t, m); no fill, no
                        // fee, no trade print, no position change.
                        let d = Qty(incoming.remaining.0.min(maker_remaining.0));
                        self.emit(EventBody::SelfTradeDecremented {
                            maker_order_id: maker_id,
                            taker_order_id: incoming.id,
                            qty: d,
                        });
                        incoming.remaining = Qty(incoming.remaining.0 - d.0);
                        if maker_remaining.0 == d.0 {
                            let maker = self.book.remove(opposite, best, head);
                            self.untrack(&maker);
                            self.emit(EventBody::OrderCanceled {
                                order_id: maker.id,
                                reason: CancelReason::StpDecrement,
                                remaining_at_cancel: Qty(0),
                            });
                        } else {
                            self.book.decrease_remaining(opposite, best, head, d);
                        }
                        makers_touched += 1; // maker (partially) consumed
                        if incoming.remaining.0 == 0 {
                            // Taker-terminal (module doc): remainder record
                            // canceled at 0; no residue rules afterwards.
                            self.emit(EventBody::OrderCanceled {
                                order_id: incoming.id,
                                reason: CancelReason::StpDecrement,
                                remaining_at_cancel: Qty(0),
                            });
                            return (LoopExit::TakerStpTerminated, makers_touched);
                        }
                        continue;
                    }
                }
            }
            let fill = Qty(incoming.remaining.0.min(maker_remaining.0));
            let maker_after = Qty(maker_remaining.0 - fill.0);
            incoming.remaining = Qty(incoming.remaining.0 - fill.0);

sol_storage! {
    #[entrypoint]
    pub struct Clob {
        /// Tick-bitmap book storage.
        BookStore book;
        /// Engine non-book ledgers + account interning.
        LedgerStore ledger;
        /// Market id (event envelope).
        uint64 market_id;
        /// --- packed MarketConfig (immutable after init) ---
        uint64 tick_size;
        uint64 max_tick;
        uint64 lot_size;
        uint64 min_order_size;
        uint32 fok_max_fill_levels;
        uint32 fill_budget;
        uint32 max_batch_len;
        uint32 max_open_orders_per_account;
        uint8 default_stp;
        /// Initialized flag (init() may run once).
        bool initialized;
    }
}


// -- public ABI -------------------------------------------------------------

#[public]
impl Clob {
    pub fn place_limit(
        &mut self,
        side: u8,
        price: u64,
        qty: u64,
        tif: u8,
        flags: u8,
        stp: u8,
        client_order_id: U256,
    ) -> Result<u64, Vec<u8>> {
        let account = self.caller_handle();
        let cfg = self.read_config();
        let mid = MarketId(self.market_id.get().low_u64());
        let mut sink = LogSink;
        let mut book = BitmapBook::new(&mut self.book);
        let mut ledger = StorageLedger::new(&mut self.ledger);
        let mut ctx = EngineCtx {
            market_id: mid,
            config: &cfg,
            book: &mut book,
            ledger: &mut ledger,
            sink: &mut sink,
        };
        // Standalone placement: a reject is an EVENT + consumed seq, NOT a tx
        // revert (Phase-1 semantics, spec E6). The OrderRejected log was already
        // emitted inside `place_limit`; we return the order id on accept, or 0
        // on reject (the auditable outcome is the log, not the return value).
        Ok(ctx
            .place_limit(
                account,
                side_from_u8(side),
                Price(price),
                Qty(qty),
                tif_from_u8(tif),
                flags_from_u8(flags),
                stp_from_u8(stp),
                ClientOrderId(client_order_id.low_u128()),
            )
            .map(|id| id.0)
            .unwrap_or(0))
    }

    // ... place_market, replace, continue_match, expire_suspended, batch ...
}

pub fn canonical_state<B: BookIndex + Clone>(engine: &Engine<B>) -> Vec<u8> {
    let mut out = Vec::new();
    out.extend_from_slice(b"RAINBOOKv1");
    engine.market_id().encode(&mut out);
    out.extend_from_slice(&engine.seq_peek().to_be_bytes());

    for side in [Side::Buy, Side::Sell] {
        let book = engine.book();
        let levels = book.levels_best_first(side); // bids desc, asks asc
        out.extend_from_slice(&u32::try_from(levels.len()).unwrap().to_be_bytes());
        for price in levels {
            let agg = book
                .level_aggregates(side, price)
                .expect("listed level must exist");
            price.encode(&mut out);
            out.extend_from_slice(&agg.order_count.to_be_bytes());
            // FIFO head → tail (spec §3.1: seq order within level).
            let mut cursor = book.level_head(side, price);
            while let Some(handle) = cursor {
                encode_order(&book.node(handle).order, &mut out);
                cursor = book.next_in_level(handle);
            }
        }
    }

    let positions = engine.positions(); // BTreeMap: account ascending
    out.extend_from_slice(&u32::try_from(positions.len()).unwrap().to_be_bytes());
    for (account, pos) in positions {
        out.extend_from_slice(&account.to_be_bytes());
        out.extend_from_slice(&pos.to_be_bytes());
    }
    // ... suspended continuation, then SHA-256 of the bytes ...
}