@gainsnetwork/sdk 0.2.71-rc4 → 1.0.0-rc2

package/lib/markets/collateral/converter.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertCollateralConfig = void 0;
+const convertCollateralConfig = (collateral) => ({
+    collateral: collateral.collateral,
+    isActive: collateral.isActive,
+    precision: Number(collateral.precision),
+    precisionDelta: Number(collateral.precisionDelta),
+    decimals: collateral.decimals,
+});
+exports.convertCollateralConfig = convertCollateralConfig;

package/lib/markets/collateral/index.d.ts

@@ -0,0 +1 @@
+export * from "./types";

package/lib/markets/collateral/index.js

@@ -0,0 +1,17 @@
+"use strict";
+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("./types"), exports);

package/lib/markets/collateral/types.d.ts

@@ -0,0 +1,7 @@
+export type CollateralConfig = {
+    collateral: string;
+    isActive: boolean;
+    precision: number;
+    precisionDelta: number;
+    decimals?: number;
+};

package/lib/markets/collateral/types.js

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

package/lib/markets/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 "../../trade/fees/fundingFees/types";
+import { BorrowingFeeParams, PairBorrowingFeeData } from "../../trade/fees/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/markets/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("../../trade/fees/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 / 100
+        borrowingFeeHourlyRate =
+            (currentBorrowingRatePerSecondP * SECONDS_PER_HOUR) /
+                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/markets/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("../../trade/fees/fundingFees/types").FundingFeeParams;
+    fundingData: import("../../trade/fees/fundingFees/types").PairFundingFeeData;
+    pairOiToken: import("../../trade/fees/fundingFees/types").PairOiAfterV10;
+    netExposureToken: number;
+    netExposureUsd: number;
+    borrowingParams: import("../../trade/fees/borrowingV2/types").BorrowingFeeParams | null;
+    borrowingData: import("../../trade/fees/borrowingV2/types").PairBorrowingFeeData | null;
+    currentPairPrice: number;
+    currentTimestamp: number;
+}

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

@@ -3,3 +3,8 @@ export * from "./forex";
 export * from "./stocks";
 export * from "./indices";
 export * from "./commodities";
+export * from "./oi";
+export * from "./collateral";
+export * from "./price";
+export * from "./holdingFees";
+export * from "./leverage";

package/lib/markets/index.js

@@ -19,3 +19,8 @@ __exportStar(require("./forex"), exports);
 __exportStar(require("./stocks"), exports);
 __exportStar(require("./indices"), exports);
 __exportStar(require("./commodities"), exports);
+__exportStar(require("./oi"), exports);
+__exportStar(require("./collateral"), exports);
+__exportStar(require("./price"), exports);
+__exportStar(require("./holdingFees"), exports);
+__exportStar(require("./leverage"), exports);

package/lib/markets/leverage/builder.d.ts

@@ -0,0 +1,12 @@
+import { GlobalTradingVariablesType } from "../../backend/tradingVariables/types";
+import { GetMarketLeverageRestrictionsContext } from "./types";
+/**
+ * Builds the context needed for getMarketLeverageRestrictions from global trading variables
+ * @param globalTradingVariables Global trading variables containing pairs, groups, etc.
+ * @param pairIndex The index of the trading pair
+ * @param pairMaxLeverages Map of pair-specific max leverage overrides
+ * @returns Context for leverage restrictions calculation
+ */
+export declare const buildMarketLeverageRestrictionsContext: (globalTradingVariables: GlobalTradingVariablesType, pairIndex: number, pairMaxLeverages?: {
+    [key: number]: number;
+} | undefined) => GetMarketLeverageRestrictionsContext;

package/lib/markets/leverage/builder.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMarketLeverageRestrictionsContext = void 0;
+/**
+ * Builds the context needed for getMarketLeverageRestrictions from global trading variables
+ * @param globalTradingVariables Global trading variables containing pairs, groups, etc.
+ * @param pairIndex The index of the trading pair
+ * @param pairMaxLeverages Map of pair-specific max leverage overrides
+ * @returns Context for leverage restrictions calculation
+ */
+const buildMarketLeverageRestrictionsContext = (globalTradingVariables, pairIndex, pairMaxLeverages) => {
+    const { pairs, groups, counterTradeSettings } = globalTradingVariables;
+    if (!pairs || !groups || !pairs[pairIndex]) {
+        throw new Error("Invalid global trading variables or pair index");
+    }
+    const pair = pairs[pairIndex];
+    const group = groups[pair.groupIndex];
+    return {
+        groupMinLeverage: group.minLeverage,
+        groupMaxLeverage: group.maxLeverage,
+        pairMaxLeverage: pairMaxLeverages === null || pairMaxLeverages === void 0 ? void 0 : pairMaxLeverages[pairIndex],
+        counterTradeSettings: counterTradeSettings === null || counterTradeSettings === void 0 ? void 0 : counterTradeSettings[pairIndex],
+    };
+};
+exports.buildMarketLeverageRestrictionsContext = buildMarketLeverageRestrictionsContext;

