@steerprotocol/liquidity-meter 1.0.0 → 2.0.4

package/package.json

@@ -1,47 +1,57 @@
 {
   "name": "@steerprotocol/liquidity-meter",
-  "version": "1.0.0",
-  "public": true,
+  "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": {
+    ".": "./src/index.js",
+    "./api": "./src/api.js",
+    "./withdraw": "./src/withdraw.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
-    "liquidity-depth": "dist/cli/liquidity-depth.js"
+    "liquidity-depth": "bin/liquidity-depth.js"
   },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "generate": "wagmi generate",
-    "start": "node dist/cli/liquidity-depth.js --help"
+    "start": "node bin/liquidity-depth.js --help",
+    "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": {
-    "@wagmi/core": "^2.20.3",
-    "axios": "^1.7.7",
-    "tevm": "^1.0.0-next.147",
-    "viem": "^2.21.13"
+    "axios": "1.7.7",
+    "tevm": "1.0.0-next.149",
+    "viem": "2.37.9"
   },
-  "devDependencies": {
-    "@types/node": "^20.19.11",
-    "@wagmi/cli": "^2.5.1",
-    "typescript": "^5.9.2"
-  }
-  ,
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./cli": {
-      "import": "./dist/cli/liquidity-depth.js"
-    },
-    "./prices": {
-      "types": "./dist/prices.d.ts",
-      "import": "./dist/prices.js"
-    }
+  "overrides": {
+    "viem": "2.37.9"
   }
 }

package/src/api.js

