@cetusprotocol/dlmm-sdk 0.0.7 → 0.0.9

package/README.md

@@ -281,6 +281,109 @@ console.log('Variable fee:', variableFee)
 console.log('Variable fee percentage:', d(variableFee).div(d(FEE_PRECISION)).toString())
 ```
 
+**getTotalFeeRate Return Value**
+
+The `getTotalFeeRate` method returns a `FeeRate` object containing the following fields:
+
+```typescript
+type FeeRate = {
+  base_fee_rate: string    // Base fee rate
+  var_fee_rate: string     // Variable fee rate
+  total_fee_rate: string   // Total fee rate
+}
+```
+
+**Field Descriptions:**
+
+- **`base_fee_rate`**: Base fee rate, calculated from the pool's `bin_step` and `base_factor`, is a fixed value
+- **`var_fee_rate`**: Variable fee rate, dynamically calculated based on the pool's volatility accumulator (`volatility_accumulator`), changes with market volatility
+- **`total_fee_rate`**: Total fee rate, equals `base_fee_rate + var_fee_rate`, but will not exceed the maximum fee rate limit (`MAX_FEE_RATE = 100,000,000`)
+
+**Fee Rate Precision:**
+- All fee rate values use `FEE_PRECISION = 1,000,000,000` as the precision unit
+- To get the actual percentage, divide the fee rate value by `FEE_PRECISION`
+- Example: If `total_fee_rate` is `3000000`, the actual fee rate is `3000000 / 1000000000 = 0.003 = 0.3%`
+
+**Usage Example:**
+```typescript
+const feeRate = await sdk.Pool.getTotalFeeRate({
+  pool_id: "0x...",
+  coin_type_a: "0x...",
+  coin_type_b: "0x..."
+})
+
+// Calculate actual percentages
+const baseFeePercentage = d(feeRate.base_fee_rate).div(d(FEE_PRECISION)).mul(100).toString()
+const varFeePercentage = d(feeRate.var_fee_rate).div(d(FEE_PRECISION)).mul(100).toString()
+const totalFeePercentage = d(feeRate.total_fee_rate).div(d(FEE_PRECISION)).mul(100).toString()
+
+console.log(`Base fee rate: ${baseFeePercentage}%`)
+console.log(`Variable fee rate: ${varFeePercentage}%`)
+console.log(`Total fee rate: ${totalFeePercentage}%`)
+```
+
+#### FeeUtils Utility Methods
+
+The `FeeUtils` class provides several utility methods for fee calculations:
+
+**1. `getVariableFee(variableParameters: VariableParameters): string`**
+
+Calculates the variable fee based on pool parameters and market volatility.
+
+```typescript
+import { FeeUtils } from '@cetusprotocol/dlmm-sdk'
+
+const variableFee = FeeUtils.getVariableFee(pool.variable_parameters)
+console.log('Variable fee:', variableFee)
+console.log('Variable fee percentage:', d(variableFee).div(d(FEE_PRECISION)).toString())
+```
+
+**2. `calculateCompositionFee(amount: string, total_fee_rate: string): string`**
+
+Calculates composition fees for liquidity operations.
+
+```typescript
+const compositionFee = FeeUtils.calculateCompositionFee(amount, total_fee_rate)
+```
+
+**3. `calculateProtocolFee(fee_amount: string, protocol_fee_rate: string): string`**
+
+Calculates protocol fees based on fee amount and protocol fee rate.
+
+```typescript
+const protocolFee = FeeUtils.calculateProtocolFee(fee_amount, protocol_fee_rate)
+```
+
+**4. `getProtocolFees(fee_a: string, fee_b: string, protocol_fee_rate: string)`**
+
+Calculates protocol fees for both tokens in a pair.
+
+```typescript
+const { protocol_fee_a, protocol_fee_b } = FeeUtils.getProtocolFees(fee_a, fee_b, protocol_fee_rate)
+console.log('Protocol fee A:', protocol_fee_a)
+console.log('Protocol fee B:', protocol_fee_b)
+```
+
+**5. `getCompositionFees(active_bin: BinAmount, used_bin: BinAmount, variableParameters: VariableParameters)`**
+
+Calculates composition fees for active and used bins, considering variable parameters.
+
+```typescript
+const { fees_a, fees_b } = FeeUtils.getCompositionFees(active_bin, used_bin, variableParameters)
+console.log('Composition fees A:', fees_a)
+console.log('Composition fees B:', fees_b)
+```
+
+**FeeUtils Methods Summary:**
+
+| Method                    | Description                                 | Parameters                                     | Returns                            |
+| ------------------------- | ------------------------------------------- | ---------------------------------------------- | ---------------------------------- |
+| `getVariableFee`          | Calculate variable fee from pool parameters | `variableParameters`                           | `string`                           |
+| `calculateCompositionFee` | Calculate composition fee for an amount     | `amount`, `total_fee_rate`                     | `string`                           |
+| `calculateProtocolFee`    | Calculate protocol fee                      | `fee_amount`, `protocol_fee_rate`              | `string`                           |
+| `getProtocolFees`         | Calculate protocol fees for both tokens     | `fee_a`, `fee_b`, `protocol_fee_rate`          | `{protocol_fee_a, protocol_fee_b}` |
+| `getCompositionFees`      | Calculate composition fees for bins         | `active_bin`, `used_bin`, `variableParameters` | `{fees_a, fees_b}`                 |
+
 #### Fee and Reward Collection
 
 You can collect fees from your positions in several ways:
@@ -296,18 +399,6 @@ 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)
 ```
