@cetusprotocol/sui-clmm-sdk 1.0.0

package/docs/add_liquidity.md

@@ -0,0 +1,145 @@
+# Add liquidity
+
+Once you have set a suitable tick range, you can proceed to add liquidity to this position. The quantity composition of tokens you need to add is affected by the current price of the pool and the tick interval you have chosen.
+
+There are two situations:
+
+1. add liquidity with a specified liquidity
+2. add liquidity with fixed coin amount.
+
+## 1. add liquidity with a specified liquidity
+
+Use `sdk.Position.createAddLiquidityPayload()` method.
+
+### Function Parameters
+
+- `pool_id`: The object id about which pool you want to operation
+- `pos_id`: The object id about position.
+- `max_amount_a`: The max limit about used coin a amount.
+- `max_amount_b`: The max limit about used coin b amount.
+- `delta_liquidity`: The actual change in liquidity that has been added.
+- `tick_lower`: Represents the index of the lower tick boundary
+- `tick_upper`: Represents the index of the upper tick boundary
+- `collect_fee`: If you already has one position, you can select collect fees while adding liquidity.
+- `rewarder_coin_types`: If these not empty, it will collect rewarder in this position, if you already open the position.
+
+### Important Notes
+
+### How to Calculate `delta_liquidity`, `max_amount_a`, and `max_amount_b`
+
+1. you can set fixed two coin amount you want to use.
+2. use ClmmPoolUtil.estLiquidityAndCoinAmountFromOneAmounts() to calculated the delta_liquidity.
+3. Apply price slippage adjustment to the two coin amounts(max_amount_a and max_amount_b) calculated above by method adjustForCoinSlippage
+
+### Example
+
+```typescript
+const pool = await sdk.Pool.getPool(pool_id)
+const position = await sdk.Position.getPositionById(pos_id)
+const cur_sqrt_price = new BN(pool.current_sqrt_price)
+const lower_tick = Number(position.tick_lower_index)
+const upper_tick = Number(position.tick_upper_index)
+
+const lower_sqrt_price = TickMath.tickIndexToSqrtPriceX64(lower_tick)
+const upper_sqrt_price = TickMath.tickIndexToSqrtPriceX64(upper_tick)
+
+const slippage_tolerance = new Percentage(new BN(5), new BN(100))
+const liquidity = 10000
+
+const coin_amounts = ClmmPoolUtil.getCoinAmountFromLiquidity(new BN(liquidity), cur_sqrt_price, lower_sqrt_price, upper_sqrt_price, false)
+
+const { coin_amount_limit_a, coin_amount_limit_b } = adjustForCoinSlippage(coin_amounts, slippage_tolerance, true)
+
+const add_liquidity_payload_params: AddLiquidityParams = {
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  pool_id: pool.id,
+  tick_lower: lower_tick.toString(),
+  tick_upper: upper_tick.toString(),
+  delta_liquidity: liquidity.toString(),
+  max_amount_a: coin_amount_limit_a.toString(),
+  max_amount_b: coin_amount_limit_b.toString(),
+  pos_id: position.pos_object_id,
+  rewarder_coin_types: [],
+  collect_fee: false,
+}
+
+const payload = await sdk.Position.createAddLiquidityPayload(add_liquidity_payload_params)
+
+printTransaction(payload)
+const send_key_pair = 'The key pair generated by your private key'
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, payload, true)
+```
+
+### 2. Add liquidity with a fixed coin amount
+
+Use `sdk.Position.createAddLiquidityFixTokenPayload()` method.
+
+### Function Parameters
+
+- `pool_id`: The object id about which pool you want to operation
+- `coin_type_a`: The coin type address about coinA
+- `coin_type_b`: The coin type address about coinB
+- `tick_lower`: Represents the index of the lower tick boundary
+- `tick_upper`: Represents the index of the upper tick boundary
+- `is_open`: true means if first add liquidity, so needs open one position
+- `pos_id`: The object id about position
+- `fix_amount_a`: true means fixed coinA amount, false means fixed coinB amount
+- `slippage`: Price slippage point.
+- `amount_a`: If fixed amount A, you must set amount_a, amount_b will be auto calculated by `ClmmPoolUtil.estLiquidityAndCoinAmountFromOneAmounts()`
+- `amount_b`: If fixed amount B, you must set amount_b, amount_a will be auto calculated by `ClmmPoolUtil.estLiquidityAndCoinAmountFromOneAmounts()`
+- `collect_fee`: If you already has one position, you can select collect fees while adding liquidity
+- `rewarder_coin_types`: If these not empty, it will collect rewarder in this position, if you already open the position
+
+### Important Notes
+
+- The tick index must be an integer multiple of tickSpacing. If the provided parameter is not a multiple of tickSpacing, the contract will throw an error.
+- `-443636 < tick_lower_index < tick_upper_index < 443636`, 443636 is a constant, derived from the maximum range representable by the Q32.62 fixed-point number format.
+- If you know price range, you can use `TickMath.priceToTickIndex()` to transform real price to tick index.
+- You can just open one position near the current price of the pool, use `TickMath.getPrevInitializeTickIndex()` and `TickMath.getNextInitializeTickIndex()` to find the next initialized tick.
+- If you want to add global liquidity, you can set:
+  - `tick_lower_index = -443636 + (443636 % tick_spacing)`
+  - `tick_upper_index = 443636 - (443636 % tick_spacing)`
+
+```typescript
+const pool = await sdk.Pool.getPool(pool_id)
+const position = await sdk.Position.getPositionById(pos_id)
+const tick_lower_index = position.tick_lower_index
+const tick_upper_index = position.tick_upper_index
+const coin_amount = new BN(500)
+const fix_amount_a = true
+const slippage = 0.1
+const cur_sqrt_price = new BN(pool.current_sqrt_price)
+
+const liquidity_input = ClmmPoolUtil.estLiquidityAndCoinAmountFromOneAmounts(
+  tick_lower_index,
+  tick_upper_index,
+  coin_amount,
+  fix_amount_a,
+  true,
+  slippage,
+  cur_sqrt_price
+)
+
+const amount_a = fix_amount_a ? coin_amount.toNumber() : Number(liquidity_input.coin_amount_limit_a)
+const amount_b = fix_amount_a ? Number(liquidity_input.coin_amount_limit_b) : coin_amount.toNumber()
+
+const add_liquidity_payload_params: AddLiquidityFixTokenParams = {
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  pool_id: pool.id,
+  tick_lower: tick_lower_index.toString(),
+  tick_upper: tick_upper_index.toString(),
+  fix_amount_a,
+  amount_a,
+  amount_b,
+  slippage,
+  is_open: false,
+  pos_id: position.pos_object_id,
+  rewarder_coin_types: [],
+  collect_fee: true,
+}
+const add_liquidity_payload = await sdk.Position.createAddLiquidityFixTokenPayload(add_liquidity_payload_params)
+
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, add_liquidity_payload, true)
+```

