@cetusprotocol/dlmm-zap-sdk 0.0.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+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 in DLMM (Dynamic Liquidity Market Maker) pools.
 
 ## Getting Started
 
@@ -21,7 +21,7 @@ npm install @cetusprotocol/zap-sdk
 Import the SDK into the TypeScript file where you intend to use it:
 
 ```typescript
-import { CetusZapSDK } from '@cetusprotocol/zap-sdk'
+import { CetusDlmmZapSDK } from '@cetusprotocol/zap-sdk'
 ```
 
 ### Initializing the SDK
@@ -31,7 +31,7 @@ Initialize the SDK with the required configuration parameters. This typically in
 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()
+const sdk = CetusDlmmZapSDK.createSDK({ env: 'mainnet' })
 ```
 
 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:
@@ -39,17 +39,14 @@ If you wish to set your own full node URL or network (You have the option to sel
 ```typescript
 const env = 'mainnet'
 const full_rpc_url = 'YOUR_FULL_NODE_URL'
-const wallet = 'YOUR_WALLET_ADDRESS'
 
-const sdk = CetusZapSDK.createSDK({ env })
+const sdk = CetusDlmmZapSDK.createSDK({ env, full_rpc_url })
 ```
 
-If you wish to set your own full node URL or SuiClient, you can do so as follows:
+If you wish to set your own SuiClient, you can do so as follows:
 
 ```typescript
-const sdk = CetusZapSDK.createSDK({ env, sui_client })
-// or
-const sdk = CetusZapSDK.createSDK({ env, full_rpc_url })
+const sdk = CetusDlmmZapSDK.createSDK({ env, sui_client })
 ```
 
 ## Usage
@@ -73,74 +70,146 @@ 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
+- `lower_bin_id` & `upper_bin_id`: Bin ID range boundaries for the position
+- `active_id`: Current active bin ID of the pool
+- `bin_step`: The bin step size of the pool
+- `strategy_type`: Strategy type for the position (e.g., `StrategyType.Spot`)
 - `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
+- `active_bin_of_pool`: Information about the active bin if it's within the position range
 
 ### 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)
+**OnlyCoinA/OnlyCoinB Mode**
 
-   - `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
+- `fix_amount_a`: Boolean indicating whether to fix coin A (true) or coin B (false)
+- `coin_amount`: Amount of single coin to deposit
 
 #### Deposit Usage Example
 
+**Create New Position**
+
 ```typescript
+import { CetusDlmmZapSDK } from '@cetusprotocol/zap-sdk'
+import { StrategyType, toDecimalsAmount } from '@cetusprotocol/common-sdk'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+
 // Initialize SDK and get pool information
-const sdk = CetusZapSDK.createSDK({ env: 'mainnet' })
+const sdk = CetusDlmmZapSDK.createSDK({ env: 'mainnet' })
+const wallet = 'YOUR_WALLET_ADDRESS'
+sdk.setSenderAddress(wallet)
 
 const pool_id = 'YOUR_POOL_ID'
-const pool = await sdk.CetusClmmSDK.Pool.getPool(pool_id)
+const pool = await sdk.DlmmSDK.Pool.getPool(pool_id)
 
-// Pre-calculate deposit amounts (example: FixedOneSide mode)
+if (!pool) {
+  throw new Error('Pool not found')
+}
+
+const { active_id, bin_step, bin_manager } = pool
+
+// Define your position range
+const lower_bin_id = active_id
+const upper_bin_id = active_id + 2
+
+// Get active bin information if it's within range
+const amounts_in_active_bin = await sdk.DlmmSDK.Position.getActiveBinIfInRange(
+  bin_manager.bin_manager_handle,
+  lower_bin_id,
+  upper_bin_id,
+  active_id,
+  bin_step
+)
+
+// Pre-calculate deposit amounts (OnlyCoinB mode)
 const result = await sdk.Zap.preCalculateDepositAmount(
   {
     pool_id,
-    tick_lower,
-    tick_upper,
-    current_sqrt_price: pool.current_sqrt_price.toString(),
-    slippage: 0.01,
+    strategy_type: StrategyType.Spot,
+    active_bin_of_pool: amounts_in_active_bin,
+    lower_bin_id,
+    upper_bin_id,
+    active_id: pool.active_id,
+    bin_step: pool.bin_step,
   },
   {
-    mode: 'FixedOneSide',
-    fixed_amount: toDecimalsAmount(1, 6).toString(),
-    fixed_coin_a: false,
+    fix_amount_a: false, // false means fix coin B
+    coin_amount: toDecimalsAmount(0.1, 9).toString(), // Amount of coin B
   }
 )
 
