@insiderfinance/totalfinance 0.1.0

package/modules/crypto/dist/curve.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { CONVENTIONS_VERSION, ErrorCode, InputError, ensureKnownKeys, ensureNonNegative, ensurePositive, finalizeResult, requireArgumentArray, requireArgumentObject, } from '../../core/dist/index.js';
+import { futuresBasis } from './carry.js';
+/** Classify the term-structure shape from the forward-carry sequence. */
+function classifyShape(carries, tolerance) {
+    if (carries.length < 2)
+        return 'flat';
+    const min = Math.min(...carries);
+    const max = Math.max(...carries);
+    if (max - min < tolerance)
+        return 'flat';
+    const diffs = [];
+    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, ys, timeToExpiryYears) {
+    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() {
+    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',
+];
+export function carryCurve(input) {
+    const functionName = 'carryCurve';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, CARRY_CURVE_KEYS);
+    ensurePositive(input.spot, 'spot', functionName);
+    requireArgumentArray(functionName, 'futures', input.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 = [];
+    const points = 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 = {
+            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 = [];
+    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 = {
+        spot: input.spot,
+        points,
+        forwards,
+        shape,
+    };
+    if (input.queryTenors !== undefined) {
+        requireArgumentArray(functionName, 'queryTenors', input.queryTenors);
+        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,
+        },
+    });
+}
+//# sourceMappingURL=curve.js.map

package/modules/crypto/dist/curve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"curve.js","sourceRoot":"","sources":["../src/curve.ts"],"names":[],"mappings":"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"}

package/modules/crypto/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@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';
+//# sourceMappingURL=index.d.ts.map

package/modules/crypto/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,GACX,MAAM,YAAY,CAAC"}

package/modules/crypto/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@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 { inverseFuture, inverseHedge } from './inverse.js';
+export { liquidationPrice } from './liquidation.js';
+export { carryCurve } from './curve.js';
+//# sourceMappingURL=index.js.map

