@bananapus/router-terminal-v6 0.0.27 → 0.0.28

package/ADMINISTRATION.md

@@ -11,14 +11,14 @@
 
 ## Purpose
 
-`nana-router-terminal-v6` splits administration between a global registry and project-local terminal selection. The router logic itself is mostly immutable; the mutable control plane lives in `JBRouterTerminalRegistry`.
+`nana-router-terminal-v6` splits administration between a global registry and project-local terminal selection. The router logic itself is mostly immutable. The mutable control plane lives in `JBRouterTerminalRegistry`.
 
 ## Control Model
 
-- `JBRouterTerminalRegistry` is globally `Ownable`.
-- Project owners or delegates choose and can lock their router terminal.
-- `JBRouterTerminal` has immutable routing dependencies and no owner-controlled strategy knobs.
-- Some transaction paths depend on project-local `JBPermissions`, such as `TRANSFER_CREDITS`.
+- `JBRouterTerminalRegistry` is globally `Ownable`
+- project owners or delegates choose and can lock their router terminal
+- `JBRouterTerminal` has immutable routing dependencies and no owner-controlled strategy knobs
+- some transaction paths depend on project-local `JBPermissions`, such as `TRANSFER_CREDITS`
 
 ## Roles
 
@@ -39,38 +39,38 @@
 
 ## Immutable And One-Way
 
-- `lockTerminalFor(...)` is irreversible.
-- Constructor dependencies on the router are immutable.
-- The current default terminal must move before the old default can be disallowed.
+- `lockTerminalFor(...)` is irreversible
+- constructor dependencies on the router are immutable
+- the current default terminal must move before the old default can be disallowed
 
 ## Operational Notes
 
-- Keep the terminal allowlist small and explicit.
-- Change the default terminal carefully because unconfigured projects inherit it.
-- Encourage projects to lock only after validating the resolved terminal and routing behavior.
-- Review credit-cashout routing permissions before relying on that path operationally.
-- Distinguish configuration risk from quote-quality risk: some route-discovery paths are best-effort, and some V4 quote paths can rely on weaker spot-style assumptions when robust history is unavailable.
+- keep the terminal allowlist small and explicit
+- change the default terminal carefully because unconfigured projects inherit it
+- encourage projects to lock only after validating the resolved terminal and routing behavior
+- review credit-cashout routing permissions before relying on that path
+- distinguish configuration risk from quote-quality risk
 
 ## Machine Notes
 
-- Do not treat registry ownership as authority to override locked project choice.
-- Inspect `src/JBRouterTerminalRegistry.sol` and `src/JBRouterTerminal.sol` separately; they govern different control boundaries.
-- If the effective terminal resolution and the documented default differ, stop and resolve the registry state before further actions.
-- If route previews are falling back to weaker discovery or quote paths, do not describe the router as offering uniform oracle-quality guarantees across all pools and states.
+- do not treat registry ownership as authority to override a locked project choice
+- inspect `src/JBRouterTerminalRegistry.sol` and `src/JBRouterTerminal.sol` separately; they govern different control boundaries
+- if effective terminal resolution and the documented default differ, resolve registry state before further actions
+- if route previews are falling back to weaker discovery or quote paths, do not describe the router as offering uniform oracle-quality guarantees
 
 ## Recovery
 
-- Unlocked projects can switch to another allowlisted terminal.
-- Locked projects cannot be unlocked by the registry.
-- Bad immutable router behavior means replacement infrastructure, not in-place edits.
-- Quote-path weakness is usually mitigated operationally with better pool choice, external quoting, or replacement routing infrastructure, not with an owner-only hotfix.
+- unlocked projects can switch to another allowlisted terminal
+- locked projects cannot be unlocked by the registry
+- bad immutable router behavior means replacement infrastructure, not in-place edits
+- quote-path weakness is usually mitigated operationally with better pool choice, external quoting, or replacement routing infrastructure
 
 ## Admin Boundaries
 
-- The registry owner cannot unlock or override a locked project terminal.
-- Project operators cannot set a terminal that the registry does not allow.
-- Router maintainers cannot tune routing heuristics or constructor immutables post-deploy.
-- There is no pause surface in the registry or router.
+- the registry owner cannot unlock or override a locked project terminal
+- project operators cannot set a terminal that the registry does not allow
+- router maintainers cannot tune routing heuristics or constructor immutables post-deploy
+- there is no pause surface in the registry or router
 
 ## Source Map
 

package/ARCHITECTURE.md

@@ -2,24 +2,26 @@
 
 ## Purpose
 
-`nana-router-terminal-v6` lets a payer fund a Juicebox project with a token the project does not directly accept. It discovers the destination token, unwraps or wraps native assets when needed, can recursively cash out upstream JB project tokens, and swaps through bounded Uniswap V3 or V4 routes before forwarding value to the destination terminal.
+`nana-router-terminal-v6` lets a payer fund a Juicebox project with a token the project does not directly accept. It discovers the destination token, wraps or unwraps native assets when needed, can recursively cash out upstream JB project tokens, and swaps through bounded Uniswap V3 or V4 routes before forwarding value to the destination terminal.
 
 The router is intentionally heuristic. It does not search every possible route for a globally optimal price.
 
 ## System Overview
 
-`JBRouterTerminal` is a terminal-shaped adapter, not an accounting source of truth. `JBRouterTerminalRegistry` is both a registry and a stable project-facing proxy surface: projects can point at the registry while the registry resolves, and can later lock, the actual router terminal implementation to use. `JBPayRouteResolver` expands preview candidates without forcing the main router contract to carry all preview complexity inline. Final accounting still occurs in the downstream terminal selected through `nana-core-v6`.
+`JBRouterTerminal` is a terminal-shaped adapter, not an accounting source of truth. `JBRouterTerminalRegistry` is both a registry and a stable project-facing proxy surface: projects can point at the registry while the registry resolves, and can later lock, the actual router terminal implementation to use. `JBPayRouteResolver` expands preview candidates without forcing the main router contract to carry all preview complexity inline.
+
+Final accounting still happens in the downstream terminal selected through `nana-core-v6`.
 
 ## Core Invariants
 
-- The router's own accounting context is synthetic and must not be treated as the project ledger.
-- Preview route discovery and live execution must stay aligned.
-- Refund behavior is part of correctness, not UX.
-- Registry locking prevents silent migration to untrusted router implementations.
-- Final terminal-facing ERC-20 hops only support standard, non-lossy transfers.
-- Recursive project-token cashout routing is intentionally bounded; non-converging paths should fail instead of looping.
-- Caller reclaim minima only apply to the first cashout hop, because later hops may change token units.
-- Circular `router -> registry -> same router` forwarding remains blocked in the registry.
+- the router's own accounting context is synthetic and must not be treated as the project ledger
+- preview route discovery and live execution must stay aligned
+- refund behavior is part of correctness, not just UX
+- registry locking prevents silent migration to untrusted router implementations
+- final terminal-facing ERC-20 hops only support standard, non-lossy transfers
+- recursive project-token cashout routing is intentionally bounded
+- caller reclaim minima only apply to the first cashout hop, because later hops may change token units
+- circular `router -> registry -> same router` forwarding remains blocked in the registry
 
 ## Modules
 
@@ -32,10 +34,10 @@ The router is intentionally heuristic. It does not search every possible route f
 
 ## Trust Boundaries
 
