@steerprotocol/liquidity-meter 1.0.0 → 2.0.4

package/src/uniswapv3-subgraph.js

@@ -0,0 +1,141 @@
+// Uniswap v3 subgraph client (axios-based)
+// Pulls pool snapshot and ticks in a target range.
+
+import { DepthInternals } from './depth.js';
+import axios from 'axios';
+
+const DEFAULT_SUBGRAPH = 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v3';
+
+function percentToTickDelta(pct) {
+  const r = 1 + pct / 100;
+  const delta = Math.log(r) / Math.log(1.0001);
+  return Math.max(1, Math.round(delta));
+}
+
+async function graphqlFetch(url, query, variables) {
+  const res = await axios.post(url, { query, variables }, {
+    headers: { 'content-type': 'application/json' },
+    maxRedirects: 5,
+    timeout: 15000,
+    validateStatus: (s) => s >= 200 && s < 300,
+  });
+  const body = res.data;
+  if (body.errors) {
+    const msg = body.errors.map((e) => e.message).join('; ');
+    throw new Error(`Subgraph error: ${msg}`);
+  }
+  return body.data;
+}
+
+export async function fetchPoolSnapshot({
+  poolAddress,
+  percentBuckets = [1, 2, 5, 10],
+  subgraphUrl = DEFAULT_SUBGRAPH,
+  blockNumber,
+}) {
+  const id = poolAddress.toLowerCase();
+  let blockVar = null;
+  if (blockNumber !== undefined && blockNumber !== null) {
+    const bn = typeof blockNumber === 'bigint' ? blockNumber : BigInt(blockNumber);
+    if (bn < 0n) throw new Error('Block number must be non-negative');
+    const asNumber = Number(bn);
+    if (!Number.isFinite(asNumber)) throw new Error('Block number is too large for subgraph query');
+    blockVar = { number: asNumber };
+  }
+
+  // First fetch pool core fields + ETH price
+  const coreQuery = `
+    query PoolCore($id: ID!, $block: Block_height) {
+      bundle(id: "1", block: $block) { ethPriceUSD }
+      pool(id: $id, block: $block) {
+        id
+        sqrtPrice
+        tick
+        liquidity
+        feeTier
+        token0 { id symbol decimals derivedETH }
+        token1 { id symbol decimals derivedETH }
+      }
+    }
+  `;
+
+  const core = await graphqlFetch(subgraphUrl, coreQuery, { id, block: blockVar });
+  if (!core.pool) throw new Error(`Pool not found in subgraph: ${id}`);
+
+  const ethPriceUSD = Number(core.bundle?.ethPriceUSD ?? 0);
+  const pool = core.pool;
+
+  const sqrtPriceX96 = BigInt(pool.sqrtPrice);
+  const tick = Number(pool.tick);
+  const liquidity = BigInt(pool.liquidity);
+  const feePips = Number(pool.feeTier);
+
+  const token0 = {
+    decimals: Number(pool.token0.decimals),
+    usdPrice: Number(pool.token0.derivedETH) * ethPriceUSD,
+    symbol: pool.token0.symbol,
+    id: pool.token0.id,
+  };
+  const token1 = {
+    decimals: Number(pool.token1.decimals),
+    usdPrice: Number(pool.token1.derivedETH) * ethPriceUSD,
+    symbol: pool.token1.symbol,
+    id: pool.token1.id,
+  };
+
+  // Determine tick bounds for the farthest bucket
+  const far = Math.max(...percentBuckets);
+  const delta = percentToTickDelta(far);
+  const start = Math.max(DepthInternals.MIN_TICK, tick - delta);
+  const end = Math.min(DepthInternals.MAX_TICK, tick + delta);
+
+  // Paginate ticks in [start, end]
+  const ticks = [];
+  const pageSize = 1000;
+  let skip = 0;
+  while (true) {
+    const ticksQuery = `
+      query PoolTicks($id: ID!, $start: Int!, $end: Int!, $first: Int!, $skip: Int!, $block: Block_height) {
+        pool(id: $id, block: $block) {
+          ticks(where: { tickIdx_gte: $start, tickIdx_lte: $end }, orderBy: tickIdx, orderDirection: asc, first: $first, skip: $skip) {
+            tickIdx
+            liquidityNet
+          }
+        }
+      }
+    `;
+    const data = await graphqlFetch(subgraphUrl, ticksQuery, {
+      id,
+      start,
+      end,
+      first: pageSize,
+      skip,
+      block: blockVar,
+    });
+    const page = data.pool?.ticks ?? [];
+    for (const t of page) {
+      ticks.push({ index: Number(t.tickIdx), liquidityNet: BigInt(t.liquidityNet) });
+    }
+    if (page.length < pageSize) break;
+    skip += pageSize;
+  }
+
+  return {
+    sqrtPriceX96,
+    tick,
+    liquidity,
+    feePips,
+    ticks,
+    token0: { decimals: token0.decimals, usdPrice: token0.usdPrice },
+    token1: { decimals: token1.decimals, usdPrice: token1.usdPrice },
+    meta: {
+      token0,
+      token1,
+      ethPriceUSD,
+      poolId: id,
+      range: { start, end },
+      farPercent: far,
+      blockNumber: blockVar?.number ?? undefined,
+    },
+  };
+}

package/src/viem-onchain.js

