@cetusprotocol/dlmm-zap-sdk 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -1,8 +1,11 @@
+import * as _cetusprotocol_aggregator_sdk from '@cetusprotocol/aggregator-sdk';
 import { AggregatorClient } from '@cetusprotocol/aggregator-sdk';
 import { StrategyType, BinAmount, BinLiquidityInfo, CetusDlmmSDK } from '@cetusprotocol/dlmm-sdk';
-import { CoinPairType, IModule, SdkWrapper, BaseSdkOptions, BaseError } from '@cetusprotocol/common-sdk';
+import { CoinPairType, IModule, SuiObjectIdType, SuiAddressType, SdkWrapper, BaseSdkOptions, BaseError } from '@cetusprotocol/common-sdk';
+import * as _mysten_sui_transactions from '@mysten/sui/transactions';
 import { TransactionObjectArgument, Transaction } from '@mysten/sui/transactions';
-import Decimal from 'decimal.js';
+import * as Decimal from 'decimal.js';
+import Decimal__default from 'decimal.js';
 
 declare const defaultSwapSlippage = 0.005;
 /**
@@ -142,6 +145,509 @@ declare class ZapModule implements IModule<CetusDlmmZapSDK> {
     buildWithdrawPayload(options: WithdrawOptions): Promise<Transaction>;
 }
 
+/**
+ * Common parameters shared across multiple compound operations
+ */
+type CommonParams = {
+    /**
+     * The object id about which pool you want to operation.
+     */
+    pool_id: SuiObjectIdType;
+    /**
+     * The object id about position.
+     */
+    pos_id: SuiObjectIdType;
+};
+/**
+ * Parameters for closing position and returning amount coins with merge swap functionality
+ */
+type ClosePosReturnAmountCoinAParams = CommonParams & CoinPairType & {
+    remove_percent?: number;
+    active_id: number;
+    bin_step: number;
+    slippage: number;
+    bin_infos: BinLiquidityInfo;
+    /**
+      * Coin types associated with rewarder contracts.
+      */
+    rewarder_coin_types: SuiAddressType[];
+    close_position?: boolean;
+};
+/**
+ * Parameters for closing position and returning only amount coins without merge swap
+ */
+type ClosePosOnlyReturnAmountCoinsParams = CommonParams & CoinPairType & {
+    remove_percent?: number;
+    active_id: number;
+    bin_step: number;
+    slippage: number;
+    bin_infos: BinLiquidityInfo;
+    rewarder_coin_types: string[];
+    close_position?: boolean;
+};
+/**
+ * Parameters for collecting fees and rewards and returning coins
+ */
+type CollectFeeAndRewardsAndReturnCoinsParams = CommonParams & CoinPairType & {
+    /**
+     * Coin types associated with rewarder contracts
+     */
+    rewarder_coin_types: SuiAddressType[];
+};
+/**
+ * Parameters for calculating claim merge swap routes
+ */
+type CalculateClaimMergeParams = CoinPairType & {
+    /**
+     * The object id about which pool you want to operation
+     */
+    pool_id: string;
+    /**
+     * The object id about position
+     */
+    position_id: string;
+    /**
+     * Array of rewarder coin types
+     */
+    rewarder_types: string[];
+    /**
+     * Target coin type for merge swap
+     */
+    target_coin_type: string;
+    not_merge_coins: string[];
+};
+/**
+ * Parameters for creating claim merge swap payload
+ */
+type CreateClaimMergePayloadParams = CoinPairType & {
+    /**
+     * The object id about which pool you want to operation
+     */
+    pool_id: string;
+    /**
+     * The object id about position
+     */
+    pos_id: string;
+    /**
+     * Array of rewarder coin types
+     */
+    rewarder_coin_types: string[];
+    /**
+     * Coins to exclude from merge swap
+     */
+    not_merge_coins: string[];
+    /**
+     * Router configuration for merge swap
+     */
+    merge_routers: any;
+    /**
+     * Slippage tolerance for the swap
+     */
+    slippage: number;
+    /**
+     * Target coin type for merge swap
+     */
+    target_coin_type: string;
+};
+/**
+ * Parameters for calculating optimal rebalancing
+ */
+type CalculateRebalanceParams = {
+    /**
+     * The object id about which pool you want to operation
+     */
+    pool_id: string;
+    /**
+     * Coin type for the first token in the pair
+     */
+    coin_type_a: string;
+    /**
+     * Coin type for the second token in the pair
+     */
+    coin_type_b: string;
+    /**
+     * Decimal precision for the first coin
+     */
+    coin_decimal_a: number;
+    /**
+     * Decimal precision for the second coin
+     */
+    coin_decimal_b: number;
+    /**
+     * Current amount of the first coin
+     */
+    amount_a: string;
+    /**
+     * Current amount of the second coin
+     */
+    amount_b: string;
+    lower_bin_id: number;
+    upper_bin_id: number;
+    active_id: number;
+    bin_step: number;
+    strategy_type: StrategyType;
+    active_bin_of_pool?: BinAmount;
+    /**
+     * Slippage tolerance for swaps
+     */
+    slippage: number;
+    /**
+     * Maximum remaining rate threshold (optional, default: 0.01)
+     */
+    max_remain_rate?: number;
+    /**
+     * Mark price for calculation (optional)
+     */
+    mark_price?: string;
+    /**
+     * Loop counter for price verification (optional, default: 0)
+     */
+    verify_price_loop?: number;
+    old_pos_origin_amount_a?: string;
+    old_pos_origin_amount_b?: string;
+};
+/**
+ * Result of rebalancing calculation with optimal allocation
+ */
+type RebalanceResult = {
+    bin_infos: BinLiquidityInfo;
+    lower_bin_id: number;
+    upper_bin_id: number;
+    /**
+     * Amount of the first coin to use
+     */
+    use_amount_a: string;
+    /**
+     * Amount of the second coin to use
+     */
+    use_amount_b: string;
+    /**
+     * Whether the first coin amount is fixed
+     */
+    fix_amount_a: boolean;
+    /**
+     * Remaining amount after optimal allocation
+     */
+    remain_amount: string;
+    /**
+     * Swap result if rebalancing requires swapping (optional)
+     */
+    swap_result?: any;
+    /**
+     * Error message if rebalancing fails (optional)
+     */
+    error?: string;
+    swap_amount_in?: string;
+    swap_in_coin_type?: string;
+};
+/**
+ * Parameters for creating move position payload to migrate from old range to new range
+ */
+type CreateMovePositionPayloadParams = {
+    /**
+     * Old position details
+     */
+    oldPos: {
+        /**
+         * The object id about which pool you want to operation
+         */
+        pool_id: string;
+        /**
+         * The object id about position
+         */
+        pos_id: string;
+        /**
+         * Coin type for the first token in the pair
+         */
+        coin_type_a: SuiAddressType;
+        /**
+         * Coin type for the second token in the pair
+         */
+        coin_type_b: SuiAddressType;
+        /**
+         * Coin types associated with rewarder contracts
+         */
+        rewarder_coin_types: SuiAddressType[];
+        active_id: number;
+        bin_step: number;
+        slippage: number;
+        bin_infos: BinLiquidityInfo;
+        remove_percent?: number;
+        close_position?: boolean;
+    };
+    /**
+     * New position details
+     */
+    newPos: {
+        lower_bin_id: number;
+        upper_bin_id: number;
+        active_id: number;
+        bin_step: number;
+        strategy_type: StrategyType;
+        active_bin_of_pool?: BinAmount;
+    };
+    /**
+     * Pre-calculated rebalancing result
+     */
+    rebalancePre: RebalanceResult;
+    /**
+     * Slippage tolerance for swaps
+     */
+    slippage: number;
+    /**
+     * Optional merge swap configuration
+     */
+    rewarderMergeOption?: {
+        /**
+         * Router configuration for merge swap
+         */
+        merge_routers: any;
+        /**
+         * Slippage tolerance for merge swap
+         */
+        slippage: number;
+        /**
+         * Coins to exclude from merge swap
+         */
+        not_merge_coins: string[];
+    };
+    /**
+     * Whether fees and rewards have already been claimed (optional)
+     */
+    have_claim?: boolean;
+};
+/**
+ * Parameters for pre-calculating swap operations
+ */
+type PreSwapParams = {
+    /**
+     * The object id about which pool you want to operation
+     */
+    pool_id: string;
+    /**
+     * Source coin type for the swap
+     */
+    from_coin_type: string;
+    /**
+     * Target coin type for the swap
+     */
+    target_coin_type: string;
+    /**
+     * Amount to swap
+     */
+    amount: string;
+    /**
+     * Decimal precision for the source coin
+     */
+    from_coin_decimal: number;
+    /**
+     * Decimal precision for the target coin
+     */
+    target_coin_decimal: number;
+    /**
+     * Whether swapping from coin A to coin B
+     */
+    is_a2b: boolean;
+    /**
+     * Slippage tolerance for the swap
+     */
+    slippage: number;
+};
+/**
+ * Parameters for creating compound rebalance add payload
+ */
+type CreateCompoundRebalanceAddPayload = {
+    /**
+     * Base parameters for the compound operation
+     */
+    baseParams: {
+        /**
+         * The object id about which pool you want to operation
+         */
+        pool_id: string;
+        /**
+         * The object id about position
+         */
+        pos_id: string;
+        /**
+         * Coin type for the first token in the pair
+         */
+        coin_type_a: SuiAddressType;
+        /**
+         * Coin type for the second token in the pair
+         */
+        coin_type_b: SuiAddressType;
+        /**
+         * Coin types associated with rewarder contracts
+         */
+        rewarder_coin_types: SuiAddressType[];
+        active_id: number;
+        bin_step: number;
+        strategy_type: StrategyType;
+        active_bin_of_pool?: BinAmount;
+    };
+    /**
+     * Pre-calculated rebalancing result
+     */
+    rebalancePre: RebalanceResult;
+    /**
+     * Merge swap configuration for rewarders
+     */
+    rewarderMergeOption: {
+        /**
+         * Router configuration for merge swap
+         */
+        merge_routers: any;
+        /**
+         * Slippage tolerance for merge swap
+         */
+        slippage: number;
+        /**
+         * Coins to exclude from merge swap
+         */
+        not_merge_coins: string[];
+    };
+    /**
+     * Optional transaction object (creates new one if not provided)
+     */
+    tx?: Transaction;
+};
+
+/**
+ * DLMM 复投/调仓模块。
+ * 该模块负责三类核心能力：
+ * 1) 仓位手续费与奖励的归集、可选合并兑换；
+ * 2) 根据目标配比计算再平衡（是否需要先 swap）；
+ * 3) 关老仓并把资产迁移到新价格区间（move position）。
+ */
+declare class CompoundModule implements IModule<CetusDlmmZapSDK> {
+    protected _sdk: CetusDlmmZapSDK;
+    constructor(sdk: CetusDlmmZapSDK);
+    get sdk(): CetusDlmmZapSDK;
+    /** 统一滑点处理：按向下取整保守估算可得数量，避免高估导致后续交易失败。 */
+    private calculateAmountWithSlippage;
+    /**
+     * 拉取单个仓位当前可领取的 fee/reward 快照。
+     * 注意：这里只做读取，不构建交易，也不改变链上状态。
+     */
+    private fetchFeeAndRewardSnapshot;
+    /**
+     * 获取“归集后可用”的 A/B 两币数量：
+     * - fee + reward 中同币种会合并到 coin_amount_a / coin_amount_b；
+     * - 其它奖励币会尝试聚合路由估算后并入目标币；
+     * - not_merge_coins 中的币不会进入 merge swap。
+     */
+    getFeeAndReward(params: {
+        pool_id: string;
+        position_id: string;
+        coin_type_a: SuiAddressType;
+        coin_type_b: SuiAddressType;
+        rewarder_types: string[];
+        merge_swap_target_coin_type: string;
+        not_merge_coins: string[];
+    }): Promise<{
+        coin_amount_a: string;
+        coin_amount_b: string;
+        merge_routers: _cetusprotocol_aggregator_sdk.MergeSwapRouterData | null | undefined;
+    }>;
+    /**
+     * 计算“claim 后一次性 merge 到目标币”的路由输入集合。
+     * 返回 null 表示无可合并资产，调用方可直接跳过 merge 流程。
+     */
+    calculateClaimMerge(params: CalculateClaimMergeParams): Promise<_cetusprotocol_aggregator_sdk.MergeSwapRouterData | null>;
+    /**
+     * 计算再平衡方案：
+     * 1) 先用当前 A/B 数量求“理论可加仓分布”；
+     * 2) 若明显偏单边，则按目标配比求需 swap 数量；
+     * 3) 使用 swap 后的真实数量重新计算最终 bin_infos。
+     */
+    calculateRebalance(params: CalculateRebalanceParams): Promise<RebalanceResult>;
+    /** 单次预交换查询：返回路由、路由价格、滑点后最小可得数量。 */
+    preSwap(params: PreSwapParams): Promise<{
+        swapResult: any;
+        routerPrice: string;
+        swapAmountOutWithSlippage: string;
+    }>;
+    /**
+     * 构造“领取 fee/reward 且不立即转账”的交易片段，并把同币奖励合并到 fee 结果中：
+     * - fee_a / fee_b 作为后续复投主输入；
+     * - 其它奖励币独立返回，交给上层决定是 merge 还是直接转走。
+     */
+    collectFeeAndRewardsAndReturnCoins(params: {
+        pool_id: string;
+        pos_id: string;
+        coin_type_a: string;
+        coin_type_b: string;
+        rewarder_coin_types: string[];
+    }, tx: Transaction): Promise<{
+        fee_a: _mysten_sui_transactions.TransactionObjectArgument;
+        fee_b: _mysten_sui_transactions.TransactionObjectArgument;
+        other_rewarder: Record<string, any>;
+    }>;
+    /**
+     * 领取并处理奖励：
+     * - A/B 同币奖励直接并入 coin_a/coin_b；
+     * - 可 merge 的其它奖励币收集进 mergeInputCoinMap；
+     * - 不处理的其它奖励币直接转回用户地址。
+     */
+    claimFeeAndRewardsAndMergeRewards(baseParams: {
+        pool_id: string;
+        pos_id: string;
+        coin_type_a: SuiAddressType;
+        coin_type_b: SuiAddressType;
+        rewarder_coin_types: SuiAddressType[];
+    }, rewarderMergeOption?: {
+        merge_routers: any;
+        slippage: number;
+        not_merge_coins: string[];
+    }, tx?: Transaction): Promise<{
+        coin_a: any;
+        coin_b: any;
+    }>;
+    /**
+     * 关闭或部分移除老仓，仅返回“仓位本金币对象”：
+     * - fee/reward 先领取并直接转给用户；
+     * - close_position=true 走 closePosition；
+     * - 否则走 removeLiquidity（按 remove_percent）。
+     */
+    closePosOnlyReturnAmountCoins(params: ClosePosOnlyReturnAmountCoinsParams, tx: Transaction): Promise<{
+        coin_a: _mysten_sui_transactions.TransactionObjectArgument;
+        coin_b: _mysten_sui_transactions.TransactionObjectArgument;
+    }>;
+    /**
+     * 关闭/部分移除仓位并保留 A/B 两币对象：
+     * - 与 closePosOnlyReturnAmountCoins 的区别是，这里会先做奖励 merge；
+     * - 最终把仓位本金并回 coin_a/coin_b，作为后续复投输入。
+     */
+    closePosReturnCoinWithMerge(params: ClosePosReturnAmountCoinAParams, rewarderMergeOption?: {
+        merge_routers: any;
+        slippage: number;
+        not_merge_coins: string[];
+    }, tx?: Transaction): Promise<{
+        coin_a: any;
+        coin_b: any;
+    }>;
+    /**
+     * 仅构建 claim + merge + transfer 的独立交易：
+     * 适用于“先把奖励统一换成目标币并提现”场景，不含加仓行为。
+     */
+    createClaimMergePayload(params: CreateClaimMergePayloadParams): Promise<Transaction>;
+    /**
+     * 复投主流程（不迁仓）：
+     * - 先 claim + 可选 merge；
+     * - 若 rebalance 需要 swap，则在 tx 内先完成路由兑换；
+     * - 最后按 rebalance 计算结果 addLiquidity 回原仓位。
+     */
+    createCompoundRebalanceAddPayload(params: CreateCompoundRebalanceAddPayload): Promise<Transaction>;
+    /**
+     * 迁仓主流程（move position）：
+     * 1) 老仓位取回资产（可选是否已 claim）；
+     * 2) 按 rebalancePre 需要执行一次 swap；
+     * 3) 将资产按新 bin 区间 addLiquidity 到新仓位配置。
+     */
+    createMovePositionPayload(params: CreateMovePositionPayloadParams, tx?: Transaction): Promise<Transaction>;
+}
+
 /**
  * Represents options and configurations for an SDK.
  */
