@mento-protocol/mento-sdk 0.1.3 → 0.1.5

package/README.md

@@ -2,72 +2,16 @@
 
 The official Mento Protocol SDK for interacting with Multi-Collateral Mento smart contracts on the Celo network.
 
-# Example Usage
+## Installation
 
-```javascript
-import { Wallet, providers, utils } from 'ethers'
+```sh
+# Install with npm
+npm install @mento-protocol/mento-sdk
 
-import { Mento } from '@mento-protocol/mento-sdk'
-
-async function main() {
-  const provider = new providers.JsonRpcProvider(
-    'https://baklava-forno.celo-testnet.org'
-  )
-  const pKey =
-    'b214fcf9673dc1a880f8041a8c8952c2dc7daff41fb64cf7715919df095c3fce'
-  const wallet = new Wallet(pKey, provider)
-
-  const mento = await Mento.create(wallet)
-  console.log('available pairs: ', await mento.getTradeablePairs())
-  /*
-          [
-        [
-          {
-            address: '0x62492A644A588FD904270BeD06ad52B9abfEA1aE',
-            symbol: 'cUSD'
-          },
-          {
-            address: '0xdDc9bE57f553fe75752D61606B94CBD7e0264eF8',
-            symbol: 'CELO'
-          }
-        ],
-        ...
-      ]
-      */
-
-  // swap 1 CELO for cUSD
-  const one = 1
-  const tokenIn = '0xdDc9bE57f553fe75752D61606B94CBD7e0264eF8' // CELO
-  const tokenOut = '0x62492A644A588FD904270BeD06ad52B9abfEA1aE' // cUSD
-  const amountIn = utils.parseUnits(one.toString(), 18)
-  const expectedAmountOut = await mento.getAmountOut(
-    tokenIn,
-    tokenOut,
-    utils.parseUnits(one.toString(), 18)
-  )
-  // 95% of the quote to allow some slippage
-  const minAmountOut = expectedAmountOut.mul(95).div(100)
-
-  // allow the broker contract to spend CELO on behalf of the wallet
-  const allowanceTxObj = await mento.increaseTradingAllowance(tokenIn, amountIn)
-  const allowanceTx = await wallet.sendTransaction(allowanceTxObj)
-  const allowanceReceipt = await allowanceTx.wait()
-  console.log('increaseAllowance receipt', allowanceReceipt)
-
-  // execute the swap
-  const swapTxObj = await mento.swapIn(
-    tokenIn,
-    tokenOut,
-    amountIn,
-    minAmountOut
-  )
-  const swapTx = await wallet.sendTransaction(swapTxObj)
-  const swapReceipt = await swapTx.wait()
+# Or install with yarn
+yarn add @mento-protocol/mento-sdk
+```
 
-  console.log('swapIn receipt', swapReceipt)
-}
+# Learn more
 
-main()
-  .then(() => console.log('Done'))
-  .catch((e) => console.error('Error:', e))
-```
+You can find example usages of the SDK in the [mento-sdk-examples](https://github.com/mento-protocol/mento-sdk-examples) repository. For in-depth documentation and walk through explanations please see the [SDK section](https://docs.mento.org/mento-protocol/developers/sdk) of the Mento docs.

package/dist/cjs/limits.d.ts

@@ -0,0 +1,33 @@
+import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './types';
+import { Broker } from '@mento-protocol/mento-core-ts';
+/**
+ * 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
+ */
+export declare function getLimitsConfig(broker: Broker, exchangeId: string, asset: Address): Promise<TradingLimitsConfig>;
+/**
+ * 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
+ */
+export declare function getLimitsState(broker: Broker, exchangeId: string, asset: Address): Promise<TradingLimitsState>;
+/**
+ * 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
+ */
+export declare function getLimits(broker: Broker, exchangeId: string, asset: Address): Promise<TradingLimit[]>;
+/**
+ * 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
+ */
+export declare function getLimitId(exchangeId: string, asset: Address): string;

package/dist/cjs/limits.js

@@ -0,0 +1,122 @@
+"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 {
+            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 {
+            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,
+            });
+        }
+        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

@@ -1,6 +1,6 @@
+import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './types';
 import { IBroker } from '@mento-protocol/mento-core-ts';
