@bananapus/router-terminal-v6 0.0.16 → 0.0.18

package/ADMINISTRATION.md

@@ -13,7 +13,7 @@ Admin privileges and their scope in nana-router-terminal-v6.
 ### 2. Project Owner / SET_ROUTER_TERMINAL Delegate
 
 **Contract**: `JBRouterTerminalRegistry`
-**Assigned via**: Ownership of the project's ERC-721 NFT (via `JBProjects.ownerOf(projectId)`), or delegation via `JBPermissions` with permission ID `SET_ROUTER_TERMINAL` (28).
+**Assigned via**: Ownership of the project's ERC-721 NFT (via `JBProjects.ownerOf(projectId)`), or delegation via `JBPermissions` with permission ID `SET_ROUTER_TERMINAL` (29).
 **Scope**: Per-project -- controls which router terminal a specific project uses, and can permanently lock that choice.
 
 ### 3. Router Terminal Owner (Ownable)
@@ -22,12 +22,26 @@ Admin privileges and their scope in nana-router-terminal-v6.
 **Assigned via**: Constructor parameter `owner`, transferable via `Ownable.transferOwnership()`.
 **Scope**: Currently unused. `JBRouterTerminal` inherits `Ownable` but does not gate any functions behind `onlyOwner`. The owner exists for potential future use or subclass extensions. The `Ownable.renounceOwnership()` and `Ownable.transferOwnership()` functions are inherited but have no practical effect on the terminal's operation.
 
+**Risk note:** While the owner has no current powers over the terminal's operation, the `Ownable` inheritance means a future code change or subclass could introduce `onlyOwner`-gated functions. If the terminal is deployed with a specific owner address, that address retains transfer rights indefinitely.
+
 ### 4. Credit Cashout Payer (Implicit)
 
 **Contract**: `JBRouterTerminal`
 **Required permission**: `TRANSFER_CREDITS` (permission ID 13) -- must be granted by the payer to the router terminal address for the source project via `JBPermissions`.
 **Scope**: Per-transaction. Required only when using the `cashOutSource` metadata key to route payments through credit cashouts.
 
+## Terminal Resolution
+
+When a payment is forwarded through the registry, the terminal is resolved as follows:
+
+1. If the project has called `setTerminalFor(projectId, terminal)`, that explicit terminal is used.
+2. If no explicit terminal is set, the registry's `defaultTerminal` is used.
+3. If neither exists, the forwarding reverts.
+
+**Lock semantics:** When `lockTerminalFor()` is called on a project with no explicit terminal, the current default is snapshot into `_terminalOf[projectId]` before locking. The project becomes independent of future default changes.
+
+**Disallow interaction:** If the registry owner calls `disallowTerminal()` on the current default terminal, the `defaultTerminal` is automatically cleared (set to `address(0)`). Projects relying on the default (without locking) would lose their terminal resolution until a new default is set. Projects should lock their terminal to avoid disruption.
+
 ## Privileged Functions
 
 ### JBRouterTerminalRegistry
@@ -37,8 +51,8 @@ Admin privileges and their scope in nana-router-terminal-v6.
 | `allowTerminal(terminal)` | Registry Owner | `onlyOwner` | Global | Adds a terminal to the allowlist (`isTerminalAllowed[terminal] = true`). Projects can only use allowlisted terminals. |
 | `disallowTerminal(terminal)` | Registry Owner | `onlyOwner` | Global | Removes a terminal from the allowlist. Also clears `defaultTerminal` if it matches the disallowed terminal. Does NOT affect projects that have already locked their terminal. |
 | `setDefaultTerminal(terminal)` | Registry Owner | `onlyOwner` | Global | Sets the default terminal for all projects that have not set a project-specific terminal. Also auto-allows the terminal. |
-| `setTerminalFor(projectId, terminal)` | Project Owner or Delegate | `SET_ROUTER_TERMINAL` (28) | Per-project | Routes a specific project to a specific allowed terminal. Reverts if the terminal is not allowlisted or if the project's terminal is locked. |
-| `lockTerminalFor(projectId, expectedTerminal)` | Project Owner or Delegate | `SET_ROUTER_TERMINAL` (28) | Per-project | Permanently locks the terminal choice for a project. If no explicit terminal is set, snapshots the current default into `_terminalOf[projectId]`. Reverts with `TerminalMismatch` if the resolved terminal differs from `expectedTerminal` (race condition protection). **Irreversible.** |
+| `setTerminalFor(projectId, terminal)` | Project Owner or Delegate | `SET_ROUTER_TERMINAL` (29) | Per-project | Routes a specific project to a specific allowed terminal. Reverts if the terminal is not allowlisted or if the project's terminal is locked. |
+| `lockTerminalFor(projectId, expectedTerminal)` | Project Owner or Delegate | `SET_ROUTER_TERMINAL` (29) | Per-project | Permanently locks the terminal choice for a project. If no explicit terminal is set, snapshots the current default into `_terminalOf[projectId]`. Reverts with `TerminalMismatch` if the resolved terminal differs from `expectedTerminal` (race condition protection). **Irreversible.** |
 
 ### JBRouterTerminal
 
@@ -62,6 +76,8 @@ The following values are set at deploy time and cannot be changed:
 
 | Property | Set At | Mutable? | Description |
 |----------|--------|----------|-------------|
