Uniswap v4 Hook Testing Framework

Comprehensive testing harness for Uniswap v4 hooks.

Overview

A Foundry-based testing framework that introspects hook permission flags, dynamically generates test scenarios, and validates both functional correctness and security properties of Uniswap v4 hooks.

Demo

uni-v4-hooks-checker.Demo.mp4

Key Features

Capability Detection

• Parses hook address flags to determine implemented callbacks
• Conditionally executes tests based on Hooks.Permissions bitmap
• Validates permission consistency between address flags and getHookPermissions()

Security Validation

• Access control: Verifies onlyPoolManager modifier on all entry points
• Delta integrity: Validates BeforeSwapDelta handling and settlement accounting
• State isolation: Checks for proper pool key validation and exclusivity patterns
• Return value correctness: Ensures proper selector returns for all callbacks

Functional Coverage

• Core operations: Swap (both directions), liquidity modification, donations
• Delta mechanics: Tests beforeSwapReturnDelta, afterAddLiquidityReturnDelta, etc.
• Edge cases: Sequential operations, boundary values, revert scenarios
• Integration: Full PoolManager interaction flows with proper router usage

Extensibility

• Fuzz testing support via Foundry's property-based testing
• Configurable strictness via environment variables
• Fork-compatible for testing deployed hooks
• Modular test suites for custom extension

Use Cases

Development & CI/CD

• Integration testing during hook development
• Regression detection in continuous integration pipelines
• Pre-deployment validation of security properties

Security Audits

• Automated verification of common vulnerability patterns
• Access control and authorization validation
• Delta manipulation and accounting correctness checks

Protocol Integration

• Third-party hook verification before allowlisting
• Compliance validation against Uniswap v4 hook standards
• Behavior analysis under various market conditions

Quick Start

1. Install Dependencies

First, install Foundry if you haven't already:

curl -L https://foundry.paradigm.xyz | bash
foundryup

2. Clone and Build

git clone <repository-url>
cd uni-v4-hooks-checker

# Initialize submodules and build
./build.sh

3. Try the Example Hook

Run the included example to see the framework in action:

forge test --match-contract ExampleHookTest -vv

This will:

• Deploy a fresh PoolManager
• Deploy the ExampleHook to a valid address
• Run all security and functional tests
• Show a detailed report of results

Architecture

This project uses a hybrid dependency management approach:

• Git Submodules: Complex Uniswap repositories (v4-core, v4-periphery, uniswap-hooks)
• Foundry Dependencies: Standard libraries (forge-std, solmate)

Why This Approach?

• Git submodules handle repositories with nested dependencies and complex structures
• Foundry dependencies manage simple, standalone libraries efficiently
• Unified build script (./build.sh) handles all setup automatically: submodules, dependencies, and compilation with correct remappings @uniswap/v4-core/=lib/v4-core/ @uniswap/v4-periphery/=lib/v4-periphery/ solmate/=lib/solmate/

4. Create Test Contract

Create `test/TestMyHook.t.sol`:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {MainTestEntry} from "uni-v4-hooks-checker/test/MainTestEntry.t.sol";

contract TestMyHook is MainTestEntry {}

5. Run Tests

Test your hook by setting its address:

# Set hook address and run all tests
HOOK_ADDRESS=0xYourHookAddress forge test --match-contract TestMyHook -vv

# Or with .env file
echo "HOOK_ADDRESS=0xYourHookAddress" > .env
forge test --match-contract TestMyHook -vv

Test Coverage

Functional

• Swap operations (single, multiple, exact in/out, price limits)
• Liquidity operations (add, remove, modify positions)
• Donate operations
• Initialize operations

Security

• Authorization and access control
• EOA guard validation
• Configuration checks
• Delta manipulation detection
• Exclusivity patterns

Analysis

• Hook capability detection
• Function introspection
• Coverage reporting

Configuration

Optional .env file:

HOOK_ADDRESS=0x...
POOL_MANAGER=0x...
RPC_URL=https://eth.llamarpc.com

Usage Examples

Test on Fork

# Test against mainnet fork
forge test --match-contract MainTestEntry \
  --fork-url https://eth.llamarpc.com \
  -vv

Test Locally with Anvil

# Terminal 1: Start local node
anvil --port 8545

# Terminal 2: Deploy your hook
forge script script/Deploy.s.sol \
  --rpc-url http://127.0.0.1:8545 \
  --private-key 0x0 \
  --broadcast

# Terminal 2: Run tests
HOOK_ADDRESS=0x... forge test \
  --match-contract MainTestEntry \
  --fork-url http://127.0.0.1:8545 \
  -vv

Run Fuzz Tests

HOOK_ADDRESS=0x... forge test \
  --match-contract FuzzTestEntry \
  --fuzz-runs 100 \
  -vv

Custom Tests

import {MainTestEntry} from "uv4-hook-check/test/MainTestEntry.t.sol";

contract TestHook is MainTestEntry {
    function test_custom() public onlyReady {
        (int256 amt0, int256 amt1) = _swap(key, true, -1e18, ZERO_BYTES);
        assertEq(amt0, expectedAmount);
    }
}

Troubleshooting

"Member not found" errors

Update your dependencies:

git submodule update --remote --merge
forge clean
forge build

"Hook not ready" message

Set the HOOK_ADDRESS environment variable or use --fork-url.

Tests fail with revert errors

Check that:

1. Your hook is properly deployed
2. The hook address has correct permission flags
3. Anvil is running if testing locally

Requirements

• Foundry (latest version)
• Solidity ^0.8.24
• Git

License

MIT