@gainsnetwork/sdk 1.0.6-rc3 → 1.1.0-rc1

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

@@ -0,0 +1,80 @@
+/**
+ * @dev OI Validation module
+ * @dev Provides validation functions for Open Interest limits
+ */
+import { UnifiedPairOi } from "./types";
+import * as BorrowingFee from "../../trade/fees/borrowing/types";
+import { PairIndex } from "../../trade/types";
+/**
+ * @dev Check if a position would exceed per-pair OI limits
+ * @param pairOi Current OI data for the pair
+ * @param long Whether the position is long
+ * @param positionSizeCollateral Position size in collateral
+ * @param currentPrice Current collateral price in USD (required for dynamic OI)
+ * @returns true if within limits, false if would exceed
+ */
+export declare const withinMaxPairOi: (pairOi: UnifiedPairOi, long: boolean, positionSizeCollateral: number, currentPrice: number) => boolean;
+/**
+ * @dev Calculate dynamic OI for a specific side
+ * @param pairOi OI data for the pair
+ * @param currentPrice Current collateral price in USD
+ * @param long Whether to calculate for long side
+ * @returns Dynamic OI in collateral value
+ */
+export declare const calculateDynamicOi: (pairOi: UnifiedPairOi, currentPrice: number, long: boolean) => number;
+/**
+ * @dev Calculate remaining OI capacity for a side
+ * @param pairOi OI data for the pair
+ * @param currentPrice Current collateral price in USD
+ * @param long Whether to calculate for long side
+ * @returns Remaining capacity in collateral (0 if unlimited)
+ */
+export declare const getRemainingOiCapacity: (pairOi: UnifiedPairOi, currentPrice: number, long: boolean) => number;
+/**
+ * @dev Updated group OI validation using dynamic OI
+ * @param pairIndex Index of the trading pair
+ * @param long Whether the position is long
+ * @param positionSizeCollateral Position size in collateral
+ * @param currentPrice Current collateral price in USD
+ * @param context Context with groups, pairs, and OI data
+ * @returns true if within group limits, false if would exceed
+ */
+export declare const withinMaxGroupOiDynamic: (pairIndex: PairIndex, long: boolean, positionSizeCollateral: number, currentPrice: number, context: {
+    groups: BorrowingFee.Group[];
+    pairs: BorrowingFee.Pair[];
+    pairOis: UnifiedPairOi[];
+}) => boolean;
+/**
+ * @dev Calculate total dynamic OI for a group
+ * @param groupIndex Index of the group
+ * @param currentPrice Current collateral price in USD
+ * @param context Context with pairs and OI data
+ * @returns Total dynamic OI for the group
+ */
+export declare const getGroupDynamicOi: (groupIndex: number, currentPrice: number, context: {
+    pairs: BorrowingFee.Pair[];
+    pairOis: UnifiedPairOi[];
+}) => {
+    long: number;
+    short: number;
+    total: number;
+};
+/**
+ * @dev Check both pair and group OI limits
+ * @param pairIndex Index of the trading pair
+ * @param long Whether the position is long
+ * @param positionSizeCollateral Position size in collateral
+ * @param currentPrice Current collateral price in USD
+ * @param context Full context with all required data
+ * @returns Object with validation results
+ */
+export declare const validateOiLimits: (pairIndex: PairIndex, long: boolean, positionSizeCollateral: number, currentPrice: number, context: {
+    groups: BorrowingFee.Group[];
+    pairs: BorrowingFee.Pair[];
+    pairOis: UnifiedPairOi[];
+}) => {
+    withinPairLimit: boolean;
+    withinGroupLimit: boolean;
+    pairRemainingCapacity: number;
+    groupRemainingCapacity: number;
+};

