Uniswap v4 Hook Template

A template for writing Uniswap v4 Hooks 🦄

Get Started

This template provides a starting point for writing Uniswap v4 Hooks, including a simple example and preconfigured test environment. Start by creating a new repository using the "Use this template" button at the top right of this page. Alternatively you can also click this link:

1. The example hook Counter.sol demonstrates the beforeSwap() and afterSwap() hooks
2. The test template Counter.t.sol preconfigures the v4 pool manager, test tokens, and test liquidity.

Updating to v4-template:latest

This template is actively maintained -- you can update the v4 dependencies, scripts, and helpers:

git remote add template https://github.com/uniswapfoundation/v4-template
git fetch template
git merge template/main <BRANCH> --allow-unrelated-histories

Requirements

This template is designed to work with Foundry (stable). If you are using Foundry Nightly, you may encounter compatibility issues. You can update your Foundry installation to the latest stable version by running:

foundryup

To set up the project, run the following commands in your terminal to install dependencies and run the tests:

forge install
forge test

Local Development

Other than writing unit tests (recommended!), you can only deploy & test hooks on anvil locally. Scripts are available in the script/ directory, which can be used to deploy hooks, create pools, provide liquidity and swap tokens. The scripts support both local anvil environment as well as running them directly on a production network.

Troubleshooting

Permission Denied

When installing dependencies with forge install, Github may throw a Permission Denied error

Typically caused by missing Github SSH keys, and can be resolved by following the steps here

Or adding the keys to your ssh-agent, if you have already uploaded SSH keys

Anvil fork test failures

Some versions of Foundry may limit contract code size to ~25kb, which could prevent local tests to fail. You can resolve this by setting the code-size-limit flag

anvil --code-size-limit 40000

Hook deployment failures

Hook deployment failures are caused by incorrect flags or incorrect salt mining

1. Verify the flags are in agreement:
   • getHookCalls() returns the correct flags
   • flags provided to HookMiner.find(...)
2. Verify salt mining is correct:
   • In forge test: the deployer for: new Hook{salt: salt}(...) and HookMiner.find(deployer, ...) are the same. This will be address(this). If using vm.prank, the deployer will be the pranking address
   • In forge script: the deployer must be the CREATE2 Proxy: 0x4e59b44847b379578588920cA78FbF26c0B4956C
     • If anvil does not have the CREATE2 deployer, your foundry may be out of date. You can update it with foundryup

Additional Resources

• Uniswap v4 docs
• v4-periphery
• v4-core
• v4-by-example