HookLens

HookLens is a comprehensive, open-source Uniswap v4 hook inspector and swap simulation workspace designed specifically for developers, smart contract auditors, and DeFi researchers.

With the introduction of Uniswap v4, developers can now deploy "hooks"—custom smart contracts that execute logic at specific points in a pool's lifecycle (like before or after a swap, or when modifying liquidity). While hooks are incredibly powerful, they introduce a critical problem: to users and external developers, hooks act as black boxes. It is difficult to ascertain exactly what permissions a hook has, whether its code is safe, and most importantly, whether routing a swap through a specific hook pool provides better execution compared to the broader market. HookLens solves this transparency problem through a holistic suite of discovery, inspection, and simulation tools.

Key Features & Core Value Propositions:

1. Live Hook Discovery & Dashboard: HookLens taps directly into the Uniswap v4 subgraphs on networks like Ethereum and Base to provide a live pulse of the hook ecosystem. Users don't have to guess which hooks are active; the dashboard aggregates pool activity, indexing 7-day and 30-day volume windows. This allows researchers to immediately identify which hooks are managing real capital and generating genuine traction.

2. Deep Contract Inspection & Flag Decoding: When a user clicks into a specific hook address, HookLens demystifies the contract. It instantly decodes all 14 of the Uniswap v4 hook permission bits. At a glance, users can see exactly what the hook is authorized to do (e.g., beforeSwap, afterAddLiquidity, beforeDonate, etc.).

3. Source-Code Verification & Safety Analysis: To address security concerns, HookLens automatically interfaces with Sourcify to pull verified smart contract source code. It then runs a deterministic static safety analysis pipeline against the code, automatically flagging common hook-specific risks, vulnerabilities, or unusual patterns before a user ever interacts with the pool.

4. Deterministic Swap Simulation (AI Studio): Static analysis is only half the battle; understanding practical execution is critical. In the HookLens "AI Studio," users can run a sophisticated, 6-step deterministic swap-routing pipeline: Plan, Quote, Score, Classify Risk, Decide, and Report.

5. Privacy-Preserving AI Auditor (Ollama Integration): Because swap routing data and security flags can be complex to interpret, HookLens integrates a local AI assistant powered by Ollama. Once the routing engine generates a final swap report, users can chat directly with the local AI. The AI acts as a dedicated smart contract auditor, answering questions about the hook's performance metrics and security flags while ensuring all data stays completely private and local.

Technical Architecture: Built for high performance, HookLens utilizes a React 18 frontend with Vite, TypeScript, and Tailwind CSS. It manages state via Zustand and relies on @uniswap/sdk-core and @uniswap/v4-sdk for precise native token and decimal resolution. The backend relies on dual Vite and Vercel serverless proxies to securely manage API keys for the Uniswap Trading API, while local Docker containers effortlessly spin up the environment alongside the Ollama AI models.

By combining on-chain discovery, permission decoding, security analysis, side-by-side quote comparison, and local AI chatting, HookLens transforms Uniswap v4 hooks from opaque black boxes into transparent, verifiable, and strictly measurable financial primitives.

HookLens is built as a highly responsive single-page application prioritizing performance and a smooth developer experience. The frontend is built using React 18, Vite, TypeScript, and Tailwind CSS, with state management handled gracefully by Zustand and routing by React Router.

Partner Technologies & Core Integrations: The backbone of HookLens relies heavily on Uniswap's latest stack. We integrated @uniswap/sdk-core and @uniswap/v4-sdk to cleanly handle Currency, Token, Ether, and WETH9 primitives. This was crucial for accurately normalizing human-readable token amounts into base units and managing exact token decimals across multiple chains without rewriting complex math logic.

For discovery, we utilized The Graph, querying the Uniswap v4 subgraphs on Base and Ethereum to aggregate live pool data, extracting 7-day and 30-day volume windows so users can see which hooks are actually managing capital.

For smart contract inspection, we integrated Sourcify. Instead of relying on closed-source block explorers, HookLens pings Sourcify to fetch verified contract code. We then run a custom, deterministic static safety analysis directly against this verified code to flag common hook-specific risks.

The Swap Simulation Engine: The most complex piece of architecture is our AI Studio swap simulator (src/api/uniswap.ts and src/api/agentEngine.ts). When a user runs a simulation, HookLens interfaces with the Uniswap Trading API. To determine if a hook is genuinely beneficial, the engine constructs and fires two parallel API requests:

1. A quote strictly forcing hook execution using protocols: ["V4"] and the hooksOptions: "V4_HOOKS_ONLY" parameter.
2. A standard market quote using routingPreference: "BEST_PRICE".

Our deterministic agent engine then strips down both API responses, extracts the outputAmount, gasFee, and slippage, and scores them against each other to deliver a definitive execution recommendation.

Finally, we integrated Ollama for our AI auditing chat. Rather than relying on cloud-based LLMs which pose privacy risks for proprietary smart contract audits, we run local models (like llama3.2). The app communicates with Ollama's REST API natively via standard fetch requests, avoiding bulky npm dependencies.

Hacky / Notable Workarounds: Building a bleeding-edge v4 integration came with unique challenges that required some creative engineering:

1. Beating the Rate Limit: Because our core value proposition requires comparing two complex quotes simultaneously, we quickly hit the Uniswap Trading API's 3 requests/sec rate limit. Our "hacky" but highly effective fix was to implement an asynchronous queue that artificially spaces out the hook quote and market quote requests by a few hundred milliseconds, completely eliminating 429 errors without hurting UX.
2. CORS & API Key Protection: Browsers enforce strict CORS policies, and exposing our Uniswap API key in the frontend bundle was a security risk. We built a dynamic proxy layer: in development, Vite intercepts and proxies the API calls; in production, we wrote custom Vercel Serverless Functions (api/uniswap/[...path].js) that append the API keys server-side and forward the requests, keeping the frontend fully decoupled from the secrets.
3. Parsing Opaque API Errors: When a V4_HOOKS_ONLY route fails (often because hook liquidity is still sparse), the Trading API returns deeply nested and highly varied error shapes under txFailureReason. We wrote custom extraction logic to parse these disparate error trees, transforming opaque JSON reverting errors into clean, human-readable UI feedback that tells the user exactly why the hook failed to route.