@bananapus/router-terminal-v6 0.0.28 → 0.0.30

package/RISKS.md

@@ -103,3 +103,11 @@ The router and resolver no longer contain registry-specific circular-resolution
 ### 8.6 V4 spot fallback is an accepted risk for programmatic integrations
 
 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.
+
+### 8.7 Credit cash-outs only work when calling the router terminal directly
+
+The credit-cashout path in `_acceptFundsFor` uses `holder = _msgSender()` — the direct caller — as the credit holder. This means credit cash-outs **do not work through the `JBRouterTerminalRegistry`**, because when the registry forwards a `pay()` call, `_msgSender()` inside the router terminal resolves to the registry's address, not the original user. The registry has no credits, so `transferCreditsFrom` would fail.
+
+This is intentional. The previous design used `_resolveOriginalPayer(sender)` to recover the original user from the registry's transient `originalPayer` storage. However, any contract implementing `IJBPayerTracker.originalPayer()` could spoof a victim's address and steal their credits (H-24). The fix uses the direct sender unconditionally for credit transfers, closing the spoofing vector at the cost of registry-mediated credit flows.
+
+Users who need to cash out credits through the router should call `JBRouterTerminal.pay()` directly with `cashOutSource` metadata, not through the registry.

package/package.json

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

package/src/JBRouterTerminal.sol

@@ -1052,9 +1052,9 @@ contract JBRouterTerminal is
 
             (uint256 sourceProjectId, uint256 creditAmount) = abi.decode(creditData, (uint256, uint256));
 
-            // Registry-style forwarders preserve the original payer in transient storage so credit transfers debit
-            // the actual holder rather than the intermediary.
-            address holder = _resolveOriginalPayer(sender);
+            // 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)));
@@ -1177,28 +1177,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;) {
-            // When a preferred token was supplied, check whether the route can already finish into it before taking
-            // another cashout hop.
-            if (preferredToken != address(0)) {
-                if (_hasSameRoutingAsset({tokenA: token, tokenB: preferredToken})) {
-                    // Ask the directory for the terminal that accepts the caller's preferred concrete asset.
-                    destTerminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: preferredToken});
-
-                    // If a real external terminal accepts that preferred asset, align into it and finish the route.
-                    if (address(destTerminal) != address(0)) {
-                        (token, amount) =
+            // 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, token, amount);
                     }
-                }
-            }
-            // Skip the destination check on the first iteration if we have a credit override.
-            else if (sourceProjectIdOverride == 0) {
-                // Ask the directory whether the destination already has a usable primary terminal for the current
-                // token.
-                destTerminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: token});
-                if (address(destTerminal) != address(0)) {
-                    return (destTerminal, token, amount);
+                    return (destTerminal, routeToken, amount);
                 }
             }
 
@@ -1884,6 +1874,33 @@ contract JBRouterTerminal is
         return super._contextSuffixLength();
     }
 
+    /// @notice Check whether a cashout route can complete at the current destination.
+    /// @dev Shared by _cashOutLoop and _previewCashOutLoop to keep destination logic in sync.
+    /// @param destProjectId The destination project.
+    /// @param token The current token in the route.
+    /// @param preferredToken The caller's preferred output token (or address(0) for none).
+    /// @return terminal The usable terminal if a route was found, or IJBTerminal(address(0)).
+    /// @return resultToken The token accepted by the terminal.
+    function _findRouteTerminal(
+        uint256 destProjectId,
+        address token,
+        address preferredToken
+    )
+        internal
+        view
+        returns (IJBTerminal terminal, address resultToken)
+    {
+        if (preferredToken != address(0)) {
+            if (_hasSameRoutingAsset({tokenA: token, tokenB: preferredToken})) {
+                terminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: preferredToken});
+                if (address(terminal) != address(0)) return (terminal, preferredToken);
+            }
+        } else {
+            terminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: token});
+            if (address(terminal) != address(0)) return (terminal, token);
+        }
+    }
+
     /// @notice Search Uniswap V3 and V4 for the best pool between two tokens.
     /// @dev Returns the pool with the highest liquidity across both protocols.
     /// @param normalizedTokenIn The input token (wrapped if native).
