@cetusprotocol/dlmm-sdk 0.0.5 → 0.0.7

package/README.md

@@ -2,6 +2,16 @@
 
 The SDK provides a DLMM (Dynamic Liquidity Market Maker) 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.
 
+## Features
+
+- **Multiple Liquidity Strategies**: Spot, BidAsk, and Curve strategies for different trading approaches
+- **Comprehensive Pool Management**: Create, query, and manage DLMM pools
+- **Advanced Position Management**: Add/remove liquidity, collect fees and rewards
+- **Flexible Swap Operations**: Support for both A-to-B and B-to-A swaps
+- **Partner Integration**: Built-in partner and referral system
+- **Rich Utility Functions**: Bin calculations, price conversions, and liquidity management tools
+- **Multi-Network Support**: Works with both mainnet and testnet
+
 ## Getting Started
 
 ## How to Use the DLMM SDK?
@@ -26,27 +36,34 @@ import { CetusDlmmSDK } from '@cetusprotocol/dlmm-sdk'
 
 Initialize the SDK with the required configuration parameters. This typically includes setting up the network if needed.
 
-If you would like to use the mainnet network and the official Sui rpc url, you can do so as follows:
-
+**Option 1: Use default mainnet configuration**
 ```typescript
 const sdk = CetusDlmmSDK.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:
-
+**Option 2: Specify network environment**
 ```typescript
-const env = 'mainnet'
-const full_rpc_url = 'YOUR_FULL_NODE_URL'
+// For mainnet
+const sdk = CetusDlmmSDK.createSDK({ env: 'mainnet' })
 
-const sdk = CetusDlmmSDK.createSDK({ env })
+// For testnet
+const sdk = CetusDlmmSDK.createSDK({ env: 'testnet' })
 ```
 
-If you wish to set your own full node URL or SuiClient, you can do so as follows:
+**Option 3: Use custom RPC URL**
+```typescript
+const sdk = CetusDlmmSDK.createSDK({ 
+  env: 'mainnet',
+  full_rpc_url: 'YOUR_FULL_NODE_URL' 
+})
+```
 
+**Option 4: Use custom SuiClient**
 ```typescript
-const sdk = CetusDlmmSDK.createSDK({ env, sui_client })
-// or
-const sdk = CetusDlmmSDK.createSDK({ env, full_rpc_url })
+import { SuiClient } from '@mysten/sui/client'
+
+const suiClient = new SuiClient({ url: 'YOUR_RPC_URL' })
+const sdk = CetusDlmmSDK.createSDK({ env: 'mainnet', sui_client: suiClient })
 ```
 
 ## Usage
@@ -55,15 +72,13 @@ After linking your wallet, if you need use your wallet address to do something,
 
 ```typescript
 const wallet = 'YOUR_WALLET_ADDRESS'
-
 sdk.setSenderAddress(wallet)
 ```
 
-if you need to change your rpc url, you can do so as follows:
+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)
 ```
 
