@mento-protocol/mento-sdk 3.2.7 → 3.3.0-beta.0

package/dist/utils/costUtils.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPoolCostPercent = getPoolCostPercent;
+const types_1 = require("../core/types");
+const abis_1 = require("../core/abis");
+const virtualPool_1 = require("../core/abis/virtualPool");
+const multicall_1 = require("./multicall");
+/**
+ * Calculate cost percentage for a pool based on its type
+ * Returns cost as a percentage (e.g., 0.5 = 0.5%)
+ *
+ * @param pool - The pool to calculate cost for
+ * @param publicClient - Viem public client for RPC calls
+ * @returns Cost percentage for the pool
+ */
+async function getPoolCostPercent(pool, publicClient) {
+    if (pool.poolType === types_1.PoolType.FPMM) {
+        return getFPMMCostPercent(pool.poolAddr, publicClient);
+    }
+    else if (pool.poolType === types_1.PoolType.Virtual) {
+        return getVirtualPoolCostPercent(pool.poolAddr, publicClient);
+    }
+    else {
+        throw new Error('Invalid pool type');
+    }
+}
+/**
+ * Calculate cost for FPMM pools
+ * FPMM pools use lpFee + protocolFee in basis points (10000 = 100%)
+ */
+async function getFPMMCostPercent(poolAddress, publicClient) {
+    const results = await (0, multicall_1.multicall)(publicClient, [
+        { address: poolAddress, abi: abis_1.FPMM_ABI, functionName: 'lpFee' },
+        { address: poolAddress, abi: abis_1.FPMM_ABI, functionName: 'protocolFee' },
+    ]);
+    if (results[0].status === 'failure' || results[1].status === 'failure') {
+        throw new Error(`Failed to read fees for pool ${poolAddress}`);
+    }
+    const lpFee = results[0].result;
+    const protocolFee = results[1].result;
+    // Convert from basis points to percentage using BigInt arithmetic to avoid precision loss
+    const totalBasisPoints = lpFee + protocolFee;
+    const scaled = totalBasisPoints * 1000000n;
+    return Number(scaled / 100n) / 1e6;
+}
+/**
+ * Calculate cost for Virtual pools
+ */
+async function getVirtualPoolCostPercent(poolAddress, publicClient) {
+    const results = await (0, multicall_1.multicall)(publicClient, [
+        { address: poolAddress, abi: virtualPool_1.VIRTUAL_POOL_ABI, functionName: 'protocolFee' },
+    ]);
+    if (results[0].status === 'failure') {
+        throw new Error(`Failed to read protocolFee for pool ${poolAddress}`);
+    }
+    // Convert from basis points to percentage using BigInt arithmetic to avoid precision loss
+    const scaled = results[0].result * 1000000n;
+    return Number(scaled / 100n) / 1e6;
+}
+//# sourceMappingURL=costUtils.js.map

package/dist/utils/deadline.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Creates a deadline timestamp from a duration in minutes.
+ *
+ * @param minutes - Number of minutes from now
+ * @returns Unix timestamp as bigint suitable for router contract deadline parameter
+ *
+ * @example
+ * ```typescript
+ * import { deadlineFromMinutes } from '@mento-protocol/mento-sdk'
+ *
+ * // 5 minute deadline
+ * const deadline = deadlineFromMinutes(5)
+ *
+ * const swap = await mento.swap.buildSwapParams(
+ *   tokenIn, tokenOut, amountIn, recipient,
+ *   { slippageTolerance: 0.5, deadline }
+ * )
+ * ```
+ */
+export declare function deadlineFromMinutes(minutes: number): bigint;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/utils/deadline.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deadlineFromMinutes = deadlineFromMinutes;
+/**
+ * Creates a deadline timestamp from a duration in minutes.
+ *
+ * @param minutes - Number of minutes from now
+ * @returns Unix timestamp as bigint suitable for router contract deadline parameter
+ *
+ * @example
+ * ```typescript
+ * import { deadlineFromMinutes } from '@mento-protocol/mento-sdk'
+ *
+ * // 5 minute deadline
+ * const deadline = deadlineFromMinutes(5)
+ *
+ * const swap = await mento.swap.buildSwapParams(
+ *   tokenIn, tokenOut, amountIn, recipient,
+ *   { slippageTolerance: 0.5, deadline }
+ * )
+ * ```
+ */
+function deadlineFromMinutes(minutes) {
+    return BigInt(Date.now()) / 1000n + BigInt(minutes * 60);
+}
+//# sourceMappingURL=deadline.js.map