@@ -0,0 +1,568 @@
+import { createPublicClient, http as viemHttp } from 'viem';
+import {
+  computeMarketDepthBands,
+  computePriceImpactsBySizes,
+} 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
+      .map((value) => Number(value))
+      .filter((value) => Number.isFinite(value) && value > 0)
+      .sort((a, b) => a - b);
+  }
+  return String(input)
+    .split(',')
+    .map((value) => Number(value.trim()))
+    .filter((value) => Number.isFinite(value) && value > 0)
+    .sort((a, b) => a - b);
+}
+
+export function parseBlockIdentifier(input) {
+  if (input == null) return undefined;
+  const raw = String(input).trim();
+  if (!raw) throw new Error('Empty block identifier');
+  const lowered = raw.toLowerCase();
+  if (
+    lowered === 'latest' ||
+    lowered === 'pending' ||
+    lowered === 'safe' ||
+    lowered === 'finalized'
+  ) {
+    return undefined;
+  }
+  let value;
+  if (/^0x[0-9a-f]+$/i.test(raw)) value = BigInt(raw);
+  else if (/^-?\d+$/.test(raw)) value = BigInt(raw);
+  else throw new Error(`Invalid block identifier: ${raw}`);
+  if (value < 0n) throw new Error('Block number must be non-negative');
+  return value;
+}
+
+export function parseTimestampArg(input) {
+  if (input == null) return undefined;
+  const raw = String(input).trim();
+  if (!raw) throw new Error('Empty timestamp');
+  if (/^-?\d+$/.test(raw)) {
+    let ts = BigInt(raw);
+    if (ts < 0n) throw new Error('Timestamp must be non-negative');
+    if (ts > 1_000_000_000_000n) ts /= 1000n;
+    return ts;
+  }
+  const ms = Date.parse(raw);
+  if (!Number.isFinite(ms)) throw new Error(`Invalid timestamp: ${raw}`);
+  if (ms < 0) throw new Error('Timestamp must be >= 1970-01-01');
+  return BigInt(Math.floor(ms / 1000));
+}
+
+export function parseDurationArg(input) {
+  if (input == null) throw new Error('Missing duration');
+  const raw = String(input).trim();
+  if (!raw) throw new Error('Empty duration');
+  const match = raw.match(/^([0-9]+(?:\.[0-9]+)?)([a-zA-Z]*)$/);
+  if (!match) throw new Error(`Invalid duration: ${raw}`);
+  const value = Number(match[1]);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error('Duration must be positive');
+  }
+  const unit = match[2].toLowerCase();
+  const multipliers = {
+    '': 1,
+    s: 1,
+    m: 60,
+    h: 3600,
+    d: 86400,
+    w: 604800,
+  };
+  const multiplier = multipliers[unit];
+  if (!multiplier) {
+    throw new Error(`Unsupported duration unit in ${raw} (use s, m, h, d, w)`);
+  }
+  const rounded = Math.round(value * multiplier);
+  if (!Number.isFinite(rounded) || rounded <= 0) {
+    throw new Error(`Duration out of range: ${raw}`);
+  }
+  return BigInt(rounded);
+}
+
+export function formatTimestampUTC(seconds) {
+  if (seconds == null) return undefined;
+  try {
+    const numeric = Number(seconds);
+    if (!Number.isFinite(numeric)) return undefined;
+    return new Date(numeric * 1000).toISOString();
+  } catch (_) {
+    return undefined;
+  }
+}
+
+export async function findBlockNumberForTimestamp({
+  rpcUrl,
+  targetTimestampSec,
+  debug = false,
+  client,
+  bounds,
+  blockCache,
+}) {
+  if (!rpcUrl) throw new Error('RPC URL required to resolve timestamp');
+  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 = 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 = 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 = loTimestamp <= targetTimestampSec ? lo : (genesis.number ?? 0n);
+  for (let iter = 0; iter < 80 && lo <= hi; iter++) {
+    const mid = (lo + hi) >> 1n;
+    const block = await readBlock(mid);
+    if (!block || block.timestamp == null) {
+      hi = mid - 1n;
+      continue;
+    }
+    if (block.timestamp === targetTimestampSec) {
+      return block.number;
+    }
+    if (block.timestamp < targetTimestampSec) {
+      best = block.number;
+      lo = mid + 1n;
+    } else {
+      if (mid === 0n) break;
+      hi = mid - 1n;
+    }
+  }
+  if (debug) {
+    console.error(`[api] resolved timestamp ${targetTimestampSec} -> block ${best}`);
+  }
+  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;
+  if (block != null) {
+    const parsed = parseBlockIdentifier(block);
+    if (parsed !== undefined) {
+      blockNumber = parsed;
+      blockSource = '--block';
+    }
+  }
+
+  let timestampSec;
+  if (blockNumber === undefined && timestamp != null) {
+    timestampSec = parseTimestampArg(timestamp);
+  }
+
+  if (blockNumber === undefined && timestampSec !== undefined) {
+    if (!rpcUrl) {
+      throw new Error('--timestamp requires --rpc (or RPC_URL env) to resolve block number');
+    }
+    blockNumber = await findBlockNumberForTimestamp({
+      rpcUrl,
+      targetTimestampSec: timestampSec,
+      debug,
+      client,
+    });
+    blockSource = '--timestamp';
+  }
+
+  const resolvedBlockTag =
+    blockTag ?? (blockNumber !== undefined ? blockNumber : 'latest');
+  if (debug && blockNumber !== undefined) {
+    const tsInfo = timestampSec !== undefined ? ` timestamp=${timestampSec}` : '';
+    console.error(
+      `[api] using blockTag=${resolvedBlockTag} (${blockSource || 'implicit'})${tsInfo}`
+    );
+  }
+
+  return {
+    blockNumber,
+    blockSource,
+    timestampSec,
+    blockTag: resolvedBlockTag,
+  };
+}
+
+function normalizeUsdSizes(input) {
+  if (Array.isArray(input)) {
+    return input
+      .map((value) => Number(value))
+      .filter((value) => Number.isFinite(value) && value > 0)
+      .sort((a, b) => a - b);
+  }
+  return String(input ?? '')
+    .split(',')
+    .map((value) => Number(value.trim()))
+    .filter((value) => Number.isFinite(value) && value > 0)
+    .sort((a, b) => a - b);
+}
+
+function usdToRaw(usd, usdPrice, decimals) {
+  if (!usdPrice || usdPrice <= 0) return 0n;
+  const micros = Math.round(usd * 1e6);
+  const usdMicrosPrice = Math.round(usdPrice * 1e6);
+  if (usdMicrosPrice <= 0) return 0n;
+  const scale = 10n ** BigInt(decimals);
+  return (BigInt(micros) * scale) / BigInt(usdMicrosPrice);
+}
+
+async function resolveChainId({ client, rpcUrl, blockTag }) {
+  try {
+    if (client && typeof client.getChainId === 'function') {
+      const chainId = await client.getChainId();
+      if (rpcUrl) chainIdByRpcUrl.set(rpcUrl, chainId);
+      return chainId;
+    }
+  } catch (_) {}
+  try {
+    if (!rpcUrl) return undefined;
+    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;
+  }
+}
+
+async function computeSnapshotMetrics({
+  options,
+  snap,
+  percentBuckets,
+  client,
+  blockTag,
+}) {
+  const usd0 = Number.isFinite(options.token0USD)
+    ? options.token0USD
+    : snap.token0.usdPrice;
+  const usd1 = Number.isFinite(options.token1USD)
+    ? options.token1USD
+    : snap.token1.usdPrice;
+
+  let token0USD = usd0;
+  let token1USD = usd1;
+  const dec0 = snap.token0.decimals;
+  const dec1 = snap.token1.decimals;
+  const price1Per0 =
+    Math.pow(1.0001, snap.tick) * Math.pow(10, dec0 - dec1);
+
+  if (!usd0 && usd1) token0USD = usd1 * price1Per0;
+  if (usd0 && !usd1) token1USD = usd0 / price1Per0;
+
+  let priceSource0 = usd0 ? 'override' : undefined;
+  let priceSource1 = usd1 ? 'override' : undefined;
+
+  if (!token0USD || !token1USD) {
+    try {
+      const { fetchTokenUSDPrices } = await import('./prices.js');
+      const addresses = [
+        snap.meta?.token0?.id || snap.token0.id,
+        snap.meta?.token1?.id || snap.token1.id,
+      ].map((address) => address.toLowerCase());
+      const chainId = await resolveChainId({
+        client,
+        rpcUrl: options.rpcUrl,
+        blockTag,
+      });
+      if (options.debug) {
+        console.error(
+          `[api] price fetch: addrs=${addresses.join(',')} source=${options.prices} rpc=${options.rpcUrl ? 'yes' : 'no'} chainId=${chainId ?? 'n/a'}`
+        );
+      }
+      const { byAddress } = await fetchTokenUSDPrices({
+        addresses,
+        source: options.prices,
+        chainId,
+        rpcUrl: options.rpcUrl,
+        debug: !!options.debug,
+        reserveLimit: options.reserveLimit,
+      });
+      const p0 = byAddress[addresses[0]];
+      const p1 = byAddress[addresses[1]];
+      if (!token0USD && p0) {
+        token0USD = p0.price;
+        priceSource0 = p0.source;
+      }
+      if (!token1USD && p1) {
+        token1USD = p1.price;
+        priceSource1 = p1.source;
+      }
+      if (token0USD && !token1USD) {
+        token1USD = token0USD / price1Per0;
+        if (!priceSource1) priceSource1 = 'derived';
+      }
+      if (!token0USD && token1USD) {
+        token0USD = token1USD * price1Per0;
+        if (!priceSource0) priceSource0 = 'derived';
+      }
+    } catch (_) {}
+  }
+
+  if (!priceSource0 && usd0) priceSource0 = 'subgraph';
+  if (!priceSource1 && usd1) priceSource1 = 'subgraph';
+
+  if (!token0USD || !token1USD) {
+    if (
+      options.assumeStable === 0 ||
+      /USD|USDC|USDT|DAI/i.test(snap.meta?.token0?.symbol || '')
+    ) {
+      if (!token0USD) {
+        token0USD = 1;
+        priceSource0 = 'inferred';
+      }
+      if (!token1USD) {
+        token1USD = 1 / price1Per0;
+        priceSource1 = 'inferred';
+      }
+    } else if (
+      options.assumeStable === 1 ||
+      /USD|USDC|USDT|DAI/i.test(snap.meta?.token1?.symbol || '')
+    ) {
+      if (!token1USD) {
+        token1USD = 1;
+        priceSource1 = 'inferred';
+      }
+      if (!token0USD) {
+        token0USD = price1Per0;
+        priceSource0 = 'inferred';
+      }
+    }
+  }
+
+  if (options.debug) {
+    console.error(
+      `[api] usd results: token0=${token0USD ?? 'n/a'} src0=${priceSource0 ?? 'n/a'} token1=${token1USD ?? 'n/a'} src1=${priceSource1 ?? 'n/a'}`
+    );
+  }
+
+  if (!priceSource0 && token0USD) priceSource0 = 'inferred';
+  if (!priceSource1 && token1USD) priceSource1 = 'inferred';
+
+  const result = computeMarketDepthBands({
+    sqrtPriceX96: snap.sqrtPriceX96,
+    tick: snap.tick,
+    liquidity: snap.liquidity,
+    feePips: snap.feePips,
+    ticks: snap.ticks,
+    token0: { decimals: snap.token0.decimals, usdPrice: token0USD || 0 },
+    token1: { decimals: snap.token1.decimals, usdPrice: token1USD || 0 },
+    percentBuckets,
+  });
+
+  const usdSizes = normalizeUsdSizes(options.usdSizes);
+  let priceImpacts = null;
+  if (usdSizes.length && token0USD && token1USD) {
+    const buySizesToken1 = usdSizes.map((usd) =>
+      usdToRaw(usd, token1USD, snap.token1.decimals)
+    );
+    const sellSizesToken0 = usdSizes.map((usd) =>
+      usdToRaw(usd, token0USD, snap.token0.decimals)
+    );
+    priceImpacts = computePriceImpactsBySizes({
+      sqrtPriceX96: snap.sqrtPriceX96,
+      tick: snap.tick,
+      liquidity: snap.liquidity,
+      feePips: snap.feePips,
+      ticks: snap.ticks,
+      buySizesToken1,
+      sellSizesToken0,
+    });
+  }
+
+  return {
+    token0USD,
+    token1USD,
+    priceSource0,
+    priceSource1,
+    result,
+    usdSizes,
+    priceImpacts,
+  };
+}
+
+export async function analyzePool(input = {}) {
+  const options = {
+    poolAddress: input.poolAddress ?? input.pool,
+    percentBuckets:
+      input.percentBuckets ?? parsePercentBuckets(input.percent ?? '1,2,5,10'),
+    source: input.source ?? 'tevm',
+    rpcUrl: input.rpcUrl ?? input.rpc,
+    subgraphUrl: input.subgraphUrl ?? input.subgraph,
+    token0USD: input.token0USD,
+    token1USD: input.token1USD,
+    assumeStable: input.assumeStable,
+    usdSizes: input.usdSizes ?? '1000,5000,10000,25000,50000,100000',
+    prices: input.prices ?? 'auto',
+    reserveLimit: input.reserveLimit ?? 100,
+    block: input.block,
+    timestamp: input.timestamp,
+    debug: !!input.debug,
+    snapshot: input.snapshot,
+    client: input.client ?? null,
+    blockTag: input.blockTag,
+  };
+
+  if (!options.percentBuckets.length) {
+    throw new Error('No valid percent buckets parsed.');
+  }
+
+  const {
+    blockNumber,
+    blockSource,
+    timestampSec,
+    blockTag,
+  } = await resolveAnalysisBlockContext({
+    block: options.block,
+    timestamp: options.timestamp,
+    rpcUrl: options.rpcUrl,
+    debug: options.debug,
+    blockTag: options.blockTag,
+    client: options.client,
+  });
+
+  let client = options.client;
+  let usedSource = options.source;
+  let snap = options.snapshot;
+
+  if (!snap) {
+    const useTevm =
+      options.source === 'viem' ||
+      options.source === 'tevm' ||
+      (options.source === 'auto' && options.rpcUrl);
+
+    if (useTevm) {
+      if (!options.rpcUrl) {
+        throw new Error('Missing --rpc (or RPC_URL env) for tevm source.');
+      }
+      const { fetchPoolSnapshotViem } = await import('./viem-onchain.js');
+      if (!client) {
+        client = getCachedPublicClient(options.rpcUrl);
+      }
+      usedSource = 'tevm';
+      snap = await fetchPoolSnapshotViem({
+        poolAddress: options.poolAddress,
+        rpcUrl: options.rpcUrl,
+        percentBuckets: options.percentBuckets,
+        client,
+        blockTag,
+      });
+    } else if (options.source === 'subgraph' || options.source === 'auto') {
+      usedSource = 'subgraph';
+      snap = await fetchFromSubgraph({
+        poolAddress: options.poolAddress,
+        percentBuckets: options.percentBuckets,
+        subgraphUrl: options.subgraphUrl,
+        blockNumber,
+      });
+    } else {
+      throw new Error(`Unknown --source: ${options.source}`);
+    }
+  } else {
+    usedSource = options.source === 'auto' ? 'snapshot' : options.source;
+  }
+
+  const metrics = await computeSnapshotMetrics({
+    options,
+    snap,
+    percentBuckets: options.percentBuckets,
+    client,
+    blockTag,
+  });
+
+  return {
+    snap,
+    client,
+    usedSource,
+    percentBuckets: options.percentBuckets,
+    blockTag,
+    blockNumber,
+    blockSource,
+    timestampSec,
+    ...metrics,
+  };
+}