@mento-protocol/mento-sdk 1.0.0 → 1.0.2

package/dist/cjs/mento.d.ts

@@ -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,120 @@ 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(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.
+     */
+    getDirectPairs(): Promise<TradablePair[]>;
+    /**
+     * 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.
      */
-    getTradeablePairs(): Promise<[Asset, Asset][]>;
+    getTradablePairsWithPath(cached?: boolean): Promise<readonly TradablePair[]>;
     /**
-     * Returns the amount of tokenIn to be sold to buy amountOut of tokenOut
+     * 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

package/dist/cjs/mento.js

@@ -15,6 +15,9 @@ const ethers_1 = require("ethers");
 const utils_1 = require("./utils");
 const limits_1 = require("./limits");
 const assert_1 = require("assert");
+const tradablePairs_1 = require("./constants/tradablePairs");
+const mento_router_ts_1 = require("mento-router-ts");
+const addresses_1 = require("./constants/addresses");
 class Mento {
     /**
      * This constructor is private, use the static create or createWithParams methods
@@ -23,9 +26,10 @@ class Mento {
      * @param brokerAddress the address of the broker contract
      * @param exchanges exchange data for the broker
      */
-    constructor(signerOrProvider, brokerAddress, exchanges) {
+    constructor(signerOrProvider, brokerAddress, routerAddress, exchanges) {
         this.signerOrProvider = signerOrProvider;
         this.broker = mento_core_ts_1.IBroker__factory.connect(brokerAddress, signerOrProvider);
+        this.router = mento_router_ts_1.IMentoRouter__factory.connect(routerAddress, signerOrProvider);
         this.exchanges = exchanges || [];
     }
     /**
@@ -37,7 +41,7 @@ class Mento {
     static create(signerOrProvider) {
         return __awaiter(this, void 0, void 0, function* () {
             (0, utils_1.validateSignerOrProvider)(signerOrProvider);
-            return new Mento(signerOrProvider, yield (0, utils_1.getBrokerAddressFromRegistry)(signerOrProvider));
+            return new Mento(signerOrProvider, yield (0, utils_1.getBrokerAddressFromRegistry)(signerOrProvider), yield (0, addresses_1.getAddress)('MentoRouter', yield (0, utils_1.getChainId)(signerOrProvider)));
         });
     }
     /**
@@ -48,9 +52,9 @@ class Mento {
      * @param exchanges the exchanges data for the broker
      * @returns a new Mento object instance
      */
-    static createWithParams(signerOrProvider, brokerAddr, exchanges) {
+    static createWithParams(signerOrProvider, brokerAddr, routerAddr, exchanges) {
         (0, utils_1.validateSignerOrProvider)(signerOrProvider);
-        return new Mento(signerOrProvider, brokerAddr, exchanges);
+        return new Mento(signerOrProvider, brokerAddr, routerAddr, exchanges);
     }
     /**
      * Returns a new Mento instance connected to the given signer
@@ -59,55 +63,240 @@ class Mento {
      */
     connectSigner(signer) {
         (0, utils_1.validateSigner)(signer);
-        return new Mento(signer, this.broker.address, this.exchanges);
+        return new Mento(signer, this.broker.address, this.router.address, this.exchanges);
     }
     /**
-     * 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
      */
-    getTradeablePairs() {
+    getTradablePairs(cached = true) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return (yield this.getTradablePairsWithPath(cached)).map((pair) => pair.assets);
+        });
+    }
+    /**
+     * 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.
+     */
+    getDirectPairs() {
         return __awaiter(this, void 0, void 0, function* () {
             const exchanges = yield this.getExchanges();
-            const pairs = [];
+            // Map from pair id (symbol-symbol) to its TradablePair
+            const directPairsMap = new Map();
             for (const exchange of exchanges) {
-                const asset0 = exchange.assets[0];
-                const asset1 = exchange.assets[1];
-                const symbols = yield Promise.all([
-                    (0, utils_1.getSymbolFromTokenAddress)(asset0, this.signerOrProvider),
-                    (0, utils_1.getSymbolFromTokenAddress)(asset1, this.signerOrProvider),
-                ]);
-                pairs.push([
-                    { address: asset0, symbol: symbols[0] },
-                    { address: asset1, symbol: symbols[1] },
+                const [token0, token1] = exchange.assets;
+                const [symbol0, symbol1] = yield Promise.all([
+                    (0, utils_1.getSymbolFromTokenAddress)(token0, this.signerOrProvider),
+                    (0, utils_1.getSymbolFromTokenAddress)(token1, this.signerOrProvider),
                 ]);
+                // Determine canonical order by symbol
+                let assets;
+                let pairId;
+                if (symbol0 <= symbol1) {
+                    assets = [
+                        { address: token0, symbol: symbol0 },
+                        { address: token1, symbol: symbol1 },
+                    ];
+                    pairId = `${symbol0}-${symbol1}`;
+                }
+                else {
+                    assets = [
+                        { address: token1, symbol: symbol1 },
+                        { address: token0, symbol: symbol0 },
+                    ];
+                    pairId = `${symbol1}-${symbol0}`;
+                }
+                const pathEntry = {
+                    providerAddr: exchange.providerAddr,
+                    id: exchange.id,
+                    assets: exchange.assets,
+                };
+                if (directPairsMap.has(pairId)) {
+                    directPairsMap.get(pairId).path.push(pathEntry);
+                }
+                else {
+                    directPairsMap.set(pairId, { id: pairId, assets, path: [pathEntry] });
+                }
+            }
+            return Array.from(directPairsMap.values());
+        });
+    }
+    /**
+     * 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(cached = true) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Get tradable pairs from cache if available.
+            if (cached) {
+                const value = (0, tradablePairs_1.getCachedTradablePairs)(yield (0, utils_1.getChainId)(this.signerOrProvider));
+                if (value) {
+                    return value;
+                }
             }
-            return pairs;
+            // Retrieve direct pairs first.
+            const directPairs = yield this.getDirectPairs();
+            // Build helper maps:
+            // assetMap: maps token address to its Asset details.
+            const assetMap = new Map();
+            // directPathMap: maps a sorted pair of token addresses (by address) to a direct exchange hop.
+            const directPathMap = new Map();
+            // graph: maps a token address to the set of addresses it connects to directly.
+            const graph = new Map();
+            for (const pair of directPairs) {
+                const [assetA, assetB] = pair.assets;
+                assetMap.set(assetA.address, assetA);
+                assetMap.set(assetB.address, assetB);
+                const sortedAddresses = [assetA.address, assetB.address].sort().join('-');
+                if (!directPathMap.has(sortedAddresses)) {
+                    // Use the first available direct hop for the connectivity graph.
+                    directPathMap.set(sortedAddresses, pair.path[0]);
+                }
+                if (!graph.has(assetA.address))
+                    graph.set(assetA.address, new Set());
+                if (!graph.has(assetB.address))
+                    graph.set(assetB.address, new Set());
+                graph.get(assetA.address).add(assetB.address);
+                graph.get(assetB.address).add(assetA.address);
+            }
+            // Initialize tradablePairsMap with direct pairs keyed by their id (symbol-symbol).
+            const tradablePairsMap = new Map();
+            for (const pair of directPairs) {
+                tradablePairsMap.set(pair.id, pair);
+            }
+            // Generate two-hop pairs using the connectivity graph.
+            // For each potential route: start -> intermediate -> end, add a two-hop pair
+            // only if no direct route (i.e. same symbol pair) exists.
+            for (const [start, neighbors] of graph.entries()) {
+                for (const intermediate of neighbors) {
+                    const secondHopNeighbors = graph.get(intermediate);
+                    if (!secondHopNeighbors)
+                        continue;
+                    for (const end of secondHopNeighbors) {
+                        if (end === start)
+                            continue; // Avoid self-loop.
+                        const assetStart = assetMap.get(start);
+                        const assetEnd = assetMap.get(end);
+                        if (!assetStart || !assetEnd)
+                            continue;
+                        // Determine canonical pair id based on asset symbols.
+                        const sortedSymbols = [assetStart.symbol, assetEnd.symbol].sort();
+                        const pairId = `${sortedSymbols[0]}-${sortedSymbols[1]}`;
+                        if (tradablePairsMap.has(pairId))
+                            continue; // Skip if a direct pair exists.
+                        // Retrieve the direct hops for the two segments.
+                        const hop1Key = [start, intermediate].sort().join('-');
+                        const hop2Key = [intermediate, end].sort().join('-');
+                        const hop1 = directPathMap.get(hop1Key);
+                        const hop2 = directPathMap.get(hop2Key);
+                        if (!hop1 || !hop2)
+                            continue;
+                        let assets;
+                        if (assetStart.symbol <= assetEnd.symbol) {
+                            assets = [assetStart, assetEnd];
+                        }
+                        else {
+                            assets = [assetEnd, assetStart];
+                        }
+                        tradablePairsMap.set(pairId, {
+                            id: pairId,
+                            assets,
+                            path: [hop1, hop2],
+                        });
+                    }
+                }
+            }
+            return Array.from(tradablePairsMap.values());
         });
     }
     /**
-     * Returns the amount of tokenIn to be sold to buy amountOut of tokenOut
+     * 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, tokenOut, amountOut) {
+    getAmountIn(tokenIn, tokenOut, amountOut, tradablePair) {
         return __awaiter(this, void 0, void 0, function* () {
-            const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
-            return this.broker.getAmountIn(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountOut);
+            if (!tradablePair) {
+                tradablePair = yield this.findPairForTokens(tokenIn, tokenOut);
+            }
+            if (tradablePair.path.length === 1) {
+                return this.getAmountInDirect(tokenIn, tokenOut, amountOut, tradablePair);
+            }
+            else {
+                return this.getAmountInRouted(tokenIn, tokenOut, amountOut, tradablePair);
+            }
         });
     }
     /**
-     * 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, tokenOut, amountIn) {
+    getAmountOut(tokenIn, tokenOut, amountIn, tradablePair) {
         return __awaiter(this, void 0, void 0, function* () {
-            const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
-            return this.broker.getAmountOut(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountIn);
+            if (!tradablePair) {
+                tradablePair = yield this.findPairForTokens(tokenIn, tokenOut);
+            }
+            if (tradablePair.path.length === 1) {
+                return this.getAmountOutDirect(tokenIn, tokenOut, amountIn, tradablePair);
+            }
+            else {
+                return this.getAmountOutRouted(tokenIn, tokenOut, amountIn, tradablePair);
+            }
+        });
+    }
+    /**
+     * Internal method for direct pricing: retrieves the exchange for the given tokens
+     * and returns the amountIn using the broker.
+     */
+    getAmountInDirect(tokenIn, tokenOut, amountOut, tradablePair) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.broker.getAmountIn(tradablePair.path[0].providerAddr, tradablePair.path[0].id, tokenIn, tokenOut, amountOut);
+        });
+    }
+    /**
+     * Internal method for direct pricing: retrieves the exchange for the given tokens
+     * and returns the amountOut using the broker.
+     */
+    getAmountOutDirect(tokenIn, tokenOut, amountIn, tradablePair) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.broker.getAmountOut(tradablePair.path[0].providerAddr, tradablePair.path[0].id, tokenIn, tokenOut, amountIn);
+        });
+    }
+    /**
+     * 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.
+     */
+    getAmountInRouted(tokenIn, tokenOut, amountOut, tradablePair) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const steps = this.buildSteps(tokenIn, tokenOut, tradablePair);
+            return this.router.getAmountIn(amountOut, steps);
+        });
+    }
+    /**
+     * 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.
+     */
+    getAmountOutRouted(tokenIn, tokenOut, amountIn, tradablePair) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const steps = this.buildSteps(tokenIn, tokenOut, tradablePair);
+            return this.router.getAmountOut(amountIn, steps);
         });
     }
     /**
@@ -116,10 +305,10 @@ class Mento {
      * @param amount the amount to increase the allowance by
      * @returns the populated TransactionRequest object
      */
