@gainsnetwork/sdk 0.0.0-v10.rc2 → 0.0.0-v10.rc21

package/lib/trade/liquidation/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/trade/pnl/builder.d.ts

@@ -0,0 +1,16 @@
+import { TradeContainer } from "../types";
+import { GlobalTradingVariablesType } from "src/backend/tradingVariables/types";
+import { GetComprehensivePnlContext } from "./types";
+/**
+ * @dev Builds a complete context for comprehensive PnL calculations
+ * @dev Uses sub-context builders to create properly scoped contexts
+ * @param globalTradingVariables The transformed global trading variables from backend
+ * @param tradeContainer Full trade container with trade, tradeInfo, fees data and liquidation params
+ * @param additionalParams Additional parameters not available in trading variables
+ * @returns Complete context ready for getComprehensivePnl
+ */
+export declare const buildComprehensivePnlContext: (globalTradingVariables: GlobalTradingVariablesType, tradeContainer: TradeContainer, additionalParams: {
+    currentBlock: number;
+    currentTimestamp: number;
+    traderFeeMultiplier?: number;
+}) => GetComprehensivePnlContext;

package/lib/trade/pnl/builder.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildComprehensivePnlContext = void 0;
+const builder_1 = require("../fees/borrowingV2/builder");
+const builder_2 = require("../fees/fundingFees/builder");
+const builder_3 = require("../fees/borrowing/builder");
+const builder_4 = require("../fees/trading/builder");
+/**
+ * @dev Builds a complete context for comprehensive PnL calculations
+ * @dev Uses sub-context builders to create properly scoped contexts
+ * @param globalTradingVariables The transformed global trading variables from backend
+ * @param tradeContainer Full trade container with trade, tradeInfo, fees data and liquidation params
+ * @param additionalParams Additional parameters not available in trading variables
+ * @returns Complete context ready for getComprehensivePnl
+ */
+const buildComprehensivePnlContext = (globalTradingVariables, tradeContainer, additionalParams) => {
+    var _a;
+    const { trade, tradeInfo } = tradeContainer;
+    const collateralIndex = trade.collateralIndex || 1;
+    const collateral = globalTradingVariables.collaterals[collateralIndex - 1];
+    return {
+        // Core shared context
+        core: {
+            currentBlock: additionalParams.currentBlock,
+            currentTimestamp: additionalParams.currentTimestamp,
+            collateralPriceUsd: ((_a = collateral.prices) === null || _a === void 0 ? void 0 : _a.collateralPriceUsd) || 1,
+            contractsVersion: tradeInfo.contractsVersion,
+        },
+        // Build sub-contexts using dedicated builders
+        borrowingV1: (0, builder_3.buildBorrowingV1Context)(globalTradingVariables, collateralIndex, additionalParams.currentBlock),
+        borrowingV2: (0, builder_1.buildBorrowingV2Context)(globalTradingVariables, collateralIndex, trade.pairIndex, additionalParams.currentTimestamp),
+        funding: (0, builder_2.buildFundingContext)(globalTradingVariables, collateralIndex, trade.pairIndex, additionalParams.currentTimestamp),
+        trading: (0, builder_4.buildTradingFeesContext)(globalTradingVariables, trade.pairIndex, additionalParams.traderFeeMultiplier),
+        // Trade-specific data
+        tradeData: tradeContainer.tradeFeesData && tradeContainer.liquidationParams
+            ? {
+                tradeFeesData: tradeContainer.tradeFeesData,
+                liquidationParams: tradeContainer.liquidationParams,
+                initialAccFees: tradeContainer.initialAccFees,
+            }
+            : undefined,
+    };
+};
+exports.buildComprehensivePnlContext = buildComprehensivePnlContext;

