@mento-protocol/mento-sdk 3.2.3 → 3.2.5

package/dist/esm/services/trading/TradingService.js

@@ -0,0 +1,222 @@
+import { isTradingEnabled, PoolType, } from '../../core/types';
+import { TradingLimitsService } from './TradingLimitsService';
+import { BIPOOL_MANAGER_ABI, BREAKERBOX_ABI, FPMM_ABI } from '../../core/abis';
+import { getContractAddress, tryGetContractAddress } from '../../core/constants';
+import { multicall } from '../../utils/multicall';
+/**
+ * Service for checking trading status and circuit breaker state in the Mento protocol.
+ * Provides methods to query whether trading is enabled for specific rate feeds,
+ * token pairs, or routes. Also integrates trading limit checks.
+ */
+export class TradingService {
+    constructor(publicClient, chainId, routeService) {
+        this.publicClient = publicClient;
+        this.chainId = chainId;
+        this.routeService = routeService;
+        this.tradingLimitsService = new TradingLimitsService(publicClient, chainId);
+    }
+    /**
+     * Returns the current trading mode for a given rate feed.
+     *
+     * The BreakerBox uses a bitmask approach where 0 means bidirectional trading
+     * is enabled, and any non-zero value means trading is suspended.
+     *
+     * @param rateFeedId - The address of the rate feed
+     * @returns The raw trading mode value from BreakerBox (0 = enabled, non-zero = suspended)
+     *
+     * @example
+     * ```typescript
+     * const mode = await tradingService.getRateFeedTradingMode(rateFeedId)
+     * if (mode === TradingMode.BIDIRECTIONAL) {
+     *   console.log('Trading is enabled')
+     * }
+     * ```
+     */
+    async getRateFeedTradingMode(rateFeedId) {
+        const breakerBoxAddr = getContractAddress(this.chainId, 'BreakerBox');
+        const mode = await this.publicClient.readContract({
+            address: breakerBoxAddr,
+            abi: BREAKERBOX_ABI,
+            functionName: 'getRateFeedTradingMode',
+            args: [rateFeedId],
+        });
+        return Number(mode);
+    }
+    /**
+     * Checks if a trading pair is currently tradable.
+     * For multi-hop routes (e.g., CELO → USDm → USDT), checks that ALL
+     * intermediate rate feeds are in BIDIRECTIONAL mode.
+     *
+     * @param tokenIn - Input token address
+     * @param tokenOut - Output token address
+     * @returns true if the pair is tradable (all rate feeds BIDIRECTIONAL), false otherwise
+     * @throws {RouteNotFoundError} If no route exists between the token pair
+     *
+     * @example
+     * ```typescript
+     * const isTradable = await tradingService.isPairTradable(USDm, CELO)
+     * if (!isTradable) {
+     *   console.log('Trading is currently suspended for this pair')
+     * }
+     * ```
+     */
+    async isPairTradable(tokenIn, tokenOut) {
+        const route = await this.routeService.findRoute(tokenIn, tokenOut);
+        return this.isRouteTradable(route);
+    }
+    /**
+     * Checks if a route is currently tradable.
+     * Verifies that all pools in the route's path have their rate feeds
+     * in BIDIRECTIONAL mode.
+     *
+     * @param route - The route to check
+     * @returns true if all pools in the route are tradable, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const route = await routeService.findRoute(tokenIn, tokenOut)
+     * const isRouteTradable = await tradingService.isRouteTradable(route)
+     * ```
+     */
+    async isRouteTradable(route) {
+        const tradingModes = await this.getTradingModesForPools(route.path);
+        // All rate feeds must have trading enabled for the route to be tradable
+        return tradingModes.every((tradingMode) => isTradingEnabled(tradingMode));
+    }
+    /**
+     * Get trading limits for a pool.
+     *
+     * @param pool - The pool to get trading limits for
+     * @returns Array of TradingLimit objects with maxIn/maxOut/until
+     *
+     * @example
+     * ```typescript
+     * const limits = await tradingService.getPoolTradingLimits(pool)
+     * limits.forEach(limit => {
+     *   console.log(`${limit.asset}: maxIn=${limit.maxIn}, maxOut=${limit.maxOut}`)
+     * })
+     * ```
+     */
+    async getPoolTradingLimits(pool) {
+        return this.tradingLimitsService.getPoolTradingLimits(pool);
+    }
+    /**
+     * Get complete tradability status for a pool.
+     * Returns separate flags for circuit breaker and trading limits,
+     * allowing frontends to show different messages for each condition.
+     *
+     * @param pool - The pool to check
+     * @returns PoolTradabilityStatus with tradable, circuitBreakerOk, limitsOk, and limits
+     *
+     * @example
+     * ```typescript
+     * const status = await tradingService.getPoolTradabilityStatus(pool)
+     * if (!status.circuitBreakerOk) {
+     *   showModal("Trading temporarily suspended (circuit breaker)")
+     * } else if (!status.limitsOk) {
+     *   showModal("Trading limit reached", status.limits)
+     * }
+     * ```
+     */
+    async getPoolTradabilityStatus(pool) {
+        const [[tradingMode], limits] = await Promise.all([
+            this.getTradingModesForPools([pool]),
+            this.tradingLimitsService.getPoolTradingLimits(pool),
+        ]);
+        const circuitBreakerOk = isTradingEnabled(tradingMode);
+        // Limits are OK if no limits configured OR all limits have capacity
+        const limitsOk = limits.length === 0 || limits.every((l) => l.maxIn > 0n && l.maxOut > 0n);
+        return {
+            tradable: circuitBreakerOk && limitsOk,
+            circuitBreakerOk,
+            tradingMode,
+            limitsOk,
+            limits,
+        };
+    }
+    /**
+     * Get the reference rate feed ID for a pool.
+     * FPMM pools expose this via referenceRateFeedID() directly.
+     * Virtual pools wrap a BiPoolManager exchange; the rate feed is read from
+     * BiPoolManager.getPoolExchange(exchangeId).config.referenceRateFeedID.
+     *
+     * @param pool - The pool to get rate feed ID for
+     * @returns The rate feed ID address
+     */
+    async getPoolRateFeedId(pool) {
+        const [rateFeedId] = await this.getPoolRateFeedIds([pool]);
+        return rateFeedId;
+    }
+    async getTradingModesForPools(pools) {
+        const rateFeedIds = await this.getPoolRateFeedIds(pools);
+        return this.getTradingModesForRateFeeds(rateFeedIds);
+    }
+    async getPoolRateFeedIds(pools) {
+        if (pools.length === 0) {
+            return [];
+        }
+        const biPoolManagerAddr = pools.some((pool) => pool.poolType === PoolType.Virtual)
+            ? tryGetContractAddress(this.chainId, 'BiPoolManager')
+            : undefined;
+        const contracts = pools.map((pool) => {
+            if (pool.poolType === PoolType.Virtual) {
+                if (!pool.exchangeId) {
+                    throw new Error(`Virtual pool ${pool.poolAddr} is missing exchangeId`);
+                }
+                if (!biPoolManagerAddr) {
+                    throw new Error(`BiPoolManager address not configured for chain ID ${this.chainId}; cannot resolve rate feed for virtual pool ${pool.poolAddr}`);
+                }
+                return {
+                    address: biPoolManagerAddr,
+                    abi: BIPOOL_MANAGER_ABI,
+                    functionName: 'getPoolExchange',
+                    args: [pool.exchangeId],
+                };
+            }
+            return {
+                address: pool.poolAddr,
+                abi: FPMM_ABI,
+                functionName: 'referenceRateFeedID',
+                args: [],
+            };
+        });
+        const results = await multicall(this.publicClient, contracts, { allowFailure: false });
+        return results.map((result, index) => {
+            if (result.status === 'failure') {
+                throw result.error;
+            }
+            if (pools[index].poolType === PoolType.Virtual) {
+                const exchange = result.result;
+                return exchange.config.referenceRateFeedID;
+            }
+            return result.result;
+        });
+    }
+    async getTradingModesForRateFeeds(rateFeedIds) {
+        if (rateFeedIds.length === 0) {
+            return [];
+        }
+        const breakerBoxAddr = getContractAddress(this.chainId, 'BreakerBox');
+        const uniqueRateFeeds = Array.from(new Map(rateFeedIds.map((rateFeedId) => [rateFeedId.toLowerCase(), rateFeedId])).values());
+        const results = await multicall(this.publicClient, uniqueRateFeeds.map((rateFeedId) => ({
+            address: breakerBoxAddr,
+            abi: BREAKERBOX_ABI,
+            functionName: 'getRateFeedTradingMode',
+            args: [rateFeedId],
+        })), { allowFailure: false });
+        const tradingModes = new Map();
+        for (const [index, result] of results.entries()) {
+            if (result.status === 'failure') {
+                throw result.error;
+            }
+            tradingModes.set(uniqueRateFeeds[index].toLowerCase(), Number(result.result));
+        }
+        return rateFeedIds.map((rateFeedId) => {
+            const tradingMode = tradingModes.get(rateFeedId.toLowerCase());
+            if (tradingMode === undefined) {
+                throw new Error(`Trading mode not found for rate feed ${rateFeedId}`);
+            }
+            return tradingMode;
+        });
+    }
+}

