test(v2-agg): complete V2 aggregator hook test suite

[SocksNFlops]

Tracks PROTO-1373 — PR 1 of the V2-on-V4 migration. Branched from `main` per Option B (independent of `socksnflops/eco-206-inherit-permissioned-router`).

What this commit lays down

• `test/foundry-tests/aggregators/_AggregatorBase.t.sol` — shared fork harness (block 23M), token constants (APE / WETH / USDC / DAI), `UniswapV2Aggregator` deployment via precompiled creation bytecode + inline HookMiner, canonical PoolKey builder.
• `test/foundry-tests/aggregators/v2/V2AggregatorMatrix.t.sol` — 24 cell stubs (Position × Token Role × Direction) plus 3 smoke tests. All currently `vm.skip` until per-cell bodies land in follow-up commits.
• `test/foundry-tests/aggregators/v2/interfaces/IUniswapV2Aggregator.sol` — minimal interface for cross-pragma calls.
• `test/foundry-tests/aggregators/v2/precompile/UniswapV2Aggregator.bin` — creation bytecode extracted from `v4-hooks-public` (regen instructions in the directory README).
• `test/foundry-tests/aggregators/README.md` — explains the approach, the matrix shape, and the precompile-regen procedure.
• `foundry.toml` — `fs_permissions` extended to read the precompile directory.

Why precompile + assembly create2 (not submodule)

`UniswapV2Aggregator` is pinned to `pragma solidity 0.8.29`; UR is pinned to `0.8.26`. The precompile + assembly create2 pattern (already used by v4-hooks-public itself for V2 factory) sidesteps the cross-version compilation problem and avoids the heavy `v4-hooks-public` + `protocol-fees` submodule tree.

Local verification

```
forge build --skip "test/integration-tests/" # compiles clean
forge test --match-path "test/foundry-tests/aggregators/"

27 passed; 0 failed; 0 skipped — onlyForked modifier no-ops cleanly without FORK_URL

```

What's NOT here yet (follow-up commits on this branch, before merge)

• Per-cell test bodies for the 24 matrix cells
• `V2AggregatorMultiHop.t.sol`, `V2AggregatorNative.t.sol`, `V2AggregatorFeeOnTransfer.t.sol`
• Gas snapshots (`gas/V2AggregatorGas.t.sol`)
• Invariant suite (`invariants/V2AggregatorInvariant.t.sol` + handler)

Reviewer notes

• No production-contract changes. Pure additive test scaffolding. Removing the V2 module happens in PR 2 (stacked on this branch, not yet pushed).
• Draft status until the matrix bodies are filled in and results are shared.

AI-Generated Description

Summary

End-to-end test suite proving Universal Router can route V2 swaps through V4's V4_SWAP command against a UniswapV2Aggregator hook — the prerequisite for deleting the V2-specific swap module (~1.5 KB bytecode recovery toward the EIP-170 limit).
Tracks PROTO-1373 — branched from main (independent of socksnflops/eco-206-inherit-permissioned-router).

Changes

Test framework (_AggregatorBase.t.sol)

• Shared fork harness pinned to mainnet block 23M with token constants (APE / WETH / USDC / DAI)
• In-tree UniswapV2AggregatorMock deployed via CREATE2 with inline HookMiner for correct permission-flag address
• Canonical PoolKey builder, user funding + Permit2 approval helpers, V4 plan encoders

24-cell matrix (V2AggregatorMatrix.t.sol)

• Full Position (Beginning / Middle / End) x Token Role (V2-only Input / Output) x Direction (exact-in / exact-out) coverage
• 2 valid V2-only cells with inline plan-structure proofs (SETTLE -> SWAP -> TAKE)
• SETTLE-omitted negative control proving the plan sequence is mandatory
• 4 structurally-impossible V2-only cells asserting PoolNotInitialized revert
• All 6 V2-Mostly cells (PM's aggregate balance backs the V2 hop)
• Multi-hop cells 11-24 covering chained V2-agg -> V4 and V4 -> V2-agg routes

Additional test suites

• V2AggregatorMultiHop.t.sol — differential quote-vs-execution check, bounded fuzz on single-hop amountIn
• V2AggregatorFeeOnTransfer.t.sol — exact-in FoT success, exact-out FoT revert (K-invariant violation), invariant fuzz (K non-decreasing, no residual tokens)
• V2AggregatorNative.t.sol — WRAP_ETH / UNWRAP_WETH composition; native currency initialize revert
• V2AggregatorIntermediateLimitation.t.sol — documents exact-out V2-only-intermediate limitation as acceptance criteria for flash-swap hook redesign

Gas snapshots (gas/V2AggregatorGas.t.sol)

• Single-hop and multi-hop gas benchmarks written to snapshots/V2AggregatorGas.json

Invariant suite (invariants/)

• V2AggregatorHandler.sol + V2AggregatorInvariant.t.sol — K non-decreasing and no-residual-tokens invariants under fuzzed swap sequences

Mocks

• UniswapV2AggregatorMock.sol — in-tree mock mirroring production hook behavior (same permission flags, _swapOnPair flow, BeforeSwapDelta shape) under ^0.8.24 pragma to avoid cross-version compilation issues
• MockFoTToken.sol — configurable fee-on-transfer ERC20 for FoT test paths

Why in-tree mock (not submodule)

UniswapV2Aggregator in v4-hooks-public is pinned to pragma 0.8.29; UR is on 0.8.26. The mock avoids dragging 5+ transitive submodules and lets tests override hook behavior for edge-case fuzzing.

Notes

• No production-contract changes — pure additive test scaffolding
• All tests gate on FORK_URL env var; without it, tests no-op cleanly via onlyForked modifier
• foundry.toml fs_permissions extended to read the test directory

[github-actions]

🤖 Claude PR Metadata Generation

Status: ❌ Error
Job: View workflow run

---

⚠️ Generation Failed

The automated PR title and description generation encountered an error.

Next Steps:

1. Check the workflow logs for details
2. Verify the GitHub Actions configuration
3. Ensure the Anthropic API key is valid

---

You can manually set the PR title and description, or re-trigger by pushing a new commit.

[linear]

PROTO-1373