package/lib/markets/leverage/getMarketLeverageRestrictions.d.ts

@@ -0,0 +1,7 @@
+import { GetMarketLeverageRestrictionsContext, MarketLeverageRestrictions } from "./types";
+/**
+ * Gets the leverage restrictions for a trading pair, including both regular and counter trade limits
+ * @param context Context containing group limits, pair overrides, and counter trade settings
+ * @returns Object with regular and counter trade leverage restrictions
+ */
+export declare const getMarketLeverageRestrictions: (context: GetMarketLeverageRestrictionsContext) => MarketLeverageRestrictions;

package/lib/markets/leverage/getMarketLeverageRestrictions.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMarketLeverageRestrictions = void 0;
+/**
+ * Gets the leverage restrictions for a trading pair, including both regular and counter trade limits
+ * @param context Context containing group limits, pair overrides, and counter trade settings
+ * @returns Object with regular and counter trade leverage restrictions
+ */
+const getMarketLeverageRestrictions = (context) => {
+    const { groupMinLeverage, groupMaxLeverage, pairMaxLeverage, counterTradeSettings, } = context;
+    // Calculate regular trade leverage limits
+    let regularMin = groupMinLeverage;
+    let regularMax = pairMaxLeverage === undefined || pairMaxLeverage === 0
+        ? groupMaxLeverage
+        : pairMaxLeverage;
+    // If max is less than min, set both to 0 (pair is effectively disabled)
+    if (regularMax < regularMin) {
+        regularMin = 0;
+        regularMax = 0;
+    }
+    // Calculate counter trade leverage limits if settings exist
+    let counterTradeLimits = null;
+    if (counterTradeSettings) {
+        // Counter trades use the group's min leverage but have their own max leverage
+        counterTradeLimits = {
+            min: groupMinLeverage,
+            max: counterTradeSettings.maxLeverage,
+        };
+    }
+    return {
+        regular: {
+            min: regularMin,
+            max: regularMax,
+        },
+        counterTrade: counterTradeLimits,
+    };
+};
+exports.getMarketLeverageRestrictions = getMarketLeverageRestrictions;

package/lib/markets/leverage/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./getMarketLeverageRestrictions";
+export * from "./builder";

package/lib/markets/leverage/index.js

@@ -0,0 +1,19 @@
+"use strict";
+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("./types"), exports);
+__exportStar(require("./getMarketLeverageRestrictions"), exports);
+__exportStar(require("./builder"), exports);

package/lib/markets/leverage/types.d.ts

@@ -0,0 +1,15 @@
+import { CounterTradeSettings } from "../../trade/types";
+export type LeverageRestrictions = {
+    min: number;
+    max: number;
+};
+export type MarketLeverageRestrictions = {
+    regular: LeverageRestrictions;
+    counterTrade: LeverageRestrictions | null;
+};
+export type GetMarketLeverageRestrictionsContext = {
+    groupMinLeverage: number;
+    groupMaxLeverage: number;
+    pairMaxLeverage?: number;
+    counterTradeSettings?: CounterTradeSettings;
+};

package/lib/markets/leverage/types.js

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