package/modules/crypto/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAiBpB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAS3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAQpD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/modules/crypto/dist/inverse.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { type Computed } from '../../core/dist/index.js';
+declare const SIDES: readonly ["long", "short"];
+/** Position side of an inverse contract. */
+export type InverseSide = (typeof SIDES)[number];
+/** 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;
+}
+export declare function inverseFuture(input: InverseFutureInput): Computed<InverseFuture>;
+/** 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;
+}
+export declare function inverseHedge(input: InverseHedgeInput): Computed<InverseHedge>;
+export {};
+//# sourceMappingURL=inverse.d.ts.map

package/modules/crypto/dist/inverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inverse.d.ts","sourceRoot":"","sources":["../src/inverse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAYL,KAAK,QAAQ,EACd,MAAM,0BAAoB,CAAC;AAE5B,QAAA,MAAM,KAAK,4BAA6B,CAAC;AACzC,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAYjD,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,uGAAuG;IACvG,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,SAAS,EAAE,MAAM,CAAC;IAClB,yGAAyG;IACzG,YAAY,EAAE,MAAM,CAAC;CACtB;AAUD,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,QAAQ,CAAC,aAAa,CAAC,CA+BhF;AAID,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,kGAAkG;IAClG,cAAc,EAAE,MAAM,CAAC;IACvB,8GAA8G;IAC9G,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAYD,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,QAAQ,CAAC,YAAY,CAAC,CA+B7E"}

package/modules/crypto/dist/inverse.js

@@ -0,0 +1,89 @@
+/**
+ * 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, CONVENTIONS_VERSION, ensureEnum, ensureFinite, ensureKnownKeys, ensurePositive, finalizeResult, requireArgumentObject, } from '../../core/dist/index.js';
+const SIDES = ['long', 'short'];
+function assumptions(engine) {
+    return { conventionsVersion: CONVENTIONS_VERSION, model: 'inverse-future', engine };
+}
+function diagnostics(engine) {
+    return { engine, method: 'closed-form', converged: true, warnings: [] };
+}
+/**
+ * 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'];
+export function inverseFuture(input) {
+    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'),
+    });
+}
+/**
+ * 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'];
+export function inverseHedge(input) {
+    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 = 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 = {
+        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'),
+    });
+}
+//# sourceMappingURL=inverse.js.map

package/modules/crypto/dist/inverse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inverse.js","sourceRoot":"","sources":["../src/inverse.ts"],"names":[],"mappings":"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"}

package/modules/crypto/dist/liquidation.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 Computed } from '../../core/dist/index.js';
+import type { InverseSide } from './inverse.js';
+declare const MARGIN_MODES: readonly ["inverse", "linear"];
+/** Margin mode: `inverse` = coin-margined (Deribit/BitMEX), `linear` = USDT-margined. */
+export type MarginMode = (typeof MARGIN_MODES)[number];
+/** 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;
+}
+/**
+ * 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 declare function liquidationPrice(input: LiquidationInput): Computed<Liquidation, LiquidationAssumptions>;
+export {};
+//# sourceMappingURL=liquidation.d.ts.map

package/modules/crypto/dist/liquidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquidation.d.ts","sourceRoot":"","sources":["../src/liquidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAWL,KAAK,QAAQ,EACd,MAAM,0BAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,QAAA,MAAM,YAAY,gCAAiC,CAAC;AACpD,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAIvD,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,MAAM,EAAE,UAAU,CAAC;IACnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,uCAAuC;IACvC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,sFAAsF;AACtF,MAAM,WAAW,sBAAuB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrE,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,kGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,eAAe,EAAE,MAAM,CAAC;IACxB,0GAA0G;IAC1G,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8CAA8C;IAC9C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,gBAAgB,GACtB,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC,CA8D/C"}

package/modules/crypto/dist/liquidation.js

@@ -0,0 +1,103 @@
+/**
+ * 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 { CONVENTIONS_VERSION, ensureEnum, ensureFinite, ensureKnownKeys, ensurePositive, ErrorCode, finalizeResult, InputError, requireArgumentObject, } from '../../core/dist/index.js';
+const MARGIN_MODES = ['inverse', 'linear'];
+const SIDES = ['long', 'short'];
+/** EXACT {@link LiquidationInput} fields (Law 12) — unknown keys are rejected, never ignored. */
+const LIQUIDATION_KEYS = [
+    'margin',
+    'entryPrice',
+    'leverage',
+    'maintenanceMarginRate',
+    'side',
+];
+/**
+ * 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) {
+    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) => 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, side, mmr) {
+    return {
+        conventionsVersion: CONVENTIONS_VERSION,
+        model: 'perp-liquidation',
+        engine: 'perp-liquidation',
+        margin,
+        side,
+        maintenanceMarginRate: mmr,
+        marginBasis: 'isolated; maintenance assessed at the mark',
+    };
+}
+//# sourceMappingURL=liquidation.js.map

package/modules/crypto/dist/liquidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquidation.js","sourceRoot":"","sources":["../src/liquidation.ts"],"names":[],"mappings":"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"}

package/modules/crypto/etc/crypto.api.md

@@ -0,0 +1,45 @@
+# @insiderfinance/totalfinance/crypto — public API
+
+> Generated by `tools/api-report`. Do not edit by hand. Run `pnpm api:update` after intentional
+> public API changes; `pnpm api:check` fails on undocumented drift.
+
+## Exports (38)
+
+- `function carryCurve`: (input: CarryCurveInput) => Computed<CarryCurve>
+- `function fundingBasisSpread`: (input: FundingBasisSpreadInput) => Computed<FundingBasisSpread>
+- `function futuresBasis`: (input: FuturesBasisInput) => Computed<FuturesBasis>
+- `function inverseFuture`: (input: InverseFutureInput) => Computed<InverseFuture>
+- `function inverseHedge`: (input: InverseHedgeInput) => Computed<InverseHedge>
+- `function liquidationPrice`: (input: LiquidationInput) => Computed<Liquidation, LiquidationAssumptions>
+- `function optionsBasisSpread`: (input: OptionsBasisSpreadInput) => Computed<OptionsBasisSpread>
+- `function perpetualFunding`: (input: PerpetualFundingInput) => Computed<PerpetualFunding>
+- `function predictedFunding`: (input: PredictedFundingInput) => Computed<PredictedFunding>
+- `interface CarryCurve`: CarryCurve
+- `interface CarryCurveFuture`: CarryCurveFuture
+- `interface CarryCurveInput`: CarryCurveInput
+- `interface CarryCurvePoint`: CarryCurvePoint
+- `interface CarryForward`: CarryForward
+- `interface CarryInterp`: CarryInterp
+- `interface FundingBasisSpread`: FundingBasisSpread
+- `interface FundingBasisSpreadInput`: FundingBasisSpreadInput
+- `interface FuturesBasis`: FuturesBasis
+- `interface FuturesBasisInput`: FuturesBasisInput
+- `interface InverseFuture`: InverseFuture
+- `interface InverseFutureInput`: InverseFutureInput
+- `interface InverseHedge`: InverseHedge
+- `interface InverseHedgeInput`: InverseHedgeInput
+- `interface Liquidation`: Liquidation
+- `interface LiquidationAssumptions`: LiquidationAssumptions
+- `interface LiquidationInput`: LiquidationInput
+- `interface OptionsBasisSpread`: OptionsBasisSpread
+- `interface OptionsBasisSpreadInput`: OptionsBasisSpreadInput
+- `interface PerpetualFunding`: PerpetualFunding
+- `interface PerpetualFundingInput`: PerpetualFundingInput
+- `interface PredictedFunding`: PredictedFunding
+- `interface PredictedFundingInput`: PredictedFundingInput
+- `type BasisStructure`: BasisStructure
+- `type CarryCurveShape`: CarryCurveShape
+- `type CarrySignal`: CarrySignal
+- `type InverseSide`: 'long' | 'short'
+- `type MarginMode`: 'inverse' | 'linear'
+- `type OptionsCarrySignal`: OptionsCarrySignal