Core architecture and vision

• beforeInitialize / afterInitialize
• beforeSwap / afterSwap
• beforeAddLiquidity / afterAddLiquidity
• beforeDonate / afterDonate

• On-chain Limit Orders: Create more expressive and gas-efficient limit orders than v3's range orders.
• Dynamic Fees: Implement fee structures that adjust algorithmically based on volatility or other on-chain data.
• Custom AMM Curves: Move beyond the standard concentrated liquidity model to implement unique bonding curves.
• Integrated MEV Protection: Build in mechanisms like routing trades through private relays or implementing TWAMM (Time-Weighted Average Market Maker) functionality to shield users.

• Pool Creation: Creating a new pool is no longer a full contract deployment (CREATE2) but a simple state update within the PoolManager, making it up to 99% cheaper.
• Multi-hop Swaps: When trading across multiple pools (e.g., A -> B -> C), tokens no longer need to be transferred between separate pool contracts. All accounting is handled internally within the singleton, drastically reducing gas costs for complex trades.

Security analysis: a proactive assessment

• Reentrancy Risk: The very nature of hooks reintroduces the risk of reentrancy attacks, a class of vulnerability that was largely solved in the core contracts of v2 and v3. A hook that makes an external call to an untrusted contract before its own state is fully updated could be exploited to drain funds or manipulate pool state.
• Malicious Logic and Access Control: A hook is arbitrary code. A malicious hook could be designed to siphon a percentage of a swap, front-run its own users, or block withdrawals under certain conditions. A critical vulnerability discovered in the Cork Protocol, which used a v4-style hook architecture, was due to a lack of access control. This allowed an attacker to call the hook's functions directly—bypassing the PoolManager—and manipulate its internal state to mint unbacked derivative tokens. This highlights the absolute necessity for hooks to verify that their caller is the legitimate PoolManager.
• Gas-Based Denial of Service (DoS): A hook containing an unbounded loop or a computationally expensive operation could consume all the gas in a transaction, causing it to revert. An attacker could exploit this to make a pool permanently unusable or to trap user funds by ensuring that any withdrawal transaction fails.

• Uniswap Labs is responsible for the security of the PoolManager kernel.
• Hook Developers are responsible for their code's security.
• End-Users are responsible for deciding which hooks to trust.

Developer integration guide

• Designing and Implementing Hooks: The primary development task in v4 is creating hooks. This involves selecting which core hook functions (beforeSwap, afterAddLiquidity, etc.) are needed and implementing them securely and efficiently.
• Hook Address Mining: A hook's permissions—which functions it is allowed to implement—are encoded in the least significant bits of its deployed contract address. This gas-saving measure allows the PoolManager to check permissions with bitwise operations instead of storage reads. Consequently, developers must use a "mining" tool (like the provided HookMiner utility) to find a CREATE2 salt that generates a contract address with the correct permission flags enabled.
• Interacting with the Singleton and unlock: All pool actions are initiated through the single PoolManager contract. The standard interaction pattern involves calling unlock, which grants the caller a temporary lock and makes a callback to the caller's contract. Within this callback, the developer can then execute a series of pool actions (swaps, liquidity modifications).
• Understanding Flash Accounting and Deltas: Integrations must be built around the flash accounting system. Logic should not track individual token transfers but instead operate on the BalanceDelta object returned by pool actions. This object represents the net change to a user's balance for each token at the end of the unlock scope.

• Access Control: All hook functions that are called by the PoolManager must verify that msg.sender is the PoolManager address to prevent direct, malicious external calls.
• Reentrancy Guards: Any hook function that performs an external call to another contract must use a reentrancy guard (nonReentrant modifier) to prevent recursive execution.
• Input Validation: Hooks must rigorously validate all parameters. An attacker could create a pool with malicious or non-standard ERC-20 tokens to exploit vulnerabilities in a hook's logic.
• State Management: If a hook is intended to be used by multiple pools, its state management must be carefully designed to prevent data from one pool from affecting another (e.g., by mapping state variables to the PoolId).
• Custom Accounting Risks: Hooks with permission to modify accounting deltas are particularly powerful and dangerous. The logic must be mathematically sound and rigorously tested to prevent exploits related to rounding errors, integer overflows/underflows, or economic manipulation.
• Trust Assumptions and Upgradeability: Developers must be transparent about their hook's trust assumptions. If a hook has a privileged owner or is upgradeable via a proxy, this introduces a significant centralization risk that must be secured by robust governance mechanisms, such as a timelock or a multi-signature wallet.

