@mento-protocol/mento-sdk 3.2.3 → 3.2.5

package/dist/services/routes/RouteService.js

@@ -0,0 +1,306 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteService = void 0;
+const abis_1 = require("../../core/abis");
+const errors_1 = require("../../core/errors");
+const routeUtils_1 = require("../../utils/routeUtils");
+const sortUtils_1 = require("../../utils/sortUtils");
+const multicall_1 = require("../../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.
+ */
+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 = (0, sortUtils_1.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 errors_1.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 = (0, routeUtils_1.buildConnectivityStructures)(directRoutes);
+        // Generate all possible routes (direct + 2-hop)
+        const allRoutes = (0, routeUtils_1.generateAllRoutes)(connectivity);
+        // Select routes based on returnAllRoutes flag
+        const selectedRoutes = (0, routeUtils_1.selectOptimalRoutes)(allRoutes, returnAllRoutes, connectivity.addrToSymbol);
+        return selectedRoutes;
+    }
+    /**
+     * Load cached tradable routes for current chain
+     * @private
+     */
+    async loadCachedRoutes() {
+        const { getCachedRoutes } = await Promise.resolve().then(() => __importStar(require('../../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 (0, multicall_1.multicall)(this.publicClient, missingAddresses.map((address) => ({
+            address: address,
+            abi: abis_1.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: abis_1.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;
+        }
+    }
+}
+exports.RouteService = RouteService;
+function makeTokenPairKey(tokenA, tokenB) {
+    const [first, second] = [tokenA.toLowerCase(), tokenB.toLowerCase()].sort();
+    return `${first}:${second}`;
+}
+//# sourceMappingURL=RouteService.js.map

package/dist/services/routes/index.d.ts

@@ -0,0 +1,2 @@
+export * from './RouteService';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/routes/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./RouteService"), exports);
+//# sourceMappingURL=index.js.map

package/dist/services/swap/SwapService.d.ts

@@ -0,0 +1,198 @@
+import { PublicClient } from 'viem';
+import { RouteService } from '../routes';
+import { QuoteService } from '../quotes';
+import { Route, CallParams } from '../../core/types';
+import { RouterRoute } from '../../utils/pathEncoder';
+/**
+ * Options for configuring a swap transaction
+ */
+export interface SwapOptions {
+    /**
+     * Maximum acceptable slippage as a percentage (e.g., 0.5 for 0.5%)
+     */
+    slippageTolerance: number;
+    /**
+     * Unix timestamp after which the transaction will revert.
+     * Use `deadlineFromMinutes()` for convenience.
+     */
+    deadline: bigint;
+}
+/**
+ * Detailed swap parameters including decoded values for transparency
+ */
+export interface SwapDetails {
+    /**
+     * Transaction parameters ready to send
+     */
+    params: CallParams;
+    /**
+     * The route being used for the swap
+     */
+    route: Route;
+    /**
+     * Encoded route for the Router contract
+     */
+    routerRoutes: RouterRoute[];
+    /**
+     * Input amount in wei
+     */
+    amountIn: bigint;
+    /**
+     * Minimum output amount after slippage
+     */
+    amountOutMin: bigint;
+    /**
+     * Expected output amount (before slippage)
+     */
+    expectedAmountOut: bigint;
+    /**
+     * Transaction deadline
+     */
+    deadline: bigint;
+}
+/**
+ * Combined swap transaction with optional approval
+ */
+export interface SwapTransaction {
+    /**
+     * Approval transaction params - null if approval not needed
+     */
+    approval: CallParams | null;
+    /**
+     * Swap details including transaction params
+     */
+    swap: SwapDetails;
+}
+export interface PrepareSwapInput {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: bigint;
+    slippageTolerance: number;
+    recipient?: string;
+    owner?: string;
+    deadline?: bigint;
+    route?: Route;
+}
+export interface PreparedSwap {
+    route: Route;
+    routerRoutes: RouterRoute[];
+    expectedAmountOut: bigint;
+    amountOutMin: bigint;
+    approval?: CallParams | null;
+    params?: CallParams;
+}
+/**
+ * Service for building token swap transactions on the Mento protocol.
+ * Returns transaction parameters that can be executed by any wallet.
+ */
+export declare class SwapService {
+    private publicClient;
+    private chainId;
+    private routeService;
+    private quoteService;
+    constructor(publicClient: PublicClient, chainId: number, routeService: RouteService, quoteService: QuoteService);
+    /**
+     * Builds a complete swap transaction including approval if needed.
+     * This is the recommended method for most use cases.
+     *
+     * @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 recipient - The address to receive the output tokens
+     * @param owner - The address that owns the input tokens (needed to check allowance)
+     * @param options - Swap configuration options (slippage, deadline)
+     * @param route - Optional pre-fetched route for better performance
+     * @returns Combined transaction with approval (if needed) and swap params
+     * @throws {Error} 'amountIn must be greater than zero' - if amountIn <= 0
+     * @throws {Error} 'Slippage tolerance cannot be negative' - if slippageTolerance < 0
+     * @throws {Error} 'Slippage tolerance exceeds maximum' - if slippageTolerance > 20%
+     * @throws {Error} 'Deadline must be in the future' - if deadline is not a future timestamp
+     * @throws {Error} Invalid address - if any address parameter is not a valid Ethereum address
+     * @throws {RouteNotFoundError} If no trading route exists between the token pair
+     *
+     * @example
+     * ```typescript
+     * const { approval, swap } = await mento.swap.buildSwapTransaction(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a', // USDm
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438', // CELO
+     *   parseUnits('100', 18),
+     *   '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // recipient
+     *   '0x123...', // owner
+     *   { slippageTolerance: 0.5, deadline: deadlineFromMinutes(5) }
+     * )
+     *
+     * // Execute approval if needed
+     * if (approval) {
+     *   await walletClient.sendTransaction(approval)
+     * }
+     *
+     * // Execute swap
+     * await walletClient.sendTransaction(swap.params)
+     * ```
+     */
+    buildSwapTransaction(tokenIn: string, tokenOut: string, amountIn: bigint, recipient: string, owner: string, options: SwapOptions, route?: Route): Promise<SwapTransaction>;
+    /**
+     * Builds swap transaction parameters without executing the transaction.
+     * Does NOT check or handle token approval - use buildSwapTransaction for that.
+     *
+     * @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 recipient - The address to receive the output tokens
+     * @param options - Swap configuration options (slippage, deadline)
+     * @param route - Optional pre-fetched route for better performance
+     * @returns Detailed swap parameters including transaction data
+     * @throws {Error} 'amountIn must be greater than zero' - if amountIn <= 0
+     * @throws {Error} 'Slippage tolerance cannot be negative' - if slippageTolerance < 0
+     * @throws {Error} 'Slippage tolerance exceeds maximum' - if slippageTolerance > 20%
+     * @throws {Error} 'Deadline must be in the future' - if deadline is not a future timestamp
+     * @throws {Error} Invalid address - if any address parameter is not a valid Ethereum address
+     * @throws {RouteNotFoundError} If no trading route exists between the token pair
+     *
+     * @example
+     * ```typescript
+     * const swapDetails = await mento.swap.buildSwapParams(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a', // USDm
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438', // CELO
+     *   parseUnits('100', 18),
+     *   '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // recipient
+     *   { slippageTolerance: 0.5, deadline: deadlineFromMinutes(5) }
+     * )
+     *
+     * // Execute with any wallet (assumes approval already granted)
+     * await walletClient.sendTransaction(swapDetails.params)
+     * ```
+     */
+    buildSwapParams(tokenIn: string, tokenOut: string, amountIn: bigint, recipient: string, options: SwapOptions, route?: Route): Promise<SwapDetails>;
+    prepareSwap(input: PrepareSwapInput): Promise<PreparedSwap>;
+    /**
+     * Builds approval transaction params for the Router to spend tokenIn
+     * @private
+     */
+    private buildApprovalParams;
+    /**
+     * Gets current allowance for the Router contract
+     * @private
+     */
+    private getAllowance;
+    /**
+     * Validates that the input amount is strictly positive.
+     * @private
+     */
+    private validateAmountIn;
+    /**
+     * Calculates minimum output amount after applying slippage tolerance
+     * @param amountOut - Expected output amount
+     * @param slippageTolerance - Slippage tolerance as percentage (e.g., 0.5 for 0.5%)
+     * @returns Minimum acceptable output amount
+     * @throws Error if slippage tolerance is invalid
+     * @private
+     */
+    private calculateMinAmountOut;
+    /**
+     * Encodes the swapExactTokensForTokens function call
+     * @private
+     */
+    private encodeSwapCall;
+}
+//# sourceMappingURL=SwapService.d.ts.map