@gainsnetwork/sdk 1.4.0-rc1 → 1.4.2-rc1

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,3 +4,4 @@
 export * from "./types";
 export * from "./marketPrice";
 export * from "./builder";
+export * from "./signedPrices";

package/lib/markets/price/index.js

@@ -20,3 +20,4 @@ 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

@@ -0,0 +1,36 @@
+import { Oracle, SignedPricesResponse } from "./types";
+import { PendingOrderType } from "../../trade";
+export interface FetchSignedPricesInput {
+    oracles: Oracle[];
+    pairs: number[];
+    chain: number;
+    minAnswer?: number;
+    timeoutMs?: number;
+}
+export declare const fetchSignedPrices: (input: FetchSignedPricesInput) => Promise<SignedPricesResponse[] | null>;
+export interface FetchSignedLookbackPricesInput {
+    oracles: Oracle[];
+    trader: string;
+    tradeIndex: number;
+    pair: number;
+    orderType: PendingOrderType;
+    currentBlock: number;
+    fromBlock: number;
+    chain: number;
+    minAnswer?: number;
+    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[];
+};
+export declare const isValidSignedPricesChain: (chainId: number) => boolean;
+export declare const isValidSignedPricesOrderType: (orderType: PendingOrderType) => boolean;

package/lib/markets/price/signedPrices.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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");
+const fetchSignedPrices = async (input) => {
+    const { minAnswers, timeoutMs, oracles, chain } = {
+        minAnswers: input.chain === types_1.ChainId.ARBITRUM_SEPOLIA ? 2 : 3,
+        timeoutMs: 1000,
+        ...input,
+    };
+    if (!(0, exports.isValidSignedPricesChain)(chain))
+        throw new Error(`Invalid chain ${chain}`);
+    const { valid, pairs } = (0, exports.validateSignedPricesPairs)(input.pairs);
+    if (!valid)
+        throw new Error(`Invalid pairs array`);
+    return await initiateSignedPricesRequest(oracles, "signPrices", JSON.stringify({ pairs, chain }), minAnswers, timeoutMs);
+};
+exports.fetchSignedPrices = fetchSignedPrices;
+const fetchSignedLookbackPrices = async (input) => {
+    const { minAnswers, timeoutMs, oracles, trader, tradeIndex, pair, orderType, currentBlock, fromBlock, chain, } = {
+        minAnswers: input.chain === types_1.ChainId.ARBITRUM_SEPOLIA ? 2 : 3,
+        timeoutMs: 6000,
+        ...input,
+    };
+    if (!(0, exports.isValidSignedPricesChain)(chain))
+        throw new Error(`Invalid chain ${chain}`);
+    if (!(0, exports.isValidSignedPricesOrderType)(orderType))
+        throw new Error(`Invalid orderType ${orderType}`);
+    if (isNaN(pair))
+        throw new Error(`Invalid pair ${pair}`);
+    if (isNaN(tradeIndex) || tradeIndex < 0)
+        throw new Error(`Invalid tradeIndex ${tradeIndex}`);
+    if (!currentBlock || !fromBlock)
+        throw new Error(`Invalid block numbers`);
+    return await initiateSignedPricesRequest(oracles, "signLookbackPrices", JSON.stringify({
+        trader,
+        tradeIndex,
+        pair,
+        orderType,
+        currentBlock,
+        fromBlock,
+        chain,
+    }), 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 {
+        // Fetch signed prices from all oracles in parallel
+        const signedPrices = await Promise.allSettled(oracles.map(oracle => _getSignedPricesFromSigner(`${oracle.url}/${request}`, requestBody, oracle?.key, timeoutMs)));
+        // Filter out failed requests and null responses, then sort by signerId
+        const successfulResponses = signedPrices.filter(res => res.status === "fulfilled" && res.value !== null // Filter out failed or null responses
+        )
+            // Extract `value`
+            .map((res) => res.value)
+            // Sort by signerId, contracts expect signerId ascending
+            .sort((a, b) => a.signedData.signerId - b.signedData.signerId);
+        // Ensure we have at least `minAnswers` valid responses
+        if (successfulResponses.length < minAnswers) {
+            throw new Error(`Not enough valid signed prices. Wanted ${minAnswers} but got ${successfulResponses.length}`);
+        }
+        return successfulResponses;
+    }
+    catch (e) {
+        console.error("Error processing signed prices", e);
+        throw e;
+    }
+};
+const _getSignedPricesFromSigner = async (url, requestBody, authKey, timeoutMs) => {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs || 2000);
+        const response = await fetch(`${url}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": authKey || "",
+            },
+            body: requestBody,
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch signed prices from ${url}: ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        console.error(`Error fetching signed prices from ${url}:`, {
+            error: error?.message,
+        });
+        return null;
+    }
+};
+const validateSignedPricesPairs = (pairs) => {
+    if (!Array.isArray(pairs) || pairs?.length === 0 || pairs.some(p => isNaN(p)))
+        return { valid: false, pairs: [] };
+    // Pairs must always be in ascending order
+    return { valid: true, pairs: [...new Set(pairs)].sort((a, b) => a - b) };
+};
+exports.validateSignedPricesPairs = validateSignedPricesPairs;
+const isValidSignedPricesChain = (chainId) => {
+    return (!isNaN(chainId) &&
+        [
+            types_1.ChainId.POLYGON,
+            types_1.ChainId.BASE,
+            types_1.ChainId.ARBITRUM,
+            types_1.ChainId.ARBITRUM_SEPOLIA,
+            types_1.ChainId.APECHAIN,
+        ].includes(chainId));
+};
+exports.isValidSignedPricesChain = isValidSignedPricesChain;
+const isValidSignedPricesOrderType = (orderType) => {
+    return (!isNaN(orderType) &&
+        [
+            trade_1.PendingOrderType.LIMIT_OPEN,
+            trade_1.PendingOrderType.STOP_OPEN,
+            trade_1.PendingOrderType.TP_CLOSE,
+            trade_1.PendingOrderType.SL_CLOSE,
+            trade_1.PendingOrderType.LIQ_CLOSE,
+        ].includes(orderType));
+};
+exports.isValidSignedPricesOrderType = isValidSignedPricesOrderType;

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

@@ -21,3 +21,30 @@ 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[];