@gainsnetwork/sdk 0.2.67-rc7 → 0.2.67-rc8

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

@@ -0,0 +1,95 @@
+/**
+ * @dev Types for borrowing v2 fees system (simplified rate-based model)
+ */
+/**
+ * @dev Borrowing fee parameters for a specific pair/collateral combination
+ */
+export type BorrowingFeeParams = {
+    /**
+     * @dev Borrowing rate % per second
+     * @dev Raw contract value divided by 1e10
+     * @dev Max: ~0.0000317097 => 1,000% APR
+     */
+    borrowingRatePerSecondP: number;
+};
+/**
+ * @dev Accumulated borrowing fee data for a specific pair/collateral combination
+ */
+export type PairBorrowingFeeData = {
+    /**
+     * @dev Accumulated borrowing fees % weighted by pair price
+     * @dev Unit: fee collateral per 100 units of OI in pair amount
+     */
+    accBorrowingFeeP: number;
+    /**
+     * @dev Timestamp of last accumulated borrowing fees update
+     */
+    lastBorrowingUpdateTs: number;
+};
+/**
+ * @dev Trade-specific borrowing fee data stored when position is opened
+ */
+export type TradeInitialAccFees = {
+    /**
+     * @dev Initial accumulated borrowing fee when trade was opened (normalized float)
+     * @dev Raw contract value divided by 1e20
+     * @dev Used to calculate how much borrowing fees the trade owes
+     */
+    initialAccBorrowingFeeP: number;
+};
+/**
+ * @dev Context required for borrowing v2 fee calculations
+ * @dev Context is already scoped to a specific collateral
+ */
+export type GetBorrowingFeeV2Context = {
+    /**
+     * @dev Current timestamp (defaults to Date.now() / 1000)
+     */
+    currentTimestamp?: number;
+    /**
+     * @dev Borrowing fee parameters for pairs
+     * @dev Indexed by: params[pairIndex]
+     */
+    borrowingParams: Record<number, BorrowingFeeParams>;
+    /**
+     * @dev Borrowing fee data for pairs
+     * @dev Indexed by: data[pairIndex]
+     */
+    borrowingData: Record<number, PairBorrowingFeeData>;
+};
+/**
+ * @dev Context for pair-specific borrowing v2 fee calculations
+ */
+export type GetPairBorrowingFeeV2Context = {
+    /**
+     * @dev Current timestamp (defaults to Date.now() / 1000)
+     */
+    currentTimestamp?: number;
+    /**
+     * @dev Borrowing fee parameters for this specific pair
+     */
+    params: BorrowingFeeParams;
+    /**
+     * @dev Borrowing fee data for this specific pair
+     */
+    data: PairBorrowingFeeData;
+};
+/**
+ * @dev Input for calculating pending borrowing fees for a pair
+ */
+export type PairBorrowingFeeInput = {
+    pairIndex: number;
+    currentPairPrice: number;
+    currentTimestamp?: number;
+};
+/**
+ * @dev Input for calculating borrowing fees for a specific trade
+ */
+export type TradeBorrowingFeeInput = {
+    positionSizeCollateral: number;
+    openPrice: number;
+    pairIndex: number;
+    currentPairPrice: number;
+    initialAccBorrowingFeeP: number;
+    currentTimestamp?: number;
+};

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

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * @dev Types for borrowing v2 fees system (simplified rate-based model)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,48 @@
+/**
+ * @dev Converters for fee data between contract and SDK formats
+ */
+import { IFundingFees } from "../../contracts/types/generated/GNSMultiCollatDiamond";
+import { TradeFeesData, UiRealizedPnlData } from "../types";
+import { CollateralConfig } from "../../markets/collateral/types";
+/**
+ * @dev Converts contract TradeFeesData to SDK format
+ * @param data Trade fees data from contract
+ * @param collateralConfig Config for the collateral (contains decimals)
+ * @returns Normalized trade fees data
+ */
+export declare const convertTradeFeesData: (data: IFundingFees.TradeFeesDataStructOutput, collateralConfig: CollateralConfig) => TradeFeesData;
+/**
+ * @dev Converts array of TradeFeesData from contract
+ * @param dataArray Array of trade fees data
+ * @param collateralConfig Config for the collateral
+ * @returns Array of normalized trade fees data
+ */
+export declare const convertTradeFeesDataArray: (dataArray: IFundingFees.TradeFeesDataStructOutput[], collateralConfig: CollateralConfig) => TradeFeesData[];
+/**
+ * @dev Converts contract UiRealizedPnlData to SDK format
+ * @param data UI realized PnL data from contract
+ * @param collateralConfig Config for the collateral (contains decimals)
+ * @returns Normalized UI realized PnL data
+ */
+export declare const convertUiRealizedPnlData: (data: IFundingFees.UiRealizedPnlDataStructOutput, collateralConfig: CollateralConfig) => UiRealizedPnlData;
+/**
+ * @dev Converts array of UiRealizedPnlData from contract
+ * @param dataArray Array of UI realized PnL data
+ * @param collateralConfig Config for the collateral
+ * @returns Array of normalized UI realized PnL data
+ */
+export declare const convertUiRealizedPnlDataArray: (dataArray: IFundingFees.UiRealizedPnlDataStructOutput[], collateralConfig: CollateralConfig) => UiRealizedPnlData[];
+/**
+ * @dev Converts TradeFeesData to contract format (for encoding)
+ * @param data SDK trade fees data
+ * @param collateralConfig Config for the collateral
+ * @returns Contract-formatted trade fees data
+ */
+export declare const encodeTradeFeesData: (data: TradeFeesData, collateralConfig: CollateralConfig) => IFundingFees.TradeFeesDataStruct;
+/**
+ * @dev Converts UiRealizedPnlData to contract format (for encoding)
+ * @param data SDK UI realized PnL data
+ * @param collateralConfig Config for the collateral
+ * @returns Contract-formatted UI realized PnL data
+ */
+export declare const encodeUiRealizedPnlData: (data: UiRealizedPnlData, collateralConfig: CollateralConfig) => IFundingFees.UiRealizedPnlDataStruct;

