@mento-protocol/mento-sdk 1.0.9 → 1.10.1

package/dist/cjs/enums/chainId.d.ts

@@ -1,5 +1,4 @@
 export declare enum ChainId {
     CELO = 42220,
-    ALFAJORES = 44787,
-    BAKLAVA = 62320
+    ALFAJORES = 44787
 }

package/dist/cjs/enums/chainId.js

@@ -5,5 +5,4 @@ var ChainId;
 (function (ChainId) {
     ChainId[ChainId["CELO"] = 42220] = "CELO";
     ChainId[ChainId["ALFAJORES"] = 44787] = "ALFAJORES";
-    ChainId[ChainId["BAKLAVA"] = 62320] = "BAKLAVA";
 })(ChainId = exports.ChainId || (exports.ChainId = {}));

package/dist/cjs/index.d.ts

@@ -1,5 +1,6 @@
-export * from './mento';
-export * from './governance';
-export * from './utils';
 export * from './constants';
+export * from './governance';
+export * from './mento';
+export * from './routeUtils';
 export { ContractAddresses } from './types';
+export * from './utils';

package/dist/cjs/index.js

@@ -15,7 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./mento"), exports);
+__exportStar(require("./constants"), exports);
 __exportStar(require("./governance"), exports);
+__exportStar(require("./mento"), exports);
+__exportStar(require("./routeUtils"), exports);
 __exportStar(require("./utils"), exports);
-__exportStar(require("./constants"), exports);

package/dist/cjs/mento.d.ts

@@ -1,6 +1,7 @@
 import { IBroker } from '@mento-protocol/mento-core-ts';
-import { BigNumber, BigNumberish, Signer, providers } from 'ethers';
+import { BigNumber, BigNumberish, providers, Signer } from 'ethers';
 import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './interfaces';
+import { TradablePairWithSpread } from './constants/tradablePairs';
 export interface Exchange {
     providerAddr: Address;
     id: string;
@@ -10,8 +11,9 @@ export interface Asset {
     address: Address;
     symbol: string;
 }
+export type TradablePairID = `${Address}-${Address}`;
 export interface TradablePair {
-    id: string;
+    id: TradablePairID;
     assets: [Asset, Asset];
     path: Array<{
         providerAddr: Address;
@@ -74,11 +76,19 @@ export declare class Mento {
      * 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.
+     * @param options - Optional parameters
+     * @param options.cached - Whether to use cached data (default: true)
+     * @param options.returnAllRoutes - Whether to return all possible routes or just the best one per pair (default: false)
      * @returns An array of TradablePair objects representing available trade routes.
      */
-    getTradablePairsWithPath({ cached, }?: {
+    getTradablePairsWithPath({ cached, returnAllRoutes, }?: {
         cached?: boolean;
-    }): Promise<readonly TradablePair[]>;
+        returnAllRoutes?: boolean;
+    }): Promise<readonly (TradablePair | TradablePairWithSpread)[]>;
+    /**
+     * Attempts to get cached tradable pairs for the current chain
+     */
+    private getCachedTradablePairs;
     /**
      * 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.

package/dist/cjs/mento.js

@@ -18,6 +18,7 @@ const assert_1 = require("assert");
 const mento_router_ts_1 = require("mento-router-ts");
 const addresses_1 = require("./constants/addresses");
 const tradablePairs_1 = require("./constants/tradablePairs");
+const routeUtils_1 = require("./routeUtils");
 class Mento {
     /**
      * This constructor is private, use the static create or createWithParams methods
@@ -129,90 +130,33 @@ class Mento {
      * 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.
+     * @param options - Optional parameters
+     * @param options.cached - Whether to use cached data (default: true)
+     * @param options.returnAllRoutes - Whether to return all possible routes or just the best one per pair (default: false)
      * @returns An array of TradablePair objects representing available trade routes.
      */
-    getTradablePairsWithPath({ cached = true, } = {}) {
+    getTradablePairsWithPath({ cached = true, returnAllRoutes = false, } = {}) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Get tradable pairs from cache if available.
+            // Try to get cached data first
             if (cached) {
-                const value = (0, tradablePairs_1.getCachedTradablePairs)(yield (0, utils_1.getChainId)(this.signerOrProvider));
-                if (value) {
-                    return value;
-                }
+                const cachedPairs = yield this.getCachedTradablePairs();
+                if (cachedPairs)
+                    return cachedPairs;
             }
-            // Retrieve direct pairs first.
+            // Generate routes from scratch
             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());
+            const connectivity = (0, routeUtils_1.buildConnectivityStructures)(directPairs);
+            const allRoutes = (0, routeUtils_1.generateAllRoutes)(connectivity);
+            return (0, routeUtils_1.selectOptimalRoutes)(allRoutes, returnAllRoutes, connectivity.addrToSymbol);
+        });
+    }
+    /**
+     * Attempts to get cached tradable pairs for the current chain
+     */
+    getCachedTradablePairs() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const chainId = yield (0, utils_1.getChainId)(this.signerOrProvider);
+            return yield (0, tradablePairs_1.getCachedTradablePairs)(chainId);
         });
     }
     /**
@@ -458,19 +402,21 @@ class Mento {
      */
     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)))));
