@bananapus/router-terminal-v6 0.0.41 → 0.0.43

package/CHANGELOG.md

@@ -6,6 +6,35 @@ This file describes the verified change from `nana-swap-terminal-v5` to the curr
 
 ## In-v6 changes
 
+### Chain-same CREATE2 address for `JBRouterTerminal`
+
+`JBRouterTerminal` now deploys to the same address on every chain via CREATE2. The four chain-specific
+immutables (`WRAPPED_NATIVE_TOKEN`, `FACTORY`, `POOL_MANAGER`, `UNIV4_HOOK`) moved from `immutable` to public
+storage and are wired in after deployment via a new one-shot `setChainSpecificConstants(wrappedNativeToken, factory, poolManager, univ4Hook)` setter, gated by a `_DEPLOYER` internal immutable (same pattern as `JBBuybackHook` and `JBUniswapV4LPSplitHookDeployer`).
+
+- Constructor signature changed: `(IJBDirectory directory, IJBTokens tokens, IPermit2 permit2, address buybackHook, address trustedForwarder, address deployer)` — was 9 args, now 6. The four chain-different dependencies are no longer ctor inputs.
+- New external function: `setChainSpecificConstants(IWETH9 wrappedNativeToken, IUniswapV3Factory factory, IPoolManager poolManager, address univ4Hook)`. Reverts with `JBRouterTerminal_Unauthorized(caller)` if msg.sender != `_DEPLOYER`; reverts with `JBRouterTerminal_AlreadyConfigured()` if `WRAPPED_NATIVE_TOKEN` has already been set.
+- `BUYBACK_HOOK` stays as `public immutable` because `JBBuybackHook` is itself chain-same as of `@bananapus/buyback-hook-v6@0.0.44`.
+
+`JBPayRouteResolver` also lost its `WRAPPED_NATIVE_TOKEN` immutable but does NOT call back into the router for it. Instead, the router passes its `WRAPPED_NATIVE_TOKEN` storage value as a parameter (`address wrappedNativeToken`) on every external resolver call (`previewBestPayRoute`, `previewPayRouteForCandidate`, `previewFallbackRoute`, `resolveTokenOut`), and the resolver threads it through internal helpers (`_normalizedTokenOf`, `_hasSameRoutingAsset`, `_discoverAcceptedToken`, `_resolveTokenOut`, `_previewAmountToToken`, `_previewRoute`). `_normalizedTokenOf` and `_hasSameRoutingAsset` are `pure` again. This avoids an extra external call per normalization step (which would compound inside the loops in `_discoverAcceptedToken`).
+
+The resolver is still deployed in the router's constructor (chain-same input: just `directory`); its CREATE address is `router.address + nonce 1`, which is chain-same once the router itself is chain-same.
+
+Integrator impact: deployers must call `setChainSpecificConstants` once after construction (the script in `script/Deploy.s.sol` does this in the same transaction as the deploy). Tests and the local deploy script have been updated accordingly.
+
+Size: `JBRouterTerminal` 23,706 → 23,468 B (-238 B; headroom 870 → 1,108 B against the EIP-170 24,576 B limit). `JBPayRouteResolver` 10,438 → 10,398 B (-40 B).
+
+### Removed: credit cash-out input path
+
+The router no longer accepts unclaimed Juicebox credits as a payment input. The `cashOutSource` metadata key, the `sourceProjectIdOverride` parameter on `previewCashOutLoopOf`, the `IJBController.transferCreditsFrom` pull in `_acceptFundsFor`, and the `_cashOutSourceFrom` helper have all been removed. Credit holders should call `JBTokens.claimFor` to materialize their credits as an ERC-20 first, then route through the router as a normal ERC-20 payment.
+
+- Removed: `IJBController` import + `_CASH_OUT_SOURCE_ID` immutable.
+- Removed: 3 test files (`RouterTerminalCreditCashout.t.sol`, `regression/CreditCashoutSpoofedPayer.t.sol`, `regression/CreditCashoutPreferredTokenBypass.t.sol`, `regression/PreviewCashOutShortcircuitDivergence.t.sol`).
+- Changed: `IJBPayRoutePreviewer.previewCashOutLoopOf` signature — dropped the `uint256 sourceProjectIdOverride` parameter (now 5 args).
+- Frees ~580 B of runtime size; reduces attack surface (no msg.sender-vs-originalPayer ambiguity in the credit pull).
+
+Integrator impact: any frontend or backend that constructs the `cashOutSource` metadata key and routes JB credits via the router must switch to a two-step flow (`claimFor` → `router.pay`).
+
 ### Threshold-protected `setDefaultTerminal`
 
 The registry owner's `setDefaultTerminal(IJBTerminal)` call now applies only to projects created AFTER the call. Existing projects without an explicit `setTerminalFor` override keep resolving to the default that was current when their project-ID cohort was active. The outgoing default is snapshotted into an append-only `_defaultTerminalHistory` array on every `setDefaultTerminal` call.

package/foundry.toml

@@ -1,5 +1,6 @@
 [profile.default]
 solc = '0.8.28'
+bytecode_hash = "none"
 evm_version = 'cancun'
 optimizer_runs = 200
 via_ir = true

package/package.json

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

package/script/Deploy.s.sol

@@ -172,19 +172,24 @@ contract DeployScript is Script, Sphinx {
             trustedForwarder: trustedForwarder
         });
 
-        // Deploy the router terminal using the resolved network-specific Uniswap and buyback-hook addresses.
+        // Deploy the router terminal with chain-same CREATE2 inputs; chain-specific constants
+        // (WETH + Uniswap V3 factory + V4 PoolManager + V4 hook) are wired afterwards via the
+        // DEPLOYER-gated one-shot setChainSpecificConstants setter on the terminal.
         require(address(buyback.hook) != address(0), "RouterTerminal: missing buyback hook");
         require(address(univ4Router.hook) != address(0), "RouterTerminal: missing v4 hook");
         JBRouterTerminal terminal = new JBRouterTerminal{salt: ROUTER_TERMINAL}({
             directory: core.directory,
             tokens: core.tokens,
             permit2: IPermit2(permit2),
-            weth: IWETH9(weth),
+            buybackHook: address(buyback.hook),
+            trustedForwarder: trustedForwarder,
+            deployer: safeAddress()
+        });
+        terminal.setChainSpecificConstants({
+            wrappedNativeToken: IWETH9(weth),
             factory: IUniswapV3Factory(factory),
             poolManager: IPoolManager(poolManager),
-            buybackHook: address(buyback.hook),
-            univ4Hook: address(univ4Router.hook),
-            trustedForwarder: trustedForwarder
+            univ4Hook: address(univ4Router.hook)
         });
 
         // Set the terminal as the default for the registry.

package/src/JBPayRouteResolver.sol

@@ -32,18 +32,18 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @notice The directory storing project terminal relationships, cached from the router at construction time.
     IJBDirectory public immutable DIRECTORY;
 
-    /// @notice The ERC-20 wrapper for the chain's native token, cached from the router at construction time.
-    IWETH9 public immutable WRAPPED_NATIVE_TOKEN;
-
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
     /// @param directory The directory storing project terminal relationships.
