@mento-protocol/mento-sdk 3.2.7 → 3.2.8

package/dist/core/types/borrow.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=borrow.js.map

package/dist/core/types/contractAddresses.d.ts

@@ -0,0 +1,42 @@
+import type { ChainId } from '../constants/chainId';
+/**
+ * All possible contract identifiers across all chains.
+ * Not all chains have all contracts deployed.
+ */
+export type ContractAddresses = {
+    FPMMFactory?: string;
+    VirtualPoolFactory?: string;
+    BreakerBox?: string;
+    MedianDeltaBreaker?: string;
+    SortedOracles?: string;
+    ValueDeltaBreaker?: string;
+    BiPoolManager?: string;
+    Broker?: string;
+    ConstantProductPricingModule?: string;
+    ConstantSumPricingModule?: string;
+    MentoRouter?: string;
+    Reserve?: string;
+    Airgrab?: string;
+    Emission?: string;
+    GovernanceFactory?: string;
+    Locking?: string;
+    MentoGovernor?: string;
+    MentoToken?: string;
+    TimelockController?: string;
+    StableToken?: string;
+    StableTokenEUR?: string;
+    StableTokenBRL?: string;
+    StableTokenXOF?: string;
+    Router?: string;
+    ReserveLiquidityStrategy?: string;
+    CDPLiquidityStrategy?: string;
+    OpenLiquidityStrategy?: string;
+};
+/**
+ * Map of chain IDs to their contract addresses.
+ * Each chain may have a different subset of contracts deployed.
+ */
+export type ContractAddressMap = {
+    [key in ChainId]: ContractAddresses;
+};
+//# sourceMappingURL=contractAddresses.d.ts.map

package/dist/core/types/contractAddresses.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=contractAddresses.js.map

package/dist/core/types/index.d.ts

@@ -0,0 +1,10 @@
+export * from './contractAddresses';
+export * from './transaction';
+export * from './token';
+export * from './route';
+export * from './pool';
+export * from './tradingMode';
+export * from './tradingLimits';
+export * from './liquidity';
+export * from './borrow';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/types/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("./contractAddresses"), exports);
+__exportStar(require("./transaction"), exports);
+__exportStar(require("./token"), exports);
+__exportStar(require("./route"), exports);
+__exportStar(require("./pool"), exports);
+__exportStar(require("./tradingMode"), exports);
+__exportStar(require("./tradingLimits"), exports);
+__exportStar(require("./liquidity"), exports);
+__exportStar(require("./borrow"), exports);
+//# sourceMappingURL=index.js.map

package/dist/core/types/liquidity.d.ts

