@cetusprotocol/aggregator-sdk 0.4.4 → 0.5.0

package/README.md

@@ -43,10 +43,12 @@ npm install @cetusprotocol/aggregator-sdk
 
 1. Fast init:
   ```typescript
-    const client = new AggregatorClient()
+    const client = new AggregatorClient({})
   ```
 
 2. Full init:
+> Note: overlayFeeRate and overlayFeeReceiver are used for additional fee logic beyond protocol fees, allowing project parties to collect extra fees.
+
   ```typescript
     const client = new AggregatorClient({
       // endpoint, // If you do not have a exclusive aggregator api domain，just use cetus default aggregator endpoints.
@@ -54,6 +56,9 @@ npm install @cetusprotocol/aggregator-sdk
       client: suiClient,
       env: Env.Mainnet,
       pythUrls: ["YOUR_PYTH_URL", "ANOTHER_PYTH_URL"],
+      partner: "YOUR_PARTNER_ID", // Partner ID for fee sharing. Set once during initialization instead of per swap.
+      overlayFeeRate: 0.01, // Overlay fee rate (0.01 represents 1%). The denominator is 1000000, so 0.01% = 100
+      overlayFeeReceiver: "0x..", // Address to receive the overlay fees
     })
   ```
 **Notes**: Some providers, such as HaedalHMM and Metastable, rely on Pyth oracle prices when build transactions. Currently, we have a default configuration that connects to Pyth's publicly available node. However, if you frequently build transactions, we recommend setting up a private Pyth node interface as an additional backup. This will ensure uninterrupted access to HaedalHMM and Metastable, even if the public node experiences occasional downtime.
@@ -75,7 +80,6 @@ const routers = await client.findRouters({
 ```
 
 ## 3. Confirm and do fast swap
-
 ```typescript
 const routerTx = new Transaction()
 
@@ -85,16 +89,22 @@ if (routerRes != null) {
     txb: routerTx,
     slippage: 0.01,
     isMergeTragetCoin: true,
-    refreshAllCoins: true,
+    refreshAllCoins: true
   })
 
   let result = await client.devInspectTransactionBlock(routerTx, keypair)
 
   if (result.effects.status.status === "success") {
-    console.log("Sim exec transaction success")
+    console.log("[Cetus] Transaction simulation successful")
     const result = await client.signAndExecuteTransaction(routerTx, keypair)
+    console.log("[Cetus] Transaction executed successfully:", {
+      digest: result.digest,
+      status: result.effects?.status,
+      gasUsed: result.effects?.gasUsed
+    })
+  } else {
+    console.error("[Cetus] Transaction simulation failed:", result.effects?.status)
   }
-  console.log("result", result)
 }
 ```
 
@@ -113,7 +123,7 @@ if (routerRes != null) {
   })
 
   // you can use this target coin object argument to build your ptb.
-  const client.transferOrDestoryCoin(
+  client.transferOrDestroyCoin(
       txb,
       targetCoin,
       targetCoinType
@@ -122,10 +132,16 @@ if (routerRes != null) {
   let result = await client.devInspectTransactionBlock(routerTx, keypair)
 
   if (result.effects.status.status === "success") {
-    console.log("Sim exec transaction success")
+    console.log("[Cetus] Transaction simulation successful")
     const result = await client.signAndExecuteTransaction(routerTx, keypair)
+    console.log("[Cetus] Transaction executed successfully:", {
+      digest: result.digest,
+      status: result.effects?.status,
+      gasUsed: result.effects?.gasUsed
+    })
+  } else {
+    console.error("[Cetus] Transaction simulation failed:", result.effects?.status)
   }
-  console.log("result", result)
 }
 ```
 

package/dist/index.d.mts

@@ -83,6 +83,7 @@ declare const SPRINGSUI = "SPRINGSUI";
 declare const STEAMM = "STEAMM";
 declare const METASTABLE = "METASTABLE";
 declare const OBRIC = "OBRIC";
