@cetusprotocol/aggregator-sdk 1.4.3 → 1.4.5

package/README.md

@@ -29,129 +29,7 @@ Multi-Platform Support: Currently, we have integrated multiple mainstream DEXs o
 
 By using our aggregator, you can trade more efficiently and securely on the Sui blockchain, fully leveraging the various opportunities brought by decentralized finance (DeFi).
 
-## Supported Providers
-
-The Cetus Aggregator SDK supports 25+ decentralized exchanges (DEXs) on the Sui blockchain:
-
-- **Cetus**
-- **DeepBook V3**
-- **Kriya V2/V3**
-- **FlowX V2/V3**
-- **Turbos**
-- **Aftermath**
-- **Haedal**
-- **Volo**
-- **AfSui**
-- **Bluemove**
-- **Scallop**
-- **Suilend**
-- **Bluefin**
-- **HaedalHMM**
-- **Alphafi**
-- **SpringSui**
-- **Steamm CPMM**
-- **Steamm OMM**
-- **Metastable**
-- **Obric**
-- **HaWAL**
-- **Momentum**
-- **Magma**
-- **Sevenk**
-
-# Aggregator SDK V3
-
-## Advantages of Aggregator Client V3
-
-The new Aggregator Client V3 offers significant improvements over the previous version:
-
-### Transaction Traceability
-
-- **Complete Transaction History**: All swap transactions are fully traceable on the blockchain
-- **Detailed Route Information**: Track exactly which DEXs and pools were used in multi-hop swaps
-- **Gas Optimization Transparency**: See how transactions were optimized to reduce gas costs
-
-### Transaction Merging for Gas Optimization
-
-- **Reduced Gas Costs**: Significantly lower transaction fees through optimized execution paths
-- **Smart Route Aggregation**: Automatically combines similar operations to minimize gas usage
-
-### Enhanced Features
-
-- **Increased Reliability**: More robust transaction execution with better error handling
-
-## Migration from V2 to V3 API
-
-### Installation
-
-Both V2 and V3 APIs use the same package:
-
-```bash
-npm install @cetusprotocol/aggregator-sdk
-```
-
-### Key Changes
-
-**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
-   import { AggregatorClient } from "@cetusprotocol/aggregator-sdk"
-
-   const client = new AggregatorClient({
-     // Optional: Add custom configuration
-   })
-   ```
-
-2. **Router Finding (API unchanged, but return type differs)**
-
-   ```typescript
-   import BN from "bn.js"
-
-   // Works with both V2 and V3
-   const routers = await client.findRouters({
-     from: "0x2::sui::SUI",
-     target: "0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS",
-     amount: new BN(1000000),
-     byAmountIn: true,
-   })
-
-   // V2 returns: RouterData with routes[]
-   // V3 returns: RouterDataV3 with paths[]
-   ```
-
-3. **Transaction Building**
-
-   ```typescript
-   import { Transaction } from "@mysten/sui/transactions"
-
-   const txb = new Transaction()
-
-   // V3 Method (Recommended) - Automatic coin handling
-   await client.fastRouterSwap({
-     router: routers,
-     txb,
-     slippage: 0.01,
-   })
-
-   // V3 Alternative - Manual coin handling for PTB building
-   const targetCoin = await client.routerSwap({
-     router: routers,
-     txb,
-     inputCoin,  // TransactionObjectArgument
-     slippage: 0.01,
-   })
-   ```
-
-4. **Benefits of V3 Migration**
-   - Reduced gas costs through transaction merging
-   - Better transaction traceability on-chain
-   - Improved error handling and reliability
-   - Access to latest DEX integrations
-   - Automatic coin management with `fastRouterSwap()`
+# Aggregator SDK
 
 ## Install
 
@@ -163,208 +41,74 @@ npm install @cetusprotocol/aggregator-sdk
 
 ## Usage
 
-### Complete Example with All Imports
+### 1. Init client with rpc and package config
 
 ```typescript
-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")
+const client = new AggregatorClient({})
 ```
 
-### 1. Initialize Client
+### 2. Get best router swap result from aggregator service
 
 ```typescript
-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 amount = new BN(1000000)
 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 = 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. Fast Swap (Recommended - Automatic Coin Handling)
-
-The easiest way to execute a swap with automatic coin management:
-
-```typescript
-const txb = new Transaction()
-
-await client.fastRouterSwap({
-  router: routers,
-  txb,
-  slippage: 0.01, // 1% slippage tolerance
-  // Optional:
-  // partner: "your-partner-id",
-  // payDeepFeeAmount: 1000000,  // For DeepBook V3 pools
+  byAmountIn: true, // true means fix input amount, false means fix output amount
 })
-
-// Simulate the transaction first
-const dryRunResult = await client.devInspectTransactionBlock(txb, keypair)
-
-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:
+### 3. Confirm and do fast swap
 
 ```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)