-import { BigNumber, providers, Signer } from 'ethers';
-import { Address } from './types';
+import { BigNumber, BigNumberish, Signer, providers } from 'ethers';
 export interface Exchange {
     providerAddr: Address;
     id: string;
@@ -56,7 +56,7 @@ export declare class Mento {
      * @param amountOut the amount of tokenOut to be bought
      * @returns the amount of tokenIn to be sold
      */
-    getAmountIn(tokenIn: Address, tokenOut: Address, amountOut: BigNumber): Promise<BigNumber>;
+    getAmountIn(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish): Promise<BigNumber>;
     /**
      * Returns the amount of tokenOut to be bought by selling amountIn of tokenIn
      * @param tokenIn the token to be sold
@@ -64,14 +64,14 @@ export declare class Mento {
      * @param amountIn the amount of tokenIn to be sold
      * @returns the amount of tokenOut to be bought
      */
-    getAmountOut(tokenIn: Address, tokenOut: Address, amountIn: BigNumber): Promise<BigNumber>;
+    getAmountOut(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish): Promise<BigNumber>;
     /**
      * 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(token: Address, amount: BigNumber): Promise<providers.TransactionRequest>;
+    increaseTradingAllowance(token: Address, amount: BigNumberish): Promise<providers.TransactionRequest>;
     /**
      * Returns a token swap populated tx object with a fixed amount of tokenIn and a minimum amount of tokenOut
      * Submitting the transaction to execute the swap is left to the consumer
@@ -81,7 +81,7 @@ export declare class Mento {
      * @param amountOutMin the minimum amount of tokenOut to be bought
      * @returns the populated TransactionRequest object
      */
-    swapIn(tokenIn: Address, tokenOut: Address, amountIn: BigNumber, amountOutMin: BigNumber): Promise<providers.TransactionRequest>;
+    swapIn(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish, amountOutMin: BigNumberish): Promise<providers.TransactionRequest>;
     /**
      * Returns a token swap populated tx object with a maximum amount of tokenIn and a fixed amount of tokenOut
      * Submitting the transaction to execute the swap is left to the consumer
@@ -91,7 +91,7 @@ export declare class Mento {
      * @param amountInMax the maximum amount of tokenIn to be sold
      * @returns the populated TransactionRequest object
      */
-    swapOut(tokenIn: Address, tokenOut: Address, amountOut: BigNumber, amountInMax: BigNumber): Promise<providers.TransactionRequest>;
+    swapOut(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish, amountInMax: BigNumberish): Promise<providers.TransactionRequest>;
     /**
      * Returns the mento instance's broker contract
      * @returns broker contract
@@ -109,9 +109,44 @@ export declare class Mento {
     getExchangesForProvider(exchangeProviderAddr: Address): Promise<Exchange[]>;
     /**
      * Returns the Mento exchange (if any) for a given pair of tokens
-     * @param token0 the first token
-     * @param token1 the second token
+     * @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>;
+    /**
+     * 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 configuration 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>;
 }

package/dist/cjs/mento.js

@@ -13,6 +13,7 @@ exports.Mento = void 0;
 const mento_core_ts_1 = require("@mento-protocol/mento-core-ts");
 const ethers_1 = require("ethers");
 const utils_1 = require("./utils");
+const limits_1 = require("./limits");
 const assert_1 = require("assert");
 class Mento {
     /**
@@ -117,13 +118,15 @@ class Mento {
      */
     increaseTradingAllowance(token, amount) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!ethers_1.Signer.isSigner(this.signerOrProvider)) {
-                throw new Error('A signer is required to populate the increaseAllowance tx object');
-            }
             const spender = this.broker.address;
             const tx = yield (0, utils_1.increaseAllowance)(token, spender, amount, this.signerOrProvider);
-            // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
-            return this.signerOrProvider.populateTransaction(tx);
+            if (ethers_1.Signer.isSigner(this.signerOrProvider)) {
+                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
+                return this.signerOrProvider.populateTransaction(tx);
+            }
+            else {
+                return tx;
+            }
         });
     }
     /**
@@ -137,13 +140,15 @@ class Mento {
      */
     swapIn(tokenIn, tokenOut, amountIn, amountOutMin) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!ethers_1.Signer.isSigner(this.signerOrProvider)) {
-                throw new Error('A signer is required to populate the swapIn tx object');
-            }
             const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
             const tx = yield this.broker.populateTransaction.swapIn(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountIn, amountOutMin);
