@bananapus/router-terminal-v6 0.0.31 → 0.0.33

package/RISKS.md

@@ -17,7 +17,7 @@ Pool discovery ranks candidates by instantaneous liquidity, so an attacker could
 When a user provides `quoteForSwap` metadata, the quote may not match the auto-selected output token. Frontends should set `quoteForSwap` per the expected output token.
 
 **Multi-hop cashout slippage cleared after first hop.** *(Minor)*
-Only the final output matters; the outer function enforces end-to-end minimum via `minReclaimed`. Intermediate per-hop slippage checks are intentionally omitted.
+Only the final output matters; the outer function enforces end-to-end minimum via `minReclaimed`. Intermediate per-hop slippage checks are intentionally omitted. Maximum 20 recursive cashout iterations allowed (`_MAX_CASHOUT_ITERATIONS`); beyond that the operation reverts.
 
 **Zero oracle quote disables swap protection.** *(Minor)*
 When the oracle returns zero (no liquidity), slippage tolerance becomes zero. The swap would fail anyway due to lack of liquidity, so this has no practical impact.
@@ -35,6 +35,11 @@ When payments flow through the registry, credits accrue to the registry address,
 **Forwarder claim disables receipt check.** *(Minor)*
 Forwarding terminals registered by project owners are trusted to handle receipts correctly, so receipt validation is skipped for these callers.
 
+## Token Compatibility Risks
+
+**Fee-on-transfer (FOT) tokens not supported for routed payments.** *(Medium)*
+The `pay()` flow does not enforce an ERC-20 receipt check (balance-delta validation) on the destination terminal. This was intentionally removed because pay hooks attached to the destination terminal can legitimately consume tokens during `pay()`, making a balance-delta check produce false reverts for any project with active pay hooks. As a consequence, fee-on-transfer tokens will silently lose value during routing — the terminal receives fewer tokens than `amount` but the router cannot detect this. Projects using FOT tokens should route payments directly to the terminal, bypassing the router. The `addToBalanceOf()` flow retains receipt enforcement since it has no hooks.
+
 ## Minor Configuration Risks
 
 **Unbounded quadratic candidate enumeration.** *(Minor)*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,9 +17,9 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-router-terminal-v6'"
   },
   "dependencies": {
-    "@bananapus/buyback-hook-v6": "^0.0.27",
-    "@bananapus/core-v6": "^0.0.34",
-    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@bananapus/buyback-hook-v6": "^0.0.30",
+    "@bananapus/core-v6": "^0.0.36",
+    "@bananapus/permission-ids-v6": "^0.0.19",
     "@openzeppelin/contracts": "^5.6.1",
     "@uniswap/permit2": "github:Uniswap/permit2",
     "@uniswap/v3-core": "github:Uniswap/v3-core#0.8",

package/src/JBPayRouteResolver.sol

@@ -10,7 +10,7 @@ import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingCo
 import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
 
-import {IJBForwardingTerminal} from "./interfaces/IJBForwardingTerminal.sol";
+import {JBForwardingCheck} from "./libraries/JBForwardingCheck.sol";
 import {IJBPayRoutePreviewer} from "./interfaces/IJBPayRoutePreviewer.sol";
 import {IJBPayRouteResolver} from "./interfaces/IJBPayRouteResolver.sol";
 import {IWETH9} from "./interfaces/IWETH9.sol";
@@ -274,9 +274,23 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
             }
 
             // Decode only the minimum token-count commitments needed to score the buyback-enhanced preview.
-            (,,,,,,,,, uint256 minimumBeneficiaryTokenCount, uint256 minimumReservedTokenCount,) = abi.decode(
+            (,,,,,,,,,, uint256 minimumBeneficiaryTokenCount, uint256 minimumReservedTokenCount,) = abi.decode(
                 specification.metadata,
-                (bool, uint256, uint256, bool, address, uint256, int24, uint128, bytes32, uint256, uint256, uint256)
+                (
+                    bool,
+                    uint256,
+                    uint256,
+                    bool,
+                    address,
+                    uint256,
+                    uint256,
+                    int24,
+                    uint128,
+                    bytes32,
+                    uint256,
+                    uint256,
+                    uint256
+                )
             );
 
             // Keep whichever decoded hook commitment implies the stronger user-visible preview outcome.
@@ -326,7 +340,9 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         return _normalizedTokenOf(tokenA) == _normalizedTokenOf(tokenB);
     }
 
