@reyaxyz/account-figures 0.0.0-stage → 0.2.0

package/dist/engine.js

@@ -0,0 +1,318 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyFill = exports.admit = exports.project = exports.projectD = exports.roundingAllowance = exports.marginText = exports.riskText = exports.parseMargin = exports.parseRisk = exports.SETTLEMENT_RESERVE = exports.INITIAL_MARGIN = exports.LIQUIDATION_THRESHOLD = exports.SETTLEMENT_RESERVE_RATE = void 0;
+/**
+ * The matching engine's margin projection and admission verdict, ported from
+ * the Agent Kit's `agent_kit/scripts/_margin.py` (kit 0.12.20), which ports the
+ * engine's risk engine (`matching-engine/src/base/risk_engine`, revision
+ * 4d8ed012): `compute.rs` (`project_account_with_lots`, `finish_projection`)
+ * and `checks/taker_margin.rs` (`admit_taker`).
+ *
+ * All amounts are rUSD. Like the engine, cash is floored and requirements are
+ * rounded up to rUSD's 6 decimals per component, and E18 steps are reproduced
+ * where it rounds. Every amount in and out is a decimal string.
+ *
+ * The account figures use `project` only for the liquidation and initial
+ * margin, which depend on positions alone. For the engine's admission verdict
+ * (`admit`), the balances must be credited by the engine's own collateral
+ * rules, which give some collateral no credit: `buildMarginSnapshot` values
+ * collateral as Core does, not as the engine admits it.
+ */
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const decimal_1 = require("./decimal");
+const errors_1 = require("./errors");
+/**
+ * The engine's V1 policy constant (`[risk] reserve_rate`), applied once to the
+ * notional of the order and of the account's matched-but-unsettled fills. V2
+ * does not publish it.
+ */
+exports.SETTLEMENT_RESERVE_RATE = '0.01';
+exports.LIQUIDATION_THRESHOLD = 'below_liquidation_threshold';
+exports.INITIAL_MARGIN = 'below_initial_margin';
+exports.SETTLEMENT_RESERVE = 'below_settlement_reserve';
+function parseRisk(market, risk) {
+    return {
+        base: (0, decimal_1.parseDecimal)(risk.base, `${market} base`),
+        mark: (0, decimal_1.parseDecimal)(risk.mark, `${market} mark price`),
+        marginRate: (0, decimal_1.parseDecimal)(risk.marginRate, `${market} margin rate`),
+        entry: (0, decimal_1.parseDecimal)(risk.entry, `${market} entry price`),
+    };
+}
+exports.parseRisk = parseRisk;
+function parseMargin(margin) {
+    const markets = new Map();
+    for (const [market, risk] of Object.entries(margin.markets)) {
+        markets.set(market, parseRisk(market, risk));
+    }
+    return {
+        realBalance: (0, decimal_1.parseDecimal)(margin.realBalance, 'real balance'),
+        marginBalance: (0, decimal_1.parseDecimal)(margin.marginBalance, 'margin balance'),
+        markets,
+    };
+}
+exports.parseMargin = parseMargin;
+function riskText(risk) {
+    return {
+        base: (0, decimal_1.toText)(risk.base),
+        mark: (0, decimal_1.toText)(risk.mark),
+        marginRate: (0, decimal_1.toText)(risk.marginRate),
+        entry: (0, decimal_1.toText)(risk.entry),
+    };
+}
+exports.riskText = riskText;
+function marginText(margin) {
+    const markets = {};
+    for (const [market, risk] of margin.markets) {
+        markets[market] = riskText(risk);
+    }
+    return {
+        realBalance: (0, decimal_1.toText)(margin.realBalance),
+        marginBalance: (0, decimal_1.toText)(margin.marginBalance),
+        markets,
+    };
+}
+exports.marginText = marginText;
+function parseLot(lot) {
+    return {
+        market: lot.market,
+        qty: (0, decimal_1.parseDecimal)(lot.qty, `${lot.market} lot qty`),
+        price: (0, decimal_1.parseDecimal)(lot.price, `${lot.market} lot price`),
+    };
+}
+function parseProjection(p) {
+    return {
+        mbFloor: (0, decimal_1.parseDecimal)(p.mbFloor, 'mbFloor'),
+        rbFloor: (0, decimal_1.parseDecimal)(p.rbFloor, 'rbFloor'),
+        lm: (0, decimal_1.parseDecimal)(p.lm, 'lm'),
+        im: (0, decimal_1.parseDecimal)(p.im, 'im'),
+        reserve: (0, decimal_1.parseDecimal)(p.reserve, 'reserve'),
+        h: (0, decimal_1.parseDecimal)(p.h, 'h'),
+        c: (0, decimal_1.parseDecimal)(p.c, 'c'),
+    };
+}
+function projectionText(p) {
+    return {
+        mbFloor: (0, decimal_1.toText)(p.mbFloor),
+        rbFloor: (0, decimal_1.toText)(p.rbFloor),
+        lm: (0, decimal_1.toText)(p.lm),
+        im: (0, decimal_1.toText)(p.im),
+        reserve: (0, decimal_1.toText)(p.reserve),
+        h: (0, decimal_1.toText)(p.h),
+        c: (0, decimal_1.toText)(p.c),
+    };
+}
+// --------------------------------------------------------------------------
+// Projection
+// --------------------------------------------------------------------------
+class Fold {
+    constructor(buys = decimal_1.ZERO, 
+    /** Summed signed, so never positive. */
+    sells = decimal_1.ZERO, instantLoss = decimal_1.ZERO, reserveNotional = decimal_1.ZERO, transitions = 0) {
+        this.buys = buys;
+        this.sells = sells;
+        this.instantLoss = instantLoss;
+        this.reserveNotional = reserveNotional;
+        this.transitions = transitions;
+    }
+    add(lot, mark, unit) {
+        if (lot.qty.gt(0)) {
+            this.buys = this.buys.plus(lot.qty);
+        }
+        else {
+            this.sells = this.sells.plus(lot.qty);
+        }
+        // A fill priced worse than the mark loses at once; a better one is never credited.
+        this.instantLoss = this.instantLoss.plus((0, decimal_1.floorTo)((0, decimal_1.minOf)((0, decimal_1.floorTo)(lot.qty.times(mark.minus(lot.price))), decimal_1.ZERO), unit));
+        this.reserveNotional = this.reserveNotional.plus((0, decimal_1.floorTo)(lot.qty.abs().times(lot.price)));
+        if (!lot.qty.isZero()) {
+            this.transitions += 1;
+        }
+    }
+    merged(other) {
+        return new Fold(this.buys.plus(other.buys), this.sells.plus(other.sells), this.instantLoss.plus(other.instantLoss), this.reserveNotional.plus(other.reserveNotional), this.transitions + other.transitions);
+    }
+}
+function roundingAllowanceD(worstBase, transitions, decimals) {
+    if (transitions === 0) {
+        return decimal_1.ZERO;
+    }
+    const drift = worstBase.integerValue(bignumber_js_1.default.ROUND_CEIL).plus(2).times(decimal_1.E18);
+    return (0, decimal_1.ceilTo)(drift, (0, decimal_1.nativeUnit)(decimals)).times(transitions);
+}
+/**
+ * Core's average-entry and PnL truncation bound: one native unit per
+ * transition for any realistic size.
+ */
+function roundingAllowance(worstBase, transitions, decimals = decimal_1.RUSD_DECIMALS) {
+    return (0, decimal_1.toText)(roundingAllowanceD((0, decimal_1.parseDecimal)(worstBase, 'worst base'), transitions, decimals));
+}
+exports.roundingAllowance = roundingAllowance;
+function projectD(margin, imMultiplier, candidates = [], inFlight = [], reserveRate = new decimal_1.Dec(exports.SETTLEMENT_RESERVE_RATE), decimals = decimal_1.RUSD_DECIMALS) {
+    const unit = (0, decimal_1.nativeUnit)(decimals);
+    let mbFloor = margin.marginBalance;
+    let rbFloor = margin.realBalance;
+    let lm = decimal_1.ZERO;
+    let reserveNotional = decimal_1.ZERO;
+    const names = [
+        ...new Set([
+            ...margin.markets.keys(),
+            ...inFlight.map((lot) => lot.market),
+            ...candidates.map((lot) => lot.market),
+        ]),
+    ].sort();
+    for (const market of names) {
+        const risk = margin.markets.get(market);
+        if (risk === undefined) {
+            throw new errors_1.AccountFiguresInputError(`No mark or margin rate for ${market}`);
+        }
+        const optional = new Fold();
+        const candidate = new Fold();
+        for (const lot of inFlight) {
+            if (lot.market === market) {
+                optional.add(lot, risk.mark, unit);
+            }
+        }
+        let candidateQty = decimal_1.ZERO;
+        for (const lot of candidates) {
+            if (lot.market === market) {
+                candidate.add(lot, risk.mark, unit);
+                candidateQty = candidateQty.plus(lot.qty);
+            }
+        }
+        const possible = optional.merged(candidate);
+        const settled = risk.base;
+        const worst = (0, decimal_1.maxOf)(settled.abs(), settled.plus(possible.buys).abs(), settled.plus(possible.sells).abs());
+        const delta = possible.instantLoss.minus(roundingAllowanceD(worst, (settled.isZero() ? 0 : 1) + possible.transitions, decimals));
+        mbFloor = mbFloor.plus(delta);
+        rbFloor = rbFloor.plus(delta);
+        // Exposure is the worst settle/bust corner of the unsettled lots, shifted by the candidate.
+        const shifted = settled.plus(candidateQty);
+        const exposureBase = (0, decimal_1.maxOf)(shifted.abs(), shifted.plus(optional.buys).abs(), shifted.plus(optional.sells).abs());
+        lm = lm.plus((0, decimal_1.ceilTo)((0, decimal_1.ceilTo)(risk.marginRate.times((0, decimal_1.ceilTo)(exposureBase.times(risk.mark)))), unit));
+        if (!settled.isZero()) {
+            // Closing part of the position realizes its loss at mark into the real balance.
+            const opposite = settled.gt(0) ? possible.sells.negated() : possible.buys;
+            const closable = (0, decimal_1.minOf)(settled.abs(), opposite);
+            const signed = settled.gt(0) ? closable : closable.negated();
+            rbFloor = rbFloor.plus((0, decimal_1.floorTo)((0, decimal_1.minOf)((0, decimal_1.floorTo)(signed.times(risk.mark.minus(risk.entry))), decimal_1.ZERO), unit));
+        }
+        reserveNotional = reserveNotional.plus(possible.reserveNotional);
+    }
+    const im = (0, decimal_1.ceilTo)((0, decimal_1.ceilTo)(imMultiplier.times(lm)), unit);
+    const reserve = (0, decimal_1.ceilTo)(reserveRate.times(reserveNotional), unit);
+    const h = (0, decimal_1.minOf)(mbFloor.minus(lm), rbFloor);
+    return { mbFloor, rbFloor, lm, im, reserve, h, c: h.minus(reserve) };
+}
+exports.projectD = projectD;
+/**
+ * The engine's `project_account_with_lots`: settled state plus unsettled lots
+ * plus candidates. With no lots it is the settled account, whose `lm` and `im`
+ * are the account's LMR and IMR.
+ */
+function project(margin, candidates, options) {
+    return projectionText(projectD(parseMargin(margin), (0, decimal_1.parseDecimal)(options.imMultiplier, 'IM multiplier'), candidates.map(parseLot), (options.inFlight ?? []).map(parseLot), (0, decimal_1.parseDecimal)(options.reserveRate ?? exports.SETTLEMENT_RESERVE_RATE, 'reserve rate'), options.decimals ?? decimal_1.RUSD_DECIMALS));
+}
+exports.project = project;
+// --------------------------------------------------------------------------
+// Verdict
+// --------------------------------------------------------------------------
+function shortfallText(delta) {
+    return (0, decimal_1.toText)(delta.abs());
+}
+/**
+ * The engine's `admit_taker`: the liquidation-threshold precondition for every
+ * request, then initial margin before and after and the settlement reserve
+ * after, for an ordinary one only. `strictReduceOnly` is the reduce-only flag
+ * or a TP/SL; an order that merely opposes the position is ordinary. The
+ * messages are the engine's own.
+ */
+function admit(before, after, strictReduceOnly) {
+    const p0 = parseProjection(before);
+    const pq = parseProjection(after);
+    if (p0.h.lt(0)) {
+        return {
+            code: exports.LIQUIDATION_THRESHOLD,
+            errorCode: 'ACCOUNT_BELOW_LIQUIDATION_MARGIN_ERROR',
+            shortfall: (0, decimal_1.toText)(p0.h.negated()),
+            engineMessage: `This account is ${shortfallText(p0.h)} rUSD below its liquidation safety threshold. ` +
+                'Add collateral before placing another order.',
+        };
+    }
+    if (strictReduceOnly) {
+        return null;
+    }
+    for (const projection of [p0, pq]) {
+        if (projection.mbFloor.lt(projection.im)) {
+            const delta = projection.mbFloor.minus(projection.im);
+            return {
+                code: exports.INITIAL_MARGIN,
+                errorCode: 'ACCOUNT_BELOW_INITIAL_MARGIN_ERROR',
+                shortfall: (0, decimal_1.toText)(delta.negated()),
+                engineMessage: `Insufficient margin: the account is ${shortfallText(delta)} rUSD below the initial margin ` +
+                    'requirement for this order. Add collateral, reduce the order size, or submit a reduce-only order.',
+            };
+        }
+    }
+    if (pq.h.lt(pq.reserve)) {
+        const delta = pq.h.minus(pq.reserve);
+        return {
+            code: exports.SETTLEMENT_RESERVE,
+            errorCode: 'ACCOUNT_BELOW_INITIAL_MARGIN_ERROR',
+            shortfall: (0, decimal_1.toText)(delta.negated()),
+            engineMessage: `Insufficient margin: this order would leave the account ${shortfallText(delta)} rUSD below its ` +
+                'settlement reserve. Reduce the order size or add collateral.',
+        };
+    }
+    return null;
+}
+exports.admit = admit;
+// --------------------------------------------------------------------------
+// A fill applied the way Core updates a position
+// --------------------------------------------------------------------------
+/** The account after `lot` fills in full at its price, settled the way Core updates a position. */
+function applyFill(margin, lot, fee = '0') {
+    const parsed = parseMargin(margin);
+    const fill = parseLot(lot);
+    const feeD = (0, decimal_1.parseDecimal)(fee, 'fee');
+    const risk = parsed.markets.get(fill.market);
+    if (risk === undefined) {
+        throw new errors_1.AccountFiguresInputError(`No mark or margin rate for ${fill.market}`);
+    }
+    const base = risk.base;
+    let entry = risk.entry;
+    let realized = decimal_1.ZERO;
+    const total = base.plus(fill.qty);
+    if (base.isZero() || base.times(fill.qty).gt(0)) {
+        if (total.isZero()) {
+            throw new errors_1.AccountFiguresInputError(`A fill on a flat ${fill.market} position needs a non-zero qty`);
+        }
+        entry = base.times(entry).plus(fill.qty.times(fill.price)).div(total);
+    }
+    else if (base.times(total).gte(0)) {
+        realized = fill.qty.negated().times(fill.price.minus(entry));
+    }
+    else {
+        realized = base.times(fill.price.minus(entry));
+        entry = fill.price;
+    }
+    if (total.isZero()) {
+        entry = risk.mark;
+    }
+    const oldUpnl = base.times(risk.mark.minus(risk.entry));
+    const newUpnl = total.times(risk.mark.minus(entry));
+    const markets = new Map(parsed.markets);
+    markets.set(fill.market, { ...risk, base: total, entry });
+    return marginText({
+        realBalance: parsed.realBalance.plus(realized).minus(feeD),
+        marginBalance: parsed.marginBalance
+            .plus(realized)
+            .minus(feeD)
+            .minus(oldUpnl)
+            .plus(newUpnl),
+        markets,
+    });
+}
+exports.applyFill = applyFill;

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Input the figures cannot be computed from: a missing or non-numeric price,
+ * market, asset definition or margin parameter. Missing data is never counted
+ * as zero, since that would produce wrong risk numbers.
+ */
+export declare class AccountFiguresInputError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountFiguresInputError = void 0;
+/**
+ * Input the figures cannot be computed from: a missing or non-numeric price,
+ * market, asset definition or margin parameter. Missing data is never counted
+ * as zero, since that would produce wrong risk numbers.
+ */
+class AccountFiguresInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AccountFiguresInputError';
+    }
+}
+exports.AccountFiguresInputError = AccountFiguresInputError;

