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

package/dist/utils/routeUtils.js

@@ -0,0 +1,371 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConnectivityStructures = buildConnectivityStructures;
+exports.generateAllRoutes = generateAllRoutes;
+exports.createTwoHopRoute = createTwoHopRoute;
+exports.selectOptimalRoutes = selectOptimalRoutes;
+exports.selectBestRoute = selectBestRoute;
+exports.getIntermediateToken = getIntermediateToken;
+exports.hasCostData = hasCostData;
+const sortUtils_1 = require("./sortUtils");
+/**
+ * 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
+ * ```
+ */
+function buildConnectivityStructures(directRoutes) {
+    const addrToSymbol = new Map();
+    const directRouteMap = new Map();
+    const tokenGraph = new Map();
+    for (const route of directRoutes) {
+        const [tokenA, tokenB] = route.tokens;
+        // Build address-to-symbol map for quick symbol lookups
+        addrToSymbol.set(tokenA.address, tokenA.symbol);
+        addrToSymbol.set(tokenB.address, tokenB.symbol);
+        // Build direct path map (sorted addresses as key for consistency)
+        // for quick lookup of exchange details for any token pair
+        const routeId = (0, sortUtils_1.canonicalSymbolKey)(tokenA.symbol, tokenB.symbol);
+        if (!directRouteMap.has(routeId)) {
+            directRouteMap.set(routeId, route.path[0]);
+        }
+        // Build bidirectional connectivity graph for route traversal
+        // Each token can reach its directly connected tokens
+        if (!tokenGraph.has(tokenA.address))
+            tokenGraph.set(tokenA.address, new Set());
+        if (!tokenGraph.has(tokenB.address))
+            tokenGraph.set(tokenB.address, new Set());
+        tokenGraph.get(tokenA.address).add(tokenB.address);
+        tokenGraph.get(tokenB.address).add(tokenA.address);
+    }
+    return { addrToSymbol, directRouteMap, tokenGraph, directRoutes };
+}
+/**
+ * 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
+ * // ]
+ * ```
+ */
+function generateAllRoutes(connectivityData) {
+    const { addrToSymbol, directRouteMap, tokenGraph, directRoutes } = connectivityData;
+    const allRoutes = new Map();
+    // Step 1: Add all direct pairs (single-hop routes)
+    for (const route of directRoutes) {
+        if (!allRoutes.has(route.id)) {
+            allRoutes.set(route.id, []);
+        }
+        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
+    // OUTER LOOP: "For each starting token..." (e.g., cUSD, CELO, cEUR, etc.)
+    for (const [start, neighbors] of tokenGraph.entries()) {
+        // MIDDLE LOOP: "Where can I go from the starting token?" (first hop)
+        // Example: If start = cUSD, neighbors might be [CELO, USDC, cKES]
+        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 [cUSD, cEUR, cBRL]
+            for (const end of secondHopNeighbors) {
+                // Skip circular routes like cUSD → CELO → cUSD (pointless)
+                if (end === start)
+                    continue;
+                // At this point we have a potential route: start → intermediate → end
+                // Example: cUSD → CELO → cEUR
+                // 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);
+                }
+            }
+        }
+    }
+    return allRoutes;
+}
+/**
+ * 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 }
+ * //   ]
+ * // }
+ * ```
+ */
+function createTwoHopRoute(startAddr, intermediateAddr, endAddr, addrToSymbol, directRouteMap) {
+    // Validate that both all tokens exist in our address-to-symbol map
+    const startSymbol = addrToSymbol.get(startAddr);
+    const intermediateSymbol = addrToSymbol.get(intermediateAddr);
+    const endSymbol = addrToSymbol.get(endAddr);
+    if (!startSymbol || !intermediateSymbol || !endSymbol)
+        return null;
+    // Find exchange hops for both segments of the two-hop route
+    // Keys are sorted token addresses for consistent lookup
+    const hop1Key = (0, sortUtils_1.canonicalSymbolKey)(startSymbol, intermediateSymbol);
+    const hop2Key = (0, sortUtils_1.canonicalSymbolKey)(intermediateSymbol, endSymbol);
+    const hop1 = directRouteMap.get(hop1Key);
+    const hop2 = directRouteMap.get(hop2Key);
+    // If either hop doesn't exist, this route is invalid
+    if (!hop1 || !hop2)
+        return null;
+    // Create canonical pair structure (alphabetical symbol ordering)
+    const routeId = (0, sortUtils_1.canonicalSymbolKey)(startSymbol, endSymbol);
+    // Create Token objects from address and symbol
+    const startToken = { address: startAddr, symbol: startSymbol };
+    const endToken = { address: endAddr, symbol: endSymbol };
+    // Token array follows alphabetical ordering for consistency
+    const tokens = startSymbol <= endSymbol ? [startToken, endToken] : [endToken, startToken];
+    return {
+        id: routeId,
+        tokens,
+        path: [hop1, hop2], // Preserves actual routing path for execution
+    };
+}
+/**
+ * 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%)
+ * ```
+ */
+function selectOptimalRoutes(allRoutes, returnAllRoutes, addrToSymbol) {
+    const result = new Map();
+    for (const [routeId, routes] of allRoutes) {
+        if (routes.length === 1) {
+            // Only one route available - use it directly
+            result.set(routeId, routes[0]);
+        }
+        else if (returnAllRoutes) {
+            // Return all routes with unique keys (used for cache generation)
+            routes.forEach((route, index) => {
+                result.set(`${routeId}_${index}`, route);
+            });
+        }
+        else {
+            // Multiple routes - select the best one using optimization logic
+            const bestRoute = selectBestRoute(routes, addrToSymbol);
+            result.set(routeId, bestRoute);
+        }
+    }
+    return Array.from(result.values());
+}
+/**
+ * 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)
+ * ```
+ */
+function selectBestRoute(candidates, addrToSymbol) {
+    // Tier 1: Prefer routes with cost data (lowest cost wins)
+    const candidatesWithCost = candidates.filter(hasCostData);
+    if (candidatesWithCost.length > 0) {
+        return candidatesWithCost.reduce((best, current) => current.costData.totalCostPercent < best.costData.totalCostPercent ? current : best);
+    }
+    // Tier 2: Prefer direct routes (single-hop, lower risk)
+    const directRoute = candidates.find((c) => c.path.length === 1);
+    if (directRoute)
+        return directRoute;
+    // Tier 3: Prefer routes through major stablecoins (better liquidity)
+    const stablecoins = ['cUSD', 'cEUR', '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);
+    });
+    // Tier 4: Use first available route as last resort
+    return routeWithStablecoin || candidates[0];
+}
+/**
+ * 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).
+ */
+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));
+}
+/**
+ * Type guard to check if a Route has cost data.
+ */
+function hasCostData(pair) {
+    return 'costData' in pair && pair.costData !== undefined;
+}
+//# sourceMappingURL=routeUtils.js.map