-            // The broker's call doesn't populate all of the signer fields, so we need an extra call for the signer
-            return this.signerOrProvider.populateTransaction(tx);
+            if (ethers_1.Signer.isSigner(this.signerOrProvider)) {
+                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
+                return this.signerOrProvider.populateTransaction(tx);
+            }
+            else {
+                return tx;
+            }
         });
     }
     /**
@@ -157,13 +162,15 @@ class Mento {
      */
     swapOut(tokenIn, tokenOut, amountOut, amountInMax) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!ethers_1.Signer.isSigner(this.signerOrProvider)) {
-                throw new Error('A signer is required to populate the swapOut tx object');
-            }
             const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
             const tx = yield this.broker.populateTransaction.swapOut(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountOut, amountInMax);
-            // The broker's call doesn't populate all of the signer fields, so we need an extra call for the signer
-            return this.signerOrProvider.populateTransaction(tx);
+            if (ethers_1.Signer.isSigner(this.signerOrProvider)) {
+                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
+                return this.signerOrProvider.populateTransaction(tx);
+            }
+            else {
+                return tx;
+            }
         });
     }
     /**
@@ -208,8 +215,8 @@ class Mento {
     }
     /**
      * Returns the Mento exchange (if any) for a given pair of tokens
-     * @param token0 the first token
-     * @param token1 the second token
+     * @param token0 the address of the first token
+     * @param token1 the address of the second token
      * @returns exchange
      */
     getExchangeForTokens(token0, token1) {
@@ -222,5 +229,83 @@ class Mento {
             return exchanges[0];
         });
     }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchanges = (yield this.getExchanges()).filter((e) => e.id === exchangeId);
+            if (exchanges.length === 0) {
+                throw Error(`No exchange found for id ${exchangeId}`);
+            }
+            (0, assert_1.strict)(exchanges.length === 1, `More than one exchange found with id ${exchangeId}`);
+            return exchanges[0];
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const biPoolManager = mento_core_ts_1.BiPoolManager__factory.connect(exchange.providerAddr, this.signerOrProvider);
+            const [breakerBoxAddr, exchangeConfig] = yield Promise.all([
+                biPoolManager.breakerBox(),
+                biPoolManager.getPoolExchange(exchangeId),
+            ]);
+            const breakerBox = mento_core_ts_1.IBreakerBox__factory.connect(breakerBoxAddr, this.signerOrProvider);
+            const currentMode = yield breakerBox.getRateFeedTradingMode(exchangeConfig.config.referenceRateFeedID);
+            const BI_DIRECTIONAL_TRADING_MODE = 0;
+            return currentMode.toNumber() == BI_DIRECTIONAL_TRADING_MODE;
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const broker = mento_core_ts_1.Broker__factory.connect(this.broker.address, this.signerOrProvider);
+            const assetWithLimit = exchange.assets[0]; // currently limits are configured only on asset0
+            return (0, limits_1.getLimits)(broker, exchangeId, assetWithLimit);
+        });
+    }
+    /**
+     * Returns the trading limits configuration for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @returns the trading limits configuration
+     */
+    getTradingLimitConfig(exchangeId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const broker = mento_core_ts_1.Broker__factory.connect(this.broker.address, this.signerOrProvider);
+            const assetWithLimit = exchange.assets[0]; // currently limits are configured only on asset0
+            return (0, limits_1.getLimitsConfig)(broker, exchangeId, assetWithLimit);
+        });
+    }
+    /**
+     * Returns the trading limits state for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @returns the trading limits state
+     */
+    getTradingLimitState(exchangeId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const broker = mento_core_ts_1.Broker__factory.connect(this.broker.address, this.signerOrProvider);
+            const assetWithLimit = exchange.assets[0]; // currently limits are configured only on asset0
+            return (0, limits_1.getLimitsState)(broker, exchangeId, assetWithLimit);
+        });
+    }
 }
 exports.Mento = Mento;

package/dist/cjs/types.d.ts

@@ -1 +1,22 @@
 export type Address = string;