@@ -0,0 +1,194 @@
+import { CallParams } from './transaction';
+import { LiquidityStrategyDirection } from './pool';
+import { RouterRoute } from '../../utils/pathEncoder';
+export interface LiquidityOptions {
+    slippageTolerance: number;
+    deadline: bigint;
+}
+export interface AddLiquidityQuote {
+    amountA: bigint;
+    amountB: bigint;
+    liquidity: bigint;
+}
+export interface RemoveLiquidityQuote {
+    amount0: bigint;
+    amount1: bigint;
+}
+export interface AddLiquidityDetails {
+    params: CallParams;
+    poolAddress: string;
+    token0: string;
+    token1: string;
+    tokenA: string;
+    tokenB: string;
+    amountADesired: bigint;
+    amountBDesired: bigint;
+    amountAMin: bigint;
+    amountBMin: bigint;
+    estimatedMinLiquidity: bigint;
+    deadline: bigint;
+}
+export interface RemoveLiquidityDetails {
+    params: CallParams;
+    poolAddress: string;
+    token0: string;
+    token1: string;
+    liquidity: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+    expectedAmount0: bigint;
+    expectedAmount1: bigint;
+    deadline: bigint;
+}
+export interface TokenApproval {
+    token: string;
+    amount: bigint;
+    params: CallParams;
+}
+export interface AddLiquidityTransaction {
+    approvalA: TokenApproval | null;
+    approvalB: TokenApproval | null;
+    addLiquidity: AddLiquidityDetails;
+}
+export interface RemoveLiquidityTransaction {
+    approval: TokenApproval | null;
+    removeLiquidity: RemoveLiquidityDetails;
+}
+export interface LPTokenBalance {
+    poolAddress: string;
+    balance: bigint;
+    token0: string;
+    token1: string;
+    totalSupply: bigint;
+    sharePercent: number;
+}
+export interface ZapParams {
+    tokenA: string;
+    tokenB: string;
+    factory: string;
+    amountOutMinA: bigint;
+    amountOutMinB: bigint;
+    amountAMin: bigint;
+    amountBMin: bigint;
+}
+export interface ZapInQuote {
+    amountOutFromA: bigint;
+    amountOutFromB: bigint;
+    amountAMin: bigint;
+    amountBMin: bigint;
+    estimatedMinLiquidity: bigint;
+}
+export interface ZapOutQuote {
+    amountOutFromA: bigint;
+    amountOutFromB: bigint;
+    amountAMin: bigint;
+    amountBMin: bigint;
+    estimatedMinTokenOut: bigint;
+}
+export interface ZapInDetails {
+    params: CallParams;
+    poolAddress: string;
+    tokenIn: string;
+    amountIn: bigint;
+    amountInA: bigint;
+    amountInB: bigint;
+    routesA: RouterRoute[];
+    routesB: RouterRoute[];
+    zapParams: ZapParams;
+    estimatedMinLiquidity: bigint;
+}
+export interface ZapOutDetails {
+    params: CallParams;
+    poolAddress: string;
+    tokenOut: string;
+    liquidity: bigint;
+    routesA: RouterRoute[];
+    routesB: RouterRoute[];
+    zapParams: ZapParams;
+    estimatedMinTokenOut: bigint;
+}
+export interface ZapInTransaction {
+    approval: TokenApproval | null;
+    zapIn: ZapInDetails;
+}
+export interface ZapOutTransaction {
+    approval: TokenApproval | null;
+    zapOut: ZapOutDetails;
+}
+export interface RebalanceDetails {
+    params: CallParams;
+    poolAddress: string;
+    strategyAddress: string;
+    inputToken: string;
+    outputToken: string;
+    amountRequired: bigint;
+    expectedAmountTransferred: bigint;
+    expectedProtocolIncentive: bigint;
+    expectedLiquiditySourceIncentive: bigint;
+    approvalToken: string;
+    approvalSpender: string;
+    approvalAmount: bigint;
+    direction: LiquidityStrategyDirection;
+}
+export interface RebalanceTransaction {
+    approval: TokenApproval | null;
+    rebalance: RebalanceDetails;
+}
+export interface PreparedZapIn {
+    routesA: RouterRoute[];
+    routesB: RouterRoute[];
+    quote: ZapInQuote;
+    approval?: TokenApproval | null;
+    details: ZapInDetails;
+}
+export interface PreparedZapOut {
+    routesA: RouterRoute[];
+    routesB: RouterRoute[];
+    quote: ZapOutQuote;
+    approval?: TokenApproval | null;
+    details: ZapOutDetails;
+}
+/** Input for adding liquidity (without approval handling) */
+export interface AddLiquidityInput {
+    poolAddress: string;
+    tokenA: string;
+    amountA: bigint;
+    tokenB: string;
+    amountB: bigint;
+    recipient: string;
+    options: LiquidityOptions;
+}
+/** Input for removing liquidity (without approval handling) */
+export interface RemoveLiquidityInput {
+    poolAddress: string;
+    liquidity: bigint;
+    recipient: string;
+    options: LiquidityOptions;
+}
+/** Input for zap in (without approval handling) */
+export interface ZapInInput {
+    poolAddress: string;
+    tokenIn: string;
+    amountIn: bigint;
+    amountInSplit: number;
+    recipient: string;
+    options: LiquidityOptions;
+}
+export interface PrepareZapInInput extends ZapInInput {
+    owner?: string;
+}
+/** Input for zap out (without approval handling) */
+export interface ZapOutInput {
+    poolAddress: string;
+    tokenOut: string;
+    liquidity: bigint;
+    recipient: string;
+    options: LiquidityOptions;
+}
+export interface PrepareZapOutInput extends ZapOutInput {
+    owner?: string;
+}
+export interface RebalanceInput {
+    poolAddress: string;
+}
+//# sourceMappingURL=liquidity.d.ts.map

