@steerprotocol/liquidity-meter 2.0.0 → 2.0.4

package/README.md

@@ -22,6 +22,15 @@ Install
 - As a package dependency:
   - `npm install @steerprotocol/liquidity-meter`
 
+Release Workflow
+
+- Releases are automated with `semantic-release` on pushes to `master` or `main`.
+- Commit messages are validated with `commitlint` using the Conventional Commits spec.
+- CI runs unit tests on Node.js 20 and 22, then enforces coverage thresholds on Node.js 22.
+- Required repository secrets:
+  - `NPM_TOKEN` for npm publishing.
+- GitHub releases use the default `GITHUB_TOKEN` provided by Actions.
+
 Library Usage
 
 ```js

package/bin/liquidity-depth.js

@@ -4,12 +4,10 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { execFile as _execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-const execFile = promisify(_execFile);
-import { parseAbi, getAddress } from 'viem';
+import { createPublicClient, parseAbi, getAddress, http as viemHttp } from 'viem';
 import {
   analyzePool,
+  findBlockNumbersForTimestamps,
   formatTimestampUTC,
   parseDurationArg,
   parsePercentBuckets,
@@ -263,9 +261,7 @@ async function runBatch(args) {
     if (!looksLikeAddress(t0 || '') || !looksLikeAddress(t1 || '') || !feeNum) return undefined;
     if (!rpcUrl) return undefined;
 
-    const { createMemoryClient, http } = await import('tevm');
-    const client = createMemoryClient({ fork: { transport: http(rpcUrl), blockTag: 'latest' }, loggingLevel: 'error' });
-    if (client.tevmReady) await client.tevmReady();
+    const client = createPublicClient({ transport: viemHttp(rpcUrl) });
     try {
       const pool = await client.readContract({ address: UNISWAP_V3_FACTORY, abi: FACTORY_ABI, functionName: 'getPool', args: [getAddress(t0), getAddress(t1), feeNum] });
       if (pool && pool !== '0x0000000000000000000000000000000000000000') return pool;
@@ -275,27 +271,6 @@ async function runBatch(args) {
     return undefined;
   }
 
-  // base args to pass through from CLI
-  const base = [];
-  if (args.percent) base.push('--percent', String(args.percent));
-  if (args.source) base.push('--source', String(args.source));
-  if (args.rpc) base.push('--rpc', String(args.rpc));
-  if (args.subgraph) base.push('--subgraph', String(args.subgraph));
-  if (Number.isFinite(args.token0USD)) base.push('--token0-usd', String(args.token0USD));
-  if (Number.isFinite(args.token1USD)) base.push('--token1-usd', String(args.token1USD));
-  if (Number.isFinite(args.assumeStable)) base.push('--assume-stable', String(args.assumeStable));
-  if (args.usdSizes) base.push('--usd-sizes', String(args.usdSizes));
-  if (args.prices) base.push('--prices', String(args.prices));
-  if (args.reserveLimit) base.push('--reserve-limit', String(args.reserveLimit));
-  if (args.json) base.push('--json');
-  if (args.debug) base.push('--debug');
-  if (args.block) base.push('--block', String(args.block));
-  if (args.timestamp) base.push('--timestamp', String(args.timestamp));
-  if (args.owner) base.push('--owner', String(args.owner));
-  if (Number.isFinite(args.withdrawPct)) base.push('--withdraw-pct', String(args.withdrawPct));
-  if (args.withdrawShares) base.push('--withdraw-shares', String(args.withdrawShares));
-
-  const scriptPath = process.argv[1];
   for (let idx = 0; idx < rows.length; idx++) {
     const row = rows[idx];
     let pool = pick(row, ['pool', 'address', 'pool_address', 'id', 'Pool', 'Address', 'contract_address', 'contract address', 'pair_address', 'pair address']);
@@ -316,36 +291,29 @@ async function runBatch(args) {
       continue;
     }
 
-    const per = [...base];
-    const rpcs = pick(row, ['rpc', 'RPC', 'rpc_url', 'RPC_URL']);
-    if (rpcs) per.push('--rpc', rpcs);
-    const source = pick(row, ['source', 'Source']);
-    if (source) per.push('--source', source);
-    const percent = pick(row, ['percent', 'Percents', 'buckets']);
-    if (percent) per.push('--percent', percent);
-    const blockOverride = pick(row, ['block', 'Block', 'block_number', 'block number']);
-    if (blockOverride) per.push('--block', blockOverride);
-    const tsOverride = pick(row, ['timestamp', 'Timestamp', 'time', 'Time']);
-    if (tsOverride) per.push('--timestamp', tsOverride);
-    const token0USD = pick(row, ['token0_usd', 'token0-usd', 'token0USD']);
-    const token1USD = pick(row, ['token1_usd', 'token1-usd', 'token1USD']);
-    if (token0USD) per.push('--token0-usd', String(token0USD));
-    if (token1USD) per.push('--token1-usd', String(token1USD));
-    const usdSizes = pick(row, ['usd_sizes', 'usd-sizes', 'usdSizes']);
-    if (usdSizes) per.push('--usd-sizes', usdSizes);
-    const assumeStable = pick(row, ['assume_stable', 'assume-stable', 'assumeStable']);
-    if (assumeStable != null) per.push('--assume-stable', String(assumeStable));
-    const prices = pick(row, ['prices', 'Prices']);
-    if (prices) per.push('--prices', String(prices));
-
-    const vault = pick(row, ['vault', 'Vault', 'vault_address', 'VaultAddress', 'vault address', 'strategy']);
-    if (vault) per.push('--vault', vault);
-    const owner = pick(row, ['owner', 'Owner', 'owner_address', 'owner address', 'withdraw_owner', 'withdraw owner', 'account', 'user', 'recipient', 'to']);
-    if (owner) per.push('--owner', owner);
-    const wpct = pick(row, ['withdraw_pct', 'withdraw-pct', 'withdraw percent', 'withdraw_percent', 'withdrawPercentage', 'withdrawPercent', 'pct_withdraw', 'percent_withdraw']);
-    if (wpct) per.push('--withdraw-pct', String(wpct));
-    const wshares = pick(row, ['withdraw_shares', 'withdraw-shares', 'withdraw shares', 'withdrawShares', 'shares_to_withdraw', 'withdraw_share_amount']);
-    if (wshares) per.push('--withdraw-shares', String(wshares));
+    const rowArgs = {
+      ...args,
+      pool,
+      rpc: pick(row, ['rpc', 'RPC', 'rpc_url', 'RPC_URL']) || args.rpc,
+      source: pick(row, ['source', 'Source']) || args.source,
+      percent: pick(row, ['percent', 'Percents', 'buckets']) || args.percent,
+      block: pick(row, ['block', 'Block', 'block_number', 'block number']) || args.block,
+      timestamp: pick(row, ['timestamp', 'Timestamp', 'time', 'Time']) || args.timestamp,
+      token0USD: pick(row, ['token0_usd', 'token0-usd', 'token0USD']) != null ? Number(pick(row, ['token0_usd', 'token0-usd', 'token0USD'])) : args.token0USD,
+      token1USD: pick(row, ['token1_usd', 'token1-usd', 'token1USD']) != null ? Number(pick(row, ['token1_usd', 'token1-usd', 'token1USD'])) : args.token1USD,
+      usdSizes: pick(row, ['usd_sizes', 'usd-sizes', 'usdSizes']) || args.usdSizes,
+      assumeStable: pick(row, ['assume_stable', 'assume-stable', 'assumeStable']) != null ? Number(pick(row, ['assume_stable', 'assume-stable', 'assumeStable'])) : args.assumeStable,
+      prices: pick(row, ['prices', 'Prices']) || args.prices,
+      vault: pick(row, ['vault', 'Vault', 'vault_address', 'VaultAddress', 'vault address', 'strategy']) || args.vault,
+      owner: pick(row, ['owner', 'Owner', 'owner_address', 'owner address', 'withdraw_owner', 'withdraw owner', 'account', 'user', 'recipient', 'to']) || args.owner,
+      withdrawPct: pick(row, ['withdraw_pct', 'withdraw-pct', 'withdraw percent', 'withdraw_percent', 'withdrawPercentage', 'withdrawPercent', 'pct_withdraw', 'percent_withdraw']) != null ? Number(pick(row, ['withdraw_pct', 'withdraw-pct', 'withdraw percent', 'withdraw_percent', 'withdrawPercentage', 'withdrawPercent', 'pct_withdraw', 'percent_withdraw'])) : args.withdrawPct,
+      withdrawShares: pick(row, ['withdraw_shares', 'withdraw-shares', 'withdraw shares', 'withdrawShares', 'shares_to_withdraw', 'withdraw_share_amount']) || args.withdrawShares,
+    };
+
+    const wpct = rowArgs.withdrawPct;
+    const wshares = rowArgs.withdrawShares;
+    const vault = rowArgs.vault;
+    const owner = rowArgs.owner;
 
     if (args.debug) {
       const dbg = [];
@@ -356,20 +324,14 @@ async function runBatch(args) {
       if (dbg.length) console.error(`[batch] row ${idx + 1} overrides: ${dbg.join(' ')}`);
     }
 
-    const argsArr = [scriptPath, '--pool', pool, ...per];
     try {
-      const { stdout, stderr } = await execFile(process.execPath, argsArr, { env: process.env, maxBuffer: 5 * 1024 * 1024 });
       const baseName = `${pool.toLowerCase()}`;
       const file = path.join(outdir, `${baseName}.${args.json ? 'json' : 'txt'}`);
-      const cleaned = cleanReportOutput(stdout);
-      await fs.writeFile(file, cleaned, 'utf8');
-      if (args.debug && stderr) {
-        // Forward child's debug logs to parent stderr
-        process.stderr.write(stderr);
-      }
+      const output = await runSingleInvocation(rowArgs);
+      await fs.writeFile(file, output, 'utf8');
       console.log(`Wrote: ${file}`);
     } catch (err) {
-      const errMsg = String(err?.stderr || err?.stdout || err?.message || err);
+      const errMsg = String(err?.stack || err?.message || err);
       const errFile = path.join(outdir, `error-${pool.toLowerCase()}.txt`);
       await fs.writeFile(errFile, errMsg, 'utf8');
       console.error(`Failed row ${idx + 1} (${pool}): ${err?.message || err}`);
@@ -378,41 +340,6 @@ async function runBatch(args) {
   }
 }
 
-function parseChildJsonOutput(raw) {
-  // First, strip known noisy lines from stdout (e.g., tevm logs, hex chainId)
-  const cleaned = cleanReportOutput(String(raw ?? ''));
-  const trimmed = cleaned.trim();
-  if (!trimmed) return null;
-  try {
-    return JSON.parse(trimmed);
-  } catch (err) {
-    // Try to recover by locating a likely JSON block. Prefer the last complete
-    // object/array, since noise often appears before the payload.
-    const lastObj = trimmed.lastIndexOf('{');
-    const lastArr = trimmed.lastIndexOf('[');
-    const start = Math.max(lastObj, lastArr);
-    if (start >= 0) {
-      const endChar = trimmed[start] === '[' ? ']' : '}';
-      const end = trimmed.lastIndexOf(endChar);
-      if (end > start) {
-        const slice = trimmed.slice(start, end + 1).trim();
-        if (slice) {
-          try {
-            return JSON.parse(slice);
-          } catch (_) {
-            // fall through to error reporting below
-          }
-        }
-      }
-    }
-    const snippet = trimmed.length > 240 ? `${trimmed.slice(0, 240)}…` : trimmed;
-    const message = `${err?.message || err}. Child output: ${snippet}`;
-    const outErr = err instanceof Error ? err : new Error(String(message));
-    if (outErr instanceof Error) outErr.message = message;
-    throw outErr;
-  }
-}
-
 async function runTimeSeries(args) {
   if (!args.pool) {
     console.error('Time-series mode requires --pool');
@@ -511,6 +438,11 @@ async function runTimeSeries(args) {
     console.error('No timestamps resolved for time-series mode');
     process.exit(1);
   }
+  const resolvedBlocks = await findBlockNumbersForTimestamps({
+    rpcUrl: args.rpc,
+    timestamps,
+    debug: !!args.debug,
+  });
 
   if (!args.json) {
     const startIso = formatTimestampUTC(BigInt(tsStrings[0]));
@@ -519,60 +451,33 @@ async function runTimeSeries(args) {
     console.log(`Time-series: ${tsStrings.length} snapshots from ${startIso || tsStrings[0]} to ${endIso || tsStrings[tsStrings.length - 1]} every ~${intervalHuman}`);
   }
 
-  const base = [];
-  if (args.percent) base.push('--percent', String(args.percent));
-  if (args.source) base.push('--source', String(args.source));
-  if (args.rpc) base.push('--rpc', String(args.rpc));
-  if (args.subgraph) base.push('--subgraph', String(args.subgraph));
-  if (Number.isFinite(args.token0USD)) base.push('--token0-usd', String(args.token0USD));
-  if (Number.isFinite(args.token1USD)) base.push('--token1-usd', String(args.token1USD));
-  if (Number.isFinite(args.assumeStable)) base.push('--assume-stable', String(args.assumeStable));
-  if (args.usdSizes) base.push('--usd-sizes', String(args.usdSizes));
-  if (args.prices) base.push('--prices', String(args.prices));
-  if (args.reserveLimit) base.push('--reserve-limit', String(args.reserveLimit));
-  if (args.json) base.push('--json');
-  if (args.debug) base.push('--debug');
-  if (args.owner) base.push('--owner', String(args.owner));
-  if (Number.isFinite(args.withdrawPct)) base.push('--withdraw-pct', String(args.withdrawPct));
-  if (args.withdrawShares) base.push('--withdraw-shares', String(args.withdrawShares));
-  if (args.vault) base.push('--vault', String(args.vault));
-  if (args.outdir) base.push('--outdir', String(args.outdir));
-
-  const scriptPath = process.argv[1];
   const jsonResults = [];
   for (let i = 0; i < tsStrings.length; i++) {
     const tsStr = tsStrings[i];
-    const perArgs = [scriptPath, '--pool', args.pool, '--timestamp', tsStr, ...base];
+    const pointArgs = {
+      ...args,
+      timestamp: undefined,
+      block: resolvedBlocks[i].toString(),
+    };
     const label = formatTimestampUTC(BigInt(tsStr)) || tsStr;
     if (!args.json) {
       console.log(`\n=== ${label} (unix ${tsStr}) ===`);
     }
     try {
-      const { stdout, stderr } = await execFile(process.execPath, perArgs, { env: process.env, maxBuffer: 5 * 1024 * 1024 });
+      const output = await runSingleInvocation(pointArgs);
       if (args.json) {
-        const text = stdout.trim();
+        const text = output.trim();
         if (text) {
-          try {
-            jsonResults.push(parseChildJsonOutput(text));
-          } catch (err) {
-            if (args.debug && stderr) process.stderr.write(stderr);
-            console.error(`Failed to parse JSON for timestamp ${tsStr}: ${err?.message || err}`);
-            console.error('Raw child stdout:');
-            console.error(text);
-            process.exit(1);
-          }
+          jsonResults.push(JSON.parse(text));
         } else {
           jsonResults.push(null);
         }
       } else {
-        process.stdout.write(stdout);
-        if (!stdout.endsWith('\n')) console.log('');
+        process.stdout.write(output);
+        if (!output.endsWith('\n')) console.log('');
       }
-      if (args.debug && stderr) process.stderr.write(stderr);
     } catch (err) {
       console.error(`Time-series run failed for timestamp ${tsStr}: ${err?.message || err}`);
-      const errText = err?.stderr || err?.stdout;
-      if (errText) console.error(String(errText).trim());
       process.exit(1);
     }
   }
@@ -582,66 +487,29 @@ async function runTimeSeries(args) {
   }
 }
 
-// Strip noisy logs (e.g., TEVM warnings) from report files while preserving CLI output
-function cleanReportOutput(s) {
+function captureConsoleOutput(run) {
+  const lines = [];
+  const original = console.log;
+  console.log = (...args) => {
+    lines.push(args.join(' '));
+  };
   try {
-    const lines = String(s || '').split(/\r?\n/);
-    const out = [];
-    for (const line of lines) {
-      if (!line) { out.push(line); continue; }
-      // Filter known noisy patterns
-      if (line.includes('"name":"@tevm/')) continue; // TEVM structured logs
-      if (/\bEIP-7702\b/i.test(line)) continue;       // EIP-7702 warning block
-      if (/^\s*\{\s*chainId\s*:/i.test(line)) continue; // stray chainId object
-      if (/^\s*0x[0-9a-fA-F]+\s*$/.test(line)) continue;  // bare hex line
-      out.push(line);
-    }
-    // Trim leading empty lines left by filtering
-    while (out.length && out[0].trim() === '') out.shift();
-    return out.join('\n');
-  } catch (_) {
-    return s;
+    run();
+  } finally {
+    console.log = original;
   }
+  return lines.length ? `${lines.join('\n')}\n` : '';
 }
 
-async function main() {
-  const args = parseArgs(process.argv);
-  if (args.version) {
-    console.log('liquidity-depth 0.1.0');
-    return;
-  }
-  if (args.help || (!args.pool && !args.csv)) {
-    printHelp();
-    if (!args.pool && !args.csv) process.exitCode = 1;
-    return;
-  }
-
-  if (args.csv) {
-    await runBatch(args);
-    return;
-  }
-
-  const wantsTimeSeries =
-    args.timeStart != null ||
-    args.timeEnd != null ||
-    args.timeInterval != null ||
-    args.timeWindow != null ||
-    args.timeCount != null;
-  if (wantsTimeSeries) {
-    await runTimeSeries(args);
-    return;
-  }
-
+async function executeSingle(args) {
   let percentBuckets;
   try {
     percentBuckets = parsePercentBuckets(args.percent);
   } catch (e) {
-    console.error(`Invalid --percent value: ${e?.message || e}`);
-    process.exit(1);
+    throw new Error(`Invalid --percent value: ${e?.message || e}`);
   }
   if (!percentBuckets.length) {
-    console.error('No valid percent buckets parsed.');
-    process.exit(1);
+    throw new Error('No valid percent buckets parsed.');
   }
 
   const wantsWithdraw =
@@ -650,8 +518,7 @@ async function main() {
   let sharedBlockTag;
   if (wantsWithdraw) {
     if (!args.rpc) {
-      console.error('Missing --rpc (or RPC_URL env) for tevm source.');
-      process.exit(1);
+      throw new Error('Missing --rpc (or RPC_URL env) for tevm source.');
     }
     const blockContext = await resolveAnalysisBlockContext({
       block: args.block,
@@ -667,36 +534,24 @@ async function main() {
   }
 
   let before;
-  try {
-    before = await analyzePool({
-      poolAddress: args.pool,
-      percentBuckets,
-      source: args.source,
-      rpcUrl: args.rpc,
-      subgraphUrl: args.subgraph,
-      token0USD: args.token0USD,
-      token1USD: args.token1USD,
-      assumeStable: args.assumeStable,
-      usdSizes: args.usdSizes,
-      prices: args.prices,
-      reserveLimit: args.reserveLimit,
-      block: args.block,
-      timestamp: args.timestamp,
-      debug: args.debug,
-      client: sharedClient,
-      blockTag: sharedBlockTag,
-    });
-  } catch (e) {
-    if (
-      args.timestamp != null &&
-      args.rpc == null &&
-      String(e?.message || '').includes('--timestamp requires --rpc')
-    ) {
-      console.error('--timestamp requires --rpc (or RPC_URL env) to resolve block number');
-      process.exit(1);
-    }
-    throw e;
-  }
+  before = await analyzePool({
+    poolAddress: args.pool,
+    percentBuckets,
+    source: args.source,
+    rpcUrl: args.rpc,
+    subgraphUrl: args.subgraph,
+    token0USD: args.token0USD,
+    token1USD: args.token1USD,
+    assumeStable: args.assumeStable,
+    usdSizes: args.usdSizes,
+    prices: args.prices,
+    reserveLimit: args.reserveLimit,
+    block: args.block,
+    timestamp: args.timestamp,
+    debug: args.debug,
+    client: sharedClient,
+    blockTag: sharedBlockTag,
+  });
 
   let after = null;
   if (before.usedSource === 'tevm' && wantsWithdraw) {
@@ -734,6 +589,10 @@ async function main() {
     }
   }
 
+  return { before, after };
+}
+
+function renderSingle(args, before, after) {
   if (args.json) {
     const output = after
       ? {
@@ -741,15 +600,64 @@ async function main() {
           after: serializeAnalysis(args, after),
         }
       : serializeAnalysis(args, before);
-    console.log(JSON.stringify(output, null, 2));
+    return `${JSON.stringify(output, null, 2)}\n`;
+  }
+  return captureConsoleOutput(() => {
+    printAnalysisSummary(args, before);
+    if (after) {
+      console.log('');
+      console.log('--- After Withdraw ---');
+      printAnalysisSummary(args, after);
+    }
+  });
+}
+
+async function runSingleInvocation(args) {
+  const { before, after } = await executeSingle(args);
+  return renderSingle(args, before, after);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.version) {
+    console.log('liquidity-depth 0.1.0');
+    return;
+  }
+  if (args.help || (!args.pool && !args.csv)) {
+    printHelp();
+    if (!args.pool && !args.csv) process.exitCode = 1;
     return;
   }
 
-  printAnalysisSummary(args, before);
-  if (after) {
-    console.log('');
-    console.log('--- After Withdraw ---');
-    printAnalysisSummary(args, after);
+  if (args.csv) {
+    await runBatch(args);
+    return;
+  }
+
+  const wantsTimeSeries =
+    args.timeStart != null ||
+    args.timeEnd != null ||
+    args.timeInterval != null ||
+    args.timeWindow != null ||
+    args.timeCount != null;
+  if (wantsTimeSeries) {
+    await runTimeSeries(args);
+    return;
+  }
+
+  try {
+    const output = await runSingleInvocation(args);
+    process.stdout.write(output);
+  } catch (e) {
+    if (
+      args.timestamp != null &&
+      args.rpc == null &&
+      String(e?.message || '').includes('--timestamp requires --rpc')
+    ) {
+      console.error('--timestamp requires --rpc (or RPC_URL env) to resolve block number');
+      process.exit(1);
+    }
+    throw e;
   }
 }
 

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@steerprotocol/liquidity-meter",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "private": false,
   "description": "CLI to compute Uniswap v3 market depth bands using real on-chain/subgraph data",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SteerProtocol/liquidity-meter.git"
+  },
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -17,6 +21,9 @@
     "README.md",
     "templates"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
     "liquidity-depth": "bin/liquidity-depth.js"
   },
@@ -25,7 +32,19 @@
   },
   "scripts": {
     "start": "node bin/liquidity-depth.js --help",
-    "test": "node --test"
+    "test": "node --test",
+    "test:coverage": "node ./scripts/check-coverage.mjs",
+    "lint:commits": "commitlint --from HEAD~1 --to HEAD",
+    "release": "semantic-release"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.5.0",
+    "@commitlint/config-conventional": "20.5.0",
+    "@semantic-release/commit-analyzer": "13.0.1",
+    "@semantic-release/github": "11.0.6",
+    "@semantic-release/npm": "13.1.3",
+    "@semantic-release/release-notes-generator": "14.1.0",
+    "semantic-release": "25.0.3"
   },
   "dependencies": {
     "axios": "1.7.7",

package/src/api.js

@@ -5,6 +5,19 @@ import {
 } from './depth.js';
 import { fetchPoolSnapshot as fetchFromSubgraph } from './uniswapv3-subgraph.js';
 
+const chainIdByRpcUrl = new Map();
+const publicClientByRpcUrl = new Map();
+
+function getCachedPublicClient(rpcUrl) {
+  if (!rpcUrl) return null;
+  let client = publicClientByRpcUrl.get(rpcUrl);
+  if (!client) {
+    client = createPublicClient({ transport: viemHttp(rpcUrl) });
+    publicClientByRpcUrl.set(rpcUrl, client);
+  }
+  return client;
+}
+
 export function parsePercentBuckets(input = '1,2,5,10') {
   if (Array.isArray(input)) {
     return input
@@ -101,28 +114,44 @@ export async function findBlockNumberForTimestamp({
   rpcUrl,
   targetTimestampSec,
   debug = false,
+  client,
+  bounds,
+  blockCache,
 }) {
   if (!rpcUrl) throw new Error('RPC URL required to resolve timestamp');
-  const client = createPublicClient({ transport: viemHttp(rpcUrl) });
-  const latestNumber = await client.getBlockNumber();
-  const latestBlock = await client.getBlock({ blockNumber: latestNumber });
+  const resolvedClient = client || getCachedPublicClient(rpcUrl);
+  const cache = blockCache || new Map();
+  const readBlock = async (blockNumber) => {
+    const key = blockNumber.toString();
+    if (cache.has(key)) return cache.get(key);
+    const block = await resolvedClient.getBlock({ blockNumber });
+    cache.set(key, block);
+    return block;
+  };
+  const latestNumber = bounds?.latestNumber ?? await resolvedClient.getBlockNumber();
+  const latestBlock = bounds?.latestBlock ?? await readBlock(latestNumber);
   if (!latestBlock || latestBlock.timestamp == null) {
     throw new Error('Latest block did not include a timestamp');
   }
   const latestTs = latestBlock.timestamp;
-  const genesis = await client.getBlock({ blockNumber: 0n });
+  const genesis = bounds?.genesisBlock ?? await readBlock(0n);
   if (!genesis || genesis.timestamp == null) {
     throw new Error('Genesis block did not include a timestamp');
   }
   if (targetTimestampSec <= genesis.timestamp) return 0n;
   if (targetTimestampSec >= latestTs) return latestBlock.number;
 
-  let lo = 0n;
+  let lo = bounds?.loBlock?.number ?? 0n;
+  let loTimestamp = bounds?.loBlock?.timestamp ?? genesis.timestamp;
+  if (loTimestamp > targetTimestampSec) {
+    lo = 0n;
+    loTimestamp = genesis.timestamp;
+  }
   let hi = latestBlock.number;
-  let best = genesis.number ?? 0n;
+  let best = loTimestamp <= targetTimestampSec ? lo : (genesis.number ?? 0n);
   for (let iter = 0; iter < 80 && lo <= hi; iter++) {
     const mid = (lo + hi) >> 1n;
-    const block = await client.getBlock({ blockNumber: mid });
+    const block = await readBlock(mid);
     if (!block || block.timestamp == null) {
       hi = mid - 1n;
       continue;
@@ -144,12 +173,54 @@ export async function findBlockNumberForTimestamp({
   return best;
 }
 
+export async function findBlockNumbersForTimestamps({
+  rpcUrl,
+  timestamps,
+  debug = false,
+  client,
+}) {
+  if (!timestamps?.length) return [];
+  const resolvedClient = client || getCachedPublicClient(rpcUrl);
+  const blockCache = new Map();
+  const latestNumber = await resolvedClient.getBlockNumber();
+  const latestBlock = await resolvedClient.getBlock({ blockNumber: latestNumber });
+  const genesisBlock = await resolvedClient.getBlock({ blockNumber: 0n });
+  blockCache.set(latestNumber.toString(), latestBlock);
+  blockCache.set('0', genesisBlock);
+
+  let previousBlock = genesisBlock;
+  const out = [];
+  for (const timestamp of timestamps) {
+    const blockNumber = await findBlockNumberForTimestamp({
+      rpcUrl,
+      targetTimestampSec: timestamp,
+      debug,
+      client: resolvedClient,
+      bounds: {
+        latestNumber,
+        latestBlock,
+        genesisBlock,
+        loBlock: previousBlock,
+      },
+      blockCache,
+    });
+    const resolvedBlock =
+      blockCache.get(blockNumber.toString()) ||
+      await resolvedClient.getBlock({ blockNumber });
+    blockCache.set(blockNumber.toString(), resolvedBlock);
+    previousBlock = resolvedBlock;
+    out.push(blockNumber);
+  }
+  return out;
+}
+
 export async function resolveAnalysisBlockContext({
   block,
   timestamp,
   rpcUrl,
   debug = false,
   blockTag,
+  client,
 }) {
   let blockNumber;
   let blockSource;
@@ -174,6 +245,7 @@ export async function resolveAnalysisBlockContext({
       rpcUrl,
       targetTimestampSec: timestampSec,
       debug,
+      client,
     });
     blockSource = '--timestamp';
   }
@@ -221,13 +293,18 @@ function usdToRaw(usd, usdPrice, decimals) {
 async function resolveChainId({ client, rpcUrl, blockTag }) {
   try {
     if (client && typeof client.getChainId === 'function') {
-      return await client.getChainId();
+      const chainId = await client.getChainId();
+      if (rpcUrl) chainIdByRpcUrl.set(rpcUrl, chainId);
+      return chainId;
     }
   } catch (_) {}
   try {
     if (!rpcUrl) return undefined;
-    const tempClient = createPublicClient({ transport: viemHttp(rpcUrl) });
-    return await tempClient.getChainId();
+    if (chainIdByRpcUrl.has(rpcUrl)) return chainIdByRpcUrl.get(rpcUrl);
+    const tempClient = getCachedPublicClient(rpcUrl);
+    const chainId = await tempClient.getChainId();
+    chainIdByRpcUrl.set(rpcUrl, chainId);
+    return chainId;
   } catch (_) {
     return undefined;
   }
@@ -425,6 +502,7 @@ export async function analyzePool(input = {}) {
     rpcUrl: options.rpcUrl,
     debug: options.debug,
     blockTag: options.blockTag,
+    client: options.client,
   });
 
   let client = options.client;
@@ -443,7 +521,7 @@ export async function analyzePool(input = {}) {
       }
       const { fetchPoolSnapshotViem } = await import('./viem-onchain.js');
       if (!client) {
-        client = createPublicClient({ transport: viemHttp(options.rpcUrl) });
+        client = getCachedPublicClient(options.rpcUrl);
       }
       usedSource = 'tevm';
       snap = await fetchPoolSnapshotViem({

package/src/viem-onchain.js

@@ -1,8 +1,14 @@
-// On-chain fetcher for Uniswap v3 pools using a viem public client
-// - Reads pool slot0, liquidity, fee, tickSpacing, token0/1 addresses + ERC20 decimals/symbols
-// - Enumerates initialized ticks via tickBitmap within a bounded range
+// On-chain fetcher for Uniswap v3 pools using a viem public client.
+// It prefers JSON-RPC batching when an RPC URL is available to reduce HTTP round trips.
 
-import { createPublicClient, getAddress, http, parseAbi } from 'viem';
+import {
+  createPublicClient,
+  decodeFunctionResult,
+  encodeFunctionData,
+  getAddress,
+  http,
+  parseAbi,
+} from 'viem';
 
 const UNISWAP_POOL_ABI = parseAbi([
   'function slot0() view returns (uint160 sqrtPriceX96, int24 tick, uint16 observationIndex, uint16 observationCardinality, uint16 observationCardinalityNext, uint8 feeProtocol, bool unlocked)',
@@ -32,6 +38,124 @@ const ERC20_ABI = parseAbi([
 const GLOBAL_STATE_SELECTOR = '0xe76c01e4';
 const TWO_256 = 1n << 256n;
 const TWO_255 = 1n << 255n;
+const poolStaticCache = new Map();
+const tokenMetaCache = new Map();
+
+function toRpcBlockTag(blockTag) {
+  if (typeof blockTag === 'bigint') return `0x${blockTag.toString(16)}`;
+  if (typeof blockTag === 'number') return `0x${blockTag.toString(16)}`;
+  return blockTag ?? 'latest';
+}
+
+async function batchRpcRequest({ rpcUrl, requests }) {
+  if (!rpcUrl) throw new Error('rpcUrl is required for batched RPC requests');
+  const res = await fetch(rpcUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(requests),
+  });
+  if (!res.ok) {
+    throw new Error(`Batched RPC request failed with HTTP ${res.status}`);
+  }
+  const body = await res.json();
+  const responses = Array.isArray(body) ? body : [body];
+  const byId = new Map(responses.map((entry) => [entry.id, entry]));
+  return requests.map((request) => {
+    const response = byId.get(request.id);
+    if (!response) {
+      throw new Error(`Missing batched RPC response for id ${request.id}`);
+    }
+    if (response.error) {
+      throw new Error(response.error.message || JSON.stringify(response.error));
+    }
+    return response.result;
+  });
+}
+
+async function readContractsBatch({ rpcUrl, blockTag, address, abi, calls }) {
+  const normalizedAddress = getAddress(address);
+  return readContractCallsBatch({
+    rpcUrl,
+    blockTag,
+    calls: calls.map((call) => ({ ...call, address: normalizedAddress, abi })),
+  });
+}
+
+async function readContractCallsBatch({ rpcUrl, blockTag, calls }) {
+  const rpcBlockTag = toRpcBlockTag(blockTag);
+  const requests = calls.map((call, index) => ({
+    jsonrpc: '2.0',
+    id: index + 1,
+    method: 'eth_call',
+    params: [
+      {
+        to: getAddress(call.address),
+        data: encodeFunctionData({
+          abi: call.abi,
+          functionName: call.functionName,
+          args: call.args,
+        }),
+      },
+      rpcBlockTag,
+    ],
+  }));
+  const results = await batchRpcRequest({ rpcUrl, requests });
+  return results.map((result, index) =>
+    decodeFunctionResult({
+      abi: calls[index].abi,
+      functionName: calls[index].functionName,
+      data: result,
+    })
+  );
+}
+
+async function readContracts({ client, rpcUrl, blockTag, address, abi, calls, readBlockParams }) {
+  if (rpcUrl) {
+    try {
+      return await readContractsBatch({ rpcUrl, blockTag, address, abi, calls });
+    } catch (_) {}
+  }
+  return Promise.all(
+    calls.map((call) =>
+      client.readContract({
+        address,
+        abi,
+        functionName: call.functionName,
+        args: call.args,
+        ...readBlockParams,
+      })
+    )
+  );
+}
+
+async function readRawCall({ client, rpcUrl, to, data, blockTag }) {
+  if (rpcUrl) {
+    try {
+      const [result] = await batchRpcRequest({
+        rpcUrl,
+        requests: [
+          {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'eth_call',
+            params: [{ to, data }, toRpcBlockTag(blockTag)],
+          },
+        ],
+      });
+      return result;
+    } catch (_) {}
+  }
+  return client.transport.request({
+    method: 'eth_call',
+    params: [{ to, data }, toRpcBlockTag(blockTag)],
+  });
+}
+
+function chunk(array, size) {
+  const out = [];
+  for (let i = 0; i < array.length; i += size) out.push(array.slice(i, i + size));
+  return out;
+}
 
 function toSigned256(x) {
   return x >= TWO_255 ? x - TWO_256 : x;
@@ -115,57 +239,126 @@ export async function fetchPoolSnapshotViem({ poolAddress, rpcUrl, percentBucket
   let token0Addr;
   let token1Addr;
   let poolType = 'uniswap';
+  const poolCacheKey = pool.toLowerCase();
+  const cachedPoolStatic = poolStaticCache.get(poolCacheKey);
 
-  try {
-    const [slot0, L, fee, spacing, tok0, tok1] = await Promise.all([
-      c.readContract({ address: pool, abi: UNISWAP_POOL_ABI, functionName: 'slot0', ...readBlockParams }),
-      c.readContract({ address: pool, abi: UNISWAP_POOL_ABI, functionName: 'liquidity', ...readBlockParams }),
-      c.readContract({ address: pool, abi: UNISWAP_POOL_ABI, functionName: 'fee', ...readBlockParams }),
-      c.readContract({ address: pool, abi: UNISWAP_POOL_ABI, functionName: 'tickSpacing', ...readBlockParams }),
-      c.readContract({ address: pool, abi: UNISWAP_POOL_ABI, functionName: 'token0', ...readBlockParams }),
-      c.readContract({ address: pool, abi: UNISWAP_POOL_ABI, functionName: 'token1', ...readBlockParams }),
-    ]);
+  if (cachedPoolStatic?.poolType === 'uniswap') {
+    poolType = 'uniswap';
+    const [slot0, L] = await readContracts({
+      client: c,
+      rpcUrl,
+      blockTag,
+      address: pool,
+      abi: UNISWAP_POOL_ABI,
+      calls: [{ functionName: 'slot0' }, { functionName: 'liquidity' }],
+      readBlockParams,
+    });
     sqrtPriceX96 = slot0[0];
     tick = Number(slot0[1]);
     liquidity = L;
-    feePips = Number(fee);
-    tickSpacing = Number(spacing);
-    token0Addr = tok0;
-    token1Addr = tok1;
-  } catch (uniswapErr) {
+    feePips = cachedPoolStatic.feePips;
+    tickSpacing = cachedPoolStatic.tickSpacing;
+    token0Addr = cachedPoolStatic.token0Addr;
+    token1Addr = cachedPoolStatic.token1Addr;
+  } else if (cachedPoolStatic?.poolType === 'algebra') {
     poolType = 'algebra';
-    let globalState;
-    try {
-      const callResult = await c.transport.request({
-        method: 'eth_call',
-        params: [
-          { to: pool, data: GLOBAL_STATE_SELECTOR },
-          typeof blockTag === 'bigint'
-            ? `0x${blockTag.toString(16)}`
-            : typeof blockTag === 'number'
-              ? `0x${blockTag.toString(16)}`
-              : blockTag ?? 'latest',
-        ],
-      });
-      globalState = decodeAlgebraGlobalState(callResult);
-    } catch (algebraStateErr) {
-      const combined = new Error(`Failed to read pool state as Uniswap (slot0): ${uniswapErr?.message || uniswapErr}. Algebra globalState call also failed: ${algebraStateErr?.message || algebraStateErr}`);
-      combined.cause = { uniswap: uniswapErr, algebra: algebraStateErr };
-      throw combined;
-    }
-    const [L, spacing, tok0, tok1] = await Promise.all([
-      c.readContract({ address: pool, abi: ALGEBRA_POOL_ABI, functionName: 'liquidity', ...readBlockParams }),
-      c.readContract({ address: pool, abi: ALGEBRA_POOL_ABI, functionName: 'tickSpacing', ...readBlockParams }),
-      c.readContract({ address: pool, abi: ALGEBRA_POOL_ABI, functionName: 'token0', ...readBlockParams }),
-      c.readContract({ address: pool, abi: ALGEBRA_POOL_ABI, functionName: 'token1', ...readBlockParams }),
+    const [globalStateHex, L] = await Promise.all([
+      readRawCall({ client: c, rpcUrl, to: pool, data: GLOBAL_STATE_SELECTOR, blockTag }),
+      readContracts({
+        client: c,
+        rpcUrl,
+        blockTag,
+        address: pool,
+        abi: ALGEBRA_POOL_ABI,
+        calls: [{ functionName: 'liquidity' }],
+        readBlockParams,
+      }).then((results) => results[0]),
     ]);
+    const globalState = decodeAlgebraGlobalState(globalStateHex);
     sqrtPriceX96 = globalState.sqrtPriceX96;
     tick = globalState.tick;
     liquidity = L;
     feePips = globalState.feePips;
-    tickSpacing = Number(spacing);
-    token0Addr = tok0;
-    token1Addr = tok1;
+    tickSpacing = cachedPoolStatic.tickSpacing;
+    token0Addr = cachedPoolStatic.token0Addr;
+    token1Addr = cachedPoolStatic.token1Addr;
+  } else {
+    try {
+      const [slot0, L, fee, spacing, tok0, tok1] = await readContracts({
+        client: c,
+        rpcUrl,
+        blockTag,
+        address: pool,
+        abi: UNISWAP_POOL_ABI,
+        calls: [
+          { functionName: 'slot0' },
+          { functionName: 'liquidity' },
+          { functionName: 'fee' },
+          { functionName: 'tickSpacing' },
+          { functionName: 'token0' },
+          { functionName: 'token1' },
+        ],
+        readBlockParams,
+      });
+      sqrtPriceX96 = slot0[0];
+      tick = Number(slot0[1]);
+      liquidity = L;
+      feePips = Number(fee);
+      tickSpacing = Number(spacing);
+      token0Addr = tok0;
+      token1Addr = tok1;
+      poolStaticCache.set(poolCacheKey, {
+        poolType: 'uniswap',
+        feePips,
+        tickSpacing,
+        token0Addr,
+        token1Addr,
+      });
+    } catch (uniswapErr) {
+      poolType = 'algebra';
+      let globalState;
+      try {
+        const callResult = await readRawCall({
+          client: c,
+          rpcUrl,
+          to: pool,
+          data: GLOBAL_STATE_SELECTOR,
+          blockTag,
+        });
+        globalState = decodeAlgebraGlobalState(callResult);
+      } catch (algebraStateErr) {
+        const combined = new Error(`Failed to read pool state as Uniswap (slot0): ${uniswapErr?.message || uniswapErr}. Algebra globalState call also failed: ${algebraStateErr?.message || algebraStateErr}`);
+        combined.cause = { uniswap: uniswapErr, algebra: algebraStateErr };
+        throw combined;
+      }
+      const [L, spacing, tok0, tok1] = await readContracts({
+        client: c,
+        rpcUrl,
+        blockTag,
+        address: pool,
+        abi: ALGEBRA_POOL_ABI,
+        calls: [
+          { functionName: 'liquidity' },
+          { functionName: 'tickSpacing' },
+          { functionName: 'token0' },
+          { functionName: 'token1' },
+        ],
+        readBlockParams,
+      });
+      sqrtPriceX96 = globalState.sqrtPriceX96;
+      tick = globalState.tick;
+      liquidity = L;
+      feePips = globalState.feePips;
+      tickSpacing = Number(spacing);
+      token0Addr = tok0;
+      token1Addr = tok1;
+      poolStaticCache.set(poolCacheKey, {
+        poolType: 'algebra',
+        tickSpacing,
+        token0Addr,
+        token1Addr,
+      });
+    }
   }
 
   tickSpacing = Math.abs(Number(tickSpacing));
@@ -173,12 +366,66 @@ export async function fetchPoolSnapshotViem({ poolAddress, rpcUrl, percentBucket
     throw new Error('tickSpacing resolved to zero');
   }
 
-  const [dec0, sym0, dec1, sym1] = await Promise.all([
-    c.readContract({ address: token0Addr, abi: ERC20_ABI, functionName: 'decimals', ...readBlockParams }),
-    c.readContract({ address: token0Addr, abi: ERC20_ABI, functionName: 'symbol', ...readBlockParams }),
-    c.readContract({ address: token1Addr, abi: ERC20_ABI, functionName: 'decimals', ...readBlockParams }),
-    c.readContract({ address: token1Addr, abi: ERC20_ABI, functionName: 'symbol', ...readBlockParams }),
-  ]);
+  const token0Key = token0Addr.toLowerCase();
+  const token1Key = token1Addr.toLowerCase();
+  let token0Meta = tokenMetaCache.get(token0Key);
+  let token1Meta = tokenMetaCache.get(token1Key);
+
+  if (!token0Meta || !token1Meta) {
+    if (rpcUrl) {
+      const pendingCalls = [];
+      if (!token0Meta) {
+        pendingCalls.push(
+          { address: token0Addr, abi: ERC20_ABI, functionName: 'decimals' },
+          { address: token0Addr, abi: ERC20_ABI, functionName: 'symbol' }
+        );
+      }
+      if (!token1Meta) {
+        pendingCalls.push(
+          { address: token1Addr, abi: ERC20_ABI, functionName: 'decimals' },
+          { address: token1Addr, abi: ERC20_ABI, functionName: 'symbol' }
+        );
+      }
+      const results = await readContractCallsBatch({ rpcUrl, blockTag, calls: pendingCalls });
+      let offset = 0;
+      if (!token0Meta) {
+        token0Meta = { decimals: Number(results[offset]), symbol: results[offset + 1] };
+        tokenMetaCache.set(token0Key, token0Meta);
+        offset += 2;
+      }
+      if (!token1Meta) {
+        token1Meta = { decimals: Number(results[offset]), symbol: results[offset + 1] };
+        tokenMetaCache.set(token1Key, token1Meta);
+      }
+    } else {
+      if (!token0Meta) {
+        const [decimals, symbol] = await readContracts({
+          client: c,
+          rpcUrl,
+          blockTag,
+          address: token0Addr,
+          abi: ERC20_ABI,
+          calls: [{ functionName: 'decimals' }, { functionName: 'symbol' }],
+          readBlockParams,
+        });
+        token0Meta = { decimals: Number(decimals), symbol };
+        tokenMetaCache.set(token0Key, token0Meta);
+      }
+      if (!token1Meta) {
+        const [decimals, symbol] = await readContracts({
+          client: c,
+          rpcUrl,
+          blockTag,
+          address: token1Addr,
+          abi: ERC20_ABI,
+          calls: [{ functionName: 'decimals' }, { functionName: 'symbol' }],
+          readBlockParams,
+        });
+        token1Meta = { decimals: Number(decimals), symbol };
+        tokenMetaCache.set(token1Key, token1Meta);
+      }
+    }
+  }
 
   const far = Math.max(...percentBuckets);
   const delta = percentToTickDelta(far);
@@ -193,19 +440,45 @@ export async function fetchPoolSnapshotViem({ poolAddress, rpcUrl, percentBucket
   const ticks = [];
   const poolAbi = poolType === 'algebra' ? ALGEBRA_POOL_ABI : UNISWAP_POOL_ABI;
   const bitmapFn = poolType === 'algebra' ? 'tickTable' : 'tickBitmap';
-  for (let w = wordStart; w <= wordEnd; w++) {
-    // tickBitmap index is int16
-    const bitmap = await c.readContract({ address: pool, abi: poolAbi, functionName: bitmapFn, args: [BigInt(w)], ...readBlockParams });
+  const bitmapWords = [];
+  for (let w = wordStart; w <= wordEnd; w++) bitmapWords.push(w);
+  const bitmapResults = bitmapWords.length
+    ? await readContracts({
+      client: c,
+      rpcUrl,
+      blockTag,
+      address: pool,
+      abi: poolAbi,
+      calls: bitmapWords.map((w) => ({ functionName: bitmapFn, args: [BigInt(w)] })),
+      readBlockParams,
+    })
+    : [];
+  const tickIndexes = [];
+  for (let i = 0; i < bitmapWords.length; i++) {
+    const w = bitmapWords[i];
+    const bitmap = bitmapResults[i];
     if (bitmap === 0n) continue;
     for (let bit = 0; bit < 256; bit++) {
       if (((bitmap >> BigInt(bit)) & 1n) === 0n) continue;
       const compressed = w * 256 + bit;
       const t = compressed * tickSpacing;
       if (t < start || t > end) continue;
-      // Read tick data to get liquidityNet
-      const ret = await c.readContract({ address: pool, abi: poolAbi, functionName: 'ticks', args: [t], ...readBlockParams });
-      const liquidityNet = ret[1];
-      ticks.push({ index: t, liquidityNet: liquidityNet });
+      tickIndexes.push(t);
+    }
+  }
+
+  for (const tickBatch of chunk(tickIndexes, 128)) {
+    const tickResults = await readContracts({
+      client: c,
+      rpcUrl,
+      blockTag,
+      address: pool,
+      abi: poolAbi,
+      calls: tickBatch.map((tickIndex) => ({ functionName: 'ticks', args: [tickIndex] })),
+      readBlockParams,
+    });
+    for (let i = 0; i < tickBatch.length; i++) {
+      ticks.push({ index: tickBatch[i], liquidityNet: tickResults[i][1] });
     }
   }
 
@@ -215,11 +488,11 @@ export async function fetchPoolSnapshotViem({ poolAddress, rpcUrl, percentBucket
     liquidity,
     feePips,
     ticks: ticks.sort((a,b) => a.index - b.index),
-    token0: { decimals: Number(dec0), usdPrice: 0, symbol: sym0, id: token0Addr },
-    token1: { decimals: Number(dec1), usdPrice: 0, symbol: sym1, id: token1Addr },
+    token0: { decimals: token0Meta.decimals, usdPrice: 0, symbol: token0Meta.symbol, id: token0Addr },
+    token1: { decimals: token1Meta.decimals, usdPrice: 0, symbol: token1Meta.symbol, id: token1Addr },
     meta: {
-      token0: { decimals: Number(dec0), symbol: sym0, id: token0Addr },
-      token1: { decimals: Number(dec1), symbol: sym1, id: token1Addr },
+      token0: { decimals: token0Meta.decimals, symbol: token0Meta.symbol, id: token0Addr },
+      token1: { decimals: token1Meta.decimals, symbol: token1Meta.symbol, id: token1Addr },
       poolId: pool,
       range: { start, end },
       farPercent: far,