@mento-protocol/mento-sdk 3.3.0 → 3.4.0

package/dist/utils/routeUtils.js

@@ -5,9 +5,13 @@ exports.generateAllRoutes = generateAllRoutes;
 exports.createTwoHopRoute = createTwoHopRoute;
 exports.selectOptimalRoutes = selectOptimalRoutes;
 exports.selectBestRoute = selectBestRoute;
+exports.compareRoutePath = compareRoutePath;
+exports.deterministicRoutePathKey = deterministicRoutePathKey;
 exports.getIntermediateToken = getIntermediateToken;
+exports.getIntermediateTokens = getIntermediateTokens;
 exports.hasCostData = hasCostData;
 const sortUtils_1 = require("./sortUtils");
+const MAX_DISCOVERED_ROUTE_HOPS = 3;
 /**
  * Builds the connectivity data structures needed for route generation.
  *
@@ -88,15 +92,15 @@ function buildConnectivityStructures(directRoutes) {
     return { addrToSymbol, directRouteMap, tokenGraph, directRoutes };
 }
 /**
- * Generates all possible routes (direct + two-hop) using connectivity data.
+ * Generates all possible routes (direct + two-hop + eligible three-hop) using
+ * connectivity data.
  *
  * This function implements a route discovery algorithm that:
  *
- * 1. **Adds all direct routes** (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
+ * 1. **Adds all direct routes** (single-hop routes).
+ * 2. **Discovers multi-hop candidates** with one bounded simple-path traversal.
+ * 3. **Keeps every two-hop route** and only the shortest routes with three or
+ *    more hops. The current discovery limit is three hops.
  *
  * **Route Deduplication**: Multiple routes between the same token pair
  * are collected in arrays, allowing the selection algorithm to choose
@@ -131,39 +135,110 @@ function generateAllRoutes(connectivityData) {
         }
         allRoutes.get(route.id).push(route);
     }
-    // Step 2: Generate two-hop routes using graph traversal
-    // Algorithm: For each token, explore all paths of length 2
+    // Step 2: Discover every simple multi-hop candidate in one bounded traversal.
+    const discoveredRoutes = [];
     // OUTER LOOP: "For each starting token..." (e.g., USDm, CELO, EURm, etc.)
-    for (const [start, neighbors] of tokenGraph.entries()) {
-        // MIDDLE LOOP: "Where can I go from the starting token?" (first hop)
-        // Example: If start = USDm, neighbors might be [CELO, USDC, KESm]
-        for (const intermediate of neighbors) {
-            // Get all tokens reachable from this intermediate token (second hop destinations)
-            const secondHopNeighbors = tokenGraph.get(intermediate);
-            if (!secondHopNeighbors)
-                continue;
-            // INNER LOOP: "From the intermediate token, where can I go?" (second hop)
-            // Example: If intermediate = CELO, secondHopNeighbors might be [USDm, EURm, BRLm]
-            for (const end of secondHopNeighbors) {
-                // Skip circular routes like USDm → CELO → USDm (pointless)
-                if (end === start)
-                    continue;
-                // At this point we have a potential route: start → intermediate → end
-                // Example: USDm → CELO → EURm
-                // Try to create a valid two-hop trading pair from this route
-                const twoHopRoute = createTwoHopRoute(start, intermediate, end, addrToSymbol, directRouteMap);
-                // If we successfully created the pair, add it to our collection
-                if (twoHopRoute) {
-                    if (!allRoutes.has(twoHopRoute.id)) {
-                        allRoutes.set(twoHopRoute.id, []);
-                    }
-                    allRoutes.get(twoHopRoute.id).push(twoHopRoute);
-                }
-            }
+    for (const start of tokenGraph.keys()) {
+        discoverSimplePaths(start, start, [], new Set([start]), new Set(), MAX_DISCOVERED_ROUTE_HOPS, tokenGraph, addrToSymbol, directRouteMap, (route, pathStart, pathEnd) => discoveredRoutes.push({ route, start: pathStart, end: pathEnd }));
+    }
+    // Step 3: Determine the minimum structural distance for every endpoint pair.
+    // Direct routes seed the map with one hop. The traversal supplies distances
+    // from two hops up to MAX_DISCOVERED_ROUTE_HOPS.
+    const minimumHopsByRouteId = new Map();
+    for (const routeId of allRoutes.keys())
+        minimumHopsByRouteId.set(routeId, 1);
+    for (const { route } of discoveredRoutes) {
+        const minimumHops = minimumHopsByRouteId.get(route.id);
+        if (minimumHops === undefined || route.path.length < minimumHops) {
+            minimumHopsByRouteId.set(route.id, route.path.length);
         }
     }
+    // Preserve existing two-hop alternatives, including alternatives for direct
+    // pairs. Routes with three or more hops are eligible only when they are the
+    // shortest structural path for their endpoint pair. Insert every two-hop
+    // route first to preserve the existing route and map order.
+    const seenGeneratedPaths = new Set();
+    for (const { route, start, end } of discoveredRoutes) {
+        if (route.path.length !== 2)
+            continue;
+        addGeneratedRoute(allRoutes, route, start, end, addrToSymbol, seenGeneratedPaths);
+    }
+    for (const { route, start, end } of discoveredRoutes) {
+        const minimumHops = minimumHopsByRouteId.get(route.id);
+        if (route.path.length < 3 || route.path.length !== minimumHops)
+            continue;
+        addGeneratedRoute(allRoutes, route, start, end, addrToSymbol, seenGeneratedPaths);
+    }
     return allRoutes;
 }
+/**
+ * Walks a token graph up to `maxHops`, emitting only simple paths. The graph
+ * stores token connectivity while `directRouteMap` resolves each edge to the
+ * executable pool used by the route path.
+ */
+function discoverSimplePaths(start, current, path, visitedTokens, visitedPools, maxHops, tokenGraph, addrToSymbol, directRouteMap, onRoute) {
+    if (path.length === maxHops)
+        return;
+    // RECURSIVE LOOP: "Where can I go from the current token?"
+    // Example: USDm → CELO then inspects CELO's neighbors, such as EURm.
+    for (const next of tokenGraph.get(current) ?? []) {
+        // Skip circular paths such as USDm → CELO → USDm.
+        if (visitedTokens.has(next))
+            continue;
+        const currentSymbol = addrToSymbol.get(current);
+        const nextSymbol = addrToSymbol.get(next);
+        if (!currentSymbol || !nextSymbol)
+            continue;
+        const pool = directRouteMap.get((0, sortUtils_1.canonicalSymbolKey)(currentSymbol, nextSymbol));
+        if (!pool || visitedPools.has(poolSignature(pool)))
+            continue;
+        const nextPath = [...path, pool];
+        const nextVisitedTokens = new Set(visitedTokens).add(next);
+        const nextVisitedPools = new Set(visitedPools).add(poolSignature(pool));
+        // Two or more pools define a potential multi-hop route.
+        // Example: USDm → CELO → EURm is a two-hop route.
+        if (nextPath.length >= 2) {
+            const route = createRouteFromPath(start, next, nextPath, addrToSymbol);
+            if (route)
+                onRoute(route, start, next);
+        }
+        discoverSimplePaths(start, next, nextPath, nextVisitedTokens, nextVisitedPools, maxHops, tokenGraph, addrToSymbol, directRouteMap, onRoute);
+    }
+}
+function addGeneratedRoute(allRoutes, route, start, end, addrToSymbol, seenGeneratedPaths) {
+    const canonicalRoute = canonicalizeGeneratedRoute(route, start, end, addrToSymbol);
+    const signature = `${canonicalRoute.id}:${canonicalRoute.path.map(poolSignature).join('|')}`;
+    if (seenGeneratedPaths.has(signature))
+        return;
+    seenGeneratedPaths.add(signature);
+    if (!allRoutes.has(canonicalRoute.id))
+        allRoutes.set(canonicalRoute.id, []);
+    allRoutes.get(canonicalRoute.id).push(canonicalRoute);
+}
+function createRouteFromPath(startAddr, endAddr, path, addrToSymbol) {
+    const startSymbol = addrToSymbol.get(startAddr);
+    const endSymbol = addrToSymbol.get(endAddr);
+    if (!startSymbol || !endSymbol || startAddr === endAddr)
+        return null;
+    const routeId = (0, sortUtils_1.canonicalSymbolKey)(startSymbol, endSymbol);
+    const startToken = { address: startAddr, symbol: startSymbol };
+    const endToken = { address: endAddr, symbol: endSymbol };
+    return {
+        id: routeId,
+        tokens: startSymbol <= endSymbol ? [startToken, endToken] : [endToken, startToken],
+        path,
+    };
+}
+function canonicalizeGeneratedRoute(route, startAddr, endAddr, addrToSymbol) {
+    const startSymbol = addrToSymbol.get(startAddr);
+    const endSymbol = addrToSymbol.get(endAddr);
+    if (!startSymbol || !endSymbol || startSymbol < endSymbol)
+        return route;
+    return { ...route, path: [...route.path].reverse() };
+}
+function poolSignature(pool) {
+    return `${pool.poolAddr}:${pool.factoryAddr}`;
+}
 /**
  * Creates a two-hop tradable pair if valid exchange hops exist.
  *
@@ -294,8 +369,10 @@ function selectOptimalRoutes(allRoutes, returnAllRoutes, addrToSymbol) {
 /**
  * Selects the best route from candidates using cost data or fallback heuristics.
  *
- * This function implements a sophisticated route selection algorithm with
- * multiple optimization tiers:
+ * This function implements a tiered route selection algorithm.
+ *
+ * **Eligibility guard**:
+ * - Exclude three-hop candidates when a direct or two-hop candidate exists
  *
  * **Tier 1 - Cost-Based Optimization** (Preferred):
  * - Use routes with cost data (actual cost information)
@@ -310,8 +387,8 @@ function selectOptimalRoutes(allRoutes, returnAllRoutes, addrToSymbol) {
  * - For two-hop routes, prefer those going through major stablecoins
  * - Major FX currencies like USDm and EURm typically have better liquidity
  *
- * **Tier 4 - First Available** (Last Resort):
- * - If no other heuristics apply, use the first route found
+ * **Tier 4 - Deterministic Path Order** (Last Resort):
+ * - If no other heuristic applies, use the route with the lowest stable path key
  *
  * @param candidates - Array of possible routes for the same token pair
  * @param assetMap - Asset map for token symbol lookups
@@ -330,37 +407,94 @@ function selectOptimalRoutes(allRoutes, returnAllRoutes, addrToSymbol) {
  * ```
  */
 function selectBestRoute(candidates, addrToSymbol) {
+    // A three-hop route is eligible only when no direct or two-hop candidate
+    // exists. Keep this invariant at selection time as a defense against stale
+    // or manually assembled candidate sets.
+    const shorterCandidates = candidates.filter((candidate) => candidate.path.length <= 2);
+    const eligibleCandidates = shorterCandidates.length > 0 ? shorterCandidates : candidates;
     // Tier 1: Prefer routes with cost data (lowest cost wins)
-    const candidatesWithCost = candidates.filter(hasCostData);
+    const candidatesWithCost = eligibleCandidates.filter(hasCostData);
     if (candidatesWithCost.length > 0) {
-        return candidatesWithCost.reduce((best, current) => current.costData.totalCostPercent < best.costData.totalCostPercent ? current : best);
+        return candidatesWithCost.reduce((best, current) => (compareCostedRoutes(current, best) < 0 ? current : best));
     }
     // Tier 2: Prefer direct routes (single-hop, lower risk)
-    const directRoute = candidates.find((c) => c.path.length === 1);
-    if (directRoute)
-        return directRoute;
+    const directRoutes = eligibleCandidates.filter((candidate) => candidate.path.length === 1);
+    if (directRoutes.length > 0)
+        return [...directRoutes].sort(compareRoutePath)[0];
     // Tier 3: Prefer routes through major stablecoins (better liquidity)
     const stablecoins = ['USDm', 'EURm', 'USDC', 'USDT'];
-    const routeWithStablecoin = candidates.find((candidate) => {
-        const intermediateToken = getIntermediateToken(candidate);
-        if (!intermediateToken)
-            return false;
-        const symbol = addrToSymbol.get(intermediateToken);
-        return symbol && stablecoins.includes(symbol);
+    const routesWithStablecoin = eligibleCandidates.filter((candidate) => {
+        return getIntermediateTokens(candidate).some((token) => {
+            const symbol = addrToSymbol.get(token);
+            return symbol !== undefined && stablecoins.includes(symbol);
+        });
     });
-    // Tier 4: Use first available route as last resort
-    return routeWithStablecoin || candidates[0];
+    if (routesWithStablecoin.length > 0)
+        return [...routesWithStablecoin].sort(compareRoutePath)[0];
+    // Tier 4: Use a stable path key so discovery order cannot change the result.
+    return [...eligibleCandidates].sort(compareRoutePath)[0];
+}
+function compareCostedRoutes(candidate, current) {
+    const costDifference = candidate.costData.totalCostPercent - current.costData.totalCostPercent;
+    return costDifference || compareRoutePath(candidate, current);
+}
+/**
+ * Compares route paths by hop count and a stable pool identity key.
+ *
+ * Callers must apply their own higher-level ordering before this comparator,
+ * such as route ID or cost preference.
+ */
+function compareRoutePath(first, second) {
+    const hopDifference = first.path.length - second.path.length;
+    if (hopDifference !== 0)
+        return hopDifference;
+    const firstKey = deterministicRoutePathKey(first);
+    const secondKey = deterministicRoutePathKey(second);
+    if (firstKey < secondKey)
+        return -1;
+    if (firstKey > secondKey)
+        return 1;
+    return 0;
+}
+/**
+ * Returns the canonical, case-insensitive key for a route's pool path.
+ *
+ * Keep this ordering stable across fresh route selection, cache generation,
+ * and cached route lookup.
+ */
+function deterministicRoutePathKey(route) {
+    return route.path
+        .map((pool) => [pool.poolType, pool.factoryAddr, pool.poolAddr, pool.token0, pool.token1]
+        .map((value) => value.toLowerCase())
+        .join(':'))
+        .join('|');
 }
 /**
- * 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).
+ * Extracts the first intermediate token address from a multi-hop route.
+ * In a two-hop route A->B->C, this function finds token B. For longer routes,
+ * it preserves the helper's original single-token return type and returns the
+ * first intermediate token.
  */
 function getIntermediateToken(route) {
-    // Find the common token between the two hops
-    const [hop1, hop2] = route.path;
-    const hop1Tokens = [hop1.token0, hop1.token1];
-    const hop2Tokens = [hop2.token0, hop2.token1];
-    return hop1Tokens.find((addr) => hop2Tokens.includes(addr));
+    return getIntermediateTokens(route)[0];
+}
+/**
+ * Returns every intermediate token in an executable multi-hop path. Adjacent
+ * pools must share exactly one token for that token to be considered part of
+ * the path.
+ */
+function getIntermediateTokens(route) {
+    const intermediateTokens = [];
+    for (let index = 0; index < route.path.length - 1; index++) {
+        const currentPool = route.path[index];
+        const nextPool = route.path[index + 1];
+        const nextTokens = new Set([nextPool.token0, nextPool.token1]);
+        const sharedTokens = [currentPool.token0, currentPool.token1].filter((token) => nextTokens.has(token));
+        if (sharedTokens.length !== 1)
+            return [];
+        intermediateTokens.push(sharedTokens[0]);
+    }
+    return intermediateTokens;
 }
 /**
  * Type guard to check if a Route has cost data.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mento-protocol/mento-sdk",
   "description": "Official SDK for interacting with the Mento Protocol",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "license": "MIT",
   "author": "Mento Labs",
   "keywords": [