@@ -75,6 +90,53 @@ sdk.updateFullRpcUrl(new_rpc_url)
 - `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
 
+### Default Fee Options
+
+The SDK provides predefined fee configurations for different types of trading pairs. These configurations are optimized based on asset volatility and market characteristics:
+
+```typescript
+const dlmmDefaultFeeOptions = [
+  { binStep: 1, baseFactor: 10000, fee: '0.0001' },
+  { binStep: 1, baseFactor: 20000, fee: '0.0002' },
+  { binStep: 2, baseFactor: 15000, fee: '0.0003' },
+  { binStep: 2, baseFactor: 20000, fee: '0.0004' },
+  { binStep: 5, baseFactor: 10000, fee: '0.0005' },
+  { binStep: 10, baseFactor: 10000, fee: '0.001' },
+  { binStep: 15, baseFactor: 10000, fee: '0.0015' },
+  { binStep: 20, baseFactor: 10000, fee: '0.002' },
+  { binStep: 25, baseFactor: 10000, fee: '0.0025' },
+  { binStep: 30, baseFactor: 10000, fee: '0.003' },
+  { binStep: 50, baseFactor: 8000, fee: '0.004' },
+  { binStep: 80, baseFactor: 7500, fee: '0.006' },
+  { binStep: 100, baseFactor: 8000, fee: '0.008' },
+  { binStep: 100, baseFactor: 10000, fee: '0.01' },
+  { binStep: 200, baseFactor: 10000, fee: '0.02' },
+  { binStep: 400, baseFactor: 10000, fee: '0.04' }
+]
+```
+
+**Parameter Explanations:**
+
+- **`binStep`**: The step size between bins, determining the price granularity of the pool. Smaller values provide finer price resolution but require more computational resources.
+- **`baseFactor`**: A multiplier used in fee calculations, affecting the overall fee structure of the pool.
+- **`fee`**: The trading fee rate as a decimal (e.g., '0.0001' = 0.01%). This is the fee charged for each swap transaction.
+
+**Fee Tier Recommendations:**
+
+- **Low fees (0.01% - 0.05%)**: Best for stable pairs or low-volatility mainstream assets
+- **Medium fees (0.1% - 0.3%)**: Suitable for medium-volatility assets or mainstream trading pairs
+- **High fees (0.4% - 4%)**: Recommended for high-volatility assets, altcoins, or small market cap pairs
+
+When creating a new pool, choose the fee configuration that best matches your trading pair's characteristics:
+
+```typescript
+// Example: Create a pool for a stable pair (USDC/USDT)
+const stablePairConfig = { binStep: 1, baseFactor: 10000, fee: '0.0001' }
+
+// Example: Create a pool for a volatile altcoin pair
+const altcoinConfig = { binStep: 100, baseFactor: 10000, fee: '0.01' }
+```
+
 ### 1. Pool Operations
 
 #### Get Pool Information
@@ -201,27 +263,25 @@ const { feeData, rewardData } = await sdk.Position.fetchPositionFeeAndReward([
   },
 ])
 
-// feeData structure
-// {
-//   [position_id]: {
-//     position_id: string,
-//     fee_owned_a: string,  // Amount of token A fees owned
-//     fee_owned_b: string   // Amount of token B fees owned
-//   }
-// }
+```
+
+#### Fee Rate Calculations
 
-// rewardData structure
-// {
-//   [position_id]: {
-//     position_id: string,
-//     rewards: {
-//       [coin_type]: string  // Amount of reward tokens owned
-//     }
-//   }
-// }
+```typescript
+// Get total fee rate for a pool
+const totalFeeRate = await sdk.Pool.getTotalFeeRate({
+  pool_id,
+  coin_type_a,
+  coin_type_b
+})
+
+// Get variable fee from pool parameters
+const variableFee = FeeUtils.getVariableFee(pool.variable_parameters)
+console.log('Variable fee:', variableFee)
+console.log('Variable fee percentage:', d(variableFee).div(d(FEE_PRECISION)).toString())
 ```
 
-#### Fee Collection
+#### Fee and Reward Collection
 
 You can collect fees from your positions in several ways:
 
@@ -236,6 +296,18 @@ const tx = await sdk.Position.collectRewardAndFeePayload([{
   coin_type_b
 }])
 
