6 Essential Questions to Ask Before Building a Uniswap v4 Hook

Source: 6 Questions To Ask Before Writing a Uniswap v4 Hook - OpenZeppelin Blog

Uniswap v4’s new PoolManager enables custom hooks-special contracts that modify pool behavior mid-liquidity action. This unlocks powerful bespoke features but also brings complexity and security considerations.

Here’s a focused guide with 6 key questions every developer should ask before building a Uniswap v4 hook. These help ensure your hook is both functional and secure.

1. How Many Pools Will Use This Hook?

• Default behavior: Any pool can link to any eligible hook without the hook’s explicit approval.
• Single-pool hooks should:
  • Restrict usage to one pool only (e.g., limit initialization to a single `afterInitialize` call).
• Multi-pool hooks must:
  • Handle multiple pools calling simultaneously.
  • Isolate storage/state per pool to prevent data corruption or overwriting.
  • Accurately track which pool is interacting at any time, especially when modifying amounts through callbacks.

Properly managing these relationships avoids state clashes and keeps accounting accurate.

2. Does Your Hook Initiate Calls Back to the PoolManager?

• Hooks can call the PoolManager, not just respond to it.
• When your hook calls PoolManager functions, you must:
  • Implement `unlockCallback` carefully to control calldata and prevent unauthorized access.
  • Design calldata encoding/decoding to avoid injection risks, especially if using low-level assembly.
  • Consider that permissioned callbacks do not trigger if the hook itself calls PoolManager, but will if called by others.
  • Ensure your callback logic handles both cases correctly.

This reduces risks from unexpected or malicious interactions.

3. Will the Hook Call `modifyLiquidity` and Own Positions?

Hooks calling `modifyLiquidity` effectively own the liquidity positions they handle. This leads to important responsibilities:

• Fee management:
  • Correctly separate fee deltas from principal liquidity changes.
  • Handle fee attribution and distribution precisely to avoid misallocation.
• Delta handling:
  • Understand how slippage applies only to principal, not fees.
• Position uniqueness:
  • Use unique salts to identify positions unambiguously.
• Just-in-time liquidity risks:
  • Manage scenarios where liquidity is added or removed rapidly to prevent abuse.
• Minting shares:
  • If issuing custom “shares” to represent liquidity ownership, keep terminology clear:
  • “Liquidity” = Uniswap v4 units.
  • “Shares” = Hook-issued tokens.
• Convert consistently and watch for rounding errors when moving between amounts, liquidity, and shares.

Thorough testing and precise logic here protect fee integrity and user balances.

4. Do Your Swap Callbacks Handle All Swap Paths Symmetrically?

Swaps can be `exact-input` or `exact-output`, and amount deltas may be positive or negative. A proper hook must:

• Support callbacks before and after swaps.
• Adjust either `specifiedAmount` (provided by user) or `unspecifiedAmount` (calculated value) as needed.
• Handle the direction indicator (`zeroForOne` boolean).
• Maintain logical symmetry to cover all swap scenarios.

Custom swap logic-like anti-front-running mechanisms using reference prices-raises risks of price manipulation or logic errors:

• Ensure conditional checks for applying adjustments are bulletproof.
• Review math carefully to avoid rounding errors exploitable by attackers.

This maintains fairness and security across swap types.

5. Does Your Hook Support Native Tokens?

Native token pools require your hook to:

• Accept `msg.value` from users.
• Return any excess native tokens properly.
• Correctly interact with PoolManager for native token settlement.

Native tokens increase reentrancy risks and can distort accounting if not handled carefully, potentially opening manipulation vectors. Guard against reentrancy and test extensively.

6. How Is Access Control Implemented?

Access control is critical to prevent exploits like the recent $10M+ Cork protocol hack caused by insufficient restrictions.

• Validate callers where appropriate:
  • Is `msg.sender` the PoolManager or a trusted pool?
  • Prevent calls from malicious contracts or externally crafted transactions.
• Define administrative roles for:
  • Parameter initialization or updates.
  • Emergency function pausing.
  • Fund or fee management.
• Properly set function visibility (`public`, `external`, `internal`, `private`).
• Carefully analyze `unlockCallback` calldata handling to restrict callable functions.
• If upgradeable, strictly control who can perform upgrades.

Strong, well-architected access control prevents unauthorized state changes, funds mismanagement, and secures your hook’s integrity.

Conclusion

Uniswap v4 hooks open vast possibilities but bring new risks and subtle complexities. These 6 questions provide a foundational checklist to guide your design and security review.

Keep in mind:

• Hooks may introduce novel attack surfaces not seen in Uniswap v3.
• Detailed threat modeling and extensive testing remain essential.
• As the ecosystem evolves, expect new best practices to emerge.

Stay vigilant, iterate thoughtfully, and secure your hooks to tap into the full power of Uniswap v4’s PoolManager.