@gainsnetwork/sdk 1.4.0-rc1 → 1.4.2-rc1

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";

package/lib/pricing/depthBands/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * @dev Depth bands module exports
+ */
+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 });
+// Types
+__exportStar(require("./types"), exports);
+// Core functions
+__exportStar(require("./encoder"), exports);
+__exportStar(require("./decoder"), exports);
+__exportStar(require("./validator"), exports);
+__exportStar(require("./converter"), exports);

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

@@ -0,0 +1,49 @@
+/**
+ * @dev Depth bands types for price impact calculations
+ */
+export declare const DEPTH_BANDS_COUNT = 30;
+export declare const DEPTH_BANDS_PER_SLOT1 = 14;
+export declare const HUNDRED_P_BPS = 10000;
+/**
+ * @dev Encoded depth bands for a single direction
+ */
+export interface EncodedDepthBands {
+    slot1: bigint;
+    slot2: bigint;
+}
+/**
+ * @dev Encoded depth bands for both directions
+ */
+export interface PairDepthBands {
+    aboveSlot1: bigint;
+    aboveSlot2: bigint;
+    belowSlot1: bigint;
+    belowSlot2: bigint;
+}
+/**
+ * @dev Decoded depth bands data
+ */
+export interface DecodedDepthBands {
+    totalDepthUsd: number;
+    bands: number[];
+}
+/**
+ * @dev Input for encoding depth bands
+ */
+export interface DepthBandsInput {
+    totalDepthUsd: number;
+    cumulativeDepthUsd: number[];
+}
+/**
+ * @dev Depth bands mapping for all pairs
+ */
+export interface DepthBandsMapping {
+    slot1: bigint;
+    slot2: bigint;
+}
+/**
+ * @dev Decoded depth bands mapping
+ */
+export interface DecodedDepthBandsMapping {
+    bands: number[];
+}

package/lib/pricing/depthBands/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * @dev Depth bands types for price impact calculations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUNDRED_P_BPS = exports.DEPTH_BANDS_PER_SLOT1 = exports.DEPTH_BANDS_COUNT = void 0;
+// Constants matching smart contract
+exports.DEPTH_BANDS_COUNT = 30;
+exports.DEPTH_BANDS_PER_SLOT1 = 14;
+exports.HUNDRED_P_BPS = 10000;

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

@@ -0,0 +1,22 @@
+/**
+ * @dev Depth bands validation functions
+ */
+import { type DecodedDepthBands, type DepthBandsInput } from "./types";
+/**
+ * Validate that depth bands are properly formed
+ * @param bands Decoded depth bands to validate
+ * @throws Error if bands are invalid
+ */
+export declare function validateDepthBands(bands: DecodedDepthBands): void;
+/**
+ * Validate depth bands input before encoding
+ * @param input Depth bands input to validate
+ * @throws Error if input is invalid
+ */
+export declare function validateDepthBandsInput(input: DepthBandsInput): void;
+/**
+ * Validate depth bands mapping
+ * @param bands Array of band offset values in ppm
+ * @throws Error if mapping is invalid
+ */
+export declare function validateDepthBandsMapping(bands: number[]): void;