Guidance for securely forking and extending Uniswap v4

• Underestimating Core Complexity: Teams often fork code they do not fully understand. The v4 PoolManager relies on subtle interdependencies between the singleton architecture, flash accounting, transient storage (EIP-1153), and the hook callback system. A seemingly minor change to the accounting logic or lock mechanism can have catastrophic, cascading consequences that break core invariants.
• Introducing Unsafe Upgradeability: A common and dangerous mistake is wrapping the forked PoolManager in an upgradeable proxy controlled by a simple EOA or a small multi-sig. This centralizes control over all pools and liquidity, creating a single point of failure. A compromise of the admin key can lead to the instantaneous theft of all funds in the protocol.
• Neglecting the Hook Security Model: The security of a v4 fork is not just the core contract but the entire ecosystem of hooks built upon it. A forked protocol that fails to provide clear security guidelines, developer education, and tools for its hook builders is creating a dangerous environment. The responsibility for security is shared, and the fork's creator must lead that effort.
• Assuming Original Audits Are Sufficient: This is a critical error. Any modification, no matter how small, invalidates the security assumptions of the original audits. A fork is a new protocol and must undergo its own comprehensive, independent security review, including economic modeling and formal verification if possible.

1. Core protocol modifications

• Justify the Fork: Can your desired feature be implemented as a hook instead of a core protocol change? A core fork should be the absolute last resort.
• Invariant Testing: Have you written a comprehensive suite of invariant tests (e.g., using Foundry) to ensure your changes do not break the fundamental accounting principles of the protocol? Key invariants include:
  • The total balance of tokens held by the PoolManager must always equal the sum of all pool balances.
  • A user's balance delta can never be manipulated to create or destroy tokens.
• Analyze Gas and State Impact: How do your changes affect the gas cost of common operations like swaps and liquidity management? Have you introduced any new state growth vectors that could lead to gas bloat over time?
• Scrutinize Low-Level Code: If you modify any assembly or unchecked math blocks, have these changes been reviewed independently by multiple engineers and formally verified if possible? These are the most likely sources of critical bugs.

2. Hook ecosystem security

• Define a Hook Policy: Do you have a clear policy on the types of hooks that will be encouraged or discouraged in your ecosystem? Will you provide a registry or vetting process for third-party hooks?
• Developer Education: Have you created robust documentation, tutorials, and security best practices specifically for writing hooks on your forked protocol? This should include explicit warnings about reentrancy, access control, and state management.
• Governance of Hook Permissions: Have you considered the implications of the hook permission system? If you alter it, how will you prevent developers from creating overly-permissive, dangerous hooks?

3. Economic security

• Model Economic Interactions: Have you modeled how your core changes could interact with various hook designs to create novel economic exploits? For example, could a dynamic fee hook be manipulated to drain a pool when combined with a specific trade pattern?
• Oracle Integrity: If any of your changes affect the storage or calculation of ticks and liquidity, have you verified that the TWAP oracle remains manipulation-resistant?
• MEV Vector Analysis: Have you analyzed whether your modifications create new, profitable MEV opportunities (beyond standard arbitrage and sandwich attacks) that could harm users?

4. Operational security

• Secure Deployment and Administration: Is your deployment process scripted, tested, and secure? If the protocol includes any administrative roles (e.g., for protocol fee collection), how are those keys managed and secured?
• Incident Response Plan: Do you have a detailed incident response plan ready before launch? This should include monitoring systems, a communication strategy, a war room of technical and legal experts, and tools to pause the protocol if necessary.
• Bug Bounty Program: Have you funded and launched a competitive, public bug bounty program with clear scope and reward tiers? This should go live before your mainnet launch to attract white hats to review your code.

Conclusion

Get in touch

FAQ: Deep dive into the Uniswap protocol

Glossary