feat(order): add realized quote and fee onto OrderRecord (#171)

## Purpose

`get_my_orders` exposes the original limit price and cumulative base
`filled_quantity`, but nothing about the price(s) actually traded — so
the realized notional, the volume-weighted average price (VWAP), and the
fees paid cannot be recovered from an order. This adds the first,
order-level layer of that missing data: two cumulative scalars folded
into the write that already updates `filled_quantity`.

## Requirements coverage

- **R1** — `filled_quote` accumulates the realized quote notional per
fill at the maker price.
- **R2** — `filled_fee` accumulates the realized fee in the order's
receive token (the amount withheld).
- **R6 (order-level)** — both scalars are exposed on `OrderRecord`
through `get_my_orders` / `get_my_order`.
- **R7** — the scalars are folded into the same per-order write as
`filled_quantity` and only under the write gate, so replay does not
double-count.
- **R9** — every accumulation uses an always-on overflow trap.
- **R11** — per-fill notional, fees, and roles are computed once and
feed both the balance operations and the per-order deltas, so the two
can never diverge.

## Performance impact

Measured with canbench (`just bench-check`); deltas are versus the
pre-feature baseline.

- `matching` scope: ~+10–14% from the inherent per-fill u256 notional
and fee rollup.
- per-fill `qty` rollup: ~+28–35%, dominated by the u256 `Quantity`
arithmetic the realized notional/fee require (this is intrinsic to the
feature, not allocation overhead).
- `order_history::apply_update`: ~+3–6% for writing the two extra scalar
fields.
- The settlement path makes a single pass over the fills — no
intermediate `Vec<FillSettlement>` is materialized — so the residual
cost is the per-fill u256 rollup itself, not allocation.
- The whole settlement (per-fill rollup, balance-op construction,
per-order writes) now runs only under the write gate, so post-upgrade
replay does none of this work; the committed `canbench_results.yml` is
unchanged by that gating (`just bench-check` reports no change versus
the committed baseline).
- The former `status` bench scope is renamed `apply_order_updates` (it
wraps the whole per-order apply-update), so its baseline key/value
changed accordingly.

## 📚 PR stack

1. **#171 — Order-level scalars** (this PR) — base `main`.
2. **#179 — Fill store (stable-memory persistence)** — base #171.
3. **#186 — Per-order `get_my_trades { ByOrder }` feed** — base #179.
4. **#180 — Account-wide `ByAccount` filter** — base #186.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gregorydemay

canister/canbench_results.yml

@@ -297,6 +297,14 @@ type OrderRecord = record {
     last_updated_at : opt nat64;
     /// Time-in-force policy the order was placed with.
     time_in_force : TimeInForce;
+    /// Cumulative realized quote notional transacted across the order's fills,
+    /// in quote-token smallest units. The average execution price is
+    /// `filled_quote / filled_quantity` (VWAP), a ratio of the two tokens'
+    /// smallest units.
+    filled_quote : nat;
+    /// Cumulative realized fee charged across the order's fills, in the order's
+    /// receive token — base for a buy, quote for a sell.
+    filled_fee : nat;
 };
 
 /// Request for `get_my_orders`.

canister/oisy_trade.did

@@ -1,12 +1,12 @@
 use super::plan::{FillPlan, FillPlanBuilder, PlanOutcome};
 use super::queue::{OrderQueue, OrderQueueIter};
 use super::{
-    FeeRates, LotSize, Order, OrderBookId, OrderSeq, Price, Quantity, RestingOrder, Side, TickSize,
+    FeeRates, Fill, LotSize, Order, OrderBookId, OrderSeq, Price, Quantity, RestingOrder, Side,
+    TickSize,
 };
 use minicbor::{Decode, Encode};
 use std::cmp::Reverse;
 use std::collections::{BTreeMap, BTreeSet, VecDeque};
-use std::num::NonZeroU64;
 
 /// Central limit order book for a single trading pair.
 ///
@@ -579,44 +579,6 @@ impl MatchResult {
     }
 }
 
