@cetusprotocol/dlmm-zap-sdk 0.0.1

package/README.md

@@ -0,0 +1,216 @@
+# @cetusprotocol/zap-sdk
+
+The SDK provides a Zap module for specialized liquidity operations with different modes to suit various trading strategies. This module enables users to perform complex liquidity operations with flexibility in how they want to manage their positions.
+
+## Getting Started
+
+## How to Use the Zap SDK ?
+
+### Installation
+
+To start using the `Zap SDK`, you first need to install it in your TypeScript project:
+
+npm link: <https://www.npmjs.com/package/@cetusprotocol/zap-sdk>
+
+```bash
+npm install @cetusprotocol/zap-sdk
+```
+
+### Setup
+
+Import the SDK into the TypeScript file where you intend to use it:
+
+```typescript
+import { CetusZapSDK } from '@cetusprotocol/zap-sdk'
+```
+
+### Initializing the SDK
+
+Initialize the SDK with the required configuration parameters. This typically includes setting up the network and API keys, if needed.
+
+If you would like to use the mainnet network and the official Sui rpc url, you can do so as follows:
+
+```typescript
+const sdk = CetusZapSDK.createSDK()
+```
+
+If you wish to set your own full node URL or network (You have the option to select either 'mainnet' or 'testnet' for the network), you can do so as follows:
+
+```typescript
+const env = 'mainnet'
+const full_rpc_url = 'YOUR_FULL_NODE_URL'
+const wallet = 'YOUR_WALLET_ADDRESS'
+
+const sdk = CetusZapSDK.createSDK({ env })
+```
+
+If you wish to set your own full node URL or SuiClient, you can do so as follows:
+
+```typescript
+const sdk = CetusZapSDK.createSDK({ env, sui_client })
+// or
+const sdk = CetusZapSDK.createSDK({ env, full_rpc_url })
+```
+
+## Usage
+
+After linking your wallet, if you need use your wallet address to do something, you should set it by `sdk.setSenderAddress`.
+
+```typescript
+const wallet = 'YOUR_WALLET_ADDRESS'
+
+sdk.setSenderAddress(wallet)
+```
+
+if you need to change your rpc url, you can do so as follows:
+
+```typescript
+const new_rpc_url = 'YOUR_NEW_FULL_NODE_URL'
+
+sdk.updateFullRpcUrl(new_rpc_url)
+```
+
+### Common Parameters
+
+- `pool_id`: The ID of the liquidity pool
+- `tick_lower` & `tick_upper`: Price range boundaries for the position
+- `current_sqrt_price`: Current square root price of the pool
+- `slippage`: Maximum acceptable price slippage (e.g., 0.01 for 1%)
+- `coin_type_a` & `coin_type_b`: Coin type identifiers for the trading pair
+- `coin_decimal_a` & `coin_decimal_b`: Decimal places for each coin type
+
+### 1. Deposit Operations
+
+#### Deposit Mode-Specific Parameters
+
+1. **FixedOneSide**
+
+   - `fixed_amount`: Fixed amount to deposit
+   - `fixed_coin_a`: Boolean indicating whether to fix coin A (true) or coin B (false)
+
+2. **FlexibleBoth** (This feature will be supported in a future release, currently a placeholder)
+
+   - `coin_amount_a`: Amount of coin A to deposit
+   - `coin_amount_b`: Amount of coin B to deposit
+
+3. **OnlyCoinA/OnlyCoinB**
+   - `coin_amount`: Amount of single coin to deposit
+
+#### Deposit Usage Example
+
+```typescript
+// Initialize SDK and get pool information
+const sdk = CetusZapSDK.createSDK({ env: 'mainnet' })
+
+const pool_id = 'YOUR_POOL_ID'
+const pool = await sdk.CetusClmmSDK.Pool.getPool(pool_id)
+
+// Pre-calculate deposit amounts (example: FixedOneSide mode)
+const result = await sdk.Zap.preCalculateDepositAmount(
+  {
+    pool_id,
+    tick_lower,
+    tick_upper,
+    current_sqrt_price: pool.current_sqrt_price.toString(),
+    slippage: 0.01,
+  },
+  {
+    mode: 'FixedOneSide',
+    fixed_amount: toDecimalsAmount(1, 6).toString(),
+    fixed_coin_a: false,
+  }
+)
+
+const pos_id = 'YOUR_POSITION_ID'
+// Build and send transaction
+const tx = await sdk.Zap.buildDepositPayload({
+  deposit_obj: result,
+  pool_id,
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  tick_lower,
+  tick_upper,
+  slippage: 0.01,
+  pos_obj: {
+    // Optional: Add to existing position
+    pos_id,
+    collect_fee: false,
+    collect_rewarder_types: [],
+  },
+})
+
+// Simulate or send the transaction
+const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
+```
+
+### 2. Withdraw Operations
+
+Withdrawals require an existing position in the pool.
+
+#### Withdraw Mode-Specific Parameters
+
+1. **FixedOneSide**
+
+   - `fixed_amount`: Fixed amount to withdraw
+   - `fixed_coin_a`: Boolean indicating whether to withdraw coin A (true) or coin B (false)
+
+2. **OnlyCoinA/OnlyCoinB**
+   - `burn_liquidity`: Amount of liquidity to burn
+   - `available_liquidity`: Total available liquidity in the position
+
+#### Withdraw Usage Example
+
+```typescript
+// Get pool and position information
+const pool = await sdk.CetusClmmSDK.Pool.getPool(pool_id)
+const position = await sdk.CetusClmmSDK.Position.getPositionById(pos_id)
+
+if (!pool || !position) {
+  throw new Error('Pool or Position not found')
+}
+
+// Pre-calculate withdrawal (example: OnlyCoinA mode)
+const result = await sdk.Zap.preCalculateWithdrawAmount({
+  mode: 'OnlyCoinA',
+  pool_id,
+  tick_lower: position.tick_lower_index,
+  tick_upper: position.tick_upper_index,
+  current_sqrt_price: pool.current_sqrt_price.toString(),
+  burn_liquidity: '200000',
+  available_liquidity: position.liquidity.toString(),
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  coin_decimal_a: 6,
+  coin_decimal_b: 9,
+})
+
+// Build and send transaction
+const tx = await sdk.Zap.buildWithdrawPayload({
+  withdraw_obj: result,
+  pool_id,
+  pos_id,
+  close_pos: false, // Whether to close the position
+  collect_fee: true, // Whether to collect accumulated fees
+  collect_rewarder_types: [], // Types of rewards to collect
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  tick_lower: position.tick_lower_index,
+  tick_upper: position.tick_upper_index,
+  slippage: 0.01,
+})
+
+// Simulate or send the transaction
+const simulate_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
+```
+
+## More About Cetus
+
+Use the following links to learn more about Cetus:
+
+Learn more about working with Cetus in the [Cetus Documentation](https://cetus-1.gitbook.io/cetus-docs).
+
+Join the Cetus community on [Cetus Discord](https://discord.com/channels/1009749448022315008/1009751382783447072).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,319 @@
+import { AggregatorClient } from '@cetusprotocol/aggregator-sdk';
+import { StrategyType, BinAmount, BinLiquidityInfo, CetusDlmmSDK } from '@cetusprotocol/dlmm-sdk';
+import { IModule, SdkWrapper, BaseSdkOptions, BaseError } from '@cetusprotocol/common-sdk';
+import { TransactionObjectArgument, Transaction } from '@mysten/sui/transactions';
+import Decimal from 'decimal.js';
+
+/**
+ * Represents a pair of coins used in a financial context.
+ */
+type CoinPairType = {
+    /**
+     * The address type of the coin a in the pair.
+     */
+    coin_type_a: SuiAddressType;
+    /**
+     * The address type of the coin b in the pair.
+     */
+    coin_type_b: SuiAddressType;
+};
+
+/**
+ * Represents a SUI address, which is a string.
+ */
+type SuiAddressType = string;
+
+declare const defaultSwapSlippage = 0.005;
+/**
+ * Result of a swap operation containing amounts and price information
+ */
+type SwapResult = {
+    swap_in_amount: string;
+    swap_out_amount: string;
+    route_obj?: any;
+};
+type BaseDepositOptions = {
+    pool_id: string;
+    strategy_type: StrategyType;
+    active_bin_of_pool?: BinAmount;
+    lower_bin_id: number;
+    upper_bin_id: number;
+    active_id: number;
+    bin_step: number;
+};
+type OnlyCoinDepositOptions = {
+    fix_amount_a: boolean;
+    coin_amount: string;
+};
+/**
+ * Result of a deposit calculation
+ */
+type CalculationDepositResult = {
+    bin_infos: BinLiquidityInfo;
+    swap_result?: SwapResult;
+    fix_amount_a: boolean;
+    coin_amount: string;
+};
+/**
+ * Complete options for executing a deposit
+ */
+type DepositOptions = {
+    deposit_obj: CalculationDepositResult;
+    slippage: number;
+    pool_id: string;
+    strategy_type: StrategyType;
+    lower_bin_id: number;
+    upper_bin_id: number;
+    active_id: number;
+    bin_step: number;
+    swap_slippage?: number;
+    pos_obj?: {
+        pos_id: string | TransactionObjectArgument;
+        collect_fee: boolean;
+        collect_rewarder_types: string[];
+    };
+};
+type WithdrawMode = 'OnlyCoinA' | 'OnlyCoinB' | 'Both';
+type CalculationWithdrawOptions = {
+    remove_bin_range: BinAmount[];
+    active_id: number;
+    bin_step: number;
+    expected_receive_amount: string;
+    is_receive_coin_a: boolean;
+    mode: WithdrawMode;
+} & CoinPairType;
+type CalculationWithdrawAvailableAmountOptions = {
+    remove_bin_range: BinAmount[];
+    active_id: number;
+    bin_step: number;
+    is_receive_coin_a: boolean;
+    mode: WithdrawMode;
+};
+/**
+ * Result of a withdrawal calculation
+ */
+type CalculationWithdrawResult = {
+    remove_liquidity_info: BinLiquidityInfo;
+    mode: WithdrawMode;
+    is_receive_coin_a?: boolean;
+    swap_result?: SwapResult;
+    expected_receive_amount: string;
+    remove_percent: string;
+};
+/**
+ * Complete options for executing a withdrawal
+ */
+type WithdrawOptions = {
+    withdraw_obj: CalculationWithdrawResult;
+    swap_slippage?: number;
+    pool_id: string;
+    position_id: string;
+    active_id: number;
+    bin_step: number;
+    slippage: number;
+    reward_coins: string[];
+    collect_fee: boolean;
+    remove_percent?: number;
+    is_close_position: boolean;
+} & CoinPairType;
+
+/**
+ * ZapModule handles interactions with clmm pools within the system.
+ */
+declare class ZapModule implements IModule<CetusDlmmZapSDK> {
+    protected _sdk: CetusDlmmZapSDK;
+    constructor(sdk: CetusDlmmZapSDK);
+    /**
+     * Returns the associated SDK instance
+     */
+    get sdk(): CetusDlmmZapSDK;
+    private calculateBalanceSwapAmountWithoutActiveId;
+    private calculateBalanceSwapAmount;
+    /**
+     * Pre-calculates the deposit amount based on the selected mode.
+     * @param options
+     * @param mode_options
+     * @returns
+     */
+    preCalculateDepositAmount(options: BaseDepositOptions, mode_options: OnlyCoinDepositOptions): Promise<CalculationDepositResult>;
+    buildDepositPayload(options: DepositOptions, tx?: Transaction): Promise<Transaction>;
+    findRouters(from: string, target: string, amount: string): Promise<SwapResult>;
+    calculateZapOutAvailableAmount(options: CalculationWithdrawAvailableAmountOptions): {
+        available_amount: string;
+        user_total_amount_a: string;
+        user_total_amount_b: string;
+        active_bin: BinAmount | undefined;
+        is_receive_coin_a: boolean;
+    };
+    preCalculateWithdrawAmount(options: CalculationWithdrawOptions): Promise<CalculationWithdrawResult>;
+    buildWithdrawPayload(options: WithdrawOptions): Promise<Transaction>;
+}
+
+/**
+ * Represents options and configurations for an SDK.
+ */
+interface SdkOptions extends BaseSdkOptions {
+    /**
+     * The URL of the aggregator service.
+     */
+    aggregator_url: string;
+    /**
+     * A list of  aggregator providers.
+     */
+    providers: string[];
+    /**
+     * A list of Pyth price ID.
+     */
+    pyth_urls?: string[];
+}
+/**
+ * The entry class of CetusDlmmZapSDK, which is almost responsible for all interactions with dlmm zap.
+ */
+declare class CetusDlmmZapSDK extends SdkWrapper<SdkOptions> {
+    /**
+     * Module for managing vaults.
+     */
+    protected _zapModule: ZapModule;
+    protected _dlmmSDK: CetusDlmmSDK;
+    /**
+     * Client for interacting with the Aggregator service.
+     */
+    protected _aggregatorClient: AggregatorClient;
+    constructor(options: SdkOptions, dlmmSDK?: CetusDlmmSDK);
+    setSenderAddress(value: string): void;
+    getSenderAddress(validate?: boolean): string;
+    /**
+     * Updates the providers for the AggregatorClient.
+     * @param providers - The new providers to set.
+     */
+    updateProviders(providers: string[]): void;
+    updateFullRpcUrl(url: string): void;
+    /**
+     * Getter for the DlmmSDK property.
+     * @returns {CetusDlmmSDK} The DlmmSDK property value.
+     */
+    get DlmmSDK(): CetusDlmmSDK;
+    /**
+     * Getter for the AggregatorClient property.
+     * @returns {AggregatorClient} The AggregatorClient property value.
+     */
+    get AggregatorClient(): AggregatorClient;
+    /**
+     * Getter for the ZapModule property.
+     * @returns {ZapModule} The ZapModule property value.
+     */
+    get Zap(): ZapModule;
+    /**
+     * Static factory method to initialize the SDK
+     * @param options SDK initialization options
+     * @param clmm_sdk Optional CLMM SDK instance
+     * @returns An instance of CetusZapSDK
+     */
+    static createSDK(options: BaseSdkOptions, dlmm_sdk?: any): CetusDlmmZapSDK;
+    /**
+     * Create a custom SDK instance with the given options
+     * @param options The options for the SDK
+     * @returns An instance of CetusBurnSDK
+     */
+    static createCustomSDK<T extends BaseSdkOptions>(options: T & SdkOptions, dlmm_sdk?: CetusDlmmSDK): CetusDlmmZapSDK;
+}
+
+/**
+ * Calculate if there is enough liquidity amount for adding liquidity to a pool
+ * @param amount_a - Amount of token A
+ * @param amount_b - Amount of token B
+ * @param curr_sqrt_price - Current square root price of the pool
+ * @param lower_tick - Lower tick boundary of the position
+ * @param upper_tick - Upper tick boundary of the position
+ * @param slippage - Slippage tolerance for the calculation
+ * @param fix_amount_a - Whether to fix the amount of token A
+ * @returns Object containing:
+ *   - is_enough_amount: Whether there is enough amount for the other token
+ *   - use_amount_a: Amount of token A to be used
+ *   - use_amount_b: Amount of token B to be used
+ *   - liquidity: Calculated liquidity amount
+ *   - amount_limit_a: Minimum amount limit for token A
+ *   - amount_limit_b: Minimum amount limit for token B
+ *   - remain_amount: Remaining amount of the non-fixed token
+ */
+declare function calculateLiquidityAmountEnough(amount_a: string, amount_b: string, curr_sqrt_price: string, lower_tick: number, upper_tick: number, slippage: number, fix_amount_a: boolean): {
+    is_enough_amount: boolean;
+    use_amount_a: string;
+    use_amount_b: string;
+    liquidity: string;
+    amount_limit_a: string;
+    amount_limit_b: string;
+    remain_amount: Decimal;
+};
+/**
+ * Calculate the optimal side for adding liquidity based on current price and tick range
+ * @param amount_a - Amount of token A
+ * @param amount_b - Amount of token B
+ * @param curr_sqrt_price - Current square root price of the pool
+ * @param lower_tick - Lower tick boundary of the position
+ * @param upper_tick - Upper tick boundary of the position
+ * @param slippage - Slippage tolerance for the calculation
+ * @param fix_amount_a - Whether to fix the amount of token A
+ * @returns Object containing:
+ *   - fix_liquidity_amount_a: Whether to fix token A amount
+ *   - is_enough_amount: Whether there is enough amount for the other token
+ *   - use_amount_a: Amount of token A to be used
+ *   - use_amount_b: Amount of token B to be used
+ *   - liquidity: Calculated liquidity amount
+ *   - amount_limit_a: Minimum amount limit for token A
+ *   - amount_limit_b: Minimum amount limit for token B
+ *   - remain_amount: Remaining amount of the non-fixed token
+ */
+declare function calculateLiquidityAmountSide(amount_a: string, amount_b: string, curr_sqrt_price: string, lower_tick: number, upper_tick: number, slippage: number, fix_amount_a: boolean): {
+    is_enough_amount: boolean;
+    use_amount_a: string;
+    use_amount_b: string;
+    liquidity: string;
+    amount_limit_a: string;
+    amount_limit_b: string;
+    remain_amount: Decimal;
+    fix_liquidity_amount_a: boolean;
+};
+/**
+ * Calculate the swap amount needed to achieve target ratio
+ * @param coin_amount - Total coin amount available
+ * @param fix_amount_a - Whether to fix token A amount (true) or token B amount (false)
+ * @param current_price - Current price:
+ *   - When fix_amount_a = true: current_price = B/A (price of B in terms of A)
+ *   - When fix_amount_a = false: current_price = A/B (price of A in terms of B)
+ * @param target_ratio - Target ratio to achieve:
+ *   - When fix_amount_a = true: target_ratio = B/A
+ *   - When fix_amount_a = false: target_ratio = A/B
+ * @param tolerance - Tolerance for the target ratio (default: 0.01)
+ * @returns Object containing:
+ *   - swap_amount: Amount to swap
+ *   - 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)
+ */
+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;
+};
+
+declare const zapMainnet: SdkOptions;
+
+declare const zapTestnet: SdkOptions;
+
+declare enum ZapErrorCode {
+    UnsupportedDepositMode = "UnsupportedDepositMode",
+    PositionIdUndefined = "PositionIdUndefined",
+    ParameterError = "ParameterError",
+    ReachMaxIterations = "ReachMaxIterations",
+    BestLiquidityIsZero = "BestLiquidityIsZero",
+    SwapAmountError = "SwapAmountError",
+    AggregatorError = "AggregatorError"
+}
+declare class ZapError extends BaseError {
+    constructor(message: string, errorCode?: ZapErrorCode, details?: Record<string, any>);
+    static isZapErrorCode(e: any, code: ZapErrorCode): boolean;
+}
+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 };