+export interface TradingLimit {
+    asset: Address;
+    maxIn: number;
+    maxOut: number;
+    until: number;
+}
+export interface TradingLimitsConfig {
+    timestep0: number;
+    timestep1: number;
+    limit0: number;
+    limit1: number;
+    limitGlobal: number;
+    flags: number;
+}
+export interface TradingLimitsState {
+    lastUpdated0: number;
+    lastUpdated1: number;
+    netflow0: number;
+    netflow1: number;
+    netflowGlobal: number;
+}

package/dist/cjs/utils.d.ts

@@ -1,4 +1,4 @@
-import { BigNumber, providers, Signer } from 'ethers';
+import { BigNumberish, providers, Signer } from 'ethers';
 import { Address } from './types';
 /**
  * Ensures that given signer is truly a a connected signer
@@ -30,7 +30,7 @@ export declare function getSymbolFromTokenAddress(tokenAddr: Address, signerOrPr
  * @param tokenAddr the address of the erc20 token
  * @param spender the address of the spender
  * @param amount the amount to increase the allowance by
- * @param signer an ethers signer
+ * @param signerOrProvider an ethers signer or provider
  * @returns the populated TransactionRequest object
  */
-export declare function increaseAllowance(tokenAddr: string, spender: string, amount: BigNumber, signer: Signer): Promise<providers.TransactionRequest>;
+export declare function increaseAllowance(tokenAddr: string, spender: string, amount: BigNumberish, signerOrProvider: Signer | providers.Provider): Promise<providers.TransactionRequest>;

package/dist/cjs/utils.js

@@ -81,15 +81,17 @@ exports.getSymbolFromTokenAddress = getSymbolFromTokenAddress;
  * @param tokenAddr the address of the erc20 token
  * @param spender the address of the spender
  * @param amount the amount to increase the allowance by
- * @param signer an ethers signer
+ * @param signerOrProvider an ethers signer or provider
  * @returns the populated TransactionRequest object
  */
-function increaseAllowance(tokenAddr, spender, amount, signer) {
+function increaseAllowance(tokenAddr, spender, amount, signerOrProvider) {
     return __awaiter(this, void 0, void 0, function* () {
         const abi = [
             'function increaseAllowance(address spender, uint256 value) external returns (bool)',
         ];
-        const contract = new ethers_1.Contract(tokenAddr, abi, signer);
+        // TODO, not all ERC-20 contracts support increaseAllowance
+        // Add a check for that here
+        const contract = new ethers_1.Contract(tokenAddr, abi, signerOrProvider);
         return yield contract.populateTransaction.increaseAllowance(spender, amount);
     });
 }

package/dist/esm/limits.d.ts

@@ -0,0 +1,33 @@
+import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './types';
+import { Broker } from '@mento-protocol/mento-core-ts';
+/**
+ * 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
+ */
+export declare function getLimitsConfig(broker: Broker, exchangeId: string, asset: Address): Promise<TradingLimitsConfig>;
+/**
+ * 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
+ */
+export declare function getLimitsState(broker: Broker, exchangeId: string, asset: Address): Promise<TradingLimitsState>;
+/**
+ * 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
+ */
+export declare function getLimits(broker: Broker, exchangeId: string, asset: Address): Promise<TradingLimit[]>;
+/**
+ * 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
+ */
+export declare function getLimitId(exchangeId: string, asset: Address): string;

package/dist/esm/limits.js

@@ -0,0 +1,115 @@
+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());
+    });
+};
+import { strict as assert } from 'assert';
+import { utils } from '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
+ */
+export 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 {
+            timestep0: cfg['timestep0'],
+            timestep1: cfg['timestep1'],
+            limit0: cfg['limit0'],
+            limit1: cfg['limit1'],
+            limitGlobal: cfg['limitGlobal'],
+            flags: cfg['flags'],
+        };
+    });
+}
+/**
+ * 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
+ */
+export 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 {
+            lastUpdated0: isL0Outdated ? nowEpoch : state['lastUpdated0'],
+            lastUpdated1: isL1Outdated ? nowEpoch : state['lastUpdated1'],
+            netflow0: isL0Outdated ? 0 : state['netflow0'],
+            netflow1: isL1Outdated ? 0 : state['netflow1'],
+            netflowGlobal: state['netflowGlobal'],
+        };
+    });
+}
+/**
+ * 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
+ */
+export 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,
+            });
+        }
+        return limits;
+    });
+}
+/**
+ * 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
+ */
+export function getLimitId(exchangeId, asset) {
+    const assetBytes32 = utils.zeroPad(asset, 32);
+    const exchangeIdBytes = utils.arrayify(exchangeId);
+    const assetBytes = utils.arrayify(assetBytes32);
+    assert(exchangeIdBytes.length === assetBytes.length, 'exchangeId and asset0 must be the same length');
+    return utils.hexlify(exchangeIdBytes.map((b, i) => b ^ assetBytes[i]));
+}