-/// A single fill produced when an incoming order matches a resting order.
-#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
-pub struct Fill {
-    /// The sequence of the incoming (taker) order.
-    #[n(0)]
-    pub taker_order_seq: OrderSeq,
-    /// The side of the taker order.
-    #[n(1)]
-    pub taker_side: Side,
-    /// The limit price of the taker order.
-    #[n(2)]
-    pub taker_price: Price,
-    /// The sequence of the resting (maker) order that was matched.
-    #[n(3)]
-    pub maker_order_seq: OrderSeq,
-    /// The price at which the fill occurred (always the maker's price).
-    #[n(4)]
-    pub maker_price: Price,
-    /// The quantity filled.
-    #[n(5)]
-    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
-    }
-}
-
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum MatchOrderError {
     /// Price is not a positive multiple of the tick size.

canister/src/order/book.rs

@@ -0,0 +1,203 @@
+use super::{FeeRates, OrderSeq, OrderUpdate, PairToken, Price, Quantity, RemovedOrder, Side};
+use crate::state::event;
+use minicbor::{Decode, Encode};
+use std::collections::BTreeMap;
+use std::num::NonZeroU64;
+
+/// A single fill produced when an incoming order matches a resting order.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct Fill {
+    /// The sequence of the incoming (taker) order.
+    #[n(0)]
+    pub taker_order_seq: OrderSeq,
+    /// The side of the taker order.
+    #[n(1)]
+    pub taker_side: Side,
+    /// The limit price of the taker order.
+    #[n(2)]
+    pub taker_price: Price,
+    /// The sequence of the resting (maker) order that was matched.
+    #[n(3)]
+    pub maker_order_seq: OrderSeq,
+    /// The price at which the fill occurred (always the maker's price).
+    #[n(4)]
+    pub maker_price: Price,
+    /// The quantity filled.
+    #[n(5)]
+    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.
+pub struct FillSettlement {
+    fill: Fill,
+    /// Quote notional `maker_price × quantity / base_scale` (the executed
+    /// price; a buy taker's reservation surplus is excluded).
+    notional: Quantity,
+    /// Fee charged to the taker order, in its receive token (base if the taker
+    /// bought, quote if it sold).
+    taker_fee: Quantity,
+    /// Fee charged to the maker order, in its receive token.
+    maker_fee: Quantity,
+    /// 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,
+}
+
+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 surplus = if fill.taker_side == Side::Buy
+            && let Some(diff) = fill.taker_price.checked_sub(fill.maker_price)
+            && !diff.is_zero()
+        {
+            diff.checked_mul_quantity_scaled(&fill.quantity, base_scale)
+                .expect("BUG: price_diff * quantity overflow — validated in validate_limit_order")
+        } else {
+            Quantity::ZERO
+        };
+        Self {
+            fill,
+            notional,
+            taker_fee,
+            maker_fee,
+            surplus,
+        }
+    }
+
+    /// Push the (up to three) balance operations a single fill settles into `ops`.
+    pub fn push_balance_operations(&self, ops: &mut Vec<event::BalanceOperation>) {
+        let fill = &self.fill;
+        let (buyer_seq, seller_seq) = match fill.taker_side {
+            Side::Buy => (fill.taker_order_seq, fill.maker_order_seq),
+            Side::Sell => (fill.maker_order_seq, fill.taker_order_seq),
+        };
+        let (quote_fee, base_fee) = match fill.taker_side {
+            Side::Buy => (self.maker_fee, self.taker_fee),
+            Side::Sell => (self.taker_fee, self.maker_fee),
+        };
+        ops.push(event::BalanceOperation::Transfer {
+            from_order: buyer_seq,
+            to_order: seller_seq,
+            token: PairToken::Quote,
+            amount: self.notional,
+            fee: nonzero(quote_fee),
+        });
+        if !self.surplus.is_zero() {
+            ops.push(event::BalanceOperation::Unreserve {
+                order: fill.taker_order_seq,
+                token: PairToken::Quote,
+                amount: self.surplus,
+            });
+        }
+        ops.push(event::BalanceOperation::Transfer {
+            from_order: seller_seq,
+            to_order: buyer_seq,
+            token: PairToken::Base,
+            amount: fill.quantity,
+            fee: nonzero(base_fee),
+        });
+    }
+
+    /// Update maker and taker orders based on this fill.
+    pub fn accrue_fill(&self, updates: &mut BTreeMap<OrderSeq, OrderUpdate>) {
+        for (order_seq, fee) in [
+            (self.fill.maker_order_seq, self.maker_fee),
+            (self.fill.taker_order_seq, self.taker_fee),
+        ] {
+            let update = updates.entry(order_seq).or_default();
+            update.filled_delta = update
+                .filled_delta
+                .checked_add(self.fill.quantity)
+                .expect("BUG: filled_delta overflow");
+            update.quote_delta = update
+                .quote_delta
+                .checked_add(self.notional)
+                .expect("BUG: quote_delta overflow");
+            update.fee_delta = update
+                .fee_delta
+                .checked_add(fee)
+                .expect("BUG: fee_delta overflow");
+        }
+    }
+}
+
+/// The settlement of a removed order (canceled or killed): the placement
+/// reservation released back to its owner, computed where `base_scale` is in
+/// scope so the matcher stays scale-agnostic.
+pub struct RemovedOrderSettlement {
+    order_seq: OrderSeq,
+    token: PairToken,
+    amount: Quantity,
+}
+
+impl RemovedOrderSettlement {
+    /// Compute the reservation released by removing an order.
+    pub fn new(order_seq: OrderSeq, removed: &RemovedOrder, base_scale: NonZeroU64) -> Self {
+        let (token, amount) = match removed.side {
+            Side::Buy => (
+                PairToken::Quote,
+                removed
+                    .price
+                    .checked_mul_quantity_scaled(&removed.remaining_quantity, base_scale)
+                    .expect("BUG: price * remaining overflow — validated at placement"),
+            ),
+            Side::Sell => (PairToken::Base, removed.remaining_quantity),
+        };
+        Self {
+            order_seq,
+            token,
+            amount,
+        }
+    }
+
+    /// Push the single unreserve operation that releases the reservation.
+    pub fn push_balance_operations(&self, ops: &mut Vec<event::BalanceOperation>) {
+        ops.push(event::BalanceOperation::Unreserve {
+            order: self.order_seq,
+            token: self.token,
+            amount: self.amount,
+        });
+    }
+}
+
+/// 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
+/// charged".
+fn nonzero(q: Quantity) -> Option<Quantity> {
+    if q.is_zero() { None } else { Some(q) }
+}