package/dist/esm/services/trading/index.js

@@ -0,0 +1,2 @@
+export * from './TradingService';
+export * from './TradingLimitsService';

package/dist/esm/utils/chainConfig.js

@@ -0,0 +1,118 @@
+import { celo } from 'viem/chains';
+import { defineChain } from 'viem';
+import { ChainId } from '../core/constants/chainId';
+// Celo Sepolia chain definition (not available in viem/chains yet)
+const celoSepolia = defineChain({
+    id: 11142220,
+    name: 'Celo Sepolia',
+    nativeCurrency: {
+        decimals: 18,
+        name: 'CELO',
+        symbol: 'CELO',
+    },
+    rpcUrls: {
+        default: {
+            http: ['https://forno.celo-sepolia.celo-testnet.org'],
+        },
+    },
+    blockExplorers: {
+        default: {
+            name: 'Celo Explorer',
+            url: 'https://sepolia.celoscan.io',
+        },
+    },
+    testnet: true,
+});
+const monadTestnet = defineChain({
+    id: 10143,
+    name: 'Monad Testnet',
+    nativeCurrency: {
+        decimals: 18,
+        name: 'MON',
+        symbol: 'MON',
+    },
+    rpcUrls: {
+        default: {
+            http: ['https://testnet-rpc.monad.xyz'],
+        },
+    },
+    blockExplorers: {
+        default: {
+            name: 'Monad Testnet Explorer',
+            url: 'https://testnet.monadexplorer.com',
+        },
+    },
+    contracts: {
+        multicall3: {
+            address: '0xcA11bde05977b3631167028862bE2a173976CA11',
+            blockCreated: 251449,
+        },
+    },
+    testnet: true,
+});
+const monad = defineChain({
+    id: 143,
+    name: 'Monad',
+    nativeCurrency: {
+        decimals: 18,
+        name: 'MON',
+        symbol: 'MON',
+    },
+    rpcUrls: {
+        default: {
+            http: ['https://rpc.monad.xyz'],
+        },
+    },
+    blockExplorers: {
+        default: {
+            name: 'Monad Explorer',
+            url: 'https://monadvision.com',
+        },
+    },
+    contracts: {
+        multicall3: {
+            address: '0xcA11bde05977b3631167028862bE2a173976CA11',
+            blockCreated: 9248132,
+        },
+    },
+});
+/**
+ * Get the default RPC URL for a given chain ID
+ * @param chainId - The chain ID
+ * @returns The default RPC URL for the chain
+ * @throws Error if chain ID is not supported
+ */
+export function getDefaultRpcUrl(chainId) {
+    switch (chainId) {
+        case ChainId.CELO:
+            return 'https://forno.celo.org';
+        case ChainId.CELO_SEPOLIA:
+            return 'https://forno.celo-sepolia.celo-testnet.org';
+        case ChainId.MONAD_TESTNET:
+            return 'https://testnet-rpc.monad.xyz';
+        case ChainId.MONAD:
+            return 'https://rpc.monad.xyz';
+        default:
+            throw new Error(`Unsupported chain ID: ${chainId}`);
+    }
+}
+/**
+ * Get the viem chain configuration for a given chain ID
+ * @param chainId - The chain ID
+ * @returns The viem chain configuration
+ * @throws Error if chain ID is not supported
+ */
+export function getChainConfig(chainId) {
+    switch (chainId) {
+        case ChainId.CELO:
+            return celo;
+        case ChainId.CELO_SEPOLIA:
+            return celoSepolia;
+        case ChainId.MONAD_TESTNET:
+            return monadTestnet;
+        case ChainId.MONAD:
+            return monad;
+        default:
+            throw new Error(`Unsupported chain ID: ${chainId}`);
+    }
+}