package/dist/esm/mento.d.ts

@@ -1,6 +1,6 @@
+import { Address, TradingLimit, TradingLimitsConfig, TradingLimitsState } from './types';
 import { IBroker } from '@mento-protocol/mento-core-ts';
-import { BigNumber, providers, Signer } from 'ethers';
-import { Address } from './types';
+import { BigNumber, BigNumberish, Signer, providers } from 'ethers';
 export interface Exchange {
     providerAddr: Address;
     id: string;
@@ -56,7 +56,7 @@ export declare class Mento {
      * @param amountOut the amount of tokenOut to be bought
      * @returns the amount of tokenIn to be sold
      */
-    getAmountIn(tokenIn: Address, tokenOut: Address, amountOut: BigNumber): Promise<BigNumber>;
+    getAmountIn(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish): Promise<BigNumber>;
     /**
      * Returns the amount of tokenOut to be bought by selling amountIn of tokenIn
      * @param tokenIn the token to be sold
@@ -64,14 +64,14 @@ export declare class Mento {
      * @param amountIn the amount of tokenIn to be sold
      * @returns the amount of tokenOut to be bought
      */
-    getAmountOut(tokenIn: Address, tokenOut: Address, amountIn: BigNumber): Promise<BigNumber>;
+    getAmountOut(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish): Promise<BigNumber>;
     /**
      * 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(token: Address, amount: BigNumber): Promise<providers.TransactionRequest>;
+    increaseTradingAllowance(token: Address, amount: BigNumberish): Promise<providers.TransactionRequest>;
     /**
      * Returns a token swap populated tx object with a fixed amount of tokenIn and a minimum amount of tokenOut
      * Submitting the transaction to execute the swap is left to the consumer
@@ -81,7 +81,7 @@ export declare class Mento {
      * @param amountOutMin the minimum amount of tokenOut to be bought
      * @returns the populated TransactionRequest object
      */
-    swapIn(tokenIn: Address, tokenOut: Address, amountIn: BigNumber, amountOutMin: BigNumber): Promise<providers.TransactionRequest>;
+    swapIn(tokenIn: Address, tokenOut: Address, amountIn: BigNumberish, amountOutMin: BigNumberish): Promise<providers.TransactionRequest>;
     /**
      * Returns a token swap populated tx object with a maximum amount of tokenIn and a fixed amount of tokenOut
      * Submitting the transaction to execute the swap is left to the consumer
@@ -91,7 +91,7 @@ export declare class Mento {
      * @param amountInMax the maximum amount of tokenIn to be sold
      * @returns the populated TransactionRequest object
      */
-    swapOut(tokenIn: Address, tokenOut: Address, amountOut: BigNumber, amountInMax: BigNumber): Promise<providers.TransactionRequest>;
+    swapOut(tokenIn: Address, tokenOut: Address, amountOut: BigNumberish, amountInMax: BigNumberish): Promise<providers.TransactionRequest>;
     /**
      * Returns the mento instance's broker contract
      * @returns broker contract
@@ -109,9 +109,44 @@ export declare class Mento {
     getExchangesForProvider(exchangeProviderAddr: Address): Promise<Exchange[]>;
     /**
      * Returns the Mento exchange (if any) for a given pair of tokens
-     * @param token0 the first token
-     * @param token1 the second token
+     * @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>;
+    /**
+     * 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 configuration 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>;
 }

package/dist/esm/mento.js

@@ -7,9 +7,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { IBroker__factory, IExchangeProvider__factory, } from '@mento-protocol/mento-core-ts';
+import { BiPoolManager__factory, Broker__factory, IBreakerBox__factory, IBroker__factory, IExchangeProvider__factory, } from '@mento-protocol/mento-core-ts';
 import { Signer } from 'ethers';
 import { getBrokerAddressFromRegistry, getSymbolFromTokenAddress, increaseAllowance, validateSigner, validateSignerOrProvider, } from './utils';
+import { getLimits, getLimitsConfig, getLimitsState } from './limits';
 import { strict as assert } from 'assert';
 export class Mento {
     /**
@@ -114,13 +115,15 @@ export class Mento {
      */
     increaseTradingAllowance(token, amount) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!Signer.isSigner(this.signerOrProvider)) {
-                throw new Error('A signer is required to populate the increaseAllowance tx object');
-            }
             const spender = this.broker.address;
             const tx = yield increaseAllowance(token, spender, amount, this.signerOrProvider);
-            // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
-            return this.signerOrProvider.populateTransaction(tx);
+            if (Signer.isSigner(this.signerOrProvider)) {
+                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
+                return this.signerOrProvider.populateTransaction(tx);
+            }
+            else {
+                return tx;
+            }
         });
     }
     /**
@@ -134,13 +137,15 @@ export class Mento {
      */
     swapIn(tokenIn, tokenOut, amountIn, amountOutMin) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!Signer.isSigner(this.signerOrProvider)) {
-                throw new Error('A signer is required to populate the swapIn tx object');
-            }
             const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
             const tx = yield this.broker.populateTransaction.swapIn(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountIn, amountOutMin);
