@steerprotocol/liquidity-meter 1.0.0 → 2.0.4

package/src/withdraw.js

@@ -0,0 +1,333 @@
+import {
+  createPublicClient,
+  encodeFunctionData,
+  getAddress,
+  http as viemHttp,
+  parseAbi,
+  parseEther,
+} from 'viem';
+import { sendTransaction as viemSendTransaction } from 'viem/actions';
+
+const ERC20_ABI = parseAbi([
+  'function balanceOf(address) view returns (uint256)',
+  'function decimals() view returns (uint8)',
+  'function symbol() view returns (string)',
+  'function totalSupply() view returns (uint256)',
+]);
+
+const VAULT_ABI = parseAbi([
+  'function pool() view returns (address)',
+  'function token0() view returns (address)',
+  'function token1() view returns (address)',
+  'function decimals() view returns (uint8)',
+  'function withdraw(uint256 shares,uint256 amount0Min,uint256 amount1Min,address to) returns (uint256 amount0,uint256 amount1)',
+]);
+
+function formatUnits(value, decimals) {
+  try {
+    let normalized = BigInt(value);
+    const negative = normalized < 0n;
+    if (negative) normalized = -normalized;
+    const stringified = normalized
+      .toString()
+      .padStart(Number(decimals) + 1, '0');
+    const integer = stringified.slice(0, stringified.length - Number(decimals));
+    const fraction = stringified
+      .slice(stringified.length - Number(decimals))
+      .replace(/0+$/, '')
+      .slice(0, 8);
+    return `${negative ? '-' : ''}${integer}${fraction ? `.${fraction}` : ''}`;
+  } catch (_) {
+    return String(value);
+  }
+}
+
+function formatToken(value, decimals, symbol) {
+  return `${formatUnits(value, decimals)} ${symbol || ''}`.trim();
+}
+
+export async function createForkClient({ rpcUrl, blockTag = 'latest' }) {
+  const { createMemoryClient, http } = await import('tevm');
+  const client = createMemoryClient({
+    fork: { transport: http(rpcUrl), blockTag },
+    loggingLevel: 'error',
+  });
+  if (client.tevmReady) await client.tevmReady();
+  return client;
+}
+
+export async function resolveTevmCommon(rpcUrl) {
+  try {
+    const tevmCommon = await import('tevm/common');
+    const client = createPublicClient({ transport: viemHttp(rpcUrl) });
+    const chainId = await client.getChainId();
+    for (const value of Object.values(tevmCommon)) {
+      if (value && typeof value === 'object' && 'id' in value && value.id === chainId) {
+        return value;
+      }
+    }
+  } catch (_) {}
+  return undefined;
+}
+
+export async function resolveViemChain(rpcUrl) {
+  try {
+    const viemChains = await import('viem/chains');
+    const client = createPublicClient({ transport: viemHttp(rpcUrl) });
+    const chainId = await client.getChainId();
+    for (const value of Object.values(viemChains)) {
+      if (value && typeof value === 'object' && 'id' in value && value.id === chainId) {
+        return value;
+      }
+    }
+  } catch (_) {}
+  return undefined;
+}
+
+export async function resolveViemChainFromClient(client) {
+  try {
+    const viemChains = await import('viem/chains');
+    const chainId = await client.getChainId();
+    for (const value of Object.values(viemChains)) {
+      if (value && typeof value === 'object' && 'id' in value && value.id === chainId) {
+        return value;
+      }
+    }
+  } catch (_) {}
+  return undefined;
+}
+
+export async function simulateVaultWithdraw({
+  client,
+  vault,
+  owner,
+  withdrawPct,
+  withdrawShares,
+  debug = false,
+  cliPool,
+  viemChain,
+  sendTransaction = viemSendTransaction,
+}) {
+  if (!client) throw new Error('simulateVaultWithdraw requires tevm client');
+  if (!vault) throw new Error('Missing --vault');
+  if (!owner) throw new Error('Missing --owner for withdraw simulation');
+
+  const vaultAddress = getAddress(vault);
+  const ownerAddress = getAddress(owner);
+
+  let poolAddress;
+  try {
+    poolAddress = await client.readContract({
+      address: vaultAddress,
+      abi: VAULT_ABI,
+      functionName: 'pool',
+    });
+  } catch (error) {
+    throw new Error(`Failed to read vault.pool(): ${error?.message || error}`);
+  }
+
+  let vaultDecimals = 18;
+  try {
+    vaultDecimals = Number(
+      await client.readContract({
+        address: vaultAddress,
+        abi: VAULT_ABI,
+        functionName: 'decimals',
+      })
+    );
+  } catch (_) {}
+
+  const token0Address = await client.readContract({
+    address: vaultAddress,
+    abi: VAULT_ABI,
+    functionName: 'token0',
+  });
+  const token1Address = await client.readContract({
+    address: vaultAddress,
+    abi: VAULT_ABI,
+    functionName: 'token1',
+  });
+
+  const [token0Decimals, token1Decimals] = await Promise.all([
+    client.readContract({
+      address: token0Address,
+      abi: ERC20_ABI,
+      functionName: 'decimals',
+    }),
+    client.readContract({
+      address: token1Address,
+      abi: ERC20_ABI,
+      functionName: 'decimals',
+    }),
+  ]);
+
+  let [token0Symbol, token1Symbol] = ['T0', 'T1'];
+  try {
+    token0Symbol = await client.readContract({
+      address: token0Address,
+      abi: ERC20_ABI,
+      functionName: 'symbol',
+    });
+  } catch (_) {}
+  try {
+    token1Symbol = await client.readContract({
+      address: token1Address,
+      abi: ERC20_ABI,
+      functionName: 'symbol',
+    });
+  } catch (_) {}
+
+  let shares = null;
+  if (withdrawShares != null) {
+    try {
+      shares = BigInt(String(withdrawShares));
+    } catch (_) {
+      throw new Error('--withdraw-shares must be a BigInt-compatible value');
+    }
+  } else if (Number.isFinite(withdrawPct)) {
+    const balance = await client.readContract({
+      address: vaultAddress,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [ownerAddress],
+    });
+    const pct = BigInt(Math.max(0, Math.min(100, Math.floor(Number(withdrawPct)))));
+    shares = (BigInt(balance) * pct) / 100n;
+  }
+
+  const ownerShares = await client.readContract({
+    address: vaultAddress,
+    abi: ERC20_ABI,
+    functionName: 'balanceOf',
+    args: [ownerAddress],
+  });
+  const totalShares = await client.readContract({
+    address: vaultAddress,
+    abi: ERC20_ABI,
+    functionName: 'totalSupply',
+  });
+
+  if (debug) {
+    const poolWarning =
+      cliPool && cliPool.toLowerCase() !== poolAddress.toLowerCase()
+        ? ` (CLI pool=${cliPool})`
+        : '';
+    console.error(
+      `[withdraw] vault=${vaultAddress} pool=${poolAddress}${poolWarning}`
+    );
+    console.error(
+      `[withdraw] owner=${ownerAddress} ownerShares=${formatToken(ownerShares, vaultDecimals, 'shares')} totalSupply=${formatToken(totalShares, vaultDecimals, 'shares')}`
+    );
+    console.error(
+      `[withdraw] planned shares=${formatToken(shares ?? 0n, vaultDecimals, 'shares')} (${Number(withdrawPct ?? 0)}%)`
+    );
+  }
+
+  if (!shares || shares <= 0n) {
+    if (debug) console.error('[withdraw] no shares to withdraw; skipping');
+    return false;
+  }
+
+  try {
+    await client.setBalance({ address: ownerAddress, value: parseEther('0.05') });
+  } catch (_) {}
+  try {
+    await client.impersonateAccount({ address: ownerAddress });
+  } catch (_) {}
+
+  const [owner0Before, owner1Before, vault0Before, vault1Before] = await Promise.all([
+    client.readContract({
+      address: token0Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [ownerAddress],
+    }),
+    client.readContract({
+      address: token1Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [ownerAddress],
+    }),
+    client.readContract({
+      address: token0Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [vaultAddress],
+    }),
+    client.readContract({
+      address: token1Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [vaultAddress],
+    }),
+  ]);
+
+  if (debug) {
+    console.error(
+      `[withdraw] owner balances before: ${formatToken(owner0Before, token0Decimals, token0Symbol)}, ${formatToken(owner1Before, token1Decimals, token1Symbol)}`
+    );
+    console.error(
+      `[withdraw] vault  balances before: ${formatToken(vault0Before, token0Decimals, token0Symbol)}, ${formatToken(vault1Before, token1Decimals, token1Symbol)}`
+    );
+  }
+
+  const data = encodeWithdrawData(shares, ownerAddress);
+  const chain = viemChain || (await resolveViemChainFromClient(client));
+  const hash = await sendTransaction(client, {
+    account: ownerAddress,
+    to: vaultAddress,
+    data,
+    chain,
+  });
+  if (debug) console.error(`[withdraw] tx sent: ${hash}`);
+  await client.mine({ blocks: 1 });
+
+  const [owner0After, owner1After, vault0After, vault1After] = await Promise.all([
+    client.readContract({
+      address: token0Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [ownerAddress],
+    }),
+    client.readContract({
+      address: token1Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [ownerAddress],
+    }),
+    client.readContract({
+      address: token0Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [vaultAddress],
+    }),
+    client.readContract({
+      address: token1Address,
+      abi: ERC20_ABI,
+      functionName: 'balanceOf',
+      args: [vaultAddress],
+    }),
+  ]);
+
+  if (debug) {
+    console.error(
+      `[withdraw] owner balances after : ${formatToken(owner0After, token0Decimals, token0Symbol)}, ${formatToken(owner1After, token1Decimals, token1Symbol)}`
+    );
+    console.error(
+      `[withdraw] vault  balances after : ${formatToken(vault0After, token0Decimals, token0Symbol)}, ${formatToken(vault1After, token1Decimals, token1Symbol)}`
+    );
+    console.error(
+      `[withdraw] owner deltas: ${formatToken(BigInt(owner0After) - BigInt(owner0Before), token0Decimals, token0Symbol)}, ${formatToken(BigInt(owner1After) - BigInt(owner1Before), token1Decimals, token1Symbol)}`
+    );
+  }
+
+  return true;
+}
+
+function encodeWithdrawData(shares, ownerAddress) {
+  return encodeFunctionData({
+    abi: VAULT_ABI,
+    functionName: 'withdraw',
+    args: [shares, 0n, 0n, ownerAddress],
+  });
+}

