@gainsnetwork/sdk 1.1.0 → 1.1.1-rc1

package/lib/pricing/depthBands/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * @dev Depth bands module exports
+ */
+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 });
+// Types
+__exportStar(require("./types"), exports);
+// Core functions
+__exportStar(require("./encoder"), exports);
+__exportStar(require("./decoder"), exports);
+__exportStar(require("./validator"), exports);
+__exportStar(require("./converter"), exports);

package/lib/pricing/depthBands/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @dev Depth bands types for price impact calculations
+ */
+export declare const DEPTH_BANDS_COUNT = 30;
+export declare const DEPTH_BANDS_PER_SLOT1 = 14;
+export declare const HUNDRED_P_BPS = 10000;
+/**
+ * @dev Encoded depth bands for a single direction
+ */
+export interface EncodedDepthBands {
+    slot1: bigint;
+    slot2: bigint;
+}
+/**
+ * @dev Encoded depth bands for both directions
+ */
+export interface PairDepthBands {
+    aboveSlot1: bigint;
+    aboveSlot2: bigint;
+    belowSlot1: bigint;
+    belowSlot2: bigint;
+}
+/**
+ * @dev Decoded depth bands data
+ */
+export interface DecodedDepthBands {
+    totalDepthUsd: number;
+    bands: number[];
+}
+/**
+ * @dev Input for encoding depth bands
+ */
+export interface DepthBandsInput {
+    totalDepthUsd: number;
+    cumulativeDepthUsd: number[];
+}
+/**
+ * @dev Depth bands mapping for all pairs
+ */
+export interface DepthBandsMapping {
+    slot1: bigint;
+    slot2: bigint;
+}
+/**
+ * @dev Decoded depth bands mapping
+ */
+export interface DecodedDepthBandsMapping {
+    bands: number[];
+}

package/lib/pricing/depthBands/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * @dev Depth bands types for price impact calculations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUNDRED_P_BPS = exports.DEPTH_BANDS_PER_SLOT1 = exports.DEPTH_BANDS_COUNT = void 0;
+// Constants matching smart contract
+exports.DEPTH_BANDS_COUNT = 30;
+exports.DEPTH_BANDS_PER_SLOT1 = 14;
+exports.HUNDRED_P_BPS = 10000;

package/lib/pricing/depthBands/validator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @dev Depth bands validation functions
+ */
+import { type DecodedDepthBands, type DepthBandsInput } from "./types";
+/**
+ * Validate that depth bands are properly formed
+ * @param bands Decoded depth bands to validate
+ * @throws Error if bands are invalid
+ */
+export declare function validateDepthBands(bands: DecodedDepthBands): void;
+/**
+ * Validate depth bands input before encoding
+ * @param input Depth bands input to validate
+ * @throws Error if input is invalid
+ */
+export declare function validateDepthBandsInput(input: DepthBandsInput): void;
+/**
+ * Validate depth bands mapping
+ * @param bands Array of band offset values in ppm
+ * @throws Error if mapping is invalid
+ */
+export declare function validateDepthBandsMapping(bands: number[]): void;

