uniswap-v2-loader 4.0.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +107 -45
  2. package/calp-dark.svg +3 -0
  3. package/calp-light.svg +3 -0
  4. package/default_cache_filename.js +2 -2
  5. package/index.js +2 -1
  6. package/package.json +1 -1
  7. package/debug.js +0 -3
package/README.md CHANGED
@@ -1,61 +1,123 @@
1
- # uniswap-v2-loader
1
+ # <picture>
2
+ <source media="(prefers-color-scheme: dark)" srcset="./calp-dark.svg">
3
+ <img alt="calp.pro icon" src="./calp-light.svg" height="32" style="vertical-align: middle;">
4
+ </picture> uniswap-v2-loader
5
+ <br>
6
+ <br>
2
7
 
3
- High-speed Uniswap v2 pair loader using viem multicall and parallel CPU processing.
8
+ **Fast DeFi AMM pools loader.** Optimized for **Multi-core CPUs** with **viem** multicall and smart **disk-cache**.
4
9
 
5
- ## Configuration
6
- The package uses Alchemy. Set your key as an environment variable (a default key is used if none is provided):
7
- `export KEY=your_alchemy_key`
10
+ ### Popular Uniswap V2 based protocols
11
+ | Protocol | Factory Address |
12
+ | :--- | :--- |
13
+ | **Uniswap V2** | `0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f` |
14
+ | **SushiSwap** | `0xC0AEe478e3658e2610c5F7A4A2E1777cE9e4f2Ac` |
15
+ | **PancakeSwap** | `0x1097053Fd2ea711dad45caCcc45EfF7548fCB362` |
16
+ | **ShibaSwap** | `0x115934131916C8b277DD010Ee02de363c09d037c` |
17
+ | **DefiSwap** | `0x9DEB29c9a4c7A88a3C0257393b7f3335338D9A9D` |
18
+ | **EtherVista** | `0x9a27cb5ae0B2cEe0bb71f9A85C0D60f3920757B4` |
19
+ | **Balancer V2** | `0xBA12222222228d8Ba445958a75a0704d566BF2C8` |
8
20
 
9
- ## CLI
10
- ```
21
+
22
+ ### CLI
23
+ ```bash
11
24
  npm i -g uniswap-v2-loader
12
- uniswap-v2-loader
25
+ uniswap-v2-loader --help
26
+ Options:
27
+ --key
28
+ --factory
29
+ --filename
30
+ --multicall_size
31
+ --from
32
+ --to
33
+ --workers
34
+ --update_timeout
13
35
  ```
14
36
 
15
-
16
37
  ## API Reference
38
+
17
39
  ### `load(params)`
18
- - **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.
19
- - **Arguments**:
20
- - `params`: (Object)
21
- - `from`: (number) Start loading from this index (default 0).
22
- - `to`: (number) Load up to this index.
23
- - `filename`: (string) Path to cache CSV file.
24
- - `multicall_size`: (number) Items per multicall (default 50).
25
- - `factory`: (string) Factory address.
26
- - `key`: (string) Alchemy/Infura API key.
27
- - `workers`: (number) Number of worker threads (default max CPUs - 1).
28
- - **Returns**: `Promise<Array<Object>>` (Array of Pair Objects)
40
+ High-performance parallel fetcher for liquidity pairs. Efficiently synchronizes state with local disk cache and executes multi-threaded RPC requests.
41
+
42
+ **Parameters**
43
+ | Name | Type | Description | Default |
44
+ | :--- | :--- | :--- | :--- |
45
+ | `from` | `number` | Start loading from this pair index. | `0` |
46
+ | `to` | `number` | End index (exclusive). Required for range loading. | `undefined` |
47
+ | `filename` | `string` | Local CSV cache path. Supports OS-standard locations. | *Auto-detected* |
48
+ | `factory` | `string` | Smart contract factory address. | `Uniswap V2` |
49
+ | `key` | `string` | Alchemy/RPC API Key (priority over ENV). | `process.env.KEY` |
50
+ | `multicall_size` | `number` | RPC batch size per multicall request. | `50` |
51
+ | `workers` | `number` | Number of parallel worker threads. | `CPU - 1` |
52
+ | `progress` | `function` | Progress callback: `(current, total) => {}`. | `undefined` |
53
+
54
+ **Returns**: `Promise<Pair[]>`
55
+
56
+ **Example Response**
57
+ ```json
58
+ [
59
+ {
60
+ "id": 0,
61
+ "pair": "0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc",
62
+ "token0": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eb48",
63
+ "token1": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
64
+ }
65
+ ]
66
+ ```
67
+
68
+ ---
69
+
70
+ ### Smart Cross-Platform Caching
71
+ The loader automatically identifies the optimal persistent storage path for your operating system to ensure zero-configuration caching:
72
+ - **Linux:** `$XDG_CACHE_HOME` or `~/.cache/`
73
+ - **macOS:** `~/Library/Caches/`
74
+ - **Windows:** `%LOCALAPPDATA%` or `AppData/Local/`
75
+
76
+ Cache files are named following the pattern `${package_name}_{factory_address}.csv`.
77
+
78
+ ---
29
79
 
30
80
  ### `onupdate(callback, params)`
31
- - **Description**: Subscribes to new pairs appearing at the factory contract. It initially calls the callback with cached pairs and then polls for updates.
32
- - **Arguments**:
33
- - `callback`: (function) Called with an array of Pair Objects.
34
- - `params`: (Object) Same as `load()` plus:
35
- - `update_timeout`: (number) Polling interval in ms (default 5000).
36
- - **Returns**: `Function` An unsubscribe function to stop polling.
37
-
38
- ### Pair Object
39
- The pair object contains the following fields:
40
- - `id`: (number) The pair index.
41
- - `pair`: (string) The pair contract address.
42
- - `token0`: (string) The address of the first token in the pair.
43
- - `token1`: (string) The address of the second token in the pair.
44
-
45
- ## Usage
81
+ Continuous synchronization engine. Performs initial load and subsequently polls for new pairs.
82
+
83
+ **Parameters**
84
+ | Name | Type | Description | Default |
85
+ | :--- | :--- | :--- | :--- |
86
+ | `callback` | `function` | Invoked with updated `Pair[]` array. | **Required** |
87
+ | `params` | `object` | All options from `load()` plus `update_timeout`. | - |
88
+ | `update_timeout` | `number` | Polling interval in milliseconds. | `5000` |
89
+
90
+ **Returns**: `function` (Stop/Unsubscribe function)
91
+
92
+ ---
93
+
94
+ ### Schema: `Pair`
95
+ Standardized liquidity pool object.
96
+
97
+ | Property | Type | Description |
98
+ | :--- | :--- | :--- |
99
+ | `id` | `number` | Global index of the pair in the factory. |
100
+ | `pair` | `string` | Ethereum address of the liquidity pool. |
101
+ | `token0` | `string` | Address of the first asset. |
102
+ | `token1` | `string` | Address of the second asset. |
103
+
104
+ ---
105
+
106
+ ## Usage Example
46
107
  ```javascript
