@mento-protocol/mento-sdk 1.0.9 → 1.10.0

package/README.md

@@ -12,6 +12,10 @@ npm install @mento-protocol/mento-sdk
 yarn add @mento-protocol/mento-sdk
 ```
 
+## Learn more
+
+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/developers/mento-sdk) of the Mento docs.
+
 ## Tradable Pairs Cache
 
 Anytime we launch a new stable token, we need to update the tradable pairs cache.
@@ -22,6 +26,42 @@ The `yarn cacheTradablePairs` script generates a TypeScript file containing a li
 yarn cacheTradablePairs
 ```
 
-## Learn more
+## Token Graph Visualization
 
-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/developers/mento-sdk) of the Mento docs.
+Current token connectivity on Celo Mainnet (last updated: 2025-06-19):
+
+```mermaid
+graph TD
+    USDT["USD₮"]
+    USDC --- cUSD
+    USDT --- cUSD
+    CELO --- cEUR
+    CELO --- cREAL
+    USDC --- cREAL
+    USDC --- cEUR
+    axlUSDC --- cUSD
+    CELO --- cUSD
+    PUSO --- cUSD
+    cJPY --- cUSD
+    cCOP --- cUSD
+    cGBP --- cUSD
+    cUSD --- cZAR
+    cCAD --- cUSD
+    cAUD --- cUSD
+    cCHF --- cUSD
+    axlUSDC --- cEUR
+    axlUSDC --- cREAL
+    axlEUROC --- cEUR
+    cKES --- cUSD
+    cGHS --- cUSD
+    cNGN --- cUSD
+    CELO --- eXOF
+    axlEUROC --- eXOF
+
+```
+
+**Network Stats:** 20 tokens, 24 direct trading pairs
+
+> 💡 This graph shows direct trading pairs only. The SDK automatically finds optimal routes including multi-hop paths.
+>
+> To regenerate: `yarn getTokenGraph`

package/dist/cjs/scripts/cacheTradablePairs/config.d.ts

@@ -0,0 +1,5 @@
+import { TradablePairWithSpread } from '../../src/constants/tradablePairs';
+import { NETWORK_MAP, rpcUrls, SupportedChainId } from '../shared/network';
+export { NETWORK_MAP, rpcUrls };
+export { TradablePairWithSpread };
+export type { SupportedChainId };

package/dist/cjs/scripts/cacheTradablePairs/config.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rpcUrls = exports.NETWORK_MAP = void 0;
+const network_1 = require("../shared/network");
+Object.defineProperty(exports, "NETWORK_MAP", { enumerable: true, get: function () { return network_1.NETWORK_MAP; } });
+Object.defineProperty(exports, "rpcUrls", { enumerable: true, get: function () { return network_1.rpcUrls; } });

package/dist/cjs/scripts/quotes/config.d.ts

@@ -0,0 +1,20 @@
+export declare const RPC_URLS: Record<number, string>;
+export declare const CHAIN_NAMES: Record<number, string>;
+export declare const CHAIN_NAME_TO_ID: Record<string, number>;
+export declare const DEFAULT_CHAIN_ID = 42220;
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const QUOTE_TIMEOUT_MS = 8000;
+export declare const DEFAULT_BATCH_SIZE = 10;
+export declare const DEFAULT_BATCH_DELAY_MS = 100;
+export declare const DEFAULT_SPREAD_FALLBACK = 0.25;
+export declare const MAX_DECIMAL_PLACES = 4;
+export declare const TOKEN_ABI_FRAGMENT: readonly [{
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}];
+export declare const DEFAULT_DECIMALS = 18;

