@scallop-io/scallop-swap-sdk 1.3.2 → 2.1.0

package/README.md

@@ -1,3 +1,34 @@
 ### Scallop Swap Meta Aggregator SDK
 
 A unified SDK that aggregates existing swap aggregators on Sui, including Aftermath, Cetus, 7K, and FlowX and provides a generic `SwapSdkBase` class for seamless integration and extension with future swap aggregators.
+
+#### Adding a Custom SDK Integration
+
+Extend `SwapSdkBase` with your own SDK-specific generic types:
+
+```typescript
+import { SwapSdkBase, SwapSdkConstructorParams } from '@scallop-io/scallop-swap-sdk';
+
+class MyDexSwap extends SwapSdkBase<MyPoolType, MyRawRoute, MyFetchSettings, MyClient> {
+  constructor(params: SwapSdkConstructorParams<MyFetchSettings>) {
+    super('mydex', params);
+    this.client = new MyClient(/* ... */);
+  }
+
+  // Implement abstract methods: fetchRoute, buildSwapTransaction, setFetchRouteSettings, calcSlippage
+}
+```
+
+To get type-safe access via `aggregator.getAggregator('mydex')`, extend the `SdkRegistry` interface using declaration merging:
+
+```typescript
+declare module '@scallop-io/scallop-swap-sdk' {
+  interface SdkRegistry {
+    mydex: MyDexSwap;
+  }
+}
+
+// Now fully typed:
+const mydex = aggregator.getAggregator('mydex'); // MyDexSwap | undefined
+mydex?.client; // MyClient | undefined
+```

package/dist/index.d.mts