-    /// @param weth The ERC-20 wrapper for the chain's native token, used for router token normalization.
-    constructor(IJBDirectory directory, IWETH9 weth) {
+    /// @dev The wrapped-native-token address is intentionally NOT cached here. The router passes it in as a parameter
+    /// (`address wrappedNativeToken`) on every external resolver call and the resolver threads it through internal
+    /// helpers. This keeps the resolver's constructor inputs chain-same (no chain-specific WETH baked in) so its
+    /// CREATE address (router + nonce 1) stays unified, AND avoids paying an extra external call per normalization
+    /// step inside loops like `_discoverAcceptedToken`.
+    constructor(IJBDirectory directory) {
         DIRECTORY = directory;
-        WRAPPED_NATIVE_TOKEN = weth;
     }
 
     //*********************************************************************//
@@ -140,12 +140,15 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @notice Search a project's terminals for an accepted token that has a Uniswap pool with `tokenIn`.
     /// @dev Falls back to the first accepted token if no pool exists.
     /// @param router The router whose normalization and pool-discovery helpers should be used.
+    /// @param wrappedNativeToken The router's wrapped-native-token address (threaded from the caller to avoid an extra
+    /// external call on every normalization in this loop).
     /// @param projectId The destination project whose accepted tokens should be searched.
     /// @param tokenIn The input token to find a route from.
     /// @return tokenOut The best accepted token found.
     /// @return destTerminal The terminal that accepts `tokenOut`.
     function _discoverAcceptedToken(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn
     )
@@ -157,7 +160,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         IJBDirectory directory = DIRECTORY;
 
         // Normalize the input token once so liquidity comparisons use the router's canonical token form.
-        address normalizedTokenIn = _normalizedTokenOf(tokenIn);
+        address normalizedTokenIn = _normalizedTokenOf({wrappedNativeToken: wrappedNativeToken, token: tokenIn});
 
         // Read the destination project's currently known terminals directly from the directory.
         IJBTerminal[] memory terminals = directory.terminalsOf(projectId);
@@ -187,7 +190,8 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
                 address candidateToken = contexts[j].token;
 
                 // Normalize the candidate so native-vs-wrapped comparisons behave the same as the router.
-                address normalizedCandidate = _normalizedTokenOf(candidateToken);
+                address normalizedCandidate =
+                    _normalizedTokenOf({wrappedNativeToken: wrappedNativeToken, token: candidateToken});
 
                 // Skip tokens that are equivalent to the input token because they do not require route discovery.
                 if (normalizedCandidate == normalizedTokenIn) {
@@ -366,15 +370,25 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Check whether two tokens share the same routing representation for the router.
+    /// @param wrappedNativeToken The router's wrapped-native-token address, used to normalize native vs wrapped.
     /// @param tokenA The first token to compare.
     /// @param tokenB The second token to compare.
     /// @return hasSameAsset A flag indicating whether the router would treat both tokens as the same asset.
-    function _hasSameRoutingAsset(address tokenA, address tokenB) internal view returns (bool hasSameAsset) {
+    function _hasSameRoutingAsset(
+        address wrappedNativeToken,
+        address tokenA,
+        address tokenB
+    )
+        internal
+        pure
+        returns (bool hasSameAsset)
+    {
         // Treat exact-token matches as the same routing asset without extra normalization work.
         if (tokenA == tokenB) return true;
 
         // Otherwise compare normalized representations so native and wrapped native tokens share one routing identity.
-        return _normalizedTokenOf(tokenA) == _normalizedTokenOf(tokenB);
+        return _normalizedTokenOf({wrappedNativeToken: wrappedNativeToken, token: tokenA})
+            == _normalizedTokenOf({wrappedNativeToken: wrappedNativeToken, token: tokenB});
     }
 
     /// @notice Whether previewing through a terminal would cycle back into the router.
@@ -397,14 +411,23 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Normalize a token into the form the router uses for routing comparisons.
+    /// @param wrappedNativeToken The router's wrapped-native-token address.
     /// @param token The token to normalize.
     /// @return normalizedToken The normalized token address.
-    function _normalizedTokenOf(address token) internal view returns (address normalizedToken) {
-        return token == JBConstants.NATIVE_TOKEN ? address(WRAPPED_NATIVE_TOKEN) : token;
+    function _normalizedTokenOf(
+        address wrappedNativeToken,
+        address token
+    )
+        internal
+        pure
+        returns (address normalizedToken)
+    {
+        return token == JBConstants.NATIVE_TOKEN ? wrappedNativeToken : token;
     }
 
     /// @notice Preview the amount that would be routed into a specific destination token.
     /// @param router The router terminal whose preview helpers to use.
+    /// @param wrappedNativeToken The router's wrapped-native-token address.
     /// @param destProjectId The destination project the router is trying to pay.
     /// @param tokenIn The token currently available to route.
     /// @param amount The amount of `tokenIn` to preview.
@@ -414,6 +437,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @return routedAmountIn The amount of `routedTokenIn` that would reach the destination terminal.
     function _previewAmountToToken(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 destProjectId,
         address tokenIn,
         uint256 amount,
@@ -436,7 +460,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         });
 
         // Return early when the routed token already matches the desired destination token.
-        if (_hasSameRoutingAsset({tokenA: routedTokenIn, tokenB: tokenOut})) {
+        if (_hasSameRoutingAsset({wrappedNativeToken: wrappedNativeToken, tokenA: routedTokenIn, tokenB: tokenOut})) {
             return (tokenOut, routedAmountIn);
         }
 
@@ -467,6 +491,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @return hookSpecifications The hook specifications returned by the terminal preview.
     function _previewPayRouteForCandidate(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         uint256 amount,
@@ -490,6 +515,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         // First preview the route into the candidate destination token so the terminal is scored on post-route inputs.
         (address routedTokenIn, uint256 routedAmountIn) = _previewAmountToToken({
             router: router,
+            wrappedNativeToken: wrappedNativeToken,
             destProjectId: projectId,
             tokenIn: tokenIn,
             amount: amount,
@@ -532,6 +558,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @return amountOut The amount of `tokenOut` that would be routed.
     function _previewRoute(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 destProjectId,
         address tokenIn,
         uint256 amount,
@@ -555,11 +582,16 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         if (address(destTerminal) != address(0)) return (destTerminal, tokenIn, amount);
 
         // Resolve the destination token and terminal that the project would accept from the remaining input.
-        (tokenOut, destTerminal) =
-            _resolveTokenOut({router: router, projectId: destProjectId, tokenIn: tokenIn, metadata: metadata});
+        (tokenOut, destTerminal) = _resolveTokenOut({
+            router: router,
+            wrappedNativeToken: wrappedNativeToken,
+            projectId: destProjectId,
+            tokenIn: tokenIn,
+            metadata: metadata
+        });
 
         // Return the current amount unchanged when no swap is needed after token resolution.
-        if (_hasSameRoutingAsset({tokenA: tokenIn, tokenB: tokenOut})) {
+        if (_hasSameRoutingAsset({wrappedNativeToken: wrappedNativeToken, tokenA: tokenIn, tokenB: tokenOut})) {
             return (destTerminal, tokenOut, amount);
         }
 
@@ -590,19 +622,16 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         view
         returns (IJBTerminal resolvedTerminal, address routedTokenIn, uint256 routedAmountIn)
     {
-        // Resolve whether this preview should first treat the input token as a JB project-token cashout source.
-        (uint256 sourceProjectIdOverride, uint256 sourceProjectId) =
-            _sourceProjectIdOf({router: router, tokenIn: tokenIn, metadata: metadata});
-
-        // When there is no project-token source, the current input already is the routed input.
-        if (sourceProjectId == 0) return (resolvedTerminal, tokenIn, amount);
+        // When the input is not a JB project token, the current input already is the routed input.
+        if (tokenIn == JBConstants.NATIVE_TOKEN || router.TOKENS().projectIdOf(IJBToken(tokenIn)) == 0) {
+            return (resolvedTerminal, tokenIn, amount);
+        }
 
         // Otherwise reuse the router's own preview cashout loop so preview and execution stay aligned.
         return router.previewCashOutLoopOf({
             destProjectId: destProjectId,
             token: tokenIn,
             amount: amount,
-            sourceProjectIdOverride: sourceProjectIdOverride,
             metadata: metadata,
             preferredToken: preferredToken
         });
@@ -610,6 +639,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
 
     /// @notice Resolve what output token a project accepts for a given input token.
     /// @param router The router whose view helpers to use.
+    /// @param wrappedNativeToken The router's wrapped-native-token address.
     /// @param projectId The destination project to pay.
     /// @param tokenIn The input token to route.
     /// @param metadata Metadata forwarded into route-token resolution.
@@ -617,6 +647,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @return destTerminal The terminal that accepts `tokenOut`.
     function _resolveTokenOut(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         bytes calldata metadata
@@ -658,8 +689,8 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         }
 
         // Then try the native-token and wrapped-native-token equivalent form before falling back to pool discovery.
-        if (tokenIn == JBConstants.NATIVE_TOKEN || tokenIn == address(WRAPPED_NATIVE_TOKEN)) {
-            tokenOut = tokenIn == JBConstants.NATIVE_TOKEN ? address(WRAPPED_NATIVE_TOKEN) : JBConstants.NATIVE_TOKEN;
+        if (tokenIn == JBConstants.NATIVE_TOKEN || tokenIn == wrappedNativeToken) {
+            tokenOut = tokenIn == JBConstants.NATIVE_TOKEN ? wrappedNativeToken : JBConstants.NATIVE_TOKEN;
             destTerminal = directory.primaryTerminalOf({projectId: projectId, token: tokenOut});
             if (
                 address(destTerminal) != address(0)
@@ -670,7 +701,9 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         }
 
         // Finally discover the best accepted token using the router's liquidity heuristic.
-        (tokenOut, destTerminal) = _discoverAcceptedToken({router: router, projectId: projectId, tokenIn: tokenIn});
+        (tokenOut, destTerminal) = _discoverAcceptedToken({
+            router: router, wrappedNativeToken: wrappedNativeToken, projectId: projectId, tokenIn: tokenIn
+        });
 
         // Revert when discovery failed entirely or only found a circular route.
         if (
@@ -743,36 +776,6 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         reservedTokenCount = tokenCount - beneficiaryTokenCount;
     }
 
-    /// @notice Resolve whether the current route input should first be treated as a project-token cashout source.
-    /// @param router The router terminal whose project-token lookup should be used.
-    /// @param tokenIn The current route input token.
-    /// @param metadata Metadata that may include an explicit cashout-source override.
-    /// @return sourceProjectIdOverride The source project ID encoded in metadata, or 0 if none was provided.
-    /// @return sourceProjectId The effective source project ID inferred from `metadata` and `tokenIn`.
-    function _sourceProjectIdOf(
-        IJBPayRoutePreviewer router,
-        address tokenIn,
-        bytes calldata metadata
-    )
-        internal
-        view
-        returns (uint256 sourceProjectIdOverride, uint256 sourceProjectId)
-    {
-        // Read the router-scoped cashout-source metadata so preview matches the router's own metadata namespace.
-        (bool exists, bytes memory creditData) = _getDataFor({router: router, metadata: metadata, key: "cashOutSource"});
-
-        // Decode the explicit source-project override when the caller supplied one.
-        if (exists) (sourceProjectIdOverride,) = abi.decode(creditData, (uint256, uint256));
-
-        // Start from the explicit override.
-        sourceProjectId = sourceProjectIdOverride;
-
-        // Fall back to inferring the project ID from the input token whenever the token is not the native sentinel.
-        if (sourceProjectId == 0 && tokenIn != JBConstants.NATIVE_TOKEN) {
-            sourceProjectId = router.TOKENS().projectIdOf(IJBToken(tokenIn));
-        }
-    }
-
     /// @notice Choose the stronger preview outcome using beneficiary tokens first and reserved tokens as a tie-break.
     /// @param currentBeneficiaryTokenCount The beneficiary token count from the strongest route so far.
     /// @param currentReservedTokenCount The reserved token count from the strongest route so far.
@@ -841,6 +844,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @inheritdoc IJBPayRouteResolver
     function previewBestPayRoute(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         uint256 amount,
@@ -884,6 +888,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
             // Score the explicitly requested route directly instead of scanning every accepted token.
             return _previewPayRouteForCandidate({
                 router: router,
+                wrappedNativeToken: wrappedNativeToken,
                 projectId: projectId,
                 tokenIn: tokenIn,
                 amount: amount,
@@ -914,7 +919,15 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
 
             // Isolate each candidate preview so one broken route does not brick the whole search.
             try self.previewPayRouteForCandidate(
-                router, projectId, tokenIn, amount, beneficiary, metadata, candidateTokens[i], candidateTerminal
+                router,
+                wrappedNativeToken,
+                projectId,
+                tokenIn,
+                amount,
+                beneficiary,
+                metadata,
+                candidateTokens[i],
+                candidateTerminal
             ) returns (
                 IJBTerminal candidateDestTerminal,
                 address candidateTokenOut,
@@ -964,7 +977,9 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         // No candidate token could be scored — fall back to the router's generic route resolution.
         // Uses an external self-call (`self.previewFallbackRoute`) so Solidity's try/catch can isolate
         // reverts from broken terminals or price feeds without bricking the entire best-route preview.
-        try self.previewFallbackRoute(router, projectId, tokenIn, amount, beneficiary, metadata) returns (
+        try self.previewFallbackRoute(
+            router, wrappedNativeToken, projectId, tokenIn, amount, beneficiary, metadata
+        ) returns (
             IJBTerminal fallbackDestTerminal,
             address fallbackTokenOut,
             uint256 fallbackAmountOut,
@@ -1005,6 +1020,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @return hookSpecifications Any pay-hook specifications returned by the terminal preview.
     function previewFallbackRoute(
         IJBPayRoutePreviewer routePreviewer,
+        address wrappedNativeToken,
         uint256 destProjectId,
         address tokenIn,
         uint256 amountIn,
@@ -1025,7 +1041,12 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     {
         // Resolve which terminal and token the fallback route would use.
         (destTerminal, tokenOut, amountOut) = _previewRoute({
-            router: routePreviewer, destProjectId: destProjectId, tokenIn: tokenIn, amount: amountIn, metadata: metadata
+            router: routePreviewer,
+            wrappedNativeToken: wrappedNativeToken,
+            destProjectId: destProjectId,
+            tokenIn: tokenIn,
+            amount: amountIn,
+            metadata: metadata
         });
 
         // Simulate the terminal pay to get token counts and hook specs.
@@ -1065,6 +1086,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @return hookSpecifications The hook specifications returned by the terminal preview.
     function previewPayRouteForCandidate(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         uint256 amount,
@@ -1087,6 +1109,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     {
         return _previewPayRouteForCandidate({
             router: router,
+            wrappedNativeToken: wrappedNativeToken,
             projectId: projectId,
             tokenIn: tokenIn,
             amount: amount,
@@ -1100,6 +1123,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @inheritdoc IJBPayRouteResolver
     function resolveTokenOut(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         bytes calldata metadata
@@ -1108,7 +1132,13 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         view
         returns (address tokenOut, IJBTerminal destTerminal)
     {
-        return _resolveTokenOut({router: router, projectId: projectId, tokenIn: tokenIn, metadata: metadata});
+        return _resolveTokenOut({
+            router: router,
+            wrappedNativeToken: wrappedNativeToken,
+            projectId: projectId,
+            tokenIn: tokenIn,
+            metadata: metadata
+        });
     }
 
     /// @inheritdoc IJBPayRouteResolver

package/src/JBRouterTerminal.sol

@@ -2,7 +2,6 @@
 pragma solidity 0.8.28;
 
 import {IJBCashOutTerminal} from "@bananapus/core-v6/src/interfaces/IJBCashOutTerminal.sol";
-import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermitTerminal} from "@bananapus/core-v6/src/interfaces/IJBPermitTerminal.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
@@ -72,6 +71,7 @@ contract JBRouterTerminal is
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    error JBRouterTerminal_AlreadyConfigured();
     error JBRouterTerminal_AmountOverflow(uint256 amount);
     error JBRouterTerminal_CallerNotPool(address caller);
     error JBRouterTerminal_CallerNotPoolManager(address caller);
@@ -88,6 +88,7 @@ contract JBRouterTerminal is
     );
     error JBRouterTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
     error JBRouterTerminal_SlippageExceeded(uint256 amountOut, uint256 minAmountOut);
+    error JBRouterTerminal_Unauthorized(address caller);
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
@@ -120,39 +121,35 @@ contract JBRouterTerminal is
     //*********************************************************************//
 
     /// @notice The canonical buyback hook whose preview hook specification metadata this router understands.
+    /// @dev Chain-same: `JBBuybackHook` is deployed via CREATE2 to a unified address on every chain, so this stays
+    /// `immutable` without breaking the router's own chain-same CREATE2 address.
     address public immutable BUYBACK_HOOK;
 
-    /// @notice The canonical Uniswap V4 router hook address used by supported hooked pools.
-    address public immutable UNIV4_HOOK;
-
     /// @notice The directory of terminals and controllers for projects.
     IJBDirectory public immutable DIRECTORY;
 
-    /// @notice The Uniswap V3 factory used for pool discovery and verification.
-    IUniswapV3Factory public immutable FACTORY;
-
     /// @notice The Permit2 contract used for token approvals and transfers.
     IPermit2 public immutable override PERMIT2;
 
-    /// @notice The Uniswap V4 PoolManager. Can be address(0) if V4 is not deployed on this chain.
-    IPoolManager public immutable POOL_MANAGER;
-
     /// @notice Manages minting, burning, and balances of projects' tokens and token credits.
     IJBTokens public immutable TOKENS;
 
-    /// @notice The ERC-20 wrapper for the native token.
-    IWETH9 public immutable WRAPPED_NATIVE_TOKEN;
-
     //*********************************************************************//
     // -------------- internal immutable stored properties -------------- //
     //*********************************************************************//
 
+    /// @notice The deployer authorized to call `setChainSpecificConstants` exactly once.
+    /// @dev Held immutable so the constructor inputs are byte-identical across chains and the CREATE2 address is
+    /// unified. Mirrors the `JBOptimismSuckerDeployer.setChainSpecificConstants` pattern in nana-suckers-v6.
+    address internal immutable _DEPLOYER;
+
     /// @notice The helper contract used to resolve best pay-route previews without bloating router runtime size.
+    /// @dev Deployed in the constructor with chain-same inputs (just `directory` — the resolver does NOT cache
+    /// `WRAPPED_NATIVE_TOKEN` locally; the router passes it in on every external resolver call as a parameter to
+    /// avoid an extra external call on each normalization step). Because this router's address is chain-same via
+    /// CREATE2 and the resolver is deployed at the router's nonce 1, the resolver's address is chain-same too.
     IJBPayRouteResolver internal immutable _PAY_ROUTE_RESOLVER;
 
-    /// @notice Pre-computed metadata ID for "cashOutSource".
-    bytes4 internal immutable _CASH_OUT_SOURCE_ID;
-
     /// @notice Pre-computed metadata ID for "permit2".
     bytes4 internal immutable _PERMIT2_ID;
 
@@ -162,6 +159,32 @@ contract JBRouterTerminal is
     /// @notice Pre-computed metadata ID for "quoteForSwap".
     bytes4 internal immutable _QUOTE_FOR_SWAP_ID;
 
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    /// @notice The Uniswap V3 factory used for pool discovery and verification.
+    /// @dev Set once by `_DEPLOYER` via `setChainSpecificConstants`. Held as storage rather than immutable so the
+    /// constructor inputs are byte-identical on every chain (Uniswap V3 deploys to a different factory address per
+    /// chain).
+    IUniswapV3Factory public FACTORY;
+
+    /// @notice The Uniswap V4 PoolManager. Can be `address(0)` if V4 is not deployed on this chain.
+    /// @dev Set once by `_DEPLOYER` via `setChainSpecificConstants`. Held as storage rather than immutable so the
+    /// constructor inputs are byte-identical on every chain.
+    IPoolManager public POOL_MANAGER;
+
+    /// @notice The canonical Uniswap V4 router hook address used by supported hooked pools.
+    /// @dev Set once by `_DEPLOYER` via `setChainSpecificConstants`. Held as storage rather than immutable because
+    /// `JBUniswapV4Hook` inherits Uniswap's `BaseHook -> ImmutableState`, which forces a chain-specific PoolManager
+    /// immutable inside the hook itself — making the hook chain-different by design.
+    address public UNIV4_HOOK;
+
+    /// @notice The ERC-20 wrapper for the native token.
+    /// @dev Set once by `_DEPLOYER` via `setChainSpecificConstants`. Held as storage rather than immutable so the
+    /// constructor inputs are byte-identical on every chain (WETH/WCELO/etc. differ per chain).
+    IWETH9 public override WRAPPED_NATIVE_TOKEN;
+
     //*********************************************************************//
     // ---------------------- internal stored properties ----------------- //
     //*********************************************************************//
@@ -173,36 +196,28 @@ contract JBRouterTerminal is
     /// @param directory A contract storing directories of terminals and controllers for each project.
     /// @param tokens A contract managing project token balances.
     /// @param permit2 A permit2 utility.
-    /// @param weth The ERC-20 wrapper for the chain's native token (e.g. WETH on Ethereum, WCELO on Celo).
-    /// @param factory The Uniswap V3 factory for pool discovery.
-    /// @param poolManager The Uniswap V4 PoolManager (address(0) if V4 not available).
-    /// @param univ4Hook The canonical Uniswap V4 router hook used by supported hooked pools.
+    /// @param buybackHook The canonical buyback hook (chain-same across all chains).
     /// @param trustedForwarder The trusted forwarder for the contract.
+    /// @param deployer The address authorized to call `setChainSpecificConstants` exactly once. Held immutable so the
+    /// constructor inputs are byte-identical across chains and the CREATE2 address is unified.
     constructor(
         IJBDirectory directory,
         IJBTokens tokens,
         IPermit2 permit2,
-        IWETH9 weth,
-        IUniswapV3Factory factory,
-        IPoolManager poolManager,
         address buybackHook,
-        address univ4Hook,
-        address trustedForwarder
+        address trustedForwarder,
+        address deployer
     )
         ERC2771Context(trustedForwarder)
     {
         DIRECTORY = directory;
         TOKENS = tokens;
-        FACTORY = factory;
-        POOL_MANAGER = poolManager;
         PERMIT2 = permit2;
-        WRAPPED_NATIVE_TOKEN = weth;
         BUYBACK_HOOK = buybackHook;
-        UNIV4_HOOK = univ4Hook;
-        _PAY_ROUTE_RESOLVER = IJBPayRouteResolver(address(new JBPayRouteResolver({directory: directory, weth: weth})));
+        _DEPLOYER = deployer;
+        _PAY_ROUTE_RESOLVER = IJBPayRouteResolver(address(new JBPayRouteResolver({directory: directory})));
 
         // Pre-compute metadata IDs to avoid hashing string literals on every call.
-        _CASH_OUT_SOURCE_ID = JBMetadataResolver.getId("cashOutSource");
         _PERMIT2_ID = JBMetadataResolver.getId("permit2");
         _CASH_OUT_MIN_RECLAIMED_ID = JBMetadataResolver.getId("cashOutMinReclaimed");
         _QUOTE_FOR_SWAP_ID = JBMetadataResolver.getId("quoteForSwap");
@@ -377,6 +392,32 @@ contract JBRouterTerminal is
         // than `amount` but the router cannot detect or prevent this. See RISKS.md for details.
     }
 
+    /// @notice One-shot setter for the chain-specific Uniswap and wrapped-native addresses.
+    /// @dev Callable only by `_DEPLOYER` and only once (when `WRAPPED_NATIVE_TOKEN` is still `address(0)`). After this
+    /// call all four values are effectively immutable for the contract's lifetime. Mirrors the
+    /// `JBOptimismSuckerDeployer.setChainSpecificConstants` pattern so the contract's CREATE2 inputs stay
+    /// byte-identical across chains and its deployed address is unified.
+    /// @param wrappedNativeToken The ERC-20 wrapper for the chain's native token (e.g. WETH on Ethereum,
+    /// WCELO on Celo).
+    /// @param factory The Uniswap V3 factory for pool discovery on this chain.
+    /// @param poolManager The Uniswap V4 PoolManager on this chain (may be `address(0)` if V4 is not deployed there).
+    /// @param univ4Hook The canonical Uniswap V4 router hook on this chain.
+    function setChainSpecificConstants(
+        IWETH9 wrappedNativeToken,
+        IUniswapV3Factory factory,
+        IPoolManager poolManager,
+        address univ4Hook
+    )
+        external
+    {
+        if (msg.sender != _DEPLOYER) revert JBRouterTerminal_Unauthorized({caller: msg.sender});
+        if (address(WRAPPED_NATIVE_TOKEN) != address(0)) revert JBRouterTerminal_AlreadyConfigured();
+        WRAPPED_NATIVE_TOKEN = wrappedNativeToken;
+        FACTORY = factory;
+        POOL_MANAGER = poolManager;
+        UNIV4_HOOK = univ4Hook;
+    }
+
     /// @notice The Uniswap v3 pool callback where the token transfer is expected to happen.
     /// @dev Verifies the caller is a legitimate pool via the factory using the encoded tokenIn/tokenOut pair.
     /// @param amount0Delta The amount of token 0 used for the swap.
@@ -603,18 +644,16 @@ contract JBRouterTerminal is
             JBPayHookSpecification[] memory hookSpecifications
         )
     {
-        // Simulate how the router would normalize the incoming funds before routing.
-        amount = _previewAcceptFundsFor({amount: amount, metadata: metadata});
-        (,,, ruleset, beneficiaryTokenCount, reservedTokenCount, hookSpecifications) = _previewBestPayRoute({
-            projectId: projectId, tokenIn: token, amount: amount, beneficiary: beneficiary, metadata: metadata
-        });
+        (,,, ruleset, beneficiaryTokenCount, reservedTokenCount, hookSpecifications) =
+            _previewBestPayRoute({
+                projectId: projectId, tokenIn: token, amount: amount, beneficiary: beneficiary, metadata: metadata
+            });
     }
 
     /// @notice Preview the recursive cashout loop the router would use for a project-token input.
     /// @param destProjectId The destination project the router is trying to pay.
     /// @param token The current token to route.
     /// @param amount The amount of `token` to preview.
-    /// @param sourceProjectIdOverride The one-shot source project override encoded in metadata, if any.
     /// @param metadata Metadata forwarded into preview helpers.
     /// @param preferredToken The token the cashout loop should prefer to land on, or `address(0)` for no preference.
     /// @return destTerminal The terminal reached by the cashout loop, or address(0) if routing should continue.
@@ -624,7 +663,6 @@ contract JBRouterTerminal is
         uint256 destProjectId,
         address token,
         uint256 amount,
-        uint256 sourceProjectIdOverride,
         bytes calldata metadata,
         address preferredToken
     )
@@ -636,7 +674,6 @@ contract JBRouterTerminal is
             destProjectId: destProjectId,
             token: token,
             amount: amount,
-            sourceProjectIdOverride: sourceProjectIdOverride,
             metadata: metadata,
             preferredToken: preferredToken
         });
@@ -716,7 +753,7 @@ contract JBRouterTerminal is
 
     /// @notice Resolve the original payer when called through an intermediary.
     /// @dev Registry-style forwarders record the original payer in transient storage via `IJBPayerTracker`. When
-    /// present, that address is used for refunds and credit cashouts instead of the intermediary.
+    /// present, that address is used for refunds instead of the intermediary.
     /// @param fallback_ The default address to use when no original payer is available.
     /// @return The original payer, or `fallback_` if none is available.
     function _resolveOriginalPayer(address fallback_) internal view returns (address) {
@@ -854,8 +891,11 @@ contract JBRouterTerminal is
         )
     {
         // Delegate the heavy preview-selection logic to the helper contract so the router stays within runtime size.
+        // Pass `wrappedNativeToken` once (single SLOAD) so the resolver does not have to call back into the router for
+        // it on every normalization step.
         return _PAY_ROUTE_RESOLVER.previewBestPayRoute({
             router: IJBPayRoutePreviewer(address(this)),
+            wrappedNativeToken: address(WRAPPED_NATIVE_TOKEN),
             projectId: projectId,
             tokenIn: tokenIn,
             amount: amount,
@@ -891,18 +931,6 @@ contract JBRouterTerminal is
         });
     }
 
-    /// @notice Check whether two tokens share the same routing representation.
-    /// @param tokenA The first token to compare.
-    /// @param tokenB The second token to compare.
-    /// @return hasSameAsset A flag indicating whether the router treats both tokens as the same asset.
-    function _hasSameRoutingAsset(address tokenA, address tokenB) internal view returns (bool hasSameAsset) {
-        // Treat exact-token matches as the same asset without doing any normalization work.
-        if (tokenA == tokenB) return true;
-
-        // Otherwise compare normalized representations so native and wrapped native tokens share one routing identity.
-        return _normalize(tokenA) == _normalize(tokenB);
-    }
-
     /// @notice Snapshot a destination terminal's pre-call token balance and check forwarding status.
     /// @dev Combines both the balance snapshot and forwarding probe into a single helper to avoid duplicate
     /// `_isForwardingTerminal` calls in the pay/addToBalance flows.
@@ -1006,57 +1034,21 @@ contract JBRouterTerminal is
     }
 
     /// @notice Resolve which source project a routed token should cash out from.
-    /// @param sourceProjectIdOverride A one-shot source-project override decoded from routing metadata.
     /// @param token The current route token that may be a JB project token.
     /// @return sourceProjectId The project to cash out from, or 0 if the token is not a JB project token.
-    function _sourceProjectIdOf(
-        uint256 sourceProjectIdOverride,
-        address token
-    )
-        internal
-        view
-        returns (uint256 sourceProjectId)
-    {
-        // Prefer the explicit one-shot override when metadata supplied one.
-        sourceProjectId = sourceProjectIdOverride;
-
-        // Otherwise infer the source project from the current token unless it is the native-token sentinel.
-        if (sourceProjectId == 0 && token != JBConstants.NATIVE_TOKEN) {
-            sourceProjectId = _projectIdOf(token);
-        }
+    function _sourceProjectIdOf(address token) internal view returns (uint256 sourceProjectId) {
+        if (token != JBConstants.NATIVE_TOKEN) sourceProjectId = _projectIdOf(token);
     }
 
     /// @notice Accept a token paid in by the caller.
     /// @param token The address of the token to accept.
     /// @param amount The amount of tokens to accept.
-    /// @param metadata The metadata in which `permit2` and credit context is provided.
+    /// @param metadata The metadata in which `permit2` context is provided.
     /// @return The amount of tokens accepted.
     function _acceptFundsFor(address token, uint256 amount, bytes calldata metadata) internal returns (uint256) {
         // Cache _msgSender() once to avoid repeated ERC-2771 context resolution.
         address sender = _msgSender();
 
-        // Check for credit cash-out metadata.
-        (bool creditExists, bytes memory creditData) = _getDataFor({metadata: metadata, id: _CASH_OUT_SOURCE_ID});
-
-        if (creditExists) {
-            // Credit cashouts don't use msg.value — revert if ETH was sent to prevent it being trapped.
-            if (msg.value != 0) revert JBRouterTerminal_NoMsgValueAllowed(msg.value);
-
-            (uint256 sourceProjectId, uint256 creditAmount) = abi.decode(creditData, (uint256, uint256));
-
-            // Use the direct sender as the credit holder. Do NOT resolve via _resolveOriginalPayer here,
-            // because a malicious contract could spoof originalPayer() to steal another user's credits.
-            address holder = sender;
-
-            // Pull credits through the project's controller, which enforces holder permissions for credit transfers.
-            IJBController controller = IJBController(address(DIRECTORY.controllerOf(sourceProjectId)));
-            controller.transferCreditsFrom({
-                holder: holder, projectId: sourceProjectId, recipient: address(this), creditCount: creditAmount
-            });
-
-            return creditAmount;
-        }
-
         // If native tokens are being paid in, return the `msg.value`.
         if (token == JBConstants.NATIVE_TOKEN) return msg.value;
 
@@ -1142,8 +1134,6 @@ contract JBRouterTerminal is
     /// @param destProjectId The ID of the destination project.
     /// @param token The current token to process.
     /// @param amount The amount of the current token.
-    /// @param sourceProjectIdOverride When non-zero, use this as the source project ID instead of looking up via
-    /// `TOKENS.projectIdOf()`. Reset to 0 after first use.
     /// @param metadata Bytes in `JBMetadataResolver`'s format (may contain cashOutMinReclaimed).
     /// @return destTerminal The terminal that accepts the final token (address(0) if no direct acceptance found).
     /// @return finalToken The token after all cashouts.
@@ -1152,7 +1142,6 @@ contract JBRouterTerminal is
         uint256 destProjectId,
         address token,
         uint256 amount,
-        uint256 sourceProjectIdOverride,
         bytes calldata metadata,
         address preferredToken
     )
@@ -1168,24 +1157,18 @@ contract JBRouterTerminal is
         // Walk the cashout path hop by hop until we reach a directly acceptable destination asset or exhaust the
         // bounded iteration limit.
         for (uint256 i; i < _MAX_CASHOUT_ITERATIONS;) {
-            // Skip the destination check on the first iteration if we have a credit override — the forced
-            // cashout must happen before any early return.
-            if (sourceProjectIdOverride == 0) {
-                address routeToken;
-                (destTerminal, routeToken) =
-                    _findRouteTerminal({destProjectId: destProjectId, token: token, preferredToken: preferredToken});
-                if (address(destTerminal) != address(0)) {
-                    if (preferredToken != address(0)) {
-                        (routeToken, amount) =
-                            _alignTokenToPreferredToken({token: token, amount: amount, preferredToken: preferredToken});
-                    }
-                    return (destTerminal, routeToken, amount);
+            address routeToken;
+            (destTerminal, routeToken) =
+                _findRouteTerminal({destProjectId: destProjectId, token: token, preferredToken: preferredToken});
+            if (address(destTerminal) != address(0)) {
+                if (preferredToken != address(0)) {
+                    (routeToken, amount) =
+                        _alignTokenToPreferredToken({token: token, amount: amount, preferredToken: preferredToken});
                 }
+                return (destTerminal, routeToken, amount);
             }
 
-            // Use the override if provided, otherwise look up the project ID from the token.
-            uint256 sourceProjectId =
-                _sourceProjectIdOf({sourceProjectIdOverride: sourceProjectIdOverride, token: token});
+            uint256 sourceProjectId = _sourceProjectIdOf(token);
 
             // If it's not a JB project token, return as-is (caller handles the swap).
             if (sourceProjectId == 0) return (IJBTerminal(address(0)), token, amount);
@@ -1236,7 +1219,6 @@ contract JBRouterTerminal is
 
             // Update for next iteration.
             token = tokenToReclaim;
-            sourceProjectIdOverride = 0;
 
             unchecked {
                 ++i;
@@ -1410,7 +1392,7 @@ contract JBRouterTerminal is
         address v4In = normalizedTokenIn == address(WRAPPED_NATIVE_TOKEN) ? address(0) : normalizedTokenIn;
 
         // Determine the V4 swap direction by comparing the input token to currency0 in the pool key.
-        bool zeroForOne = _unwrapCurrency(key.currency0) == v4In;
+        bool zeroForOne = Currency.unwrap(key.currency0) == v4In;
 
         // Use extreme sqrtPriceLimitX96 to allow full swap execution. Slippage is enforced by
         // the post-swap minAmountOut check in the unlock callback.
@@ -1525,7 +1507,11 @@ contract JBRouterTerminal is
 
         // Resolve what token the destination project accepts and which terminal to use.
         (tokenOut, destTerminal) = _PAY_ROUTE_RESOLVER.resolveTokenOut({
-            router: IJBPayRoutePreviewer(address(this)), projectId: destProjectId, tokenIn: tokenIn, metadata: metadata
+            router: IJBPayRoutePreviewer(address(this)),
+            wrappedNativeToken: address(WRAPPED_NATIVE_TOKEN),
+            projectId: destProjectId,
+            tokenIn: tokenIn,
+            metadata: metadata
         });
 
         // Convert the post-cashout route input into the resolved destination token and refund any leftover input.
@@ -1595,7 +1581,7 @@ contract JBRouterTerminal is
     /// @param destProjectId The destination project to reach.
     /// @param tokenIn The current route input token.
     /// @param amount The current route input amount.
-    /// @param metadata Metadata that may include a cashout-source override.
+    /// @param metadata Metadata that may include a cashOutMinReclaimed floor.
     /// @param preferredToken The preferred token to target during any cashout loop.
     /// @return resolvedTerminal The terminal found by the cashout loop, or address(0) if conversion should continue.
     /// @return routedTokenIn The token that remains to be routed after the cashout step.
@@ -1610,20 +1596,14 @@ contract JBRouterTerminal is
         internal
         returns (IJBTerminal resolvedTerminal, address routedTokenIn, uint256 routedAmountIn)
     {
-        // Read any one-shot source-project override that should force the first cashout hop.
-        (uint256 sourceProjectIdOverride,) = _cashOutSourceFrom(metadata);
-        // Start from the explicit override, then fall back to inferring the source project from the input token.
-        uint256 sourceProjectId = _sourceProjectIdOf({sourceProjectIdOverride: sourceProjectIdOverride, token: tokenIn});
-
-        // Leave the route unchanged when the input is not a JB project token and no override was provided.
-        if (sourceProjectId == 0) return (resolvedTerminal, tokenIn, amount);
+        // Leave the route unchanged when the input is not a JB project token.
+        if (_sourceProjectIdOf(tokenIn) == 0) return (resolvedTerminal, tokenIn, amount);
 
         // Cash out through the discovered source project before the caller continues with direct routing or swaps.
         return _cashOutLoop({
             destProjectId: destProjectId,
             token: tokenIn,
             amount: amount,
-            sourceProjectIdOverride: sourceProjectIdOverride,
             metadata: metadata,
             preferredToken: preferredToken
         });
@@ -1667,7 +1647,7 @@ contract JBRouterTerminal is
     /// @param amount The amount of `currency` to settle.
     /// @param canUseExistingNativeBalance Whether already-held raw native tokens can be used before unwrapping.
     function _settleV4(Currency currency, uint256 amount, bool canUseExistingNativeBalance) internal {
-        if (_unwrapCurrency(currency) == address(0)) {
+        if (Currency.unwrap(currency) == address(0)) {
             // Native-funded routes may spend the ETH they already hold.
             // Wrapped-native-funded routes must not consume unrelated raw native tokens already sitting on the router.
             if (canUseExistingNativeBalance) {
@@ -1686,7 +1666,7 @@ contract JBRouterTerminal is
             // ERC20 settlement requires PoolManager to observe the token first (`sync`), then receive the transfer,
             // then finalize the accounting with `settle`.
             POOL_MANAGER.sync(currency);
-            IERC20(_unwrapCurrency(currency)).safeTransfer({to: address(POOL_MANAGER), value: amount});
+            IERC20(Currency.unwrap(currency)).safeTransfer({to: address(POOL_MANAGER), value: amount});
             POOL_MANAGER.settle();
         }
     }
@@ -1699,7 +1679,7 @@ contract JBRouterTerminal is
         POOL_MANAGER.take({currency: currency, to: address(this), amount: amount});
 
         // If native token output, wrap it (downstream _handleSwap unwraps if needed).
-        if (_unwrapCurrency(currency) == address(0)) _wrapNativeToken(amount);
+        if (Currency.unwrap(currency) == address(0)) _wrapNativeToken(amount);
     }
 
     /// @notice Transfer tokens from one address to another using direct approval, `safeTransfer`, or Permit2 as a
@@ -1859,22 +1839,6 @@ contract JBRouterTerminal is
         if (address(pool.v3Pool) != address(0)) return pool.v3Pool.liquidity();
     }
 
-    /// @notice Parse the optional `cashOutSource` metadata.
-    /// @param metadata The metadata to inspect for credit cashout overrides.
-    /// @return sourceProjectId The source project override, or 0 if none is specified.
-    /// @return amount The credit amount, or 0 if none is specified.
-    function _cashOutSourceFrom(bytes calldata metadata)
-        internal
-        view
-        returns (uint256 sourceProjectId, uint256 amount)
-    {
-        // Read the optional cash-out source payload from the metadata blob.
-        (bool exists, bytes memory creditData) = _getDataFor({metadata: metadata, id: _CASH_OUT_SOURCE_ID});
-
-        // Decode the source project and credit amount if the payload is present.
-        if (exists) (sourceProjectId, amount) = abi.decode(creditData, (uint256, uint256));
-    }
-
     /// @notice Return the ERC-2771 context suffix length used by the inherited forwarder-aware context.
     /// @return suffixLength The number of bytes appended to calldata for the forwarded sender.
     /// @dev ERC-2771 specifies the context as a single address, which is always 20 bytes.
@@ -1899,7 +1863,8 @@ contract JBRouterTerminal is
         returns (IJBTerminal terminal, address resultToken)
     {
         if (preferredToken != address(0)) {
-            if (_hasSameRoutingAsset({tokenA: token, tokenB: preferredToken})) {
+            // Same-routing-asset check: exact match, or both normalize to the same wrapped-native form.
+            if (token == preferredToken || _normalize(token) == _normalize(preferredToken)) {
                 terminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: preferredToken});
                 if (address(terminal) != address(0)) return (terminal, preferredToken);
             }
@@ -2099,7 +2064,7 @@ contract JBRouterTerminal is
 
                 // Priority 1: Does the destination project directly accept this token through a usable terminal?
                 IJBTerminal destTerminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: contextToken});
-                candidates = _recordCashOutPathCandidate({
+                _recordCashOutPathCandidate({
                     candidates: candidates, contextToken: contextToken, terminal: terminal, destTerminal: destTerminal
                 });
 
@@ -2133,11 +2098,11 @@ contract JBRouterTerminal is
     }
 
     /// @notice Record a reclaim token as a direct, recursive, or base fallback during cashout-path discovery.
-    /// @param candidates The current fallback candidates accumulated so far.
+    /// @dev Mutates `candidates` in place (memory struct passed by reference) — no return value needed.
+    /// @param candidates The current fallback candidates accumulated so far. Updated in-place by this call.
     /// @param contextToken The token exposed by the current cashout terminal accounting context.
     /// @param terminal The cashout terminal that can reclaim `contextToken`.
     /// @param destTerminal The destination project's direct terminal for `contextToken`, if any.
-    /// @return updatedCandidates The fallback set after considering `contextToken`.
     function _recordCashOutPathCandidate(
         CashOutPathCandidates memory candidates,
         address contextToken,
@@ -2146,10 +2111,7 @@ contract JBRouterTerminal is
     )
         internal
         view
-        returns (CashOutPathCandidates memory updatedCandidates)
     {
-        updatedCandidates = candidates;
-
         // Treat native ETH as a non-recursive base asset. For ERC-20s, detect whether the token is itself a JB
         // project token so recursive and base fallbacks stay disjoint.
         bool isJbProjectToken;
@@ -2158,22 +2120,22 @@ contract JBRouterTerminal is
         }
 
         // Record the first directly accepted token only when its destination terminal is actually usable.
-        if (address(destTerminal) != address(0) && address(updatedCandidates.directFallbackTerminal) == address(0)) {
-            updatedCandidates.directFallbackToken = contextToken;
-            updatedCandidates.directFallbackTerminal = terminal;
+        if (address(destTerminal) != address(0) && address(candidates.directFallbackTerminal) == address(0)) {
+            candidates.directFallbackToken = contextToken;
+            candidates.directFallbackTerminal = terminal;
         }
 
         // Record the first JB project token so the router can recurse through another cashout hop if no direct or
         // base-token exit ends up existing.
-        if (address(updatedCandidates.fallbackTerminal) == address(0) && isJbProjectToken) {
-            updatedCandidates.fallbackToken = contextToken;
-            updatedCandidates.fallbackTerminal = terminal;
+        if (address(candidates.fallbackTerminal) == address(0) && isJbProjectToken) {
+            candidates.fallbackToken = contextToken;
+            candidates.fallbackTerminal = terminal;
         }
 
         // Record the first non-JB base-token fallback so the router can at least continue via a swap route.
-        if (address(updatedCandidates.baseFallbackTerminal) == address(0) && !isJbProjectToken) {
-            updatedCandidates.baseFallbackToken = contextToken;
-            updatedCandidates.baseFallbackTerminal = terminal;
+        if (address(candidates.baseFallbackTerminal) == address(0) && !isJbProjectToken) {
+            candidates.baseFallbackToken = contextToken;
+            candidates.baseFallbackTerminal = terminal;
         }
     }
 
@@ -2510,28 +2472,10 @@ contract JBRouterTerminal is
         }
     }
 
-    /// @notice A view-only mirror of `_acceptFundsFor` used for previews.
-    /// @dev Preview semantics use the caller-supplied `amount` as the intended input amount.
-    /// @param amount The caller-supplied payment amount.
-    /// @param metadata The metadata to inspect for credit cashout overrides.
-    /// @return The effective amount that routing should use.
-    function _previewAcceptFundsFor(uint256 amount, bytes calldata metadata) internal view returns (uint256) {
-        // Credit cashouts use the credit amount encoded in metadata rather than the raw token amount.
-        (uint256 sourceProjectId, uint256 creditAmount) = _cashOutSourceFrom(metadata);
-
-        // Mirror execution semantics exactly: the presence of a source override means the decoded
-        // credit amount, even `0`, is the effective routed amount.
-        if (sourceProjectId != 0) return creditAmount;
-
-        // Otherwise, use the caller-specified amount unchanged.
-        return amount;
-    }
-
     /// @notice A view-only mirror of `_cashOutLoop`.
     /// @param destProjectId The ID of the destination project.
     /// @param token The current token to process.
     /// @param amount The amount of the current token.
-    /// @param sourceProjectIdOverride An optional source project override from metadata.
     /// @param metadata Bytes in `JBMetadataResolver`'s format.
     /// @return destTerminal The terminal that accepts the final token, if found.
     /// @return finalToken The token after all cash-out steps.
@@ -2540,7 +2484,6 @@ contract JBRouterTerminal is
         uint256 destProjectId,
         address token,
         uint256 amount,
-        uint256 sourceProjectIdOverride,
         bytes calldata metadata,
         address preferredToken
     )
@@ -2555,17 +2498,12 @@ contract JBRouterTerminal is
 
         // Walk the same cash-out path execution would take, bounded to prevent circular routes.
         for (uint256 i; i < _MAX_CASHOUT_ITERATIONS;) {
-            // Skip destination checks when the forced first cashout hasn't happened yet (mirrors _cashOutLoop).
-            if (sourceProjectIdOverride == 0) {
-                address routeToken;
-                (destTerminal, routeToken) =
-                    _findRouteTerminal({destProjectId: destProjectId, token: token, preferredToken: preferredToken});
-                if (address(destTerminal) != address(0)) return (destTerminal, routeToken, amount);
-            }
+            address routeToken;
+            (destTerminal, routeToken) =
+                _findRouteTerminal({destProjectId: destProjectId, token: token, preferredToken: preferredToken});
+            if (address(destTerminal) != address(0)) return (destTerminal, routeToken, amount);
 
-            // Use the override once when present; otherwise infer the source project from the current JB token.
-            uint256 sourceProjectId =
-                _sourceProjectIdOf({sourceProjectIdOverride: sourceProjectIdOverride, token: token});
+            uint256 sourceProjectId = _sourceProjectIdOf(token);
 
             // If this is no longer a JB project token, stop cashing out and let the caller continue routing from it.
             if (sourceProjectId == 0) return (IJBTerminal(address(0)), token, amount);
@@ -2592,9 +2530,6 @@ contract JBRouterTerminal is
             // Continue previewing from the token reclaimed in this hop.
             token = tokenToReclaim;
 
-            // Consume the one-shot override so later hops derive their project from the reclaimed token itself.
-            sourceProjectIdOverride = 0;
-
             unchecked {
                 ++i;
             }
@@ -2710,13 +2645,6 @@ contract JBRouterTerminal is
         return Currency.wrap(token);
     }
 
-    /// @notice Unwrap a Uniswap V4 `Currency` back into an address.
-    /// @param currency The currency value to unwrap.
-    /// @return token The unwrapped token address.
-    function _unwrapCurrency(Currency currency) internal pure returns (address token) {
-        return Currency.unwrap(currency);
-    }
-
     /// @notice Return the V3 fee tier at the given index.
     /// @dev Replaces the storage array `_FEE_TIERS` with a pure function (no SLOAD).
     /// @param index The tier index (0-3), ordered by commonality: 0.3%, 0.05%, 1%, 0.01%.

package/src/JBRouterTerminalRegistry.sol

@@ -26,6 +26,8 @@ import {IJBForwardingTerminal} from "./interfaces/IJBForwardingTerminal.sol";
 import {IJBPayerTracker} from "./interfaces/IJBPayerTracker.sol";
 import {IJBRouterTerminalRegistry} from "./interfaces/IJBRouterTerminalRegistry.sol";
 
+import {JBForwardingCheck} from "./libraries/JBForwardingCheck.sol";
+
 import {DefaultTerminalSegment} from "./structs/DefaultTerminalSegment.sol";
 
 /// @notice A forwarding layer that lets each project choose which router terminal receives its payments, with an
@@ -306,26 +308,45 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         return ERC2771Context._msgSender();
     }
 
-    /// @notice Reject terminal choices that would forward the project back into this registry.
+    /// @notice Returns the original payer to record in transient storage. If `_msgSender()` is a
+    /// contract that exposes `IJBPayerTracker.originalPayer()` and that getter returns a non-zero
+    /// value, the upstream payer is propagated so a forwarding chain (project payer -> registry
+    /// -> router) refunds the true originator instead of the intermediary. Otherwise the direct
+    /// caller is recorded — the common direct-call case.
+    /// @return originalPayerOrSender The upstream payer if the resolved sender is a forwarding
+    /// tracker that returns a non-zero address; otherwise the resolved sender itself.
+    function _originalPayerOrSender() internal view returns (address originalPayerOrSender) {
+        // Resolve through ERC-2771 so a trusted meta-tx forwarder is transparently unwrapped.
+        address sender = _msgSender();
+
+        // EOAs and contracts without code can't implement IJBPayerTracker — record them directly.
+        if (sender.code.length == 0) return sender;
+
+        // Probe the caller for IJBPayerTracker.originalPayer() via staticcall so a reverting or
+        // non-conformant caller does not bubble up — fall back to the resolved sender on failure.
+        (bool ok, bytes memory data) = sender.staticcall(abi.encodeWithSelector(IJBPayerTracker.originalPayer.selector));
+
+        // Caller doesn't implement the interface (revert) or returned a truncated payload — treat
+        // it as a direct payment from the caller itself.
+        if (!ok || data.length < 32) return sender;
+
+        // Decode the upstream payer the caller advertised. A zero value means "no upstream tracked",
+        // which only happens when the caller is itself receiving a direct call — record the caller.
+        address upstream = abi.decode(data, (address));
+        return upstream == address(0) ? sender : upstream;
+    }
+
+    /// @notice Reject terminal choices that would forward the project back into this registry,
+    /// directly or transitively. Walks up to the depth limit `JBForwardingCheck` enforces so a
+    /// chain registry -> A -> B -> registry is caught (the previous one-hop probe missed those
+    /// transitive cycles, letting a project lock itself into a route that always loops).
     /// @param projectId The project to validate forwarding for.
     /// @param terminal The terminal to validate.
     function _requireNonCircularTerminalFor(uint256 projectId, IJBTerminal terminal) internal view {
         // Reject direct self-selection so the registry cannot forward a project to itself.
         if (address(terminal) == address(this)) revert JBRouterTerminalRegistry_CircularForward(terminal);
-
-        // Externally owned accounts cannot implement `terminalOf`, so there is no forwarding route to inspect.
-        if (address(terminal).code.length == 0) return;
-
-        // If the candidate is another forwarding terminal, ask where this project would end up.
-        try IJBForwardingTerminal(address(terminal)).terminalOf({projectId: projectId}) returns (
-            IJBTerminal downstreamTerminal
-        ) {
-            // Reject one-hop forwarding cycles that bounce this project back into the registry.
-            if (address(downstreamTerminal) == address(this)) {
-                revert JBRouterTerminalRegistry_CircularForward({terminal: terminal});
-            }
-        } catch {
-            // Non-forwarding terminals are valid choices; failed interface probes should not block them.
+        if (JBForwardingCheck.isCircularTerminal({target: address(this), projectId: projectId, terminal: terminal})) {
+            revert JBRouterTerminalRegistry_CircularForward({terminal: terminal});
         }
     }
 
@@ -409,8 +430,9 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         address previousPayer = originalPayer;
 
         // Store the original payer in transient storage so downstream router terminals can refund partial-fill
-        // leftovers to the true payer.
-        originalPayer = _msgSender();
+        // leftovers to the true payer. If the immediate caller is itself a forwarding intermediary that exposes
+        // its own original payer, propagate that — otherwise refunds in nested forwards stop at the intermediary.
+        originalPayer = _originalPayerOrSender();
 
         // Reject forwards that would bounce straight back into this call's immediate caller.
         _enforceNoCircularForward(terminal);
@@ -559,8 +581,9 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         address previousPayer = originalPayer;
 
         // Store the original payer in transient storage so downstream router terminals can refund partial-fill
-        // leftovers to the true payer.
-        originalPayer = _msgSender();
+        // leftovers to the true payer. If the immediate caller is itself a forwarding intermediary that exposes
+        // its own original payer, propagate that — otherwise refunds in nested forwards stop at the intermediary.
+        originalPayer = _originalPayerOrSender();
 
         // Reject forwards that would bounce straight back into this call's immediate caller.
         _enforceNoCircularForward(terminal);
@@ -598,6 +621,11 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
 
         uint256 count = PROJECTS.count();
 
+        // Reject defaults that would route any current project back into the registry through a
+        // transitive forwarding chain. Probed at the current project-count snapshot since the
+        // default is what unconfigured (and all-future) projects will resolve to.
+        _requireNonCircularTerminalFor({projectId: count, terminal: terminal});
+
         // Snapshot the OUTGOING default so existing projects (ID <= count) continue resolving to
         // it, not to the new default. First-ever call has defaultTerminal == 0 and nothing to snapshot.
         if (address(defaultTerminal) != address(0)) {

package/src/interfaces/IJBPayRoutePreviewer.sol

@@ -30,7 +30,6 @@ interface IJBPayRoutePreviewer {
     /// @param destProjectId The destination project the router is trying to pay.
     /// @param token The current token to route.
     /// @param amount The amount of `token` to preview.
-    /// @param sourceProjectIdOverride The one-shot source project override encoded in metadata, if any.
     /// @param metadata Metadata forwarded into preview helpers.
     /// @param preferredToken The token the cashout loop should prefer to land on, or `address(0)` for no preference.
     /// @return destTerminal The terminal reached by the cashout loop, or address(0) if routing should continue.
@@ -40,7 +39,6 @@ interface IJBPayRoutePreviewer {
         uint256 destProjectId,
         address token,
         uint256 amount,
-        uint256 sourceProjectIdOverride,
         bytes calldata metadata,
         address preferredToken
     )

package/src/interfaces/IJBPayRouteResolver.sol

@@ -11,6 +11,8 @@ import {IJBPayRoutePreviewer} from "./IJBPayRoutePreviewer.sol";
 interface IJBPayRouteResolver {
     /// @notice Preview the best pay route for a router terminal.
     /// @param router The router terminal whose preview helpers to use.
+    /// @param wrappedNativeToken The router's wrapped-native-token address, passed in so the resolver does not have to
+    /// call back into the router for it on every normalization step.
     /// @param projectId The destination project that would receive the payment.
     /// @param tokenIn The token currently available to route.
     /// @param amount The amount of `tokenIn` to preview.
@@ -25,6 +27,7 @@ interface IJBPayRouteResolver {
     /// @return hookSpecifications The hook specifications returned by the chosen terminal preview.
     function previewBestPayRoute(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         uint256 amount,
@@ -45,6 +48,7 @@ interface IJBPayRouteResolver {
 
     /// @notice Preview a specific candidate pay route so callers can isolate revert-prone candidates with `try/catch`.
     /// @param router The router terminal whose preview helpers to use.
+    /// @param wrappedNativeToken The router's wrapped-native-token address.
     /// @param projectId The destination project that would receive the payment.
     /// @param tokenIn The token currently available to route.
     /// @param amount The amount of `tokenIn` to preview.
@@ -61,6 +65,7 @@ interface IJBPayRouteResolver {
     /// @return hookSpecifications The hook specifications returned by the terminal preview.
     function previewPayRouteForCandidate(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         uint256 amount,
@@ -83,6 +88,7 @@ interface IJBPayRouteResolver {
 
     /// @notice Determine what output token a project accepts for a given input token.
     /// @param router The router whose view helpers to use.
+    /// @param wrappedNativeToken The router's wrapped-native-token address.
     /// @param projectId The destination project to pay.
     /// @param tokenIn The input token to route.
     /// @param metadata Metadata forwarded into route-token resolution.
@@ -90,6 +96,7 @@ interface IJBPayRouteResolver {
     /// @return destTerminal The terminal that accepts `tokenOut`.
     function resolveTokenOut(
         IJBPayRoutePreviewer router,
+        address wrappedNativeToken,
         uint256 projectId,
         address tokenIn,
         bytes calldata metadata
@@ -102,6 +109,7 @@ interface IJBPayRouteResolver {
     /// @dev Called via `self.previewFallbackRoute(...)` so `try/catch` can absorb reverts from broken
     /// terminals or price feeds without bricking the entire best-route preview.
     /// @param routePreviewer The router terminal whose preview helpers to use for simulating the route.
+    /// @param wrappedNativeToken The router's wrapped-native-token address.
     /// @param destProjectId The project to pay through the fallback route.
     /// @param tokenIn The token the payer is sending.
     /// @param amountIn The amount of `tokenIn` to route.
@@ -116,6 +124,7 @@ interface IJBPayRouteResolver {
     /// @return hookSpecifications Any pay-hook specifications returned by the terminal preview.
     function previewFallbackRoute(
         IJBPayRoutePreviewer routePreviewer,
+        address wrappedNativeToken,
         uint256 destProjectId,
         address tokenIn,
         uint256 amountIn,