package/lib/markets/oi/validation.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * @dev OI Validation module
+ * @dev Provides validation functions for Open Interest limits
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOiLimits = exports.getGroupDynamicOi = exports.withinMaxGroupOiDynamic = exports.getRemainingOiCapacity = exports.calculateDynamicOi = exports.withinMaxPairOi = void 0;
+const converter_1 = require("./converter");
+/**
+ * @dev Check if a position would exceed per-pair OI limits
+ * @param pairOi Current OI data for the pair
+ * @param long Whether the position is long
+ * @param positionSizeCollateral Position size in collateral
+ * @param currentPrice Current collateral price in USD (required for dynamic OI)
+ * @returns true if within limits, false if would exceed
+ */
+const withinMaxPairOi = (pairOi, long, positionSizeCollateral, currentPrice) => {
+    // If maxCollateral is 0, unlimited OI allowed
+    if (pairOi.maxCollateral === 0) {
+        return true;
+    }
+    // Calculate current dynamic OI
+    const computed = (0, converter_1.computeOiValues)(pairOi, currentPrice);
+    const currentOi = long
+        ? computed.totalDynamicCollateral.long
+        : computed.totalDynamicCollateral.short;
+    // Check if adding position would exceed max
+    const newOi = currentOi + positionSizeCollateral;
+    return newOi <= pairOi.maxCollateral;
+};
+exports.withinMaxPairOi = withinMaxPairOi;
+/**
+ * @dev Calculate dynamic OI for a specific side
+ * @param pairOi OI data for the pair
+ * @param currentPrice Current collateral price in USD
+ * @param long Whether to calculate for long side
+ * @returns Dynamic OI in collateral value
+ */
+const calculateDynamicOi = (pairOi, currentPrice, long) => {
+    const computed = (0, converter_1.computeOiValues)(pairOi, currentPrice);
+    return long
+        ? computed.totalDynamicCollateral.long
+        : computed.totalDynamicCollateral.short;
+};
+exports.calculateDynamicOi = calculateDynamicOi;
+/**
+ * @dev Calculate remaining OI capacity for a side
+ * @param pairOi OI data for the pair
+ * @param currentPrice Current collateral price in USD
+ * @param long Whether to calculate for long side
+ * @returns Remaining capacity in collateral (0 if unlimited)
+ */
+const getRemainingOiCapacity = (pairOi, currentPrice, long) => {
+    // If maxCollateral is 0, unlimited capacity
+    if (pairOi.maxCollateral === 0) {
+        return 0; // Indicates unlimited
+    }
+    const dynamicOi = (0, exports.calculateDynamicOi)(pairOi, currentPrice, long);
+    const remaining = pairOi.maxCollateral - dynamicOi;
+    // Return 0 if already at or over capacity
+    return Math.max(0, remaining);
+};
+exports.getRemainingOiCapacity = getRemainingOiCapacity;
+/**
+ * @dev Updated group OI validation using dynamic OI
+ * @param pairIndex Index of the trading pair
+ * @param long Whether the position is long
+ * @param positionSizeCollateral Position size in collateral
+ * @param currentPrice Current collateral price in USD
+ * @param context Context with groups, pairs, and OI data
+ * @returns true if within group limits, false if would exceed
+ */
+const withinMaxGroupOiDynamic = (pairIndex, long, positionSizeCollateral, currentPrice, context) => {
+    const pair = context.pairs[pairIndex];
+    if (!pair)
+        return false;
+    // Get group index from first group in pair's groups array
+    const groupIndex = pair.groups.length > 0 ? pair.groups[0].groupIndex : 0;
+    const group = context.groups[groupIndex];
+    if (!group)
+        return false;
+    // If maxOi is 0, unlimited OI allowed
+    if (group.oi.max === 0) {
+        return true;
+    }
+    // Calculate total dynamic OI for all pairs in group
+    let totalGroupOi = 0;
+    context.pairs.forEach((p, idx) => {
+        const pGroupIndex = p.groups.length > 0 ? p.groups[0].groupIndex : 0;
+        if (pGroupIndex === groupIndex && context.pairOis[idx]) {
+            const pairOi = context.pairOis[idx];
+            const computed = (0, converter_1.computeOiValues)(pairOi, currentPrice);
+            // Add both long and short OI for the pair
+            totalGroupOi +=
+                computed.totalDynamicCollateral.long +
+                    computed.totalDynamicCollateral.short;
+        }
+    });
+    // Check if adding position would exceed group max
+    const newTotalOi = totalGroupOi + positionSizeCollateral;
+    return newTotalOi <= group.oi.max;
+};
+exports.withinMaxGroupOiDynamic = withinMaxGroupOiDynamic;
+/**
+ * @dev Calculate total dynamic OI for a group
+ * @param groupIndex Index of the group
+ * @param currentPrice Current collateral price in USD
+ * @param context Context with pairs and OI data
+ * @returns Total dynamic OI for the group
+ */
+const getGroupDynamicOi = (groupIndex, currentPrice, context) => {
+    let longOi = 0;
+    let shortOi = 0;
+    context.pairs.forEach((p, idx) => {
+        const pGroupIndex = p.groups.length > 0 ? p.groups[0].groupIndex : 0;
+        if (pGroupIndex === groupIndex && context.pairOis[idx]) {
+            const pairOi = context.pairOis[idx];
+            const computed = (0, converter_1.computeOiValues)(pairOi, currentPrice);
+            longOi += computed.totalDynamicCollateral.long;
+            shortOi += computed.totalDynamicCollateral.short;
+        }
+    });
+    return {
+        long: longOi,
+        short: shortOi,
+        total: longOi + shortOi,
+    };
+};
+exports.getGroupDynamicOi = getGroupDynamicOi;
+/**
+ * @dev Check both pair and group OI limits
+ * @param pairIndex Index of the trading pair
+ * @param long Whether the position is long
+ * @param positionSizeCollateral Position size in collateral
+ * @param currentPrice Current collateral price in USD
+ * @param context Full context with all required data
+ * @returns Object with validation results
+ */
+const validateOiLimits = (pairIndex, long, positionSizeCollateral, currentPrice, context) => {
+    const pairOi = context.pairOis[pairIndex];
+    if (!pairOi) {
+        return {
+            withinPairLimit: false,
+            withinGroupLimit: false,
+            pairRemainingCapacity: 0,
+            groupRemainingCapacity: 0,
+        };
+    }
+    // Check pair limits
+    const withinPairLimit = (0, exports.withinMaxPairOi)(pairOi, long, positionSizeCollateral, currentPrice);
+    const pairRemainingCapacity = (0, exports.getRemainingOiCapacity)(pairOi, currentPrice, long);
+    // Check group limits
+    const withinGroupLimit = (0, exports.withinMaxGroupOiDynamic)(pairIndex, long, positionSizeCollateral, currentPrice, context);
+    // Calculate group remaining capacity
+    const pair = context.pairs[pairIndex];
+    let groupRemainingCapacity = 0;
+    if (pair) {
+        const groupIndex = pair.groups.length > 0 ? pair.groups[0].groupIndex : 0;
+        const group = context.groups[groupIndex];
+        if (group && group.oi.max > 0) {
+            const groupOi = (0, exports.getGroupDynamicOi)(groupIndex, currentPrice, context);
+            groupRemainingCapacity = Math.max(0, group.oi.max - groupOi.total);
+        }
+    }
+    return {
+        withinPairLimit,
+        withinGroupLimit,
+        pairRemainingCapacity,
+        groupRemainingCapacity,
+    };
+};
+exports.validateOiLimits = validateOiLimits;

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

