@somnia-chain/markets-sdk / index / LiquidationEvent
Type Alias: LiquidationEvent
LiquidationEvent =
object
Defined in: packages/sdk/src/perp/history.ts:66
A liquidation event (mirror of the indexer LiquidationEvent entity). All
numeric fields are raw units; any may be null when the source event didn't
carry it.
Properties
id
id:
string
Defined in: packages/sdk/src/perp/history.ts:68
Event id (${txHash}_${logIndex}).
account
account:
string
Defined in: packages/sdk/src/perp/history.ts:70
Liquidated account (lowercased).
pool
pool:
string|null
Defined in: packages/sdk/src/perp/history.ts:72
Perp pool (lowercased); null on account-scoped rows.
kind
kind:
string
Defined in: packages/sdk/src/perp/history.ts:93
WHICH stage of the liquidation/deleveraging waterfall this row is. Read this first — the rows are stages of one mechanism, not repetitions of one event, and without it an ADL leg is indistinguishable from a liquidation:
AccountLiquidated account-level summary (positionsProcessed, stageReached) PositionLiquidated per-position liquidation (size, price) PositionSkipped below min quantity, left in place (size) PositionTakenOver stage-4 backstop takeover (counterparty = bidder, price) AutoDeleveraged ADL leg (counterparty absorbed it; price = bankruptcy price) PositionTransferred stage-4 transfer (counterparty, size) CloseOutMarginSettled stage-4 close-out margin flow (counterparty) BadDebtAbsorbed the fund PAID (insuranceCovered, deficit, counterparty = fund) ResidualBadDebt uncovered, INSOLVENT hole after the waterfall (badDebt) AdlPriceCapacityExhausted terminal: hole exceeds aggregate position capacity (badDebt) ResidualBackedByOpenPnl hole fully backed by the account's OWN open PnL (deficit, equity) CoverageDeclined coverage the equity cap DEFERRED (coverageDeclined) AdlSessionDiscarded ADL session abandoned; amount is on the same-tx BadDebtAbsorbed row AdlCapacityShortfall ADL could not source enough capacity (size)
size
size:
string|null
Defined in: packages/sdk/src/perp/history.ts:100
Signed size for the leg, where the event carries one (raw base units).
Signed, not absolute: PositionLiquidated emits a signed sizeDelta, and the sign
is the side being closed.
price
price:
string|null
Defined in: packages/sdk/src/perp/history.ts:105
Price for the leg (raw quote per whole base) — mark price, takeover price, or ADL
bankruptcy price depending on kind.
counterparty
counterparty:
string|null
Defined in: packages/sdk/src/perp/history.ts:111
The other side of the leg: the ADL counterparty who absorbed it, the takeover
bidder, the transfer/close-out peer, or — on BadDebtAbsorbed — the Insurance Fund
that covered the debt. Null on rows with no counterparty.
penalty
penalty:
string|null
Defined in: packages/sdk/src/perp/history.ts:113
Penalty charged (raw collateral; reserved — not carried by current events).
badDebt
badDebt:
string|null
Defined in: packages/sdk/src/perp/history.ts:134
The LEVEL of the account's uncovered, genuinely insolvent realized hole after this
liquidate() call — ResidualBadDebt, or AdlPriceCapacityExhausted for the
terminal price-capacity case (raw collateral).
A level, not a flow — never SUM this across rows. The underlying residual is a
post-call state sample, so a later call on the same account re-reports the same
(possibly changed) hole, and a stage-5 residual can co-fire with a terminal ADL one
in a single call: two samples of one hole at two stages.
Sound aggregates: the latest row per account is that account's currently known uncovered hole (an upper bound — a deposit can repay it with no row here, see MarginEvent), and the sum of those latest rows across accounts is point-in-time system bad debt.
Deliberately narrow: what the fund actually paid is LiquidationEvent.insuranceCovered,
a gross pre-coverage hole is LiquidationEvent.deficit, and a deferred coverage
decision is LiquidationEvent.coverageDeclined. Collateral that merely MOVED
between accounts is in collateralAmount.
insuranceCovered
insuranceCovered:
string|null
Defined in: packages/sdk/src/perp/history.ts:148
Wei the Insurance Fund ACTUALLY moved — BadDebtAbsorbed only (raw collateral).
A flow, and the only summable amount here: rows are disjoint payments, so a SUM
over any slice is exact fund outflow. A insuranceCovered below the same row's
deficit does NOT mean the fund was underfunded — part of a hole is unattributable
(a pre-existing balance, or funding owed), and that remainder surfaces as a
ResidualBadDebt row instead.
AdlSessionDiscarded deliberately leaves this null: its absorption is the same
absorbBadDebt call that emits BadDebtAbsorbed in the same transaction, so
counting both would double the outflow. Join on txHash.
deficit
deficit:
string|null
Defined in: packages/sdk/src/perp/history.ts:161
The GROSS realized hole a stage reported, before coverage (raw collateral) —
BadDebtAbsorbed (the full negative balance) and ResidualBackedByOpenPnl (a hole
the account's own open profit fully backs, so it is NOT bad debt; read equity
alongside it, and note it becomes bad debt if the position reverses).
A level, and overlapping per-stage views of one hole — never SUM, and never add to
badDebt. When BadDebtAbsorbed and ResidualBadDebt both fire in one call the
balance moved only by what the fund paid, so badDebt == deficit - insuranceCovered
for that call: a useful cross-row audit check, and the direct proof that summing the
gross figure with the residual double-counts.
coverageDeclined
coverageDeclined:
string|null
Defined in: packages/sdk/src/perp/history.ts:172
Attributable coverage the stage-5 equity cap did NOT pay — CoverageDeclined only
(raw collateral).
A flow and summable as "total coverage deferred", but NOT a loss: the fund underwrites insolvency and the account was not insolvent by that much at that moment. If the backing later evaporates the hole returns as a pre-existing negative balance, which is unattributable by definition, so it is written off rather than re-declined (accepted policy, OQ-13).
collateralAmount
collateralAmount:
string|null
Defined in: packages/sdk/src/perp/history.ts:178
Collateral that MOVED rather than was lost — PositionTransferred (collateral
following the position) and CloseOutMarginSettled. Kept separate from badDebt so
neither aggregate contaminates the other.
equity
equity:
string|null
Defined in: packages/sdk/src/perp/history.ts:180
Account equity where the event reports it (ResidualBackedByOpenPnl; signed).
positionsProcessed
positionsProcessed:
string|null
Defined in: packages/sdk/src/perp/history.ts:182
Positions processed (AccountLiquidated only).
stageReached
stageReached:
number|null
Defined in: packages/sdk/src/perp/history.ts:184
Highest waterfall stage reached (AccountLiquidated only).
marginStatusBefore
marginStatusBefore:
number|null
Defined in: packages/sdk/src/perp/history.ts:186
Margin status before / after (AccountLiquidated only).
marginStatusAfter
marginStatusAfter:
number|null
Defined in: packages/sdk/src/perp/history.ts:187
timestamp
timestamp:
string
Defined in: packages/sdk/src/perp/history.ts:189
Timestamp (unix seconds) of the row.
blockNumber
blockNumber:
string
Defined in: packages/sdk/src/perp/history.ts:190
txHash
txHash:
string
Defined in: packages/sdk/src/perp/history.ts:192
Tx hash the row landed in. Stages of one liquidation share it.