-- Final accounting remains in the downstream terminal selected through `JBDirectory`.
-- The router trusts Uniswap V3, Uniswap V4, Permit2, and optional payer trackers for routing-side behavior.
-- Fee-on-transfer tokens are only tolerated on ingress where received-balance deltas can be reconciled.
-- The registry is trusted to resolve and forward into the intended router terminal implementation for a project.
+- final accounting remains in the downstream terminal selected through `JBDirectory`
+- the router trusts Uniswap V3, Uniswap V4, Permit2, and optional payer trackers for routing-side behavior
+- fee-on-transfer tokens are only tolerated on ingress where received-balance deltas can be reconciled
+- the registry is trusted to resolve and forward into the intended router implementation for a project
 
 ## Critical Flows
 
@@ -55,24 +57,23 @@ router pay call
 
 The router does not own project balances. It owns transient route accounting: input reconciliation, swap execution, forwarded amount, and refund resolution.
 
-Preview and execution share the same conceptual route shape: optional recursive cashout first, then destination-token resolution, then final conversion and forwarding. `JBPayRouteResolver` narrows candidate tokens and usable external terminals so the live router does not need to brute-force every possibility inline.
+Preview and execution share the same conceptual route shape: optional recursive cashout first, then destination-token resolution, then final conversion and forwarding.
 
 ## Security Model
 
-- Native-asset handling and refunds are the most failure-prone paths.
-- V3 and V4 discovery must stay synchronized between preview and live execution.
-- V4 discovery intentionally considers both vanilla pools and pools using the canonical `UNIV4_HOOK`.
-- The router's “best route” claim is only as strong as its bounded discovery set and external-terminal safety checks. It is not a global optimizer.
-- Recursive cashout behavior, preferred-token handling, and one-shot source overrides are tightly coupled; changing one can silently desynchronize preview from execution.
-- “Best route” means best under the bounded discovery heuristic, not globally optimal routing.
+- native-asset handling and refunds are the most failure-prone paths
+- V3 and V4 discovery must stay synchronized between preview and live execution
+- V4 discovery intentionally considers both vanilla pools and pools using the canonical `UNIV4_HOOK`
+- the router's "best route" claim is only as strong as its bounded discovery set and external-terminal safety checks
+- recursive cashout behavior, preferred-token handling, and one-shot source overrides are tightly coupled
 
 ## Safe Change Guide
 
-- Keep route discovery and route execution semantics paired.
-- Be conservative with native wrapping, unwrapping, and refund behavior.
-- If recursive cash-out logic changes, review hop limits and failure handling together.
-- If metadata semantics change, re-check first-hop reclaim minima, one-shot source overrides, and preferred-token routing together.
-- Do not turn the router into a persistent treasury layer.
+- keep route discovery and route execution semantics paired
+- be conservative with native wrapping, unwrapping, and refund behavior
+- if recursive cash-out logic changes, review hop limits and failure handling together
+- if metadata semantics change, re-check first-hop reclaim minima, one-shot source overrides, and preferred-token routing together
+- do not turn the router into a persistent treasury layer
 
 ## Canonical Checks
 

package/AUDIT_INSTRUCTIONS.md

@@ -5,6 +5,7 @@ This repo accepts one token and routes value into whatever token a destination p
 ## Audit Objective
 
 Find issues that:
+
 - route user funds through an incorrect pool or protocol path
 - under-deliver relative to quoted or minimum-return semantics
 - refund leftovers to the wrong party or trap them in the router
@@ -14,6 +15,7 @@ Find issues that:
 ## Scope
 
 In scope:
+
 - `src/JBRouterTerminal.sol`
 - `src/JBRouterTerminalRegistry.sol`
 - `src/interfaces/`
@@ -22,6 +24,7 @@ In scope:
 - deployment scripts in `script/`
 
 Key dependencies:
+
 - `nana-core-v6`
 - Uniswap V3 and V4 integration surfaces
 
@@ -34,7 +37,8 @@ Key dependencies:
 ## Security Model
 
 The router terminal:
-- discovers what token a project’s terminal accepts
+
+- discovers what token a project's terminal accepts
 - decides whether to route via wrap/unwrap, V3, V4, Juicebox token cash-out, or a combination
 - forwards value into the destination terminal
 - optionally handles Permit2-funded transfers
@@ -59,17 +63,14 @@ The registry chooses which router terminal instance a project uses and whether t
 
 ## Critical Invariants
 
-1. User intent is preserved
-The actual destination project, beneficiary, minimum output semantics, and refund recipient must match the request and metadata.
-
-2. No leftover value disappears
-Partial fills, failed paths, and overfunded inputs must either be forwarded or refunded to the intended party.
-
-3. Pool discovery and settlement agree
-The quoted path, callback settlement, and final forwarded amount must all describe the same trade.
-
-4. Registry controls stay narrow
-Default terminals, allowed terminals, and lock semantics must not let an unexpected router instance take over project routing.
+1. User intent is preserved.  
+   The actual destination project, beneficiary, minimum output semantics, and refund recipient must match the request and metadata.
+2. No leftover value disappears.  
+   Partial fills, failed paths, and overfunded inputs must either be forwarded or refunded to the intended party.
+3. Pool discovery and settlement agree.  
+   The quoted path, callback settlement, and final forwarded amount must all describe the same trade.
+4. Registry controls stay narrow.  
+   Default terminals, allowed terminals, and lock semantics must not let an unexpected router instance take over project routing.
 
 ## Attack Surfaces
 

package/README.md

@@ -1,6 +1,6 @@
 # Juicebox Router Terminal
 
-`@bananapus/router-terminal-v6` is a routing terminal for Juicebox V6. It accepts value in many input tokens, discovers what token the destination project actually accepts, and forwards the payment through the best previewed route it can resolve from the configured candidates.
+`@bananapus/router-terminal-v6` is a routing terminal for Juicebox V6. It accepts value in many input tokens, discovers what token the destination project actually accepts, and forwards the payment through the best route it can resolve from the configured candidates.
 
 Docs: <https://docs.juicebox.money>  
 Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
@@ -19,7 +19,7 @@ It can route through:
 - direct forwarding when the destination already accepts the input token
 - wrapping or unwrapping native ETH and WETH
 - Uniswap V3 or V4 swaps
-- recursive Juicebox token cash outs when the input itself is a project token
+- recursive Juicebox token cash outs when the input is itself a project token
 
 Projects can use the registry to choose, and optionally lock, a project-specific router terminal or fall back to the registry's default terminal.
 
@@ -60,18 +60,18 @@ The shortest useful reading order is:
 
 ## Integration Traps
 
-- projects that expose a router terminal still settle into ordinary Juicebox terminals underneath; downstream semantics still matter
-- route discovery and route execution are related but not identical, especially when liquidity or metadata-supplied quotes move
+- projects that expose a router terminal still settle into ordinary Juicebox terminals underneath
+- route discovery and route execution are related but not identical, especially when liquidity or caller-supplied quote data moves
 - using JB project tokens as router input creates recursive path complexity that frontends and integrators should model explicitly
-- the registry layer changes who a project routes through, but not what the downstream terminal ultimately is
+- the registry changes which router a project uses, but not what downstream terminal ultimately settles the payment
 
 ## Where State Lives
 
-- route-selection logic lives in `JBRouterTerminal`
-- per-project router choice and lock status live in `JBRouterTerminalRegistry`
-- accepted-token accounting and final balance changes live in the downstream terminal, usually in `nana-core-v6`
+- route-selection logic: `JBRouterTerminal`
+- per-project router choice and lock status: `JBRouterTerminalRegistry`
+- accepted-token accounting and final balance changes: the downstream terminal, usually in `nana-core-v6`
 
