@bananapus/router-terminal-v6 0.0.4 → 0.0.6

package/foundry.toml

@@ -16,6 +16,9 @@ runs = 1024
 depth = 100
 fail_on_revert = false
 
+[rpc_endpoints]
+mainnet = "${RPC_ETHEREUM_MAINNET}"
+
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

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

package/src/JBRouterTerminal.sol

@@ -483,7 +483,8 @@ contract JBRouterTerminal is
                 destProjectId: destProjectId,
                 token: tokenIn,
                 amount: amount,
-                sourceProjectIdOverride: sourceProjectIdOverride
+                sourceProjectIdOverride: sourceProjectIdOverride,
+                metadata: metadata
             });
 
             // If the cashout loop found a terminal that accepts the reclaimed token, we're done.
@@ -575,6 +576,7 @@ contract JBRouterTerminal is
         bool hasFallback;
 
         for (uint256 i; i < terminals.length; i++) {
+            // slither-disable-next-line calls-loop
             JBAccountingContext[] memory contexts = terminals[i].accountingContextsOf(projectId);
 
             for (uint256 j; j < contexts.length; j++) {
@@ -611,9 +613,11 @@ contract JBRouterTerminal is
     function _bestPoolLiquidity(address tokenA, address tokenB) internal view returns (uint128 bestLiquidity) {
         // Search V3.
         for (uint256 i; i < 4; i++) {
+            // slither-disable-next-line calls-loop
             address poolAddr = FACTORY.getPool(tokenA, tokenB, _FEE_TIERS[i]);
             if (poolAddr == address(0)) continue;
 
+            // slither-disable-next-line calls-loop
             uint128 liquidity = IUniswapV3Pool(poolAddr).liquidity();
             if (liquidity > bestLiquidity) bestLiquidity = liquidity;
         }
@@ -708,6 +712,12 @@ contract JBRouterTerminal is
             callbackData: abi.encode(projectId, tokenIn, tokenOut)
         });
 
+        // For native token inputs, wrap any raw ETH remaining from partial fills so the leftover check catches it.
+        // In partial fills, the swap callback only wraps the amount the pool consumed, leaving excess as raw ETH.
+        if (tokenIn == JBConstants.NATIVE_TOKEN && address(this).balance != 0) {
+            WETH.deposit{value: address(this).balance}();
+        }
+
         // Unwrap if output is native token.
         if (tokenOut == JBConstants.NATIVE_TOKEN) WETH.withdraw(amountOut);
 
@@ -801,8 +811,9 @@ contract JBRouterTerminal is
 
         uint160 sqrtPriceLimitX96 = zeroForOne ? TickMath.MIN_SQRT_RATIO + 1 : TickMath.MAX_SQRT_RATIO - 1;
 
+        // V4 sign convention: negative = exact input, positive = exact output.
         bytes memory result =
-            POOL_MANAGER.unlock(abi.encode(key, zeroForOne, int256(amount), sqrtPriceLimitX96, minAmountOut));
+            POOL_MANAGER.unlock(abi.encode(key, zeroForOne, -int256(amount), sqrtPriceLimitX96, minAmountOut));
 
         amountOut = abi.decode(result, (uint256));
     }
@@ -811,11 +822,13 @@ contract JBRouterTerminal is
     function _settleV4(Currency currency, uint256 amount) internal {
         if (Currency.unwrap(currency) == address(0)) {
             // Native ETH: contract already holds raw ETH.
+            // slither-disable-next-line unused-return
             POOL_MANAGER.settle{value: amount}();
         } else {
             // ERC20: sync then transfer then settle.
             POOL_MANAGER.sync(currency);
             IERC20(Currency.unwrap(currency)).safeTransfer(address(POOL_MANAGER), amount);
+            // slither-disable-next-line unused-return
             POOL_MANAGER.settle();
         }
     }
