@mento-protocol/mento-sdk 2.0.0-beta.9 → 3.0.0-beta.2

package/dist/services/routes/RouteService.js

@@ -0,0 +1,241 @@
+"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 (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __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");
+/**
+ * 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();
+    }
+    /**
+     * 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 Promise.all(tokenAddresses.map((addr) => this.fetchTokenSymbol(addr)));
+        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) {
+                // TODO: Consider error handling across the codebase for better consumer experience.
+                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;
+        if (cached) {
+            // Try to load from static cache
+            try {
+                const cachedRoutes = await this.loadCachedRoutes();
+                if (cachedRoutes.length > 0) {
+                    return cachedRoutes;
+                }
+            }
+            catch {
+                console.warn('Failed to load cached routes, falling back to fresh generation');
+            }
+        }
+        // Generate fresh routes from blockchain
+        return this.generateFreshRoutes(returnAllRoutes);
+    }
+    /**
+     * 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 cUSD = '0x765DE816845861e75A25fCA122bb6898B8B1282a'
+     * const cBRL = '0xE4D5...'
+     * const route = await routeService.findRoute(cUSD, cBRL)
+     *
+     * if (route.path.length === 1) {
+     *   console.log('Direct route available')
+     * } else {
+     *   console.log('Two-hop route:', route.path)
+     * }
+     * ```
+     */
+    async findRoute(tokenIn, tokenOut, options) {
+        // Get all tradable routes
+        const allRoutes = await this.getRoutes(options);
+        const t0 = tokenIn.toLowerCase();
+        const t1 = tokenOut.toLowerCase();
+        // Search for matching route (bidirectional)
+        const matchingRoute = allRoutes.find((route) => {
+            const a0 = route.tokens[0].address.toLowerCase();
+            const a1 = route.tokens[1].address.toLowerCase();
+            // Match either direction: (t0,t1) or (t1,t0)
+            return (a0 === t0 && a1 === t1) || (a0 === t1 && a1 === t0);
+        });
+        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 || [];
+    }
+    /**
+     * 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({
+                // TODO: Consider using Address type from viem. Keep this consistent across the codebase
+                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
+            console.warn(`Failed to fetch symbol for token ${address}, using address as fallback`);
+            this.symbolCache.set(address, address);
+            return address;
+        }
+    }
+}
+exports.RouteService = RouteService;
+//# sourceMappingURL=RouteService.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RouteService.js","sourceRoot":"","sources":["../../../src/services/routes/RouteService.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AACA,0CAA2C;AAC3C,8CAAsD;AAEtD,uDAA4G;AAC5G,qDAA0D;AAc1D;;;;;;;GAOG;AACH,MAAa,YAAY;IAGvB,YAAoB,YAA0B,EAAU,OAAe,EAAU,WAAwB;QAArF,iBAAY,GAAZ,YAAY,CAAc;QAAU,YAAO,GAAP,OAAO,CAAQ;QAAU,gBAAW,GAAX,WAAW,CAAa;QAFjG,gBAAW,GAAwB,IAAI,GAAG,EAAE,CAAA;IAEwD,CAAC;IAE7G;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,eAAe;QACnB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAA;QAE/C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAA;QACX,CAAC;QAED,mCAAmC;QACnC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAA;QACtC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAU,EAAE,EAAE;YAC3B,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YAC7B,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC/B,CAAC,CAAC,CAAA;QAEF,mEAAmE;QACnE,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;QAC/C,MAAM,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAEpF,MAAM,MAAM,GAAY,EAAE,CAAA;QAE1B,iBAAiB;QACjB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YACjD,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YAEjD,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;gBACzB,oFAAoF;gBACpF,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;YAChF,CAAC;YAED,4DAA4D;YAC5D,MAAM,OAAO,GAAG,IAAA,8BAAkB,EAAC,OAAO,EAAE,OAAO,CAAY,CAAA;YAE/D,6EAA6E;YAC7E,MAAM,YAAY,GAChB,OAAO,GAAG,OAAO;gBACf,CAAC,CAAC;oBACE,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;oBACzC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;iBAC1C;gBACH,CAAC,CAAC;oBACE,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;oBACzC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;iBAC1C,CAAA;YAEP,MAAM,CAAC,IAAI,CAAC;gBACV,EAAE,EAAE,OAAO;gBACX,MAAM,EAAE,YAAY;gBACpB,IAAI,EAAE,CAAC,IAAI,CAAC;aACb,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,SAAS,CAAC,OAAsB;QACpC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,IAAI,CAAA;QACtC,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,KAAK,CAAA;QAEzD,IAAI,MAAM,EAAE,CAAC;YACX,gCAAgC;YAChC,IAAI,CAAC;gBACH,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAA;gBAClD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC5B,OAAO,YAAY,CAAA;gBACrB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAA;YAChF,CAAC;QACH,CAAC;QAED,wCAAwC;QACxC,OAAO,IAAI,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAA;IAClD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,QAAgB,EAAE,OAA8B;QAC/E,0BAA0B;QAC1B,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAE/C,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA;QAChC,MAAM,EAAE,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAA;QAEjC,4CAA4C;QAC5C,MAAM,aAAa,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YAC7C,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAA;YAChD,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAA;YAEhD,6CAA6C;YAC7C,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QAC7D,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,IAAI,2BAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;QACjD,CAAC;QAED,OAAO,aAAsB,CAAA;IAC/B,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,mBAAmB,CAAC,kBAA2B,KAAK;QAChE,oBAAoB;QACpB,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,eAAe,EAAE,CAAA;QAEjD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAA;QACX,CAAC;QAED,kDAAkD;QAClD,MAAM,YAAY,GAAG,IAAA,wCAA2B,EAAC,YAAY,CAAC,CAAA;QAE9D,gDAAgD;QAChD,MAAM,SAAS,GAAG,IAAA,8BAAiB,EAAC,YAAY,CAAC,CAAA;QAEjD,8CAA8C;QAC9C,MAAM,cAAc,GAAG,IAAA,gCAAmB,EAAC,SAAS,EAAE,eAAe,EAAE,YAAY,CAAC,YAAY,CAAC,CAAA;QAEjG,OAAO,cAAyB,CAAA;IAClC,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,gBAAgB;QAC5B,MAAM,EAAE,eAAe,EAAE,GAAG,wDAAa,oBAAoB,GAAC,CAAA;QAC9D,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACxD,OAAQ,YAAgC,IAAI,EAAE,CAAA;IAChD,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,gBAAgB,CAAC,OAAe;QAC5C,oCAAoC;QACpC,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAE,CAAA;QACvC,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC;gBACnD,wFAAwF;gBACxF,OAAO,EAAE,OAAwB;gBACjC,GAAG,EAAE,gBAAS;gBACd,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,EAAE;aACT,CAAC,CAAW,CAAA;YAEb,mBAAmB;YACnB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YACrC,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;YAC5C,OAAO,CAAC,IAAI,CAAC,oCAAoC,OAAO,6BAA6B,CAAC,CAAA;YACtF,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YACtC,OAAO,OAAO,CAAA;QAChB,CAAC;IACH,CAAC;CACF;AAlOD,oCAkOC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/routes/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA"}

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/routes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/routes/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA8B"}

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

@@ -0,0 +1,158 @@
+import { Address, 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
+     * Defaults to 20 minutes from now if not provided
+     */
+    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;
+}
+/**
+ * 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
+     * @param tokenOut - The address of the output token
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const { approval, swap } = await mento.swap.buildSwapTransaction(
+     *   cUSD,
+     *   CELO,
+     *   parseUnits('100', 18),
+     *   recipientAddress,
+     *   ownerAddress,
+     *   { slippageTolerance: 0.5 }
+     * )
+     *
+     * // Execute approval if needed
+     * if (approval) {
+     *   await walletClient.sendTransaction(approval)
+     * }
+     *
+     * // Execute swap
+     * await walletClient.sendTransaction(swap.params)
+     * ```
+     */
+    buildSwapTransaction(tokenIn: Address, tokenOut: Address, amountIn: bigint, recipient: Address, owner: Address, 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
+     * @param tokenOut - The address of the output token
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const swapDetails = await mento.swap.buildSwapParams(
+     *   cUSD,
+     *   CELO,
+     *   parseUnits('100', 18),
+     *   recipientAddress,
+     *   { slippageTolerance: 0.5 }
+     * )
+     *
+     * // Execute with any wallet (assumes approval already granted)
+     * await walletClient.sendTransaction(swapDetails.params)
+     * ```
+     */
+    buildSwapParams(tokenIn: Address, tokenOut: Address, amountIn: bigint, recipient: Address, options: SwapOptions, route?: Route): Promise<SwapDetails>;
+    /**
+     * Builds approval transaction params for the Router to spend tokenIn
+     * @private
+     */
+    private buildApprovalParams;
+    /**
+     * Gets current allowance for the Router contract
+     * @private
+     */
+    private getAllowance;
+    /**
+     * Calculates minimum output amount after applying slippage tolerance
+     * @private
+     */
+    private calculateMinAmountOut;
+    /**
+     * Encodes the swapExactTokensForTokens function call
+     * @private
+     */
+    private encodeSwapCall;
+}
+//# sourceMappingURL=SwapService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SwapService.d.ts","sourceRoot":"","sources":["../../../src/services/swap/SwapService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAsB,MAAM,MAAM,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAGpD,OAAO,EAAmB,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAEtE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAA;IACZ;;OAEG;IACH,YAAY,EAAE,WAAW,EAAE,CAAA;IAC3B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAA;IAC3B;;OAEG;IACH,IAAI,EAAE,WAAW,CAAA;CAClB;AAED;;;GAGG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,YAAY;gBAHZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,YAAY;IAGpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,oBAAoB,CACxB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,EAClB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,KAAK,GACZ,OAAO,CAAC,eAAe,CAAC;IAW3B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,eAAe,CACnB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,KAAK,GACZ,OAAO,CAAC,WAAW,CAAC;IA+BvB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;OAGG;YACW,YAAY;IAU1B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAM7B;;;OAGG;IACH,OAAO,CAAC,cAAc;CAavB"}

package/dist/services/swap/SwapService.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwapService = void 0;
+const viem_1 = require("viem");
+const abis_1 = require("../../core/abis");
+const constants_1 = require("../../core/constants");
+const pathEncoder_1 = require("../../utils/pathEncoder");
+/**
+ * Service for building token swap transactions on the Mento protocol.
+ * Returns transaction parameters that can be executed by any wallet.
+ */
+class SwapService {
+    constructor(publicClient, chainId, routeService, quoteService) {
+        this.publicClient = publicClient;
+        this.chainId = chainId;
+        this.routeService = routeService;
+        this.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
+     * @param tokenOut - The address of the output token
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const { approval, swap } = await mento.swap.buildSwapTransaction(
+     *   cUSD,
+     *   CELO,
+     *   parseUnits('100', 18),
+     *   recipientAddress,
+     *   ownerAddress,
+     *   { slippageTolerance: 0.5 }
+     * )
+     *
+     * // Execute approval if needed
+     * if (approval) {
+     *   await walletClient.sendTransaction(approval)
+     * }
+     *
+     * // Execute swap
+     * await walletClient.sendTransaction(swap.params)
+     * ```
+     */
+    async buildSwapTransaction(tokenIn, tokenOut, amountIn, recipient, owner, options, route) {
+        // Build swap params first
+        const swap = await this.buildSwapParams(tokenIn, tokenOut, amountIn, recipient, options, route);
+        // Check if approval is needed
+        const currentAllowance = await this.getAllowance(tokenIn, owner);
+        const approval = currentAllowance < amountIn ? this.buildApprovalParams(tokenIn, amountIn) : null;
+        return { approval, swap };
+    }
+    /**
+     * 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
+     * @param tokenOut - The address of the output token
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const swapDetails = await mento.swap.buildSwapParams(
+     *   cUSD,
+     *   CELO,
+     *   parseUnits('100', 18),
+     *   recipientAddress,
+     *   { slippageTolerance: 0.5 }
+     * )
+     *
+     * // Execute with any wallet (assumes approval already granted)
+     * await walletClient.sendTransaction(swapDetails.params)
+     * ```
+     */
+    async buildSwapParams(tokenIn, tokenOut, amountIn, recipient, options, route) {
+        // Find route if not provided
+        if (!route) {
+            route = await this.routeService.findRoute(tokenIn, tokenOut);
+        }
+        const expectedAmountOut = await this.quoteService.getAmountOut(tokenIn, tokenOut, amountIn, route);
+        const amountOutMin = this.calculateMinAmountOut(expectedAmountOut, options.slippageTolerance);
+        // Set deadline (default: 20 minutes from now)
+        const deadline = options.deadline ?? BigInt(Math.floor(Date.now() / 1000) + 20 * 60);
+        const routerRoutes = (0, pathEncoder_1.encodeRoutePath)(route.path, tokenIn, tokenOut);
+        const routerAddress = (0, constants_1.getContractAddress)(this.chainId, 'Router');
+        const data = this.encodeSwapCall(amountIn, amountOutMin, routerRoutes, recipient, deadline);
+        return {
+            params: {
+                to: routerAddress,
+                data,
+                value: '0',
+            },
+            route,
+            routerRoutes,
+            amountIn,
+            amountOutMin,
+            expectedAmountOut,
+            deadline,
+        };
+    }
+    /**
+     * Builds approval transaction params for the Router to spend tokenIn
+     * @private
+     */
+    buildApprovalParams(tokenIn, amount) {
+        const routerAddress = (0, constants_1.getContractAddress)(this.chainId, 'Router');
+        const data = (0, viem_1.encodeFunctionData)({
+            abi: abis_1.ERC20_ABI,
+            functionName: 'approve',
+            args: [routerAddress, amount],
+        });
+        return { to: tokenIn, data, value: '0' };
+    }
+    /**
+     * Gets current allowance for the Router contract
+     * @private
+     */
+    async getAllowance(tokenIn, owner) {
+        const routerAddress = (0, constants_1.getContractAddress)(this.chainId, 'Router');
+        return this.publicClient.readContract({
+            address: tokenIn,
+            abi: abis_1.ERC20_ABI,
+            functionName: 'allowance',
+            args: [owner, routerAddress],
+        });
+    }
+    /**
+     * Calculates minimum output amount after applying slippage tolerance
+     * @private
+     */
+    calculateMinAmountOut(amountOut, slippageTolerance) {
+        const basisPoints = BigInt(Math.floor(slippageTolerance * 100));
+        const slippageMultiplier = 10000n - basisPoints;
+        return (amountOut * slippageMultiplier) / 10000n;
+    }
+    /**
+     * Encodes the swapExactTokensForTokens function call
+     * @private
+     */
+    encodeSwapCall(amountIn, amountOutMin, routes, recipient, deadline) {
+        return (0, viem_1.encodeFunctionData)({
+            abi: abis_1.ROUTER_ABI,
+            functionName: 'swapExactTokensForTokens',
+            args: [amountIn, amountOutMin, routes, recipient, deadline],
+        });
+    }
+}
+exports.SwapService = SwapService;
+//# sourceMappingURL=SwapService.js.map

package/dist/services/swap/SwapService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwapService.js","sourceRoot":"","sources":["../../../src/services/swap/SwapService.ts"],"names":[],"mappings":"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"}

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

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

package/dist/services/swap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/swap/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA"}

package/dist/services/swap/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("./SwapService"), exports);
+//# sourceMappingURL=index.js.map

package/dist/services/swap/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/swap/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA6B"}

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

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

package/dist/services/tokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/tokens/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA"}

package/dist/services/tokens/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("./tokenService"), exports);
+//# sourceMappingURL=index.js.map