package/dist/utils/index.d.ts

@@ -0,0 +1,10 @@
+export * from './retry';
+export * from './chainConfig';
+export * from './routes';
+export * from './sortUtils';
+export * from './pathEncoder';
+export * from './tokens';
+export * from './rateFeed';
+export * from './tradingLimits';
+export * from './deadline';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -0,0 +1,26 @@
+"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("./retry"), exports);
+__exportStar(require("./chainConfig"), exports);
+__exportStar(require("./routes"), exports);
+__exportStar(require("./sortUtils"), exports);
+__exportStar(require("./pathEncoder"), exports);
+__exportStar(require("./tokens"), exports);
+__exportStar(require("./rateFeed"), exports);
+__exportStar(require("./tradingLimits"), exports);
+__exportStar(require("./deadline"), exports);
+//# sourceMappingURL=index.js.map

package/dist/utils/multicall.d.ts

@@ -0,0 +1,30 @@
+import type { Abi, PublicClient } from 'viem';
+/**
+ * Standard Multicall3 contract address, deployed at the same address on all EVM chains.
+ * https://www.multicall3.com/
+ */
+export declare const MULTICALL3_ADDRESS: "0xcA11bde05977b3631167028862bE2a173976CA11";
+type MulticallResult = {
+    status: 'success';
+    result: unknown;
+} | {
+    status: 'failure';
+    error: Error;
+};
+interface ContractCall {
+    address: `0x${string}`;
+    abi: Abi | readonly unknown[];
+    functionName: string;
+    args?: readonly unknown[];
+}
+interface MulticallOptions {
+    allowFailure?: boolean;
+    batchSize?: number;
+}
+/**
+ * Wrapper around viem's multicall that explicitly provides the Multicall3 address.
+ * This ensures multicall works even when the PublicClient was created without a `chain` config.
+ */
+export declare function multicall(publicClient: PublicClient, contracts: ContractCall[], options?: MulticallOptions): Promise<MulticallResult[]>;
+export {};
+//# sourceMappingURL=multicall.d.ts.map

package/dist/utils/multicall.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTICALL3_ADDRESS = void 0;
+exports.multicall = multicall;
+/**
+ * Standard Multicall3 contract address, deployed at the same address on all EVM chains.
+ * https://www.multicall3.com/
+ */
+exports.MULTICALL3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11';
+/**
+ * Wrapper around viem's multicall that explicitly provides the Multicall3 address.
+ * This ensures multicall works even when the PublicClient was created without a `chain` config.
+ */
+async function multicall(publicClient, contracts, options = {}) {
+    const { allowFailure = true, batchSize } = options;
+    const client = publicClient;
+    if (typeof client.multicall !== 'function') {
+        if (typeof client.readContract !== 'function') {
+            throw new Error('Public client does not support multicall or readContract');
+        }
+        return Promise.all(contracts.map(async (contract) => {
+            try {
+                const result = await client.readContract({
+                    ...contract,
+                    args: contract.args ?? [],
+                });
+                return { status: 'success', result };
+            }
+            catch (error) {
+                if (!allowFailure) {
+                    throw error;
+                }
+                return {
+                    status: 'failure',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                };
+            }
+        }));
+    }
+    const raw = await client.multicall({
+        allowFailure,
+        batchSize,
+        contracts: contracts,
+        multicallAddress: exports.MULTICALL3_ADDRESS,
+    });
+    const results = raw;
+    if (!allowFailure) {
+        return results.map((result) => ({ status: 'success', result }));
+    }
+    return results;
+}
+//# sourceMappingURL=multicall.js.map

