@mento-protocol/mento-sdk 3.2.2-beta1 → 3.2.3

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

@@ -1,6 +1,12 @@
-import type { Route, RouteID, RouteWithCost, Pool } from '../core/types';
+import { TradablePairWithSpread } from './constants';
+import { Address } from './interfaces';
+import { TradablePair, TradablePairID } from './mento';
 type TokenSymbol = string;
-type Address = string;
+interface ExchangeDetails {
+    providerAddr: Address;
+    id: string;
+    assets: [Address, Address];
+}
 /**
  * =============================================================================
  * ROUTE GENERATION UTILITIES
@@ -12,12 +18,12 @@ type Address = string;
  *
  * 1. Build connectivity structures from direct trading pairs
  * 2. Generate all possible routes (direct + two-hop)
- * 3. Select optimal routes using cost data or heuristics
+ * 3. Select optimal routes using spread data or heuristics
  *
  * ALGORITHM OVERVIEW:
  * - Creates a graph where tokens are nodes and direct exchanges are edges
  * - Uses graph traversal to find two-hop routes through intermediate tokens
- * - Optimizes route selection based on cost data when available
+ * - Optimizes route selection based on spread costs when available
  * - Falls back to heuristics (prefer direct routes, major stablecoins)
  * =============================================================================
  */
@@ -27,15 +33,15 @@ type Address = string;
  *
  * CONCRETE EXAMPLE:
  * Given these direct trading pairs:
- * - USDm ↔ CELO (direct exchange exists)
- * - CELO ↔ EURm (direct exchange exists)
- * - USDm ↔ BRLm (direct exchange exists)
+ * - cUSD ↔ CELO (direct exchange exists)
+ * - CELO ↔ cEUR (direct exchange exists)
+ * - cUSD ↔ cREAL (direct exchange exists)
  *
  * How route finding works:
- * - Direct route: USDm → EURm? Check token graph: USDm connects to [CELO, BRLm], none is EURm → No direct route
- * - Two-hop route: USDm → ? → EURm?
- *   - USDm connects to CELO, CELO connects to EURm → Found route: USDm → CELO → EURm
- *   - USDm connects to BRLm, BRLm connects to [USDm] → No route via BRLm
+ * - Direct route: cUSD → cEUR? Check token graph: cUSD connects to [CELO, cREAL], none is cEUR → No direct route
+ * - Two-hop route: cUSD → ? → cEUR?
+ *   - cUSD connects to CELO, CELO connects to cEUR → Found route: cUSD → CELO → cEUR
+ *   - cUSD connects to cREAL, cREAL connects to [cUSD] → No route via cREAL
  *
  * The "connectivity" part means we can quickly traverse the network of
  * token connections to find all possible trading paths.