-That separation is the reason a successful route can still end in a downstream terminal behavior you did not expect.
+That separation is why a successful route can still end in downstream terminal behavior you did not expect.
 
 ## High-Signal Tests
 
@@ -125,8 +125,8 @@ script/
 - the router synthesizes accounting context for discovery and should not be treated as an accounting-truth surface
 - swap previews are best-effort estimates and depend on current pool state plus caller-supplied quote data
 - recursive cash-out routing increases complexity when the input token is itself a Juicebox project token
-- slippage and sandwich resistance depend on the quality of the quote path chosen for the route
-- final terminal-facing ERC-20 hops must be standard tokens; lossy terminal pulls are rejected on both router and registry paths
+- slippage and sandwich resistance depend on the quality of the chosen quote path
+- final terminal-facing ERC-20 hops must be standard tokens; lossy terminal pulls are rejected
 
 The most common reader mistake here is to stop at the router and forget to inspect the terminal that actually receives the value.
 

package/RISKS.md

@@ -1,118 +1,105 @@
 # Router Terminal Risk Register
 
-This file focuses on the routing, accounting-context, and liquidity-selection risks in the terminal that accepts arbitrary tokens and forwards them into the destination project's real accounting surface.
+This file covers the routing, accounting-context, and liquidity-selection risks in the terminal that accepts arbitrary tokens and forwards them into a project's real accounting surface.
 
-## How to use this file
+## How To Use This File
 
-- Read `Priority risks` first; they explain where routing convenience can diverge from accounting truth.
-- Use the detailed sections for token-decimal synthesis, swap-path, and integration reasoning.
-- Treat `Accepted Behaviors` as explicit statements about what this terminal does not guarantee.
+- Read `Priority risks` first. They explain where routing convenience can diverge from accounting truth.
+- Use the later sections for token-decimal synthesis, swap-path, and integration reasoning.
+- Treat `Accepted behaviors` as explicit statements about what this terminal does not guarantee.
 
-## Priority risks
+## Priority Risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
-| P0 | Synthetic accounting context misuse | The router synthesizes best-effort decimals and routing context; if downstream systems treat it as accounting truth, they can misprice or mis-lend. | Clear docs, registry scoping, and explicit prohibition on accounting-sensitive reuse. |
-| P1 | Wrong-route or low-liquidity execution | The router chooses among direct forwarding, V3, V4, and cash-out paths; a bad route can degrade user execution. | Route selection tests, liquidity checks, and user-specified minimum returns. |
-| P1 | Integration fragility with broken tokens | Non-standard ERC-20 metadata or transfer behavior can distort decimal inference or swap execution. | Fallback defaults, defensive probing, receipt checks on terminal-facing hops, and integration testing with hostile token behavior. |
-
+| P0 | Synthetic accounting context misuse | The router synthesizes best-effort decimals and routing context. If downstream systems treat it as accounting truth, they can misprice or mis-lend. | Clear docs, registry scoping, and explicit prohibition on accounting-sensitive reuse. |
+| P1 | Wrong-route or low-liquidity execution | The router chooses among direct forwarding, V3, V4, and cash-out paths. A bad route can degrade user execution. | Route-selection tests, liquidity checks, and user-specified minimum returns. |
+| P1 | Integration fragility with broken tokens | Non-standard ERC-20 metadata or transfer behavior can distort decimal inference or swap execution. | Fallback defaults, defensive probing, receipt checks on terminal-facing hops, and hostile-token testing. |
 
 ## 1. Trust Assumptions
 
-- **Uniswap V3 Factory / V4 PoolManager.** Pool discovery trusts `FACTORY.getPool()` and `POOL_MANAGER.getSlot0()` to return legitimate pools. If the factory or pool manager is compromised, swaps route through attacker-controlled pools.
-- **Canonical V4 hook configuration.** Hooked V4 pool discovery relies on the immutable `UNIV4_HOOK` constructor value. If deployers point it at the wrong hook, the router can miss the intended buyback-hook / LP-split-hook pools and degrade to weaker routes or no route.
-- **Trusted forwarder.** ERC-2771 `_msgSender()` trusted for fund transfers. A compromised forwarder can initiate payments/transfers on behalf of any user.
-- **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.** `_resolveRefundWithBackupRecipient` 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 price manipulation.** `_getV4Quote` first attempts a 30-second TWAP from the pool's oracle hook (e.g., `IGeomeanOracle.observe()`). If no oracle hook exists or the call fails, it falls back to 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. This spot-fallback path is an accepted risk for integrations that cannot source external quotes, particularly when routing routine flow through sufficiently deep pools where manipulation cost is expected to dominate likely extractable value. Deep liquidity reduces practical risk but does not eliminate the same-block manipulation surface. Thin pools, fresh pools, and unusually large swaps should not rely on this fallback. Front-ends SHOULD supply `quoteForSwap` metadata for V4 swaps whenever possible. Note: `_getV4Quote` 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.
-- **Hooked V4 discovery scope.** Auto-discovery checks both vanilla V4 pools and pools using the configured canonical `UNIV4_HOOK`. That keeps buyback-hook and LP-split-hook routes discoverable, but it also means deployment misconfiguration of `UNIV4_HOOK` changes which hooked pools are even visible to the router.
-- **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. `cashOutMinReclaimed` is enforced only on the first concrete cashout hop. Later hops intentionally do not reuse or rescale that minimum, because multi-hop cashouts can change token units and a single metadata amount cannot be propagated safely across different assets. 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.
-- **Pre-existing balances are intentionally not swept into refunds.** `_handleSwap` snapshots a per-route refund baseline and only refunds the leftover input balance attributable to the current route. Tokens or ETH that were already sitting in the router before the route began are excluded from that refund calculation. This avoids gifting prior stray balances to the next caller, but it also means accidentally sent balances can remain stranded because the router has no sweep mechanism.
-- **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.
-- **Heuristic route selection, not best execution.** Automatic routing chooses among discovered paths using bounded heuristics, and pool discovery prefers the deepest discovered pool rather than exhaustively quoting every viable pool. This is an intentional tradeoff to keep routing predictable and gas-bounded. Integrators should treat router-selected execution as best-effort convenience, not a guarantee of the globally best obtainable output. When execution quality matters more than convenience, frontends should supply `quoteForSwap` metadata.
+- **Uniswap V3 factory and V4 PoolManager behave correctly.** Pool discovery trusts those external systems to point at real pools.
+- **Canonical V4 hook configuration is correct.** If deployers set the wrong `UNIV4_HOOK`, the router can miss intended hooked pools.
+- **The trusted forwarder is trustworthy.** A compromised forwarder can initiate transfers on behalf of any user.
+- **`JBDirectory` resolves the right terminals.** A compromised directory can redirect funds.
+- **Permit2 allowances are intentional.** Stale approvals can be abused.
+- **The registry owner acts correctly.** The owner controls allowlisting and the default router terminal.
+- **`IJBPayerTracker` callers are trusted to name their own refund recipient.** A caller implementing `originalPayer()` can redirect leftovers from its own route.
+
+## 2. Economic And Manipulation Risks
+
+- **V4 price manipulation.** `_getV4Quote` tries a 30-second TWAP first. If that fails, it falls back to spot pricing, which is manipulable within the block.
+- **Hooked V4 discovery scope.** Auto-discovery checks both vanilla V4 pools and pools using the configured canonical `UNIV4_HOOK`.
+- **V3 TWAP manipulation.** Short history reduces manipulation resistance, especially in new pools.
+- **Cash-out loop value extraction.** `_cashOutLoop` is capped at 20 iterations. `cashOutMinReclaimed` only applies on the first real cash-out hop.
+- **Pre-existing balances are intentionally excluded from route refunds.** Stray balances already sitting in the router are not swept into the next caller's refund.
+- **V4 native ETH settlement is special-cased.** `_settleV4` unwraps WETH when the pool manager expects native ETH.
+- **Pool selection is liquidity-first.** `_discoverPool` picks the deepest discovered pool, not the globally best execution path.
+- **Route selection is heuristic, not best execution.** The router bounds discovery for predictability and gas, not exhaustive optimization.
 
 ## 3. Access Control
 