+// Simulate or send the transaction
+const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
+```
+2. **Collect Partner ref fee**:
+```typescript
+// Build collect fee and reward transaction
+const tx = await sdk.Position.claimRefFeePayload({
+  partner_id: "0x..",
+  partner_cap_id: "0x..", // Optional parameter
+  fee_coin_types: [coin_type]
+})
+
 // Simulate or send the transaction
 const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
 ```
@@ -244,6 +316,174 @@ const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
 
 #### Add Liquidity
 
+The DLMM SDK provides two main methods for adding liquidity:
+
+1. **`calculateAddLiquidityInfo(option)`** - Calculates the liquidity distribution across bins
+2. **`addLiquidityPayload(option, tx?)`** - Creates the transaction payload for adding liquidity
+
+**Method 1: `calculateAddLiquidityInfo(option: CalculateAddLiquidityOption | CalculateAddLiquidityAutoFillOption)`**
+
+This method calculates how liquidity should be distributed across different bins based on your strategy and parameters.
+
+**Parameters for `CalculateAddLiquidityOption`:**
+```typescript
+interface CalculateAddLiquidityOption {
+  pool_id: string                    // Pool ID
+  amount_a: string                   // Amount of token A to add
+  amount_b: string                   // Amount of token B to add
+  active_id: number                  // Current active bin ID
+  bin_step: number                   // Bin step size
+  lower_bin_id: number               // Lower bound of bin range
+  upper_bin_id: number               // Upper bound of bin range
+  active_bin_of_pool?: {             // Active bin amounts (if active bin is in range)
+    amount_a: string
+    amount_b: string
+  }
+  strategy_type: StrategyType        // Liquidity strategy (Spot, BidAsk, Curve)
+}
+```
+
+**Parameters for `CalculateAddLiquidityAutoFillOption`:**
+```typescript
+interface CalculateAddLiquidityAutoFillOption {
+  pool_id: string                    // Pool ID
+  coin_amount: string                // Fixed amount of one token
+  fix_amount_a: boolean              // true for token A, false for token B
+  active_id: number                  // Current active bin ID
+  bin_step: number                   // Bin step size
+  lower_bin_id: number               // Lower bound of bin range
+  upper_bin_id: number               // Upper bound of bin range
+  active_bin_of_pool?: {             // Active bin amounts (if active bin is in range)
+    amount_a: string
+    amount_b: string
+  }
+  strategy_type: StrategyType        // Liquidity strategy (Spot, BidAsk, Curve)
+}
+```
+
+**Method 2: `addLiquidityPayload(option: AddLiquidityOption | OpenAndAddLiquidityOption, tx?: Transaction)`**
+
+This method creates the transaction payload for adding liquidity to an existing position or opening a new position.
+
+**Parameters for `AddLiquidityOption` (existing position):**
+```typescript
+interface AddLiquidityOption {
+  pool_id: string                    // Pool ID
+  bin_infos: BinLiquidityInfo        // Calculated bin distribution from calculateAddLiquidityInfo
+  coin_type_a: string                // Token A coin type
+  coin_type_b: string                // Token B coin type
+  active_id: number                  // Current active bin ID
+  position_id: string                // Existing position ID
+  collect_fee: boolean               // Whether to collect fees
+  reward_coins: string[]             // Reward coin types
+  strategy_type: StrategyType        // Liquidity strategy
+  use_bin_infos: boolean             // Whether to use calculated bin_infos
+  max_price_slippage: number         // Maximum price slippage tolerance
+  bin_step: number                   // Bin step size
+}
+```
+
+**Parameters for `OpenAndAddLiquidityOption` (new position):**
+```typescript
+interface OpenAndAddLiquidityOption {
+  pool_id: string                    // Pool ID
+  bin_infos: BinLiquidityInfo        // Calculated bin distribution from calculateAddLiquidityInfo
+  coin_type_a: string                // Token A coin type
+  coin_type_b: string                // Token B coin type
+  lower_bin_id: number               // Lower bound of bin range
+  upper_bin_id: number               // Upper bound of bin range
+  active_id: number                  // Current active bin ID
+  strategy_type: StrategyType        // Liquidity strategy
+  use_bin_infos: boolean             // Whether to use calculated bin_infos
+  max_price_slippage: number         // Maximum price slippage tolerance
+  bin_step: number                   // Bin step size
+}
+```
+
+**Complete Example - Adding Liquidity to Existing Position:**
+
+```typescript
+// Step 1: Calculate liquidity distribution
+const calculateOption: CalculateAddLiquidityOption = {
+  pool_id: '0x...',
+  amount_a: '1000000',
+  amount_b: '1200000',
+  active_id: 100,
+  bin_step: 2,
+  lower_bin_id: 90,
+  upper_bin_id: 110,
+  active_bin_of_pool: amounts_in_active_bin, // Optional: if active bin is in range
+  strategy_type: StrategyType.Spot
+}
+
+const bin_infos = await sdk.Position.calculateAddLiquidityInfo(calculateOption)
+
+// Step 2: Create transaction payload
+const addLiquidityOption: AddLiquidityOption = {
+  pool_id: '0x...',
+  bin_infos: bin_infos,
+  coin_type_a: '0x...::usdc::USDC',
+  coin_type_b: '0x...::usdt::USDT',
+  active_id: 100,
+  position_id: '0x...',
+  collect_fee: true,
+  reward_coins: [],
+  strategy_type: StrategyType.Spot,
+  use_bin_infos: false,
+  max_price_slippage: 0.01,
+  bin_step: 2
+}
+
+const tx = sdk.Position.addLiquidityPayload(addLiquidityOption)
+```
+
+**Complete Example - Opening New Position:**
+
+```typescript
+// Step 1: Calculate liquidity distribution
+const calculateOption: CalculateAddLiquidityOption = {
+  pool_id: '0x...',
+  amount_a: '1000000',
+  amount_b: '1200000',
+  active_id: 100,
+  bin_step: 2,
+  lower_bin_id: 90,
+  upper_bin_id: 110,
+  active_bin_of_pool: amounts_in_active_bin,
+  strategy_type: StrategyType.Spot
+}
+
+const bin_infos = await sdk.Position.calculateAddLiquidityInfo(calculateOption)
+
+// Step 2: Create transaction payload for new position
+const openPositionOption: OpenAndAddLiquidityOption = {
+  pool_id: '0x...',
+  bin_infos: bin_infos,
+  coin_type_a: '0x...::usdc::USDC',
+  coin_type_b: '0x...::usdt::USDT',
+  lower_bin_id: 90,
+  upper_bin_id: 110,
+  active_id: 100,
+  strategy_type: StrategyType.Spot,
+  use_bin_infos: false,
+  max_price_slippage: 0.01,
+  bin_step: 2
+}
+
+const tx = sdk.Position.addLiquidityPayload(openPositionOption)
+```
+
+**Important Parameter Notes:**
+
+- **`active_bin_of_pool`**: This parameter is crucial when the active bin falls within your position's range. Use `getActiveBinIfInRange()` to get the correct values.
+- **`use_bin_infos`**: When `false`, the contract calculates liquidity distribution internally; when `true`, it uses the provided `bin_infos`.
+- **`max_price_slippage`**: Protects against price movements during transaction execution (e.g., 0.01 = 1% slippage tolerance).
+- **`collect_fee`**: Only applicable for existing positions; determines whether to collect accumulated fees when adding liquidity.
+- **`strategy_type`**: Affects how liquidity is distributed across bins:
+  - `Spot`: Even distribution around current price
+  - `BidAsk`: Concentrated at specific price levels
+  - `Curve`: Smooth distribution following a curve
+
 There are three strategies for adding liquidity: Spot, BidAsk, and Curve. Here's how to use each:
 
 1. **Spot Strategy**:
@@ -263,6 +503,7 @@ const amounts_in_active_bin = await sdk.Position.getActiveBinIfInRange(
 
 // Calculate liquidity distribution
 const calculateOption = {
+  pool_id,
   amount_a: '1000000',
   amount_b: '1200000',
   active_id,
@@ -273,30 +514,36 @@ const calculateOption = {
   amount_b_in_active_bin: amounts_in_active_bin?.amount_b || '0',
   strategy_type: StrategyType.Spot
 }
-const bin_infos = sdk.Position.calculateAddLiquidityInfo(calculateOption)
+const bin_infos = await sdk.Position.calculateAddLiquidityInfo(calculateOption)
 
 // For new position
 const addOption = {
   pool_id,
-  bin_infos,
-  coin_type_a: pool.coin_type_a,
-  coin_type_b: pool.coin_type_b,
-  lower_bin_id: -10,
-  upper_bin_id: 10,
-  active_id
+  amount_a,
+  amount_b,
+  active_id,
+  bin_step,
+  lower_bin_id,
+  upper_bin_id,
+  active_bin_of_pool: amounts_in_active_bin,
+  strategy_type: StrategyType.Spot,
 }
 const tx = sdk.Position.addLiquidityPayload(addOption)
 
 // For existing position
 const addOption = {
   pool_id,
-  bin_infos,
-  coin_type_a: pool.coin_type_a,
-  coin_type_b: pool.coin_type_b,
+  bin_infos: bin_infos,
+  coin_type_a,
+  coin_type_b,
   active_id,
   position_id,
   collect_fee: true,
-  reward_coins: []
+  reward_coins: [],
+  strategy_type: StrategyType.Spot,
+  use_bin_infos: false,
+  max_price_slippage: 0.01,
+  bin_step,
 }
 const tx = sdk.Position.addLiquidityPayload(addOption)
 ```