+// Build transaction
+const tx = await sdk.Zap.buildDepositPayload({
+  deposit_obj: result,
+  pool_id,
+  strategy_type: StrategyType.Spot,
+  lower_bin_id,
+  upper_bin_id,
+  active_id: pool.active_id,
+  bin_step: pool.bin_step,
+  slippage: 0.01,
+})
+
+// Execute the transaction
+// Note: send_key_pair should be your wallet's keypair or signer
+// For example: const send_key_pair = new Ed25519Keypair(...)
+const res = await sdk.FullClient.executeTx(send_key_pair, tx, false)
+```
+
+**Add Liquidity to Existing Position**
+
+```typescript
 const pos_id = 'YOUR_POSITION_ID'
-// Build and send transaction
+const position = await sdk.DlmmSDK.Position.getPosition(pos_id)
+const { lower_bin_id, upper_bin_id } = position
+
+// Get active bin information if it's within range
+const amounts_in_active_bin = await sdk.DlmmSDK.Position.getActiveBinIfInRange(
+  bin_manager.bin_manager_handle,
+  lower_bin_id,
+  upper_bin_id,
+  active_id,
+  bin_step
+)
+
+const result = await sdk.Zap.preCalculateDepositAmount(
+  {
+    pool_id,
+    strategy_type: StrategyType.Spot,
+    active_bin_of_pool: amounts_in_active_bin,
+    lower_bin_id,
+    upper_bin_id,
+    active_id: pool.active_id,
+    bin_step: pool.bin_step,
+  },
+  {
+    fix_amount_a: true, // true means fix coin A
+    coin_amount: toDecimalsAmount(0.5, 6).toString(), // Amount of coin A
+  }
+)
+
+// Build transaction with position object
 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,
+  strategy_type: StrategyType.Spot,
+  lower_bin_id,
+  upper_bin_id,
+  active_id: pool.active_id,
+  bin_step: pool.bin_step,
   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)
+// Execute the transaction
+// Note: send_key_pair should be your wallet's keypair or signer
+const res = await sdk.FullClient.executeTx(send_key_pair, tx, false)
 ```
 
 ### 2. Withdraw Operations
@@ -149,58 +218,160 @@ Withdrawals require an existing position in the pool.
 
 #### Withdraw Mode-Specific Parameters
 
-1. **FixedOneSide**
+1. **OnlyCoinA/OnlyCoinB**
 
-   - `fixed_amount`: Fixed amount to withdraw
-   - `fixed_coin_a`: Boolean indicating whether to withdraw coin A (true) or coin B (false)
+   - `expected_receive_amount`: Expected amount to receive
+   - `is_receive_coin_a`: Boolean indicating whether to receive coin A (true) or coin B (false)
+   - `mode`: Withdrawal mode - `'OnlyCoinA'`, `'OnlyCoinB'`, or `'Both'`
 
-2. **OnlyCoinA/OnlyCoinB**
-   - `burn_liquidity`: Amount of liquidity to burn
-   - `available_liquidity`: Total available liquidity in the position
+2. **Both**
+   - `expected_receive_amount`: Expected amount to receive (will be split between both coins)
+   - `is_receive_coin_a`: Boolean indicating which coin the expected amount refers to
+   - `mode`: Set to `'Both'`
 
 #### Withdraw Usage Example
 
+**Calculate Available Withdraw Amount**
+
 ```typescript
+import { parseLiquidityShares } from '@cetusprotocol/dlmm-sdk'
+
+const pool_id = 'YOUR_POOL_ID'
+const pos_id = 'YOUR_POSITION_ID'
+
 // Get pool and position information
-const pool = await sdk.CetusClmmSDK.Pool.getPool(pool_id)
-const position = await sdk.CetusClmmSDK.Position.getPositionById(pos_id)
+const pool = await sdk.DlmmSDK.Pool.getPool(pool_id)
+const position = await sdk.DlmmSDK.Position.getPosition(pos_id)
 
 if (!pool || !position) {
   throw new Error('Pool or Position not found')
 }
 