-            // The broker's call doesn't populate all of the signer fields, so we need an extra call for the signer
-            return this.signerOrProvider.populateTransaction(tx);
+            if (Signer.isSigner(this.signerOrProvider)) {
+                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
+                return this.signerOrProvider.populateTransaction(tx);
+            }
+            else {
+                return tx;
+            }
         });
     }
     /**
@@ -154,13 +159,15 @@ export class Mento {
      */
     swapOut(tokenIn, tokenOut, amountOut, amountInMax) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!Signer.isSigner(this.signerOrProvider)) {
-                throw new Error('A signer is required to populate the swapOut tx object');
-            }
             const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
             const tx = yield this.broker.populateTransaction.swapOut(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountOut, amountInMax);
-            // The broker's call doesn't populate all of the signer fields, so we need an extra call for the signer
-            return this.signerOrProvider.populateTransaction(tx);
+            if (Signer.isSigner(this.signerOrProvider)) {
+                // The contract call doesn't populate all of the signer fields, so we need an extra call for the signer
+                return this.signerOrProvider.populateTransaction(tx);
+            }
+            else {
+                return tx;
+            }
         });
     }
     /**
@@ -205,8 +212,8 @@ export class Mento {
     }
     /**
      * Returns the Mento exchange (if any) for a given pair of tokens
-     * @param token0 the first token
-     * @param token1 the second token
+     * @param token0 the address of the first token
+     * @param token1 the address of the second token
      * @returns exchange
      */
     getExchangeForTokens(token0, token1) {
@@ -219,4 +226,82 @@ export class Mento {
             return exchanges[0];
         });
     }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchanges = (yield this.getExchanges()).filter((e) => e.id === exchangeId);
+            if (exchanges.length === 0) {
+                throw Error(`No exchange found for id ${exchangeId}`);
+            }
+            assert(exchanges.length === 1, `More than one exchange found with id ${exchangeId}`);
+            return exchanges[0];
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const biPoolManager = BiPoolManager__factory.connect(exchange.providerAddr, this.signerOrProvider);
+            const [breakerBoxAddr, exchangeConfig] = yield Promise.all([
+                biPoolManager.breakerBox(),
+                biPoolManager.getPoolExchange(exchangeId),
+            ]);
+            const breakerBox = IBreakerBox__factory.connect(breakerBoxAddr, this.signerOrProvider);
+            const currentMode = yield breakerBox.getRateFeedTradingMode(exchangeConfig.config.referenceRateFeedID);
+            const BI_DIRECTIONAL_TRADING_MODE = 0;
+            return currentMode.toNumber() == BI_DIRECTIONAL_TRADING_MODE;
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const broker = Broker__factory.connect(this.broker.address, this.signerOrProvider);
+            const assetWithLimit = exchange.assets[0]; // currently limits are configured only on asset0
+            return getLimits(broker, exchangeId, assetWithLimit);
+        });
+    }
+    /**
+     * Returns the trading limits configuration for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @returns the trading limits configuration
+     */
+    getTradingLimitConfig(exchangeId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const broker = Broker__factory.connect(this.broker.address, this.signerOrProvider);
+            const assetWithLimit = exchange.assets[0]; // currently limits are configured only on asset0
+            return getLimitsConfig(broker, exchangeId, assetWithLimit);
+        });
+    }
+    /**
+     * Returns the trading limits state for a given exchange id
+     * @param exchangeId the id of the exchange
+     * @returns the trading limits state
+     */
+    getTradingLimitState(exchangeId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeById(exchangeId);
+            const broker = Broker__factory.connect(this.broker.address, this.signerOrProvider);
+            const assetWithLimit = exchange.assets[0]; // currently limits are configured only on asset0
+            return getLimitsState(broker, exchangeId, assetWithLimit);
+        });
+    }
 }