package/dist/utils/pathEncoder.d.ts

@@ -0,0 +1,34 @@
+import { Address } from 'viem';
+import { Pool } from '../core/types';
+/**
+ * Route structure expected by the Router contract's getAmountsOut and swapTokensForTokens functions
+ */
+export interface RouterRoute {
+    from: Address;
+    to: Address;
+    factory: Address;
+}
+export type ReadonlyRouterRoutes = readonly {
+    from: Address;
+    to: Address;
+    factory: Address;
+}[];
+/**
+ * Converts a route path to the format expected by the Router contract.
+ * Used by both QuoteService (getAmountsOut) and SwapService (swapTokensForTokens).
+ *
+ * @param path - The route path (array of pools)
+ * @param tokenIn - The input token address (determines swap direction)
+ * @param _tokenOut - The output token address (unused but kept for API clarity)
+ * @returns Array of RouterRoute objects for the contract call
+ * @throws {Error} If path is empty, too long, or contains invalid pools
+ *
+ * @example
+ * ```typescript
+ * const route = await routeService.findRoute(USDm, CELO)
+ * const routerRoutes = encodeRoutePath(route.path, USDm, CELO)
+ * // routerRoutes can now be passed to Router.getAmountsOut or Router.swapTokensForTokens
+ * ```
+ */
+export declare function encodeRoutePath(path: Pool[], tokenIn: Address, _tokenOut: Address): RouterRoute[];
+//# sourceMappingURL=pathEncoder.d.ts.map

package/dist/utils/pathEncoder.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeRoutePath = encodeRoutePath;
+/**
+ * Converts a route path to the format expected by the Router contract.
+ * Used by both QuoteService (getAmountsOut) and SwapService (swapTokensForTokens).
+ *
+ * @param path - The route path (array of pools)
+ * @param tokenIn - The input token address (determines swap direction)
+ * @param _tokenOut - The output token address (unused but kept for API clarity)
+ * @returns Array of RouterRoute objects for the contract call
+ * @throws {Error} If path is empty, too long, or contains invalid pools
+ *
+ * @example
+ * ```typescript
+ * const route = await routeService.findRoute(USDm, CELO)
+ * const routerRoutes = encodeRoutePath(route.path, USDm, CELO)
+ * // routerRoutes can now be passed to Router.getAmountsOut or Router.swapTokensForTokens
+ * ```
+ */
+function encodeRoutePath(path, tokenIn, _tokenOut) {
+    // Validate path is not empty
+    if (!path || path.length === 0) {
+        throw new Error('Internal error: Route path is empty. This should not happen - routes are validated before encoding.');
+    }
+    // Validate all pools have required structure
+    for (let i = 0; i < path.length; i++) {
+        const pool = path[i];
+        if (!pool.token0 || !pool.token1 || !pool.factoryAddr) {
+            throw new Error(`Invalid pool structure at index ${i}: missing required fields. ` +
+                `Pool must have token0, token1, and factoryAddr. ` +
+                `Got: ${JSON.stringify(pool)}`);
+        }
+    }
+    const routes = [];
+    const tokenInLower = tokenIn.toLowerCase();
+    // Check if we need to reverse the path
+    // The path is stored in canonical order, but we may need to traverse it backwards
+    const firstPool = path[0];
+    const startsWithTokenIn = firstPool.token0.toLowerCase() === tokenInLower || firstPool.token1.toLowerCase() === tokenInLower;
+    // If tokenIn isn't in the first pool, reverse the path
+    const orderedPath = startsWithTokenIn ? path : [...path].reverse();
+    let currentTokenIn = tokenInLower;
+    for (const pool of orderedPath) {
+        const token0 = pool.token0.toLowerCase();
+        const token1 = pool.token1.toLowerCase();
+        // Determine direction: which token is the input for this hop?
+        let from;
+        let to;
+        if (currentTokenIn === token0) {
+            from = pool.token0;
+            to = pool.token1;
+        }
+        else if (currentTokenIn === token1) {
+            from = pool.token1;
+            to = pool.token0;
+        }
+        else {
+            throw new Error(`Route encoding error: Token ${currentTokenIn} not found in pool ${pool.poolAddr}. ` +
+                `Pool contains tokens: ${token0}, ${token1}. ` +
+                `This indicates the route path is invalid or tokens don't form a connected path.`);
+        }
+        routes.push({
+            from,
+            to,
+            factory: pool.factoryAddr,
+        });
+        // The output of this hop becomes the input of the next hop
+        currentTokenIn = to.toLowerCase();
+    }
+    return routes;
+}
+//# sourceMappingURL=pathEncoder.js.map