package/templates/README.md

@@ -0,0 +1,37 @@
+Templates
+
+This folder contains ready-to-edit templates to help you get started quickly.
+
+Pick one of the CSVs below, copy it somewhere (or edit in place), fill in your addresses and options, then run the CLI with `--csv`.
+
+Files
+
+- pools_minimal.csv
+  - Minimal columns for running depth analysis per pool.
+  - Columns:
+    - pool: Uniswap v3 pool address (required)
+    - usd_sizes: Optional comma-separated USD sizes for price impact
+
+- pools_with_vault.csv
+  - Includes Steer vault withdraw simulation columns.
+  - Columns:
+    - pool: Uniswap v3 pool address (required)
+    - vault: Steer vault address (required for withdraw simulation)
+    - owner: Address whose shares will be withdrawn (required for withdraw simulation)
+    - withdraw_pct: Percent of owner shares to withdraw (e.g., 25). Use `withdraw_shares` if you prefer exact shares.
+    - usd_sizes: Optional comma-separated USD sizes for price impact
+
+Example commands
+
+- Minimal (on-chain via Tevm fork):
+  - liquidity-depth --csv ./templates/pools_minimal.csv --outdir ./reports --rpc https://developer-access-mainnet.base.org
+
+- With withdraw simulation (per-row):
+  - liquidity-depth --csv ./templates/pools_with_vault.csv --outdir ./reports --rpc https://developer-access-mainnet.base.org
+
+Notes
+
+- You can also set `--owner` and `--withdraw-pct` as CLI flags to apply globally and omit them from the CSV.
+- Prices source defaults to `auto`. You can override per-row with a `prices` column or globally with `--prices`.
+- If any row resolves invalid or missing addresses, that row will be skipped with a warning.
+

