@mento-protocol/mento-sdk 0.1.0

package/dist/esm/mento.js

@@ -0,0 +1,218 @@
+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());
+    });
+};
+// SPDX-License-Identifier: GPL-3.0-or-later
+import { Signer, providers } from 'ethers';
+import { IBroker__factory, IExchangeProvider__factory, } from '@mento-protocol/mento-core-ts';
+import { getBrokerAddressFromRegistry, getSymbolFromTokenAddress, increaseAllowance, } from './utils';
+import { strict as assert } from 'assert';
+export class Mento {
+    /**
+     * This constructor is private, use the static create or createWithBrokerAddress methods
+     * to create a new Mento instance
+     * @param brokerAddress the address of the broker contract
+     * @param provider an ethers provider
+     * @param signer an optional ethers signer to execute swaps (must be connected to a provider)
+     */
+    constructor(brokerAddress, signerOrProvider) {
+        this.broker = IBroker__factory.connect(brokerAddress, signerOrProvider);
+        this.signerOrProvider = signerOrProvider;
+        this.exchanges = new Array();
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const isSigner = Signer.isSigner(signerOrProvider);
+            const isProvider = providers.Provider.isProvider(signerOrProvider);
+            if (!isSigner && !isProvider) {
+                throw new Error('A valid signer or provider must be provided');
+            }
+            if (isSigner) {
+                if (!providers.Provider.isProvider(signerOrProvider.provider)) {
+                    throw new Error('Signer must be connected to a provider');
+                }
+            }
+            return new Mento(yield getBrokerAddressFromRegistry(signerOrProvider), signerOrProvider);
+        });
+    }
+    /**
+     * Create a new Mento object instance given a specific broker address
+     * When constructed with only a Provider only read-only operations are supported
+     * @param brokerAddr the address of the broker contract
+     * @param signerOrProvider an ethers signer or provider. A signer is required to execute swaps
+     * @returns a new Mento object instance
+     */
+    static createWithBrokerAddress(brokerAddr, signerOrProvider) {
+        const isSigner = Signer.isSigner(signerOrProvider);
+        const isProvider = providers.Provider.isProvider(signerOrProvider);
+        if (!isSigner && !isProvider) {
+            throw new Error('A valid signer or provider must be provided');
+        }
+        if (isSigner) {
+            if (!providers.Provider.isProvider(signerOrProvider.provider)) {
+                throw new Error('Signer must be connected to a provider');
+            }
+        }
+        return new Mento(brokerAddr, signerOrProvider);
+    }
+    /**
+     * Returns a list of all the pairs that can be traded on Mento
+     * @returns The list of tradeable pairs in the form of [{address, symbol}]
+     */
+    getTradeablePairs() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchanges = yield this.getExchanges();
+            const pairs = [];
+            for (const exchange of exchanges) {
+                const asset0 = exchange.assets[0];
+                const asset1 = exchange.assets[1];
+                const symbols = yield Promise.all([
+                    getSymbolFromTokenAddress(asset0, this.signerOrProvider),
+                    getSymbolFromTokenAddress(asset1, this.signerOrProvider),
+                ]);
+                pairs.push([
+                    { address: asset0, symbol: symbols[0] },
+                    { address: asset1, symbol: symbols[1] },
+                ]);
+            }
+            return pairs;
+        });
+    }
+    /**
+     * Returns the amount of tokenIn to be sold to buy amountOut of tokenOut
+     * @param tokenIn the token to be sold
+     * @param tokenOut the token to be bought
+     * @param amountOut the amount of tokenOut to be bought
+     * @returns the amount of tokenIn to be sold
+     */
+    getAmountIn(tokenIn, tokenOut, amountOut) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
+            return this.broker.getAmountIn(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountOut);
+        });
+    }
+    /**
+     * Returns the amount of tokenOut to be bought by selling amountIn of tokenIn
+     * @param tokenIn the token to be sold
+     * @param tokenOut the token to be bought
+     * @param amountIn the amount of tokenIn to be sold
+     * @returns the amount of tokenOut to be bought
+     */
+    getAmountOut(tokenIn, tokenOut, amountIn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchange = yield this.getExchangeForTokens(tokenIn, tokenOut);
+            return this.broker.getAmountOut(exchange.providerAddr, exchange.id, tokenIn, tokenOut, amountIn);
+        });
+    }
+    /**
+     * 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, 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);
+        });
+    }
+    /**
+     * 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
+     * @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
+     * @returns the populated TransactionRequest object
+     */
+    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);
+        });
+    }
+    /**
+     * 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
+     * @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, 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);
+        });
+    }
+    /**
+     * Returns the list of exchanges available in Mento (cached)
+     * @returns the list of exchanges
+     */
+    getExchanges() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.exchanges.length > 0) {
+                return this.exchanges;
+            }
+            const exchanges = [];
+            const exchangeProvidersAddresses = yield this.broker.getExchangeProviders();
+            for (const exchangeProviderAddr of exchangeProvidersAddresses) {
+                const exchangeManager = IExchangeProvider__factory.connect(exchangeProviderAddr, this.signerOrProvider);
+                const exchangesInManager = yield exchangeManager.getExchanges();
+                for (const exchange of exchangesInManager) {
+                    assert(exchange.assets.length === 2, 'Exchange must have 2 assets');
+                    exchanges.push({
+                        providerAddr: exchangeProviderAddr,
+                        id: exchange.exchangeId,
+                        assets: exchange.assets,
+                    });
+                }
+            }
+            this.exchanges = exchanges;
+            return exchanges;
+        });
+    }
+    /**
+     * Returns the Mento exchange (if any) for a given pair of tokens
+     * @param token0 the first token
+     * @param token1 the second token
+     * @returns
+     */
+    getExchangeForTokens(token0, token1) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchanges = (yield this.getExchanges()).filter((e) => e.assets.includes(token0) && e.assets.includes(token1));
+            if (exchanges.length === 0) {
+                throw Error(`No exchange found for ${token0} and ${token1}`);
+            }
+            assert(exchanges.length === 1, `More than one exchange found for ${token0} and ${token1}`);
+            return exchanges[0];
+        });
+    }
+}