@@ -44,36 +50,36 @@ export interface ConnectivityData {
     /** Maps token address to symbol for efficient lookups
      *
      *    ```
-     *    '0x765D...' → 'USDm'
+     *    '0x765D...' → 'cUSD'
      *    '0x471E...' → 'CELO'
-     *    '0xD876...' → 'EURm'
+     *    '0xD876...' → 'cEUR'
      *    ```
      */
     addrToSymbol: Map<Address, TokenSymbol>;
     /** Adjacency list mapping which tokens connect to which
      * Used for finding two-hop routes by traversing token → neighbor → neighbor.
      *
-     * Example for a USDm => EURm swap: First we find USDm → [CELO, KESm, ...]
-     * Then we find CELO → [USDm, EURm, ...] = found route via USDm → CELO → EURm
+     * Example for a cUSD => cEUR swap: First we find cUSD → [CELO, cKES, ...]
+     * Then we find CELO → [cUSD, cEUR, ...] = found route via cUSD → CELO → cEUR
      *
      *    ```
-     *    'USDm_addr' → Set(['CELO_addr', 'KESm_addr'])  // USDm connects to CELO and KESm
-     *    'CELO_addr' → Set(['USDm_addr', 'EURm_addr'])  // CELO connects to USDm and EURm
-     *    'EURm_addr' → Set(['CELO_addr'])               // EURm connects to CELO
-     *    'KESm_addr' → Set(['USDm_addr'])               // KESm connects to USDm
+     *    'cUSD_addr' → Set(['CELO_addr', 'cKES_addr'])  // cUSD connects to CELO and cKES
+     *    'CELO_addr' → Set(['cUSD_addr', 'cEUR_addr'])  // CELO connects to cUSD and cEUR
+     *    'cEUR_addr' → Set(['CELO_addr'])               // cEUR connects to CELO
+     *    'cKES_addr' → Set(['cUSD_addr'])               // cKES connects to cUSD
      *    ```
      */
     tokenGraph: Map<Address, Set<Address>>;
-    /** Maps sorted token address pairs to their direct route details
+    /** Maps sorted token address pairs to their direct exchange hop details
      *    ```
-     *    'CELO_addr-EURm_addr' → { route details for CELO ↔ EURm }
-     *    'CELO_addr-USDm_addr' → { route details for CELO ↔ USDm }
-     *    'USDm_addr-KESm_addr' → { route details for USDm ↔ KESm }
+     *    'CELO_addr-cEUR_addr' → { exchange details for CELO ↔ cEUR }
+     *    'CELO_addr-cUSD_addr' → { exchange details for CELO ↔ cUSD }
+     *    'cUSD_addr-cKES_addr' → { exchange details for cUSD ↔ cKES }
      *    ```
      */
-    directRouteMap: Map<RouteID, Pool>;
-    /** Original direct routes from mento.getDirectRoutes() for reference */
-    directRoutes: Route[];
+    directPathMap: Map<TradablePairID, ExchangeDetails>;
+    /** Original direct trading pairs from mento.getDirectPairs() for reference */
+    directPairs: TradablePair[];
 }
 /**
  * Builds the connectivity data structures needed for route generation.
@@ -85,23 +91,23 @@ export interface ConnectivityData {
  *
  * ```
  * Input: TradablePairs = [
- *   { id: 'USDm-CELO', assets: [USDm, CELO], path: [exchange1_CELO_USDm] },
- *   { id: 'CELO-EURm', assets: [CELO, EURm], path: [exchange2_CELO_EURm] }
+ *   { 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:
- *   USDm.address → 'USDm'
+ *   cUSD.address → 'cUSD'
  *   CELO.address → 'CELO'
- *   EURm.address → 'EURm'
+ *   cEUR.address → 'cEUR'
  *
  * Step 2 - Build directPathMap (sorted alphabetically for consistency):
- *   'CELO_addr-EURm_addr' → exchange2_CELO_EURm
- *   'CELO_addr-USDm_addr' → exchange1_CELO_USDm
+ *   'CELO_addr-cEUR_addr' → exchange2_CELO_cEUR
+ *   'CELO_addr-cUSD_addr' → exchange1_CELO_cUSD
  *
  * Step 3 - Build bidirectional tokenGraph:
- *   USDm.address → Set([CELO.address])
- *   CELO.address → Set([USDm.address, EURm.address])
- *   EURm.address → Set([CELO.address])
+ *   cUSD.address → Set([CELO.address])
+ *   CELO.address → Set([cUSD.address, cEUR.address])
+ *   cEUR.address → Set([CELO.address])
  * ```
  *
  * **Result**: We can now efficiently answer:
@@ -109,32 +115,32 @@ export interface ConnectivityData {
  * - "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
+ * @param directPairs - 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] }
+ *   { 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 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
+ * // 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
  * ```
  */
-export declare function buildConnectivityStructures(directRoutes: Route[]): ConnectivityData;
+export declare function buildConnectivityStructures(directPairs: TradablePair[]): ConnectivityData;
 /**
  * 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)
+ * 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
@@ -142,28 +148,28 @@ export declare function buildConnectivityStructures(directRoutes: Route[]): Conn
  *
  * **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.
+ * the best one based on spread data or heuristics.
  *
- * **Canonical Route IDs**: All routes use alphabetically sorted symbols
- * (e.g., 'EURm-USDm' not 'USDm-EURm') for consistent identification.
+ * **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 route ID -> array of possible routes for that token pair
+ * @returns Map of pair ID -> array of possible routes for that pair
  *
  * @example
  * ```typescript
- * // Given direct routes: USDm-CELO, CELO-EURm, USDm-USDC
+ * // Given direct pairs: cUSD-CELO, CELO-cEUR, cUSD-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
+ * // '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
  * // ]
  * ```
  */