package/dist/core/types/liquidity.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=liquidity.js.map

package/dist/core/types/pool.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Types of liquidity pools supported in the Mento protocol
+ */
+export declare enum PoolType {
+    /** FPMM (Fixed Product Market Maker) pools - v3 native pools */
+    FPMM = "FPMM",
+    /** Virtual pools - wrapper around v2 BiPoolManager exchanges */
+    Virtual = "Virtual"
+}
+/**
+ * Represents a liquidity pool between two tokens in the Mento protocol
+ */
+export interface Pool {
+    /**
+     * The address of the factory contract that was used to deploy this pool
+     */
+    factoryAddr: string;
+    /**
+     * The deployed pool contract address (serves as unique identifier)
+     */
+    poolAddr: string;
+    /**
+     * The address of the first token in the pool
+     */
+    token0: string;
+    /**
+     * The address of the second token in the pool
+     */
+    token1: string;
+    /**
+     * The type of pool (FPMM or Virtual)
+     */
+    poolType: `${PoolType}`;
+    /**
+     * The exchange ID from BiPoolManager (Virtual pools only).
+     */
+    exchangeId?: string;
+}
+/**
+ * Pricing and oracle data for an FPMM pool
+ */
+export interface FPMMPricing {
+    /** Raw oracle price numerator from contract */
+    oraclePriceNum: bigint;
+    /** Raw oracle price denominator from contract */
+    oraclePriceDen: bigint;
+    /** Oracle price as a decimal number (num / den) */
+    oraclePrice: number;
+    /** Raw reserve/pool price numerator from contract */
+    reservePriceNum: bigint;
+    /** Raw reserve/pool price denominator from contract */
+    reservePriceDen: bigint;
+    /** Reserve/pool price as a decimal number (num / den) */
+    reservePrice: number;
+    /** Price difference in basis points (raw from contract) */
+    priceDifferenceBps: bigint;
+    /** Price difference as a percentage (bps / 100, e.g. 12 bps → 0.12%) */
+    priceDifferencePercent: number;
+    /** Whether the reserve/pool price is above the oracle price */
+    reservePriceAboveOraclePrice: boolean;
+}
+/**
+ * Fee configuration for an FPMM pool
+ */
+export interface FPMMFees {
+    /** LP fee in basis points (raw) */
+    lpFeeBps: bigint;
+    /** LP fee as a percentage (e.g. 0.25 = 0.25%) */
+    lpFeePercent: number;
+    /** Protocol fee in basis points (raw) */
+    protocolFeeBps: bigint;
+    /** Protocol fee as a percentage */
+    protocolFeePercent: number;
+    /** Total fee (lpFee + protocolFee) as a percentage */
+    totalFeePercent: number;
+}
+/**
+ * Rebalancing state and configuration for an FPMM pool
+ */
+export interface FPMMRebalancing {
+    /** Rebalance incentive in basis points (raw) */
+    rebalanceIncentiveBps: bigint;
+    /** Rebalance incentive as a percentage */
+    rebalanceIncentivePercent: number;
+    /** Threshold above oracle price in basis points (raw) */
+    rebalanceThresholdAboveBps: bigint;
+    /** Threshold above as a percentage */
+    rebalanceThresholdAbovePercent: number;
+    /** Threshold below oracle price in basis points (raw) */
+    rebalanceThresholdBelowBps: bigint;
+    /** Threshold below as a percentage */
+    rebalanceThresholdBelowPercent: number;
+    /** Whether the current price is within rebalancing thresholds (null when pricing unavailable) */
+    inBand: boolean | null;
+    /** The registered Open Liquidity Strategy address for this pool, or null if none */
+    liquidityStrategy: string | null;
+}
+export type LiquidityStrategyDirection = 'Expand' | 'Contract';
+export interface LiquidityStrategyRebalanceIncentives {
+    liquiditySourceIncentiveExpansion: bigint;
+    protocolIncentiveExpansion: bigint;
+    liquiditySourceIncentiveContraction: bigint;
+    protocolIncentiveContraction: bigint;
+}
+export interface LiquidityStrategyPoolConfig {
+    isToken0Debt: boolean;
+    lastRebalance: number;
+    rebalanceCooldown: number;
+    protocolFeeRecipient: string;
+    liquiditySourceIncentiveExpansion: bigint;
+    protocolIncentiveExpansion: bigint;
+    liquiditySourceIncentiveContraction: bigint;
+    protocolIncentiveContraction: bigint;
+}
+export interface LiquidityStrategyContext {
+    pool: string;
+    reserves: {
+        reserveNum: bigint;
+        reserveDen: bigint;
+    };
+    prices: {
+        oracleNum: bigint;
+        oracleDen: bigint;
+        poolPriceAbove: boolean;
+        rebalanceThreshold: number;
+    };
+    token0: string;
+    token1: string;
+    token0Dec: bigint;
+    token1Dec: bigint;
+    isToken0Debt: boolean;
+    incentives: LiquidityStrategyRebalanceIncentives;
+}
+export interface LiquidityStrategyAction {
+    dir: LiquidityStrategyDirection;
+    amount0Out: bigint;
+    amount1Out: bigint;
+    amountOwedToPool: bigint;
+}
+export interface PoolRebalanceTokenAmount {
+    token: string;
+    amount: bigint;
+}
+export interface PoolRebalancePreview {
+    poolAddress: string;
+    strategyAddress: string;
+    direction: LiquidityStrategyDirection;
+    config: LiquidityStrategyPoolConfig;
+    context: LiquidityStrategyContext;
+    action: LiquidityStrategyAction;
+    inputToken: string;
+    outputToken: string;
+    amountRequired: PoolRebalanceTokenAmount;
+    amountTransferred: PoolRebalanceTokenAmount;
+    protocolIncentive: PoolRebalanceTokenAmount;
+    liquiditySourceIncentive: PoolRebalanceTokenAmount;
+    approvalToken: string;
+    approvalSpender: string;
+    approvalAmount: bigint;
+}
+/**
+ * Enriched details for an FPMM pool including pricing, fees, and rebalancing state
+ */
+export interface FPMMPoolDetails extends Pool {
+    poolType: 'FPMM';
+    /** Scaling factor for token0 (10^tokenDecimals) */
+    scalingFactor0: bigint;
+    /** Scaling factor for token1 (10^tokenDecimals) */
+    scalingFactor1: bigint;
+    /** Reserve of token0 (raw) */
+    reserve0: bigint;
+    /** Reserve of token1 (raw) */
+    reserve1: bigint;
+    /** Block timestamp of last reserve update */
+    blockTimestampLast: bigint;
+    /** Pricing and oracle data (null when FX market is closed) */
+    pricing: FPMMPricing | null;
+    /** Fee configuration */
+    fees: FPMMFees;
+    /** Rebalancing state */
+    rebalancing: FPMMRebalancing;
+}
+/**
+ * Enriched details for a Virtual pool including reserves and spread
+ */
+export interface VirtualPoolDetails extends Pool {
+    poolType: 'Virtual';
+    /** Scaling factor for token0 (10^tokenDecimals) */
+    scalingFactor0: bigint;
+    /** Scaling factor for token1 (10^tokenDecimals) */
+    scalingFactor1: bigint;
+    /** Reserve (bucket) of token0 (raw) */
+    reserve0: bigint;
+    /** Reserve (bucket) of token1 (raw) */
+    reserve1: bigint;
+    /** Block timestamp of last reserve update */
+    blockTimestampLast: bigint;
+    /** Spread/fee in basis points (raw) */
+    spreadBps: bigint;
+    /** Spread as a percentage (e.g. 0.5 = 0.5%) */
+    spreadPercent: number;
+}
+/**
+ * Discriminated union of enriched pool details.
+ * Use `poolType` to narrow the type.
+ */
+export type PoolDetails = FPMMPoolDetails | VirtualPoolDetails;
+//# sourceMappingURL=pool.d.ts.map