package/dist/cjs/scripts/quotes/config.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DECIMALS = exports.TOKEN_ABI_FRAGMENT = exports.MAX_DECIMAL_PLACES = exports.DEFAULT_SPREAD_FALLBACK = exports.DEFAULT_BATCH_DELAY_MS = exports.DEFAULT_BATCH_SIZE = exports.QUOTE_TIMEOUT_MS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_CHAIN_ID = exports.CHAIN_NAME_TO_ID = exports.CHAIN_NAMES = exports.RPC_URLS = void 0;
+exports.RPC_URLS = {
+    42220: 'https://forno.celo.org',
+    44787: 'https://alfajores-forno.celo-testnet.org',
+};
+exports.CHAIN_NAMES = {
+    42220: 'Celo',
+    44787: 'Alfajores',
+};
+exports.CHAIN_NAME_TO_ID = {
+    celo: 42220,
+    alfajores: 44787,
+};
+exports.DEFAULT_CHAIN_ID = 42220;
+exports.DEFAULT_TIMEOUT_MS = 10000;
+exports.QUOTE_TIMEOUT_MS = 8000; // Timeout for individual quote calculations
+exports.DEFAULT_BATCH_SIZE = 10;
+exports.DEFAULT_BATCH_DELAY_MS = 100;
+exports.DEFAULT_SPREAD_FALLBACK = 0.25;
+exports.MAX_DECIMAL_PLACES = 4;
+// ERC20 token ABI fragment for decimals
+exports.TOKEN_ABI_FRAGMENT = [
+    {
+        name: 'decimals',
+        type: 'function',
+        inputs: [],
+        outputs: [{ type: 'uint8' }],
+        stateMutability: 'view',
+    },
+];
+exports.DEFAULT_DECIMALS = 18;

package/dist/cjs/scripts/quotes/spread.d.ts

@@ -0,0 +1,25 @@
+import { TradablePair } from '../../src/mento';
+import { TradablePairWithSpread } from '../cacheTradablePairs/config';
+/**
+ * Calculates the total spread for a trading route by compounding spreads across all hops.
+ *
+ * For multi-hop routes, spreads compound multiplicatively:
+ * - Single hop: spread = pairSpread
+ * - Multi-hop: spread = (1 - ((1 - spread1) * (1 - spread2) * ...))
+ *
+ * @param route - The route to calculate spread for
+ * @param allPairs - All available pairs with spread data
+ * @returns Total spread as a decimal (e.g., 0.005 = 0.5%)
+ */
+export declare function calculateCompoundSpread(route: TradablePair, allPairs: readonly TradablePair[] | readonly TradablePairWithSpread[]): number;
+/**
+ * Creates a human-readable display string for a trading route.
+ * Shows token symbols and route structure (e.g., "USDC → cUSD → cEUR").
+ *
+ * @param tradablePair - The route to display
+ * @param fromSymbol - Symbol of the input token
+ * @param toSymbol - Symbol of the output token
+ * @param allPairs - All pairs data for symbol resolution
+ * @returns Formatted route string
+ */
+export declare function buildRouteDisplay(tradablePair: TradablePair, fromSymbol: string, toSymbol: string, allPairs: readonly TradablePair[] | readonly TradablePairWithSpread[]): string;