canister/src/order/fill.rs

@@ -45,6 +45,15 @@ pub struct OrderRecord {
     /// Time-in-force policy the order was placed with.
     #[n(8)]
     pub time_in_force: TimeInForce,
+    /// Cumulative realized quote notional transacted across the order's fills,
+    /// `Σ (maker_price × fill_quantity / base_scale)`. Always quote-denominated;
+    /// a buy taker's released reservation surplus is excluded.
+    #[n(9)]
+    pub filled_quote: Quantity,
+    /// Cumulative realized fee charged across the order's fills, denominated in
+    /// the order's receive token — base for a buy, quote for a sell.
+    #[n(10)]
+    pub filled_fee: Quantity,
 }
 
 impl From<OrderRecord> for oisy_trade_types::OrderRecord {
@@ -59,17 +68,22 @@ impl From<OrderRecord> for oisy_trade_types::OrderRecord {
             created_at: record.created_at.as_nanos(),
             last_updated_at: record.last_updated_at.map(|t| t.as_nanos()),
             time_in_force: record.time_in_force.into(),
+            filled_quote: record.filled_quote.into(),
+            filled_fee: record.filled_fee.into(),
         }
     }
 }
 
 /// A combined update to an order record, applied in a single read-modify-write
-/// by [`OrderHistory::apply_update`]: an optional status transition plus a
-/// fill delta to add to `filled_quantity`.
+/// by [`OrderHistory::apply_update`]: an optional status transition plus the
+/// fill, quote, and fee deltas to add to `filled_quantity`, `filled_quote`, and
+/// `filled_fee`.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct OrderUpdate {
     pub status: Option<OrderStatus>,
     pub filled_delta: Quantity,
+    pub quote_delta: Quantity,
+    pub fee_delta: Quantity,
 }
 
 impl OrderUpdate {
@@ -78,6 +92,8 @@ impl OrderUpdate {
         Self {
             status: Some(status),
             filled_delta: Quantity::ZERO,
+            quote_delta: Quantity::ZERO,
+            fee_delta: Quantity::ZERO,
         }
     }
 
@@ -86,6 +102,8 @@ impl OrderUpdate {
         Self {
             status: None,
             filled_delta,
+            quote_delta: Quantity::ZERO,
+            fee_delta: Quantity::ZERO,
         }
     }
 
@@ -94,13 +112,16 @@ impl OrderUpdate {
     /// # Panics
     ///
     /// `filled_quantity` is monotonic non-decreasing and must never exceed
-    /// `quantity`; this invariant is enforced by an always-on check that traps
-    /// on violation.
+    /// `quantity`; `filled_quote` and `filled_fee` are monotonic
+    /// non-decreasing. These invariants are enforced by always-on checks that
+    /// trap on violation.
     pub fn apply(self, order: &mut OrderRecord) -> bool {
         let mut changed = false;
         let OrderUpdate {
             status,
             filled_delta,
+            quote_delta,
+            fee_delta,
         } = self;
 
         if let Some(new_status) = status
@@ -125,6 +146,22 @@ impl OrderUpdate {
                 order.created_at,
             );
         }
+
+        if quote_delta != Quantity::ZERO {
+            changed = true;
+            order.filled_quote = order
+                .filled_quote
+                .checked_add(quote_delta)
+                .expect("BUG: filled_quote overflow");
+        }
+
+        if fee_delta != Quantity::ZERO {
+            changed = true;
+            order.filled_fee = order
+                .filled_fee
+                .checked_add(fee_delta)
+                .expect("BUG: filled_fee overflow");
+        }
         changed
     }
 }