package/docs/close_position.md

@@ -0,0 +1,57 @@
+# Close Position
+
+When you withdraw all the liquidity from your position, you can decide whether to close the position. Please note that when closing the position, you must also withdraw all the current position's liquidity, fees, and rewards.
+
+## 1. Close Position
+
+Use `sdk.Position.closePositionPayload()` method.
+
+### Function Parameters
+
+- `pool_id`: The object id about which pool you want to operation
+- `pos_id`: The object id about which position you want to operation
+- `coin_type_a`: The coin type address about coinA
+- `coin_type_b`: The coin type address about coinB
+- `min_amount_a`: The minimum amount of coin A that a user can acquire.
+- `min_amount_b`: The minimum amount of coin B that a user can acquire.
+- `rewarder_coin_types`: When closing the position, all pending rewards must be collected
+
+### Important Notes
+
+- Because of pool price will change, the amount of coin A and coin B will change. So the min_amount_a and min_amount_a means no matter how the price moves, the amount quantity that I need to receive at least is typically obtained
+  by adding the amount potentially acquired through calculations to the slippage adjustment.
+
+### Example
+
+```typescript
+const pool = await sdk.Pool.getPool(pool_id)
+const position = await sdk.Position.getPositionById(pos_id)
+
+const lower_tick = Number(position.tick_lower_index)
+const upper_tick = Number(position.tick_upper_index)
+
+const lower_sqrt_price = TickMath.tickIndexToSqrtPriceX64(lower_tick)
+const upper_sqrt_price = TickMath.tickIndexToSqrtPriceX64(upper_tick)
+
+const liquidity = new BN(position.liquidity)
+const slippage_tolerance = new Percentage(new BN(5), new BN(100))
+const cur_sqrt_price = new BN(pool.current_sqrt_price)
+
+const coin_amounts = ClmmPoolUtil.getCoinAmountFromLiquidity(liquidity, cur_sqrt_price, lower_sqrt_price, upper_sqrt_price, false)
+const { coin_amount_limit_a, coin_amount_limit_b } = adjustForCoinSlippage(coin_amounts, slippage_tolerance, false)
+
+const reward_coin_types = pool.rewarder_infos.map((rewarder) => rewarder.coin_type)
+
+const close_position_payload = await sdk.Position.closePositionPayload({
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  min_amount_a: coin_amount_limit_a.toString(),
+  min_amount_b: coin_amount_limit_b.toString(),
+  rewarder_coin_types: reward_coin_types,
+  pool_id: pool.id,
+  pos_id: position_nft_id,
+  collect_fee: true,
+})
+const send_key_pair = 'The key pair generated by your private key'
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, close_position_payload, true)
+```