package/lib/trade/fees/converter.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * @dev Converters for fee data between contract and SDK formats
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeUiRealizedPnlData = exports.encodeTradeFeesData = exports.convertUiRealizedPnlDataArray = exports.convertUiRealizedPnlData = exports.convertTradeFeesDataArray = exports.convertTradeFeesData = void 0;
+/**
+ * @dev Converts contract TradeFeesData to SDK format
+ * @param data Trade fees data from contract
+ * @param collateralConfig Config for the collateral (contains decimals)
+ * @returns Normalized trade fees data
+ */
+const convertTradeFeesData = (data, collateralConfig) => {
+    const decimals = collateralConfig.decimals || 18;
+    return {
+        realizedTradingFeesCollateral: parseFloat(data.realizedTradingFeesCollateral.toString()) /
+            Math.pow(10, decimals),
+        realizedPnlCollateral: parseFloat(data.realizedPnlCollateral.toString()) / Math.pow(10, decimals),
+        manuallyRealizedNegativePnlCollateral: parseFloat(data.manuallyRealizedNegativePnlCollateral.toString()) /
+            Math.pow(10, decimals),
+        alreadyTransferredNegativePnlCollateral: parseFloat(data.alreadyTransferredNegativePnlCollateral.toString()) /
+            Math.pow(10, decimals),
+        virtualAvailableCollateralInDiamond: parseFloat(data.virtualAvailableCollateralInDiamond.toString()) /
+            Math.pow(10, decimals),
+        initialAccFundingFeeP: parseFloat(data.initialAccFundingFeeP.toString()) / 1e10,
+        initialAccBorrowingFeeP: parseFloat(data.initialAccBorrowingFeeP.toString()) / 1e10,
+    };
+};
+exports.convertTradeFeesData = convertTradeFeesData;
+/**
+ * @dev Converts array of TradeFeesData from contract
+ * @param dataArray Array of trade fees data
+ * @param collateralConfig Config for the collateral
+ * @returns Array of normalized trade fees data
+ */
+const convertTradeFeesDataArray = (dataArray, collateralConfig) => {
+    return dataArray.map(data => (0, exports.convertTradeFeesData)(data, collateralConfig));
+};
+exports.convertTradeFeesDataArray = convertTradeFeesDataArray;
+/**
+ * @dev Converts contract UiRealizedPnlData to SDK format
+ * @param data UI realized PnL data from contract
+ * @param collateralConfig Config for the collateral (contains decimals)
+ * @returns Normalized UI realized PnL data
+ */
+const convertUiRealizedPnlData = (data, collateralConfig) => {
+    const decimals = collateralConfig.decimals || 18;
+    return {
+        realizedTradingFeesCollateral: parseFloat(data.realizedTradingFeesCollateral.toString()) /
+            Math.pow(10, decimals),
+        realizedOldBorrowingFeesCollateral: parseFloat(data.realizedOldBorrowingFeesCollateral.toString()) /
+            Math.pow(10, decimals),
+        realizedNewBorrowingFeesCollateral: parseFloat(data.realizedNewBorrowingFeesCollateral.toString()) /
+            Math.pow(10, decimals),
+        realizedFundingFeesCollateral: parseFloat(data.realizedFundingFeesCollateral.toString()) /
+            Math.pow(10, decimals),
+        realizedPnlPartialCloseCollateral: parseFloat(data.realizedPnlPartialCloseCollateral.toString()) /
+            Math.pow(10, decimals),
+        pnlWithdrawnCollateral: parseFloat(data.pnlWithdrawnCollateral.toString()) / Math.pow(10, decimals),
+    };
+};
+exports.convertUiRealizedPnlData = convertUiRealizedPnlData;
+/**
+ * @dev Converts array of UiRealizedPnlData from contract
+ * @param dataArray Array of UI realized PnL data
+ * @param collateralConfig Config for the collateral
+ * @returns Array of normalized UI realized PnL data
+ */
+const convertUiRealizedPnlDataArray = (dataArray, collateralConfig) => {
+    return dataArray.map(data => (0, exports.convertUiRealizedPnlData)(data, collateralConfig));
+};
+exports.convertUiRealizedPnlDataArray = convertUiRealizedPnlDataArray;
+/**
+ * @dev Converts TradeFeesData to contract format (for encoding)
+ * @param data SDK trade fees data
+ * @param collateralConfig Config for the collateral
+ * @returns Contract-formatted trade fees data
+ */
+const encodeTradeFeesData = (data, collateralConfig) => {
+    const decimals = collateralConfig.decimals || 18;
+    return {
+        realizedTradingFeesCollateral: Math.round(data.realizedTradingFeesCollateral * Math.pow(10, decimals)),
+        realizedPnlCollateral: Math.round(data.realizedPnlCollateral * Math.pow(10, decimals)),
+        manuallyRealizedNegativePnlCollateral: Math.round(data.manuallyRealizedNegativePnlCollateral * Math.pow(10, decimals)),
+        alreadyTransferredNegativePnlCollateral: Math.round(data.alreadyTransferredNegativePnlCollateral * Math.pow(10, decimals)),
+        virtualAvailableCollateralInDiamond: Math.round(data.virtualAvailableCollateralInDiamond * Math.pow(10, decimals)),
+        __placeholder: 0,
+        initialAccFundingFeeP: Math.round(data.initialAccFundingFeeP * 1e10),
+        initialAccBorrowingFeeP: Math.round(data.initialAccBorrowingFeeP * 1e10),
+    };
+};
+exports.encodeTradeFeesData = encodeTradeFeesData;
+/**
+ * @dev Converts UiRealizedPnlData to contract format (for encoding)
+ * @param data SDK UI realized PnL data
+ * @param collateralConfig Config for the collateral
+ * @returns Contract-formatted UI realized PnL data
+ */
+const encodeUiRealizedPnlData = (data, collateralConfig) => {
+    const decimals = collateralConfig.decimals || 18;
+    return {
+        realizedTradingFeesCollateral: Math.round(data.realizedTradingFeesCollateral * Math.pow(10, decimals)),
+        realizedOldBorrowingFeesCollateral: Math.round(data.realizedOldBorrowingFeesCollateral * Math.pow(10, decimals)),
+        realizedNewBorrowingFeesCollateral: Math.round(data.realizedNewBorrowingFeesCollateral * Math.pow(10, decimals)),
+        realizedFundingFeesCollateral: Math.round(data.realizedFundingFeesCollateral * Math.pow(10, decimals)),
+        realizedPnlPartialCloseCollateral: Math.round(data.realizedPnlPartialCloseCollateral * Math.pow(10, decimals)),
+        pnlWithdrawnCollateral: Math.round(data.pnlWithdrawnCollateral * Math.pow(10, decimals)),
+    };
+};
+exports.encodeUiRealizedPnlData = encodeUiRealizedPnlData;

