@cetusprotocol/sui-clmm-sdk 1.0.0

package/docs/get_positions.md

@@ -0,0 +1,70 @@
+# Get Positions
+
+## 1. Get all positions of one pool by ownerAddress
+
+Use `sdk.Position.getPositionList()` method.
+
+### Function Parameters
+
+- `account_address`: The user account address
+- `assign_pool_ids`: An array of pool ID
+- `show_display`: When some testnet rpc nodes can't return object's display data, you can set this option to false to avoid returning errors. Default is true.
+
+### Example
+
+```typescript
+const account_address = '0xcd0247d0b67e53dde69b285e7a748e3dc390e8a5244eb9dd9c5c53d95e4cf0aa'
+const assign_pool_ids = ['0x83c101a55563b037f4cd25e5b326b26ae6537dc8048004c1408079f7578dd160']
+const res = await sdk.Position.getPositionList(account_address, assign_pool_ids, false)
+```
+
+## 2. Get all positions of one pool
+
+Use `sdk.Pool.getPositionList()` method.
+
+### Function Parameters
+
+- `position_handle`: The position handle of pool
+
+### Example
+
+```typescript
+const position_handle = '0x83c101a55563b037f4cd25e5b326b26ae6537dc8048004c1408079f7578dd160'
+const pool = await sdk.Pool.getPool(position_handle)
+const res = await sdk.Pool.getPositionList(pool.position_manager.positions_handle)
+```
+
+## 3. Get one position
+
+Use `sdk.Position.getPositionById()` method.
+
+### Function Parameters
+
+- `position_id`: The position object ID
+- `calculate_rewarder`: Whether to calculate the rewarder of the position
+- `show_display`: When some testnet rpc nodes can't return object's display data, you can set this option to false to avoid returning errors. Default is true.
+
+### Example
+
+```typescript
+const position_id = '0xfbf94213d59d285f66bacdb3d667a4db00b491af35887022e9197bb244705bde'
+const res = await sdk.Position.getPositionById(position_id)
+```
+
+## 4. Batch get position fees
+
+Use `sdk.Position.batchFetchPositionFees()` method.
+
+### Function Parameters
+
+- `position_ids`: An array of position ID
+
+### Example
+
+```typescript
+const position_ids = [
+  '0xf10d37cc00bcd60f85cef3fe473ea979e3f7f3631d522618e80c876b349e56bc',
+  '0xfbf94213d59d285f66bacdb3d667a4db00b491af35887022e9197bb244705bde',
+]
+const fees = await TestnetSDK.Position.batchFetchPositionFees(position_ids)
+```

package/docs/get_reward.md

@@ -0,0 +1,53 @@
+# Get Position Rewards
+
+## 1. Get Position Reward List of One Pool
+
+Use `SDK.Pool.fetchPositionRewardList()` method.
+
+### Parameters
+
+- `pool_id`: The pool object ID
+- `coin_type_a`: Coin A type
+- `coin_type_b`: Coin B type
+
+### Example
+
+```typescript
+const pool_id = '0x83c101a55563b037f4cd25e5b326b26ae6537dc8048004c1408079f7578dd160'
+const pool = await sdk.Pool.getPool(pool_id)
+const res = await sdk.Pool.fetchPositionRewardList({
+  pool_id: pool.id,
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+})
+```
+
+## 2. Get Daily Reward Emission Info for One Pool
+
+Use `sdk.Rewarder.emissionsEveryDay()` method.
+
+### Parameters
+
+- `pool_id`: The pool object ID
+
+### Example
+
+```typescript
+const pool_id = '0x83c101a55563b037f4cd25e5b326b26ae6537dc8048004c1408079f7578dd160'
+const emissions_everyday = await sdk.Rewarder.emissionsEveryDay(pool_id)
+```
+
+## 3. Get Rewards of Position
+
+Use `sdk.Rewarder.batchFetchPositionRewarders()` method.
+
+### Parameters
+
+- `position_ids`: Array of position object ID
+
+### Example
+
+```typescript
+const position_ids = ['0xf10d37cc00bcd60f85cef3fe473ea979e3f7f3631d522618e80c876b349e56bc']
+const pos_rewarders_amount = await sdk.Rewarder.batchFetchPositionRewarders(position_ids)
+```

package/docs/get_ticks.md

