@gainsnetwork/sdk 0.0.0-v10.rc1 → 0.0.0-v10.rc3

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

@@ -0,0 +1,86 @@
+/**
+ * @dev Types for PnL calculations
+ */
+import { Trade, TradeInfo, TradeFeesData } from "../types";
+/**
+ * @dev Input for trade value calculation with all fees
+ * @dev Mirrors contract's TradeValueInput struct
+ */
+export type TradeValueInput = {
+    trade: Trade;
+    currentPrice: number;
+    collateralPriceUsd: number;
+    fees: {
+        openingFeeCollateral: number;
+        closingFeeCollateral: number;
+        holdingFeesCollateral: number;
+    };
+};
+/**
+ * @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;
+    fees: FeeBreakdown;
+    priceImpact?: PriceImpactBreakdown;
+    isLiquidated: boolean;
+    isProfitable: boolean;
+    leveragedPositionSize: number;
+    netPnlAfterFees: number;
+};
+/**
+ * @dev Simple PnL result for backward compatibility
+ */
+export type SimplePnlResult = [pnlCollateral: number, pnlPercent: number];
+/**
+ * @dev Input for PnL calculation with price impact
+ */
+export type PnlWithPriceImpactInput = {
+    trade: Trade;
+    tradeInfo: TradeInfo;
+    oraclePrice: number;
+    currentPairPrice: number;
+    usePriceImpact: boolean;
+    includeOpeningFees?: boolean;
+};
+/**
+ * @dev Context for v10 PnL calculations
+ */
+export type V10PnlContext = {
+    tradeFeesData: TradeFeesData;
+    priceImpactContext?: any;
+    skewContext?: any;
+    cumulVolContext?: any;
+};

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/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @dev Trade closing price impact calculations
+ * @dev Mirrors contract's TradingCommonUtils.getTradeClosingPriceImpact
+ */
+import { TradeClosingPriceImpactInput, TradeClosingPriceImpactContext, TradeClosingPriceImpactResult } from "./types";
+export type { TradeClosingPriceImpactInput, TradeClosingPriceImpactContext, TradeClosingPriceImpactResult, };
+/**
+ * @dev Calculates all price impacts for trade closing
+ * @dev Mirrors contract's getTradeClosingPriceImpact function
+ * @param input Trade parameters
+ * @param context Combined context for calculations
+ * @returns Price impact breakdown and trade value
+ */
+export declare const getTradeClosingPriceImpact: (input: TradeClosingPriceImpactInput, context: TradeClosingPriceImpactContext) => TradeClosingPriceImpactResult;
+/**
+ * @dev Simplified version using oracle price as current price
+ * @param input Trade parameters (without currentPairPrice)
+ * @param context Combined context
+ * @returns Price impact breakdown and trade value
+ */
+export declare const getTradeClosingPriceImpactAtOracle: (input: Omit<TradeClosingPriceImpactInput, "currentPairPrice">, context: TradeClosingPriceImpactContext) => TradeClosingPriceImpactResult;