package/dist/utils/rateFeed.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Computes the rate feed ID from a rate feed identifier string.
+ * Follows the Solidity formula: address(uint160(uint256(keccak256(abi.encodePacked(rateFeed)))))
+ *
+ * @param rateFeed - The rate feed identifier string (e.g., "EURUSD", "relayed:COPUSD")
+ * @returns The computed rate feed address as a hex string
+ *
+ * @example
+ * ```typescript
+ * const rateFeedId = toRateFeedId('EURUSD')
+ * // Returns the computed address for the EURUSD rate feed
+ *
+ * const relayedRateFeedId = toRateFeedId('relayed:COPUSD')
+ * // Returns the computed address for the relayed COPUSD rate feed
+ * ```
+ */
+export declare function toRateFeedId(rateFeed: string): `0x${string}`;
+//# sourceMappingURL=rateFeed.d.ts.map

package/dist/utils/rateFeed.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRateFeedId = toRateFeedId;
+const viem_1 = require("viem");
+/**
+ * Computes the rate feed ID from a rate feed identifier string.
+ * Follows the Solidity formula: address(uint160(uint256(keccak256(abi.encodePacked(rateFeed)))))
+ *
+ * @param rateFeed - The rate feed identifier string (e.g., "EURUSD", "relayed:COPUSD")
+ * @returns The computed rate feed address as a hex string
+ *
+ * @example
+ * ```typescript
+ * const rateFeedId = toRateFeedId('EURUSD')
+ * // Returns the computed address for the EURUSD rate feed
+ *
+ * const relayedRateFeedId = toRateFeedId('relayed:COPUSD')
+ * // Returns the computed address for the relayed COPUSD rate feed
+ * ```
+ */
+function toRateFeedId(rateFeed) {
+    const hashedBytes = (0, viem_1.keccak256)((0, viem_1.toBytes)(rateFeed));
+    const hashAsBigInt = BigInt(hashedBytes);
+    const maskedToUint160 = hashAsBigInt & ((1n << 160n) - 1n);
+    return `0x${maskedToUint160.toString(16).padStart(40, '0')}`;
+}
+//# sourceMappingURL=rateFeed.js.map

package/dist/utils/retry.d.ts

@@ -0,0 +1,12 @@
+export interface RetryOptions {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+}
+/**
+ * Retry an operation a number of times with exponential backoff.
+ * @param operation - The operation to retry
+ * @param options - The retry options
+ * @returns The result of the operation
+ */
+export declare function retryOperation<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryOperation = retryOperation;
+/**
+ * Retry an operation a number of times with exponential backoff.
+ * @param operation - The operation to retry
+ * @param options - The retry options
+ * @returns The result of the operation
+ */
+async function retryOperation(operation, options = {}) {
+    const maxAttempts = options.maxAttempts ?? 3;
+    const delayMs = options.initialDelayMs ?? 1000;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === maxAttempts)
+                break;
+            // Exponential backoff
+            await new Promise((resolve) => setTimeout(resolve, delayMs * attempt));
+        }
+    }
+    throw new Error(`Operation failed after ${maxAttempts} attempts: ${lastError?.message}`);
+}
+//# sourceMappingURL=retry.js.map