@@ -0,0 +1,39 @@
+# Get ticks
+
+## 1. Batch get ticks by pool ID
+
+Use `SDK.Pool.fetchTicks()` method.
+
+### Parameters
+
+- `pool_id`: The pool object ID
+- `coin_type_a`: Coin A type
+- `coin_type_b`: Coin B type
+
+### Example
+
+```typescript
+const pool_id = '0xbed3136f15b0ea649fb94bcdf9d3728fb82ba1c3e189bf6062d78ff547850054'
+const coin_type_a = '0x26b3bc67befc214058ca78ea9a2690298d731a2d4309485ec3d40198063c4abc::usdt::USDT'
+const coin_type_b = '0x26b3bc67befc214058ca78ea9a2690298d731a2d4309485ec3d40198063c4abc::cetus::CETUS'
+const tick_data = await sdk.Pool.fetchTicks({
+  pool_id,
+  coin_type_a,
+  coin_type_b,
+})
+```
+
+## 2.Batch get ticks by tickHandle
+
+Use `sdk.Pool.fetchTicksByRpc()` method.
+
+### Parameters
+
+- `tick_handle`: The tick handle of pool.
+
+### Example
+
+```typescript
+const pool = await sdk.Pool.getPool('0x6fd4915e6d8d3e2ba6d81787046eb948ae36fdfc75dad2e24f0d4aaa2417a416')
+const tick_data = await sdk.Pool.fetchTicksByRpc(pool.ticks_handle)
+```

package/docs/migrate_to_version_6.0.md