package/lib/trade/priceImpact/close/index.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * @dev Trade closing price impact calculations
+ * @dev Mirrors contract's TradingCommonUtils.getTradeClosingPriceImpact
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTradeClosingPriceImpactAtOracle = exports.getTradeClosingPriceImpact = void 0;
+const cumulVol_1 = require("../cumulVol");
+const skew_1 = require("../skew");
+const types_1 = require("../../../contracts/types");
+/**
+ * @dev Calculates position size in tokens for partial close
+ * @param originalPositionSizeToken Original position size in tokens
+ * @param originalCollateral Original collateral amount
+ * @param closingCollateral Collateral amount being closed
+ * @returns Proportional position size in tokens
+ */
+const calculateClosingPositionSizeToken = (originalPositionSizeToken, originalCollateral, closingCollateral) => {
+    if (originalCollateral === 0)
+        return 0;
+    // Proportional calculation: (closingCollateral / originalCollateral) * originalPositionSizeToken
+    return (closingCollateral * originalPositionSizeToken) / originalCollateral;
+};
+/**
+ * @dev Calculates all price impacts for trade closing
+ * @dev Mirrors contract's getTradeClosingPriceImpact function
+ * @param input Trade parameters
+ * @param context Combined context for calculations
+ * @returns Price impact breakdown and trade value
+ */
+const getTradeClosingPriceImpact = (input, context) => {
+    // For trades before V9.2, return oracle price without any impact
+    if (input.contractsVersion === types_1.ContractsVersion.BEFORE_V9_2) {
+        return {
+            positionSizeToken: 0,
+            fixedSpreadP: 0,
+            cumulVolPriceImpactP: 0,
+            skewPriceImpactP: 0,
+            totalPriceImpactP: 0,
+            priceAfterImpact: input.oraclePrice,
+            tradeValueCollateralNoFactor: 0,
+        };
+    }
+    // Calculate position size in tokens (proportional to collateral being closed)
+    const positionSizeToken = input.trade.positionSizeToken
+        ? calculateClosingPositionSizeToken(input.trade.positionSizeToken, input.trade.collateralAmount, input.positionSizeCollateral)
+        : 0;
+    // Calculate fixed spread (reversed for closing)
+    const fixedSpreadP = (0, cumulVol_1.getFixedSpreadP)(input.pairSpreadP, input.trade.long, false // closing
+    );
+    let cumulVolPriceImpactP = 0;
+    let tradeValueCollateralNoFactor = 0;
+    if (input.useCumulativeVolPriceImpact) {
+        // First pass: Calculate with negative PnL assumption
+        const positionSizeUsd = input.positionSizeCollateral * context.collateralPriceUsd;
+        cumulVolPriceImpactP = (0, cumulVol_1.getTradeCumulVolPriceImpactP)(input.trade.user, input.pairIndex, input.trade.long, positionSizeUsd, false, // Assume negative PnL initially
+        false, // closing
+        context.tradeInfo.lastPosIncreaseBlock || context.tradeInfo.createdBlock, Object.assign(Object.assign({}, context), { isOpen: false, isPnlPositive: false, contractsVersion: input.contractsVersion, createdBlock: context.tradeInfo.createdBlock }));
+        // Calculate price with conservative impact
+        const priceWithImpact = input.trade.long
+            ? input.currentPairPrice *
+                (1 - (fixedSpreadP + cumulVolPriceImpactP) / 100)
+            : input.currentPairPrice /
+                (1 - (fixedSpreadP + cumulVolPriceImpactP) / 100);
+        // Calculate trade value in collateral
+        // For long: value = positionSizeToken * priceWithImpact
+        // For short: value = positionSizeToken / priceWithImpact * openPrice^2 / currentPrice
+        if (positionSizeToken > 0) {
+            if (input.trade.long) {
+                tradeValueCollateralNoFactor = positionSizeToken * priceWithImpact;
+            }
+            else {
+                // Short calculation: profit from price decrease
+                const pnlFactor = (2 * input.trade.openPrice - priceWithImpact) / input.trade.openPrice;
+                tradeValueCollateralNoFactor = input.positionSizeCollateral * pnlFactor;
+            }
+        }
+        else {
+            tradeValueCollateralNoFactor = input.positionSizeCollateral;
+        }
+        // Determine actual PnL
+        const isPnlPositive = tradeValueCollateralNoFactor > input.trade.collateralAmount;
+        // Second pass: Recalculate with actual PnL if positive
+        if (isPnlPositive) {
+            cumulVolPriceImpactP = (0, cumulVol_1.getTradeCumulVolPriceImpactP)(input.trade.user, input.pairIndex, input.trade.long, positionSizeUsd, true, // Positive PnL
+            false, // closing
+            context.tradeInfo.lastPosIncreaseBlock ||
+                context.tradeInfo.createdBlock, Object.assign(Object.assign({}, context), { isOpen: false, isPnlPositive: true, contractsVersion: input.contractsVersion, createdBlock: context.tradeInfo.createdBlock }));
+        }
+    }
+    // Calculate skew price impact (v10+ only)
+    const skewPriceImpactP = input.contractsVersion === types_1.ContractsVersion.V10
+        ? (0, skew_1.getTradeSkewPriceImpactWithChecks)({
+            collateralIndex: input.collateralIndex,
+            pairIndex: input.pairIndex,
+            long: input.trade.long,
+            open: false,
+            positionSizeCollateral: input.positionSizeCollateral,
+            currentPrice: input.currentPairPrice,
+            contractsVersion: input.contractsVersion,
+            isCounterTrade: input.trade.isCounterTrade,
+        }, context.skewContext)
+        : 0;
+    // Total price impact (all components)
+    const totalPriceImpactP = fixedSpreadP + cumulVolPriceImpactP + skewPriceImpactP;
+    // Calculate final price after all impacts
+    // For closing: longs get worse price when impact is positive, shorts get better
+    const priceAfterImpact = input.trade.long
+        ? input.currentPairPrice * (1 - totalPriceImpactP / 100)
+        : input.currentPairPrice / (1 - totalPriceImpactP / 100);
+    return {
+        positionSizeToken,
+        fixedSpreadP,
+        cumulVolPriceImpactP,
+        skewPriceImpactP,
+        totalPriceImpactP,
+        priceAfterImpact,
+        tradeValueCollateralNoFactor,
+    };
+};
+exports.getTradeClosingPriceImpact = getTradeClosingPriceImpact;
+/**
+ * @dev Simplified version using oracle price as current price
+ * @param input Trade parameters (without currentPairPrice)
+ * @param context Combined context
+ * @returns Price impact breakdown and trade value
+ */
+const getTradeClosingPriceImpactAtOracle = (input, context) => {
+    return (0, exports.getTradeClosingPriceImpact)(Object.assign(Object.assign({}, input), { currentPairPrice: input.oraclePrice }), context);
+};
+exports.getTradeClosingPriceImpactAtOracle = getTradeClosingPriceImpactAtOracle;

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

