{"id":25664903,"url":"https://github.com/lunaris-lab/dex-pathfinder","last_synced_at":"2025-02-24T06:33:52.005Z","repository":{"id":256098896,"uuid":"834602685","full_name":"lunaris-lab/dex-pathfinder","owner":"lunaris-lab","description":"A library made for interacting with decentralized exchanges in a fully decentralized context","archived":false,"fork":false,"pushed_at":"2024-11-07T16:59:29.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-11-07T17:52:41.325Z","etag":null,"topics":["aggregator","blockchain","defi","dex","ethereum","pair","pathfinder","pool","swap","uniswap"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lunaris-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-27T19:16:48.000Z","updated_at":"2024-11-07T16:59:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"859a5ef7-ae3f-4725-8cbb-ff0cf62c6adf","html_url":"https://github.com/lunaris-lab/dex-pathfinder","commit_stats":null,"previous_names":["lunaris-lab/dex-pathfinder"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaris-lab%2Fdex-pathfinder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaris-lab%2Fdex-pathfinder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaris-lab%2Fdex-pathfinder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunaris-lab%2Fdex-pathfinder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lunaris-lab","download_url":"https://codeload.github.com/lunaris-lab/dex-pathfinder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240429720,"owners_count":19799936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aggregator","blockchain","defi","dex","ethereum","pair","pathfinder","pool","swap","uniswap"],"created_at":"2025-02-24T06:31:55.599Z","updated_at":"2025-02-24T06:33:51.963Z","avatar_url":"https://github.com/lunaris-lab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dex-pathfinder\n\n`dex-pathfinder` is a JavaScript library designed for interacting with decentralized exchanges (DEX) such as Uniswap. It's goal is to find best return for a given pair of tokens without relying in any trusted entity. It run fully local and facilitates fetching and indexing token pairs directly from the Ethereum blockchain (or any evm chain) and supports flexible storage options thanks to [level](https://github.com/level/level) interface.\n\n\u003e Currently only compatible with uniswapV2 interfaces\n\n## Installation\n\nTo install `dex-pathfinder`, use npm or yarn:\n\n```bash\nnpm install @lunarislab/dex-pathfinder\n```\n\n## How it works?\n\nFirst of all, the library need to sync to the blockchain, this step could be really heavy in requests calls if you use a RPC provider.\n\nSo in the future commits, we'll provide some templates files if you want to speed up this step. But if you want to make it yourself, consider using the param 'requestsPerSeconds' correctly as it can burn your usage limit.\n\nOnce all pairs are fetched, they'll be indexed and you'll be able to use the pathfinder.\n\n```ts\nimport { Client } from 'dex-pathfinder';\nimport { Level } from \"level\";\n\nconst viem = {\n    public: createPublicClient(config),\n    wallet: createWalletClient(config)\n};\n\nconst client = new Client({\n    viem,\n    // this need to be set correctly\n    requestsPerSeconds: 50,\n    // the more router you have, the more pairs you'll fetch.\n    routers: [\n        {\n            address: \"0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D\",\n            type: \"UniswapV2Router\"\n        }\n    ],\n    storage: Level, // you can use any level implementation\n    storagefolder: \"./src/data\" // optional, to store the databases in a specific folder.\n});\n\n// this is necessary before any call\nawait client.init();\n\n// this will launch the sync process\nclient.sync();\n```\n\nYou can monitor the sync process using listeners, here is an example using ora.\n\n```ts\nconst spinner = ora({\n    color: \"cyan\",\n    text: `Fetching pairs...`\n}).start();\n\nclient.pairsFetcher.uniswapV2.on('fetchedPair', (data) =\u003e {\n    spinner.text = `[${data.router.type}] - Fetching ${data.pair.address} ${data.progress}/${data.total}`\n});\nclient.pairsFetcher.uniswapV2.on('indexedPair', (data) =\u003e {\n    spinner.text = `[${data.router.type}] - Indexing... ${data.pair.address} ${data.progress}/${data.total}`\n});\n```\n\nThe module will also listen all new blocks and update all pairs reserves to keep it up to date. If you close the client, it will restart at where it was closed and read all missing blocks to be up to date again.\n\n## Usage\n\nOnce all the fetching process is done and indexed, you can use the swap function to find the best path to swap between two tokens.\n\nNote that depending on your params, it can be really heavy in calculations. The depth and minPoolSize params are here\nto let you control the precision.\n\nThe more deph, and the less minPoolSize, the more precise it will be. But it will also take longer to find a path.\nLowering theses params will rely on more probabilistic results, but with less calculations.\n\nI recommend using less than 6 as depth, but it depend on your hardware.\n\n```ts\n   (async () =\u003e {\n       const tokenA = \"0x39AA39c021dfbaE8faC545936693aC917d5E7563\";\n       const tokenB = \"0x5d3a536E4D6DbD6114cc1Ead35777bAB948E3643\";\n\n       // this is just a simulation, you'll need to send a tx to do the swap\n       const swap = await client.swap({\n           inputToken: tokenA,\n           outputToken: tokenB,\n           inputAmount: 100000n,\n           // the maximum length of path, not recommed to set it too high\n           // as complexity of calculations will increase exponentially\n           depth: 3\n           // this is not yet implemented, it will be the minimum\n           // liquidity required to use a pool in a swap, quoted in eth.\n           minPoolSize: 100n,\n       });\n\n       // this will return a swap object with a list of paths,\n       // path[0] is the most profitable one, path[1] is the second most profitable one, etc...\n       console.log(swap);\n   })();\n```\n\nTo understand how it find paths, you have to understand how pairs are indexed. The index create a graph\nwhere each node is a token and all links are a pair.\n\nOnce we have a graph it allow applying a pathfinding algorithm (DFS in that case), similar to algorithms used for GPS, and find all existing paths. Then instead of calculating distances like GPS, we just need to calculate the return for each paths and sort them.\n\nThe project is currently under heavy development, and not yet ready for production usage.\n\nToday it has some limitations, for example it dont filter frozen pools, so some paths could be just unusable, it will be\npartially fixed with the minPoolSize option, but a blacklist/whitelist system will be implemented too to allow you to select\npools you want to use or not.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunaris-lab%2Fdex-pathfinder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flunaris-lab%2Fdex-pathfinder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunaris-lab%2Fdex-pathfinder/lists"}