@xspswap/smart-order-router 1.0.0

package/README.md

@@ -0,0 +1,189 @@
+# Xswap Smart Order Router
+
+This repository contains routing logic for the Xswap V3 protocol.
+
+It searches for the most efficient way to swap token A for token B, considering splitting swaps across multiple routes and gas costs.
+
+## Testing
+
+### Unit Tests
+
+First make sure you have run `npm install` and `npm run build`.
+
+```
+npm run test
+```
+
+### Integration Tests
+
+Make sure the `.env` file is configured to connect to mainnet and other chains. See the [CLI](#cli) section below for more details.
+
+```
+npm run integ-test
+```
+
+### Tenderly Simulations
+
+Quotes can be simulated on Tenderly
+
+Ensure you set the following environment variables:
+
+```
+process.env.TENDERLY_BASE_URL!,
+process.env.TENDERLY_USER!,
+process.env.TENDERLY_PROJECT!,
+process.env.TENDERLY_ACCESS_KEY!,
+```
+
+### CLI
+
+The package can be run as a CLI for testing purposes.
+
+First create a `.env` file in the root of the project and configure:
+
+```
+JSON_RPC_PROVIDER = '<JSON_RPC_PROVIDER>'
+```
+
+To run on chains other than mainnet set up a connection by specifying the environment variable
+
+```
+JSON_RPC_PROVIDER_ROPSTEN = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_RINKEBY = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_GORLI = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_KOVAN = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_OPTIMISM = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_OPTIMISM_GOERLI = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_OPTIMISTIC_KOVAN = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_ARBITRUM_ONE = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_ARBITRUM_RINKEBY = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_ARBITRUM_GOERLI = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_POLYGON = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_POLYGON_MUMBAI = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_CELO = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_CELO_ALFAJORES = '<JSON_RPC_PROVIDER>'
+JSON_RPC_PROVIDER_BSC = '<JSON_RPC_PROVIDER>'
+```
+
+Then from the root directory you can execute the CLI.
+
+## Examples
+
+Some examples to use for manual CLI testing.
+
+### Mainnet
+
+```
+./bin/cli quote --tokenIn 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --tokenOut 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 --amount 1000 --exactIn --recipient 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B --protocols v2,v3
+
+Best Route:
+100.00% = USDC -- 0.3% --> UNI
+	Raw Quote Out:
+		35.72
+	Gas Adjusted Quote Out:
+		34.03
+
+Gas Used Quote Token: 1.691772
+Gas Used USD: 47.592951
+Calldata: 0x414bf389000000000000...
+Value: 0x00
+
+  blockNumber: "13088815"
+  estimatedGasUsed: "113000"
+  gasPriceWei: "130000000000"
+
+
+./bin/cli quote-to-ratio --token0 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --token1 0xdac17f958d2ee523a2206206994597c13d831ec7 --feeAmount 3000 --recipient 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B  --token0Balance 1000 --token1Balance 2000 --tickLower -120 --tickUpper 120
+
+Best Route:
+100.00% = USDT -- 0.05% --> USDC
+Raw Quote Exact In:
+	392.68
+Gas Adjusted Quote In}:
+	346.13
+
+Gas Used Quote Token: 46.550010
+Gas Used USD: 46.342899
+Calldata: 0x414bf389000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb4800000000000000000000000000000000000000000000000000000000000001f4000000000000000000000000ab5801a7d398351b8be11c439e05c5b3259aec9b000000000000000000000000000000000000000000000000000000000000006400000000000000000000000000000000000000000000000000000000176a736c000000000000000000000000000000000000000000000000000000001764f8650000000000000000000000000000000000000000000000000000000000000000
+	Value: 0x00
+
+	blockNumber: "13239188"
+	estimatedGasUsed: "113000"
+	gasPriceWei: "116690684398"
+
+./bin/cli quote --tokenIn 0x0391D2021f89DC339F60Fff84546EA23E337750f --tokenOut 0x4d224452801ACEd8B2F0aebE155379bb5D594381 --amount 10000 --exactIn --recipient 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B --protocols v2,v3,mixed
+Best Route:
+[V2 + V3] 100.00% = BOND -- [0x6591c4BcD6D7A1eb4E537DA8B78676C1576Ba244] --> USDC -- 0.3% [0xB07Fe2F407F971125D4EB1977f8aCEe8846C7324] --> APE
+	Raw Quote Exact In:
+		10437.85
+	Gas Adjusted Quote In:
+		10433.83
+
+Gas Used Quote Token: 4.018625
+Gas Used USD: 29.669402
+Calldata: 0x5ae401dc0000000000000000000000000000000000000000000000000000000000000064000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000000e4472b43f300000000000000000000000000000000000000000000021e19e0c9bab240000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020000000000000000000000000391d2021f89dc339f60fff84546ea23e337750f000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000104b858183f00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000080000000000000000000000000ab5801a7d398351b8be11c439e05c5b3259aec9b00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002358df5b3b4459a3f5b000000000000000000000000000000000000000000000000000000000000002ba0b86991c6218b36c1d19d4a2e9eb0ce3606eb48000bb84d224452801aced8b2f0aebe155379bb5d59438100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+Value: 0x00
+
+  blockNumber: "15303839"
+  estimatedGasUsed: "434000"
+  gasPriceWei: "38218865879"
+Total ticks crossed: 7
+```
+
+## XDC Mainnet
+
+```
+XSP
+./bin/cli quote --tokenIn 0x36726235dAdbdb4658D33E62a249dCA7c4B2bC68 --tokenOut 0xD4B5f10D61916Bd6E0860144a91Ac658dE8a1437 --amount 1000 --exactIn --minSplits 1 --protocols v2,v3,mixed --router alpha --chainId 50
+
+
+SRX - USDT
+./bin/cli quote --tokenIn 0x5d5f074837f5d4618b3916ba74de1bf9662a3fed --tokenOut 0xD4B5f10D61916Bd6E0860144a91Ac658dE8a1437 --amount 1000 --exactIn --minSplits 1 --protocols v2 --router alpha --chainId 50
+
+SRX - WXDC
+./bin/cli quote --tokenIn 0x5d5f074837f5d4618b3916ba74de1bf9662a3fed --tokenOut 0x951857744785e80e2de051c32ee7b25f9c458c42 --amount 1000 --exactIn --minSplits 1 --protocols v2,v3,mixed --router alpha --chainId 50
+
+```
+
+## Adding a new Chain
+
+The main components to complete are:
+
+- Deploy contracts on chain, add the pools to subgraph
+- Populate v3 providers in `src/providers/v3/subgraph-provider` and `src/providers/v3/static-subgraph-provider`
+- Populate chainId and addresses in `src/util/chains.ts` and `src/util/addresses.ts`
+- Populate token providers in `src/providers/caching-token-provider` and `src/providers/token-provider.ts`
+- Populate gas constants in `src/routers/alpha-router/gas-models/*`
+- Populate bases in `src/routers/legacy-router/bases.ts`
+- Populate `test/integ/routers/alpha-router/alpha-router.integration.test.ts` and `src/providers/v2/static-subgraph-provider.ts`
+- Populate `src/routers/alpha-router/*`
+- Add a log to `/CHANGELOG.md`
+- Run `npm run integ-test` successfully
+
+# Troubleshooting
+
+## ProviderGasLimit errors
+
+The package sends many large multicall requests to nodes. You must ensure that your node provider's `eth_call` gas limit is high enough to succesfully process the RPC calls.
+
+By default each `eth_call` will consume up to:
+
+- 132,000,000 gas on Optimism
+- 120,000,000 gas on Arbitrum
+- 50,000,000 gas on Celo
+- 150,000,000 gas on every other network (Mainnet, Goerli, etc.)
+
+These parameters should work on Infura and Alchemy by default.
+
+This total amount of gas each `eth_call` can consume is equal to the `multicallChunk` config value multiplied by the `gasLimitPerCall` config value. If you are using a node provider with a lower gas limit per `eth_call` you will need to override the default `V3QuoteProvider` with an instance that lowers the `multicallChunk` and `gasLimitPerCall` parameters such that the multiplication is below your node providers limit. Lowering these values will cause each multicall to consume less gas. See [here](https://github.com/Xs/smart-order-router/blob/98c58bdee9981fd9ffac9e7d7a97b18302d5f77a/src/routers/alpha-router/alpha-router.ts#L415-L416) for examples of how to set these values. Note some providers have different limits per chain.
+
+If you are running your own node, we recommend you configure start your node with a higher gas limit per call. For example, on Geth you can use the command line argument `--rpc.gascap 150000000` to raise the limit to 150m, which is enough to run the default configuration of this package.
+
+If you are using Hardhat mainnet forking, you should add `blockGasLimit: 150_000_000` to your Hardhat config to use the default package configuration.
+
+# TODO
+1) Check default gas limit for XDC
+2) add v2 against
+
+___
+node version 15 

