@cetusprotocol/aggregator-sdk 1.4.0 → 1.4.1

package/README.md

@@ -79,11 +79,11 @@ The new Aggregator Client V3 offers significant improvements over the previous v
 
 - **Increased Reliability**: More robust transaction execution with better error handling
 
-## Migration from Aggregator Client to V3
+## Migration from V2 to V3 API
 
 ### Installation
 
-Both versions use the same package:
+Both V2 and V3 APIs use the same package:
 
 ```bash
 npm install @cetusprotocol/aggregator-sdk
@@ -91,61 +91,67 @@ npm install @cetusprotocol/aggregator-sdk
 
 ### Key Changes
 
-1. **Client Initialization**
+**Important:** Both V2 and V3 use the same `AggregatorClient` class. The main differences are:
+- **Return types**: V3 uses `RouterDataV3` (with flattened `paths`) instead of V2's `RouterData` (with nested `routes`)
+- **Swap methods**: V3 introduces `fastRouterSwap()` for automatic coin handling
+- **Transaction structure**: V3 optimizes gas through transaction merging
+
+1. **Client Initialization (Same for both)**
 
    ```typescript
-   // V2 (Legacy)
-   const client = new AggregatorClient({})
+   import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"
 
-   // V3 (New)
-   const client = new AggregatorClient({})
+   const client = new AggregatorClient({
+     // Optional: Add custom configuration
+   })
    ```
 
-2. **Router Finding**
+2. **Router Finding (API unchanged, but return type differs)**
 
    ```typescript
-   // Both versions use the same API
+   import BN from "bn.js"
+
+   // Works with both V2 and V3
    const routers = await client.findRouters({
      from: "0x2::sui::SUI",
-     target:
-       "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
+     target: "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
      amount: new BN(1000000),
      byAmountIn: true,
    })
+
+   // V2 returns: RouterData with routes[]
+   // V3 returns: RouterDataV3 with paths[]
    ```
 
 3. **Transaction Building**
 
    ```typescript
-   // V2 Method
-   await client.buildRouterSwap({
-     routers,
-     txb,
-     inputCoin,
-     slippage: 0.01,
-   })
+   import { Transaction } from "@mysten/sui/transactions"
+
+   const txb = new Transaction()
 
-   // V3 Method (Recommended)
+   // V3 Method (Recommended) - Automatic coin handling
    await client.fastRouterSwap({
-     routers,
+     router: routers,
      txb,
      slippage: 0.01,
    })
 
-   // V3 Alternative (For PTB building)
+   // V3 Alternative - Manual coin handling for PTB building
    const targetCoin = await client.routerSwap({
-     routers,
+     router: routers,
      txb,
-     inputCoin,
+     inputCoin,  // TransactionObjectArgument
      slippage: 0.01,
    })
    ```
 
-4. **Benefits of Migration**
+4. **Benefits of V3 Migration**
    - Reduced gas costs through transaction merging
-   - Better transaction traceability
+   - Better transaction traceability on-chain
    - Improved error handling and reliability
    - Access to latest DEX integrations
+   - Automatic coin management with `fastRouterSwap()`
 
 ## Install
 
@@ -157,74 +163,208 @@ npm install @cetusprotocol/aggregator-sdk
 
 ## Usage
 
-### 1. Init client with rpc and package config
+### Complete Example with All Imports
 
 ```typescript
-const client = new AggregatorClient({})
+import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"
+import { Transaction } from "@mysten/sui/transactions"
+import BN from "bn.js"
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519"
+
+// Initialize your keypair (example using Ed25519)
+const keypair = Ed25519Keypair.deriveKeypair("your-mnemonic-phrase")
 ```
 
-### 2. Get best router swap result from aggregator service
+### 1. Initialize Client
 
 ```typescript
-const amount = new BN(1000000)
+import { Env } from "@cetusprotocol/aggregator-sdk"
+import { getFullnodeUrl, SuiClient } from "@mysten/sui/client"
+
+const client = new AggregatorClient({
+  // Optional configuration parameters:
+
+  // Network environment (default: Mainnet)
+  env: Env.Mainnet,  // or Env.Testnet
+
+  // Custom API endpoint for aggregator service
+  // endpoint: "https://api-sui.cetus.zone",
+
+  // Custom Sui client (default: mainnet RPC)
+  // client: new SuiClient({ url: getFullnodeUrl("mainnet") }),
+
+  // Partner ID for revenue sharing
+  // partner: "your-partner-id",
+
+  // CETUS DLMM specific partner ID
+  // cetusDlmmPartner: "your-dlmm-partner-id",
+
+  // Overlay fee rate (0 to 0.01 for 0-1%)
+  // overlayFeeRate: 0.001,  // 0.1%
+
+  // Overlay fee receiver address
+  // overlayFeeReceiver: "0x...",
+
+  // Custom Pyth oracle URLs
+  // pythUrls: ["https://hermes.pyth.network"],
+
+  // API key for rate limiting
+  // apiKey: "your-api-key",
+})
+```
+
+### 2. Find Best Router
+
+Get the optimal swap route from the aggregator service:
+
+```typescript
+const amount = new BN(1000000) // 1 SUI (with 6 decimals)
 const from = "0x2::sui::SUI"