package/dist/figures.d.ts

@@ -0,0 +1,81 @@
+import { CollateralRow, MarginInputs, MarginSnapshot, PositionDetail } from './snapshot';
+/** What the figures leave out, for a reader of them. */
+export declare const MARGIN_ASSUMPTIONS: readonly string[];
+export interface PositionRisk {
+    /** This position's own liquidation margin requirement, rounded up to 6 dp. */
+    lmr: string;
+    /**
+     * The liquidation price on the tick, rounded toward the mark. `null` when no
+     * positive price is the liquidation line.
+     */
+    liquidationPrice: string | null;
+    /** The same price before rounding onto the tick. */
+    liquidationPriceExact: string | null;
+    /**
+     * How far the mark must move against the position to reach the liquidation
+     * price, as a fraction of the mark (from the exact price). Negative when the
+     * account is already past the line.
+     */
+    distanceToLiquidation: string | null;
+    /**
+     * The account holds non-stable collateral whose price follows this
+     * position's market (WETH or wstETH with an ETH perp, BTC with a BTC perp).
+     * The liquidation price holds that collateral's price fixed, which it is
+     * not: for a long, the collateral falls with the mark and liquidation comes
+     * sooner than shown.
+     */
+    assumesFixedCollateral: boolean;
+}
+export interface PositionFigures extends PositionDetail, PositionRisk {
+    /** |qty| × mark. */
+    notional: string;
+    /** s, the market's liquidation-margin parameter. */
+    liquidationMarginRate: string;
+}
+export interface AccountFigures {
+    accountId: number | string;
+    /**
+     * Margin balance: collateral as Core values it (price × (1 − haircut), a
+     * debt at price / (1 − haircut)) + unrealised PnL at mark. Realised PnL and
+     * funding are already in V2's rUSD balance.
+     */
+    equity: string;
+    /** Collateral as Core values it, without unrealised PnL. */
+    realBalance: string;
+    unrealizedPnl: string;
+    /** Liquidation margin requirement (LMR): the account is liquidated when equity falls below it. */
+    lmr: string;
+    /** Initial margin requirement (IMR): new exposure needs equity at or above it. */
+    imr: string;
+    imMultiplier: string;
+    /**
+     * LMR / margin balance (`equity`): what the app calls "Cross margin ratio".
+     * The figure liquidation depends on; 1 is liquidation. `null` when equity
+     * is not positive.
+     */
+    liquidationMarginUsage: string | null;
+    /**
+     * IMR / margin balance (`equity`): what the app calls "Cross margin usage".
+     * At 1 no new position fits; liquidation comes later, at
+     * `liquidationMarginUsage` 1. `null` when equity is not positive.
+     */
+    initialMarginUsage: string | null;
+    /** equity < LMR. */
+    liquidatable: boolean;
+    /** equity − LMR. */
+    marginBuffer: string;
+    /** equity − IMR: the room for new exposure (negative when below the IMR). */
+    availableMargin: string;
+    collateral: CollateralRow[];
+    positions: PositionFigures[];
+}
+/**
+ * Liquidation margin, liquidation price and distance for one held market, on
+ * the settled account. `lmr` is the account's LMR when the caller already has
+ * it.
+ */
+export declare function positionRisk(snapshot: MarginSnapshot, symbol: string, lmr?: string): PositionRisk;
+/** Account-level equity, requirements, usage and buffers, and each position's figures. */
+export declare function accountFigures(snapshot: MarginSnapshot): AccountFigures;
+/** One account's figures straight from V2 reads. */
+export declare function computeAccountFigures(inputs: MarginInputs): AccountFigures;