-    /// @notice Whether previewing through a terminal would immediately cycle back into the router.
+    /// @notice Whether previewing through a terminal would cycle back into the router.
+    /// @dev Delegates to `JBForwardingCheck.isCircularTerminal` — shared with `JBRouterTerminal` so that
+    /// preview and execution use identical cycle-detection logic.
     /// @param router The router whose preview path is being evaluated.
     /// @param projectId The project whose forwarding terminal would be resolved.
     /// @param terminal The terminal that would receive the previewed route.
@@ -340,30 +356,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         view
         returns (bool isCircular)
     {
-        // Follow the forwarding chain up to 5 hops to detect circular routes back to the router.
-        // A bounded loop prevents infinite gas consumption from longer chains while catching realistic cycles.
-        IJBTerminal current = terminal;
-        for (uint256 i; i < 5; i++) {
-            // Treat routes back to the router as circular.
-            if (address(current) == address(router)) return true;
-
-            // Probe via staticcall so plain terminals degrade cleanly.
-            // slither-disable-next-line calls-loop
-            (bool success, bytes memory data) =
-                address(current).staticcall(abi.encodeCall(IJBForwardingTerminal.terminalOf, (projectId)));
-
-            // Non-forwarding terminals (call fails or returns zero) end the chain — not circular.
-            if (!success || data.length < 32) return false;
-            IJBTerminal forwardingTarget = abi.decode(data, (IJBTerminal));
-            if (address(forwardingTarget) == address(0)) return false;
-
-            // Follow the forwarding chain one more hop.
-            current = forwardingTarget;
-        }
-
-        // If we followed 5 hops without finding a non-forwarding terminal or the router,
-        // treat this as a suspicious deep chain and mark it as circular to be safe.
-        return true;
+        return JBForwardingCheck.isCircularTerminal({target: address(router), projectId: projectId, terminal: terminal});
     }
 
     /// @notice Normalize a token into the form the router uses for routing comparisons.

package/src/JBRouterTerminal.sol

@@ -44,6 +44,7 @@ import {IJBPayRoutePreviewer} from "./interfaces/IJBPayRoutePreviewer.sol";
 import {IJBPayRouteResolver} from "./interfaces/IJBPayRouteResolver.sol";
 import {IJBRouterTerminal} from "./interfaces/IJBRouterTerminal.sol";
 import {IWETH9} from "./interfaces/IWETH9.sol";
+import {JBForwardingCheck} from "./libraries/JBForwardingCheck.sol";
 import {JBSwapLib} from "./libraries/JBSwapLib.sol";
 import {JBPayRouteResolver} from "./JBPayRouteResolver.sol";
 import {CashOutPathCandidates} from "./structs/CashOutPathCandidates.sol";
@@ -356,11 +357,6 @@ contract JBRouterTerminal is
         // native.
         uint256 payValue = _beforeTransferFor({to: address(destTerminal), token: token, amount: amount});
 
-        // Snapshot the destination terminal's ERC20 balance and forwarding status for receipt enforcement.
-        // Combines both checks into one call to avoid duplicate _isForwardingTerminal probes.
-        (uint256 terminalReceiptBaseline, bool isForwarding) =
-            _terminalReceiptBaselineOf({terminal: destTerminal, token: token, projectId: projectId});
-
         // Execute the final payment on the destination terminal and bubble back the beneficiary token count it
         // returned.
         beneficiaryTokenCount = destTerminal.pay{value: payValue}({
@@ -375,14 +371,11 @@ contract JBRouterTerminal is
 
         _afterTransferFor({destTerminal: destTerminal, token: token});
 
-        // Reject fee-on-transfer or otherwise lossy ERC20 terminal pulls on the final forwarded hop.
-        _enforceStandardTerminalReceipt({
-            terminal: destTerminal,
-            token: token,
-            expectedAmount: amount,
-            receiptBaseline: terminalReceiptBaseline,
-            isForwarding: isForwarding
-        });
+        // NOTE: No ERC-20 receipt enforcement here (unlike addToBalanceOf).
+        // Pay hooks attached to the destination terminal may legitimately consume tokens during
+        // pay(), making a balance-delta check produce false reverts. Fee-on-transfer (FOT) tokens
+        // are therefore NOT supported for routed payments — the terminal will receive fewer tokens
+        // than `amount` but the router cannot detect or prevent this. See RISKS.md for details.
     }
 
     /// @notice The Uniswap v3 pool callback where the token transfer is expected to happen.
@@ -436,7 +429,7 @@ contract JBRouterTerminal is
             params: SwapParams({
                 zeroForOne: zeroForOne, amountSpecified: amountSpecified, sqrtPriceLimitX96: sqrtPriceLimitX96
             }),
-            hookData: ""
+            hookData: address(key.hooks) != address(0) ? abi.encode(minAmountOut) : bytes("")
         });
 
         // Determine input/output amounts from the delta.