package/lib/markets/oi/converter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @dev Converters for OI data between contract and SDK formats
+ * @dev Handles the three OI storage systems and precision conversions
+ */
+import { IBorrowingFees, IPriceImpact } from "../../contracts/types/generated/GNSMultiCollatDiamond";
+import { UnifiedPairOi, ComputedOi } from "./types";
+/**
+ * @dev Converts pre-v10 OI from contract format
+ * @param contractOi Contract OpenInterest struct from BorrowingFeesStorage
+ * @returns Normalized OI with long/short values
+ */
+export declare const convertBeforeV10Collateral: (contractOi: IBorrowingFees.OpenInterestStructOutput) => {
+    long: number;
+    short: number;
+};
+/**
+ * @dev Converts post-v10 collateral OI from contract format
+ * @param contractOi Contract PairOiCollateral struct
+ * @param precision Collateral precision for conversion
+ * @returns Normalized OI with long/short values
+ */
+export declare const convertCollateralOi: (contractOi: IPriceImpact.PairOiCollateralStructOutput, precision: number) => {
+    long: number;
+    short: number;
+};
+/**
+ * @dev Converts post-v10 token OI from contract format
+ * @param contractOi Contract PairOiToken struct
+ * @returns Normalized OI with long/short values (1e18 precision)
+ */
+export declare const convertTokenOi: (contractOi: IPriceImpact.PairOiTokenStructOutput) => {
+    long: number;
+    short: number;
+};
+/**
+ * @dev Converts all OI data for a pair into unified structure
+ * @param beforeV10 Pre-v10 OI from BorrowingFeesStorage
+ * @param afterV10Collateral Post-v10 collateral OI from PriceImpactStorage
+ * @param afterV10Token Post-v10 token OI from PriceImpactStorage
+ * @param maxOi Maximum OI allowed (from BorrowingFeesStorage)
+ * @param collateralPrecision Precision for collateral conversions
+ * @returns Unified PairOi structure
+ */
+export declare const convertPairOi: (beforeV10: IBorrowingFees.OpenInterestStructOutput, afterV10Collateral: IPriceImpact.PairOiCollateralStructOutput, afterV10Token: IPriceImpact.PairOiTokenStructOutput, collateralPrecision: number) => UnifiedPairOi;
+/**
+ * @dev Batch converter for multiple pairs
+ * @param pairs Array of OI data for multiple pairs
+ * @param collateralPrecision Precision for collateral conversions
+ * @returns Array of unified PairOi structures
+ */
+export declare const convertPairOiArray: (pairs: Array<{
+    beforeV10: IBorrowingFees.OpenInterestStructOutput;
+    collateral: IPriceImpact.PairOiCollateralStructOutput;
+    token: IPriceImpact.PairOiTokenStructOutput;
+}>, collateralPrecision: number) => UnifiedPairOi[];
+/**
+ * @dev Computes derived OI values from unified structure
+ * @param pairOi Unified pair OI data
+ * @param tokenPriceCollateral Current token price in collateral units
+ * @returns Computed values including total OI and skew
+ */
+export declare const computeOiValues: (pairOi: UnifiedPairOi, tokenPriceCollateral: number) => ComputedOi;

package/lib/markets/oi/converter.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * @dev Converters for OI data between contract and SDK formats
+ * @dev Handles the three OI storage systems and precision conversions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeOiValues = exports.convertPairOiArray = exports.convertPairOi = exports.convertTokenOi = exports.convertCollateralOi = exports.convertBeforeV10Collateral = void 0;
+/**
+ * @dev Converts pre-v10 OI from contract format
+ * @param contractOi Contract OpenInterest struct from BorrowingFeesStorage
+ * @returns Normalized OI with long/short values
+ */
+const convertBeforeV10Collateral = (contractOi) => {
+    return {
+        long: Number(contractOi.long) / 1e10,
+        short: Number(contractOi.short) / 1e10,
+    };
+};
+exports.convertBeforeV10Collateral = convertBeforeV10Collateral;
+/**
+ * @dev Converts post-v10 collateral OI from contract format
+ * @param contractOi Contract PairOiCollateral struct
+ * @param precision Collateral precision for conversion
+ * @returns Normalized OI with long/short values
+ */
+const convertCollateralOi = (contractOi, precision) => {
+    return {
+        long: Number(contractOi.oiLongCollateral) / precision,
+        short: Number(contractOi.oiShortCollateral) / precision,
+    };
+};
+exports.convertCollateralOi = convertCollateralOi;
+/**
+ * @dev Converts post-v10 token OI from contract format
+ * @param contractOi Contract PairOiToken struct
+ * @returns Normalized OI with long/short values (1e18 precision)
+ */
+const convertTokenOi = (contractOi) => {
+    return {
+        long: Number(contractOi.oiLongToken) / 1e18,
+        short: Number(contractOi.oiShortToken) / 1e18,
+    };
+};
+exports.convertTokenOi = convertTokenOi;
+/**
+ * @dev Converts all OI data for a pair into unified structure
+ * @param beforeV10 Pre-v10 OI from BorrowingFeesStorage
+ * @param afterV10Collateral Post-v10 collateral OI from PriceImpactStorage
+ * @param afterV10Token Post-v10 token OI from PriceImpactStorage
+ * @param maxOi Maximum OI allowed (from BorrowingFeesStorage)
+ * @param collateralPrecision Precision for collateral conversions
+ * @returns Unified PairOi structure
+ */
+const convertPairOi = (beforeV10, afterV10Collateral, afterV10Token, collateralPrecision) => {
+    return {
+        maxCollateral: Number(beforeV10.max) / 1e10,
+        beforeV10Collateral: (0, exports.convertBeforeV10Collateral)(beforeV10),
+        collateral: (0, exports.convertCollateralOi)(afterV10Collateral, collateralPrecision),
+        token: (0, exports.convertTokenOi)(afterV10Token),
+    };
+};
+exports.convertPairOi = convertPairOi;
+/**
+ * @dev Batch converter for multiple pairs
+ * @param pairs Array of OI data for multiple pairs
+ * @param collateralPrecision Precision for collateral conversions
+ * @returns Array of unified PairOi structures
+ */
+const convertPairOiArray = (pairs, collateralPrecision) => {
+    return pairs.map(p => (0, exports.convertPairOi)(p.beforeV10, p.collateral, p.token, collateralPrecision));
+};
+exports.convertPairOiArray = convertPairOiArray;
+/**
+ * @dev Computes derived OI values from unified structure
+ * @param pairOi Unified pair OI data
+ * @param tokenPriceCollateral Current token price in collateral units
+ * @returns Computed values including total OI and skew
+ */
+const computeOiValues = (pairOi, tokenPriceCollateral) => {
+    // Static total (used for admin operations)
+    const totalStaticLong = pairOi.beforeV10Collateral.long + pairOi.collateral.long;
+    const totalStaticShort = pairOi.beforeV10Collateral.short + pairOi.collateral.short;
+    // Dynamic total (used for real-time calculations)
+    const tokenLongCollateral = pairOi.token.long * tokenPriceCollateral;
+    const tokenShortCollateral = pairOi.token.short * tokenPriceCollateral;
+    const totalDynamicLong = pairOi.beforeV10Collateral.long + tokenLongCollateral;
+    const totalDynamicShort = pairOi.beforeV10Collateral.short + tokenShortCollateral;
+    // Skew (v10+ only, in tokens)
+    const skewToken = pairOi.token.long - pairOi.token.short;
+    return {
+        totalStaticCollateral: {
+            long: totalStaticLong,
+            short: totalStaticShort,
+        },
+        totalDynamicCollateral: {
+            long: totalDynamicLong,
+            short: totalDynamicShort,
+        },
+        skewToken,
+    };
+};
+exports.computeOiValues = computeOiValues;