@@ -0,0 +1,143 @@
+# 📦 Migrate to SDK Version 6.0
+
+> In SDK version 6.0, we’ve made significant upgrades and refactoring across the entire SDK. Function names, parameter styles, and return value field formats have been unified. Deprecated APIs have been removed. **It is strongly recommended to migrate as soon as possible.**
+
+> The following are the main migration highlights. Please refer to the TypeScript types for specific details.
+
+---
+
+## 🚨 Important Notice
+
+> All method parameters and response fields now use **snake_case naming convention**.  
+> Example: `tickSpacing` → `tick_spacing`
+
+> ⚠️ This migration guide focuses only on major structural changes.Minor field name updates and signature adjustments are not exhaustively listed here.Please rely on TypeScript type hints and editor autocomplete to complete the migration accurately
+
+---
+
+## 1. CetusClmmSDK
+
+🛠 SDK Initialization Updated
+
+```diff
+- const cetusClmmSDK = initCetusSDK({network: 'mainnet'})
++ const sdk = CetusClmmSDK.createSDK({ env: 'mainnet' })
+
+// Setting `senderAddress` has changed
+- sdk.senderAddress = "0x..."
++ sdk.setSenderAddress("0x...")
+```
+
+🔄 Method Migration
+
+```diff
+// Get wallet balance
+- sdk.getOwnerCoinAssets()
++ sdk.FullClient.getOwnerCoinAssets()
+- sdk.getOwnerCoinBalances()
++ sdk.FullClient.getOwnerCoinAssets()
+
+export type CoinAsset = {
+- coinAddress: string
++ coin_type: string
+}
+```
+
+❌ Removed Modules
+The Router and RouterV2 modules have been removed for better maintenance.
+Use the recommended [Cetus Aggregator SDK](https://cetus-1.gitbook.io/cetus-developer-docs/developer/cetus-aggregator) instead.
+
+| Deprecated Modules | Replacement    |
+| ------------------ | -------------- |
+| Router             | Aggregator SDK |
+| RouterV2           | Aggregator SDK |
+
+## 2. Pool Module
+
+🔄 Method Migration
+
+```diff
+- sdk.Pool.getSuiTransactionResponse(previousTx)
++ sdk.FullClient.getSuiTransactionResponse(previousTx)
+
+- sdk.Pool.getPoolsWithPage([], 'all', true)
++ sdk.Pool.getPoolsWithPage('all', true)
++ sdk.Pool.getAssignPools([])
+
+export type Pool = {
+- poolAddress: string
++ id: string
+- coinTypeA: string
++ coin_type_a: string
+- coinTypeB: string
++ coin_type_b: string
+...
+}
+```
+
+❌ Removed Methods
+| Removed | Replacement |
+| ---------------------------------- | ------------------------- |
+| ~~`getPoolImmutables`~~ | getPoolImmutablesWithPage |
+| ~~`getPools`~~ | getPoolsWithPage |
+| ~~`creatPoolsTransactionPayload`~~ | createPoolPayload |
+| ~~`creatPoolTransactionPayload`~~ | createPoolPayload |
+
+✏️ Renamed Methods  
+| Old Method | New Method |
+| ------------------------------- | -------------------- |
+| createPoolTransactionPayload | createPoolPayload |
+| createPoolTransactionRowPayload | createPoolRowPayload |
+
+## 3. Position Module
+
+❌ Removed Methods
+| Removed Method | Replacement |
+| ------------------ | ----------------- |
+| ~~`calculateFee`~~ | fetchPosFeeAmount |
+
+✏️ Renamed Methods  
+| Old Method | New Method |
+| --------------------------------- | ----------------------------- |
+| getSipmlePositionList | getSimplePositionList |
+| removeLiquidityTransactionPayload | removeLiquidityPayload |
+| closePositionTransactionPayload | closePositionPayload |
+| openPositionTransactionPayload | openPositionPayload |
+| collectFeeTransactionPayload | collectFeePayload |
+| createCollectFeePaylod | createCollectFeePayload |
+| createCollectFeeNoSendPaylod | createCollectFeeNoSendPayload |
+
+## 4. Rewarder Module
+
+❌ Removed Methods
+| Removed Method | Replacement |
+| ------------------------- | ------------------------ |
+| ~~`posRewardersAmount`~~ | fetchPosRewardersAmount |
+| ~~`poolRewardersAmount`~~ | fetchPoolRewardersAmount |
+
+✏️ Renamed Methods  
+| Old Method | New Method |
+| --------------------------------- | ---------------------------------- |
+| collectRewarderTransactionPayload | collectRewarderPayload |
+| batchCollectRewardePayload | batchCollectRewardsPayload |
+| createCollectRewarderPaylod | createCollectRewarderPayload |
+| createCollectRewarderNoSendPaylod | createCollectRewarderNoSendPayload |
+
+## 5. helpers
+
+🔄 Method Migration
+Several commonly used utility methods have been moved from @cetusprotocol/sui-clmm-sdk to @cetusprotocol/common-sdk.
+Below are some typical import and usage changes:
+
+> 🚫 `TransactionUtil` is deprecated and replaced CoinAssist
+
+```diff
+- import type { CoinAssist, ClmmPoolUtil, TickMath，TickUtil  } from '@cetusprotocol/sui-clmm-sdk'
++ import type { CoinAssist, ClmmPoolUtil, TickMath，TickUtil  } from '@cetusprotocol/common-sdk'
+
+- TransactionUtil.buildCoinForAmount()
++ CoinAssist.buildCoinForAmount()
+
+- TransactionUtil.buildCoinWithBalance()
++ CoinAssist.buildCoinWithBalance()
+```

package/docs/open_position.md

@@ -0,0 +1,224 @@
+# Open Position
+
+Before you want to deposit liquidity, you need to choose an appropriate price range (corresponding to the tick range) to open a position.
+
+There are two situations:
+
+1. Open a position only
+2. Open position and add liquidity (recommended)
+
+In most cases, opening a position and adding liquidity are supposed to be done simultaneously.
+
+## 1.1. Open a Position Only with tick range
+
+Use `sdk.Position.openPositionPayload()` 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
+
+### 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)`
+
+### 1 Example
+
+```typescript
+const send_key_pair = 'The key pair generated by your private key'
+// fetch pool data
+const pool = await sdk.Pool.getPool(pool_id)
+// build tick range
+const lower_tick = TickMath.getPrevInitializeTickIndex(new BN(pool.current_tick_index).toNumber(), new BN(pool.tick_spacing).toNumber())
+const upper_tick = TickMath.getNextInitializeTickIndex(new BN(pool.current_tick_index).toNumber(), new BN(pool.tick_spacing).toNumber())
+// build open position payload
+const open_position_payload = sdk.Position.openPositionPayload({
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  tick_lower: lower_tick.toString(),
+  tick_upper: upper_tick.toString(),
+  pool_id: pool.id,
+})
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, open_position_payload, true)
+```
+
+### 1.2 Open a Position Only with price range
+
+Use `sdk.Position.openPositionWithPricePayload()` method.
+
+#### Required Parameters
+
+- `pool_id`: The object id about which pool you want to operation
+- `add_mode_params`: Configuration for price range:
+  - For custom range: `{ is_full_range: false, min_price: string, max_price: string , price_base_coin: 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')
+
+```typescript
+const pool_id = '0x0...'
+
+// use full range price mode
+const full_range_params: OpenPositionWithPriceParams = {
+  pool_id,
+  is_full_range: true,
+}
+const open_payload = await sdk.Position.openPositionWithPricePayload(full_range_params)
+
+// or
+// use custom price range
+const custom_price_range_params: OpenPositionWithPriceParams = {
+  pool_id,
+  coin_decimals_a: 6,
+  coin_decimals_b: 9,
+  is_full_range: false,
+  min_price: '0.2',
+  max_price: '0.9',
+  price_base_coin: 'coin_a',
+}
+const open_payload = await sdk.Position.openPositionWithPricePayload(custom_price_range_params)
+
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, open_payload, true)
+```
+
+## 2.1 Open Position with Add Liquidity by tick range
+
+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
+- `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)`
+
+### Example
+
+```typescript
+const pool = await sdk.Pool.getPool(pool_id)
+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 tick_lower_index = TickMath.getPrevInitializeTickIndex(
+  new BN(pool.current_tick_index).toNumber(),
+  new BN(pool.tick_spacing).toNumber()
+)
+const tick_upper_index = TickMath.getNextInitializeTickIndex(
+  new BN(pool.current_tick_index).toNumber(),
+  new BN(pool.tick_spacing).toNumber()
+)
+
+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: true,
+  pos_id: position.pos_object_id,
+  rewarder_coin_types: [],
+  collect_fee: false,
+}
+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)
+```
+
+## 2.2 Open Position with Add Liquidity by price range
+
+Use `sdk.Position.createAddLiquidityFixCoinWithPricePayload()` method.
+
+### Function Parameters
+
+- `pool_id`: The object id about which pool you want to operation
+- `add_mode_params`: Configuration for price range:
+  - For custom range: `{ is_full_range: false, min_price: string, max_price: string , price_base_coin: string, coin_decimals_a: number, coin_decimals_b: number}`
+  - 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')
+
+### Example
+
+Use `sdk.Position.createAddLiquidityFixTokenPayload()` method.
+
+```typescript
+// custom price range
+const params: CustomRangeParams = {
+  s_full_range: false,
+  min_price: '0.2',
+  max_price: '0.7',
+  coin_decimals_a: 6,
+  coin_decimals_b: 9,
+  price_base_coin: 'coin_a',
+}
+
+// or
+//  full range price
+const params: FullRangeParams = {
+  is_full_range: true,
+}
+
+const result = await sdk.Position.calculateAddLiquidityResultWithPrice({
+  add_mode_params: params,
+  pool_id,
+  slippage: 0.01,
+  coin_amount: toDecimalsAmount(1, 6).toString(),
+  fix_amount_a: true,
+})
+
+const payload = await sdk.Position.createAddLiquidityFixCoinWithPricePayload({
+  pool_id,
+  calculate_result: result,
+  add_mode_params: params,
+})
+
+const transfer_txn = await sdk.FullClient.executeTx(send_key_pair, payload, true)
+```

package/docs/partner_swap.md

@@ -0,0 +1,60 @@
+# Partner Swap
+
+Currently, only established project teams are eligible for applying for partner swap.
+
+## Partner
+
+We offer a partner function. When you utilize the standard swap method, we will allocate the agreed-upon share to the partner. However, due to Sui contract limitations, partner functionality doesn't work in the latest smart router function with split order or when integrating other pools like DeepBook.
+
+## Partner AccountCap
+
+Only verified accounts are eligible to collect partner referral fees. When creating a partner, we generate a Partner AccountCap object (visible in your NFT list). Only accounts that possess the AccountCap are able to claim the fees.
+
+## Claim Referral Fee
+
+We provide a function `sdk.Pool.claimPartnerRefFeePayload()` to check referral fees.
+
+### Function Parameters
+
+Please refer to the original function for specific parameter types.
+
+- `partner_cap`: The object ID of the partner cap
+- `partner`: The object ID of the partner
+- `coin_type`: The coin type for the fee coin type. You can obtain the referral fee using this specified method.
+
+### Example
+
+```typescript
+const partner_cap = '0x...'
+const partner = '0x...'
+const coin_type = '0x...::...::....'
+const claim_ref_ree_payload = await sdk.Pool.claimPartnerRefFeePayload(partner_cap, partner, coin_type)
+const transfer_txn = await sdk.fullClient.sendTransaction(buildTestAccount(), claim_ref_ree_payload)
+```
+
+## Check Referral Fee
+
+We provide a function `sdk.Pool.getPartnerRefFeeAmount()` to check referral fees.
+
+### Function Parameters
+
+Please refer to the original function for specific parameter types.
+
+- `partner_id`: The object ID of the partner
+
+### Example
+
+```typescript
+import BN from 'bn.js'
+import { CetusClmmSDK } from '@cetusprotocol/sui-clmm-sdk'
+
+const sdk = CetusClmmSDK.createSDK({ env: 'mainnet' })
+
+const partner_id = '0x...'
+const ref_fee = await sdk.Pool.getPartnerRefFeeAmount(partner_id)
+```
+
+## Apply for Partner Swap
+
+Interested in Partner Swap? Submit a request from here:
+[https://4bx69zjogri.typeform.com/to/UUETIX2f](https://4bx69zjogri.typeform.com/to/UUETIX2f)