@@ -994,13 +987,16 @@ contract JBRouterTerminal is
         terminal = DIRECTORY.primaryTerminalOf({projectId: projectId, token: token});
 
         // Drop terminals that would route straight back into the router (circular).
-        if (address(terminal) == address(0) || _isCircularTerminal(terminal)) {
+        if (
+            address(terminal) == address(0)
+                || JBForwardingCheck.isCircularTerminal({
+                    target: address(this), projectId: projectId, terminal: terminal
+                })
+        ) {
             return IJBTerminal(address(0));
         }
 
         // Check if the terminal is a forwarding layer that routes back into this router.
-        // Uses the same low-level staticcall pattern as _isForwardingTerminal — non-forwarding terminals degrade
-        // cleanly into a no-op (success=false or empty data).
         // slither-disable-next-line calls-loop
         (bool ok, bytes memory data) =
             address(terminal).staticcall(abi.encodeCall(IJBForwardingTerminal.terminalOf, (projectId)));
@@ -1031,13 +1027,6 @@ contract JBRouterTerminal is
         }
     }
 
-    /// @notice Whether routing through a terminal would cycle back into the router.
-    /// @param terminal The terminal that would receive the route.
-    /// @return isCircular A flag indicating whether `terminal` is this router itself.
-    function _isCircularTerminal(IJBTerminal terminal) internal view returns (bool isCircular) {
-        return address(terminal) == address(this);
-    }
-
     /// @notice Accepts a token being paid in.
     /// @param token The address of the token being paid in.
     /// @param amount The amount of tokens being paid in.
@@ -1213,15 +1202,16 @@ contract JBRouterTerminal is
             // Cash out the source project's tokens.
             // Don't rely on the terminal return value here. Buyback-hook sell-side execution returns 0 reclaimAmount
             // from nana-core, then transfers the real proceeds during the hook callback.
-            // Pass the metadata-level minimum only on the first hop, while the amount is still expressed in the unit
-            // the caller supplied. Later hops may reclaim different assets, so reusing this floor would be unsound.
+            // Pass minTokensReclaimed=0 to the terminal because the buyback hook's sell-side delivers tokens via
+            // callback (reclaimAmount=0 from the terminal's perspective), which would fail the terminal's own min
+            // check. The router enforces the user's minimum via the balance-delta check below instead.
             // slither-disable-next-line unused-return,calls-loop
             cashOutTerminal.cashOutTokensOf({
                 holder: address(this),
                 projectId: sourceProjectId,
                 cashOutCount: amount,
                 tokenToReclaim: tokenToReclaim,
-                minTokensReclaimed: minTokensReclaimed,
+                minTokensReclaimed: 0,
                 beneficiary: payable(address(this)),
                 metadata: ""
             });