package/dist/cjs/scripts/quotes/spread.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRouteDisplay = exports.calculateCompoundSpread = void 0;
+const config_1 = require("./config");
+/**
+ * Calculates the total spread for a trading route by compounding spreads across all hops.
+ *
+ * For multi-hop routes, spreads compound multiplicatively:
+ * - Single hop: spread = pairSpread
+ * - Multi-hop: spread = (1 - ((1 - spread1) * (1 - spread2) * ...))
+ *
+ * @param route - The route to calculate spread for
+ * @param allPairs - All available pairs with spread data
+ * @returns Total spread as a decimal (e.g., 0.005 = 0.5%)
+ */
+function calculateCompoundSpread(route, allPairs) {
+    if (route.path.length === 1) {
+        return getFixedSpreadForRoute(route, allPairs);
+    }
+    // For multi-hop routes, calculate compound spread
+    let compoundRate = 1; // Start with 100% (no loss)
+    for (const hop of route.path) {
+        const hopSpreadPercent = getHopSpreadPercent(hop, allPairs);
+        // Convert spread percentage to rate multiplier
+        // If spread is 0.25%, rate multiplier is 0.9975 (1 - 0.0025)
+        const hopRate = 1 - hopSpreadPercent / 100;
+        compoundRate *= hopRate;
+    }
+    // Convert back to spread percentage
+    return (1 - compoundRate) * 100;
+}
+exports.calculateCompoundSpread = calculateCompoundSpread;
+/**
+ * Creates a human-readable display string for a trading route.
+ * Shows token symbols and route structure (e.g., "USDC → cUSD → cEUR").
+ *
+ * @param tradablePair - The route to display
+ * @param fromSymbol - Symbol of the input token
+ * @param toSymbol - Symbol of the output token
+ * @param allPairs - All pairs data for symbol resolution
+ * @returns Formatted route string
+ */
+function buildRouteDisplay(tradablePair, fromSymbol, toSymbol, allPairs) {
+    if (tradablePair.path.length === 1) {
+        return `${fromSymbol} → ${toSymbol}`;
+    }
+    const routeSymbols = buildRouteSymbols(tradablePair, fromSymbol, toSymbol, allPairs);
+    return routeSymbols.length < tradablePair.path.length + 1
+        ? `${fromSymbol} → ${toSymbol} (${tradablePair.path.length} hops)`
+        : routeSymbols.join(' → ');
+}
+exports.buildRouteDisplay = buildRouteDisplay;
+function getFixedSpreadForRoute(route, allPairs) {
+    const matchingPair = findMatchingPair(route, allPairs);
+    if (matchingPair && hasSpreadData(matchingPair)) {
+        return matchingPair.spreadData
+            .totalSpreadPercent;
+    }
+    return route.path.length * config_1.DEFAULT_SPREAD_FALLBACK;
+}
+function getHopSpreadPercent(hop, allPairs) {
+    const directPair = allPairs.find((pair) => pair.path.length === 1 &&
+        // @ts-ignore - hop structure is known
+        pair.path[0].id === hop.id &&
+        // @ts-ignore - hop structure is known
+        pair.path[0].providerAddr === hop.providerAddr);
+    if (directPair && hasSpreadData(directPair)) {
+        return directPair.spreadData
+            .totalSpreadPercent;
+    }
+    return config_1.DEFAULT_SPREAD_FALLBACK;
+}
+function findMatchingPair(route, allPairs) {
+    return allPairs.find((pair) => {
+        if (pair.path.length !== route.path.length)
+            return false;
+        return route.path.every((hop, index) => {
+            const pairHop = pair.path[index];
+            return (hop.id === pairHop.id &&
+                hop.providerAddr === pairHop.providerAddr &&
+                hop.assets[0] === pairHop.assets[0] &&
+                hop.assets[1] === pairHop.assets[1]);
+        });
+    });
+}
+function hasSpreadData(pair) {
+    return ('spreadData' in pair &&
+        pair.spreadData &&
+        typeof pair.spreadData === 'object' &&
+        'totalSpreadPercent' in pair.spreadData);
+}
+function buildRouteSymbols(tradablePair, fromSymbol, toSymbol, allPairs) {
+    var _a, _b;
+    const addressToSymbol = createAddressToSymbolMap(allPairs);
+    // Handle special case where user input might be different from actual symbol
+    // For example, user inputs "USDT" but actual symbol is "USD₮"
+    const actualFromSymbol = findActualSymbolForInput(fromSymbol, tradablePair.assets);
+    const actualToSymbol = findActualSymbolForInput(toSymbol, tradablePair.assets);
+    // Get the addresses from tradablePair.assets using actual symbols
+    const fromAddress = (_a = tradablePair.assets
+        .find((asset) => asset.symbol === actualFromSymbol)) === null || _a === void 0 ? void 0 : _a.address.toLowerCase();
+    const toAddress = (_b = tradablePair.assets
+        .find((asset) => asset.symbol === actualToSymbol)) === null || _b === void 0 ? void 0 : _b.address.toLowerCase();
+    if (!fromAddress || !toAddress) {
+        return [fromSymbol, toSymbol];
+    }
+    // For multi-hop routes, we need to find the common intermediate tokens
+    // First, collect all unique addresses in the path
+    const allAddresses = new Set();
+    tradablePair.path.forEach((hop) => {
+        hop.assets.forEach((addr) => {
+            allAddresses.add(addr.toLowerCase());
+        });
+    });
+    // Remove our from and to addresses to find intermediates
+    allAddresses.delete(fromAddress);
+    allAddresses.delete(toAddress);
+    // Convert intermediate addresses to symbols
+    const intermediateTokens = Array.from(allAddresses)
+        .map((addr) => addressToSymbol.get(addr))
+        .filter((symbol) => symbol !== undefined);
+    // Build the route: from -> intermediates -> to
+    const route = [fromSymbol];
+    // Add intermediate tokens
+    intermediateTokens.forEach((token) => {
+        if (!route.includes(token)) {
+            route.push(token);
+        }
+    });
+    // Add destination
+    route.push(toSymbol);
+    return route;
+}
+/**
+ * Finds the actual symbol in the tradable pair assets for a given input symbol.
+ * Handles special cases like "USDT" mapping to "USD₮".
+ */
+function findActualSymbolForInput(inputSymbol, assets) {
+    // First try exact match
+    const exactMatch = assets.find((asset) => asset.symbol === inputSymbol);
+    if (exactMatch) {
+        return inputSymbol;
+    }
+    // Handle USDT special case
+    if (inputSymbol.toLowerCase() === 'usdt') {
+        // Look for USD₮ or other USDT variants
+        const usdtVariant = assets.find((asset) => {
+            const normalizedSymbol = asset.symbol.replace(/[^\w]/g, '').toLowerCase();
+            return normalizedSymbol === 'usdt' || asset.symbol === 'USD₮';
+        });
+        if (usdtVariant) {
+            return usdtVariant.symbol;
+        }
+    }
+    // Fallback to original input
+    return inputSymbol;
+}
+function createAddressToSymbolMap(allPairs) {
+    const addressToSymbol = new Map();
+    allPairs.forEach((pair) => {
+        pair.assets.forEach((asset) => {
+            addressToSymbol.set(asset.address.toLowerCase(), asset.symbol);
+        });
+    });
+    return addressToSymbol;
+}

