Skip to content

Commit 22eedf9

Browse files
committed
Stage 10a — liquidation margin math (pure compute)
First sub-stage of the liquidation engine. Pure compute: no I/O, no state, no async. Same shape as `openhl-funding` Stage 8b — a deterministic function bank over snapshots, with i64 + saturating arithmetic so validators reach the same MarginHealth on the same inputs. What's in: - `LiquidationParams { initial_margin_bps, maintenance_margin_bps, liquidation_fee_bps }` + `hyperliquid_default()` (10% / 2% / 1.5%) - `AccountSnapshot { account, position_size, avg_entry, collateral }` - `MarginRatio` newtype scaled by `MARGIN_SCALE = 10_000` (bps) - `MarginHealth` enum: `Safe`, `AtRisk`, `Liquidatable`, `Underwater` - `CloseOrderSpec { account, side, qty }` — bridge encodes this as `clob::Action::SubmitMarket` - Six pure compute functions: notional_value, unrealized_pnl, account_equity, margin_ratio, margin_health, close_order_spec - 21 unit tests + 3 proptests (long monotonicity in the levered regime, short monotonicity, ratio determinism) What's out (deferred to next sub-stages): - Stage 10b — insurance fund state machine, deficit absorption, fee credit - Stage 10c — multi-account scanner, CLOB integration, position registry hook - Auto-deleveraging (Stage 10d, optional) Two design notes worth pinning: 1. `AccountSnapshot` carries `avg_entry` and `collateral` that the funding `Position` doesn't — liquidation needs unrealized PnL, funding doesn't. Bridge layer assembles the snapshot per account per tick. The two crates stay independent. 2. Long ratio monotonicity holds only when `entry × size > collateral` (the levered regime). When collateral dominates notional, the `collateral / notional` term inverts the relationship — but that case is uninteresting for liquidation (the account can never be liquidated), so the proptest excludes it via `prop_assume!`.
1 parent 0cac571 commit 22eedf9

5 files changed

Lines changed: 616 additions & 0 deletions

File tree

Cargo.lock

Lines changed: 5 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

crates/liquidation/Cargo.toml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@ repository = { workspace = true }
88
authors = { workspace = true }
99

1010
[dependencies]
11+
openhl-clob = { path = "../clob" }
12+
openhl-funding = { path = "../funding" }
13+
14+
[dev-dependencies]
15+
proptest = { workspace = true }
1116

1217
[lints]
1318
workspace = true

0 commit comments

Comments
 (0)