package/lib/trade/pnl/converter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @dev Converters for PnL data between contract and SDK formats
+ */
+/**
+ * @dev Convert PnL percentage from contract precision to SDK format
+ * @param pnlPercentContract PnL percentage with 1e10 precision
+ * @returns PnL percentage as regular number (e.g., 10 = 10%)
+ */
+export declare const convertPnlPercent: (pnlPercentContract: bigint | number) => number;
+/**
+ * @dev Convert PnL percentage from SDK format to contract precision
+ * @param pnlPercent PnL percentage as regular number
+ * @returns PnL percentage with 1e10 precision
+ */
+export declare const encodePnlPercent: (pnlPercent: number) => bigint;
+/**
+ * @dev Convert collateral amount considering precision
+ * @param amount Amount in contract format
+ * @param collateralDecimals Collateral token decimals (6 or 18)
+ * @returns Amount as SDK float
+ */
+export declare const convertCollateralAmount: (amount: bigint | number, collateralDecimals: number) => number;
+/**
+ * @dev Convert price from contract format to SDK format
+ * @param price Price with 1e10 precision
+ * @returns Price as SDK float
+ */
+export declare const convertPrice: (price: bigint | number) => number;
+/**
+ * @dev Convert leverage from contract format to SDK format
+ * @param leverage Leverage with 1e3 precision
+ * @returns Leverage as SDK float (e.g., 10 = 10x)
+ */
+export declare const convertLeverage: (leverage: bigint | number) => number;
+/**
+ * @dev Batch convert PnL results from contract format
+ * @param results Array of PnL results from contract
+ * @param collateralDecimals Collateral token decimals
+ * @returns Array of converted PnL results
+ */
+export declare const convertPnlResults: (results: Array<{
+    pnlCollateral: bigint;
+    pnlPercent: bigint;
+}>, collateralDecimals: number) => Array<{
+    pnlCollateral: number;
+    pnlPercent: number;
+}>;

package/lib/trade/pnl/converter.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * @dev Converters for PnL data between contract and SDK formats
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertPnlResults = exports.convertLeverage = exports.convertPrice = exports.convertCollateralAmount = exports.encodePnlPercent = exports.convertPnlPercent = void 0;
+/**
+ * @dev Convert PnL percentage from contract precision to SDK format
+ * @param pnlPercentContract PnL percentage with 1e10 precision
+ * @returns PnL percentage as regular number (e.g., 10 = 10%)
+ */
+const convertPnlPercent = (pnlPercentContract) => {
+    const value = typeof pnlPercentContract === "bigint"
+        ? Number(pnlPercentContract)
+        : pnlPercentContract;
+    // Contract uses 1e10 precision for percentages
+    return value / 1e10;
+};
+exports.convertPnlPercent = convertPnlPercent;
+/**
+ * @dev Convert PnL percentage from SDK format to contract precision
+ * @param pnlPercent PnL percentage as regular number
+ * @returns PnL percentage with 1e10 precision
+ */
+const encodePnlPercent = (pnlPercent) => {
+    return BigInt(Math.round(pnlPercent * 1e10));
+};
+exports.encodePnlPercent = encodePnlPercent;
+/**
+ * @dev Convert collateral amount considering precision
+ * @param amount Amount in contract format
+ * @param collateralDecimals Collateral token decimals (6 or 18)
+ * @returns Amount as SDK float
+ */
+const convertCollateralAmount = (amount, collateralDecimals) => {
+    const value = typeof amount === "bigint" ? Number(amount) : amount;
+    return value / Math.pow(10, collateralDecimals);
+};
+exports.convertCollateralAmount = convertCollateralAmount;
+/**
+ * @dev Convert price from contract format to SDK format
+ * @param price Price with 1e10 precision
+ * @returns Price as SDK float
+ */
+const convertPrice = (price) => {
+    const value = typeof price === "bigint" ? Number(price) : price;
+    return value / 1e10;
+};
+exports.convertPrice = convertPrice;
+/**
+ * @dev Convert leverage from contract format to SDK format
+ * @param leverage Leverage with 1e3 precision
+ * @returns Leverage as SDK float (e.g., 10 = 10x)
+ */
+const convertLeverage = (leverage) => {
+    const value = typeof leverage === "bigint" ? Number(leverage) : leverage;
+    return value / 1e3;
+};
+exports.convertLeverage = convertLeverage;
+/**
+ * @dev Batch convert PnL results from contract format
+ * @param results Array of PnL results from contract
+ * @param collateralDecimals Collateral token decimals
+ * @returns Array of converted PnL results
+ */
+const convertPnlResults = (results, collateralDecimals) => {
+    return results.map(result => ({
+        pnlCollateral: (0, exports.convertCollateralAmount)(result.pnlCollateral, collateralDecimals),
+        pnlPercent: (0, exports.convertPnlPercent)(result.pnlPercent),
+    }));
+};
+exports.convertPnlResults = convertPnlResults;

