@mento-protocol/mento-sdk 3.2.3 → 3.2.5

package/dist/services/pools/rebalancePreview.js

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

package/dist/services/quotes/QuoteService.d.ts

@@ -0,0 +1,51 @@
+import { PublicClient } from 'viem';
+import { RouteService } from '../routes';
+import { Route } from '../../core/types';
+/**
+ * Service for getting swap quotes from the Mento protocol.
+ * Calculates expected output amounts for trades without executing them.
+ */
+export declare class QuoteService {
+    private publicClient;
+    private chainId;
+    private routeService;
+    constructor(publicClient: PublicClient, chainId: number, routeService: RouteService);
+    /**
+     * Calculates the expected output amount for a swap between two tokens.
+     *
+     * @param tokenIn - The address of the input token (e.g., '0x765DE816845861e75A25fCA122bb6898B8B1282a')
+     * @param tokenOut - The address of the output token (e.g., '0x471EcE3750Da237f93B8E339c536989b8978a438')
+     * @param amountIn - The amount of input tokens (in wei/smallest unit)
+     * @param route - Optional pre-fetched route. If not provided, the optimal route will be found automatically.
+     * @returns The expected output amount (in wei/smallest unit)
+     * @throws {RouteNotFoundError} If no route exists between the token pair
+     * @throws {Error} If the Router contract call fails
+     *
+     * @example
+     * ```typescript
+     * // Calculate output for 100 USDm
+     * const amountIn = BigInt(100) * BigInt(10 ** 18) // 100 USDm in wei
+     * const expectedOut = await quoteService.getAmountOut(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a', // USDm
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438', // CELO
+     *   amountIn
+     * )
+     * console.log(`Expected CELO output: ${expectedOut}`)
+     *
+     * // Or provide a pre-fetched route for better performance
+     * const route = await routeService.findRoute(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a',
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438'
+     * )
+     * const expectedOut2 = await quoteService.getAmountOut(
+     *   '0x765DE816845861e75A25fCA122bb6898B8B1282a',
+     *   '0x471EcE3750Da237f93B8E339c536989b8978a438',
+     *   amountIn,
+     *   route
+     * )
+     * ```
+     */
+    getAmountOut(tokenIn: string, tokenOut: string, amountIn: bigint, route?: Route): Promise<bigint>;
+}
+export declare function getAmountOutForRoute(publicClient: PublicClient, chainId: number, tokenIn: string, tokenOut: string, amountIn: bigint, route: Route): Promise<bigint>;
+//# sourceMappingURL=QuoteService.d.ts.map

package/dist/services/quotes/QuoteService.js

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

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

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

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

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

@@ -0,0 +1,117 @@
+import { PoolService } from '../pools';
+import { Route, RouteWithCost } from '../../core/types';
+import { PublicClient } from 'viem';
+export interface RouteOptions {
+    /**
+     * Whether to use pre-generated cached routes (default: true)
+     */
+    cached?: boolean;
+    /**
+     * Whether to return all possible routes or just the optimal one per pair (default: false)
+     */
+    returnAllRoutes?: boolean;
+}
+/**
+ * Service for discovering and managing trading routes in the Mento protocol.
+ * Handles route discovery for both direct (single-hop) and multi-hop trading paths.
+ *
+ * Routes are identified by their token pair and include the path of pools
+ * needed to execute the trade. Multi-hop routes (up to 2 hops) are automatically
+ * discovered when no direct route exists between two tokens.
+ */
+export declare class RouteService {
+    private publicClient;
+    private chainId;
+    private poolService;
+    private symbolCache;
+    private routeCache;
+    private routeLookupCache;
+    private routePromises;
+    constructor(publicClient: PublicClient, chainId: number, poolService: PoolService);
+    /**
+     * 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`)
+     * ```
+     */
+    getDirectRoutes(): Promise<Route[]>;
+    /**
+     * 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 })
+     * ```
+     */
+    getRoutes(options?: RouteOptions): Promise<readonly (Route | RouteWithCost)[]>;
+    warm(options?: RouteOptions): Promise<readonly (Route | RouteWithCost)[]>;
+    /**
+     * 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)
+     * }
+     * ```
+     */
+    findRoute(tokenIn: string, tokenOut: string, options?: {
+        cached?: boolean;
+    }): Promise<Route>;
+    /**
+     * Generate fresh tradable routes from blockchain data
+     * @param returnAllRoutes - Whether to return all routes or just optimal ones per pair
+     * @private
+     */
+    private generateFreshRoutes;
+    /**
+     * Load cached tradable routes for current chain
+     * @private
+     */
+    private loadCachedRoutes;
+    private loadRoutes;
+    private getCacheKey;
+    private buildLookup;
+    private hydrateTokenSymbols;
+    /**
+     * Helper: Fetch token symbol from on-chain
+     * Results are cached to avoid redundant RPC calls
+     * Falls back to address if symbol fetch fails
+     *
+     * @private
+     */
+    private fetchTokenSymbol;
+}
+//# sourceMappingURL=RouteService.d.ts.map