@cetusprotocol/dlmm-sdk 0.0.0-experimental-20250925173459

package/README.md

@@ -0,0 +1,654 @@
+# @cetusprotocol/dlmm-sdk
+
+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.
+
+## Getting Started
+
+## How to Use the DLMM SDK?
+
+### Installation
+
+To start using the `DLMM SDK`, you first need to install it in your TypeScript project:
+
+```bash
+npm install @cetusprotocol/dlmm-sdk
+```
+
+### Setup
+
+Import the SDK into the TypeScript file where you intend to use it:
+
+```typescript
+import { CetusDlmmSDK } from '@cetusprotocol/dlmm-sdk'
+```
+
+### Initializing the 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:
+
+```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:
+
+```typescript
+const env = 'mainnet'
+const full_rpc_url = 'YOUR_FULL_NODE_URL'
+
+const sdk = CetusDlmmSDK.createSDK({ env })
+```
+
+If you wish to set your own full node URL or SuiClient, you can do so as follows:
+
+```typescript
+const sdk = CetusDlmmSDK.createSDK({ env, sui_client })
+// or
+const sdk = CetusDlmmSDK.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
+- `bin_id`: The ID of the bin in the pool
+- `bin_step`: The step size between bins
+- `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. Pool Operations
+
+#### Get Pool Information
+
+```typescript
+// Get all pools
+const pools = await sdk.Pool.getPools()
+
+// Get specific pool
+const pool = await sdk.Pool.getPool(pool_id)
+
+// Get specific pools by their IDs
+const assign_pools = await sdk.Pool.getAssignPoolList([
+  '0x...',
+  // Add more pool IDs as needed
+])
+
+// Get bin information
+const bin_info = await sdk.Pool.getBinInfo(pool_id, bin_id, bin_step)
+
+// Get pool bin information
+const pool_bin_info = await sdk.Pool.getPoolBinInfo(pool_id)
+
+// Get bin step configurations
+const bin_step_configs = await sdk.Pool.getBinStepConfigs()
+
+// Get pool transaction list
+const pool_transactions = await sdk.Pool.getPoolTransactionList({
+  pool_id: '0x...',
+  pagination_args: { limit: 10 }
+})
+```
+
+#### Create Pool
+
+There are two ways to create a pool:
+
+**Method 1: Create Pool Only**
+
+```typescript
+// Create a new pool without adding liquidity
+const bin_step = 2
+const base_factor = 10000
+const price = '1.1'
+const active_id = BinUtils.getBinIdFromPrice(price, bin_step, true, 6, 6)
+
+const tx = new Transaction()
+await sdk.Pool.createPoolPayload({
+  active_id,
+  bin_step,
+  coin_type_a: '0x...::usdc::USDC',
+  coin_type_b: '0x...::usdt::USDT',
+  base_factor,
+}, tx)
+```
+
+**Method 2: Create Pool and Add Liquidity in One Transaction**
+
+```typescript
+// Create pool and add liquidity in one transaction
+const bin_step = 2
+const base_factor = 10000
+const price = '1.1'
+const active_id = BinUtils.getBinIdFromPrice(price, bin_step, true, 6, 6)
+
+// Calculate liquidity distribution
+const bin_infos = sdk.Position.calculateAddLiquidityInfo({
+  active_id,
+  bin_step,
+  lower_bin_id: active_id - 10,
+  upper_bin_id: active_id + 10,
+  amount_a_in_active_bin: '0',
+  amount_b_in_active_bin: '0',
+  strategy_type: StrategyType.Spot,
+  coin_amount: '10000000',
+  fix_amount_a: true,
+})
+
+const createAndAddTx = await sdk.Pool.createPoolAndAddLiquidityPayload({
+  active_id,
+  lower_bin_id: active_id - 10,
+  upper_bin_id: active_id + 10,
+  bin_step,
+  bin_infos,
+  coin_type_a: '0x14a71d857b34677a7d57e0feb303df1adb515a37780645ab763d42ce8d1a5e48::usdc::USDC',
+  coin_type_b: '0x14a71d857b34677a7d57e0feb303df1adb515a37780645ab763d42ce8d1a5e48::eth::ETH',
+  strategy_type: StrategyType.Spot,
+  use_bin_infos: false,
+  base_factor,
+})
+```
+
+### 2. Position Operations
+
+#### Get Position Information
+
+```typescript
+// Get owner's position list
+const positions = await sdk.Position.getOwnerPositionList(wallet)
+
+// Get specific position
+const position = await sdk.Position.getPosition(position_id)
+```
+
+### 3. Fee Operations
+
+#### Fee and Reward Calculation
+
+To calculate fees and rewards for a position, you can use the `fetchPositionFeeAndReward` method. This method allows you to get both fee and reward data for one or multiple positions:
+
+```typescript
+// First get the pool information
+const pool = await sdk.Pool.getPool(pool_id)
+const { id, coin_type_a, coin_type_b, reward_manager } = pool
+
+// Fetch fee and reward data
+const { feeData, rewardData } = await sdk.Position.fetchPositionFeeAndReward([
+  {
+    pool_id: id,
+    position_id: position_id,
+    reward_coins: reward_manager.rewards.map((reward) => reward.reward_coin),
+    coin_type_a,
+    coin_type_b,
+  },
+])
+
+// 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
+//   }
+// }
+
+// rewardData structure
+// {
+//   [position_id]: {
+//     position_id: string,
+//     rewards: {
+//       [coin_type]: string  // Amount of reward tokens owned
+//     }
+//   }
+// }
+```
+
+#### Fee Collection
+
+You can collect fees from your positions in several ways:
+
+1. **Collect Fees and Rewards Together**:
+```typescript
+// Build collect fee and reward transaction
+const tx = await sdk.Position.collectRewardAndFeePayload([{
+  pool_id,
+  position_id,
+  reward_coins: reward_manager.rewards.map((reward) => reward.reward_coin),
+  coin_type_a,
+  coin_type_b
+}])
+
+// Simulate or send the transaction
+const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
+```
+
+### 4. Liquidity Operations
+
+#### Add Liquidity
+
+There are three strategies for adding liquidity: Spot, BidAsk, and Curve. Here's how to use each:
+
+1. **Spot Strategy**:
+```typescript
+// Get pool information
+const pool = await sdk.Pool.getPool(pool_id)
+const { active_id, bin_step, bin_manager } = pool
+
+// Get amounts in active bin if it's within the range
+const amounts_in_active_bin = await sdk.Position.getActiveBinIfInRange(
+  bin_manager.bin_manager_handle,
+  lower_bin_id,
+  upper_bin_id,
+  active_id,
+  bin_step
+)
+
+// Calculate liquidity distribution
+const calculateOption = {
+  amount_a: '1000000',
+  amount_b: '1200000',
+  active_id,
+  bin_step,
+  lower_bin_id: -10,
+  upper_bin_id: 10,
+  amount_a_in_active_bin: amounts_in_active_bin?.amount_a || '0',
+  amount_b_in_active_bin: amounts_in_active_bin?.amount_b || '0',
+  strategy_type: StrategyType.Spot
+}
+const bin_infos = 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
+}
+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,
+  active_id,
+  position_id,
+  collect_fee: true,
+  reward_coins: []
+}
+const tx = sdk.Position.addLiquidityPayload(addOption)
+```
+
+Note: The `amount_a_in_active_bin` and `amount_b_in_active_bin` parameters are used to calculate the correct liquidity distribution when the active bin is within your position's range. These values are obtained using the `getActiveBinIfInRange` method, which:
+1. Checks if the active bin is within your specified range
+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
+const calculateOption = {
+  amount_a: '1000000',
+  amount_b: '1200000',
+  active_id,
+  bin_step,
+  lower_bin_id: -10,
+  upper_bin_id: 10,
+  amount_a_in_active_bin: '0',
+  amount_b_in_active_bin: '0',
+  strategy_type: StrategyType.BidAsk
+}
+```
+
+3. **Curve Strategy**:
+```typescript
+// Similar to Spot strategy but with different strategy_type
+const calculateOption = {
+  amount_a: '1000000',
+  amount_b: '1200000',
+  active_id,
+  bin_step,
+  lower_bin_id: -10,
+  upper_bin_id: 10,
+  amount_a_in_active_bin: '0',
+  amount_b_in_active_bin: '0',
+  strategy_type: StrategyType.Curve
+}
+```
+
+4. **Fixed Amount Strategy**:
+```typescript
+// Calculate with fixed amount of one token
+const calculateOption = {
+  coin_amount: '1000000',
+  fix_amount_a: true, // true for token A, false for token B
+  active_id,
+  bin_step,
+  lower_bin_id: -10,
+  upper_bin_id: 10,
+  amount_a_in_active_bin: '0',
+  amount_b_in_active_bin: '0',
+  strategy_type: StrategyType.Spot // or BidAsk or Curve
+}
+```
+
+5. **Add Liquidity with Price**:
+```typescript
+// Add liquidity with specific price range
+const addOption = {
+  pool_id,
+  bin_infos,
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  price_base_coin: 'coin_a',
+  price: price.toString(),
+  lower_price,
+  upper_price,
+  bin_step,
+  amount_a_in_active_bin: amounts_in_active_bin?.amount_a || '0',
+  amount_b_in_active_bin: amounts_in_active_bin?.amount_b || '0',
+  strategy_type: StrategyType.Spot,
+  decimals_a: 6,
+  decimals_b: 6,
+  max_bin_slippage: 0.01,
+  active_id,
+  // If use_bin_infos is true, liquidity is allocated according to bin_infos; otherwise, it is calculated internally by the contract
+  use_bin_infos: false,
+}
+const tx = sdk.Position.addLiquidityWithPricePayload(addOption)
+```
+
+#### Remove Liquidity
+
+There are two ways to remove liquidity:
+
+1. **Remove with Both Amounts**:
+```typescript
+// Get position and pool information
+const pool = await sdk.Pool.getPool(pool_id)
+const position = await sdk.Position.getPosition(position_id)
+const { active_id, bin_step, bin_manager } = pool
+
+// Get active bin information
+const active_bin = await sdk.Pool.getBinInfo(bin_manager.bin_manager_handle, active_id, bin_step)
+const liquidity_shares_data = parseLiquidityShares(position.liquidity_shares, bin_step, position.lower_bin_id, active_bin)
+
+// Calculate removal amounts
+const calculateOption = {
+  bins: liquidity_shares_data.bins,
+  active_id,
+  fix_amount_a: true,
+  coin_amount: '100000'
+}
+const bin_infos = sdk.Position.calculateRemoveLiquidityInfo(calculateOption)
+
+// Build and send transaction
+const removeOption = {
+  pool_id,
+  bin_infos,
+  coin_type_a: pool.coin_type_a,
+  coin_type_b: pool.coin_type_b,
+  position_id,
+  active_id,
+  slippage: 0.01,
+  reward_coins: []，
+  collect_fee: true,
+  reward_coins: [],
+  bin_step,
+  remove_percent: 0.5, // If remove_percent is specified, bin_infos will not be effective
+}
+const tx = sdk.Position.removeLiquidityPayload(removeOption)
+```
+
+2. **Remove Only One Token**:
+```typescript
+const calculateOption = {
+  bins: liquidity_shares_data.bins,
+  active_id,
+  is_only_a: true, // true for token A, false for token B
+  coin_amount: '100000'
+}
+```
+
+#### Close Position
+
+```typescript
+// Close position (This will collect all fees, rewards and remove all liquidity)
+const tx = sdk.Position.closePositionPayload({
+  pool_id,
+  position_id,
+  coin_type_a,
+  coin_type_b,
+  reward_coins: pool.reward_manager.rewards.map(reward => reward.reward_coin) // Required: Must include all reward coin types from the pool
+})
+
+// Simulate or send the transaction
+const sim_result = await sdk.FullClient.sendSimulationTransaction(tx, wallet)
+```
+
+Note: Closing a position will:
+1. Collect all accumulated fees
+2. Collect all pending rewards (must include all reward coins from the pool)
+3. Remove all liquidity from the position
+4. Delete the position
+
+### 5. Swap Operations
+
+```typescript
+// Get pool information
+const pool = await sdk.Pool.getPool(pool_id)
+const { coin_type_a, coin_type_b } = pool
+
+// Get swap quote
+const quote_obj = await sdk.Swap.preSwapQuote({
+  pool_id,
+  a2b: true, // true for A to B, false for B to A
+  by_amount_in: true, // true for exact input, false for exact output
+  in_amount: '2000000',
+  coin_type_a,
+  coin_type_b
+})
+
+// Build and send swap transaction
+const tx = sdk.Swap.swapPayload({
+  coin_type_a,
+  coin_type_b,
+  quote_obj,
+  by_amount_in: true,
+  slippage: 0.01
+})
+```
+
+### 6. Partner Operations
+
+#### Partner Management
+
+```typescript
+// Get partner list
+const partnerList = await sdk.Partner.getPartnerList()
+
+// Get specific partner
+const partner = await sdk.Partner.getPartner(partner_id)
+
+// Get partner capability ID
+const partnerCapId = await sdk.Partner.getPartnerCapId(account, partner_id)
+
+// Get partner balance
+const partnerBalance = await sdk.Partner.getPartnerBalance(partner_id)
+
+// Create partner
+const start_time = Math.floor(Date.now() / 1000) + 5000
+const tx = sdk.Partner.createPartnerPayload({
+  name: 'test partner',
+  ref_fee_rate: 0.01,
+  start_time,
+  end_time: start_time + 9 * 24 * 3600,
+  recipient: account,
+})
+
+// Update referral fee rate
+const updateFeeTx = await sdk.Partner.updateRefFeeRatePayload({
+  partner_id: '0x9d171399393e3cbedffc24269eb606e735fb56fee17c15153eb5e2d5274a3677',
+  ref_fee_rate: 0.02,
+})
+
+// Update time range
+const start_time = Math.floor(Date.now() / 1000)
+const updateTimeTx = await sdk.Partner.updateTimeRangePayload({
+  partner_id: '0x9d171399393e3cbedffc24269eb606e735fb56fee17c15153eb5e2d5274a3677',
+  start_time,
+  end_time: start_time + 10 * 7 * 24 * 3600,
+})
+```
+
+### 7. Reward Operations
+
+#### Reward Management
+
+```typescript
+// Initialize rewards for a pool
+const initTx = sdk.Reward.initRewardPayload({
+  pool_id,
+  reward_coin_types: ['0x2::sui::SUI', '0x5::usdc::USDC']
+})
+
+// Add reward to a pool
+const addRewardTx = sdk.Reward.addRewardPayload({
+  pool_id,
+  reward_coin_type: '0x2::sui::SUI',
+  reward_amount: '1000000',
+  end_time_seconds: Math.floor(Date.now() / 1000) + 30 * 24 * 3600, // 30 days
+  start_time_seconds: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+})
+
+// Update reward access (public/private)
+const accessTx = sdk.Reward.updateRewardAccessPayload({
+  pool_id,
+  type: 'to_public', // or 'to_private'
+})
+
+// Manage reward whitelist
+const whitelistTx = sdk.Reward.updateRewardWhiteListPayload({
+  reward_coin_types: ['0x2::sui::SUI'],
+  type: 'add' // or 'remove'
+})
+```
+
+### 8. Bin Operations
+
+The SDK provides utility functions for working with bins and prices through the `BinUtils` class:
+
+```typescript
+import { BinUtils } from '@cetusprotocol/dlmm-sdk'
+
+// Convert price to bin ID
+const binId = BinUtils.getBinIdFromPrice(
+  '1040.07',  // price
+  2,          // bin step
+  true,       // is base coin A
+  6,          // decimals for coin A
+  9           // decimals for coin B
+)
+
+// Convert bin ID to price
+const price = BinUtils.getPriceFromBinId(
+  -4787,      // bin ID
+  2,          // bin step
+  6,          // decimals for coin A
+  9           // decimals for coin B
+)
+
+// Get Q price from bin ID
+const q_price = BinUtils.getQPriceFromId(
+  -4400,      // bin ID
+  100         // bin step
+)
+
+// Get price per lamport from Q price
+const price_per_lamport = BinUtils.getPricePerLamportFromQPrice(q_price)
+
+// Get liquidity from amounts
+const liquidity = BinUtils.getLiquidity('0', '266666', '18431994054197767090')
+
+// Get amount A from liquidity
+const amountA = BinUtils.getAmountAFromLiquidity('4101094304427826916657468', '18461505896777422276')
+
+// 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)
+```
+
+These utility functions are particularly useful when:
+- Setting up price ranges for liquidity positions
+- Calculating optimal bin ranges for trading strategies
+- Converting between different price representations
+- Managing liquidity distributions across bins
+
+### 9. Advanced Operations
+
+#### Validate Active ID Slippage
+
+```typescript
+// Validate that the active ID hasn't moved too much
+const isValid = await sdk.Position.validateActiveIdSlippage({
+  pool_id,
+  active_id,
+  max_bin_slippage: 0.01
+})
+```
+
+#### Update Position Fee and Rewards
+
+```typescript
+// Update position fee and reward information
+await sdk.Position.updatePositionFeeAndRewards({
+  pool_id,
+  position_id,
+  coin_type_a,
+  coin_type_b
+})
+```
+
+## 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
+