package/dist/figures.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeAccountFigures = exports.accountFigures = exports.positionRisk = exports.MARGIN_ASSUMPTIONS = void 0;
+/**
+ * Account-level and per-position figures on the settled account. The shape
+ * follows the Agent Kit's `account_figures` and `position_risk` (kit 0.12.20);
+ * the inputs are valued as Core values them (see `snapshot.ts`). Every amount
+ * is exact; `format.ts` rounds for display.
+ */
+const decimal_1 = require("./decimal");
+const engine_1 = require("./engine");
+const liquidation_1 = require("./liquidation");
+const snapshot_1 = require("./snapshot");
+const errors_1 = require("./errors");
+/** What the figures leave out, for a reader of them. */
+exports.MARGIN_ASSUMPTIONS = [
+    'An estimate from public V2 data of the margin Core computes; Core can differ slightly.',
+    'Equity (margin balance) = each collateral at its oracle price × (1 − haircut), a debt at price / (1 − haircut), ' +
+        "+ unrealized PnL at mark. The USDC balance already includes realized PnL, funding and ADL cashflows up to V2's latest market trackers.",
+    'Liquidation happens below the liquidation margin; liquidation margin usage = liquidation margin / equity (1 = liquidation).',
+    'Liquidation price per position: cross margin, every other mark, collateral price and funding unchanged. ' +
+        "It errs when a collateral's price follows the position's market (assumesFixedCollateral).",
+    'Not visible: matched fills that have not settled yet (seconds), and funding since the latest market trackers.',
+];
+function settled(snapshot) {
+    const margin = (0, engine_1.parseMargin)(snapshot.margin);
+    const projection = (0, engine_1.projectD)(margin, (0, decimal_1.parseDecimal)(snapshot.imMultiplier, 'IM multiplier'));
+    return { margin, projection };
+}
+/** Whether a held collateral's price follows `symbol`'s market (rUSD never does). */
+function collateralFollows(snapshot, symbol) {
+    const market = (0, snapshot_1.marketUnderlying)(symbol);
+    return snapshot.collateral.some((c) => c.asset !== snapshot_1.RUSD &&
+        !(0, decimal_1.parseDecimal)(c.balance, `${c.asset} balance`).isZero() &&
+        (0, snapshot_1.collateralUnderlying)(c.asset) === market);
+}
+/**
+ * Liquidation margin, liquidation price and distance for one held market, on
+ * the settled account. `lmr` is the account's LMR when the caller already has
+ * it.
+ */
+function positionRisk(snapshot, symbol, lmr) {
+    const margin = (0, engine_1.parseMargin)(snapshot.margin);
+    const lm = lmr === undefined
+        ? settled(snapshot).projection.lm
+        : (0, decimal_1.parseDecimal)(lmr, 'liquidation margin');
+    const risk = margin.markets.get(symbol);
+    const definition = snapshot.definitions[symbol];
+    if (risk === undefined || definition === undefined) {
+        throw new errors_1.AccountFiguresInputError(`No position or market data for ${symbol}`);
+    }
+    const price = (0, liquidation_1.liquidationPriceD)(margin, symbol, lm);
+    const tick = (0, decimal_1.parseDecimal)(definition.tickSize, `${symbol} tick size`);
+    const ownLm = (0, decimal_1.ceilTo)((0, decimal_1.ceilTo)(risk.marginRate.times((0, decimal_1.ceilTo)(risk.base.abs().times(risk.mark)))), (0, decimal_1.nativeUnit)(decimal_1.RUSD_DECIMALS));
+    const rounded = (0, liquidation_1.roundTowardMarkD)(price, risk, tick);
+    const distance = (0, liquidation_1.distanceToLiquidationD)(risk, price);
+    return {
+        lmr: (0, decimal_1.toText)(ownLm),
+        liquidationPrice: rounded === null ? null : (0, decimal_1.toText)(rounded),
+        liquidationPriceExact: price === null ? null : (0, decimal_1.toText)(price),
+        distanceToLiquidation: distance === null ? null : (0, decimal_1.toText)(distance),
+        assumesFixedCollateral: collateralFollows(snapshot, symbol),
+    };
+}
+exports.positionRisk = positionRisk;
+/** Account-level equity, requirements, usage and buffers, and each position's figures. */
+function accountFigures(snapshot) {
+    const { margin, projection } = settled(snapshot);
+    const equity = margin.marginBalance;
+    const liquidationUsage = (0, liquidation_1.marginUsageD)(equity, projection.lm);
+    const initialUsage = (0, liquidation_1.marginUsageD)(equity, projection.im);
+    const lmr = (0, decimal_1.toText)(projection.lm);
+    const positions = snapshot.positions.map((detail) => {
+        const risk = margin.markets.get(detail.symbol);
+        if (risk === undefined) {
+            throw new errors_1.AccountFiguresInputError(`No position or market data for ${detail.symbol}`);
+        }
+        return {
+            ...detail,
+            notional: (0, decimal_1.toText)(risk.base.abs().times(risk.mark)),
+            liquidationMarginRate: (0, decimal_1.toText)(risk.marginRate),
+            ...positionRisk(snapshot, detail.symbol, lmr),
+        };
+    });
+    return {
+        accountId: snapshot.accountId,
+        equity: (0, decimal_1.toText)(equity),
+        realBalance: (0, decimal_1.toText)(margin.realBalance),
+        unrealizedPnl: snapshot.unrealizedPnl,
+        lmr,
+        imr: (0, decimal_1.toText)(projection.im),
+        imMultiplier: snapshot.imMultiplier,
+        liquidationMarginUsage: liquidationUsage === null ? null : (0, decimal_1.toText)(liquidationUsage),
+        initialMarginUsage: initialUsage === null ? null : (0, decimal_1.toText)(initialUsage),
+        liquidatable: equity.lt(projection.lm),
+        marginBuffer: (0, decimal_1.toText)(equity.minus(projection.lm)),
+        availableMargin: (0, decimal_1.toText)(equity.minus(projection.im)),
+        collateral: snapshot.collateral,
+        positions,
+    };
+}
+exports.accountFigures = accountFigures;
+/** One account's figures straight from V2 reads. */
+function computeAccountFigures(inputs) {
+    return accountFigures((0, snapshot_1.buildMarginSnapshot)(inputs));
+}
+exports.computeAccountFigures = computeAccountFigures;