@@ -759,17 +850,28 @@ const tx = sdk.Partner.createPartnerPayload({
 
 // Update referral fee rate
 const updateFeeTx = await sdk.Partner.updateRefFeeRatePayload({
-  partner_id: '0x9d171399393e3cbedffc24269eb606e735fb56fee17c15153eb5e2d5274a3677',
+  partner_id: '0x..',
   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',
+  partner_id: '0x..',
   start_time,
   end_time: start_time + 10 * 7 * 24 * 3600,
 })
+
+// claim ref fee
+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)
+
 ```
 
 ### 7. Reward Operations

package/dist/index.d.mts

@@ -474,13 +474,13 @@ declare class PoolModule implements IModule<CetusDlmmSDK> {
      * @param tx - The transaction object
      * @returns The transaction object
      */
-    createPoolPayload(option: CreatePoolOption, tx: Transaction): Promise<TransactionObjectArgument>;
+    createPoolPayload(option: CreatePoolOption, tx: Transaction): TransactionObjectArgument;
     /**
      * Create a pool and add liquidity
      * @param option - The option for creating a pool and adding liquidity
      * @returns The transaction for creating a pool and adding liquidity
      */
-    createPoolAndAddLiquidityPayload(option: CreatePoolAndAddOption): Promise<Transaction>;
+    createPoolAndAddLiquidityPayload(option: CreatePoolAndAddOption): Transaction;
 }
 
 declare class PositionModule implements IModule<CetusDlmmSDK> {
@@ -1023,6 +1023,44 @@ declare class FeeUtils {
     };
 }
 
+type IlmInputOptions = {
+    curvature: number;
+    initial_price: string;
+    max_price: string;
+    bin_step: number;
+    total_supply: string;
+    pool_share_percentage: number;
+    config: {
+        price_curve_points_num: number;
+        liquidity_distribution_num: number;
+        tokens_table_num: number;
+        price_table_num: number;
+    };
+};
+type Axis = {
+    x: string;
+    y: string;
+};
+type TokenTable = {
+    withdrawn: string;
+    price: string;
+    usdc_in_pool: string;
+};
+type IlmInputResult = {
+    price_curve: Axis[];
+    liquidity_curve: Axis[];
+    dlmm_bins: Axis[];
+    tokens_table: TokenTable[];
+    price_table: TokenTable[];
+    initial_fdv: string;
+    final_fdv: string;
+    usdc_in_pool: string;
+};
+
+declare class IlmUtils {
+    static calculateIlm(options: IlmInputOptions): IlmInputResult;
+}
+
 declare const MAX_BIN_PER_POSITION = 1000;
 declare const MIN_BIN_ID = -443636;
 declare const MAX_BIN_ID = 443636;
@@ -1040,4 +1078,4 @@ declare const dlmmMainnet: SdkOptions;
 
 declare const dlmmTestnet: SdkOptions;
 
-export { type AddLiquidityOption, type AddRewardOption, BASIS_POINT, BASIS_POINT_MAX, BIN_BOUND, type BaseAddLiquidityOption, type BaseCalculateAddLiquidityOption, type BaseCreatePoolAndAddOption, type BaseCreatePoolOption, type BinAmount, type BinLiquidityInfo, type BinManager, type BinStepConfig, type BinSwap, BinUtils, type BinWeight, type CalculateAddLiquidityAutoFillOption, type CalculateAddLiquidityOption, type CalculateRemoveLiquidityBothOption, type CalculateRemoveLiquidityOnlyOption, CetusDlmmSDK, type ClaimRefFeeOption, type ClosePositionOption, type CollectFeeOption, type CollectRewardAndFeeOption, type CollectRewardOption, type CreatePartnerOption, type CreatePoolAndAddOption, type CreatePoolAndAddWithPriceOption, type CreatePoolOption, DEFAULT_MAX_WEIGHT, DEFAULT_MIN_WEIGHT, type DlmmBasePool, type DlmmConfigs, type DlmmGlobalConfig, type DlmmPool, type DlmmPosition, FEE_PRECISION, type FeeRate, FeeUtils, type GetPoolBinInfoOption, type GetTotalFeeRateOption, type InitRewardOption, MAX_BIN_ID, MAX_BIN_PER_POSITION, MAX_FEE_RATE, MIN_BIN_ID, ONE, type OpenAndAddLiquidityOption, type OpenAndAddLiquidityWithPriceOption, type OpenPositionOption, type Partner, PoolModule, type PoolPermissions, type PoolTransactionInfo, type PositionFee, type PositionManager, type PositionReward, type PreSwapOption, type PreSwapQuote, REWARD_PERIOD, REWARD_PERIOD_START_AT, type RemoveLiquidityOption, type Reward, type RewardAccessOption, type RewardInfo, type RewardManager, type RewardPeriodEmission, type RewardPeriodEmissionFormat, type RewardWhiteListOption, SCALE_OFFSET, type SdkOptions, StrategyType, StrategyUtils, type SwapOption, type UpdatePositionFeeAndRewardsOption, type UpdateRefFeeRateOption, type UpdateTimeRangeOption, type ValidateActiveIdSlippageOption, type VariableParameters, WeightUtils, type WeightsInfo, type WeightsOptions, buildPoolKey, CetusDlmmSDK as default, dlmmMainnet, dlmmTestnet, generateRewardSchedule, getRouterModule, parseBinInfo, parseBinInfoList, parseCurrentRewardPeriodEmission, parseDlmmBasePool, parseDlmmPool, parseDlmmPosition, parseLiquidityShares, parsePartner, parsePoolTransactionInfo, parseRewardPeriodEmission, parseStrategyType, parsedDlmmPosFeeData, parsedDlmmPosRewardData, parsedSwapQuoteData, poolFilterEvenTypes, safeAmount, safeMulAmount };
+export { type AddLiquidityOption, type AddRewardOption, type Axis, BASIS_POINT, BASIS_POINT_MAX, BIN_BOUND, type BaseAddLiquidityOption, type BaseCalculateAddLiquidityOption, type BaseCreatePoolAndAddOption, type BaseCreatePoolOption, type BinAmount, type BinLiquidityInfo, type BinManager, type BinStepConfig, type BinSwap, BinUtils, type BinWeight, type CalculateAddLiquidityAutoFillOption, type CalculateAddLiquidityOption, type CalculateRemoveLiquidityBothOption, type CalculateRemoveLiquidityOnlyOption, CetusDlmmSDK, type ClaimRefFeeOption, type ClosePositionOption, type CollectFeeOption, type CollectRewardAndFeeOption, type CollectRewardOption, type CreatePartnerOption, type CreatePoolAndAddOption, type CreatePoolAndAddWithPriceOption, type CreatePoolOption, DEFAULT_MAX_WEIGHT, DEFAULT_MIN_WEIGHT, type DlmmBasePool, type DlmmConfigs, type DlmmGlobalConfig, type DlmmPool, type DlmmPosition, FEE_PRECISION, type FeeRate, FeeUtils, type GetPoolBinInfoOption, type GetTotalFeeRateOption, type IlmInputOptions, type IlmInputResult, IlmUtils, type InitRewardOption, MAX_BIN_ID, MAX_BIN_PER_POSITION, MAX_FEE_RATE, MIN_BIN_ID, ONE, type OpenAndAddLiquidityOption, type OpenAndAddLiquidityWithPriceOption, type OpenPositionOption, type Partner, PoolModule, type PoolPermissions, type PoolTransactionInfo, type PositionFee, type PositionManager, type PositionReward, type PreSwapOption, type PreSwapQuote, REWARD_PERIOD, REWARD_PERIOD_START_AT, type RemoveLiquidityOption, type Reward, type RewardAccessOption, type RewardInfo, type RewardManager, type RewardPeriodEmission, type RewardPeriodEmissionFormat, type RewardWhiteListOption, SCALE_OFFSET, type SdkOptions, StrategyType, StrategyUtils, type SwapOption, type TokenTable, type UpdatePositionFeeAndRewardsOption, type UpdateRefFeeRateOption, type UpdateTimeRangeOption, type ValidateActiveIdSlippageOption, type VariableParameters, WeightUtils, type WeightsInfo, type WeightsOptions, buildPoolKey, CetusDlmmSDK as default, dlmmMainnet, dlmmTestnet, generateRewardSchedule, getRouterModule, parseBinInfo, parseBinInfoList, parseCurrentRewardPeriodEmission, parseDlmmBasePool, parseDlmmPool, parseDlmmPosition, parseLiquidityShares, parsePartner, parsePoolTransactionInfo, parseRewardPeriodEmission, parseStrategyType, parsedDlmmPosFeeData, parsedDlmmPosRewardData, parsedSwapQuoteData, poolFilterEvenTypes, safeAmount, safeMulAmount };

package/dist/index.d.ts

@@ -474,13 +474,13 @@ declare class PoolModule implements IModule<CetusDlmmSDK> {
      * @param tx - The transaction object
      * @returns The transaction object
      */
-    createPoolPayload(option: CreatePoolOption, tx: Transaction): Promise<TransactionObjectArgument>;
+    createPoolPayload(option: CreatePoolOption, tx: Transaction): TransactionObjectArgument;
     /**
      * Create a pool and add liquidity
      * @param option - The option for creating a pool and adding liquidity
      * @returns The transaction for creating a pool and adding liquidity
      */
-    createPoolAndAddLiquidityPayload(option: CreatePoolAndAddOption): Promise<Transaction>;
+    createPoolAndAddLiquidityPayload(option: CreatePoolAndAddOption): Transaction;
 }
 
 declare class PositionModule implements IModule<CetusDlmmSDK> {
@@ -1023,6 +1023,44 @@ declare class FeeUtils {
     };
 }
 
+type IlmInputOptions = {
+    curvature: number;
+    initial_price: string;
+    max_price: string;
+    bin_step: number;
+    total_supply: string;
+    pool_share_percentage: number;
+    config: {
+        price_curve_points_num: number;
+        liquidity_distribution_num: number;
+        tokens_table_num: number;
+        price_table_num: number;
+    };
+};
+type Axis = {
+    x: string;
+    y: string;
+};
+type TokenTable = {
+    withdrawn: string;
+    price: string;
+    usdc_in_pool: string;
+};
+type IlmInputResult = {
+    price_curve: Axis[];
+    liquidity_curve: Axis[];
+    dlmm_bins: Axis[];
+    tokens_table: TokenTable[];
+    price_table: TokenTable[];
+    initial_fdv: string;
+    final_fdv: string;
+    usdc_in_pool: string;
+};
+
+declare class IlmUtils {
+    static calculateIlm(options: IlmInputOptions): IlmInputResult;
+}
+
 declare const MAX_BIN_PER_POSITION = 1000;
 declare const MIN_BIN_ID = -443636;
 declare const MAX_BIN_ID = 443636;
@@ -1040,4 +1078,4 @@ declare const dlmmMainnet: SdkOptions;
 
 declare const dlmmTestnet: SdkOptions;
 
-export { type AddLiquidityOption, type AddRewardOption, BASIS_POINT, BASIS_POINT_MAX, BIN_BOUND, type BaseAddLiquidityOption, type BaseCalculateAddLiquidityOption, type BaseCreatePoolAndAddOption, type BaseCreatePoolOption, type BinAmount, type BinLiquidityInfo, type BinManager, type BinStepConfig, type BinSwap, BinUtils, type BinWeight, type CalculateAddLiquidityAutoFillOption, type CalculateAddLiquidityOption, type CalculateRemoveLiquidityBothOption, type CalculateRemoveLiquidityOnlyOption, CetusDlmmSDK, type ClaimRefFeeOption, type ClosePositionOption, type CollectFeeOption, type CollectRewardAndFeeOption, type CollectRewardOption, type CreatePartnerOption, type CreatePoolAndAddOption, type CreatePoolAndAddWithPriceOption, type CreatePoolOption, DEFAULT_MAX_WEIGHT, DEFAULT_MIN_WEIGHT, type DlmmBasePool, type DlmmConfigs, type DlmmGlobalConfig, type DlmmPool, type DlmmPosition, FEE_PRECISION, type FeeRate, FeeUtils, type GetPoolBinInfoOption, type GetTotalFeeRateOption, type InitRewardOption, MAX_BIN_ID, MAX_BIN_PER_POSITION, MAX_FEE_RATE, MIN_BIN_ID, ONE, type OpenAndAddLiquidityOption, type OpenAndAddLiquidityWithPriceOption, type OpenPositionOption, type Partner, PoolModule, type PoolPermissions, type PoolTransactionInfo, type PositionFee, type PositionManager, type PositionReward, type PreSwapOption, type PreSwapQuote, REWARD_PERIOD, REWARD_PERIOD_START_AT, type RemoveLiquidityOption, type Reward, type RewardAccessOption, type RewardInfo, type RewardManager, type RewardPeriodEmission, type RewardPeriodEmissionFormat, type RewardWhiteListOption, SCALE_OFFSET, type SdkOptions, StrategyType, StrategyUtils, type SwapOption, type UpdatePositionFeeAndRewardsOption, type UpdateRefFeeRateOption, type UpdateTimeRangeOption, type ValidateActiveIdSlippageOption, type VariableParameters, WeightUtils, type WeightsInfo, type WeightsOptions, buildPoolKey, CetusDlmmSDK as default, dlmmMainnet, dlmmTestnet, generateRewardSchedule, getRouterModule, parseBinInfo, parseBinInfoList, parseCurrentRewardPeriodEmission, parseDlmmBasePool, parseDlmmPool, parseDlmmPosition, parseLiquidityShares, parsePartner, parsePoolTransactionInfo, parseRewardPeriodEmission, parseStrategyType, parsedDlmmPosFeeData, parsedDlmmPosRewardData, parsedSwapQuoteData, poolFilterEvenTypes, safeAmount, safeMulAmount };
+export { type AddLiquidityOption, type AddRewardOption, type Axis, BASIS_POINT, BASIS_POINT_MAX, BIN_BOUND, type BaseAddLiquidityOption, type BaseCalculateAddLiquidityOption, type BaseCreatePoolAndAddOption, type BaseCreatePoolOption, type BinAmount, type BinLiquidityInfo, type BinManager, type BinStepConfig, type BinSwap, BinUtils, type BinWeight, type CalculateAddLiquidityAutoFillOption, type CalculateAddLiquidityOption, type CalculateRemoveLiquidityBothOption, type CalculateRemoveLiquidityOnlyOption, CetusDlmmSDK, type ClaimRefFeeOption, type ClosePositionOption, type CollectFeeOption, type CollectRewardAndFeeOption, type CollectRewardOption, type CreatePartnerOption, type CreatePoolAndAddOption, type CreatePoolAndAddWithPriceOption, type CreatePoolOption, DEFAULT_MAX_WEIGHT, DEFAULT_MIN_WEIGHT, type DlmmBasePool, type DlmmConfigs, type DlmmGlobalConfig, type DlmmPool, type DlmmPosition, FEE_PRECISION, type FeeRate, FeeUtils, type GetPoolBinInfoOption, type GetTotalFeeRateOption, type IlmInputOptions, type IlmInputResult, IlmUtils, type InitRewardOption, MAX_BIN_ID, MAX_BIN_PER_POSITION, MAX_FEE_RATE, MIN_BIN_ID, ONE, type OpenAndAddLiquidityOption, type OpenAndAddLiquidityWithPriceOption, type OpenPositionOption, type Partner, PoolModule, type PoolPermissions, type PoolTransactionInfo, type PositionFee, type PositionManager, type PositionReward, type PreSwapOption, type PreSwapQuote, REWARD_PERIOD, REWARD_PERIOD_START_AT, type RemoveLiquidityOption, type Reward, type RewardAccessOption, type RewardInfo, type RewardManager, type RewardPeriodEmission, type RewardPeriodEmissionFormat, type RewardWhiteListOption, SCALE_OFFSET, type SdkOptions, StrategyType, StrategyUtils, type SwapOption, type TokenTable, type UpdatePositionFeeAndRewardsOption, type UpdateRefFeeRateOption, type UpdateTimeRangeOption, type ValidateActiveIdSlippageOption, type VariableParameters, WeightUtils, type WeightsInfo, type WeightsOptions, buildPoolKey, CetusDlmmSDK as default, dlmmMainnet, dlmmTestnet, generateRewardSchedule, getRouterModule, parseBinInfo, parseBinInfoList, parseCurrentRewardPeriodEmission, parseDlmmBasePool, parseDlmmPool, parseDlmmPosition, parseLiquidityShares, parsePartner, parsePoolTransactionInfo, parseRewardPeriodEmission, parseStrategyType, parsedDlmmPosFeeData, parsedDlmmPosRewardData, parsedSwapQuoteData, poolFilterEvenTypes, safeAmount, safeMulAmount };