@hawksightco/hawk-sdk 1.3.169 → 1.3.171

package/dist/src/meteora/liquidityStrategy.d.ts

@@ -0,0 +1,268 @@
+import BN from 'bn.js';
+/**
+ * Liquidity strategy types matching Meteora DLMM SDK.
+ */
+export declare enum StrategyType {
+    /** Uniform distribution - equal value per bin (adjusted for price) */
+    SPOT = 0,
+    /** Curve distribution - decreasing amounts away from active bin */
+    CURVE = 1,
+    /** Bid-Ask distribution - increasing amounts away from active bin */
+    BID_ASK = 2
+}
+/**
+ * Liquidity strategy parameters for rebalanceLiquidity instruction.
+ * These parameters define how liquidity is distributed across bins.
+ *
+ * For SPOT strategy: deltaX = 0, deltaY = 0 (uniform distribution)
+ * For CURVE strategy: deltaX < 0, deltaY < 0 (decreasing away from active)
+ * For BID_ASK strategy: deltaX > 0, deltaY > 0 (increasing away from active)
+ *
+ * Amount per bin is calculated as:
+ * - Ask side (X): amountX = (x0 + deltaX * deltaId) * price_weight
+ * - Bid side (Y): amountY = y0 + deltaY * distance_from_active
+ */
+export interface LiquidityStrategyParameters {
+    /** Base amount for X token (ask side) */
+    x0: BN;
+    /** Base amount for Y token (bid side) */
+    y0: BN;
+    /** Delta change per bin for X (0 for SPOT, negative for CURVE, positive for BID_ASK) */
+    deltaX: BN;
+    /** Delta change per bin for Y (0 for SPOT, negative for CURVE, positive for BID_ASK) */
+    deltaY: BN;
+}
+/**
+ * Calculates the Q-price from a bin ID.
+ * Price = (1 + binStep/10000)^binId in Q64.64 format.
+ *
+ * Uses binary exponentiation matching Meteora SDK for precision.
+ *
+ * @param binId - The bin ID (can be negative)
+ * @param binStep - The bin step in basis points
+ * @returns Price in Q64.64 fixed-point format
+ */
+export declare function getQPriceFromId(binId: BN, binStep: BN): BN;
+/**
+ * Builds liquidity strategy parameters for SPOT (uniform) distribution.
+ *
+ * This function calculates x0 and y0 values that will distribute the given amounts
+ * uniformly across the specified bin range when used with the rebalanceLiquidity instruction.
+ *
+ * The function handles three cases:
+ * 1. Position entirely below active bin (bid side only) → only Y deposited
+ * 2. Position entirely above active bin (ask side only) → only X deposited
+ * 3. Position spans active bin → both X and Y deposited
+ *
+ * @param amountX - Total X amount to deposit
+ * @param amountY - Total Y amount to deposit
+ * @param minDeltaId - Minimum delta ID (lowerBinId - activeId)
+ * @param maxDeltaId - Maximum delta ID (upperBinId - activeId)
+ * @param binStep - The bin step in basis points
+ * @param activeId - The active bin ID
+ * @param favorXInActiveId - Whether X is favored in the active bin (affects bid/ask boundary)
+ * @returns Strategy parameters { x0, y0, deltaX, deltaY }
+ */
+export declare function buildSpotStrategyParameters(amountX: BN, amountY: BN, minDeltaId: BN, maxDeltaId: BN, binStep: BN, activeId: BN, favorXInActiveId?: boolean): LiquidityStrategyParameters;
+/**
+ * Resets strategy parameters for a chunk that may not span the full position range.
+ *
+ * When splitting a position into chunks, each chunk may only cover part of the range:
+ * - If chunk is entirely on bid side → zero out X parameters
+ * - If chunk is entirely on ask side → zero out Y parameters
+ * - If chunk spans active bin → keep both X and Y parameters
+ *
+ * @param minDeltaId - Chunk's minimum delta ID
+ * @param maxDeltaId - Chunk's maximum delta ID
+ * @param favorXInActiveId - Whether X is favored in the active bin
+ * @param params - Original strategy parameters from buildSpotStrategyParameters
+ * @returns Adjusted parameters for the chunk
+ */
+export declare function resetUninvolvedLiquidityParams(minDeltaId: BN, maxDeltaId: BN, favorXInActiveId: boolean, params: LiquidityStrategyParameters): LiquidityStrategyParameters;
+/**
+ * Calculates the actual X amount that will be deposited into a bin on the ask side.
+ *
+ * For SPOT strategy: amountX = x0 * price_weight
+ * where price_weight = (1 + binStep/10000)^(-(activeId + deltaId))
+ *
+ * @param x0 - Base X amount from strategy parameters
+ * @param deltaId - Delta ID relative to active bin
+ * @param binStep - The bin step in basis points
+ * @param activeId - The active bin ID
+ * @returns Amount of X for this bin
+ */
+export declare function getAmountXForBin(x0: BN, deltaId: BN, binStep: BN, activeId: BN): BN;
+/**
+ * Calculates the actual Y amount that will be deposited into a bin on the bid side.
+ *
+ * For SPOT strategy: amountY = y0 (constant per bin)
+ *
+ * @param y0 - Base Y amount from strategy parameters
+ * @returns Amount of Y for this bin
+ */
+export declare function getAmountYForBin(y0: BN): BN;
+/**
+ * Calculates total X and Y amounts for a chunk based on strategy parameters.
+ *
+ * This iterates through each bin in the chunk and sums up the amounts.
+ *
+ * @param activeId - The active bin ID
+ * @param minDeltaId - Chunk's minimum delta ID
+ * @param maxDeltaId - Chunk's maximum delta ID
+ * @param params - Strategy parameters (after resetUninvolvedLiquidityParams)
+ * @param binStep - The bin step in basis points
+ * @param favorXInActiveId - Whether X is favored in the active bin
+ * @returns Total X and Y amounts for the chunk
+ */
+export declare function calculateChunkAmounts(activeId: BN, minDeltaId: BN, maxDeltaId: BN, params: LiquidityStrategyParameters, binStep: BN, favorXInActiveId: boolean): {
+    totalXAmount: BN;
+    totalYAmount: BN;
+};
+/**
+ * Builds liquidity strategy parameters for CURVE distribution.
+ *
+ * CURVE strategy concentrates liquidity near the active bin with amounts
+ * decreasing as you move away. This is achieved with negative deltaX/deltaY.
+ *
+ * @param amountX - Total X amount to deposit
+ * @param amountY - Total Y amount to deposit
+ * @param minDeltaId - Minimum delta ID (lowerBinId - activeId)
+ * @param maxDeltaId - Maximum delta ID (upperBinId - activeId)
+ * @param binStep - The bin step in basis points
+ * @param activeId - The active bin ID
+ * @param favorXInActiveId - Whether X is favored in the active bin
+ * @returns Strategy parameters { x0, y0, deltaX, deltaY }
+ */
+export declare function buildCurveStrategyParameters(amountX: BN, amountY: BN, minDeltaId: BN, maxDeltaId: BN, binStep: BN, activeId: BN, favorXInActiveId?: boolean): LiquidityStrategyParameters;
+/**
+ * Builds liquidity strategy parameters for BID_ASK distribution.
+ *
+ * BID_ASK strategy has liquidity increasing away from the active bin.
+ * This is achieved with positive deltaX/deltaY values.
+ *
+ * @param amountX - Total X amount to deposit
+ * @param amountY - Total Y amount to deposit
+ * @param minDeltaId - Minimum delta ID (lowerBinId - activeId)
+ * @param maxDeltaId - Maximum delta ID (upperBinId - activeId)
+ * @param binStep - The bin step in basis points
+ * @param activeId - The active bin ID
+ * @param favorXInActiveId - Whether X is favored in the active bin
+ * @returns Strategy parameters { x0, y0, deltaX, deltaY }
+ */
+export declare function buildBidAskStrategyParameters(amountX: BN, amountY: BN, minDeltaId: BN, maxDeltaId: BN, binStep: BN, activeId: BN, favorXInActiveId?: boolean): LiquidityStrategyParameters;
+/**
+ * Builds liquidity strategy parameters for the specified strategy type.
+ *
+ * This is the main entry point that dispatches to the appropriate strategy builder.
+ *
+ * @param strategyType - The type of strategy (SPOT, CURVE, or BID_ASK)
+ * @param amountX - Total X amount to deposit
+ * @param amountY - Total Y amount to deposit
+ * @param minDeltaId - Minimum delta ID (lowerBinId - activeId)
+ * @param maxDeltaId - Maximum delta ID (upperBinId - activeId)
+ * @param binStep - The bin step in basis points
+ * @param activeId - The active bin ID
+ * @param favorXInActiveId - Whether X is favored in the active bin
+ * @returns Strategy parameters { x0, y0, deltaX, deltaY }
+ */
+export declare function buildStrategyParameters(strategyType: StrategyType, amountX: BN, amountY: BN, minDeltaId: BN, maxDeltaId: BN, binStep: BN, activeId: BN, favorXInActiveId?: boolean): LiquidityStrategyParameters;
+/**
+ * Represents a bin range chunk with its calculated deposit amounts.
+ */
+export interface ChunkedDepositParameters {
+    /** Lower bin ID of this chunk (absolute bin ID) */
+    lowerBinId: number;
+    /** Upper bin ID of this chunk (absolute bin ID) */
+    upperBinId: number;
+    /** Minimum delta ID relative to active bin */
+    minDeltaId: BN;
+    /** Maximum delta ID relative to active bin */
+    maxDeltaId: BN;
+    /** Strategy parameters adjusted for this chunk */
+    params: LiquidityStrategyParameters;
+    /** Maximum X amount to deposit in this chunk */
+    maxAmountX: BN;
+    /** Maximum Y amount to deposit in this chunk */
+    maxAmountY: BN;
+}
+/**
+ * Divides a bin range into chunks of specified size.
+ *
+ * This is similar to Meteora's `chunkBinRange` but with a configurable chunk size
+ * instead of a fixed 70-bin limit.
+ *
+ * @param minBinId - The starting bin ID of the range (absolute bin ID)
+ * @param maxBinId - The ending bin ID of the range (absolute bin ID)
+ * @param chunkSize - Maximum number of bins per chunk
+ * @returns Array of bin range chunks
+ */
+export declare function chunkBinRange(minBinId: number, maxBinId: number, chunkSize: number): {
+    lowerBinId: number;
+    upperBinId: number;
+}[];
+/**
+ * Converts strategy parameters to on-chain format with bit flag for negative values.
+ *
+ * The Solana program uses unsigned integers, so negative values are stored as
+ * positive with a bit flag indicating the sign.
+ *
+ * Bit flags:
+ * - Bit 0 (0b0001): x0 is negative
+ * - Bit 1 (0b0010): y0 is negative
+ * - Bit 2 (0b0100): deltaX is negative
+ * - Bit 3 (0b1000): deltaY is negative
+ *
+ * @param x0 - Base X amount (may be negative)
+ * @param y0 - Base Y amount (may be negative)
+ * @param deltaX - Delta X per bin (may be negative)
+ * @param deltaY - Delta Y per bin (may be negative)
+ * @returns Parameters with absolute values and bit flag
+ */
+export declare function buildBitFlagAndNegateStrategyParameters(x0: BN, y0: BN, deltaX: BN, deltaY: BN): {
+    bitFlag: number;
+    x0: BN;
+    y0: BN;
+    deltaX: BN;
+    deltaY: BN;
+};
+/**
+ * Calculates amounts for each bin in a range.
+ *
+ * This function iterates through all bins and calculates the X/Y amount
+ * for each bin based on the strategy parameters.
+ *
+ * @param activeId - The active bin ID
+ * @param minDeltaId - Minimum delta ID relative to active bin
+ * @param maxDeltaId - Maximum delta ID relative to active bin
+ * @param deltaX - Delta X per bin
+ * @param deltaY - Delta Y per bin
+ * @param x0 - Base X amount
+ * @param y0 - Base Y amount
+ * @param binStep - Bin step in basis points
+ * @param favorXInActiveBin - Whether X is favored in active bin
+ * @returns Array of { binId, amountX, amountY } for each bin
+ */
+export declare function toAmountIntoBins(activeId: BN, minDeltaId: BN, maxDeltaId: BN, deltaX: BN, deltaY: BN, x0: BN, y0: BN, binStep: BN, favorXInActiveBin: boolean): {
+    binId: number;
+    amountX: BN;
+    amountY: BN;
+}[];
+/**
+ * Chunks a deposit into multiple transactions based on bin range.
+ *
+ * This function:
+ * 1. Takes pre-built strategy parameters for the entire position
+ * 2. Chunks the bin range into smaller ranges
+ * 3. For each chunk, adjusts params and calculates amounts
+ *
+ * @param params - Strategy parameters from buildStrategyParameters (for entire position)
+ * @param minDeltaId - Minimum delta ID (lowerBinId - activeId)
+ * @param maxDeltaId - Maximum delta ID (upperBinId - activeId)
+ * @param activeId - Current active bin ID
+ * @param binStep - Bin step in basis points
+ * @param chunkSize - Maximum bins per chunk
+ * @param favorXInActiveBin - Whether X is favored in active bin
+ * @returns Array of chunked deposit parameters
+ */
+export declare function chunkDepositParameters(params: LiquidityStrategyParameters, minDeltaId: BN, maxDeltaId: BN, activeId: BN, binStep: BN, chunkSize: number, favorXInActiveBin?: boolean): ChunkedDepositParameters[];
+//# sourceMappingURL=liquidityStrategy.d.ts.map

package/dist/src/meteora/liquidityStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquidityStrategy.d.ts","sourceRoot":"","sources":["../../../src/meteora/liquidityStrategy.ts"],"names":[],"mappings":"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"}