47
108
  const { load, onupdate } = require('uniswap-v2-loader')
109
+ const rl = require('readline')
48
110
 
49
- // Load initial set
50
- load({to: 10}).then(pairs =>
51
- pairs.forEach(({id, pair}) => console.log(`ID: ${id} | Pair: ${pair}`))
52
- )
53
111
 
54
- // Subscribe to new pairs (24/7 monitoring)
55
- const unsubscribe = onupdate(pairs => {
56
- console.log(`Pools count: ${pairs.length}`)
112
+ load({
113
+ factory: '0xC0AEe478e3658e2610c5F7A4A2E1777cE9e4f2Ac', // SushiSwap
114
+ to: 1000,
115
+ progress: (c, t) => {
116
+ rl.cursorTo(process.stdout, 0)
117
+ rl.clearLine(process.stdout, 0)
118
+ process.stdout.write(`Loaded: ${c} / ${t} (${(c/t*100).toFixed(2)}%)`)
119
+ }
120
+ }).then(pairs => {
121
+ console.log(`\nSuccessfully loaded ${pairs.length} SushiSwap pairs`)
57
122
  })
58
-
59
- // Stop monitoring if needed
60
- // unsubscribe()
61
123
  ```
package/calp-dark.svg ADDED
@@ -0,0 +1,3 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
2
+ <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)"/>
3
+ </svg>
package/calp-light.svg ADDED
@@ -0,0 +1,3 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
2
+ <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)"/>
3
+ </svg>
package/default_cache_filename.js CHANGED
@@ -4,7 +4,7 @@ const os = require('os')
4
4
  const home = os.homedir()
5
5
  const pkg = require('./package.json')
6
6
 
7
- module.exports = path.join(
7
+ module.exports = (factory) => path.join(
8
8
  ...(process.platform === 'win32'
9
9
  ? (env.LOCALAPPDATA || env.APPDATA)
10
10
  ? [env.LOCALAPPDATA || env.APPDATA]
@@ -15,5 +15,5 @@ module.exports = path.join(
15
15
  ? [env.XDG_CACHE_HOME]
16
16
  : [home, '.cache']
17
17
  ),
18
- pkg.name + '_pairs.csv'
18
+ `${pkg.name}_${factory.toLowerCase()}.csv`
19
19
  )
package/index.js CHANGED
@@ -13,7 +13,7 @@ const load = (params = {}) => {
13
13
  var {
14
14
  key = debug_key,
15
15
  factory = uniswap_v2_factory,
16
- filename = default_cache_filename,
16
+ filename,
17
17
  multicall_size = 50,
18
18
  from = 0,
19
19
  to,
@@ -21,6 +21,7 @@ const load = (params = {}) => {
21
21
  workers = max_workers,
22
22
  pairs,
23
23
  } = params
24
+ filename ??= default_cache_filename(factory)
24
25
  const client = createPublicClient({
25
26
  chain: mainnet,
26
27
  transport: http('https://eth-mainnet.g.alchemy.com/v2/' + key)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniswap-v2-loader",
3
- "version": "4.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "Uniswap v2 protocol loader",
5
5
  "keywords": [
6
6
  "uniswap-v2",
package/debug.js DELETED
@@ -1,3 +0,0 @@
1
- require('./index')
2
- //.all({to: 102, filename: 'test.csv', multicore: false})
3
- .all({multicore: false})