@@ -2331,7 +2321,7 @@ contract JBRouterTerminal is
         if (address(key.hooks) != address(0)) {
             // Build the two-element lookback array: [_TWAP_WINDOW seconds ago, now].
             uint32[] memory secondsAgos = new uint32[](2);
-            secondsAgos[0] = _TWAP_WINDOW; // Start of the window (30 seconds ago).
+            secondsAgos[0] = _TWAP_WINDOW; // Start of the window (120 seconds ago).
             secondsAgos[1] = 0; // End of the window (current block).
 
             // Ask the hook for cumulative tick data over the window. Silently catch if it doesn't support it.

package/src/libraries/JBForwardingCheck.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBForwardingTerminal} from "../interfaces/IJBForwardingTerminal.sol";
+
+/// @notice Shared circular-terminal detection used by both `JBRouterTerminal` (execution) and
+/// `JBPayRouteResolver` (preview).
+library JBForwardingCheck {
+    /// @notice Whether routing through `terminal` would cycle back to `target` within 5 hops.
+    /// @param target The address to detect cycles against (typically the router).
+    /// @param projectId The project whose forwarding chain is being followed.
+    /// @param terminal The starting terminal to check.
+    /// @return isCircular True if the terminal forwards (directly or transitively) back to `target`.
+    function isCircularTerminal(
+        address target,
+        uint256 projectId,
+        IJBTerminal terminal
+    )
+        internal
+        view
+        returns (bool isCircular)
+    {
+        IJBTerminal current = terminal;
+        for (uint256 i; i < 5; i++) {
+            if (address(current) == target) return true;
+
+            // Probe via staticcall so plain terminals degrade cleanly.
+            // slither-disable-next-line calls-loop
+            (bool success, bytes memory data) =
+                address(current).staticcall(abi.encodeCall(IJBForwardingTerminal.terminalOf, (projectId)));
+
+            // Non-forwarding terminals (call fails or returns zero) end the chain — not circular.
+            if (!success || data.length < 32) return false;
+            IJBTerminal forwardingTarget = abi.decode(data, (IJBTerminal));
+            if (address(forwardingTarget) == address(0)) return false;
+
+            current = forwardingTarget;
+        }
+
+        // 5 hops without resolution — treat as circular to be safe.
+        return true;
+    }
+}

package/test/RouterTerminal.t.sol

@@ -2271,6 +2271,7 @@ contract RouterTerminalTest is Test {
                 false,
                 address(0),
                 uint256(0),
+                uint256(0),
                 int24(0),
                 uint128(0),
                 PoolId.wrap(bytes32(0)),
@@ -2499,8 +2500,8 @@ contract RouterTerminalTest is Test {
             );
         }
 