package/lib/pricing/depthBands/validator.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * @dev Depth bands validation functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDepthBandsMapping = exports.validateDepthBandsInput = exports.validateDepthBands = void 0;
+const types_1 = require("./types");
+/**
+ * Validate that depth bands are properly formed
+ * @param bands Decoded depth bands to validate
+ * @throws Error if bands are invalid
+ */
+function validateDepthBands(bands) {
+    const { totalDepthUsd, bands: bandValues } = bands;
+    // Check band count
+    if (bandValues.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid band count: expected ${types_1.DEPTH_BANDS_COUNT}, got ${bandValues.length}`);
+    }
+    // Check totalDepthUsd is non-negative
+    if (totalDepthUsd < 0) {
+        throw new Error(`Total depth USD cannot be negative: ${totalDepthUsd}`);
+    }
+    // Check bands are monotonically increasing
+    let prevBand = 0;
+    for (let i = 0; i < bandValues.length; i++) {
+        const band = bandValues[i];
+        if (band < 0) {
+            throw new Error(`Band ${i} cannot be negative: ${band}`);
+        }
+        if (band < prevBand) {
+            throw new Error(`Band ${i} (${band}) is less than previous band (${prevBand})`);
+        }
+        if (band > types_1.HUNDRED_P_BPS) {
+            throw new Error(`Band ${i} exceeds 100%: ${band} bps > ${types_1.HUNDRED_P_BPS} bps`);
+        }
+        prevBand = band;
+    }
+    // Check that last band reaches 100% (with tolerance for rounding)
+    const lastBand = bandValues[bandValues.length - 1];
+    if (totalDepthUsd > 0 && Math.abs(lastBand - types_1.HUNDRED_P_BPS) > 10) {
+        throw new Error(`Last band does not reach 100%: ${lastBand} bps (expected ~${types_1.HUNDRED_P_BPS} bps)`);
+    }
+}
+exports.validateDepthBands = validateDepthBands;
+/**
+ * Validate depth bands input before encoding
+ * @param input Depth bands input to validate
+ * @throws Error if input is invalid
+ */
+function validateDepthBandsInput(input) {
+    const { totalDepthUsd, cumulativeDepthUsd } = input;
+    // Check array length
+    if (cumulativeDepthUsd.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid cumulative depth array length: expected ${types_1.DEPTH_BANDS_COUNT}, got ${cumulativeDepthUsd.length}`);
+    }
+    // Check totalDepthUsd
+    if (totalDepthUsd < 0) {
+        throw new Error(`Total depth USD cannot be negative: ${totalDepthUsd}`);
+    }
+    const maxUint32 = Math.pow(2, 32) - 1;
+    if (totalDepthUsd > maxUint32) {
+        throw new Error(`Total depth USD exceeds uint32 max: ${totalDepthUsd} > ${maxUint32}`);
+    }
+    // Check cumulative values are monotonically increasing
+    let prevValue = 0;
+    for (let i = 0; i < cumulativeDepthUsd.length; i++) {
+        const value = cumulativeDepthUsd[i];
+        if (value < 0) {
+            throw new Error(`Cumulative depth at band ${i} cannot be negative: ${value}`);
+        }
+        if (value < prevValue) {
+            throw new Error(`Cumulative depth at band ${i} (${value}) is less than previous (${prevValue})`);
+        }
+        if (value > totalDepthUsd) {
+            throw new Error(`Cumulative depth at band ${i} (${value}) exceeds total depth (${totalDepthUsd})`);
+        }
+        prevValue = value;
+    }
+    // Check that last cumulative value equals total depth (with tolerance)
+    const lastValue = cumulativeDepthUsd[cumulativeDepthUsd.length - 1];
+    if (totalDepthUsd > 0 && Math.abs(lastValue - totalDepthUsd) > 1) {
+        throw new Error(`Last cumulative depth (${lastValue}) does not match total depth (${totalDepthUsd})`);
+    }
+}
+exports.validateDepthBandsInput = validateDepthBandsInput;
+/**
+ * Validate depth bands mapping
+ * @param bands Array of band offset values in ppm
+ * @throws Error if mapping is invalid
+ */
+function validateDepthBandsMapping(bands) {
+    // Check array length
+    if (bands.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid band count: expected ${types_1.DEPTH_BANDS_COUNT}, got ${bands.length}`);
+    }
+    // Check bands are monotonically increasing and within range
+    let prevBand = 0;
+    const maxUint16 = Math.pow(2, 16) - 1;
+    for (let i = 0; i < bands.length; i++) {
+        const band = bands[i];
+        if (band < 0) {
+            throw new Error(`Band ${i} cannot be negative: ${band}`);
+        }
+        if (band > maxUint16) {
+            throw new Error(`Band ${i} exceeds uint16 max: ${band} > ${maxUint16}`);
+        }
+        if (band < prevBand) {
+            throw new Error(`Band ${i} (${band} ppm) is less than previous band (${prevBand} ppm)`);
+        }
+        prevBand = band;
+    }
+}
+exports.validateDepthBandsMapping = validateDepthBandsMapping;

package/lib/pricing/depthBands.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @dev Depth bands encoding/decoding functions
+ */
+/**
+ * Encode depth bands data into two uint256 slots
+ * @param totalDepthUsd Total depth in USD (must fit in uint32)
+ * @param bandPercentagesBps Array of 30 band percentages in basis points
+ * @returns Two slots as bigints
+ */
+export declare function encodeDepthBands(totalDepthUsd: number, bandPercentagesBps: number[]): {
+    slot1: bigint;
+    slot2: bigint;
+};
+/**
+ * Decode depth bands from two uint256 slots
+ * @param slot1 First slot containing totalDepthUsd and bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Total depth and array of band percentages
+ */
+export declare function decodeDepthBands(slot1: bigint, slot2: bigint): {
+    totalDepthUsd: number;
+    bands: number[];
+};
+/**
+ * Encode depth bands mapping (global offsets for all pairs)
+ * @param bands Array of 30 band offset values in ppm
+ * @returns Two slots as bigints
+ */
+export declare function encodeDepthBandsMapping(bands: number[]): {
+    slot1: bigint;
+    slot2: bigint;
+};
+/**
+ * Decode depth bands mapping from two uint256 slots
+ * @param slot1 First slot containing bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Array of band offset values in ppm
+ */
+export declare function decodeDepthBandsMapping(slot1: bigint, slot2: bigint): number[];

package/lib/pricing/depthBands.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * @dev Depth bands encoding/decoding functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeDepthBandsMapping = exports.encodeDepthBandsMapping = exports.decodeDepthBands = exports.encodeDepthBands = void 0;
+const DEPTH_BANDS_COUNT = 30;
+const DEPTH_BANDS_PER_SLOT1 = 14;
+/**
+ * Encode depth bands data into two uint256 slots
+ * @param totalDepthUsd Total depth in USD (must fit in uint32)
+ * @param bandPercentagesBps Array of 30 band percentages in basis points
+ * @returns Two slots as bigints
+ */
+function encodeDepthBands(totalDepthUsd, bandPercentagesBps) {
+    // Pack slot1: totalDepthUsd (32 bits) + bands 0-13 (14 * 16 bits)
+    let slot1 = BigInt(totalDepthUsd);
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        const shift = 32 + i * 16;
+        slot1 |= BigInt(bandPercentagesBps[i]) << BigInt(shift);
+    }
+    // Pack slot2: bands 14-29 (16 * 16 bits)
+    let slot2 = BigInt(0);
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        slot2 |= BigInt(bandPercentagesBps[i]) << BigInt(shift);
+    }
+    return { slot1, slot2 };
+}
+exports.encodeDepthBands = encodeDepthBands;
+/**
+ * Decode depth bands from two uint256 slots
+ * @param slot1 First slot containing totalDepthUsd and bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Total depth and array of band percentages
+ */
+function decodeDepthBands(slot1, slot2) {
+    const totalDepthUsd = Number(slot1 & BigInt(0xffffffff));
+    const bands = [];
+    // Extract bands 0-13 from slot1
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        const shift = 32 + i * 16;
+        bands.push(Number((slot1 >> BigInt(shift)) & BigInt(0xffff)));
+    }
+    // Extract bands 14-29 from slot2
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        bands.push(Number((slot2 >> BigInt(shift)) & BigInt(0xffff)));
+    }
+    return { totalDepthUsd, bands };
+}
+exports.decodeDepthBands = decodeDepthBands;
+/**
+ * Encode depth bands mapping (global offsets for all pairs)
+ * @param bands Array of 30 band offset values in ppm
+ * @returns Two slots as bigints
+ */
+function encodeDepthBandsMapping(bands) {
+    // Pack slot1: bands 0-13 (14 * 16 bits)
+    let slot1 = BigInt(0);
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        slot1 |= BigInt(bands[i]) << BigInt(i * 16);
+    }
+    // Pack slot2: bands 14-29 (16 * 16 bits)
+    let slot2 = BigInt(0);
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        slot2 |= BigInt(bands[i]) << BigInt(shift);
+    }
+    return { slot1, slot2 };
+}
+exports.encodeDepthBandsMapping = encodeDepthBandsMapping;
+/**
+ * Decode depth bands mapping from two uint256 slots
+ * @param slot1 First slot containing bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Array of band offset values in ppm
+ */
+function decodeDepthBandsMapping(slot1, slot2) {
+    const bands = [];
+    // Extract bands 0-13 from slot1
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        bands.push(Number((slot1 >> BigInt(i * 16)) & BigInt(0xffff)));
+    }
+    // Extract bands 14-29 from slot2
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        bands.push(Number((slot2 >> BigInt(shift)) & BigInt(0xffff)));
+    }
+    return bands;
+}
+exports.decodeDepthBandsMapping = decodeDepthBandsMapping;

package/lib/pricing/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @dev Pricing module exports
+ */
+export * from "./depthBands";

package/lib/pricing/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @dev Pricing module exports
+ */
+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 });
+__exportStar(require("./depthBands"), exports);

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

@@ -0,0 +1,23 @@
+import { GlobalTradingVariablesType } from "../../backend/tradingVariables/types";
+import { TradeInfo } from "..";
+import { TradeEffectiveLeverageContext } from "./types";
+/**
+ * @dev Builds a complete context for effective leverage calculations
+ * @dev Uses the closing price impact context builder as a sub-context
+ * @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 for price impact calculations
+ * @returns Complete context ready for getTradeNewEffectiveLeverage
+ */
+export declare const buildTradeEffectiveLeverageContext: (globalTradingVariables: GlobalTradingVariablesType, collateralIndex: number, pairIndex: number, tradeInfo: TradeInfo, additionalParams: {
+    currentBlock: number;
+    contractsVersion?: number;
+    isPnlPositive?: boolean;
+    userPriceImpact?: {
+        cumulVolPriceImpactMultiplier: number;
+        fixedSpreadP: number;
+    };
+    protectionCloseFactorWhitelist?: boolean;
+}) => TradeEffectiveLeverageContext | undefined;

package/lib/trade/effectiveLeverage/builder.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTradeEffectiveLeverageContext = void 0;
+const __1 = require("..");
+/**
+ * @dev Builds a complete context for effective leverage calculations
+ * @dev Uses the closing price impact context builder as a sub-context
+ * @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 for price impact calculations
+ * @returns Complete context ready for getTradeNewEffectiveLeverage
+ */
+const buildTradeEffectiveLeverageContext = (globalTradingVariables, collateralIndex, pairIndex, tradeInfo, additionalParams) => {
+    var _a;
+    // Build the closing price impact context which we'll use for PnL calculations
+    const closingPriceImpactContext = (0, __1.buildTradeClosingPriceImpactContext)(globalTradingVariables, collateralIndex, pairIndex, tradeInfo, additionalParams);
+    if (!closingPriceImpactContext) {
+        return undefined;
+    }
+    // Extract base spread from pairs data
+    const pairs = globalTradingVariables.pairs;
+    const baseSpreadP = ((_a = pairs === null || pairs === void 0 ? void 0 : pairs[pairIndex]) === null || _a === void 0 ? void 0 : _a.spreadP) || 0;
+    return {
+        closingPriceImpactContext,
+        baseSpreadP,
+    };
+};
+exports.buildTradeEffectiveLeverageContext = buildTradeEffectiveLeverageContext;

package/lib/trade/fees/holdingFees/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @dev Holding fees calculation utilities for v10+ markets
+ * @dev Combines funding fees and borrowing v2 fees
+ */
+import { FundingFeeParams, PairFundingFeeData, PairOiAfterV10 } from "../fundingFees/types";
+import { BorrowingFeeParams, PairBorrowingFeeData } from "../borrowingV2/types";
+export type HoldingFeeRates = {
+    longHourlyRate: number;
+    shortHourlyRate: number;
+    fundingFeeLongHourlyRate: number;
+    fundingFeeShortHourlyRate: number;
+    borrowingFeeHourlyRate: number;
+    currentFundingRatePerSecondP: number;
+    currentBorrowingRatePerSecondP: number;
+};
+export type GetPairHoldingFeeRatesInput = {
+    fundingParams: FundingFeeParams;
+    fundingData: PairFundingFeeData;
+    pairOiToken: PairOiAfterV10;
+    netExposureToken: number;
+    netExposureUsd: number;
+    borrowingParams: BorrowingFeeParams | null;
+    borrowingData: PairBorrowingFeeData | null;
+    currentPairPrice: number;
+    currentTimestamp: number;
+};
+/**
+ * @dev Calculates current holding fee rates per hour for display
+ * @param input Input parameters for calculation
+ * @returns Holding fee rates per hour with breakdown
+ */
+export declare const getPairHoldingFeeRates: (input: GetPairHoldingFeeRatesInput) => HoldingFeeRates;
+/**
+ * @dev Converts a per-second rate to annual percentage rate (APR)
+ * @param ratePerSecond Rate per second
+ * @returns Annual percentage rate
+ */
+export declare const convertRatePerSecondToAPR: (ratePerSecond: number) => number;
+/**
+ * @dev Formats a holding fee rate for display
+ * @param rate Hourly rate (can be negative)
+ * @param decimals Number of decimal places
+ * @returns Formatted string with sign
+ */
+export declare const formatHoldingFeeRate: (rate: number, decimals?: number) => string;
+export * as HoldingFees from "./types";

package/lib/trade/fees/holdingFees/index.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * @dev Holding fees calculation utilities for v10+ markets
+ * @dev Combines funding fees and borrowing v2 fees
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HoldingFees = exports.formatHoldingFeeRate = exports.convertRatePerSecondToAPR = exports.getPairHoldingFeeRates = void 0;
+const fundingFees_1 = require("../fundingFees");
+const SECONDS_PER_HOUR = 3600;
+const SECONDS_PER_YEAR = 365 * 24 * 60 * 60;
+const PERCENTAGE_PRECISION = 100;
+/**
+ * @dev Calculates current holding fee rates per hour for display
+ * @param input Input parameters for calculation
+ * @returns Holding fee rates per hour with breakdown
+ */
+const getPairHoldingFeeRates = (input) => {
+    const { fundingParams, fundingData, pairOiToken, netExposureToken, netExposureUsd, borrowingParams, borrowingData, currentPairPrice, currentTimestamp, } = input;
+    // Calculate funding fee rates
+    let fundingFeeLongHourlyRate = 0;
+    let fundingFeeShortHourlyRate = 0;
+    let currentFundingRatePerSecondP = 0;
+    if (fundingParams.fundingFeesEnabled) {
+        // Get current funding rate
+        const pendingFunding = (0, fundingFees_1.getPairPendingAccFundingFees)(fundingParams, fundingData, currentPairPrice, pairOiToken, netExposureToken, netExposureUsd, currentTimestamp);
+        currentFundingRatePerSecondP = pendingFunding.currentFundingRatePerSecondP;
+        // Get APR multipliers
+        const { longAprMultiplier, shortAprMultiplier } = (0, fundingFees_1.getLongShortAprMultiplier)(currentFundingRatePerSecondP, pairOiToken.oiLongToken, pairOiToken.oiShortToken, fundingParams.aprMultiplierEnabled);
+        // Calculate hourly rates
+        // Funding rate * seconds per hour * current price * APR multiplier / 100
+        const baseHourlyRate = (currentFundingRatePerSecondP * SECONDS_PER_HOUR * currentPairPrice) /
+            PERCENTAGE_PRECISION;
+        // Long side pays when rate is positive, earns when negative
+        fundingFeeLongHourlyRate = baseHourlyRate * longAprMultiplier;
+        // Short side is opposite
+        fundingFeeShortHourlyRate = -baseHourlyRate * shortAprMultiplier;
+    }
+    // Calculate borrowing v2 rates
+    let borrowingFeeHourlyRate = 0;
+    let currentBorrowingRatePerSecondP = 0;
+    if (borrowingParams && borrowingData) {
+        currentBorrowingRatePerSecondP = borrowingParams.borrowingRatePerSecondP;
+        // Borrowing rate * seconds per hour * current price / 100
+        borrowingFeeHourlyRate =
+            (currentBorrowingRatePerSecondP * SECONDS_PER_HOUR * currentPairPrice) /
+                PERCENTAGE_PRECISION;
+    }
+    // Total holding fees (funding can be negative/positive, borrowing always positive cost)
+    const longHourlyRate = fundingFeeLongHourlyRate + borrowingFeeHourlyRate;
+    const shortHourlyRate = fundingFeeShortHourlyRate + borrowingFeeHourlyRate;
+    return {
+        longHourlyRate,
+        shortHourlyRate,
+        fundingFeeLongHourlyRate,
+        fundingFeeShortHourlyRate,
+        borrowingFeeHourlyRate,
+        currentFundingRatePerSecondP,
+        currentBorrowingRatePerSecondP,
+    };
+};
+exports.getPairHoldingFeeRates = getPairHoldingFeeRates;
+/**
+ * @dev Converts a per-second rate to annual percentage rate (APR)
+ * @param ratePerSecond Rate per second
+ * @returns Annual percentage rate
+ */
+const convertRatePerSecondToAPR = (ratePerSecond) => {
+    return ratePerSecond * SECONDS_PER_YEAR * PERCENTAGE_PRECISION;
+};
+exports.convertRatePerSecondToAPR = convertRatePerSecondToAPR;
+/**
+ * @dev Formats a holding fee rate for display
+ * @param rate Hourly rate (can be negative)
+ * @param decimals Number of decimal places
+ * @returns Formatted string with sign
+ */
+const formatHoldingFeeRate = (rate, decimals = 4) => {
+    const sign = rate > 0 ? "+" : "";
+    return `${sign}${rate.toFixed(decimals)}%`;
+};
+exports.formatHoldingFeeRate = formatHoldingFeeRate;
+exports.HoldingFees = __importStar(require("./types"));

package/lib/trade/fees/holdingFees/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @dev Type definitions for holding fees (funding + borrowing v2)
+ */
+export interface HoldingFeeRates {
+    longHourlyRate: number;
+    shortHourlyRate: number;
+    fundingFeeLongHourlyRate: number;
+    fundingFeeShortHourlyRate: number;
+    borrowingFeeHourlyRate: number;
+    currentFundingRatePerSecondP: number;
+    currentBorrowingRatePerSecondP: number;
+}
+export interface GetPairHoldingFeeRatesInput {
+    fundingParams: import("../fundingFees/types").FundingFeeParams;
+    fundingData: import("../fundingFees/types").PairFundingFeeData;
+    pairOiToken: import("../fundingFees/types").PairOiAfterV10;
+    netExposureToken: number;
+    netExposureUsd: number;
+    borrowingParams: import("../borrowingV2/types").BorrowingFeeParams | null;
+    borrowingData: import("../borrowingV2/types").PairBorrowingFeeData | null;
+    currentPairPrice: number;
+    currentTimestamp: number;
+}

package/lib/trade/fees/holdingFees/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @dev Type definitions for holding fees (funding + borrowing v2)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/trade/fees/trading/holdingFees.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @dev Holding fees calculation for structured contexts
+ */
+import { Trade, TradeInfo, TradeFeesData } from "../../types";
+import { TradeHoldingFees } from "./types";
+import { ContractsVersion } from "../../../contracts/types";
+import type { BorrowingV1SubContext, BorrowingV2SubContext, FundingFeesSubContext } from "../../pnl";
+/**
+ * @dev Context for holding fees calculation with structured sub-contexts
+ */
+export type GetStructuredHoldingFeesContext = {
+    contractsVersion: ContractsVersion;
+    currentTimestamp: number;
+    collateralPriceUsd: number;
+    borrowingV1?: BorrowingV1SubContext;
+    borrowingV2?: BorrowingV2SubContext;
+    funding?: FundingFeesSubContext;
+};
+/**
+ * @dev Calculates total holding fees using structured context
+ * @param trade The trade to calculate fees for
+ * @param tradeInfo Trade info containing contracts version
+ * @param tradeFeesData Trade fees data containing initial acc fees
+ * @param currentPairPrice Current pair price
+ * @param context Structured context with sub-contexts for each fee type
+ * @returns Object containing all holding fee components
+ */
+export declare const getTradePendingHoldingFeesCollateralStructured: (trade: Trade, tradeInfo: TradeInfo, tradeFeesData: TradeFeesData, currentPairPrice: number, context: GetStructuredHoldingFeesContext) => TradeHoldingFees;