@mento-protocol/mento-sdk 2.0.0-beta.9 → 3.0.0-beta.2

package/dist/utils/chainConfig.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultRpcUrl = getDefaultRpcUrl;
+exports.getChainConfig = getChainConfig;
+const chains_1 = require("viem/chains");
+const viem_1 = require("viem");
+const chainId_1 = require("../core/constants/chainId");
+// Celo Sepolia chain definition (not available in viem/chains yet)
+const celoSepolia = (0, viem_1.defineChain)({
+    id: 11142220,
+    name: 'Celo Sepolia',
+    nativeCurrency: {
+        decimals: 18,
+        name: 'CELO',
+        symbol: 'CELO',
+    },
+    rpcUrls: {
+        default: {
+            http: ['https://forno.celo-sepolia.celo-testnet.org'],
+        },
+    },
+    blockExplorers: {
+        default: {
+            name: 'Celo Explorer',
+            url: 'https://sepolia.celoscan.io',
+        },
+    },
+    testnet: true,
+});
+/**
+ * Get the default RPC URL for a given chain ID
+ * @param chainId - The chain ID
+ * @returns The default RPC URL for the chain
+ * @throws Error if chain ID is not supported
+ */
+function getDefaultRpcUrl(chainId) {
+    switch (chainId) {
+        case chainId_1.ChainId.CELO:
+            return 'https://forno.celo.org';
+        case chainId_1.ChainId.CELO_SEPOLIA:
+            return 'https://forno.celo-sepolia.celo-testnet.org';
+        default:
+            throw new Error(`Unsupported chain ID: ${chainId}`);
+    }
+}
+/**
+ * Get the viem chain configuration for a given chain ID
+ * @param chainId - The chain ID
+ * @returns The viem chain configuration
+ * @throws Error if chain ID is not supported
+ */
+function getChainConfig(chainId) {
+    switch (chainId) {
+        case chainId_1.ChainId.CELO:
+            return chains_1.celo;
+        case chainId_1.ChainId.CELO_SEPOLIA:
+            return celoSepolia;
+        default:
+            throw new Error(`Unsupported chain ID: ${chainId}`);
+    }
+}
+//# sourceMappingURL=chainConfig.js.map

package/dist/utils/chainConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chainConfig.js","sourceRoot":"","sources":["../../src/utils/chainConfig.ts"],"names":[],"mappings":";;AAiCA,4CASC;AAQD,wCASC;AA3DD,wCAA8C;AAC9C,+BAAkC;AAClC,uDAAmD;AAEnD,mEAAmE;AACnE,MAAM,WAAW,GAAG,IAAA,kBAAW,EAAC;IAC9B,EAAE,EAAE,QAAQ;IACZ,IAAI,EAAE,cAAc;IACpB,cAAc,EAAE;QACd,QAAQ,EAAE,EAAE;QACZ,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,MAAM;KACf;IACD,OAAO,EAAE;QACP,OAAO,EAAE;YACP,IAAI,EAAE,CAAC,6CAA6C,CAAC;SACtD;KACF;IACD,cAAc,EAAE;QACd,OAAO,EAAE;YACP,IAAI,EAAE,eAAe;YACrB,GAAG,EAAE,6BAA6B;SACnC;KACF;IACD,OAAO,EAAE,IAAI;CACd,CAAC,CAAA;AAEF;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,OAAe;IAC9C,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,iBAAO,CAAC,IAAI;YACf,OAAO,wBAAwB,CAAA;QACjC,KAAK,iBAAO,CAAC,YAAY;YACvB,OAAO,6CAA6C,CAAA;QACtD;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAA;IACvD,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,OAAe;IAC5C,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,iBAAO,CAAC,IAAI;YACf,OAAO,aAAI,CAAA;QACb,KAAK,iBAAO,CAAC,YAAY;YACvB,OAAO,WAAW,CAAA;QACpB;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAA;IACvD,CAAC;AACH,CAAC"}

package/dist/utils/costUtils.d.ts