+declare const HAWAL = "HAWAL";
 declare const DEFAULT_ENDPOINT = "https://api-sui.cetus.zone/router_v2";
 type BuildRouterSwapParams = {
     routers: Router[];
@@ -136,6 +137,9 @@ type AggregatorClientParams = {
     env?: Env;
     pythUrls?: string[];
     apiKey?: string;
+    partner?: string;
+    overlayFeeRate?: number;
+    overlayFeeReceiver?: string;
 };
 declare class AggregatorClient {
     endpoint: string;
@@ -146,13 +150,16 @@ declare class AggregatorClient {
     private allCoins;
     private pythConnections;
     private pythClient;
+    private overlayFeeRate;
+    private overlayFeeReceiver;
+    private partner?;
     private static readonly CONFIG;
     constructor(params: AggregatorClientParams);
     newPythClients(pythUrls: string[]): SuiPriceServiceConnection[];
     getCoins(coinType: string, refresh?: boolean): Promise<CoinAsset[]>;
     findRouters(params: FindRouterParams): Promise<RouterData | null>;
-    executeFlexibleInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], amountOutLimit: BN, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
-    expectInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], amountOutLimit: BN, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
+    executeFlexibleInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], expectedAmountOut: string, amountLimit: string, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
+    expectInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], expectedAmountOut: string, amountLimit: string, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
     expectOutputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], partner?: string, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
     swapInPools(params: SwapInPoolsParams): Promise<SwapInPoolsResult | null>;
     routerSwap(params: BuildRouterSwapParams | BuildRouterSwapParamsV2): Promise<TransactionObjectArgument>;