package/dist/cjs/scripts/shared/network.d.ts

@@ -0,0 +1,23 @@
+export declare const NETWORK_MAP: Record<string, number>;
+export declare const rpcUrls: {
+    readonly 42220: "https://forno.celo.org";
+    readonly 44787: "https://alfajores-forno.celo-testnet.org";
+};
+export type SupportedChainId = keyof typeof rpcUrls;
+export interface NetworkConfig {
+    chainId: number;
+    rpcUrl: string;
+}
+/**
+ * Parse network arguments and return network configuration
+ * @param networkArg - The network name argument (e.g., 'celo', 'alfajores')
+ * @param chainIdArg - The chainId argument (e.g., '42220', '44787')
+ * @returns NetworkConfig with chainId and rpcUrl
+ */
+export declare function parseNetworkArgs(networkArg?: string, chainIdArg?: string): NetworkConfig;
+/**
+ * Get the network name from chainId
+ * @param chainId - The chain ID
+ * @returns The network name or 'Unknown' if not found
+ */
+export declare function getNetworkName(chainId: number): string;

package/dist/cjs/scripts/shared/network.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNetworkName = exports.parseNetworkArgs = exports.rpcUrls = exports.NETWORK_MAP = void 0;
+// Network name to chainId mapping
+exports.NETWORK_MAP = {
+    celo: 42220,
+    alfajores: 44787,
+};
+// RPC URLs for different networks
+exports.rpcUrls = {
+    42220: 'https://forno.celo.org',
+    44787: 'https://alfajores-forno.celo-testnet.org',
+};
+/**
+ * Parse network arguments and return network configuration
+ * @param networkArg - The network name argument (e.g., 'celo', 'alfajores')
+ * @param chainIdArg - The chainId argument (e.g., '42220', '44787')
+ * @returns NetworkConfig with chainId and rpcUrl
+ */
+function parseNetworkArgs(networkArg, chainIdArg) {
+    let chainId;
+    let rpcUrl;
+    if (networkArg) {
+        const networkName = networkArg.toLowerCase();
+        if (!exports.NETWORK_MAP[networkName]) {
+            console.error(`❌ Invalid network "${networkArg}". Valid networks: ${Object.keys(exports.NETWORK_MAP).join(', ')}`);
+            process.exit(1);
+        }
+        chainId = exports.NETWORK_MAP[networkName];
+        rpcUrl = exports.rpcUrls[chainId];
+    }
+    else if (chainIdArg) {
+        chainId = Number(chainIdArg);
+        if (!exports.rpcUrls[chainId]) {
+            console.error(`❌ Invalid chainId "${chainId}". Valid chainIds: ${Object.keys(exports.rpcUrls).join(', ')}`);
+            process.exit(1);
+        }
+        rpcUrl = exports.rpcUrls[chainId];
+    }
+    else {
+        // Default to Celo mainnet if no network specified
+        chainId = 42220;
+        rpcUrl = exports.rpcUrls[42220];
+    }
+    return { chainId, rpcUrl };
+}
+exports.parseNetworkArgs = parseNetworkArgs;
+/**
+ * Get the network name from chainId
+ * @param chainId - The chain ID
+ * @returns The network name or 'Unknown' if not found
+ */
+function getNetworkName(chainId) {
+    const networkEntry = Object.entries(exports.NETWORK_MAP).find(([, id]) => id === chainId);
+    return networkEntry ? networkEntry[0] : 'Unknown';
+}
+exports.getNetworkName = getNetworkName;