package/docs/collect_fees.md

@@ -0,0 +1,37 @@
+# Collect rewards
+
+When you provide liquidity within a valid price range, when transactions occurring within this range, the rewards will be distributed every second based on the proportional share of effective liquidity from all positions within the current range. If you intend to harvest rewards separately, please follow the method below.
+
+## 1. Collect rewards
+
+Use `sdk.Position.collectRewarderPayload()` method.
+
+### Function Parameters
+
+- `pool_id`: The object id about which pool you want to operation
+- `pos_id`: The object id about which position you want to operation
+- `coin_type_a`: The coin type address about coinA
+- `coin_type_b`: The coin type address about coinB
+- `collect_fee`: you can select weather collect fees while Collect rewards.
+- `rewarder_coin_types`: If these not empty, it will collect rewarders in this position, if you already open the position. You can even determine which types of rewards you want to harvest by specifying the coin types you pass.
+
+### Example
+
+```typescript
+const pool = await sdk.Pool.getPool(pool_id)
+
+const reward_coin_types = pool.rewarder_infos.map((rewarder) => rewarder.coin_type)
+
+const collect_rewarder_params: CollectRewarderParams = {
+  pool_id: pool.id,
+  pos_id,
+  rewarder_coin_types: reward_coin_types,
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  collect_fee: true,
+}
+
+const collect_rewarder_payload = await sdk.Rewarder.collectRewarderPayload(collect_rewarder_params)
+const send_key_pair = 'The key pair generated by your private key'
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, collect_rewarder_payload, true)
+```

package/docs/create_clmm_pool.md