-- **No access control on `pay` / `addToBalanceOf`.** Anyone can route payments. This is by design but means the contract processes arbitrary token types and amounts.
-- **Lossy terminal-facing ERC-20s unsupported on the router.** Ingress into the router is balance-delta reconciled, and the router's final forwarded ERC-20 hop is enforced by checking that the destination terminal actually received the full nominal ERC-20 amount. Fee-on-transfer or otherwise lossy terminal-facing ERC-20 pulls revert on the router. The registry does not perform receipt enforcement because it always forwards to the router terminal, which never retains tokens.
-- **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 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.
-- **Registry terminal selection can permanently snapshot a bad terminal.** `lockTerminalFor` is intentionally a one-way commitment to the project's currently resolved terminal. If governance or a project owner selects a terminal that later proves unusable, hostile, or simply misconfigured, locking that choice can permanently brick registry-mediated routing for that project until governance and deployment topology change around it. This is not unique to the registry itself pointing at itself; it is true for any bad terminal choice, so terminal selection and locking should be treated as a high-trust operational action.
-- **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
-  routing discovery but unsafe for integrations that treat the router or registry as a truthful accounting source for
-  non-18-decimal assets. Lending and debt-normalization flows must point at a real terminal, not the router layer.
-  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`.
+- **`pay` and `addToBalanceOf` are permissionless.** Anyone can route payments.
+- **Lossy terminal-facing ERC-20s are unsupported.** Final forwarded ERC-20 hops must settle exactly on the router path.
+- **Credit cash-out path depends on `TRANSFER_CREDITS`.** Broad grants of that permission widen the attack surface.
+- **The registry owner controls allowlisting and the global default.** Disallowing the current default now reverts instead of silently clearing it.
+- **Registry terminal locking can freeze a bad choice.** `lockTerminalFor` is a one-way commitment.
+- **Router accounting contexts are synthetic.** They are safe for discovery, but unsafe as accounting truth for lending, debt, or balance normalization.
 
 ## 4. DoS Vectors
 
-- **No pool exists.** If no V3 or V4 pool exists for a token pair, `_discoverPool` returns empty and the swap reverts. Projects accepting uncommon tokens may become unpayable through this terminal.
-- **No observation history.** V3 pools without TWAP observations cause `_getV3TwapQuote` to revert with `NoObservationHistory`. This blocks automatic routing.
-- **Cashout loop limit.** Circular or deep token dependency chains hit `_MAX_CASHOUT_ITERATIONS = 20` and revert.
-- **Pool with zero liquidity.** Pools with zero in-range liquidity cause reverts.
-- **External terminal reverts.** The final `destTerminal.pay()` or `destTerminal.addToBalanceOf()` call is not wrapped in try-catch. A reverting destination terminal blocks the entire payment.
-- **Non-standard final ERC-20 transfer behavior.** Terminal-facing ERC-20 hops are enforced to settle exactly on the router path. Tokens that burn, tax, or otherwise reduce the amount actually received by the destination terminal will revert on the final forwarded hop. The registry does not independently enforce receipt checks; it relies on the router to reject lossy transfers.
+- **No pool exists.** If no V3 or V4 pool exists for a token pair, automatic swap routing fails.
+- **No observation history.** V3 TWAP quoting can revert on fresh pools.
+- **Cash-out loop limit.** Circular or deep token dependency chains hit `_MAX_CASHOUT_ITERATIONS = 20` and revert.
+- **Zero-liquidity pools.** Pools with no usable liquidity revert.
+- **External terminal reverts.** Final terminal calls are not wrapped in `try/catch`.
+- **Non-standard final ERC-20 transfer behavior.** Lossy terminal-facing tokens revert on the final forwarded hop.
 
 ## 5. Integration Risks
 
-- **Registry default terminal change.** Projects without explicit terminal assignments use `defaultTerminal`. If the registry owner changes the default, all unlocked projects are silently migrated. `lockTerminalFor` mitigates this.
-- **Locked bad-terminal risk.** `lockTerminalFor` protects projects from silent migrations, but it also freezes the current resolved terminal exactly as-is. If the locked terminal is malformed, recursively forwards, reverts on use, or otherwise cannot actually process routed payments, the project can be left permanently unroutable through the registry.
-- **forceApprove for terminal transfers.** `_beforeTransferFor` uses `forceApprove`, which resets the allowance to zero before setting the new value. This mitigates stale-allowance accumulation: even if a previous transaction left a non-zero allowance, `forceApprove` overwrites it rather than adding to it. The reset-then-set pattern prevents cumulative allowance drift.
-- **Callback data trust.** `uniswapV3SwapCallback` validates the caller by reconstructing the pool address from `(tokenIn, tokenOut, fee)`. The factory `getPool` lookup makes spoofing infeasible in practice.
-- **receive() function.** The contract accepts arbitrary ETH via `receive()`. This is necessary for WETH unwraps, cashout reclaims, and V4 PoolManager takes. Route-specific leftover refunds only return ETH attributable to the active route; arbitrary ETH already sitting in the router before that route is not swept out automatically and can remain stranded.
+- **Registry default terminal changes affect unlocked projects.** Projects without explicit assignments follow `defaultTerminal`.
+- **Locked bad-terminal risk remains.** Locking protects against silent migration, but also freezes any mistake.
+- **`forceApprove` is used for terminal transfers.** This resets allowance before setting a new value and avoids stale-allowance accumulation.
+- **Callback data trust matters.** `uniswapV3SwapCallback` validates the pool by reconstructing its address from the expected parameters.
+- **The contract accepts arbitrary ETH.** That is necessary for unwraps and V4 settlement, but stray ETH can remain stranded.
 
 ## 6. MEV Surface
 
-- **V3 path: TWAP-protected.** The 10-minute TWAP oracle makes single-block manipulation futile. Multi-block attacks require sustained capital.
-- **V4 path: TWAP-first, spot-fallback.** V4 pools attempt a 30-second TWAP via the oracle hook first. If unavailable, the spot fallback is vulnerable. Without `quoteForSwap` metadata, V4 swaps using the spot fallback are exposed to up to sigmoid-slippage% loss per trade. The 2% floor bounds worst-case extraction.
-- **Cross-route arbitrage.** When JB routing bypasses the AMM (minting tokens directly), an arbitrage opportunity exists between the JB bonding curve price and the AMM price.
+- **V3 path is TWAP-protected.** A 10-minute TWAP makes single-block manipulation much harder.
+- **V4 path is TWAP-first, spot-fallback.** When no oracle quote is available, the spot fallback is vulnerable.
+- **Cross-route arbitrage exists.** When JB routing bypasses the AMM, differences between bonding-curve price and AMM price create arbitrage opportunities.
 
-## 7. Invariants to Verify
+## 7. Invariants To Verify
 
-- After any `pay()` or `addToBalanceOf()`, the contract should not retain balances attributable to the just-processed route. Pre-existing stray balances may still remain because refund logic intentionally excludes them.
-- `minAmountOut` in swaps is never zero when TWAP/spot price is available (the sigmoid formula has a 2% floor).
-- Callback validation: `uniswapV3SwapCallback` only transfers tokens to verified pool addresses.
-- `unlockCallback` only executes when called by `POOL_MANAGER`.
-- Credit cashout path: credits are transferred FROM `_msgSender()` only, never from arbitrary addresses.
-- Cashout loop terminates: either finds a terminal, reverts with `CashOutLoopLimit`, or reverts with `NoCashOutPath`.
+- after any `pay()` or `addToBalanceOf()`, the router should not retain balances attributable to the just-processed route
+- `minAmountOut` in swaps is never zero when TWAP or spot price is available
+- `uniswapV3SwapCallback` only transfers tokens to verified pool addresses
+- `unlockCallback` only executes when called by `POOL_MANAGER`
+- credit cash-out only transfers credits from `_msgSender()`
+- the cash-out loop always terminates: it finds a terminal, hits the loop limit, or reverts for lack of path
 
 ## 8. Accepted Behaviors
 
-### 8.1 No reentrancy guard (stateless routing)
-
-The router terminal has no `ReentrancyGuard` or `_routing` flag. This is a conscious design choice, not an oversight. During `_cashOutLoop`, the cashout terminal's callback could re-enter `pay()` or `addToBalanceOf()` on this router. This is safe because:
+### 8.1 No reentrancy guard
 
-- **The router is stateless.** It does not maintain mutable accounting between `_route()` and the final `destTerminal.pay/addToBalanceOf`. Each call independently accepts funds, routes them, and forwards the result. There is no shared mutable state that a re-entrant call could corrupt — no balances, no counters, no flags. The only storage is immutable configuration (DIRECTORY, TOKENS, WETH, etc.).
-- **CEI ordering is maintained within each call.** The execution flow follows a strict pipeline: (1) `_acceptFundsFor` pulls funds from the caller, (2) `_route` computes the destination and converts tokens if needed, (3) `_beforeTransferFor` + `destTerminal.pay/addToBalanceOf` forwards the result. Because there is no mutable state written between steps (1) and (3), there is nothing for a re-entrant call to read-before-write or corrupt. The "checks" and "effects" are collapsed into stateless computation, and the "interaction" (the final forwarding call) operates only on local variables.
-- **Each call uses its own funds.** The re-entrant call would need to supply its own tokens/ETH (via `_acceptFundsFor`). It cannot consume funds belonging to the outer call because those funds are already committed to the routing pipeline.
-- **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.
+The router has no `ReentrancyGuard` or `_routing` flag. This is intentional because the router is designed as a stateless routing layer, not a persistent accounting surface. Each call must fund and resolve its own route, and a blanket reentrancy guard would break legitimate composed routing 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`) confirms that routed operations do not strand balances attributable to the active route, including operations that exercise the cashout recursion loop (`_cashOutLoop`, up to `_MAX_CASHOUT_ITERATIONS = 20`). That does not imply the router can never hold pre-existing stray balances, because refund logic intentionally excludes balances that were already present before the route began.
+### 8.2 Router trusts `originalPayer()` from any caller that implements it
 