-    increaseTradingAllowance(token, amount) {
+    increaseTradingAllowance(tokenIn, amount, tradablePair) {
         return __awaiter(this, void 0, void 0, function* () {
-            const spender = this.broker.address;
-            const tx = yield (0, utils_1.increaseAllowance)(token, spender, amount, this.signerOrProvider);
+            const spender = !tradablePair || (tradablePair === null || tradablePair === void 0 ? void 0 : tradablePair.path.length) == 1 ? this.broker.address : this.router.address;
+            const tx = yield (0, utils_1.increaseAllowance)(tokenIn, spender, amount, this.signerOrProvider);
             if (ethers_1.Signer.isSigner(this.signerOrProvider)) {
                 // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
                 return this.signerOrProvider.populateTransaction(tx);
@@ -130,47 +319,125 @@ class Mento {
         });
     }
     /**
-     * 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, tokenOut, amountIn, amountOutMin) {
+    swapIn(tokenIn, tokenOut, amountIn, amountOutMin, tradablePair) {
         return __awaiter(this, void 0, void 0, function* () {
-            const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
-            const tx = yield this.broker.populateTransaction.swapIn(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountIn, amountOutMin);
-            if (ethers_1.Signer.isSigner(this.signerOrProvider)) {
-                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
-                return this.signerOrProvider.populateTransaction(tx);
+            if (!tradablePair) {
+                tradablePair = yield this.findPairForTokens(tokenIn, tokenOut);
+            }
+            if (tradablePair.path.length === 1) {
+                return this.swapInDirect(tokenIn, tokenOut, amountIn, amountOutMin);
             }
             else {
-                return tx;
+                return this.swapInRouted(tokenIn, tokenOut, amountIn, amountOutMin, tradablePair);
             }
         });
     }
+    swapInDirect(tokenIn, tokenOut, amountIn, amountOutMin) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
+            const tx = yield this.broker.populateTransaction.swapIn(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountIn, amountOutMin);
+            return ethers_1.Signer.isSigner(this.signerOrProvider)
+                ? this.signerOrProvider.populateTransaction(tx)
+                : tx;
+        });
+    }
+    swapInRouted(tokenIn, tokenOut, amountIn, amountOutMin, tradablePair) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const steps = this.buildSteps(tokenIn, tokenOut, tradablePair);
+            const tx = yield this.router.populateTransaction.swapExactTokensForTokens(amountIn, amountOutMin, steps);
+            return ethers_1.Signer.isSigner(this.signerOrProvider)
+                ? this.signerOrProvider.populateTransaction(tx)
+                : tx;
+        });
+    }
     /**
-     * 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, tokenOut, amountOut, amountInMax) {
+    swapOut(tokenIn, tokenOut, amountOut, amountInMax, tradablePair) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!tradablePair) {
+                tradablePair = yield this.findPairForTokens(tokenIn, tokenOut);
+            }
+            if (tradablePair.path.length === 1) {
+                return this.swapOutDirect(tokenIn, tokenOut, amountOut, amountInMax);
+            }
+            else {
+                return this.swapOutRouted(tokenIn, tokenOut, amountOut, amountInMax, tradablePair);
+            }
+        });
+    }
+    swapOutDirect(tokenIn, tokenOut, amountOut, amountInMax) {
         return __awaiter(this, void 0, void 0, function* () {
             const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
             const tx = yield this.broker.populateTransaction.swapOut(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountOut, amountInMax);
-            if (ethers_1.Signer.isSigner(this.signerOrProvider)) {
-                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
-                return this.signerOrProvider.populateTransaction(tx);
+            return ethers_1.Signer.isSigner(this.signerOrProvider)
+                ? this.signerOrProvider.populateTransaction(tx)
+                : tx;
+        });
+    }
+    swapOutRouted(tokenIn, tokenOut, amountOut, amountInMax, tradablePair) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const steps = this.buildSteps(tokenIn, tokenOut, tradablePair);
+            const tx = yield this.router.populateTransaction.swapTokensForExactTokens(amountOut, amountInMax, steps);
+            return ethers_1.Signer.isSigner(this.signerOrProvider)
+                ? this.signerOrProvider.populateTransaction(tx)
+                : tx;
+        });
+    }
+    /**
+     * Helper method to build the steps for a routed swap, ensuring proper token ordering
+     * through the path segments
+     */
+    buildSteps(tokenIn, tokenOut, tradablePair) {
+        let path = [...tradablePair.path];
+        if (path[0].assets.includes(tokenOut)) {
+            path = path.reverse();
+        }
+        return path.map((step, idx) => {
+            const isFirstStep = idx === 0;
+            const isLastStep = idx === tradablePair.path.length - 1;
+            const prevStep = idx > 0 ? tradablePair.path[idx - 1] : null;
+            // For first step, ensure assetIn is tokenIn
+            // For middle steps, ensure assetIn matches previous step's assetOut
+            // For last step, ensure assetOut is tokenOut
+            let [assetIn, assetOut] = step.assets;
+            if (isFirstStep && assetIn !== tokenIn) {
+                ;
+                [assetIn, assetOut] = [assetOut, assetIn];
             }
-            else {
-                return tx;
+            else if (!isFirstStep &&
+                !isLastStep &&
+                assetIn !== prevStep.assets[1]) {
+                ;
+                [assetIn, assetOut] = [assetOut, assetIn];
+            }
+            else if (isLastStep && assetOut !== tokenOut) {
+                ;
+                [assetIn, assetOut] = [assetOut, assetIn];
             }
+            return {
+                exchangeProvider: step.providerAddr,
+                exchangeId: step.id,
+                assetIn,
+                assetOut,
+            };
         });
     }
     /**
@@ -180,6 +447,28 @@ class Mento {
     getBroker() {
         return this.broker;
     }
+    /**
+     * 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, tokenOut) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const pair = (yield this.getTradablePairsWithPath()).find((p) => 
+            // Direct path
+            (p.path.length === 1 && p.path[0].assets.includes(tokenIn) && p.path[0].assets.includes(tokenOut)) ||
+                // Routed path
+                (p.path.length === 2 &&
+                    ((p.path[0].assets.includes(tokenIn) && p.path[1].assets.includes(tokenOut)) ||
+                        (p.path[0].assets.includes(tokenOut) && p.path[1].assets.includes(tokenIn)))));
+            if (!pair) {
+                throw new Error(`No tradable pair found for tokens ${tokenIn} and ${tokenOut}`);
+            }
+            return pair;
+        });
+    }
     /**
      * Returns the list of exchanges available in Mento (cached)
      * @returns the list of exchanges

package/dist/cjs/types/contractAddresses.d.ts

@@ -6,6 +6,7 @@ export type ContractAddresses = {
     MentoToken: string;
     TimelockController: string;
     Locking: string;
+    MentoRouter: string;
     Broker: string;
     BiPoolManager: string;
     BreakerBox: string;