package/lib/trade/fees/fundingFees/builder.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @dev Builder functions for funding fees context
+ */
+import { GlobalTradingVariablesType } from "../../../backend/tradingVariables/types";
+import { GetPairFundingFeeContext } from "./pairContext";
+/**
+ * @dev Builds funding fees sub-context for a specific pair
+ */
+export declare const buildFundingContext: (globalTradingVariables: GlobalTradingVariablesType, collateralIndex: number, pairIndex: number, currentTimestamp: number) => GetPairFundingFeeContext | undefined;

package/lib/trade/fees/fundingFees/builder.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @dev Builder functions for funding fees context
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFundingContext = void 0;
+/**
+ * @dev Builds funding fees sub-context for a specific pair
+ */
+const buildFundingContext = (globalTradingVariables, collateralIndex, pairIndex, currentTimestamp) => {
+    var _a, _b, _c, _d, _e;
+    const collateral = globalTradingVariables.collaterals[collateralIndex - 1];
+    if (!(collateral === null || collateral === void 0 ? void 0 : collateral.pairFundingFees)) {
+        return undefined;
+    }
+    const params = (_a = collateral.pairFundingFees.params) === null || _a === void 0 ? void 0 : _a[pairIndex];
+    const data = (_b = collateral.pairFundingFees.data) === null || _b === void 0 ? void 0 : _b[pairIndex];
+    const pairOi = (_c = collateral.pairOis) === null || _c === void 0 ? void 0 : _c[pairIndex];
+    if (!params || !data) {
+        return undefined;
+    }
+    return {
+        params,
+        data,
+        pairOi: pairOi
+            ? {
+                oiLongToken: ((_d = pairOi.token) === null || _d === void 0 ? void 0 : _d.long) || 0,
+                oiShortToken: ((_e = pairOi.token) === null || _e === void 0 ? void 0 : _e.short) || 0,
+            }
+            : undefined,
+        currentTimestamp,
+        // TODO: Add net exposure when available
+    };
+};
+exports.buildFundingContext = buildFundingContext;

