DeFi Pool Research
Research liquidity pools without confusing reported metrics, verified state, and missing evidence.
01 — The brief
Start with the useful tension.
Pool research can blur indexed snapshots, on-chain state, liquidity depth, historical fee attribution, and valuation assumptions. This tool keeps those boundaries visible while researching token markets and concentrated-liquidity pools.
Builders and analysts researching token markets, liquidity quality, pool history, fees, and concentrated-liquidity state across supported EVM chains.
Independently built the Node.js research CLI, protocol inspection paths, concentrated-liquidity math, and quality/provenance safeguards.
02 — Capability ledger
What exists, what is next.
A plain-language status check, so a polished surface never implies more than the work supports.
Implemented
06- Exact-address pool discovery
Queries indexed pool data for a token or pair, applies an exact chain filter, normalizes venues and direct-quote classification, and reports returned pools with links, reserves, volume, and turnover fields.
- Quality-first liquidity and valuation handling
Preserves missing or inconsistent values as unavailable, emits warnings for incomplete indexed coverage and price disagreement, distinguishes direct quote assumptions from other-token pairs, and avoids treating listed market cap or FDV as verified circulating-supply valuation.
- Uniswap v3/v4 pool inspection
Inspects a pool by URL or chain-specific identifier, dispatches between Uniswap v3 and v4 metadata, gathers trailing history and recent transaction samples, calculates indexed spot and fee context, and compares indexed competing pools.
- Optional pinned-block RPC verification
Adds bounded, read-only RPC checks when requested: chain identity, pinned block provenance, contract bytecode, token identity, decimals, total supply, pool state, fee, and marginal spot comparison on supported paths. Provider failures remain explicit and sellability is never inferred.
- Concentrated-liquidity math and position context
Provides zero-dependency ESM helpers for sqrt-price and tick conversion, range pricing, capital concentration, token split, principal amounts, boundary exits, and basic RPC decoding; position scripts expose v3/v4/Aerodrome-oriented range and fee context.
- Supported protocol and chain dispatch
Covers indexed discovery across the configured EVM chain list, with pool inspection for Uniswap v3/v4 and position scanning paths for configured Uniswap and Aerodrome managers; the source documents coverage limits instead of claiming an exhaustive census.
Planned
00Nothing recorded here yet.
Unverified
00Nothing recorded here yet.
03 — Design decisions
The reasoning stays in the room.
01Fast indexed default with opt-in verification
The default path keeps public discovery and inspection bounded; RPC reads are opt-in so the tool does not sweep every returned pool and can disclose exactly which state was independently checked.
02Unavailable is distinct from zero
Missing history, quotes, liquidity, or provider responses should not become fabricated zeros or annualized returns; warnings and reasons remain attached to the result.
03Exact addresses and conservative quote classification
Symbols are ambiguous across chains, so discovery matches token addresses and only treats configured canonical USDC, native ETH, and WETH addresses as direct quote classes.
04Protocol-aware fee and pool identity handling
Uniswap v3 pools and v4 singleton pool IDs have different state and fee semantics, so the inspector dispatches by protocol and keeps protocol-fee fields separate from historical LP fee attribution.
05Provenance and bounded failure handling
Every backend or RPC source carries an observation record, retry limits and redaction behavior, allowing a failed provider to remain visible without leaking credentials or silently switching semantics.
06No execution-depth or trading claim
TVL, active liquidity, historical volume, and marginal prices are reported as research context rather than as an executable quote or buy/sell recommendation; no transaction path is exposed.
04 — In the hand
Screens that explain themselves.
Images are shown as captured when available. Missing captures are labelled rather than quietly invented.
05 — A short walk-through
See the shape of the interaction.
CLI transcript: discover an exact token, inspect one pool, read quality warnings
- Start in a terminal using a credential-free scratch copy with no `.env`, then run `node scripts/find-pools.js 0xB095274743941e953c746F9C228DA9c18Bb6ec29 --chain base`.
- Show the returned-pool count, direct-quote scope, leading Aerodrome and Uniswap venues, and the indexed-only warnings without implying an exhaustive market census.
- Run `node scripts/inspect-pool.js --chain base --pool 0x7702411B3893ea4F6Ab96C50231cFEc65448AB9F` and open the generated quality report for the selected Uniswap v3 pool.
- Optionally run the supported `--verify` path against the configured public Base RPC; keep the pinned block/provenance when available and show `unavailable` plus the provider reason when bounded retries fail.
- End with history coverage, null net LP fee attribution, `executionDepth: not_verified`, and `sellability: not_tested` visible; no wallet, swap, signing, or transaction action occurs.
The materials