How to Start Your First Uniswap V4 Hook: Essentials, Libraries, and Risks

Setting up camp: the essentials

The Hooks library

• What's in it? This library contains constants for different hook flags (like BEFORE_SWAP_FLAG, AFTER_SWAP_FLAG), and functions for validating and calling hooks.
• What can you do? With this, you can specify exactly when your hook should spring into action. Want to do something before a swap? After adding liquidity? This is your go-to toolkit.

PoolKey and PoolId

• What are they? PoolKey is a struct that uniquely identifies a pool, while PoolId is a more gas-efficient representation of PoolKey.
• What can you do? You can use these to target specific pools, retrieve pool information, or create new pools with your hooks attached.

Currency library

• What's in it? Functions for transferring tokens, checking balances, and handling both native and ERC20 tokens uniformly.
• What can you do? You can create hooks that work seamlessly with any token type, opening up a world of possibilities for cross-token interactions.

BaseHook contract

• What is it? An abstract contract that implements the basic structure required for a Uniswap V4 hook.
• What can you do? By inheriting from this, you get a head start on hook development. It handles a lot of the boilerplate, letting you focus on your hook's unique features.

Crafting your first hook: a step-by-step guide

Step 1: Laying the foundation

1import {BaseHook} from "@uniswap/v4-periphery/contracts/BaseHook.sol";
2import {Hooks} from "@uniswap/v4-core/contracts/libraries/Hooks.sol";
3import {IPoolManager} from "@uniswap/v4-core/contracts/interfaces/IPoolManager.sol";
4import {PoolKey} from "@uniswap/v4-core/contracts/types/PoolKey.sol";
5import {PoolId, PoolIdLibrary} from "@uniswap/v4-core/contracts/types/PoolId.sol";
6import {Currency, CurrencyLibrary} from "@uniswap/v4-core/contracts/types/Currency.sol";
7import {FixedPointMathLib} from "solmate/src/utils/FixedPointMathLib.sol";
8
9contract MyAwesomeHook is BaseHook {
10    using StateLibrary for IPoolManager;
11    using PoolIdLibrary for PoolKey;
12    using CurrencyLibrary for Currency;
13    using FixedPointMathLib for uint256;
14
15    constructor(IPoolManager _poolManager) BaseHook(_poolManager) {}
16
17    // More exciting stuff to come!
18}

1. using StateLibrary for IPoolManager; — This enables efficient interaction with pool states. It allows you to call StateLibrary functions directly on IPoolManager objects, simplifying operations like querying pool liquidity or swap data.
2. using PoolIdLibrary for PoolKey; — This facilitates easy conversion between PoolKey structs and PoolIds. It's crucial for operations that require identifying specific pools, such as targeting hooks to particular trading pairs.
3. using CurrencyLibrary for Currency; — This statement enhances your ability to work with different token types uniformly. It enables direct use of CurrencyLibrary functions on Currency objects, streamlining token transfers, balance checks, and other token-related operations.
4. using FixedPointMathLib for uint256; — This provides access to precise mathematical operations crucial for DeFi applications. It allows you to perform fixed-point arithmetic on uint256 numbers, which is essential for accurate price calculations, fee computations, and other financial operations.

Step 2: Declaring your intentions

1function getHookPermissions() public pure override returns (Hooks.Permissions memory) {
2    return Hooks.Permissions({
3        beforeInitialize: false,
4        afterInitialize: false,
5        beforeAddLiquidity: false,
6        afterAddLiquidity: false,
7        beforeRemoveLiquidity: false,
8        afterRemoveLiquidity: false,
9        beforeSwap: false,
10        afterSwap: false,
11        beforeDonate: false,
12        afterDonate: false,
13        beforeSwapReturnDelta: false,
14        afterSwapReturnDelta: false,
15        afterAddLiquidityReturnDelta: false,
16        afterRemoveLiquidityReturnDelta: false
17    });
18}

Step 3: Adding your special sauce

1function beforeSwap(
2    address sender,
3    PoolKey calldata key,
4    IPoolManager.SwapParams calldata params,
5    bytes calldata data
6)
7    external
8    override
9    returns (bytes4)
10{
11    // Your magic goes here!
12    console.log("Ooh, a swap is about to happen from", sender);
13
14    // Don't forget this part!
15    return BaseHook.beforeSwap.selector;
16}

Step 4: Taking it for a spin

1. Deploy your hook contract to the blockchain.
2. When creating a new liquidity pool, you'd specify your hook's address.
3. Now, every time someone tries to swap in that pool, your beforeSwap function will run!

Important considerations