@@ -0,0 +1,43 @@
+/**
+ * @dev Types for trade closing price impact calculations
+ */
+import { CumulVolContext } from "../cumulVol";
+import { SkewPriceImpactContext } from "../skew/types";
+import { Trade, TradeInfo, PairIndex } from "../../types";
+/**
+ * @dev Input parameters for trade closing price impact
+ * @dev Mirrors contract's TradePriceImpactInput struct
+ */
+export type TradeClosingPriceImpactInput = {
+    trade: Trade;
+    oraclePrice: number;
+    positionSizeCollateral: number;
+    currentPairPrice: number;
+    useCumulativeVolPriceImpact: boolean;
+    collateralIndex: number;
+    pairIndex: PairIndex;
+    pairSpreadP: number;
+    contractsVersion: number;
+};
+/**
+ * @dev Context for trade closing price impact calculation
+ * Combines contexts from spread, cumul vol, and skew
+ */
+export type TradeClosingPriceImpactContext = CumulVolContext & {
+    skewContext: SkewPriceImpactContext;
+    collateralPriceUsd: number;
+    tradeInfo: TradeInfo;
+};
+/**
+ * @dev Result of trade closing price impact calculation
+ * @dev Mirrors contract's TradePriceImpact struct with additional return value
+ */
+export type TradeClosingPriceImpactResult = {
+    positionSizeToken: number;
+    fixedSpreadP: number;
+    cumulVolPriceImpactP: number;
+    skewPriceImpactP: number;
+    totalPriceImpactP: number;
+    priceAfterImpact: number;
+    tradeValueCollateralNoFactor: number;
+};

package/lib/trade/priceImpact/close/types.js

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

package/lib/trade/priceImpact/cumulVol/converter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @dev Converters for cumulative volume price impact data between contract and SDK formats
+ * @dev All BigNumber values are normalized to floats with appropriate precision
+ */
+import { IPriceImpact } from "../../../contracts/types/generated/GNSMultiCollatDiamond";
+import { OiWindowsSettings, OiWindow, OiWindows } from "../../types";
+/**
+ * @dev Converts contract OI windows settings to SDK format
+ * @param contractData Contract OiWindowsSettings struct
+ * @returns Normalized OI windows settings
+ */
+export declare const convertOiWindowsSettings: (contractData: IPriceImpact.OiWindowsSettingsStructOutput) => OiWindowsSettings;
+/**
+ * @dev Converts contract PairOi data to SDK OiWindow format
+ * @param contractData Contract PairOi struct with USD values
+ * @returns Normalized OI window data
+ */
+export declare const convertOiWindow: (contractData: IPriceImpact.PairOiStructOutput) => OiWindow;
+/**
+ * @dev Converts array of OI windows from contract format
+ * @param windowIds Array of window IDs (as strings for mapping)
+ * @param contractWindows Array of PairOi data from contract
+ * @returns Normalized OI windows mapping
+ */
+export declare const convertOiWindows: (windowIds: string[], contractWindows: IPriceImpact.PairOiStructOutput[]) => OiWindows;
+/**
+ * @dev Batch converter for multiple OI windows settings
+ * @param contractDataArray Array of contract OiWindowsSettings
+ * @returns Array of normalized OI windows settings
+ */
+export declare const convertOiWindowsSettingsArray: (contractDataArray: IPriceImpact.OiWindowsSettingsStructOutput[]) => OiWindowsSettings[];

