@mento-protocol/mento-sdk 3.2.3 → 3.2.4

package/dist/{cjs → utils}/routeUtils.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasSpreadData = exports.getIntermediateToken = exports.selectBestRoute = exports.selectOptimalRoutes = exports.createTwoHopPair = exports.generateAllRoutes = exports.buildConnectivityStructures = void 0;
+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.
  *
@@ -11,23 +18,23 @@ exports.hasSpreadData = exports.getIntermediateToken = exports.selectBestRoute =
  *
  * ```
  * Input: TradablePairs = [
- *   { id: 'cUSD-CELO', assets: [cUSD, CELO], path: [exchange1_CELO_cUSD] },
- *   { id: 'CELO-cEUR', assets: [CELO, cEUR], path: [exchange2_CELO_cEUR] }
+ *   { id: 'USDm-CELO', assets: [USDm, CELO], path: [exchange1_CELO_USDm] },
+ *   { id: 'CELO-EURm', assets: [CELO, EURm], path: [exchange2_CELO_EURm] }
  * ]
  *
  * Step 1 - Build addrToSymbol map:
- *   cUSD.address → 'cUSD'
+ *   USDm.address → 'USDm'
  *   CELO.address → 'CELO'
- *   cEUR.address → 'cEUR'
+ *   EURm.address → 'EURm'
  *
  * Step 2 - Build directPathMap (sorted alphabetically for consistency):
- *   'CELO_addr-cEUR_addr' → exchange2_CELO_cEUR
- *   'CELO_addr-cUSD_addr' → exchange1_CELO_cUSD
+ *   'CELO_addr-EURm_addr' → exchange2_CELO_EURm
+ *   'CELO_addr-USDm_addr' → exchange1_CELO_USDm
  *
  * Step 3 - Build bidirectional tokenGraph:
- *   cUSD.address → Set([CELO.address])
- *   CELO.address → Set([cUSD.address, cEUR.address])
- *   cEUR.address → Set([CELO.address])
+ *   USDm.address → Set([CELO.address])
+ *   CELO.address → Set([USDm.address, EURm.address])
+ *   EURm.address → Set([CELO.address])
  * ```
  *
  * **Result**: We can now efficiently answer:
@@ -35,60 +42,57 @@ exports.hasSpreadData = exports.getIntermediateToken = exports.selectBestRoute =
  * - "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
+ * @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] }
+ *   { id: 'USDm-CELO', assets: [USDm, CELO], path: [exchange1] },
+ *   { id: 'CELO-EURm', assets: [CELO, EURm], 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
+ * // 1. Check if USDm connects to anything: connectivityData.tokenGraph.get(USDm.address) → [CELO.address]
+ * // 2. Check if CELO connects to EURm: connectivityData.tokenGraph.get(CELO.address) → [USDm.address, EURm.address] ✓
+ * // 3. Get exchange details: connectivityData.directPathMap.get('CELO_addr-EURm_addr') → exchange2_CELO_EURm
+ * // Result: Found route USDm → CELO → EURm with exchange details
  * ```
  */
-function buildConnectivityStructures(directPairs) {
+function buildConnectivityStructures(directRoutes) {
     const addrToSymbol = new Map();
-    const directPathMap = new Map();
+    const directRouteMap = new Map();
     const tokenGraph = new Map();
-    for (const pair of directPairs) {
-        const [assetA, assetB] = pair.assets;
+    for (const route of directRoutes) {
+        const [tokenA, tokenB] = route.tokens;
         // Build address-to-symbol map for quick symbol lookups
-        addrToSymbol.set(assetA.address, assetA.symbol);
-        addrToSymbol.set(assetB.address, assetB.symbol);
+        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 sortedAddresses = [assetA.address, assetB.address]
-            .sort()
-            .join('-');
-        if (!directPathMap.has(sortedAddresses)) {
-            directPathMap.set(sortedAddresses, pair.path[0]);
+        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(assetA.address))
-            tokenGraph.set(assetA.address, new Set());
-        if (!tokenGraph.has(assetB.address))
-            tokenGraph.set(assetB.address, new Set());
-        tokenGraph.get(assetA.address).add(assetB.address);
-        tokenGraph.get(assetB.address).add(assetA.address);
+        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, directPathMap, tokenGraph, directPairs };
+    return { addrToSymbol, directRouteMap, tokenGraph, directRoutes };
 }
-exports.buildConnectivityStructures = buildConnectivityStructures;
 /**
  * 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)
+ * 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
@@ -96,71 +100,70 @@ exports.buildConnectivityStructures = buildConnectivityStructures;
  *
  * **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.
+ * the best one based on cost data or heuristics.
  *
- * **Canonical Pair IDs**: All pairs use alphabetically sorted symbols
- * (e.g., 'cEUR-cUSD' not 'cUSD-cEUR') for consistent identification.
+ * **Canonical Route IDs**: All routes use alphabetically sorted symbols
+ * (e.g., 'EURm-USDm' not 'USDm-EURm') for consistent identification.
  *
  * @param connectivityData - The connectivity data from buildConnectivityStructures()
- * @returns Map of pair ID -> array of possible routes for that pair
+ * @returns Map of route ID -> array of possible routes for that token pair
  *
  * @example
  * ```typescript
- * // Given direct pairs: cUSD-CELO, CELO-cEUR, cUSD-USDC
+ * // Given direct routes: USDm-CELO, CELO-EURm, USDm-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
+ * // 'USDm-CELO' -> [{ path: [USDm->CELO] }] // direct route
+ * // 'EURm-USDm' -> [
+ * //   { path: [USDm->USDC, USDC->EURm] } // two-hop via USDC
+ * //   { path: [USDm->CELO, CELO->EURm] } // two-hop via CELO
  * // ]
  * ```
  */
 function generateAllRoutes(connectivityData) {
-    const { addrToSymbol, directPathMap, tokenGraph, directPairs } = connectivityData;
+    const { addrToSymbol, directRouteMap, tokenGraph, directRoutes } = connectivityData;
     const allRoutes = new Map();
     // Step 1: Add all direct pairs (single-hop routes)
-    for (const pair of directPairs) {
-        if (!allRoutes.has(pair.id)) {
-            allRoutes.set(pair.id, []);
+    for (const route of directRoutes) {
+        if (!allRoutes.has(route.id)) {
+            allRoutes.set(route.id, []);
         }
-        allRoutes.get(pair.id).push(pair);
+        allRoutes.get(route.id).push(route);
     }
-    // Step 2: Generate two-hop pairs using graph traversal
+    // 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.)
+    // 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 = cUSD, neighbors might be [CELO, USDC, cKES]
+        // 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 [cUSD, cEUR, cBRL]
+            // Example: If intermediate = CELO, secondHopNeighbors might be [USDm, EURm, BRLm]
             for (const end of secondHopNeighbors) {
-                // Skip circular routes like cUSD → CELO → cUSD (pointless)
+                // Skip circular routes like USDm → CELO → USDm (pointless)
                 if (end === start)
                     continue;
                 // At this point we have a potential route: start → intermediate → end
-                // Example: cUSD → CELO → cEUR
+                // Example: USDm → CELO → EURm
                 // Try to create a valid two-hop trading pair from this route
-                const twoHopPair = createTwoHopPair(start, intermediate, end, addrToSymbol, directPathMap);
+                const twoHopRoute = createTwoHopRoute(start, intermediate, end, addrToSymbol, directRouteMap);
                 // If we successfully created the pair, add it to our collection
-                if (twoHopPair) {
-                    if (!allRoutes.has(twoHopPair.id)) {
-                        allRoutes.set(twoHopPair.id, []);
+                if (twoHopRoute) {
+                    if (!allRoutes.has(twoHopRoute.id)) {
+                        allRoutes.set(twoHopRoute.id, []);
                     }
-                    allRoutes.get(twoHopPair.id).push(twoHopPair);
+                    allRoutes.get(twoHopRoute.id).push(twoHopRoute);
                 }
             }
         }
     }
     return allRoutes;
 }
-exports.generateAllRoutes = generateAllRoutes;
 /**
  * Creates a two-hop tradable pair if valid exchange hops exist.
  *
@@ -184,56 +187,55 @@ exports.generateAllRoutes = generateAllRoutes;
  *
  * @example
  * ```typescript
- * // Create route: cUSD -> CELO -> cEUR
+ * // Create route: USDm -> CELO -> EURm
  * const pair = createTwoHopPair(
- *   '0x765D...', // cUSD address
+ *   '0x765D...', // USDm address
  *   '0x471E...', // CELO address
- *   '0xD876...', // cEUR address
+ *   '0xD876...', // EURm address
  *   addrToSymbol,
  *   directPathMap
  * )
  *
  * // Result:
  * // {
- * //   id: 'cEUR-cUSD',           // alphabetical order
- * //   assets: [cEUR, cUSD],     // alphabetical order
+ * //   id: 'EURm-USDm',           // alphabetical order
+ * //   assets: [EURm, USDm],     // alphabetical order
  * //   path: [                   // actual routing path
- * //     { cUSD->CELO exchange },
- * //     { CELO->cEUR exchange }
+ * //     { USDm->CELO exchange },
+ * //     { CELO->EURm exchange }
  * //   ]
  * // }
  * ```
  */
-function createTwoHopPair(startToken, intermediateToken, endToken, addrToSymbol, directPathMap) {
-    // Validate that both start and end tokens exist in our address-to-symbol map
-    const startSymbol = addrToSymbol.get(startToken);
-    const endSymbol = addrToSymbol.get(endToken);
-    if (!startSymbol || !endSymbol)
+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;
-    // Create Asset objects from address and symbol
-    const startAsset = { address: startToken, symbol: startSymbol };
-    const endAsset = { address: endToken, symbol: endSymbol };
     // Find exchange hops for both segments of the two-hop route
     // Keys are sorted token addresses for consistent lookup
-    const hop1Key = [startToken, intermediateToken].sort().join('-');
-    const hop2Key = [intermediateToken, endToken].sort().join('-');
-    const hop1 = directPathMap.get(hop1Key);
-    const hop2 = directPathMap.get(hop2Key);
+    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 sortedSymbols = [startSymbol, endSymbol].sort();
-    const pairId = `${sortedSymbols[0]}-${sortedSymbols[1]}`;
-    // Assets array follows alphabetical ordering for consistency
-    const assets = startSymbol <= endSymbol ? [startAsset, endAsset] : [endAsset, startAsset];
+    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: pairId,
-        assets,
+        id: routeId,
+        tokens,
         path: [hop1, hop2], // Preserves actual routing path for execution
     };
 }
-exports.createTwoHopPair = createTwoHopPair;
 /**
  * Selects optimal routes from all candidates based on spread data or heuristics.
  *
@@ -255,59 +257,58 @@ exports.createTwoHopPair = createTwoHopPair;
  *
  * @example
  * ```typescript
- * // Multiple routes for cUSD-cEUR pair
+ * // Multiple routes for USDm-EURm 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
+ *   ['EURm-USDm', [
+ *     { path: [USDm->CELO->EURm], costData: { totalCostPercent: 0.5 } },
+ *     { path: [USDm->BRLm->EURm], costData: { totalCostPercent: 0.3 } },
+ *     { path: [USDm->EURm] } // direct route, no cost data
  *   ]]
  * ])
  *
  * const optimal = selectOptimalRoutes(candidates, false, assetMap)
- * // Returns the cUSD->cREAL->cEUR route (lowest spread: 0.3%)
+ * // Returns the USDm->BRLm->EURm route (lowest cost: 0.3%)
  * ```
  */
 function selectOptimalRoutes(allRoutes, returnAllRoutes, addrToSymbol) {
     const result = new Map();
-    for (const [pairId, routes] of allRoutes) {
+    for (const [routeId, routes] of allRoutes) {
         if (routes.length === 1) {
             // Only one route available - use it directly
-            result.set(pairId, routes[0]);
+            result.set(routeId, routes[0]);
         }
         else if (returnAllRoutes) {
             // Return all routes with unique keys (used for cache generation)
             routes.forEach((route, index) => {
-                result.set(`${pairId}_${index}`, route);
+                result.set(`${routeId}_${index}`, route);
             });
         }
         else {
             // Multiple routes - select the best one using optimization logic
             const bestRoute = selectBestRoute(routes, addrToSymbol);
-            result.set(pairId, bestRoute);
+            result.set(routeId, bestRoute);
         }
     }
     return Array.from(result.values());
 }
-exports.selectOptimalRoutes = selectOptimalRoutes;
 /**
- * Selects the best route from candidates using spread data or fallback heuristics.
+ * 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 - Spread-Based Optimization** (Preferred):
- * - Use routes with spread data (actual cost information)
- * - Select route with lowest `totalSpreadPercent`
+ * **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 spread data available, prefer direct (single-hop) routes
+ * - 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
+ * - 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
@@ -319,29 +320,27 @@ exports.selectOptimalRoutes = selectOptimalRoutes;
  * @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
+ *   { 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% spread)
+ * // Returns the A->D->C route (0.4% cost)
  * ```
  */
 function selectBestRoute(candidates, addrToSymbol) {
-    // Tier 1: Prefer routes with spread data (lowest spread wins)
-    const candidatesWithSpread = candidates.filter(hasSpreadData);
-    if (candidatesWithSpread.length > 0) {
-        return candidatesWithSpread.reduce((best, current) => current.spreadData.totalSpreadPercent < best.spreadData.totalSpreadPercent
-            ? current
-            : best);
+    // 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 stablecoins = ['USDm', 'EURm', 'USDC', 'USDT'];
     const routeWithStablecoin = candidates.find((candidate) => {
         const intermediateToken = getIntermediateToken(candidate);
         if (!intermediateToken)
@@ -352,7 +351,6 @@ function selectBestRoute(candidates, addrToSymbol) {
     // Tier 4: Use first available route as last resort
     return routeWithStablecoin || candidates[0];
 }
-exports.selectBestRoute = selectBestRoute;
 /**
  * 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).
@@ -360,13 +358,14 @@ exports.selectBestRoute = selectBestRoute;
 function getIntermediateToken(route) {
     // Find the common token between the two hops
     const [hop1, hop2] = route.path;
-    return hop1.assets.find((addr) => hop2.assets.includes(addr));
+    const hop1Tokens = [hop1.token0, hop1.token1];
+    const hop2Tokens = [hop2.token0, hop2.token1];
+    return hop1Tokens.find((addr) => hop2Tokens.includes(addr));
 }
-exports.getIntermediateToken = getIntermediateToken;
 /**
- * Type guard to check if a Route has spread data.
+ * Type guard to check if a Route has cost data.
  */
-function hasSpreadData(pair) {
-    return 'spreadData' in pair && pair.spreadData !== undefined;
+function hasCostData(pair) {
+    return 'costData' in pair && pair.costData !== undefined;
 }
-exports.hasSpreadData = hasSpreadData;
+//# sourceMappingURL=routeUtils.js.map

package/dist/utils/routes.d.ts

@@ -0,0 +1,3 @@
+export { getCachedRoutes, cachedRoutes } from '../cache/routes';
+export type { RouteWithCost } from '../core/types';
+//# sourceMappingURL=routes.d.ts.map

package/dist/utils/routes.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachedRoutes = exports.getCachedRoutes = void 0;
+// Re-export from consolidated cache
+var routes_1 = require("../cache/routes");
+Object.defineProperty(exports, "getCachedRoutes", { enumerable: true, get: function () { return routes_1.getCachedRoutes; } });
+Object.defineProperty(exports, "cachedRoutes", { enumerable: true, get: function () { return routes_1.cachedRoutes; } });
+//# sourceMappingURL=routes.js.map

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.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/tokens.d.ts

@@ -0,0 +1,2 @@
+export { TokenSymbol, cachedTokens, getCachedTokens, getCachedTokensSync, getTokenAddress, findTokenBySymbol, TOKEN_ADDRESSES_BY_CHAIN, } from '../cache/tokens';
+//# sourceMappingURL=tokens.d.ts.map

package/dist/utils/tokens.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_ADDRESSES_BY_CHAIN = exports.findTokenBySymbol = exports.getTokenAddress = exports.getCachedTokensSync = exports.getCachedTokens = exports.cachedTokens = exports.TokenSymbol = void 0;
+// Re-export from consolidated cache
+var tokens_1 = require("../cache/tokens");
+Object.defineProperty(exports, "TokenSymbol", { enumerable: true, get: function () { return tokens_1.TokenSymbol; } });
+Object.defineProperty(exports, "cachedTokens", { enumerable: true, get: function () { return tokens_1.cachedTokens; } });
+Object.defineProperty(exports, "getCachedTokens", { enumerable: true, get: function () { return tokens_1.getCachedTokens; } });
+Object.defineProperty(exports, "getCachedTokensSync", { enumerable: true, get: function () { return tokens_1.getCachedTokensSync; } });
+Object.defineProperty(exports, "getTokenAddress", { enumerable: true, get: function () { return tokens_1.getTokenAddress; } });
+Object.defineProperty(exports, "findTokenBySymbol", { enumerable: true, get: function () { return tokens_1.findTokenBySymbol; } });
+Object.defineProperty(exports, "TOKEN_ADDRESSES_BY_CHAIN", { enumerable: true, get: function () { return tokens_1.TOKEN_ADDRESSES_BY_CHAIN; } });
+//# sourceMappingURL=tokens.js.map

package/dist/utils/tradingLimits.d.ts

@@ -0,0 +1,41 @@
+import type { TradingLimit, TradingLimitsConfigV1, TradingLimitsStateV1, TradingLimitsConfigV2, TradingLimitsStateV2 } from '../core/types';
+/**
+ * Compute limit ID for Broker (V1) trading limits.
+ * limitId = exchangeId XOR bytes32(uint256(uint160(token)))
+ *
+ * @param exchangeId - The exchange ID (bytes32)
+ * @param token - The token address
+ * @returns The limit ID as hex string
+ */
+export declare function computeLimitId(exchangeId: string, token: string): `0x${string}`;
+/**
+ * Calculate trading limits from V1 config and state (Broker/Virtual pools).
+ * Returns human-friendly TradingLimit objects with maxIn/maxOut/until.
+ *
+ * @param config - V1 trading limits configuration
+ * @param state - V1 trading limits state
+ * @param asset - Token address
+ * @param tokenDecimals - Token decimals for consumer reference
+ * @returns Array of TradingLimit objects
+ */
+export declare function calculateTradingLimitsV1(config: TradingLimitsConfigV1, state: TradingLimitsStateV1, asset: string, tokenDecimals: number): TradingLimit[];
+/**
+ * Calculate trading limits from V2 config and state (FPMM pools).
+ * V2 uses fixed timeframes: 5 min for L0, 1 day for L1.
+ * Values are stored with 15 decimals precision.
+ *
+ * @param config - V2 trading limits configuration
+ * @param state - V2 trading limits state
+ * @param asset - Token address
+ * @returns Array of TradingLimit objects
+ */
+export declare function calculateTradingLimitsV2(config: TradingLimitsConfigV2, state: TradingLimitsStateV2, asset: string): TradingLimit[];
+/**
+ * Check if any trading limits are configured (flags > 0 for V1, or limit0/limit1 > 0 for V2)
+ */
+export declare function hasConfiguredLimitsV1(config: TradingLimitsConfigV1): boolean;
+/**
+ * Check if any trading limits are configured for V2
+ */
+export declare function hasConfiguredLimitsV2(config: TradingLimitsConfigV2): boolean;
+//# sourceMappingURL=tradingLimits.d.ts.map