@mento-protocol/mento-sdk 1.18.0 → 1.19.0

package/dist/cjs/limits.js

@@ -0,0 +1,130 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLimitId = exports.getLimits = exports.getLimitsState = exports.getLimitsConfig = void 0;
+const assert_1 = require("assert");
+const ethers_1 = require("ethers");
+/**
+ * Returns the limit configuration in the broker for the given exchange and asset
+ * @param broker an instance of the broker
+ * @param exchangeId the id of the exchange
+ * @param asset the address of the limited asset
+ * @returns the limit configuration
+ */
+function getLimitsConfig(broker, exchangeId, asset) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const limitId = getLimitId(exchangeId, asset);
+        const cfg = yield broker.tradingLimitsConfig(limitId);
+        return {
+            asset,
+            timestep0: cfg['timestep0'],
+            timestep1: cfg['timestep1'],
+            limit0: cfg['limit0'],
+            limit1: cfg['limit1'],
+            limitGlobal: cfg['limitGlobal'],
+            flags: cfg['flags'],
+        };
+    });
+}
+exports.getLimitsConfig = getLimitsConfig;
+/**
+ * Returns the limit state in the broker for the given exchange and asset
+ * @param broker an instance of the broker
+ * @param exchangeId the id of the exchange
+ * @param asset the address of the limited asset
+ * @returns the limit state
+ */
+function getLimitsState(broker, exchangeId, asset) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const limitId = getLimitId(exchangeId, asset);
+        const [cfg, state] = yield Promise.all([
+            getLimitsConfig(broker, exchangeId, asset),
+            broker.tradingLimitsState(limitId),
+        ]);
+        const isL0Enabled = cfg.timestep0 > 0;
+        const isL1Enabled = cfg.timestep1 > 0;
+        const nowEpoch = Math.floor(Date.now() / 1000);
+        const isL0Outdated = isL0Enabled && nowEpoch > state['lastUpdated0'] + cfg.timestep0;
+        const isL1Outdated = isL1Enabled && nowEpoch > state['lastUpdated1'] + cfg.timestep1;
+        return {
+            asset,
+            lastUpdated0: isL0Outdated ? nowEpoch : state['lastUpdated0'],
+            lastUpdated1: isL1Outdated ? nowEpoch : state['lastUpdated1'],
+            netflow0: isL0Outdated ? 0 : state['netflow0'],
+            netflow1: isL1Outdated ? 0 : state['netflow1'],
+            netflowGlobal: state['netflowGlobal'],
+        };
+    });
+}
+exports.getLimitsState = getLimitsState;
+/**
+ * Returns a human-friendly representation of the limits for the given exchange and asset
+ * @param broker an instance of the broker
+ * @param exchangeId the id of the exchange
+ * @param asset the address of the asset with the limit
+ * @returns a list of TradingLimit objects
+ */
+function getLimits(broker, exchangeId, asset) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const [cfg, state] = yield Promise.all([
+            getLimitsConfig(broker, exchangeId, asset),
+            getLimitsState(broker, exchangeId, asset),
+        ]);
+        const limits = [];
+        if (cfg.limit0 > 0) {
+            limits.push({
+                asset: asset,
+                maxIn: cfg.limit0 - state.netflow0,
+                maxOut: cfg.limit0 + state.netflow0,
+                until: state.lastUpdated0 + cfg.timestep0,
+            });
+        }
+        if (cfg.limit1 > 0) {
+            limits.push({
+                asset: asset,
+                maxIn: cfg.limit1 - state.netflow1,
+                maxOut: cfg.limit1 + state.netflow1,
+                until: state.lastUpdated1 + cfg.timestep1,
+            });
+        }
+        if (cfg.limitGlobal > 0) {
+            const timestampIn2030 = 1893456000; // a far away timestamp
+            limits.push({
+                asset: asset,
+                maxIn: cfg.limitGlobal - state.netflowGlobal,
+                maxOut: cfg.limitGlobal + state.netflowGlobal,
+                until: timestampIn2030,
+            });
+        }
+        // Limits with a smaller timeframe are restricted by the ones with a larger one
+        // e.g: if maxIn is 0 in LG, it should also be 0 in L1 and L0
+        for (let i = limits.length - 1; i > 0; i--) {
+            limits[i - 1].maxIn = Math.min(limits[i - 1].maxIn, limits[i].maxIn);
+            limits[i - 1].maxOut = Math.min(limits[i - 1].maxOut, limits[i].maxOut);
+        }
+        return limits;
+    });
+}
+exports.getLimits = getLimits;
+/**
+ * Returns the limit id for the given exchange and asset
+ * @param exchangeId the id of the exchange
+ * @param asset the address of the asset with the limit
+ * @returns the limit id
+ */
+function getLimitId(exchangeId, asset) {
+    const assetBytes32 = ethers_1.utils.zeroPad(asset, 32);
+    const exchangeIdBytes = ethers_1.utils.arrayify(exchangeId);
+    const assetBytes = ethers_1.utils.arrayify(assetBytes32);
+    (0, assert_1.strict)(exchangeIdBytes.length === assetBytes.length, 'exchangeId and asset0 must be the same length');
+    return ethers_1.utils.hexlify(exchangeIdBytes.map((b, i) => b ^ assetBytes[i]));
+}
+exports.getLimitId = getLimitId;

