@gainsnetwork/sdk 0.0.0-me-rc1

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

@@ -0,0 +1,22 @@
+import { GlobalTradingVariablesType } from "../../../backend/tradingVariables/types";
+import { CumulVolContext } from "./index";
+/**
+ * @dev Builds cumulative volume price impact sub-context for a specific pair
+ * @param globalTradingVariables The transformed global trading variables from backend
+ * @param collateralIndex The collateral index (1-based)
+ * @param pairIndex The pair index
+ * @param additionalParams Additional parameters not available in trading variables
+ * @returns Cumulative volume context ready for getTradeCumulVolPriceImpactP
+ */
+export declare const buildCumulVolContext: (globalTradingVariables: GlobalTradingVariablesType, collateralIndex: number, pairIndex: number, additionalParams: {
+    currentBlock: number;
+    contractsVersion?: number;
+    isPnlPositive?: boolean;
+    isOpen?: boolean;
+    createdBlock?: number;
+    userPriceImpact?: {
+        cumulVolPriceImpactMultiplier: number;
+        fixedSpreadP: number;
+    };
+    protectionCloseFactorWhitelist?: boolean;
+}) => CumulVolContext | undefined;

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCumulVolContext = void 0;
+/**
+ * @dev Builds cumulative volume price impact sub-context for a specific pair
+ * @param globalTradingVariables The transformed global trading variables from backend
+ * @param collateralIndex The collateral index (1-based)
+ * @param pairIndex The pair index
+ * @param additionalParams Additional parameters not available in trading variables
+ * @returns Cumulative volume context ready for getTradeCumulVolPriceImpactP
+ */
+const buildCumulVolContext = (globalTradingVariables, collateralIndex, pairIndex, additionalParams) => {
+    const collateral = globalTradingVariables.collaterals[collateralIndex - 1];
+    if (!collateral) {
+        return undefined;
+    }
+    // Get pair-specific data from global variables
+    const pairDepthBands = globalTradingVariables.pairDepthBands?.[pairIndex];
+    const depthBandsMapping = globalTradingVariables.depthBandsMapping;
+    const pairFactor = globalTradingVariables.pairFactors?.[pairIndex];
+    const oiWindows = globalTradingVariables.oiWindows?.[pairIndex];
+    // Get OI windows settings (same for all pairs)
+    // OI windows settings from global trading variables are already in SDK format
+    const oiWindowsSettings = globalTradingVariables.oiWindowsSettings;
+    // Get user-specific parameters from additionalParams
+    const userPriceImpact = additionalParams.userPriceImpact;
+    const protectionCloseFactorWhitelist = additionalParams.protectionCloseFactorWhitelist;
+    // Get liquidation params - check both pair and group level
+    const liquidationParams = globalTradingVariables.liquidationParams?.pairs?.[pairIndex] ||
+        globalTradingVariables.liquidationParams?.groups?.[0]; // fallback to first group
+    return {
+        // Trade state
+        isOpen: additionalParams.isOpen,
+        isPnlPositive: additionalParams.isPnlPositive,
+        createdBlock: additionalParams.createdBlock,
+        // Protection factors
+        liquidationParams,
+        currentBlock: additionalParams.currentBlock,
+        contractsVersion: additionalParams.contractsVersion,
+        protectionCloseFactorWhitelist,
+        // Price impact data
+        pairDepthBands,
+        depthBandsMapping,
+        oiWindowsSettings,
+        oiWindows,
+        // User/collateral specific
+        userPriceImpact,
+        collateralPriceUsd: collateral.prices?.collateralPriceUsd || 1,
+        // Pair factors (spread across the context)
+        ...pairFactor,
+    };
+};
+exports.buildCumulVolContext = buildCumulVolContext;

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