-        // Router now applies the reclaim minimum on the first concrete cashout hop only.
-        // Later hops intentionally drop the floor because the route may change token units.
+        // The router now passes minTokensReclaimed=0 to the terminal and enforces the user's
+        // minimum via the balance-delta check instead (to support buyback-hook sell-side flows).
         vm.expectCall(
             address(mockCashOutTerminal),
             abi.encodeCall(
@@ -2510,7 +2511,7 @@ contract RouterTerminalTest is Test {
                     2, // sourceProjectId
                     100e18, // amount
                     JBConstants.NATIVE_TOKEN,
-                    50e18, // first hop receives the user-specified reclaim minimum directly
+                    0, // router passes 0 and enforces via balance-delta
                     payable(address(routerTerminal)),
                     bytes("")
                 )

package/test/RouterTerminalCreditCashout.t.sol

@@ -557,10 +557,12 @@ contract CreditCashoutSpoofingIntermediary is IJBPayerTracker {
             uint256 result = routerTerminal.pay(destProjectId, JBConstants.NATIVE_TOKEN, 0, payer, 0, "", metadata);
 
             assertEq(result, 200, "pay should return dest terminal token count");
+            // The router now passes minTokensReclaimed=0 to the terminal and enforces the user's
+            // minimum via the balance-delta check instead (to support buyback-hook sell-side flows).
             assertEq(
                 cashOutTerminal.lastMinTokensReclaimed(),
-                minReclaimed,
-                "router should forward the metadata floor on the first hop"
+                0,
+                "router should pass 0 to the terminal and enforce via balance-delta"
             );
             assertEq(destTerminal.lastAmount(), 60e18, "dest terminal should receive the reclaimed amount");
             assertEq(destTerminal.lastValue(), 60e18, "dest terminal should receive ETH value");

package/test/audit/CodexNemesisPayHookReceiptDoS.t.sol

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBToken} from "@bananapus/core-v6/src/interfaces/IJBToken.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
+import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
+import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.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";
+
+contract CodexNemesisERC20 is ERC20 {
+    constructor() ERC20("Codex Nemesis Token", "CNT") {}
+
+    function mint(address account, uint256 amount) external {
+        _mint(account, amount);
+    }
+}
+
+contract HookForwardingTerminal is IJBTerminal {
+    IERC20 public immutable TOKEN;
+    address public immutable HOOK;
+    uint256 public immutable HOOK_AMOUNT;
+
+    constructor(IERC20 token_, address hook_, uint256 hookAmount_) {
+        TOKEN = token_;
+        HOOK = hook_;
+        HOOK_AMOUNT = hookAmount_;
+    }
+
+    function accountingContextForTokenOf(uint256, address token_) external pure returns (JBAccountingContext memory) {
+        return JBAccountingContext({token: token_, decimals: 18, currency: 0});
+    }
+
+    function accountingContextsOf(uint256) external view returns (JBAccountingContext[] memory contexts) {
+        contexts = new JBAccountingContext[](1);
+        contexts[0] = JBAccountingContext({token: address(TOKEN), decimals: 18, currency: 0});
+    }
+
+    function currentSurplusOf(uint256, address[] calldata, uint256, uint256) external pure returns (uint256) {
+        return 0;
+    }
+
+    function previewPayFor(
+        uint256,
+        address,
+        uint256,
+        address,
+        bytes calldata
+    )
+        external
+        view
+        returns (
+            JBRuleset memory ruleset,
+            uint256 beneficiaryTokenCount,
+            uint256 terminalTokenAmount,
+            JBPayHookSpecification[] memory specs
+        )
+    {
+        specs = new JBPayHookSpecification[](1);
+        specs[0].amount = HOOK_AMOUNT;
+        beneficiaryTokenCount = 1;
+        terminalTokenAmount = HOOK_AMOUNT;
+        ruleset.id = 1;
+    }
+
+    function addAccountingContextsFor(uint256, JBAccountingContext[] calldata) external {}
+
+    function addToBalanceOf(uint256, address, uint256, bool, string calldata, bytes calldata) external payable {}
+
+    function migrateBalanceOf(uint256, address, IJBTerminal) external pure returns (uint256) {
+        return 0;
+    }
+
+    function pay(
+        uint256,
+        address,
+        uint256 amount,
+        address,
+        uint256,
+        string calldata,
+        bytes calldata
+    )
+        external
+        payable
+        returns (uint256)
+    {
+        require(TOKEN.transferFrom(msg.sender, address(this), amount));
+        require(TOKEN.transfer(HOOK, HOOK_AMOUNT));
+        return 1;
+    }
+
+    function supportsInterface(bytes4 interfaceId) external pure returns (bool) {
+        return interfaceId == type(IJBTerminal).interfaceId || interfaceId == type(IERC165).interfaceId;
+    }
+}
+
+contract CodexNemesisPayHookReceiptDoSTest is Test {
+    /// @notice After M-39 fix: pay() no longer enforces _enforceStandardTerminalReceipt, so a terminal
+    ///         that forwards tokens to a pay hook should succeed rather than revert.
+    function test_routerAllowsErc20TerminalThatForwardsToPayHook() external {
+        uint256 projectId = 1;
+        address payer = address(0xA11CE);
+        address beneficiary = address(0xB0B);
+        address hook = address(0xCAFE);
+        uint256 amount = 100 ether;
+        uint256 hookAmount = 40 ether;
+
+        CodexNemesisERC20 token = new CodexNemesisERC20();
+        HookForwardingTerminal terminal = new HookForwardingTerminal(token, hook, hookAmount);
+
+        address directory = address(0xD1);
+        address tokens = address(0x70);
+        vm.etch(directory, hex"00");
+        vm.etch(tokens, hex"00");
+
+        IJBTerminal[] memory terminals = new IJBTerminal[](1);
+        terminals[0] = IJBTerminal(address(terminal));
+
+        vm.mockCall(directory, abi.encodeCall(IJBDirectory.terminalsOf, (projectId)), abi.encode(terminals));
+        vm.mockCall(
+            directory,
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (projectId, address(token))),
+            abi.encode(address(terminal))
+        );
+        vm.mockCall(tokens, abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(address(token)))), abi.encode(uint256(0)));
+
+        JBRouterTerminal router = new JBRouterTerminal({
+            directory: IJBDirectory(directory),
+            tokens: IJBTokens(tokens),
+            permit2: IPermit2(address(0x22)),
+            weth: IWETH9(address(0x33)),
+            factory: IUniswapV3Factory(address(0x44)),
+            poolManager: IPoolManager(address(0)),
+            buybackHook: address(0),
+            univ4Hook: address(0),
+            trustedForwarder: address(0)
+        });
+
+        token.mint(payer, amount);
+
+        vm.startPrank(payer);
+        token.approve(address(router), amount);
+        // M-39 fix: pay() no longer reverts when hooks consume tokens — should succeed.
+        uint256 beneficiaryTokenCount = router.pay({
+            projectId: projectId,
+            token: address(token),
+            amount: amount,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "",
+            metadata: ""
+        });
+        vm.stopPrank();
+
+        assertEq(beneficiaryTokenCount, 1, "beneficiary should receive 1 token from mock terminal");
+    }
+}

