Skip to content

Latest commit

 

History

History
245 lines (176 loc) · 5.83 KB

README.md

File metadata and controls

245 lines (176 loc) · 5.83 KB

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