@@ -162,7 +169,7 @@ declare class AggregatorClient {
     publishedAtV2Extend(): string;
     deepbookv3DeepFeeType(): string;
     transferOrDestoryCoin(txb: Transaction, coin: TransactionObjectArgument, coinType: string, aggregatorV2PublishedAt: string): void;
-    checkCoinThresholdAndMergeCoin(txb: Transaction, coins: TransactionObjectArgument[], coinType: string, amountLimit: BN, aggregatorV2PublishedAt: string): TransactionObjectArgument;
+    checkCoinThresholdAndMergeCoin(txb: Transaction, coins: TransactionObjectArgument[], coinType: string, expectedAmountOut: string, threshold: string, aggregatorV2ExtendPublishedAt: string): TransactionObjectArgument;
     newDex(provider: string, pythPriceIDs: Map<string, string>, partner?: string): Dex;
     signAndExecuteTransaction(txb: Transaction, signer: Signer): Promise<_mysten_sui_client.SuiTransactionBlockResponse>;
     devInspectTransactionBlock(txb: Transaction): Promise<_mysten_sui_client.DevInspectResults>;
@@ -301,13 +308,14 @@ type RouterData = {
     packages?: Map<string, string>;
     totalDeepFee?: number;
     error?: RouterError;
+    overlayFee?: number;
 };
 type AggregatorResponse = {
     code: number;
     msg: string;
     data: RouterData;
 };
-declare function getRouterResult(endpoint: string, apiKey: string, params: FindRouterParams): Promise<RouterData | null>;
+declare function getRouterResult(endpoint: string, apiKey: string, params: FindRouterParams, overlayFee: number, overlayFeeReceiver: string): Promise<RouterData | null>;
 type DeepbookV3Config = {
     id: string;
     is_alternative_payment: boolean;
@@ -332,4 +340,4 @@ declare enum Env {
     Testnet = 1
 }
 
-export { AFSUI, AFTERMATH, AGGREGATOR_V2, AGGREGATOR_V2_EXTEND, ALPHAFI, AggregatorClient, type AggregatorClientParams, type AggregatorResponse, BLUEFIN, BLUEMOVE, type BuildCoinResult, type BuildFastRouterSwapParams, type BuildFastRouterSwapParamsV2, type BuildRouterSwapParams, type BuildRouterSwapParamsV2, CETUS, CLOCK_ADDRESS, DEEPBOOKV2, DEEPBOOKV3, DEFAULT_ENDPOINT, type DeepbookV3Config, type DeepbookV3ConfigResponse, type Dex, Env, type ExtendedDetails, FLOWXV2, FLOWXV3, type FindRouterParams, HAEDAL, HAEDALPMM, KRIYA, KRIYAV3, METASTABLE, OBRIC, ONE, type Path, type PreSwapLpChangeParams, type Router, type RouterData, type RouterError, SCALLOP, SPRINGSUI, STEAMM, SUILEND, type SwapInPoolsParams, type SwapInPoolsResult, TEN_POW_NINE, TURBOS, TWO, U128, U64_MAX, U64_MAX_BN, VOLO, ZERO, buildInputCoin, checkInvalidSuiAddress, compareCoins, completionCoin, composeType, createTarget, dealWithFastRouterSwapParamsForMsafe, extractAddressFromType, extractStructTagFromType, findPythPriceIDs, fixSuiObjectId, getAggregatorV2ExtendPublishedAt, getAggregatorV2PublishedAt, getDeepbookV3Config, getRouterResult, isSortedSymbols, mintZeroCoin, normalizeCoinType, parseRouterResponse, patchFixSuiObjectId, printTransaction, processEndpoint, restituteMsafeFastRouterSwapParams };
+export { AFSUI, AFTERMATH, AGGREGATOR_V2, AGGREGATOR_V2_EXTEND, ALPHAFI, AggregatorClient, type AggregatorClientParams, type AggregatorResponse, BLUEFIN, BLUEMOVE, type BuildCoinResult, type BuildFastRouterSwapParams, type BuildFastRouterSwapParamsV2, type BuildRouterSwapParams, type BuildRouterSwapParamsV2, CETUS, CLOCK_ADDRESS, DEEPBOOKV2, DEEPBOOKV3, DEFAULT_ENDPOINT, type DeepbookV3Config, type DeepbookV3ConfigResponse, type Dex, Env, type ExtendedDetails, FLOWXV2, FLOWXV3, type FindRouterParams, HAEDAL, HAEDALPMM, HAWAL, KRIYA, KRIYAV3, METASTABLE, OBRIC, ONE, type Path, type PreSwapLpChangeParams, type Router, type RouterData, type RouterError, SCALLOP, SPRINGSUI, STEAMM, SUILEND, type SwapInPoolsParams, type SwapInPoolsResult, TEN_POW_NINE, TURBOS, TWO, U128, U64_MAX, U64_MAX_BN, VOLO, ZERO, buildInputCoin, checkInvalidSuiAddress, compareCoins, completionCoin, composeType, createTarget, dealWithFastRouterSwapParamsForMsafe, extractAddressFromType, extractStructTagFromType, findPythPriceIDs, fixSuiObjectId, getAggregatorV2ExtendPublishedAt, getAggregatorV2PublishedAt, getDeepbookV3Config, getRouterResult, isSortedSymbols, mintZeroCoin, normalizeCoinType, parseRouterResponse, patchFixSuiObjectId, printTransaction, processEndpoint, restituteMsafeFastRouterSwapParams };

package/dist/index.d.ts

@@ -83,6 +83,7 @@ declare const SPRINGSUI = "SPRINGSUI";
 declare const STEAMM = "STEAMM";
 declare const METASTABLE = "METASTABLE";
 declare const OBRIC = "OBRIC";
+declare const HAWAL = "HAWAL";
 declare const DEFAULT_ENDPOINT = "https://api-sui.cetus.zone/router_v2";
 type BuildRouterSwapParams = {
     routers: Router[];
@@ -136,6 +137,9 @@ type AggregatorClientParams = {
     env?: Env;
     pythUrls?: string[];
     apiKey?: string;
+    partner?: string;
+    overlayFeeRate?: number;
+    overlayFeeReceiver?: string;
 };
 declare class AggregatorClient {
     endpoint: string;
@@ -146,13 +150,16 @@ declare class AggregatorClient {
     private allCoins;
     private pythConnections;
     private pythClient;
+    private overlayFeeRate;
+    private overlayFeeReceiver;
+    private partner?;
     private static readonly CONFIG;
     constructor(params: AggregatorClientParams);
     newPythClients(pythUrls: string[]): SuiPriceServiceConnection[];
     getCoins(coinType: string, refresh?: boolean): Promise<CoinAsset[]>;
     findRouters(params: FindRouterParams): Promise<RouterData | null>;
-    executeFlexibleInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], amountOutLimit: BN, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
-    expectInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], amountOutLimit: BN, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
+    executeFlexibleInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], expectedAmountOut: string, amountLimit: string, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
+    expectInputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], expectedAmountOut: string, amountLimit: string, pythPriceIDs: Map<string, string>, partner?: string, deepbookv3DeepFee?: TransactionObjectArgument, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
     expectOutputSwap(txb: Transaction, inputCoin: TransactionObjectArgument, routers: Router[], partner?: string, packages?: Map<string, string>): Promise<TransactionObjectArgument>;
     swapInPools(params: SwapInPoolsParams): Promise<SwapInPoolsResult | null>;
     routerSwap(params: BuildRouterSwapParams | BuildRouterSwapParamsV2): Promise<TransactionObjectArgument>;
@@ -162,7 +169,7 @@ declare class AggregatorClient {
     publishedAtV2Extend(): string;
     deepbookv3DeepFeeType(): string;
     transferOrDestoryCoin(txb: Transaction, coin: TransactionObjectArgument, coinType: string, aggregatorV2PublishedAt: string): void;
-    checkCoinThresholdAndMergeCoin(txb: Transaction, coins: TransactionObjectArgument[], coinType: string, amountLimit: BN, aggregatorV2PublishedAt: string): TransactionObjectArgument;
+    checkCoinThresholdAndMergeCoin(txb: Transaction, coins: TransactionObjectArgument[], coinType: string, expectedAmountOut: string, threshold: string, aggregatorV2ExtendPublishedAt: string): TransactionObjectArgument;
     newDex(provider: string, pythPriceIDs: Map<string, string>, partner?: string): Dex;
     signAndExecuteTransaction(txb: Transaction, signer: Signer): Promise<_mysten_sui_client.SuiTransactionBlockResponse>;
     devInspectTransactionBlock(txb: Transaction): Promise<_mysten_sui_client.DevInspectResults>;
@@ -301,13 +308,14 @@ type RouterData = {
     packages?: Map<string, string>;
     totalDeepFee?: number;
     error?: RouterError;
+    overlayFee?: number;
 };
 type AggregatorResponse = {
     code: number;
     msg: string;
     data: RouterData;
 };
-declare function getRouterResult(endpoint: string, apiKey: string, params: FindRouterParams): Promise<RouterData | null>;
+declare function getRouterResult(endpoint: string, apiKey: string, params: FindRouterParams, overlayFee: number, overlayFeeReceiver: string): Promise<RouterData | null>;
 type DeepbookV3Config = {
     id: string;
     is_alternative_payment: boolean;
@@ -332,4 +340,4 @@ declare enum Env {
     Testnet = 1
 }
 
-export { AFSUI, AFTERMATH, AGGREGATOR_V2, AGGREGATOR_V2_EXTEND, ALPHAFI, AggregatorClient, type AggregatorClientParams, type AggregatorResponse, BLUEFIN, BLUEMOVE, type BuildCoinResult, type BuildFastRouterSwapParams, type BuildFastRouterSwapParamsV2, type BuildRouterSwapParams, type BuildRouterSwapParamsV2, CETUS, CLOCK_ADDRESS, DEEPBOOKV2, DEEPBOOKV3, DEFAULT_ENDPOINT, type DeepbookV3Config, type DeepbookV3ConfigResponse, type Dex, Env, type ExtendedDetails, FLOWXV2, FLOWXV3, type FindRouterParams, HAEDAL, HAEDALPMM, KRIYA, KRIYAV3, METASTABLE, OBRIC, ONE, type Path, type PreSwapLpChangeParams, type Router, type RouterData, type RouterError, SCALLOP, SPRINGSUI, STEAMM, SUILEND, type SwapInPoolsParams, type SwapInPoolsResult, TEN_POW_NINE, TURBOS, TWO, U128, U64_MAX, U64_MAX_BN, VOLO, ZERO, buildInputCoin, checkInvalidSuiAddress, compareCoins, completionCoin, composeType, createTarget, dealWithFastRouterSwapParamsForMsafe, extractAddressFromType, extractStructTagFromType, findPythPriceIDs, fixSuiObjectId, getAggregatorV2ExtendPublishedAt, getAggregatorV2PublishedAt, getDeepbookV3Config, getRouterResult, isSortedSymbols, mintZeroCoin, normalizeCoinType, parseRouterResponse, patchFixSuiObjectId, printTransaction, processEndpoint, restituteMsafeFastRouterSwapParams };
+export { AFSUI, AFTERMATH, AGGREGATOR_V2, AGGREGATOR_V2_EXTEND, ALPHAFI, AggregatorClient, type AggregatorClientParams, type AggregatorResponse, BLUEFIN, BLUEMOVE, type BuildCoinResult, type BuildFastRouterSwapParams, type BuildFastRouterSwapParamsV2, type BuildRouterSwapParams, type BuildRouterSwapParamsV2, CETUS, CLOCK_ADDRESS, DEEPBOOKV2, DEEPBOOKV3, DEFAULT_ENDPOINT, type DeepbookV3Config, type DeepbookV3ConfigResponse, type Dex, Env, type ExtendedDetails, FLOWXV2, FLOWXV3, type FindRouterParams, HAEDAL, HAEDALPMM, HAWAL, KRIYA, KRIYAV3, METASTABLE, OBRIC, ONE, type Path, type PreSwapLpChangeParams, type Router, type RouterData, type RouterError, SCALLOP, SPRINGSUI, STEAMM, SUILEND, type SwapInPoolsParams, type SwapInPoolsResult, TEN_POW_NINE, TURBOS, TWO, U128, U64_MAX, U64_MAX_BN, VOLO, ZERO, buildInputCoin, checkInvalidSuiAddress, compareCoins, completionCoin, composeType, createTarget, dealWithFastRouterSwapParamsForMsafe, extractAddressFromType, extractStructTagFromType, findPythPriceIDs, fixSuiObjectId, getAggregatorV2ExtendPublishedAt, getAggregatorV2PublishedAt, getDeepbookV3Config, getRouterResult, isSortedSymbols, mintZeroCoin, normalizeCoinType, parseRouterResponse, patchFixSuiObjectId, printTransaction, processEndpoint, restituteMsafeFastRouterSwapParams };