@mento-protocol/mento-sdk 1.0.9 → 1.10.0

package/dist/cjs/src/routeUtils.js

@@ -0,0 +1,372 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSpreadData = exports.getIntermediateToken = exports.selectBestRoute = exports.selectOptimalRoutes = exports.createTwoHopPair = exports.generateAllRoutes = exports.buildConnectivityStructures = void 0;
+/**
+ * Builds the connectivity data structures needed for route generation.
+ *
+ * Transforms a list of direct trading pairs into our ConnectivityData
+ * that allow us to quickly find trading routes.
+ *
+ * **Construction Process:**
+ *
+ * ```
+ * Input: TradablePairs = [
+ *   { id: 'cUSD-CELO', assets: [cUSD, CELO], path: [exchange1_CELO_cUSD] },
+ *   { id: 'CELO-cEUR', assets: [CELO, cEUR], path: [exchange2_CELO_cEUR] }
+ * ]
+ *
+ * Step 1 - Build addrToSymbol map:
+ *   cUSD.address → 'cUSD'
+ *   CELO.address → 'CELO'
+ *   cEUR.address → 'cEUR'
+ *
+ * Step 2 - Build directPathMap (sorted alphabetically for consistency):
+ *   'CELO_addr-cEUR_addr' → exchange2_CELO_cEUR
+ *   'CELO_addr-cUSD_addr' → exchange1_CELO_cUSD
+ *
+ * Step 3 - Build bidirectional tokenGraph:
+ *   cUSD.address → Set([CELO.address])
+ *   CELO.address → Set([cUSD.address, cEUR.address])
+ *   cEUR.address → Set([CELO.address])
+ * ```
+ *
+ * **Result**: We can now efficiently answer:
+ * - "What's the symbol for address X?" → addrToSymbol.get(addr)
+ * - "What exchange connects tokens X and Y?" → directPathMap.get(sortedAddressPairKey)
+ * - "What tokens can I reach from token X?" → tokenGraph.get(X)
+ *
+ * @param directPairs - Array of direct trading pairs
+ * @returns Connectivity data structure for efficient route generation
+ *
+ * @example
+ * ```typescript
+ * const directPairs = [
+ *   { id: 'cUSD-CELO', assets: [cUSD, CELO], path: [exchange1] },
+ *   { id: 'CELO-cEUR', assets: [CELO, cEUR], path: [exchange2] }
+ * ]
+ *
+ * const connectivityData = buildConnectivityStructures(directPairs)
+ *
+ * // Now we can efficiently find routes:
+ * // 1. Check if cUSD connects to anything: connectivityData.tokenGraph.get(cUSD.address) → [CELO.address]
+ * // 2. Check if CELO connects to cEUR: connectivityData.tokenGraph.get(CELO.address) → [cUSD.address, cEUR.address] ✓
+ * // 3. Get exchange details: connectivityData.directPathMap.get('CELO_addr-cEUR_addr') → exchange2_CELO_cEUR
+ * // Result: Found route cUSD → CELO → cEUR with exchange details
+ * ```
+ */
+function buildConnectivityStructures(directPairs) {
+    const addrToSymbol = new Map();
+    const directPathMap = new Map();
+    const tokenGraph = new Map();
+    for (const pair of directPairs) {
+        const [assetA, assetB] = pair.assets;
+        // Build address-to-symbol map for quick symbol lookups
+        addrToSymbol.set(assetA.address, assetA.symbol);
+        addrToSymbol.set(assetB.address, assetB.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]);
+        }
+        // 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);
+    }
+    return { addrToSymbol, directPathMap, tokenGraph, directPairs };
+}
+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)
+ * 2. **Discovers two-hop routes** using graph traversal:
+ *    - For each token A, find its neighbors (tokens directly connected)
+ *    - For each neighbor B, find B's neighbors
+ *    - If B connects to token C (C ≠ A), then A->B->C is a valid route
+ *
+ * **Route Deduplication**: Multiple routes between the same token pair
+ * are collected in arrays, allowing the selection algorithm to choose
+ * the best one based on spread data or heuristics.
+ *
+ * **Canonical Pair IDs**: All pairs use alphabetically sorted symbols
+ * (e.g., 'cEUR-cUSD' not 'cUSD-cEUR') for consistent identification.
+ *
+ * @param connectivityData - The connectivity data from buildConnectivityStructures()
+ * @returns Map of pair ID -> array of possible routes for that pair
+ *
+ * @example
+ * ```typescript
+ * // Given direct pairs: cUSD-CELO, CELO-cEUR, cUSD-USDC
+ * const allRoutes = generateAllRoutes(connectivityData)
+ *
+ * // Results might include:
+ * // 'cUSD-CELO' -> [{ path: [cUSD->CELO] }] // direct route
+ * // 'cEUR-cUSD' -> [
+ * //   { path: [cUSD->USDC, USDC->cEUR] } // two-hop via USDC
+ * //   { path: [cUSD->CELO, CELO->cEUR] } // two-hop via CELO
+ * // ]
+ * ```
+ */
+function generateAllRoutes(connectivityData) {
+    const { addrToSymbol, directPathMap, tokenGraph, directPairs } = 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, []);
+        }
+        allRoutes.get(pair.id).push(pair);
+    }
+    // Step 2: Generate two-hop pairs 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 twoHopPair = createTwoHopPair(start, intermediate, end, addrToSymbol, directPathMap);
+                // If we successfully created the pair, add it to our collection
+                if (twoHopPair) {
+                    if (!allRoutes.has(twoHopPair.id)) {
+                        allRoutes.set(twoHopPair.id, []);
+                    }
+                    allRoutes.get(twoHopPair.id).push(twoHopPair);
+                }
+            }
+        }
+    }
+    return allRoutes;
+}
+exports.generateAllRoutes = generateAllRoutes;
+/**
+ * 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 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)
+        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);
+    // 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];
+    return {
+        id: pairId,
+        assets,
+        path: [hop1, hop2], // Preserves actual routing path for execution
+    };
+}
+exports.createTwoHopPair = createTwoHopPair;
+/**
+ * Selects optimal routes from all candidates based on spread data or heuristics.
+ *
+ * This is the route optimization engine that implements the following logic:
+ *
+ * **For Single Route**: Use it directly (no optimization needed)
+ *
+ * **For Multiple Routes**:
+ * - If `returnAllRoutes=true`: Return all routes (used for cache generation)
+ * - If `returnAllRoutes=false`: Apply optimization to select the best route
+ *
+ * **Route Selection Strategy**: Delegates to `selectBestRoute()` which uses
+ * a multi-tier approach prioritizing cost efficiency and reliability.
+ *
+ * @param allRoutes - Map of pair ID -> array of possible routes
+ * @param returnAllRoutes - Whether to return all routes or optimize selection
+ * @param assetMap - Asset map for token symbol lookups during optimization
+ * @returns Array of selected optimal routes
+ *
+ * @example
+ * ```typescript
+ * // Multiple routes for cUSD-cEUR pair
+ * const candidates = new Map([
+ *   ['cEUR-cUSD', [
+ *     { path: [cUSD->CELO->cEUR], spreadData: { totalSpreadPercent: 0.5 } },
+ *     { path: [cUSD->cREAL->cEUR], spreadData: { totalSpreadPercent: 0.3 } },
+ *     { path: [cUSD->cEUR] } // direct route, no spread data
+ *   ]]
+ * ])
+ *
+ * const optimal = selectOptimalRoutes(candidates, false, assetMap)
+ * // Returns the cUSD->cREAL->cEUR route (lowest spread: 0.3%)
+ * ```
+ */
+function selectOptimalRoutes(allRoutes, returnAllRoutes, addrToSymbol) {
+    const result = new Map();
+    for (const [pairId, routes] of allRoutes) {
+        if (routes.length === 1) {
+            // Only one route available - use it directly
+            result.set(pairId, routes[0]);
+        }
+        else if (returnAllRoutes) {
+            // Return all routes with unique keys (used for cache generation)
+            routes.forEach((route, index) => {
+                result.set(`${pairId}_${index}`, route);
+            });
+        }
+        else {
+            // Multiple routes - select the best one using optimization logic
+            const bestRoute = selectBestRoute(routes, addrToSymbol);
+            result.set(pairId, bestRoute);
+        }
+    }
+    return Array.from(result.values());
+}
+exports.selectOptimalRoutes = selectOptimalRoutes;
+/**
+ * Selects the best route from candidates using spread data or fallback heuristics.
+ *
+ * This function implements a sophisticated route selection algorithm with
+ * multiple optimization tiers:
+ *
+ * **Tier 1 - Spread-Based Optimization** (Preferred):
+ * - Use routes with spread data (actual cost information)
+ * - Select route with lowest `totalSpreadPercent`
+ * - This provides the most cost-efficient trading
+ *
+ * **Tier 2 - Direct Route Preference** (Fallback):
+ * - If no spread data available, prefer direct (single-hop) routes
+ * - Direct routes have lower execution risk and gas costs
+ *
+ * **Tier 3 - Major Stablecoin Preference** (Final Fallback):
+ * - For two-hop routes, prefer those going through major stablecoins
+ * - Major FX currencies like cUSD and cEUR typically have better liquidity
+ *
+ * **Tier 4 - First Available** (Last Resort):
+ * - If no other heuristics apply, use the first route found
+ *
+ * @param candidates - Array of possible routes for the same token pair
+ * @param assetMap - Asset map for token symbol lookups
+ * @returns The optimal route selected using the tier system
+ *
+ * @example
+ * ```typescript
+ * const candidates = [
+ *   { path: [A->B->C], spreadData: { totalSpreadPercent: 0.8 } },
+ *   { path: [A->D->C], spreadData: { totalSpreadPercent: 0.4 } }, // Winner: lowest spread
+ *   { path: [A->C] }, // direct route, no spread data
+ * ]
+ *
+ * const best = selectBestRoute(candidates, assetMap)
+ * // Returns the A->D->C route (0.4% spread)
+ * ```
+ */
+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 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];
+}
+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).
+ */
+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));
+}
+exports.getIntermediateToken = getIntermediateToken;
+/**
+ * Type guard to check if a Route has spread data.
+ */
+function hasSpreadData(pair) {
+    return 'spreadData' in pair && pair.spreadData !== undefined;
+}
+exports.hasSpreadData = hasSpreadData;

package/dist/cjs/{utils.d.ts → src/utils.d.ts}

@@ -1,5 +1,6 @@
 import { BigNumberish, providers, Signer } from 'ethers';
 import { Address } from './interfaces';
+import { TradablePair } from './mento';
 /**
  * Gets the chain ID from a signer or provider
  * @param signerOrProvider an ethers provider or signer
@@ -40,3 +41,10 @@ export declare function getSymbolFromTokenAddress(tokenAddr: Address, signerOrPr
  * @returns the populated TransactionRequest object
  */
 export declare function increaseAllowance(tokenAddr: string, spender: string, amount: BigNumberish, signerOrProvider: Signer | providers.Provider): Promise<providers.TransactionRequest>;
+/**
+ * Find a token address by its symbol from tradable pairs
+ * @param pairs array of tradable pairs to search through
+ * @param symbol the token symbol to find (case-insensitive)
+ * @returns the token address if found, null otherwise
+ */
+export declare function findTokenBySymbol(pairs: readonly TradablePair[], symbol: string): string | null;

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

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.increaseAllowance = exports.getSymbolFromTokenAddress = exports.getBrokerAddressFromRegistry = exports.validateSignerOrProvider = exports.validateSigner = exports.getChainId = void 0;
+exports.findTokenBySymbol = exports.increaseAllowance = exports.getSymbolFromTokenAddress = exports.getBrokerAddressFromRegistry = exports.validateSignerOrProvider = exports.validateSigner = exports.getChainId = void 0;
 const ethers_1 = require("ethers");
 /**
  * Gets the chain ID from a signer or provider
@@ -110,3 +110,20 @@ function increaseAllowance(tokenAddr, spender, amount, signerOrProvider) {
     });
 }
 exports.increaseAllowance = increaseAllowance;
+/**
+ * Find a token address by its symbol from tradable pairs
+ * @param pairs array of tradable pairs to search through
+ * @param symbol the token symbol to find (case-insensitive)
+ * @returns the token address if found, null otherwise
+ */
+function findTokenBySymbol(pairs, symbol) {
+    for (const pair of pairs) {
+        for (const asset of pair.assets) {
+            if (asset.symbol.toLowerCase() === symbol.toLowerCase()) {
+                return asset.address;
+            }
+        }
+    }
+    return null;
+}
+exports.findTokenBySymbol = findTokenBySymbol;

package/dist/esm/scripts/cacheTradablePairs/config.d.ts

@@ -0,0 +1,5 @@
+import { TradablePairWithSpread } from '../../src/constants/tradablePairs';
+import { NETWORK_MAP, rpcUrls, SupportedChainId } from '../shared/network';
+export { NETWORK_MAP, rpcUrls };
+export { TradablePairWithSpread };
+export type { SupportedChainId };

package/dist/esm/scripts/cacheTradablePairs/config.js

@@ -0,0 +1,3 @@
+import { NETWORK_MAP, rpcUrls } from '../shared/network';
+// Re-export network constants for backward compatibility
+export { NETWORK_MAP, rpcUrls };

package/dist/esm/scripts/quotes/config.d.ts

@@ -0,0 +1,20 @@
+export declare const RPC_URLS: Record<number, string>;
+export declare const CHAIN_NAMES: Record<number, string>;
+export declare const CHAIN_NAME_TO_ID: Record<string, number>;
+export declare const DEFAULT_CHAIN_ID = 42220;
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const QUOTE_TIMEOUT_MS = 8000;
+export declare const DEFAULT_BATCH_SIZE = 10;
+export declare const DEFAULT_BATCH_DELAY_MS = 100;
+export declare const DEFAULT_SPREAD_FALLBACK = 0.25;
+export declare const MAX_DECIMAL_PLACES = 4;
+export declare const TOKEN_ABI_FRAGMENT: readonly [{
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}];
+export declare const DEFAULT_DECIMALS = 18;

package/dist/esm/scripts/quotes/config.js

@@ -0,0 +1,30 @@
+export const RPC_URLS = {
+    42220: 'https://forno.celo.org',
+    44787: 'https://alfajores-forno.celo-testnet.org',
+};
+export const CHAIN_NAMES = {
+    42220: 'Celo',
+    44787: 'Alfajores',
+};
+export const CHAIN_NAME_TO_ID = {
+    celo: 42220,
+    alfajores: 44787,
+};
+export const DEFAULT_CHAIN_ID = 42220;
+export const DEFAULT_TIMEOUT_MS = 10000;
+export const QUOTE_TIMEOUT_MS = 8000; // Timeout for individual quote calculations
+export const DEFAULT_BATCH_SIZE = 10;
+export const DEFAULT_BATCH_DELAY_MS = 100;
+export const DEFAULT_SPREAD_FALLBACK = 0.25;
+export const MAX_DECIMAL_PLACES = 4;
+// ERC20 token ABI fragment for decimals
+export const TOKEN_ABI_FRAGMENT = [
+    {
+        name: 'decimals',
+        type: 'function',
+        inputs: [],
+        outputs: [{ type: 'uint8' }],
+        stateMutability: 'view',
+    },
+];
+export const DEFAULT_DECIMALS = 18;

package/dist/esm/scripts/quotes/spread.d.ts

@@ -0,0 +1,25 @@
+import { TradablePair } from '../../src/mento';
+import { TradablePairWithSpread } from '../cacheTradablePairs/config';
+/**
+ * Calculates the total spread for a trading route by compounding spreads across all hops.
+ *
+ * For multi-hop routes, spreads compound multiplicatively:
+ * - Single hop: spread = pairSpread
+ * - Multi-hop: spread = (1 - ((1 - spread1) * (1 - spread2) * ...))
+ *
+ * @param route - The route to calculate spread for
+ * @param allPairs - All available pairs with spread data
+ * @returns Total spread as a decimal (e.g., 0.005 = 0.5%)
+ */
+export declare function calculateCompoundSpread(route: TradablePair, allPairs: readonly TradablePair[] | readonly TradablePairWithSpread[]): number;
+/**
+ * Creates a human-readable display string for a trading route.
+ * Shows token symbols and route structure (e.g., "USDC → cUSD → cEUR").
+ *
+ * @param tradablePair - The route to display
+ * @param fromSymbol - Symbol of the input token
+ * @param toSymbol - Symbol of the output token
+ * @param allPairs - All pairs data for symbol resolution
+ * @returns Formatted route string
+ */
+export declare function buildRouteDisplay(tradablePair: TradablePair, fromSymbol: string, toSymbol: string, allPairs: readonly TradablePair[] | readonly TradablePairWithSpread[]): string;

package/dist/esm/scripts/quotes/spread.js

@@ -0,0 +1,161 @@
+import { DEFAULT_SPREAD_FALLBACK } from './config';
+/**
+ * Calculates the total spread for a trading route by compounding spreads across all hops.
+ *
+ * For multi-hop routes, spreads compound multiplicatively:
+ * - Single hop: spread = pairSpread
+ * - Multi-hop: spread = (1 - ((1 - spread1) * (1 - spread2) * ...))
+ *
+ * @param route - The route to calculate spread for
+ * @param allPairs - All available pairs with spread data
+ * @returns Total spread as a decimal (e.g., 0.005 = 0.5%)
+ */
+export function calculateCompoundSpread(route, allPairs) {
+    if (route.path.length === 1) {
+        return getFixedSpreadForRoute(route, allPairs);
+    }
+    // For multi-hop routes, calculate compound spread
+    let compoundRate = 1; // Start with 100% (no loss)
+    for (const hop of route.path) {
+        const hopSpreadPercent = getHopSpreadPercent(hop, allPairs);
+        // Convert spread percentage to rate multiplier
+        // If spread is 0.25%, rate multiplier is 0.9975 (1 - 0.0025)
+        const hopRate = 1 - hopSpreadPercent / 100;
+        compoundRate *= hopRate;
+    }
+    // Convert back to spread percentage
+    return (1 - compoundRate) * 100;
+}
+/**
+ * Creates a human-readable display string for a trading route.
+ * Shows token symbols and route structure (e.g., "USDC → cUSD → cEUR").
+ *
+ * @param tradablePair - The route to display
+ * @param fromSymbol - Symbol of the input token
+ * @param toSymbol - Symbol of the output token
+ * @param allPairs - All pairs data for symbol resolution
+ * @returns Formatted route string
+ */
+export function buildRouteDisplay(tradablePair, fromSymbol, toSymbol, allPairs) {
+    if (tradablePair.path.length === 1) {
+        return `${fromSymbol} → ${toSymbol}`;
+    }
+    const routeSymbols = buildRouteSymbols(tradablePair, fromSymbol, toSymbol, allPairs);
+    return routeSymbols.length < tradablePair.path.length + 1
+        ? `${fromSymbol} → ${toSymbol} (${tradablePair.path.length} hops)`
+        : routeSymbols.join(' → ');
+}
+function getFixedSpreadForRoute(route, allPairs) {
+    const matchingPair = findMatchingPair(route, allPairs);
+    if (matchingPair && hasSpreadData(matchingPair)) {
+        return matchingPair.spreadData
+            .totalSpreadPercent;
+    }
+    return route.path.length * DEFAULT_SPREAD_FALLBACK;
+}
+function getHopSpreadPercent(hop, allPairs) {
+    const directPair = allPairs.find((pair) => pair.path.length === 1 &&
+        // @ts-ignore - hop structure is known
+        pair.path[0].id === hop.id &&
+        // @ts-ignore - hop structure is known
+        pair.path[0].providerAddr === hop.providerAddr);
+    if (directPair && hasSpreadData(directPair)) {
+        return directPair.spreadData
+            .totalSpreadPercent;
+    }
+    return DEFAULT_SPREAD_FALLBACK;
+}
+function findMatchingPair(route, allPairs) {
+    return allPairs.find((pair) => {
+        if (pair.path.length !== route.path.length)
+            return false;
+        return route.path.every((hop, index) => {
+            const pairHop = pair.path[index];
+            return (hop.id === pairHop.id &&
+                hop.providerAddr === pairHop.providerAddr &&
+                hop.assets[0] === pairHop.assets[0] &&
+                hop.assets[1] === pairHop.assets[1]);
+        });
+    });
+}
+function hasSpreadData(pair) {
+    return ('spreadData' in pair &&
+        pair.spreadData &&
+        typeof pair.spreadData === 'object' &&
+        'totalSpreadPercent' in pair.spreadData);
+}
+function buildRouteSymbols(tradablePair, fromSymbol, toSymbol, allPairs) {
+    var _a, _b;
+    const addressToSymbol = createAddressToSymbolMap(allPairs);
+    // Handle special case where user input might be different from actual symbol
+    // For example, user inputs "USDT" but actual symbol is "USD₮"
+    const actualFromSymbol = findActualSymbolForInput(fromSymbol, tradablePair.assets);
+    const actualToSymbol = findActualSymbolForInput(toSymbol, tradablePair.assets);
+    // Get the addresses from tradablePair.assets using actual symbols
+    const fromAddress = (_a = tradablePair.assets
+        .find((asset) => asset.symbol === actualFromSymbol)) === null || _a === void 0 ? void 0 : _a.address.toLowerCase();
+    const toAddress = (_b = tradablePair.assets
+        .find((asset) => asset.symbol === actualToSymbol)) === null || _b === void 0 ? void 0 : _b.address.toLowerCase();
+    if (!fromAddress || !toAddress) {
+        return [fromSymbol, toSymbol];
+    }
+    // For multi-hop routes, we need to find the common intermediate tokens
+    // First, collect all unique addresses in the path
+    const allAddresses = new Set();
+    tradablePair.path.forEach((hop) => {
+        hop.assets.forEach((addr) => {
+            allAddresses.add(addr.toLowerCase());
+        });
+    });
+    // Remove our from and to addresses to find intermediates
+    allAddresses.delete(fromAddress);
+    allAddresses.delete(toAddress);
+    // Convert intermediate addresses to symbols
+    const intermediateTokens = Array.from(allAddresses)
+        .map((addr) => addressToSymbol.get(addr))
+        .filter((symbol) => symbol !== undefined);
+    // Build the route: from -> intermediates -> to
+    const route = [fromSymbol];
+    // Add intermediate tokens
+    intermediateTokens.forEach((token) => {
+        if (!route.includes(token)) {
+            route.push(token);
+        }
+    });
+    // Add destination
+    route.push(toSymbol);
+    return route;
+}
+/**
+ * Finds the actual symbol in the tradable pair assets for a given input symbol.
+ * Handles special cases like "USDT" mapping to "USD₮".
+ */
+function findActualSymbolForInput(inputSymbol, assets) {
+    // First try exact match
+    const exactMatch = assets.find((asset) => asset.symbol === inputSymbol);
+    if (exactMatch) {
+        return inputSymbol;
+    }
+    // Handle USDT special case
+    if (inputSymbol.toLowerCase() === 'usdt') {
+        // Look for USD₮ or other USDT variants
+        const usdtVariant = assets.find((asset) => {
+            const normalizedSymbol = asset.symbol.replace(/[^\w]/g, '').toLowerCase();
+            return normalizedSymbol === 'usdt' || asset.symbol === 'USD₮';
+        });
+        if (usdtVariant) {
+            return usdtVariant.symbol;
+        }
+    }
+    // Fallback to original input
+    return inputSymbol;
+}
+function createAddressToSymbolMap(allPairs) {
+    const addressToSymbol = new Map();
+    allPairs.forEach((pair) => {
+        pair.assets.forEach((asset) => {
+            addressToSymbol.set(asset.address.toLowerCase(), asset.symbol);
+        });
+    });
+    return addressToSymbol;
+}