@@ -0,0 +1,506 @@
+// 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,
+  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)',
+  'function liquidity() view returns (uint128)',
+  'function fee() view returns (uint24)',
+  'function tickSpacing() view returns (int24)',
+  'function token0() view returns (address)',
+  'function token1() view returns (address)',
+  'function tickBitmap(int16) view returns (uint256)',
+  'function ticks(int24 tick) view returns (uint128 liquidityGross, int128 liquidityNet, uint256 feeGrowthOutside0X128, uint256 feeGrowthOutside1X128, int56 tickCumulativeOutside, uint160 secondsPerLiquidityOutsideX128, uint32 secondsOutside, bool initialized)'
+]);
+
+const ALGEBRA_POOL_ABI = parseAbi([
+  'function liquidity() view returns (uint128)',
+  'function tickSpacing() view returns (int24)',
+  'function token0() view returns (address)',
+  'function token1() view returns (address)',
+  'function tickTable(int16) view returns (uint256)',
+  'function ticks(int24 tick) view returns (uint256 liquidityTotal, int128 liquidityDelta, int24 prevTick, int24 nextTick, uint256 outerFeeGrowth0Token, uint256 outerFeeGrowth1Token)'
+]);
+
+const ERC20_ABI = parseAbi([
+  'function decimals() view returns (uint8)',
+  'function symbol() view returns (string)'
+]);
+
+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;
+}
+
+function decodeAlgebraGlobalState(hexData) {
+  if (!hexData || hexData === '0x') {
+    throw new Error('Empty globalState response');
+  }
+  const clean = hexData.slice(2);
+  const words = [];
+  for (let i = 0; i < clean.length; i += 64) {
+    const chunk = clean.slice(i, i + 64);
+    if (chunk.length === 0) break;
+    words.push(BigInt('0x' + chunk));
+  }
+  if (words.length < 2) {
+    throw new Error('Unexpected globalState payload');
+  }
+  const sqrtPriceX96 = words[0];
+  const tickBig = toSigned256(words[1]);
+  const feeWord = words[2] ?? 0n;
+  const tick = Number(tickBig);
+  if (!Number.isSafeInteger(tick)) {
+    throw new Error('Decoded Algebra tick is not a safe integer');
+  }
+  const feePips = Number(feeWord);
+  return { sqrtPriceX96, tick, feePips };
+}
+
+function percentToTickDelta(pct) {
+  const r = 1 + pct / 100;
+  const delta = Math.log(r) / Math.log(1.0001);
+  return Math.max(1, Math.round(delta));
+}
+
+function floorDiv(a, b) {
+  const q = Math.trunc(a / b);
+  const r = a % b;
+  return (r !== 0 && ((r > 0) !== (b > 0))) ? q - 1 : q;
+}
+
+export async function fetchPoolSnapshotViem({ poolAddress, rpcUrl, percentBuckets = [1,2,5,10], client, blockTag = 'latest' }) {
+  let c = client;
+  if (!c) {
+    c = createPublicClient({ transport: http(rpcUrl) });
+  }
+  const pool = getAddress(poolAddress);
+  const readBlockParams =
+    typeof blockTag === 'bigint'
+      ? { blockNumber: blockTag }
+      : typeof blockTag === 'number'
+        ? { blockNumber: BigInt(blockTag) }
+        : blockTag && blockTag !== 'latest'
+          ? { blockTag }
+          : {};
+
+  let resolvedBlockNumber;
+  let resolvedBlockTimestamp;
+  try {
+    const blk = await c.getBlock(
+      'blockNumber' in readBlockParams || 'blockTag' in readBlockParams
+        ? readBlockParams
+        : { blockTag: 'latest' }
+    );
+    if (blk) {
+      resolvedBlockNumber = blk.number;
+      resolvedBlockTimestamp = blk.timestamp;
+    }
+  } catch (_) {
+    try {
+      resolvedBlockNumber = await c.getBlockNumber();
+    } catch (_) {}
+  }
+
+  let sqrtPriceX96;
+  let tick;
+  let liquidity;
+  let feePips;
+  let tickSpacing;
+  let token0Addr;
+  let token1Addr;
+  let poolType = 'uniswap';
+  const poolCacheKey = pool.toLowerCase();
+  const cachedPoolStatic = poolStaticCache.get(poolCacheKey);
+
+  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 = cachedPoolStatic.feePips;
+    tickSpacing = cachedPoolStatic.tickSpacing;
+    token0Addr = cachedPoolStatic.token0Addr;
+    token1Addr = cachedPoolStatic.token1Addr;
+  } else if (cachedPoolStatic?.poolType === 'algebra') {
+    poolType = 'algebra';
+    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 = 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));
+  if (!tickSpacing) {
+    throw new Error('tickSpacing resolved to zero');
+  }
+
+  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);
+  const start = tick - delta;
+  const end = tick + delta;
+
+  const compStart = floorDiv(start, tickSpacing);
+  const compEnd = floorDiv(end, tickSpacing);
+  const wordStart = floorDiv(compStart, 256);
+  const wordEnd = floorDiv(compEnd, 256);
+
+  const ticks = [];
+  const poolAbi = poolType === 'algebra' ? ALGEBRA_POOL_ABI : UNISWAP_POOL_ABI;
+  const bitmapFn = poolType === 'algebra' ? 'tickTable' : 'tickBitmap';
+  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;
+      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] });
+    }
+  }
+
+  return {
+    sqrtPriceX96,
+    tick,
+    liquidity,
+    feePips,
+    ticks: ticks.sort((a,b) => a.index - b.index),
+    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: token0Meta.decimals, symbol: token0Meta.symbol, id: token0Addr },
+      token1: { decimals: token1Meta.decimals, symbol: token1Meta.symbol, id: token1Addr },
+      poolId: pool,
+      range: { start, end },
+      farPercent: far,
+      tickSpacing,
+      poolType,
+      blockNumber: resolvedBlockNumber,
+      blockTimestamp: resolvedBlockTimestamp,
+      blockTag,
+    },
+  };
+}