@mento-protocol/mento-sdk 1.0.1 → 1.0.3

package/dist/esm/mento.d.ts

@@ -1,6 +1,6 @@
-import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './interfaces';
 import { IBroker } from '@mento-protocol/mento-core-ts';
 import { BigNumber, BigNumberish, Signer, providers } from 'ethers';
+import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './interfaces';
 export interface Exchange {
     providerAddr: Address;
     id: string;
@@ -10,9 +10,19 @@ export interface Asset {
     address: Address;
     symbol: string;
 }
+export interface TradablePair {
+    id: string;
+    assets: [Asset, Asset];
+    path: Array<{
+        providerAddr: Address;
+        id: string;
+        assets: [Address, Address];
+    }>;
+}
 export declare class Mento {
     private readonly signerOrProvider;
     private readonly broker;
+    private readonly router;
     private exchanges;
     /**
      * This constructor is private, use the static create or createWithParams methods
@@ -37,7 +47,7 @@ export declare class Mento {
      * @param exchanges the exchanges data for the broker
      * @returns a new Mento object instance
      */
-    static createWithParams(signerOrProvider: Signer | providers.Provider, brokerAddr: Address, exchanges?: Exchange[]): Mento;
+    static createWithParams(signerOrProvider: Signer | providers.Provider, brokerAddr: Address, routerAddr: Address, exchanges?: Exchange[]): Mento;
     /**
      * Returns a new Mento instance connected to the given signer
      * @param signer an ethers signer
@@ -45,58 +55,124 @@ export declare class Mento {
      */
     connectSigner(signer: Signer): Mento;
     /**
-     * Returns a list of all the pairs that can be traded on Mento
-     * @returns The list of tradeable pairs in the form of [{address, symbol}]
+     * Get tradable pairs for backwards compatibility
+     * @returns an array of Asset pairs
+     */
+    getTradablePairs(options?: {
+        cached?: boolean;
+    }): Promise<[Asset, Asset][]>;
+    /**
+     * Returns a list of all tradable pairs on Mento via direct exchanges.
+     * Each pair is represented using the TradablePair interface, with its id
+     * (a concatenation of the two asset symbols in alphabetical order),
+     * the two Asset objects, and a path (an array with a single direct exchange hop).
+     * @returns An array of direct TradablePair objects.
      */
-    getTradeablePairs(): Promise<[Asset, Asset][]>;
+    getDirectPairs(): Promise<TradablePair[]>;
     /**
-     * Returns the amount of tokenIn to be sold to buy amountOut of tokenOut
+     * Returns a list of all tradable pairs on Mento, including those achievable
+     * via two-hop routes. For two-hop pairs, the path will contain two exchange hops.
+     * Each TradablePair contains an id (the concatenation of the two asset symbols in alphabetical order),
+     * the two Asset objects, and an array of exchange details for each hop.
+     * @returns An array of TradablePair objects representing available trade routes.
+     */
+    getTradablePairsWithPath(options?: {
+        cached?: boolean;
+    }): Promise<readonly TradablePair[]>;
+    /**
+     * Returns the amount of tokenIn to be sold to buy amountOut of tokenOut.
+     * If the provided tradablePair has a single (direct) pricing path, then direct pricing is used.
+     * Otherwise, routed pricing via the MentoRouter is applied.
      * @param tokenIn the token to be sold
      * @param tokenOut the token to be bought
-     * @param amountOut the amount of tokenOut to be bought
+     * @param amountOut the desired amount of tokenOut to be obtained
+     * @param tradablePair the TradablePair object containing the pricing path information
      * @returns the amount of tokenIn to be sold
      */
-    getAmountIn(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish): Promise<BigNumber>;
+    getAmountIn(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish, tradablePair?: TradablePair): Promise<BigNumber>;
     /**
-     * Returns the amount of tokenOut to be bought by selling amountIn of tokenIn
+     * Returns the amount of tokenOut to be bought by selling amountIn of tokenIn.
+     * If the provided tradablePair has a single (direct) pricing path, then direct pricing is used.
+     * Otherwise, routed pricing via the MentoRouter is applied.
      * @param tokenIn the token to be sold
      * @param tokenOut the token to be bought
      * @param amountIn the amount of tokenIn to be sold
+     * @param tradablePair the TradablePair object containing the pricing path information
      * @returns the amount of tokenOut to be bought
      */
-    getAmountOut(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish): Promise<BigNumber>;
+    getAmountOut(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish, tradablePair?: TradablePair): Promise<BigNumber>;
+    /**
+     * Internal method for direct pricing: retrieves the exchange for the given tokens
+     * and returns the amountIn using the broker.
+     */
+    private getAmountInDirect;
+    /**
+     * Internal method for direct pricing: retrieves the exchange for the given tokens
+     * and returns the amountOut using the broker.
+     */
+    private getAmountOutDirect;
+    /**
+     * Internal method for routed pricing: uses the MentoRouter to determine the required tokenIn
+     * for obtaining amountOut through a multi-hop route specified in tradablePair.path.
+     */
+    private getAmountInRouted;
+    /**
+     * Internal method for routed pricing: uses the MentoRouter to determine the amountOut
+     * obtainable by selling amountIn through a multi-hop route specified in tradablePair.path.
+     */
+    private getAmountOutRouted;
     /**
      * Increases the broker's trading allowance for the given token
      * @param token the token to increase the allowance for
      * @param amount the amount to increase the allowance by
      * @returns the populated TransactionRequest object
      */
-    increaseTradingAllowance(token: Address, amount: BigNumberish): Promise<providers.TransactionRequest>;
+    increaseTradingAllowance(tokenIn: Address, amount: BigNumberish, tradablePair?: TradablePair): Promise<providers.TransactionRequest>;
     /**
-     * Returns a token swap populated tx object with a fixed amount of tokenIn and a minimum amount of tokenOut
-     * Submitting the transaction to execute the swap is left to the consumer
+     * Returns a token swap populated tx object with a fixed amount of tokenIn and a minimum amount of tokenOut.
+     * If the tradablePair contains a single-hop route, a direct swap is executed using swapExactTokensForTokens on the broker.
+     * Otherwise, a routed swap is executed via the router.
      * @param tokenIn the token to be sold
      * @param tokenOut the token to be bought
      * @param amountIn the amount of tokenIn to be sold
      * @param amountOutMin the minimum amount of tokenOut to be bought
+     * @param tradablePair the tradable pair details to determine routing
      * @returns the populated TransactionRequest object
      */
-    swapIn(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish, amountOutMin: BigNumberish): Promise<providers.TransactionRequest>;
+    swapIn(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish, amountOutMin: BigNumberish, tradablePair?: TradablePair): Promise<providers.TransactionRequest>;
+    private swapInDirect;
+    private swapInRouted;
     /**
-     * Returns a token swap populated tx object with a maximum amount of tokenIn and a fixed amount of tokenOut
-     * Submitting the transaction to execute the swap is left to the consumer
+     * Returns a token swap populated tx object with a maximum amount of tokenIn and a fixed amount of tokenOut.
+     * If the tradablePair contains a single-hop route, a direct swap is executed using swapTokensForExactTokens on the broker.
+     * Otherwise, a routed swap is executed via the router.
      * @param tokenIn the token to be sold
      * @param tokenOut the token to be bought
      * @param amountOut the amount of tokenOut to be bought
      * @param amountInMax the maximum amount of tokenIn to be sold
      * @returns the populated TransactionRequest object
      */
-    swapOut(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish, amountInMax: BigNumberish): Promise<providers.TransactionRequest>;
+    swapOut(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish, amountInMax: BigNumberish, tradablePair?: TradablePair): Promise<providers.TransactionRequest>;
+    private swapOutDirect;
+    private swapOutRouted;
+    /**
+     * Helper method to build the steps for a routed swap, ensuring proper token ordering
+     * through the path segments
+     */
+    private buildSteps;
     /**
      * Returns the mento instance's broker contract
      * @returns broker contract
      */
     getBroker(): IBroker;
+    /**
+     * Finds a tradable pair for the given input and output tokens
+     * @param tokenIn the input token address
+     * @param tokenOut the output token address
+     * @returns the tradable pair containing the path between the tokens
+     * @throws if no path is found between the tokens
+     */
+    findPairForTokens(tokenIn: Address, tokenOut: Address): Promise<TradablePair>;
     /**
      * Returns the list of exchanges available in Mento (cached)
      * @returns the list of exchanges