package/build/main/index.d.ts

@@ -0,0 +1,3 @@
+export * from './providers';
+export * from './routers';
+export * from './util';

package/build/main/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./providers"), exports);
+__exportStar(require("./routers"), exports);
+__exportStar(require("./util"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLDhDQUE0QjtBQUM1Qiw0Q0FBMEI7QUFDMUIseUNBQXVCIn0=

package/build/main/providers/cache-node.d.ts

@@ -0,0 +1,9 @@
+import NodeCache from 'node-cache';
+import { ICache } from './cache';
+export declare class NodeJSCache<T> implements ICache<T> {
+    private nodeCache;
+    constructor(nodeCache: NodeCache);
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+}

package/build/main/providers/cache-node.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeJSCache = void 0;
+class NodeJSCache {
+    constructor(nodeCache) {
+        this.nodeCache = nodeCache;
+    }
+    async get(key) {
+        return this.nodeCache.get(key);
+    }
+    async set(key, value) {
+        return this.nodeCache.set(key, value);
+    }
+    async has(key) {
+        return this.nodeCache.has(key);
+    }
+}
+exports.NodeJSCache = NodeJSCache;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FjaGUtbm9kZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9wcm92aWRlcnMvY2FjaGUtbm9kZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFJQSxNQUFhLFdBQVc7SUFDdEIsWUFBb0IsU0FBb0I7UUFBcEIsY0FBUyxHQUFULFNBQVMsQ0FBVztJQUFHLENBQUM7SUFFNUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxHQUFXO1FBQ25CLE9BQU8sSUFBSSxDQUFDLFNBQVMsQ0FBQyxHQUFHLENBQUksR0FBRyxDQUFDLENBQUM7SUFDcEMsQ0FBQztJQUVELEtBQUssQ0FBQyxHQUFHLENBQUMsR0FBVyxFQUFFLEtBQVE7UUFDN0IsT0FBTyxJQUFJLENBQUMsU0FBUyxDQUFDLEdBQUcsQ0FBQyxHQUFHLEVBQUUsS0FBSyxDQUFDLENBQUM7SUFDeEMsQ0FBQztJQUVELEtBQUssQ0FBQyxHQUFHLENBQUMsR0FBVztRQUNuQixPQUFPLElBQUksQ0FBQyxTQUFTLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQ2pDLENBQUM7Q0FDRjtBQWRELGtDQWNDIn0=

package/build/main/providers/cache.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generic cache used by providers. Allows caching of results to minimize
+ * round trips to external data sources.
+ *
+ * @export
+ * @interface ICache
+ * @template T
+ */
+export interface ICache<T> {
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+}

package/build/main/providers/cache.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FjaGUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcHJvdmlkZXJzL2NhY2hlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/build/main/providers/caching/route/index.d.ts

@@ -0,0 +1,2 @@
+export * from './route-caching-provider';
+export * from './model/';

package/build/main/providers/caching/route/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./route-caching-provider"), exports);
+__exportStar(require("./model/"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvcHJvdmlkZXJzL2NhY2hpbmcvcm91dGUvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLDJEQUF5QztBQUN6QywyQ0FBeUIifQ==

package/build/main/providers/caching/route/model/cache-mode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CacheMode enum that controls the way that the RouteCachingProvider works.
+ * - *Livemode*:   This mode will set materialized routes into cache and fetch routes from cache.
+ *                 If the route exists in cache, it will be quoted and returned, otherwise it will materialized.
+ * - *Darkmode*:   This mode indicates that the cache will not be used, it will not be inserted nor fetched.
+ *                 Routes will always be materialized.
+ * - *Tapcompare*: In this mode we will insert and fetch routes to/from cache, and we will also materialize the route.
+ *                 Ultimately the materialized route will be returned, but we will log some metrics comparing both.
+ *
+ * @enum {string}
+ */
+export declare enum CacheMode {
+    Livemode = "livemode",
+    Darkmode = "darkmode",
+    Tapcompare = "tapcompare"
+}

package/build/main/providers/caching/route/model/cache-mode.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheMode = void 0;
+/**
+ * CacheMode enum that controls the way that the RouteCachingProvider works.
+ * - *Livemode*:   This mode will set materialized routes into cache and fetch routes from cache.
+ *                 If the route exists in cache, it will be quoted and returned, otherwise it will materialized.
+ * - *Darkmode*:   This mode indicates that the cache will not be used, it will not be inserted nor fetched.
+ *                 Routes will always be materialized.
+ * - *Tapcompare*: In this mode we will insert and fetch routes to/from cache, and we will also materialize the route.
+ *                 Ultimately the materialized route will be returned, but we will log some metrics comparing both.
+ *
+ * @enum {string}
+ */
+var CacheMode;
+(function (CacheMode) {
+    CacheMode["Livemode"] = "livemode";
+    CacheMode["Darkmode"] = "darkmode";
+    CacheMode["Tapcompare"] = "tapcompare";
+})(CacheMode = exports.CacheMode || (exports.CacheMode = {}));
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FjaGUtbW9kZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uLy4uLy4uL3NyYy9wcm92aWRlcnMvY2FjaGluZy9yb3V0ZS9tb2RlbC9jYWNoZS1tb2RlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBOzs7Ozs7Ozs7O0dBVUc7QUFDSCxJQUFZLFNBSVg7QUFKRCxXQUFZLFNBQVM7SUFDbkIsa0NBQXFCLENBQUE7SUFDckIsa0NBQXFCLENBQUE7SUFDckIsc0NBQXlCLENBQUE7QUFDM0IsQ0FBQyxFQUpXLFNBQVMsR0FBVCxpQkFBUyxLQUFULGlCQUFTLFFBSXBCIn0=

package/build/main/providers/caching/route/model/cached-route.d.ts

@@ -0,0 +1,23 @@
+import { Protocol } from '@xswap-v3/router-sdk';
+import { MixedRoute, V2Route, V3Route } from '../../../../routers';
+interface CachedRouteParams<Route extends V3Route | V2Route | MixedRoute> {
+    route: Route;
+    percent: number;
+}
+/**
+ * Class defining the route to cache
+ *
+ * @export
+ * @class CachedRoute
+ */
+export declare class CachedRoute<Route extends V3Route | V2Route | MixedRoute> {
+    readonly route: Route;
+    readonly percent: number;
+    /**
+     * @param route
+     * @param percent
+     */
+    constructor({ route, percent }: CachedRouteParams<Route>);
+    get protocol(): Protocol;
+}
+export {};

package/build/main/providers/caching/route/model/cached-route.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedRoute = void 0;
+/**
+ * Class defining the route to cache
+ *
+ * @export
+ * @class CachedRoute
+ */
+class CachedRoute {
+    /**
+     * @param route
+     * @param percent
+     */
+    constructor({ route, percent }) {
+        this.route = route;
+        this.percent = percent;
+    }
+    get protocol() {
+        return this.route.protocol;
+    }
+}
+exports.CachedRoute = CachedRoute;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FjaGVkLXJvdXRlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vLi4vLi4vc3JjL3Byb3ZpZGVycy9jYWNoaW5nL3JvdXRlL21vZGVsL2NhY2hlZC1yb3V0ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFTQTs7Ozs7R0FLRztBQUNILE1BQWEsV0FBVztJQUl0Qjs7O09BR0c7SUFDSCxZQUFZLEVBQUUsS0FBSyxFQUFFLE9BQU8sRUFBNEI7UUFDdEQsSUFBSSxDQUFDLEtBQUssR0FBRyxLQUFLLENBQUM7UUFDbkIsSUFBSSxDQUFDLE9BQU8sR0FBRyxPQUFPLENBQUM7SUFDekIsQ0FBQztJQUVELElBQVcsUUFBUTtRQUNqQixPQUFPLElBQUksQ0FBQyxLQUFLLENBQUMsUUFBUSxDQUFDO0lBQzdCLENBQUM7Q0FDRjtBQWhCRCxrQ0FnQkMifQ==

package/build/main/providers/caching/route/model/cached-routes.d.ts

@@ -0,0 +1,63 @@
+import { Protocol } from '@xswap-v3/router-sdk';
+import { Token, TradeType } from '@uniswap/sdk-core';
+import { MixedRoute, RouteWithValidQuote, V2Route, V3Route } from '../../../../routers';
+import { ChainId } from '../../../../util';
+import { CachedRoute } from './cached-route';
+interface CachedRoutesParams {
+    routes: CachedRoute<V3Route | V2Route | MixedRoute>[];
+    chainId: ChainId;
+    tokenIn: Token;
+    tokenOut: Token;
+    protocolsCovered: Protocol[];
+    blockNumber: number;
+    tradeType: TradeType;
+    blocksToLive?: number;
+}
+/**
+ * Class defining the route to cache
+ *
+ * @export
+ * @class CachedRoute
+ */
+export declare class CachedRoutes {
+    readonly routes: CachedRoute<V3Route | V2Route | MixedRoute>[];
+    readonly chainId: ChainId;
+    readonly tokenIn: Token;
+    readonly tokenOut: Token;
+    readonly protocolsCovered: Protocol[];
+    readonly blockNumber: number;
+    readonly tradeType: TradeType;
+    blocksToLive: number;
+    /**
+     * @param routes
+     * @param chainId
+     * @param tokenIn
+     * @param tokenOut
+     * @param protocolsCovered
+     * @param blockNumber
+     * @param tradeType
+     * @param blocksToLive
+     */
+    constructor({ routes, chainId, tokenIn, tokenOut, protocolsCovered, blockNumber, tradeType, blocksToLive }: CachedRoutesParams);
+    /**
+     * Factory method that creates a `CachedRoutes` object from an array of RouteWithValidQuote.
+     *
+     * @public
+     * @static
+     * @param routes
+     * @param chainId
+     * @param tokenIn
+     * @param tokenOut
+     * @param protocolsCovered
+     * @param blockNumber
+     * @param tradeType
+     */
+    static fromRoutesWithValidQuotes(routes: RouteWithValidQuote[], chainId: ChainId, tokenIn: Token, tokenOut: Token, protocolsCovered: Protocol[], blockNumber: number, tradeType: TradeType): CachedRoutes | undefined;
+    /**
+     * Function to determine if, given a block number, the CachedRoute is expired or not.
+     *
+     * @param currentBlockNumber
+     */
+    notExpired(currentBlockNumber: number): boolean;
+}
+export {};

package/build/main/providers/caching/route/model/cached-routes.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedRoutes = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const cached_route_1 = require("./cached-route");
+/**
+ * Class defining the route to cache
+ *
+ * @export
+ * @class CachedRoute
+ */
+class CachedRoutes {
+    /**
+     * @param routes
+     * @param chainId
+     * @param tokenIn
+     * @param tokenOut
+     * @param protocolsCovered
+     * @param blockNumber
+     * @param tradeType
+     * @param blocksToLive
+     */
+    constructor({ routes, chainId, tokenIn, tokenOut, protocolsCovered, blockNumber, tradeType, blocksToLive = 0 }) {
+        this.routes = routes;
+        this.chainId = chainId;
+        this.tokenIn = tokenIn;
+        this.tokenOut = tokenOut;
+        this.protocolsCovered = protocolsCovered;
+        this.blockNumber = blockNumber;
+        this.tradeType = tradeType;
+        this.blocksToLive = blocksToLive;
+    }
+    /**
+     * Factory method that creates a `CachedRoutes` object from an array of RouteWithValidQuote.
+     *
+     * @public
+     * @static
+     * @param routes
+     * @param chainId
+     * @param tokenIn
+     * @param tokenOut
+     * @param protocolsCovered
+     * @param blockNumber
+     * @param tradeType
+     */
+    static fromRoutesWithValidQuotes(routes, chainId, tokenIn, tokenOut, protocolsCovered, blockNumber, tradeType) {
+        if (routes.length == 0)
+            return undefined;
+        const cachedRoutes = lodash_1.default.map(routes, (route) => new cached_route_1.CachedRoute({ route: route.route, percent: route.percent }));
+        return new CachedRoutes({
+            routes: cachedRoutes,
+            chainId: chainId,
+            tokenIn: tokenIn,
+            tokenOut: tokenOut,
+            protocolsCovered: protocolsCovered,
+            blockNumber: blockNumber,
+            tradeType: tradeType
+        });
+    }
+    /**
+     * Function to determine if, given a block number, the CachedRoute is expired or not.
+     *
+     * @param currentBlockNumber
+     */
+    notExpired(currentBlockNumber) {
+        return (currentBlockNumber - this.blockNumber) <= this.blocksToLive;
+    }
+}
+exports.CachedRoutes = CachedRoutes;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FjaGVkLXJvdXRlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uLy4uLy4uL3NyYy9wcm92aWRlcnMvY2FjaGluZy9yb3V0ZS9tb2RlbC9jYWNoZWQtcm91dGVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7OztBQUVBLG9EQUF1QjtBQUt2QixpREFBNkM7QUFhN0M7Ozs7O0dBS0c7QUFDSCxNQUFhLFlBQVk7SUFXdkI7Ozs7Ozs7OztPQVNHO0lBQ0gsWUFDRSxFQUNFLE1BQU0sRUFDTixPQUFPLEVBQ1AsT0FBTyxFQUNQLFFBQVEsRUFDUixnQkFBZ0IsRUFDaEIsV0FBVyxFQUNYLFNBQVMsRUFDVCxZQUFZLEdBQUcsQ0FBQyxFQUNHO1FBRXJCLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO1FBQ3JCLElBQUksQ0FBQyxPQUFPLEdBQUcsT0FBTyxDQUFDO1FBQ3ZCLElBQUksQ0FBQyxPQUFPLEdBQUcsT0FBTyxDQUFDO1FBQ3ZCLElBQUksQ0FBQyxRQUFRLEdBQUcsUUFBUSxDQUFDO1FBQ3pCLElBQUksQ0FBQyxnQkFBZ0IsR0FBRyxnQkFBZ0IsQ0FBQztRQUN6QyxJQUFJLENBQUMsV0FBVyxHQUFHLFdBQVcsQ0FBQztRQUMvQixJQUFJLENBQUMsU0FBUyxHQUFHLFNBQVMsQ0FBQztRQUMzQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztJQUNuQyxDQUFDO0lBRUQ7Ozs7Ozs7Ozs7OztPQVlHO0lBQ0ksTUFBTSxDQUFDLHlCQUF5QixDQUNyQyxNQUE2QixFQUM3QixPQUFnQixFQUNoQixPQUFjLEVBQ2QsUUFBZSxFQUNmLGdCQUE0QixFQUM1QixXQUFtQixFQUNuQixTQUFvQjtRQUVwQixJQUFJLE1BQU0sQ0FBQyxNQUFNLElBQUksQ0FBQztZQUFFLE9BQU8sU0FBUyxDQUFDO1FBRXpDLE1BQU0sWUFBWSxHQUFHLGdCQUFDLENBQUMsR0FBRyxDQUFDLE1BQU0sRUFBRSxDQUFDLEtBQTBCLEVBQUUsRUFBRSxDQUNoRSxJQUFJLDBCQUFXLENBQUMsRUFBRSxLQUFLLEVBQUUsS0FBSyxDQUFDLEtBQUssRUFBRSxPQUFPLEVBQUUsS0FBSyxDQUFDLE9BQU8sRUFBRSxDQUFDLENBQ2hFLENBQUM7UUFFRixPQUFPLElBQUksWUFBWSxDQUFDO1lBQ3RCLE1BQU0sRUFBRSxZQUFZO1lBQ3BCLE9BQU8sRUFBRSxPQUFPO1lBQ2hCLE9BQU8sRUFBRSxPQUFPO1lBQ2hCLFFBQVEsRUFBRSxRQUFRO1lBQ2xCLGdCQUFnQixFQUFFLGdCQUFnQjtZQUNsQyxXQUFXLEVBQUUsV0FBVztZQUN4QixTQUFTLEVBQUUsU0FBUztTQUNyQixDQUFDLENBQUM7SUFDTCxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNJLFVBQVUsQ0FBQyxrQkFBMEI7UUFDMUMsT0FBTyxDQUFDLGtCQUFrQixHQUFHLElBQUksQ0FBQyxXQUFXLENBQUMsSUFBSSxJQUFJLENBQUMsWUFBWSxDQUFDO0lBQ3RFLENBQUM7Q0FDRjtBQTFGRCxvQ0EwRkMifQ==

package/build/main/providers/caching/route/model/index.d.ts

@@ -0,0 +1,3 @@
+export * from './cached-route';
+export * from './cached-routes';
+export * from './cache-mode';

package/build/main/providers/caching/route/model/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cached-route"), exports);
+__exportStar(require("./cached-routes"), exports);
+__exportStar(require("./cache-mode"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi8uLi9zcmMvcHJvdmlkZXJzL2NhY2hpbmcvcm91dGUvbW9kZWwvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLGlEQUErQjtBQUMvQixrREFBZ0M7QUFDaEMsK0NBQTZCIn0=

package/build/main/providers/caching/route/route-caching-provider.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Provider for getting token data from a Token List.
+ *
+ * @export
+ * @interface IRouteCachingProvider
+ */
+import { Protocol } from '@xswap-v3/router-sdk';
+import { Currency, CurrencyAmount, Token, TradeType } from '@uniswap/sdk-core';
+import { ChainId } from '../../../util';
+import { CacheMode } from './model';
+import { CachedRoutes } from './model/cached-routes';
+/**
+ * Abstract class for a RouteCachingProvider.
+ * Defines the base methods of how to interact with this interface, but not the implementation of how to cache.
+ */
+export declare abstract class IRouteCachingProvider {
+    /**
+     * Final implementation of the public `getCachedRoute` method, this is how code will interact with the implementation
+     *
+     * @public
+     * @readonly
+     * @param chainId
+     * @param amount
+     * @param quoteToken
+     * @param tradeType
+     * @param protocols
+     * @param blockNumber
+     */
+    readonly getCachedRoute: (chainId: number, amount: CurrencyAmount<Currency>, quoteToken: Token, tradeType: TradeType, protocols: Protocol[], blockNumber: number) => Promise<CachedRoutes | undefined>;
+    /**
+     * Final implementation of the public `setCachedRoute` method.
+     * This method will set the blockToLive in the CachedRoutes object before calling the internal method to insert in cache.
+     *
+     * @public
+     * @readonly
+     * @param cachedRoutes The route to cache.
+     * @returns Promise<boolean> Indicates if the route was inserted into cache.
+     */
+    readonly setCachedRoute: (cachedRoutes: CachedRoutes, amount: CurrencyAmount<Currency>) => Promise<boolean>;
+    /**
+     * Returns the CacheMode for the given cachedRoutes and amount
+     *
+     * @param cachedRoutes
+     * @param amount
+     */
+    getCacheModeFromCachedRoutes(cachedRoutes: CachedRoutes, amount: CurrencyAmount<Currency>): Promise<CacheMode>;
+    /**
+     * Returns the CacheMode for the given combination of chainId, tokenIn, tokenOut and tradetype
+     *
+     * @public
+     * @abstract
+     * @param chainId
+     * @param tokenIn
+     * @param tokenOut
+     * @param tradeType
+     * @param amount
+     */
+    abstract getCacheMode(chainId: ChainId, amount: CurrencyAmount<Currency>, quoteToken: Token, tradeType: TradeType, protocols: Protocol[]): Promise<CacheMode>;
+    private filterExpiredCachedRoutes;
+    /**
+     * Internal function to fetch the CachedRoute from the cache.
+     * Must be implemented.
+     *
+     * @param chainId
+     * @param amount
+     * @param quoteToken
+     * @param tradeType
+     * @param protocols
+     * @protected
+     */
+    protected abstract _getCachedRoute(chainId: ChainId, amount: CurrencyAmount<Currency>, quoteToken: Token, tradeType: TradeType, protocols: Protocol[]): Promise<CachedRoutes | undefined>;
+    /**
+     * Internal function to insert the CachedRoute into cache.
+     * Must be implemented.
+     *
+     * @param cachedRoutes
+     * @param amount
+     * @protected
+     */
+    protected abstract _setCachedRoute(cachedRoutes: CachedRoutes, amount: CurrencyAmount<Currency>): Promise<boolean>;
+    /**
+     * Internal function to getBlocksToLive for a given cachedRoute.
+     * This function is called before attempting to insert the route into cache.
+     * Must be implemented.
+     *
+     * @param cachedRoutes
+     * @param amount
+     * @protected
+     */
+    protected abstract _getBlocksToLive(cachedRoutes: CachedRoutes, amount: CurrencyAmount<Currency>): Promise<number>;
+}