-### 8.2 Router trusts `originalPayer()` from any `msg.sender` that implements it
+`_resolveRefundWithBackupRecipient` calls `IJBPayerTracker(msg.sender).originalPayer()` in a `try/catch`. If the caller returns a non-zero address, leftovers can be sent there. This is accepted because the caller already supplied the funds being routed.
 
-`_resolveRefundWithBackupRecipient` 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.5 Registry owns immediate circular-forward protection
+### 8.3 Cash-out loop slippage is first-hop only
 
-The router and resolver no longer contain registry-specific circular-resolution logic. Instead, `JBRouterTerminalRegistry` rejects forwarding back into its immediate caller. This preserves separation of concerns: the router only rejects direct self-routes, while the registry owns protection against `router -> registry -> same router` recursion.
+`_cashOutLoop` applies `cashOutMinReclaimed` to the first cash-out step only. Later recursive hops may reclaim different assets with different units, so reusing one minimum across the full loop would be unsound.
 
-### 8.3 Cashout loop slippage is first-hop only
+### 8.4 Liquidity-first pool selection is intentional
 
-`_cashOutLoop` applies `cashOutMinReclaimed` to the first cashout step only. Subsequent recursive cashouts (steps 2-20) do not carry that minimum forward. This is intentional: later hops may reclaim different assets with different units and decimals, so rescaling a single metadata amount across the remaining path would be unit-unsound. Users who need tighter protection on the final routed output should still rely on the destination terminal's `minReturnedTokens` parameter and swap-level quote controls such as `quoteForSwap`.
+The router does not do an exhaustive best-execution search across every viable V3 and V4 pool. It prefers bounded discovery, lower complexity, and predictable behavior.
 
-### 8.4 Liquidity-first pool selection is intentional
+### 8.5 Registry owns immediate circular-forward protection
 
-The router does not attempt full best-execution search across every viable V3 and V4 pool. `_discoverPool` prefers the deepest discovered pool, and the selected pool is then quoted and executed. This can underperform an alternative pool in some market states, but it is an accepted product tradeoff: bounded route discovery, lower complexity, and predictable behavior are prioritized over exhaustive output maximization. Users who need tighter execution guarantees should provide `quoteForSwap` metadata or route externally.
+The router and resolver no longer contain registry-specific circular-resolution logic. `JBRouterTerminalRegistry` rejects forwarding back into its immediate caller instead.
 
 ### 8.6 V4 spot fallback is an accepted risk for programmatic integrations
 
-Automatic V4 quoting first tries a hook-provided oracle observation and only falls back to spot when no such quote is available. That fallback remains manipulable within the block and is not equivalent to an external quote or a trusted TWAP. It is nevertheless accepted in this terminal because some programmatic integrations cannot provide `quoteForSwap` metadata and still need a bounded on-chain quoting path. The intended operating envelope is routine routing through sufficiently deep pools with moderate swap sizes, where manipulation is possible in principle but expected to be uneconomic in practice. This is a risk reduction argument, not a safety proof: deep liquidity raises attack cost, but does not remove the vulnerability class.
+Automatic V4 quoting first tries a hook-provided oracle observation and falls back to spot only when that quote is unavailable. The fallback is still manipulable and is accepted only as a bounded on-chain quoting path for integrations that cannot provide `quoteForSwap` metadata.

package/SKILLS.md

@@ -2,8 +2,8 @@
 
 ## Use This File For
 
-- Use this file when the task involves routed payments or cash-outs, swap-path metadata, dynamic accepted-token discovery, route-registry selection, or router-terminal fee and slippage behavior.
-- Start here, then decide whether the problem is route discovery, swap execution, cash-out recursion, or registry selection. Those are distinct failure modes in this repo.
+- Use this file when the task involves routed payments or cash outs, swap-path metadata, dynamic accepted-token discovery, registry selection, or router slippage and refund behavior.
+- Start here, then decide whether the problem is route discovery, swap execution, cash-out recursion, or registry selection.
 
 ## Read This Next
 
@@ -32,17 +32,15 @@ Universal routing terminal for Juicebox V6. This repo accepts many input tokens,
 
 ## Reference Files
 
