MarginRiskMetrics
Margin and liquidation-risk state of one account, produced by calculateMarginRisk.
All amounts are 18-decimal wei bigint and may be negative where the arithmetic allows it. Every figure describes a single liquidation domain — see the overview for why they must never be summed across accounts.
Properties
totalMarginbigintrequiredThe collateral allocated to the account — allocatedBalance, unchanged.
maintenanceMarginbigintrequiredlockedCVA + lockedLF — the level equity liquidates at.
initialMarginbigintrequiredlockedPartyAMM + maintenanceMargin — every leg partyA has locked, matching the contract’s
LockedValuesOps.totalForPartyA(). These are live locked values, so the figure shrinks on a partial close.
equitybigintrequiredtotalMargin + upnl — the account’s mark-to-market value.
remainingToLiquidationbigintrequiredequity − maintenanceMargin — the cushion left before liquidation. Negative means already liquidatable.
liquidationBufferPercentbigint | undefinedremainingToLiquidation / (totalMargin − maintenanceMargin) × 100 as an 18-decimal fixed-point percent: how much
of the zero-uPnL cushion is still intact. Exceeds 100% in profit, goes negative once liquidatable, and is not
clamped. undefined when the zero-uPnL cushion is not positive.
isLiquidatablebooleanrequiredremainingToLiquidation < 0n — bit-for-bit the on-chain predicate
allocatedBalance − (cva + lf) + upnl < 0 from LibAccount.partyAAvailableBalanceForLiquidation (perps-core
v0.8.6). The boundary is strict: equity exactly equal to the maintenance margin is still solvent.
Why liquidationBufferPercent is optional
It is a ratio, and its denominator — the cushion the account would have at zero unrealized PnL — can be zero or negative. When it is, the ratio does not exist, and the SDK says so rather than substituting 0:
if (metrics.liquidationBufferPercent === undefined) {
/**
* `allocatedBalance ≤ maintenanceMargin`. The account may still be perfectly
* solvent on unrealized profit — read `isLiquidatable`, not the percent.
*/
return <BufferUnavailable liquidatable={metrics.isLiquidatable} />;
}Reporting 0% here would paint a profitable account as maximum risk. The same reasoning drives the other optional figures across the SDK (QuoteGroupMetrics.leverage, weightedOpenPrice): an indeterminate value is undefined, never a zero standing in for one.
Rendering the buffer
The percent is unclamped on purpose. Clamp the bar, not the number:
const width = Math.min(Math.max(Number(buffer / 10n ** 16n) / 100, 0), 100);Colour on isLiquidatable first, and only then on a threshold — a low percent is a warning, but the flag is the fact.
Related
calculateMarginRisk— the fold that produces this.QuoteGroupUpnl— where theupnlinput comes from for a grouped position.