package/templates/pools_minimal.csv

@@ -0,0 +1,3 @@
+pool,usd_sizes
+0xPOOL_ADDRESS,"1000,5000,10000"
+

package/templates/pools_with_vault.csv

@@ -0,0 +1,3 @@
+pool,vault,owner,withdraw_pct,usd_sizes
+0xPOOL_ADDRESS,0xVAULT_ADDRESS,0xOWNER_ADDRESS,25,"1000,5000,10000,25000,50000"
+

package/dist/adapters/onchain.d.ts

@@ -1,51 +0,0 @@
-import { createMemoryClient } from 'tevm';
-import { Tick } from '../core/depth.js';
-export type PoolSnapshotOnchain = {
-    sqrtPriceX96: bigint;
-    tick: number;
-    liquidity: bigint;
-    feePips: number;
-    ticks: Tick[];
-    token0: {
-        decimals: number;
-        usdPrice: number;
-        id?: string;
-        symbol?: string;
-    };
-    token1: {
-        decimals: number;
-        usdPrice: number;
-        id?: string;
-        symbol?: string;
-    };
-    meta: {
-        token0: {
-            decimals: number;
-            id: string;
-            symbol?: string;
-        };
-        token1: {
-            decimals: number;
-            id: string;
-            symbol?: string;
-        };
-        poolId: string;
-        range: {
-            start: number;
-            end: number;
-        };
-        farPercent: number;
-        tickSpacing: number;
-    };
-};
-export declare function fetchPoolSnapshotViem(params: {
-    poolAddress: string;
-    rpcUrl?: string;
-    percentBuckets?: number[];
-    client?: ReturnType<typeof createMemoryClient>;
-}): Promise<PoolSnapshotOnchain>;
-export declare function fetchPoolSnapshotCore(params: {
-    poolAddress: string;
-    rpcUrl: string;
-    percentBuckets?: number[];
-}): Promise<PoolSnapshotOnchain>;