-- Open [`references/runtime.md`](./references/runtime.md) when you need the route-selection flow, cash-out loop behavior, callback and swap semantics, or the main invariants.
-- Open [`references/operations.md`](./references/operations.md) when you need registry and permission behavior, metadata keys, test breadcrumbs, or the main failure modes that cause stale assumptions.
+- Open [`references/runtime.md`](./references/runtime.md) when you need route-selection flow, cash-out loop behavior, callback and swap semantics, or main invariants.
+- Open [`references/operations.md`](./references/operations.md) when you need registry and permission behavior, metadata keys, test breadcrumbs, or common stale assumptions.
 
 ## Working Rules
 
 - Start in [`src/JBRouterTerminal.sol`](./src/JBRouterTerminal.sol) for execution behavior, but verify downstream semantics in the destination terminal before treating the router as the source of truth.
-- The router intentionally synthesizes accounting contexts instead of storing a static accepted-token list. If token acceptance looks wrong, verify discovery logic before touching registry state.
-- Treat preview behavior, quote selection, and execution callbacks as tightly coupled. Changes in one usually need verification in the others.
-- When the input token is itself a Juicebox project token, follow the cash-out loop carefully. Recursive routing assumptions are where subtle bugs hide.
-- Multi-hop and buyback-assisted routes are first-class behavior here, not edge cases. Verify them explicitly when changing route selection.
-- Refund handling is route-specific state, not cleanup garnish. Baseline snapshots and partial-fill leftovers are part of correctness.
-- Final terminal-facing receipt enforcement is a real boundary. If a terminal pull or forwarding model is non-standard, prove receipt semantics still hold before weakening guards.
-- Callback guards and final-hop receipt checks are security boundaries. Do not weaken them to accommodate non-standard token paths.
-- If you touch registry behavior, verify project-specific overrides, allowlisting, and terminal locking all still match the intended governance model.
+- The router intentionally synthesizes accounting contexts instead of storing a static accepted-token list.
+- Treat preview behavior, quote selection, and execution callbacks as tightly coupled.
+- When the input token is itself a Juicebox project token, follow the cash-out loop carefully.
+- Refund handling is part of correctness.
+- Final terminal-facing receipt enforcement and callback guards are real security boundaries.
+- If you touch registry behavior, verify project-specific overrides, allowlisting, and terminal locking together.

package/USER_JOURNEYS.md

@@ -2,9 +2,7 @@
 
 ## Repo Purpose
 
-This repo is the project-facing payment router for "user has X, project wants Y."
-It owns route discovery, preview behavior, registry-level router choice, and special handling for project-token and
-credit-based sources. It does not replace the downstream terminal that finally receives and accounts for value.
+This repo is the project-facing payment router for "user has X, project wants Y." It owns route discovery, preview behavior, registry-level router choice, and special handling for project-token and credit-based sources. It does not replace the downstream terminal that finally receives and accounts for value.
 
 ## Primary Actors
 
@@ -60,12 +58,12 @@ credit-based sources. It does not replace the downstream terminal that finally r
 **Failure Modes**
 - quotes are stale or liquidity moved before execution
 - permit, allowance, or refund handling breaks mid-route
-- metadata is valid for the destination terminal but not for route discovery assumptions
+- metadata is valid for the destination terminal but not for route-discovery assumptions
 
 **Postconditions**
 - the router converts the user's asset into the terminal's accepted asset and forwards the payment
 
-## Journey 3: Pay With A Juicebox Project Token Instead Of An External Asset
+## Journey 3: Pay With A Juicebox Project Token
 
 **Actor:** payer holding a project token.
 
@@ -86,7 +84,7 @@ credit-based sources. It does not replace the downstream terminal that finally r
 **Postconditions**
 - the router handles the recursive path correctly instead of assuming the input is a normal ERC-20
 
-## Journey 4: Route A Payment From Credits Or A Cash-Out Source
+## Journey 4: Route A Payment From Credits Or Another Cash-Out Source
 
 **Actor:** payer or integration using a non-wallet source position.
 
@@ -98,7 +96,7 @@ credit-based sources. It does not replace the downstream terminal that finally r
 **Main Flow**
 1. Encode the `cashOutSource` or equivalent metadata the router expects.
 2. Let the router pull credits or source-project value through the token and terminal surfaces it integrates with.
-3. Continue through the route-discovery process only after the source value has been converted into something the destination path can use.
+3. Continue through route discovery only after the source value has been converted into something the destination path can use.
 
 **Failure Modes**
 - `msg.value` is sent alongside credit-based routing and the route shape is wrong
@@ -124,7 +122,7 @@ credit-based sources. It does not replace the downstream terminal that finally r
 
 **Failure Modes**
 - preview assumptions become stale between quote and execution
-- the frontend surfaces a route as deterministic when the final path still depends on live market state
+- the frontend presents a route as deterministic when the final path still depends on live market state
 
 **Postconditions**
 - the quote is useful, and execution either lands close to it or fails clearly when conditions changed too much

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JBPayRouteResolver.sol

