uniswap-v2-loader 3.0.0 → 4.0.1

package/README.md

@@ -1,65 +1,123 @@
-# uniswap-v2-loader
+# <picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./calp-dark.svg">
+  <img alt="calp.pro icon" src="./calp-light.svg" height="32" style="vertical-align: middle;">
+</picture> uniswap-v2-loader
+<br>
+<br>
 
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-High-speed Uniswap v2 pair loader using viem multicall and parallel CPU processing.
+**Fast DeFi AMM pools loader.** Optimized for **Multi-core CPUs** with **viem** multicall and smart **disk-cache**.
 
-## Configuration
-The package uses Alchemy. Set your key as an environment variable (a default key is used if none is provided):
-`export KEY=your_alchemy_key`
+### Popular Uniswap V2 based protocols
+| Protocol | Factory Address |
+| :--- | :--- |
+| **Uniswap V2** | `0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f` |
+| **SushiSwap** | `0xC0AEe478e3658e2610c5F7A4A2E1777cE9e4f2Ac` |
+| **PancakeSwap** | `0x1097053Fd2ea711dad45caCcc45EfF7548fCB362` |
+| **ShibaSwap** | `0x115934131916C8b277DD010Ee02de363c09d037c` |
+| **DefiSwap** | `0x9DEB29c9a4c7A88a3C0257393b7f3335338D9A9D` |
+| **EtherVista** | `0x9a27cb5ae0B2cEe0bb71f9A85C0D60f3920757B4` |
+| **Balancer V2** | `0xBA12222222228d8Ba445958a75a0704d566BF2C8` |
 
-## CLI
-```
+
+### CLI
+```bash
 npm i -g uniswap-v2-loader
-uniswap-v2-loader
+uniswap-v2-loader --help
+Options:
+ 	--key
+	--factory
+	--filename
+	--multicall_size
+	--from
+	--to
+	--workers
+	--update_timeout
 ```
 
-
 ## API Reference
+
 ### `load(params)`
-- **Description**: Fetches token pairs from a Uniswap V2-compatible factory (e.g., Uniswap, PancakeSwap, SushiSwap). It utilizes multicall from `viem` and splits the loading process between multiple CPUs for high-speed execution.
-- **Arguments**:
-    - `params`: (Object)
-        - `from`: (number) Start loading from this index (default 0).
-        - `to`: (number) Load up to this index.
-        - `filename`: (string) Path to cache CSV file.
-        - `multicall_size`: (number) Items per multicall (default 50).
-        - `factory`: (string) Factory address.
-        - `key`: (string) Alchemy/Infura API key.
-        - `workers`: (number) Number of worker threads (default max CPUs - 1).
-- **Returns**: `Promise<Array<Object>>` (Array of Pair Objects)
+High-performance parallel fetcher for liquidity pairs. Efficiently synchronizes state with local disk cache and executes multi-threaded RPC requests.
+
+**Parameters**
+| Name | Type | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `from` | `number` | Start loading from this pair index. | `0` |
+| `to` | `number` | End index (exclusive). Required for range loading. | `undefined` |
+| `filename` | `string` | Local CSV cache path. Supports OS-standard locations. | *Auto-detected* |
+| `factory` | `string` | Smart contract factory address. | `Uniswap V2` |
+| `key` | `string` | Alchemy/RPC API Key (priority over ENV). | `process.env.KEY` |
+| `multicall_size` | `number` | RPC batch size per multicall request. | `50` |
+| `workers` | `number` | Number of parallel worker threads. | `CPU - 1` |
+| `progress` | `function` | Progress callback: `(current, total) => {}`. | `undefined` |
+
+**Returns**: `Promise<Pair[]>`
+
+**Example Response**
+```json
+[
+  {
+    "id": 0,
+    "pair": "0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc",
+    "token0": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eb48",
+    "token1": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
+  }
+]
+```
+
+---
+
+### Smart Cross-Platform Caching
+The loader automatically identifies the optimal persistent storage path for your operating system to ensure zero-configuration caching:
+- **Linux:** `$XDG_CACHE_HOME` or `~/.cache/`
+- **macOS:** `~/Library/Caches/`
+- **Windows:** `%LOCALAPPDATA%` or `AppData/Local/`
+
+Cache files are named following the pattern `${package_name}_{factory_address}.csv`.
+
+---
 
 ### `onupdate(callback, params)`
-- **Description**: Subscribes to new pairs appearing at the factory contract. It initially calls the callback with cached pairs and then polls for updates.
-- **Arguments**:
-    - `callback`: (function) Called with an array of Pair Objects.
-    - `params`: (Object) Same as `load()` plus:
-        - `update_timeout`: (number) Polling interval in ms (default 5000).
-- **Returns**: `Function` An unsubscribe function to stop polling.
-
-### `clear_cache()`
-- **Description**: Clears the default cache file.
-
-### Pair Object
-The pair object contains the following fields:
-- `id`: (number) The pair index.
-- `pair`: (string) The pair contract address.
-- `token0`: (string) The address of the first token in the pair.
-- `token1`: (string) The address of the second token in the pair.
-
-## Usage
+Continuous synchronization engine. Performs initial load and subsequently polls for new pairs.
+
+**Parameters**
+| Name | Type | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `callback` | `function` | Invoked with updated `Pair[]` array. | **Required** |
+| `params` | `object` | All options from `load()` plus `update_timeout`. | - |
+| `update_timeout` | `number` | Polling interval in milliseconds. | `5000` |
+
+**Returns**: `function` (Stop/Unsubscribe function)
+
+---
+
+### Schema: `Pair`
+Standardized liquidity pool object.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `number` | Global index of the pair in the factory. |
+| `pair` | `string` | Ethereum address of the liquidity pool. |
+| `token0` | `string` | Address of the first asset. |
+| `token1` | `string` | Address of the second asset. |
+
+---
+
+## Usage Example
 ```javascript
 const { load, onupdate } = require('uniswap-v2-loader')