+if (routerRes != null) {
+  await client.fastRouterSwap({
+    routers,
+    txb,
+    slippage: 0.01,
+  })
 
-// Simulate and execute
-const dryRunResult = await client.devInspectTransactionBlock(txb, keypair)
+  const result = 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)
+  if (result.effects.status.status === "success") {
+    console.log("Sim exec transaction success")
+    const result = await client.signAndExecuteTransaction(txb, keypair)
+  }
+  console.log("result", result)
 }
 ```
 
-### 5. Advanced: Swap with Maximum Input Amount
-
-Protect against excessive input amounts:
+### 4. Build PTB and return target coin
 
 ```typescript
 const txb = new Transaction()
-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,
+const byAmountIn = true
+
+if (routerRes != null) {
+  const targetCoin = await client.routerSwap({
+    routers,
+    txb,
+    inputCoin,
+    slippage: 0.01,
   })
 
-  if (!routers) {
-    throw new Error("No route found")
-  }
+  // you can use this target coin object argument to build your ptb.
+  client.transferOrDestoryCoin(txb, targetCoin, targetCoinType)
 
-  if (routers.insufficientLiquidity) {
-    throw new Error("Insufficient liquidity for this swap")
-  }
+  const result = await client.devInspectTransactionBlock(txb, keypair)
 
-  if (routers.error) {
-    throw new Error(`Router error: ${routers.error.msg}`)
+  if (result.effects.status.status === "success") {
+    console.log("Sim exec transaction success")
+    const result = await client.signAndExecuteTransaction(txb, keypair)
   }
-
-  // Proceed with swap...
-} catch (error) {
-  console.error("Swap failed:", error)
+  console.log("result", result)
 }
 ```
 
@@ -374,34 +118,34 @@ try {
 
 | Contract                  | Tag of Repo | Latest published at address                                        |
 | ------------------------- | ----------- | ------------------------------------------------------------------ |
-| CetusAggregatorV2         | mainnet     | 0x3864c7c59a4889fec05d1aae4bc9dba5a0e0940594b424fbed44cb3f6ac4c032 |
-| CetusAggregatorV2ExtendV1 | mainnet     | 0x39402d188b7231036e52266ebafad14413b4bf3daea4ac17115989444e6cd516 |
-| CetusAggregatorV2ExtendV2 | mainnet     | 0x368d13376443a8051b22b42a9125f6a3bc836422bb2d9c4a53984b8d6624c326 |
+| CetusAggregatorV2         | mainnet     | 0x40e457bc65a398d2db7026881358fcb7cfa2f1bb052bca41f46c55a1103f2d6f |
+| CetusAggregatorV2ExtendV1 | mainnet     | 0x2edc22bf96c85482b2208624fa9339255d5055113c92fd6c33add48ce971b774 |
+| CetusAggregatorV2ExtendV2 | mainnet     | 0x2e227a3cbc6715518b18ed339d2f967153674b7b257da114ca62c72b2011258a |
 
 ## Example
 
 ```
-CetusAggregatorV2 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/mainnet", rev = "mainnet", override = true }
+CetusAggregatorV2 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/mainnet", rev = "mainnet-v1.56.0", override = true }
 
-CetusAggregatorV2ExtendV1 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2-extend-v1", rev = "mainnet", override = true }
+CetusAggregatorV2ExtendV1 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2-extend-v1", rev = "mainnet-v1.56.0", override = true }
 
-CetusAggregatorV2ExtendV2 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2-extend-v2", rev = "mainnet", override = true }
+CetusAggregatorV2ExtendV2 = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2-extend-v2", rev = "mainnet-v1.56.0", override = true }
 ```
 
 # Simple Aggregator Contract Interface
 
-- include: cetus, flowxv3, turbos, bluefin, haedalhmm, momentum, obric
+- include: cetus, flowxv3, turbos, bluefin, haedalhmm, momentum, obric, deepbookv3
 
 ## Tags corresponding to different networks
 
 | Contract              | Tag of Repo | Latest published at address                                        |
 | --------------------- | ----------- | ------------------------------------------------------------------ |
-| CetusAggregatorSimple | mainnet     | 0x44ca6438ab034be95cedfca7d4070e6d33fa12e088e9dce13abb1bf055093264 |
+| CetusAggregatorSimple | mainnet     | 0x54394cb5bceb8073c60df0964b904a607c9974ef771d9e8b3f9c45b8ce075499 |
 
 ## Example
 
 ```
-CetusAggregatorSimple = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/simple-mainnet", rev = "mainnet-v1.50.2", override = true }
+CetusAggregatorSimple = { git = "https://github.com/CetusProtocol/aggregator.git", subdir = "packages/cetus-aggregator-v2/simple-mainnet", rev = "mainnet-v1.58.0", override = true }
 ```
 
 ## Usage