@@ -0,0 +1,12 @@
+import { Pool } from '../core/types';
+import type { PublicClient } from 'viem';
+/**
+ * Calculate cost percentage for a pool based on its type
+ * Returns cost as a percentage (e.g., 0.5 = 0.5%)
+ *
+ * @param pool - The pool to calculate cost for
+ * @param publicClient - Viem public client for RPC calls
+ * @returns Cost percentage for the pool
+ */
+export declare function getPoolCostPercent(pool: Pool, publicClient: PublicClient): Promise<number>;
+//# sourceMappingURL=costUtils.d.ts.map

package/dist/utils/costUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"costUtils.d.ts","sourceRoot":"","sources":["../../src/utils/costUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,IAAI,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAGxC;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAQhG"}

package/dist/utils/costUtils.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPoolCostPercent = getPoolCostPercent;
+const types_1 = require("../core/types");
+const abis_1 = require("../core/abis");
+const virtualPool_1 = require("../core/abis/virtualPool");
+/**
+ * Calculate cost percentage for a pool based on its type
+ * Returns cost as a percentage (e.g., 0.5 = 0.5%)
+ *
+ * @param pool - The pool to calculate cost for
+ * @param publicClient - Viem public client for RPC calls
+ * @returns Cost percentage for the pool
+ */
+async function getPoolCostPercent(pool, publicClient) {
+    if (pool.poolType === types_1.PoolType.FPMM) {
+        return getFPMMCostPercent(pool.poolAddr, publicClient);
+    }
+    else if (pool.poolType === types_1.PoolType.Virtual) {
+        return getVirtualPoolCostPercent(pool.poolAddr, publicClient);
+    }
+    else {
+        throw new Error('Invalid pool type');
+    }
+}
+/**
+ * Calculate cost for FPMM pools
+ * FPMM pools use lpFee + protocolFee in basis points (10000 = 100%)
+ */
+async function getFPMMCostPercent(poolAddress, publicClient) {
+    const [lpFee, protocolFee] = await Promise.all([
+        publicClient.readContract({
+            address: poolAddress,
+            abi: abis_1.FPMM_ABI,
+            functionName: 'lpFee',
+        }),
+        publicClient.readContract({
+            address: poolAddress,
+            abi: abis_1.FPMM_ABI,
+            functionName: 'protocolFee',
+        }),
+    ]);
+    // Convert from basis points to percentage
+    const totalBasisPoints = Number(lpFee) + Number(protocolFee);
+    return totalBasisPoints / 100;
+}
+/**
+ * Calculate cost for Virtual pools
+ */
+async function getVirtualPoolCostPercent(poolAddress, publicClient) {
+    const protocolFee = await publicClient.readContract({
+        address: poolAddress,
+        abi: virtualPool_1.VIRTUAL_POOL_ABI,
+        functionName: 'protocolFee',
+    });
+    //TODO: Confirim calculation
+    return Number(protocolFee) / 100;
+}
+//# sourceMappingURL=costUtils.js.map

package/dist/utils/costUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costUtils.js","sourceRoot":"","sources":["../../src/utils/costUtils.ts"],"names":[],"mappings":";;AAaA,gDAQC;AArBD,yCAA8C;AAC9C,uCAAuC;AAEvC,0DAA2D;AAE3D;;;;;;;GAOG;AACI,KAAK,UAAU,kBAAkB,CAAC,IAAU,EAAE,YAA0B;IAC7E,IAAI,IAAI,CAAC,QAAQ,KAAK,gBAAQ,CAAC,IAAI,EAAE,CAAC;QACpC,OAAO,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IACxD,CAAC;SAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,gBAAQ,CAAC,OAAO,EAAE,CAAC;QAC9C,OAAO,yBAAyB,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IAC/D,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAA;IACtC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,kBAAkB,CAAC,WAAmB,EAAE,YAA0B;IAC/E,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC7C,YAAY,CAAC,YAAY,CAAC;YACxB,OAAO,EAAE,WAA4B;YACrC,GAAG,EAAE,eAAQ;YACb,YAAY,EAAE,OAAO;SACtB,CAAoB;QACrB,YAAY,CAAC,YAAY,CAAC;YACxB,OAAO,EAAE,WAA4B;YACrC,GAAG,EAAE,eAAQ;YACb,YAAY,EAAE,aAAa;SAC5B,CAAoB;KACtB,CAAC,CAAA;IAEF,0CAA0C;IAC1C,MAAM,gBAAgB,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAA;IAC5D,OAAO,gBAAgB,GAAG,GAAG,CAAA;AAC/B,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,yBAAyB,CAAC,WAAmB,EAAE,YAA0B;IACtF,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,YAAY,CAAC;QAClD,OAAO,EAAE,WAA4B;QACrC,GAAG,EAAE,8BAAgB;QACrB,YAAY,EAAE,aAAa;KAC5B,CAAC,CAAA;IAEF,4BAA4B;IAC5B,OAAO,MAAM,CAAC,WAAW,CAAC,GAAG,GAAG,CAAA;AAClC,CAAC"}