+| `PERMISSIONS` | Constructor | No | JB permissions registry for permission checks |
+| `Trusted forwarder` | Constructor | No | ERC-2771 trusted forwarder for meta-transactions |
 | `DIRECTORY` | Constructor | No | JB directory for terminal/controller lookups |
 | `PROJECTS` | Constructor | No | JB project NFT registry |
 | `TOKENS` | Constructor | No | JB token manager for credit transfers and project token lookups |
@@ -79,6 +95,8 @@ The following values are set at deploy time and cannot be changed:
 
 | Property | Set At | Mutable? | Description |
 |----------|--------|----------|-------------|
+| `PERMISSIONS` | Constructor | No | JB permissions registry for permission checks |
+| `Trusted forwarder` | Constructor | No | ERC-2771 trusted forwarder for meta-transactions |
 | `PROJECTS` | Constructor | No | JB project NFT registry |
 | `PERMIT2` | Constructor | No | Permit2 contract for gasless approvals |
 

package/ARCHITECTURE.md

@@ -11,6 +11,7 @@ src/
 ├── JBRouterTerminal.sol         — Payment routing: swap + forward to destination terminal
 ├── JBRouterTerminalRegistry.sol — Registry mapping projects to router terminal configs
 ├── interfaces/
+│   ├── IJBPayerTracker.sol
 │   ├── IJBRouterTerminal.sol
 │   ├── IJBRouterTerminalRegistry.sol
 │   └── IWETH9.sol
@@ -25,13 +26,47 @@ src/
 ### Payment Routing
 ```
 Payer → JBRouterTerminal.pay(projectId, token, amount)
-  → Discover destination project's accepted token
-  → If same token: forward directly to project's terminal
-  → If different token:
-    → Compare V3 and V4 pool quotes
-    → Swap via better pool
-  → Forward swapped tokens to project's terminal
-  → Return token count from destination payment
+  │
+  ├─ Accept funds (msg.value for native, Permit2 pull for ERC-20, or credit transfer)
+  │
+  ├─ If input is a JB project token (credit or ERC-20):
+  │    → Cash out recursively via _cashOutLoop (up to 20 hops)
+  │    → Reclaimed token becomes the new tokenIn
+  │
+  ├─ Resolve tokenOut: what does the destination project accept?
+  │    1. Metadata override ("routeTokenOut")
+  │    2. Direct acceptance — project already accepts tokenIn
+  │    3. NATIVE ↔ WETH equivalence check
+  │    4. Dynamic discovery — iterate project terminals, find swappable token
+  │
+  ├─ Convert tokenIn → tokenOut via _convert:
+  │    ├─ Same token: no-op
+  │    ├─ NATIVE ↔ WETH: wrap (WETH.deposit) or unwrap (WETH.withdraw)
+  │    └─ Different tokens: Uniswap swap
+  │         │
+  │         ├─ If native ETH input: held as raw ETH until V3 callback
+  │         │   wraps (WETH.deposit) only the amount the pool consumes
+  │         │
+  │         ├─ Pool discovery (_discoverPool):
+  │         │   Search V3 pools across 4 fee tiers (0.3%, 0.05%, 1%, 0.01%)
+  │         │   Search V4 pools across same fee tiers (if PoolManager deployed)
+  │         │   Compare in-range liquidity across all candidates
+  │         │   Select the single pool with highest liquidity
+  │         │
+  │         ├─ Quote & slippage (_pickPoolAndQuote):
+  │         │   1. User-provided quote (metadata "quoteForSwap") — used as-is
+  │         │   2. V3 fallback: 10-min TWAP via OracleLibrary.consult()
+  │         │   3. V4 fallback: spot price from getSlot0() (no built-in TWAP)
+  │         │   Apply sigmoid slippage: minSlippage + range * impact/(impact+K)
+  │         │
+  │         ├─ Execute swap via V3 pool.swap() or V4 POOL_MANAGER.unlock()
+  │         │
+  │         ├─ If native ETH input: wrap any remaining raw ETH (partial fills)
+  │         ├─ If native ETH output: unwrap WETH → ETH (WETH.withdraw)
+  │         └─ Return leftover input tokens via _resolveRefundTo (checks msg.sender's IJBPayerTracker.originalPayer() via try-catch, falls back to beneficiary/msgSender)
+  │
+  ├─ Approve destination terminal for output tokens (or set msg.value for native)
+  └─ Forward to destTerminal.pay() → return beneficiary token count
 ```
 
 ### Preview Routing
@@ -48,14 +83,30 @@ Caller → JBRouterTerminal.previewPayFor(projectId, token, amount)
 |-------|-----------|---------|
 | Terminal | `IJBTerminal` | Acts as a terminal that routes payments |
 | Registry | `IJBRouterTerminalRegistry` | Maps projects to routing configs |
+| Payer tracker | `IJBPayerTracker` | Exposes the original payer of a forwarded call for refund resolution |
 | Permit | `IJBPermitTerminal` | Permit2 token approval support |
 
 ## Composition Boundary
 
 The router terminal exposes the `IJBTerminal` surface because it needs to participate in Juicebox routing, but its
