feat(order): persist per-fill records in stable memory (3/5)

canister/oisy_trade.did

@@ -695,6 +695,18 @@ type MatchingEvent = record {
 type SettlingEvent = record {
     book_id : nat64;
     balance_operations : vec BalanceOperation;
+    fills : vec FillEvent;
+};
+
+// Per-fill record carried on a settling event: the fill's identity, the matched
+// quantity, and the maker/taker fee rates in basis points.
+type FillEvent = record {
+    fill_seq : nat64;
+    taker_order_seq : nat64;
+    maker_order_seq : nat64;
+    quantity : nat;
+    maker_fee_bps : nat16;
+    taker_fee_bps : nat16;
 };
 
 // Balance movement recorded during settlement. `from_order` / `to_order` /

canister/src/main.rs

@@ -243,6 +243,17 @@ fn get_events(
         }
     }
 
+    fn map_fill_event(fill: oisy_trade_canister::order::FillEvent) -> event::FillEvent {
+        event::FillEvent {
+            fill_seq: fill.fill_seq.get(),
+            taker_order_seq: fill.taker_order_seq.get(),
+            maker_order_seq: fill.maker_order_seq.get(),
+            quantity: fill.quantity.into(),
+            maker_fee_bps: fill.fee_rates.maker.get(),
+            taker_fee_bps: fill.fee_rates.taker.get(),
+        }
+    }
+
     fn map_event(event: Event) -> event::Event {
         event::Event {
             timestamp: event.timestamp.as_nanos(),
@@ -333,12 +344,14 @@ fn get_events(
                 EventType::Settling(oisy_trade_canister::state::event::SettlingEvent {
                     book_id,
                     balance_operations,
+                    fills,
                 }) => event::EventType::Settling(event::SettlingEvent {
                     book_id: book_id.get(),
                     balance_operations: balance_operations
                         .into_iter()
                         .map(map_balance_operation)
                         .collect(),
+                    fills: fills.into_iter().map(map_fill_event).collect(),
                 }),
                 EventType::SetHalt(e) => event::EventType::SetHalt(event::SetHaltEvent {
                     book_ids: e

canister/src/order/fill.rs

@@ -1,7 +1,8 @@
 use super::{
     FeeRates, OrderBookId, OrderId, OrderSeq, OrderUpdate, PairToken, Price, Quantity,
-    RemovedOrder, Side,
+    RemovedOrder, Side, TradeLeg, TradeRecord,
 };
+use crate::Timestamp;
 use crate::ids::{CompositeId, Seq, SeqMarker};
 use crate::state::event;
 use minicbor::{Decode, Encode};
@@ -49,50 +50,42 @@ impl TradeId {
 }
 
 /// A single fill produced when an incoming order matches a resting order.
-#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Fill {
     /// The per-book sequence of this match, minted by the order book.
-    #[n(0)]
     pub fill_seq: FillSeq,
     /// The sequence of the incoming (taker) order.
-    #[n(1)]
     pub taker_order_seq: OrderSeq,
     /// The side of the taker order.
-    #[n(2)]
     pub taker_side: Side,
     /// The limit price of the taker order.
-    #[n(3)]
     pub taker_price: Price,
     /// The sequence of the resting (maker) order that was matched.
-    #[n(4)]
     pub maker_order_seq: OrderSeq,
     /// The price at which the fill occurred (always the maker's price).
-    #[n(5)]
     pub maker_price: Price,
     /// The quantity filled.
-    #[n(6)]
     pub quantity: Quantity,
 }
 
 impl Fill {
-    /// The amount of quote tokens exchanged:
-    /// `maker_price × quantity / base_scale` (`base_scale = 10^base_decimals`).
-    pub fn quote_amount(&self, base_scale: NonZeroU64) -> Quantity {
-        self.maker_price
-            .checked_mul_quantity_scaled(&self.quantity, base_scale)
-            .expect("BUG: validation of order should prevent overflow")
-    }
-
     /// The amount of base tokens exchanged (same as quantity).
     pub fn base_amount(&self) -> &Quantity {
         &self.quantity
     }
 }
 
 /// A single [`Fill`] together with the realized values derived from it, computed
-/// once in settlement (the only point where both `fee_rates` and `base_scale`
-/// are in scope) and reused to build both the [`event::BalanceOperation`]s and
-/// the per-order scalar deltas, so the two can never diverge.
+/// once in the matching phase (the only point where both `fee_rates` and
+/// `base_scale` are in scope) and used to project both the
+/// [`event::BalanceOperation`]s and the per-order scalar deltas, so the two can
+/// never diverge.
+///
+/// This is a matching-phase, heap-only helper: it is never CBOR-encoded into the
+/// event log. The settling event carries the lean [`FillEvent`] instead, and the
+/// settling phase recovers side/price from the order records and recomputes the
+/// realized values to rebuild the two side-projected [`TradeRecord`]s.
+#[derive(Debug)]
 pub struct FillSettlement {
     fill: Fill,
     /// Quote notional `maker_price × quantity / base_scale` (the executed
@@ -106,27 +99,21 @@ pub struct FillSettlement {
     /// Quote surplus released back to a buy taker that crossed below its limit;
     /// Zero for a sell taker or an exact-price fill.
     surplus: Quantity,
+    /// Snapshot of the book's fee rates at match time, carried onto the lean
+    /// [`FillEvent`] so settling can recompute the fees off the pinned rates.
+    fee_rates: FeeRates,
 }
 
 impl FillSettlement {
     /// Compute the realized values of a single fill once.
     pub fn new(fill: Fill, fee_rates: FeeRates, base_scale: NonZeroU64) -> Self {
-        // Receive-side convention: buyer pays fee in base (the asset they
-        // receive), seller in quote. Each side's rate is `taker` if they
-        // were the taker, else `maker`.
-        let (buyer_rate, seller_rate) = match fill.taker_side {
-            Side::Buy => (fee_rates.taker, fee_rates.maker),
-            Side::Sell => (fee_rates.maker, fee_rates.taker),
-        };
-        let notional = fill.quote_amount(base_scale);
-        let quote_fee = seller_rate.mul_ceil(notional);
-        let base_fee = buyer_rate.mul_ceil(fill.quantity);
-        // The taker pays on the side it traded: base if it bought, quote if
-        // it sold. The maker pays on the opposite side.
-        let (taker_fee, maker_fee) = match fill.taker_side {
-            Side::Buy => (base_fee, quote_fee),
-            Side::Sell => (quote_fee, base_fee),
-        };
+        let (notional, taker_fee, maker_fee) = fees(
+            fill.maker_price,
+            fill.quantity,
+            fill.taker_side,
+            fee_rates,
+            base_scale,
+        );
         let surplus = if fill.taker_side == Side::Buy
             && let Some(diff) = fill.taker_price.checked_sub(fill.maker_price)
             && !diff.is_zero()
@@ -142,6 +129,7 @@ impl FillSettlement {
             taker_fee,
             maker_fee,
             surplus,
+            fee_rates,
         }
     }
 
@@ -200,6 +188,124 @@ impl FillSettlement {
                 .expect("BUG: fee_delta overflow");
         }
     }
+
+    /// The lean, normalized record persisted on the settling event: the fill's
+    /// identity, quantity, and the fee-rate snapshot — everything else is
+    /// recovered or recomputed in the settling phase.
+    pub fn settled_fill(&self) -> FillEvent {
+        FillEvent {
+            fill_seq: self.fill.fill_seq,
+            taker_order_seq: self.fill.taker_order_seq,
+            maker_order_seq: self.fill.maker_order_seq,
+            quantity: self.fill.quantity,
+            fee_rates: self.fee_rates,
+        }
+    }
+}
+
+/// The lean, normalized per-fill record carried on the settling event and the only
+/// fill data persisted in the event log. It stores just what cannot be recovered
+/// otherwise: the fill's identity, the matched `quantity`, and a snapshot of the
+/// book's `fee_rates` at match time.
+///
+/// The fill's execution price (the maker price) and its taker `side` are NOT
+/// stored: they are recovered in the settling phase from the two referenced order
+/// records. `fee_rates` is snapshotted here rather than recovered because the rate
+/// lives on the book and is mutable — it is the one fee input pinned by neither the
+/// fill identity nor the orders.
+#[derive(Clone, PartialEq, Eq, Debug, Encode, Decode)]
+pub struct FillEvent {
+    #[n(0)]
+    pub fill_seq: FillSeq,
+    #[n(1)]
+    pub taker_order_seq: OrderSeq,
+    #[n(2)]
+    pub maker_order_seq: OrderSeq,
+    #[n(3)]
+    pub quantity: Quantity,
+    #[n(4)]
+    pub fee_rates: FeeRates,
+}
+
+impl FillEvent {
+    /// Rebuild the two side-projected [`TradeRecord`]s — the taker leg and the
+    /// maker leg — from this lean record, the side/price recovered from the order
+    /// records, and the freshly recomputed `notional` and fees. Each leg is keyed
+    /// by its [`TradeId`] `(OrderId, FillSeq)`, shares the match's `fill_seq`, and
+    /// self-describes one order's view of the execution without ever referencing
+    /// the counterparty. Consumed by [`crate::order::TradeHistory::append`].
+    pub fn trade_legs(
+        &self,
+        book_id: OrderBookId,
+        taker_side: Side,
+        maker_price: Price,
+        base_scale: NonZeroU64,
+        timestamp: Timestamp,
+    ) -> [TradeLeg; 2] {
+        let (notional, taker_fee, maker_fee) = fees(
+            maker_price,
+            self.quantity,
+            taker_side,
+            self.fee_rates,
+            base_scale,
+        );
+        let maker_side = match taker_side {
+            Side::Buy => Side::Sell,
+            Side::Sell => Side::Buy,
+        };
+        let taker_id = TradeId::new(OrderId::new(book_id, self.taker_order_seq), self.fill_seq);
+        let taker_leg = TradeRecord {
+            side: taker_side,
+            price: maker_price,
+            quantity: self.quantity,
+            notional,
+            fee: taker_fee,
+            fee_token: fee_token(taker_side),
+            is_maker: false,
+            timestamp,
+        };
+        let maker_id = TradeId::new(OrderId::new(book_id, self.maker_order_seq), self.fill_seq);
+        let maker_leg = TradeRecord {
+            side: maker_side,
+            price: maker_price,
+            quantity: self.quantity,
+            notional,
+            fee: maker_fee,
+            fee_token: fee_token(maker_side),
+            is_maker: true,
+            timestamp,
+        };
+        [(taker_id, taker_leg), (maker_id, maker_leg)]
+    }
+}
+
+/// The fill's `(notional, taker_fee, maker_fee)`: the quote notional and the fee
+/// charged to each of the fill's two orders, each in its receive token. Shared by
+/// the matching-phase [`FillSettlement::new`] and the settling-phase
+/// [`FillEvent::trade_legs`] recompute, so the balance ops and the persisted trade
+/// legs can never diverge, and the notional (the costliest arithmetic) is computed
+/// once per fill at each call site.
+fn fees(
+    maker_price: Price,
+    quantity: Quantity,
+    taker_side: Side,
+    fee_rates: FeeRates,
+    base_scale: NonZeroU64,
+) -> (Quantity, Quantity, Quantity) {
+    let (buyer_rate, seller_rate) = match taker_side {
+        Side::Buy => (fee_rates.taker, fee_rates.maker),
+        Side::Sell => (fee_rates.maker, fee_rates.taker),
+    };
+    let notional = maker_price
+        .checked_mul_quantity_scaled(&quantity, base_scale)
+        .expect("BUG: validation of order should prevent overflow");
+    let quote_fee = seller_rate.mul_ceil(notional);
+    let base_fee = buyer_rate.mul_ceil(quantity);
+    let (taker_fee, maker_fee) = match taker_side {
+        Side::Buy => (base_fee, quote_fee),
+        Side::Sell => (quote_fee, base_fee),
+    };
+    (notional, taker_fee, maker_fee)
 }
 
 /// The settlement of a removed order (canceled or killed): the placement
@@ -241,6 +347,15 @@ impl RemovedOrderSettlement {
     }
 }
 
+/// The token a fill's fee is charged in, per the receive-side convention: a
+/// buyer is charged in the base token it receives, a seller in quote.
+fn fee_token(side: Side) -> PairToken {
+    match side {
+        Side::Buy => PairToken::Base,
+        Side::Sell => PairToken::Quote,
+    }
+}
+
 /// Collapse a zero-quantity fee to `None`. Keeps `Some(_)` reserved for
 /// "fee was actually charged" so callers (audit log, apply path,
 /// `/metrics`) can distinguish "no fee on this fill" from "fee of zero

canister/src/order/mod.rs

@@ -9,13 +9,12 @@ mod tests;
 mod trades;
 
 pub use crate::history::CursorNotFound;
-pub use crate::history::CursorNotFound as TradeCursorNotFound;
 pub use book::{
     MatchOrderError, MatchResult, MatchingOutput, NotionalError, OrderBook, OrderBookSnapshot,
     PriceLevel, RemovedOrder,
 };
 pub use fees::{BasisPoint, FeeRates, InvalidBasisPoint};
-pub use fill::{Fill, FillId, FillSeq, FillSettlement, RemovedOrderSettlement, TradeId};
+pub use fill::{Fill, FillEvent, FillId, FillSeq, FillSettlement, RemovedOrderSettlement, TradeId};
 pub use history::{OrderHistory, OrderUpdate};
 pub use trades::{TradeHistory, TradeLeg, TradeRecord};