@@ -0,0 +1,94 @@
+/**
+ * @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";
+import { DepthBands, PairDepthBands, DepthBandsMapping } 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[];
+/**
+ * @dev Converts decoded depth bands from contract to SDK format
+ * @param totalDepthUsd Total depth in USD (already decoded from contract)
+ * @param bandsBps Array of 30 band percentages in basis points from contract
+ * @returns Normalized depth bands with bands in 0-1 range
+ */
+export declare const convertDepthBands: (totalDepthUsd: number, bandsBps: number[]) => DepthBands;
+/**
+ * @dev Converts decoded pair depth bands from contract to SDK format
+ * @param aboveDepth Decoded above depth bands from getPairDepthBandsDecoded
+ * @param belowDepth Decoded below depth bands from getPairDepthBandsDecoded
+ * @returns Normalized pair depth bands with above/below
+ */
+export declare const convertPairDepthBands: (aboveDepth: {
+    totalDepthUsd: number;
+    bands: number[];
+} | undefined, belowDepth: {
+    totalDepthUsd: number;
+    bands: number[];
+} | undefined) => PairDepthBands;
+/**
+ * @dev Converts decoded depth bands mapping from contract to SDK format
+ * @param bandsBps Array of 30 band offset values in basis points from getDepthBandsMappingDecoded
+ * @returns Normalized depth bands mapping with offset values in 0-1 range
+ */
+export declare const convertDepthBandsMapping: (bandsBps: number[]) => DepthBandsMapping;
+/**
+ * @dev Validates depth bands have correct number of bands
+ * @param depthBands Depth bands to validate
+ * @returns True if valid (30 bands)
+ */
+export declare const validateDepthBands: (depthBands: DepthBands) => boolean;
+/**
+ * @dev Validates depth bands mapping has correct number of bands
+ * @param mapping Depth bands mapping to validate
+ * @returns True if valid (30 bands)
+ */
+export declare const validateDepthBandsMapping: (mapping: DepthBandsMapping) => boolean;
+/**
+ * @dev Alternative converter for decoded pair depth bands from contract
+ * @param contractData Decoded pair depth bands from getPairDepthBandsDecoded
+ * @returns Normalized pair depth bands
+ */
+export declare const convertPairDepthBandsDecoded: (contractData: {
+    above: {
+        totalDepthUsd: number;
+        bands: number[];
+    };
+    below: {
+        totalDepthUsd: number;
+        bands: number[];
+    };
+}) => PairDepthBands;
+/**
+ * @dev Alternative converter for raw slot-based pair depth bands (if needed for legacy)
+ * @param aboveSlot1 First slot for above bands
+ * @param aboveSlot2 Second slot for above bands
+ * @param belowSlot1 First slot for below bands
+ * @param belowSlot2 Second slot for below bands
+ * @returns Normalized pair depth bands
+ */
+export declare const convertPairDepthBandsFromSlots: (aboveSlot1: bigint, aboveSlot2: bigint, belowSlot1: bigint, belowSlot2: bigint) => PairDepthBands;

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

