aggregator-hook-creator
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAggregator Hook Integration
Aggregator Hook 集成
Integrate external DEX liquidity (Curve, Balancer, Aerodrome, etc.) into Uniswap V4 routing via Aggregator Hooks.
通过Aggregator Hooks将外部DEX流动性（Curve、Balancer、Aerodrome等）集成到Uniswap V4路由中。
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.
Aggregator Hooks是Uniswap V4的钩子，用于封装非Uniswap池，使Uniswap路由器能够纳入外部流动性来源。通过跨多个协议路由至最优可用流动性，可提升执行质量。
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.
使用本方案需熟悉以下内容：
- viem 集成 - EVM 基础知识
- 兑换集成 - Uniswap 兑换模式
- Uniswap V4 Hook 架构基础
- v4-security-foundations - 在构建aggregator hooks前需完成安全基础技能学习。理解NoOp攻击、delta记账和访问控制至关重要。
Quick Decision Guide
快速决策指南
| Building... | Use This Approach |
|---|---|
| Single protocol (e.g., just Curve) | Protocol-Specific Hook (Proposal #2) |
| Multi-protocol aggregation | Generic Hook (Proposal #1) |
| Quick PoC / testing | Generic Hook with hardcoded calls |
| Production deployment at scale | Protocol-Specific Hooks |
| 构建场景 | 适用方案 |
|---|---|
| 单一协议（如仅Curve） | 协议专属Hook（方案#2） |
| 多协议聚合 | 通用Hook（方案#1） |
| 快速原型开发/测试 | 带硬编码调用的通用Hook |
| 大规模生产部署 | 协议专属Hook |
Supported Patterns
支持的模式
| Pattern | Description | Callbacks |
|---|---|---|
| Price Comparison | Compare V4 price with external source | |
| Split Routing | Split orders across multiple venues | |
| Fallback Routing | Route to external if V4 liquidity is low | |
| Analytics | Track routing decisions and volume | |
| 模式 | 描述 | 回调函数 |
|---|---|---|
| 价格对比 | 对比V4价格与外部来源价格 | |
| 拆分路由 | 在多个平台间拆分订单 | |
| ** fallback路由** | 当V4流动性不足时路由至外部来源 | |
| 数据分析 | 跟踪路由决策和交易量 | |
Hook Architecture
Hook架构
Proposal #1: Generic Hook (Single Deployment)
方案#1：通用Hook（单次部署）
A single hook that accepts encoded external calls via hookData. All routing logic is computed off-chain.
solidity
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.
单个Hook通过hookData接收编码后的外部调用。所有路由逻辑在链下计算。
solidity
struct ExternalAction {
address to; // 目标合约（如Curve池）
uint256 value; // 发送的ETH数量
bytes data; // 编码后的函数调用
}
// hookData = abi.encode(ExternalAction[])适用场景：快速原型开发、最大灵活性、不想为每个协议部署新合约。
优点：一次部署即可支持任意协议、面向未来、智能合约开发工作量更少。
缺点：链下集成更复杂、调用数据更大、链上索引更困难。
Proposal #2: Protocol-Specific Hooks (One Per DEX)
方案#2：协议专属Hook（每个DEX一个）
Dedicated hooks for each external protocol. The hook knows how to interact with its target DEX.
solidity
// 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.
为每个外部协议打造专属Hook。Hook知晓如何与目标DEX交互。
solidity
// CurveAggregatorHook.sol
contract CurveAggregatorHook is BaseHook {
ICurvePool public immutable curvePool;
function beforeSwap(...) external override {
// 从SwapParams编码Curve专属兑换调用
curvePool.exchange(i, j, dx, min_dy);
}
}适用场景：生产部署、优化Gas消耗、链下集成更简单。
优点：链下逻辑更简单、调用数据更少、审计更易。
缺点：需为每个池/协议部署新Hook、智能合约开发工作量更多、必须为每个DEX添加显式支持。
Protocol Compatibility Matrix
协议兼容性矩阵
| Protocol | Extra Hops | Callback? | Replaces Router? | Unique Pools? |
|---|---|---|---|---|
| Curve | 0 | No | Yes | No |
| Aerodrome | 0 | No | Yes | Yes |
| Balancer | 1 | No | No | No |
| Fluid V2 | 0 | Yes | Yes | No |
| Sushiswap | 0 | No | Yes | Yes |
| PancakeswapV3 | 0 | Yes | Yes | Yes |
- Unique Pools = Can use one hook per protocol (vs. one hook per pool)
- Extra Hops = Additional contract calls compared to direct DEX interaction
| 协议 | 额外调用次数 | 是否需要回调 | 是否替代路由器 | 是否支持单Hook多池 |
|---|---|---|---|---|
| Curve | 0 | 否 | 是 | 否 |
| Aerodrome | 0 | 否 | 是 | 是 |
| Balancer | 1 | 否 | 否 | 否 |
| Fluid V2 | 0 | 是 | 是 | 否 |
| Sushiswap | 0 | 否 | 是 | 是 |
| PancakeswapV3 | 0 | 是 | 是 | 是 |
- 是否支持单Hook多池 = 可单个Hook对应整个协议（而非单个Hook对应单个池）
- 额外调用次数 = 与直接DEX交互相比的额外合约调用次数
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
如需协议专属接口和实现细节，请参考：
- Curve：查看 references/protocols/curve.md
- Balancer：查看 references/protocols/balancer.md
- Aerodrome：查看 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
如需完整实现代码，包括：
- 通用Aggregator Hook（Solidity）
- 链下集成（TypeScript/viem）
- 测试套件（Foundry）
请查看 references/implementations.md
Security Considerations
安全注意事项
Must Validate
必须验证的内容
- External call safety: Verify external DEX responses; don't blindly trust return values
- Price manipulation: Don't trust single-block prices for large amounts; use TWAPs or multiple sources
- Reentrancy: Use appropriate guards for external calls; consider modifier
nonReentrant - Slippage: Respect user-specified slippage parameters; never allow zero minAmountOut
- 外部调用安全性：验证外部DEX的响应；不要盲目信任返回值
- 价格操纵防范：大额交易不要信任单区块价格；使用TWAP或多数据源
- 重入攻击防护：为外部调用使用适当的防护机制；考虑使用修饰器
nonReentrant - 滑点控制：遵守用户指定的滑点参数；绝不允许minAmountOut为0
Must Avoid
必须避免的操作
- Unbounded loops: Can cause out-of-gas; limit array sizes
- Hardcoded addresses: Use constructor parameters or governance-updatable storage
- Direct ETH handling: Use WETH wrapper for consistency
- Unchecked arithmetic: Use Solidity 0.8.x checked math
- 无界循环：可能导致Gas耗尽；限制数组大小
- 硬编码地址：使用构造函数参数或可通过治理更新的存储变量
- 直接处理ETH：使用WETH封装器以保证一致性
- 未检查的算术运算：使用Solidity 0.8.x的内置检查算术
Generic Hook Specific Risks
通用Hook专属风险
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
通用Hook模式允许任意外部调用，需考虑：
- 白名单机制：仅允许调用预批准的合约
- 函数选择器过滤：仅允许已知安全的函数选择器
- 金额限制：限制每次调用的ETH金额
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
- 审计Hook合约
- 使用分叉主网和真实池地址进行测试
- 验证代币授权流程是否正确
- 检查所有支持协议的Gas估算
- 使用正确的PoolManager地址部署Hook
- 初始化绑定Hook的池
- 测试端到端兑换流程
- 为RouteDecision事件设置监控
Troubleshooting
故障排除
| Issue | Cause | Solution |
|---|---|---|
| External call failed | Wrong calldata encoding | Verify function selector and parameters |
| Tokens stuck in hook | Missing sweep/transfer | Add token recovery in afterSwap |
| High gas usage | Inefficient external calls | Consider protocol-specific hooks |
| Hook not authorized | Wrong permissions | Check getHookPermissions() |
| Volume not tracking | afterSwap not enabled | Set afterSwap: true in permissions |
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 外部调用失败 | 调用数据编码错误 | 验证函数选择器和参数 |
| 代币滞留在Hook中 | 缺少清理/转账逻辑 | 在afterSwap中添加代币回收功能 |
| Gas消耗过高 | 外部调用效率低下 | 考虑使用协议专属Hook |
| Hook未授权 | 权限设置错误 | 检查getHookPermissions() |
| 交易量未被跟踪 | afterSwap未启用 | 在权限中设置afterSwap: true |
Research Notes
研究笔记
For open questions and ongoing research topics, see references/research-notes.md.
如需了解未解决问题和正在进行的研究主题，请查看 references/research-notes.md