@@ -0,0 +1,228 @@
+# Create CLMM Pool
+
+Everyone can create Cetus CLMM pools directly.
+
+## 1. Create a CLMM Pool with Initial Liquidity
+
+Use `sdk.Pool.createPoolTransactionPayload()` to create a pool.
+
+### Function Parameters
+
+#### Required Parameters
+
+- `tick_spacing`: Affects price precision. Different tick spacing values correspond to different fee rates:
+
+  | Tick Spacing | Fee Rate |
+  | ------------ | -------- |
+  | 2            | 0.0001   |
+  | 10           | 0.0005   |
+  | 20           | 0.001    |
+  | 60           | 0.0025   |
+  | 200          | 0.01     |
+  | 220          | 0.02     |
+
+- `initialize_sqrt_price`: For computational convenience, we use fixed-point numbers to represent square root prices. Use `TickMath.priceToSqrtPriceX64()` to transform price to sqrtPrice.
+- `coin_type_a`: The coin type address for coin A.
+- `coin_type_b`: The coin type address for coin B.
+- `amount_a`: The amount of coin A to add as liquidity.
+- `amount_b`: The amount of coin B to add as liquidity.
+- `fix_amount_a`: Boolean value - true means fixed coin A amount, false means fixed coin B amount.
+- `tick_lower`: The index of the lower tick boundary.
+- `tick_upper`: The index of the upper tick boundary.
+- `metadata_a`: The coin metadata ID of coin A.
+- `metadata_b`: The coin metadata ID of coin B.
+
+#### Optional Parameters
+
+- `uri`: The icon of the pool (can be null).
+
+### Determining Coin Type A and B
+
+1. Complete the Coin Type: Ensure the coin type is complete before comparing.
+2. Character-by-Character Comparison: Compare the characters of both coin type addresses.
+3. ASCII Value Comparison: When encountering differing characters, compare their ASCII values. The coin with the larger ASCII value becomes "coin A".
+
+#### Examples:
+
+1. Example 1:
+
+   - coin_type_a: `0x6864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS`
+   - coin_type_b: `0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI`
+
+2. Example 2:
+   - coin_type_a: `0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC`
+   - coin_type_b: `0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN`
+
+### Important Notes
+
+- The tick index must be an integer multiple of tickSpacing.
+- Range: `-443636 < tick_lower_index < current_tick_index < tick_upper_index < 443636`
+- Currently, creating a pool requires adding bidirectional liquidity.
+
+## Example Code
+
+```typescript
+const sdk = CetusClmmSDK.createSDK({ env: 'mainnet' })
+const signer = ... // set keypair
+sdk.senderAddress = signer.getPublicKey().toSuiAddress() // set sdk.senderAddress
+
+// Initialize sqrt_price
+const initialize_sqrt_price = TickMath.priceToSqrtPriceX64(d(1.2),6,6).toString()
+const tick_spacing = 2
+const current_tick_index = TickMath.sqrtPriceX64ToTickIndex(new BN(initialize_sqrt_price))
+
+// Build tick range
+const tick_lower = TickMath.getPrevInitializeTickIndex(
+    new BN(current_tick_index).toNumber(),
+    new BN(tick_spacing).toNumber()
+)
+const tick_upper = TickMath.getNextInitializeTickIndex(
+    new BN(current_tick_index).toNumber(),
+    new BN(tick_spacing).toNumber()
+)
+
+// Input token amount
+const fix_coin_amount = new BN(200)
+const fix_amount_a = true // input token amount is token a
+const slippage = 0.05 // 5% slippage
+const cur_sqrt_price = new BN(initialize_sqrt_price)
+
+// Estimate liquidity and token amount from one amounts
+const res = ClmmPoolUtil.estLiquidityAndCoinAmountFromOneAmounts(
+    lower_tick,
+    upper_tick,
+    fix_coin_amount,
+    fix_amount_a,
+    true,
+    slippage,
+    cur_sqrt_price
+)
+
+// Estimate token a and token b amount
+const amount_a = fix_amount_a ? fix_coin_amount.toNumber() : res.coin_amount_limit_a.toNumber()
+const amount_b = fix_amount_a ? res.coin_amount_b.toNumber() : fix_coin_amount.toNumber()
+
+const coin_type_a = '0x3cfe7b9f6106808a8178ebd2d5ae6656cd0ccec15d33e63fd857c180bde8da75::coin:CetusUSDT'
+const coin_type_b = '0x3cfe7b9f6106808a8178ebd2d5ae6656cd0ccec15d33e63fd857c180bde8da75::coin::CetusUSDC'
+
+const coin_metadata_a_id = await suiClient.fetchCoinMetadata({coinType: coin_type_a}).id
+const coin_metadata_b_id = await suiClient.fetchCoinMetadata({coinType: coin_type_b}).id
+
+// Build createPoolPayload
+const create_pool_payload = sdk.Pool.createPoolPayload({
+    coin_type_a,
+    coin_type_b,
+    tick_spacing: tick_spacing,
+    initialize_sqrt_price: initialize_sqrt_price,
+    uri: '',
+    amount_a,
+    amount_b,
+    fix_amount_a,
+    tick_lower,
+    tick_upper,
+    metadata_a: coin_metadata_a_id,
+    metadata_b: coin_metadata_b_id,
+})
+const send_key_pair = 'The key pair generated by your private key'
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, tx, true)
+```
+
+## 2. Create a CLMM Pool with Initial Liquidity by directly inputting the price range
+
+Use `sdk.Pool.createPoolWithPricePayload()` to create a pool.
+
+### Function Parameters
+
+#### Required Parameters
+
+- `tick_spacing`: Affects price precision and fee rate (see table above)
+- `current_price`: The initial price of the pool
+- `coin_amount`: The amount of coins to add as liquidity
+- `fix_amount_a`: Boolean value - true means fixed coin A amount, false means fixed coin B amount
+- `add_mode_params`: Configuration for price range:
+  - For custom range: `{ is_full_range: false, min_price: string, max_price: string }`
+  - For full range: `{ is_full_range: true }`
+- `coin_decimals_a`: Number of decimal places for coin A
+- `coin_decimals_b`: Number of decimal places for coin B
+- `price_base_coin`: Base coin for price calculation ('coin_a' or 'coin_b')
+- `slippage`: Maximum acceptable slippage (e.g., 0.05 for 5%)
+
+### Two Ways to Create Pool
+
+1. **Create Pool with Position Return**
+   Use `sdk.Pool.createPoolWithPriceReturnPositionPayload()` to create a pool and get the position ID and remaining coins.
+
+```typescript
+// Custom price range example
+const tick_spacing = 220
+
+const mode_params: CreatePoolCustomRangeParams = {
+  is_full_range: false,
+  min_price: '0.2',
+  max_price: '0.7',
+}
+
+const result = await sdk.Pool.calculateCreatePoolWithPrice({
+  tick_spacing,
+  current_price: '0.5',
+  coin_amount: '1000000',
+  fix_amount_a: true,
+  add_mode_params: mode_params,
+  coin_decimals_a: 6,
+  coin_decimals_b: 9,
+  price_base_coin: 'coin_a',
+  slippage: 0.05,
+})
+
+const { tx, pos_id, remain_coin_a, remain_coin_b, remain_coin_type_a, remain_coin_type_b } =
+  await sdk.Pool.createPoolWithPriceReturnPositionPayload({
+    tick_spacing,
+    calculate_result: result,
+    add_mode_params: mode_params,
+    coin_type_a,
+    coin_type_b,
+  })
+
+// Handle remaining coins
+buildTransferCoin(sdk, tx, remain_coin_a, remain_coin_type_a)
+buildTransferCoin(sdk, tx, remain_coin_b, remain_coin_type_b)
+tx.transferObjects([pos_id], sdk.getSenderAddress())
+```
+
+2. **Create Pool Directly**
+   Use `sdk.Pool.createPoolWithPricePayload()` for a simpler pool creation without position management.
+
+```typescript
+// Full range example
+const full_range_params: FullRangeParams = {
+  is_full_range: true,
+}
+
+const full_range_result = await sdk.Pool.calculateCreatePoolWithPrice({
+  tick_spacing,
+  current_price: '0.5',
+  coin_amount: '1000000',
+  fix_amount_a: true,
+  add_mode_params: full_range_params,
+  coin_decimals_a: 6,
+  coin_decimals_b: 9,
+  price_base_coin: 'coin_a',
+  slippage: 0.05,
+})
+
+const tx = await sdk.Pool.createPoolWithPricePayload({
+  tick_spacing,
+  calculate_result: full_range_result,
+  add_mode_params: full_range_params,
+  coin_type_a,
+  coin_type_b,
+})
+```
+
+### Important Notes
+
+- The price range must be valid and within acceptable bounds
+- For custom ranges, ensure min_price < current_price < max_price
+- The tick spacing determines the fee rate and price precision
+- Slippage protection is important to prevent significant price impact
+- Consider the decimal places of both coins when calculating amounts