@@ -0,0 +1,155 @@
+"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.convertPairDepthBandsFromSlots = exports.convertPairDepthBandsDecoded = exports.validateDepthBandsMapping = exports.validateDepthBands = exports.convertDepthBandsMapping = exports.convertPairDepthBands = exports.convertDepthBands = exports.convertOiWindowsSettingsArray = exports.convertOiWindows = exports.convertOiWindow = exports.convertOiWindowsSettings = void 0;
+const depthBands_1 = require("../../../pricing/depthBands");
+/**
+ * @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;
+/**
+ * @dev Converts decoded depth bands from contract to SDK format
+ * @param totalDepthUsd Total depth in USD (already decoded from contract)
+ * @param bandsBps Array of 30 band percentages in basis points from contract
+ * @returns Normalized depth bands with bands in 0-1 range
+ */
+const convertDepthBands = (totalDepthUsd, bandsBps) => {
+    // Convert bands from basis points to 0-1 range
+    const bands = bandsBps.map(bps => bps / 10000);
+    return {
+        totalDepthUsd,
+        bands,
+    };
+};
+exports.convertDepthBands = convertDepthBands;
+/**
+ * @dev Converts decoded pair depth bands from contract to SDK format
+ * @param aboveDepth Decoded above depth bands from getPairDepthBandsDecoded
+ * @param belowDepth Decoded below depth bands from getPairDepthBandsDecoded
+ * @returns Normalized pair depth bands with above/below
+ */
+const convertPairDepthBands = (aboveDepth, belowDepth) => {
+    // Convert above bands if configured
+    const above = aboveDepth && aboveDepth.totalDepthUsd > 0
+        ? (0, exports.convertDepthBands)(aboveDepth.totalDepthUsd, aboveDepth.bands)
+        : undefined;
+    // Convert below bands if configured
+    const below = belowDepth && belowDepth.totalDepthUsd > 0
+        ? (0, exports.convertDepthBands)(belowDepth.totalDepthUsd, belowDepth.bands)
+        : undefined;
+    return {
+        above,
+        below,
+    };
+};
+exports.convertPairDepthBands = convertPairDepthBands;
+/**
+ * @dev Converts decoded depth bands mapping from contract to SDK format
+ * @param bandsBps Array of 30 band offset values in basis points from getDepthBandsMappingDecoded
+ * @returns Normalized depth bands mapping with offset values in 0-1 range
+ */
+const convertDepthBandsMapping = (bandsBps) => {
+    // Convert bands from basis points to 0-1 range
+    const bands = bandsBps.map(bps => bps / 10000);
+    return {
+        bands,
+    };
+};
+exports.convertDepthBandsMapping = convertDepthBandsMapping;
+/**
+ * @dev Validates depth bands have correct number of bands
+ * @param depthBands Depth bands to validate
+ * @returns True if valid (30 bands)
+ */
+const validateDepthBands = (depthBands) => {
+    return depthBands.bands.length === 30;
+};
+exports.validateDepthBands = validateDepthBands;
+/**
+ * @dev Validates depth bands mapping has correct number of bands
+ * @param mapping Depth bands mapping to validate
+ * @returns True if valid (30 bands)
+ */
+const validateDepthBandsMapping = (mapping) => {
+    return mapping.bands.length === 30;
+};
+exports.validateDepthBandsMapping = validateDepthBandsMapping;
+/**
+ * @dev Alternative converter for decoded pair depth bands from contract
+ * @param contractData Decoded pair depth bands from getPairDepthBandsDecoded
+ * @returns Normalized pair depth bands
+ */
+const convertPairDepthBandsDecoded = (contractData) => {
+    return (0, exports.convertPairDepthBands)(contractData.above, contractData.below);
+};
+exports.convertPairDepthBandsDecoded = convertPairDepthBandsDecoded;
+/**
+ * @dev Alternative converter for raw slot-based pair depth bands (if needed for legacy)
+ * @param aboveSlot1 First slot for above bands
+ * @param aboveSlot2 Second slot for above bands
+ * @param belowSlot1 First slot for below bands
+ * @param belowSlot2 Second slot for below bands
+ * @returns Normalized pair depth bands
+ */
+const convertPairDepthBandsFromSlots = (aboveSlot1, aboveSlot2, belowSlot1, belowSlot2) => {
+    // Use the decoding functions from pricing module if raw slots are provided
+    const above = aboveSlot1 !== BigInt(0) || aboveSlot2 !== BigInt(0)
+        ? (0, depthBands_1.decodeDepthBands)(aboveSlot1, aboveSlot2)
+        : undefined;
+    const below = belowSlot1 !== BigInt(0) || belowSlot2 !== BigInt(0)
+        ? (0, depthBands_1.decodeDepthBands)(belowSlot1, belowSlot2)
+        : undefined;
+    return (0, exports.convertPairDepthBands)(above, below);
+};
+exports.convertPairDepthBandsFromSlots = convertPairDepthBandsFromSlots;

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

@@ -0,0 +1,109 @@
+/**
+ * @dev Cumulative volume price impact calculations
+ * @dev Mirrors contract's getTradeCumulVolPriceImpactP functionality
+ */
+import { PairDepthBands, DepthBandsMapping } from "./types";
+import { LiquidationParams, OiWindows, OiWindowsSettings, 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;
+    oiWindowsSettings?: OiWindowsSettings | undefined;
+    oiWindows?: OiWindows | undefined;
+    pairDepthBands?: PairDepthBands | undefined;
+    depthBandsMapping?: DepthBandsMapping | 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 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, context: CumulVolContext) => 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, context: CumulVolContext) => number;
+export { convertOiWindowsSettings, convertOiWindow, convertOiWindows, convertOiWindowsSettingsArray, } from "./converter";
+export { buildCumulVolContext } from "./builder";