package/dist/esm/utils.d.ts

@@ -0,0 +1,23 @@
+import { BigNumber, Signer, providers } from 'ethers';
+/**
+ * Returns the broker address from the Celo registry
+ * @param signerOrProvider an ethers provider or signer
+ * @returns the broker address
+ */
+export declare function getBrokerAddressFromRegistry(signerOrProvider: Signer | providers.Provider): Promise<Address>;
+/**
+ * Returns the symbol of an erc20 token
+ * @param tokenAddr the address of the erc20 token
+ * @param signerOrProvider an ethers provider or signer
+ * @returns the symbol of the erc20 token
+ */
+export declare function getSymbolFromTokenAddress(tokenAddr: Address, signerOrProvider: Signer | providers.Provider): Promise<string>;
+/**
+ * Returns a populated tx obj for increasing the allowance of a spender for a given erc20 token by a given amount
+ * @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
+ * @returns the populated TransactionRequest object
+ */
+export declare function increaseAllowance(tokenAddr: string, spender: string, amount: BigNumber, signer: Signer): Promise<providers.TransactionRequest>;

package/dist/esm/utils.js

@@ -0,0 +1,61 @@
+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());
+    });
+};
+// SPDX-License-Identifier: GPL-3.0-or-later
+import { Contract, constants } from 'ethers';
+/**
+ * Returns the broker address from the Celo registry
+ * @param signerOrProvider an ethers provider or signer
+ * @returns the broker address
+ */
+export function getBrokerAddressFromRegistry(signerOrProvider) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const celoRegistryAddress = '0x000000000000000000000000000000000000ce10';
+        const brokerIdentifier = 'Broker';
+        const registryAbi = [
+            'function getAddressForString(string calldata identifier) external view returns (address)',
+        ];
+        const contract = new Contract(celoRegistryAddress, registryAbi, signerOrProvider);
+        const brokerAddress = yield contract.getAddressForString(brokerIdentifier);
+        if (brokerAddress === constants.AddressZero) {
+            throw Error('Broker address not found in the registry');
+        }
+        return brokerAddress;
+    });
+}
+/**
+ * Returns the symbol of an erc20 token
+ * @param tokenAddr the address of the erc20 token
+ * @param signerOrProvider an ethers provider or signer
+ * @returns the symbol of the erc20 token
+ */
+export function getSymbolFromTokenAddress(tokenAddr, signerOrProvider) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const erc20Abi = ['function symbol() external view returns (string memory)'];
+        const contract = new Contract(tokenAddr, erc20Abi, signerOrProvider);
+        return contract.symbol();
+    });
+}
+/**
+ * Returns a populated tx obj for increasing the allowance of a spender for a given erc20 token by a given amount
+ * @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
+ * @returns the populated TransactionRequest object
+ */
+export function increaseAllowance(tokenAddr, spender, amount, signer) {
+    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);
+        return yield contract.populateTransaction.increaseAllowance(spender, amount);
+    });
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@mento-protocol/mento-sdk",
+  "description": "Official SDK for interacting with the Mento Protocol",
+  "version": "0.1.0",
+  "license": "GPL-3.0-or-later",
+  "author": "Mento Labs",
+  "keywords": [
+    "mento",
+    "celo",
+    "solidity"
+  ],
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "typings": "dist/esm/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "analyze": "size-limit --why",
+    "build": "yarn build:cjs && yarn build:esm",
+    "build:cjs": "tsc --project ./tsconfig.json",
+    "build:esm": "tsc --project ./tsconfig.esm.json",
+    "lint": "eslint --config ./.eslintrc.json **/*.{json,ts}",
+    "prettier": "prettier --config ./.prettierrc.json --write **/*.{json,md,js,ts,yml}",
+    "size": "size-limit",
+    "test": "jest --runInBand --verbose",
+    "coverage": "jest --coverage"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "yarn lint"
+    }
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/?(*.)+(test).ts"
+    ]
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "size-limit": [
+    {
+      "path": "dist/sdk.cjs.production.min.js",
+      "limit": "10 KB"
+    },
+    {
+      "path": "dist/sdk.esm.js",
+      "limit": "10 KB"
+    }
+  ],
+  "devDependencies": {
+    "@babel/preset-env": "^7.20.2",
+    "@babel/preset-typescript": "^7.18.6",
+    "@size-limit/preset-small-lib": "^8.1.0",
+    "@tsconfig/recommended": "^1.0.1",
+    "@types/jest": "^29.4.0",
+    "@types/node": "^18.13.0",
+    "@typescript-eslint/eslint-plugin": "^5.51.0",
+    "@typescript-eslint/parser": "^5.51.0",
+    "eslint": "^8.33.0",
+    "ethers": "^5.7.2",
+    "husky": "^8.0.2",
+    "jest": "^29.4.2",
+    "prettier": "^2.8.4",
+    "size-limit": "^8.1.0",
+    "ts-jest": "^29.0.5",
+    "typescript": "^4.9.5"
+  },
+  "dependencies": {
+    "@mento-protocol/mento-core-ts": "^0.1.0"
+  },
+  "peerDependencies": {
+    "ethers": "^5.7.2"
+  }
+}