-const target =
-  "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS"
+const target = "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS"
 
 const routers = await client.findRouters({
   from,
   target,
   amount,
-  byAmountIn: true, // true means fix input amount, false means fix output amount
+  byAmountIn: true, // true = fixed input amount, false = fixed output amount
+  // Optional parameters:
+  // depth: 3,  // Maximum number of hops
+  // providers: ["CETUS", "TURBOS"],  // Limit to specific DEXs
 })
+
+// Check if a valid route was found
+if (!routers || routers.insufficientLiquidity) {
+  console.error("No valid route found or insufficient liquidity")
+  process.exit(1)
+}
+
+console.log(`Expected output: ${routers.amountOut.toString()}`)
 ```
 
-### 3. Confirm and do fast swap
+### 3. Fast Swap (Recommended - Automatic Coin Handling)
+
+The easiest way to execute a swap with automatic coin management:
 
 ```typescript
 const txb = new Transaction()
 
-if (routerRes != null) {
-  await client.fastRouterSwap({
-    routers,
-    txb,
-    slippage: 0.01,
-  })
+await client.fastRouterSwap({
+  router: routers,
+  txb,
+  slippage: 0.01, // 1% slippage tolerance
+  // Optional:
+  // partner: "your-partner-id",
+  // payDeepFeeAmount: 1000000,  // For DeepBook V3 pools
+})
 
-  const result = await client.devInspectTransactionBlock(txb, keypair)
+// Simulate the transaction first
+const dryRunResult = await client.devInspectTransactionBlock(txb, keypair)
 
-  if (result.effects.status.status === "success") {
-    console.log("Sim exec transaction success")
-    const result = await client.signAndExecuteTransaction(txb, keypair)
-  }
-  console.log("result", result)
+if (dryRunResult.effects.status.status === "success") {
+  console.log("Simulation successful, executing transaction...")
+
+  // Execute the actual transaction
+  const result = await client.signAndExecuteTransaction(txb, keypair)
+  console.log("Transaction result:", result)
+} else {
+  console.error("Simulation failed:", dryRunResult.effects.status)
+}
+```
+
+### 4. Manual Swap (Advanced - For Custom PTB Building)
+
+Use this when you need to build complex programmable transaction blocks:
+
+```typescript
+import { coinWithBalance } from "@mysten/sui/transactions"
+
+const txb = new Transaction()
+
+// Create input coin object
+// Option 1: From existing coin object
+const inputCoin = txb.object("0x...") // Your coin object ID
+
+// Option 2: Create coin with specific balance
+// const inputCoin = coinWithBalance({
+//   type: from,
+//   balance: amount.toString()
+// })
+
+// Execute swap and get output coin
+const targetCoin = await client.routerSwap({
+  router: routers,
+  txb,
+  inputCoin,
+  slippage: 0.01, // 1% slippage tolerance
+  // Optional:
+  // partner: "your-partner-id",
+  // deepbookv3DeepFee: deepCoinObject,  // For DeepBook V3
+})
+
+// Use the target coin in your custom PTB logic
+// For example, transfer to recipient or use in another DeFi protocol
+txb.transferObjects([targetCoin], keypair.toSuiAddress())
+
+// Or destroy if sending to current address
+// client.transferOrDestroyCoin(txb, targetCoin, target)
+
+// Simulate and execute
+const dryRunResult = await client.devInspectTransactionBlock(txb, keypair)
+
+if (dryRunResult.effects.status.status === "success") {
+  console.log("Simulation successful, executing transaction...")
+  const result = await client.signAndExecuteTransaction(txb, keypair)
+  console.log("Transaction result:", result)
+} else {
+  console.error("Simulation failed:", dryRunResult.effects.status)
 }
 ```
 
-### 4. Build PTB and return target coin
+### 5. Advanced: Swap with Maximum Input Amount
+
+Protect against excessive input amounts:
 
 ```typescript
 const txb = new Transaction()
-const byAmountIn = true
-
-if (routerRes != null) {
-  const targetCoin = await client.routerSwap({
-    routers,
-    txb,
-    inputCoin,
-    slippage: 0.01,
+const inputCoin = txb.object("0x...") // Your coin object
+
+const targetCoin = await client.routerSwapWithMaxAmountIn({
+  router: routers,
+  txb,
+  inputCoin,
+  slippage: 0.01,
+  maxAmountIn: new BN(2000000), // Maximum 2 SUI allowed
+})
+
+// Transaction will abort if input amount exceeds maxAmountIn
+```
+
+### Error Handling
+
+```typescript
+try {
+  const routers = await client.findRouters({
+    from,
+    target,
+    amount,
+    byAmountIn: true,
   })
 
-  // you can use this target coin object argument to build your ptb.
-  client.transferOrDestoryCoin(txb, targetCoin, targetCoinType)
+  if (!routers) {
+    throw new Error("No route found")
+  }
 
-  const result = await client.devInspectTransactionBlock(txb, keypair)
+  if (routers.insufficientLiquidity) {
+    throw new Error("Insufficient liquidity for this swap")
+  }
 
-  if (result.effects.status.status === "success") {
-    console.log("Sim exec transaction success")
-    const result = await client.signAndExecuteTransaction(txb, keypair)
+  if (routers.error) {
+    throw new Error(`Router error: ${routers.error.msg}`)
   }
-  console.log("result", result)
+
+  // Proceed with swap...
+} catch (error) {
+  console.error("Swap failed:", error)
 }
 ```
 

package/dist/index.d.mts

@@ -9,7 +9,7 @@ import { Signer } from '@mysten/sui/cryptography';
 interface FindRouterParams {
     from: string;
     target: string;
-    amount: BN;
+    amount: BN | string | number | bigint;
     byAmountIn: boolean;
     depth?: number;
     splitAlgorithm?: string;
@@ -20,11 +20,11 @@ interface FindRouterParams {
 }
 interface MergeSwapFromCoin {
     coinType: string;
-    amount: BN | string | number;
+    amount: BN | string | number | bigint;
 }
 interface MergeSwapFromCoin {
     coinType: string;
-    amount: BN | string | number;
+    amount: BN | string | number | bigint;
 }
 interface MergeSwapParams {
     target: string;
@@ -394,9 +394,24 @@ declare class AggregatorClient {
     executeFlexibleInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, expectedAmountOut: string, amountLimit: string, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<void>;
     newDexRouterV3(provider: string, pythPriceIDs: Map<string, string>, partner?: string, cetusDlmmPartner?: string): DexRouter;
     expectInputSwapV3(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, expectAmountOut: string, amountOutLimit: string, pythPriceIDs: Map<string, string>, partner?: string, cetusDlmmPartner?: string): TransactionObjectArgument;
+    expectInputSwapV3WithMaxAmountIn(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, maxAmountIn: BN, expectAmountOut: string, amountOutLimit: string, pythPriceIDs: Map<string, string>, partner?: string, cetusDlmmPartner?: string): TransactionObjectArgument;
     expectOutputSwapV3(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, amountOut: string, _amountLimit: string, // it will set when build inputcoin
     partner?: string): TransactionObjectArgument;
+    expectOutputSwapV3WithMaxAmountIn(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, maxAmountIn: BN, amountOut: string, _amountLimit: string, // it will set when build inputcoin
+    partner?: string): TransactionObjectArgument;
     routerSwap(params: BuildRouterSwapParamsV3): Promise<TransactionObjectArgument>;
+    /**
+     * Router swap with max amount in validation.
+     * This method validates that the input coin amount does not exceed maxAmountIn.
+     * If the validation fails, the transaction will abort with an error.
+     *
+     * @param params - Router swap parameters with maxAmountIn
+     * @returns TransactionObjectArgument - The output coin from the swap
+     * @throws Error if input coin amount exceeds maxAmountIn
+     */
+    routerSwapWithMaxAmountIn(params: BuildRouterSwapParamsV3 & {
+        maxAmountIn: BN;
+    }): Promise<TransactionObjectArgument>;
     fastRouterSwap(params: BuildFastRouterSwapParamsV3): Promise<void>;
     mergeSwap(params: BuildMergeSwapParams): Promise<TransactionObjectArgument>;
     fastMergeSwap(params: BuildFastMergeSwapParams): Promise<void>;

package/dist/index.d.ts

@@ -9,7 +9,7 @@ import { Signer } from '@mysten/sui/cryptography';
 interface FindRouterParams {
     from: string;
     target: string;
-    amount: BN;
+    amount: BN | string | number | bigint;
     byAmountIn: boolean;
     depth?: number;
     splitAlgorithm?: string;
@@ -20,11 +20,11 @@ interface FindRouterParams {
 }
 interface MergeSwapFromCoin {
     coinType: string;
-    amount: BN | string | number;
+    amount: BN | string | number | bigint;
 }
 interface MergeSwapFromCoin {
     coinType: string;
-    amount: BN | string | number;
+    amount: BN | string | number | bigint;
 }
 interface MergeSwapParams {
     target: string;
@@ -394,9 +394,24 @@ declare class AggregatorClient {
     executeFlexibleInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, expectedAmountOut: string, amountLimit: string, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<void>;
     newDexRouterV3(provider: string, pythPriceIDs: Map<string, string>, partner?: string, cetusDlmmPartner?: string): DexRouter;
     expectInputSwapV3(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, expectAmountOut: string, amountOutLimit: string, pythPriceIDs: Map<string, string>, partner?: string, cetusDlmmPartner?: string): TransactionObjectArgument;
+    expectInputSwapV3WithMaxAmountIn(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, maxAmountIn: BN, expectAmountOut: string, amountOutLimit: string, pythPriceIDs: Map<string, string>, partner?: string, cetusDlmmPartner?: string): TransactionObjectArgument;
     expectOutputSwapV3(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, amountOut: string, _amountLimit: string, // it will set when build inputcoin
     partner?: string): TransactionObjectArgument;
+    expectOutputSwapV3WithMaxAmountIn(txb: Transaction, inputCoin: TransactionObjectArgument, routerData: RouterDataV3, maxAmountIn: BN, amountOut: string, _amountLimit: string, // it will set when build inputcoin
+    partner?: string): TransactionObjectArgument;
     routerSwap(params: BuildRouterSwapParamsV3): Promise<TransactionObjectArgument>;
+    /**
+     * Router swap with max amount in validation.
+     * This method validates that the input coin amount does not exceed maxAmountIn.
+     * If the validation fails, the transaction will abort with an error.
+     *
+     * @param params - Router swap parameters with maxAmountIn
+     * @returns TransactionObjectArgument - The output coin from the swap
+     * @throws Error if input coin amount exceeds maxAmountIn
+     */
+    routerSwapWithMaxAmountIn(params: BuildRouterSwapParamsV3 & {
+        maxAmountIn: BN;
+    }): Promise<TransactionObjectArgument>;
     fastRouterSwap(params: BuildFastRouterSwapParamsV3): Promise<void>;
     mergeSwap(params: BuildMergeSwapParams): Promise<TransactionObjectArgument>;
     fastMergeSwap(params: BuildFastMergeSwapParams): Promise<void>;

package/dist/index.js

@@ -3453,7 +3453,7 @@ var AGGREGATOR_V3_CONFIG = {
 };
 
 // src/api.ts
-var SDK_VERSION = 1010400;
+var SDK_VERSION = 1010401;
 function parseRouterResponse(data, byAmountIn) {
   let packages = /* @__PURE__ */ new Map();
   if (data.packages) {
@@ -7759,6 +7759,37 @@ function newSwapContext(params, txb) {
   });
   return swap_context;
 }
+function newSwapContextV2(params, txb) {
+  const {
+    quoteID,
+    fromCoinType,
+    targetCoinType,
+    maxAmountIn,
+    expectAmountOut,
+    amountOutLimit,
+    inputCoin,
+    feeRate,
+    feeRecipient,
+    aggregatorPublishedAt,
+    packages
+  } = params;
+  const publishedAt = getAggregatorPublishedAt(packages, aggregatorPublishedAt);
+  const args = [
+    txb.pure.string(quoteID),
+    txb.pure.u64(maxAmountIn.toString()),
+    txb.pure.u64(expectAmountOut.toString()),
+    txb.pure.u64(amountOutLimit.toString()),
+    inputCoin,
+    txb.pure.u32(Number(feeRate.toString())),
+    txb.pure.address(feeRecipient)
+  ];
+  const swap_context = txb.moveCall({
+    target: `${publishedAt}::router::new_swap_context_v2`,
+    typeArguments: [fromCoinType, targetCoinType],
+    arguments: args
+  });
+  return swap_context;
+}
 function confirmSwap(params, txb) {
   const { swapContext, targetCoinType, aggregatorPublishedAt, packages } = params;
   const publishedAt = getAggregatorPublishedAt(packages, aggregatorPublishedAt);
@@ -8760,6 +8791,53 @@ var _AggregatorClient = class _AggregatorClient {
     );
     return outputCoin;
   }
+  expectInputSwapV3WithMaxAmountIn(txb, inputCoin, routerData, maxAmountIn, expectAmountOut, amountOutLimit, pythPriceIDs, partner, cetusDlmmPartner) {
+    if (routerData.quoteID == null) {
+      throw new Error(CLIENT_CONFIG.ERRORS.QUOTE_ID_REQUIRED);
+    }
+    const processedData = processFlattenRoutes(routerData);
+    const swapCtx = newSwapContextV2(
+      {
+        quoteID: processedData.quoteID,
+        fromCoinType: processedData.fromCoinType,
+        targetCoinType: processedData.targetCoinType,
+        maxAmountIn,
+        expectAmountOut,
+        amountOutLimit,
+        inputCoin,
+        feeRate: this.overlayFeeRate,
+        feeRecipient: this.overlayFeeReceiver,
+        packages: processedData.packages
+      },
+      txb
+    );
+    let dexRouters = /* @__PURE__ */ new Map();
+    for (const flattenedPath of processedData.flattenedPaths) {
+      const path = flattenedPath.path;
+      if (!dexRouters.has(path.provider)) {
+        dexRouters.set(
+          path.provider,
+          this.newDexRouterV3(
+            path.provider,
+            pythPriceIDs,
+            partner,
+            cetusDlmmPartner
+          )
+        );
+      }
+      const dex = dexRouters.get(path.provider);
+      dex.swap(txb, flattenedPath, swapCtx, { pythPriceIDs });
+    }
+    const outputCoin = confirmSwap(
+      {
+        swapContext: swapCtx,
+        targetCoinType: processedData.targetCoinType,
+        packages: processedData.packages
+      },
+      txb
+    );
+    return outputCoin;
+  }
   expectOutputSwapV3(txb, inputCoin, routerData, amountOut, _amountLimit, partner) {
     const receipts = [];
     const dex = new CetusRouter(this.env, partner);
@@ -8869,6 +8947,116 @@ var _AggregatorClient = class _AggregatorClient {
     );
     return outputCoin;
   }
+  expectOutputSwapV3WithMaxAmountIn(txb, inputCoin, routerData, maxAmountIn, amountOut, _amountLimit, partner) {
+    const receipts = [];
+    const dex = new CetusRouter(this.env, partner);
+    const processedData = processFlattenRoutes(routerData);
+    const swapCtx = newSwapContextV2(
+      {
+        quoteID: processedData.quoteID,
+        fromCoinType: processedData.fromCoinType,
+        targetCoinType: processedData.targetCoinType,
+        maxAmountIn,
+        expectAmountOut: amountOut,
+        amountOutLimit: amountOut,
+        // amountOutLimit equals expectAmountOut when fix amout out
+        inputCoin,
+        feeRate: this.overlayFeeRate,
+        feeRecipient: this.overlayFeeReceiver,
+        packages: processedData.packages
+      },
+      txb
+    );
+    const firstCoinRecord = recordFirstCoinIndex(routerData.paths);
+    let needRepayRecord = /* @__PURE__ */ new Map();
+    let payRecord = /* @__PURE__ */ new Map();
+    for (let j = routerData.paths.length - 1; j >= 0; j--) {
+      const path = routerData.paths[j];
+      const firstFromTokenIndex = firstCoinRecord.get(path.from);
+      let amountArg;
+      if (j !== firstFromTokenIndex || path.target === processedData.targetCoinType) {
+        if (path.target !== processedData.targetCoinType) {
+          let payAmount = BigInt(path.amountOut);
+          if (payRecord.has(path.target)) {
+            const oldPayAmount = payRecord.get(path.target);
+            payAmount = oldPayAmount + payAmount;
+          }
+          payRecord.set(path.target, payAmount);
+        }
+        amountArg = txb.pure.u64(
+          path.amountOut.toString()
+        );
+      } else {
+        if (!needRepayRecord.has(path.target)) {
+          throw Error("no need repay record");
+        }
+        if (payRecord.has(path.target)) {
+          const oldPayAmount = payRecord.get(path.target);
+          const oldNeedRepay = needRepayRecord.get(path.target);
+          amountArg = dex.sub(
+            txb,
+            oldNeedRepay,
+            txb.pure.u64(oldPayAmount),
+            path.publishedAt
+          );
+        } else {
+          amountArg = needRepayRecord.get(path.target);
+        }
+      }
+      const flashSwapResult = dex.flashSwapFixedOutput(
+        txb,
+        path,
+        amountArg,
+        swapCtx
+      );
+      receipts.unshift(flashSwapResult.flashReceipt);
+      if (needRepayRecord.has(path.from)) {
+        const oldNeedRepay = needRepayRecord.get(path.from);
+        needRepayRecord.set(
+          path.from,
+          dex.add(
+            txb,
+            oldNeedRepay,
+            flashSwapResult.repayAmount,
+            path.publishedAt
+          )
+        );
+      } else {
+        needRepayRecord.set(path.from, flashSwapResult.repayAmount);
+      }
+    }
+    for (let j = 0; j < routerData.paths.length; j++) {
+      const path = routerData.paths[j];
+      dex.repayFlashSwapFixedOutput(txb, path, swapCtx, receipts[j]);
+    }
+    const remainInputBalance = takeBalance(
+      {
+        coinType: processedData.fromCoinType,
+        amount: U64_MAX,
+        swapCtx,
+        packages: processedData.packages
+      },
+      txb
+    );
+    transferBalance(
+      {
+        balance: remainInputBalance,
+        coinType: processedData.fromCoinType,
+        recipient: this.signer,
+        packages: processedData.packages
+      },
+      txb
+    );
+    const outputCoin = confirmSwap(
+      {
+        swapContext: swapCtx,
+        targetCoinType: processedData.targetCoinType,
+        packages: processedData.packages
+      },
+      txb
+    );
+    return outputCoin;
+  }
   routerSwap(params) {
     return __async(this, null, function* () {
       const { router, inputCoin, slippage, txb, partner } = params;
@@ -8919,6 +9107,67 @@ var _AggregatorClient = class _AggregatorClient {
       }
     });
   }
+  /**
+   * Router swap with max amount in validation.
+   * This method validates that the input coin amount does not exceed maxAmountIn.
+   * If the validation fails, the transaction will abort with an error.
+   *
+   * @param params - Router swap parameters with maxAmountIn
+   * @returns TransactionObjectArgument - The output coin from the swap
+   * @throws Error if input coin amount exceeds maxAmountIn
+   */
+  routerSwapWithMaxAmountIn(params) {
+    return __async(this, null, function* () {
+      const { router, inputCoin, slippage, txb, partner, maxAmountIn } = params;
+      if (slippage > 1 || slippage < 0) {
+        throw new Error(CLIENT_CONFIG.ERRORS.INVALID_SLIPPAGE);
+      }
+      if (!params.router.packages || !params.router.packages.get(PACKAGE_NAMES.AGGREGATOR_V3)) {
+        throw new Error(CLIENT_CONFIG.ERRORS.PACKAGES_REQUIRED);
+      }
+      const byAmountIn = params.router.byAmountIn;
+      const amountIn = router.amountIn;
+      const amountOut = router.amountOut;
+      checkOverlayFeeConfig(this.overlayFeeRate, this.overlayFeeReceiver);
+      let overlayFee = new import_bn6.default(0);
+      if (byAmountIn) {
+        overlayFee = amountOut.mul(new import_bn6.default(this.overlayFeeRate)).div(new import_bn6.default(1e6));
+      } else {
+        overlayFee = amountIn.mul(new import_bn6.default(this.overlayFeeRate)).div(new import_bn6.default(1e6));
+      }
+      const expectedAmountOut = byAmountIn ? amountOut.sub(overlayFee) : amountOut;
+      const expectedAmountIn = byAmountIn ? amountIn : amountIn.add(overlayFee);
+      const amountLimit = CalculateAmountLimitBN(
+        byAmountIn ? expectedAmountOut : expectedAmountIn,
+        byAmountIn,
+        slippage
+      );
+      const priceIDs = findPythPriceIDs(router.paths);
+      const priceInfoObjectIds = priceIDs.length > 0 ? yield this.updatePythPriceIDs(priceIDs, txb) : /* @__PURE__ */ new Map();
+      if (byAmountIn) {
+        return this.expectInputSwapV3WithMaxAmountIn(
+          txb,
+          inputCoin,
+          router,
+          maxAmountIn,
+          amountOut.toString(),
+          amountLimit.toString(),
+          priceInfoObjectIds,
+          partner != null ? partner : this.partner
+        );
+      } else {
+        return this.expectOutputSwapV3WithMaxAmountIn(
+          txb,
+          inputCoin,
+          router,
+          maxAmountIn,
+          amountOut.toString(),
+          amountLimit.toString(),
+          partner != null ? partner : this.partner
+        );
+      }
+    });
+  }
   // auto build input coin
   // auto merge, transfer or destory target coin.
   fastRouterSwap(params) {

package/dist/index.mjs

@@ -3447,7 +3447,7 @@ var AGGREGATOR_V3_CONFIG = {
 };
 
 // src/api.ts
-var SDK_VERSION = 1010400;
+var SDK_VERSION = 1010401;
 function parseRouterResponse(data, byAmountIn) {
   let packages = /* @__PURE__ */ new Map();
   if (data.packages) {
@@ -7753,6 +7753,37 @@ function newSwapContext(params, txb) {
   });
   return swap_context;
 }
+function newSwapContextV2(params, txb) {
+  const {
+    quoteID,
+    fromCoinType,
+    targetCoinType,
+    maxAmountIn,
+    expectAmountOut,
+    amountOutLimit,
+    inputCoin,
+    feeRate,
+    feeRecipient,
+    aggregatorPublishedAt,
+    packages
+  } = params;
+  const publishedAt = getAggregatorPublishedAt(packages, aggregatorPublishedAt);
+  const args = [
+    txb.pure.string(quoteID),
+    txb.pure.u64(maxAmountIn.toString()),
+    txb.pure.u64(expectAmountOut.toString()),
+    txb.pure.u64(amountOutLimit.toString()),
+    inputCoin,
+    txb.pure.u32(Number(feeRate.toString())),
+    txb.pure.address(feeRecipient)
+  ];
+  const swap_context = txb.moveCall({
+    target: `${publishedAt}::router::new_swap_context_v2`,
+    typeArguments: [fromCoinType, targetCoinType],
+    arguments: args
+  });
+  return swap_context;
+}
 function confirmSwap(params, txb) {
   const { swapContext, targetCoinType, aggregatorPublishedAt, packages } = params;
   const publishedAt = getAggregatorPublishedAt(packages, aggregatorPublishedAt);
@@ -8754,6 +8785,53 @@ var _AggregatorClient = class _AggregatorClient {
     );
     return outputCoin;
   }
+  expectInputSwapV3WithMaxAmountIn(txb, inputCoin, routerData, maxAmountIn, expectAmountOut, amountOutLimit, pythPriceIDs, partner, cetusDlmmPartner) {
+    if (routerData.quoteID == null) {
+      throw new Error(CLIENT_CONFIG.ERRORS.QUOTE_ID_REQUIRED);
+    }
+    const processedData = processFlattenRoutes(routerData);
+    const swapCtx = newSwapContextV2(
+      {
+        quoteID: processedData.quoteID,
+        fromCoinType: processedData.fromCoinType,
+        targetCoinType: processedData.targetCoinType,
+        maxAmountIn,
+        expectAmountOut,
+        amountOutLimit,
+        inputCoin,
+        feeRate: this.overlayFeeRate,
+        feeRecipient: this.overlayFeeReceiver,
+        packages: processedData.packages
+      },
+      txb
+    );
+    let dexRouters = /* @__PURE__ */ new Map();
+    for (const flattenedPath of processedData.flattenedPaths) {
+      const path = flattenedPath.path;
+      if (!dexRouters.has(path.provider)) {
+        dexRouters.set(
+          path.provider,
+          this.newDexRouterV3(
+            path.provider,
+            pythPriceIDs,
+            partner,
+            cetusDlmmPartner
+          )
+        );
+      }
+      const dex = dexRouters.get(path.provider);
+      dex.swap(txb, flattenedPath, swapCtx, { pythPriceIDs });
+    }
+    const outputCoin = confirmSwap(
+      {
+        swapContext: swapCtx,
+        targetCoinType: processedData.targetCoinType,
+        packages: processedData.packages
+      },
+      txb
+    );
+    return outputCoin;
+  }
   expectOutputSwapV3(txb, inputCoin, routerData, amountOut, _amountLimit, partner) {
     const receipts = [];
     const dex = new CetusRouter(this.env, partner);
@@ -8863,6 +8941,116 @@ var _AggregatorClient = class _AggregatorClient {
     );
     return outputCoin;
   }
+  expectOutputSwapV3WithMaxAmountIn(txb, inputCoin, routerData, maxAmountIn, amountOut, _amountLimit, partner) {
+    const receipts = [];
+    const dex = new CetusRouter(this.env, partner);
+    const processedData = processFlattenRoutes(routerData);
+    const swapCtx = newSwapContextV2(
+      {
+        quoteID: processedData.quoteID,
+        fromCoinType: processedData.fromCoinType,
+        targetCoinType: processedData.targetCoinType,
+        maxAmountIn,
+        expectAmountOut: amountOut,
+        amountOutLimit: amountOut,
+        // amountOutLimit equals expectAmountOut when fix amout out
+        inputCoin,
+        feeRate: this.overlayFeeRate,
+        feeRecipient: this.overlayFeeReceiver,
+        packages: processedData.packages
+      },
+      txb
+    );
+    const firstCoinRecord = recordFirstCoinIndex(routerData.paths);
+    let needRepayRecord = /* @__PURE__ */ new Map();
+    let payRecord = /* @__PURE__ */ new Map();
+    for (let j = routerData.paths.length - 1; j >= 0; j--) {
+      const path = routerData.paths[j];
+      const firstFromTokenIndex = firstCoinRecord.get(path.from);
+      let amountArg;
+      if (j !== firstFromTokenIndex || path.target === processedData.targetCoinType) {
+        if (path.target !== processedData.targetCoinType) {
+          let payAmount = BigInt(path.amountOut);
+          if (payRecord.has(path.target)) {
+            const oldPayAmount = payRecord.get(path.target);
+            payAmount = oldPayAmount + payAmount;
+          }
+          payRecord.set(path.target, payAmount);
+        }
+        amountArg = txb.pure.u64(
+          path.amountOut.toString()
+        );
+      } else {
+        if (!needRepayRecord.has(path.target)) {
+          throw Error("no need repay record");
+        }
+        if (payRecord.has(path.target)) {
+          const oldPayAmount = payRecord.get(path.target);
+          const oldNeedRepay = needRepayRecord.get(path.target);
+          amountArg = dex.sub(
+            txb,
+            oldNeedRepay,
+            txb.pure.u64(oldPayAmount),
+            path.publishedAt
+          );
+        } else {
+          amountArg = needRepayRecord.get(path.target);
+        }
+      }
+      const flashSwapResult = dex.flashSwapFixedOutput(
+        txb,
+        path,
+        amountArg,
+        swapCtx
+      );
+      receipts.unshift(flashSwapResult.flashReceipt);
+      if (needRepayRecord.has(path.from)) {
+        const oldNeedRepay = needRepayRecord.get(path.from);
+        needRepayRecord.set(
+          path.from,
+          dex.add(
+            txb,
+            oldNeedRepay,
+            flashSwapResult.repayAmount,
+            path.publishedAt
+          )
+        );
+      } else {
+        needRepayRecord.set(path.from, flashSwapResult.repayAmount);
+      }
+    }
+    for (let j = 0; j < routerData.paths.length; j++) {
+      const path = routerData.paths[j];
+      dex.repayFlashSwapFixedOutput(txb, path, swapCtx, receipts[j]);
+    }
+    const remainInputBalance = takeBalance(
+      {
+        coinType: processedData.fromCoinType,
+        amount: U64_MAX,
+        swapCtx,
+        packages: processedData.packages
+      },
+      txb
+    );
+    transferBalance(
+      {
+        balance: remainInputBalance,
+        coinType: processedData.fromCoinType,
+        recipient: this.signer,
+        packages: processedData.packages
+      },
+      txb
+    );
+    const outputCoin = confirmSwap(
+      {
+        swapContext: swapCtx,
+        targetCoinType: processedData.targetCoinType,
+        packages: processedData.packages
+      },
+      txb
+    );
+    return outputCoin;
+  }
   routerSwap(params) {
     return __async(this, null, function* () {
       const { router, inputCoin, slippage, txb, partner } = params;
@@ -8913,6 +9101,67 @@ var _AggregatorClient = class _AggregatorClient {
       }
     });
   }
+  /**
+   * Router swap with max amount in validation.
+   * This method validates that the input coin amount does not exceed maxAmountIn.
+   * If the validation fails, the transaction will abort with an error.
+   *
+   * @param params - Router swap parameters with maxAmountIn
+   * @returns TransactionObjectArgument - The output coin from the swap
+   * @throws Error if input coin amount exceeds maxAmountIn
+   */
+  routerSwapWithMaxAmountIn(params) {
+    return __async(this, null, function* () {
+      const { router, inputCoin, slippage, txb, partner, maxAmountIn } = params;
+      if (slippage > 1 || slippage < 0) {
+        throw new Error(CLIENT_CONFIG.ERRORS.INVALID_SLIPPAGE);
+      }
+      if (!params.router.packages || !params.router.packages.get(PACKAGE_NAMES.AGGREGATOR_V3)) {
+        throw new Error(CLIENT_CONFIG.ERRORS.PACKAGES_REQUIRED);
+      }
+      const byAmountIn = params.router.byAmountIn;
+      const amountIn = router.amountIn;
+      const amountOut = router.amountOut;
+      checkOverlayFeeConfig(this.overlayFeeRate, this.overlayFeeReceiver);
+      let overlayFee = new import_bn6.default(0);
+      if (byAmountIn) {
+        overlayFee = amountOut.mul(new import_bn6.default(this.overlayFeeRate)).div(new import_bn6.default(1e6));
+      } else {
+        overlayFee = amountIn.mul(new import_bn6.default(this.overlayFeeRate)).div(new import_bn6.default(1e6));
+      }
+      const expectedAmountOut = byAmountIn ? amountOut.sub(overlayFee) : amountOut;
+      const expectedAmountIn = byAmountIn ? amountIn : amountIn.add(overlayFee);
+      const amountLimit = CalculateAmountLimitBN(
+        byAmountIn ? expectedAmountOut : expectedAmountIn,
+        byAmountIn,
+        slippage
+      );
+      const priceIDs = findPythPriceIDs(router.paths);
+      const priceInfoObjectIds = priceIDs.length > 0 ? yield this.updatePythPriceIDs(priceIDs, txb) : /* @__PURE__ */ new Map();
+      if (byAmountIn) {
+        return this.expectInputSwapV3WithMaxAmountIn(
+          txb,
+          inputCoin,
+          router,
+          maxAmountIn,
+          amountOut.toString(),
+          amountLimit.toString(),
+          priceInfoObjectIds,
+          partner != null ? partner : this.partner
+        );
+      } else {
+        return this.expectOutputSwapV3WithMaxAmountIn(
+          txb,
+          inputCoin,
+          router,
+          maxAmountIn,
+          amountOut.toString(),
+          amountLimit.toString(),
+          partner != null ? partner : this.partner
+        );
+      }
+    });
+  }
   // auto build input coin
   // auto merge, transfer or destory target coin.
   fastRouterSwap(params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cetusprotocol/aggregator-sdk",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",