Aggregator Hook Integration

Integrate external DEX liquidity (Curve, Balancer, Aerodrome, etc.) into Uniswap V4 routing via Aggregator Hooks.

Overview

Aggregator Hooks are Uniswap V4 hooks that wrap non-Uniswap pools, allowing the Uniswap router to include external liquidity sources. This improves execution quality by routing through the best available liquidity across multiple protocols.

Prerequisites

This skill assumes familiarity with:

• viem Integration – EVM basics
• Swap Integration – Uniswap swap patterns
• Uniswap V4 hook architecture basics
• v4-security-foundations – Complete the security foundations skill before building aggregator hooks. Understanding NoOp attacks, delta accounting, and access control is essential.

Quick Decision Guide

Supported Patterns

Hook Architecture

Proposal #1: Generic Hook (Single Deployment)

A single hook that accepts encoded external calls via hookData. All routing logic is computed off-chain.

struct ExternalAction {
    address to;      // Target contract (e.g., Curve pool)
    uint256 value;   // ETH value to send
    bytes data;      // Encoded function call
}

// hookData = abi.encode(ExternalAction[])

When to use: Rapid prototyping, maximum flexibility, don’t want to deploy new contracts for each protocol.

Pros: Deploy once (supports any protocol), future-proof, less smart contract development.

Cons: More complex off-chain integration, larger calldata, harder to index on-chain.

Proposal #2: Protocol-Specific Hooks (One Per DEX)

Dedicated hooks for each external protocol. The hook knows how to interact with its target DEX.

// CurveAggregatorHook.sol
contract CurveAggregatorHook is BaseHook {
    ICurvePool public immutable curvePool;

    function beforeSwap(...) external override {
        // Encode Curve-specific swap call from SwapParams
        curvePool.exchange(i, j, dx, min_dy);
    }
}

When to use: Production deployments, optimized gas usage, simpler off-chain integration.

Pros: Simpler off-chain logic, less calldata, easier to audit.

Cons: Deploy new hook per pool/protocol, more smart contract development, must add explicit support for each DEX.

Protocol Compatibility Matrix

• Unique Pools = Can use one hook per protocol (vs. one hook per pool)
• Extra Hops = Additional contract calls compared to direct DEX interaction

Protocol Integration Guides

For protocol-specific interfaces and implementation details:

• Curve: See references/protocols/curve.md
• Balancer: See references/protocols/balancer.md
• Aerodrome: See references/protocols/aerodrome.md

Implementation

For full implementation code including:

• Generic Aggregator Hook (Solidity)
• Off-chain integration (TypeScript/viem)
• Test suite (Foundry)

See references/implementations.md

Security Considerations

Must Validate

1. External call safety: Verify external DEX responses; don’t blindly trust return values
2. Price manipulation: Don’t trust single-block prices for large amounts; use TWAPs or multiple sources
3. Reentrancy: Use appropriate guards for external calls; consider nonReentrant modifier
4. Slippage: Respect user-specified slippage parameters; never allow zero minAmountOut

Must Avoid

1. Unbounded loops: Can cause out-of-gas; limit array sizes
2. Hardcoded addresses: Use constructor parameters or governance-updatable storage
3. Direct ETH handling: Use WETH wrapper for consistency
4. Unchecked arithmetic: Use Solidity 0.8.x checked math

Generic Hook Specific Risks

The generic hook pattern allows arbitrary external calls. Consider:

• Allowlisting: Only permit calls to pre-approved contracts
• Selector filtering: Only permit known-safe function selectors
• Value limits: Cap ETH value per call

Deployment Checklist

• Audit hook contract
• Test on forked mainnet with real pool addresses
• Verify token approvals flow correctly
• Check gas estimates for all supported protocols
• Deploy hook with correct PoolManager address
• Initialize pools with hook attached
• Test end-to-end swap flow
• Set up monitoring for RouteDecision events

Troubleshooting

Research Notes

For open questions and ongoing research topics, see references/research-notes.md.

References

• Uniswap V4 Hooks
• Hook Permissions
• BaseHook Contract
• Curve Technical Docs
• Balancer V2 Docs
• Aerodrome Docs