package/dist/cjs/{constants → src/constants}/addresses.js

@@ -49,29 +49,6 @@ exports.addresses = {
         StableTokenXOF: '0xB0FA15e002516d0301884059c0aaC0F0C72b019D',
         SortedOracles: '0xFdd8bD58115FfBf04e47411c1d228eCC45E93075',
     },
-    [enums_1.ChainId.BAKLAVA]: {
-        GovernanceFactory: '0xe23A28a92B95c743fC0F09c16a6b2E6D59F234Fa',
-        Airgrab: '0xNotDeployed',
-        Emission: '0xNotDeployed',
-        MentoGovernor: '0xf1873597aA9757f57BA8Ed84a3EDb2E3217EF09f',
-        MentoToken: '0x8942330eCB5A6c808aac3Aec3C6aab6D8CF436FE',
-        TimelockController: '0x8c045769087F9de69B70949ED7fC23c14Db71e20',
-        Locking: '0x1E15b108c51a0cAEAFf1a0E6f27A853Bde1AA2e6',
-        MentoRouter: '0xC5449dbB0aF89F5E3C8E0e1611966E1964F891b1',
-        Broker: '0x6723749339e320E1EFcd9f1B0D997ecb45587208',
-        BiPoolManager: '0xFF9a3da00F42839CD6D33AD7adf50bCc97B41411',
-        BreakerBox: '0x5Ea5A5F694F10de979BEeC7b8041E9f931F54bc7',
-        Reserve: '0x68Dd816611d3DE196FDeb87438B74A9c29fd649f',
-        ConstantSumPricingModule: '0x2901da88dd444a3c41AF51696548DEe3524Cf8Dc',
-        ConstantProductPricingModule: '0x7586680Dd2e4F977C33cDbd597fa2490e342CbA2',
-        MedianDeltaBreaker: '0x286a8137EE9EE6dE8B5e5be334706fA812400994',
-        ValueDeltaBreaker: '0xf631F58b1B51E99dF3Ad1CE18f5C42ab41e4A17a',
-        StableToken: '0x62492A644A588FD904270BeD06ad52B9abfEA1aE',
-        StableTokenEUR: '0xf9ecE301247aD2CE21894941830A2470f4E774ca',
-        StableTokenBRL: '0x6a0EEf2bed4C30Dc2CB42fe6c5f01F80f7EF16d1',
-        StableTokenXOF: '0x64c1D812673E93Bc036AdC3D547d9950696DA5Af',
-        SortedOracles: '0x88A187a876290E9843175027902B9f7f1B092c88',
-    },
 };
 function getAddress(identifier, chainId) {
     const addressesForChain = exports.addresses[chainId];

package/dist/cjs/src/constants/index.d.ts

@@ -0,0 +1,2 @@
+export * from './addresses';
+export * from './tradablePairs';

package/dist/cjs/{constants → src/constants}/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./addresses"), exports);
+__exportStar(require("./tradablePairs"), exports);

package/dist/cjs/src/constants/tradablePairs.42220.d.ts

@@ -0,0 +1,2 @@
+import { TradablePairWithSpread } from './tradablePairs';
+export declare const tradablePairs42220: TradablePairWithSpread[];