1. Gas Efficiency — In the world of Ethereum, every computation costs gas. Be mindful of your hook's complexity. Inefficient code can make your hook prohibitively expensive to use.
2. Reentrancy Risks — If your hook interacts with external contracts, be wary of reentrancy attacks. Always follow the checks-effects-interactions pattern.
3. Access Control — Ensure that sensitive functions in your hook can only be called by authorized addresses. Uniswap V4 provides some built-in protections, but it's still important to be vigilant. A critical vulnerability found in the Cork Protocol — which used a v4-style hook architecture — was due to a lack of access control, allowing an attacker to call the hook's functions directly.
4. State Management — Remember, hooks are designed to be stateless between calls. If you need to maintain state, do so carefully and consider the implications on gas costs and potential attack vectors.

5. Decimal Precision — When working with token amounts and prices, be extra careful with decimal precision. Rounding errors can lead to significant issues in financial calculations.
6. Testing — Thoroughly test your hooks in various scenarios. Uniswap provides a testing framework — use it extensively before even thinking about deploying to mainnet.
7. Upgradability — Consider whether your hook needs to be upgradable. If so, implement upgrade patterns carefully to avoid introducing vulnerabilities.
8. MEV Awareness — Be aware that sophisticated actors might try to exploit your hook for MEV (Miner Extractable Value). Design your hooks with this in mind.
9. Composability — Your hook might interact with other DeFi protocols. Always consider the broader ecosystem and potential unexpected interactions.
10. Audits — For any hook intended for production use, professional audits are a must. Even simple-looking code can have hidden vulnerabilities.

Complete template

1// SPDX-License-Identifier: MIT
2pragma solidity ^0.8.19;
3
4import {BaseHook} from "@uniswap/v4-periphery/contracts/BaseHook.sol";
5import {Hooks} from "@uniswap/v4-core/contracts/libraries/Hooks.sol";
6import {IPoolManager} from "@uniswap/v4-core/contracts/interfaces/IPoolManager.sol";
7import {PoolKey} from "@uniswap/v4-core/contracts/types/PoolKey.sol";
8import {PoolId, PoolIdLibrary} from "@uniswap/v4-core/contracts/types/PoolId.sol";
9import {Currency, CurrencyLibrary} from "@uniswap/v4-core/contracts/types/Currency.sol";
10import {FixedPointMathLib} from "solmate/src/utils/FixedPointMathLib.sol";
11
12contract MyAwesomeHook is BaseHook {
13    using PoolIdLibrary for PoolKey;
14    using CurrencyLibrary for Currency;
15    using FixedPointMathLib for uint256;
16
17    constructor(IPoolManager _poolManager) BaseHook(_poolManager) {}
18
19    function getHookPermissions() public pure override returns (Hooks.Permissions memory) {
20        return Hooks.Permissions({
21            beforeInitialize: false,
22            afterInitialize: false,
23            beforeAddLiquidity: false,
24            afterAddLiquidity: false,
25            beforeRemoveLiquidity: false,
26            afterRemoveLiquidity: false,
27            beforeSwap: true,
28            afterSwap: false,
29            beforeDonate: false,
30            afterDonate: false,
31            beforeSwapReturnDelta: false,
32            afterSwapReturnDelta: false,
33            afterAddLiquidityReturnDelta: false,
34            afterRemoveLiquidityReturnDelta: false
35        });
36    }
37
38    function beforeSwap(
39        address sender,
40        PoolKey calldata key,
41        IPoolManager.SwapParams calldata params,
42        bytes calldata data
43    )
44        external
45        override
46        returns (bytes4)
47    {
48        // Your custom logic goes here
49        console.log("Swap initiated by", sender);
50
51        return BaseHook.beforeSwap.selector;
52    }
53}

Wrapping up

1. You've set up the basic structure for a Uniswap V4 hook contract.
2. You've learned about the essential libraries and components that power these hooks.
3. You've implemented the getHookPermissions() function, which is crucial for defining your hook's capabilities.
4. You've created a simple beforeSwap function as a starting point for your hook's logic.

• You can expand on the beforeSwap function.
• You can explore other hook functions like afterSwap or beforeAddLiquidity to influence different aspects of trading. Our Uniswap V4 hooks Q&A covers the locking mechanism, transient accounting, and how hooks interact with the PoolManager in depth.
• You can dive deeper into the libraries we've introduced to create more sophisticated interactions with pools and tokens. For a full walkthrough of how swaps flow through V4 — exactInput, exactOutput, and BalanceDelta — read Uniswap V4 Swaps Explained.

Get in touch

FAQ

Glossary