+            const allPairs = yield this.getTradablePairsWithPath();
+            // Find the pair for these tokens
+            const pair = allPairs.find((p) => {
+                // Check if the pair connects tokenIn to tokenOut
+                if (p.assets[0].address === tokenIn && p.assets[1].address === tokenOut) {
+                    return true;
+                }
+                // Check reverse direction
+                if (p.assets[0].address === tokenOut && p.assets[1].address === tokenIn) {
+                    return true;
+                }
+                return false;
+            });
             if (!pair) {
-                throw new Error(`No tradable pair found for tokens ${tokenIn} and ${tokenOut}`);
+                throw new Error(`No pair found for tokens ${tokenIn} and ${tokenOut}. They may not have a tradable path.`);
             }
             return pair;
         });

package/dist/cjs/routeUtils.d.ts

@@ -0,0 +1,304 @@
+import { TradablePairWithSpread } from './constants';
+import { Address } from './interfaces';
+import { TradablePair, TradablePairID } from './mento';
+type TokenSymbol = string;
+interface ExchangeDetails {
+    providerAddr: Address;
+    id: string;
+    assets: [Address, Address];
+}
+/**
+ * =============================================================================
+ * ROUTE GENERATION UTILITIES
+ * =============================================================================
+ *
+ * Utilities for generating optimal trading routes in the Mento protocol.
+ *
+ * The main workflow is:
+ *
+ * 1. Build connectivity structures from direct trading pairs
+ * 2. Generate all possible routes (direct + two-hop)
+ * 3. Select optimal routes using spread data or heuristics
+ *
+ * ALGORITHM OVERVIEW:
+ * - Creates a graph where tokens are nodes and direct exchanges are edges
+ * - Uses graph traversal to find two-hop routes through intermediate tokens
+ * - Optimizes route selection based on spread costs when available
+ * - Falls back to heuristics (prefer direct routes, major stablecoins)
+ * =============================================================================
+ */
+/**
+ * Connectivity data structure that represents the token graph connecting all tokens.
+ * Helps to efficiently answer: "How can I trade from token A to token B?"
+ *
+ * CONCRETE EXAMPLE:
+ * Given these direct trading pairs:
+ * - cUSD ↔ CELO (direct exchange exists)
+ * - CELO ↔ cEUR (direct exchange exists)
+ * - cUSD ↔ cREAL (direct exchange exists)
+ *
+ * How route finding works:
+ * - Direct route: cUSD → cEUR? Check token graph: cUSD connects to [CELO, cREAL], none is cEUR → No direct route
+ * - Two-hop route: cUSD → ? → cEUR?
+ *   - cUSD connects to CELO, CELO connects to cEUR → Found route: cUSD → CELO → cEUR
+ *   - cUSD connects to cREAL, cREAL connects to [cUSD] → No route via cREAL
+ *
+ * The "connectivity" part means we can quickly traverse the network of
+ * token connections to find all possible trading paths.
+ */
+export interface ConnectivityData {
+    /** Maps token address to symbol for efficient lookups
+     *
+     *    ```
+     *    '0x765D...' → 'cUSD'
+     *    '0x471E...' → 'CELO'
+     *    '0xD876...' → 'cEUR'
+     *    ```
+     */
+    addrToSymbol: Map<Address, TokenSymbol>;
+    /** Adjacency list mapping which tokens connect to which
+     * Used for finding two-hop routes by traversing token → neighbor → neighbor.
+     *
+     * Example for a cUSD => cEUR swap: First we find cUSD → [CELO, cKES, ...]
+     * Then we find CELO → [cUSD, cEUR, ...] = found route via cUSD → CELO → cEUR
+     *
+     *    ```
+     *    'cUSD_addr' → Set(['CELO_addr', 'cKES_addr'])  // cUSD connects to CELO and cKES
+     *    'CELO_addr' → Set(['cUSD_addr', 'cEUR_addr'])  // CELO connects to cUSD and cEUR
+     *    'cEUR_addr' → Set(['CELO_addr'])               // cEUR connects to CELO
+     *    'cKES_addr' → Set(['cUSD_addr'])               // cKES connects to cUSD
+     *    ```
+     */
+    tokenGraph: Map<Address, Set<Address>>;
+    /** Maps sorted token address pairs to their direct exchange hop details
+     *    ```
+     *    'CELO_addr-cEUR_addr' → { exchange details for CELO ↔ cEUR }
+     *    'CELO_addr-cUSD_addr' → { exchange details for CELO ↔ cUSD }
+     *    'cUSD_addr-cKES_addr' → { exchange details for cUSD ↔ cKES }
+     *    ```
+     */
+    directPathMap: Map<TradablePairID, ExchangeDetails>;
+    /** Original direct trading pairs from mento.getDirectPairs() for reference */
+    directPairs: TradablePair[];
+}
+/**
+ * Builds the connectivity data structures needed for route generation.
+ *
+ * Transforms a list of direct trading pairs into our ConnectivityData
+ * that allow us to quickly find trading routes.
+ *
+ * **Construction Process:**
+ *
+ * ```
+ * Input: TradablePairs = [
+ *   { id: 'cUSD-CELO', assets: [cUSD, CELO], path: [exchange1_CELO_cUSD] },
+ *   { id: 'CELO-cEUR', assets: [CELO, cEUR], path: [exchange2_CELO_cEUR] }
+ * ]
+ *
+ * Step 1 - Build addrToSymbol map:
+ *   cUSD.address → 'cUSD'
+ *   CELO.address → 'CELO'
+ *   cEUR.address → 'cEUR'
+ *
+ * Step 2 - Build directPathMap (sorted alphabetically for consistency):
+ *   'CELO_addr-cEUR_addr' → exchange2_CELO_cEUR
+ *   'CELO_addr-cUSD_addr' → exchange1_CELO_cUSD
+ *
+ * Step 3 - Build bidirectional tokenGraph:
+ *   cUSD.address → Set([CELO.address])
+ *   CELO.address → Set([cUSD.address, cEUR.address])
+ *   cEUR.address → Set([CELO.address])
+ * ```
+ *
+ * **Result**: We can now efficiently answer:
+ * - "What's the symbol for address X?" → addrToSymbol.get(addr)
+ * - "What exchange connects tokens X and Y?" → directPathMap.get(sortedAddressPairKey)
+ * - "What tokens can I reach from token X?" → tokenGraph.get(X)
+ *
+ * @param directPairs - Array of direct trading pairs
+ * @returns Connectivity data structure for efficient route generation
+ *
+ * @example
+ * ```typescript
+ * const directPairs = [
+ *   { id: 'cUSD-CELO', assets: [cUSD, CELO], path: [exchange1] },
+ *   { id: 'CELO-cEUR', assets: [CELO, cEUR], path: [exchange2] }
+ * ]
+ *
+ * const connectivityData = buildConnectivityStructures(directPairs)
+ *
+ * // Now we can efficiently find routes:
+ * // 1. Check if cUSD connects to anything: connectivityData.tokenGraph.get(cUSD.address) → [CELO.address]
+ * // 2. Check if CELO connects to cEUR: connectivityData.tokenGraph.get(CELO.address) → [cUSD.address, cEUR.address] ✓
+ * // 3. Get exchange details: connectivityData.directPathMap.get('CELO_addr-cEUR_addr') → exchange2_CELO_cEUR
+ * // Result: Found route cUSD → CELO → cEUR with exchange details
+ * ```
+ */
+export declare function buildConnectivityStructures(directPairs: TradablePair[]): ConnectivityData;
+/**
+ * Generates all possible routes (direct + two-hop) using connectivity data.
+ *
+ * This function implements a route discovery algorithm that:
+ *
+ * 1. **Adds all direct pairs** (single-hop routes)
+ * 2. **Discovers two-hop routes** using graph traversal:
+ *    - For each token A, find its neighbors (tokens directly connected)
+ *    - For each neighbor B, find B's neighbors
+ *    - If B connects to token C (C ≠ A), then A->B->C is a valid route
+ *
+ * **Route Deduplication**: Multiple routes between the same token pair
+ * are collected in arrays, allowing the selection algorithm to choose
+ * the best one based on spread data or heuristics.
+ *
+ * **Canonical Pair IDs**: All pairs use alphabetically sorted symbols
+ * (e.g., 'cEUR-cUSD' not 'cUSD-cEUR') for consistent identification.
+ *
+ * @param connectivityData - The connectivity data from buildConnectivityStructures()
+ * @returns Map of pair ID -> array of possible routes for that pair
+ *
+ * @example
+ * ```typescript
+ * // Given direct pairs: cUSD-CELO, CELO-cEUR, cUSD-USDC
+ * const allRoutes = generateAllRoutes(connectivityData)
+ *
+ * // Results might include:
+ * // 'cUSD-CELO' -> [{ path: [cUSD->CELO] }] // direct route
+ * // 'cEUR-cUSD' -> [
+ * //   { path: [cUSD->USDC, USDC->cEUR] } // two-hop via USDC
+ * //   { path: [cUSD->CELO, CELO->cEUR] } // two-hop via CELO
+ * // ]
+ * ```
+ */
+export declare function generateAllRoutes(connectivityData: ConnectivityData): Map<TradablePairID, TradablePair[]>;
+/**
+ * Creates a two-hop tradable pair if valid exchange hops exist.
+ *
+ * 1. **Validates tokens exist** in the asset map
+ * 2. **Finds exchange hops** for both segments of the route
+ * 3. **Creates canonical pair structure** with sorted symbols
+ *
+ * **Route Structure**: The resulting pair represents trading from start->end
+ * via intermediate token, but the assets are ordered alphabetically by symbol
+ * for consistency (canonical form).
+ *
+ * **Path Representation**: The path array contains the actual exchange hops
+ * needed to execute the trade, preserving the routing information.
+ *
+ * @param startToken - Starting token address
+ * @param intermediate - Intermediate token address for routing
+ * @param end - Destination token address
+ * @param assetMap - Map of token address -> Asset details
+ * @param directPathMap - Map of token pairs -> exchange hop details
+ * @returns Route if valid route exists, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // Create route: cUSD -> CELO -> cEUR
+ * const pair = createTwoHopPair(
+ *   '0x765D...', // cUSD address
+ *   '0x471E...', // CELO address
+ *   '0xD876...', // cEUR address
+ *   addrToSymbol,
+ *   directPathMap
+ * )
+ *
+ * // Result:
+ * // {
+ * //   id: 'cEUR-cUSD',           // alphabetical order
+ * //   assets: [cEUR, cUSD],     // alphabetical order
+ * //   path: [                   // actual routing path
+ * //     { cUSD->CELO exchange },
+ * //     { CELO->cEUR exchange }
+ * //   ]
+ * // }
+ * ```
+ */
+export declare function createTwoHopPair(startToken: Address, intermediateToken: Address, endToken: Address, addrToSymbol: Map<Address, TokenSymbol>, directPathMap: Map<string, {
+    providerAddr: Address;
+    id: string;
+    assets: [Address, Address];
+}>): TradablePair | null;
+/**
+ * Selects optimal routes from all candidates based on spread data or heuristics.
+ *
+ * This is the route optimization engine that implements the following logic:
+ *
+ * **For Single Route**: Use it directly (no optimization needed)
+ *
+ * **For Multiple Routes**:
+ * - If `returnAllRoutes=true`: Return all routes (used for cache generation)
+ * - If `returnAllRoutes=false`: Apply optimization to select the best route
+ *
+ * **Route Selection Strategy**: Delegates to `selectBestRoute()` which uses
+ * a multi-tier approach prioritizing cost efficiency and reliability.
+ *
+ * @param allRoutes - Map of pair ID -> array of possible routes
+ * @param returnAllRoutes - Whether to return all routes or optimize selection
+ * @param assetMap - Asset map for token symbol lookups during optimization
+ * @returns Array of selected optimal routes
+ *
+ * @example
+ * ```typescript
+ * // Multiple routes for cUSD-cEUR pair
+ * const candidates = new Map([
+ *   ['cEUR-cUSD', [
+ *     { path: [cUSD->CELO->cEUR], spreadData: { totalSpreadPercent: 0.5 } },
+ *     { path: [cUSD->cREAL->cEUR], spreadData: { totalSpreadPercent: 0.3 } },
+ *     { path: [cUSD->cEUR] } // direct route, no spread data
+ *   ]]
+ * ])
+ *
+ * const optimal = selectOptimalRoutes(candidates, false, assetMap)
+ * // Returns the cUSD->cREAL->cEUR route (lowest spread: 0.3%)
+ * ```
+ */
+export declare function selectOptimalRoutes(allRoutes: Map<TradablePairID, TradablePair[]>, returnAllRoutes: boolean, addrToSymbol: Map<Address, TokenSymbol>): (TradablePair | TradablePairWithSpread)[];
+/**
+ * Selects the best route from candidates using spread data or fallback heuristics.
+ *
+ * This function implements a sophisticated route selection algorithm with
+ * multiple optimization tiers:
+ *
+ * **Tier 1 - Spread-Based Optimization** (Preferred):
+ * - Use routes with spread data (actual cost information)
+ * - Select route with lowest `totalSpreadPercent`
+ * - This provides the most cost-efficient trading
+ *
+ * **Tier 2 - Direct Route Preference** (Fallback):
+ * - If no spread data available, prefer direct (single-hop) routes
+ * - Direct routes have lower execution risk and gas costs
+ *
+ * **Tier 3 - Major Stablecoin Preference** (Final Fallback):
+ * - For two-hop routes, prefer those going through major stablecoins
+ * - Major FX currencies like cUSD and cEUR typically have better liquidity
+ *
+ * **Tier 4 - First Available** (Last Resort):
+ * - If no other heuristics apply, use the first route found
+ *
+ * @param candidates - Array of possible routes for the same token pair
+ * @param assetMap - Asset map for token symbol lookups
+ * @returns The optimal route selected using the tier system
+ *
+ * @example
+ * ```typescript
+ * const candidates = [
+ *   { path: [A->B->C], spreadData: { totalSpreadPercent: 0.8 } },
+ *   { path: [A->D->C], spreadData: { totalSpreadPercent: 0.4 } }, // Winner: lowest spread
+ *   { path: [A->C] }, // direct route, no spread data
+ * ]
+ *
+ * const best = selectBestRoute(candidates, assetMap)
+ * // Returns the A->D->C route (0.4% spread)
+ * ```
+ */
+export declare function selectBestRoute(candidates: TradablePair[], addrToSymbol: Map<Address, TokenSymbol>): TradablePair | TradablePairWithSpread;
+/**
+ * Extracts the intermediate token address from a two-hop route.
+ * In a two-hop route A->B->C, this function finds token B (the intermediate).
+ */
+export declare function getIntermediateToken(route: TradablePair): Address | undefined;
+/**
+ * Type guard to check if a Route has spread data.
+ */
+export declare function hasSpreadData(pair: TradablePair | TradablePairWithSpread): pair is TradablePairWithSpread;
+export {};