@steerprotocol/liquidity-meter 1.0.0

package/dist/core/depth.d.ts

@@ -0,0 +1,48 @@
+export type Tick = {
+    index: number;
+    liquidityNet: bigint;
+};
+export type TokenInfoUSD = {
+    decimals: number;
+    usdPrice: number;
+};
+export type MarketDepthInput = {
+    sqrtPriceX96: bigint;
+    tick: number;
+    liquidity: bigint;
+    feePips?: number;
+    ticks: Tick[];
+    token0: TokenInfoUSD;
+    token1: TokenInfoUSD;
+    percentBuckets?: number[];
+};
+export type MarketDepthOutput = {
+    buyCumUSD: number[];
+    sellCumUSD: number[];
+    buyBandsUSD: number[];
+    sellBandsUSD: number[];
+    depthPlus2USD: number;
+    depthMinus2USD: number;
+    buyCumToken1: bigint[];
+    sellCumToken0: bigint[];
+};
+export type PriceImpactInput = {
+    sqrtPriceX96: bigint;
+    tick: number;
+    liquidity: bigint;
+    feePips?: number;
+    ticks: Tick[];
+    buySizesToken1: bigint[];
+    sellSizesToken0: bigint[];
+};
+export type PriceImpactOutput = {
+    buyPct: number[];
+    sellPct: number[];
+};
+export declare const DepthInternals: {
+    readonly MIN_TICK: -887272;
+    readonly MAX_TICK: 887272;
+};
+export declare function getSqrtRatioAtTick(tick: number): bigint;
+export declare function computeMarketDepthBands(input: MarketDepthInput): MarketDepthOutput;
+export declare function computePriceImpactsBySizes(input: PriceImpactInput): PriceImpactOutput;

package/dist/core/depth.js