package/lib/trade/pnl/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @dev PnL calculation module
+ * @dev Provides functions matching v10 contract implementations
+ */
+import { Trade, TradeInfo, LiquidationParams, Fee, GlobalTradeFeeParams, TradeFeesData } from "../types";
+import { ComprehensivePnlResult, GetComprehensivePnlContext } from "./types";
+import { BorrowingFee } from "../fees/borrowing";
+import { ContractsVersion } from "../../contracts/types";
+/**
+ * @dev Gets trade realized PnL components from TradeFeesData
+ * @dev Mirrors contract's getTradeRealizedPnlCollateral function
+ * @param tradeFeesData Trade fees data containing realized components
+ * @returns Tuple of [realizedPnlCollateral, realizedTradingFeesCollateral, totalRealizedPnlCollateral]
+ */
+export declare const getTradeRealizedPnlCollateral: (tradeFeesData: TradeFeesData) => {
+    realizedPnlCollateral: number;
+    realizedTradingFeesCollateral: number;
+    totalRealizedPnlCollateral: number;
+};
+/**
+ * @dev Calculates PnL percentage for a position
+ * @dev Mirrors contract's getPnlPercent function
+ * @param openPrice Trade open price
+ * @param currentPrice Current market price
+ * @param long Whether position is long
+ * @param leverage Position leverage
+ * @returns PnL percentage (e.g., 10 = 10% profit, -50 = 50% loss)
+ */
+export declare const getPnlPercent: (openPrice: number, currentPrice: number, long: boolean, leverage: number) => number;
+/**
+ * @dev Calculates trade value from collateral and PnL
+ * @dev Mirrors contract's getTradeValuePure function
+ * @param collateral Trade collateral amount
+ * @param pnlPercent PnL percentage
+ * @param totalFees Total fees to deduct
+ * @returns Trade value after PnL and fees
+ */
+export declare const getTradeValue: (collateral: number, pnlPercent: number, totalFees: number) => number;
+/**
+ * @dev Comprehensive PnL calculation including all fees
+ * @param trade The trade to calculate PnL for
+ * @param currentPrice Current market price
+ * @param tradeInfo Trade info with version and timestamps
+ * @param context Context with all fee parameters
+ * @returns Detailed PnL breakdown
+ */
+export declare const getComprehensivePnl: (trade: Trade, currentPrice: number, tradeInfo: TradeInfo, context: GetComprehensivePnlContext) => ComprehensivePnlResult;
+/**
+ * @dev Legacy getPnl function for backward compatibility
+ * @deprecated Use getComprehensivePnl for new implementations
+ */
+export type GetPnlContext = {
+    currentBlock: number;
+    groups: BorrowingFee.Group[];
+    pairs: BorrowingFee.Pair[];
+    collateralPriceUsd: number | undefined;
+    contractsVersion: ContractsVersion | undefined;
+    feeMultiplier: number | undefined;
+    fee: Fee;
+    globalTradeFeeParams: GlobalTradeFeeParams;
+    traderFeeMultiplier?: number;
+};
+/**
+ * @dev Legacy PnL calculation function
+ * @deprecated Use getComprehensivePnl for more comprehensive calculations
+ * @param price Current price
+ * @param trade Trade object
+ * @param tradeInfo Trade info (not used in legacy implementation)
+ * @param initialAccFees Initial accumulated fees
+ * @param liquidationParams Liquidation parameters
+ * @param useFees Whether to include fees
+ * @param context Context with fee calculation parameters
+ * @returns [pnlCollateral, pnlPercentage] or undefined if no price
+ */
+export declare const getPnl: (price: number | undefined, trade: Trade, _tradeInfo: TradeInfo, initialAccFees: BorrowingFee.InitialAccFees, liquidationParams: LiquidationParams, useFees: boolean, context: GetPnlContext) => number[] | undefined;
+/**
+ * @dev Calculates the price needed to achieve a target PnL percentage
+ * @param targetPnlPercent The target PnL percentage (e.g., 50 for 50% profit, -25 for 25% loss)
+ * @param trade The trade to calculate for
+ * @param tradeInfo Trade info with timestamps
+ * @param context Context with fee calculation parameters
+ * @param netPnl Whether to include closing fees in the calculation
+ * @returns The price that would result in the target PnL percentage
+ */
+export declare const getPriceForTargetPnlPercentage: (targetPnlPercent: number, trade: Trade, tradeInfo: TradeInfo, context: GetComprehensivePnlContext, netPnl?: boolean) => number;
+export * from "./types";
+export * from "./converter";
+export * from "./builder";