package/lib/trade/fees/fundingFees/converter.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @dev Converters for funding fees data between contract and SDK formats
+ * @dev All BigNumber values are normalized to floats with appropriate precision
+ */
+import { IFundingFees } from "../../../contracts/types/generated/GNSMultiCollatDiamond";
+import { FundingFeeParams, PairFundingFeeData, PairGlobalParams, TradeInitialAccFundingFees, GetFundingFeeContext } from "./types";
+export declare const FUNDING_FEES_PRECISION: {
+    SKEW_COEFFICIENT_PER_YEAR: number;
+    ABSOLUTE_VELOCITY_PER_YEAR_CAP: number;
+    ABSOLUTE_RATE_PER_SECOND_CAP: number;
+    ACC_FUNDING_FEE_P: number;
+    FUNDING_RATE_PER_SECOND_P: number;
+};
+/**
+ * @dev Converts contract funding fee params to SDK format
+ * @param contractParams Contract funding fee params struct
+ * @returns Normalized funding fee params
+ */
+export declare const convertFundingFeeParams: (contractParams: IFundingFees.FundingFeeParamsStruct) => FundingFeeParams;
+/**
+ * @dev Converts array of contract funding fee params to SDK format
+ * @param contractParamsArray Array of contract funding fee params
+ * @returns Array of normalized funding fee params
+ */
+export declare const convertFundingFeeParamsArray: (contractParamsArray: IFundingFees.FundingFeeParamsStruct[]) => FundingFeeParams[];
+/**
+ * @dev Converts contract pair funding fee data to SDK format
+ * @param contractData Contract pair funding fee data struct
+ * @returns Normalized pair funding fee data
+ */
+export declare const convertPairFundingFeeData: (contractData: IFundingFees.PairFundingFeeDataStruct) => PairFundingFeeData;
+/**
+ * @dev Converts array of contract pair funding fee data to SDK format
+ * @param contractDataArray Array of contract pair funding fee data
+ * @returns Array of normalized pair funding fee data
+ */
+export declare const convertPairFundingFeeDataArray: (contractDataArray: IFundingFees.PairFundingFeeDataStruct[]) => PairFundingFeeData[];
+/**
+ * @dev Converts contract pair global params to SDK format
+ * @param contractParams Contract pair global params struct
+ * @returns Normalized pair global params
+ */
+export declare const convertPairGlobalParams: (contractParams: IFundingFees.PairGlobalParamsStruct) => PairGlobalParams;
+/**
+ * @dev Converts array of contract pair global params to SDK format
+ * @param contractParamsArray Array of contract pair global params
+ * @returns Array of normalized pair global params
+ */
+export declare const convertPairGlobalParamsArray: (contractParamsArray: IFundingFees.PairGlobalParamsStruct[]) => PairGlobalParams[];
+/**
+ * @dev Converts contract trade initial acc funding fees to SDK format
+ * @param contractFees Contract trade fees data (only funding fee part)
+ * @returns Normalized trade initial acc funding fees
+ */
+export declare const convertTradeInitialAccFundingFees: (contractFees: {
+    initialAccFundingFeeP: bigint | number | string;
+}) => TradeInitialAccFundingFees;
+/**
+ * @dev Creates a funding fee context from arrays of data
+ * @param collateralIndices Array of collateral indices
+ * @param pairIndices Array of pair indices
+ * @param params Array of funding fee parameters
+ * @param data Array of pair funding fee data
+ * @param globalParams Optional array of global parameters
+ * @param currentTimestamp Optional current timestamp
+ * @returns Complete funding fee context
+ */
+export declare const createFundingFeeContext: (collateralIndices: number[], pairIndices: number[], params: FundingFeeParams[], data: PairFundingFeeData[], globalParams?: PairGlobalParams[], currentTimestamp?: number) => GetFundingFeeContext;
+/**
+ * @dev Validates funding rate is within allowed bounds
+ * @param absoluteRatePerSecondCap Rate cap (normalized)
+ * @returns Whether the rate is valid
+ */
+export declare const isValidFundingRate: (absoluteRatePerSecondCap: number) => boolean;
+/**
+ * @dev Converts funding rate per second to APR
+ * @param ratePerSecondP Funding rate per second (normalized)
+ * @returns APR as percentage
+ */
+export declare const fundingRateToAPR: (ratePerSecondP: number) => number;
+/**
+ * @dev Converts APR to funding rate per second
+ * @param apr APR as percentage
+ * @returns Funding rate per second (normalized)
+ */
+export declare const aprToFundingRate: (apr: number) => number;
+/**
+ * @dev Calculates velocity per year from skew coefficient
+ * @param skewRatio Current skew ratio (net exposure / total OI)
+ * @param skewCoefficientPerYear Skew coefficient per year (normalized)
+ * @returns Velocity per year
+ */
+export declare const calculateVelocityFromSkew: (skewRatio: number, skewCoefficientPerYear: number) => number;
+/**
+ * @dev Creates a GetFundingFeeContext from arrays (alias for consistency)
+ * @param collateralIndices Array of collateral indices
+ * @param pairIndices Array of pair indices
+ * @param params Array of funding fee parameters
+ * @param data Array of pair funding fee data
+ * @returns Complete funding fee context
+ */
+export declare const createGetFundingFeeContext: (collateralIndices: number[], pairIndices: number[], params: FundingFeeParams[], data: PairFundingFeeData[]) => GetFundingFeeContext;