package/docs/error_code.md

@@ -0,0 +1,69 @@
+#  Contract Error Codes
+
+the Cetus smart contract may return the following error codes:
+
+| Module                   | Error Code | Description                                 | Contract Methods                                                                                              |
+| ------------------------ | ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| cetus_clmm::pool         | 0          | Amount is incorrect                         | flash_swap_internal,add_liquidity_fix_coin,repay_add_liquidity,repay_flash_swap,repay_flash_swap_with_partner |
+| cetus_clmm::pool         | 1          | Liquidity overflow                          | add_liquidity_internal,calculate_swap_result                                                                  |
+| cetus_clmm::pool         | 3          | Liquidity is zero                           | add_liquidity,remove_liquidity,add_liquidity_internal                                                         |
+| cetus_clmm::pool         | 4          | Not enough liquidity                        | swap_in_pool                                                                                                  |
+| cetus_clmm::pool         | 5          | Remainder amount underflow                  | check_remainer_amount_sub                                                                                     |
+| cetus_clmm::pool         | 6          | Swap amount in overflow                     | update_swap_result                                                                                            |
+| cetus_clmm::pool         | 7          | Swap amount out overflow                    | update_swap_result                                                                                            |
+| cetus_clmm::pool         | 8          | Fee amount overflow                         | update_swap_result                                                                                            |
+| cetus_clmm::pool         | 9          | Invalid fee rate                            | update_fee_rate                                                                                               |
+| cetus_clmm::pool         | 10         | Invalid fixed coin type                     | get_liquidity_from_amount                                                                                     |
+| cetus_clmm::pool         | 11         | Wrong sqrt price limit                      | flash_swap_internal                                                                                           |
+| cetus_clmm::pool         | 12         | Pool ID is error                            | repay_add_liquidity                                                                                           |
+| cetus_clmm::pool         | 13         | Pool is paused                              |                                                                                                               |
+| cetus_clmm::pool         | 14         | Flash swap receipt not match                | repay_flash_swap_with_partner, repay_flash_swap                                                               |
+| cetus_clmm::pool         | 16         | Invalid partner ref fee rate                | swap_in_pool                                                                                                  |
+| cetus_clmm::pool         | 17         | Reward does not exist                       | get_position_reward ,calculate_and_update_reward,collect_reward                                               |
+| cetus_clmm::pool         | 18         | Amount out is zero                          | flash_swap_internal                                                                                           |
+| cetus_clmm::pool         | 19         | Pool position not match                     | collect_reward,add_liquidity,add_liquidity_fix_coin,remove_liquidity,close_position,collect_fee               |
+| cetus_clmm::position     | 1          | Fee owned overflow                          | update_fee_internal                                                                                           |
+| cetus_clmm::position     | 2          | Reward owned overflow                       | update_rewards_internal                                                                                       |
+| cetus_clmm::position     | 3          | Points owned overflow                       | update_points_internal                                                                                        |
+| cetus_clmm::position     | 5          | Invalid position tick range                 | check_position_tick_range                                                                                     |
+| cetus_clmm::position     | 6          | Position does not exist                     | borrow_mut_position_info，fetch_positions，borrow_position_info                                               |
+| cetus_clmm::position     | 7          | Position is not empty                       | close_position                                                                                                |
+| cetus_clmm::position     | 8          | Liquidity change overflow                   | increase_liquidity                                                                                            |
+| cetus_clmm::position     | 9          | Liquidity change underflow                  | decrease_liquidity                                                                                            |
+| cetus_clmm::position     | 10         | Invalid reward index                        | update_and_reset_rewards                                                                                      |
+| cetus_clmm::rewarder     | 1          | Reward slot is full                         | add_rewarder                                                                                                  |
+| cetus_clmm::rewarder     | 2          | Reward already exists                       | add_rewarder                                                                                                  |
+| cetus_clmm::rewarder     | 3          | Invalid time                                | settle                                                                                                        |
+| cetus_clmm::rewarder     | 4          | Reward amount insufficient                  | update_emission                                                                                               |
+| cetus_clmm::rewarder     | 5          | Reward does not exist                       | borrow_mut_rewarder，borrow_rewarder                                                                          |
+| cetus_clmm::tick         | 0          | Liquidity overflow                          | update_by_liquidity                                                                                           |
+| cetus_clmm::tick         | 1          | Liquidity underflow                         | update_by_liquidity，cross_by_swap                                                                            |
+| cetus_clmm::tick         | 2          | Invalid tick                                | tick_score，                                                                                                  |
+| cetus_clmm::tick         | 3          | Tick not found                              | decrease_liquidity，                                                                                          |
+| cetus_clmm::pool_creator | 1          | Pool is permission                          | create_pool_v2                                                                                                |
+| cetus_clmm::pool_creator | 4          | Cap not match with pool key                 | create_pool_v2_with_creation_cap                                                                              |
+| cetus_clmm::pool_creator | 5          | Init sqrt price not between lower and upper | create_pool_v2                                                                                                |
+| cetus_clmm::partner      | 1          | Partner already exists                      | create_partner                                                                                                |
+| cetus_clmm::partner      | 2          | Invalid time                                | create_partner，update_time_range                                                                             |
+| cetus_clmm::partner      | 3          | Invalid partner ref fee rate                | update_ref_fee_rate，create_partner                                                                           |
+| cetus_clmm::partner      | 4          | Invalid partner cap                         | claim_ref_fee                                                                                                 |
+| cetus_clmm::partner      | 5          | Invalid coin type                           | claim_ref_fee                                                                                                 |
+| cetus_clmm::partner      | 6          | Invalid partner name                        | create_partner                                                                                                |
+| cetus_clmm::factory      | 1          | Pool already exists                         | create_pool_internal                                                                                          |
+| cetus_clmm::factory      | 2          | Invalid sqrt price                          | create_pool_internal                                                                                          |
+| cetus_clmm::factory      | 3          | Same coin type                              | new_pool_key，create_pool_internal                                                                            |
+| cetus_clmm::factory      | 4          | Amount in above max limit                   | create_pool_v2_                                                                                               |
+| cetus_clmm::factory      | 5          | Amount out below min limit                  | create_pool_v2_                                                                                               |
+| cetus_clmm::factory      | 6          | Invalid coin type sequence                  | new_pool_key                                                                                                  |
+| cetus_clmm::factory      | 7          | Quote coin type not in allowed pair config  | register_permission_pair_internal                                                                             |
+| cetus_clmm::factory      | 8          | Tick spacing not in allowed pair config     | register_permission_pair_internal                                                                             |
+| cetus_clmm::factory      | 9          | Pool key already registered                 | register_permission_pair_internal                                                                             |
+| cetus_clmm::factory      | 10         | Pool key not registered                     | unregister_permission_pair_internal                                                                           |
+| cetus_clmm::factory      | 11         | Cap already registered                      | mint_pool_creation_cap_by_admin，mint_pool_creation_cap                                                       |
+| cetus_clmm::factory      | 12         | Coin type not allowed                       | create_pool_v2_                                                                                               |
+| cetus_clmm::factory      | 13         | Cap not match with coin type                | unregister_permission_pair_internal，register_permission_pair_internal                                        |
+| cetus_clmm::factory      | 14         | Coin already exists in list                 | add_denied_coin， add_allowed_list                                                                            |
+| cetus_clmm::factory      | 15         | Coin not exists in list                     | remove_denied_list，remove_allowed_list                                                                       |
+| cetus_clmm::factory      | 16         | Liquidity check failed                      | create_pool_v2_                                                                                               |
+| cetus_clmm::factory      | 17         | Tick spacing not exists in fee tier         | add_allowed_pair_config                                                                                       |
+