package/dist/adapters/onchain.js

@@ -1,158 +0,0 @@
-// On-chain fetcher for Uniswap v3 pools (TypeScript)
-import { createMemoryClient, http } from 'tevm';
-import { getAddress } from 'viem';
-import { readContract } from '@wagmi/core';
-import { configFromRpc } from '../wagmi/config.js';
-import { erc20Abi, uniswapV3PoolAbi } from '../wagmi/generated.js';
-// ABIs sourced from wagmi CLI generated file
-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(params) {
-    const { poolAddress, rpcUrl, percentBuckets = [1, 2, 5, 10], client } = params;
-    let c = client;
-    if (!c) {
-        if (!rpcUrl)
-            throw new Error('rpcUrl required when client is not provided');
-        c = createMemoryClient({ fork: { transport: http(rpcUrl), blockTag: 'latest' }, loggingLevel: 'error' });
-        if (c.tevmReady)
-            await c.tevmReady();
-    }
-    const pool = getAddress(poolAddress);
-    const [slot0Raw, LRaw, feeRaw, spacingRaw, token0Addr, token1Addr] = await Promise.all([
-        c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'slot0' }),
-        c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'liquidity' }),
-        c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'fee' }),
-        c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'tickSpacing' }),
-        c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'token0' }),
-        c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'token1' }),
-    ]);
-    const [dec0, sym0, dec1, sym1] = await Promise.all([
-        c.readContract({ address: token0Addr, abi: erc20Abi, functionName: 'decimals' }),
-        c.readContract({ address: token0Addr, abi: erc20Abi, functionName: 'symbol' }),
-        c.readContract({ address: token1Addr, abi: erc20Abi, functionName: 'decimals' }),
-        c.readContract({ address: token1Addr, abi: erc20Abi, functionName: 'symbol' }),
-    ]);
-    const sqrtPriceX96 = slot0Raw[0];
-    const tick = Number(slot0Raw[1]);
-    const liquidity = LRaw;
-    const feePips = Number(feeRaw);
-    const tickSpacing = Number(spacingRaw);
-    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 = [];
-    for (let w = wordStart; w <= wordEnd; w++) {
-        const bitmap = await c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'tickBitmap', args: [BigInt(w)] });
-        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;
-            const ret = await c.readContract({ address: pool, abi: uniswapV3PoolAbi, functionName: 'ticks', args: [t] });
-            const liquidityNet = ret[1];
-            ticks.push({ index: t, liquidityNet });
-        }
-    }
-    return {
-        sqrtPriceX96,
-        tick,
-        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 },
-        meta: {
-            token0: { decimals: Number(dec0), symbol: sym0, id: token0Addr },
-            token1: { decimals: Number(dec1), symbol: sym1, id: token1Addr },
-            poolId: pool,
-            range: { start, end },
-            farPercent: far,
-            tickSpacing,
-        },
-    };
-}
-// Fetch using wagmi/core actions (no TEVM), talking directly to RPC
-export async function fetchPoolSnapshotCore(params) {
-    const { poolAddress, rpcUrl, percentBuckets = [1, 2, 5, 10] } = params;
-    const cfg = await configFromRpc(rpcUrl);
-    const chainId = cfg.chains[0].id;
-    const pool = getAddress(poolAddress);
-    const [slot0Raw, LRaw, feeRaw, spacingRaw, token0Addr, token1Addr] = await Promise.all([
-        readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'slot0', chainId }),
-        readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'liquidity', chainId }),
-        readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'fee', chainId }),
-        readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'tickSpacing', chainId }),
-        readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'token0', chainId }),
-        readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'token1', chainId }),
-    ]);
-    const [dec0, sym0, dec1, sym1] = await Promise.all([
-        readContract(cfg, { address: token0Addr, abi: erc20Abi, functionName: 'decimals', chainId }),
-        readContract(cfg, { address: token0Addr, abi: erc20Abi, functionName: 'symbol', chainId }),
-        readContract(cfg, { address: token1Addr, abi: erc20Abi, functionName: 'decimals', chainId }),
-        readContract(cfg, { address: token1Addr, abi: erc20Abi, functionName: 'symbol', chainId }),
-    ]);
-    const sqrtPriceX96 = slot0Raw[0];
-    const tick = Number(slot0Raw[1]);
-    const liquidity = LRaw;
-    const feePips = Number(feeRaw);
-    const tickSpacing = Number(spacingRaw);
-    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 = [];
-    for (let w = wordStart; w <= wordEnd; w++) {
-        const bitmap = (await readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'tickBitmap', args: [BigInt(w)], chainId }));
-        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;
-            const ret = (await readContract(cfg, { address: pool, abi: uniswapV3PoolAbi, functionName: 'ticks', args: [t], chainId }));
-            const liquidityNet = ret[1];
-            ticks.push({ index: t, liquidityNet });
-        }
-    }
-    return {
-        sqrtPriceX96,
-        tick,
-        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 },
-        meta: {
-            token0: { decimals: Number(dec0), symbol: sym0, id: token0Addr },
-            token1: { decimals: Number(dec1), symbol: sym1, id: token1Addr },
-            poolId: pool,
-            range: { start, end },
-            farPercent: far,
-            tickSpacing,
-        },
-    };
-}

package/dist/adapters/uniswapv3-subgraph.d.ts

@@ -1,44 +0,0 @@
-import { Tick } from '../core/depth.js';
-export type PoolSnapshot = {
-    sqrtPriceX96: bigint;
-    tick: number;
-    liquidity: bigint;
-    feePips: number;
-    ticks: Tick[];
-    token0: {
-        decimals: number;
-        usdPrice: number;
-        id?: string;
-        symbol?: string;
-    };
-    token1: {
-        decimals: number;
-        usdPrice: number;
-        id?: string;
-        symbol?: string;
-    };
-    meta: {
-        token0?: {
-            decimals: number;
-            id: string;
-            symbol?: string;
-        };
-        token1?: {
-            decimals: number;
-            id: string;
-            symbol?: string;
-        };
-        ethPriceUSD?: number;
-        poolId: string;
-        range: {
-            start: number;
-            end: number;
-        };
-        farPercent: number;
-    };
-};
-export declare function fetchPoolSnapshot(params: {
-    poolAddress: string;
-    percentBuckets?: number[];
-    subgraphUrl?: string;
-}): Promise<PoolSnapshot>;