package/lib/trade/fees/fundingFees/converter.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * @dev Converters for funding fees data between contract and SDK formats
+ * @dev All BigNumber values are normalized to floats with appropriate precision
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGetFundingFeeContext = exports.calculateVelocityFromSkew = exports.aprToFundingRate = exports.fundingRateToAPR = exports.isValidFundingRate = exports.createFundingFeeContext = exports.convertTradeInitialAccFundingFees = exports.convertPairGlobalParamsArray = exports.convertPairGlobalParams = exports.convertPairFundingFeeDataArray = exports.convertPairFundingFeeData = exports.convertFundingFeeParamsArray = exports.convertFundingFeeParams = exports.FUNDING_FEES_PRECISION = void 0;
+// Precision constants from contract
+exports.FUNDING_FEES_PRECISION = {
+    SKEW_COEFFICIENT_PER_YEAR: 1e26,
+    ABSOLUTE_VELOCITY_PER_YEAR_CAP: 1e7,
+    ABSOLUTE_RATE_PER_SECOND_CAP: 1e10,
+    ACC_FUNDING_FEE_P: 1e20,
+    FUNDING_RATE_PER_SECOND_P: 1e18, // Funding rate per second precision
+};
+/**
+ * @dev Converts contract funding fee params to SDK format
+ * @param contractParams Contract funding fee params struct
+ * @returns Normalized funding fee params
+ */
+const convertFundingFeeParams = (contractParams) => {
+    return {
+        skewCoefficientPerYear: Number(contractParams.skewCoefficientPerYear) /
+            exports.FUNDING_FEES_PRECISION.SKEW_COEFFICIENT_PER_YEAR,
+        absoluteVelocityPerYearCap: Number(contractParams.absoluteVelocityPerYearCap) /
+            exports.FUNDING_FEES_PRECISION.ABSOLUTE_VELOCITY_PER_YEAR_CAP,
+        absoluteRatePerSecondCap: Number(contractParams.absoluteRatePerSecondCap) /
+            exports.FUNDING_FEES_PRECISION.ABSOLUTE_RATE_PER_SECOND_CAP,
+        thetaThresholdUsd: Number(contractParams.thetaThresholdUsd),
+        fundingFeesEnabled: Boolean(contractParams.fundingFeesEnabled),
+        aprMultiplierEnabled: Boolean(contractParams.aprMultiplierEnabled),
+    };
+};
+exports.convertFundingFeeParams = convertFundingFeeParams;
+/**
+ * @dev Converts array of contract funding fee params to SDK format
+ * @param contractParamsArray Array of contract funding fee params
+ * @returns Array of normalized funding fee params
+ */
+const convertFundingFeeParamsArray = (contractParamsArray) => {
+    return contractParamsArray.map(exports.convertFundingFeeParams);
+};
+exports.convertFundingFeeParamsArray = convertFundingFeeParamsArray;
+/**
+ * @dev Converts contract pair funding fee data to SDK format
+ * @param contractData Contract pair funding fee data struct
+ * @returns Normalized pair funding fee data
+ */
+const convertPairFundingFeeData = (contractData) => {
+    return {
+        accFundingFeeLongP: Number(contractData.accFundingFeeLongP) /
+            exports.FUNDING_FEES_PRECISION.ACC_FUNDING_FEE_P,
+        accFundingFeeShortP: Number(contractData.accFundingFeeShortP) /
+            exports.FUNDING_FEES_PRECISION.ACC_FUNDING_FEE_P,
+        lastFundingRatePerSecondP: Number(contractData.lastFundingRatePerSecondP) /
+            exports.FUNDING_FEES_PRECISION.FUNDING_RATE_PER_SECOND_P,
+        lastFundingUpdateTs: Number(contractData.lastFundingUpdateTs),
+    };
+};
+exports.convertPairFundingFeeData = convertPairFundingFeeData;
+/**
+ * @dev Converts array of contract pair funding fee data to SDK format
+ * @param contractDataArray Array of contract pair funding fee data
+ * @returns Array of normalized pair funding fee data
+ */
+const convertPairFundingFeeDataArray = (contractDataArray) => {
+    return contractDataArray.map(exports.convertPairFundingFeeData);
+};
+exports.convertPairFundingFeeDataArray = convertPairFundingFeeDataArray;
+/**
+ * @dev Converts contract pair global params to SDK format
+ * @param contractParams Contract pair global params struct
+ * @returns Normalized pair global params
+ */
+const convertPairGlobalParams = (contractParams) => {
+    return {
+        maxSkewCollateral: Number(contractParams.maxSkewCollateral),
+    };
+};
+exports.convertPairGlobalParams = convertPairGlobalParams;
+/**
+ * @dev Converts array of contract pair global params to SDK format
+ * @param contractParamsArray Array of contract pair global params
+ * @returns Array of normalized pair global params
+ */
+const convertPairGlobalParamsArray = (contractParamsArray) => {
+    return contractParamsArray.map(exports.convertPairGlobalParams);
+};
+exports.convertPairGlobalParamsArray = convertPairGlobalParamsArray;
+/**
+ * @dev Converts contract trade initial acc funding fees to SDK format
+ * @param contractFees Contract trade fees data (only funding fee part)
+ * @returns Normalized trade initial acc funding fees
+ */
+const convertTradeInitialAccFundingFees = (contractFees) => {
+    return {
+        initialAccFundingFeeP: Number(contractFees.initialAccFundingFeeP) /
+            exports.FUNDING_FEES_PRECISION.ACC_FUNDING_FEE_P,
+    };
+};
+exports.convertTradeInitialAccFundingFees = convertTradeInitialAccFundingFees;
+/**
+ * @dev Creates a funding fee context from arrays of data
+ * @param collateralIndices Array of collateral indices
+ * @param pairIndices Array of pair indices
+ * @param params Array of funding fee parameters
+ * @param data Array of pair funding fee data
+ * @param globalParams Optional array of global parameters
+ * @param currentTimestamp Optional current timestamp
+ * @returns Complete funding fee context
+ */
+const createFundingFeeContext = (collateralIndices, pairIndices, params, data, globalParams, currentTimestamp) => {
+    const context = {
+        currentTimestamp: currentTimestamp !== null && currentTimestamp !== void 0 ? currentTimestamp : Math.floor(Date.now() / 1000),
+        fundingParams: {},
+        fundingData: {},
+        globalParams: globalParams ? {} : undefined,
+    };
+    // Build nested objects indexed by collateralIndex and pairIndex
+    for (let i = 0; i < collateralIndices.length; i++) {
+        const collateralIndex = collateralIndices[i];
+        const pairIndex = pairIndices[i];
+        // Initialize collateral index objects if they don't exist
+        if (!context.fundingParams[collateralIndex]) {
+            context.fundingParams[collateralIndex] = {};
+        }
+        if (!context.fundingData[collateralIndex]) {
+            context.fundingData[collateralIndex] = {};
+        }
+        if (globalParams && context.globalParams) {
+            if (!context.globalParams[collateralIndex]) {
+                context.globalParams[collateralIndex] = {};
+            }
+        }
+        // Store data
+        context.fundingParams[collateralIndex][pairIndex] = params[i];
+        context.fundingData[collateralIndex][pairIndex] = data[i];
+        if (globalParams && context.globalParams) {
+            context.globalParams[collateralIndex][pairIndex] = globalParams[i];
+        }
+    }
+    return context;
+};
+exports.createFundingFeeContext = createFundingFeeContext;
+/**
+ * @dev Validates funding rate is within allowed bounds
+ * @param absoluteRatePerSecondCap Rate cap (normalized)
+ * @returns Whether the rate is valid
+ */
+const isValidFundingRate = (absoluteRatePerSecondCap) => {
+    // Convert back to contract precision for validation
+    const contractValue = absoluteRatePerSecondCap *
+        exports.FUNDING_FEES_PRECISION.ABSOLUTE_RATE_PER_SECOND_CAP;
+    return contractValue <= 3170979; // MAX_FUNDING_RATE_PER_SECOND from contract
+};
+exports.isValidFundingRate = isValidFundingRate;
+/**
+ * @dev Converts funding rate per second to APR
+ * @param ratePerSecondP Funding rate per second (normalized)
+ * @returns APR as percentage
+ */
+const fundingRateToAPR = (ratePerSecondP) => {
+    return ratePerSecondP * 365 * 24 * 60 * 60 * 100;
+};
+exports.fundingRateToAPR = fundingRateToAPR;
+/**
+ * @dev Converts APR to funding rate per second
+ * @param apr APR as percentage
+ * @returns Funding rate per second (normalized)
+ */
+const aprToFundingRate = (apr) => {
+    return apr / (365 * 24 * 60 * 60 * 100);
+};
+exports.aprToFundingRate = aprToFundingRate;
+/**
+ * @dev Calculates velocity per year from skew coefficient
+ * @param skewRatio Current skew ratio (net exposure / total OI)
+ * @param skewCoefficientPerYear Skew coefficient per year (normalized)
+ * @returns Velocity per year
+ */
+const calculateVelocityFromSkew = (skewRatio, skewCoefficientPerYear) => {
+    return Math.abs(skewRatio) * skewCoefficientPerYear;
+};
+exports.calculateVelocityFromSkew = calculateVelocityFromSkew;
+/**
+ * @dev Creates a GetFundingFeeContext from arrays (alias for consistency)
+ * @param collateralIndices Array of collateral indices
+ * @param pairIndices Array of pair indices
+ * @param params Array of funding fee parameters
+ * @param data Array of pair funding fee data
+ * @returns Complete funding fee context
+ */
+const createGetFundingFeeContext = (collateralIndices, pairIndices, params, data) => {
+    return (0, exports.createFundingFeeContext)(collateralIndices, pairIndices, params, data);
+};
+exports.createGetFundingFeeContext = createGetFundingFeeContext;