package/lib/trade/priceImpact/cumulVol/converter.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * @dev Converters for cumulative volume price impact data between contract and SDK formats
+ * @dev All BigNumber values are normalized to floats with appropriate precision
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertOiWindowsSettingsArray = exports.convertOiWindows = exports.convertOiWindow = exports.convertOiWindowsSettings = void 0;
+/**
+ * @dev Converts contract OI windows settings to SDK format
+ * @param contractData Contract OiWindowsSettings struct
+ * @returns Normalized OI windows settings
+ */
+const convertOiWindowsSettings = (contractData) => {
+    return {
+        startTs: Number(contractData.startTs),
+        windowsDuration: Number(contractData.windowsDuration),
+        windowsCount: Number(contractData.windowsCount),
+    };
+};
+exports.convertOiWindowsSettings = convertOiWindowsSettings;
+/**
+ * @dev Converts contract PairOi data to SDK OiWindow format
+ * @param contractData Contract PairOi struct with USD values
+ * @returns Normalized OI window data
+ */
+const convertOiWindow = (contractData) => {
+    // USD values are stored as 1e18 in contract
+    return {
+        oiLongUsd: Number(contractData.oiLongUsd) / 1e18,
+        oiShortUsd: Number(contractData.oiShortUsd) / 1e18,
+    };
+};
+exports.convertOiWindow = convertOiWindow;
+/**
+ * @dev Converts array of OI windows from contract format
+ * @param windowIds Array of window IDs (as strings for mapping)
+ * @param contractWindows Array of PairOi data from contract
+ * @returns Normalized OI windows mapping
+ */
+const convertOiWindows = (windowIds, contractWindows) => {
+    if (windowIds.length !== contractWindows.length) {
+        throw new Error("Window IDs and data arrays must have the same length");
+    }
+    const windows = {};
+    windowIds.forEach((id, index) => {
+        windows[id] = (0, exports.convertOiWindow)(contractWindows[index]);
+    });
+    return windows;
+};
+exports.convertOiWindows = convertOiWindows;
+/**
+ * @dev Batch converter for multiple OI windows settings
+ * @param contractDataArray Array of contract OiWindowsSettings
+ * @returns Array of normalized OI windows settings
+ */
+const convertOiWindowsSettingsArray = (contractDataArray) => {
+    return contractDataArray.map(exports.convertOiWindowsSettings);
+};
+exports.convertOiWindowsSettingsArray = convertOiWindowsSettingsArray;

