@gainsnetwork/sdk 1.4.4 → 1.5.0-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/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[];

package/lib/pricing/depthBands/decoder.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * @dev Depth bands decoding functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bandsToCumulativeDepth = exports.decodeDepthBandsMapping = exports.decodePairDepthBands = exports.decodeDepthBands = void 0;
+const types_1 = require("./types");
+/**
+ * Get a specific band value from encoded slots
+ * @param slot1 First slot containing totalDepthUsd and bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @param bandIndex Index of the band to retrieve (0-29)
+ * @returns Band value
+ */
+function getBandValue(slot1, slot2, bandIndex) {
+    if (bandIndex < 0 || bandIndex >= types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid band index: must be 0-${types_1.DEPTH_BANDS_COUNT - 1}, got ${bandIndex}`);
+    }
+    if (bandIndex < types_1.DEPTH_BANDS_PER_SLOT1) {
+        // Get from slot1 (skip the first 32 bits which contain totalDepthUsd)
+        const shift = 32 + bandIndex * 16;
+        return Number((slot1 >> BigInt(shift)) & BigInt(0xffff));
+    }
+    else {
+        // Get from slot2
+        const shift = (bandIndex - types_1.DEPTH_BANDS_PER_SLOT1) * 16;
+        return Number((slot2 >> BigInt(shift)) & BigInt(0xffff));
+    }
+}
+/**
+ * Get total depth USD from encoded slot1
+ * @param slot1 First slot containing totalDepthUsd as uint32
+ * @returns Total depth in USD (6 decimal precision)
+ */
+function getTotalDepthUsd(slot1) {
+    return Number(slot1 & BigInt(0xffffffff));
+}
+/**
+ * Decode depth bands from encoded slots
+ * @param encoded Encoded depth bands
+ * @returns Decoded depth bands with totalDepthUsd and band percentages
+ */
+function decodeDepthBands(encoded) {
+    const { slot1, slot2 } = encoded;
+    const totalDepthUsd = getTotalDepthUsd(slot1);
+    const bands = [];
+    for (let i = 0; i < types_1.DEPTH_BANDS_COUNT; i++) {
+        bands.push(getBandValue(slot1, slot2, i));
+    }
+    return { totalDepthUsd, bands };
+}
+exports.decodeDepthBands = decodeDepthBands;
+/**
+ * Decode pair depth bands (both directions)
+ * @param pairBands Encoded pair depth bands
+ * @returns Decoded depth bands for above and below
+ */
+function decodePairDepthBands(pairBands) {
+    const above = decodeDepthBands({
+        slot1: pairBands.aboveSlot1,
+        slot2: pairBands.aboveSlot2,
+    });
+    const below = decodeDepthBands({
+        slot1: pairBands.belowSlot1,
+        slot2: pairBands.belowSlot2,
+    });
+    return { above, below };
+}
+exports.decodePairDepthBands = decodePairDepthBands;
+/**
+ * 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
+ */
+function decodeDepthBandsMapping(slot1, slot2) {
+    const bands = [];
+    // Note: For mapping, there's no totalDepthUsd, all bits are used for bands
+    for (let i = 0; i < types_1.DEPTH_BANDS_COUNT; i++) {
+        if (i < types_1.DEPTH_BANDS_PER_SLOT1) {
+            // Get from slot1
+            const shift = i * 16;
+            bands.push(Number((slot1 >> BigInt(shift)) & BigInt(0xffff)));
+        }
+        else {
+            // Get from slot2
+            const shift = (i - types_1.DEPTH_BANDS_PER_SLOT1) * 16;
+            bands.push(Number((slot2 >> BigInt(shift)) & BigInt(0xffff)));
+        }
+    }
+    return { bands };
+}
+exports.decodeDepthBandsMapping = decodeDepthBandsMapping;
+/**
+ * Convert decoded band percentages back to cumulative depth USD
+ * @param decoded Decoded depth bands
+ * @returns Array of cumulative depth values in USD
+ */
+function bandsToCumulativeDepth(decoded) {
+    const { totalDepthUsd, bands } = decoded;
+    const cumulativeDepthUsd = [];
+    for (const bandBps of bands) {
+        // Convert from basis points to USD
+        const depthUsd = (bandBps * totalDepthUsd) / 10000;
+        cumulativeDepthUsd.push(depthUsd);
+    }
+    return cumulativeDepthUsd;
+}
+exports.bandsToCumulativeDepth = bandsToCumulativeDepth;

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

@@ -0,0 +1,19 @@
+/**
+ * @dev Depth bands encoding functions
+ */
+import { type DepthBandsInput, type EncodedDepthBands } from "./types";
+/**
+ * Encode depth bands data into two uint256 slots
+ * @param input Depth bands input data
+ * @returns Encoded depth bands with two slots
+ */
+export declare function encodeDepthBands(input: DepthBandsInput): EncodedDepthBands;
+/**
+ * Encode depth bands mapping (global offsets for all pairs)
+ * @param bands Array of 30 band offset values in parts per million (ppm)
+ * @returns Encoded mapping with two slots
+ */
+export declare function encodeDepthBandsMapping(bands: number[]): {
+    slot1: bigint;
+    slot2: bigint;
+};

package/lib/pricing/depthBands/encoder.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * @dev Depth bands encoding functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeDepthBandsMapping = exports.encodeDepthBands = void 0;
+const types_1 = require("./types");
+/**
+ * Encode depth bands data into two uint256 slots
+ * @param input Depth bands input data
+ * @returns Encoded depth bands with two slots
+ */
+function encodeDepthBands(input) {
+    const { totalDepthUsd, cumulativeDepthUsd } = input;
+    // Validate input
+    if (cumulativeDepthUsd.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid cumulativeDepthUsd length: expected ${types_1.DEPTH_BANDS_COUNT}, got ${cumulativeDepthUsd.length}`);
+    }
+    // Validate totalDepthUsd range (must fit in uint32)
+    const maxUint32 = Math.pow(2, 32) - 1;
+    if (totalDepthUsd < 0 || totalDepthUsd > maxUint32) {
+        throw new Error(`Invalid totalDepthUsd: must be between 0 and ${maxUint32}, got ${totalDepthUsd}`);
+    }
+    // Convert cumulative depths to band percentages
+    const bandPercentagesBps = [];
+    let prevCumulativeDepth = 0;
+    for (let i = 0; i < types_1.DEPTH_BANDS_COUNT; i++) {
+        const currentCumulativeDepth = cumulativeDepthUsd[i];
+        // Validate cumulative depth is non-decreasing
+        if (currentCumulativeDepth < prevCumulativeDepth) {
+            throw new Error(`Invalid cumulative depth at band ${i}: ${currentCumulativeDepth} is less than previous ${prevCumulativeDepth}`);
+        }
+        // Calculate percentage of total depth (in basis points)
+        const percentageBps = totalDepthUsd > 0
+            ? Math.round((currentCumulativeDepth * types_1.HUNDRED_P_BPS) / totalDepthUsd)
+            : 0;
+        // Validate percentage doesn't exceed 100%
+        if (percentageBps > types_1.HUNDRED_P_BPS) {
+            throw new Error(`Band ${i} percentage exceeds 100%: ${percentageBps} bps`);
+        }
+        // Validate percentage fits in uint16
+        const maxUint16 = Math.pow(2, 16) - 1;
+        if (percentageBps > maxUint16) {
+            throw new Error(`Band ${i} percentage too large for uint16: ${percentageBps}`);
+        }
+        bandPercentagesBps.push(percentageBps);
+        prevCumulativeDepth = currentCumulativeDepth;
+    }
+    // Validate that final band reaches 100% (or close to it due to rounding)
+    const finalPercentage = bandPercentagesBps[types_1.DEPTH_BANDS_COUNT - 1];
+    if (totalDepthUsd > 0 && Math.abs(finalPercentage - types_1.HUNDRED_P_BPS) > 10) {
+        throw new Error(`Final band does not reach 100%: ${finalPercentage} bps`);
+    }
+    // Pack into slot1: totalDepthUsd (32 bits) + bands 0-13 (14 * 16 bits)
+    let slot1 = BigInt(totalDepthUsd);
+    for (let i = 0; i < types_1.DEPTH_BANDS_PER_SLOT1; i++) {
+        const shift = 32 + i * 16;
+        slot1 |= BigInt(bandPercentagesBps[i]) << BigInt(shift);
+    }
+    // Pack into slot2: bands 14-29 (16 * 16 bits)
+    let slot2 = BigInt(0);
+    for (let i = types_1.DEPTH_BANDS_PER_SLOT1; i < types_1.DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - types_1.DEPTH_BANDS_PER_SLOT1) * 16;
+        slot2 |= BigInt(bandPercentagesBps[i]) << BigInt(shift);
+    }
+    return { slot1, slot2 };
+}
+exports.encodeDepthBands = encodeDepthBands;
+/**
+ * Encode depth bands mapping (global offsets for all pairs)
+ * @param bands Array of 30 band offset values in parts per million (ppm)
+ * @returns Encoded mapping with two slots
+ */
+function encodeDepthBandsMapping(bands) {
+    // Validate input
+    if (bands.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid bands length: expected ${types_1.DEPTH_BANDS_COUNT}, got ${bands.length}`);
+    }
+    // Validate each band value and monotonic increase
+    let prevBand = 0;
+    const maxUint16 = Math.pow(2, 16) - 1;
+    for (let i = 0; i < bands.length; i++) {
+        const band = bands[i];
+        if (band < 0 || band > maxUint16) {
+            throw new Error(`Band ${i} value out of range: must be 0-${maxUint16}, got ${band}`);
+        }
+        if (band < prevBand) {
+            throw new Error(`Band ${i} value ${band} is less than previous band ${prevBand}`);
+        }
+        prevBand = band;
+    }
+    // Pack into slot1: bands 0-13 (14 * 16 bits)
+    let slot1 = BigInt(0);
+    for (let i = 0; i < types_1.DEPTH_BANDS_PER_SLOT1; i++) {
+        slot1 |= BigInt(bands[i]) << BigInt(i * 16);
+    }
+    // Pack into slot2: bands 14-29 (16 * 16 bits)
+    let slot2 = BigInt(0);
+    for (let i = types_1.DEPTH_BANDS_PER_SLOT1; i < types_1.DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - types_1.DEPTH_BANDS_PER_SLOT1) * 16;
+        slot2 |= BigInt(bands[i]) << BigInt(shift);
+    }
+    return { slot1, slot2 };
+}
+exports.encodeDepthBandsMapping = encodeDepthBandsMapping;

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

@@ -0,0 +1,8 @@
+/**
+ * @dev Depth bands module exports
+ */
+export * from "./types";
+export * from "./encoder";
+export * from "./decoder";
+export * from "./validator";
+export * from "./converter";