@mento-protocol/mento-sdk 3.2.7 → 3.2.8

package/dist/esm/utils/routeUtils.js

@@ -0,0 +1,361 @@
+import { canonicalSymbolKey } from './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: 'USDm-CELO', assets: [USDm, CELO], path: [exchange1_CELO_USDm] },
+ *   { id: 'CELO-EURm', assets: [CELO, EURm], path: [exchange2_CELO_EURm] }
+ * ]
+ *
+ * Step 1 - Build addrToSymbol map:
+ *   USDm.address → 'USDm'
+ *   CELO.address → 'CELO'
+ *   EURm.address → 'EURm'
+ *
+ * Step 2 - Build directPathMap (sorted alphabetically for consistency):
+ *   'CELO_addr-EURm_addr' → exchange2_CELO_EURm
+ *   'CELO_addr-USDm_addr' → exchange1_CELO_USDm
+ *
+ * Step 3 - Build bidirectional tokenGraph:
+ *   USDm.address → Set([CELO.address])
+ *   CELO.address → Set([USDm.address, EURm.address])
+ *   EURm.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: '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 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
+ * ```
+ */
+export 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 = 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., 'EURm-USDm' not 'USDm-EURm') 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: USDm-CELO, CELO-EURm, USDm-USDC
+ * const allRoutes = generateAllRoutes(connectivityData)
+ *
+ * // Results might include:
+ * // '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
+ * // ]
+ * ```
+ */
+export 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., 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 = 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 [USDm, EURm, BRLm]
+            for (const end of secondHopNeighbors) {
+                // Skip circular routes like USDm → CELO → USDm (pointless)
+                if (end === start)
+                    continue;
+                // At this point we have a potential route: start → intermediate → end
+                // Example: USDm → CELO → EURm
+                // 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: USDm -> CELO -> EURm
+ * const pair = createTwoHopPair(
+ *   '0x765D...', // USDm address
+ *   '0x471E...', // CELO address
+ *   '0xD876...', // EURm address
+ *   addrToSymbol,
+ *   directPathMap
+ * )
+ *
+ * // Result:
+ * // {
+ * //   id: 'EURm-USDm',           // alphabetical order
+ * //   assets: [EURm, USDm],     // alphabetical order
+ * //   path: [                   // actual routing path
+ * //     { USDm->CELO exchange },
+ * //     { CELO->EURm exchange }
+ * //   ]
+ * // }
+ * ```
+ */
+export 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 = canonicalSymbolKey(startSymbol, intermediateSymbol);
+    const hop2Key = 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 = 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 USDm-EURm pair
+ * const candidates = new Map([
+ *   ['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 USDm->BRLm->EURm route (lowest cost: 0.3%)
+ * ```
+ */
+export 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 USDm and EURm typically have better liquidity
+ *
+ * **Tier 4 - First Available** (Last Resort):
+ * - If no other heuristics apply, use the first route found
+ *
+ * @param candidates - Array of possible routes for the same token pair
+ * @param assetMap - Asset map for token symbol lookups
+ * @returns The optimal route selected using the tier system
+ *
+ * @example
+ * ```typescript
+ * const candidates = [
+ *   { path: [A->B->C], costData: { totalCostPercent: 0.8 } },
+ *   { path: [A->D->C], costData: { totalCostPercent: 0.4 } }, // Winner: lowest cost
+ *   { path: [A->C] }, // direct route, no cost data
+ * ]
+ *
+ * const best = selectBestRoute(candidates, assetMap)
+ * // Returns the A->D->C route (0.4% cost)
+ * ```
+ */
+export 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 = ['USDm', 'EURm', '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).
+ */
+export 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.
+ */
+export function hasCostData(pair) {
+    return 'costData' in pair && pair.costData !== undefined;
+}

package/dist/esm/utils/routes.js

@@ -0,0 +1,2 @@
+// Re-export from consolidated cache
+export { getCachedRoutes, cachedRoutes } from '../cache/routes';

package/dist/esm/utils/sortUtils.js

@@ -0,0 +1,33 @@
+/**
+ * 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 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.
+ */
+export 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.
+ */
+export function canonicalSymbolKey(symbolA, symbolB, separator = '-') {
+    return symbolA < symbolB
+        ? `${symbolA}${separator}${symbolB}`
+        : `${symbolB}${separator}${symbolA}`;
+}

package/dist/esm/utils/tokens.js

@@ -0,0 +1,2 @@
+// Re-export from consolidated cache
+export { TokenSymbol, cachedTokens, getCachedTokens, getCachedTokensSync, getTokenAddress, findTokenBySymbol, TOKEN_ADDRESSES_BY_CHAIN, } from '../cache/tokens';

package/dist/esm/utils/tradingLimits.js

@@ -0,0 +1,163 @@
+import { pad, hexToBigInt, numberToHex } from 'viem';
+/** V2 trading limits use 15 decimals internally */
+const V2_INTERNAL_DECIMALS = 15;
+/** V2 L0 window is fixed at 5 minutes */
+const V2_L0_TIMESTEP = 5 * 60; // 300 seconds
+/** V2 L1 window is fixed at 1 day */
+const V2_L1_TIMESTEP = 24 * 60 * 60; // 86400 seconds
+/** Far future timestamp for global limits (year 2030) */
+const TIMESTAMP_FAR_FUTURE = 1893456000;
+/**
+ * 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 function computeLimitId(exchangeId, token) {
+    // Pad token address to 32 bytes (left-padded with zeros)
+    const tokenBytes32 = pad(token, { size: 32 });
+    // Convert both to BigInt for XOR operation
+    const exchangeIdBigInt = hexToBigInt(exchangeId);
+    const tokenBigInt = hexToBigInt(tokenBytes32);
+    // XOR operation
+    const limitIdBigInt = exchangeIdBigInt ^ tokenBigInt;
+    // Convert back to hex with proper padding
+    return pad(numberToHex(limitIdBigInt), { size: 32 });
+}
+/**
+ * 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 function calculateTradingLimitsV1(config, state, asset, tokenDecimals) {
+    const nowEpoch = Math.floor(Date.now() / 1000);
+    const limits = [];
+    // Check if L0 is enabled (bit 0 of flags)
+    const isL0Enabled = (config.flags & 0x01) !== 0;
+    // Check if L1 is enabled (bit 1 of flags)
+    const isL1Enabled = (config.flags & 0x02) !== 0;
+    // Check if LG is enabled (bit 2 of flags)
+    const isLGEnabled = (config.flags & 0x04) !== 0;
+    // Reset netflows if time windows have passed
+    const isL0Outdated = isL0Enabled && nowEpoch > state.lastUpdated0 + config.timestep0;
+    const isL1Outdated = isL1Enabled && nowEpoch > state.lastUpdated1 + config.timestep1;
+    const effectiveNetflow0 = isL0Outdated ? 0n : state.netflow0;
+    const effectiveNetflow1 = isL1Outdated ? 0n : state.netflow1;
+    const effectiveLastUpdated0 = isL0Outdated ? nowEpoch : state.lastUpdated0;
+    const effectiveLastUpdated1 = isL1Outdated ? nowEpoch : state.lastUpdated1;
+    // Add L0 limit if configured
+    if (isL0Enabled && config.limit0 > 0n) {
+        limits.push({
+            asset,
+            maxIn: config.limit0 - effectiveNetflow0,
+            maxOut: config.limit0 + effectiveNetflow0,
+            until: effectiveLastUpdated0 + config.timestep0,
+            decimals: tokenDecimals,
+        });
+    }
+    // Add L1 limit if configured
+    if (isL1Enabled && config.limit1 > 0n) {
+        limits.push({
+            asset,
+            maxIn: config.limit1 - effectiveNetflow1,
+            maxOut: config.limit1 + effectiveNetflow1,
+            until: effectiveLastUpdated1 + config.timestep1,
+            decimals: tokenDecimals,
+        });
+    }
+    // Add LG (global) limit if configured
+    if (isLGEnabled && config.limitGlobal > 0n) {
+        limits.push({
+            asset,
+            maxIn: config.limitGlobal - state.netflowGlobal,
+            maxOut: config.limitGlobal + state.netflowGlobal,
+            until: TIMESTAMP_FAR_FUTURE,
+            decimals: tokenDecimals,
+        });
+    }
+    // Apply cascading restrictions: limits with larger timeframes restrict smaller ones
+    // e.g., if maxIn is 0 in LG, it should also be 0 in L1 and L0
+    for (let i = limits.length - 1; i > 0; i--) {
+        if (limits[i - 1].maxIn > limits[i].maxIn) {
+            limits[i - 1] = { ...limits[i - 1], maxIn: limits[i].maxIn };
+        }
+        if (limits[i - 1].maxOut > limits[i].maxOut) {
+            limits[i - 1] = { ...limits[i - 1], maxOut: limits[i].maxOut };
+        }
+    }
+    return limits;
+}
+/**
+ * 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 function calculateTradingLimitsV2(config, state, asset) {
+    const nowEpoch = Math.floor(Date.now() / 1000);
+    const limits = [];
+    // Check if L0 is configured (limit0 > 0)
+    const isL0Enabled = config.limit0 > 0n;
+    // Check if L1 is configured (limit1 > 0)
+    const isL1Enabled = config.limit1 > 0n;
+    // Reset netflows if time windows have passed
+    const isL0Outdated = isL0Enabled && nowEpoch > state.lastUpdated0 + V2_L0_TIMESTEP;
+    const isL1Outdated = isL1Enabled && nowEpoch > state.lastUpdated1 + V2_L1_TIMESTEP;
+    const effectiveNetflow0 = isL0Outdated ? 0n : state.netflow0;
+    const effectiveNetflow1 = isL1Outdated ? 0n : state.netflow1;
+    const effectiveLastUpdated0 = isL0Outdated ? nowEpoch : state.lastUpdated0;
+    const effectiveLastUpdated1 = isL1Outdated ? nowEpoch : state.lastUpdated1;
+    // Add L0 limit if configured
+    if (isL0Enabled) {
+        limits.push({
+            asset,
+            maxIn: config.limit0 - effectiveNetflow0,
+            maxOut: config.limit0 + effectiveNetflow0,
+            until: effectiveLastUpdated0 + V2_L0_TIMESTEP,
+            decimals: V2_INTERNAL_DECIMALS, // V2 returns 15 decimal values
+        });
+    }
+    // Add L1 limit if configured
+    if (isL1Enabled) {
+        limits.push({
+            asset,
+            maxIn: config.limit1 - effectiveNetflow1,
+            maxOut: config.limit1 + effectiveNetflow1,
+            until: effectiveLastUpdated1 + V2_L1_TIMESTEP,
+            decimals: V2_INTERNAL_DECIMALS, // V2 returns 15 decimal values
+        });
+    }
+    // Apply cascading restrictions
+    for (let i = limits.length - 1; i > 0; i--) {
+        if (limits[i - 1].maxIn > limits[i].maxIn) {
+            limits[i - 1] = { ...limits[i - 1], maxIn: limits[i].maxIn };
+        }
+        if (limits[i - 1].maxOut > limits[i].maxOut) {
+            limits[i - 1] = { ...limits[i - 1], maxOut: limits[i].maxOut };
+        }
+    }
+    return limits;
+}
+/**
+ * Check if any trading limits are configured (flags > 0 for V1, or limit0/limit1 > 0 for V2)
+ */
+export function hasConfiguredLimitsV1(config) {
+    return config.flags > 0;
+}
+/**
+ * Check if any trading limits are configured for V2
+ */
+export function hasConfiguredLimitsV2(config) {
+    return config.limit0 > 0n || config.limit1 > 0n;
+}

package/dist/esm/utils/validation.js

@@ -0,0 +1,30 @@
+import { isAddress } from 'viem';
+/**
+ * Validates an Ethereum address format using viem's isAddress utility
+ *
+ * @param address - The address string to validate
+ * @param paramName - Optional parameter name for better error messages
+ * @returns True if valid (type guard for `0x${string}`)
+ * @throws Error if address is invalid
+ *
+ * @example
+ * ```typescript
+ * validateAddress('0x765DE816845861e75A25fCA122bb6898B8B1282a')
+ * // Returns true
+ *
+ * validateAddress('invalid', 'tokenIn')
+ * // Throws: "Invalid address for tokenIn: invalid"
+ * ```
+ */
+export function validateAddress(address, paramName) {
+    if (typeof address !== 'string') {
+        const param = paramName ? ` for ${paramName}` : '';
+        throw new Error(`Address${param} must be a string, got ${typeof address}`);
+    }
+    // Use viem's isAddress with strict: false to allow both checksummed and non-checksummed addresses
+    if (!isAddress(address, { strict: false })) {
+        const param = paramName ? ` for ${paramName}` : '';
+        throw new Error(`Invalid address${param}: ${address}. Expected 0x followed by 40 hex characters`);
+    }
+    return true;
+}