-// Pre-calculate withdrawal (example: OnlyCoinA mode)
+const { bin_step, bin_manager, active_id } = pool
+const { lower_bin_id, liquidity_shares } = position
+
+// Get active bin information
+const active_bin = await sdk.DlmmSDK.Pool.getBinInfo(
+  bin_manager.bin_manager_handle,
+  active_id,
+  bin_step
+)
+
+// Parse liquidity shares to get bin range
+const liquidity_shares_data = parseLiquidityShares(
+  liquidity_shares,
+  bin_step,
+  lower_bin_id,
+  active_bin
+)
+
+// Calculate available withdraw amount
+const available_obj = sdk.Zap.calculateZapOutAvailableAmount({
+  remove_bin_range: liquidity_shares_data.bins,
+  active_id,
+  bin_step,
+  is_receive_coin_a: false, // Receive coin B
+  mode: 'OnlyCoinB',
+})
+
+console.log('Available withdraw amount:', available_obj)
+```
+
+**Withdraw in OnlyCoinB Mode**
+
+```typescript
+import { toDecimalsAmount } from '@cetusprotocol/common-sdk'
+
+const { coin_type_a, coin_type_b, bin_step, bin_manager, active_id, reward_manager } = pool
+const slippage = 0.01
+const is_receive_coin_a = false
+const expected_receive_amount = toDecimalsAmount(0.05, 9).toString() // Amount of coin B
+const mode = 'OnlyCoinB'
+
+// Get active bin and parse liquidity shares
+const active_bin = await sdk.DlmmSDK.Pool.getBinInfo(
+  bin_manager.bin_manager_handle,
+  active_id,
+  bin_step
+)
+const liquidity_shares_data = parseLiquidityShares(
+  liquidity_shares,
+  bin_step,
+  lower_bin_id,
+  active_bin
+)
+
+// Pre-calculate withdrawal
 const result = await sdk.Zap.preCalculateWithdrawAmount({
-  mode: 'OnlyCoinA',
+  remove_bin_range: liquidity_shares_data.bins,
+  active_id,
+  bin_step,
+  expected_receive_amount,
+  is_receive_coin_a,
+  mode,
+  coin_type_a,
+  coin_type_b,
+})
+
+// Build transaction
+const tx = await sdk.Zap.buildWithdrawPayload({
+  withdraw_obj: result,
+  swap_slippage: 0.01,
   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,
+  position_id: pos_id,
+  active_id,
+  bin_step,
+  slippage,
+  reward_coins: reward_manager.rewards.map((reward) => reward.reward_coin),
+  collect_fee: true,
+  remove_percent: Number(result.remove_percent),
+  coin_type_a,
+  coin_type_b,
+  is_close_position: false, // Set to true to close the position
+})
+
+// Execute the transaction
+// Note: send_key_pair should be your wallet's keypair or signer
+const res = await sdk.FullClient.executeTx(send_key_pair, tx, false)
+```
+
+**Withdraw in Both Mode**
+
+```typescript
+const mode = 'Both'
+const expected_receive_amount = toDecimalsAmount(0.05, 9).toString()
+const is_receive_coin_a = false
+
+const result = await sdk.Zap.preCalculateWithdrawAmount({
+  remove_bin_range: liquidity_shares_data.bins,
+  active_id,
+  bin_step,
+  expected_receive_amount,
+  is_receive_coin_a,
+  mode,
+  coin_type_a,
+  coin_type_b,
 })
 
-// Build and send transaction
 const tx = await sdk.Zap.buildWithdrawPayload({
   withdraw_obj: result,
+  swap_slippage: 0.01,
   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,
+  position_id: pos_id,
+  active_id,
+  bin_step,
+  slippage,
+  reward_coins: reward_manager.rewards.map((reward) => reward.reward_coin),
+  collect_fee: true,
+  remove_percent: Number(result.remove_percent),
+  coin_type_a,
+  coin_type_b,
+  is_close_position: true, // Close the position
 })
 
-// Simulate or send the transaction
-const simulate_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
+// Execute the transaction
+// Note: send_key_pair should be your wallet's keypair or signer
+const res = await sdk.FullClient.executeTx(send_key_pair, tx, false)
 ```
 
 ## More About Cetus

package/dist/index.d.mts

@@ -81,6 +81,12 @@ type CalculationWithdrawOptions = {
     expected_receive_amount: string;
     is_receive_coin_a: boolean;
     mode: WithdrawMode;
+    coin_decimal_a: number;
+    coin_decimal_b: number;
+    prices?: {
+        coin_a_price: string;
+        coin_b_price: string;
+    };
 } & CoinPairType;
 type CalculationWithdrawAvailableAmountOptions = {
     remove_bin_range: BinAmount[];
@@ -88,6 +94,12 @@ type CalculationWithdrawAvailableAmountOptions = {
     bin_step: number;
     is_receive_coin_a: boolean;
     mode: WithdrawMode;
+    coin_decimal_a: number;
+    coin_decimal_b: number;
+    prices?: {
+        coin_a_price: string;
+        coin_b_price: string;
+    };
 };
 /**
  * Result of a withdrawal calculation

package/dist/index.d.ts

@@ -81,6 +81,12 @@ type CalculationWithdrawOptions = {
     expected_receive_amount: string;
     is_receive_coin_a: boolean;
     mode: WithdrawMode;
+    coin_decimal_a: number;
+    coin_decimal_b: number;
+    prices?: {
+        coin_a_price: string;
+        coin_b_price: string;
+    };
 } & CoinPairType;
 type CalculationWithdrawAvailableAmountOptions = {
     remove_bin_range: BinAmount[];
@@ -88,6 +94,12 @@ type CalculationWithdrawAvailableAmountOptions = {
     bin_step: number;
     is_receive_coin_a: boolean;
     mode: WithdrawMode;
+    coin_decimal_a: number;
+    coin_decimal_b: number;
+    prices?: {
+        coin_a_price: string;
+        coin_b_price: string;
+    };
 };
 /**
  * Result of a withdrawal calculation