@@ -68,8 +68,13 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         JBAccountingContext[][] memory allContexts = new JBAccountingContext[][](terminals.length);
         uint256 totalContexts;
         for (uint256 i; i < terminals.length;) {
-            allContexts[i] = terminals[i].accountingContextsOf(projectId);
-            totalContexts += allContexts[i].length;
+            // Wrap in try/catch so a single reverting terminal does not DoS the entire route enumeration.
+            try terminals[i].accountingContextsOf(projectId) returns (JBAccountingContext[] memory ctx) {
+                allContexts[i] = ctx;
+                totalContexts += ctx.length;
+            } catch {
+                // Skip terminals that revert — allContexts[i] remains an empty array.
+            }
             unchecked {
                 ++i;
             }
@@ -165,7 +170,17 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
 
         for (uint256 i; i < terminals.length;) {
             // Read each terminal's accepted accounting contexts so the scorer can inspect every candidate token.
-            JBAccountingContext[] memory contexts = terminals[i].accountingContextsOf(projectId);
+            // Wrap in try/catch so a single reverting terminal does not DoS the entire route discovery.
+            JBAccountingContext[] memory contexts;
+            try terminals[i].accountingContextsOf(projectId) returns (JBAccountingContext[] memory ctx) {
+                contexts = ctx;
+            } catch {
+                // Skip terminals that revert.
+                unchecked {
+                    ++i;
+                }
+                continue;
+            }
 
             for (uint256 j; j < contexts.length;) {
                 // Pull the candidate token out of the accounting context being inspected.

package/test/audit/RevertingTerminalRouteDiscovery.t.sol

@@ -0,0 +1,463 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {IJBRulesetApprovalHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetApprovalHook.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
+import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
+import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
+
+import {JBPayRouteResolver} from "../../src/JBPayRouteResolver.sol";
+import {IJBPayRoutePreviewer} from "../../src/interfaces/IJBPayRoutePreviewer.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Mock: Terminal that returns accounting contexts normally.
+// ──────────────────────────────────────────────────────────────────────────────
+
+contract GoodTerminal {
+    address public immutable ACCEPTED_TOKEN;
+
+    constructor(address token_) {
+        ACCEPTED_TOKEN = token_;
+    }
+
+    function accountingContextsOf(uint256) external view returns (JBAccountingContext[] memory contexts) {
+        contexts = new JBAccountingContext[](1);
+        // forge-lint: disable-next-line(unsafe-typecast)
+        contexts[0] =
+            JBAccountingContext({token: ACCEPTED_TOKEN, decimals: 18, currency: uint32(uint160(ACCEPTED_TOKEN))});
+    }
+
+    function accountingContextForTokenOf(uint256, address token) external pure returns (JBAccountingContext memory) {
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return JBAccountingContext({token: token, decimals: 18, currency: uint32(uint160(token))});
+    }
+
+    function previewPayFor(
+        uint256,
+        address,
+        uint256 amount,
+        address,
+        bytes calldata
+    )
+        external
+        pure
+        returns (
+            JBRuleset memory ruleset,
+            uint256 beneficiaryTokenCount,
+            uint256 reservedTokenCount,
+            JBPayHookSpecification[] memory hookSpecifications
+        )
+    {
+        ruleset = JBRuleset({
+            cycleNumber: 1,
+            id: 1,
+            basedOnId: 0,
+            start: 0,
+            duration: 0,
+            weight: 0,
+            weightCutPercent: 0,
+            approvalHook: IJBRulesetApprovalHook(address(0)),
+            metadata: 0
+        });
+        beneficiaryTokenCount = amount;
+        reservedTokenCount = 0;
+        hookSpecifications = new JBPayHookSpecification[](0);
+    }
+
+    function supportsInterface(bytes4) external pure returns (bool) {
+        return true;
+    }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Mock: Terminal that always reverts on accountingContextsOf.
+// ──────────────────────────────────────────────────────────────────────────────
+
+contract RevertingTerminal {
+    function accountingContextsOf(uint256) external pure returns (JBAccountingContext[] memory) {
+        revert("RevertingTerminal: broken");
+    }
+
+    function accountingContextForTokenOf(uint256, address) external pure returns (JBAccountingContext memory) {
+        revert("RevertingTerminal: broken");
+    }
+
+    function supportsInterface(bytes4) external pure returns (bool) {
+        return true;
+    }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Mock: Minimal WETH for constructor.
+// ──────────────────────────────────────────────────────────────────────────────
+
+contract MockWETH {
+    mapping(address => uint256) public balanceOf;
+
+    function deposit() external payable {
+        balanceOf[msg.sender] += msg.value;
+    }
+
+    function withdraw(uint256 amount) external {
+        balanceOf[msg.sender] -= amount;
+        payable(msg.sender).transfer(amount);
+    }
+
+    receive() external payable {}
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Test contract
+// ──────────────────────────────────────────────────────────────────────────────
+
+contract RevertingTerminalRouteDiscoveryTest is Test {
+    JBPayRouteResolver internal resolver;
+    IJBDirectory internal directory;
+    IWETH9 internal weth;
+    IJBPayRoutePreviewer internal router;
+
+    uint256 internal constant PROJECT_ID = 42;
+    address internal tokenA;
+    address internal tokenB;
+    address internal tokenIn;
+
+    function setUp() public {
+        directory = IJBDirectory(makeAddr("directory"));
+        weth = IWETH9(address(new MockWETH()));
+        router = IJBPayRoutePreviewer(makeAddr("router"));
+
+        vm.etch(address(directory), hex"00");
+        vm.etch(address(router), hex"00");
+
+        resolver = new JBPayRouteResolver({directory: directory, weth: weth});
+
+        // Create distinct token addresses for testing.
+        tokenA = makeAddr("tokenA");
+        tokenB = makeAddr("tokenB");
+        tokenIn = makeAddr("tokenIn");
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Test 1: Route discovery succeeds when all terminals respond normally.
+    // ─────────────────────────────────────────────────────────────────────────
+
+    function test_resolveTokenOut_allTerminalsHealthy() public {
+        GoodTerminal goodTerminal = new GoodTerminal(tokenA);
+
+        IJBTerminal[] memory terminals = new IJBTerminal[](1);
+        terminals[0] = IJBTerminal(address(goodTerminal));
+
+        // Mock directory.terminalsOf -> returns the good terminal.
+        vm.mockCall(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (PROJECT_ID)), abi.encode(terminals));
+
+        // Mock directory.primaryTerminalOf for tokenIn -> address(0) (not directly accepted).
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenIn)),
+            abi.encode(address(0))
+        );
+
+        // Mock directory.primaryTerminalOf for tokenA -> goodTerminal.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenA)),
+            abi.encode(address(goodTerminal))
+        );
+
+        // Mock router.WETH() -> our weth address.
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.WETH, ()), abi.encode(address(weth)));
+
+        // Mock router.TOKENS() -> return a mock that says tokenIn is not a project token.
+        address mockTokens = makeAddr("tokens");
+        vm.etch(address(mockTokens), hex"00");
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.TOKENS, ()), abi.encode(mockTokens));
+        vm.mockCall(mockTokens, abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
+
+        // Mock router.bestPoolLiquidityOf -> some liquidity for tokenIn/tokenA pair.
+        vm.mockCall(
+            address(router),
+            abi.encodeCall(IJBPayRoutePreviewer.bestPoolLiquidityOf, (tokenIn, tokenA)),
+            abi.encode(uint128(1_000_000))
+        );
+
+        // Mock WETH for native token check (no native terminal).
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, address(weth))),
+            abi.encode(address(0))
+        );
+
+        (address resolvedTokenOut, IJBTerminal resolvedTerminal) =
+            resolver.resolveTokenOut({router: router, projectId: PROJECT_ID, tokenIn: tokenIn, metadata: ""});
+
+        assertEq(resolvedTokenOut, tokenA, "should resolve to tokenA from the healthy terminal");
+        assertEq(address(resolvedTerminal), address(goodTerminal), "should resolve to goodTerminal");
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Test 2: Route discovery still works when one terminal reverts -
+    //          other terminals' tokens are still discovered.
+    // ─────────────────────────────────────────────────────────────────────────
+
+    function test_resolveTokenOut_revertingTerminalSkipped_otherTerminalDiscovered() public {
+        RevertingTerminal revertingTerminal = new RevertingTerminal();
+        GoodTerminal goodTerminal = new GoodTerminal(tokenA);
+
+        IJBTerminal[] memory terminals = new IJBTerminal[](2);
+        terminals[0] = IJBTerminal(address(revertingTerminal));
+        terminals[1] = IJBTerminal(address(goodTerminal));
+
+        // Mock directory.terminalsOf -> returns both terminals.
+        vm.mockCall(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (PROJECT_ID)), abi.encode(terminals));
+
+        // Mock directory.primaryTerminalOf for tokenIn -> address(0) (not directly accepted).
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenIn)),
+            abi.encode(address(0))
+        );
+
+        // Mock directory.primaryTerminalOf for tokenA -> goodTerminal.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenA)),
+            abi.encode(address(goodTerminal))
+        );
+
+        // Mock router.WETH().
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.WETH, ()), abi.encode(address(weth)));
+
+        // Mock router.TOKENS().
+        address mockTokens = makeAddr("tokens");
+        vm.etch(address(mockTokens), hex"00");
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.TOKENS, ()), abi.encode(mockTokens));
+        vm.mockCall(mockTokens, abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
+
+        // Mock router.bestPoolLiquidityOf for tokenIn/tokenA pair.
+        vm.mockCall(
+            address(router),
+            abi.encodeCall(IJBPayRoutePreviewer.bestPoolLiquidityOf, (tokenIn, tokenA)),
+            abi.encode(uint128(500_000))
+        );
+
+        // Mock WETH for native token check.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, address(weth))),
+            abi.encode(address(0))
+        );
+
+        (address resolvedTokenOut, IJBTerminal resolvedTerminal) =
+            resolver.resolveTokenOut({router: router, projectId: PROJECT_ID, tokenIn: tokenIn, metadata: ""});
+
+        // The reverting terminal is skipped; the good terminal's token is discovered.
+        assertEq(resolvedTokenOut, tokenA, "should discover tokenA despite the reverting terminal");
+        assertEq(address(resolvedTerminal), address(goodTerminal), "should resolve to goodTerminal");
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Test 3: Route discovery returns empty when the only terminal reverts.
+    //          _discoverAcceptedToken returns (address(0), address(0)) and
+    //          resolveTokenOut reverts with JBRouterTerminal_NoRouteFound.
+    // ─────────────────────────────────────────────────────────────────────────
+
+    function test_resolveTokenOut_onlyTerminalReverts_noRouteFound() public {
+        RevertingTerminal revertingTerminal = new RevertingTerminal();
+
+        IJBTerminal[] memory terminals = new IJBTerminal[](1);
+        terminals[0] = IJBTerminal(address(revertingTerminal));
+
+        // Mock directory.terminalsOf -> returns the single reverting terminal.
+        vm.mockCall(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (PROJECT_ID)), abi.encode(terminals));
+
+        // Mock directory.primaryTerminalOf for tokenIn -> address(0).
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenIn)),
+            abi.encode(address(0))
+        );
+
+        // Mock router.WETH().
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.WETH, ()), abi.encode(address(weth)));
+
+        // Mock router.TOKENS().
+        address mockTokens = makeAddr("tokens");
+        vm.etch(address(mockTokens), hex"00");
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.TOKENS, ()), abi.encode(mockTokens));
+        vm.mockCall(mockTokens, abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
+
+        // Mock WETH for native token check.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, address(weth))),
+            abi.encode(address(0))
+        );
+
+        // Should revert because the only terminal reverts, leaving no discovered route.
+        vm.expectRevert();
+        resolver.resolveTokenOut({router: router, projectId: PROJECT_ID, tokenIn: tokenIn, metadata: ""});
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Test 4: previewBestPayRoute works when one terminal reverts and another
+    //          responds. Exercises _candidatePayRouteTokens.
+    // ─────────────────────────────────────────────────────────────────────────
+
+    function test_previewBestPayRoute_revertingTerminalSkipped() public {
+        RevertingTerminal revertingTerminal = new RevertingTerminal();
+        GoodTerminal goodTerminal = new GoodTerminal(tokenA);
+
+        IJBTerminal[] memory terminals = new IJBTerminal[](2);
+        terminals[0] = IJBTerminal(address(revertingTerminal));
+        terminals[1] = IJBTerminal(address(goodTerminal));
+
+        // Mock directory.terminalsOf.
+        vm.mockCall(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (PROJECT_ID)), abi.encode(terminals));
+
+        // Mock directory.primaryTerminalOf for tokenIn -> address(0) (not directly accepted).
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenIn)),
+            abi.encode(address(0))
+        );
+
+        // Mock directory.primaryTerminalOf for tokenA -> goodTerminal.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenA)),
+            abi.encode(address(goodTerminal))
+        );
+
+        // Mock router.WETH().
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.WETH, ()), abi.encode(address(weth)));
+
+        // Mock router.TOKENS() -> mock that says tokenIn is not a project token.
+        address mockTokens = makeAddr("tokens");
+        vm.etch(address(mockTokens), hex"00");
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.TOKENS, ()), abi.encode(mockTokens));
+        vm.mockCall(mockTokens, abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
+
+        // Mock router.BUYBACK_HOOK() -> address(0).
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.BUYBACK_HOOK, ()), abi.encode(address(0)));
+
+        // Mock router.bestPoolLiquidityOf -> 0 (no pool, triggers fallback route logic).
+        vm.mockCall(
+            address(router),
+            abi.encodeCall(IJBPayRoutePreviewer.bestPoolLiquidityOf, (tokenIn, tokenA)),
+            abi.encode(uint128(0))
+        );
+
+        // Mock WETH for native token check.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, address(weth))),
+            abi.encode(address(0))
+        );
+
+        // Mock router.previewSwapAmountOutOf -> returns amount (1:1 swap for simplicity).
+        vm.mockCall(
+            address(router),
+            abi.encodeWithSelector(IJBPayRoutePreviewer.previewSwapAmountOutOf.selector),
+            abi.encode(uint256(100 ether))
+        );
+
+        // Mock router.previewCashOutLoopOf -> returns no cashout (destTerminal=0, finalToken=tokenIn, amount
+        // unchanged).
+        vm.mockCall(
+            address(router),
+            abi.encodeWithSelector(IJBPayRoutePreviewer.previewCashOutLoopOf.selector),
+            abi.encode(IJBTerminal(address(0)), tokenIn, uint256(100 ether))
+        );
+
+        // Mock router.previewTerminalPayOf -> return a valid preview.
+        JBRuleset memory mockRuleset = JBRuleset({
+            cycleNumber: 1,
+            id: 1,
+            basedOnId: 0,
+            start: 0,
+            duration: 0,
+            weight: 0,
+            weightCutPercent: 0,
+            approvalHook: IJBRulesetApprovalHook(address(0)),
+            metadata: 0
+        });
+        JBPayHookSpecification[] memory emptyHooks = new JBPayHookSpecification[](0);
+        vm.mockCall(
+            address(router),
+            abi.encodeWithSelector(IJBPayRoutePreviewer.previewTerminalPayOf.selector),
+            abi.encode(mockRuleset, uint256(100 ether), uint256(0), emptyHooks)
+        );
+
+        // Call previewBestPayRoute — should succeed despite the reverting terminal.
+        (IJBTerminal destTerminal, address resolvedTokenOut,,, uint256 beneficiaryTokenCount,,) = resolver.previewBestPayRoute({
+            router: router,
+            projectId: PROJECT_ID,
+            tokenIn: tokenIn,
+            amount: 100 ether,
+            beneficiary: makeAddr("beneficiary"),
+            metadata: ""
+        });
+
+        assertEq(address(destTerminal), address(goodTerminal), "should route to goodTerminal");
+        assertEq(resolvedTokenOut, tokenA, "should route through tokenA");
+        assertGt(beneficiaryTokenCount, 0, "should produce beneficiary tokens");
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Test 5: previewBestPayRoute with only reverting terminals produces no
+    //          route (reverts).
+    // ─────────────────────────────────────────────────────────────────────────
+
+    function test_previewBestPayRoute_allTerminalsRevert_noRoute() public {
+        RevertingTerminal revertingTerminal = new RevertingTerminal();
+
+        IJBTerminal[] memory terminals = new IJBTerminal[](1);
+        terminals[0] = IJBTerminal(address(revertingTerminal));
+
+        // Mock directory.terminalsOf.
+        vm.mockCall(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (PROJECT_ID)), abi.encode(terminals));
+
+        // Mock directory.primaryTerminalOf for tokenIn -> address(0).
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, tokenIn)),
+            abi.encode(address(0))
+        );
+
+        // Mock router.WETH().
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.WETH, ()), abi.encode(address(weth)));
+
+        // Mock router.TOKENS().
+        address mockTokens = makeAddr("tokens");
+        vm.etch(address(mockTokens), hex"00");
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.TOKENS, ()), abi.encode(mockTokens));
+        vm.mockCall(mockTokens, abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
+
+        // Mock router.BUYBACK_HOOK().
+        vm.mockCall(address(router), abi.encodeCall(IJBPayRoutePreviewer.BUYBACK_HOOK, ()), abi.encode(address(0)));
+
+        // Mock WETH for native token check.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, address(weth))),
+            abi.encode(address(0))
+        );
+
+        // Should revert since no candidates are found.
+        vm.expectRevert();
+        resolver.previewBestPayRoute({
+            router: router,
+            projectId: PROJECT_ID,
+            tokenIn: tokenIn,
+            amount: 100 ether,
+            beneficiary: makeAddr("beneficiary"),
+            metadata: ""
+        });
+    }
+}