package/lib/trade/priceImpact/cumulVol/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @dev Cumulative volume price impact calculations
+ * @dev Mirrors contract's getTradeCumulVolPriceImpactP functionality
+ */
+import { LiquidationParams, OiWindows, OiWindowsSettings, PairDepth, PairFactor, UserPriceImpact } from "../../types";
+import { ContractsVersion } from "../../../contracts/types";
+export type CumulVolContext = {
+    isOpen?: boolean;
+    isPnlPositive?: boolean;
+    createdBlock?: number;
+    liquidationParams?: LiquidationParams | undefined;
+    currentBlock?: number | undefined;
+    contractsVersion?: ContractsVersion | undefined;
+    protectionCloseFactorWhitelist?: boolean;
+    pairDepth?: PairDepth | undefined;
+    oiWindowsSettings?: OiWindowsSettings | undefined;
+    oiWindows?: OiWindows | undefined;
+    userPriceImpact?: UserPriceImpact | undefined;
+    collateralPriceUsd?: number;
+} & Partial<PairFactor>;
+/**
+ * @dev Gets the protection close factor with user multiplier
+ * @param context Cumulative volume context
+ * @returns Protection close factor (1 = 100%)
+ */
+export declare const getProtectionCloseFactor: (context: CumulVolContext | undefined) => number;
+/**
+ * @dev Checks if protection close factor is active
+ * @param context Cumulative volume context
+ * @returns True if protection close factor should be applied
+ */
+export declare const isProtectionCloseFactorActive: (context: CumulVolContext | undefined) => boolean | undefined;
+/**
+ * @dev Gets the cumulative factor for price impact calculation
+ * @param context Cumulative volume context
+ * @returns Cumulative factor (default 1)
+ */
+export declare const getCumulativeFactor: (context: CumulVolContext | undefined) => number;
+/**
+ * @dev Gets the legacy factor for v9.2 compatibility
+ * @param context Cumulative volume context
+ * @returns 1 for pre-v9.2, 2 for v9.2+
+ */
+export declare const getLegacyFactor: (context: CumulVolContext | undefined) => number;
+/**
+ * @dev Calculates cumulative volume price impact percentage
+ * @dev Mirrors contract's getTradeCumulVolPriceImpactP function
+ * @param trader Trader address
+ * @param pairIndex Trading pair index
+ * @param long True for long, false for short
+ * @param tradeOpenInterestUsd Position size in USD
+ * @param isPnlPositive Whether PnL is positive (only relevant when closing)
+ * @param open True for opening, false for closing
+ * @param lastPosIncreaseBlock Last block when position was increased (only relevant when closing)
+ * @param context Additional context with depths, OI data, and factors
+ * @returns Cumulative volume price impact percentage (not including spread)
+ */
+export declare const getTradeCumulVolPriceImpactP: (trader: string, pairIndex: number, long: boolean, tradeOpenInterestUsd: number, isPnlPositive: boolean, open: boolean, lastPosIncreaseBlock: number, context: CumulVolContext) => number;
+/**
+ * @dev Gets the fixed spread percentage with direction
+ * @dev Mirrors contract's getFixedSpreadP function
+ * @param spreadP Total spread percentage (includes base + user spread)
+ * @param long True for long position
+ * @param open True for opening, false for closing
+ * @returns Signed spread percentage (positive or negative based on direction)
+ */
+export declare const getFixedSpreadP: (spreadP: number, long: boolean, open: boolean) => number;
+/**
+ * @dev Gets the base spread percentage
+ * @param pairSpreadP Pair spread percentage
+ * @param isLiquidation True if liquidation
+ * @param liquidationParams Liquidation parameters
+ * @param userPriceImpact User-specific price impact settings
+ * @returns Base spread percentage
+ * @todo Review if this function still makes sense or should use getFixedSpreadP pattern
+ *       Currently it may double-count user fixed spread if pairSpreadP already includes it
+ */
+export declare const getSpreadP: (pairSpreadP: number | undefined, isLiquidation?: boolean | undefined, liquidationParams?: LiquidationParams | undefined, userPriceImpact?: UserPriceImpact | undefined) => number;
+/**
+ * @dev Gets spread with cumulative volume price impact
+ * @dev This combines base spread + cumulative volume impact
+ * @param pairSpreadP Base pair spread percentage
+ * @param buy True for long, false for short
+ * @param collateral Collateral amount
+ * @param leverage Position leverage
+ * @param pairDepth 1% depth values for the pair
+ * @param oiWindowsSettings OI windows configuration
+ * @param oiWindows Current OI windows data
+ * @param context Additional context for the calculation
+ * @returns Total spread + cumulative volume price impact percentage
+ */
+export declare const getSpreadWithCumulVolPriceImpactP: (pairSpreadP: number, buy: boolean, collateral: number, leverage: number, pairDepth: PairDepth | undefined, oiWindowsSettings?: OiWindowsSettings | undefined, oiWindows?: OiWindows | undefined, context?: CumulVolContext | undefined) => number;
+/**
+ * @dev Convenience function for calculating cumulative volume price impact
+ * @dev Uses collateral and leverage instead of USD position size
+ * @param buy True for long, false for short
+ * @param collateral Collateral amount
+ * @param leverage Position leverage
+ * @param open True for opening, false for closing
+ * @param context Full context including depths, OI data, and collateral price
+ * @returns Cumulative volume price impact percentage
+ */
+export declare const getCumulVolPriceImpact: (buy: boolean, collateral: number, leverage: number, open: boolean, context: CumulVolContext & {
+    collateralPriceUsd: number;
+}) => number;
+export declare const getSpreadWithPriceImpactP: (pairSpreadP: number, buy: boolean, collateral: number, leverage: number, pairDepth: PairDepth | undefined, oiWindowsSettings?: OiWindowsSettings | undefined, oiWindows?: OiWindows | undefined, context?: CumulVolContext | undefined) => number;
+export { convertOiWindowsSettings, convertOiWindow, convertOiWindows, convertOiWindowsSettingsArray, } from "./converter";