-accounting context is intentionally synthetic. `accountingContextForTokenOf()` returns `decimals = 18` for any token,
-and the registry forwards that value unchanged. Treat the router layer as a payment router only, not as an
-accounting-sensitive terminal source for loan sizing, debt normalization, or any other decimals-dependent logic.
+accounting context is intentionally synthetic. `accountingContextForTokenOf()` returns `decimals = 18` for native
+tokens and probes `IERC20Metadata.decimals()` for ERC-20s (falling back to `18` if the call fails). The registry
+forwards that value unchanged. Treat the router layer as a payment router only, not as an accounting-sensitive
+terminal source for loan sizing, debt normalization, or any other decimals-dependent logic.
+
+## Design Decisions
+
+**Why the router is a terminal, not a standalone contract.** By implementing `IJBTerminal`, the router can be set as a project's terminal in the directory. Payers and frontend integrations call the same `pay()` / `addToBalanceOf()` interface they use for any terminal — no special routing code required on the caller side. The router accepts funds, converts them, and forwards to the real destination terminal in a single transaction.
+
+**Why both Uniswap V3 and V4 support.** V4 pools may offer deeper liquidity for certain pairs (especially native-ETH pairs that V4 handles natively), while V3 pools have years of established liquidity. The router searches both and picks the pool with the highest in-range liquidity, giving payers the best available execution without requiring them to know which protocol version has the better pool.
+
+**Why synthetic accounting contexts.** The router accepts any token and converts it before forwarding. It never holds balances between transactions, so it has no meaningful accounting of its own. `accountingContextForTokenOf()` returns a best-effort context (probing `decimals()` with an 18-decimal fallback) purely so the directory can register it. The real accounting happens at the destination terminal.
+
+**Why the registry pattern.** `JBRouterTerminalRegistry` lets project owners lock a specific `JBRouterTerminal` instance for their project and manage Permit2 approvals in one place. This provides a stable entry point: if the router implementation is upgraded, the registry can be pointed to the new instance without changing the project's directory entry. It also gates which router terminals are allowed, preventing untrusted implementations from being set.
+
+**Why `IJBPayerTracker` is a separate interface.** The router terminal needs to know the original payer when called through an intermediary so it can return leftover tokens from partial swap fills to the right address. Rather than coupling the router to `IJBRouterTerminalRegistry` specifically, the refund resolution logic (`_resolveRefundTo`) queries `IJBPayerTracker(msg.sender).originalPayer()` via a try-catch. This means any contract that implements `IJBPayerTracker` -- not just the registry -- can act as a forwarding intermediary. The registry inherits `IJBPayerTracker` through `IJBRouterTerminalRegistry`, keeping backward compatibility while opening the door for other intermediary patterns.
+
+**Why liquidity-based pool selection instead of quote comparison.** Comparing actual output quotes across V3 and V4 would require executing (or simulating) swaps on both — expensive on-chain and complex for V4 where swaps must go through `PoolManager.unlock()`. Comparing in-range liquidity is a single `liquidity()` or `getLiquidity()` read per pool, is gas-cheap, and strongly correlates with execution quality for typical swap sizes.
 
 ## Dependencies
 - `@bananapus/core-v6` — Terminal, directory, permissions

package/AUDIT_INSTRUCTIONS.md

@@ -12,8 +12,8 @@ Two contracts. One library. One struct.
 
 | 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`. |
+| `JBRouterTerminal` | ~1,672 | 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` | ~514 | 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. |
 
@@ -141,18 +141,18 @@ The registry implements a two-phase terminal assignment:
 
 ## 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.
+**JBRouterTerminal:** Uses balance-delta accounting in `_acceptFundsFor()` (lines 569-575). 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.
+**JBRouterTerminalRegistry:** Does NOT use balance-delta accounting in `_acceptFundsFor()` (line 432). 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.
+**Audit focus:** Verify that the registry's `_acceptFundsFor` cannot be exploited with fee-on-transfer tokens. The comment on lines 466-468 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();`
+- `JBRouterTerminal._transferFrom()` line 944: `if (amount > type(uint160).max) revert JBRouterTerminal_AmountOverflow(amount);`
+- `JBRouterTerminalRegistry._transferFrom()` line 510: `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.
 
@@ -252,7 +252,7 @@ forge test
 
 ### Foundry Configuration
 
-- Solidity 0.8.26, EVM target `cancun`, optimizer 200 runs
+- Solidity ^0.8.28, 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)
@@ -261,14 +261,22 @@ forge test
 
 | 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 |
+| `RouterTerminal.t.sol` | Unit (mocked) | Core routing, swap paths, cashout, V4, pool discovery, TWAP, errors | ~39 |
+| `RouterTerminalRegistry.t.sol` | Unit (mocked) | Allow/disallow, set/lock, forwarding, permissions | ~18 |
 | `RouterTerminalFork.t.sol` | Fork (mainnet) | End-to-end swaps: ETH->USDC, USDC->ETH, ETH->DAI, addToBalance, quote metadata | ~12 |
+| `RouterTerminalCashOutFork.t.sol` | Fork (mainnet) | Cashout routing through terminals | ~5 |
+| `RouterTerminalCreditCashout.t.sol` | Unit (mocked) | Credit cashout path | ~6 |
+| `RouterTerminalERC2771.t.sol` | Unit (mocked) | ERC-2771 meta-transaction forwarding | ~3 |
 | `RouterTerminalFeeCashOutFork.t.sol` | Fork (mainnet) | Fee routing through cashout: project 3 payouts -> fee -> cashout -> project 1 | 1 |
+| `RouterTerminalMultihopFork.t.sol` | Fork (mainnet) | Multi-hop cashout chains across projects | ~3 |
+| `RouterTerminalPreviewFork.t.sol` | Fork (mainnet) | Preview functions for pay and cashout routing | ~4 |
+| `RouterTerminalReentrancy.t.sol` | Unit (mocked) | Reentrancy scenarios through callbacks | ~3 |
 | `RouterTerminalSandwichFork.t.sol` | Fork (mainnet) | MEV/sandwich: V3 TWAP resistance, V4 spot manipulation, user quote | 4 |
+| `fork/V4QuoteAndSettlementFork.t.sol` | Fork (mainnet) | V4 quote computation and settlement | ~4 |
+| `invariant/RouterTerminalInvariant.t.sol` | Invariant | Zero-balance, callback verification, loop termination (9 invariants) | 9 |
 | `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 |