package/docs/get_clmm_pools.md

@@ -0,0 +1,92 @@
+# Getting CLMM Pools
+
+## 1. Get All Pools
+
+Use `sdk.Pool.getPoolsWithPage()` method to retrieve all pools.
+
+### Parameters
+
+- `pagination_args`: Default to get all pool lists, supports pagination
+
+### Example
+
+```typescript
+async function getAllPools() {
+  const pools = await sdk.Pool.getPoolsWithPage()
+  console.log(`pool length: ${pools.length}`)
+}
+```
+
+## 2. Batch Get assign Pools
+
+Use `sdk.Pool.getAssignPools()` method to retrieve specific pools.
+
+### Parameters
+
+- `assign_pools`: An array of pool ID to get.
+
+### Example
+
+```typescript
+const pools = await sdk.Pool.getAssignPools(['0x0...'])
+console.log(pools)
+```
+
+## 3. Get Single Pool
+
+Use `sdk.Pool.getPool()` method to retrieve a specific pool.
+
+### Parameters
+
+- `pool_id`: Pool address
+- `force_refresh`: Optional boolean to refresh cache
+
+### Example
+
+```typescript
+const pool = await sdk.Pool.getPool('0x0...')
+console.log({ pool })
+```
+
+## 4. Get Pool by Coin Types
+
+Use `sdk.Pool.getPoolByCoins()` method to find pools by coin types.
+
+### Parameters
+
+- `coins`: Array of coin types
+- `fee_rate`: Optional fee rate number
+
+### Example
+
+```typescript
+const coin_type_a = '0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN'
+const coin_type_b = '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN'
+
+const pools = await sdk.Pool.getPoolByCoins([coin_type_a, coin_type_b])
+```
+
+## 5. Notes
+
+Some common methods for pool
+
+### 1. Convert SqrtPrice to Price
+
+Use `TickMath.sqrtPriceX64ToPrice()` method to convert a given sqrtPrice to a price.
+
+### Parameters
+
+- `sqrt_price_x64`: The sqrtPrice value to convert.
+- `decimals_a`: The number of decimals for coin A.
+- `decimals_b`: The number of decimals for coin B.
+
+### Example
+
+```typescript
+const sqrt_price_x64 = '18446744073709551616'
+const decimals_a = 6
+const decimals_b = 9
+
+const price = TickMath.sqrtPriceX64ToPrice(new BN(sqrt_price_x64), decimals_a, decimals_b)
+console.log('Price:', price.toString())
+```