@@ -935,6 +948,7 @@ contract JBRouterTerminal is
         returns (uint256 minAmountOut)
     {
         PoolId id = key.toId();
+        // slither-disable-next-line unused-return
         (, int24 tick,,) = POOL_MANAGER.getSlot0(id);
         uint128 liquidity = POOL_MANAGER.getLiquidity(id);
 
@@ -976,10 +990,12 @@ contract JBRouterTerminal is
 
         // Search V3.
         for (uint256 i; i < 4; i++) {
+            // slither-disable-next-line calls-loop
             address poolAddr = FACTORY.getPool(normalizedTokenIn, normalizedTokenOut, _FEE_TIERS[i]);
 
             if (poolAddr == address(0)) continue;
 
+            // slither-disable-next-line calls-loop
             uint128 poolLiquidity = IUniswapV3Pool(poolAddr).liquidity();
 
             if (poolLiquidity > bestLiquidity) {
@@ -1035,9 +1051,11 @@ contract JBRouterTerminal is
                 hooks: IHooks(address(0))
             });
 
+            // slither-disable-next-line unused-return,calls-loop
             (uint160 sqrtPriceX96,,,) = POOL_MANAGER.getSlot0(key.toId());
             if (sqrtPriceX96 == 0) continue;
 
+            // slither-disable-next-line calls-loop
             uint128 poolLiquidity = POOL_MANAGER.getLiquidity(key.toId());
             if (poolLiquidity > currentBestLiquidity) {
                 currentBestLiquidity = poolLiquidity;
@@ -1084,6 +1102,7 @@ contract JBRouterTerminal is
     /// @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.
     /// @return finalAmount The amount of the final token.
@@ -1091,14 +1110,24 @@ contract JBRouterTerminal is
         uint256 destProjectId,
         address token,
         uint256 amount,
-        uint256 sourceProjectIdOverride
+        uint256 sourceProjectIdOverride,
+        bytes calldata metadata
     )
         internal
         returns (IJBTerminal destTerminal, address finalToken, uint256 finalAmount)
     {
+        // Check for a user-provided minimum cashout reclaim amount (slippage protection).
+        uint256 minTokensReclaimed;
+        {
+            (bool exists, bytes memory minData) =
+                JBMetadataResolver.getDataFor({id: JBMetadataResolver.getId("cashOutMinReclaimed"), metadata: metadata});
+            if (exists) minTokensReclaimed = abi.decode(minData, (uint256));
+        }
+
         while (true) {
             // Skip the destination check on the first iteration if we have a credit override.
             if (sourceProjectIdOverride == 0) {
+                // slither-disable-next-line calls-loop
                 destTerminal = DIRECTORY.primaryTerminalOf({projectId: destProjectId, token: token});
                 if (address(destTerminal) != address(0)) {
                     return (destTerminal, token, amount);
@@ -1106,6 +1135,7 @@ contract JBRouterTerminal is
             }
 
             // Use the override if provided, otherwise look up the project ID from the token.
+            // slither-disable-next-line calls-loop
             uint256 sourceProjectId =
                 sourceProjectIdOverride != 0 ? sourceProjectIdOverride : TOKENS.projectIdOf(IJBToken(token));
 
@@ -1119,16 +1149,20 @@ contract JBRouterTerminal is
                 _findCashOutPath({sourceProjectId: sourceProjectId, destProjectId: destProjectId});
 
             // Cash out the source project's tokens.
+            // slither-disable-next-line calls-loop
             amount = cashOutTerminal.cashOutTokensOf({
                 holder: address(this),
                 projectId: sourceProjectId,
                 cashOutCount: amount,
                 tokenToReclaim: tokenToReclaim,
-                minTokensReclaimed: 0,
+                minTokensReclaimed: minTokensReclaimed,
                 beneficiary: payable(address(this)),
                 metadata: bytes("")
             });
 
+            // Only apply the minimum to the first cashout step.
+            minTokensReclaimed = 0;
+
             // Update for next iteration.
             token = tokenToReclaim;
             sourceProjectIdOverride = 0;
@@ -1155,11 +1189,13 @@ contract JBRouterTerminal is
         address baseFallbackToken;
         IJBCashOutTerminal baseFallbackTerminal;
 
+        // slither-disable-next-line calls-loop
         IJBTerminal[] memory terminals = DIRECTORY.terminalsOf(sourceProjectId);
 
         for (uint256 i; i < terminals.length; i++) {
             // Check if this terminal supports the IJBCashOutTerminal interface.
             {
+                // slither-disable-next-line calls-loop
                 try IERC165(address(terminals[i])).supportsInterface(type(IJBCashOutTerminal).interfaceId) returns (
                     bool supported
                 ) {
@@ -1170,6 +1206,7 @@ contract JBRouterTerminal is
             }
 
             IJBCashOutTerminal terminal = IJBCashOutTerminal(address(terminals[i]));
+            // slither-disable-next-line calls-loop
             JBAccountingContext[] memory contexts = terminals[i].accountingContextsOf(sourceProjectId);
 
             for (uint256 j; j < contexts.length; j++) {
@@ -1177,6 +1214,7 @@ contract JBRouterTerminal is
 
                 // Priority 1: Does the destination project directly accept this token?
                 {
+                    // slither-disable-next-line calls-loop
                     IJBTerminal destTerminal =
                         DIRECTORY.primaryTerminalOf({projectId: destProjectId, token: contextToken});
                     if (address(destTerminal) != address(0)) {
@@ -1186,6 +1224,7 @@ contract JBRouterTerminal is
 
                 // Priority 2: Is this a JB project token (so we can recurse)?
                 if (address(fallbackTerminal) == address(0) && contextToken != JBConstants.NATIVE_TOKEN) {
+                    // slither-disable-next-line calls-loop
                     if (TOKENS.projectIdOf(IJBToken(contextToken)) != 0) {
                         fallbackToken = contextToken;
                         fallbackTerminal = terminal;
@@ -1218,9 +1257,12 @@ contract JBRouterTerminal is
                 JBMetadataResolver.getDataFor({id: JBMetadataResolver.getId("cashOutSource"), metadata: metadata});
 
             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));
 
-                // Pull credits from the payer.
+                // Pull credits from the payer (requires payer to have granted TRANSFER_CREDITS to this contract).
                 TOKENS.transferCreditsFrom({
                     holder: _msgSender(), projectId: sourceProjectId, recipient: address(this), count: creditAmount
                 });
@@ -1258,6 +1300,7 @@ contract JBRouterTerminal is
                 sigDeadline: allowance.sigDeadline
             });
 
+            // slither-disable-next-line reentrancy-events
             try PERMIT2.permit({owner: _msgSender(), permitSingle: permitSingle, signature: allowance.signature}) {}
             catch (bytes memory reason) {
                 emit Permit2AllowanceFailed(token, _msgSender(), reason);

package/test/RouterTerminal.t.sol

@@ -823,4 +823,197 @@ contract RouterTerminalTest is Test {
         _mockV4PoolNotExists(sorted0, sorted1, 10_000, int24(200));
         _mockV4PoolNotExists(sorted0, sorted1, 100, int24(1));
     }
+
+    //*********************************************************************//
+    // ---------- Bug fix regression tests: ETH + credit revert ---------- //
+    //*********************************************************************//
+
+    /// @notice Sending msg.value alongside cashOutSource credit metadata should revert (fix #2).
+    function test_pay_revertsWhenETHSentWithCreditMetadata() public {
+        uint256 projectId = 1;
+        address payer = makeAddr("payer");
+
+        // Build metadata with cashOutSource — must use router address for getId.
+        bytes4 metadataId = JBMetadataResolver.getId("cashOutSource", address(routerTerminal));
+        bytes memory metadata = JBMetadataResolver.addToMetadata("", metadataId, abi.encode(uint256(2), uint256(1e18)));
+
+        vm.deal(payer, 1 ether);
+        vm.prank(payer);
+        vm.expectRevert(abi.encodeWithSelector(IJBRouterTerminal.JBRouterTerminal_NoMsgValueAllowed.selector, 1 ether));
+        routerTerminal.pay{value: 1 ether}(projectId, JBConstants.NATIVE_TOKEN, 1 ether, payer, 0, "", metadata);
+    }
+
+    /// @notice addToBalanceOf should also revert when ETH sent with credit metadata.
+    function test_addToBalanceOf_revertsWhenETHSentWithCreditMetadata() public {
+        address payer = makeAddr("payer");
+
+        // Build metadata with cashOutSource — must use router address for getId.
+        bytes4 metadataId = JBMetadataResolver.getId("cashOutSource", address(routerTerminal));
+        bytes memory metadata = JBMetadataResolver.addToMetadata("", metadataId, abi.encode(uint256(2), uint256(1e18)));
+
+        vm.deal(payer, 1 ether);
+        vm.prank(payer);
+        vm.expectRevert(abi.encodeWithSelector(IJBRouterTerminal.JBRouterTerminal_NoMsgValueAllowed.selector, 1 ether));
+        routerTerminal.addToBalanceOf{value: 1 ether}(1, JBConstants.NATIVE_TOKEN, 1 ether, false, "", metadata);
+    }
+
+    //*********************************************************************//
+    // ----------- Bug fix regression tests: V4 sign convention ---------- //
+    //*********************************************************************//
+
+    /// @notice The V4 unlock callback should receive a negative amountSpecified for exact-input (fix #1).
+    function test_unlockCallback_negativeAmountSpecified() public {
+        address tokenA = makeAddr("tokenA");
+        address tokenB = makeAddr("tokenB");
+        (address sorted0, address sorted1) = tokenA < tokenB ? (tokenA, tokenB) : (tokenB, tokenA);
+
+        PoolKey memory key = PoolKey({
+            currency0: Currency.wrap(sorted0),
+            currency1: Currency.wrap(sorted1),
+            fee: 3000,
+            tickSpacing: int24(60),
+            hooks: IHooks(address(0))
+        });
+
+        uint256 amount = 1e18;
+        int256 amountSpecified = -int256(amount); // exact-input: NEGATIVE
+        uint160 sqrtPriceLimitX96 = 4_295_128_740; // MIN_SQRT_RATIO + 1
+        uint256 minAmountOut = 0;
+
+        // Encode the data as the contract would encode it (with the sign fix).
+        bytes memory callbackData = abi.encode(key, true, amountSpecified, sqrtPriceLimitX96, minAmountOut);
+
+        // Mock the PoolManager.swap call — it should receive a negative amountSpecified.
+        // We construct the expected SwapParams to verify the sign.
+        vm.mockCall(
+            address(mockPoolManager),
+            abi.encodeWithSelector(IPoolManager.swap.selector),
+            // Return a BalanceDelta where token0 goes in (-1e18) and token1 comes out (+5e17).
+            abi.encode(int256(-1e18) << 128 | int256(uint256(5e17)))
+        );
+
+        // Mock settle and take.
+        vm.mockCall(address(mockPoolManager), abi.encodeWithSignature("settle()"), abi.encode(uint256(1e18)));
+        vm.mockCall(address(mockPoolManager), abi.encodeWithSignature("settle{value}()"), abi.encode(uint256(1e18)));
+        vm.mockCall(address(mockPoolManager), abi.encodeWithSignature("sync(address)"), abi.encode());
+        vm.mockCall(address(mockPoolManager), abi.encodeWithSignature("take(address,address,uint256)"), abi.encode());
+        vm.mockCall(sorted0, abi.encodeCall(IERC20.transfer, (address(mockPoolManager), 1e18)), abi.encode(true));
+
+        // Call from the PoolManager (authorized).
+        vm.prank(address(mockPoolManager));
+
+        // The callback should decode a NEGATIVE amountSpecified and process the swap.
+        // If the old bug existed (positive), the swap behavior would be different.
+        bytes memory result = routerTerminal.unlockCallback(callbackData);
+
+        // Verify amountOut is decoded correctly.
+        uint256 amountOut = abi.decode(result, (uint256));
+        assertEq(amountOut, 5e17);
+    }
+
+    //*********************************************************************//
+    // --------- Bug fix regression tests: cashout slippage -------------- //
+    //*********************************************************************//
+
+    /// @notice cashOutMinReclaimed metadata should be forwarded to the cashout terminal (fix #4).
+    function test_pay_cashOutMinReclaimedMetadata() public {
+        uint256 destProjectId = 1;
+        address payer = makeAddr("payer");
+        address jbToken = makeAddr("jbToken");
+        vm.etch(jbToken, hex"00");
+        uint256 sourceProjectId = 2;
+        uint256 amount = 100e18;
+        uint256 minReclaimed = 50e18;
+        address mockTerminal = makeAddr("destTerminal");
+        vm.etch(mockTerminal, hex"00");
+        address mockCashOutTerminal = makeAddr("cashOutTerminal");
+        vm.etch(mockCashOutTerminal, hex"00");
+
+        // Build metadata with cashOutMinReclaimed — must use router address for getId.
+        bytes4 metadataId = JBMetadataResolver.getId("cashOutMinReclaimed", address(routerTerminal));
+        bytes memory metadata = JBMetadataResolver.addToMetadata("", metadataId, abi.encode(minReclaimed));
+
+        // jbToken is a JB project token for sourceProjectId.
+        vm.mockCall(
+            address(mockTokens), abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(jbToken))), abi.encode(sourceProjectId)
+        );
+
+        // Dest project accepts NATIVE_TOKEN.
+        vm.mockCall(
+            address(mockDirectory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, JBConstants.NATIVE_TOKEN)),
+            abi.encode(mockTerminal)
+        );
+
+        // Dest project doesn't accept jbToken directly.
+        vm.mockCall(
+            address(mockDirectory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, jbToken)),
+            abi.encode(address(0))
+        );
+
+        // Source project's terminals (for _findCashOutPath).
+        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 — use broad selector matching since vm.mockCall matches by prefix.
+        // The key assertion: the call should use minReclaimed (not 0).
+        vm.mockCall(
+            mockCashOutTerminal,
+            abi.encodeWithSelector(IJBCashOutTerminal.cashOutTokensOf.selector),
+            abi.encode(uint256(60e18))
+        );
+
+        // Expect the specific cashOutTokensOf call with minReclaimed = minReclaimed.
+        vm.expectCall(
+            mockCashOutTerminal,
+            abi.encodeCall(
+                IJBCashOutTerminal.cashOutTokensOf,
+                (
+                    address(routerTerminal),
+                    sourceProjectId,
+                    amount,
+                    JBConstants.NATIVE_TOKEN,
+                    minReclaimed,
+                    payable(address(routerTerminal)),
+                    bytes("")
+                )
+            )
+        );
+
+        // Mock token transfer from payer.
+        vm.mockCall(jbToken, abi.encodeCall(IERC20.allowance, (payer, address(routerTerminal))), abi.encode(amount));
+        vm.mockCall(
+            jbToken, abi.encodeCall(IERC20.transferFrom, (payer, address(routerTerminal), amount)), abi.encode(true)
+        );
+
+        // Mock dest terminal pay.
+        vm.mockCall(mockTerminal, abi.encodeWithSelector(IJBTerminal.pay.selector), abi.encode(uint256(10)));
+
+        vm.prank(payer);
+        routerTerminal.pay(destProjectId, jbToken, amount, payer, 0, "", metadata);
+    }
 }

package/test/RouterTerminalFork.t.sol

@@ -0,0 +1,509 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import "forge-std/Test.sol";
+
+// JB core (via TestBaseWorkflow pattern — deploy fresh within fork).
+import {JBPermissions} from "@bananapus/core-v6/src/JBPermissions.sol";
+import {JBProjects} from "@bananapus/core-v6/src/JBProjects.sol";
+import {JBDirectory} from "@bananapus/core-v6/src/JBDirectory.sol";
+import {JBRulesets} from "@bananapus/core-v6/src/JBRulesets.sol";
+import {JBTokens} from "@bananapus/core-v6/src/JBTokens.sol";
+import {JBERC20} from "@bananapus/core-v6/src/JBERC20.sol";
+import {JBSplits} from "@bananapus/core-v6/src/JBSplits.sol";
+import {JBPrices} from "@bananapus/core-v6/src/JBPrices.sol";
+import {JBController} from "@bananapus/core-v6/src/JBController.sol";
+import {JBFundAccessLimits} from "@bananapus/core-v6/src/JBFundAccessLimits.sol";
+import {JBFeelessAddresses} from "@bananapus/core-v6/src/JBFeelessAddresses.sol";
+import {JBTerminalStore} from "@bananapus/core-v6/src/JBTerminalStore.sol";
+import {JBMultiTerminal} from "@bananapus/core-v6/src/JBMultiTerminal.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 {JBRulesetConfig} from "@bananapus/core-v6/src/structs/JBRulesetConfig.sol";
+import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadata.sol";
+import {JBTerminalConfig} from "@bananapus/core-v6/src/structs/JBTerminalConfig.sol";
+import {JBSplitGroup} from "@bananapus/core-v6/src/structs/JBSplitGroup.sol";
+import {JBFundAccessLimitGroup} from "@bananapus/core-v6/src/structs/JBFundAccessLimitGroup.sol";
+import {JBCurrencyAmount} from "@bananapus/core-v6/src/structs/JBCurrencyAmount.sol";
+import {IJBRulesetApprovalHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetApprovalHook.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+
+// Uniswap.
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IUniswapV3Pool} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Pool.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+
+// OpenZeppelin.
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+// Router terminal.
+import {JBRouterTerminal} from "../src/JBRouterTerminal.sol";
+import {IWETH9} from "../src/interfaces/IWETH9.sol";
+
+/// @notice Fork tests for JBRouterTerminal against real Uniswap V3 pools on Ethereum mainnet.
+/// @dev Uses a pinned block for determinism. JB core is deployed fresh within the fork so we control project state.
+contract RouterTerminalForkTest is Test {
+    // ───────────────────────── Mainnet addresses
+    // ──────────────────────────
+
+    // Post-V4-deployment block (V4 PoolManager deployed ~21,690,000) with good TWAP history.
+    uint256 constant BLOCK_NUMBER = 21_700_000;
+
+    IWETH9 constant WETH = IWETH9(0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2);
+    IERC20 constant USDC = IERC20(0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48);
+    IERC20 constant DAI = IERC20(0x6B175474E89094C44Da98b954EedeAC495271d0F);
+    IUniswapV3Factory constant V3_FACTORY = IUniswapV3Factory(0x1F98431c8aD98523631AE4a59f267346ea31F984);
+    IPermit2 constant PERMIT2 = IPermit2(0x000000000022D473030F116dDEE9F6B43aC78BA3);
+    IPoolManager constant V4_POOL_MANAGER = IPoolManager(0x000000000004444c5dc75cB358380D2e3dE08A90);
+
+    // Well-known V3 pools (we don't create them — they exist on mainnet).
+    // WETH/USDC 0.05%: 0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640
+    // WETH/DAI  0.3%:  0xC2e9F25Be6257c210d7Adf0D4Cd6E3E881ba25f8
+
+    // ───────────────────────── JB core (deployed fresh)
+    // ────────────────────
+
+    address multisig = address(0xBEEF);
+    address payer = makeAddr("payer");
+    address beneficiary = makeAddr("beneficiary");
+    address trustedForwarder = address(0);
+
+    JBPermissions jbPermissions;
+    JBProjects jbProjects;
+    JBDirectory jbDirectory;
+    JBRulesets jbRulesets;
+    JBTokens jbTokens;
+    JBSplits jbSplits;
+    JBPrices jbPrices;
+    JBFundAccessLimits jbFundAccessLimits;
+    JBFeelessAddresses jbFeelessAddresses;
+    JBController jbController;
+    JBTerminalStore jbTerminalStore;
+    JBMultiTerminal jbMultiTerminal;
+    JBRouterTerminal routerTerminal;
+
+    // Project IDs.
+    uint256 feeProjectId; // Project 1 (fee recipient).
+    uint256 ethProjectId; // Accepts NATIVE_TOKEN (ETH).
+    uint256 usdcProjectId; // Accepts USDC.
+    uint256 daiProjectId; // Accepts DAI.
+
+    // ───────────────────────── Setup
+    // ──────────────────────────────────────
+
+    function setUp() public {
+        // Skip fork tests in CI when no RPC URL is configured.
+        string memory rpcUrl = vm.envOr("RPC_ETHEREUM_MAINNET", string(""));
+        if (bytes(rpcUrl).length == 0) {
+            vm.skip(true);
+            return;
+        }
+        vm.createSelectFork(rpcUrl, BLOCK_NUMBER);
+
+        // Deploy all JB core contracts fresh within the fork.
+        _deployJBCore();
+
+        // Deploy the router terminal with real Uniswap + real Permit2, but fresh JB core.
+        routerTerminal = new JBRouterTerminal({
+            directory: jbDirectory,
+            permissions: jbPermissions,
+            projects: jbProjects,
+            tokens: jbTokens,
+            permit2: PERMIT2,
+            owner: multisig,
+            weth: WETH,
+            factory: V3_FACTORY,
+            poolManager: V4_POOL_MANAGER,
+            trustedForwarder: trustedForwarder
+        });
+
+        // Create test projects.
+        feeProjectId = _launchProject({acceptedToken: JBConstants.NATIVE_TOKEN, decimals: 18});
+        ethProjectId = _launchProject({acceptedToken: JBConstants.NATIVE_TOKEN, decimals: 18});
+        usdcProjectId = _launchProject({acceptedToken: address(USDC), decimals: 6});
+        daiProjectId = _launchProject({acceptedToken: address(DAI), decimals: 18});
+
+        // Labels for trace readability.
+        vm.label(address(WETH), "WETH");
+        vm.label(address(USDC), "USDC");
+        vm.label(address(DAI), "DAI");
+        vm.label(address(routerTerminal), "RouterTerminal");
+        vm.label(address(jbMultiTerminal), "JBMultiTerminal");
+        vm.label(payer, "payer");
+        vm.label(beneficiary, "beneficiary");
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // V3 SWAP: ETH → USDC (pay project that accepts USDC with ETH)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    function test_fork_payETH_projectAcceptsUSDC_small() public {
+        uint256 amountIn = 0.01 ether;
+        _payETHAndAssert(usdcProjectId, amountIn, address(USDC));
+    }
+
+    function test_fork_payETH_projectAcceptsUSDC_medium() public {
+        uint256 amountIn = 1 ether;
+        _payETHAndAssert(usdcProjectId, amountIn, address(USDC));
+    }
+
+    function test_fork_payETH_projectAcceptsUSDC_large() public {
+        uint256 amountIn = 100 ether;
+        _payETHAndAssert(usdcProjectId, amountIn, address(USDC));
+    }
+
+    function test_fork_payETH_projectAcceptsUSDC_veryLarge() public {
+        uint256 amountIn = 1000 ether;
+        _payETHAndAssert(usdcProjectId, amountIn, address(USDC));
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // V3 SWAP: USDC → ETH (pay project that accepts ETH with USDC)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    function test_fork_payUSDC_projectAcceptsETH_small() public {
+        uint256 amountIn = 10e6; // 10 USDC
+        _payERC20AndAssert(usdcProjectId, ethProjectId, address(USDC), amountIn, JBConstants.NATIVE_TOKEN);
+    }
+
+    function test_fork_payUSDC_projectAcceptsETH_large() public {
+        uint256 amountIn = 1_000_000e6; // 1M USDC
+        _payERC20AndAssert(usdcProjectId, ethProjectId, address(USDC), amountIn, JBConstants.NATIVE_TOKEN);
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // DIRECT FORWARD (no swap needed)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    function test_fork_payETH_projectAcceptsETH() public {
+        uint256 amountIn = 1 ether;
+
+        vm.deal(payer, amountIn);
+        uint256 payerBalBefore = payer.balance;
+
+        vm.prank(payer);
+        uint256 tokenCount = routerTerminal.pay{value: amountIn}({
+            projectId: ethProjectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: amountIn,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "direct ETH forward",
+            metadata: ""
+        });
+
+        // Project tokens minted.
+        assertGt(tokenCount, 0, "no tokens minted for direct ETH forward");
+
+        // Payer spent exactly amountIn.
+        assertEq(payerBalBefore - payer.balance, amountIn, "payer balance mismatch");
+
+        // Terminal received the ETH.
+        uint256 terminalBal =
+            jbTerminalStore.balanceOf(address(jbMultiTerminal), ethProjectId, JBConstants.NATIVE_TOKEN);
+        assertGt(terminalBal, 0, "terminal has no ETH balance");
+
+        // Router has no leftover.
+        assertEq(address(routerTerminal).balance, 0, "router has leftover ETH");
+    }
+
+    function test_fork_payUSDC_projectAcceptsUSDC() public {
+        uint256 amountIn = 1000e6; // 1000 USDC
+
+        deal(address(USDC), payer, amountIn);
+
+        vm.startPrank(payer);
+        USDC.approve(address(routerTerminal), amountIn);
+        uint256 tokenCount = routerTerminal.pay({
+            projectId: usdcProjectId,
+            token: address(USDC),
+            amount: amountIn,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "direct USDC forward",
+            metadata: ""
+        });
+        vm.stopPrank();
+
+        assertGt(tokenCount, 0, "no tokens minted for direct USDC forward");
+
+        // Terminal received the USDC.
+        uint256 terminalBal = jbTerminalStore.balanceOf(address(jbMultiTerminal), usdcProjectId, address(USDC));
+        assertGt(terminalBal, 0, "terminal has no USDC balance");
+
+        // Router has no leftover.
+        assertEq(USDC.balanceOf(address(routerTerminal)), 0, "router has leftover USDC");
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // V3 SWAP: ETH → DAI
+    // ═══════════════════════════════════════════════════════════════════════
+
+    function test_fork_payETH_projectAcceptsDAI() public {
+        uint256 amountIn = 1 ether;
+        _payETHAndAssert(daiProjectId, amountIn, address(DAI));
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // addToBalanceOf
+    // ═══════════════════════════════════════════════════════════════════════
+
+    function test_fork_addToBalance_ETHtoUSDC() public {
+        uint256 amountIn = 1 ether;
+
+        vm.deal(payer, amountIn);
+        uint256 terminalBalBefore = jbTerminalStore.balanceOf(address(jbMultiTerminal), usdcProjectId, address(USDC));
+
+        vm.prank(payer);
+        routerTerminal.addToBalanceOf{value: amountIn}({
+            projectId: usdcProjectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: amountIn,
+            shouldReturnHeldFees: false,
+            memo: "add to balance ETH->USDC",
+            metadata: ""
+        });
+
+        uint256 terminalBalAfter = jbTerminalStore.balanceOf(address(jbMultiTerminal), usdcProjectId, address(USDC));
+
+        assertGt(terminalBalAfter, terminalBalBefore, "terminal balance did not increase");
+        assertEq(address(routerTerminal).balance, 0, "router has leftover ETH");
+        assertEq(USDC.balanceOf(address(routerTerminal)), 0, "router has leftover USDC");
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // User-provided quote (metadata override)
+    // ═══════════════════════════════════════════════════════════════════════
+
+    function test_fork_payETH_withQuoteMetadata() public {
+        uint256 amountIn = 1 ether;
+
+        // Set a generous quote (1 USDC minimum — well below market, should succeed).
+        bytes4 quoteId = JBMetadataResolver.getId("quoteForSwap", address(routerTerminal));
+        bytes memory metadata = JBMetadataResolver.addToMetadata("", quoteId, abi.encode(uint256(1e6)));
+
+        vm.deal(payer, amountIn);
+
+        vm.prank(payer);
+        uint256 tokenCount = routerTerminal.pay{value: amountIn}({
+            projectId: usdcProjectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: amountIn,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "ETH->USDC with quote metadata",
+            metadata: metadata
+        });
+
+        assertGt(tokenCount, 0, "no tokens minted with quote metadata");
+
+        // Terminal received USDC.
+        uint256 terminalBal = jbTerminalStore.balanceOf(address(jbMultiTerminal), usdcProjectId, address(USDC));
+        assertGt(terminalBal, 0, "terminal has no USDC balance after quote metadata pay");
+
+        // Router clean.
+        assertEq(address(routerTerminal).balance, 0, "router has leftover ETH");
+        assertEq(USDC.balanceOf(address(routerTerminal)), 0, "router has leftover USDC");
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Slippage / revert scenarios
+    // ═══════════════════════════════════════════════════════════════════════
+
+    function test_fork_payETH_tightQuote_reverts() public {
+        uint256 amountIn = 1 ether;
+
+        // Set a quote 3x above market (~3,300 USDC/ETH → require 10,000 USDC).
+        // This is tight enough to trigger SlippageExceeded but not so extreme that
+        // sqrtPriceLimitFromAmounts falls back to "no limit".
+        bytes4 quoteId = JBMetadataResolver.getId("quoteForSwap", address(routerTerminal));
+        bytes memory metadata = JBMetadataResolver.addToMetadata("", quoteId, abi.encode(uint256(10_000e6)));
+
+        vm.deal(payer, amountIn);
+
+        vm.prank(payer);
+        vm.expectRevert();
+        routerTerminal.pay{value: amountIn}({
+            projectId: usdcProjectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: amountIn,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "should revert - tight quote",
+            metadata: metadata
+        });
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════
+    // Internal helpers
+    // ═══════════════════════════════════════════════════════════════════════
+
+    /// @dev Pay ETH via the router terminal to a project that accepts `expectedTokenOut`. Asserts swap happened.
+    function _payETHAndAssert(uint256 projectId, uint256 amountIn, address expectedTokenOut) internal {
+        vm.deal(payer, amountIn);
+        uint256 payerBalBefore = payer.balance;
+
+        vm.prank(payer);
+        uint256 tokenCount = routerTerminal.pay{value: amountIn}({
+            projectId: projectId,
+            token: JBConstants.NATIVE_TOKEN,
+            amount: amountIn,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "fork test ETH swap",
+            metadata: ""
+        });
+
+        // 1. Swap produced output — tokens minted.
+        assertGt(tokenCount, 0, "no tokens minted");
+
+        // 2. Destination terminal received the output tokens (project balance increased).
+        uint256 terminalBal = jbTerminalStore.balanceOf(address(jbMultiTerminal), projectId, expectedTokenOut);
+        assertGt(terminalBal, 0, "terminal has no balance in expected token");
+
+        // 3. No leftover tokens stuck in the router.
+        assertEq(address(routerTerminal).balance, 0, "router has leftover ETH");
+        assertEq(IERC20(address(WETH)).balanceOf(address(routerTerminal)), 0, "router has leftover WETH");
+        assertEq(IERC20(expectedTokenOut).balanceOf(address(routerTerminal)), 0, "router has leftover output token");
+
+        // 4. Payer's balance decreased by exactly the input amount.
+        assertEq(payerBalBefore - payer.balance, amountIn, "payer balance mismatch");
+    }
+
+    /// @dev Pay ERC-20 via the router terminal to a project that accepts a different token.
+    function _payERC20AndAssert(
+        uint256, /* sourceProjectIdForDeal — unused */
+        uint256 destProjectId,
+        address tokenIn,
+        uint256 amountIn,
+        address expectedTokenOut
+    )
+        internal
+    {
+        deal(tokenIn, payer, amountIn);
+
+        vm.startPrank(payer);
+        IERC20(tokenIn).approve(address(routerTerminal), amountIn);
+        uint256 tokenCount = routerTerminal.pay({
+            projectId: destProjectId,
+            token: tokenIn,
+            amount: amountIn,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "fork test ERC20 swap",
+            metadata: ""
+        });
+        vm.stopPrank();
+
+        // Tokens minted.
+        assertGt(tokenCount, 0, "no tokens minted for ERC20 swap");
+
+        // Terminal received expected output token.
+        uint256 terminalBal = jbTerminalStore.balanceOf(address(jbMultiTerminal), destProjectId, expectedTokenOut);
+        assertGt(terminalBal, 0, "terminal has no balance in expected token");
+
+        // Router clean.
+        assertEq(IERC20(tokenIn).balanceOf(address(routerTerminal)), 0, "router has leftover tokenIn");
+        if (expectedTokenOut != JBConstants.NATIVE_TOKEN) {
+            assertEq(IERC20(expectedTokenOut).balanceOf(address(routerTerminal)), 0, "router has leftover tokenOut");
+        }
+        assertEq(address(routerTerminal).balance, 0, "router has leftover ETH");
+    }
+
+    // ───────────────────────── JB Core Deployment
+    // ─────────────────────────
+
+    function _deployJBCore() internal {
+        jbPermissions = new JBPermissions(trustedForwarder);
+        jbProjects = new JBProjects(multisig, address(0), trustedForwarder);
+        jbDirectory = new JBDirectory(jbPermissions, jbProjects, multisig);
+        JBERC20 jbErc20 = new JBERC20();
+        jbTokens = new JBTokens(jbDirectory, jbErc20);
+        jbRulesets = new JBRulesets(jbDirectory);
+        jbPrices = new JBPrices(jbDirectory, jbPermissions, jbProjects, multisig, trustedForwarder);
+        jbSplits = new JBSplits(jbDirectory);
+        jbFundAccessLimits = new JBFundAccessLimits(jbDirectory);
+        jbFeelessAddresses = new JBFeelessAddresses(multisig);
+
+        jbController = new JBController(
+            jbDirectory,
+            jbFundAccessLimits,
+            jbPermissions,
+            jbPrices,
+            jbProjects,
+            jbRulesets,
+            jbSplits,
+            jbTokens,
+            address(0), // omnichainRulesetOperator
+            trustedForwarder
+        );
+
+        vm.prank(multisig);
+        jbDirectory.setIsAllowedToSetFirstController(address(jbController), true);
+
+        jbTerminalStore = new JBTerminalStore(jbDirectory, jbPrices, jbRulesets);
+
+        jbMultiTerminal = new JBMultiTerminal(
+            jbFeelessAddresses,
+            jbPermissions,
+            jbProjects,
+            jbSplits,
+            jbTerminalStore,
+            jbTokens,
+            PERMIT2,
+            trustedForwarder
+        );
+    }
+
+    /// @dev Launch a JB project that accepts `acceptedToken` via the multi terminal.
+    function _launchProject(address acceptedToken, uint8 decimals) internal returns (uint256 projectId) {
+        JBRulesetMetadata memory metadata = JBRulesetMetadata({
+            reservedPercent: 0,
+            cashOutTaxRate: 0,
+            baseCurrency: uint32(uint160(acceptedToken)),
+            pausePay: false,
+            pauseCreditTransfers: false,
+            allowOwnerMinting: false,
+            allowSetCustomToken: false,
+            allowTerminalMigration: false,
+            allowSetTerminals: false,
+            allowSetController: false,
+            allowAddAccountingContext: true,
+            allowAddPriceFeed: false,
+            ownerMustSendPayouts: false,
+            holdFees: false,
+            useTotalSurplusForCashOuts: false,
+            useDataHookForPay: false,
+            useDataHookForCashOut: false,
+            dataHook: address(0),
+            metadata: 0
+        });
+
+        JBRulesetConfig[] memory rulesetConfigs = new JBRulesetConfig[](1);
+        rulesetConfigs[0].mustStartAtOrAfter = 0;
+        rulesetConfigs[0].duration = 0;
+        rulesetConfigs[0].weight = 1_000_000e18; // 1M tokens per unit of currency
+        rulesetConfigs[0].weightCutPercent = 0;
+        rulesetConfigs[0].approvalHook = IJBRulesetApprovalHook(address(0));
+        rulesetConfigs[0].metadata = metadata;
+        rulesetConfigs[0].splitGroups = new JBSplitGroup[](0);
+        rulesetConfigs[0].fundAccessLimitGroups = new JBFundAccessLimitGroup[](0);
+
+        JBAccountingContext[] memory tokensToAccept = new JBAccountingContext[](1);
+        tokensToAccept[0] =
+            JBAccountingContext({token: acceptedToken, decimals: decimals, currency: uint32(uint160(acceptedToken))});
+
+        JBTerminalConfig[] memory terminalConfigs = new JBTerminalConfig[](1);
+        terminalConfigs[0] = JBTerminalConfig({terminal: jbMultiTerminal, accountingContextsToAccept: tokensToAccept});
+
+        projectId = jbController.launchProjectFor({
+            owner: multisig,
+            projectUri: "test-project",
+            rulesetConfigurations: rulesetConfigs,
+            terminalConfigurations: terminalConfigs,
+            memo: ""
+        });
+    }
+}