@@ -167,6 +673,7 @@ declare class CetusDlmmZapSDK extends SdkWrapper<SdkOptions> {
      * Module for managing vaults.
      */
     protected _zapModule: ZapModule;
+    protected _compoundModule: CompoundModule;
     protected _dlmmSDK: CetusDlmmSDK;
     /**
      * Client for interacting with the Aggregator service.
@@ -198,6 +705,7 @@ declare class CetusDlmmZapSDK extends SdkWrapper<SdkOptions> {
      * @returns {ZapModule} The ZapModule property value.
      */
     get Zap(): ZapModule;
+    get Compound(): CompoundModule;
     /**
      * Static factory method to initialize the SDK
      * @param options SDK initialization options
@@ -238,7 +746,7 @@ declare function calculateLiquidityAmountEnough(amount_a: string, amount_b: stri
     liquidity: string;
     amount_limit_a: string;
     amount_limit_b: string;
-    remain_amount: Decimal;
+    remain_amount: Decimal__default;
 };
 /**
  * Calculate the optimal side for adding liquidity based on current price and tick range
@@ -266,7 +774,7 @@ declare function calculateLiquidityAmountSide(amount_a: string, amount_b: string
     liquidity: string;
     amount_limit_a: string;
     amount_limit_b: string;
-    remain_amount: Decimal;
+    remain_amount: Decimal__default;
     fix_liquidity_amount_a: boolean;
 };
 /**
@@ -285,12 +793,75 @@ declare function calculateLiquidityAmountSide(amount_a: string, amount_b: string
  *   - final_amount_a: Final amount of token A (remaining A when fix_amount_a=true, obtained A when fix_amount_a=false)
  *   - final_amount_b: Final amount of token B (obtained B when fix_amount_a=true, remaining B when fix_amount_a=false)
  */
+/**
+ * Calculate the swap amount needed to adjust two coin balances to a target ratio.
+ *
+ * The function automatically determines whether to swap A→B or B→A based on
+ * the current balances and the target ratio, then binary-searches for the
+ * minimal swap size that brings the final B/A ratio within 0.1 % of `target_ratio`.
+ *
+ * @param amount_a      - Current amount of coin A
+ * @param amount_b      - Current amount of coin B
+ * @param current_price - Real exchange rate expressed as B/A (how many B per 1 A)
+ * @param target_ratio  - Desired final ratio expressed as B/A (final_b / final_a)
+ * @returns
+ *   - swap_amount:    Amount to swap (denominated in the source coin)
+ *   - final_amount_a: Final amount of coin A after the swap
+ *   - final_amount_b: Final amount of coin B after the swap
+ *   - a_to_b:         Swap direction – true = sell A for B, false = sell B for A
+ */
+declare function calcSwapAmountForTargetRatio(amount_a: string, amount_b: string, current_price: string, target_ratio: string): {
+    swap_amount: string;
+    final_amount_a: string;
+    final_amount_b: string;
+    a_to_b: boolean;
+};
 declare function calcExactSwapAmount(coin_amount: string, fix_amount_a: boolean, current_price: string, target_ratio: string): {
     swap_amount: string;
     final_amount_a: string;
     final_amount_b: string;
 };
 
+/**
+ * Calculate liquidity amounts with fallback strategy
+ * First tries to fix amount_a, if not enough then tries to fix amount_b
+ * @param current_sqrt_price - Current sqrt price of the pool
+ * @param tick_lower - Lower tick boundary of the position
+ * @param tick_upper - Upper tick boundary of the position
+ * @param amount_a - Amount of token A available
+ * @param amount_b - Amount of token B available
+ * @param slippage - Slippage tolerance for the calculation
+ * @returns Object containing:
+ *   - liquidity: Calculated liquidity amount
+ *   - use_amount_a: Amount of token A to be used
+ *   - use_amount_b: Amount of token B to be used
+ *   - amount_limit_a: Minimum amount limit for token A
+ *   - amount_limit_b: Minimum amount limit for token B
+ *   - fix_amount_a: Whether amount A was fixed (true) or amount B was fixed (false)
+ *   - remain_amount: Remaining amount of the non-fixed token
+ *   - is_enough_amount: Whether there was enough amount for the calculation
+ */
+declare function calculateLiquidityWithFallback({ current_sqrt_price, tick_lower, tick_upper, amount_a, amount_b, slippage }: {
+    current_sqrt_price: string;
+    tick_lower: number;
+    tick_upper: number;
+    amount_a: string;
+    amount_b: string;
+    slippage: number;
+}): {
+    liquidity: string;
+    use_amount_a: string;
+    use_amount_b: string;
+    amount_limit_a: string;
+    amount_limit_b: string;
+    fix_amount_a: boolean;
+    remain_amount: Decimal.Decimal;
+    is_enough_amount: boolean;
+};
+declare function isEmptyObj(obj: any): boolean;
+declare function isNotMergeCoin(not_merge_coins: string[], coin_type: string): boolean;
+declare function isSameType(coin_type1: string, coin_type2: string): boolean;
+
 declare const zapMainnet: SdkOptions;
 
 declare const zapTestnet: SdkOptions;
@@ -311,4 +882,4 @@ declare class ZapError extends BaseError {
 declare const handleError: (code: ZapErrorCode, error: Error, details?: Record<string, any>) => never;
 declare const handleMessageError: (code: ZapErrorCode, message: string, details?: Record<string, any>) => never;
 
-export { type BaseDepositOptions, type CalculationDepositResult, type CalculationWithdrawAvailableAmountOptions, type CalculationWithdrawOptions, type CalculationWithdrawResult, CetusDlmmZapSDK, type DepositOptions, type OnlyCoinDepositOptions, type SdkOptions, type SwapResult, type WithdrawMode, type WithdrawOptions, ZapError, ZapErrorCode, ZapModule, calcExactSwapAmount, calculateLiquidityAmountEnough, calculateLiquidityAmountSide, CetusDlmmZapSDK as default, defaultSwapSlippage, handleError, handleMessageError, zapMainnet, zapTestnet };
+export { type BaseDepositOptions, type CalculateClaimMergeParams, type CalculateRebalanceParams, type CalculationDepositResult, type CalculationWithdrawAvailableAmountOptions, type CalculationWithdrawOptions, type CalculationWithdrawResult, CetusDlmmZapSDK, type ClosePosOnlyReturnAmountCoinsParams, type ClosePosReturnAmountCoinAParams, type CollectFeeAndRewardsAndReturnCoinsParams, CompoundModule, type CreateClaimMergePayloadParams, type CreateCompoundRebalanceAddPayload, type CreateMovePositionPayloadParams, type DepositOptions, type OnlyCoinDepositOptions, type PreSwapParams, type RebalanceResult, type SdkOptions, type SwapResult, type WithdrawMode, type WithdrawOptions, ZapError, ZapErrorCode, ZapModule, calcExactSwapAmount, calcSwapAmountForTargetRatio, calculateLiquidityAmountEnough, calculateLiquidityAmountSide, calculateLiquidityWithFallback, CetusDlmmZapSDK as default, defaultSwapSlippage, handleError, handleMessageError, isEmptyObj, isNotMergeCoin, isSameType, zapMainnet, zapTestnet };