package/lib/trade/pnl/index.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * @dev PnL calculation module
+ * @dev Provides functions matching v10 contract implementations
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPriceForTargetPnlPercentage = exports.getPnl = exports.getComprehensivePnl = exports.getTradeValue = exports.getPnlPercent = exports.getTradeRealizedPnlCollateral = void 0;
+const borrowing_1 = require("../fees/borrowing");
+const trading_1 = require("../fees/trading");
+const liquidation_1 = require("../liquidation");
+/**
+ * @dev Gets trade realized PnL components from TradeFeesData
+ * @dev Mirrors contract's getTradeRealizedPnlCollateral function
+ * @param tradeFeesData Trade fees data containing realized components
+ * @returns Tuple of [realizedPnlCollateral, realizedTradingFeesCollateral, totalRealizedPnlCollateral]
+ */
+const getTradeRealizedPnlCollateral = (tradeFeesData) => {
+    const realizedPnlCollateral = tradeFeesData.realizedPnlCollateral;
+    const realizedTradingFeesCollateral = tradeFeesData.realizedTradingFeesCollateral;
+    const totalRealizedPnlCollateral = realizedPnlCollateral - realizedTradingFeesCollateral;
+    return {
+        realizedPnlCollateral,
+        realizedTradingFeesCollateral,
+        totalRealizedPnlCollateral,
+    };
+};
+exports.getTradeRealizedPnlCollateral = getTradeRealizedPnlCollateral;
+/**
+ * @dev Calculates PnL percentage for a position
+ * @dev Mirrors contract's getPnlPercent function
+ * @param openPrice Trade open price
+ * @param currentPrice Current market price
+ * @param long Whether position is long
+ * @param leverage Position leverage
+ * @returns PnL percentage (e.g., 10 = 10% profit, -50 = 50% loss)
+ */
+const getPnlPercent = (openPrice, currentPrice, long, leverage) => {
+    if (openPrice === 0)
+        return -100;
+    const priceDiff = long ? currentPrice - openPrice : openPrice - currentPrice;
+    const pnlPercent = (priceDiff / openPrice) * 100 * leverage;
+    // Cap at -100% loss
+    return Math.max(pnlPercent, -100);
+};
+exports.getPnlPercent = getPnlPercent;
+/**
+ * @dev Calculates trade value from collateral and PnL
+ * @dev Mirrors contract's getTradeValuePure function
+ * @param collateral Trade collateral amount
+ * @param pnlPercent PnL percentage
+ * @param totalFees Total fees to deduct
+ * @returns Trade value after PnL and fees
+ */
+const getTradeValue = (collateral, pnlPercent, totalFees) => {
+    const pnlCollateral = collateral * (pnlPercent / 100);
+    const value = collateral + pnlCollateral - totalFees;
+    return Math.max(0, value);
+};
+exports.getTradeValue = getTradeValue;
+/**
+ * @dev Comprehensive PnL calculation including all fees
+ * @param trade The trade to calculate PnL for
+ * @param currentPrice Current market price
+ * @param tradeInfo Trade info with version and timestamps
+ * @param context Context with all fee parameters
+ * @returns Detailed PnL breakdown
+ */
+const getComprehensivePnl = (trade, currentPrice, tradeInfo, context) => {
+    var _a;
+    // Calculate base PnL percentage
+    let pnlPercent = (0, exports.getPnlPercent)(trade.openPrice, currentPrice, trade.long, trade.leverage);
+    if (!context.tradeData) {
+        throw new Error("Trade data is undefined");
+    }
+    // Calculate position size
+    const positionSizeCollateral = trade.collateralAmount * trade.leverage;
+    // Calculate holding fees - always use getTradePendingHoldingFeesCollateral
+    // This mirrors the contract's getTradeValueCollateral which always calls this function
+    const pendingHoldingFees = (0, trading_1.getTradePendingHoldingFeesCollateral)(trade, tradeInfo, context.tradeData.tradeFeesData, currentPrice, {
+        contractsVersion: context.core.contractsVersion,
+        currentTimestamp: context.core.currentTimestamp,
+        collateralPriceUsd: context.core.collateralPriceUsd,
+        borrowingV1: context.borrowingV1,
+        borrowingV2: context.borrowingV2,
+        funding: context.funding,
+        initialAccFees: context.tradeData.initialAccFees,
+    });
+    const borrowingFeeV1 = pendingHoldingFees.borrowingFeeCollateral_old;
+    const borrowingFeeV2 = pendingHoldingFees.borrowingFeeCollateral;
+    const fundingFee = pendingHoldingFees.fundingFeeCollateral;
+    // Calculate closing fees
+    const closingFee = (0, trading_1.getTotalTradeFeesCollateral)(trade.collateralIndex, trade.user, trade.pairIndex, positionSizeCollateral, trade.isCounterTrade || false, {
+        fee: context.trading.fee,
+        globalTradeFeeParams: context.trading.globalTradeFeeParams,
+        collateralPriceUsd: context.core.collateralPriceUsd,
+        traderFeeMultiplier: context.trading.traderFeeMultiplier,
+    });
+    // Total fees
+    const totalHoldingFees = borrowingFeeV1 + borrowingFeeV2 + fundingFee;
+    const totalFees = totalHoldingFees + closingFee;
+    // Check liquidation
+    const liquidationThreshold = ((_a = context.tradeData) === null || _a === void 0 ? void 0 : _a.liquidationParams)
+        ? (0, liquidation_1.getLiqPnlThresholdP)(context.tradeData.liquidationParams, trade.leverage) *
+            -100
+        : -90; // Default 90% loss
+    const isLiquidated = pnlPercent <= liquidationThreshold;
+    // If liquidated, set PnL to -100%
+    if (isLiquidated) {
+        pnlPercent = -100;
+    }
+    // Get realized PnL components from TradeFeesData
+    const { totalRealizedPnlCollateral } = (0, exports.getTradeRealizedPnlCollateral)(context.tradeData.tradeFeesData);
+    // Calculate final trade value
+    const tradeValue = (0, exports.getTradeValue)(trade.collateralAmount, pnlPercent, totalFees);
+    // Calculate PnL in collateral
+    const pnlCollateral = trade.collateralAmount * (pnlPercent / 100);
+    // Calculate leveraged position size
+    const leveragedPositionSize = trade.collateralAmount * trade.leverage;
+    // Calculate unrealized PnL (before closing fee, after holding fees)
+    const uPnlCollateral = pnlCollateral - totalHoldingFees + totalRealizedPnlCollateral;
+    const uPnlPercent = (uPnlCollateral / trade.collateralAmount) * 100;
+    // Realized PnL (after all fees including closing)
+    const realizedPnlCollateral = pnlCollateral - totalFees + totalRealizedPnlCollateral;
+    const realizedPnlPercent = (realizedPnlCollateral / trade.collateralAmount) * 100;
+    return {
+        // Core PnL values
+        pnlPercent,
+        pnlCollateral,
+        tradeValue,
+        // Unrealized PnL (after holding fees, before closing fee)
+        uPnlCollateral,
+        uPnlPercent,
+        // Realized PnL (after all fees)
+        realizedPnlCollateral,
+        realizedPnlPercent,
+        // Fee breakdown
+        fees: {
+            borrowingV1: borrowingFeeV1,
+            borrowingV2: borrowingFeeV2,
+            funding: fundingFee,
+            closing: closingFee,
+            total: totalFees,
+        },
+        // Status flags
+        isLiquidated,
+        isProfitable: pnlPercent > 0,
+        // Additional info
+        leveragedPositionSize,
+    };
+};
+exports.getComprehensivePnl = getComprehensivePnl;
+/**
+ * @dev Legacy PnL calculation function
+ * @deprecated Use getComprehensivePnl for more comprehensive calculations
+ * @param price Current price
+ * @param trade Trade object
+ * @param tradeInfo Trade info (not used in legacy implementation)
+ * @param initialAccFees Initial accumulated fees
+ * @param liquidationParams Liquidation parameters
+ * @param useFees Whether to include fees
+ * @param context Context with fee calculation parameters
+ * @returns [pnlCollateral, pnlPercentage] or undefined if no price
+ */
+const getPnl = (price, trade, _tradeInfo, initialAccFees, liquidationParams, useFees, context) => {
+    var _a;
+    if (!price) {
+        return;
+    }
+    const posCollat = trade.collateralAmount;
+    const { openPrice, leverage } = trade;
+    let pnlCollat = trade.long
+        ? ((price - openPrice) / openPrice) * leverage * posCollat
+        : ((openPrice - price) / openPrice) * leverage * posCollat;
+    if (useFees &&
+        context.pairs &&
+        context.groups &&
+        context.currentBlock !== undefined &&
+        context.collateralPriceUsd !== undefined) {
+        pnlCollat -= (0, borrowing_1.getBorrowingFee)(posCollat * trade.leverage, trade.pairIndex, trade.long, initialAccFees, {
+            currentBlock: context.currentBlock,
+            groups: context.groups,
+            pairs: context.pairs,
+            collateralPriceUsd: context.collateralPriceUsd,
+        });
+    }
+    let pnlPercentage = (pnlCollat / posCollat) * 100;
+    // Can be liquidated
+    if (pnlPercentage <=
+        (0, liquidation_1.getLiqPnlThresholdP)(liquidationParams, leverage) * -100) {
+        pnlPercentage = -100;
+    }
+    else {
+        // Calculate closing fee using the same function as opening fees
+        const positionSizeCollateral = posCollat * trade.leverage;
+        const closingFee = (0, trading_1.getTotalTradeFeesCollateral)(0, // collateralIndex not used
+        trade.user, trade.pairIndex, positionSizeCollateral, (_a = trade.isCounterTrade) !== null && _a !== void 0 ? _a : false, {
+            fee: context.fee,
+            globalTradeFeeParams: context.globalTradeFeeParams,
+            collateralPriceUsd: context.collateralPriceUsd || 1,
+            traderFeeMultiplier: context.traderFeeMultiplier,
+        });
+        pnlCollat -= closingFee;
+        pnlPercentage = (pnlCollat / posCollat) * 100;
+    }
+    pnlPercentage = pnlPercentage < -100 ? -100 : pnlPercentage;
+    pnlCollat = (posCollat * pnlPercentage) / 100;
+    return [pnlCollat, pnlPercentage];
+};
+exports.getPnl = getPnl;
+/**
+ * @dev Calculates the price needed to achieve a target PnL percentage
+ * @param targetPnlPercent The target PnL percentage (e.g., 50 for 50% profit, -25 for 25% loss)
+ * @param trade The trade to calculate for
+ * @param tradeInfo Trade info with timestamps
+ * @param context Context with fee calculation parameters
+ * @param netPnl Whether to include closing fees in the calculation
+ * @returns The price that would result in the target PnL percentage
+ */
+const getPriceForTargetPnlPercentage = (targetPnlPercent, trade, tradeInfo, context, netPnl = false) => {
+    var _a, _b;
+    const { leverage, openPrice, long, collateralAmount } = trade;
+    const positionSizeCollateral = collateralAmount * leverage;
+    // Calculate holding fees - always use getTradePendingHoldingFeesCollateral
+    // This mirrors the contract's getTradeValueCollateral which always calls this function
+    const fees = (0, trading_1.getTradePendingHoldingFeesCollateral)(trade, tradeInfo, ((_a = context.tradeData) === null || _a === void 0 ? void 0 : _a.tradeFeesData) || {
+        realizedTradingFeesCollateral: 0,
+        realizedPnlCollateral: 0,
+        manuallyRealizedNegativePnlCollateral: 0,
+        alreadyTransferredNegativePnlCollateral: 0,
+        virtualAvailableCollateralInDiamond: 0,
+        initialAccFundingFeeP: 0,
+        initialAccBorrowingFeeP: 0,
+    }, openPrice, // Use open price as a baseline
+    {
+        contractsVersion: context.core.contractsVersion,
+        currentTimestamp: context.core.currentTimestamp,
+        collateralPriceUsd: context.core.collateralPriceUsd,
+        borrowingV1: context.borrowingV1,
+        borrowingV2: context.borrowingV2,
+        funding: context.funding,
+        initialAccFees: (_b = context.tradeData) === null || _b === void 0 ? void 0 : _b.initialAccFees,
+    });
+    const totalHoldingFees = fees.fundingFeeCollateral +
+        fees.borrowingFeeCollateral +
+        fees.borrowingFeeCollateral_old;
+    const targetPnlInCollateral = (collateralAmount * targetPnlPercent) / 100;
+    let targetPnlGross = targetPnlInCollateral + totalHoldingFees;
+    if (netPnl) {
+        // Include closing fees
+        const closingFee = (0, trading_1.getTotalTradeFeesCollateral)(trade.collateralIndex, trade.user, trade.pairIndex, positionSizeCollateral, trade.isCounterTrade || false, {
+            fee: context.trading.fee,
+            globalTradeFeeParams: context.trading.globalTradeFeeParams,
+            collateralPriceUsd: context.core.collateralPriceUsd,
+            traderFeeMultiplier: context.trading.traderFeeMultiplier,
+        });
+        targetPnlGross += closingFee;
+    }
+    // Calculate the price
+    let price;
+    if (long) {
+        price = openPrice + (targetPnlGross * openPrice) / positionSizeCollateral;
+    }
+    else {
+        price = openPrice - (targetPnlGross * openPrice) / positionSizeCollateral;
+    }
+    return price;
+};
+exports.getPriceForTargetPnlPercentage = getPriceForTargetPnlPercentage;
+// Re-export types
+__exportStar(require("./types"), exports);
+__exportStar(require("./converter"), exports);
+__exportStar(require("./builder"), exports);