package/dist/format.d.ts

@@ -0,0 +1,8 @@
+export type Rounding = 'down' | 'up';
+/** A USD amount to 2 dp, e.g. `formatUsd(equity)` or `formatUsd(lmr, 'up')`. */
+export declare function formatUsd(value: string, rounding?: Rounding): string;
+/**
+ * A ratio as a percentage to 2 dp, e.g. `formatPct(liquidationMarginUsage, 'up')` or
+ * `formatPct(distanceToLiquidation, 'down')`.
+ */
+export declare function formatPct(ratio: string, rounding: Rounding): string;

package/dist/format.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPct = exports.formatUsd = void 0;
+/**
+ * Display rounding, with the kit's conventions: cash, equity, PnL and buffers
+ * round down; requirements and margin usage round up; the distance to
+ * liquidation rounds down. Each rounding errs toward the riskier reading.
+ */
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const decimal_1 = require("./decimal");
+function fixed2(value, rounding) {
+    const text = value.toFixed(2, rounding === 'down' ? bignumber_js_1.default.ROUND_FLOOR : bignumber_js_1.default.ROUND_CEIL);
+    return text === '-0.00' ? '0.00' : text;
+}
+/** A USD amount to 2 dp, e.g. `formatUsd(equity)` or `formatUsd(lmr, 'up')`. */
+function formatUsd(value, rounding = 'down') {
+    return fixed2((0, decimal_1.parseDecimal)(value, 'USD amount'), rounding);
+}
+exports.formatUsd = formatUsd;
+/**
+ * A ratio as a percentage to 2 dp, e.g. `formatPct(liquidationMarginUsage, 'up')` or
+ * `formatPct(distanceToLiquidation, 'down')`.
+ */
+function formatPct(ratio, rounding) {
+    return fixed2((0, decimal_1.parseDecimal)(ratio, 'ratio').times(100), rounding);
+}
+exports.formatPct = formatPct;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { AccountFiguresInputError } from './errors';
+export { RUSD_DECIMALS } from './decimal';
+export type { Decimalish } from './decimal';
+export { admit, applyFill, INITIAL_MARGIN, LIQUIDATION_THRESHOLD, project, roundingAllowance, SETTLEMENT_RESERVE, SETTLEMENT_RESERVE_RATE, } from './engine';
+export type { AccountMargin, Lot, MarketRisk, Projection, ProjectOptions, Rejection, RejectionCode, } from './engine';
+export { distanceToLiquidation, liquidationPrice, marginUsage, roundTowardMark, } from './liquidation';
+export { buildMarginSnapshot, imMultiplierFrom, RUSD } from './snapshot';
+export type { CollateralRow, MarginInputs, MarginSnapshot, PositionDetail, V2AccountBalance, V2AssetDefinition, V2AssetOraclePrice, V2MarketDefinition, V2MarketSummary, V2Position, } from './snapshot';
+export { accountFigures, computeAccountFigures, MARGIN_ASSUMPTIONS, positionRisk, } from './figures';
+export type { AccountFigures, PositionFigures, PositionRisk } from './figures';
+export { formatPct, formatUsd } from './format';
+export type { Rounding } from './format';

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatUsd = exports.formatPct = exports.positionRisk = exports.MARGIN_ASSUMPTIONS = exports.computeAccountFigures = exports.accountFigures = exports.RUSD = exports.imMultiplierFrom = exports.buildMarginSnapshot = exports.roundTowardMark = exports.marginUsage = exports.liquidationPrice = exports.distanceToLiquidation = exports.SETTLEMENT_RESERVE_RATE = exports.SETTLEMENT_RESERVE = exports.roundingAllowance = exports.project = exports.LIQUIDATION_THRESHOLD = exports.INITIAL_MARGIN = exports.applyFill = exports.admit = exports.RUSD_DECIMALS = exports.AccountFiguresInputError = void 0;
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AccountFiguresInputError", { enumerable: true, get: function () { return errors_1.AccountFiguresInputError; } });
+var decimal_1 = require("./decimal");
+Object.defineProperty(exports, "RUSD_DECIMALS", { enumerable: true, get: function () { return decimal_1.RUSD_DECIMALS; } });
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "admit", { enumerable: true, get: function () { return engine_1.admit; } });
+Object.defineProperty(exports, "applyFill", { enumerable: true, get: function () { return engine_1.applyFill; } });
+Object.defineProperty(exports, "INITIAL_MARGIN", { enumerable: true, get: function () { return engine_1.INITIAL_MARGIN; } });
+Object.defineProperty(exports, "LIQUIDATION_THRESHOLD", { enumerable: true, get: function () { return engine_1.LIQUIDATION_THRESHOLD; } });
+Object.defineProperty(exports, "project", { enumerable: true, get: function () { return engine_1.project; } });
+Object.defineProperty(exports, "roundingAllowance", { enumerable: true, get: function () { return engine_1.roundingAllowance; } });
+Object.defineProperty(exports, "SETTLEMENT_RESERVE", { enumerable: true, get: function () { return engine_1.SETTLEMENT_RESERVE; } });
+Object.defineProperty(exports, "SETTLEMENT_RESERVE_RATE", { enumerable: true, get: function () { return engine_1.SETTLEMENT_RESERVE_RATE; } });
+var liquidation_1 = require("./liquidation");
+Object.defineProperty(exports, "distanceToLiquidation", { enumerable: true, get: function () { return liquidation_1.distanceToLiquidation; } });
+Object.defineProperty(exports, "liquidationPrice", { enumerable: true, get: function () { return liquidation_1.liquidationPrice; } });
+Object.defineProperty(exports, "marginUsage", { enumerable: true, get: function () { return liquidation_1.marginUsage; } });
+Object.defineProperty(exports, "roundTowardMark", { enumerable: true, get: function () { return liquidation_1.roundTowardMark; } });
+var snapshot_1 = require("./snapshot");
+Object.defineProperty(exports, "buildMarginSnapshot", { enumerable: true, get: function () { return snapshot_1.buildMarginSnapshot; } });
+Object.defineProperty(exports, "imMultiplierFrom", { enumerable: true, get: function () { return snapshot_1.imMultiplierFrom; } });
+Object.defineProperty(exports, "RUSD", { enumerable: true, get: function () { return snapshot_1.RUSD; } });
+var figures_1 = require("./figures");
+Object.defineProperty(exports, "accountFigures", { enumerable: true, get: function () { return figures_1.accountFigures; } });
+Object.defineProperty(exports, "computeAccountFigures", { enumerable: true, get: function () { return figures_1.computeAccountFigures; } });
+Object.defineProperty(exports, "MARGIN_ASSUMPTIONS", { enumerable: true, get: function () { return figures_1.MARGIN_ASSUMPTIONS; } });
+Object.defineProperty(exports, "positionRisk", { enumerable: true, get: function () { return figures_1.positionRisk; } });
+var format_1 = require("./format");
+Object.defineProperty(exports, "formatPct", { enumerable: true, get: function () { return format_1.formatPct; } });
+Object.defineProperty(exports, "formatUsd", { enumerable: true, get: function () { return format_1.formatUsd; } });