package/dist/esm/types.d.ts

@@ -1 +1,22 @@
 export type Address = string;
+export interface TradingLimit {
+    asset: Address;
+    maxIn: number;
+    maxOut: number;
+    until: number;
+}
+export interface TradingLimitsConfig {
+    timestep0: number;
+    timestep1: number;
+    limit0: number;
+    limit1: number;
+    limitGlobal: number;
+    flags: number;
+}
+export interface TradingLimitsState {
+    lastUpdated0: number;
+    lastUpdated1: number;
+    netflow0: number;
+    netflow1: number;
+    netflowGlobal: number;
+}

package/dist/esm/utils.d.ts

@@ -1,4 +1,4 @@
-import { BigNumber, providers, Signer } from 'ethers';
+import { BigNumberish, providers, Signer } from 'ethers';
 import { Address } from './types';
 /**
  * Ensures that given signer is truly a a connected signer
@@ -30,7 +30,7 @@ export declare function getSymbolFromTokenAddress(tokenAddr: Address, signerOrPr
  * @param tokenAddr the address of the erc20 token
  * @param spender the address of the spender
  * @param amount the amount to increase the allowance by
- * @param signer an ethers signer
+ * @param signerOrProvider an ethers signer or provider
  * @returns the populated TransactionRequest object
  */
-export declare function increaseAllowance(tokenAddr: string, spender: string, amount: BigNumber, signer: Signer): Promise<providers.TransactionRequest>;
+export declare function increaseAllowance(tokenAddr: string, spender: string, amount: BigNumberish, signerOrProvider: Signer | providers.Provider): Promise<providers.TransactionRequest>;

package/dist/esm/utils.js

@@ -74,15 +74,17 @@ export function getSymbolFromTokenAddress(tokenAddr, signerOrProvider) {
  * @param tokenAddr the address of the erc20 token
  * @param spender the address of the spender
  * @param amount the amount to increase the allowance by
- * @param signer an ethers signer
+ * @param signerOrProvider an ethers signer or provider
  * @returns the populated TransactionRequest object
  */
-export function increaseAllowance(tokenAddr, spender, amount, signer) {
+export function increaseAllowance(tokenAddr, spender, amount, signerOrProvider) {
     return __awaiter(this, void 0, void 0, function* () {
         const abi = [
             'function increaseAllowance(address spender, uint256 value) external returns (bool)',
         ];
-        const contract = new Contract(tokenAddr, abi, signer);
+        // TODO, not all ERC-20 contracts support increaseAllowance
+        // Add a check for that here
+        const contract = new Contract(tokenAddr, abi, signerOrProvider);
         return yield contract.populateTransaction.increaseAllowance(spender, amount);
     });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mento-protocol/mento-sdk",
   "description": "Official SDK for interacting with the Mento Protocol",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "license": "MIT",
   "author": "Mento Labs",
   "keywords": [
@@ -77,10 +77,10 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "@mento-protocol/mento-core-ts": "^0.1.0"
+    "@mento-protocol/mento-core-ts": "^0.1.1"
   },
   "peerDependencies": {
-    "ethers": "^5.7.2"
+    "ethers": "^5.7"
   },
   "packageManager": "yarn@3.3.1"
 }