@@ -3,13 +3,17 @@ import { SuiClient, CoinMetadata, SuiTransactionBlockResponse, DryRunTransaction
 import { Transaction, TransactionObjectArgument } from '@mysten/sui/transactions';
 import { EventEmitter } from 'events';
 import * as _scallop_io_sui_kit from '@scallop-io/sui-kit';
-import { SuiKitParams, AccountManagerParams, SuiKit, Transaction as Transaction$1, TransactionObjectArgument as TransactionObjectArgument$1 } from '@scallop-io/sui-kit';
+import { SuiKitParams, AccountManagerParams, Transaction as Transaction$1, TransactionObjectArgument as TransactionObjectArgument$1, SuiKit } from '@scallop-io/sui-kit';
 import * as _mysten_sui_dist_cjs_transactions from '@mysten/sui/dist/cjs/transactions';
 import { RouterDataV3, FindRouterParams, AggregatorClient, AggregatorClientParams } from '@cetusprotocol/aggregator-sdk';
+export { AggregatorClient, RouterDataV3 } from '@cetusprotocol/aggregator-sdk';
 import * as aftermath_ts_sdk from 'aftermath-ts-sdk';
 import { RouterProtocolName, RouterCompleteTradeRoute, ApiRouterPartialCompleteTradeRouteBody, Aftermath, AftermathApi, ConfigAddresses } from 'aftermath-ts-sdk';
+export { Aftermath, RouterCompleteTradeRoute } from 'aftermath-ts-sdk';
 import { SourceDex, QuoteResponse, Commission } from '@7kprotocol/sdk-ts';
-import { Protocol, GetRoutesResult, Coin as Coin$1, SingleQuoteQueryParams, Commission as Commission$1 } from '@flowx-finance/sdk';
+export { QuoteResponse } from '@7kprotocol/sdk-ts';
+import { Protocol, GetRoutesResult, Coin as Coin$1, SingleQuoteQueryParams, AggregatorQuoter, Commission as Commission$1 } from '@flowx-finance/sdk';
+export { AggregatorQuoter, GetRoutesResult } from '@flowx-finance/sdk';
 
 type SecretKeyOrMnemonicsOrWalletAddress = {
     mnemonics: string;
@@ -96,7 +100,7 @@ type SwapBuildResult<MergeResult extends boolean> = MergeResult extends true ? {
     coinOut: TransactionObjectArgument;
 };
 interface SwapSdkConstructorParams<T> {
-    client?: SuiClient;
+    suiClient?: SuiClient;
     fetchTimeoutInMs?: number;
     walletAddress: string;
     fetchSettings?: T;
@@ -104,7 +108,11 @@ interface SwapSdkConstructorParams<T> {
 /**
  * Base interface for Swap SDK
  */
-interface SwapSdkBaseInterface<PoolType = string, RawRouteResultType = any, FetchRouteSettings = any> {
+interface SwapSdkBaseInterface<PoolType = string, RawRouteResultType = any, FetchRouteSettings = any, SdkClient = SuiClient> {
+    /**
+     * SDK specific client
+     */
+    client?: SdkClient;
     /**
      * How long the route fetch request should wait before timing out (in milliseconds)
      */
@@ -197,11 +205,12 @@ declare class TypedEventEmitter<Events extends Record<string, any>> extends Even
     emit<K extends keyof Events & (string | symbol)>(event: K, payload: Events[K]): boolean;
 }
 
-declare abstract class SwapSdkBase<PoolType = string, RawRouteResultType = any, FetchRouteSettings = any> implements SwapSdkBaseInterface<PoolType, RawRouteResultType, FetchRouteSettings> {
+declare abstract class SwapSdkBase<PoolType = string, RawRouteResultType = any, FetchRouteSettings = any, SdkClient = any> implements SwapSdkBaseInterface<PoolType, RawRouteResultType, FetchRouteSettings, SdkClient> {
     protected rawRouteResult?: RawRouteResultType;
     readonly name: string;
     readonly events: TypedEventEmitter<SwapSdkEvents<PoolType>>;
-    client: SuiClient;
+    client?: SdkClient;
+    suiClient: SuiClient;
     fetchTimeoutInMs?: number;
     walletAddress: string;
     fetchSettings?: FetchRouteSettings;
@@ -211,8 +220,8 @@ declare abstract class SwapSdkBase<PoolType = string, RawRouteResultType = any,
     protected validateWalletAddress(): asserts this is typeof SwapSdkBase & {
         walletAddress: string;
     };
-    protected validateRawRouteResult(): asserts this is typeof SwapSdkBase & {
-        rawRouteResult: RawRouteResultType;
+    protected validateClient(): asserts this is typeof SwapSdkBase & {
+        client: SdkClient;
     };
     setWalletAddress(address: string): void;
     setSuiClient(client: SuiClient): void;
@@ -239,111 +248,28 @@ declare abstract class SwapSdkBase<PoolType = string, RawRouteResultType = any,
     }>;
 }
 
-declare class CoinMetadataRegistry {
-    client: SuiClient;
-    private cache;
-    constructor(client: SuiClient, initialData?: (CoinMetadata & {
-        coinType: string;
-    })[]);
-    setClient(client: SuiClient): void;
-    getCoinMetadata(coinType: string): Promise<CoinMetadata>;
-}
-
-type TxExt = {
-    initTx: Transaction;
-    coinIn: TransactionObjectArgument;
-};
-type BuildOptionsBase = {
-    slippage?: number;
-    txExtensionParams?: TxExt;
-};
-declare class Aggregator {
-    #private;
-    readonly coinMetadata: CoinMetadataRegistry;
-    readonly suiKit: SuiKit | undefined;
-    readonly events: TypedEventEmitter<AggregatorEvents<string>>;
-    protected _slippage: number;
-    private signerMode;
-    private aggregatorMap;
-    private activeAggregator;
-    private _fetchingStatus;
-    private poolStatusForwarders;
-    walletAddress: string;
-    client: SuiClient;
-    constructor(params: AggregatorConstructorParams);
-    private forwardPoolStatusChangeEvent;
-    addAggregator(aggregator: SwapSdkBase[]): void;
-    getActiveAggregators(): string[];
-    getAggregator(name: string): SwapSdkBase<string, any, any> | undefined;
-    toggleAggregator(name: string, enabled: boolean): void;
-    removeAggregator(name: string): void;
-    get aggregators(): SwapSdkBase<string, any, any>[];
-    /**
-     * Per-aggregator fetching status. True while that aggregator's fetchRoute is in-flight.
-     */
-    get fetchingStatus(): Record<string, boolean>;
-    /**
-     * Get slippage (0.01 = 1%)
-     */
-    get slippage(): number;
-    /**
-     * Set slippage (0.01 = 1%)
-     * @param slippageInDecimal
-     */
-    setSlippage(slippageInDecimal: number): void;
-    /**
-     * Set fetch timeout in milliseconds for all aggregators
-     * @param timeoutInMs
-     */
-    setFetchTimeoutInMs(timeoutInMs: number): void;
-    setSuiClient(client: SuiClient): void;
-    setWalletAddress(address: string): void;
-    getCoinMetadata(coinType: string): Promise<_mysten_sui_dist_cjs_client.CoinMetadata>;
-    /**
-     * Fetch swap routes from all aggregators, and sort them by best output amount
-     * @param params FetchRouteParams
-     * @param options FetchRoutesOptions
-     */
-    fetchRoutes(params: FetchRouteParams, options?: FetchRoutesOptions): Promise<{
-        routes: FetchRouteResult<any>[];
-        errors: {
-            name: string;
-            reason: unknown;
-        }[];
-    }>;
-    /**
-     * Build transaction with the selected aggregator's route
-     * @param options Transaction building options
-     */
-    buildRouteTransaction(route: FetchRouteResult<any>, options?: BuildOptionsBase & {
-        mergeResult?: true;
-    }): Promise<SwapBuildResult<true>>;
-    buildRouteTransaction(route: FetchRouteResult<any>, options: BuildOptionsBase & {
-        mergeResult: false;
-    }): Promise<SwapBuildResult<false>>;
-    executeSwapTransaction(tx: Transaction): Promise<SuiTransactionBlockResponse>;
-    executeSwapTransaction(tx: Transaction, dryRun: true): Promise<DryRunTransactionBlockResponse>;
-    executeSwapTransaction(tx: Transaction, dryRun: false): Promise<SuiTransactionBlockResponse>;
-}
-
 type FetchRouteSettings$3 = Omit<FindRouterParams, 'from' | 'target' | 'amount' | 'byAmountIn' | 'providers'>;
-declare class CetusSwap extends SwapSdkBase<string, RouterDataV3, FetchRouteSettings$3> {
-    readonly cetusClient: AggregatorClient;
-    constructor(params: SwapSdkConstructorParams<FetchRouteSettings$3> & AggregatorClientParams);
+
+declare class CetusSwap extends SwapSdkBase<string, RouterDataV3, FetchRouteSettings$3, AggregatorClient> {
+    constructor(params: SwapSdkConstructorParams<FetchRouteSettings$3> & Omit<AggregatorClientParams, 'client'>);
     private createRoute;
     /**
      * Parse the raw route data from Cetus to the standardized FetchRouteResult format.
      * @returns FormattedRouteResult
      */
-    private parseRawToFormattedResult;
+    parseRawToFormattedResult({ routerData, coinInType, coinOutType, }: {
+        routerData: RouterDataV3;
+        coinInType: string;
+        coinOutType: string;
+    }): Omit<FormattedRouteResult, 'name'>;
     setFetchRouteSettings(settings: FindRouterParams): void;
     calcSlippage(slippageInDecimal: number): number;
     fetchRoute(params: FetchRouteParams, abortSignal?: AbortSignal): Promise<{
         formattedResult: {
             name: string;
-            coinOut: Coin;
             routes: SwapRoute[];
             coinIn: Coin;
+            coinOut: Coin;
         };
         rawRouteResult: RouterDataV3;
     }>;
@@ -354,8 +280,8 @@ declare class CetusSwap extends SwapSdkBase<string, RouterDataV3, FetchRouteSett
 }
 
 type FetchRouteSettings$2 = Omit<ApiRouterPartialCompleteTradeRouteBody, 'coinInType' | 'coinOutType' | 'coinInAmount' | 'protocolWhitelist' | 'protocolBlacklist'>;
-declare class AftermathSwap extends SwapSdkBase<RouterProtocolName, RouterCompleteTradeRoute, FetchRouteSettings$2> {
-    readonly afClient: Aftermath;
+
+declare class AftermathSwap extends SwapSdkBase<RouterProtocolName, RouterCompleteTradeRoute, FetchRouteSettings$2, Aftermath> {
     readonly afApi: AftermathApi;
     constructor(params: SwapSdkConstructorParams<FetchRouteSettings$2> & {
         addresses?: ConfigAddresses;
@@ -391,6 +317,7 @@ interface Params {
     isSponsored?: boolean;
 }
 type FetchRouteSettings$1 = Omit<Params, 'tokenIn' | 'tokenOut' | 'amountIn' | 'sources'>;
+
 declare class _7kSwap extends SwapSdkBase<SourceDex, QuoteResponse, FetchRouteSettings$1> {
     commission: Commission;
     constructor(params: SwapSdkConstructorParams<FetchRouteSettings$1> & {
@@ -409,8 +336,9 @@ declare class _7kSwap extends SwapSdkBase<SourceDex, QuoteResponse, FetchRouteSe
 }
 
 type FetchRouteSettings = Omit<SingleQuoteQueryParams, 'amountIn' | 'tokenIn' | 'tokenOut' | 'excludeSources' | 'includeSources'>;
-declare class FlowXSwap extends SwapSdkBase<Protocol, GetRoutesResult<Coin$1, Coin$1>, FetchRouteSettings> {
-    private quoter;
+
+declare class FlowXSwap extends SwapSdkBase<Protocol, GetRoutesResult<Coin$1, Coin$1>, FetchRouteSettings, AggregatorQuoter> {
+    client: AggregatorQuoter;
     commission?: Commission$1;
     constructor(params: SwapSdkConstructorParams<FetchRouteSettings> & Omit<SingleQuoteQueryParams, 'amountIn' | 'tokenIn' | 'tokenOut'> & {
         commission?: Commission$1;
@@ -430,9 +358,105 @@ declare class FlowXSwap extends SwapSdkBase<Protocol, GetRoutesResult<Coin$1, Co
     }>;
 }
 
+interface SdkRegistry {
+    cetus: CetusSwap;
+    aftermath: AftermathSwap;
+    '7k': _7kSwap;
+    flowx: FlowXSwap;
+}
+type SdkName = keyof SdkRegistry;
+
+declare class CoinMetadataRegistry {
+    client: SuiClient;
+    private cache;
+    constructor(client: SuiClient, initialData?: (CoinMetadata & {
+        coinType: string;
+    })[]);
+    setClient(client: SuiClient): void;
+    getCoinMetadata(coinType: string): Promise<CoinMetadata>;
+}
+
+type TxExt = {
+    initTx: Transaction;
+    coinIn: TransactionObjectArgument;
+};
+type BuildOptionsBase = {
+    slippage?: number;
+    txExtensionParams?: TxExt;
+};
+declare class Aggregator {
+    #private;
+    readonly coinMetadata: CoinMetadataRegistry;
+    readonly suiKit: SuiKit | undefined;
+    readonly events: TypedEventEmitter<AggregatorEvents<string>>;
+    protected _slippage: number;
+    private signerMode;
+    private aggregatorMap;
+    private activeAggregator;
+    private _fetchingStatus;
+    private poolStatusForwarders;
+    walletAddress: string;
+    client: SuiClient;
+    constructor(params: AggregatorConstructorParams);
+    private forwardPoolStatusChangeEvent;
+    addAggregator(aggregator: SwapSdkBase[]): void;
+    getActiveAggregators(): string[];
+    getAggregator<T extends SdkName>(name: T): SdkRegistry[T] | undefined;
+    getAggregator(name: string): SwapSdkBase | undefined;
+    toggleAggregator(name: string, enabled: boolean): void;
+    removeAggregator(name: string): void;
+    get aggregators(): SwapSdkBase<string, any, any, any>[];
+    /**
+     * Per-aggregator fetching status. True while that aggregator's fetchRoute is in-flight.
+     */
+    get fetchingStatus(): Record<string, boolean>;
+    /**
+     * Get slippage (0.01 = 1%)
+     */
+    get slippage(): number;
+    /**
+     * Set slippage (0.01 = 1%)
+     * @param slippageInDecimal
+     */
+    setSlippage(slippageInDecimal: number): void;
+    /**
+     * Set fetch timeout in milliseconds for all aggregators
+     * @param timeoutInMs
+     */
+    setFetchTimeoutInMs(timeoutInMs: number): void;
+    setSuiClient(client: SuiClient): void;
+    setWalletAddress(address: string): void;
+    getCoinMetadata(coinType: string): Promise<_mysten_sui_dist_cjs_client.CoinMetadata>;
+    /**
+     * Fetch swap routes from all aggregators, and sort them by best output amount
+     * @param params FetchRouteParams
+     * @param options FetchRoutesOptions
+     */
+    fetchRoutes(params: FetchRouteParams, options?: FetchRoutesOptions): Promise<{
+        routes: FetchRouteResult<any>[];
+        errors: {
+            name: string;
+            reason: unknown;
+        }[];
+    }>;
+    /**
+     * Build transaction with the selected aggregator's route
+     * @param options Transaction building options
+     */
+    buildRouteTransaction(route: FetchRouteResult<any>, options?: BuildOptionsBase & {
+        mergeResult?: true;
+    }): Promise<SwapBuildResult<true>>;
+    buildRouteTransaction(route: FetchRouteResult<any>, options: BuildOptionsBase & {
+        mergeResult: false;
+    }): Promise<SwapBuildResult<false>>;
+    executeSwapTransaction(tx: Transaction): Promise<SuiTransactionBlockResponse>;
+    executeSwapTransaction(tx: Transaction, dryRun: true): Promise<DryRunTransactionBlockResponse>;
+    executeSwapTransaction(tx: Transaction, dryRun: false): Promise<SuiTransactionBlockResponse>;
+}
+
 declare const isSuiType: (coinType: string) => boolean;
 declare const selectCoins: (client: SuiClient, coinType: string, amount: string, owner: string) => Promise<CoinStruct[]>;
 declare const mergeWithExistingOrTransfer: (tx: Transaction, coin: TransactionObjectArgument, client: SuiClient, coinType: string, sender: string) => Promise<void>;
 declare const transformProperCase: (provider: string) => string;
 
-export { AftermathSwap, Aggregator, type AggregatorConstructorParams, type AggregatorEvents, type AggregatorStatusEvent, CetusSwap, type Coin, CoinMetadataRegistry, type FetchRouteParams, type FetchRouteResult, type FetchRoutesOptions, FlowXSwap, type FormattedRouteResult, type SecretKeyOrMnemonicsOrWalletAddress, type SuiClientOrFullnodeUrl, type SwapBuildResult, type SwapCoinInfo, type SwapParams, type SwapPath, type SwapRoute, SwapSdkBase, type SwapSdkBaseInterface, type SwapSdkConstructorParams, type SwapSdkEvents, type SwapSdkPoolStatusEvent, TypedEventEmitter, _7kSwap, isSuiType, mergeWithExistingOrTransfer, selectCoins, transformProperCase };
+export { type FetchRouteSettings$2 as AftermathFetchRouteSettings, AftermathSwap, Aggregator, type AggregatorConstructorParams, type AggregatorEvents, type AggregatorStatusEvent, type FetchRouteSettings$3 as CetusFetchRouteSettings, CetusSwap, type Coin, CoinMetadataRegistry, type FetchRouteParams, type FetchRouteResult, type FetchRoutesOptions, type FetchRouteSettings as FlowXFetchRouteSettings, FlowXSwap, type FormattedRouteResult, type SdkName, type SdkRegistry, type SecretKeyOrMnemonicsOrWalletAddress, type SuiClientOrFullnodeUrl, type SwapBuildResult, type SwapCoinInfo, type SwapParams, type SwapPath, type SwapRoute, SwapSdkBase, type SwapSdkBaseInterface, type SwapSdkConstructorParams, type SwapSdkEvents, type SwapSdkPoolStatusEvent, TypedEventEmitter, type FetchRouteSettings$1 as _7kFetchRouteSettings, _7kSwap, isSuiType, mergeWithExistingOrTransfer, selectCoins, transformProperCase };