@@ -4,4 +4,3 @@
 export * from "./types";
 export * from "./marketPrice";
 export * from "./builder";
-export * from "./signedPrices";

package/lib/markets/price/index.js

@@ -20,4 +20,3 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./marketPrice"), exports);
 __exportStar(require("./builder"), exports);
-__exportStar(require("./signedPrices"), exports);

package/lib/markets/price/signedPrices.d.ts

@@ -21,6 +21,13 @@ export interface FetchSignedLookbackPricesInput {
     timeoutMs?: number;
 }
 export declare const fetchSignedLookbackPrices: (input: FetchSignedLookbackPricesInput) => Promise<SignedPricesResponse[] | null>;
+export interface RetryOptions {
+    maxRetries?: number;
+    retryDelayMs?: number;
+    backoffMultiplier?: number;
+}
+export declare const fetchSignedPricesWithRetry: (input: FetchSignedPricesInput, retryOptions?: RetryOptions) => Promise<SignedPricesResponse[] | null>;
+export declare const fetchSignedLookbackPricesWithRetry: (input: FetchSignedLookbackPricesInput, retryOptions?: RetryOptions) => Promise<SignedPricesResponse[] | null>;
 export declare const validateSignedPricesPairs: (pairs: number[]) => {
     valid: boolean;
     pairs: number[];

package/lib/markets/price/signedPrices.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidSignedPricesOrderType = exports.isValidSignedPricesChain = exports.validateSignedPricesPairs = exports.fetchSignedLookbackPrices = exports.fetchSignedPrices = void 0;
+exports.isValidSignedPricesOrderType = exports.isValidSignedPricesChain = exports.validateSignedPricesPairs = exports.fetchSignedLookbackPricesWithRetry = exports.fetchSignedPricesWithRetry = exports.fetchSignedLookbackPrices = exports.fetchSignedPrices = void 0;
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 const types_1 = require("../../contracts/types");
 const trade_1 = require("../../trade");
@@ -34,7 +34,6 @@ const fetchSignedLookbackPrices = async (input) => {
         throw new Error(`Invalid tradeIndex ${tradeIndex}`);
     if (!currentBlock || !fromBlock)
         throw new Error(`Invalid block numbers`);
-    // @todo handle filtering to minAnswers
     return await initiateSignedPricesRequest(oracles, "signLookbackPrices", JSON.stringify({
         trader,
         tradeIndex,
@@ -46,6 +45,60 @@ const fetchSignedLookbackPrices = async (input) => {
     }), minAnswers, timeoutMs);
 };
 exports.fetchSignedLookbackPrices = fetchSignedLookbackPrices;
+// Helper to determine if an error is likely transient
+const isTransientError = (error) => {
+    const message = (error instanceof Error ? error.message : String(error))?.toLowerCase() ||
+        "";
+    return (message.includes("timeout") ||
+        message.includes("aborted") ||
+        message.includes("not enough valid signed prices") ||
+        message.includes("network") ||
+        message.includes("fetch failed"));
+};
+// Fetch signed prices with retry logic for transient failures
+const fetchSignedPricesWithRetry = async (input, retryOptions) => {
+    const { maxRetries = 2, retryDelayMs = 500, backoffMultiplier = 1.5, } = retryOptions || {};
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await (0, exports.fetchSignedPrices)(input);
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry non-transient errors or if we're out of retries
+            if (attempt === maxRetries || !isTransientError(error)) {
+                throw error;
+            }
+            // Wait with exponential backoff before retry
+            const delay = Math.floor(retryDelayMs * Math.pow(backoffMultiplier, attempt));
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+};
+exports.fetchSignedPricesWithRetry = fetchSignedPricesWithRetry;
+// Fetch lookback prices with retry logic
+const fetchSignedLookbackPricesWithRetry = async (input, retryOptions) => {
+    const { maxRetries = 2, retryDelayMs = 1000, backoffMultiplier = 2, } = retryOptions || {};
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await (0, exports.fetchSignedLookbackPrices)(input);
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry non-transient errors or if we're out of retries
+            if (attempt === maxRetries || !isTransientError(error)) {
+                throw error;
+            }
+            // Wait with exponential backoff before retry
+            const delay = Math.floor(retryDelayMs * Math.pow(backoffMultiplier, attempt));
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+};
+exports.fetchSignedLookbackPricesWithRetry = fetchSignedLookbackPricesWithRetry;
 // @todo optional filtering to minAnswers best responses
 const initiateSignedPricesRequest = async (oracles, request, requestBody, minAnswers, timeoutMs) => {
     try {

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

@@ -21,30 +21,3 @@ export type MarketPriceContext = {
         oiShortToken: number;
     };
 };
-/**
- * @dev Types for signed prices data structure
- */
-export type SignedPricesResponse = {
-    signedData: SignedPrices;
-    missingPrices: number[];
-};
-export type SignedPrices = {
-    signerId: number;
-    expiryTs: number;
-    fromBlock: number;
-    isLookback: boolean;
-    pairIndices: number[];
-    prices: Price[];
-    signature: string;
-};
-export type Price = {
-    open: string;
-    high: string;
-    low: string;
-    current: string;
-    ts: number;
-};
-export type Oracle = {
-    url: string;
-    key?: string;
-};

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

@@ -0,0 +1,65 @@
+/**
+ * @dev Depth bands conversion utilities
+ */
+import { type DepthBandsInput } from "./types";
+/**
+ * Convert raw depth data from exchanges to depth bands input format
+ * @param totalDepthUsd Total depth in USD (already in 6 decimal precision)
+ * @param depthLevels Array of depth levels with cumulative USD amounts
+ * @returns Formatted depth bands input
+ */
+export declare function formatDepthBandsInput(totalDepthUsd: number, depthLevels: Array<{
+    cumulativeUsd: number;
+}>): DepthBandsInput;
+/**
+ * Convert percentage-based depth configuration to cumulative USD values
+ * @param totalDepthUsd Total depth in USD
+ * @param percentages Array of 30 cumulative percentages (0-100)
+ * @returns Depth bands input with cumulative USD values
+ */
+export declare function percentagesToDepthBands(totalDepthUsd: number, percentages: number[]): DepthBandsInput;
+/**
+ * Convert basis points array to percentage array
+ * @param bps Array of values in basis points
+ * @returns Array of percentages (0-100)
+ */
+export declare function bpsToPercentages(bps: number[]): number[];
+/**
+ * Convert percentage array to basis points array
+ * @param percentages Array of percentages (0-100)
+ * @returns Array of values in basis points
+ */
+export declare function percentagesToBps(percentages: number[]): number[];
+/**
+ * Convert parts per million (ppm) to percentage
+ * @param ppm Value in parts per million
+ * @returns Percentage value
+ */
+export declare function ppmToPercentage(ppm: number): number;
+/**
+ * Convert percentage to parts per million (ppm)
+ * @param percentage Percentage value
+ * @returns Value in parts per million
+ */
+export declare function percentageToPpm(percentage: number): number;
+/**
+ * Create a linear depth bands configuration
+ * @param totalDepthUsd Total depth in USD
+ * @returns Linear depth bands from 0% to 100%
+ */
+export declare function createLinearDepthBands(totalDepthUsd: number): DepthBandsInput;
+/**
+ * Create an exponential depth bands configuration
+ * @param totalDepthUsd Total depth in USD
+ * @param factor Exponential factor (higher = more concentrated near 0)
+ * @returns Exponential depth bands configuration
+ */
+export declare function createExponentialDepthBands(totalDepthUsd: number, factor?: number): DepthBandsInput;
+/**
+ * Create a concentrated depth bands configuration
+ * @param totalDepthUsd Total depth in USD
+ * @param concentrationPoint Percentage (0-100) where to concentrate liquidity
+ * @param concentrationStrength How much to concentrate (0-1, higher = more concentrated)
+ * @returns Concentrated depth bands configuration
+ */
+export declare function createConcentratedDepthBands(totalDepthUsd: number, concentrationPoint?: number, concentrationStrength?: number): DepthBandsInput;

package/lib/pricing/depthBands/converter.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * @dev Depth bands conversion utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConcentratedDepthBands = exports.createExponentialDepthBands = exports.createLinearDepthBands = exports.percentageToPpm = exports.ppmToPercentage = exports.percentagesToBps = exports.bpsToPercentages = exports.percentagesToDepthBands = exports.formatDepthBandsInput = void 0;
+const types_1 = require("./types");
+/**
+ * Convert raw depth data from exchanges to depth bands input format
+ * @param totalDepthUsd Total depth in USD (already in 6 decimal precision)
+ * @param depthLevels Array of depth levels with cumulative USD amounts
+ * @returns Formatted depth bands input
+ */
+function formatDepthBandsInput(totalDepthUsd, depthLevels) {
+    // Ensure we have exactly 30 levels
+    if (depthLevels.length !== 30) {
+        throw new Error(`Expected 30 depth levels, got ${depthLevels.length}`);
+    }
+    const cumulativeDepthUsd = depthLevels.map((level) => level.cumulativeUsd);
+    return {
+        totalDepthUsd,
+        cumulativeDepthUsd,
+    };
+}
+exports.formatDepthBandsInput = formatDepthBandsInput;
+/**
+ * Convert percentage-based depth configuration to cumulative USD values
+ * @param totalDepthUsd Total depth in USD
+ * @param percentages Array of 30 cumulative percentages (0-100)
+ * @returns Depth bands input with cumulative USD values
+ */
+function percentagesToDepthBands(totalDepthUsd, percentages) {
+    if (percentages.length !== 30) {
+        throw new Error(`Expected 30 percentages, got ${percentages.length}`);
+    }
+    const cumulativeDepthUsd = percentages.map((percentage) => {
+        if (percentage < 0 || percentage > 100) {
+            throw new Error(`Invalid percentage: ${percentage}. Must be between 0 and 100`);
+        }
+        return (percentage * totalDepthUsd) / 100;
+    });
+    return {
+        totalDepthUsd,
+        cumulativeDepthUsd,
+    };
+}
+exports.percentagesToDepthBands = percentagesToDepthBands;
+/**
+ * Convert basis points array to percentage array
+ * @param bps Array of values in basis points
+ * @returns Array of percentages (0-100)
+ */
+function bpsToPercentages(bps) {
+    return bps.map((value) => (value * 100) / types_1.HUNDRED_P_BPS);
+}
+exports.bpsToPercentages = bpsToPercentages;
+/**
+ * Convert percentage array to basis points array
+ * @param percentages Array of percentages (0-100)
+ * @returns Array of values in basis points
+ */
+function percentagesToBps(percentages) {
+    return percentages.map((percentage) => {
+        const bps = Math.round((percentage * types_1.HUNDRED_P_BPS) / 100);
+        if (bps > types_1.HUNDRED_P_BPS) {
+            throw new Error(`Percentage ${percentage}% converts to ${bps} bps, which exceeds maximum ${types_1.HUNDRED_P_BPS} bps`);
+        }
+        return bps;
+    });
+}
+exports.percentagesToBps = percentagesToBps;
+/**
+ * Convert parts per million (ppm) to percentage
+ * @param ppm Value in parts per million
+ * @returns Percentage value
+ */
+function ppmToPercentage(ppm) {
+    return ppm / 10000;
+}
+exports.ppmToPercentage = ppmToPercentage;
+/**
+ * Convert percentage to parts per million (ppm)
+ * @param percentage Percentage value
+ * @returns Value in parts per million
+ */
+function percentageToPpm(percentage) {
+    return Math.round(percentage * 10000);
+}
+exports.percentageToPpm = percentageToPpm;
+/**
+ * Create a linear depth bands configuration
+ * @param totalDepthUsd Total depth in USD
+ * @returns Linear depth bands from 0% to 100%
+ */
+function createLinearDepthBands(totalDepthUsd) {
+    const cumulativeDepthUsd = [];
+    for (let i = 0; i < 30; i++) {
+        // Linear progression from 0 to 100%
+        const percentage = ((i + 1) / 30) * 100;
+        cumulativeDepthUsd.push((percentage * totalDepthUsd) / 100);
+    }
+    return {
+        totalDepthUsd,
+        cumulativeDepthUsd,
+    };
+}
+exports.createLinearDepthBands = createLinearDepthBands;
+/**
+ * Create an exponential depth bands configuration
+ * @param totalDepthUsd Total depth in USD
+ * @param factor Exponential factor (higher = more concentrated near 0)
+ * @returns Exponential depth bands configuration
+ */
+function createExponentialDepthBands(totalDepthUsd, factor = 2) {
+    const cumulativeDepthUsd = [];
+    for (let i = 0; i < 30; i++) {
+        // Exponential curve: y = (e^(factor * x) - 1) / (e^factor - 1)
+        const x = (i + 1) / 30;
+        const percentage = ((Math.exp(factor * x) - 1) / (Math.exp(factor) - 1)) * 100;
+        cumulativeDepthUsd.push((percentage * totalDepthUsd) / 100);
+    }
+    return {
+        totalDepthUsd,
+        cumulativeDepthUsd,
+    };
+}
+exports.createExponentialDepthBands = createExponentialDepthBands;
+/**
+ * Create a concentrated depth bands configuration
+ * @param totalDepthUsd Total depth in USD
+ * @param concentrationPoint Percentage (0-100) where to concentrate liquidity
+ * @param concentrationStrength How much to concentrate (0-1, higher = more concentrated)
+ * @returns Concentrated depth bands configuration
+ */
+function createConcentratedDepthBands(totalDepthUsd, concentrationPoint = 20, concentrationStrength = 0.7) {
+    const cumulativeDepthUsd = [];
+    for (let i = 0; i < 30; i++) {
+        const x = (i + 1) / 30;
+        const targetX = concentrationPoint / 100;
+        // Sigmoid-like concentration around the target point
+        const steepness = 10 * concentrationStrength;
+        const sigmoid = 1 / (1 + Math.exp(-steepness * (x - targetX)));
+        // Blend between linear and concentrated
+        const linear = x;
+        const percentage = (linear * (1 - concentrationStrength) + sigmoid * concentrationStrength) * 100;
+        cumulativeDepthUsd.push(Math.min((percentage * totalDepthUsd) / 100, totalDepthUsd));
+    }
+    // Ensure last value is exactly totalDepthUsd
+    cumulativeDepthUsd[29] = totalDepthUsd;
+    return {
+        totalDepthUsd,
+        cumulativeDepthUsd,
+    };
+}
+exports.createConcentratedDepthBands = createConcentratedDepthBands;

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

@@ -0,0 +1,32 @@
+/**
+ * @dev Depth bands decoding functions
+ */
+import { type DecodedDepthBands, type DecodedDepthBandsMapping, type EncodedDepthBands, type PairDepthBands } from "./types";
+/**
+ * Decode depth bands from encoded slots
+ * @param encoded Encoded depth bands
+ * @returns Decoded depth bands with totalDepthUsd and band percentages
+ */
+export declare function decodeDepthBands(encoded: EncodedDepthBands): DecodedDepthBands;
+/**
+ * Decode pair depth bands (both directions)
+ * @param pairBands Encoded pair depth bands
+ * @returns Decoded depth bands for above and below
+ */
+export declare function decodePairDepthBands(pairBands: PairDepthBands): {
+    above: DecodedDepthBands;
+    below: DecodedDepthBands;
+};
+/**
+ * Decode depth bands mapping (global offsets)
+ * @param slot1 First slot containing bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Decoded mapping with band offset values in ppm
+ */
+export declare function decodeDepthBandsMapping(slot1: bigint, slot2: bigint): DecodedDepthBandsMapping;
+/**
+ * Convert decoded band percentages back to cumulative depth USD
+ * @param decoded Decoded depth bands
+ * @returns Array of cumulative depth values in USD
+ */
+export declare function bandsToCumulativeDepth(decoded: DecodedDepthBands): number[];