package/lib/markets/oi/fetcher.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @dev Fetchers for retrieving OI data from contracts
+ * @dev Consolidates the three OI storage systems into unified format
+ */
+import { ethers } from "ethers";
+import { ChainId } from "../../contracts/types";
+import { UnifiedPairOi } from "./types";
+/**
+ * @dev Fetches all OI data for a single pair
+ * @param chainId Target chain
+ * @param collateralIndex Collateral type
+ * @param pairIndex Trading pair
+ * @param signer Ethers signer
+ * @returns Unified PairOi structure with all OI data
+ */
+export declare function fetchPairOi(chainId: ChainId, collateralIndex: number, pairIndex: number, signer: ethers.Signer): Promise<UnifiedPairOi>;
+/**
+ * @dev Fetches OI data for multiple pairs efficiently
+ * @param chainId Target chain
+ * @param collateralIndex Collateral type
+ * @param pairIndices Array of trading pairs
+ * @param signer Ethers signer
+ * @returns Array of unified PairOi structures
+ */
+export declare function fetchMultiplePairOi(chainId: ChainId, collateralIndex: number, pairIndices: number[], signer: ethers.Signer): Promise<UnifiedPairOi[]>;
+/**
+ * @dev Creates OI context for fee calculations
+ * @param chainId Target chain
+ * @param collateralIndex Collateral type
+ * @param pairIndex Trading pair
+ * @param signer Ethers signer
+ * @returns OI data formatted for SDK calculations
+ */
+export declare function createOiContext(chainId: ChainId, collateralIndex: number, pairIndex: number, signer: ethers.Signer): Promise<{
+    pairOi: UnifiedPairOi;
+    currentPrice: number;
+    computed: {
+        totalDynamicOi: {
+            long: number;
+            short: number;
+        };
+        totalStaticOi: {
+            long: number;
+            short: number;
+        };
+        skew: number;
+    };
+}>;
+/**
+ * @dev Fetches only the OI data needed for specific use cases
+ * @param chainId Target chain
+ * @param collateralIndex Collateral type
+ * @param pairIndex Trading pair
+ * @param useCase Which OI systems to fetch
+ * @param signer Ethers signer
+ * @returns Partial OI data based on use case
+ */
+export declare function fetchOiForUseCase(chainId: ChainId, collateralIndex: number, pairIndex: number, useCase: "skew" | "funding" | "borrowingV1" | "limits", signer: ethers.Signer): Promise<Partial<UnifiedPairOi>>;