package/dist/esm/utils/costUtils.js

@@ -0,0 +1,56 @@
+import { PoolType } from '../core/types';
+import { FPMM_ABI } from '../core/abis';
+import { VIRTUAL_POOL_ABI } from '../core/abis/virtualPool';
+import { multicall } from './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
+ */
+export async function getPoolCostPercent(pool, publicClient) {
+    if (pool.poolType === PoolType.FPMM) {
+        return getFPMMCostPercent(pool.poolAddr, publicClient);
+    }
+    else if (pool.poolType === 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 multicall(publicClient, [
+        { address: poolAddress, abi: FPMM_ABI, functionName: 'lpFee' },
+        { address: poolAddress, abi: 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 multicall(publicClient, [
+        { address: poolAddress, abi: 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;
+}

package/dist/esm/utils/deadline.js

@@ -0,0 +1,22 @@
+/**
+ * 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 function deadlineFromMinutes(minutes) {
+    return BigInt(Date.now()) / 1000n + BigInt(minutes * 60);
+}

package/dist/esm/utils/index.js

@@ -0,0 +1,9 @@
+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';

package/dist/esm/utils/multicall.js

@@ -0,0 +1,47 @@
+/**
+ * Standard Multicall3 contract address, deployed at the same address on all EVM chains.
+ * https://www.multicall3.com/
+ */
+export const 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.
+ */
+export 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: MULTICALL3_ADDRESS,
+    });
+    const results = raw;
+    if (!allowFailure) {
+        return results.map((result) => ({ status: 'success', result }));
+    }
+    return results;
+}

package/dist/esm/utils/pathEncoder.js

@@ -0,0 +1,69 @@
+/**
+ * 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 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;
+}

package/dist/esm/utils/rateFeed.js

@@ -0,0 +1,23 @@
+import { keccak256, toBytes } from '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
+ * ```
+ */
+export function toRateFeedId(rateFeed) {
+    const hashedBytes = keccak256(toBytes(rateFeed));
+    const hashAsBigInt = BigInt(hashedBytes);
+    const maskedToUint160 = hashAsBigInt & ((1n << 160n) - 1n);
+    return `0x${maskedToUint160.toString(16).padStart(40, '0')}`;
+}

package/dist/esm/utils/retry.js

@@ -0,0 +1,24 @@
+/**
+ * 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 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}`);
+}