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.

Executing locally with using Anvil:

1. Start Anvil (or fork a specific chain using anvil):

anvil

or

anvil --fork-url <YOUR_RPC_URL>

2. Execute scripts:

forge script script/00_DeployHook.s.sol \
    --rpc-url http://localhost:8545 \
    --private-key <PRIVATE_KEY> \
    --broadcast

Using RPC URLs (actual transactions):

:::info It is best to not store your private key even in .env or enter it directly in the command line. Instead use the --account flag to select your private key from your keystore. :::

Follow these steps if you have not stored your private key in the keystore:

1. Add your private key to the keystore:

cast wallet import <SET_A_NAME_FOR_KEY> --interactive

2. You will prompted to enter your private key and set a password, fill and press enter:

Enter private key: <YOUR_PRIVATE_KEY>
Enter keystore password: <SET_NEW_PASSWORD>

You should see this:

`<YOUR_WALLET_PRIVATE_KEY_NAME>` keystore was saved successfully. Address: <YOUR_WALLET_ADDRESS>

::: warning Use history -c to clear your command history. :::

1. Execute scripts:

forge script script/00_DeployHook.s.sol \
    --rpc-url <YOUR_RPC_URL> \
    --account <YOUR_WALLET_PRIVATE_KEY_NAME> \
    --sender <YOUR_WALLET_ADDRESS> \
    --broadcast

You will prompted to enter your wallet password, fill and press enter:

Enter keystore password: <YOUR_PASSWORD>

Key Modifications to note:

1. Update the token0 and token1 addresses in the BaseScript.sol file to match the tokens you want to use in the network of your choice for sepolia and mainnet deployments.
2. Update the token0Amount and token1Amount in the CreatePoolAndAddLiquidity.s.sol file to match the amount of tokens you want to provide liquidity with.
3. Update the token0Amount and token1Amount in the AddLiquidity.s.sol file to match the amount of tokens you want to provide liquidity with.
4. Update the amountIn and amountOutMin in the Swap.s.sol file to match the amount of tokens you want to swap.

Verifying the hook contract

forge verify-contract \
  --rpc-url <URL> \
  --chain <CHAIN_NAME_OR_ID> \
  # Generally etherscan
  --verifier <Verification_Provider> \
  # Use --etherscan-api-key <ETHERSCAN_API_KEY> if you are using etherscan
  --verifier-api-key <Verification_Provider_API_KEY> \
  --constructor-args <ABI_ENCODED_ARGS> \
  --num-of-optimizations <OPTIMIZER_RUNS> \
  <Contract_Address> \
  <path/to/Contract.sol:ContractName>
  --watch

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