package/lib/trade/fees/fundingFees/fetcher.d.ts

@@ -0,0 +1,66 @@
+import type { GNSMultiCollatDiamond } from "../../../contracts/types/generated";
+import type { TradeInitialAccFees } from ".";
+/**
+ * @dev Fetches pending accumulated funding fees for a specific pair
+ * @param contract GNSMultiCollatDiamond contract instance
+ * @param collateralIndex Collateral index
+ * @param pairIndex Pair index
+ * @param currentPairPrice Current pair price (1e10)
+ * @returns Promise resolving to accumulated funding fees and current rate
+ */
+export declare const fetchPairPendingAccFundingFees: (contract: GNSMultiCollatDiamond, collateralIndex: number, pairIndex: number, currentPairPrice: bigint) => Promise<{
+    accFundingFeeLongP: number;
+    accFundingFeeShortP: number;
+    currentFundingRatePerSecondP: number;
+}>;
+/**
+ * @dev Fetches funding fees for a specific trade in collateral tokens
+ * @param contract GNSMultiCollatDiamond contract instance
+ * @param trader Trader address
+ * @param index Trade index
+ * @param currentPairPrice Current pair price (1e10)
+ * @returns Promise resolving to funding fee in collateral tokens
+ */
+export declare const fetchTradeFundingFeesCollateral: (contract: GNSMultiCollatDiamond, trader: string, index: number, currentPairPrice: bigint) => Promise<number>;
+/**
+ * @dev Fetches trade fees data for a specific trade
+ * @param contract GNSMultiCollatDiamond contract instance
+ * @param trader Trader address
+ * @param index Trade index
+ * @returns Promise resolving to trade fees data
+ */
+export declare const fetchTradeFeesData: (contract: GNSMultiCollatDiamond, trader: string, index: number) => Promise<TradeInitialAccFees>;
+/**
+ * @dev Fetches trade fees data for multiple trades
+ * @param contract GNSMultiCollatDiamond contract instance
+ * @param traders Array of trader addresses
+ * @param indices Array of trade indices
+ * @returns Promise resolving to array of trade fees data
+ */
+export declare const fetchTradeFeesDataBatch: (contract: GNSMultiCollatDiamond, traders: string[], indices: number[]) => Promise<TradeInitialAccFees[]>;
+/**
+ * @dev Fetches pending accumulated funding fees for multiple pairs
+ * @param contract GNSMultiCollatDiamond contract instance
+ * @param collateralIndices Array of collateral indices
+ * @param pairIndices Array of pair indices
+ * @param currentPairPrices Array of current pair prices (1e10)
+ * @returns Promise resolving to array of accumulated funding fees
+ */
+export declare const fetchPairPendingAccFundingFeesBatch: (contract: GNSMultiCollatDiamond, collateralIndices: number[], pairIndices: number[], currentPairPrices: bigint[]) => Promise<Array<{
+    accFundingFeeLongP: number;
+    accFundingFeeShortP: number;
+    currentFundingRatePerSecondP: number;
+}>>;
+/**
+ * @dev Helper to convert price from number to contract format
+ * @param price Price as number
+ * @returns Price in contract format (1e10)
+ */
+export declare const priceToContractFormat: (price: number) => bigint;
+/**
+ * @dev Helper to convert collateral amount to contract format
+ * @param amount Amount as number
+ * @param decimals Collateral decimals (6 for USDC, 18 for others)
+ * @returns Amount in contract format
+ */
+export declare const collateralToContractFormat: (amount: number, decimals: number) => bigint;