@insiderfinance/totalfinance 0.1.0

package/modules/crypto/src/curve.ts

@@ -0,0 +1,273 @@
+/**
+ * Crypto carry curve / futures term structure (spec: `docs/specs/carry-curve.md`).
+ *
+ * `futuresBasis` reads the carry off one dated future; `carryCurve` builds the whole term structure from a
+ * spot + a set of futures: each expiry's implied carry (composing `futuresBasis` verbatim), the **forward
+ * carry** the market prices between consecutive expiries, the curve **shape**, and the carry at any
+ * interpolated tenor (log-linear in `ln F`, flat-forward beyond the ends). Deterministic; `@insiderfinance/totalfinance/core`-only.
+ */
+
+import {
+  type Assumptions,
+  CONVENTIONS_VERSION,
+  ErrorCode,
+  InputError,
+  ensureKnownKeys,
+  ensureNonNegative,
+  ensurePositive,
+  finalizeResult,
+  type QuantWarning,
+  requireArgumentArray,
+  requireArgumentObject,
+  type Computed,
+} from '@totalfinance/core';
+import { type BasisStructure, futuresBasis } from './carry.js';
+
+/** A single dated future on the underlying. */
+export interface CarryCurveFuture {
+  /** Time to expiry in years. */
+  timeToExpiryYears: number;
+  /** Future price. */
+  price: number;
+}
+
+/** Input for {@link carryCurve}. */
+export interface CarryCurveInput {
+  /** Spot / index price (`t = 0`). */
+  spot: number;
+  /** Dated futures on the same underlying (≥ 1; distinct expiries). */
+  futures: CarryCurveFuture[];
+  /** Quote financing rate — enables per-point cash-and-carry richness. */
+  financingRate?: number;
+  /** Coin (base) yield. Default 0. */
+  coinYield?: number;
+  /** Tenors (years) to interpolate the carry at. */
+  queryTenors?: number[];
+  /** |forward-carry| range below which the shape is `flat`. Default 5e-4 (5 bp). */
+  flatTolerance?: number;
+}
+
+/** A carry-curve point (one expiry). */
+export interface CarryCurvePoint {
+  timeToExpiryYears: number;
+  price: number;
+  /** `ln(price/spot)/t` — the continuously-compounded implied carry. */
+  annualizedCarry: number;
+  structure: BasisStructure;
+  /** `price − spot·e^{(r−q)t}` — present only when `financingRate` is supplied. */
+  richness?: number;
+}
+
+/** The market's marginal carry over a window between two expiries (the first is `spot → F₁`). */
+export interface CarryForward {
+  fromTenorYears: number;
+  toTenorYears: number;
+  forwardCarry: number;
+}
+
+/** An interpolated carry point. */
+export interface CarryInterp {
+  timeToExpiryYears: number;
+  impliedForward: number;
+  annualizedCarry: number;
+}
+
+/** The overall term-structure shape (from the forward-carry sequence). */
+export type CarryCurveShape = 'upward' | 'downward' | 'humped' | 'flat' | 'mixed';
+
+/** The futures carry term structure. */
+export interface CarryCurve {
+  spot: number;
+  /** One point per future, sorted by expiry. */
+  points: CarryCurvePoint[];
+  /** Forward carries: `spot → F₁`, `F₁ → F₂`, … (one per future). */
+  forwards: CarryForward[];
+  shape: CarryCurveShape;
+  /** Interpolated carries — present only when `queryTenors` is supplied. */
+  interpolated?: CarryInterp[];
+}
+
+/** Classify the term-structure shape from the forward-carry sequence. */
+function classifyShape(carries: number[], tolerance: number): CarryCurveShape {
+  if (carries.length < 2) return 'flat';
+  const min = Math.min(...carries);
+  const max = Math.max(...carries);
+  if (max - min < tolerance) return 'flat';
+  const diffs: number[] = [];
+  for (let i = 1; i < carries.length; i++) diffs.push(carries[i]! - carries[i - 1]!);
+  if (diffs.every((d) => d >= -tolerance)) return 'upward';
+  if (diffs.every((d) => d <= tolerance)) return 'downward';
+  // Humped: rises to an interior peak, then falls.
+  const peak = carries.indexOf(max);
+  if (peak > 0 && peak < carries.length - 1) {
+    const leftUp = carries
+      .slice(0, peak + 1)
+      .every((v, i, a) => i === 0 || v >= a[i - 1]! - tolerance);
+    const rightDown = carries.slice(peak).every((v, i, a) => i === 0 || v <= a[i - 1]! + tolerance);
+    if (leftUp && rightDown) return 'humped';
+  }
+  return 'mixed';
+}
+
+/** Log-linear interpolation of `ln F(t)` (flat-forward extrapolation beyond the last expiry). */
+function interpLnForward(xs: number[], ys: number[], timeToExpiryYears: number): number {
+  const n = xs.length - 1; // last index
+  for (let i = 1; i <= n; i++) {
+    if (timeToExpiryYears <= xs[i]!) {
+      const w = (timeToExpiryYears - xs[i - 1]!) / (xs[i]! - xs[i - 1]!);
+      return ys[i - 1]! + w * (ys[i]! - ys[i - 1]!);
+    }
+  }
+  // Beyond the last expiry: extend at the last window's slope (constant forward carry).
+  const slope = (ys[n]! - ys[n - 1]!) / (xs[n]! - xs[n - 1]!);
+  return ys[n]! + slope * (timeToExpiryYears - xs[n]!);
+}
+
+function assumptions(): Assumptions {
+  return {
+    conventionsVersion: CONVENTIONS_VERSION,
+    dayCount: 'ACT/365F',
+    model: 'carry',
+    engine: 'carry-curve',
+  };
+}
+
+/**
+ * Build the futures carry term structure: per-expiry implied carry (composing {@link futuresBasis}), the
+ * forward carry between consecutive expiries, the curve shape, and the carry at any requested interpolated
+ * tenor. See `docs/specs/carry-curve.md`.
+ */
+/** EXACT {@link CarryCurveInput} fields (Law 12) — unknown keys are rejected, never ignored. */
+const CARRY_CURVE_KEYS = [
+  'spot',
+  'futures',
+  'financingRate',
+  'coinYield',
+  'queryTenors',
+  'flatTolerance',
+] as const;
+
+export function carryCurve(input: CarryCurveInput): Computed<CarryCurve> {
+  const functionName = 'carryCurve';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, CARRY_CURVE_KEYS);
+  ensurePositive(input.spot, 'spot', functionName);
+  requireArgumentArray(functionName, 'futures', (input as { futures?: unknown }).futures);
+  if (input.futures.length === 0) {
+    throw new InputError(`${functionName}: futures must be a non-empty array.`, {
+      code: ErrorCode.InputOutOfRange,
+      context: { futures: 0 },
+    });
+  }
+  input.futures.forEach((f, i) => {
+    requireArgumentObject(functionName, `futures[${i}]`, f);
+    ensurePositive(f.timeToExpiryYears, `futures[${i}].timeToExpiryYears`, functionName);
+    ensurePositive(f.price, `futures[${i}].price`, functionName);
+  });
+  if (
+    input.flatTolerance !== undefined &&
+    (typeof input.flatTolerance !== 'number' || !Number.isFinite(input.flatTolerance))
+  ) {
+    throw new InputError(
+      `carryCurve: flatTolerance must be a finite number when provided. Received ${input.flatTolerance === null ? 'null' : typeof input.flatTolerance}.`,
+      { code: ErrorCode.InputWrongType, context: { field: 'flatTolerance' } },
+    );
+  }
+  const flatTolerance = input.flatTolerance ?? 5e-4;
+  ensureNonNegative(flatTolerance, 'flatTolerance', functionName);
+
+  // Sort by expiry and reject non-increasing (a zero-width forward window).
+  const sorted = [...input.futures].sort((a, b) => a.timeToExpiryYears - b.timeToExpiryYears);
+  for (let i = 1; i < sorted.length; i++) {
+    if (!(sorted[i]!.timeToExpiryYears > sorted[i - 1]!.timeToExpiryYears)) {
+      throw new InputError(
+        `${functionName}: futures must have distinct expiries; found duplicate timeToExpiryYears = ${sorted[i]!.timeToExpiryYears}.`,
+        {
+          code: ErrorCode.InputOutOfRange,
+          context: { timeToExpiryYears: sorted[i]!.timeToExpiryYears },
+        },
+      );
+    }
+  }
+
+  // Per-expiry carry, reusing futuresBasis verbatim (identical to the single-expiry tool) —
+  // INCLUDING its diagnostics: a per-point `crypto.carry_arbitrage` (or an implausible financing
+  // rate) is the curve's finding too, and dropping it made the composed tool quieter than the tool
+  // it composes.
+  const curveWarnings: QuantWarning[] = [];
+  const points: CarryCurvePoint[] = sorted.map((f) => {
+    const b = futuresBasis({
+      spot: input.spot,
+      future: f.price,
+      timeToExpiryYears: f.timeToExpiryYears,
+      ...(input.financingRate !== undefined ? { financingRate: input.financingRate } : {}),
+      ...(input.coinYield !== undefined ? { coinYield: input.coinYield } : {}),
+    });
+    for (const w of b.diagnostics.warnings) {
+      curveWarnings.push({
+        ...w,
+        context: { ...(w.context ?? {}), timeToExpiryYears: f.timeToExpiryYears },
+      });
+    }
+    const pt: CarryCurvePoint = {
+      timeToExpiryYears: f.timeToExpiryYears,
+      price: f.price,
+      annualizedCarry: b.value.annualizedLog,
+      structure: b.value.structure,
+    };
+    if (b.value.richness !== undefined) pt.richness = b.value.richness;
+    return pt;
+  });
+
+  // Forward carries: spot(t=0, F=spot) → F₁ → F₂ → …
+  const forwards: CarryForward[] = [];
+  let prevT = 0;
+  let prevF = input.spot;
+  for (const f of sorted) {
+    forwards.push({
+      fromTenorYears: prevT,
+      toTenorYears: f.timeToExpiryYears,
+      forwardCarry: Math.log(f.price / prevF) / (f.timeToExpiryYears - prevT),
+    });
+    prevT = f.timeToExpiryYears;
+    prevF = f.price;
+  }
+
+  const shape = classifyShape(
+    forwards.map((w) => w.forwardCarry),
+    flatTolerance,
+  );
+
+  const payload: CarryCurve = {
+    spot: input.spot,
+    points,
+    forwards,
+    shape,
+  };
+
+  if (input.queryTenors !== undefined) {
+    requireArgumentArray(functionName, 'queryTenors', input.queryTenors as unknown);
+    const xs = [0, ...sorted.map((f) => f.timeToExpiryYears)];
+    const ys = [Math.log(input.spot), ...sorted.map((f) => Math.log(f.price))];
+    payload.interpolated = input.queryTenors.map((tenor, i) => {
+      ensurePositive(tenor, `queryTenors[${i}]`, functionName);
+      const impliedForward = Math.exp(interpLnForward(xs, ys, tenor));
+      return {
+        timeToExpiryYears: tenor,
+        impliedForward,
+        annualizedCarry: Math.log(impliedForward / input.spot) / tenor,
+      };
+    });
+  }
+
+  return finalizeResult(functionName, {
+    value: payload,
+    assumptions: assumptions(),
+    diagnostics: {
+      engine: 'carry-curve',
+      method: 'closed-form',
+      converged: true,
+      warnings: curveWarnings,
+    },
+  });
+}