package/test/audit/DeployBuybackHookZero.t.sol

@@ -286,7 +286,8 @@ contract DeployBuybackHookZeroTest is Test {
         reclaimToken = new AuditMockERC20();
         nativeTerminal = new AuditMockPreviewDestTerminal(JBConstants.NATIVE_TOKEN, 100);
         tokenBTerminal = new AuditMockPreviewDestTerminal(address(reclaimToken), 150);
-        nativeCashOut = new AuditMockCashOutTerminal{value: 40}(jbToken, JBConstants.NATIVE_TOKEN, 40, 40);
+        vm.deal(address(this), 80);
+        nativeCashOut = new AuditMockCashOutTerminal{value: 80}(jbToken, JBConstants.NATIVE_TOKEN, 40, 40);
         tokenBCashOut = new AuditMockCashOutTerminal(jbToken, address(reclaimToken), 50, 50);
 
         reclaimToken.mint(address(tokenBCashOut), 50);
@@ -393,6 +394,7 @@ contract DeployBuybackHookZeroTest is Test {
                 false,
                 address(0),
                 uint256(0),
+                uint256(0),
                 int24(0),
                 uint128(0),
                 PoolId.wrap(bytes32(0)),

package/test/audit/HookDataEncoding.t.sol

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IHooks} from "@uniswap/v4-core/src/interfaces/IHooks.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {Currency} from "@uniswap/v4-core/src/types/Currency.sol";
+import {BalanceDelta, toBalanceDelta} from "@uniswap/v4-core/src/types/BalanceDelta.sol";
+import {SwapParams} from "@uniswap/v4-core/src/types/PoolOperation.sol";
+
+import {JBRouterTerminal} from "../../src/JBRouterTerminal.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+
+/// @notice Mock PoolManager that captures the hookData argument from swap() calls.
+/// It returns a valid BalanceDelta so the unlock callback can run to completion.
+contract CapturingPoolManager {
+    bytes public capturedHookData;
+    bool public swapCalled;
+
+    /// @notice Captures hookData and returns a delta representing a swap of 1000 in, 900 out (zeroForOne).
+    function swap(PoolKey memory, SwapParams memory, bytes calldata hookData) external returns (BalanceDelta) {
+        capturedHookData = hookData;
+        swapCalled = true;
+        // Return delta: amount0 = -1000 (input consumed), amount1 = +900 (output received)
+        // zeroForOne: input is currency0 (negative delta), output is currency1 (positive delta)
+        return toBalanceDelta(-1000, 900);
+    }
+
+    /// @notice No-op settle for ERC-20 path.
+    function settle() external payable returns (uint256) {
+        return 0;
+    }
+
+    /// @notice No-op sync for ERC-20 path.
+    function sync(Currency) external {}
+
+    /// @notice No-op take for output side.
+    function take(Currency, address, uint256) external {}
+
+    /// @notice Fallback so vm.etch and other calls don't revert.
+    fallback() external payable {}
+    receive() external payable {}
+}
+
+/// @notice When the V4 pool key has hooks != address(0), the hookData passed to PoolManager.swap()
+/// must contain abi.encode(minAmountOut), not empty bytes. Otherwise hooks like JBUniswapV4Hook will revert.
+contract HookDataEncodingTest is Test {
+    JBRouterTerminal internal router;
+    CapturingPoolManager internal poolManager;
+
+    // Use distinct non-zero addresses for ERC-20 tokens (avoid native-ETH paths for simplicity).
+    address internal tokenA = address(0xAAAA);
+    address internal tokenB = address(0xBBBB);
+    // Hook address — any non-zero address.
+    address internal hook = address(0xCC01);
+
+    function setUp() public {
+        poolManager = new CapturingPoolManager();
+
+        // Deploy the router with the capturing pool manager.
+        router = new JBRouterTerminal({
+            directory: IJBDirectory(address(1)),
+            tokens: IJBTokens(address(2)),
+            permit2: IPermit2(address(3)),
+            weth: IWETH9(address(4)),
+            factory: IUniswapV3Factory(address(5)),
+            poolManager: IPoolManager(address(poolManager)),
+            buybackHook: address(0),
+            univ4Hook: hook,
+            trustedForwarder: address(0)
+        });
+
+        // Mock the IERC20.transfer call that _settleV4 makes (safeTransfer to pool manager).
+        vm.mockCall(
+            tokenA,
+            abi.encodeWithSignature("transfer(address,uint256)", address(poolManager), uint256(1000)),
+            abi.encode(true)
+        );
+        // Mock the IERC20.transfer for output side _takeV4 (not actually called since take is no-op, but be safe).
+        vm.mockCall(
+            tokenB,
+            abi.encodeWithSignature("transfer(address,uint256)", address(router), uint256(900)),
+            abi.encode(true)
+        );
+    }
+
+    /// @notice When a hooked V4 pool is used, hookData must contain abi.encode(minAmountOut).
+    function test_hookData_containsMinAmountOut_whenHooksConfigured() public {
+        // Build a pool key with hooks.
+        PoolKey memory key = PoolKey({
+            currency0: Currency.wrap(tokenA),
+            currency1: Currency.wrap(tokenB),
+            fee: 3000,
+            tickSpacing: 60,
+            hooks: IHooks(hook)
+        });
+
+        uint256 minAmountOut = 800;
+        bool zeroForOne = true;
+        int256 amountSpecified = -1000; // exact input of 1000
+        uint160 sqrtPriceLimitX96 = 4_295_128_740; // TickMath.MIN_SQRT_RATIO + 1
+        bool canUseExistingNativeBalance = false;
+
+        // Encode the callback data exactly as _executeV4Swap does.
+        bytes memory callbackData =
+            abi.encode(key, zeroForOne, amountSpecified, sqrtPriceLimitX96, minAmountOut, canUseExistingNativeBalance);
+
+        // Call unlockCallback as the PoolManager (required by the msg.sender check).
+        vm.prank(address(poolManager));
+        router.unlockCallback(callbackData);
+
+        // Verify swap was called.
+        assertTrue(poolManager.swapCalled(), "swap should have been called");
+
+        // The key assertion: hookData should contain abi.encode(minAmountOut), not be empty.
+        bytes memory expectedHookData = abi.encode(minAmountOut);
+        assertEq(poolManager.capturedHookData(), expectedHookData, "hookData must encode minAmountOut for hooked pools");
+    }
+
+    /// @notice When a pool has no hooks (address(0)), hookData should remain empty.
+    function test_hookData_isEmpty_whenNoHooks() public {
+        // Build a pool key WITHOUT hooks.
+        PoolKey memory key = PoolKey({
+            currency0: Currency.wrap(tokenA),
+            currency1: Currency.wrap(tokenB),
+            fee: 3000,
+            tickSpacing: 60,
+            hooks: IHooks(address(0))
+        });
+
+        uint256 minAmountOut = 800;
+        bool zeroForOne = true;
+        int256 amountSpecified = -1000;
+        uint160 sqrtPriceLimitX96 = 4_295_128_740;
+        bool canUseExistingNativeBalance = false;
+
+        bytes memory callbackData =
+            abi.encode(key, zeroForOne, amountSpecified, sqrtPriceLimitX96, minAmountOut, canUseExistingNativeBalance);
+
+        vm.prank(address(poolManager));
+        router.unlockCallback(callbackData);
+
+        assertTrue(poolManager.swapCalled(), "swap should have been called");
+
+        // With no hooks, hookData should be empty.
+        assertEq(poolManager.capturedHookData(), "", "hookData must be empty when no hooks configured");
+    }
+}