@steerprotocol/liquidity-meter 1.0.0 → 2.0.0

package/bin/liquidity-depth.js

@@ -0,0 +1,887 @@
+#!/usr/bin/env node
+
+// CLI for computing Uniswap v3 market depth bands with real data
+
+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 {
+  analyzePool,
+  formatTimestampUTC,
+  parseDurationArg,
+  parsePercentBuckets,
+  parseTimestampArg,
+  resolveAnalysisBlockContext,
+} from '../src/api.js';
+import { createForkClient, simulateVaultWithdraw, resolveViemChain } from '../src/withdraw.js';
+
+const UNISWAP_V3_FACTORY = '0x1F98431c8aD98523631AE4a59f267346ea31F984';
+const FACTORY_ABI = parseAbi([
+  'function getPool(address tokenA, address tokenB, uint24 fee) view returns (address)'
+]);
+
+function parseArgs(argv) {
+  const args = {
+    percent: '1,2,5,10',
+    subgraph: undefined,
+    source: 'tevm',
+    rpc: process.env.RPC_URL,
+    usdSizes: '1000,5000,10000,25000,50000,100000',
+    prices: process.env.PRICES_SOURCE || 'auto',
+    reserveLimit: Number(process.env.RESERVE_LIMIT) || 100,
+    csv: undefined,
+    outdir: 'reports',
+    // withdraw simulation
+    vault: undefined,
+    owner: process.env.OWNER,
+    withdrawPct: undefined,
+    withdrawShares: undefined,
+    block: undefined,
+    timestamp: undefined,
+    timeStart: undefined,
+    timeEnd: undefined,
+    timeInterval: undefined,
+    timeWindow: undefined,
+    timeCount: undefined,
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--pool' || a === '-p') args.pool = argv[++i];
+    else if (a === '--percent' || a === '-b') args.percent = argv[++i];
+    else if (a === '--subgraph' || a === '-s') args.subgraph = argv[++i];
+    else if (a === '--rpc' || a === '-r') args.rpc = argv[++i];
+    else if (a === '--source') args.source = argv[++i]; // tevm|subgraph|auto
+    else if (a === '--token0-usd') args.token0USD = Number(argv[++i]);
+    else if (a === '--token1-usd') args.token1USD = Number(argv[++i]);
+    else if (a === '--assume-stable') args.assumeStable = Number(argv[++i]); // 0 or 1
+    else if (a === '--usd-sizes') args.usdSizes = argv[++i];
+    else if (a === '--prices') args.prices = argv[++i]; // llama|coingecko|auto
+    // withdraw simulation flags
+    else if (a === '--vault') args.vault = argv[++i];
+    else if (a === '--owner') args.owner = argv[++i];
+    else if (a === '--withdraw-pct' || a === '--withdraw-percent') args.withdrawPct = Number(argv[++i]);
+    else if (a === '--withdraw-shares') args.withdrawShares = argv[++i];
+    else if (a === '--block') args.block = argv[++i];
+    else if (a === '--timestamp' || a === '--time') args.timestamp = argv[++i];
+    else if (a === '--time-start') args.timeStart = argv[++i];
+    else if (a === '--time-end') args.timeEnd = argv[++i];
+    else if (a === '--time-interval') args.timeInterval = argv[++i];
+    else if (a === '--time-window') args.timeWindow = argv[++i];
+    else if (a === '--time-count') args.timeCount = Number(argv[++i]);
+    else if (a === '--debug') args.debug = true;
+    else if (a === '--csv') args.csv = argv[++i];
+    else if (a === '--outdir') args.outdir = argv[++i];
+    else if (a === '--reserve-limit') args.reserveLimit = Number(argv[++i]);
+    else if (a === '--json' || a === '-j') args.json = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a === '--version' || a === '-v') args.version = true;
+    else if (!args.pool && /^0x[0-9a-fA-F]{40}$/.test(a)) args.pool = a;
+    else {
+      console.error(`Unknown arg: ${a}`);
+      args.help = true;
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+liquidity-depth — Uniswap v3 market depth bands
+
+Usage:
+  liquidity-depth --pool <POOL_ADDRESS> [--percent 1,2,5,10] [--source tevm|viem|subgraph|auto] [--rpc <URL>] [--block N] [--timestamp ISO|SECONDS]
+                 [--time-start ISO|SECONDS] [--time-end ISO|SECONDS] [--time-interval 1h] [--time-window 7d] [--time-count N]
+                 [--token0-usd N] [--token1-usd N] [--usd-sizes 1000,5000,...] [--json]
+  liquidity-depth --pool <POOL_ADDRESS> --vault <VAULT_ADDRESS> --owner <OWNER_ADDRESS> [--withdraw-pct N | --withdraw-shares <SHARES>] [same options]
+  liquidity-depth --csv <FILE.csv> [--outdir reports] [same options as above]
+
+Options:
+  -p, --pool       Uniswap v3 pool address (e.g., 0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8)
+  -b, --percent    Percent buckets, comma-separated (default: 1,2,5,10)
+  -s, --subgraph   Subgraph URL (default: Uniswap v3 mainnet)
+      --source     Data source: tevm|viem|subgraph|auto (default: tevm)
+  -r, --rpc        RPC URL (for on-chain fetching via tevm fork). Also reads RPC_URL env var
+      --token0-usd Override token0 USD price
+      --token1-usd Override token1 USD price
+      --assume-stable 0|1  Assume token index is $1 stable (fills missing USD)
+      --usd-sizes   Comma-separated USD sizes for price impact (default: 1000,5000,10000,25000,50000,100000)
+      --block       Fork/query state at the specified block number
+      --timestamp   Resolve a historical block by timestamp (seconds or ISO-8601); requires --rpc
+      --time-start  Beginning timestamp (inclusive) for time-series mode (seconds or ISO-8601)
+      --time-end    Ending timestamp (inclusive, default: now) for time-series mode
+      --time-interval  Step between snapshots in time-series mode (e.g., 1h, 30m; default: 1h)
+      --time-window    How far back from --time-end to start when --time-start omitted (e.g., 7d)
+      --time-count     Number of intervals to fetch (e.g., 168 for 7 days hourly); implies backwards from --time-end
+      --prices      Price source: reserve|dexscreener|llama|coingecko|auto (default: auto; env PRICES_SOURCE)
+      --reserve-limit  N  Limit for Reserve API (default: 100; env RESERVE_LIMIT)
+      --debug       Print debug logs to stderr for pricing/inference
+      --csv         CSV file with a header including a 'pool' or 'address' column
+      --outdir      Output directory for per-pool reports (default: reports)
+      --vault       Steer vault address (to simulate withdrawal)
+      --owner       Owner address whose shares are withdrawn (also reads OWNER env)
+      --withdraw-pct    Percent of owner's shares to withdraw (e.g., 25)
+      --withdraw-shares Raw share amount to withdraw (overrides --withdraw-pct)
+  -j, --json       Output machine-readable JSON
+  -h, --help       Show help
+  -v, --version    Show version
+`);
+}
+
+function looksLikeAddress(x) {
+  return typeof x === 'string' && /^0x[0-9a-fA-F]{40}$/.test(x.trim());
+}
+function extractFirstAddress(x) {
+  if (typeof x !== 'string') return undefined;
+  const m = x.match(/0x[0-9a-fA-F]{40}/);
+  return m ? m[0] : undefined;
+}
+function normKey(k) {
+  return String(k || '').toLowerCase().replace(/[ _-]+/g, '');
+}
+
+// Minimal CSV parser: returns array of row objects keyed by header.
+// Supports commas, quoted fields with double-quotes escaping.
+function parseCSV(content) {
+  const outRows = [];
+  let i = 0;
+  const len = content.length;
+  const fields = [];
+  function readLine() {
+    fields.length = 0;
+    let field = '';
+    let inQuotes = false;
+    let sawAny = false;
+    while (i < len) {
+      const ch = content[i++];
+      if (!inQuotes && (ch === '\n' || ch === '\r')) {
+        if (ch === '\r' && content[i] === '\n') i++; // CRLF
+        fields.push(field);
+        return true;
+      }
+      if (ch === '"') {
+        if (inQuotes) {
+          if (content[i] === '"') { field += '"'; i++; }
+          else { inQuotes = false; }
+        } else {
+          inQuotes = true;
+          sawAny = true;
+        }
+      } else if (ch === ',' && !inQuotes) {
+        fields.push(field);
+        field = '';
+        sawAny = true;
+      } else {
+        field += ch;
+        sawAny = true;
+      }
+    }
+    if (!sawAny && field === '') return false; // EOF after last newline
+    fields.push(field);
+    return true;
+  }
+  // read header
+  if (!readLine()) return [];
+  const header = fields.map((h) => h.trim());
+  while (readLine()) {
+    const obj = {};
+    for (let j = 0; j < header.length; j++) obj[header[j]] = (fields[j] ?? '').trim();
+    outRows.push(obj);
+  }
+  return outRows;
+}
+
+async function runBatch(args) {
+  const csvPath = args.csv;
+  const outdir = args.outdir || 'reports';
+  const data = await fs.readFile(csvPath, 'utf8');
+  const rows = parseCSV(data);
+  if (!rows.length) {
+    console.error('CSV is empty or could not be parsed. Expect a header row with a pool/address column.');
+    process.exit(1);
+  }
+  await fs.mkdir(outdir, { recursive: true });
+
+  const pick = (obj, names) => {
+    // try direct keys
+    for (const n of names) if (obj[n] != null && String(obj[n]).trim() !== '') return String(obj[n]).trim();
+    // try normalized keys
+    const map = Object.fromEntries(Object.keys(obj).map((k) => [normKey(k), k]));
+    for (const n of names) {
+      const key = map[normKey(n)];
+      if (key && obj[key] != null && String(obj[key]).trim() !== '') return String(obj[key]).trim();
+    }
+    return undefined;
+  };
+
+  function parseFeeToUint24(v) {
+    if (v == null) return undefined;
+    const s = String(v).trim();
+    if (!s) return undefined;
+    // raw number like 500, 3000, 10000
+    if (/^\d+$/.test(s)) {
+      const n = Number(s);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+    // like 30bps or 5 bps
+    const mBps = s.match(/([0-9]+(?:\.[0-9]+)?)\s*bps/i);
+    if (mBps) {
+      const n = Number(mBps[1]);
+      if (Number.isFinite(n)) return Math.round(n * 100);
+    }
+    // like 0.3% or 1 %
+    const mPct = s.match(/([0-9]+(?:\.[0-9]+)?)\s*%/);
+    if (mPct) {
+      const n = Number(mPct[1]);
+      if (Number.isFinite(n)) return Math.round(n * 1e4);
+    }
+    return undefined;
+  }
+
+  async function resolvePoolFromTokens(row, rpcUrl) {
+    // attempt to find token addresses + fee
+    let t0 = pick(row, ['token0', 'token0_address', 'token 0', 'token 0 address', 'tokenA', 'base']);
+    let t1 = pick(row, ['token1', 'token1_address', 'token 1', 'token 1 address', 'tokenB', 'quote']);
+    let fee = pick(row, ['fee', 'fee_tier', 'fee tier', 'feebps']);
+
+    // If not found, scan all values for first two distinct addresses
+    if (!looksLikeAddress(t0 || '') || !looksLikeAddress(t1 || '')) {
+      const found = [];
+      for (const v of Object.values(row)) {
+        const addr = extractFirstAddress(String(v || ''));
+        if (addr && !found.includes(addr)) found.push(addr);
+        if (found.length >= 2) break;
+      }
+      if (!looksLikeAddress(t0 || '') && found[0]) t0 = found[0];
+      if (!looksLikeAddress(t1 || '') && found[1]) t1 = found[1];
+    }
+
+    // parse fee
+    const feeNum = parseFeeToUint24(fee);
+    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();
+    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;
+    } catch (_) {
+      // ignore
+    }
+    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']);
+    if (!looksLikeAddress(pool || '')) {
+      // try extract from any cell (e.g., Etherscan/Uniswap URL)
+      for (const v of Object.values(row)) {
+        const found = extractFirstAddress(String(v || ''));
+        if (found) { pool = found; break; }
+      }
+    }
+    if (!looksLikeAddress(pool || '')) {
+      // try factory lookup using tokens + fee
+      const viaFactory = await resolvePoolFromTokens(row, args.rpc);
+      if (viaFactory) pool = viaFactory;
+    }
+    if (!looksLikeAddress(pool || '')) {
+      console.warn(`Row ${idx + 1}: skipping (no valid pool address)`);
+      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));
+
+    if (args.debug) {
+      const dbg = [];
+      if (vault) dbg.push(`vault=${vault}`);
+      if (owner) dbg.push(`owner=${owner}`);
+      if (wpct) dbg.push(`withdraw_pct=${wpct}`);
+      if (wshares) dbg.push(`withdraw_shares=${wshares}`);
+      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);
+      }
+      console.log(`Wrote: ${file}`);
+    } catch (err) {
+      const errMsg = String(err?.stderr || err?.stdout || 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}`);
+      console.error(`  -> see ${errFile}`);
+    }
+  }
+}
+
+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');
+    process.exit(1);
+  }
+  if (args.block) {
+    console.error('Time-series mode cannot be combined with --block. Use --time-start/--time-window/--time-count with --timestamp.');
+    process.exit(1);
+  }
+  if (!args.rpc) {
+    console.error('Time-series mode requires --rpc (or RPC_URL env) so timestamps can be resolved to blocks.');
+    process.exit(1);
+  }
+
+  let intervalSec;
+  try {
+    intervalSec = parseDurationArg(args.timeInterval ?? '1h');
+  } catch (e) {
+    console.error(`Invalid --time-interval value: ${e?.message || e}`);
+    process.exit(1);
+  }
+  if (intervalSec <= 0n) {
+    console.error('--time-interval must be greater than zero');
+    process.exit(1);
+  }
+
+  let endSec;
+  try {
+    endSec = args.timeEnd != null ? parseTimestampArg(args.timeEnd) : BigInt(Math.floor(Date.now() / 1000));
+  } catch (e) {
+    console.error(`Invalid --time-end value: ${e?.message || e}`);
+    process.exit(1);
+  }
+
+  let startSec;
+  if (args.timeStart != null) {
+    try {
+      startSec = parseTimestampArg(args.timeStart);
+    } catch (e) {
+      console.error(`Invalid --time-start value: ${e?.message || e}`);
+      process.exit(1);
+    }
+  }
+  if (startSec == null && args.timeWindow != null) {
+    try {
+      const windowSec = parseDurationArg(args.timeWindow);
+      startSec = endSec > windowSec ? endSec - windowSec : 0n;
+    } catch (e) {
+      console.error(`Invalid --time-window value: ${e?.message || e}`);
+      process.exit(1);
+    }
+  }
+
+  let count = undefined;
+  if (args.timeCount != null) {
+    if (!Number.isFinite(args.timeCount) || args.timeCount <= 0) {
+      console.error('--time-count must be a positive integer');
+      process.exit(1);
+    }
+    count = Math.floor(args.timeCount);
+  }
+  if (startSec == null) {
+    if (count != null) {
+      const span = intervalSec * BigInt(Math.max(count - 1, 0));
+      startSec = endSec > span ? endSec - span : 0n;
+    } else {
+      console.error('Time-series mode requires --time-start, --time-window, or --time-count');
+      process.exit(1);
+    }
+  }
+
+  if (startSec > endSec) {
+    [startSec, endSec] = [endSec, startSec];
+  }
+
+  const timestamps = [];
+  const maxPoints = 10000;
+  for (let ts = startSec; ts <= endSec; ts += intervalSec) {
+    timestamps.push(ts);
+    if (count != null && timestamps.length >= count) break;
+    if (timestamps.length > maxPoints) {
+      console.error(`Time-series would produce more than ${maxPoints} snapshots. Increase --time-interval or reduce the window/count.`);
+      process.exit(1);
+    }
+  }
+  if (!timestamps.length) timestamps.push(startSec);
+  if (count == null && timestamps[timestamps.length - 1] < endSec) {
+    timestamps.push(endSec);
+  }
+  if (count != null && timestamps.length > count) {
+    timestamps.splice(0, timestamps.length - count);
+  }
+
+  const tsStrings = timestamps.map((ts) => ts.toString());
+  if (!tsStrings.length) {
+    console.error('No timestamps resolved for time-series mode');
+    process.exit(1);
+  }
+
+  if (!args.json) {
+    const startIso = formatTimestampUTC(BigInt(tsStrings[0]));
+    const endIso = formatTimestampUTC(BigInt(tsStrings[tsStrings.length - 1]));
+    const intervalHuman = args.timeInterval ?? '1h';
+    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 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 });
+      if (args.json) {
+        const text = stdout.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);
+          }
+        } else {
+          jsonResults.push(null);
+        }
+      } else {
+        process.stdout.write(stdout);
+        if (!stdout.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);
+    }
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(jsonResults, null, 2));
+  }
+}
+
+// Strip noisy logs (e.g., TEVM warnings) from report files while preserving CLI output
+function cleanReportOutput(s) {
+  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;
+  }
+}
+
+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;
+  }
+
+  let percentBuckets;
+  try {
+    percentBuckets = parsePercentBuckets(args.percent);
+  } catch (e) {
+    console.error(`Invalid --percent value: ${e?.message || e}`);
+    process.exit(1);
+  }
+  if (!percentBuckets.length) {
+    console.error('No valid percent buckets parsed.');
+    process.exit(1);
+  }
+
+  const wantsWithdraw =
+    args.vault && (Number.isFinite(args.withdrawPct) || args.withdrawShares);
+  let sharedClient = null;
+  let sharedBlockTag;
+  if (wantsWithdraw) {
+    if (!args.rpc) {
+      console.error('Missing --rpc (or RPC_URL env) for tevm source.');
+      process.exit(1);
+    }
+    const blockContext = await resolveAnalysisBlockContext({
+      block: args.block,
+      timestamp: args.timestamp,
+      rpcUrl: args.rpc,
+      debug: args.debug,
+    });
+    sharedBlockTag = blockContext.blockTag;
+    sharedClient = await createForkClient({
+      rpcUrl: args.rpc,
+      blockTag: sharedBlockTag,
+    });
+  }
+
+  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;
+  }
+
+  let after = null;
+  if (before.usedSource === 'tevm' && wantsWithdraw) {
+    const viemChain = await resolveViemChain(args.rpc);
+    await simulateVaultWithdraw({
+      client: before.client,
+      vault: args.vault,
+      owner: args.owner,
+      withdrawPct: args.withdrawPct,
+      withdrawShares: args.withdrawShares,
+      debug: !!args.debug,
+      cliPool: args.pool,
+      viemChain,
+    });
+    after = await analyzePool({
+      poolAddress: args.pool,
+      percentBuckets,
+      source: 'tevm',
+      rpcUrl: args.rpc,
+      token0USD: args.token0USD,
+      token1USD: args.token1USD,
+      assumeStable: args.assumeStable,
+      usdSizes: args.usdSizes,
+      prices: args.prices,
+      reserveLimit: args.reserveLimit,
+      debug: args.debug,
+      client: before.client,
+      blockTag: before.blockTag,
+    });
+    if (args.debug) {
+      console.error(`[after] tick: ${before.snap.tick} -> ${after.snap.tick}`);
+      console.error(
+        `[after] liquidity: ${before.snap.liquidity.toString()} -> ${after.snap.liquidity.toString()}`
+      );
+    }
+  }
+
+  if (args.json) {
+    const output = after
+      ? {
+          before: serializeAnalysis(args, before),
+          after: serializeAnalysis(args, after),
+        }
+      : serializeAnalysis(args, before);
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  printAnalysisSummary(args, before);
+  if (after) {
+    console.log('');
+    console.log('--- After Withdraw ---');
+    printAnalysisSummary(args, after);
+  }
+}
+
+function serializeAnalysis(args, analysis) {
+  const snap = analysis.snap;
+  const blockNumber =
+    snap.meta?.blockNumber ?? (analysis.blockNumber !== undefined ? analysis.blockNumber : undefined);
+  const timestamp =
+    snap.meta?.blockTimestamp ??
+    (analysis.timestampSec !== undefined ? analysis.timestampSec : undefined);
+  return {
+    pool: snap.meta.poolId,
+    tokens: {
+      token0: snap.meta.token0,
+      token1: snap.meta.token1,
+    },
+    ethPriceUSD: snap.meta.ethPriceUSD,
+    tick: snap.tick,
+    sqrtPriceX96: snap.sqrtPriceX96.toString(),
+    liquidity: snap.liquidity.toString(),
+    feePips: snap.feePips,
+    range: snap.meta.range,
+    percentBuckets: analysis.percentBuckets,
+    block: {
+      number: blockNumber != null ? String(blockNumber) : undefined,
+      timestamp: timestamp != null ? Number(timestamp) : undefined,
+      iso: formatTimestampUTC(timestamp),
+      input:
+        args.block ??
+        args.timestamp ??
+        (typeof analysis.blockTag === 'string' ? analysis.blockTag : undefined),
+    },
+    ...analysis.result,
+    priceImpacts: analysis.priceImpacts
+      ? {
+          usdSizes: analysis.usdSizes,
+          buyPct: analysis.priceImpacts.buyPct,
+          sellPct: analysis.priceImpacts.sellPct,
+        }
+      : undefined,
+    prices: {
+      token0: {
+        address: snap.meta.token0.id,
+        symbol: snap.meta.token0.symbol,
+        usd: analysis.token0USD,
+        source: analysis.priceSource0,
+      },
+      token1: {
+        address: snap.meta.token1.id,
+        symbol: snap.meta.token1.symbol,
+        usd: analysis.token1USD,
+        source: analysis.priceSource1,
+      },
+    },
+    buyCumToken1: analysis.result.buyCumToken1.map((value) => value.toString()),
+    sellCumToken0: analysis.result.sellCumToken0.map((value) => value.toString()),
+  };
+}
+
+function printAnalysisSummary(args, analysis) {
+  const snap = analysis.snap;
+  const result = analysis.result;
+  const fmtUSD = (value) =>
+    new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: 'USD',
+      maximumFractionDigits: 0,
+    }).format(value);
+
+  console.log(`Pool: ${args.pool.toLowerCase()}  [source: ${analysis.usedSource}]`);
+  const blockNumber =
+    snap.meta?.blockNumber ?? (analysis.blockNumber !== undefined ? analysis.blockNumber : undefined);
+  const timestamp =
+    snap.meta?.blockTimestamp ??
+    (analysis.timestampSec !== undefined ? analysis.timestampSec : undefined);
+  const blockInfoParts = [];
+  if (blockNumber != null) blockInfoParts.push(`#${String(blockNumber)}`);
+  const isoTimestamp = formatTimestampUTC(timestamp);
+  if (isoTimestamp) blockInfoParts.push(isoTimestamp);
+  if (blockNumber == null && typeof analysis.blockTag === 'string') {
+    blockInfoParts.push(analysis.blockTag);
+  }
+  if (blockInfoParts.length) console.log(`Block: ${blockInfoParts.join(' | ')}`);
+  console.log(
+    `Tokens: ${snap.meta.token0.symbol} (${snap.meta.token0.id}) / ${snap.meta.token1.symbol} (${snap.meta.token1.id})`
+  );
+  if (snap.meta?.ethPriceUSD) console.log(`ETH/USD: ${snap.meta.ethPriceUSD.toFixed(2)}`);
+  const feePct = snap.feePips / 10_000;
+  const feeBps = snap.feePips / 100;
+  console.log(`Tick: ${snap.tick}    Fee: ${feePct.toFixed(2)}% (${feeBps.toFixed(2)} bps)`);
+  if (analysis.token0USD || analysis.token1USD) {
+    const fmtPrice = (value) =>
+      value
+        ? `$${value.toLocaleString(undefined, { maximumFractionDigits: 6 })}`
+        : 'n/a';
+    console.log(
+      `Prices: ${snap.meta.token0.symbol} ${fmtPrice(analysis.token0USD)} (${analysis.priceSource0 || 'n/a'}), ${snap.meta.token1.symbol} ${fmtPrice(analysis.token1USD)} (${analysis.priceSource1 || 'n/a'})`
+    );
+  }
+  console.log(`Range: [${snap.meta.range.start}, ${snap.meta.range.end}] for ±${snap.meta.farPercent}%`);
+  console.log('');
+
+  const labels = analysis.percentBuckets.map((percent) => `${percent}%`);
+  console.log('Buy cumulative (token1 in → price up):');
+  labels.forEach((label, index) =>
+    console.log(`  +${label.padEnd(4)}: ${fmtUSD(result.buyCumUSD[index])}`)
+  );
+  console.log('Sell cumulative (token0 in → price down):');
+  labels.forEach((label, index) =>
+    console.log(`  -${label.padEnd(4)}: ${fmtUSD(result.sellCumUSD[index])}`)
+  );
+  console.log('');
+  console.log(`Headline Depth +2% : ${fmtUSD(result.depthPlus2USD)}`);
+  console.log(`Headline Depth -2% : ${fmtUSD(result.depthMinus2USD)}`);
+
+  if (!analysis.priceImpacts && analysis.usdSizes.length) {
+    console.log('');
+    console.log('Note: USD sizes provided but missing USD prices.');
+    console.log('      Pass --token0-usd and --token1-usd to enable price impact output.');
+  } else if (analysis.priceImpacts) {
+    console.log('');
+    console.log('Price impact by USD size:');
+    analysis.usdSizes.forEach((usd, index) => {
+      const buy = analysis.priceImpacts.buyPct[index];
+      const sell = analysis.priceImpacts.sellPct[index];
+      const fmtPct = (value) => `${value >= 0 ? '+' : ''}${value.toFixed(5)}%`;
+      console.log(`  $${usd.toLocaleString()}: buy ${fmtPct(buy)}   sell ${fmtPct(sell)}`);
+    });
+  }
+}
+
+main().catch((err) => {
+  console.error(err?.stack || err?.message || String(err));
+  process.exit(1);
+});