package/dist/utils/routeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeUtils.js","sourceRoot":"","sources":["../../src/utils/routeUtils.ts"],"names":[],"mappings":"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"}

package/dist/utils/routes.d.ts

@@ -0,0 +1,9 @@
+import type { Route, RouteWithCost } from '../core/types';
+export type { RouteWithCost };
+/**
+ * Gets cached routes for a specific chain ID
+ * @param chainId - The chain ID to get cached routes for
+ * @returns Promise resolving to the cached routes or undefined if not available
+ */
+export declare function getCachedRoutes(chainId: number): Promise<readonly (Route | RouteWithCost)[] | undefined>;
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/utils/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAGzD,YAAY,EAAE,aAAa,EAAE,CAAA;AAE7B;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,CAAC,KAAK,GAAG,aAAa,CAAC,EAAE,GAAG,SAAS,CAAC,CAmBzD"}

package/dist/utils/routes.js

@@ -0,0 +1,49 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedRoutes = getCachedRoutes;
+/**
+ * Gets cached routes for a specific chain ID
+ * @param chainId - The chain ID to get cached routes for
+ * @returns Promise resolving to the cached routes or undefined if not available
+ */
+async function getCachedRoutes(chainId) {
+    try {
+        switch (chainId) {
+            case 42220:
+                // @ts-ignore - Cache files are generated by scripts and may not exist yet
+                return await Promise.resolve().then(() => __importStar(require('../cache/routes.42220'))).then((module) => module.routes42220);
+            case 11142220:
+                // @ts-ignore - Cache files are generated by scripts and may not exist yet
+                return await Promise.resolve().then(() => __importStar(require('../cache/routes.11142220'))).then((module) => module.routes11142220);
+            default:
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=routes.js.map

package/dist/utils/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/utils/routes.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAUA,0CAqBC;AA1BD;;;;GAIG;AACI,KAAK,UAAU,eAAe,CACnC,OAAe;IAEf,IAAI,CAAC;QACH,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,KAAK;gBACR,0EAA0E;gBAC1E,OAAO,MAAM,kDAAO,uBAAuB,IAAE,IAAI,CAC/C,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAC/B,CAAA;YACH,KAAK,QAAQ;gBACX,0EAA0E;gBAC1E,OAAO,MAAM,kDAAO,0BAA0B,IAAE,IAAI,CAClD,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAClC,CAAA;YACH;gBACE,OAAO,SAAS,CAAA;QACpB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}

package/dist/utils/sortUtils.d.ts

@@ -0,0 +1,24 @@
+import { Address } from 'viem';
+/**
+ * Sorts two token addresses to match the smart contract's _sortTokens behavior.
+ * Compares addresses as numeric values (BigInt), matching Solidity's address comparison.
+ *
+ * Solidity reference:
+ * ```solidity
+ * function _sortTokens(address a, address b) private pure returns (address, address) {
+ *   return (a < b) ? (a, b) : (b, a);
+ * }
+ * ```
+ */
+export declare function sortTokenAddresses(tokenA: Address, tokenB: Address): [Address, Address];
+/**
+ * Creates a canonical route ID from two addresses.
+ * Uses numeric address comparison to match contract behavior.
+ */
+export declare function canonicalAddressKey(addressA: Address, addressB: Address, separator?: string): string;
+/**
+ * Creates a canonical pair key from two symbols.
+ * Uses standard string comparison for human-readable IDs.
+ */
+export declare function canonicalSymbolKey(symbolA: string, symbolB: string, separator?: string): string;
+//# sourceMappingURL=sortUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sortUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sortUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAE9B;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,OAAO,GACd,CAAC,OAAO,EAAE,OAAO,CAAC,CAIpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,OAAO,EACjB,SAAS,SAAM,GACd,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,SAAS,SAAM,GACd,MAAM,CAIR"}

package/dist/utils/sortUtils.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortTokenAddresses = sortTokenAddresses;
+exports.canonicalAddressKey = canonicalAddressKey;
+exports.canonicalSymbolKey = canonicalSymbolKey;
+/**
+ * Sorts two token addresses to match the smart contract's _sortTokens behavior.
+ * Compares addresses as numeric values (BigInt), matching Solidity's address comparison.
+ *
+ * Solidity reference:
+ * ```solidity
+ * function _sortTokens(address a, address b) private pure returns (address, address) {
+ *   return (a < b) ? (a, b) : (b, a);
+ * }
+ * ```
+ */
+function sortTokenAddresses(tokenA, tokenB) {
+    return BigInt(tokenA) < BigInt(tokenB)
+        ? [tokenA, tokenB]
+        : [tokenB, tokenA];
+}
+/**
+ * Creates a canonical route ID from two addresses.
+ * Uses numeric address comparison to match contract behavior.
+ */
+function canonicalAddressKey(addressA, addressB, separator = '-') {
+    const [first, second] = sortTokenAddresses(addressA, addressB);
+    return `${first}${separator}${second}`;
+}
+/**
+ * Creates a canonical pair key from two symbols.
+ * Uses standard string comparison for human-readable IDs.
+ */
+function canonicalSymbolKey(symbolA, symbolB, separator = '-') {
+    return symbolA < symbolB
+        ? `${symbolA}${separator}${symbolB}`
+        : `${symbolB}${separator}${symbolA}`;
+}
+//# sourceMappingURL=sortUtils.js.map

package/dist/utils/sortUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sortUtils.js","sourceRoot":"","sources":["../../src/utils/sortUtils.ts"],"names":[],"mappings":";;AAaA,gDAOC;AAMD,kDAOC;AAMD,gDAQC;AA7CD;;;;;;;;;;GAUG;AACH,SAAgB,kBAAkB,CAChC,MAAe,EACf,MAAe;IAEf,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;QACpC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC;QAClB,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AACtB,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CACjC,QAAiB,EACjB,QAAiB,EACjB,SAAS,GAAG,GAAG;IAEf,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAC9D,OAAO,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,EAAE,CAAA;AACxC,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAChC,OAAe,EACf,OAAe,EACf,SAAS,GAAG,GAAG;IAEf,OAAO,OAAO,GAAG,OAAO;QACtB,CAAC,CAAC,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,EAAE;QACpC,CAAC,CAAC,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,EAAE,CAAA;AACxC,CAAC"}

package/dist/utils/tokens.d.ts

@@ -0,0 +1,78 @@
+import type { Token } from '../core/types';
+/**
+ * Enum of all token symbols across all supported chains
+ */
+export declare enum TokenSymbol {
+    AUDm = "AUDm",
+    BRLm = "BRLm",
+    CADm = "CADm",
+    CELO = "CELO",
+    CHFm = "CHFm",
+    COPm = "COPm",
+    EURm = "EURm",
+    GBPm = "GBPm",
+    GHSm = "GHSm",
+    JPYm = "JPYm",
+    KESm = "KESm",
+    NGNm = "NGNm",
+    PHPm = "PHPm",
+    PUSO = "PUSO",
+    USDC = "USDC",
+    USDm = "USDm",
+    USD_ = "USD\u20AE",
+    XOFm = "XOFm",
+    ZARm = "ZARm",
+    axlEUROC = "axlEUROC",
+    axlUSDC = "axlUSDC",
+    cAUD = "cAUD",
+    cCAD = "cCAD",
+    cCHF = "cCHF",
+    cCOP = "cCOP",
+    cEUR = "cEUR",
+    cGBP = "cGBP",
+    cGHS = "cGHS",
+    cJPY = "cJPY",
+    cKES = "cKES",
+    cNGN = "cNGN",
+    cREAL = "cREAL",
+    cUSD = "cUSD",
+    cZAR = "cZAR",
+    eXOF = "eXOF"
+}
+/**
+ * Get cached tokens for a specific chain ID
+ * @param chainId - The chain ID to get tokens for
+ * @returns Promise resolving to the cached tokens array, or undefined if not available
+ */
+export declare function getCachedTokens(chainId: number): Promise<readonly Token[] | undefined>;
+/**
+ * Get cached tokens synchronously for a specific chain ID
+ * @param chainId - The chain ID to get tokens for
+ * @returns The cached tokens array
+ * @throws Error if tokens are not available for the chain
+ */
+export declare function getCachedTokensSync(chainId: number): readonly Token[];
+/**
+ * Mapping of token addresses by chain ID and token symbol
+ * Useful for quickly looking up a token address by its symbol on a specific chain
+ */
+export declare const TOKEN_ADDRESSES_BY_CHAIN: {
+    [chainId: number]: {
+        [tokenSymbol in TokenSymbol]?: string;
+    };
+};
+/**
+ * Get token address by chain ID and symbol
+ * @param chainId - The chain ID
+ * @param symbol - The token symbol
+ * @returns The token address or undefined if not found
+ */
+export declare function getTokenAddress(chainId: number, symbol: TokenSymbol): string | undefined;
+/**
+ * Find a token by its symbol on a specific chain
+ * @param chainId - The chain ID
+ * @param symbol - The token symbol
+ * @returns The token object or undefined if not found
+ */
+export declare function findTokenBySymbol(chainId: number, symbol: TokenSymbol): Token | undefined;
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/utils/tokens.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAE1C;;GAEG;AACH,oBAAY,WAAW;IACrB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,cAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;IACf,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;CACd;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC,CASvC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,EAAE,CAWrE;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE;IACrC,CAAC,OAAO,EAAE,MAAM,GAAG;SAAG,WAAW,IAAI,WAAW,CAAC,CAAC,EAAE,MAAM;KAAE,CAAA;CA8C7D,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,KAAK,GAAG,SAAS,CAOnB"}