+| `regression/V4SpotPriceSlippage.t.sol` | Unit + fuzz | Sigmoid math: floor, ceiling, monotonicity, bounded range, user quote | ~17 |
 
 ### Coverage Gaps Worth Investigating
 
@@ -276,8 +284,75 @@ forge test
 |------|--------|----------------|
 | 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 |
+| Multi-hop cashout chains (>1 step) | TESTED | `RouterTerminalMultihopFork.t.sol` covers multi-hop cashout chains (~3 tests) |
 | 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 |
+
+## Previous Audit Findings
+
+No prior formal audit with finding IDs has been conducted on this codebase. All risk analysis is internal. See [RISKS.md](./RISKS.md) for known risks.
+
+## Anti-Patterns to Hunt
+
+| Pattern | Where to Look | Why It's Dangerous |
+|---------|--------------|-------------------|
+| V4 spot price as TWAP fallback | `_getV4SpotQuote()` | V4 pools lack on-chain TWAP. Spot price is manipulable within a block. The sigmoid slippage mitigates but doesn't eliminate. |
+| Silent TWAP window degradation | `_getV3TwapQuote()` | If `oldestObservation < twapWindow`, the window is silently capped. A 10-second observation produces a near-spot quote labeled as "TWAP." |
+| Partial swap leftover refund | `_handleSwap()` | Leftover tokens are refunded to `_msgSender()`. If the caller is a contract, the refund must be receivable. Verify ETH refund doesn't fail silently. |
+| Stateless design assumption | All of `JBRouterTerminal` | No persistent balances. If any code path fails to forward or refund tokens, they're stuck permanently. No sweep function exists. |
+| Registry default terminal | `JBRouterTerminalRegistry` | Owner changing `defaultTerminal` redirects all unlocked projects. A compromised owner could redirect payments. |
+| `receive()` is empty | `JBRouterTerminal` | Accepts ETH but has no recovery mechanism. ETH sent directly (not through `pay()`) is permanently lost. |
+| Fee-on-transfer in registry | `JBRouterTerminalRegistry._acceptFundsFor()` | Returns user-supplied `amount`, not actual balance delta. Fee-on-transfer tokens cause downstream accounting mismatch. |
+
+## Error Reference
+
+| Error | Contract | Trigger |
+|-------|----------|---------|
+| `JBRouterTerminal_AmountOverflow(uint256)` | JBRouterTerminal | Amount exceeds `type(uint160).max` during Permit2 transfer, or exceeds `type(uint128).max` in V3 TWAP quote computation. |
+| `JBRouterTerminal_CallerNotPool(address)` | JBRouterTerminal | `uniswapV3SwapCallback()` called by an address that does not match the expected V3 pool computed via `FACTORY.getPool()`. |
+| `JBRouterTerminal_CallerNotPoolManager(address)` | JBRouterTerminal | `unlockCallback()` called by an address other than `POOL_MANAGER`. |
+| `JBRouterTerminal_CashOutLoopLimit()` | JBRouterTerminal | `_cashOutLoop()` or `_previewCashOutLoop()` exceeds 20 iterations without resolving to an accepted token. |
+| `JBRouterTerminal_NoCashOutPath(uint256, uint256)` | JBRouterTerminal | `_findCashOutPath()` cannot find any terminal on the source project that reclaims a usable token for the destination. |
+| `JBRouterTerminal_NoLiquidity()` | JBRouterTerminal | V3 or V4 pool selected for quoting has zero in-range liquidity. |
+| `JBRouterTerminal_NoMsgValueAllowed(uint256)` | JBRouterTerminal | `msg.value != 0` when paying with ERC-20 tokens or credits (ETH not expected on these paths). |
+| `JBRouterTerminal_NoObservationHistory()` | JBRouterTerminal | V3 pool's oldest observation is 0 seconds old -- no TWAP data available. |
+| `JBRouterTerminal_NoPoolFound(address, address)` | JBRouterTerminal | `_discoverPool()` or `_pickPoolAndQuote()` found no V3 or V4 pool with non-zero liquidity for the given token pair. |
+| `JBRouterTerminal_NoRouteFound(uint256, address)` | JBRouterTerminal | `_resolveTokenOut()` cannot find any terminal on the destination project that accepts the input token or a swappable alternative. |
+| `JBRouterTerminal_PermitAllowanceNotEnough(uint256, uint256)` | JBRouterTerminal | The Permit2 single-use allowance provided in metadata is less than the payment amount. |
+| `JBRouterTerminal_SlippageExceeded(uint256, uint256)` | JBRouterTerminal | Swap output or cashout reclaim amount is below the required minimum (`minAmountOut` or `minTokensReclaimed`). |
+| `JBRouterTerminalRegistry_AmountOverflow()` | JBRouterTerminalRegistry | Amount exceeds `type(uint160).max` during Permit2 transfer. |
+| `JBRouterTerminalRegistry_NoMsgValueAllowed(uint256)` | JBRouterTerminalRegistry | `msg.value != 0` when paying with ERC-20 tokens through the registry. |
+| `JBRouterTerminalRegistry_PermitAllowanceNotEnough(uint256, uint256)` | JBRouterTerminalRegistry | Permit2 single-use allowance in metadata is less than the payment amount. |
+| `JBRouterTerminalRegistry_TerminalLocked(uint256)` | JBRouterTerminalRegistry | `setTerminalFor()` called for a project whose terminal has already been locked via `lockTerminalFor()`. |
+| `JBRouterTerminalRegistry_TerminalMismatch(IJBTerminal, IJBTerminal)` | JBRouterTerminalRegistry | `lockTerminalFor()` called with an `expectedTerminal` that does not match the project's currently resolved terminal. |
+| `JBRouterTerminalRegistry_TerminalNotAllowed(IJBTerminal)` | JBRouterTerminalRegistry | `setTerminalFor()` called with a terminal not on the owner's allowlist. |
+| `JBRouterTerminalRegistry_TerminalNotSet(uint256)` | JBRouterTerminalRegistry | `lockTerminalFor()` called for a project with no explicit terminal and no default terminal configured. |
+| `JBRouterTerminalRegistry_ZeroAddress()` | JBRouterTerminalRegistry | `setDefaultTerminal()` called with `address(0)`. |
+
+## Compiler and Version Info
+
+- **Solidity**: ^0.8.28
+- **EVM target**: Cancun
+- **Optimizer**: via-IR, 200 runs
+- **Dependencies**: OpenZeppelin 5.x, Uniswap V3/V4, nana-core-v6
+- **Build**: `forge build` (Foundry)
+
+## How to Report Findings
+
+For each finding:
+
+1. **Title** -- one line, starts with severity (CRITICAL/HIGH/MEDIUM/LOW)
+2. **Affected contract(s)** -- exact file path and line numbers
+3. **Description** -- what is wrong, in plain language
+4. **Trigger sequence** -- step-by-step, minimal steps to reproduce
+5. **Impact** -- what an attacker gains, what a user loses (with numbers if possible)
+6. **Proof** -- code trace showing the exact execution path, or a Foundry test
+7. **Fix** -- minimal code change that resolves the issue
+
+**Severity guide:**
+- **CRITICAL**: Direct fund loss, tokens stuck permanently, or system insolvency.
+- **HIGH**: Conditional fund loss, routing bypass, or broken invariant.
+- **MEDIUM**: Value leakage, suboptimal routing, griefing.
+- **LOW**: Informational, edge-case-only with no material impact.