package/lib/trade/pnl/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @dev Types for PnL calculations
+ */
+import { ContractsVersion } from "src/contracts/types";
+import { BorrowingFee, GetBorrowingFeeContext, TradingFeesSubContext } from "../fees";
+import { GetPairBorrowingFeeV2Context } from "../fees/borrowingV2";
+import { GetPairFundingFeeContext } from "../fees/fundingFees";
+import { TradeFeesData, LiquidationParams } from "../types";
+/**
+ * @dev Result of trade value calculation
+ */
+export type TradeValueResult = {
+    tradeValue: number;
+    pnlPercent: number;
+    pnlCollateral: number;
+    totalFees: number;
+};
+/**
+ * @dev Detailed fee breakdown
+ */
+export type FeeBreakdown = {
+    borrowingV1: number;
+    borrowingV2: number;
+    funding: number;
+    closing: number;
+    opening?: number;
+    total: number;
+};
+/**
+ * @dev Price impact breakdown for v10
+ */
+export type PriceImpactBreakdown = {
+    fixedSpread: number;
+    skewImpact: number;
+    cumulVolImpact: number;
+    total: number;
+    priceAfterImpact: number;
+};
+/**
+ * @dev Comprehensive PnL result with all details
+ */
+export type ComprehensivePnlResult = {
+    pnlPercent: number;
+    pnlCollateral: number;
+    tradeValue: number;
+    uPnlCollateral: number;
+    uPnlPercent: number;
+    realizedPnlCollateral: number;
+    realizedPnlPercent: number;
+    fees: FeeBreakdown;
+    priceImpact?: PriceImpactBreakdown;
+    isLiquidated: boolean;
+    isProfitable: boolean;
+    leveragedPositionSize: number;
+};
+/**
+ * @dev Context for comprehensive PnL calculations with nested sub-contexts
+ */
+export type GetComprehensivePnlContext = {
+    core: {
+        currentBlock: number;
+        currentTimestamp: number;
+        collateralPriceUsd: number;
+        contractsVersion: ContractsVersion;
+    };
+    borrowingV1?: GetBorrowingFeeContext;
+    borrowingV2?: GetPairBorrowingFeeV2Context;
+    funding?: GetPairFundingFeeContext;
+    trading: TradingFeesSubContext;
+    tradeData?: {
+        tradeFeesData: TradeFeesData;
+        liquidationParams: LiquidationParams;
+        initialAccFees?: BorrowingFee.InitialAccFees;
+    };
+};