@@ -2499,26 +2516,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;) {
-            // When a preferred token was supplied, check whether the preview can already finish into it before
-            // previewing another cashout hop.
-            if (preferredToken != address(0)) {
-                if (_hasSameRoutingAsset({tokenA: token, tokenB: preferredToken})) {
-                    // Ask the directory for the terminal that accepts the caller's preferred concrete asset.
-                    destTerminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: preferredToken});
-
-                    // If a real external terminal accepts that preferred asset, the preview route is complete.
-                    if (address(destTerminal) != address(0)) return (destTerminal, preferredToken, amount);
-                }
-            }
-            // Only probe direct destination acceptance when there is no one-shot source override to consume first.
-            else if (sourceProjectIdOverride == 0) {
-                // Ask the directory whether the destination already has a primary terminal for the current token.
-                destTerminal = _usablePrimaryTerminalOf({projectId: destProjectId, token: token});
-
-                // If a real external terminal accepts this token, the preview route is complete and exact.
-                if (address(destTerminal) != address(0)) {
-                    return (destTerminal, token, amount);
-                }
+            // 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);
             }
 
             // Use the override once when present; otherwise infer the source project from the current JB token.

package/test/RouterTerminalCreditCashout.t.sol

@@ -405,8 +405,9 @@ contract CreditCashoutSpoofingIntermediary is IJBPayerTracker {
             assertEq(decodedAmount, creditAmount, "decoded amount should match");
         }
 