package/CHANGE_LOG.md

@@ -4,6 +4,16 @@ This document describes all changes between `nana-swap-terminal` (v5) and `nana-
 
 **Note:** This repo was renamed from `nana-swap-terminal` to `nana-router-terminal` in v6.
 
+## Summary
+
+This release represents a **philosophical shift from configured to automatic**: the swap terminal required manual pool registration and per-project TWAP configuration, while the router terminal automatically discovers the best route for any payment.
+
+- **Renamed `JBSwapTerminal` → `JBRouterTerminal`**: Reflects the broader scope — not just swapping, but full payment routing including JB token cashouts, credit transfers, and multi-hop resolution.
+- **Automatic pool discovery**: Pools are auto-discovered across both Uniswap V3 and V4 by scanning all fee tiers and selecting the highest-liquidity pool. No manual `addDefaultPool()` needed.
+- **Automatic token route discovery**: The terminal dynamically determines what token a destination project accepts by querying terminals and accounting contexts.
+- **JB token cashout routing**: Can recursively cash out JB project tokens (ERC-20 or credits) from source projects before routing the reclaimed tokens to the destination.
+- **Shared `JBSwapLib` library**: Swap math extracted for reuse with `nana-buyback-hook-v6` — includes continuous sigmoid slippage and V4 price limit computation.
+
 ---
 
 ## 1. Breaking Changes
@@ -60,7 +70,7 @@ The `SLIPPAGE_DENOMINATOR` constant was kept but changed from `uint160` to `uint
 
 ### 1.11 Solidity Version
 - **v5:** `pragma solidity 0.8.23`
-- **v6:** `pragma solidity 0.8.26`
+- **v6:** `pragma solidity ^0.8.28`
 
 ---
 