package/modules/crypto/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * `@insiderfinance/totalfinance/crypto` — crypto-native analytics. The first package in the Crypto tier.
+ *
+ * Perpetual-swap funding, dated-futures basis + the carry-curve term structure, cash-and-carry, the
+ * perp-vs-future no-arbitrage carry spread, and the inverse (coin-margined) future & its coin-delta hedge —
+ * the annualized, comparable, no-arb-grounded numbers every crypto trader watches. Deterministic (no
+ * stochastic model), browser-safe, and depends only on `@insiderfinance/totalfinance/core`.
+ *
+ * The inverse *option* (Deribit coin-settled) lives in `@insiderfinance/totalfinance/options` (`inverseOption`); the 24/7
+ * trading calendar lives in `@insiderfinance/totalfinance/calendars` (`crypto24x7`).
+ */
+
+export {
+  perpetualFunding,
+  futuresBasis,
+  predictedFunding,
+  fundingBasisSpread,
+  optionsBasisSpread,
+} from './carry.js';
+export type {
+  PerpetualFundingInput,
+  PerpetualFunding,
+  FuturesBasisInput,
+  FuturesBasis,
+  BasisStructure,
+  PredictedFundingInput,
+  PredictedFunding,
+  FundingBasisSpreadInput,
+  FundingBasisSpread,
+  CarrySignal,
+  OptionsBasisSpreadInput,
+  OptionsBasisSpread,
+  OptionsCarrySignal,
+} from './carry.js';
+
+export { inverseFuture, inverseHedge } from './inverse.js';
+export type {
+  InverseSide,
+  InverseFutureInput,
+  InverseFuture,
+  InverseHedgeInput,
+  InverseHedge,
+} from './inverse.js';
+
+export { liquidationPrice } from './liquidation.js';
+export type {
+  MarginMode,
+  LiquidationInput,
+  Liquidation,
+  LiquidationAssumptions,
+} from './liquidation.js';
+
+export { carryCurve } from './curve.js';
+export type {
+  CarryCurveFuture,
+  CarryCurveInput,
+  CarryCurvePoint,
+  CarryForward,
+  CarryInterp,
+  CarryCurveShape,
+  CarryCurve,
+} from './curve.js';