-        /// @notice Credit cashouts routed through a payer tracker should debit the tracked original payer.
-        function test_creditCashout_usesTrackedOriginalPayerAsHolder() public {
+        /// @notice After H-24 fix: credit cashouts through a payer tracker debit the intermediary (msg.sender),
+        /// not the spoofed originalPayer. This prevents credit theft.
+        function test_creditCashout_debitsIntermediaryNotSpoofedPayer() public {
             address victim = makeAddr("victim");
             address controller = makeAddr("controller");
             uint256 destProjectId = 1;
@@ -429,17 +430,21 @@ contract CreditCashoutSpoofingIntermediary is IJBPayerTracker {
                 abi.encodeCall(IJBDirectory.controllerOf, (sourceProjectId)),
                 abi.encode(controller)
             );
+
+            // After fix: transferCreditsFrom is called with the intermediary as holder, NOT the victim.
             vm.mockCall(
                 controller,
                 abi.encodeCall(
-                    IJBController.transferCreditsFrom, (victim, sourceProjectId, address(routerTerminal), creditAmount)
+                    IJBController.transferCreditsFrom,
+                    (address(intermediary), sourceProjectId, address(routerTerminal), creditAmount)
                 ),
                 abi.encode()
             );
             vm.expectCall(
                 controller,
                 abi.encodeCall(
-                    IJBController.transferCreditsFrom, (victim, sourceProjectId, address(routerTerminal), creditAmount)
+                    IJBController.transferCreditsFrom,
+                    (address(intermediary), sourceProjectId, address(routerTerminal), creditAmount)
                 )
             );
 
@@ -720,7 +725,22 @@ contract CreditCashoutSpoofingIntermediary is IJBPayerTracker {
             vm.mockCall(
                 mockCashOutTerminal,
                 abi.encodeWithSelector(IJBCashOutTerminal.previewCashOutFrom.selector),
-                abi.encode(uint256(0), new JBCashOutHookSpecification[](0))
+                abi.encode(
+                    JBRuleset({
+                        cycleNumber: 1,
+                        id: 1,
+                        basedOnId: 0,
+                        start: 0,
+                        duration: 0,
+                        weight: 0,
+                        weightCutPercent: 0,
+                        approvalHook: IJBRulesetApprovalHook(address(0)),
+                        metadata: 0
+                    }),
+                    uint256(0),
+                    uint256(0),
+                    new JBCashOutHookSpecification[](0)
+                )
             );
 
             vm.mockCall(

package/test/audit/CreditCashoutPreferredTokenBypass.t.sol

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+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 {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+
+import {JBRouterTerminal} from "../../src/JBRouterTerminal.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+
+/// @title M26_CreditCashoutPreferredTokenBypass
+/// @notice Before the fix, when sourceProjectIdOverride != 0 and preferredToken matched the
+///         current token, the _cashOutLoop would short-circuit on the first iteration — returning
+///         without cashing out. This test verifies the fix: the forced first cashout must happen.
+contract M26_CreditCashoutPreferredTokenBypass is Test {
+    JBRouterTerminal routerTerminal;
+
+    IJBDirectory mockDirectory;
+    IJBTokens mockTokens;
+
+    address payer = makeAddr("payer");
+    address controller = makeAddr("controller");
+    address mockDestTerminal = makeAddr("destTerminal");
+    address mockCashOutTerminal = makeAddr("cashOutTerminal");
+
+    uint256 destProjectId = 1;
+    uint256 sourceProjectId = 2;
+    uint256 creditAmount = 100e18;
+
+    function setUp() public {
+        mockDirectory = IJBDirectory(makeAddr("mockDirectory"));
+        vm.etch(address(mockDirectory), hex"00");
+        mockTokens = IJBTokens(makeAddr("mockTokens"));
+        vm.etch(address(mockTokens), hex"00");
+        vm.etch(controller, hex"00");
+        vm.etch(mockDestTerminal, hex"00");
+        vm.etch(mockCashOutTerminal, hex"00");
+
+        IPermit2 mockPermit2 = IPermit2(makeAddr("mockPermit2"));
+        vm.etch(address(mockPermit2), hex"00");
+        IWETH9 mockWeth = IWETH9(makeAddr("mockWeth"));
+        vm.etch(address(mockWeth), hex"00");
+        IUniswapV3Factory mockFactory = IUniswapV3Factory(makeAddr("mockFactory"));
+        vm.etch(address(mockFactory), hex"00");
+        IPoolManager mockPoolManager = IPoolManager(makeAddr("mockPoolManager"));
+        vm.etch(address(mockPoolManager), hex"00");
+
+        routerTerminal = new JBRouterTerminal(
+            mockDirectory,
+            mockTokens,
+            mockPermit2,
+            mockWeth,
+            mockFactory,
+            mockPoolManager,
+            address(0),
+            address(0),
+            address(0)
+        );
+    }
+
+    /// @notice With the fix, credit cashout with sourceProjectIdOverride and a preferred token
+    ///         that matches the token must still perform at least one cashout hop.
+    function test_creditCashout_forcedHopWithPreferredToken() public {
+        // Build metadata: cashOutSource with sourceProjectId + creditAmount,
+        // and cashOutPreferredToken with NATIVE_TOKEN.
+        bytes memory metadata;
+        {
+            bytes4 cashOutSourceId = JBMetadataResolver.getId("cashOutSource", address(routerTerminal));
+            metadata = JBMetadataResolver.addToMetadata("", cashOutSourceId, abi.encode(sourceProjectId, creditAmount));
+
+            bytes4 preferredTokenId = JBMetadataResolver.getId("cashOutPreferredToken", address(routerTerminal));
+            metadata =
+                JBMetadataResolver.addToMetadata(metadata, preferredTokenId, abi.encode(JBConstants.NATIVE_TOKEN));
+        }
+
+        // Mock: controller lookup for sourceProjectId.
+        vm.mockCall(
+            address(mockDirectory), abi.encodeCall(IJBDirectory.controllerOf, (sourceProjectId)), abi.encode(controller)
+        );
+
+        // Mock: controller.transferCreditsFrom.
+        vm.mockCall(
+            controller,
+            abi.encodeCall(
+                IJBController.transferCreditsFrom, (payer, sourceProjectId, address(routerTerminal), creditAmount)
+            ),
+            abi.encode()
+        );
+
+        // Dest project accepts NATIVE_TOKEN.
+        vm.mockCall(
+            address(mockDirectory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, JBConstants.NATIVE_TOKEN)),
+            abi.encode(mockDestTerminal)
+        );
+
+        // Source project's terminal list.
+        {
+            IJBTerminal[] memory sourceTerminals = new IJBTerminal[](1);
+            sourceTerminals[0] = IJBTerminal(mockCashOutTerminal);
+            vm.mockCall(
+                address(mockDirectory),
+                abi.encodeCall(IJBDirectory.terminalsOf, (sourceProjectId)),
+                abi.encode(sourceTerminals)
+            );
+        }
+
+        // Mock supportsInterface for IJBCashOutTerminal.
+        vm.mockCall(
+            mockCashOutTerminal,
+            abi.encodeCall(IERC165.supportsInterface, (type(IJBCashOutTerminal).interfaceId)),
+            abi.encode(true)
+        );
+
+        // Accounting context: source project terminal accepts NATIVE_TOKEN.
+        {
+            JBAccountingContext[] memory contexts = new JBAccountingContext[](1);
+            contexts[0] = JBAccountingContext({
+                token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            });
+            vm.mockCall(
+                mockCashOutTerminal,
+                abi.encodeCall(IJBTerminal.accountingContextsOf, (sourceProjectId)),
+                abi.encode(contexts)
+            );
+        }
+
+        // Mock cashOutTokensOf: returns 60 ETH reclaimed.
+        vm.mockCall(
+            mockCashOutTerminal,
+            abi.encodeWithSelector(IJBCashOutTerminal.cashOutTokensOf.selector),
+            abi.encode(uint256(60e18))
+        );
+
+        // The cashout terminal sends ETH to the router.
+        vm.deal(address(routerTerminal), 60e18);
+
+        // Mock dest terminal pay.
+        vm.mockCall(mockDestTerminal, abi.encodeWithSelector(IJBTerminal.pay.selector), abi.encode(uint256(500)));
+
+        // The key assertion: cashOutTokensOf MUST be called on the source terminal.
+        // Before the fix, the preferred-token short-circuit would skip this call entirely.
+        vm.expectCall(mockCashOutTerminal, abi.encodeWithSelector(IJBCashOutTerminal.cashOutTokensOf.selector));
+
+        vm.prank(payer);
+        uint256 result = routerTerminal.pay(destProjectId, JBConstants.NATIVE_TOKEN, 0, payer, 0, "", metadata);
+
+        assertEq(result, 500, "pay should return dest terminal token count");
+    }
+}

package/test/audit/CreditCashoutSpoofedPayer.t.sol

@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+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 {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+
+import {JBRouterTerminal} from "../../src/JBRouterTerminal.sol";
+import {IJBPayerTracker} from "../../src/interfaces/IJBPayerTracker.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+
+/// @notice Attacker contract that spoofs originalPayer() to point at a victim.
+contract AttackerSpoofingPayer is IJBPayerTracker {
+    address public override originalPayer;
+
+    constructor(address victim) {
+        originalPayer = victim;
+    }
+
+    function attackViaPay(
+        JBRouterTerminal router,
+        uint256 projectId,
+        bytes calldata metadata
+    )
+        external
+        returns (uint256)
+    {
+        return router.pay(projectId, JBConstants.NATIVE_TOKEN, 0, address(this), 0, "", metadata);
+    }
+}
+
+    /// @notice H-24: Verify that spoofing originalPayer() cannot steal another user's credits.
+    contract CreditCashoutSpoofedPayerTest is Test {
+        JBRouterTerminal routerTerminal;
+
+        IJBDirectory mockDirectory;
+        IJBPermissions mockPermissions;
+        IJBTokens mockTokens;
+        IPermit2 mockPermit2;
+        IWETH9 mockWeth;
+        IUniswapV3Factory mockFactory;
+        IPoolManager mockPoolManager;
+
+        function setUp() public {
+            mockDirectory = IJBDirectory(makeAddr("mockDirectory"));
+            vm.etch(address(mockDirectory), hex"00");
+            mockPermissions = IJBPermissions(makeAddr("mockPermissions"));
+            vm.etch(address(mockPermissions), hex"00");
+            mockTokens = IJBTokens(makeAddr("mockTokens"));
+            vm.etch(address(mockTokens), hex"00");
+            mockPermit2 = IPermit2(makeAddr("mockPermit2"));
+            vm.etch(address(mockPermit2), hex"00");
+            mockWeth = IWETH9(makeAddr("mockWeth"));
+            vm.etch(address(mockWeth), hex"00");
+            mockFactory = IUniswapV3Factory(makeAddr("mockFactory"));
+            vm.etch(address(mockFactory), hex"00");
+            mockPoolManager = IPoolManager(makeAddr("mockPoolManager"));
+            vm.etch(address(mockPoolManager), hex"00");
+
+            routerTerminal = new JBRouterTerminal(
+                mockDirectory,
+                mockTokens,
+                mockPermit2,
+                mockWeth,
+                mockFactory,
+                mockPoolManager,
+                address(0),
+                address(0),
+                address(0)
+            );
+        }
+
+        /// @notice An attacker contract spoofing originalPayer() should have its own credits debited, not the victim's.
+        function test_spoofedOriginalPayer_debitsAttackerNotVictim() public {
+            address victim = makeAddr("victim");
+            address controller = makeAddr("controller");
+            uint256 destProjectId = 1;
+            uint256 sourceProjectId = 2;
+            uint256 creditAmount = 100e18;
+            address mockDestTerminal = makeAddr("destTerminal");
+            address mockCashOutTerminal = makeAddr("cashOutTerminal");
+            vm.etch(controller, hex"00");
+            vm.etch(mockDestTerminal, hex"00");
+            vm.etch(mockCashOutTerminal, hex"00");
+
+            // Attacker contract spoofs originalPayer() to return victim's address.
+            AttackerSpoofingPayer attacker = new AttackerSpoofingPayer(victim);
+
+            bytes4 metadataId = JBMetadataResolver.getId("cashOutSource", address(routerTerminal));
+            bytes memory metadata =
+                JBMetadataResolver.addToMetadata("", metadataId, abi.encode(sourceProjectId, creditAmount));
+
+            vm.mockCall(
+                address(mockDirectory),
+                abi.encodeCall(IJBDirectory.controllerOf, (sourceProjectId)),
+                abi.encode(controller)
+            );
+
+            // The key assertion: transferCreditsFrom is called with the ATTACKER as holder, NOT the victim.
+            vm.mockCall(
+                controller,
+                abi.encodeCall(
+                    IJBController.transferCreditsFrom,
+                    (address(attacker), sourceProjectId, address(routerTerminal), creditAmount)
+                ),
+                abi.encode()
+            );
+            vm.expectCall(
+                controller,
+                abi.encodeCall(
+                    IJBController.transferCreditsFrom,
+                    (address(attacker), sourceProjectId, address(routerTerminal), creditAmount)
+                )
+            );
+
+            vm.mockCall(
+                address(mockDirectory),
+                abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, JBConstants.NATIVE_TOKEN)),
+                abi.encode(mockDestTerminal)
+            );
+
+            IJBTerminal[] memory sourceTerminals = new IJBTerminal[](1);
+            sourceTerminals[0] = IJBTerminal(mockCashOutTerminal);
+            vm.mockCall(
+                address(mockDirectory),
+                abi.encodeCall(IJBDirectory.terminalsOf, (sourceProjectId)),
+                abi.encode(sourceTerminals)
+            );
+
+            vm.mockCall(
+                mockCashOutTerminal,
+                abi.encodeCall(IERC165.supportsInterface, (type(IJBCashOutTerminal).interfaceId)),
+                abi.encode(true)
+            );
+
+            JBAccountingContext[] memory contexts = new JBAccountingContext[](1);
+            contexts[0] = JBAccountingContext({
+                token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            });
+            vm.mockCall(
+                mockCashOutTerminal,
+                abi.encodeCall(IJBTerminal.accountingContextsOf, (sourceProjectId)),
+                abi.encode(contexts)
+            );
+
+            vm.mockCall(
+                mockCashOutTerminal,
+                abi.encodeWithSelector(IJBCashOutTerminal.cashOutTokensOf.selector),
+                abi.encode(uint256(60e18))
+            );
+            vm.deal(address(routerTerminal), 60e18);
+            vm.mockCall(mockDestTerminal, abi.encodeWithSelector(IJBTerminal.pay.selector), abi.encode(uint256(500)));
+
+            attacker.attackViaPay(routerTerminal, destProjectId, metadata);
+        }
+
+        /// @notice Direct EOA credit cashouts still work — the holder is the EOA itself.
+        function test_directCreditCashout_stillWorks() public {
+            address payer = makeAddr("payer");
+            address controller = makeAddr("controller");
+            uint256 destProjectId = 1;
+            uint256 sourceProjectId = 2;
+            uint256 creditAmount = 50e18;
+            address mockDestTerminal = makeAddr("destTerminal");
+            address mockCashOutTerminal = makeAddr("cashOutTerminal");
+            vm.etch(controller, hex"00");
+            vm.etch(mockDestTerminal, hex"00");
+            vm.etch(mockCashOutTerminal, hex"00");
+
+            bytes4 metadataId = JBMetadataResolver.getId("cashOutSource", address(routerTerminal));
+            bytes memory metadata =
+                JBMetadataResolver.addToMetadata("", metadataId, abi.encode(sourceProjectId, creditAmount));
+
+            vm.mockCall(
+                address(mockDirectory),
+                abi.encodeCall(IJBDirectory.controllerOf, (sourceProjectId)),
+                abi.encode(controller)
+            );
+
+            // EOA payer is the holder — direct call, no intermediary.
+            vm.mockCall(
+                controller,
+                abi.encodeCall(
+                    IJBController.transferCreditsFrom, (payer, sourceProjectId, address(routerTerminal), creditAmount)
+                ),
+                abi.encode()
+            );
+            vm.expectCall(
+                controller,
+                abi.encodeCall(
+                    IJBController.transferCreditsFrom, (payer, sourceProjectId, address(routerTerminal), creditAmount)
+                )
+            );
+
+            vm.mockCall(
+                address(mockDirectory),
+                abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, JBConstants.NATIVE_TOKEN)),
+                abi.encode(mockDestTerminal)
+            );
+
+            IJBTerminal[] memory sourceTerminals = new IJBTerminal[](1);
+            sourceTerminals[0] = IJBTerminal(mockCashOutTerminal);
+            vm.mockCall(
+                address(mockDirectory),
+                abi.encodeCall(IJBDirectory.terminalsOf, (sourceProjectId)),
+                abi.encode(sourceTerminals)
+            );
+
+            vm.mockCall(
+                mockCashOutTerminal,
+                abi.encodeCall(IERC165.supportsInterface, (type(IJBCashOutTerminal).interfaceId)),
+                abi.encode(true)
+            );
+
+            JBAccountingContext[] memory contexts = new JBAccountingContext[](1);
+            contexts[0] = JBAccountingContext({
+                token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            });
+            vm.mockCall(
+                mockCashOutTerminal,
+                abi.encodeCall(IJBTerminal.accountingContextsOf, (sourceProjectId)),
+                abi.encode(contexts)
+            );
+
+            vm.mockCall(
+                mockCashOutTerminal,
+                abi.encodeWithSelector(IJBCashOutTerminal.cashOutTokensOf.selector),
+                abi.encode(uint256(30e18))
+            );
+            vm.deal(address(routerTerminal), 30e18);
+            vm.mockCall(mockDestTerminal, abi.encodeWithSelector(IJBTerminal.pay.selector), abi.encode(uint256(200)));
+
+            vm.prank(payer);
+            uint256 result = routerTerminal.pay(destProjectId, JBConstants.NATIVE_TOKEN, 0, payer, 0, "", metadata);
+            assertEq(result, 200);
+        }
+    }

package/test/audit/PreviewCashOutShortcircuitDivergence.t.sol

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+import {IJBCashOutTerminal} from "@bananapus/core-v6/src/interfaces/IJBCashOutTerminal.sol";
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBToken} from "@bananapus/core-v6/src/interfaces/IJBToken.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
+import {JBCashOutHookSpecification} from "@bananapus/core-v6/src/structs/JBCashOutHookSpecification.sol";
+import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
+import {IJBRulesetApprovalHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetApprovalHook.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+
+import {JBRouterTerminal} from "../../src/JBRouterTerminal.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+
+/// @title M30_PreviewCashOutShortcircuitDivergence
+/// @notice Before the fix, `_previewCashOutLoop` could short-circuit on the preferred-token check even when
+///         `sourceProjectIdOverride != 0`, skipping the forced first cashout hop. The execution path
+///         (`_cashOutLoop`) correctly gates that short-circuit behind `sourceProjectIdOverride == 0`.
+///         This test verifies that the preview now mirrors execution: the forced hop is taken before any
+///         preferred-token early return.
+contract M30_PreviewCashOutShortcircuitDivergence is Test {
+    JBRouterTerminal internal router;
+
+    IJBDirectory internal mockDirectory;
+    IJBTokens internal mockTokens;
+
+    address internal mockCashOutTerminal = makeAddr("cashOutTerminal");
+    address internal mockDestTerminal = makeAddr("destTerminal");
+
+    uint256 internal destProjectId = 1;
+    uint256 internal sourceProjectId = 2;
+    uint256 internal cashOutAmount = 100e18;
+    uint256 internal reclaimAmount = 60e18;
+
+    function setUp() public {
+        mockDirectory = IJBDirectory(makeAddr("directory"));
+        mockTokens = IJBTokens(makeAddr("tokens"));
+
+        vm.etch(address(mockDirectory), hex"00");
+        vm.etch(address(mockTokens), hex"00");
+        vm.etch(mockCashOutTerminal, hex"00");
+        vm.etch(mockDestTerminal, hex"00");
+
+        IPermit2 mockPermit2 = IPermit2(makeAddr("permit2"));
+        vm.etch(address(mockPermit2), hex"00");
+        IWETH9 mockWeth = IWETH9(makeAddr("weth"));
+        vm.etch(address(mockWeth), hex"00");
+        IUniswapV3Factory mockFactory = IUniswapV3Factory(makeAddr("factory"));
+        vm.etch(address(mockFactory), hex"00");
+        IPoolManager mockPoolManager = IPoolManager(makeAddr("poolManager"));
+        vm.etch(address(mockPoolManager), hex"00");
+
+        router = new JBRouterTerminal({
+            directory: mockDirectory,
+            tokens: mockTokens,
+            permit2: mockPermit2,
+            weth: mockWeth,
+            factory: mockFactory,
+            poolManager: mockPoolManager,
+            buybackHook: address(0),
+            univ4Hook: address(0),
+            trustedForwarder: address(0)
+        });
+
+        // --- Mock: source project terminal list ---
+        IJBTerminal[] memory sourceTerminals = new IJBTerminal[](1);
+        sourceTerminals[0] = IJBTerminal(mockCashOutTerminal);
+        vm.mockCall(
+            address(mockDirectory),
+            abi.encodeCall(IJBDirectory.terminalsOf, (sourceProjectId)),
+            abi.encode(sourceTerminals)
+        );
+
+        // --- Mock: IJBCashOutTerminal support ---
+        vm.mockCall(
+            mockCashOutTerminal,
+            abi.encodeCall(IERC165.supportsInterface, (type(IJBCashOutTerminal).interfaceId)),
+            abi.encode(true)
+        );
+
+        // --- Mock: source terminal accounting contexts (accepts NATIVE_TOKEN) ---
+        JBAccountingContext[] memory contexts = new JBAccountingContext[](1);
+        contexts[0] = JBAccountingContext({
+            token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+        });
+        vm.mockCall(
+            mockCashOutTerminal,
+            abi.encodeCall(IJBTerminal.accountingContextsOf, (sourceProjectId)),
+            abi.encode(contexts)
+        );
+
+        // --- Mock: dest project accepts NATIVE_TOKEN via destTerminal ---
+        vm.mockCall(
+            address(mockDirectory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, JBConstants.NATIVE_TOKEN)),
+            abi.encode(mockDestTerminal)
+        );
+
+        // --- Mock: previewCashOutFrom returns reclaimAmount ---
+        JBRuleset memory ruleset = JBRuleset({
+            cycleNumber: 1,
+            id: 1,
+            basedOnId: 0,
+            start: 0,
+            duration: 0,
+            weight: 0,
+            weightCutPercent: 0,
+            approvalHook: IJBRulesetApprovalHook(address(0)),
+            metadata: 0
+        });
+        JBCashOutHookSpecification[] memory emptyHooks = new JBCashOutHookSpecification[](0);
+        vm.mockCall(
+            mockCashOutTerminal,
+            abi.encodeWithSelector(IJBCashOutTerminal.previewCashOutFrom.selector),
+            abi.encode(ruleset, reclaimAmount, uint256(0), emptyHooks)
+        );
+
+        // --- Mock: tokens.projectIdOf returns 0 for NATIVE_TOKEN (not a JB project token) ---
+        vm.mockCall(
+            address(mockTokens),
+            abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(JBConstants.NATIVE_TOKEN))),
+            abi.encode(uint256(0))
+        );
+    }
+
+    /// @notice When sourceProjectIdOverride is set and the preferred token matches the current token, the preview
+    ///         must NOT short-circuit. It must take the forced cashout hop, then resolve the destination terminal.
+    function test_previewDoesNotShortcircuitWithSourceOverride() public view {
+        // The token being cashed out is a JB project token (represented by address(0xABC) for this test).
+        // The preferred token is NATIVE_TOKEN, and the source terminal reclaims NATIVE_TOKEN.
+        // With sourceProjectIdOverride != 0, the preview must NOT short-circuit even though preferredToken
+        // matches the reclaim token. It must perform the hop first.
+
+        // Call previewCashOutLoopOf with:
+        //   - token = NATIVE_TOKEN (would match preferredToken immediately without the fix)
+        //   - sourceProjectIdOverride = sourceProjectId (forces a cashout hop)
+        //   - preferredToken = NATIVE_TOKEN
+        (IJBTerminal destTerminal, address finalToken, uint256 finalAmount) = router.previewCashOutLoopOf({
+            destProjectId: destProjectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: cashOutAmount,
+            sourceProjectIdOverride: sourceProjectId,
+            metadata: "",
+            preferredToken: JBConstants.NATIVE_TOKEN
+        });
+
+        // The preview must have performed the cashout hop, so the final amount should be the reclaim amount,
+        // not the original cashOutAmount.
+        assertEq(finalAmount, reclaimAmount, "preview must perform the forced cashout hop, not short-circuit");
+        assertEq(finalToken, JBConstants.NATIVE_TOKEN, "final token should be NATIVE_TOKEN after the hop");
+        assertEq(address(destTerminal), mockDestTerminal, "preview should resolve the dest terminal after the hop");
+    }
+
+    /// @notice When sourceProjectIdOverride is 0 and the preferred token matches, the preview SHOULD
+    ///         short-circuit immediately (no cashout hop needed).
+    function test_previewShortcircuitsWithoutSourceOverride() public view {
+        // With sourceProjectIdOverride == 0, the preferred-token check should fire immediately.
+        (IJBTerminal destTerminal, address finalToken, uint256 finalAmount) = router.previewCashOutLoopOf({
+            destProjectId: destProjectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: cashOutAmount,
+            sourceProjectIdOverride: 0,
+            metadata: "",
+            preferredToken: JBConstants.NATIVE_TOKEN
+        });
+
+        // The preview should short-circuit: amount unchanged, terminal resolved directly.
+        assertEq(finalAmount, cashOutAmount, "preview should short-circuit and return original amount");
+        assertEq(finalToken, JBConstants.NATIVE_TOKEN, "final token should be the preferred token");
+        assertEq(address(destTerminal), mockDestTerminal, "dest terminal should be resolved immediately");
+    }
+
+    /// @notice After sourceProjectIdOverride is consumed on the first hop, the second iteration should
+    ///         be able to short-circuit via the preferred-token check.
+    function test_previewShortcircuitsAfterOverrideConsumed() public view {
+        // Set up a scenario where the first hop reclaims NATIVE_TOKEN, then the second iteration
+        // should short-circuit because sourceProjectIdOverride is now 0 and preferredToken matches.
+        // This is exactly the same as test_previewDoesNotShortcircuitWithSourceOverride — the forced
+        // hop happens on iteration 0, then iteration 1 should short-circuit because the reclaimed
+        // NATIVE_TOKEN matches the preferred NATIVE_TOKEN and sourceProjectIdOverride is now 0.
+
+        (IJBTerminal destTerminal, address finalToken, uint256 finalAmount) = router.previewCashOutLoopOf({
+            destProjectId: destProjectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: cashOutAmount,
+            sourceProjectIdOverride: sourceProjectId,
+            metadata: "",
+            preferredToken: JBConstants.NATIVE_TOKEN
+        });
+
+        // After the forced hop (iteration 0), the override is consumed. On iteration 1, the reclaimed
+        // NATIVE_TOKEN matches the preferred token, so the loop short-circuits with the reclaim amount.
+        assertEq(finalAmount, reclaimAmount, "second iteration should short-circuit after override consumed");
+        assertEq(address(destTerminal), mockDestTerminal, "should resolve dest terminal on second iteration");
+        assertEq(finalToken, JBConstants.NATIVE_TOKEN, "final token should be the preferred token");
+    }
+}