package/dist/utils/index.d.ts

@@ -1,2 +1,7 @@
 export * from './retry';
+export * from './chainConfig';
+export * from './routes';
+export * from './sortUtils';
+export * from './pathEncoder';
+export * from './tokens';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA"}

package/dist/utils/index.js

@@ -15,4 +15,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./retry"), exports);
+__exportStar(require("./chainConfig"), exports);
+__exportStar(require("./routes"), exports);
+__exportStar(require("./sortUtils"), exports);
+__exportStar(require("./pathEncoder"), exports);
+__exportStar(require("./tokens"), exports);
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAuB;AACvB,gDAA6B;AAC7B,2CAAwB;AACxB,8CAA2B;AAC3B,gDAA6B;AAC7B,2CAAwB"}

package/dist/utils/pathEncoder.d.ts

@@ -0,0 +1,28 @@
+import { Address } from 'viem';
+import { Pool } from '../core/types';
+/**
+ * Route structure expected by the Router contract's getAmountsOut and swapTokensForTokens functions
+ */
+export interface RouterRoute {
+    from: Address;
+    to: Address;
+    factory: Address;
+}
+/**
+ * Converts a route path to the format expected by the Router contract.
+ * Used by both QuoteService (getAmountsOut) and SwapService (swapTokensForTokens).
+ *
+ * @param path - The route path (array of pools)
+ * @param tokenIn - The input token address (determines swap direction)
+ * @param _tokenOut - The output token address (unused but kept for API clarity)
+ * @returns Array of RouterRoute objects for the contract call
+ *
+ * @example
+ * ```typescript
+ * const route = await routeService.findRoute(cUSD, CELO)
+ * const routerRoutes = encodeRoutePath(route.path, cUSD, CELO)
+ * // routerRoutes can now be passed to Router.getAmountsOut or Router.swapTokensForTokens
+ * ```
+ */
+export declare function encodeRoutePath(path: Pool[], tokenIn: Address, _tokenOut: Address): RouterRoute[];
+//# sourceMappingURL=pathEncoder.d.ts.map

package/dist/utils/pathEncoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathEncoder.d.ts","sourceRoot":"","sources":["../../src/utils/pathEncoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEpC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,WAAW,EAAE,CA4CjG"}