package/lib/pricing/depthBands/validator.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * @dev Depth bands validation functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDepthBandsMapping = exports.validateDepthBandsInput = exports.validateDepthBands = void 0;
+const types_1 = require("./types");
+/**
+ * Validate that depth bands are properly formed
+ * @param bands Decoded depth bands to validate
+ * @throws Error if bands are invalid
+ */
+function validateDepthBands(bands) {
+    const { totalDepthUsd, bands: bandValues } = bands;
+    // Check band count
+    if (bandValues.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid band count: expected ${types_1.DEPTH_BANDS_COUNT}, got ${bandValues.length}`);
+    }
+    // Check totalDepthUsd is non-negative
+    if (totalDepthUsd < 0) {
+        throw new Error(`Total depth USD cannot be negative: ${totalDepthUsd}`);
+    }
+    // Check bands are monotonically increasing
+    let prevBand = 0;
+    for (let i = 0; i < bandValues.length; i++) {
+        const band = bandValues[i];
+        if (band < 0) {
+            throw new Error(`Band ${i} cannot be negative: ${band}`);
+        }
+        if (band < prevBand) {
+            throw new Error(`Band ${i} (${band}) is less than previous band (${prevBand})`);
+        }
+        if (band > types_1.HUNDRED_P_BPS) {
+            throw new Error(`Band ${i} exceeds 100%: ${band} bps > ${types_1.HUNDRED_P_BPS} bps`);
+        }
+        prevBand = band;
+    }
+    // Check that last band reaches 100% (with tolerance for rounding)
+    const lastBand = bandValues[bandValues.length - 1];
+    if (totalDepthUsd > 0 && Math.abs(lastBand - types_1.HUNDRED_P_BPS) > 10) {
+        throw new Error(`Last band does not reach 100%: ${lastBand} bps (expected ~${types_1.HUNDRED_P_BPS} bps)`);
+    }
+}
+exports.validateDepthBands = validateDepthBands;
+/**
+ * Validate depth bands input before encoding
+ * @param input Depth bands input to validate
+ * @throws Error if input is invalid
+ */
+function validateDepthBandsInput(input) {
+    const { totalDepthUsd, cumulativeDepthUsd } = input;
+    // Check array length
+    if (cumulativeDepthUsd.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid cumulative depth array length: expected ${types_1.DEPTH_BANDS_COUNT}, got ${cumulativeDepthUsd.length}`);
+    }
+    // Check totalDepthUsd
+    if (totalDepthUsd < 0) {
+        throw new Error(`Total depth USD cannot be negative: ${totalDepthUsd}`);
+    }
+    const maxUint32 = Math.pow(2, 32) - 1;
+    if (totalDepthUsd > maxUint32) {
+        throw new Error(`Total depth USD exceeds uint32 max: ${totalDepthUsd} > ${maxUint32}`);
+    }
+    // Check cumulative values are monotonically increasing
+    let prevValue = 0;
+    for (let i = 0; i < cumulativeDepthUsd.length; i++) {
+        const value = cumulativeDepthUsd[i];
+        if (value < 0) {
+            throw new Error(`Cumulative depth at band ${i} cannot be negative: ${value}`);
+        }
+        if (value < prevValue) {
+            throw new Error(`Cumulative depth at band ${i} (${value}) is less than previous (${prevValue})`);
+        }
+        if (value > totalDepthUsd) {
+            throw new Error(`Cumulative depth at band ${i} (${value}) exceeds total depth (${totalDepthUsd})`);
+        }
+        prevValue = value;
+    }
+    // Check that last cumulative value equals total depth (with tolerance)
+    const lastValue = cumulativeDepthUsd[cumulativeDepthUsd.length - 1];
+    if (totalDepthUsd > 0 && Math.abs(lastValue - totalDepthUsd) > 1) {
+        throw new Error(`Last cumulative depth (${lastValue}) does not match total depth (${totalDepthUsd})`);
+    }
+}
+exports.validateDepthBandsInput = validateDepthBandsInput;
+/**
+ * Validate depth bands mapping
+ * @param bands Array of band offset values in ppm
+ * @throws Error if mapping is invalid
+ */
+function validateDepthBandsMapping(bands) {
+    // Check array length
+    if (bands.length !== types_1.DEPTH_BANDS_COUNT) {
+        throw new Error(`Invalid band count: expected ${types_1.DEPTH_BANDS_COUNT}, got ${bands.length}`);
+    }
+    // Check bands are monotonically increasing and within range
+    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) {
+            throw new Error(`Band ${i} cannot be negative: ${band}`);
+        }
+        if (band > maxUint16) {
+            throw new Error(`Band ${i} exceeds uint16 max: ${band} > ${maxUint16}`);
+        }
+        if (band < prevBand) {
+            throw new Error(`Band ${i} (${band} ppm) is less than previous band (${prevBand} ppm)`);
+        }
+        prevBand = band;
+    }
+}
+exports.validateDepthBandsMapping = validateDepthBandsMapping;

package/lib/pricing/depthBands.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @dev Depth bands encoding/decoding functions
+ */
+/**
+ * Encode depth bands data into two uint256 slots
+ * @param totalDepthUsd Total depth in USD (must fit in uint32)
+ * @param bandPercentagesBps Array of 30 band percentages in basis points
+ * @returns Two slots as bigints
+ */
+export declare function encodeDepthBands(totalDepthUsd: number, bandPercentagesBps: number[]): {
+    slot1: bigint;
+    slot2: bigint;
+};
+/**
+ * Decode depth bands from two uint256 slots
+ * @param slot1 First slot containing totalDepthUsd and bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Total depth and array of band percentages
+ */
+export declare function decodeDepthBands(slot1: bigint, slot2: bigint): {
+    totalDepthUsd: number;
+    bands: number[];
+};
+/**
+ * Encode depth bands mapping (global offsets for all pairs)
+ * @param bands Array of 30 band offset values in ppm
+ * @returns Two slots as bigints
+ */
+export declare function encodeDepthBandsMapping(bands: number[]): {
+    slot1: bigint;
+    slot2: bigint;
+};
+/**
+ * Decode depth bands mapping from two uint256 slots
+ * @param slot1 First slot containing bands 0-13 (starting at bit 32, first 32 bits unused)
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Array of band offset values in ppm
+ */
+export declare function decodeDepthBandsMapping(slot1: bigint, slot2: bigint): number[];