package/modules/crypto/src/inverse.ts

@@ -0,0 +1,172 @@
+/**
+ * Inverse (coin-margined, Deribit/BitMEX-style) futures & perpetuals (spec: `docs/specs/inverse-future.md`).
+ *
+ * Inverse contracts are denominated in USD notional but margined and settled IN THE COIN, so the coin PnL
+ * `s·Q·(1/F₀ − 1/F)` is a non-linear function of price — its coin delta is `Q/F²` (not constant) and a long
+ * inverse future is SHORT gamma in coin. That coin delta is exactly the instrument that hedges an inverse
+ * *option*'s coin delta, so `inverseHedge` sizes the future/perp against any coin delta and reports the
+ * residual convexity the delta hedge leaves behind. Depends only on `@insiderfinance/totalfinance/core`.
+ */
+
+import {
+  ErrorCode,
+  InputError,
+  type Assumptions,
+  CONVENTIONS_VERSION,
+  type Diagnostics,
+  ensureEnum,
+  ensureFinite,
+  ensureKnownKeys,
+  ensurePositive,
+  finalizeResult,
+  requireArgumentObject,
+  type Computed,
+} from '@totalfinance/core';
+
+const SIDES = ['long', 'short'] as const;
+/** Position side of an inverse contract. */
+export type InverseSide = (typeof SIDES)[number];
+
+function assumptions(engine: string): Assumptions {
+  return { conventionsVersion: CONVENTIONS_VERSION, model: 'inverse-future', engine };
+}
+
+function diagnostics(engine: string): Diagnostics {
+  return { engine, method: 'closed-form', converged: true, warnings: [] };
+}
+
+// ── inverseFuture ───────────────────────────────────────────────────────────────
+
+/** Input for {@link inverseFuture}. */
+export interface InverseFutureInput {
+  /** USD notional (= contracts × contract multiplier, e.g. $10/contract on Deribit). */
+  notionalUsd: number;
+  /** Entry price (USD per coin). */
+  entryPrice: number;
+  /** Current mark price (USD per coin). */
+  markPrice: number;
+  /** Position side. Default 'long'. */
+  side?: InverseSide;
+}
+
+/** The coin economics of an inverse-margined futures/perp position. */
+export interface InverseFuture {
+  /** Coin PnL since entry: `s · notionalUsd · (1/entry − 1/mark)`. */
+  coinPnl: number;
+  /** USD value of that coin PnL at the mark (`coinPnl · markPrice`). */
+  usdPnl: number;
+  /** `∂coinPnl/∂mark = s · notionalUsd / mark²` — coin per $1 move; NOT constant (inverse convexity). */
+  coinDelta: number;
+  /** `∂²coinPnl/∂mark² = s · (−2·notionalUsd / mark³)` — a LONG inverse future is SHORT gamma in coin. */
+  coinGamma: number;
+  /** Coin-equivalent size at the mark (`s · notionalUsd / mark`) — how many coins the position is long. */
+  coinExposure: number;
+}
+
+/**
+ * The coin PnL and coin greeks of an inverse-margined (Deribit/BitMEX-style) future or perpetual position.
+ * The coin PnL `s·Q·(1/entry − 1/mark)` is non-linear in price: the coin delta is `Q/mark²` and a long
+ * position is short gamma in coin. See `docs/specs/inverse-future.md`.
+ */
+/** EXACT {@link InverseFutureInput} fields (Law 12) — unknown keys are rejected, never ignored. */
+const INVERSE_FUTURE_KEYS = ['notionalUsd', 'entryPrice', 'markPrice', 'side'] as const;
+
+export function inverseFuture(input: InverseFutureInput): Computed<InverseFuture> {
+  const functionName = 'inverseFuture';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, INVERSE_FUTURE_KEYS);
+  ensurePositive(input.notionalUsd, 'notionalUsd', functionName);
+  ensurePositive(input.entryPrice, 'entryPrice', functionName);
+  ensurePositive(input.markPrice, 'markPrice', functionName);
+  if (input.side !== undefined && input.side !== 'long' && input.side !== 'short') {
+    throw new InputError(
+      `inverseFuture: side must be 'long' | 'short' when provided. Received ${input.side === null ? 'null' : JSON.stringify(input.side)}.`,
+      { code: ErrorCode.InputInvalidEnum, context: { field: 'side' } },
+    );
+  }
+  const side = input.side ?? 'long';
+  ensureEnum(side, SIDES, 'side', functionName);
+
+  const s = side === 'short' ? -1 : 1;
+  const { notionalUsd: Q, entryPrice: F0, markPrice: F } = input;
+  const coinPnl = s * Q * (1 / F0 - 1 / F);
+
+  return finalizeResult(functionName, {
+    value: {
+      coinPnl,
+      usdPnl: coinPnl * F,
+      coinDelta: (s * Q) / (F * F),
+      coinGamma: (s * -2 * Q) / (F * F * F),
+      coinExposure: (s * Q) / F,
+    },
+    assumptions: assumptions('inverse-future'),
+    diagnostics: diagnostics('inverse-future'),
+  });
+}
+
+// ── inverseHedge ────────────────────────────────────────────────────────────────
+
+/** Input for {@link inverseHedge}. */
+export interface InverseHedgeInput {
+  /** The coin delta to neutralize (e.g. `inverseOption.greeks(…).value.coin.delta`). */
+  coinDelta: number;
+  /** Mark price of the inverse future/perp used to hedge (USD per coin; a perp ≈ spot). */
+  markPrice: number;
+  /** Coin gamma of the position being hedged — supply to get the residual gamma after the delta hedge. */
+  coinGamma?: number;
+}
+
+/** The inverse future/perp trade that neutralizes a coin delta. */
+export interface InverseHedge {
+  /** USD notional of the inverse future to trade. */
+  notionalUsd: number;
+  /** Which way to trade it. */
+  side: InverseSide;
+  /** The hedge future's coin delta — equal and opposite to the input `coinDelta` (combined ⇒ 0). */
+  hedgeCoinDelta: number;
+  /** Residual coin gamma after the delta hedge (`positionGamma + hedgeFutureGamma`) — iff `coinGamma` given. */
+  residualCoinGamma?: number;
+}
+
+/**
+ * Size an inverse future/perp to neutralize a coin delta `D`: `notionalUsd = |D|·mark²`, sold if `D > 0`
+ * and bought if `D < 0`, so the hedge's coin delta `s·notionalUsd/mark² = −D` exactly. When the hedged
+ * position's `coinGamma` is supplied, the residual coin gamma after the delta hedge is reported. Assumes
+ * the perp/future mark moves 1:1 with the underlying the coin delta was measured against (exact for a
+ * perp). See `docs/specs/inverse-future.md`.
+ */
+/** EXACT {@link InverseHedgeInput} fields (Law 12) — unknown keys are rejected, never ignored. */
+const INVERSE_HEDGE_KEYS = ['coinDelta', 'markPrice', 'coinGamma'] as const;
+
+export function inverseHedge(input: InverseHedgeInput): Computed<InverseHedge> {
+  const functionName = 'inverseHedge';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, INVERSE_HEDGE_KEYS);
+  ensureFinite(input.coinDelta, 'coinDelta', functionName);
+  ensurePositive(input.markPrice, 'markPrice', functionName);
+
+  const { coinDelta: D, markPrice: F } = input;
+  const notionalUsd = Math.abs(D) * F * F;
+  const side: InverseSide = D > 0 ? 'short' : 'long';
+  const s = side === 'short' ? -1 : 1;
+  // The hedge future's coin delta = s·notionalUsd/F² = −D by construction.
+  const hedgeCoinDelta = (s * notionalUsd) / (F * F);
+
+  const payload: InverseHedge = {
+    notionalUsd,
+    side,
+    hedgeCoinDelta,
+  };
+
+  if (input.coinGamma !== undefined) {
+    ensureFinite(input.coinGamma, 'coinGamma', functionName);
+    const hedgeGamma = (s * -2 * notionalUsd) / (F * F * F);
+    payload.residualCoinGamma = input.coinGamma + hedgeGamma;
+  }
+
+  return finalizeResult(functionName, {
+    value: payload,
+    assumptions: assumptions('inverse-hedge'),
+    diagnostics: diagnostics('inverse-hedge'),
+  });
+}