package/dist/liquidation.d.ts

@@ -0,0 +1,29 @@
+import { Dec } from './decimal';
+import { AccountMargin, MarginD, MarketRisk, RiskD } from './engine';
+export declare function marginUsageD(marginBalance: Dec, lm: Dec): Dec | null;
+/**
+ * Liquidation margin / equity: 1 is the liquidation line. `null` when equity
+ * is not positive.
+ */
+export declare function marginUsage(marginBalance: string, lm: string): string | null;
+export declare function liquidationPriceD(margin: MarginD, market: string, lm: Dec): Dec | null;
+/**
+ * Cross margin: the price in `market` at which equity equals the liquidation
+ * margin `lm` (the settled projection's), every other mark, collateral price
+ * and funding unchanged. `null` for a flat market and when no positive price
+ * is the liquidation line. Exact; see `roundTowardMark` for display.
+ */
+export declare function liquidationPrice(margin: AccountMargin, market: string, lm: string): string | null;
+export declare function distanceToLiquidationD(risk: RiskD, price: Dec | null): Dec | null;
+/**
+ * How far the mark must move against the position to reach `price`, as a
+ * fraction of the mark. Negative when the account is already past the
+ * liquidation line.
+ */
+export declare function distanceToLiquidation(risk: MarketRisk, price: string | null): string | null;
+export declare function roundTowardMarkD(price: Dec | null, risk: RiskD, tick: Dec): Dec | null;
+/**
+ * A liquidation price rounded onto the tick toward the mark, so it never reads
+ * farther away than it is: up for a long, down for a short.
+ */
+export declare function roundTowardMark(price: string | null, risk: MarketRisk, tick: string): string | null;