Commit 22eedf9
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
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
11 | 16 | | |
12 | 17 | | |
13 | 18 | | |
0 commit comments