-export declare function generateAllRoutes(connectivityData: ConnectivityData): Map<RouteID, Route[]>;
+export declare function generateAllRoutes(connectivityData: ConnectivityData): Map<TradablePairID, TradablePair[]>;
 /**
  * Creates a two-hop tradable pair if valid exchange hops exist.
  *
@@ -187,27 +193,31 @@ export declare function generateAllRoutes(connectivityData: ConnectivityData): M
  *
  * @example
  * ```typescript
- * // Create route: USDm -> CELO -> EURm
+ * // Create route: cUSD -> CELO -> cEUR
  * const pair = createTwoHopPair(
- *   '0x765D...', // USDm address
+ *   '0x765D...', // cUSD address
  *   '0x471E...', // CELO address
- *   '0xD876...', // EURm address
+ *   '0xD876...', // cEUR address
  *   addrToSymbol,
  *   directPathMap
  * )
  *
  * // Result:
  * // {
- * //   id: 'EURm-USDm',           // alphabetical order
- * //   assets: [EURm, USDm],     // alphabetical order
+ * //   id: 'cEUR-cUSD',           // alphabetical order
+ * //   assets: [cEUR, cUSD],     // alphabetical order
  * //   path: [                   // actual routing path
- * //     { USDm->CELO exchange },
- * //     { CELO->EURm exchange }
+ * //     { cUSD->CELO exchange },
+ * //     { CELO->cEUR exchange }
  * //   ]
  * // }
  * ```
  */
-export declare function createTwoHopRoute(startAddr: Address, intermediateAddr: Address, endAddr: Address, addrToSymbol: Map<Address, TokenSymbol>, directRouteMap: Map<RouteID, Pool>): Route | null;
+export declare function createTwoHopPair(startToken: Address, intermediateToken: Address, endToken: Address, addrToSymbol: Map<Address, TokenSymbol>, directPathMap: Map<string, {
+    providerAddr: Address;
+    id: string;
+    assets: [Address, Address];
+}>): TradablePair | null;
 /**
  * Selects optimal routes from all candidates based on spread data or heuristics.
  *
@@ -229,38 +239,38 @@ export declare function createTwoHopRoute(startAddr: Address, intermediateAddr:
  *
  * @example
  * ```typescript
- * // Multiple routes for USDm-EURm pair
+ * // Multiple routes for cUSD-cEUR 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
+ *   ['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 USDm->BRLm->EURm route (lowest cost: 0.3%)
+ * // Returns the cUSD->cREAL->cEUR route (lowest spread: 0.3%)
  * ```
  */
-export declare function selectOptimalRoutes(allRoutes: Map<RouteID, Route[]>, returnAllRoutes: boolean, addrToSymbol: Map<Address, TokenSymbol>): (Route | RouteWithCost)[];
+export declare function selectOptimalRoutes(allRoutes: Map<TradablePairID, TradablePair[]>, returnAllRoutes: boolean, addrToSymbol: Map<Address, TokenSymbol>): (TradablePair | TradablePairWithSpread)[];
 /**
- * Selects the best route from candidates using cost data or fallback heuristics.
+ * 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 - Cost-Based Optimization** (Preferred):
- * - Use routes with cost data (actual cost information)
- * - Select route with lowest `totalCostPercent`
+ * **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 cost data available, prefer direct (single-hop) routes
+ * - 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 USDm and EURm typically have better liquidity
+ * - 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
@@ -272,24 +282,23 @@ export declare function selectOptimalRoutes(allRoutes: Map<RouteID, Route[]>, re
  * @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
+ *   { 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% cost)
+ * // Returns the A->D->C route (0.4% spread)
  * ```
  */
-export declare function selectBestRoute(candidates: Route[], addrToSymbol: Map<Address, TokenSymbol>): Route | RouteWithCost;
+export declare function selectBestRoute(candidates: TradablePair[], addrToSymbol: Map<Address, TokenSymbol>): TradablePair | TradablePairWithSpread;
 /**
  * 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 declare function getIntermediateToken(route: Route): Address | undefined;
+export declare function getIntermediateToken(route: TradablePair): Address | undefined;
 /**
- * Type guard to check if a Route has cost data.
+ * Type guard to check if a Route has spread data.
  */
-export declare function hasCostData(pair: Route | RouteWithCost): pair is RouteWithCost;
+export declare function hasSpreadData(pair: TradablePair | TradablePairWithSpread): pair is TradablePairWithSpread;
 export {};
-//# sourceMappingURL=routeUtils.d.ts.map