+const rl = require('readline')
 
-// Load initial set
-load({to: 10}).then(pairs =>
-    pairs.forEach(({id, pair}) => console.log(`ID: ${id} | Pair: ${pair}`))
-)
 
-// Subscribe to new pairs (24/7 monitoring)
-const unsubscribe = onupdate(pairs => {
-    console.log(`Pools count: ${pairs.length}`)
+load({ 
+  factory: '0xC0AEe478e3658e2610c5F7A4A2E1777cE9e4f2Ac', // SushiSwap
+  to: 1000, 
+  progress: (c, t) => {
+    rl.cursorTo(process.stdout, 0)
+    rl.clearLine(process.stdout, 0)
+    process.stdout.write(`Loaded: ${c} / ${t} (${(c/t*100).toFixed(2)}%)`)
+  }
+}).then(pairs => {
+  console.log(`\nSuccessfully loaded ${pairs.length} SushiSwap pairs`)
 })
-
-// Stop monitoring if needed
-// unsubscribe()
 ```

package/bin/uniswap-v2-loader

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const { load, count, clear_cache } = require('../index')
+const { load } = require('../index')
 const rl = require('readline')
 
 const progress = (c, t) => {
@@ -11,9 +11,43 @@ const progress = (c, t) => {
 	process.stdout.write(`Loaded: ${cur} / ${t} (${pct}%)`)
 }
 
-if (process.argv[2] == '-c' || process.argv[2] == '--count')
-	console.log(count())
-else if (process.argv[2] == '--clear')
-	clear_cache()
-else 
-	load({progress})
+const options = [
+    'key',
+    'factory',
+    'filename',
+    'multicall_size',
+    'from',
+    'to',
+    'workers',
+    'update_timeout'
+]
+
+const params = { progress }
+var i = 2
+while (arg = process.argv[i]) {
+    if (arg == '-h' || arg == '--help') {
+        console.log('Options:\n', options.map(option => `\t--${option}`).join('\n'))
+        process.exit(0)
+    }
+    if (!arg.startsWith('--')) {
+        console.log(`Option should start with "--", not: "${arg}".`)
+        process.exit(22)
+    }
+    var [option, value] = arg.slice(2).split('=')
+    if (!options.includes(option)) {
+        console.log(`Unsupported option: "${option}`)
+        process.exit(22)
+    }
+    if (!value) {
+        i++
+        value = process.argv[i]
+        if (!value || value.startsWith('--')) {
+            console.log(`Missed value for an option "${option}".`)
+            process.exit(22)
+        }
+    }
+    params[option] = value
+    i++
+}
+
+load(params)

package/calp-dark.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <polygon points="16,2 28,9 28,23 16,30 4,23 4,9" fill="none" stroke="#fff" stroke-width="3" transform="rotate(24 16 16)"/>
+</svg>

package/calp-light.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <polygon points="16,2 28,9 28,23 16,30 4,23 4,9" fill="none" stroke="#000" stroke-width="3" transform="rotate(24 16 16)"/>
+</svg>

package/default_cache_filename.js

@@ -4,7 +4,7 @@ const os = require('os')
 const home = os.homedir()
 const pkg = require('./package.json')
 