package/lib/trade/pnl/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @dev Types for PnL calculations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/trade/priceImpact/close/builder.d.ts

@@ -0,0 +1,23 @@
+import { GlobalTradingVariablesType } from "../../../backend/tradingVariables/types";
+import { TradeClosingPriceImpactContext } from "./types";
+import { TradeInfo } from "../../types";
+/**
+ * @dev Builds a complete context for trade closing price impact calculations
+ * @dev Uses sub-context builders to create properly scoped contexts
+ * @param globalTradingVariables The transformed global trading variables from backend
+ * @param collateralIndex The collateral index (1-based)
+ * @param pairIndex The pair index
+ * @param tradeInfo Trade information including createdBlock
+ * @param additionalParams Additional parameters not available in trading variables
+ * @returns Complete context ready for getTradeClosingPriceImpact
+ */
+export declare const buildTradeClosingPriceImpactContext: (globalTradingVariables: GlobalTradingVariablesType, collateralIndex: number, pairIndex: number, tradeInfo: TradeInfo, additionalParams: {
+    currentBlock: number;
+    contractsVersion?: number;
+    isPnlPositive?: boolean;
+    userPriceImpact?: {
+        cumulVolPriceImpactMultiplier: number;
+        fixedSpreadP: number;
+    };
+    protectionCloseFactorWhitelist?: boolean;
+}) => TradeClosingPriceImpactContext | undefined;