@bananapus/router-terminal-v6 0.0.10 → 0.0.12

package/AUDIT_INSTRUCTIONS.md

@@ -0,0 +1,283 @@
+# nana-router-terminal-v6 -- Audit Instructions
+
+Target: experienced Solidity auditors reviewing the Juicebox V6 router terminal.
+
+## Architecture Overview
+
+The router terminal accepts any token and dynamically discovers what each destination Juicebox project accepts. It then routes the payment there via direct forwarding, Uniswap swap (V3 or V4), JB token cashout, or a combination. It is stateless between transactions -- it holds no persistent balances, no queued operations, no pending state.
+
+Two contracts. One library. One struct.
+
+### Contract Table
+
+| Contract | Lines | Role |
+|----------|-------|------|
+| `JBRouterTerminal` | ~1,437 | Core routing engine. Accepts any token, discovers destination project's accepted token, converts via wrap/unwrap, Uniswap V3 swap, Uniswap V4 swap, or JB token cashout chain, then forwards to destination terminal. Implements `IJBTerminal`, `IJBPermitTerminal`, `IUniswapV3SwapCallback`, `IUnlockCallback`. |
+| `JBRouterTerminalRegistry` | ~481 | Maps projects to their preferred router terminal instance. Owner-managed allowlist of terminals. Default terminal fallback. Lock terminal pattern for immutability. Implements `IJBTerminal`. |
+| `JBSwapLib` (library) | ~161 | Continuous sigmoid slippage tolerance calculation. Price impact estimation. `sqrtPriceLimitX96` computation from input/output amounts. |
+| `PoolInfo` (struct) | ~14 | Tagged union: `{isV4, v3Pool, v4Key}`. Carries the winning pool from discovery. |
+
+### Dependency Graph
+
+```
+JBRouterTerminal
+  ├── JBPermissioned (nana-core-v6) -- permission checks
+  ├── Ownable (OZ) -- owner management (unused operationally)
+  ├── ERC2771Context (OZ) -- meta-transactions
+  ├── IJBTerminal -- terminal interface
+  ├── IJBPermitTerminal -- Permit2 support
+  ├── IUniswapV3SwapCallback -- V3 swap callback
+  ├── IUnlockCallback -- V4 swap callback
+  ├── JBSwapLib -- slippage math
+  ├── JBDirectory -- terminal/controller lookup
+  ├── JBTokens -- credit transfers, projectIdOf lookups
+  ├── IUniswapV3Factory -- V3 pool discovery & verification
+  ├── IPoolManager -- V4 swap execution & pool state reads
+  ├── IPermit2 -- token transfer with Permit2
+  └── IWETH9 -- wrap/unwrap native token
+
+JBRouterTerminalRegistry
+  ├── JBPermissioned -- permission checks
+  ├── Ownable -- owner-only admin (allow/disallow/setDefault)
+  ├── ERC2771Context -- meta-transactions
+  ├── IJBTerminal -- forwards pay/addToBalanceOf
+  └── IPermit2 -- token transfer with Permit2
+```
+
+### Immutable State (JBRouterTerminal)
+
+| Name | Type | Purpose |
+|------|------|---------|
+| `DIRECTORY` | `IJBDirectory` | Project terminal/controller lookup |
+| `PROJECTS` | `IJBProjects` | ERC-721 project ownership |
+| `TOKENS` | `IJBTokens` | Credit transfers, token-to-project mapping |
+| `FACTORY` | `IUniswapV3Factory` | V3 pool discovery and callback verification |
+| `POOL_MANAGER` | `IPoolManager` | V4 swap execution (can be `address(0)` if V4 unavailable) |
+| `PERMIT2` | `IPermit2` | Token transfer utility |
+| `WETH` | `IWETH9` | Native token wrapping/unwrapping |
+
+### Mutable State (JBRouterTerminalRegistry)
+
+| Name | Visibility | Purpose |
+|------|-----------|---------|
+| `defaultTerminal` | `public` | Fallback terminal for projects without explicit assignment |
+| `hasLockedTerminal` | `public mapping` | Per-project lock flag (irreversible) |
+| `isTerminalAllowed` | `public mapping` | Allowlist of terminals the owner has approved |
+| `_terminalOf` | `internal mapping` | Per-project explicit terminal assignment |
+
+## V3/V4 Pool Routing Mechanics
+
+### Pool Discovery
+
+`_discoverPool(normalizedTokenIn, normalizedTokenOut)` searches 8 pools total:
+
+**V3 (4 fee tiers):** 3000 (0.3%), 500 (0.05%), 10000 (1%), 100 (0.01%). Each is looked up via `FACTORY.getPool()`. Liquidity read via `pool.liquidity()`.
+
+**V4 (4 fee/tickSpacing pairs):** 3000/60, 500/10, 10000/200, 100/1. Each is looked up via `POOL_MANAGER.getSlot0(key.toId())` -- a zero `sqrtPriceX96` means the pool does not exist. Liquidity read via `POOL_MANAGER.getLiquidity()`.
+
+The pool with the highest in-range liquidity wins. If `POOL_MANAGER == address(0)`, V4 search is skipped entirely.
+
+### Quote Computation
+
+Quote priority in `_pickPoolAndQuote()`:
+
+1. **User-provided quote** -- If `quoteForSwap` metadata key is present, its value is used as `minAmountOut` directly. This is the recommended path for all swaps, especially V4.
+2. **V3 TWAP** -- `_getV3TwapQuote()` uses `OracleLibrary.consult()` with a 10-minute window (capped to oldest available observation). Computes `minAmountOut = twapQuote * (1 - sigmoidSlippage)`.
+3. **V4 spot price** -- `_getV4SpotQuote()` reads instantaneous tick from `getSlot0()`. Same sigmoid slippage formula applied. This is manipulable within a single block.
+
+### Sigmoid Slippage Formula
+
+```
+impact = amountIn * PRECISION / liquidity * (sqrtP or 1/sqrtP)
+tolerance = minSlippage + (MAX_SLIPPAGE - minSlippage) * impact / (impact + SIGMOID_K)
+```
+
+Where:
+- `minSlippage = max(poolFee + 100 bps, 200 bps)` -- floor of 2%
+- `MAX_SLIPPAGE = 8800 bps` -- ceiling of 88%
+- `SIGMOID_K = 5e16` -- steepness parameter
+- `IMPACT_PRECISION = 1e18`
+
+### Swap Execution
+
+**V3 path:** Direct `pool.swap()` call. Callback `uniswapV3SwapCallback()` wraps ETH if needed and transfers input tokens to the pool. Callback is verified by computing `FACTORY.getPool(tokenA, tokenB, fee)` and checking it matches `msg.sender`.
+
+**V4 path:** `POOL_MANAGER.unlock(data)` triggers `unlockCallback()`. Inside the callback: `POOL_MANAGER.swap()` executes the trade, `_settleV4()` pays the input, `_takeV4()` receives the output. For native ETH output, received ETH is immediately wrapped to WETH (downstream `_handleSwap` unwraps if the destination needs native token). Callback verified by `msg.sender == address(POOL_MANAGER)`.
+
+### Leftover Handling
+
+After a swap, `_handleSwap()` measures the balance delta of the input token. If the swap was a partial fill (sqrtPriceLimit hit), leftover input tokens are returned to `_msgSender()`. For native token inputs, any remaining raw ETH is wrapped to WETH before the delta check, then unwrapped for the refund.
+
+## Cashout Loop
+
+When the input token is a JB project token (detected via `TOKENS.projectIdOf()` or `cashOutSource` metadata), the router enters `_cashOutLoop()`:
+
+1. Check if the destination project directly accepts the current token. If yes, return.
+2. Determine the source project ID (from metadata override or token lookup).
+3. Call `_findCashOutPath()` which searches source project terminals for:
+   - **Priority 1:** A reclaimable token the destination directly accepts.
+   - **Priority 2:** A reclaimable JB project token (can recurse).
+   - **Priority 3:** Any base token (the router will swap it later).
+4. Execute `cashOutTerminal.cashOutTokensOf()` to reclaim tokens.
+5. Loop back to step 1 with the reclaimed token.
+
+**Iteration cap:** `_MAX_CASHOUT_ITERATIONS = 20`. Exceeding this reverts with `JBRouterTerminal_CashOutLoopLimit()`.
+
+**Slippage:** The `cashOutMinReclaimed` metadata value is applied only to the first cashout step. Subsequent steps have zero per-step minimum. The final output amount is validated by the destination terminal's `minReturnedTokens` parameter.
+
+**Circular dependency:** If token A cashes out to token B and token B cashes out to token A, the loop hits the 20-iteration cap and reverts cleanly (no fund loss, only gas wasted).
+
+## Lock Terminal Pattern
+
+The registry implements a two-phase terminal assignment:
+
+1. **Set:** `setTerminalFor(projectId, terminal)` -- requires `SET_ROUTER_TERMINAL` permission and terminal must be in the allowlist. Can be changed freely while unlocked.
+
+2. **Lock:** `lockTerminalFor(projectId, expectedTerminal)` -- requires `SET_ROUTER_TERMINAL` permission. The `expectedTerminal` parameter is a race condition guard: if the resolved terminal (explicit or default) does not match, the call reverts with `TerminalMismatch`. Once locked, `hasLockedTerminal[projectId] = true` and `setTerminalFor()` reverts permanently.
+
+**Default snapshot on lock:** If a project has no explicit terminal at lock time, the current `defaultTerminal` is snapshotted into `_terminalOf[projectId]` before locking. This insulates the project from future default changes.
+
+**Irreversibility:** There is no `unlockTerminalFor()`. Locking is permanent.
+
+## Fee-on-Transfer Token Risks
+
+**JBRouterTerminal:** Uses balance-delta accounting in `_acceptFundsFor()` (lines 550-556). Measures `balanceBefore` and `balanceAfter` the transfer, returning the actual amount received. This correctly handles fee-on-transfer tokens at the acceptance stage. However, the amount forwarded to the destination terminal is the delta, which may differ from what the destination terminal expects if it also performs balance-delta checks.
+
+**JBRouterTerminalRegistry:** Does NOT use balance-delta accounting in `_acceptFundsFor()` (line 437). It returns the user-supplied `amount` directly. If a fee-on-transfer token is used through the registry, the forwarded amount will exceed actual tokens received, causing a downstream revert or incorrect accounting.
+
+**Audit focus:** Verify that the registry's `_acceptFundsFor` cannot be exploited with fee-on-transfer tokens. The comment on line 433-435 states these are "not supported by design" -- confirm this is documented clearly enough and that no path silently loses funds.
+
+## uint160 Permit2 Truncation Risk
+
+Both contracts cast `amount` to `uint160` when falling through to `PERMIT2.transferFrom()`:
+
+- `JBRouterTerminal._transferFrom()` line 1425: `if (amount > type(uint160).max) revert JBRouterTerminal_AmountOverflow(amount);`
+- `JBRouterTerminalRegistry._transferFrom()` line 477: `if (amount > type(uint160).max) revert JBRouterTerminalRegistry_AmountOverflow();`
+
+Both contracts now revert before truncation occurs. Verify these overflow checks are complete and that no code path can reach the `uint160()` cast without hitting the guard.
+
+**Practical risk:** Low. ERC-20 supplies rarely approach `type(uint160).max` (~1.46e48). But the check is there -- verify it.
+
+## Short TWAP Window Concerns
+
+`_getV3TwapQuote()` defaults to a 10-minute TWAP window (`DEFAULT_TWAP_WINDOW = 600 seconds`). If the pool's oldest observation is younger than 10 minutes, the window is silently capped:
+
+```solidity
+if (oldestObservation < twapWindow) twapWindow = oldestObservation;
+```
+
+If `oldestObservation == 0`, the function reverts with `JBRouterTerminal_NoObservationHistory()`.
+
+**Risk:** A pool with 30 seconds of observation history produces a "TWAP" that is functionally a spot price. This is the same vulnerability as the V4 spot price path, but without the V4 label warning users.
+
+**Audit focus:** Consider whether the contract should enforce a minimum observation age (e.g., revert if `oldestObservation < 5 minutes`). Currently, any non-zero observation age is accepted.
+
+## Priority Audit Areas
+
+### Critical Path: Payment Routing
+
+The most complex and highest-value code path. Follow a payment from `pay()` through:
+
+1. `_acceptFundsFor()` -- token acceptance (native, ERC-20, Permit2, credit cashout)
+2. `_route()` -- routing decision (JB token cashout path vs. resolve+convert)
+3. `_cashOutLoop()` -- recursive cashout when input is a JB project token
+4. `_resolveTokenOut()` -- discover what the destination project accepts
+5. `_convert()` -- same-token no-op, wrap/unwrap, or Uniswap swap
+6. `_handleSwap()` -> `_executeSwap()` -> V3 or V4 execution
+7. `_beforeTransferFor()` -- allowance setup before forwarding
+8. `destTerminal.pay()` -- final forwarding
+
+**Key question:** Can any combination of inputs cause tokens to be stuck in the router? The contract has no sweep/rescue function and an empty `receive()`.
+
+### Callback Verification
+
+- **V3:** `uniswapV3SwapCallback()` reads `fee` from caller, computes expected pool via `FACTORY.getPool()`, checks `msg.sender == expectedPool`. Standard pattern but verify a malicious contract cannot satisfy this check.
+- **V4:** `unlockCallback()` checks `msg.sender == address(POOL_MANAGER)`. The PoolManager's unlock pattern prevents reentrancy by design. Verify no path allows a reentrant call through `POOL_MANAGER.unlock()`.
+
+### Slippage Math
+
+The sigmoid formula in `JBSwapLib` is novel. Verify:
+- Floor enforcement: `getSlippageTolerance(0, feeBps)` always returns `>= 200 bps`.
+- Ceiling enforcement: result never exceeds `MAX_SLIPPAGE (8800)`.
+- Monotonicity: higher impact always yields higher tolerance.
+- No overflow: `impact + SIGMOID_K` cannot overflow `uint256`.
+- `sqrtPriceLimitFromAmounts()` correctly handles edge cases (zero amounts, extreme ratios, boundary tick values).
+
+### Registry Trust Model
+
+- Owner can `setDefaultTerminal()` and redirect all unlocked projects.
+- Owner can `disallowTerminal()` which clears default if it matches.
+- `lockTerminalFor()` race condition guard: verify the `expectedTerminal` check is correct.
+- Verify `setTerminalFor()` correctly blocks when `hasLockedTerminal[projectId]` is true.
+
+## Invariants
+
+These should hold for every transaction and can be used as fuzzing properties:
+
+1. **Zero balance after pay/addToBalanceOf**: `address(routerTerminal).balance == 0` and `IERC20(anyToken).balanceOf(address(routerTerminal)) == 0` after every `pay()` or `addToBalanceOf()` call completes.
+
+2. **No silent truncation**: No code path reaches a `uint160()` cast with a value exceeding `type(uint160).max` without reverting first.
+
+3. **Cashout loop termination**: `_cashOutLoop()` always terminates in at most 20 iterations (revert or return).
+
+4. **Callback caller verification**: `uniswapV3SwapCallback()` only executes token transfers when `msg.sender` is a legitimate V3 pool. `unlockCallback()` only executes when `msg.sender == address(POOL_MANAGER)`.
+
+5. **Locked terminal immutability**: Once `hasLockedTerminal[projectId]` is true, `_terminalOf[projectId]` never changes.
+
+6. **Slippage floor**: `JBSwapLib.getSlippageTolerance(impact, feeBps)` always returns `>= max(feeBps + 100, 200)` (unless the ceiling applies).
+
+7. **TWAP window lower bound**: `_getV3TwapQuote()` reverts when `oldestObservation == 0`.
+
+8. **Leftover refund correctness**: After `_handleSwap()`, the balance delta of the input token (relative to the pre-swap snapshot) is returned to `_msgSender()`. No input tokens remain in the contract.
+
+## Testing Setup
+
+### Running Tests
+
+```bash
+# Unit tests (mocked dependencies, no RPC needed)
+forge test --match-path "test/RouterTerminal.t.sol"
+forge test --match-path "test/RouterTerminalRegistry.t.sol"
+forge test --match-path "test/regression/*.t.sol"
+
+# Fork tests (requires Ethereum mainnet RPC)
+# Set RPC_ETHEREUM_MAINNET in .env or foundry.toml
+forge test --match-path "test/RouterTerminalFork.t.sol" --fork-url $RPC_ETHEREUM_MAINNET
+forge test --match-path "test/RouterTerminalSandwichFork.t.sol" --fork-url $RPC_ETHEREUM_MAINNET
+forge test --match-path "test/RouterTerminalFeeCashOutFork.t.sol" --fork-url $RPC_ETHEREUM_MAINNET
+
+# All tests
+forge test
+```
+
+### Foundry Configuration
+
+- Solidity 0.8.26, EVM target `cancun`, optimizer 200 runs
+- Fuzz runs: 4,096 per test
+- Invariant runs: 1,024 with depth 100
+- Fork tests pinned to Ethereum mainnet block 21,700,000 (post-V4 deployment)
+
+### Test Coverage Summary
+
+| Test File | Type | Coverage Area | Count |
+|-----------|------|---------------|-------|
+| `RouterTerminal.t.sol` | Unit (mocked) | Core routing, swap paths, cashout, V4, pool discovery, TWAP, errors | ~35 |
+| `RouterTerminalRegistry.t.sol` | Unit (mocked) | Allow/disallow, set/lock, forwarding, permissions | ~12 |
+| `RouterTerminalFork.t.sol` | Fork (mainnet) | End-to-end swaps: ETH->USDC, USDC->ETH, ETH->DAI, addToBalance, quote metadata | ~12 |
+| `RouterTerminalFeeCashOutFork.t.sol` | Fork (mainnet) | Fee routing through cashout: project 3 payouts -> fee -> cashout -> project 1 | 1 |
+| `RouterTerminalSandwichFork.t.sol` | Fork (mainnet) | MEV/sandwich: V3 TWAP resistance, V4 spot manipulation, user quote | 4 |
+| `regression/LockTerminalRace.t.sol` | Unit | Race condition in `lockTerminalFor` with `expectedTerminal` | 3 |
+| `regression/CashOutLoopLimit.t.sol` | Unit | Circular cashout loop cap at 20 iterations | 2 |
+| `regression/V4SpotPriceSlippage.t.sol` | Unit + fuzz | Sigmoid math: floor, ceiling, monotonicity, bounded range, user quote | 14 |
+
+### Coverage Gaps Worth Investigating
+
+| Area | Status | Why It Matters |
+|------|--------|----------------|
+| Fee-on-transfer tokens | NOT TESTED | Registry `_acceptFundsFor` does not use balance-delta |
+| Short TWAP windows (<60s) | NOT TESTED | Silently degrades to near-spot-price |
+| Multi-hop cashout chains (>1 step) | NOT TESTED | Only the circular case and single-step are tested |
+| V4 pools with custom hooks | NOT TESTED | All V4 tests use `hooks: IHooks(address(0))` |
+| Concurrent pay + addToBalance | NOT TESTED | Mitigated by stateless design but worth verifying |
+| Credit cashout path (fork) | NOT TESTED | Only unit-mocked, no fork test with real credits |
+| addToBalanceOf with cashout routing | PARTIALLY | Fork covers ETH->USDC, not cashout or credit paths |