@@ -0,0 +1,314 @@
+/*
+  Uniswap v3 market depth and price impact core (TypeScript)
+  - Pure functions, no network/IO
+  - BigInt math using Q64.96 fixed-point
+*/
+// ---------------- Fixed-point + constants ----------------
+const Q32 = 1n << 32n;
+const Q96 = 1n << 96n;
+const MAX_UINT256 = (1n << 256n) - 1n;
+export const DepthInternals = {
+    MIN_TICK: -887272,
+    MAX_TICK: 887272,
+};
+const MIN_SQRT_RATIO = 4295128739n;
+const MAX_SQRT_RATIO = 1461446703485210103287273052203988822378723970342n;
+function mulDiv(a, b, d) {
+    return (a * b) / d;
+}
+function mulDivRoundingUp(a, b, d) {
+    const prod = a * b;
+    const q = prod / d;
+    return prod % d === 0n ? q : q + 1n;
+}
+// ---------------- TickMath (v3 exact) ----------------
+// Returns Q64.96 sqrt price at the LOWER boundary of `tick`.
+export function getSqrtRatioAtTick(tick) {
+    if (tick < DepthInternals.MIN_TICK || tick > DepthInternals.MAX_TICK) {
+        throw new Error('TICK_OUT_OF_RANGE');
+    }
+    let absTick = tick < 0 ? -tick : tick;
+    // 1.0001^(2^i) constants in Q128.128
+    let ratio = (absTick & 0x1) !== 0
+        ? 0xfffcb933bd6fad37aa2d162d1a594001n
+        : 0x100000000000000000000000000000000n;
+    if ((absTick & 0x2) !== 0)
+        ratio = (ratio * 0xfff97272373d413259a46990580e213an) >> 128n;
+    if ((absTick & 0x4) !== 0)
+        ratio = (ratio * 0xfff2e50f5f656932ef12357cf3c7fdccn) >> 128n;
+    if ((absTick & 0x8) !== 0)
+        ratio = (ratio * 0xffe5caca7e10e4e61c3624eaa0941cd0n) >> 128n;
+    if ((absTick & 0x10) !== 0)
+        ratio = (ratio * 0xffcb9843d60f6159c9db58835c926644n) >> 128n;
+    if ((absTick & 0x20) !== 0)
+        ratio = (ratio * 0xff973b41fa98c081472e6896dfb254c0n) >> 128n;
+    if ((absTick & 0x40) !== 0)
+        ratio = (ratio * 0xff2ea16466c96a3843ec78b326b52861n) >> 128n;
+    if ((absTick & 0x80) !== 0)
+        ratio = (ratio * 0xfe5dee046a99a2a811c461f1969c3053n) >> 128n;
+    if ((absTick & 0x100) !== 0)
+        ratio = (ratio * 0xfcbe86c7900a88aedcffc83b479aa3a4n) >> 128n;
+    if ((absTick & 0x200) !== 0)
+        ratio = (ratio * 0xf987a7253ac413176f2b074cf7815e54n) >> 128n;
+    if ((absTick & 0x400) !== 0)
+        ratio = (ratio * 0xf3392b0822b70005940c7a398e4b70f3n) >> 128n;
+    if ((absTick & 0x800) !== 0)
+        ratio = (ratio * 0xe7159475a2c29b7443b29c7fa6e889d9n) >> 128n;
+    if ((absTick & 0x1000) !== 0)
+        ratio = (ratio * 0xd097f3bdfd2022b8845ad8f792aa5825n) >> 128n;
+    if ((absTick & 0x2000) !== 0)
+        ratio = (ratio * 0xa9f746462d870fdf8a65dc1f90e061e5n) >> 128n;
+    if ((absTick & 0x4000) !== 0)
+        ratio = (ratio * 0x70d869a156d2a1b890bb3df62baf32f7n) >> 128n;
+    if ((absTick & 0x8000) !== 0)
+        ratio = (ratio * 0x31be135f97d08fd981231505542fcfa6n) >> 128n;
+    if ((absTick & 0x10000) !== 0)
+        ratio = (ratio * 0x9aa508b5b7a84e1c677de54f3e99bc9n) >> 128n;
+    if ((absTick & 0x20000) !== 0)
+        ratio = (ratio * 0x5d6af8dedb81196699c329225ee604n) >> 128n;
+    if ((absTick & 0x40000) !== 0)
+        ratio = (ratio * 0x2216e584f5fa1ea926041bedfe98n) >> 128n;
+    if ((absTick & 0x80000) !== 0)
+        ratio = (ratio * 0x48a170391f7dc42444e8fa2n) >> 128n;
+    if (tick > 0)
+        ratio = MAX_UINT256 / ratio;
+    const sqrtPriceX96 = (ratio >> 32n) + (ratio % Q32 === 0n ? 0n : 1n);
+    return sqrtPriceX96;
+}
+// ---------------- Amount delta helpers ----------------
+function amount1DeltaUp(sqrtA, sqrtB, liquidity, roundUp = true) {
+    if (sqrtB < sqrtA)
+        [sqrtA, sqrtB] = [sqrtB, sqrtA];
+    const num = liquidity * (sqrtB - sqrtA);
+    return roundUp ? mulDivRoundingUp(num, 1n, Q96) : mulDiv(num, 1n, Q96);
+}
+function amount0DeltaDown(sqrtA, sqrtB, liquidity, roundUp = true) {
+    if (sqrtB < sqrtA)
+        [sqrtA, sqrtB] = [sqrtB, sqrtA];
+    const num = liquidity * (sqrtB - sqrtA) * Q96;
+    const den = sqrtB * sqrtA;
+    return roundUp ? mulDivRoundingUp(num, 1n, den) : mulDiv(num, 1n, den);
+}
+function grossUpForFee(amountIn, feePips) {
+    if (!feePips)
+        return amountIn;
+    const feeDen = 1000000n;
+    const den = feeDen - BigInt(feePips);
+    return mulDivRoundingUp(amountIn, feeDen, den);
+}
+// ---------------- Utilities ----------------
+function toUSDFromRaw(amount, decimals, usd) {
+    if (!usd || usd <= 0)
+        return 0;
+    const scale = 10n ** BigInt(Math.max(0, decimals));
+    const usdMicros = BigInt(Math.round(usd * 1e6));
+    const micros = (amount * usdMicros) / scale;
+    return Number(micros) / 1e6;
+}
+function clamp(val, lo, hi) {
+    return Math.max(lo, Math.min(hi, val));
+}
+function firstTickIndexGreaterThan(ticks, t) {
+    let lo = 0, hi = ticks.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (ticks[mid].index <= t)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+function lastTickIndexAtOrBelow(ticks, t) {
+    return firstTickIndexGreaterThan(ticks, t) - 1;
+}
+function percentToTickDelta(pct) {
+    const r = 1 + pct / 100;
+    const delta = Math.log(r) / Math.log(1.0001);
+    return Math.max(1, Math.round(delta));
+}
+// ---------------- Integrations ----------------
+function integrateUp(sqrtStart, currentTick, Lstart, targetTick, feePips, ticks) {
+    let s = sqrtStart;
+    let L = Lstart;
+    let tick = currentTick;
+    let i = firstTickIndexGreaterThan(ticks, tick);
+    const targetSqrt = getSqrtRatioAtTick(clamp(targetTick, DepthInternals.MIN_TICK, DepthInternals.MAX_TICK));
+    let acc = 0n;
+    while (s < targetSqrt) {
+        const nextTick = i < 0 || i >= ticks.length ? null : ticks[i];
+        const sqrtAtNext = nextTick ? getSqrtRatioAtTick(nextTick.index) : MAX_SQRT_RATIO;
+        const bound = sqrtAtNext < targetSqrt ? sqrtAtNext : targetSqrt;
+        const dy = amount1DeltaUp(s, bound, L, true);
+        const dyGross = grossUpForFee(dy, feePips);
+        acc += dyGross;
+        s = bound;
+        if (s === sqrtAtNext && nextTick) {
+            L = L + nextTick.liquidityNet;
+            tick = nextTick.index;
+            i += 1;
+        }
+        else {
+            break;
+        }
+    }
+    return { token1In: acc, finalSqrt: s, finalTick: tick, finalL: L };
+}
+function integrateDown(sqrtStart, currentTick, Lstart, targetTick, feePips, ticks) {
+    let s = sqrtStart;
+    let L = Lstart;
+    let tick = currentTick;
+    let j = lastTickIndexAtOrBelow(ticks, tick);
+    const targetSqrt = getSqrtRatioAtTick(clamp(targetTick, DepthInternals.MIN_TICK, DepthInternals.MAX_TICK));
+    let acc = 0n;
+    while (s > targetSqrt) {
+        const prevTick = j >= 0 ? ticks[j] : null;
+        const sqrtAtPrev = prevTick ? getSqrtRatioAtTick(prevTick.index) : MIN_SQRT_RATIO;
+        const bound = sqrtAtPrev > targetSqrt ? sqrtAtPrev : targetSqrt;
+        const dx = amount0DeltaDown(bound, s, L, true);
+        const dxGross = grossUpForFee(dx, feePips);
+        acc += dxGross;
+        s = bound;
+        if (s === sqrtAtPrev && prevTick) {
+            L = L - prevTick.liquidityNet;
+            tick = prevTick.index - 1;
+            j -= 1;
+        }
+        else {
+            break;
+        }
+    }
+    return { token0In: acc, finalSqrt: s, finalTick: tick, finalL: L };
+}
+// ---------------- Public API ----------------
+export function computeMarketDepthBands(input) {
+    const { sqrtPriceX96, tick, liquidity, feePips = 0, ticks, token0, token1, percentBuckets = [1, 2, 5, 10], } = input;
+    const sortedTicks = [...ticks].sort((a, b) => a.index - b.index);
+    const upTargets = percentBuckets.map((p) => clamp(tick + percentToTickDelta(p), DepthInternals.MIN_TICK, DepthInternals.MAX_TICK));
+    const downTargets = percentBuckets.map((p) => clamp(tick - percentToTickDelta(p), DepthInternals.MIN_TICK, DepthInternals.MAX_TICK));
+    const buyCumToken1 = [];
+    const sellCumToken0 = [];
+    let sU = sqrtPriceX96, tU = tick, LU = liquidity;
+    for (const tgt of upTargets) {
+        const { token1In, finalSqrt, finalTick, finalL } = integrateUp(sU, tU, LU, tgt, feePips, sortedTicks);
+        const cum = (buyCumToken1.length ? buyCumToken1[buyCumToken1.length - 1] : 0n) + token1In;
+        buyCumToken1.push(cum);
+        sU = finalSqrt;
+        tU = finalTick;
+        LU = finalL;
+    }
+    let sD = sqrtPriceX96, tD = tick, LD = liquidity;
+    for (const tgt of downTargets) {
+        const { token0In, finalSqrt, finalTick, finalL } = integrateDown(sD, tD, LD, tgt, feePips, sortedTicks);
+        const cum = (sellCumToken0.length ? sellCumToken0[sellCumToken0.length - 1] : 0n) + token0In;
+        sellCumToken0.push(cum);
+        sD = finalSqrt;
+        tD = finalTick;
+        LD = finalL;
+    }
+    const buyCumUSD = buyCumToken1.map((a) => toUSDFromRaw(a, token1.decimals, token1.usdPrice));
+    const sellCumUSD = sellCumToken0.map((a) => toUSDFromRaw(a, token0.decimals, token0.usdPrice));
+    const toBands = (cum) => [cum[0], cum[1] - cum[0], cum[2] - cum[1], cum[3] - cum[2]];
+    const buyBandsUSD = toBands(buyCumUSD);
+    const sellBandsUSD = toBands(sellCumUSD);
+    const idx2 = percentBuckets.findIndex((p) => p === 2);
+    const depthPlus2USD = idx2 >= 0 ? buyCumUSD[idx2] : NaN;
+    const depthMinus2USD = idx2 >= 0 ? sellCumUSD[idx2] : NaN;
+    return { buyCumUSD, sellCumUSD, buyBandsUSD, sellBandsUSD, depthPlus2USD, depthMinus2USD, buyCumToken1, sellCumToken0 };
+}
+// ---------------- Price impact by size ----------------
+function integrateUpByAmount(sqrtStart, currentTick, Lstart, budgetGross, // token1 gross in
+feePips, ticks) {
+    let s = sqrtStart;
+    let L = Lstart;
+    let tick = currentTick;
+    let i = firstTickIndexGreaterThan(ticks, tick);
+    const feeDen = 1000000n;
+    const den = feeDen - BigInt(feePips || 0);
+    while (budgetGross > 0n && s < MAX_SQRT_RATIO) {
+        const nextTick = i < 0 || i >= ticks.length ? null : ticks[i];
+        const sqrtAtNext = nextTick ? getSqrtRatioAtTick(nextTick.index) : MAX_SQRT_RATIO;
+        const dyNetToNext = amount1DeltaUp(s, sqrtAtNext, L, true);
+        const dyGrossToNext = grossUpForFee(dyNetToNext, feePips || 0);
+        if (budgetGross < dyGrossToNext) {
+            const netIn = mulDiv(budgetGross, den, feeDen);
+            const deltaS = mulDivRoundingUp(netIn, Q96, L);
+            s = s + deltaS;
+            budgetGross = 0n;
+            break;
+        }
+        else {
+            budgetGross -= dyGrossToNext;
+            s = sqrtAtNext;
+            if (nextTick) {
+                L = L + nextTick.liquidityNet;
+                tick = nextTick.index;
+                i += 1;
+            }
+        }
+    }
+    return { finalSqrt: s, finalTick: tick, finalL: L };
+}
+function integrateDownByAmount(sqrtStart, currentTick, Lstart, budgetGross, // token0 gross in
+feePips, ticks) {
+    let s = sqrtStart;
+    let L = Lstart;
+    let tick = currentTick;
+    let j = lastTickIndexAtOrBelow(ticks, tick);
+    const feeDen = 1000000n;
+    const den = feeDen - BigInt(feePips || 0);
+    while (budgetGross > 0n && s > MIN_SQRT_RATIO) {
+        const prevTick = j >= 0 ? ticks[j] : null;
+        const sqrtAtPrev = prevTick ? getSqrtRatioAtTick(prevTick.index) : MIN_SQRT_RATIO;
+        const dxNetToPrev = amount0DeltaDown(sqrtAtPrev, s, L, true);
+        const dxGrossToPrev = grossUpForFee(dxNetToPrev, feePips || 0);
+        if (budgetGross < dxGrossToPrev) {
+            const netIn = mulDiv(budgetGross, den, feeDen);
+            const LQ = L * Q96;
+            const num = LQ * s;
+            const den2 = LQ + netIn * s;
+            const bound = den2 === 0n ? MIN_SQRT_RATIO : mulDiv(num, 1n, den2);
+            s = bound;
+            budgetGross = 0n;
+            break;
+        }
+        else {
+            budgetGross -= dxGrossToPrev;
+            s = sqrtAtPrev;
+            if (prevTick) {
+                L = L - prevTick.liquidityNet;
+                tick = prevTick.index - 1;
+                j -= 1;
+            }
+        }
+    }
+    return { finalSqrt: s, finalTick: tick, finalL: L };
+}
+function priceImpactPercent(startSqrt, endSqrt) {
+    const a = startSqrt;
+    const b = endSqrt;
+    const scale = 1000000n;
+    const numRaw = (b - a) * (b + a) * 100n * scale;
+    const den = a * a;
+    let val;
+    if (numRaw >= 0n)
+        val = (numRaw + den / 2n) / den;
+    else
+        val = -((-numRaw + den / 2n) / den);
+    return Number(val) / Number(scale);
+}
+export function computePriceImpactsBySizes(input) {
+    const { sqrtPriceX96, tick, liquidity, feePips = 0, ticks, buySizesToken1, sellSizesToken0 } = input;
+    const sortedTicks = [...ticks].sort((a, b) => a.index - b.index);
+    const buyPct = [];
+    for (const size of buySizesToken1) {
+        const { finalSqrt } = integrateUpByAmount(sqrtPriceX96, tick, liquidity, size, feePips, sortedTicks);
+        buyPct.push(priceImpactPercent(sqrtPriceX96, finalSqrt));
+    }
+    const sellPct = [];
+    for (const size of sellSizesToken0) {
+        const { finalSqrt } = integrateDownByAmount(sqrtPriceX96, tick, liquidity, size, feePips, sortedTicks);
+        sellPct.push(priceImpactPercent(sqrtPriceX96, finalSqrt));
+    }
+    return { buyPct, sellPct };
+}

package/dist/handlers/cron.d.ts

@@ -0,0 +1,27 @@
+import { type MarketDepthOutput } from '../core/depth.js';
+export type DataSource = 'subgraph' | 'onchain' | 'auto';
+export type PriceSource = 'reserve' | 'dexscreener' | 'llama' | 'coingecko' | 'auto';
+export type LiquidityDepthJobConfig = {
+    pools: string[];
+    percentBuckets?: number[];
+    dataSource?: DataSource;
+    subgraphUrl?: string;
+    rpcUrl?: string;
+    priceSource?: PriceSource;
+    reserveLimit?: number;
+};
+export type LiquidityDepthJobResult = {
+    pool: string;
+    meta?: any;
+    usdPrices: {
+        token0USD?: number;
+        token1USD?: number;
+        source0?: string;
+        source1?: string;
+    };
+    depth: MarketDepthOutput;
+};
+export declare function runLiquidityDepthJob(cfg: LiquidityDepthJobConfig): Promise<{
+    timestamp: number;
+    results: LiquidityDepthJobResult[];
+}>;

package/dist/handlers/cron.js

@@ -0,0 +1,68 @@
+import { computeMarketDepthBands } from '../core/depth.js';
+import { fetchPoolSnapshot as fetchFromSubgraph } from '../adapters/uniswapv3-subgraph.js';
+import { fetchPoolSnapshotViem as fetchOnchain } from '../adapters/onchain.js';
+import { fetchTokenUSDPrices } from '../prices.js';
+function pickSource({ dataSource, rpcUrl }) {
+    if (dataSource === 'subgraph' || dataSource === 'onchain')
+        return dataSource;
+    if (rpcUrl)
+        return 'onchain';
+    return 'subgraph';
+}
+export async function runLiquidityDepthJob(cfg) {
+    const percentBuckets = (cfg.percentBuckets && cfg.percentBuckets.length) ? cfg.percentBuckets : [1, 2, 5, 10];
+    const results = [];
+    const when = Math.floor(Date.now() / 1000);
+    for (const pool of cfg.pools) {
+        const source = pickSource({ dataSource: cfg.dataSource, rpcUrl: cfg.rpcUrl });
+        let snap;
+        if (source === 'onchain') {
+            if (!cfg.rpcUrl)
+                throw new Error('rpcUrl required for onchain data source');
+            snap = await fetchOnchain({ poolAddress: pool, rpcUrl: cfg.rpcUrl, percentBuckets });
+        }
+        else {
+            snap = await fetchFromSubgraph({ poolAddress: pool, percentBuckets, subgraphUrl: cfg.subgraphUrl });
+        }
+        // Resolve USD prices, prefer snapshot-provided values if any
+        let token0USD = Number(snap.token0?.usdPrice || 0);
+        let token1USD = Number(snap.token1?.usdPrice || 0);
+        let src0;
+        let src1;
+        if (!token0USD || !token1USD) {
+            const id0 = snap.meta?.token0?.id || snap.token0?.id;
+            const id1 = snap.meta?.token1?.id || snap.token1?.id;
+            if (id0 && id1) {
+                const { byAddress } = await fetchTokenUSDPrices({ addresses: [String(id0), String(id1)], source: cfg.priceSource ?? 'auto', rpcUrl: cfg.rpcUrl, debug: false, reserveLimit: cfg.reserveLimit ?? 100 });
+                const p0 = byAddress[String(id0).toLowerCase()];
+                const p1 = byAddress[String(id1).toLowerCase()];
+                if (!token0USD && p0) {
+                    token0USD = p0.price;
+                    src0 = p0.source;
+                }
+                if (!token1USD && p1) {
+                    token1USD = p1.price;
+                    src1 = p1.source;
+                }
+            }
+        }
+        // Compute depth
+        const depth = 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,
+        });
+        results.push({
+            pool,
+            meta: snap.meta,
+            usdPrices: { token0USD, token1USD, source0: src0, source1: src1 },
+            depth,
+        });
+    }
+    return { timestamp: when, results };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './core/depth.js';
+export * from './adapters/uniswapv3-subgraph.js';
+export * from './adapters/onchain.js';
+export * from './adapters/withdraw.js';
+export * from './prices.js';
+export * from './handlers/cron.js';
+export * from './api.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './core/depth.js';
+export * from './adapters/uniswapv3-subgraph.js';
+export * from './adapters/onchain.js';
+export * from './adapters/withdraw.js';
+export * from './prices.js';
+export * from './handlers/cron.js';
+export * from './api.js';

package/dist/prices.d.ts

@@ -0,0 +1,15 @@
+export declare function fetchPricesLlama(addresses: string[]): Promise<Record<string, number>>;
+export declare function fetchPricesCoingecko(addresses: string[], apiKey?: string): Promise<Record<string, number>>;
+export declare function fetchTokenUSDPrices(opts: {
+    addresses: string[];
+    source?: 'reserve' | 'dexscreener' | 'llama' | 'coingecko' | 'auto';
+    rpcUrl?: string;
+    chainId?: number;
+    debug?: boolean;
+    reserveLimit?: number;
+}): Promise<{
+    byAddress: Record<string, {
+        price: number;
+        source: string;
+    }>;
+}>;