@cetusprotocol/dlmm-sdk 0.0.8 → 0.1.0

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:

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> {

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> {