@@ -306,6 +553,8 @@ Note: The `amount_a_in_active_bin` and `amount_b_in_active_bin` parameters are u
 2. Returns the amounts of both tokens in the active bin if it is within range
 3. Returns undefined if the active bin is outside the range
 
+---
+
 2. **BidAsk Strategy**:
 ```typescript
 // Similar to Spot strategy but with different strategy_type
@@ -556,9 +805,31 @@ const whitelistTx = sdk.Reward.updateRewardWhiteListPayload({
 })
 ```
 
-### 8. Bin Operations
+### 8. Configuration Management
 
-The SDK provides utility functions for working with bins and prices through the `BinUtils` class:
+The SDK provides configuration management through the `Config` module:
+
+```typescript
+// Get global DLMM configuration
+const globalConfig = await sdk.Config.getDlmmGlobalConfig()
+
+// Get bin step configuration list
+const binStepConfigs = await sdk.Config.getBinStepConfigList(pool_id)
+
+// Fetch all SDK configurations
+const sdkConfigs = await sdk.Config.fetchDlmmSdkConfigs()
+
+// Get reward period emission data
+const rewardEmission = await sdk.Reward.getRewardPeriodEmission(
+  reward_manager_id,
+  reward_period,
+  current_time
+)
+```
+
+### 9. Bin Operations
+
+The SDK provides comprehensive utility functions for working with bins and prices through the `BinUtils` class:
 
 ```typescript
 import { BinUtils } from '@cetusprotocol/dlmm-sdk'
@@ -598,15 +869,15 @@ const amountA = BinUtils.getAmountAFromLiquidity('4101094304427826916657468', '1
 // Get amount B from liquidity
 const amountB = BinUtils.getAmountBFromLiquidity('4919119455159831291232256')
 
-// Get amounts from liquidity with ratio
-const [amountA, amountB] = BinUtils.getAmountsFromLiquidityWithRatio(
-  '4510099798813469403250688',
-  '18446744073709551616',
-  0.9 // ratio
-)
 
 // Split bin liquidity info
 const split_bin_infos = BinUtils.splitBinLiquidityInfo(bin_infos, 0, 70)
+
+// Get position count between bin ranges
+const positionCount = BinUtils.getPositionCount(-750, 845)
+
+// Find min/max bin ID for a given bin step
+const { minBinId, maxBinId } = BinUtils.findMinMaxBinId(10)
 ```
 
 These utility functions are particularly useful when:
@@ -614,6 +885,7 @@ These utility functions are particularly useful when:
 - Calculating optimal bin ranges for trading strategies
 - Converting between different price representations
 - Managing liquidity distributions across bins
+- Analyzing position density and distribution
 
 ### 9. Advanced Operations
 
@@ -640,6 +912,73 @@ await sdk.Position.updatePositionFeeAndRewards({
 })
 ```
 
+## Troubleshooting
+
+### Common Issues
+
+**1. Transaction Simulation Failures**
+```typescript
+// Always simulate transactions before sending
+const simResult = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
+if (simResult.effects.status.status === 'failure') {
+  console.error('Transaction simulation failed:', simResult.effects.status.error)
+}
+```
+
+**2. Insufficient Gas Budget**
+```typescript
+// Set appropriate gas budget for complex operations
+tx.setGasBudget(10000000000) // 10 SUI
+```
+
+**3. Active Bin Range Validation**
+```typescript
+// Always check if active bin is within your position range
+const amounts_in_active_bin = await sdk.Position.getActiveBinIfInRange(
+  pool.bin_manager.bin_manager_handle,
+  lower_bin_id,
+  upper_bin_id,
+  active_id,
+  bin_step
+)
+```
+
+**4. Price Slippage Protection**
+```typescript
+// Use appropriate slippage protection
+const isValid = await sdk.Position.validateActiveIdSlippage({
+  pool_id,
+  active_id,
+  max_bin_slippage: 0.01 // 1% slippage tolerance
+})
+```
+
+### Debugging Tips
+
+**1. Print Transaction Details**
+```typescript
+import { printTransaction } from '@cetusprotocol/common-sdk'
+
+// Print transaction for debugging
+printTransaction(tx)
+```
+
+**2. Check Pool State**
+```typescript
+// Always verify pool state before operations
+const pool = await sdk.Pool.getPool(pool_id)
+console.log('Pool active_id:', pool.active_id)
+console.log('Pool bin_step:', pool.bin_step)
+```
+
+**3. Validate Position Data**
+```typescript
+// Parse and validate position liquidity shares
+const active_bin = await sdk.Pool.getBinInfo(pool.bin_manager.bin_manager_handle, pool.active_id, pool.bin_step)
+const liquidity_shares_data = parseLiquidityShares(position.liquidity_shares, pool.bin_step, position.lower_bin_id, active_bin)
+console.log('Liquidity shares data:', liquidity_shares_data)
+```
+
 ## More About Cetus
 
 Use the following links to learn more about Cetus: