@mento-protocol/mento-sdk 3.2.3 → 3.2.4

package/dist/esm/services/pools/poolDiscovery.js

@@ -0,0 +1,112 @@
+import { tryGetContractAddress } from '../../core/constants';
+import { PoolType } from '../../core/types';
+import { FPMM_FACTORY_ABI, FPMM_ABI, VIRTUAL_POOL_FACTORY_ABI, VIRTUAL_POOL_ABI, BIPOOL_MANAGER_ABI, } from '../../core/abis';
+import { sortTokenAddresses } from '../../utils/sortUtils';
+import { multicall } from '../../utils/multicall';
+/**
+ * Fetches all FPMM pools from the FPMM Factory
+ */
+export async function fetchFPMMPools(publicClient, chainId) {
+    const fpmmFactoryAddress = tryGetContractAddress(chainId, 'FPMMFactory');
+    if (!fpmmFactoryAddress) {
+        return [];
+    }
+    try {
+        // Get all deployed FPMM pool addresses
+        const poolAddresses = (await publicClient.readContract({
+            address: fpmmFactoryAddress,
+            abi: FPMM_FACTORY_ABI,
+            functionName: 'deployedFPMMAddresses',
+        }));
+        if (poolAddresses.length === 0) {
+            return [];
+        }
+        // Batch all token0/token1 reads into a single multicall
+        const contracts = poolAddresses.flatMap((poolAddress) => [
+            { address: poolAddress, abi: FPMM_ABI, functionName: 'token0' },
+            { address: poolAddress, abi: FPMM_ABI, functionName: 'token1' },
+        ]);
+        const results = await multicall(publicClient, contracts);
+        return poolAddresses.map((poolAddress, i) => {
+            const token0Result = results[i * 2];
+            const token1Result = results[i * 2 + 1];
+            if (token0Result.status === 'failure' || token1Result.status === 'failure') {
+                throw new Error(`Failed to read token addresses for pool ${poolAddress}`);
+            }
+            return {
+                factoryAddr: fpmmFactoryAddress,
+                poolAddr: poolAddress,
+                token0: token0Result.result,
+                token1: token1Result.result,
+                poolType: PoolType.FPMM,
+            };
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch FPMM pools: ${error.message}`);
+    }
+}
+/**
+ * Fetches all active Virtual pools from the VirtualPoolFactory,
+ * then resolves token pairs and exchange IDs from each pool and BiPoolManager.
+ */
+export async function fetchVirtualPools(publicClient, chainId) {
+    const virtualPoolFactoryAddress = tryGetContractAddress(chainId, 'VirtualPoolFactory');
+    const biPoolManagerAddress = tryGetContractAddress(chainId, 'BiPoolManager');
+    if (!virtualPoolFactoryAddress || !biPoolManagerAddress) {
+        return [];
+    }
+    try {
+        // Fetch active pool addresses and all exchanges in parallel
+        const [poolAddresses, exchangesData] = await Promise.all([
+            publicClient.readContract({
+                address: virtualPoolFactoryAddress,
+                abi: VIRTUAL_POOL_FACTORY_ABI,
+                functionName: 'getAllPools',
+            }),
+            publicClient.readContract({
+                address: biPoolManagerAddress,
+                abi: BIPOOL_MANAGER_ABI,
+                functionName: 'getExchanges',
+            }),
+        ]);
+        if (poolAddresses.length === 0) {
+            return [];
+        }
+        // Build a lookup from sorted token pair to exchangeId
+        const tokenPairToExchangeId = new Map();
+        for (const exchange of exchangesData) {
+            if (exchange.assets.length === 2) {
+                const [t0, t1] = sortTokenAddresses(exchange.assets[0], exchange.assets[1]);
+                tokenPairToExchangeId.set(`${t0}:${t1}`, exchange.exchangeId);
+            }
+        }
+        // Batch all tokens() reads into a single multicall
+        const contracts = poolAddresses.map((poolAddress) => ({
+            address: poolAddress,
+            abi: VIRTUAL_POOL_ABI,
+            functionName: 'tokens',
+        }));
+        const results = await multicall(publicClient, contracts);
+        return poolAddresses.map((poolAddress, i) => {
+            const result = results[i];
+            if (result.status === 'failure') {
+                throw new Error(`Failed to read token addresses for virtual pool ${poolAddress}`);
+            }
+            const [token0, token1] = result.result;
+            const [sorted0, sorted1] = sortTokenAddresses(token0, token1);
+            const exchangeId = tokenPairToExchangeId.get(`${sorted0}:${sorted1}`);
+            return {
+                factoryAddr: virtualPoolFactoryAddress,
+                poolAddr: poolAddress,
+                token0: sorted0,
+                token1: sorted1,
+                poolType: PoolType.Virtual,
+                exchangeId,
+            };
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch Virtual pools: ${error.message}`);
+    }
+}

package/dist/esm/services/pools/rebalancePreview.js

@@ -0,0 +1,181 @@
+import { getAddress } from 'viem';
+import { LIQUIDITY_STRATEGY_ABI } from '../../core/abis';
+import { multicall } from '../../utils/multicall';
+// Liquidity strategy incentive rates are stored as 18-decimal percentages.
+const FEE_DENOMINATOR = 10n ** 18n;
+function toBigIntValue(value) {
+    return typeof value === 'bigint' ? value : BigInt(value);
+}
+function toNumberValue(value) {
+    return typeof value === 'number' ? value : Number(value);
+}
+function parseDirection(value) {
+    const normalized = toNumberValue(value);
+    if (normalized === 0)
+        return 'Expand';
+    if (normalized === 1)
+        return 'Contract';
+    throw new Error(`Unsupported liquidity strategy direction: ${normalized}`);
+}
+function parsePoolConfig(raw) {
+    return {
+        isToken0Debt: raw[0],
+        lastRebalance: toNumberValue(raw[1]),
+        rebalanceCooldown: toNumberValue(raw[2]),
+        protocolFeeRecipient: raw[3],
+        liquiditySourceIncentiveExpansion: toBigIntValue(raw[4]),
+        protocolIncentiveExpansion: toBigIntValue(raw[5]),
+        liquiditySourceIncentiveContraction: toBigIntValue(raw[6]),
+        protocolIncentiveContraction: toBigIntValue(raw[7]),
+    };
+}
+function parseContext(raw) {
+    return {
+        pool: raw[0],
+        reserves: {
+            reserveNum: toBigIntValue(raw[1][0]),
+            reserveDen: toBigIntValue(raw[1][1]),
+        },
+        prices: {
+            oracleNum: toBigIntValue(raw[2][0]),
+            oracleDen: toBigIntValue(raw[2][1]),
+            poolPriceAbove: raw[2][2],
+            rebalanceThreshold: toNumberValue(raw[2][3]),
+        },
+        token0: raw[3],
+        token1: raw[4],
+        token0Dec: toBigIntValue(raw[5]),
+        token1Dec: toBigIntValue(raw[6]),
+        isToken0Debt: raw[7],
+        incentives: {
+            liquiditySourceIncentiveExpansion: toBigIntValue(raw[8][0]),
+            protocolIncentiveExpansion: toBigIntValue(raw[8][1]),
+            liquiditySourceIncentiveContraction: toBigIntValue(raw[8][2]),
+            protocolIncentiveContraction: toBigIntValue(raw[8][3]),
+        },
+    };
+}
+function parseAction(raw) {
+    return {
+        dir: parseDirection(raw[0]),
+        amount0Out: toBigIntValue(raw[1]),
+        amount1Out: toBigIntValue(raw[2]),
+        amountOwedToPool: toBigIntValue(raw[3]),
+    };
+}
+function isPreviewEligible(detail) {
+    return (detail.poolType === 'FPMM' &&
+        detail.pricing !== null &&
+        detail.rebalancing.inBand === false &&
+        !!detail.rebalancing.liquidityStrategy);
+}
+function buildPreview(detail, strategyAddress, config, context, action) {
+    const debtToken = context.isToken0Debt ? context.token0 : context.token1;
+    const collateralToken = context.isToken0Debt ? context.token1 : context.token0;
+    const inputToken = action.dir === 'Expand' ? debtToken : collateralToken;
+    const outputToken = action.dir === 'Expand' ? collateralToken : debtToken;
+    const amountTransferredValue = action.amount0Out > 0n ? action.amount0Out : action.amount1Out;
+    const protocolRate = action.dir === 'Expand'
+        ? config.protocolIncentiveExpansion
+        : config.protocolIncentiveContraction;
+    const liquiditySourceRate = action.dir === 'Expand'
+        ? config.liquiditySourceIncentiveExpansion
+        : config.liquiditySourceIncentiveContraction;
+    const protocolIncentiveAmount = (amountTransferredValue * protocolRate) / FEE_DENOMINATOR;
+    const liquiditySourceBase = amountTransferredValue > protocolIncentiveAmount
+        ? amountTransferredValue - protocolIncentiveAmount
+        : 0n;
+    const liquiditySourceIncentiveAmount = (liquiditySourceBase * liquiditySourceRate) / FEE_DENOMINATOR;
+    return {
+        poolAddress: detail.poolAddr,
+        strategyAddress,
+        direction: action.dir,
+        config,
+        context,
+        action,
+        inputToken,
+        outputToken,
+        amountRequired: {
+            token: inputToken,
+            amount: action.amountOwedToPool,
+        },
+        amountTransferred: {
+            token: outputToken,
+            amount: amountTransferredValue,
+        },
+        protocolIncentive: {
+            token: outputToken,
+            amount: protocolIncentiveAmount,
+        },
+        liquiditySourceIncentive: {
+            token: outputToken,
+            amount: liquiditySourceIncentiveAmount,
+        },
+        approvalToken: inputToken,
+        approvalSpender: strategyAddress,
+        approvalAmount: action.amountOwedToPool,
+    };
+}
+export async function fetchPoolRebalancePreview(publicClient, detail) {
+    const [preview] = await fetchPoolRebalancePreviewBatch(publicClient, [detail]);
+    return preview;
+}
+export async function fetchPoolRebalancePreviewBatch(publicClient, details) {
+    const previews = details.map(() => null);
+    const eligibleTargets = details.flatMap((detail, index) => {
+        if (!isPreviewEligible(detail))
+            return [];
+        const strategyAddress = detail.rebalancing.liquidityStrategy;
+        if (!strategyAddress)
+            return [];
+        try {
+            return [
+                {
+                    index,
+                    detail,
+                    strategyAddress: getAddress(strategyAddress),
+                },
+            ];
+        }
+        catch {
+            return [];
+        }
+    });
+    if (eligibleTargets.length === 0) {
+        return previews;
+    }
+    const contracts = eligibleTargets.flatMap(({ detail, strategyAddress }) => [
+        {
+            address: strategyAddress,
+            abi: LIQUIDITY_STRATEGY_ABI,
+            functionName: 'poolConfigs',
+            args: [detail.poolAddr],
+        },
+        {
+            address: strategyAddress,
+            abi: LIQUIDITY_STRATEGY_ABI,
+            functionName: 'determineAction',
+            args: [detail.poolAddr],
+        },
+    ]);
+    const results = await multicall(publicClient, contracts);
+    eligibleTargets.forEach((target, targetIndex) => {
+        const configResult = results[targetIndex * 2];
+        const determineActionResult = results[targetIndex * 2 + 1];
+        if (!configResult || !determineActionResult)
+            return;
+        if (configResult.status === 'failure' || determineActionResult.status === 'failure')
+            return;
+        try {
+            const config = parsePoolConfig(configResult.result);
+            const [rawContext, rawAction] = determineActionResult.result;
+            const context = parseContext(rawContext);
+            const action = parseAction(rawAction);
+            previews[target.index] = buildPreview(target.detail, target.strategyAddress, config, context, action);
+        }
+        catch {
+            previews[target.index] = null;
+        }
+    });
+    return previews;
+}

package/dist/esm/services/quotes/QuoteService.js

@@ -0,0 +1,85 @@
+import { BaseError, ContractFunctionRevertedError } from 'viem';
+import { ROUTER_ABI } from '../../core/abis';
+import { getContractAddress } from '../../core/constants';
+import { FXMarketClosedError } from '../../core/errors';
+import { encodeRoutePath } from '../../utils/pathEncoder';
+import { validateAddress } from '../../utils/validation';
+/**
+ * Service for getting swap quotes from the Mento protocol.
+ * Calculates expected output amounts for trades without executing them.
+ */
+export class QuoteService {
+    constructor(publicClient, chainId, routeService) {
+        this.publicClient = publicClient;
+        this.chainId = chainId;
+        this.routeService = routeService;
+    }
+    /**
+     * Calculates the expected output amount for a swap between two tokens.
+     *
+     * @param tokenIn - The address of the input token (e.g., '0x765DE816845861e75A25fCA122bb6898B8B1282a')
+     * @param tokenOut - The address of the output token (e.g., '0x471EcE3750Da237f93B8E339c536989b8978a438')
+     * @param amountIn - The amount of input tokens (in wei/smallest unit)
+     * @param route - Optional pre-fetched route. If not provided, the optimal route will be found automatically.
+     * @returns The expected output amount (in wei/smallest unit)
+     * @throws {RouteNotFoundError} If no route exists between the token pair
+     * @throws {Error} If the Router contract call fails
+     *
+     * @example
+     * ```typescript
+     * // Calculate output for 100 USDm
+     * const amountIn = BigInt(100) * BigInt(10 ** 18) // 100 USDm in wei
+     * const expectedOut = await quoteService.getAmountOut(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a', // USDm
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438', // CELO
+     *   amountIn
+     * )
+     * console.log(`Expected CELO output: ${expectedOut}`)
+     *
+     * // Or provide a pre-fetched route for better performance
+     * const route = await routeService.findRoute(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a',
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438'
+     * )
+     * const expectedOut2 = await quoteService.getAmountOut(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a',
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438',
+     *   amountIn,
+     *   route
+     * )
+     * ```
+     */
+    async getAmountOut(tokenIn, tokenOut, amountIn, route) {
+        // Validate address inputs
+        validateAddress(tokenIn, 'tokenIn');
+        validateAddress(tokenOut, 'tokenOut');
+        // If the consumer does not provide a route then we find the best route.
+        if (!route) {
+            route = await this.routeService.findRoute(tokenIn, tokenOut);
+        }
+        return getAmountOutForRoute(this.publicClient, this.chainId, tokenIn, tokenOut, amountIn, route);
+    }
+}
+export async function getAmountOutForRoute(publicClient, chainId, tokenIn, tokenOut, amountIn, route) {
+    const routerRoutes = encodeRoutePath(route.path, tokenIn, tokenOut);
+    const routerAddress = getContractAddress(chainId, 'Router');
+    try {
+        const amounts = (await publicClient.readContract({
+            address: routerAddress,
+            abi: ROUTER_ABI,
+            functionName: 'getAmountsOut',
+            args: [amountIn, routerRoutes],
+        }));
+        return amounts[amounts.length - 1];
+    }
+    catch (error) {
+        if (error instanceof BaseError) {
+            const revertError = error.walk((candidate) => candidate instanceof ContractFunctionRevertedError);
+            if (revertError instanceof ContractFunctionRevertedError &&
+                revertError.data?.errorName === 'FXMarketClosed') {
+                throw new FXMarketClosedError();
+            }
+        }
+        throw error;
+    }
+}

package/dist/esm/services/quotes/index.js

@@ -0,0 +1 @@
+export * from './QuoteService';

package/dist/esm/services/routes/RouteService.js

@@ -0,0 +1,268 @@
+import { ERC20_ABI } from '../../core/abis';
+import { RouteNotFoundError } from '../../core/errors';
+import { buildConnectivityStructures, generateAllRoutes, selectOptimalRoutes } from '../../utils/routeUtils';
+import { canonicalSymbolKey } from '../../utils/sortUtils';
+import { multicall } from '../../utils/multicall';
+/**
+ * Service for discovering and managing trading routes in the Mento protocol.
+ * Handles route discovery for both direct (single-hop) and multi-hop trading paths.
+ *
+ * Routes are identified by their token pair and include the path of pools
+ * needed to execute the trade. Multi-hop routes (up to 2 hops) are automatically
+ * discovered when no direct route exists between two tokens.
+ */
+export class RouteService {
+    constructor(publicClient, chainId, poolService) {
+        this.publicClient = publicClient;
+        this.chainId = chainId;
+        this.poolService = poolService;
+        this.symbolCache = new Map();
+        this.routeCache = new Map();
+        this.routeLookupCache = new Map();
+        this.routePromises = new Map();
+    }
+    /**
+     * Generates all direct (single-hop) routes from available pools
+     * Routes are deduplicated and assets are sorted alphabetically by symbol
+     *
+     * @returns Array of direct routes with single-hop paths
+     * @throws {Error} If RPC calls fail
+     *
+     * @example
+     * ```typescript
+     * const directRoutes = await routeService.getDirectRoutes()
+     * console.log(`Found ${directRoutes.length} direct routes`)
+     * ```
+     */
+    async getDirectRoutes() {
+        const pools = await this.poolService.getPools();
+        if (pools.length === 0) {
+            return [];
+        }
+        // Fetch all unique token addresses
+        const uniqueTokens = new Set();
+        pools.forEach((pool) => {
+            uniqueTokens.add(pool.token0);
+            uniqueTokens.add(pool.token1);
+        });
+        // Fetch symbols for all tokens in parallel. Used for the route ids
+        const tokenAddresses = Array.from(uniqueTokens);
+        await this.hydrateTokenSymbols(tokenAddresses);
+        const routes = [];
+        // Loop all pools
+        for (const pool of pools) {
+            const symbol0 = this.symbolCache.get(pool.token0);
+            const symbol1 = this.symbolCache.get(pool.token1);
+            if (!symbol0 || !symbol1) {
+                throw new Error(`Symbol not found for token ${pool.token0} or ${pool.token1}`);
+            }
+            // Create canonical route ID (alphabetically sorted symbols)
+            const routeId = canonicalSymbolKey(symbol0, symbol1);
+            // Sort tokens to match the canonical route ID order (alphabetical by symbol)
+            const sortedTokens = symbol0 < symbol1
+                ? [
+                    { address: pool.token0, symbol: symbol0 },
+                    { address: pool.token1, symbol: symbol1 },
+                ]
+                : [
+                    { address: pool.token1, symbol: symbol1 },
+                    { address: pool.token0, symbol: symbol0 },
+                ];
+            routes.push({
+                id: routeId,
+                tokens: sortedTokens,
+                path: [pool],
+            });
+        }
+        return routes;
+    }
+    /**
+     * Discovers all tradable routes including multi-hop routes (up to 2 hops)
+     * Uses cached data by default for instant results, or generates fresh from blockchain
+     *
+     * @param options - Configuration options
+     * @param options.cached - Whether to use pre-generated cached routes (default: true)
+     * @param options.returnAllRoutes - Whether to return all possible routes or just the optimal one per pair (default: false)
+     * @returns Array of all tradable routes (direct + multi-hop routes)
+     *
+     * @example
+     * ```typescript
+     * // Fast: use pre-generated cache
+     * const cachedRoutes = await routeService.getRoutes({ cached: true })
+     *
+     * // Slower but fresh: generate from blockchain
+     * const freshRoutes = await routeService.getRoutes({ cached: false })
+     *
+     * // Get all route variants (useful for cache generation)
+     * const allRoutes = await routeService.getRoutes({ cached: false, returnAllRoutes: true })
+     * ```
+     */
+    async getRoutes(options) {
+        const cached = options?.cached ?? true;
+        const returnAllRoutes = options?.returnAllRoutes ?? false;
+        const cacheKey = this.getCacheKey(cached, returnAllRoutes);
+        const cachedRoutes = this.routeCache.get(cacheKey);
+        if (cachedRoutes) {
+            return cachedRoutes;
+        }
+        const inFlight = this.routePromises.get(cacheKey);
+        if (inFlight) {
+            return inFlight;
+        }
+        const promise = this.loadRoutes(cached, returnAllRoutes);
+        this.routePromises.set(cacheKey, promise);
+        try {
+            const routes = await promise;
+            this.routeCache.set(cacheKey, routes);
+            if (!returnAllRoutes) {
+                this.routeLookupCache.set(cacheKey, this.buildLookup(routes));
+            }
+            return routes;
+        }
+        finally {
+            this.routePromises.delete(cacheKey);
+        }
+    }
+    async warm(options) {
+        return this.getRoutes(options);
+    }
+    /**
+     * Looks up the tradable route between two tokens (direct or multi-hop)
+     *
+     * @param tokenIn - Input token address (direction matters for routing)
+     * @param tokenOut - Output token address (direction matters for routing)
+     * @param options - Optional configuration (e.g., cached)
+     * @returns The optimal tradable route connecting the two tokens
+     * @throws {RouteNotFoundError} If no route exists between the token pair
+     *
+     * @example
+     * ```typescript
+     * const USDm = '0x765DE816845861e75A25fCA122bb6898B8B1282a'
+     * const BRLm = '0xE4D5...'
+     * const route = await routeService.findRoute(USDm, BRLm)
+     *
+     * if (route.path.length === 1) {
+     *   console.log('Direct route available')
+     * } else {
+     *   console.log('Two-hop route:', route.path)
+     * }
+     * ```
+     */
+    async findRoute(tokenIn, tokenOut, options) {
+        const cached = options?.cached ?? true;
+        const cacheKey = this.getCacheKey(cached, false);
+        const routes = await this.getRoutes({ cached, returnAllRoutes: false });
+        const lookup = this.routeLookupCache.get(cacheKey) ?? this.buildLookup(routes);
+        this.routeLookupCache.set(cacheKey, lookup);
+        const matchingRoute = lookup.get(makeTokenPairKey(tokenIn, tokenOut));
+        if (!matchingRoute) {
+            throw new RouteNotFoundError(tokenIn, tokenOut);
+        }
+        return matchingRoute;
+    }
+    /**
+     * Generate fresh tradable routes from blockchain data
+     * @param returnAllRoutes - Whether to return all routes or just optimal ones per pair
+     * @private
+     */
+    async generateFreshRoutes(returnAllRoutes = false) {
+        // Get direct routes
+        const directRoutes = await this.getDirectRoutes();
+        if (directRoutes.length === 0) {
+            return [];
+        }
+        // Build connectivity structures for route finding
+        const connectivity = buildConnectivityStructures(directRoutes);
+        // Generate all possible routes (direct + 2-hop)
+        const allRoutes = generateAllRoutes(connectivity);
+        // Select routes based on returnAllRoutes flag
+        const selectedRoutes = selectOptimalRoutes(allRoutes, returnAllRoutes, connectivity.addrToSymbol);
+        return selectedRoutes;
+    }
+    /**
+     * Load cached tradable routes for current chain
+     * @private
+     */
+    async loadCachedRoutes() {
+        const { getCachedRoutes } = await import('../../utils/routes');
+        const cachedRoutes = await getCachedRoutes(this.chainId);
+        return cachedRoutes || [];
+    }
+    async loadRoutes(cached, returnAllRoutes) {
+        if (cached) {
+            try {
+                const cachedRoutes = await this.loadCachedRoutes();
+                if (cachedRoutes.length > 0) {
+                    return returnAllRoutes ? cachedRoutes : cachedRoutes;
+                }
+            }
+            catch {
+                // Cache miss or corrupt - silently fall through to fresh generation
+            }
+        }
+        return this.generateFreshRoutes(returnAllRoutes);
+    }
+    getCacheKey(cached, returnAllRoutes) {
+        return `${cached ? 'cached' : 'fresh'}:${returnAllRoutes ? 'all' : 'best'}`;
+    }
+    buildLookup(routes) {
+        const lookup = new Map();
+        for (const route of routes) {
+            lookup.set(makeTokenPairKey(route.tokens[0].address, route.tokens[1].address), route);
+        }
+        return lookup;
+    }
+    async hydrateTokenSymbols(addresses) {
+        const missingAddresses = addresses.filter((address) => !this.symbolCache.has(address));
+        if (missingAddresses.length === 0) {
+            return;
+        }
+        const results = await multicall(this.publicClient, missingAddresses.map((address) => ({
+            address: address,
+            abi: ERC20_ABI,
+            functionName: 'symbol',
+            args: [],
+        })));
+        for (const [index, address] of missingAddresses.entries()) {
+            const result = results[index];
+            if (!result || result.status === 'failure') {
+                this.symbolCache.set(address, address);
+                continue;
+            }
+            this.symbolCache.set(address, result.result);
+        }
+    }
+    /**
+     * Helper: Fetch token symbol from on-chain
+     * Results are cached to avoid redundant RPC calls
+     * Falls back to address if symbol fetch fails
+     *
+     * @private
+     */
+    async fetchTokenSymbol(address) {
+        // Return cached symbol if available
+        if (this.symbolCache.has(address)) {
+            return this.symbolCache.get(address);
+        }
+        try {
+            const symbol = (await this.publicClient.readContract({
+                address: address,
+                abi: ERC20_ABI,
+                functionName: 'symbol',
+                args: [],
+            }));
+            // Cache the symbol
+            this.symbolCache.set(address, symbol);
+            return symbol;
+        }
+        catch {
+            // Fallback to address if symbol fetch fails
+            this.symbolCache.set(address, address);
+            return address;
+        }
+    }
+}
+function makeTokenPairKey(tokenA, tokenB) {
+    const [first, second] = [tokenA.toLowerCase(), tokenB.toLowerCase()].sort();
+    return `${first}:${second}`;
+}

package/dist/esm/services/routes/index.js

@@ -0,0 +1 @@
+export * from './RouteService';