package/dist/utils/pathEncoder.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeRoutePath = encodeRoutePath;
+/**
+ * Converts a route path to the format expected by the Router contract.
+ * Used by both QuoteService (getAmountsOut) and SwapService (swapTokensForTokens).
+ *
+ * @param path - The route path (array of pools)
+ * @param tokenIn - The input token address (determines swap direction)
+ * @param _tokenOut - The output token address (unused but kept for API clarity)
+ * @returns Array of RouterRoute objects for the contract call
+ *
+ * @example
+ * ```typescript
+ * const route = await routeService.findRoute(cUSD, CELO)
+ * const routerRoutes = encodeRoutePath(route.path, cUSD, CELO)
+ * // routerRoutes can now be passed to Router.getAmountsOut or Router.swapTokensForTokens
+ * ```
+ */
+function encodeRoutePath(path, tokenIn, _tokenOut) {
+    const routes = [];
+    const tokenInLower = tokenIn.toLowerCase();
+    // Check if we need to reverse the path
+    // The path is stored in canonical order, but we may need to traverse it backwards
+    const firstPool = path[0];
+    const startsWithTokenIn = firstPool.token0.toLowerCase() === tokenInLower || firstPool.token1.toLowerCase() === tokenInLower;
+    // If tokenIn isn't in the first pool, reverse the path
+    const orderedPath = startsWithTokenIn ? path : [...path].reverse();
+    let currentTokenIn = tokenInLower;
+    for (const pool of orderedPath) {
+        const token0 = pool.token0.toLowerCase();
+        const token1 = pool.token1.toLowerCase();
+        // Determine direction: which token is the input for this hop?
+        let from;
+        let to;
+        if (currentTokenIn === token0) {
+            from = pool.token0;
+            to = pool.token1;
+        }
+        else if (currentTokenIn === token1) {
+            from = pool.token1;
+            to = pool.token0;
+        }
+        else {
+            throw new Error(`Token ${currentTokenIn} not found in pool ${pool.poolAddr}`);
+        }
+        routes.push({
+            from,
+            to,
+            factory: pool.factoryAddr,
+        });
+        // The output of this hop becomes the input of the next hop
+        currentTokenIn = to.toLowerCase();
+    }
+    return routes;
+}
+//# sourceMappingURL=pathEncoder.js.map

package/dist/utils/pathEncoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathEncoder.js","sourceRoot":"","sources":["../../src/utils/pathEncoder.ts"],"names":[],"mappings":";;AA4BA,0CA4CC;AA5DD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,eAAe,CAAC,IAAY,EAAE,OAAgB,EAAE,SAAkB;IAChF,MAAM,MAAM,GAAkB,EAAE,CAAA;IAChC,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA;IAE1C,uCAAuC;IACvC,kFAAkF;IAClF,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACzB,MAAM,iBAAiB,GACrB,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,YAAY,IAAI,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,YAAY,CAAA;IAEpG,uDAAuD;IACvD,MAAM,WAAW,GAAG,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,EAAE,CAAA;IAElE,IAAI,cAAc,GAAG,YAAY,CAAA;IAEjC,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAA;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAA;QAExC,8DAA8D;QAC9D,IAAI,IAAa,CAAA;QACjB,IAAI,EAAW,CAAA;QAEf,IAAI,cAAc,KAAK,MAAM,EAAE,CAAC;YAC9B,IAAI,GAAG,IAAI,CAAC,MAAiB,CAAA;YAC7B,EAAE,GAAG,IAAI,CAAC,MAAiB,CAAA;QAC7B,CAAC;aAAM,IAAI,cAAc,KAAK,MAAM,EAAE,CAAC;YACrC,IAAI,GAAG,IAAI,CAAC,MAAiB,CAAA;YAC7B,EAAE,GAAG,IAAI,CAAC,MAAiB,CAAA;QAC7B,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,SAAS,cAAc,sBAAsB,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC/E,CAAC;QAED,MAAM,CAAC,IAAI,CAAC;YACV,IAAI;YACJ,EAAE;YACF,OAAO,EAAE,IAAI,CAAC,WAAsB;SACrC,CAAC,CAAA;QAEF,2DAA2D;QAC3D,cAAc,GAAG,EAAE,CAAC,WAAW,EAAE,CAAA;IACnC,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/utils/routeUtils.d.ts