package/CHANGE_LOG.md

@@ -0,0 +1,290 @@
+# nana-router-terminal-v6 Changelog (v5 → v6)
+
+This document describes all changes between `nana-swap-terminal` (v5) and `nana-router-terminal-v6` (v6).
+
+**Note:** This repo was renamed from `nana-swap-terminal` to `nana-router-terminal` in v6.
+
+---
+
+## 1. Breaking Changes
+
+### 1.1 Contract Renamed: `JBSwapTerminal` → `JBRouterTerminal`
+The main contract was renamed from `JBSwapTerminal` (and `JBSwapTerminal5_1`) to `JBRouterTerminal`. All error prefixes, interface names, and references changed accordingly.
+
+### 1.2 No Fixed `TOKEN_OUT` — Dynamic Token Discovery
+- **v5:** The terminal had an immutable `TOKEN_OUT` address set at construction. All incoming tokens were swapped to this single output token. Projects had to explicitly configure pools via `addDefaultPool()`.
+- **v6:** The terminal dynamically discovers what token each destination project accepts by querying `DIRECTORY.primaryTerminalOf()` and iterating the project's terminal accounting contexts. There is no `TOKEN_OUT` immutable. The `_OUT_IS_NATIVE_TOKEN` flag is also removed.
+
+### 1.3 Constructor Parameters Changed
+- **v5:** `constructor(directory, permissions, projects, permit2, owner, weth, tokenOut, factory, trustedForwarder)` — required a fixed `tokenOut` and reverted on `address(0)`.
+- **v6:** `constructor(directory, permissions, projects, tokens, permit2, owner, weth, factory, poolManager, trustedForwarder)` — added `IJBTokens tokens` and `IPoolManager poolManager`; removed `tokenOut`.
+
+### 1.4 `IJBSwapTerminal` Interface Removed, Replaced by `IJBRouterTerminal`
+- **v5 `IJBSwapTerminal`** exposed: `DEFAULT_PROJECT_ID()`, `MAX_TWAP_WINDOW()`, `MIN_TWAP_WINDOW()`, `MIN_DEFAULT_POOL_CARDINALITY()`, `UNCERTAIN_SLIPPAGE_TOLERANCE()`, `SLIPPAGE_DENOMINATOR()`, `twapWindowOf()`, `addDefaultPool()`, `addTwapParamsFor()`.
+- **v6 `IJBRouterTerminal`** exposes only: `discoverBestPool()`, `discoverPool()`.
+- All pool/TWAP configuration functions are removed (see section 1.5).
+
+### 1.5 Removed: Per-Project Pool Configuration and TWAP Management
+The following functions and storage were removed entirely in v6:
+- `addDefaultPool(uint256 projectId, address token, IUniswapV3Pool pool)` — projects no longer manually configure pools.
+- `addTwapParamsFor(uint256 projectId, IUniswapV3Pool pool, uint256 secondsAgo)` — TWAP windows are no longer project-configurable.
+- `getPoolFor(uint256 projectId, address tokenIn)` — pool lookup is now fully automatic.
+- `twapWindowOf(uint256 projectId, IUniswapV3Pool pool)` — replaced by a fixed `DEFAULT_TWAP_WINDOW = 10 minutes`.
+- Storage mappings `_poolFor`, `_accountingContextFor`, `_tokensWithAContext`, `_twapWindowOf` — all removed.
+
+### 1.6 Removed: Constants
+The following public constants from v5 were removed:
+- `DEFAULT_PROJECT_ID` (was `0`)
+- `MAX_TWAP_WINDOW` (was `2 days`)
+- `MIN_TWAP_WINDOW` (was `2 minutes`)
+- `MIN_DEFAULT_POOL_CARDINALITY` (was `10`)
+- `UNCERTAIN_SLIPPAGE_TOLERANCE` (was `1050`)
+
+The `SLIPPAGE_DENOMINATOR` constant was kept but changed from `uint160` to `uint256`.
+
+### 1.7 `supportsInterface` Changed
+- **v5:** Reported support for `IJBTerminal`, `IJBPermitTerminal`, `IERC165`, `IUniswapV3SwapCallback`, `IJBPermissioned`, `IJBSwapTerminal`.
+- **v6:** Reports support for `IJBTerminal`, `IJBPermitTerminal`, `IERC165`, `IJBPermissioned` only. No longer advertises `IUniswapV3SwapCallback` or the custom interface.
+
+### 1.8 Permission ID Changed (Registry)
+- **v5:** `lockTerminalFor()` and `setTerminalFor()` used `JBPermissionIds.ADD_SWAP_TERMINAL_POOL`.
+- **v6:** These functions use `JBPermissionIds.SET_ROUTER_TERMINAL`.
+
+### 1.9 `lockTerminalFor` Signature Changed (Registry)
+- **v5:** `lockTerminalFor(uint256 projectId)` — no confirmation of which terminal is being locked.
+- **v6:** `lockTerminalFor(uint256 projectId, IJBTerminal expectedTerminal)` — requires the caller to confirm the expected terminal, preventing race conditions where the default changes between transaction submission and execution.
+
+### 1.10 Accounting Contexts Are Now Dynamic
+- **v5:** `accountingContextForTokenOf()` looked up stored contexts from `_accountingContextFor` mappings (set via `addDefaultPool`). `accountingContextsOf()` merged project-specific and default-project contexts.
+- **v6:** `accountingContextForTokenOf()` is `pure` and returns a synthetic context with 18 decimals for any token. `accountingContextsOf()` returns an empty array since the terminal accepts any token dynamically.
+
+### 1.11 Solidity Version
+- **v5:** `pragma solidity 0.8.23`
+- **v6:** `pragma solidity 0.8.26`
+
+---
+
+## 2. New Features
+
+### 2.1 Uniswap V4 Support
+The terminal now supports swapping via both Uniswap V3 and V4 pools. Pool discovery (`_discoverPool`) searches across all V3 fee tiers and V4 fee/tickSpacing combinations, selecting whichever pool has the highest in-range liquidity.
+
+New V4-specific components:
+- `IPoolManager POOL_MANAGER` immutable (can be `address(0)` if V4 is unavailable).
+- `IUnlockCallback` interface implemented via `unlockCallback()`.
+- `_executeV4Swap()`, `_settleV4()`, `_takeV4()`, `_discoverV4Pool()` internal functions.
+- `_getV4SpotQuote()` — uses instantaneous spot price with sigmoid slippage (security note: not MEV-resistant; users should provide `quoteForSwap` metadata).
+- `_V4_FEES` and `_V4_TICK_SPACINGS` arrays for vanilla V4 pool search.
+
+### 2.2 Automatic Pool Discovery
+- **v5:** Pools had to be manually registered per project via `addDefaultPool()`.
+- **v6:** Pools are auto-discovered at swap time by scanning all V3 fee tiers (3000, 500, 10000, 100 bps) and V4 pools, selecting the one with the highest liquidity. No manual configuration needed.
+
+### 2.3 Automatic Token Route Discovery
+New `_resolveTokenOut()` function determines what token a destination project accepts, with the following priority:
+1. Metadata override (`routeTokenOut` key).
+2. Direct acceptance (project accepts `tokenIn`).
+3. NATIVE/WETH equivalence check.
+4. Dynamic discovery — iterate all project terminals and their accounting contexts, find the accepted token with the best Uniswap pool against `tokenIn`.
+
+### 2.4 JB Token Cash Out Routing
+New `_cashOutLoop()` function enables recursive cashout of JB project tokens:
+- If `tokenIn` is a JB project token (ERC-20 or credit), the terminal can cash it out from the source project's terminal, then recursively process the reclaimed token.
+- Up to `_MAX_CASHOUT_ITERATIONS = 20` iterations to prevent infinite loops.
+- Supports `cashOutSource` metadata key for credit-based cashouts.
+- Supports `cashOutMinReclaimed` metadata key for slippage protection on the first cashout step.
+
+### 2.5 Credit Transfer Support
+`_acceptFundsFor()` now checks for `cashOutSource` metadata. If present, instead of transferring ERC-20 tokens, it pulls JB token credits from the payer via `TOKENS.transferCreditsFrom()`.
+
+### 2.6 New `IJBTokens TOKENS` Immutable
+The terminal now has a reference to the `IJBTokens` contract for looking up project IDs from token addresses and transferring credits.
+
+### 2.7 `PoolInfo` Struct (New File)
+New struct `src/structs/PoolInfo.sol` that represents either a V3 or V4 pool:
+```solidity
+struct PoolInfo {
+    bool isV4;
+    IUniswapV3Pool v3Pool;
+    PoolKey v4Key;
+}
+```
+
+### 2.8 `JBSwapLib` Library (New File)
+New library `src/libraries/JBSwapLib.sol` containing:
+- `getSlippageTolerance(impact, poolFeeBps)` — continuous sigmoid formula replacing v5's stepped if/else brackets. Returns slippage in basis points with a minimum of `poolFee + 1%` (floor 2%) and a ceiling of 88%.
+- `calculateImpact(amountIn, liquidity, sqrtP, zeroForOne)` — estimates price impact at 1e18 precision.
+- `sqrtPriceLimitFromAmounts(amountIn, minimumAmountOut, zeroForOne)` — computes a `sqrtPriceLimitX96` for partial-fill protection (V3 and V4). This replaces v5's approach of using extreme price limits (`MIN_SQRT_RATIO + 1` / `MAX_SQRT_RATIO - 1`).
+
+### 2.9 `discoverBestPool()` and `discoverPool()` Public Views
+New external view functions on `IJBRouterTerminal` for off-chain queries:
+- `discoverBestPool(tokenIn, tokenOut)` — returns a `PoolInfo` (V3 or V4).
+- `discoverPool(tokenIn, tokenOut)` — returns only the V3 pool (backwards-compatible helper).
+
+### 2.10 `Permit2AllowanceFailed` Event
+In v6, when a Permit2 allowance call fails during `_acceptFundsFor()`, an event `Permit2AllowanceFailed(token, owner, reason)` is emitted (inherited from `IJBPermitTerminal`), and the payment continues using fallback transfer. In v5, the failure was silently swallowed with an empty `catch`.
+
+### 2.11 Fee-on-Transfer Token Handling
+- **v5 `_acceptFundsFor`:** Returned `IERC20(token).balanceOf(address(this))` after transfer — would include any pre-existing balance.
+- **v6 `_acceptFundsFor`:** Uses balance-delta pattern (`balanceAfter - balanceBefore`) to accurately measure tokens received.
+
+### 2.12 Partial-Fill Leftover Handling via Balance Delta
+- **v5 `_handleTokenTransfersAndSwap`:** Measured leftovers as the full `balanceOf(normalizedTokenIn)` — could include pre-existing balances.
+- **v6 `_handleSwap`:** Snapshots `balanceBefore` and uses `balanceAfter - balanceBefore` for accurate leftover calculation.
+
+### 2.13 `PERMIT2` Exposed on `IJBRouterTerminalRegistry` Interface
+- **v5:** `PERMIT2` was an immutable on the registry contract but not exposed on the `IJBSwapTerminalRegistry` interface.
+- **v6:** `PERMIT2()` is declared on the `IJBRouterTerminalRegistry` interface.
+
+---
+
+## 3. Event Changes
+
+### 3.1 Registry Events Renamed
+All events were renamed from `JBSwapTerminalRegistry_*` to `JBRouterTerminalRegistry_*`.
+
+### 3.2 Registry Events Now Include `caller`
+All registry events now include an `address caller` parameter:
+| v5 | v6 |
+|---|---|
+| `JBSwapTerminalRegistry_AllowTerminal(IJBTerminal terminal)` | `JBRouterTerminalRegistry_AllowTerminal(IJBTerminal terminal, address caller)` |
+| `JBSwapTerminalRegistry_DisallowTerminal(IJBTerminal terminal)` | `JBRouterTerminalRegistry_DisallowTerminal(IJBTerminal terminal, address caller)` |
+| `JBSwapTerminalRegistry_LockTerminal(uint256 projectId)` | `JBRouterTerminalRegistry_LockTerminal(uint256 indexed projectId, address caller)` |
+| `JBSwapTerminalRegistry_SetDefaultTerminal(IJBTerminal terminal)` | `JBRouterTerminalRegistry_SetDefaultTerminal(IJBTerminal terminal, address caller)` |
+| `JBSwapTerminalRegistry_SetTerminal(uint256 indexed projectId, IJBTerminal terminal)` | `JBRouterTerminalRegistry_SetTerminal(uint256 indexed projectId, IJBTerminal terminal, address caller)` |
+
+### 3.3 New Event on Main Terminal
+- `Permit2AllowanceFailed(address indexed token, address indexed owner, bytes reason)` — emitted when Permit2 allowance fails (from `IJBPermitTerminal`).
+
+---
+
+## 4. Error Changes
+
+### 4.1 Main Terminal Errors Renamed and Restructured
+| v5 Error | v6 Error | Notes |
+|---|---|---|
+| `JBSwapTerminal_CallerNotPool(address)` | `JBRouterTerminal_CallerNotPool(address)` | Renamed |
+| `JBSwapTerminal_InvalidTwapWindow(uint256, uint256, uint256)` | *Removed* | TWAP windows are no longer configurable |
+| `JBSwapTerminal_SpecifiedSlippageExceeded(uint256, uint256)` | `JBRouterTerminal_SlippageExceeded(uint256 amountOut, uint256 minAmountOut)` | Renamed |
+| `JBSwapTerminal_NoDefaultPoolDefined(uint256, address)` | *Removed* | Pools are auto-discovered |
+| `JBSwapTerminal_NoMsgValueAllowed(uint256)` | `JBRouterTerminal_NoMsgValueAllowed(uint256)` | Renamed |
+| `JBSwapTerminal_PermitAllowanceNotEnough(uint256, uint256)` | `JBRouterTerminal_PermitAllowanceNotEnough(uint256, uint256)` | Renamed |
+| `JBSwapTerminal_TokenNotAccepted(uint256, address)` | `JBRouterTerminal_TokenNotAccepted(uint256, address)` | Renamed |
+| `JBSwapTerminal_UnexpectedCall(address)` | *Removed* | `receive()` is now unrestricted |
+| `JBSwapTerminal_WrongPool(address, address)` | *Removed* | No manual pool registration |
+| `JBSwapTerminal_ZeroToken()` | *Removed* | No fixed `tokenOut` constructor param |
+| *N/A* | `JBRouterTerminal_AmountOverflow(uint256)` | New — guards `uint160` cast in `_transferFrom` and `uint128` cast in TWAP quote |
+| *N/A* | `JBRouterTerminal_CallerNotPoolManager(address)` | New — V4 callback verification |
+| *N/A* | `JBRouterTerminal_CashOutLoopLimit()` | New — exceeded `_MAX_CASHOUT_ITERATIONS` |
+| *N/A* | `JBRouterTerminal_NoCashOutPath(uint256, uint256)` | New — no cashout terminal found |
+| *N/A* | `JBRouterTerminal_NoLiquidity()` | New — pool has zero liquidity |
+| *N/A* | `JBRouterTerminal_NoObservationHistory()` | New — V3 pool has no observation history for TWAP |
+| *N/A* | `JBRouterTerminal_NoPoolFound(address, address)` | New — no V3 or V4 pool exists |
+| *N/A* | `JBRouterTerminal_NoRouteFound(uint256, address)` | New — no accepted token found for project |
+
+### 4.2 Registry Errors Renamed and New
+| v5 Error | v6 Error | Notes |
+|---|---|---|
+| `JBSwapTerminalRegistry_NoMsgValueAllowed(uint256)` | `JBRouterTerminalRegistry_NoMsgValueAllowed(uint256)` | Renamed |
+| `JBSwapTerminalRegistry_PermitAllowanceNotEnough(uint256, uint256)` | `JBRouterTerminalRegistry_PermitAllowanceNotEnough(uint256, uint256)` | Renamed |
+| `JBSwapTerminalRegistry_TerminalLocked(uint256)` | `JBRouterTerminalRegistry_TerminalLocked(uint256)` | Renamed |
+| `JBSwapTerminalRegistry_TerminalNotAllowed(IJBTerminal)` | `JBRouterTerminalRegistry_TerminalNotAllowed(IJBTerminal)` | Renamed |
+| `JBSwapTerminalRegistry_TerminalNotSet(uint256)` | `JBRouterTerminalRegistry_TerminalNotSet(uint256)` | Renamed |
+| *N/A* | `JBRouterTerminalRegistry_AmountOverflow()` | New — guards `uint160` cast |
+| *N/A* | `JBRouterTerminalRegistry_TerminalMismatch(IJBTerminal, IJBTerminal)` | New — `lockTerminalFor` safety check |
+| *N/A* | `JBRouterTerminalRegistry_ZeroAddress()` | New — prevents setting `address(0)` as default terminal |
+
+---
+
+## 5. Struct Changes
+
+### 5.1 New: `PoolInfo` (`src/structs/PoolInfo.sol`)
+```solidity
+struct PoolInfo {
+    bool isV4;
+    IUniswapV3Pool v3Pool;
+    PoolKey v4Key;
+}
+```
+Represents either a Uniswap V3 or V4 pool. Used throughout the v6 pool discovery and swap execution flow.
+
+---
+
+## 6. Implementation Changes (Non-Interface)
+
+### 6.1 Slippage Tolerance: Stepped → Continuous Sigmoid
+- **v5:** Used a series of `if/else` brackets to map impact ranges to slippage tolerances (9 discrete brackets). Impact precision was `10 * SLIPPAGE_DENOMINATOR` (1e5).
+- **v6:** Uses a continuous sigmoid formula in `JBSwapLib.getSlippageTolerance()`: `minSlippage + (MAX_SLIPPAGE - minSlippage) * impact / (impact + K)`. Impact precision is 1e18. Minimum slippage is `poolFee + 1%` with a 2% floor. Maximum is 88%.
+
+### 6.2 `sqrtPriceLimitX96` Computation
+- **v5 `_swap`:** Always used extreme price limits (`MIN_SQRT_RATIO + 1` or `MAX_SQRT_RATIO - 1`), providing no partial-fill protection.
+- **v6 `_executeV3Swap` / `_executeV4Swap`:** Uses `JBSwapLib.sqrtPriceLimitFromAmounts()` to compute a meaningful price limit from `amountIn` and `minAmountOut`, providing partial-fill protection so the swap stops if execution price worsens beyond the minimum acceptable rate.
+
+### 6.3 `uniswapV3SwapCallback` Pool Verification
+- **v5:** Verified the caller by looking up the stored pool from `_poolFor[projectId][normalizedTokenIn]` and comparing `msg.sender` against it.
+- **v6:** Verifies the caller by querying the factory directly with the callback data's `tokenIn`/`tokenOut` and the pool's `fee()`. This is necessary because pools are auto-discovered rather than stored.
+
+### 6.4 `uniswapV3SwapCallback` Data Format
+- **v5:** Callback data was `abi.encode(projectId, tokenIn)`.
+- **v6:** Callback data is `abi.encode(projectId, tokenIn, tokenOut)` — includes `tokenOut` for factory verification.
+
+### 6.5 `receive()` Function
+- **v5:** Restricted to only accept ETH from the `WETH` contract, reverting with `JBSwapTerminal_UnexpectedCall` otherwise.
+- **v6:** Unrestricted — accepts ETH from cashout reclaims, WETH unwraps, and V4 PoolManager takes.
+
+### 6.6 `_acceptFundsFor` Uses `_msgSender()` Consistently
+- **v5:** Mixed `msg.sender` and `_msgSender()` — used `msg.sender` in the Permit2 permit call and `_transferFrom`.
+- **v6:** Uses `_msgSender()` consistently throughout, respecting ERC-2771 meta-transactions.
+
+### 6.7 `pay()` and `addToBalanceOf()` Routing
+- **v5:** Both functions looked up `DIRECTORY.primaryTerminalOf(projectId, TOKEN_OUT)` for a fixed output token, then swapped via `_handleTokenTransfersAndSwap()`.
+- **v6:** Both functions call `_route()` which handles the full routing pipeline: credit detection, JB token cashout, token resolution, and conversion (direct/wrap/swap).
+
+### 6.8 `_beforeTransferFor` Simplified
+- **v5:** Checked the `_OUT_IS_NATIVE_TOKEN` flag.
+- **v6:** Checks `token == JBConstants.NATIVE_TOKEN` directly (since there's no fixed output token).
+
+### 6.9 `_transferFrom` Amount Overflow Guard
+- **v5:** Cast `amount` to `uint160` unchecked when calling `PERMIT2.transferFrom`.
+- **v6:** Checks `amount > type(uint160).max` and reverts with `JBRouterTerminal_AmountOverflow` before the cast.
+
+### 6.10 Registry `terminalOf` Storage Encapsulation
+- **v5:** `terminalOf` was a `public` mapping directly on the interface.
+- **v6:** The storage mapping is `internal _terminalOf`, with a public `terminalOf(projectId)` view function that applies the default fallback. This prevents direct mapping access that would bypass the fallback logic.
+
+### 6.11 Registry `disallowTerminal` Clears Default
+- **v5:** `disallowTerminal()` only set `isTerminalAllowed[terminal] = false`.
+- **v6:** Additionally clears `defaultTerminal` if it matches the terminal being disallowed.
+
+### 6.12 Registry `setDefaultTerminal` Zero Address Check
+- **v5:** No validation on the terminal address.
+- **v6:** Reverts with `JBRouterTerminalRegistry_ZeroAddress()` if `address(terminal) == address(0)`.
+
+### 6.13 Removed: `JBSwapTerminal5_1`
+v5 contained both `JBSwapTerminal.sol` and `JBSwapTerminal5_1.sol` (a minor revision). v6 has a single `JBRouterTerminal.sol`.
+
+### 6.14 `_pickPoolAndQuote` Redesigned
+- **v5:** Looked up stored pools from `_poolFor` mappings. If no user quote was provided, used project-specific TWAP windows with fallback to slot0 for pools with no observations.
+- **v6:** Auto-discovers pools via `_discoverPool()`. If no user quote is provided, dispatches to `_getV3TwapQuote()` (for V3 pools, using a fixed 10-minute TWAP window) or `_getV4SpotQuote()` (for V4 pools, using spot price). Reverts with `JBRouterTerminal_NoPoolFound` if no pool exists (v5 reverted with `JBSwapTerminal_NoDefaultPoolDefined`).
+
+### 6.15 New Metadata Keys
+- `cashOutSource` — specifies a source project ID and credit amount for credit-based cashouts.
+- `cashOutMinReclaimed` — minimum tokens to reclaim from the first cashout step.
+- `routeTokenOut` — payer-specified output token override.
+- `quoteForSwap` — retained from v5 (user-provided minimum output quote).
+- `permit2` — retained from v5.
+
+---
+
+## 7. Migration Table
+
+| v5 File | v6 File | Status |
+|---|---|---|
+| `src/JBSwapTerminal.sol` | `src/JBRouterTerminal.sol` | **Renamed + Rewritten** |
+| `src/JBSwapTerminal5_1.sol` | *N/A* | **Removed** (consolidated into `JBRouterTerminal`) |
+| `src/JBSwapTerminalRegistry.sol` | `src/JBRouterTerminalRegistry.sol` | **Renamed + Updated** |
+| `src/interfaces/IJBSwapTerminal.sol` | `src/interfaces/IJBRouterTerminal.sol` | **Renamed + Rewritten** (entirely different surface) |
+| `src/interfaces/IJBSwapTerminalRegistry.sol` | `src/interfaces/IJBRouterTerminalRegistry.sol` | **Renamed + Updated** (added `PERMIT2()`, `caller` on events, new `lockTerminalFor` sig) |
+| `src/interfaces/IWETH9.sol` | `src/interfaces/IWETH9.sol` | **Unchanged** (import path updated to OZ) |
+| *N/A* | `src/structs/PoolInfo.sol` | **New** |
+| *N/A* | `src/libraries/JBSwapLib.sol` | **New** |