package/dist/core/types/pool.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolType = void 0;
+/**
+ * Types of liquidity pools supported in the Mento protocol
+ */
+var PoolType;
+(function (PoolType) {
+    /** FPMM (Fixed Product Market Maker) pools - v3 native pools */
+    PoolType["FPMM"] = "FPMM";
+    /** Virtual pools - wrapper around v2 BiPoolManager exchanges */
+    PoolType["Virtual"] = "Virtual";
+})(PoolType || (exports.PoolType = PoolType = {}));
+//# sourceMappingURL=pool.js.map

package/dist/core/types/provider.d.ts

@@ -0,0 +1,45 @@
+export interface ContractCallOptions {
+    address: string;
+    abi: string[] | unknown[];
+    functionName: string;
+    args?: unknown[];
+}
+/**
+ * Contract write options for building call parameters
+ *
+ * Configuration for building transaction call parameters for write operations.
+ * These parameters can be used by consumers to execute transactions themselves.
+ */
+export interface ContractWriteOptions extends ContractCallOptions {
+    /**
+     * Optional gas limit override
+     * If not provided, will be estimated automatically
+     */
+    gasLimit?: bigint;
+    /**
+     * Transaction value in wei
+     * For payable functions only
+     */
+    value?: bigint;
+}
+/**
+ * Call parameters for executing a contract transaction
+ *
+ * Contains all the data needed to execute a contract call.
+ * Consumers can use these parameters with their own wallet/signer to execute transactions.
+ */
+export interface CallParams {
+    /**
+     * Contract address to call
+     */
+    to: string;
+    /**
+     * Encoded function call data (hex string)
+     */
+    data: string;
+    /**
+     * Transaction value in wei (hex string with 0x prefix)
+     */
+    value: string;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/core/types/provider.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=provider.js.map

package/dist/core/types/route.d.ts

@@ -0,0 +1,62 @@
+import { Pool } from './pool';
+import { RouteToken } from './token';
+/**
+ * Route identifier: sorted symbols joined with hyphen
+ * Represents the two endpoint tokens regardless of the path taken
+ */
+export type RouteID = `${string}-${string}`;
+/**
+ * Represents a tradable route between two tokens, including the pool path needed to execute the trade
+ */
+export interface Route {
+    /**
+     * Canonical identifier: sorted symbols joined with hyphen
+     * Always uses alphabetical order (e.g., 'EURm-USDm' not 'USDm-EURm')
+     * Ensures consistent identification regardless of query direction
+     */
+    id: RouteID;
+    /**
+     * The two tokens being traded, in alphabetical order by symbol
+     * Always [symbolA, symbolB] where symbolA < symbolB alphabetically
+     */
+    tokens: [RouteToken, RouteToken];
+    /**
+     * Array of exchange hops needed to execute the trade
+     * Length 1: Direct route (single pool)
+     * Length 2: Two-hop route via intermediate token through two pools
+     * Order matters for execution
+     */
+    path: Array<Pool>;
+}
+/**
+ * Extended route with cost data for route optimization
+ */
+export interface RouteWithCost extends Route {
+    /**
+     * Cost data for this route
+     * Used to select optimal route when multiple options exist
+     */
+    costData: {
+        /**
+         * Total cost percentage for this route
+         * Lower is better (more cost-efficient)
+         * Example: 0.3 means 0.3% cost
+         */
+        totalCostPercent: number;
+        /**
+         * Per-hop cost breakdown
+         * Used for detailed cost analysis and debugging
+         */
+        hops: Array<{
+            /**
+             * Pool Address for this hop
+             */
+            poolAddress: string;
+            /**
+             * Cost percentage for this specific hop
+             */
+            costPercent: number;
+        }>;
+    };
+}
+//# sourceMappingURL=route.d.ts.map

package/dist/core/types/route.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=route.js.map

package/dist/core/types/token.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Minimal token info for routing purposes.
+ * Contains only the fields needed to identify and route between tokens.
+ */
+export interface RouteToken {
+    address: string;
+    symbol: string;
+}
+/**
+ * Full token info for consumer-facing operations.
+ * Extends RouteToken with display and transaction fields.
+ */
+export interface Token extends RouteToken {
+    name: string;
+    decimals: number;
+}
+export interface StableToken extends Token {
+    totalSupply: string;
+}
+export type CollateralAsset = Token;
+//# sourceMappingURL=token.d.ts.map

package/dist/core/types/token.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=token.js.map