package/dist/cjs/mento.d.ts

@@ -0,0 +1,287 @@
+import { IBroker } from '@mento-protocol/mento-core-ts';
+import { BigNumber, BigNumberish, providers, Signer } from 'ethers';
+import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './interfaces';
+import { Identifier } from './constants/addresses';
+import { TokenSymbol } from './constants/tokens';
+import { TradablePairWithSpread } from './constants/tradablePairs';
+import { TradingMode } from './enums';
+export { TokenSymbol } from './constants/tokens';
+export interface Exchange {
+    providerAddr: Address;
+    id: string;
+    assets: Address[];
+}
+export interface Asset {
+    address: Address;
+    symbol: string;
+}
+export interface Token {
+    address: Address;
+    symbol: TokenSymbol;
+    name: string;
+    decimals: number;
+}
+export type TradablePairID = `${Address}-${Address}`;
+export interface TradablePair {
+    id: TradablePairID;
+    assets: [Asset, Asset];
+    path: Array<{
+        providerAddr: Address;
+        id: string;
+        assets: [Address, Address];
+    }>;
+}
+export declare class Mento {
+    private readonly signerOrProvider;
+    private readonly broker;
+    private readonly router;
+    private exchanges;
+    private cachedChainId;
+    /**
+     * This constructor is private, use the static create or createWithParams methods
+     * to create a new Mento instance
+     * @param signerOrProvider an ethers provider or connected signer
+     * @param brokerAddress the address of the broker contract
+     * @param exchanges exchange data for the broker
+     */
+    private constructor();
+    /**
+     * Creates a new Mento object instance.
+     * When constructed with only a Provider only read-only operations are supported
+     * @param signerOrProvider an ethers signer or provider. A signer is required to execute swaps
+     * @returns a new Mento object instance
+     */
+    static create(signerOrProvider: Signer | providers.Provider): Promise<Mento>;
+    /**
+     * Create a new Mento object instance given a broker address and optional exchanges data
+     * When constructed with a Provider, only read-only operations are supported
+     * @param signerOrProvider an ethers signer or provider. A signer is required to execute swaps
+     * @param brokerAddr the address of the broker contract
+     * @param exchanges the exchanges data for the broker
+     * @returns a new Mento object instance
+     */
+    static createWithParams(signerOrProvider: Signer | providers.Provider, brokerAddr: Address, routerAddr: Address, exchanges?: Exchange[]): Mento;
+    /**
+     * Returns a new Mento instance connected to the given signer
+     * @param signer an ethers signer
+     * @returns new Mento object instance
+     */
+    connectSigner(signer: Signer): Mento;
+    /**
+     * Get tradable pairs for backwards compatibility
+     * @returns an array of Asset pairs
+     */
+    getTradablePairs({ cached, }?: {
+        cached?: boolean;
+    }): Promise<[Asset, Asset][]>;
+    /**
+     * Returns a list of all tradable pairs on Mento via direct exchanges.
+     * Each pair is represented using the TradablePair interface, with its id
+     * (a concatenation of the two asset symbols in alphabetical order),
+     * the two Asset objects, and a path (an array with a single direct exchange hop).
+     * @returns An array of direct TradablePair objects.
+     */
+    getDirectPairs(): Promise<TradablePair[]>;
+    /**
+     * Returns a list of all tradable pairs on Mento, including those achievable
+     * via two-hop routes. For two-hop pairs, the path will contain two exchange hops.
+     * Each TradablePair contains an id (the concatenation of the two asset symbols in alphabetical order),
+     * the two Asset objects, and an array of exchange details for each hop.
+     * @param options - Optional parameters
+     * @param options.cached - Whether to use cached data (default: true)
+     * @param options.returnAllRoutes - Whether to return all possible routes or just the best one per pair (default: false)
+     * @returns An array of TradablePair objects representing available trade routes.
+     */
+    getTradablePairsWithPath({ cached, returnAllRoutes, }?: {
+        cached?: boolean;
+        returnAllRoutes?: boolean;
+    }): Promise<readonly (TradablePair | TradablePairWithSpread)[]>;
+    /**
+     * Attempts to get cached tradable pairs for the current chain
+     */
+    private getCachedTradablePairs;
+    /**
+     * Returns a list of all unique tokens available on the current chain.
+     * This method is synchronous and uses pre-cached token data.
+     * For runtime fetching from the blockchain, use getTokensAsync().
+     *
+     * @returns An array of unique Token objects from the static cache.
+     * @throws Error if no cached tokens are available for the current chain or if chainId is not yet initialized
+     */
+    getTokens(): Token[];
+    /**
+     * Fetches token metadata from the blockchain at runtime.
+     * This method is async and makes blockchain calls to get fresh token data.
+     * For synchronous access using cached data, use getTokens().
+     *
+     * @param options - Optional parameters
+     * @param options.cached - Whether to use cached data (default: true).
+     *                         If true, attempts to load from static cache first.
+     * @returns A Promise resolving to an array of unique Token objects.
+     */
+    getTokensAsync({ cached, }?: {
+        cached?: boolean;
+    }): Promise<Token[]>;
+    /**
+     * Returns the amount of tokenIn to be sold to buy amountOut of tokenOut.
+     * If the provided tradablePair has a single (direct) pricing path, then direct pricing is used.
+     * Otherwise, routed pricing via the MentoRouter is applied.
+     * @param tokenIn the token to be sold
+     * @param tokenOut the token to be bought
+     * @param amountOut the desired amount of tokenOut to be obtained
+     * @param tradablePair the TradablePair object containing the pricing path information
+     * @returns the amount of tokenIn to be sold
+     */
+    getAmountIn(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish, tradablePair?: TradablePair): Promise<BigNumber>;
+    /**
+     * Returns the amount of tokenOut to be bought by selling amountIn of tokenIn.
+     * If the provided tradablePair has a single (direct) pricing path, then direct pricing is used.
+     * Otherwise, routed pricing via the MentoRouter is applied.
+     * @param tokenIn the token to be sold
+     * @param tokenOut the token to be bought
+     * @param amountIn the amount of tokenIn to be sold
+     * @param tradablePair the TradablePair object containing the pricing path information
+     * @returns the amount of tokenOut to be bought
+     */
+    getAmountOut(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish, tradablePair?: TradablePair): Promise<BigNumber>;
+    /**
+     * Internal method for direct pricing: retrieves the exchange for the given tokens
+     * and returns the amountIn using the broker.
+     */
+    private getAmountInDirect;
+    /**
+     * Internal method for direct pricing: retrieves the exchange for the given tokens
+     * and returns the amountOut using the broker.
+     */
+    private getAmountOutDirect;
+    /**
+     * Internal method for routed pricing: uses the MentoRouter to determine the required tokenIn
+     * for obtaining amountOut through a multi-hop route specified in tradablePair.path.
+     */
+    private getAmountInRouted;
+    /**
+     * Internal method for routed pricing: uses the MentoRouter to determine the amountOut
+     * obtainable by selling amountIn through a multi-hop route specified in tradablePair.path.
+     */
+    private getAmountOutRouted;
+    /**
+     * Increases the broker's trading allowance for the given token
+     * @param token the token to increase the allowance for
+     * @param amount the amount to increase the allowance by
+     * @returns the populated TransactionRequest object
+     */
+    increaseTradingAllowance(tokenIn: Address, amount: BigNumberish, tradablePair?: TradablePair): Promise<providers.TransactionRequest>;
+    /**
+     * Returns a token swap populated tx object with a fixed amount of tokenIn and a minimum amount of tokenOut.
+     * If the tradablePair contains a single-hop route, a direct swap is executed using swapExactTokensForTokens on the broker.
+     * Otherwise, a routed swap is executed via the router.
+     * @param tokenIn the token to be sold
+     * @param tokenOut the token to be bought
+     * @param amountIn the amount of tokenIn to be sold
+     * @param amountOutMin the minimum amount of tokenOut to be bought
+     * @param tradablePair the tradable pair details to determine routing
+     * @returns the populated TransactionRequest object
+     */
+    swapIn(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish, amountOutMin: BigNumberish, tradablePair?: TradablePair): Promise<providers.TransactionRequest>;
+    private swapInDirect;
+    private swapInRouted;
+    /**
+     * Returns a token swap populated tx object with a maximum amount of tokenIn and a fixed amount of tokenOut.
+     * If the tradablePair contains a single-hop route, a direct swap is executed using swapTokensForExactTokens on the broker.
+     * Otherwise, a routed swap is executed via the router.
+     * @param tokenIn the token to be sold
+     * @param tokenOut the token to be bought
+     * @param amountOut the amount of tokenOut to be bought
+     * @param amountInMax the maximum amount of tokenIn to be sold
+     * @returns the populated TransactionRequest object
+     */
+    swapOut(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish, amountInMax: BigNumberish, tradablePair?: TradablePair): Promise<providers.TransactionRequest>;
+    private swapOutDirect;
+    private swapOutRouted;
+    /**
+     * Helper method to build the steps for a routed swap, ensuring proper token ordering
+     * through the path segments
+     */
+    private buildSteps;
+    /**
+     * Returns the mento instance's broker contract
+     * @returns broker contract
+     */
+    getBroker(): IBroker;
+    /**
+     * Finds a tradable pair for the given input and output tokens
+     * @param tokenIn the input token address
+     * @param tokenOut the output token address
+     * @returns the tradable pair containing the path between the tokens
+     * @throws if no path is found between the tokens
+     */
+    findPairForTokens(tokenIn: Address, tokenOut: Address): Promise<TradablePair>;
+    /**
+     * Returns the list of exchanges available in Mento (cached)
+     * @returns the list of exchanges
+     */
+    getExchanges(): Promise<Exchange[]>;
+    /**
+     * Returns the list of exchanges for a given exchange provider address
+     * @returns list of exchanges
+     */
+    getExchangesForProvider(exchangeProviderAddr: Address): Promise<Exchange[]>;
+    /**
+     * Returns the Mento exchange (if any) for a given pair of tokens
+     * @param token0 the address of the first token
+     * @param token1 the address of the second token
+     * @returns exchange
+     */
+    getExchangeForTokens(token0: Address, token1: Address): Promise<Exchange>;
+    /**
+     * Returns the Mento exchange for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @returns the exchange with the given id
+     */
+    getExchangeById(exchangeId: string): Promise<Exchange>;
+    /**
+     * Returns whether trading is enabled in the given mode for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @param mode the trading mode
+     * @returns true if trading is enabled in the given mode, false otherwise
+     */
+    isTradingEnabled(exchangeId: string): Promise<boolean>;
+    /**
+     * Returns the current trading mode for a given rate feed
+     * @param rateFeedId the address of the rate feed
+     * @returns the current trading mode (BIDIRECTIONAL, HALTED, or DISABLED)
+     */
+    getRateFeedTradingMode(rateFeedId: Address): Promise<TradingMode>;
+    /**
+     * Checks if a trading pair is currently tradable (i.e., all rate feeds in the path are in BIDIRECTIONAL mode)
+     * For multi-hop routes (e.g., CELO → USDm → USDT), checks that all intermediate rate feeds are tradable
+     * @param tokenIn the address of the token to sell
+     * @param tokenOut the address of the token to buy
+     * @returns true if the pair is tradable (all rate feeds in BIDIRECTIONAL mode), false otherwise
+     */
+    isPairTradable(tokenIn: Address, tokenOut: Address): Promise<boolean>;
+    /**
+     * Return the trading limits for a given exchange id. Each limit is an object with the following fields:
+     * asset: the address of the asset with the limit
+     * maxIn: the maximum amount of the asset that can be sold
+     * maxOut: the maximum amount of the asset that can be bought
+     * until: the timestamp until which the limit is valid
+     * @param exchangeId the id of the exchange
+     * @returns the list of trading limits
+     */
+    getTradingLimits(exchangeId: string): Promise<TradingLimit[]>;
+    /**
+     * Returns the trading limits configurations for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @returns the trading limits configuration
+     */
+    getTradingLimitConfig(exchangeId: string): Promise<TradingLimitsConfig[]>;
+    /**
+     * Returns the trading limits state for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @returns the trading limits state
+     */
+    getTradingLimitState(exchangeId: string): Promise<TradingLimitsState[]>;
+    getAddress(identifier: Identifier): Promise<Address>;
+    chainId(): Promise<number>;
+}