package/lib/pricing/depthBands.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * @dev Depth bands encoding/decoding functions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeDepthBandsMapping = exports.encodeDepthBandsMapping = exports.decodeDepthBands = exports.encodeDepthBands = void 0;
+const DEPTH_BANDS_COUNT = 30;
+const DEPTH_BANDS_PER_SLOT1 = 14;
+/**
+ * Encode depth bands data into two uint256 slots
+ * @param totalDepthUsd Total depth in USD (must fit in uint32)
+ * @param bandPercentagesBps Array of 30 band percentages in basis points
+ * @returns Two slots as bigints
+ */
+function encodeDepthBands(totalDepthUsd, bandPercentagesBps) {
+    // Pack slot1: totalDepthUsd (32 bits) + bands 0-13 (14 * 16 bits)
+    let slot1 = BigInt(totalDepthUsd);
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        const shift = 32 + i * 16;
+        slot1 |= BigInt(bandPercentagesBps[i]) << BigInt(shift);
+    }
+    // Pack slot2: bands 14-29 (16 * 16 bits)
+    let slot2 = BigInt(0);
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        slot2 |= BigInt(bandPercentagesBps[i]) << BigInt(shift);
+    }
+    return { slot1, slot2 };
+}
+exports.encodeDepthBands = encodeDepthBands;
+/**
+ * Decode depth bands from two uint256 slots
+ * @param slot1 First slot containing totalDepthUsd and bands 0-13
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Total depth and array of band percentages
+ */
+function decodeDepthBands(slot1, slot2) {
+    const totalDepthUsd = Number(slot1 & BigInt(0xffffffff));
+    const bands = [];
+    // Extract bands 0-13 from slot1
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        const shift = 32 + i * 16;
+        bands.push(Number((slot1 >> BigInt(shift)) & BigInt(0xffff)));
+    }
+    // Extract bands 14-29 from slot2
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        bands.push(Number((slot2 >> BigInt(shift)) & BigInt(0xffff)));
+    }
+    return { totalDepthUsd, bands };
+}
+exports.decodeDepthBands = decodeDepthBands;
+/**
+ * Encode depth bands mapping (global offsets for all pairs)
+ * @param bands Array of 30 band offset values in ppm
+ * @returns Two slots as bigints
+ */
+function encodeDepthBandsMapping(bands) {
+    // Pack slot1: bands 0-13 (starting at bit 32, first 32 bits unused)
+    let slot1 = BigInt(0);
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        const shift = 32 + i * 16; // Start at bit 32 to match contract
+        slot1 |= BigInt(bands[i]) << BigInt(shift);
+    }
+    // Pack slot2: bands 14-29 (16 * 16 bits)
+    let slot2 = BigInt(0);
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        slot2 |= BigInt(bands[i]) << BigInt(shift);
+    }
+    return { slot1, slot2 };
+}
+exports.encodeDepthBandsMapping = encodeDepthBandsMapping;
+/**
+ * Decode depth bands mapping from two uint256 slots
+ * @param slot1 First slot containing bands 0-13 (starting at bit 32, first 32 bits unused)
+ * @param slot2 Second slot containing bands 14-29
+ * @returns Array of band offset values in ppm
+ */
+function decodeDepthBandsMapping(slot1, slot2) {
+    const bands = [];
+    // Extract bands 0-13 from slot1 (skip first 32 bits which are unused for mappings)
+    for (let i = 0; i < DEPTH_BANDS_PER_SLOT1; i++) {
+        const shift = 32 + i * 16; // Start at bit 32, not bit 0
+        bands.push(Number((slot1 >> BigInt(shift)) & BigInt(0xffff)));
+    }
+    // Extract bands 14-29 from slot2
+    for (let i = DEPTH_BANDS_PER_SLOT1; i < DEPTH_BANDS_COUNT; i++) {
+        const shift = (i - DEPTH_BANDS_PER_SLOT1) * 16;
+        bands.push(Number((slot2 >> BigInt(shift)) & BigInt(0xffff)));
+    }
+    return bands;
+}
+exports.decodeDepthBandsMapping = decodeDepthBandsMapping;

package/lib/pricing/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @dev Pricing module exports
+ */
+export * from "./depthBands";

package/lib/pricing/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @dev Pricing module exports
+ */
+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("./depthBands"), exports);

package/lib/trade/effectiveLeverage/builder.d.ts

@@ -0,0 +1,23 @@
+import { GlobalTradingVariablesType } from "../../backend/tradingVariables/types";
+import { TradeInfo } from "..";
+import { TradeEffectiveLeverageContext } from "./types";
+/**
+ * @dev Builds a complete context for effective leverage calculations
+ * @dev Uses the closing price impact context builder as a sub-context
+ * @param globalTradingVariables The transformed global trading variables from backend
+ * @param collateralIndex The collateral index (1-based)
+ * @param pairIndex The pair index
+ * @param tradeInfo Trade information including createdBlock
+ * @param additionalParams Additional parameters for price impact calculations
+ * @returns Complete context ready for getTradeNewEffectiveLeverage
+ */
+export declare const buildTradeEffectiveLeverageContext: (globalTradingVariables: GlobalTradingVariablesType, collateralIndex: number, pairIndex: number, tradeInfo: TradeInfo, additionalParams: {
+    currentBlock: number;
+    contractsVersion?: number;
+    isPnlPositive?: boolean;
+    userPriceImpact?: {
+        cumulVolPriceImpactMultiplier: number;
+        fixedSpreadP: number;
+    };
+    protectionCloseFactorWhitelist?: boolean;
+}) => TradeEffectiveLeverageContext | undefined;