@@ -0,0 +1,295 @@
+import type { Route, RouteID, RouteWithCost, Pool } from '../core/types';
+type TokenSymbol = string;
+type Address = string;
+/**
+ * =============================================================================
+ * 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 cost 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 cost data 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 route details
+     *    ```
+     *    'CELO_addr-cEUR_addr' → { route details for CELO ↔ cEUR }
+     *    'CELO_addr-cUSD_addr' → { route details for CELO ↔ cUSD }
+     *    'cUSD_addr-cKES_addr' → { route details for cUSD ↔ cKES }
+     *    ```
+     */
+    directRouteMap: Map<RouteID, Pool>;
+    /** Original direct routes from mento.getDirectRoutes() for reference */
+    directRoutes: Route[];
+}
+/**
+ * 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 directRoutes - 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(directRoutes: Route[]): ConnectivityData;
+/**
+ * Generates all possible routes (direct + two-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
+ *
+ * **Route Deduplication**: Multiple routes between the same token pair
+ * are collected in arrays, allowing the selection algorithm to choose
+ * the best one based on cost data or heuristics.
+ *
+ * **Canonical Route IDs**: All routes use alphabetically sorted symbols
+ * (e.g., 'cEUR-cUSD' not 'cUSD-cEUR') for consistent identification.
+ *
+ * @param connectivityData - The connectivity data from buildConnectivityStructures()
+ * @returns Map of route ID -> array of possible routes for that token pair
+ *
+ * @example
+ * ```typescript
+ * // Given direct routes: 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<RouteID, Route[]>;
+/**
+ * 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 createTwoHopRoute(startAddr: Address, intermediateAddr: Address, endAddr: Address, addrToSymbol: Map<Address, TokenSymbol>, directRouteMap: Map<RouteID, Pool>): Route | 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], costData: { totalCostPercent: 0.5 } },
+ *     { path: [cUSD->cREAL->cEUR], costData: { totalCostPercent: 0.3 } },
+ *     { path: [cUSD->cEUR] } // direct route, no cost data
+ *   ]]
+ * ])
+ *
+ * const optimal = selectOptimalRoutes(candidates, false, assetMap)
+ * // Returns the cUSD->cREAL->cEUR route (lowest cost: 0.3%)
+ * ```
+ */
+export declare function selectOptimalRoutes(allRoutes: Map<RouteID, Route[]>, returnAllRoutes: boolean, addrToSymbol: Map<Address, TokenSymbol>): (Route | RouteWithCost)[];
+/**
+ * Selects the best route from candidates using cost data or fallback heuristics.
+ *
+ * This function implements a sophisticated route selection algorithm with
+ * multiple optimization tiers:
+ *
+ * **Tier 1 - Cost-Based Optimization** (Preferred):
+ * - Use routes with cost data (actual cost information)
+ * - Select route with lowest `totalCostPercent`
+ * - This provides the most cost-efficient trading
+ *
+ * **Tier 2 - Direct Route Preference** (Fallback):
+ * - If no cost 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], costData: { totalCostPercent: 0.8 } },
+ *   { path: [A->D->C], costData: { totalCostPercent: 0.4 } }, // Winner: lowest cost
+ *   { path: [A->C] }, // direct route, no cost data
+ * ]
+ *
+ * const best = selectBestRoute(candidates, assetMap)
+ * // Returns the A->D->C route (0.4% cost)
+ * ```
+ */
+export declare function selectBestRoute(candidates: Route[], addrToSymbol: Map<Address, TokenSymbol>): Route | RouteWithCost;
+/**
+ * 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: Route): Address | undefined;
+/**
+ * Type guard to check if a Route has cost data.
+ */
+export declare function hasCostData(pair: Route | RouteWithCost): pair is RouteWithCost;
+export {};
+//# sourceMappingURL=routeUtils.d.ts.map

package/dist/utils/routeUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeUtils.d.ts","sourceRoot":"","sources":["../../src/utils/routeUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAS,aAAa,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAI/E,KAAK,WAAW,GAAG,MAAM,CAAA;AACzB,KAAK,OAAO,GAAG,MAAM,CAAA;AAErB;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,YAAY,EAAE,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,CAAA;IAEvC;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAA;IAEtC;;;;;;OAMG;IACH,cAAc,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAElC,wEAAwE;IACxE,YAAY,EAAE,KAAK,EAAE,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,KAAK,EAAE,GAAG,gBAAgB,CA4BnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAgD3F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,OAAO,EAClB,gBAAgB,EAAE,OAAO,EACzB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,EACvC,cAAc,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GACjC,KAAK,GAAG,IAAI,CAgCd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,EAChC,eAAe,EAAE,OAAO,EACxB,YAAY,EAAE,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,GACtC,CAAC,KAAK,GAAG,aAAa,CAAC,EAAE,CAoB3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,KAAK,GAAG,aAAa,CAwBnH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,SAAS,CAMtE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI,IAAI,aAAa,CAE9E"}