package/modules/crypto/src/liquidation.ts

@@ -0,0 +1,174 @@
+/**
+ * Isolated-margin **liquidation & bankruptcy prices** for leveraged perpetual/futures positions —
+ * coin-margined (inverse) and USDT-margined (linear) — the most-watched number for a leveraged crypto
+ * trader (spec: `docs/specs/perp-liquidation.md`). Depends only on `@insiderfinance/totalfinance/core`.
+ *
+ * Convention (disclosed in `assumptions`): **isolated** margin; the maintenance margin is assessed on the
+ * position value **at the mark** (the economically exact mark-to-market definition — liquidation is where
+ * account equity first equals the maintenance margin). This differs slightly from the entry-notional
+ * closed forms some venues publish (e.g. BitMEX's `entry/(1+IMR−MMR)`), which assess maintenance on the
+ * ENTRY notional — a few basis points apart. In terms of the initial-margin rate `IMR = 1/leverage` and
+ * the maintenance-margin rate `MMR = m`, the mark-based liquidation prices are:
+ *
+ * ```
+ *   inverse (coin-margined)         linear (USDT-margined)
+ *   long : F₀·(1+m)/(1+IMR)         long : F₀·(1−IMR)/(1−m)
+ *   short: F₀·(1−m)/(1−IMR)         short: F₀·(1+IMR)/(1+m)
+ * ```
+ *
+ * The **bankruptcy price** (equity = 0, all posted margin gone) is the same formula with `m = 0`; it is
+ * always beyond the liquidation price by the maintenance buffer. Both are independent of position size —
+ * they depend only on the entry price, the leverage, the side, and the margin mode.
+ */
+
+import {
+  type Assumptions,
+  CONVENTIONS_VERSION,
+  ensureEnum,
+  ensureFinite,
+  ensureKnownKeys,
+  ensurePositive,
+  ErrorCode,
+  finalizeResult,
+  InputError,
+  requireArgumentObject,
+  type Computed,
+} from '@totalfinance/core';
+import type { InverseSide } from './inverse.js';
+
+const MARGIN_MODES = ['inverse', 'linear'] as const;
+/** Margin mode: `inverse` = coin-margined (Deribit/BitMEX), `linear` = USDT-margined. */
+export type MarginMode = (typeof MARGIN_MODES)[number];
+
+const SIDES = ['long', 'short'] as const;
+
+/** Input for {@link liquidationPrice}. */
+export interface LiquidationInput {
+  /** Margin mode: coin-margined (`inverse`) or USDT-margined (`linear`). */
+  margin: MarginMode;
+  /** Entry (average) price, USD per coin. */
+  entryPrice: number;
+  /** Position leverage (`> 1`); the initial-margin rate is `1/leverage`. */
+  leverage: number;
+  /** Maintenance-margin rate `m` (fraction, e.g. `0.005` = 0.5%). `0 ≤ m < 1`. */
+  maintenanceMarginRate: number;
+  /** Position side. Default `'long'`. */
+  side?: InverseSide;
+}
+
+/** The convention fields {@link liquidationPrice} echoes in `assumptions` (Law 2). */
+export interface LiquidationAssumptions extends Record<string, unknown> {
+  margin: MarginMode;
+  side: InverseSide;
+  maintenanceMarginRate: number;
+  marginBasis: string;
+}
+
+/** Isolated-margin liquidation economics of a leveraged perp/future position. */
+export interface Liquidation {
+  /** Mark price at which account equity first equals the maintenance margin (isolated, at-mark). */
+  liquidationPrice: number;
+  /** Mark price at which equity reaches 0 (all posted margin gone) — beyond `liquidationPrice`. */
+  bankruptcyPrice: number;
+  /** Adverse move to liquidation as a fraction of entry: `|liquidationPrice − entryPrice| / entryPrice`. */
+  distanceToLiquidation: number;
+  /** Initial-margin rate used, `1/leverage`. */
+  initialMarginRate: number;
+}
+
+/** EXACT {@link LiquidationInput} fields (Law 12) — unknown keys are rejected, never ignored. */
+const LIQUIDATION_KEYS = [
+  'margin',
+  'entryPrice',
+  'leverage',
+  'maintenanceMarginRate',
+  'side',
+] as const;
+
+/**
+ * Isolated-margin liquidation & bankruptcy price of a leveraged perpetual/future position (inverse or
+ * linear). Size-independent: depends only on entry price, leverage, maintenance-margin rate, side, and
+ * margin mode. Maintenance is assessed at the mark (see the module doc for the convention and the
+ * closed forms). Requires `leverage > 1` — an isolated liquidation price is degenerate at ≤1×.
+ */
+export function liquidationPrice(
+  input: LiquidationInput,
+): Computed<Liquidation, LiquidationAssumptions> {
+  const functionName = 'liquidationPrice';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, LIQUIDATION_KEYS);
+  ensureEnum(input.margin, MARGIN_MODES, 'margin', functionName);
+  ensurePositive(input.entryPrice, 'entryPrice', functionName);
+  ensureFinite(input.leverage, 'leverage', functionName);
+  if (!(input.leverage > 1)) {
+    throw new InputError(
+      `${functionName}: leverage must be > 1 — an isolated liquidation price is degenerate at ≤1× (a 1× long liquidates only at 0, a 1× inverse short never within margin).`,
+      { code: ErrorCode.InputOutOfRange, context: { leverage: input.leverage } },
+    );
+  }
+  ensureFinite(input.maintenanceMarginRate, 'maintenanceMarginRate', functionName);
+  const m = input.maintenanceMarginRate;
+  if (!(m >= 0 && m < 1)) {
+    throw new InputError(`${functionName}: maintenanceMarginRate must be in [0, 1) — got ${m}.`, {
+      code: ErrorCode.InputOutOfRange,
+      context: { maintenanceMarginRate: m },
+    });
+  }
+  if (input.side !== undefined && input.side !== 'long' && input.side !== 'short') {
+    throw new InputError(
+      `liquidationPrice: side must be 'long' | 'short' when provided. Received ${input.side === null ? 'null' : JSON.stringify(input.side)}.`,
+      { code: ErrorCode.InputInvalidEnum, context: { field: 'side' } },
+    );
+  }
+  const side = input.side ?? 'long';
+  ensureEnum(side, SIDES, 'side', functionName);
+
+  const { entryPrice: F0, margin } = input;
+  const imr = 1 / input.leverage;
+  const isLong = side === 'long';
+
+  // Mark-based isolated liquidation (see module doc); bankruptcy is the same with m = 0.
+  const liq = (mm: number): number =>
+    margin === 'inverse'
+      ? isLong
+        ? (F0 * (1 + mm)) / (1 + imr)
+        : (F0 * (1 - mm)) / (1 - imr)
+      : isLong
+        ? (F0 * (1 - imr)) / (1 - mm)
+        : (F0 * (1 + imr)) / (1 + mm);
+
+  const liquidation = liq(m);
+  const bankruptcy = liq(0);
+
+  return finalizeResult(functionName, {
+    value: {
+      liquidationPrice: liquidation,
+      bankruptcyPrice: bankruptcy,
+      distanceToLiquidation: Math.abs(liquidation - F0) / F0,
+      initialMarginRate: imr,
+    },
+    assumptions: liquidationAssumptions(margin, side, m),
+    diagnostics: {
+      engine: 'perp-liquidation',
+      method: 'closed-form',
+      converged: true,
+      warnings: [],
+    },
+  });
+}
+
+function liquidationAssumptions(
+  margin: MarginMode,
+  side: InverseSide,
+  mmr: number,
+): Assumptions<LiquidationAssumptions> {
+  return {
+    conventionsVersion: CONVENTIONS_VERSION,
+    model: 'perp-liquidation',
+    engine: 'perp-liquidation',
+    margin,
+    side,
+    maintenanceMarginRate: mmr,
+    marginBasis: 'isolated; maintenance assessed at the mark',
+  };
+}