-module.exports = path.join(
+module.exports = (factory) => path.join(
   ...(process.platform === 'win32'
       ? (env.LOCALAPPDATA || env.APPDATA)
         ? [env.LOCALAPPDATA || env.APPDATA]
@@ -15,5 +15,5 @@ module.exports = path.join(
           ? [env.XDG_CACHE_HOME]
           : [home, '.cache']
   ),
-  pkg.name + '_pairs.csv'
+  `${pkg.name}_${factory.toLowerCase()}.csv`
 )

package/index.d.ts

@@ -45,11 +45,6 @@ export interface load_params {
  */
 export function load(params?: load_params): Promise<pair[]>
 
-/**
- * Clears the default cache file.
- */
-export function clear_cache(): void
-
 /**
  * Subscribes to new pairs being added to the factory.
  * @param callback Called whenever new pairs are loaded.

package/index.js

@@ -13,7 +13,7 @@ const load = (params = {}) => {
     var {
         key = debug_key,
         factory = uniswap_v2_factory,
-        filename = default_cache_filename,
+        filename,
         multicall_size = 50,
         from = 0,
         to,
@@ -21,6 +21,7 @@ const load = (params = {}) => {
         workers = max_workers,
         pairs,
     } = params
+    filename ??= default_cache_filename(factory)
     const client = createPublicClient({
         chain: mainnet,
         transport: http('https://eth-mainnet.g.alchemy.com/v2/' + key)
@@ -106,12 +107,6 @@ const load = (params = {}) => {
     })
 }
 
-
-module.exports.clear_cache = () => {
-    if (fs.existsSync(default_cache_filename))
-    fs.unlinkSync(default_cache_filename)
-}
-
 module.exports.load = (params = {}) =>
     load(params)
 

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "uniswap-v2-loader",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "description": "Uniswap v2 protocol loader",
   "keywords": [
     "uniswap-v2",
     "protocol",
     "loader",
     "crypto",
-    "ethereum"
+    "ethereum",
+    "defi",
+    "sushiswap",
+    "pancakeswap"
   ],
   "homepage": "https://github.com/calp-pro/uniswap-v2-loader#readme",
   "bugs": {
@@ -30,8 +33,5 @@
   },
   "dependencies": {
     "viem": "^2.46.2"
-  },
-  "devDependencies": {
-    "typescript": "^5.9.3"
   }
 }

package/CHANGELOG.md

@@ -1,25 +0,0 @@
-## [3.0.0] - 2026-02-27
-- Added TypeScript type definitions (`index.d.ts`).
-- Added JSDoc documentation for a better developer experience.
-- Generalized protocol support for any Uniswap V2-compatible factory.
-- Removed `count` method from the API for a cleaner, promise-based interface.
-
-## [2.0.0] - 2026-02-26
-- API Cleanup: `load` replaces `all` (now strictly returning `Promise<pair[]>`).
-- API Cleanup: `multicall_size` replaces `chunk_size`.
-- single core option ("multicore" - false)
-- prune async/await sintax sugar
-- worker delivery message at expected output pair format
-- fix: cross OS combine path for worker
-- fix: case where filename is not exist
-
-## [1.4.0] - 2026-02-24
-- spawn -> cluster
-- test order pool by factory id at CSV
-- clear cache CSV file
-
-## [1.3.0] - 2026-02-23
-- Add CLI version with `-c` or `--count` flag to counting loaded pairs from cache
-
-## [1.2.0] - 2026-02-22
-- Added `onupdate` function for subscribing to new pairs.

package/test.js

@@ -1,67 +0,0 @@
-const fs = require('fs')
-const { describe, before, it } = require('node:test')
-const assert = require('node:assert/strict')
-const {clear_cache, load, onupdate} = require('./index')
-
-describe('Uniswap V2', () => {
-    before(() => clear_cache())
-    
-    it('Exist USDC/USDP pair', () =>
-        load({to: 2})
-        .then(pairs => {
-            assert.equal(pairs.length, 2)
-            const i = pairs.findIndex(({id}) => id == 1)
-            assert.ok(i != -1)
-            if (i != -1) {
-                const {pair, token0, token1} = pairs[i]
-                assert.equal(pair, '0x3139Ffc91B99aa94DA8A2dc13f1fC36F9BDc98eE')
-                assert.equal(token0, '0x8E870D67F660D95d5be530380D0eC0bd388289E1')
-                assert.equal(token1, '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48')
-            }
-        })
-    )
-    
-    
-    it('Re-load first two pairs to custom CSV file', () => {
-        // If user specify a filename then
-        // a cache data will be taken from
-        // the filename provided. If file is empty then
-        // data will be uploaded again from network.
-        const filename = Date.now() + '.csv'
-        return load({to: 2, filename})
-        .then(() => {
-            const lines = fs.readFileSync(filename).toString().trim().split('\n')
-            assert.equal(lines.length, 2)
-        })
-        .finally(() =>
-            fs.unlinkSync(filename)
-        )
-    })
-
-    it('onupdate should call provided callback with 2 pairs for a current moment (from cache)', () => {
-        return new Promise(y => {
-            const unsubscribe = onupdate(pairs => {
-                assert.equal(pairs.length, 2)
-                unsubscribe()
-                y()
-            }, {to: 2})
-        })
-    })
-
-    it('Multi-core test 2 workers load 2 pools using multicall', () =>
-        // There are already 2 pools loaded from previous test
-        // 6 - 2 = 4. Rest 4 will be loaded by 2 workers. Each load 2.
-        // Multicall size is 2.
-        load({to: 6, multicall_size: 2, workers: 2 })
-        .then(pairs => {
-            assert.equal(pairs.length, 6)
-        })
-    )
-
-    it('Each line at CSV cache file should be orderd by pair id (factory id)', () => {
-        const lines = fs.readFileSync(require('./default_cache_filename'), 'utf8').trim().split('\n')
-        for (var i = 0; i < lines.length; i++)
-            assert.equal(i, +lines[i].split(',').shift())
-    })
-
-})