> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/math-engine/system.md). # System The oracle's guarded mark price is the system's central clock: it simultaneously revalues every position's unrealized PnL, sets maintenance requirements, and collars order prices, while executed fills feed back into the trade window that shapes the mark itself. The funding premium is the deliberate exception — it is measured against the perp reference price (the book's own volume-weighted median trade price), not the mark; see the funding-rate cluster below. Account health composes as fills → entry price → unrealized PnL → equity → margin ratios and admission headroom, and when equity crosses total maintenance margin the liquidation cascade fires: collateral is apportioned, bankruptcy-priced close orders execute, and the settlement residue splits into spread profit and penalties credited to the insurance fund versus bad debt drawn from it, with ADL as the terminal backstop. Funding closes the loop as a periodic value transfer that debits or credits equity through the settlement layer, coupling the price-formation and account-health subsystems continuously rather than only at liquidation. 84 expressions, 86 relationships (41 cross-primitive), across 6 clusters. ![The full relationship graph: every tagged expression grouped by primitive (order-book, position-tracker, margin-math, oracle, funding-rate, liquidation-engine, insurance-fund), with edges showing which expressions feed, bound, or trigger which others.](/files/o7dVQK3F6HENJ1587opO) *The interactive version of this graph — pan, zoom, and click through to each expression — lives on the engine's own site; this is a static capture of it.* ## Clusters ### Price formation & oracle defense Deviation guards, staleness, and re-anchor escalation defend the trusted anchor that blends with the trade median into the mark price every downstream primitive consumes. `oracle.single_step_deviation`, `oracle.path_deviation`, `oracle.path_threshold`, `oracle.is_stale`, `oracle.reanchor_step_deviation`, `oracle.escalation_trigger`, `oracle.trade_ref`, `oracle.oracle_price`, `oracle.mark_price` ### Order admission & matching Margin headroom gates, alignment and band checks, and the price-time matching loop that decides which orders enter the book and at what prices and quantities they fill. `margin-math.effective_initial_margin_rate`, `margin-math.initial_margin_required`, `margin-math.initial_margin_required_effective`, `margin-math.added_exposure`, `margin-math.admission_added_margin`, `margin-math.order_margin_headroom`, `margin-math.cross_admission_headroom`, `margin-math.max_position_size`, `order-book.lot_alignment`, `order-book.tick_alignment`, `order-book.price_band`, `order-book.mid_price`, `order-book.fok_availability`, `order-book.fill_quantity`, `order-book.fill_price`, `order-book.stp_decrement`, `order-book.slippage_span`, `order-book.running_vwap`, `order-book.vwap_estimate` ### Account health The position lifecycle (entry, PnL realization, flips) rolled up through equity, margin ratios, and the displayed liquidation/bankruptcy prices that describe how close an account is to the cascade. `margin-math.equity`, `margin-math.margin_ratio`, `margin-math.available_margin`, `margin-math.portfolio_equity`, `margin-math.portfolio_initial_margin`, `margin-math.portfolio_maintenance_margin`, `margin-math.maintenance_margin_required`, `margin-math.withdrawable_collateral`, `position-tracker.vwap_entry`, `position-tracker.unrealized_pnl`, `position-tracker.realized_pnl`, `position-tracker.closed_quantity`, `position-tracker.flip_size`, `position-tracker.liquidation_price`, `position-tracker.bankruptcy_price` ### Liquidation cascade From the equity-versus-maintenance trigger through collateral apportionment, bankruptcy-priced close orders, and fills-aware settlement into spread profit, bad debt, and ADL ranking. `liquidation-engine.fresh_unrealized_pnl`, `liquidation-engine.account_equity`, `liquidation-engine.maintenance_margin`, `liquidation-engine.liquidation_trigger`, `liquidation-engine.isolated_margin_fallback`, `liquidation-engine.cross_collateral_share`, `liquidation-engine.cross_remainder_fold`, `liquidation-engine.bankruptcy_price`, `liquidation-engine.aligned_price_sell`, `liquidation-engine.aligned_price_buy`, `liquidation-engine.safe_size`, `liquidation-engine.partial_liquidation_qty`, `liquidation-engine.reduce_only_guard`, `liquidation-engine.spread_profit`, `liquidation-engine.realized_fill_pnl`, `liquidation-engine.residual_unfilled_pnl`, `liquidation-engine.bad_debt`, `liquidation-engine.adl_priority_score` ### Loss absorption backstop The insurance fund's balance-capped debt absorption, its spread-profit and penalty income with lockstep lifetime ledgers, and the ADL threshold and settlement path when the fund runs dry. `insurance-fund.absorbed_amount`, `insurance-fund.post_liquidation_balance`, `insurance-fund.total_absorbed_update`, `insurance-fund.adl_settle_amount`, `insurance-fund.adl_trigger`, `insurance-fund.adl_priority_score`, `insurance-fund.spread_profit_balance`, `insurance-fund.total_received_update`, `insurance-fund.penalty_charged`, `insurance-fund.penalty_credit_balance`, `insurance-fund.penalty_received_update` ### Funding & settlement flows Periodic value transfers — the time-weighted funding rate settling as signed payments, and per-fill fees, rebates, and penalties accumulating into exchange revenue and fund income. `funding-rate.premium_index`, `funding-rate.sample_contribution`, `funding-rate.funding_rate`, `funding-rate.funding_payment`, `settlement.funding_transfer`, `settlement.fill_notional`, `settlement.taker_fee`, `settlement.maker_rebate`, `settlement.liquidation_penalty`, `settlement.net_exchange_revenue`, `settlement.merge_totals`, `position-tracker.taker_fee`, `position-tracker.maker_rebate` ## Relationships | From | Kind | To | How | | --------------------------------------------- | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `order-book.fill_price` | feeds | `oracle.trade_ref` | Executed fill prices populate the five-trade window whose volume-weighted median becomes the trade reference. | | `oracle.trade_ref` | feeds | `oracle.mark_price` | The volume-weighted trade median is the trade side of the convex mark-price blend. | | `oracle.trade_ref` | feeds | `funding-rate.premium_index` | The perp reference — not the mark — is the numerator deviation term measured against the oracle anchor in every premium sample. Routing the mark here would make the premium self-referential, since the mark already contains the anchor. | | `oracle.mark_price` | feeds | `position-tracker.unrealized_pnl` | Every mark update revalues each open position's unrealized PnL against its entry price. | | `oracle.mark_price` | feeds | `liquidation-engine.fresh_unrealized_pnl` | The liquidation engine recomputes per-position PnL from the fresh mark rather than trusting cached values. | | `oracle.mark_price` | feeds | `liquidation-engine.maintenance_margin` | Maintenance margin is notional at the fresh mark scaled by the maintenance rate. | | `oracle.mark_price` | feeds | `order-book.price_band` | The mark anchors the basis-point collar that admissible limit prices are measured against. | | `funding-rate.premium_index` | feeds | `funding-rate.sample_contribution` | Each sample's premium is time-weighted and added to the interval accumulator. | | `funding-rate.sample_contribution` | feeds | `funding-rate.funding_rate` | The accumulated time-weighted premium is the numerator of the clamped average funding rate. | | `funding-rate.funding_rate` | feeds | `funding-rate.funding_payment` | The settled rate scales each position's oracle-price notional (not the mark — see (F.4) and the `oracle.oracle_price` edge below) into a signed cash payment. | | `funding-rate.funding_payment` | feeds | `settlement.funding_transfer` | The signed funding payment is the amount routed through the funding pool, its sign selecting the transfer direction. | | `order-book.fill_price` | feeds | `position-tracker.vwap_entry` | Same-side fills fold their price into the size-weighted average entry price. | | `position-tracker.unrealized_pnl` | feeds | `margin-math.equity` | Total unrealized PnL over open positions is the mark-to-market component of account equity. | | `margin-math.equity` | feeds | `margin-math.margin_ratio` | Equity is the numerator of the margin ratio over total notional. | | `margin-math.equity` | feeds | `margin-math.available_margin` | Available margin is equity less the initial margin already held against open positions. | | `margin-math.available_margin` | feeds | `margin-math.order_margin_headroom` | Isolated-path admission headroom is available margin minus the order's effective-rate requirement. | | `margin-math.order_margin_headroom` | bounds | `order-book.fill_quantity` | An order reaches the matching loop only if its margin headroom is non-negative, constraining which quantities can ever fill. | | `liquidation-engine.fresh_unrealized_pnl` | feeds | `liquidation-engine.account_equity` | Fresh per-position PnL sums with collateral into the equity the trigger evaluates. | | `liquidation-engine.account_equity` | feeds | `liquidation-engine.liquidation_trigger` | Equity is the left side of the inclusive trigger comparison. | | `liquidation-engine.maintenance_margin` | bounds | `liquidation-engine.liquidation_trigger` | Total maintenance margin is the inclusive floor below which equity fires the liquidation. | | `liquidation-engine.liquidation_trigger` | triggers | `liquidation-engine.cross_collateral_share` | Only a fired trigger causes the shared cross pool to be split loss-proportionally across liquidating markets. | | `liquidation-engine.cross_collateral_share` | feeds | `liquidation-engine.bankruptcy_price` | Each market's final collateral share (after the remainder fold) is the C displacing entry price into that position's bankruptcy price. | | `position-tracker.vwap_entry` | feeds | `liquidation-engine.bankruptcy_price` | The volume-weighted entry price is the anchor from which the collateral share per unit displaces the bankruptcy price. | | `liquidation-engine.bankruptcy_price` | feeds | `liquidation-engine.spread_profit` | The tick-aligned bankruptcy price is the reference each fill's price improvement is measured against. | | `order-book.fill_price` | feeds | `liquidation-engine.realized_fill_pnl` | Liquidation close orders settle each fill's PnL at the maker price the book actually printed. | | `liquidation-engine.realized_fill_pnl` | feeds | `liquidation-engine.bad_debt` | Fills-aware realized PnL enters the post-liquidation equity whose negative part is bad debt. | | `liquidation-engine.spread_profit` | feeds | `liquidation-engine.bad_debt` | Spread profit is subtracted from retained collateral in the shortfall computation. | | `liquidation-engine.spread_profit` | feeds | `insurance-fund.spread_profit_balance` | Positive liquidation spread profit is credited to the insurance fund balance before absorption is evaluated. | | `liquidation-engine.bad_debt` | feeds | `insurance-fund.absorbed_amount` | The liquidation's non-negative shortfall is the debt the fund attempts to absorb, capped by its balance. | | `insurance-fund.absorbed_amount` | feeds | `insurance-fund.post_liquidation_balance` | The new fund balance is the old balance less the absorbed amount, floored at zero. | | `insurance-fund.post_liquidation_balance` | feeds | `insurance-fund.adl_trigger` | The post-absorption balance is what the inclusive per-market ADL threshold predicate evaluates. | | `liquidation-engine.bad_debt` | feeds | `insurance-fund.adl_settle_amount` | Bad debt exceeding the fund balance emits an ADL instruction for exactly the excess. | | `order-book.fill_price` | feeds | `settlement.fill_notional` | Every fill's maker price times quantity is the notional on which all settlement fees and penalties are computed. | | `settlement.fill_notional` | feeds | `settlement.liquidation_penalty` | The liquidation penalty is the fill notional scaled by the penalty rate on liquidation fills only. | | `settlement.liquidation_penalty` | feeds | `insurance-fund.penalty_charged` | The settlement-computed penalty is the owed amount the fund charges, capped at the liquidatee's available collateral. | | `funding-rate.funding_payment` | feeds | `margin-math.equity` | Funding settles atomically into the collateral balance C (settle-and-reset), the first term of equity; the accrual integral is identically zero at every observable state, so the live channel is C, not the phi term. | | `order-book.fill_quantity` | feeds | `position-tracker.closed_quantity` | The matched fill quantity is the amount tested against existing position size to determine closed quantity. | | `margin-math.initial_margin_required` | feeds | `margin-math.available_margin` | Per-position initial margin (or stamped allocated margin) is the hold subtracted from equity. | | `liquidation-engine.cross_collateral_share` | feeds | `liquidation-engine.cross_remainder_fold` | The pure proportional shares are corrected by folding the rounding remainder into the largest-loss share. | | `liquidation-engine.cross_remainder_fold` | feeds | `liquidation-engine.bankruptcy_price` | Each market's folded collateral share is the C that sets its bankruptcy price. | | `liquidation-engine.liquidation_trigger` | triggers | `liquidation-engine.partial_liquidation_qty` | Close-order sizing runs only for accounts the trigger selected. | | `insurance-fund.adl_settle_amount` | triggers | `insurance-fund.adl_priority_score` | A strictly positive unabsorbed amount emits an ADL instruction whose counterparties are ranked by descending score. | | `liquidation-engine.partial_liquidation_qty` | feeds | `order-book.fill_quantity` | The cascade's close orders execute through the book: liquidation sizing becomes matched fill quantity, closing the loop by which liquidation fills re-enter the trade window and hence the mark. | | `order-book.fill_price` | feeds | `liquidation-engine.spread_profit` | P\*\_j in the spread-profit sum is the book's executed fill price; the bankruptcy price only bounds it. | | `position-tracker.realized_pnl` | feeds | `margin-math.equity` | Realized PnL settles into collateral C on the fill (C' = C + sigma(P\* - P\_e)q\_c), the first term of equity — the realized channel alongside the unrealized one. | | `settlement.taker_fee` | feeds | `margin-math.equity` | Taker fees debit the collateral balance C at fill time — the same collateral channel into equity as realized PnL. | | `settlement.maker_rebate` | feeds | `margin-math.equity` | Maker rebates credit the collateral balance C at fill time — the same collateral channel into equity as realized PnL. | | `oracle.mark_price` | feeds | `margin-math.portfolio_maintenance_margin` | Portfolio maintenance margin is valued at the mark (sum q\_i \* m\_i \* r\_mm); wires the margin-math cluster to price formation. | | `oracle.mark_price` | feeds | `margin-math.portfolio_initial_margin` | Portfolio initial margin is valued at the mark (sum q\_i \* m\_i \* r\_im). | | `oracle.mark_price` | feeds | `liquidation-engine.safe_size` | Close-order sizing consumes the mark directly (C / (1.5 \* m \* r\_i)) — the mark's third entry point into the cascade. | | `oracle.mark_price` | feeds | `liquidation-engine.residual_unfilled_pnl` | The unfilled remainder is valued at the mark on its way into bad\_debt — the shortfall computation's mark dependency. | | `settlement.liquidation_penalty` | feeds | `margin-math.equity` | The cascade debits the penalty from the account's residual collateral (C\_a' = ... - sum Lambda\_i) — the account-side leg of the penalty transfer. The fund-side leg is penalty\_charged -> penalty\_credit\_balance. | | `insurance-fund.adl_trigger` | triggers | `insurance-fund.adl_priority_score` | The threshold arm-path 1\[Phi' <= kappa]. Settle-amount firing implies threshold firing (D\_adl > 0 forces Phi' = 0 <= kappa); the divergence is one-sided — the threshold can fire with D\_adl = 0 (open finding: adl\_arming\_is\_nested\_not\_ambiguous). | | `oracle.oracle_price` | feeds | `funding-rate.funding_payment` | The payment sigma*S*P\_oracle\*f is struck at the oracle price, not the mark, so both sides of a matched pair are valued on the anchor neither side's own trading can move. | | `liquidation-engine.safe_size` | feeds | `liquidation-engine.partial_liquidation_qty` | partial\_liquidation\_qty embeds q\_safe verbatim (size - q\_safe; full mode when q\_safe >= size) — the sizing sub-chain. | | `liquidation-engine.isolated_margin_fallback` | feeds | `liquidation-engine.bankruptcy_price` | For isolated positions the stamped cushion (or q*P\_e*r\_i fallback) is the C in p\_b = P\_e - d\*C/q — the isolated collateral path into bankruptcy pricing. | | `liquidation-engine.residual_unfilled_pnl` | feeds | `liquidation-engine.bad_debt` | bad\_debt consumes the residual unfilled PnL leg directly — the second PnL leg of the shortfall computation. | | `position-tracker.unrealized_pnl` | feeds | `insurance-fund.adl_priority_score` | pnl\_percent in the ADL ranking derives from position unrealized PnL — the ranking's inbound dependency on the position layer. | | `oracle.is_stale` | triggers | `oracle.reanchor_step_deviation` | The re-anchor protocol runs only off a stale anchor; is\_stale routes prints into candidate confirmation — the control edge between the oracle's two regimes. | | `order-book.mid_price` | feeds | `order-book.slippage_span` | slippage\_span = mid\_price \* beta / 10^4 — the slippage band is priced off the mid. | | `order-book.slippage_span` | bounds | `order-book.running_vwap` | The running VWAP of a market-order walk is bounded by the slippage band around the mid. | | `order-book.fill_quantity` | feeds | `position-tracker.vwap_entry` | fill\_quantity is the blend weight of the VWAP entry update (q*Pe + q\_f*P\*)/(q + q\_f) — the quantity leg alongside the price leg. | | `order-book.fill_price` | feeds | `position-tracker.realized_pnl` | Realized PnL is valued at the executed fill price P\*. | | `position-tracker.closed_quantity` | feeds | `position-tracker.realized_pnl` | closed\_qty = min(q, q\_f) is a declared input of realized PnL — the reduce-path quantity. | | `oracle.mark_price` | feeds | `margin-math.margin_ratio` | margin\_ratio's denominator total\_notional = sum q\_i \* m\_i is valued at the mark. | | `liquidation-engine.bankruptcy_price` | feeds | `liquidation-engine.aligned_price_sell` | Close orders are tick-aligned toward executability from the bankruptcy-derived close price (sell side). | | `liquidation-engine.bankruptcy_price` | feeds | `liquidation-engine.aligned_price_buy` | Close orders are tick-aligned toward executability from the bankruptcy-derived close price (buy side). | | `order-book.fill_quantity` | feeds | `liquidation-engine.spread_profit` | The per-fill spread-profit sum consumes fill quantities from the book's matching output. | | `order-book.fill_quantity` | feeds | `liquidation-engine.realized_fill_pnl` | Realized fill PnL consumes fill quantities from the matching output. | | `order-book.fill_quantity` | feeds | `liquidation-engine.residual_unfilled_pnl` | The residual leg consumes total filled quantity to size the unfilled remainder. | | `position-tracker.vwap_entry` | feeds | `position-tracker.unrealized_pnl` | entry\_price is maintained by the VWAP entry update and read by unrealized PnL — the fills -> entry -> PnL chain. | | `position-tracker.vwap_entry` | feeds | `liquidation-engine.fresh_unrealized_pnl` | The liquidation engine recomputes PnL from the entry price that only vwap\_entry maintains. | | `insurance-fund.spread_profit_balance` | feeds | `insurance-fund.absorbed_amount` | Absorption evaluates against the post-credit balance Phi\_1 = Phi + g (credit-before-absorb, code-verified 2026-07-12). | | `insurance-fund.penalty_charged` | feeds | `insurance-fund.penalty_credit_balance` | Lambda is the penalty input of the fund-side credit — the no-mint pair's fund leg. | | `margin-math.equity` | feeds | `margin-math.cross_admission_headroom` | Equity is the first input of the cross admission check E - (M\_used + M\_resv + M\_add). | | `margin-math.admission_added_margin` | feeds | `margin-math.cross_admission_headroom` | Exposure netting enters admission here: added initial margin is a declared input of the cross headroom check. | | `margin-math.added_exposure` | feeds | `margin-math.admission_added_margin` | Netted added exposure feeds the added-margin computation on the cross path (the isolated path charges gross size — open finding isolated\_headroom\_charges\_gross\_size). | | `order-book.fill_quantity` | feeds | `settlement.fill_notional` | fill\_notional = q \* P — the quantity leg alongside the price leg. | | `settlement.fill_notional` | feeds | `settlement.taker_fee` | Fees are notional \* bps; wires the exchange-revenue chain to the fill. | | `liquidation-engine.partial_liquidation_qty` | feeds | `liquidation-engine.reduce_only_guard` | The computed close quantity is the guard's tested input — the negative-share stall path (finding liquidation\_close\_order\_exceeds\_position\_size). | | `insurance-fund.penalty_credit_balance` | feeds | `insurance-fund.absorbed_amount` | Absorption evaluates against the post-credit balance Phi\_1 = Phi + Lambda + g — the penalty leg of credit-before-absorb (code-verified 2026-07-12, per\_market.rs:552-574). | | `position-tracker.vwap_entry` | feeds | `position-tracker.liquidation_price` | The displayed liquidation price consumes the entry price that only vwap\_entry maintains. | | `position-tracker.vwap_entry` | feeds | `position-tracker.bankruptcy_price` | The display twin of the engine's bankruptcy price likewise consumes the VWAP-maintained entry price. | | `oracle.single_step_deviation` | bounds | `oracle.mark_price` | The accept guard bounds anchor-leg motion of the mark to theta per tick — the channel the bounded-equity-shock invariant composes. | | `liquidation-engine.aligned_price_sell` | bounds | `order-book.fill_price` | The tick-aligned close price is the cascade order's limit — it bounds which maker prices liquidation fills can print at (sell side). | | `liquidation-engine.aligned_price_buy` | bounds | `order-book.fill_price` | Buy-side twin: the aligned close price bounds liquidation fill prices, closing the cascade's pricing loop through the book. | ## References * Derived from and adversarially verified against the Exchange's Rust implementation and its test suite. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/math-engine/system.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.