@@ -295,3 +305,5 @@ v5 contained both `JBSwapTerminal.sol` and `JBSwapTerminal5_1.sol` (a minor revi
 | `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** |
+
+> **Cross-repo impact**: `nana-fee-project-deployer-v6` replaced `SwapTerminalDeploymentLib` with `RouterTerminalDeploymentLib`. `nana-permission-ids-v6` replaced `ADD_SWAP_TERMINAL_POOL`/`ADD_SWAP_TERMINAL_TWAP_PARAMS` with `SET_ROUTER_TERMINAL` (29). `nana-buyback-hook-v6` shares the `JBSwapLib` library for sigmoid slippage and V4 swap math.

package/README.md

@@ -15,7 +15,7 @@ _If you're having trouble understanding this contract, take a look at the [core
 | Contract | Description |
 |----------|-------------|
 | `JBRouterTerminal` | Core terminal. Accepts any token via `pay` or `addToBalanceOf`, previews payment routes via `previewPayFor`, discovers the destination project's accepted token, and routes there -- swapping through Uniswap V3 or V4 pools if needed, cashing out JB project tokens if the input is a project token, or forwarding directly if the token is already accepted. Uses TWAP oracle (V3) or spot price (V4) for automatic slippage protection when the caller does not provide a quote. Implements `IJBTerminal`, `IJBPermitTerminal`, `IUniswapV3SwapCallback`, `IUnlockCallback`, and `IJBRouterTerminal`. |
-| `JBRouterTerminalRegistry` | A proxy terminal that delegates `pay`, `previewPayFor`, and `addToBalanceOf` to a per-project or default `JBRouterTerminal` instance. Project owners can choose which router terminal they use, and optionally lock that choice permanently. Implements `IJBTerminal` and the extra registry management surface via `IJBRouterTerminalRegistry`. |
+| `JBRouterTerminalRegistry` | A proxy terminal that delegates `pay`, `previewPayFor`, and `addToBalanceOf` to a per-project or default `JBRouterTerminal` instance. Project owners can choose which router terminal they use, and optionally lock that choice permanently. Implements `IJBTerminal`, `IJBPayerTracker`, and the extra registry management surface via `IJBRouterTerminalRegistry`. |
 
 ## How It Works
 
@@ -116,7 +116,7 @@ npm ci && forge install
 
 Key `foundry.toml` settings:
 
-- `solc = '0.8.26'`
+- `solc = '0.8.28'`
 - `evm_version = 'cancun'` (required for Uniswap V4's transient storage)
 - `optimizer_runs = 200`
 - `via_ir = true` (required for `JBRouterTerminal` to fit under EIP-170)
@@ -131,8 +131,9 @@ nana-router-terminal-v6/
 │   ├── JBRouterTerminal.sol              # Core router terminal
 │   ├── JBRouterTerminalRegistry.sol      # Per-project terminal routing
 │   ├── interfaces/
+│   │   ├── IJBPayerTracker.sol           # Original-payer tracking for refund resolution
 │   │   ├── IJBRouterTerminal.sol         # Router terminal interface
-│   │   ├── IJBRouterTerminalRegistry.sol # Registry interface (extends IJBTerminal)
+│   │   ├── IJBRouterTerminalRegistry.sol # Registry interface (extends IJBTerminal, IJBPayerTracker)
 │   │   └── IWETH9.sol                    # WETH wrapper interface
 │   ├── libraries/
 │   │   └── JBSwapLib.sol                 # Slippage tolerance, impact, and price limit math
@@ -146,7 +147,22 @@ nana-router-terminal-v6/
     ├── RouterTerminal.t.sol              # Unit tests (mocked dependencies)
     ├── RouterTerminalRegistry.t.sol      # Registry unit tests
     ├── RouterTerminalFork.t.sol          # Fork tests against mainnet Uniswap pools
-    └── RouterTerminalPreviewFork.t.sol   # Fork parity tests for previewPayFor
+    ├── RouterTerminalPreviewFork.t.sol   # Fork parity tests for previewPayFor
+    ├── RouterTerminalCashOutFork.t.sol   # Fork tests for cashout routing
+    ├── RouterTerminalCreditCashout.t.sol # Credit cashout unit tests
+    ├── RouterTerminalERC2771.t.sol       # ERC-2771 meta-transaction tests
+    ├── RouterTerminalFeeCashOutFork.t.sol # Fee routing through cashout (fork)
+    ├── RouterTerminalMultihopFork.t.sol  # Multi-hop routing (fork)
+    ├── RouterTerminalReentrancy.t.sol    # Reentrancy attack tests
+    ├── RouterTerminalSandwichFork.t.sol  # MEV/sandwich resistance (fork)
+    ├── fork/
+    │   └── V4QuoteAndSettlementFork.t.sol # V4 quote and settlement (fork)
+    ├── invariant/
+    │   └── RouterTerminalInvariant.t.sol  # Invariant/fuzz tests
+    └── regression/
+        ├── CashOutLoopLimit.t.sol        # Circular cashout loop cap
+        ├── LockTerminalRace.t.sol        # Lock terminal race condition
+        └── V4SpotPriceSlippage.t.sol     # Sigmoid slippage math
 ```
 
 ## Payment Metadata
@@ -181,17 +197,22 @@ If no `quoteForSwap` is provided, the terminal calculates one automatically:
 
 ## Supported Chains
 
-The deployment script supports:
+The deployment script (`script/Deploy.s.sol`) supports:
 
-| Chain | WETH | V3 Factory | V4 PoolManager |
-|-------|------|------------|----------------|
-| Ethereum Mainnet | `0xC02a...6Cc2` | `0x1F98...F984` | `0x0000...8A90` |
-| Optimism | `0x4200...0006` | `0x1F98...F984` | `0x0000...8A90` |
-| Base | `0x4200...0006` | `0x3312...FDfD` | `0x0000...8A90` |
-| Arbitrum | `0x82aF...b1DD` | `0x1F98...F984` | `0x0000...8A90` |
-| + Sepolia testnets for each | | | |
+- Ethereum Mainnet
+- Optimism
+- Base
+- Arbitrum
+- Sepolia testnets for each
 
-Permit2 is deployed at `0x000000000022D473030F116dDEE9F6B43aC78BA3` on all chains.
+Each chain is configured with the appropriate WETH, Uniswap V3 Factory, and V4 PoolManager addresses. Permit2 is deployed at `0x000000000022D473030F116dDEE9F6B43aC78BA3` on all chains. See `script/Deploy.s.sol` for the full address list.
+
+## Permissions
+
+| Permission | ID | Contract | Purpose |
+|------------|----|----------|---------|
+| `SET_ROUTER_TERMINAL` | 29 | `JBRouterTerminalRegistry` | Allows a project owner or delegate to call `setTerminalFor` (choose which router terminal a project uses) and `lockTerminalFor` (permanently lock that choice). |
+| `TRANSFER_CREDITS` | 13 | `JBRouterTerminal` | Must be granted by the payer to the router terminal address for the source project. Required when using `cashOutSource` metadata to cash out credits -- the router calls `TOKENS.transferCreditsFrom()` to pull credits from the payer. |
 
 ## Risks
 

package/RISKS.md

@@ -7,13 +7,14 @@
 - **JBDirectory.** Terminal resolution trusts `DIRECTORY.primaryTerminalOf()` and `DIRECTORY.terminalsOf()`. A compromised directory can redirect funds.
 - **PERMIT2.** Used as fallback for token transfers. Permit2 approvals can be exploited if users have stale allowances.
 - **Owner (Ownable).** Contract owner has no fund access but controls the registry terminal allowlist and default.
+- **`IJBPayerTracker` implementers.** `_resolveRefundTo` in the router terminal queries `IJBPayerTracker(msg.sender).originalPayer()` via try-catch. Any contract that is the `msg.sender` and implements `IJBPayerTracker` can direct leftover refunds to an arbitrary address. This is safe when the caller is a trusted intermediary (e.g. the registry), but a malicious `msg.sender` implementing `IJBPayerTracker` could redirect refunds. The risk is bounded: the caller must have already supplied the funds being routed, so it can only redirect leftovers from its own payment.
 
 ## 2. Economic / Manipulation Risks
 
 - **V4 spot price manipulation.** `_getV4SpotQuote` reads the instantaneous `getSlot0` tick, which is manipulable via sandwich attacks or flash loans. The sigmoid slippage formula provides a floor (min 2%) but does NOT provide full MEV protection. Without user-supplied `quoteForSwap` metadata, V4 swaps are vulnerable to extraction. Front-ends MUST supply `quoteForSwap` metadata for V4 swaps. Note: `_getV4SpotQuote` normalizes WETH to `address(0)` before calling OracleLibrary, since V4 uses `address(0)` for native ETH -- without this normalization, token sorting would mismatch the pool's currency ordering and produce inverted quotes.
 - **V3 TWAP manipulation.** Short TWAP windows (falls back to `oldestObservation` if < 10 minutes) reduce manipulation resistance. A newly created pool with minimal history can be manipulated within the TWAP window.
-- **Cashout loop value extraction.** `_cashOutLoop` iterates up to 20 times, cashing out JB project tokens recursively. Each cashout incurs bonding curve slippage. `minTokensReclaimed` is only applied to the first step -- subsequent steps have zero slippage protection.
-- **Leftover token absorption.** `_handleSwap` wraps all remaining `address(this).balance` as WETH after swaps. Any ETH sent directly to the contract (via `receive()`) is absorbed into the next swap's leftover calculation and routed to the project -- not returned to the sender.
+- **Cashout loop value extraction.** `_cashOutLoop` iterates up to 20 times, cashing out JB project tokens recursively. Each cashout incurs bonding curve slippage. `minTokensReclaimed` is only applied to the first step -- subsequent steps have zero slippage protection. Gas cost: each cashout iteration involves `terminal.cashOutTokensOf` (external call, ~100-200k gas) plus token transfer and balance accounting. At 20 iterations maximum, the worst case is ~4M gas for the loop alone, leaving headroom within a 30M block but consuming a significant portion.
+- **Leftover token absorption.** `_handleSwap` wraps all remaining `address(this).balance` as WETH after swaps. Any ETH sent directly to the contract (via `receive()`) is absorbed into the next swap's leftover calculation and routed to the project -- not returned to the sender. There is no sweep mechanism — ETH absorbed this way is permanently incorporated into the next routing operation. This is by design (the router is stateless and holds no balances across transactions), but users who accidentally send ETH directly to the contract should understand that it is unrecoverable.
 - **V4 native ETH settlement.** `_settleV4` unwraps WETH to native ETH when settling a `Currency.wrap(address(0))` debt with PoolManager. This is necessary because the router may hold WETH (from ERC-20 transfers or prior wrapping) but V4 native pools require `msg.value` settlement. If `address(this).balance` is already sufficient, no unwrap occurs.
 - **Pool selection by liquidity.** `_discoverPool` selects the pool with the highest `liquidity()` value. An attacker can deploy a pool with high but concentrated (out-of-range) liquidity to win selection, then manipulate the actual swap execution at worse prices.
 
@@ -22,7 +23,7 @@
 - **No access control on `pay` / `addToBalanceOf`.** Anyone can route payments. This is by design but means the contract processes arbitrary token types and amounts.
 - **Fee-on-transfer tokens unsupported.** `_acceptFundsFor` in the terminal uses balance-delta, but the registry does NOT. Fee-on-transfer tokens through the registry will mismatch.
 - **Credit cashout path.** `_acceptFundsFor` processes `cashOutSource` metadata to transfer credits from `_msgSender()`. Requires `TRANSFER_CREDITS` permission. If a user has this permission set broadly, any caller through the trusted forwarder could drain their credits.
-- **Registry owner.** Controls which terminals are allowlisted and sets the global default. Disallowing a terminal clears the default if it matches but does NOT clear per-project terminal settings already set to the disallowed terminal.
+- **Registry owner.** Controls which terminals are allowlisted and sets the global default. Disallowing the current default terminal now reverts with `CannotDisallowDefaultTerminal` instead of silently clearing it. Per-project terminal settings already set to a disallowed terminal are NOT cleared.
 - **Synthetic accounting contexts.** `JBRouterTerminal.accountingContextForTokenOf()` uses best-effort decimals for
   routing discovery: native tokens use `18`, ERC-20s probe `IERC20Metadata.decimals()` when available, and broken or
   non-standard tokens fall back to `18`. `JBRouterTerminalRegistry` simply forwards that context. This is safe for
@@ -30,6 +31,7 @@
   non-18-decimal assets. Lending and debt-normalization flows must point at a real terminal, not the router layer.
   The router now refuses to treat a primary terminal as direct acceptance unless that terminal also exposes non-empty
   accounting contexts for the project, so router-stack terminals do not win the direct-forward fast path.
+  For example, a USDC terminal (6 decimals) routed through the router reports `decimals: 6` correctly. But if the router cannot probe `IERC20Metadata.decimals()` (non-standard token, or reverting `decimals()` function), it falls back to 18 decimals — a 1e12 scaling error. This only affects routing discovery heuristics, not actual fund transfers, but could cause suboptimal pool selection in `_discoverPool`.
 
 ## 4. DoS Vectors
 
@@ -73,3 +75,11 @@ The router terminal has no `ReentrancyGuard` or `_routing` flag. This is a consc
 - **A reentrancy guard would block legitimate composition.** Projects may have terminal chains where terminal A routes through this router, which cashes out into terminal B, which itself routes through this router for a different project. A blanket reentrancy guard would break such flows.
 
 Verified in `RouterTerminalReentrancy.t.sol`: re-entrant calls via both `pay()` and `addToBalanceOf()` succeed without corrupting the outer call's ETH forwarding. The invariant suite (`RouterTerminalInvariant.t.sol`) further confirms that the router holds zero tokens and zero ETH after every operation — including operations that exercise the cashout recursion loop (`_cashOutLoop`, up to `_MAX_CASHOUT_ITERATIONS = 20`).
+
+### 8.2 Router trusts `originalPayer()` from any `msg.sender` that implements it
+
+`_resolveRefundTo` calls `IJBPayerTracker(msg.sender).originalPayer()` in a try-catch. If the call succeeds and returns a non-zero address, leftover tokens from partial swap fills are sent to that address instead of the beneficiary or `_msgSender()`. The router does not verify that `msg.sender` is the registry or any specific contract -- it trusts any caller that implements the interface. This is accepted because: (1) the caller (`msg.sender`) is the entity that supplied the funds, so redirecting its own leftovers is a legitimate operation, (2) if the call reverts or returns `address(0)`, the router falls back to the normal beneficiary/`_msgSender()` logic, and (3) decoupling from the registry allows other intermediary contracts (e.g. batch payers, aggregators) to participate in refund routing without requiring changes to the router terminal.
+
+### 8.3 Cashout loop slippage is first-hop only (accepted trade-off)
+
+`_cashOutLoop` applies `minTokensReclaimed` only to the first cashout step. Subsequent recursive cashouts (steps 2-20) have zero explicit slippage protection. This is accepted because: (1) adding per-step slippage would require the caller to predict intermediate token amounts across an unknown chain of cashouts, which is impractical, (2) the first-hop slippage check ensures the initial conversion meets the user's expectation, and (3) the recursive path is deterministic — intermediate projects' bonding curves and rulesets are on-chain state that cannot be manipulated between steps within a single transaction. The risk is limited to scenarios where intermediate projects have very low liquidity, causing high bonding-curve slippage on small amounts.