@reyaxyz/account-figures 0.0.0-stage → 0.3.0

package/LICENSE.md

@@ -0,0 +1 @@
+MIT License

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @reyaxyz/account-figures
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Account figures from public V2 data: equity, margin requirements, margin usage,
+available margin and per-position liquidation prices. V2 returns raw state
+only; this module turns it into the figures a trader reads.
+
+The figures follow Core's definitions (reya-network `AccountExposure.sol` and
+`PriceHelpers.sol`). The code started as a TypeScript port of the Agent Kit's
+`agent_kit/scripts/_margin.py` (kit 0.12.20), itself a port of the matching
+engine's risk engine (revision 4d8ed012). The tests replay the kit's vectors
+where the kit agrees with Core. Where it does not, they derive the expected
+values from Core's definitions. Those cases are collateral valuation and
+funding (see [Where this differs from the kit](#where-this-differs-from-the-kit)).
+
+Pure functions: no I/O, no service configuration. The only dependency is
+`bignumber.js`. Every amount in and out is a decimal string.
+
+## Use
+
+```ts
+import {
+  computeAccountFigures,
+  formatPct,
+  formatUsd,
+} from '@reyaxyz/account-figures';
+
+const figures = computeAccountFigures({
+  accountId,
+  balances, // GET /wallet/{address}/accountBalances
+  positions, // GET /wallet/{address}/positions
+  marketDefinitions, // GET /perpMarketDefinitions
+  marketSummaries, // GET /perpMarkets/summary
+  assetDefinitions, // GET /assetDefinitions (non-rUSD collateral only)
+  assetOraclePrices, // GET /assetOraclePrices (non-rUSD collateral only)
+});
+
+formatUsd(figures.equity); // "2292.50"
+formatUsd(figures.lmr, 'up');
+formatPct(figures.liquidationMarginUsage, 'up'); // "14.14", the app's "Cross margin ratio"
+figures.positions[0].liquidationPrice; // on the tick, toward the mark, or null
+```
+
+Rows of other accounts are ignored, so a wallet's full lists can be passed.
+Missing or non-numeric data (a price, a market, an asset definition, a margin
+parameter) throws `AccountFiguresInputError`; it is never counted as zero.
+
+## Figures
+
+| Figure | Definition |
+| -- | -- |
+| `equity` | The margin balance, as Core computes it: each collateral at its oracle price × (1 − haircut), or a debt at price / (1 − haircut), plus unrealised PnL at mark. V2's `WITHDRAWAL_ONLY` status is a deposit policy and changes nothing here. V2's rUSD balance already includes realised PnL and the funding and ADL cashflows up to its latest market trackers, so no funding is added. |
+| `realBalance` | The same, without unrealised PnL |
+| `lmr` | Liquidation margin requirement: Σ s × \|position\| × mark, with s the market's `liquidationMarginParameter`, rounded up to 6 dp per market. The account is liquidated when equity falls below it. Core's maintenance margin is a different threshold, not computed here. |
+| `imr` | Initial margin requirement: IM multiplier × LMR, the multiplier read from the definitions (1.3 on mainnet) |
+| `liquidationMarginUsage` | LMR / margin balance: the app's "Cross margin ratio". The figure liquidation depends on; 1 is liquidation. `null` when equity is not positive. |
+| `initialMarginUsage` | IMR / margin balance: the app's "Cross margin usage". At 1 no new position fits; liquidation comes later. `null` when equity is not positive. |
+| `marginBuffer` | equity − LMR |
+| `availableMargin` | equity − IMR (negative when below the IMR) |
+| `liquidatable` | equity < LMR |
+
+Per position:
+- `unrealizedPnl`, `notional` and `lmr` (its own);
+- `liquidationPrice` and `liquidationPriceExact`;
+- `distanceToLiquidation`: a fraction of the mark, negative when past the line;
+- `assumesFixedCollateral`, described in the next section.
+
+### Liquidation price
+
+Cross margin, per position: the price in that market at which equity equals
+the liquidation margin. Every other mark, collateral price and funding is held
+fixed, and the position's own liquidation margin is recomputed at that price.
+With q the signed base, P the mark, E equity, s the market's rate and
+LM_other the other positions' liquidation margin:
+
+```
+liq = (q·P − E + LM_other) / (q·(1 − sign(q)·s))
+```
+
+It is rounded onto the tick toward the mark, so it never reads farther away
+than it is under that assumption. It is `null` when no positive price is the
+liquidation line. For a long, that means no price liquidates it. For a short,
+it means the account is already past the line at every price, and
+`liquidatable` is then true.
+
+**`assumesFixedCollateral`** is true when the account holds non-stable
+collateral whose price follows the position's market: ETH, WETH or wstETH
+with an ETH perp, BTC with a BTC perp, and so on. The formula holds that
+collateral's price fixed, but it moves with the market. For a long, the
+collateral falls as the mark falls, so liquidation comes sooner than shown.
+For example, with 1 ETH collateral and a long of 1 ETH at 2,500, the price
+shown is 257.73, while liquidation with the collateral moving is near 1,337.
+
+Example (RET-256): one position, mark 100, s = 5%, equity 20. A long
+liquidates at 84.2105… (84.22 on a 0.01 tick), a short at 114.2857… (114.28).
+
+### Against the app's figures
+
+The app's trade page divides both requirements by the same margin balance:
+"Cross margin usage" is IMR / margin balance (`initialMarginUsage` here), and
+"Cross margin ratio" is LMR / margin balance (`liquidationMarginUsage`). Both
+the app and this module count withdrawal-only collateral after its haircut, as
+Core does. They differ on a collateral debt: Core and this module value it at
+price / (1 − haircut), the app at price × (1 − haircut). For an account with a
+debt, the module's equity is therefore slightly lower and both ratios slightly
+higher than the app's.
+
+## Where this differs from the kit
+
+- **Withdrawal-only collateral:** the kit credits it at 0. Core credits every
+  supporting collateral, and so does this module.
+- **Debts:** the kit values a debt at price. Core and this module use
+  price / (1 − haircut).
+- **Funding:** the kit subtracts a debit-only funding estimate. V2's rUSD
+  balance already contains the funding cashflow, so this module adds none.
+- **A short past the line at every price:** the kit returns a negative
+  liquidation price; this module returns `null`, per RET-256.
+
+## Display rounding
+
+`formatUsd` and `formatPct` round to 2 dp, with the kit's conventions:
+- cash, equity, PnL and buffers round down;
+- requirements and margin usage round up;
+- the distance to liquidation rounds down.
+
+## Lower-level functions
+
+For figures after a hypothetical fill, such as an order preview, compose
+`buildMarginSnapshot`, `applyFill`, `project`, `liquidationPrice` and
+`roundTowardMark`.
+
+`project` and `admit` are the matching engine's projection and admission
+verdict, with its messages. The engine credits collateral by its own rules,
+which give some collateral no credit. A snapshot from `buildMarginSnapshot`
+values collateral as Core does, so it is not the engine's admission input.
+
+## What the figures cannot see
+
+- Matched fills that have not settled yet (seconds).
+- Funding and ADL since V2's latest market trackers.
+- Collateral price skew: V2's oracle prices, not Core's feed at that block.
+- The settlement reserve rate, pinned at 1% (the engine's V1 constant; used
+  only by `project`).
+
+## Develop
+
+```sh
+pnpm --filter @reyaxyz/api-v2-sdk build   # the V2 shape test reads its types
+pnpm --filter @reyaxyz/account-figures build
+pnpm --filter @reyaxyz/account-figures code-quality:check
+pnpm --filter @reyaxyz/account-figures test
+```
+
+Do not extend `calculateTotalMargin` in `@reyaxyz/common` for these figures:
+it uses the raw base, not the ADL-adjusted size.

package/dist/decimal.d.ts

@@ -0,0 +1,32 @@
+import BigNumber from 'bignumber.js';
+/**
+ * The decimal type of the port. Addition, subtraction and multiplication are
+ * exact; division keeps 100 decimal places, rounding half to even. The kit
+ * runs Python's `decimal` at 100 significant digits with the same rounding, so
+ * every figure rounded onto a unit afterwards comes out the same.
+ *
+ * A private clone, so the global BigNumber configuration of a consumer is
+ * neither read nor changed.
+ */
+export declare const Dec: typeof BigNumber;
+export type Dec = BigNumber;
+export declare const ZERO: Dec;
+export declare const ONE: Dec;
+/** One wei: the E18 step the engine rounds intermediate products to. */
+export declare const E18: Dec;
+/** rUSD's decimals: cash is floored and requirements are rounded up to them. */
+export declare const RUSD_DECIMALS = 6;
+/** The smallest unit of a token with `decimals` decimals, never finer than one wei. */
+export declare function nativeUnit(decimals: number): Dec;
+export declare function roundTo(value: Dec, unit: Dec, mode: BigNumber.RoundingMode): Dec;
+export declare function floorTo(value: Dec, unit?: Dec): Dec;
+export declare function ceilTo(value: Dec, unit?: Dec): Dec;
+export declare function minOf(...values: Dec[]): Dec;
+export declare function maxOf(...values: Dec[]): Dec;
+export type Decimalish = string | number;
+/** A finite decimal, or an input error naming `label`. */
+export declare function parseDecimal(value: Decimalish | null | undefined, label: string): Dec;
+/** Missing prices are not zero: a price must be present, finite and positive. */
+export declare function requirePrice(value: Decimalish | null | undefined, label: string): Dec;
+/** Plain decimal notation without trailing zeros, as V2 writes decimals. */
+export declare function toText(value: Dec): string;

package/dist/decimal.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toText = exports.requirePrice = exports.parseDecimal = exports.maxOf = exports.minOf = exports.ceilTo = exports.floorTo = exports.roundTo = exports.nativeUnit = exports.RUSD_DECIMALS = exports.E18 = exports.ONE = exports.ZERO = exports.Dec = void 0;
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const errors_1 = require("./errors");
+/**
+ * The decimal type of the port. Addition, subtraction and multiplication are
+ * exact; division keeps 100 decimal places, rounding half to even. The kit
+ * runs Python's `decimal` at 100 significant digits with the same rounding, so
+ * every figure rounded onto a unit afterwards comes out the same.
+ *
+ * A private clone, so the global BigNumber configuration of a consumer is
+ * neither read nor changed.
+ */
+exports.Dec = bignumber_js_1.default.clone({
+    DECIMAL_PLACES: 100,
+    ROUNDING_MODE: bignumber_js_1.default.ROUND_HALF_EVEN,
+    EXPONENTIAL_AT: 1e9,
+});
+exports.ZERO = new exports.Dec(0);
+exports.ONE = new exports.Dec(1);
+/** One wei: the E18 step the engine rounds intermediate products to. */
+exports.E18 = new exports.Dec('1e-18');
+/** rUSD's decimals: cash is floored and requirements are rounded up to them. */
+exports.RUSD_DECIMALS = 6;
+/** The smallest unit of a token with `decimals` decimals, never finer than one wei. */
+function nativeUnit(decimals) {
+    return decimals >= 18 ? exports.E18 : exports.ONE.shiftedBy(-decimals);
+}
+exports.nativeUnit = nativeUnit;
+function roundTo(value, unit, mode) {
+    return value.div(unit).integerValue(mode).times(unit);
+}
+exports.roundTo = roundTo;
+function floorTo(value, unit = exports.E18) {
+    return roundTo(value, unit, bignumber_js_1.default.ROUND_FLOOR);
+}
+exports.floorTo = floorTo;
+function ceilTo(value, unit = exports.E18) {
+    return roundTo(value, unit, bignumber_js_1.default.ROUND_CEIL);
+}
+exports.ceilTo = ceilTo;
+function minOf(...values) {
+    return exports.Dec.min(...values);
+}
+exports.minOf = minOf;
+function maxOf(...values) {
+    return exports.Dec.max(...values);
+}
+exports.maxOf = maxOf;
+/** A finite decimal, or an input error naming `label`. */
+function parseDecimal(value, label) {
+    if (value === undefined || value === null) {
+        throw new errors_1.AccountFiguresInputError(`${label} is missing`);
+    }
+    const result = new exports.Dec(typeof value === 'string' ? value.trim() : value);
+    if (!result.isFinite()) {
+        throw new errors_1.AccountFiguresInputError(`${label} is not a finite number: ${JSON.stringify(value)}`);
+    }
+    return result;
+}
+exports.parseDecimal = parseDecimal;
+/** Missing prices are not zero: a price must be present, finite and positive. */
+function requirePrice(value, label) {
+    if (value === undefined || value === null) {
+        throw new errors_1.AccountFiguresInputError(`${label} is unavailable`);
+    }
+    const price = new exports.Dec(typeof value === 'string' ? value.trim() : value);
+    if (!price.isFinite() || price.lte(0)) {
+        throw new errors_1.AccountFiguresInputError(`${label} must be a positive finite price`);
+    }
+    return price;
+}
+exports.requirePrice = requirePrice;
+/** Plain decimal notation without trailing zeros, as V2 writes decimals. */
+function toText(value) {
+    return value.isZero() ? '0' : value.toFixed();
+}
+exports.toText = toText;

package/dist/engine.d.ts

@@ -0,0 +1,115 @@
+import { Dec } from './decimal';
+/**
+ * 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.
+ */
+export declare const SETTLEMENT_RESERVE_RATE = "0.01";
+/** One market as the projection reads it (`PositionRiskInputs`). */
+export interface MarketRisk {
+    /** Signed settled base after ADL rescaling; 0 for a market without a position. */
+    base: string;
+    mark: string;
+    /** Liquidation-margin rate s: V2 `liquidationMarginParameter`. */
+    marginRate: string;
+    /** Average entry price (Core `lastPrice`); the mark for a flat market. */
+    entry: string;
+}
+/** Settled account state (`AccountMargin`). */
+export interface AccountMargin {
+    realBalance: string;
+    /** Equity: the real balance plus unrealised PnL at mark. */
+    marginBalance: string;
+    markets: Readonly<Record<string, MarketRisk>>;
+}
+/** A fill the projection considers: an unsettled one, or an order at its limit price. */
+export interface Lot {
+    market: string;
+    /** Signed: positive buys. */
+    qty: string;
+    price: string;
+}
+export interface Projection {
+    mbFloor: string;
+    rbFloor: string;
+    /** Liquidation margin requirement (LMR). */
+    lm: string;
+    /** Initial margin requirement (IMR). */
+    im: string;
+    reserve: string;
+    /** Health: min(mbFloor − lm, rbFloor). */
+    h: string;
+    /** h − reserve. */
+    c: string;
+}
+export declare const LIQUIDATION_THRESHOLD = "below_liquidation_threshold";
+export declare const INITIAL_MARGIN = "below_initial_margin";
+export declare const SETTLEMENT_RESERVE = "below_settlement_reserve";
+export type RejectionCode = typeof LIQUIDATION_THRESHOLD | typeof INITIAL_MARGIN | typeof SETTLEMENT_RESERVE;
+export interface Rejection {
+    code: RejectionCode;
+    /** The engine's error code. */
+    errorCode: string;
+    shortfall: string;
+    /** The engine's own message, as sent on the wire. */
+    engineMessage: string;
+}
+export interface ProjectOptions {
+    imMultiplier: string;
+    /** Matched fills not settled yet. V2 does not show them, so live callers pass none. */
+    inFlight?: readonly Lot[];
+    reserveRate?: string;
+    decimals?: number;
+}
+export interface RiskD {
+    base: Dec;
+    mark: Dec;
+    marginRate: Dec;
+    entry: Dec;
+}
+export interface MarginD {
+    realBalance: Dec;
+    marginBalance: Dec;
+    markets: Map<string, RiskD>;
+}
+interface LotD {
+    market: string;
+    qty: Dec;
+    price: Dec;
+}
+interface ProjectionD {
+    mbFloor: Dec;
+    rbFloor: Dec;
+    lm: Dec;
+    im: Dec;
+    reserve: Dec;
+    h: Dec;
+    c: Dec;
+}
+export declare function parseRisk(market: string, risk: MarketRisk): RiskD;
+export declare function parseMargin(margin: AccountMargin): MarginD;
+export declare function riskText(risk: RiskD): MarketRisk;
+export declare function marginText(margin: MarginD): AccountMargin;
+/**
+ * Core's average-entry and PnL truncation bound: one native unit per
+ * transition for any realistic size.
+ */
+export declare function roundingAllowance(worstBase: string, transitions: number, decimals?: number): string;
+export declare function projectD(margin: MarginD, imMultiplier: Dec, candidates?: readonly LotD[], inFlight?: readonly LotD[], reserveRate?: Dec, decimals?: number): ProjectionD;
+/**
+ * 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.
+ */
+export declare function project(margin: AccountMargin, candidates: readonly Lot[], options: ProjectOptions): Projection;
+/**
+ * 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.
+ */
+export declare function admit(before: Projection, after: Projection, strictReduceOnly: boolean): Rejection | null;
+/** The account after `lot` fills in full at its price, settled the way Core updates a position. */
+export declare function applyFill(margin: AccountMargin, lot: Lot, fee?: string): AccountMargin;
+export {};