@katanaperps/katana-perps-sdk 2.1.0-beta.13 → 2.1.0-beta.14

package/dist/orderbook/buySellPanelEstimate.js

@@ -0,0 +1,713 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateBuySellPanelEstimate = void 0;
+const _pipmath_1 = require("#pipmath");
+const quantities_1 = require("#orderbook/quantities");
+const request_1 = require("#types/enums/request");
+/**
+ * The taker (trade fee + gas fee) on a single fill is limited to 5% of the
+ * fill's quote quantity.
+ *
+ * @see {@link https://github.com/idexio/idex-contracts-ikon} (contracts)
+ */
+const maximumTradeFeeFraction = (0, _pipmath_1.decimalToPip)('0.05');
+function makeEmptyEstimate() {
+    return {
+        tradeBaseQuantity: BigInt(0),
+        tradeQuoteQuantity: BigInt(0),
+        makerBaseQuantity: BigInt(0),
+        cost: BigInt(0),
+        liquidationPrice: null,
+        selfTradeEncountered: false,
+        freeCollateralExceeded: false,
+        availableCollateralExceeded: false,
+        executionPriceLimitExceeded: false,
+        maximumPositionSizeExceeded: false,
+        postOnlyWouldCross: false,
+        fillOrKillWouldNotExecute: false,
+        reduceOnlyWouldNotReducePosition: false,
+        reduceOnlyNoOpenPosition: false,
+        reduceOnlyOpenPositionSizeExceeded: false,
+    };
+}
+/**
+ * @private
+ */
+function wasPositionReduced(before, after) {
+    return (after === BigInt(0) ||
+        (before > BigInt(0) && after > BigInt(0) && after < before) ||
+        (before < BigInt(0) && after < BigInt(0) && after > before));
+}
+/**
+ * @private
+ * Margin requirement (held collateral) for a single open order quantity.
+ */
+function calculateMarginRequirementForOpenOrderQuantity(context, openBaseQuantity, limitPrice) {
+    if (openBaseQuantity === BigInt(0)) {
+        return BigInt(0);
+    }
+    const orderOpenQuoteQuantity = (0, _pipmath_1.multiplyPips)(openBaseQuantity, limitPrice);
+    return (0, _pipmath_1.multiplyPips)(orderOpenQuoteQuantity, (0, quantities_1.calculateInitialMarginFractionWithOverride)({
+        baseQuantity: openBaseQuantity,
+        initialMarginFractionOverride: context.initialMarginFractionOverride,
+        leverageParameters: context.leverageParameters,
+    }));
+}
+/**
+ * @private
+ * Held collateral required for a set of standing orders in a single market,
+ * given a signed position quantity. Orders that reduce the position do not
+ * require margin, up to a combined quantity that equals the position size.
+ */
+function calculateHeldCollateralForMarket(context, orders, positionQuantity) {
+    let marginRequirement = BigInt(0);
+    // The reducing side (sells for a long position, buys for a short position),
+    // processed best price first, offsets against the position.
+    const positionIsLong = positionQuantity > BigInt(0);
+    const reducingOrders = orders
+        .filter((order) => order.isBuy === !positionIsLong && order.openQuantity > BigInt(0))
+        .sort((a, b) => 
+    // Sells: lowest price first; buys: highest price first
+    a.isBuy ? Number(b.price - a.price) : Number(a.price - b.price));
+    const nonReducingOrders = orders.filter((order) => order.isBuy === positionIsLong && order.openQuantity > BigInt(0));
+    let remainingPositionQuantity = (0, _pipmath_1.absBigInt)(positionQuantity);
+    for (const order of reducingOrders) {
+        let openBaseQuantity = order.openQuantity;
+        if (remainingPositionQuantity > BigInt(0)) {
+            if (openBaseQuantity > remainingPositionQuantity) {
+                openBaseQuantity -= remainingPositionQuantity;
+                remainingPositionQuantity = BigInt(0);
+            }
+            else {
+                remainingPositionQuantity -= openBaseQuantity;
+                openBaseQuantity = BigInt(0);
+            }
+        }
+        marginRequirement += calculateMarginRequirementForOpenOrderQuantity(context, openBaseQuantity, order.price);
+    }
+    for (const order of nonReducingOrders) {
+        marginRequirement += calculateMarginRequirementForOpenOrderQuantity(context, order.openQuantity, order.price);
+    }
+    return marginRequirement;
+}
+/**
+ * @private
+ * Solves for the index price at which the account's value equals its
+ * maintenance margin requirement (the liquidation price), holding the index
+ * prices of all other markets constant (cross-margin, account-wide).
+ *
+ * Returns `null` if the resulting position is zero, and `0n` if no positive
+ * liquidation price exists (the account is not liquidatable by an adverse
+ * move).
+ */
+function calculateLiquidationPrice(args) {
+    const { newPositionQuantity, maintenanceMarginFraction, quoteBalanceAfter, otherPositionsNotionalAtIndex, otherPositionsMaintenanceMarginRequirement, } = args;
+    if (newPositionQuantity === BigInt(0)) {
+        return null;
+    }
+    // accountValue(P) = MMR(P), solved for P (in pips):
+    //   P = (otherMMR - otherNotional - quoteBalance) * oneInPips^2
+    //       / (newQty * oneInPips - abs(newQty) * mmf)
+    const numerator = (otherPositionsMaintenanceMarginRequirement -
+        otherPositionsNotionalAtIndex -
+        quoteBalanceAfter) *
+        _pipmath_1.oneInPips *
+        _pipmath_1.oneInPips;
+    const denominator = newPositionQuantity * _pipmath_1.oneInPips -
+        (0, _pipmath_1.absBigInt)(newPositionQuantity) * maintenanceMarginFraction;
+    if (denominator === BigInt(0)) {
+        return BigInt(0);
+    }
+    const liquidationPrice = numerator / denominator;
+    return liquidationPrice > BigInt(0) ? liquidationPrice : BigInt(0);
+}
+/**
+ * @private
+ * Walks the maker side of the book, accumulating the crossing (trade) portion
+ * of the taker order, distinguishing the wallet's own resting liquidity
+ * (self-trades) from other liquidity, and applying execution price limits and
+ * taker fees.
+ */
+function matchTakerOrder(context, quantity, reduceOnlyMaximumBaseQuantity) {
+    const isQuantityInQuote = 'quoteQuantity' in quantity;
+    // Working copy of own maker-side resting liquidity, indexed by price.
+    const standingOrdersCopy = context.marketStandingOrders.map((order) => ({
+        ...order,
+    }));
+    const ownMakerOrdersByPrice = new Map();
+    for (const order of standingOrdersCopy) {
+        if (order.isBuy !== context.isBuy && order.openQuantity > BigInt(0)) {
+            const list = ownMakerOrdersByPrice.get(order.price) ?? [];
+            list.push(order);
+            ownMakerOrdersByPrice.set(order.price, list);
+        }
+    }
+    const result = {
+        tradeBaseQuantity: BigInt(0),
+        tradeQuoteQuantity: BigInt(0),
+        makerOrdersMatched: BigInt(0),
+        takerTradeFee: BigInt(0),
+        takerGasFee: BigInt(0),
+        selfTradeBaseQuantity: BigInt(0),
+        selfTradeEncountered: false,
+        executionPriceLimitExceeded: false,
+        standingOrdersAfterSelfTrade: standingOrdersCopy,
+        remainingBaseQuantity: BigInt(0),
+    };
+    let remainingBase = isQuantityInQuote ? null : quantity.baseQuantity;
+    let remainingQuote = isQuantityInQuote ? quantity.quoteQuantity : null;
+    // Tracks reduce-only fill capacity (real, position-reducing fills only)
+    let remainingReduceOnly = reduceOnlyMaximumBaseQuantity;
+    for (const level of context.makerLevels) {
+        // doOrdersMatch
+        if (!context.isMarketOrder) {
+            const crosses = context.isBuy ?
+                context.limitPrice >= level.price
+                : context.limitPrice <= level.price;
+            if (!crosses) {
+                break;
+            }
+        }
+        // Execution price limit (market orders)
+        if ((context.minimumExecutionPrice !== null &&
+            level.price < context.minimumExecutionPrice) ||
+            (context.maximumExecutionPrice !== null &&
+                level.price > context.maximumExecutionPrice)) {
+            result.executionPriceLimitExceeded = true;
+            break;
+        }
+        const exhausted = remainingBase !== null ?
+            remainingBase <= BigInt(0)
+            : remainingQuote <= BigInt(0);
+        if (exhausted) {
+            break;
+        }
+        // Determine how much of this level the taker consumes.
+        let consumedBase;
+        if (remainingBase !== null) {
+            consumedBase = (0, _pipmath_1.minBigInt)(remainingBase, level.size);
+        }
+        else {
+            const levelQuoteIfFull = (0, _pipmath_1.multiplyPips)(level.size, level.price, context.isMarketOrder && context.isBuy);
+            if (levelQuoteIfFull <= remainingQuote) {
+                consumedBase = level.size;
+            }
+            else {
+                // Partial: reduce base proportionally to the quote budget
+                consumedBase = (level.size * remainingQuote) / levelQuoteIfFull;
+            }
+        }
+        // Split into self-trade (own liquidity) and real fill (other liquidity).
+        const ownOrders = ownMakerOrdersByPrice.get(level.price) ?? [];
+        let ownSizeAtLevel = BigInt(0);
+        for (const order of ownOrders) {
+            ownSizeAtLevel += order.openQuantity;
+        }
+        const selfPart = (0, _pipmath_1.minBigInt)(consumedBase, ownSizeAtLevel);
+        let realPart = consumedBase - selfPart;
+        // Reduce-only orders may only reduce the position; cap the real fill.
+        if (remainingReduceOnly !== null && realPart > remainingReduceOnly) {
+            realPart = (0, _pipmath_1.maxBigInt)(remainingReduceOnly, BigInt(0));
+            // The self-trade portion is unaffected by reduce-only fill capacity, but
+            // the order stops once its reduce-only capacity is consumed.
+            consumedBase = selfPart + realPart;
+        }
+        if (selfPart > BigInt(0)) {
+            result.selfTradeEncountered = true;
+            result.selfTradeBaseQuantity += selfPart;
+            // Reduce the wallet's own resting orders at this price.
+            let toReduce = selfPart;
+            for (const order of ownOrders) {
+                if (toReduce <= BigInt(0)) {
+                    break;
+                }
+                const reduction = (0, _pipmath_1.minBigInt)(order.openQuantity, toReduce);
+                order.openQuantity -= reduction;
+                toReduce -= reduction;
+            }
+        }
+        if (realPart > BigInt(0)) {
+            const realQuote = (0, _pipmath_1.multiplyPips)(realPart, level.price, context.isMarketOrder && context.isBuy);
+            if (realQuote === BigInt(0)) {
+                // Sub-pip quote quantity is invalid; the engine rejects such trades.
+                break;
+            }
+            result.tradeBaseQuantity += realPart;
+            result.tradeQuoteQuantity += realQuote;
+            // Taker fees for this fill. The sum of the trade and gas fee is capped at
+            // 5% of the fill's quote quantity, with priority given to the trade fee:
+            // the trade fee is capped at 5%, and the gas fee may only consume whatever
+            // of the 5% budget the trade fee leaves (zero once the trade fee hits 5%).
+            const maxFee = (0, _pipmath_1.multiplyPips)(realQuote, maximumTradeFeeFraction);
+            const tradeFee = (0, _pipmath_1.minBigInt)((0, _pipmath_1.multiplyPips)(realQuote, context.takerFeeRate), maxFee);
+            const realSizeAtLevel = (0, _pipmath_1.maxBigInt)(level.size - ownSizeAtLevel, BigInt(0));
+            const ordersAtLevel = realSizeAtLevel <= BigInt(0) ?
+                BigInt(0)
+                : (0, _pipmath_1.maxBigInt)(BigInt(1), (BigInt(level.numOrders) * realPart + realSizeAtLevel - BigInt(1)) /
+                    realSizeAtLevel);
+            const gasFee = (0, _pipmath_1.minBigInt)(context.gasFeePerOrder * ordersAtLevel, (0, _pipmath_1.maxBigInt)(maxFee - tradeFee, BigInt(0)));
+            result.makerOrdersMatched += ordersAtLevel;
+            result.takerTradeFee += tradeFee;
+            result.takerGasFee += gasFee;
+            if (remainingReduceOnly !== null) {
+                remainingReduceOnly -= realPart;
+            }
+        }
+        // Consume the taker order's remaining budget (self-trades consume it too).
+        if (remainingBase !== null) {
+            remainingBase -= consumedBase;
+        }
+        else {
+            remainingQuote -= (0, _pipmath_1.multiplyPips)(consumedBase, level.price, context.isMarketOrder && context.isBuy);
+        }
+        if (remainingReduceOnly !== null && remainingReduceOnly <= BigInt(0)) {
+            break;
+        }
+    }
+    result.remainingBaseQuantity =
+        remainingBase !== null ? (0, _pipmath_1.maxBigInt)(remainingBase, BigInt(0)) : BigInt(0);
+    return result;
+}
+/**
+ * @private
+ * Produces a complete estimate for a concrete base or quote quantity.
+ */
+function runEstimate(context, quantity) {
+    const estimate = makeEmptyEstimate();
+    // Reduce-only validity and fill capacity.
+    let reduceOnlyMaximumBaseQuantity = null;
+    if (context.reduceOnly) {
+        const positionQuantity = context.currentPositionQuantity;
+        if (positionQuantity === BigInt(0)) {
+            estimate.reduceOnlyNoOpenPosition = true;
+            return estimate;
+        }
+        const reduces = (context.isBuy && positionQuantity < BigInt(0)) ||
+            (!context.isBuy && positionQuantity > BigInt(0));
+        if (!reduces) {
+            estimate.reduceOnlyWouldNotReducePosition = true;
+            return estimate;
+        }
+        reduceOnlyMaximumBaseQuantity = (0, _pipmath_1.absBigInt)(positionQuantity);
+    }
+    // Post-only (gtx) orders may not cross the spread.
+    const bestMakerPrice = context.makerLevels.length > 0 ? context.makerLevels[0].price : null;
+    const crossesSpread = bestMakerPrice !== null &&
+        (context.isMarketOrder ||
+            (context.isBuy ?
+                context.limitPrice >= bestMakerPrice
+                : context.limitPrice <= bestMakerPrice));
+    if (context.timeInForce === request_1.TimeInForce.gtx && crossesSpread) {
+        estimate.postOnlyWouldCross = true;
+        return estimate;
+    }
+    // Limit orders are rejected if their price is outside the allowed range.
+    if (context.limitOrderPriceExceedsLimit) {
+        estimate.executionPriceLimitExceeded = true;
+        return estimate;
+    }
+    const fill = matchTakerOrder(context, quantity, reduceOnlyMaximumBaseQuantity);
+    estimate.selfTradeEncountered = fill.selfTradeEncountered;
+    estimate.executionPriceLimitExceeded = fill.executionPriceLimitExceeded;
+    // Fill-or-kill: the order must be fully filled by crossing liquidity.
+    if (context.timeInForce === request_1.TimeInForce.fok) {
+        const requestedFilled = 'baseQuantity' in quantity ?
+            fill.tradeBaseQuantity + fill.selfTradeBaseQuantity >=
+                quantity.baseQuantity
+            : fill.tradeQuoteQuantity +
+                (0, _pipmath_1.multiplyPips)(fill.selfTradeBaseQuantity, context.indexPrice) >=
+                quantity.quoteQuantity;
+        if (!requestedFilled) {
+            estimate.fillOrKillWouldNotExecute = true;
+            return estimate;
+        }
+    }
+    estimate.tradeBaseQuantity = fill.tradeBaseQuantity;
+    estimate.tradeQuoteQuantity = fill.tradeQuoteQuantity;
+    // Determine the resting (maker) portion. Reduce-only limit orders may rest on
+    // the books (their reducing portion); whether the resting quantity is valid is
+    // checked below via `reduceOnlyOpenPositionSizeExceeded`.
+    const canRest = !context.isMarketOrder &&
+        (context.timeInForce === request_1.TimeInForce.gtc ||
+            context.timeInForce === request_1.TimeInForce.gtx);
+    let makerBaseQuantity = BigInt(0);
+    if (canRest) {
+        if ('baseQuantity' in quantity) {
+            makerBaseQuantity = fill.remainingBaseQuantity;
+        }
+        else {
+            // Convert the remaining quote budget to base at the limit price.
+            const remainingQuote = (0, _pipmath_1.maxBigInt)(quantity.quoteQuantity -
+                fill.tradeQuoteQuantity -
+                (0, _pipmath_1.multiplyPips)(fill.selfTradeBaseQuantity, context.limitPrice), BigInt(0));
+            makerBaseQuantity =
+                context.limitPrice > BigInt(0) ?
+                    (0, _pipmath_1.dividePips)(remainingQuote, context.limitPrice)
+                    : BigInt(0);
+        }
+    }
+    estimate.makerBaseQuantity = makerBaseQuantity;
+    // A reduce-only order's resting (maker) quantity may not exceed the open
+    // position size that remains after the reducing fills (it would otherwise no
+    // longer be fully reducing). A zero remaining position with a resting quantity
+    // (i.e. the position is closed) is likewise flagged.
+    if (context.reduceOnly && makerBaseQuantity > BigInt(0)) {
+        const remainingOpenPositionSize = (0, _pipmath_1.absBigInt)(context.currentPositionQuantity) - fill.tradeBaseQuantity;
+        if (makerBaseQuantity > remainingOpenPositionSize) {
+            estimate.reduceOnlyOpenPositionSizeExceeded = true;
+        }
+    }
+    // Resulting position quantity in the order's market.
+    const newPositionQuantity = context.isBuy ?
+        context.currentPositionQuantity + fill.tradeBaseQuantity
+        : context.currentPositionQuantity - fill.tradeBaseQuantity;
+    // Quote balance after the trade.
+    const totalFees = fill.takerTradeFee + fill.takerGasFee;
+    const quoteBalanceAfter = context.isBuy ?
+        context.quoteBalance - fill.tradeQuoteQuantity - totalFees
+        : context.quoteBalance + fill.tradeQuoteQuantity - totalFees;
+    // Account value (equity) after the trade, holding other markets constant.
+    const equityAfter = quoteBalanceAfter +
+        (0, _pipmath_1.multiplyPips)(newPositionQuantity, context.indexPrice) +
+        (context.otherPositionsNotionalAtIndex -
+            (0, _pipmath_1.multiplyPips)(context.currentPositionQuantity, context.indexPrice));
+    // Initial margin requirement after the trade.
+    const newPositionNotional = (0, _pipmath_1.multiplyPips)((0, _pipmath_1.absBigInt)(newPositionQuantity), context.indexPrice);
+    const newPositionInitialMarginRequirement = (0, _pipmath_1.multiplyPips)(newPositionNotional, (0, quantities_1.calculateInitialMarginFractionWithOverride)({
+        baseQuantity: newPositionQuantity,
+        initialMarginFractionOverride: context.initialMarginFractionOverride,
+        leverageParameters: context.leverageParameters,
+    }));
+    const initialMarginRequirementAfter = context.initialMarginRequirement -
+        context.currentInitialMarginRequirement +
+        newPositionInitialMarginRequirement;
+    // Maintenance margin requirement after the trade.
+    const currentMaintenanceMarginRequirement = (0, _pipmath_1.multiplyPips)((0, _pipmath_1.multiplyPips)((0, _pipmath_1.absBigInt)(context.currentPositionQuantity), context.indexPrice), context.maintenanceMarginFraction);
+    const newPositionMaintenanceMarginRequirement = (0, _pipmath_1.multiplyPips)(newPositionNotional, context.maintenanceMarginFraction);
+    const otherPositionsMaintenanceMarginRequirement = (0, _pipmath_1.maxBigInt)(context.totalMaintenanceMarginRequirement -
+        currentMaintenanceMarginRequirement, BigInt(0));
+    // Held collateral after the trade: only this market's orders are affected
+    // (by the position change, the new resting order, and self-trade reductions).
+    const heldBeforeForMarket = calculateHeldCollateralForMarket(context, context.marketStandingOrders, context.currentPositionQuantity);
+    const standingOrdersAfter = fill.standingOrdersAfterSelfTrade.slice();
+    if (makerBaseQuantity > BigInt(0)) {
+        standingOrdersAfter.push({
+            isBuy: context.isBuy,
+            price: context.limitPrice,
+            openQuantity: makerBaseQuantity,
+        });
+    }
+    const heldAfterForMarket = calculateHeldCollateralForMarket(context, standingOrdersAfter, newPositionQuantity);
+    const totalHeldCollateralAfter = context.totalHeldCollateral - heldBeforeForMarket + heldAfterForMarket;
+    // Collateral measures (unclamped values are used for feasibility flags).
+    const freeCollateralBefore = (0, _pipmath_1.maxBigInt)(context.equity - context.initialMarginRequirement, BigInt(0));
+    const availableCollateralBefore = (0, _pipmath_1.maxBigInt)(freeCollateralBefore - context.totalHeldCollateral, BigInt(0));
+    const freeCollateralAfterUnclamped = equityAfter - initialMarginRequirementAfter;
+    const freeCollateralAfter = (0, _pipmath_1.maxBigInt)(freeCollateralAfterUnclamped, BigInt(0));
+    // Available collateral after the order is intentionally NOT clamped at zero:
+    // `cost` is allowed to exceed the wallet's available collateral (e.g. an order
+    // whose margin or held-collateral requirement is greater than the wallet can
+    // cover), consistent with the feasibility flags, which also reflect unclamped
+    // values.
+    const availableCollateralAfter = freeCollateralAfterUnclamped - totalHeldCollateralAfter;
+    estimate.cost = availableCollateralBefore - availableCollateralAfter;
+    // Liquidation price (cross-margin, account-wide).
+    estimate.liquidationPrice = calculateLiquidationPrice({
+        newPositionQuantity,
+        maintenanceMarginFraction: context.maintenanceMarginFraction,
+        quoteBalanceAfter,
+        otherPositionsNotionalAtIndex: context.otherPositionsNotionalAtIndex -
+            (0, _pipmath_1.multiplyPips)(context.currentPositionQuantity, context.indexPrice),
+        otherPositionsMaintenanceMarginRequirement,
+    });
+    // Feasibility flags.
+    //
+    // `freeCollateralExceeded` covers the crossing (trade) portion: the initial
+    // margin requirement must be met after a trade that increases a position, and
+    // the maintenance margin requirement after a trade that reduces it.
+    if (crossesSpread && fill.tradeBaseQuantity > BigInt(0)) {
+        const positionReduced = wasPositionReduced(context.currentPositionQuantity, newPositionQuantity);
+        estimate.freeCollateralExceeded =
+            positionReduced ?
+                equityAfter -
+                    (otherPositionsMaintenanceMarginRequirement +
+                        newPositionMaintenanceMarginRequirement) <
+                    BigInt(0)
+                : freeCollateralAfterUnclamped < BigInt(0);
+    }
+    // `availableCollateralExceeded` covers any resting (maker) portion: its held
+    // collateral may not exceed the wallet's available collateral. This applies
+    // both to non-crossing orders and to the unfilled remainder of an order that
+    // partially crossed the spread.
+    if (makerBaseQuantity > BigInt(0)) {
+        estimate.availableCollateralExceeded =
+            freeCollateralAfter - totalHeldCollateralAfter < BigInt(0);
+    }
+    // Maximum position size. Check the order's requested quantity against the
+    // room left by the current position (`maximumPositionSize` ∓ position).
+    if (!context.reduceOnly) {
+        const maxAdditionalLiquidity = context.isBuy ?
+            context.maximumPositionSize - context.currentPositionQuantity
+            : context.maximumPositionSize + context.currentPositionQuantity;
+        // For quote-denominated orders the requested base quantity is not fixed; the
+        // realized base (fills + resting + self-trade) is used as a proxy.
+        const orderBaseQuantity = 'baseQuantity' in quantity ?
+            quantity.baseQuantity
+            : fill.tradeBaseQuantity + fill.selfTradeBaseQuantity + makerBaseQuantity;
+        if (context.isMarketOrder || crossesSpread) {
+            // Market and crossing limit orders are checked against the order quantity
+            // alone; the wallet's other standing orders may be canceled after the
+            // incoming order is executed if the sum of all standing orders exceeds
+            // the maximum position size.
+            if (orderBaseQuantity > maxAdditionalLiquidity) {
+                estimate.maximumPositionSizeExceeded = true;
+            }
+        }
+        else {
+            // A non-crossing (resting) limit order must fit alongside the wallet's
+            // other same-side standing orders without collectively exceeding the
+            // maximum position.
+            let sameSideActiveQuantity = BigInt(0);
+            for (const order of context.marketStandingOrders) {
+                if (order.isBuy === context.isBuy) {
+                    sameSideActiveQuantity += order.openQuantity;
+                }
+            }
+            if (sameSideActiveQuantity + orderBaseQuantity > maxAdditionalLiquidity) {
+                estimate.maximumPositionSizeExceeded = true;
+            }
+        }
+    }
+    return estimate;
+}
+/**
+ * @private
+ * Resolves the slider input (a fraction of available collateral to consume)
+ * into a base quantity, by searching for the largest base quantity whose
+ * estimated cost does not exceed the target.
+ */
+function resolveBaseQuantityForCollateralRatio(context, ratio) {
+    const freeCollateralBefore = (0, _pipmath_1.maxBigInt)(context.equity - context.initialMarginRequirement, BigInt(0));
+    const availableCollateralBefore = (0, _pipmath_1.maxBigInt)(freeCollateralBefore - context.totalHeldCollateral, BigInt(0));
+    const targetCost = (0, _pipmath_1.multiplyPips)(availableCollateralBefore, ratio);
+    if (targetCost <= BigInt(0)) {
+        return BigInt(0);
+    }
+    // Upper bound: all matchable liquidity, plus resting capacity for limit
+    // orders that may add to the books.
+    let matchableBase = BigInt(0);
+    for (const level of context.makerLevels) {
+        if (!context.isMarketOrder) {
+            const crosses = context.isBuy ?
+                context.limitPrice >= level.price
+                : context.limitPrice <= level.price;
+            if (!crosses) {
+                break;
+            }
+        }
+        if ((context.minimumExecutionPrice !== null &&
+            level.price < context.minimumExecutionPrice) ||
+            (context.maximumExecutionPrice !== null &&
+                level.price > context.maximumExecutionPrice)) {
+            break;
+        }
+        matchableBase += level.size;
+    }
+    const canRest = !context.isMarketOrder &&
+        (context.timeInForce === request_1.TimeInForce.gtc ||
+            context.timeInForce === request_1.TimeInForce.gtx);
+    const restingCapacity = canRest ?
+        (0, _pipmath_1.maxBigInt)(context.maximumPositionSize +
+            (0, _pipmath_1.absBigInt)(context.currentPositionQuantity), BigInt(0))
+        : BigInt(0);
+    let high = matchableBase + restingCapacity;
+    if (high <= BigInt(0)) {
+        return BigInt(0);
+    }
+    // The slider seeks the largest quantity that (a) does not exceed the target
+    // cost and (b) remains feasible (does not breach the wallet's collateral).
+    //
+    // The feasibility gate is essential, not merely a cost comparison: `cost` is
+    // clamped at the available collateral (available-after cannot go below zero),
+    // so at a 100% slider the target equals that ceiling and a cost-only check
+    // (`cost <= target`) is satisfied by *every* larger quantity on the clamped
+    // "plateau" — which made the search walk all the way to `high` (matching all
+    // liquidity, or all liquidity up to the limit price). A quantity past the
+    // boundary sets freeCollateral/availableCollateralExceeded, which excludes the
+    // plateau and yields the largest quantity that drives available collateral to
+    // ~zero while remaining acceptable.
+    const isAcceptable = (baseQuantity) => {
+        const e = runEstimate(context, { baseQuantity });
+        return (e.cost <= targetCost &&
+            !e.freeCollateralExceeded &&
+            !e.availableCollateralExceeded);
+    };
+    // If even the maximum quantity is acceptable (e.g. liquidity- or
+    // position-size-limited so the target cost is never reached), return it.
+    if (isAcceptable(high)) {
+        return high;
+    }
+    let low = BigInt(0);
+    for (let iteration = 0; iteration < 80; iteration += 1) {
+        if (high - low <= BigInt(1)) {
+            break;
+        }
+        const mid = (low + high) / BigInt(2);
+        if (isAcceptable(mid)) {
+            low = mid;
+        }
+        else {
+            high = mid;
+        }
+    }
+    return low;
+}
+function buildContext(args) {
+    const { market, wallet, order } = args;
+    const { side } = order;
+    const isBuy = side === request_1.OrderSide.buy;
+    const isMarketOrder = typeof order.limitPrice === 'undefined';
+    const limitPrice = order.limitPrice ?? BigInt(0);
+    const timeInForce = order.timeInForce ?? request_1.TimeInForce.gtc;
+    const reduceOnly = order.reduceOnly ?? false;
+    const indexPrice = (0, _pipmath_1.decimalToPip)(market.indexPrice);
+    const leverageParameters = (0, quantities_1.convertToLeverageParametersBigInt)(market);
+    const maximumPositionSize = (0, _pipmath_1.decimalToPip)(market.maximumPositionSize);
+    const maintenanceMarginFraction = (0, _pipmath_1.decimalToPip)(market.maintenanceMarginFraction);
+    const overrideDecimal = (args.walletInitialMarginFractionOverrides ?? []).find((imfo) => imfo.market === market.market)?.initialMarginFractionOverride;
+    const initialMarginFractionOverride = typeof overrideDecimal === 'string' ? (0, _pipmath_1.decimalToPip)(overrideDecimal) : null;
+    // The wallet's effective taker fee rate already reflects the lowest of the
+    // exchange, market, and wallet rates.
+    const takerFeeRate = (0, _pipmath_1.decimalToPip)(wallet.takerFeeRate);
+    const gasFeePerOrder = args.takerTradeGasFee ?? BigInt(0);
+    // Maker-side order book levels, best price first.
+    const makerLevels = (isBuy ? args.orderBook.asks : args.orderBook.bids)
+        .filter((level) => level.size > BigInt(0))
+        .slice()
+        .sort((a, b) => isBuy ? Number(a.price - b.price) : Number(b.price - a.price));
+    // Execution price limits.
+    const bestAsk = args.orderBook.asks.length > 0 ? args.orderBook.asks[0].price : null;
+    const bestBid = args.orderBook.bids.length > 0 ? args.orderBook.bids[0].price : null;
+    const baselinePrice = bestAsk !== null && bestBid !== null ?
+        (bestAsk + bestBid) / BigInt(2)
+        : indexPrice;
+    const marketOrderExecutionPriceLimit = (0, _pipmath_1.decimalToPip)(market.marketOrderExecutionPriceLimit);
+    let minimumExecutionPrice = null;
+    let maximumExecutionPrice = null;
+    if (isMarketOrder &&
+        marketOrderExecutionPriceLimit > BigInt(0) &&
+        baselinePrice > BigInt(0)) {
+        minimumExecutionPrice = (0, _pipmath_1.multiplyPips)(baselinePrice, _pipmath_1.oneInPips - marketOrderExecutionPriceLimit);
+        maximumExecutionPrice = (0, _pipmath_1.dividePips)(baselinePrice, _pipmath_1.oneInPips - marketOrderExecutionPriceLimit);
+    }
+    const limitOrderExecutionPriceLimit = (0, _pipmath_1.decimalToPip)(market.limitOrderExecutionPriceLimit);
+    let limitOrderPriceExceedsLimit = false;
+    if (!isMarketOrder &&
+        limitOrderExecutionPriceLimit > BigInt(0) &&
+        baselinePrice > BigInt(0)) {
+        const minimumLimitPrice = (0, _pipmath_1.multiplyPips)(baselinePrice, _pipmath_1.oneInPips - limitOrderExecutionPriceLimit);
+        const maximumLimitPrice = (0, _pipmath_1.dividePips)(baselinePrice, _pipmath_1.oneInPips - limitOrderExecutionPriceLimit);
+        limitOrderPriceExceedsLimit =
+            limitPrice < minimumLimitPrice || limitPrice > maximumLimitPrice;
+    }
+    // The wallet's resting limit orders in the order's market. Untriggered stop
+    // orders have the `active` status; they are excluded because they cannot be
+    // matched or self-traded and do not require held collateral.
+    const restingOrderStatuses = ['open', 'partiallyFilled'];
+    const marketStandingOrders = (args.walletsStandingOrders ?? [])
+        .filter((standingOrder) => standingOrder.market === market.market &&
+        typeof standingOrder.price !== 'undefined' &&
+        restingOrderStatuses.includes(standingOrder.status))
+        .map((standingOrder) => ({
+        isBuy: standingOrder.side === request_1.OrderSide.buy,
+        // The filter above guarantees a defined price.
+        price: (0, _pipmath_1.decimalToPip)(standingOrder.price ?? '0'),
+        openQuantity: (0, _pipmath_1.decimalToPip)(standingOrder.originalQuantity) -
+            (0, _pipmath_1.decimalToPip)(standingOrder.executedQuantity),
+    }))
+        .filter((standingOrder) => standingOrder.openQuantity > BigInt(0));
+    // Position and account-level aggregates.
+    const positions = wallet.positions ?? [];
+    const equity = (0, _pipmath_1.decimalToPip)(wallet.equity);
+    const quoteBalance = (0, _pipmath_1.decimalToPip)(wallet.quoteBalance);
+    const totalHeldCollateral = (0, _pipmath_1.decimalToPip)(wallet.heldCollateral);
+    let initialMarginRequirement = BigInt(0);
+    let currentPositionQuantity = BigInt(0);
+    let currentInitialMarginRequirement = BigInt(0);
+    for (const position of positions) {
+        initialMarginRequirement += (0, _pipmath_1.decimalToPip)(position.marginRequirement);
+        if (position.market === market.market) {
+            currentPositionQuantity = (0, _pipmath_1.decimalToPip)(position.quantity);
+            currentInitialMarginRequirement = (0, _pipmath_1.decimalToPip)(position.marginRequirement);
+        }
+    }
+    const totalMaintenanceMarginRequirement = (0, _pipmath_1.multiplyPips)((0, _pipmath_1.decimalToPip)(wallet.marginRatio), equity);
+    // Σ (every position's notional at index price) == equity - quoteBalance
+    const otherPositionsNotionalAtIndex = equity - quoteBalance;
+    return {
+        side,
+        isBuy,
+        isMarketOrder,
+        limitPrice,
+        timeInForce,
+        reduceOnly,
+        indexPrice,
+        leverageParameters,
+        maximumPositionSize,
+        initialMarginFractionOverride,
+        maintenanceMarginFraction,
+        takerFeeRate,
+        gasFeePerOrder,
+        makerLevels,
+        minimumExecutionPrice,
+        maximumExecutionPrice,
+        limitOrderPriceExceedsLimit,
+        marketStandingOrders,
+        currentPositionQuantity,
+        equity,
+        quoteBalance,
+        initialMarginRequirement,
+        currentInitialMarginRequirement,
+        totalHeldCollateral,
+        totalMaintenanceMarginRequirement,
+        otherPositionsNotionalAtIndex,
+    };
+}
+/**
+ * Generates an estimate of how a taker order submitted via the buy/sell panel
+ * would be executed by the trading engine. The estimate takes into account
+ * trade and gas fees, the (incremental) initial margin fraction and its
+ * overrides, the maximum position size, collateral freed up by the reduction of
+ * positions, the effect of differences between the execution and index price on
+ * collateral, self-trades, held collateral (for standing orders), and changes
+ * in held collateral as a result of self-trades and position size changes.
+ *
+ * The minimum taker quantity is intentionally ignored; the estimate generates
+ * results for quantities that do not meet the minimum.
+ *
+ * The order's quantity may be expressed in base asset terms, in quote asset
+ * terms, or as a fraction of the wallet's available collateral to consume (the
+ * panel's slider). See {@link BuySellPanelEstimateQuantity}.
+ *
+ * All quantities, prices, and collateral values are expressed in pips
+ * (see {@link decimalToPip}).
+ */
+function calculateBuySellPanelEstimate(args) {
+    const { order } = args;
+    const quantityInputCount = (typeof order.baseQuantity !== 'undefined' ? 1 : 0) +
+        (typeof order.quoteQuantity !== 'undefined' ? 1 : 0) +
+        (typeof order.availableCollateralRatio !== 'undefined' ? 1 : 0);
+    if (quantityInputCount !== 1) {
+        throw new Error('Provide exactly one of baseQuantity, quoteQuantity, or availableCollateralRatio');
+    }
+    const context = buildContext(args);
+    if (typeof order.quoteQuantity !== 'undefined') {
+        return runEstimate(context, { quoteQuantity: order.quoteQuantity });
+    }
+    if (typeof order.baseQuantity !== 'undefined') {
+        return runEstimate(context, { baseQuantity: order.baseQuantity });
+    }
+    const baseQuantity = resolveBaseQuantityForCollateralRatio(context, order.availableCollateralRatio);
+    return runEstimate(context, { baseQuantity });
+}
+exports.calculateBuySellPanelEstimate = calculateBuySellPanelEstimate;