@bananapus/router-terminal-v6 0.0.32 → 0.0.34

package/README.md

@@ -91,8 +91,8 @@ npm install @bananapus/router-terminal-v6
 
 ```bash
 npm install
-forge build
-forge test
+forge build --deny notes
+forge test --deny notes
 ```
 
 Useful scripts:

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-router-terminal-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/Deploy.s.sol",
+    "script/helpers/",
+    "src/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -17,16 +26,17 @@
     "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.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",
-    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#0.8",
-    "@uniswap/v4-core": "^1.0.0"
+    "@bananapus/buyback-hook-v6": "0.0.36",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@bananapus/univ4-router-v6": "0.0.22",
+    "@openzeppelin/contracts": "5.6.1",
+    "@uniswap/permit2": "github:Uniswap/permit2#cc56ad0f3439c502c246fc5cfcc3db92bb8b7219",
+    "@uniswap/v3-core": "github:Uniswap/v3-core#6562c52e8f75f0c10f9deaf44861847585fc8129",
+    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#b325bb0905d922ae61fcc7df85ee802e8df5e96c",
+    "@uniswap/v4-core": "1.0.2"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/src/JBPayRouteResolver.sol

@@ -9,8 +9,9 @@ import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataRes
 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 {mulDiv} from "@prb/math/src/Common.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";
@@ -273,8 +274,17 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
                 continue;
             }
 
-            // Decode only the minimum token-count commitments needed to score the buyback-enhanced preview.
-            (,,,,,,,,,, uint256 minimumBeneficiaryTokenCount, uint256 minimumReservedTokenCount,) = abi.decode(
+            // Decode the buyback hook's routing metadata. When the hook mints in `afterPayRecordedWith`, the terminal
+            // preview returns zero token counts and the router must score the route from the hook's commitments.
+            (
+                ,
+                uint256 amountToMintWith,
+                uint256 minimumSwapAmountOut,,,
+                uint256 tokenCountWithoutHook,,,,,
+                uint256 minimumBeneficiaryTokenCount,
+                uint256 minimumReservedTokenCount,
+                uint256 rawSwapQuote
+            ) = abi.decode(
                 specification.metadata,
                 (
                     bool,
@@ -293,14 +303,44 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
                 )
             );
 
-            // Keep whichever decoded hook commitment implies the stronger user-visible preview outcome.
-            if (
-                minimumBeneficiaryTokenCount > effectiveBeneficiaryTokenCount
-                    || (minimumBeneficiaryTokenCount == effectiveBeneficiaryTokenCount
-                        && minimumReservedTokenCount > effectiveReservedTokenCount)
-            ) {
-                effectiveBeneficiaryTokenCount = minimumBeneficiaryTokenCount;
-                effectiveReservedTokenCount = minimumReservedTokenCount;
+            // The hook's beneficiary/reserved commitments are only for the AMM leg. If the hook leaves part of the
+            // payment to mint directly, estimate that direct-mint leg at the same issuance rate used for the swapped
+            // amount so the router compares a whole-route token count against ordinary terminal previews.
+            uint256 directMintTokenCount;
+            if (amountToMintWith != 0 && specification.amount != 0 && tokenCountWithoutHook != 0) {
+                directMintTokenCount =
+                    mulDiv({x: amountToMintWith, y: tokenCountWithoutHook, denominator: specification.amount});
+            }
+
+            // Score the executable floor first. This supports callers that only provide a minimum and no live quote.
+            (uint256 candidateBeneficiaryTokenCount, uint256 candidateReservedTokenCount) = _scaledPreviewPayTokenCounts({
+                tokenCount: minimumSwapAmountOut + directMintTokenCount,
+                referenceTokenCount: minimumSwapAmountOut,
+                referenceBeneficiaryTokenCount: minimumBeneficiaryTokenCount,
+                referenceReservedTokenCount: minimumReservedTokenCount
+            });
+            (effectiveBeneficiaryTokenCount, effectiveReservedTokenCount) = _strongerPreviewPayTokenCounts({
+                currentBeneficiaryTokenCount: effectiveBeneficiaryTokenCount,
+                currentReservedTokenCount: effectiveReservedTokenCount,
+                candidateBeneficiaryTokenCount: candidateBeneficiaryTokenCount,
+                candidateReservedTokenCount: candidateReservedTokenCount
+            });
+
+            // If the hook also surfaced a stronger live quote, score it too. This lets programmatic buyback routes win
+            // when the expected executable output is better than the conservative minimum.
+            if (rawSwapQuote > minimumSwapAmountOut) {
+                (candidateBeneficiaryTokenCount, candidateReservedTokenCount) = _scaledPreviewPayTokenCounts({
+                    tokenCount: rawSwapQuote + directMintTokenCount,
+                    referenceTokenCount: minimumSwapAmountOut,
+                    referenceBeneficiaryTokenCount: minimumBeneficiaryTokenCount,
+                    referenceReservedTokenCount: minimumReservedTokenCount
+                });
+                (effectiveBeneficiaryTokenCount, effectiveReservedTokenCount) = _strongerPreviewPayTokenCounts({
+                    currentBeneficiaryTokenCount: effectiveBeneficiaryTokenCount,
+                    currentReservedTokenCount: effectiveReservedTokenCount,
+                    candidateBeneficiaryTokenCount: candidateBeneficiaryTokenCount,
+                    candidateReservedTokenCount: candidateReservedTokenCount
+                });
             }
             unchecked {
                 ++i;
@@ -340,7 +380,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.
@@ -354,30 +396,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.
@@ -689,6 +708,45 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         return abi.decode(data, (IJBTerminal[]));
     }
 
+    /// @notice Scale a known beneficiary/reserved token split to a different total token count.
+    /// @param tokenCount The total token count being scored.
+    /// @param referenceTokenCount The total token count the reference split was computed from.
+    /// @param referenceBeneficiaryTokenCount The beneficiary share of the reference split.
+    /// @param referenceReservedTokenCount The reserved share of the reference split.
+    /// @return beneficiaryTokenCount The scaled beneficiary token count.
+    /// @return reservedTokenCount The scaled reserved token count.
+    function _scaledPreviewPayTokenCounts(
+        uint256 tokenCount,
+        uint256 referenceTokenCount,
+        uint256 referenceBeneficiaryTokenCount,
+        uint256 referenceReservedTokenCount
+    )
+        internal
+        pure
+        returns (uint256 beneficiaryTokenCount, uint256 reservedTokenCount)
+    {
+        // A zero candidate means there is no stronger route output to scale, so preserve the known reference split.
+        if (tokenCount == 0) {
+            return (referenceBeneficiaryTokenCount, referenceReservedTokenCount);
+        }
+
+        // Prefer the already-previewed beneficiary/reserved total because it includes the destination's reserve logic.
+        uint256 referenceTotal = referenceBeneficiaryTokenCount + referenceReservedTokenCount;
+
+        // Fall back to the original token count when previewed counts were unavailable but the hook reported a floor.
+        if (referenceTotal == 0) referenceTotal = referenceTokenCount;
+
+        // If both reference totals are zero, treat the whole candidate as beneficiary tokens so the route stays
+        // comparable instead of disappearing from scoring.
+        if (referenceTotal == 0) return (tokenCount, 0);
+
+        // Scale the beneficiary share proportionally from the reference split to the candidate total being scored.
+        beneficiaryTokenCount = mulDiv({x: tokenCount, y: referenceBeneficiaryTokenCount, denominator: referenceTotal});
+
+        // Assign the residual to reserved tokens so rounding cannot lose supply during route comparison.
+        reservedTokenCount = tokenCount - beneficiaryTokenCount;
+    }
+
     /// @notice Resolve whether the current route input should first be treated as a project-token cashout source.
     /// @param router The router terminal whose project-token lookup should be used.
     /// @param tokenIn The current route input token.
@@ -719,6 +777,39 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         }
     }
 
+    /// @notice Choose the stronger preview outcome using beneficiary tokens first and reserved tokens as a tie-break.
+    /// @param currentBeneficiaryTokenCount The beneficiary token count from the strongest route so far.
+    /// @param currentReservedTokenCount The reserved token count from the strongest route so far.
+    /// @param candidateBeneficiaryTokenCount The beneficiary token count from the candidate route.
+    /// @param candidateReservedTokenCount The reserved token count from the candidate route.
+    /// @return beneficiaryTokenCount The beneficiary token count to keep.
+    /// @return reservedTokenCount The reserved token count to keep.
+    function _strongerPreviewPayTokenCounts(
+        uint256 currentBeneficiaryTokenCount,
+        uint256 currentReservedTokenCount,
+        uint256 candidateBeneficiaryTokenCount,
+        uint256 candidateReservedTokenCount
+    )
+        internal
+        pure
+        returns (uint256 beneficiaryTokenCount, uint256 reservedTokenCount)
+    {
+        // Prefer the route that gives the beneficiary more tokens, since that is the user's primary output.
+        if (
+            candidateBeneficiaryTokenCount > currentBeneficiaryTokenCount
+                || (
+                    // When beneficiary output ties, keep the route that also mints more reserved tokens.
+                    candidateBeneficiaryTokenCount == currentBeneficiaryTokenCount
+                    && candidateReservedTokenCount > currentReservedTokenCount
+                )
+        ) {
+            return (candidateBeneficiaryTokenCount, candidateReservedTokenCount);
+        }
+
+        // Keep the current winner when the candidate does not improve beneficiary output or the reserved tie-break.
+        return (currentBeneficiaryTokenCount, currentReservedTokenCount);
+    }
+
     /// @notice Resolve the usable primary terminal for a discovered candidate token.
     /// @param router The router whose circular-terminal rule should be applied.
     /// @param directory The directory used to resolve primary terminals.

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";
@@ -74,6 +75,7 @@ contract JBRouterTerminal is
     error JBRouterTerminal_AmountOverflow(uint256 amount);
     error JBRouterTerminal_CallerNotPool(address caller);
     error JBRouterTerminal_CallerNotPoolManager(address caller);
+    error JBRouterTerminal_CashOutDidNotDeliver(address sourceToken, address tokenToReclaim, uint256 cashOutCount);
     error JBRouterTerminal_CashOutLoopLimit();
     error JBRouterTerminal_InsufficientTwapHistory();
     error JBRouterTerminal_NoCashOutPath(uint256 sourceProjectId, uint256 destProjectId);
@@ -356,11 +358,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 +372,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 +430,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.
@@ -456,7 +450,10 @@ contract JBRouterTerminal is
             amountOut = uint256(uint128(delta0));
         }
 
-        if (amountOut < minAmountOut) revert JBRouterTerminal_SlippageExceeded(amountOut, minAmountOut);
+        // Enforce the caller's V4 minimum against the realized delta before settling/taking pool balances.
+        if (amountOut < minAmountOut) {
+            revert JBRouterTerminal_SlippageExceeded({amountOut: amountOut, minAmountOut: minAmountOut});
+        }
 
         // Settle input (pay what we owe to the PoolManager).
         Currency inputCurrency = zeroForOne ? key.currency0 : key.currency1;
@@ -812,15 +809,13 @@ contract JBRouterTerminal is
                 continue;
             }
 
-            // Decode only the fields needed to determine the user-visible sell-side output implied by the hook.
-            (uint256 minimumSwapAmountOut,,,,,, uint256 rawSwapQuote) =
+            // Decode only the buyback field used for route scoring. `minimumSwapAmountOut` is executable because the
+            // hook will enforce it; the later raw quote word is diagnostic and can overstate what execution can prove.
+            (uint256 minimumSwapAmountOut,,,,,,) =
                 abi.decode(specification.metadata, (uint256, uint256, uint256, int24, uint128, PoolId, uint256));
 
-            // Prefer the raw quote when present, otherwise fall back to the hook's minimum swap commitment.
-            uint256 quotedAmount = rawSwapQuote != 0 ? rawSwapQuote : minimumSwapAmountOut;
-
-            // Keep whichever understood hook quote implies the strongest previewed cash-out output.
-            if (quotedAmount > effectiveAmount) effectiveAmount = quotedAmount;
+            // Keep whichever understood executable hook commitment implies the strongest cash-out output.
+            if (minimumSwapAmountOut > effectiveAmount) effectiveAmount = minimumSwapAmountOut;
 
             unchecked {
                 ++i;
@@ -994,13 +989,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 +1029,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.
@@ -1208,26 +1199,40 @@ contract JBRouterTerminal is
                 sourceProjectId: sourceProjectId, destProjectId: destProjectId, preferredToken: preferredToken
             });
 
+            uint256 cashOutCount = amount;
             uint256 balanceBefore = _balanceOf({token: tokenToReclaim, account: address(this)});
 
             // 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: ""
             });
 
+            // Measure the reclaimed-token balance delta so fee-on-transfer behavior cannot fake delivery.
             amount = _balanceOf({token: tokenToReclaim, account: address(this)}) - balanceBefore;
-            if (amount < minTokensReclaimed) revert JBRouterTerminal_SlippageExceeded(amount, minTokensReclaimed);
+
+            // A non-zero cashout that delivers no reclaim tokens means this hop cannot safely continue.
+            if (cashOutCount != 0 && amount == 0) {
+                revert JBRouterTerminal_CashOutDidNotDeliver({
+                    sourceToken: token, tokenToReclaim: tokenToReclaim, cashOutCount: cashOutCount
+                });
+            }
+
+            // Enforce the caller's first-hop reclaim floor against the actual balance delta received.
+            if (amount < minTokensReclaimed) {
+                revert JBRouterTerminal_SlippageExceeded({amountOut: amount, minAmountOut: minTokensReclaimed});
+            }
 
             // Clear the reclaim minimum after the first hop.
             // Multi-hop routes can change token units between hops, so there is no sound generic way to rescale a
@@ -1384,7 +1389,9 @@ contract JBRouterTerminal is
 
         // Enforce slippage protection via realized output vs minimum acceptable output.
         // This is strictly more correct than sqrtPriceLimitX96 (which conflates marginal and average price).
-        if (amountOut < minAmountOut) revert JBRouterTerminal_SlippageExceeded(amountOut, minAmountOut);
+        if (amountOut < minAmountOut) {
+            revert JBRouterTerminal_SlippageExceeded({amountOut: amountOut, minAmountOut: minAmountOut});
+        }
     }
 
     /// @notice Execute a swap through a V4 pool via PoolManager.unlock().
@@ -2343,9 +2350,12 @@ contract JBRouterTerminal is
                 // An OOB access in the try-success block panics and is NOT caught by catch{}.
                 if (tickCumulatives.length >= 2) {
                     // Derive the arithmetic mean tick: (cumulative_now - cumulative_start) / elapsed_seconds.
-                    // forge-lint: disable-next-line(unsafe-typecast)
                     int56 tickDelta = tickCumulatives[1] - tickCumulatives[0];
+                    // The TWAP window is a small protocol constant that fits in int32 and int56.
+                    // forge-lint: disable-next-line(unsafe-typecast)
                     int56 period = int56(int32(_TWAP_WINDOW));
+                    // The cumulative tick values come from Uniswap observations, whose average tick is int24-bounded.
+                    // forge-lint: disable-next-line(unsafe-typecast)
                     tick = int24(tickDelta / period);
                     // Round towards negative infinity for negative ticks (Uniswap convention).
                     if (tickDelta < 0 && (tickDelta % period != 0)) tick--;
@@ -2576,7 +2586,9 @@ contract JBRouterTerminal is
             });
 
             // Enforce the caller's minimum reclaim amount only on the first hop.
-            if (amount < minTokensReclaimed) revert JBRouterTerminal_SlippageExceeded(amount, minTokensReclaimed);
+            if (amount < minTokensReclaimed) {
+                revert JBRouterTerminal_SlippageExceeded({amountOut: amount, minAmountOut: minTokensReclaimed});
+            }
 
             // Clear the reclaim minimum after the first hop because later hops may operate in different token units.
             minTokensReclaimed = 0;
@@ -2632,6 +2644,8 @@ contract JBRouterTerminal is
             metadata: ""
         });
 
+        // Deployment config makes this router a feeless cash-out beneficiary, so previews use the terminal's raw
+        // reclaim amount and avoid carrying fee-discovery bytecode in the router.
         reclaimAmount = _effectivePreviewCashOutAmount(reclaimAmount, hookSpecifications);
     }
 

package/src/JBRouterTerminalRegistry.sol

@@ -226,6 +226,13 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         return super._contextSuffixLength();
     }
 
+    /// @notice Prevent the registry from forwarding straight back into its immediate caller.
+    /// @param terminal The terminal the registry is about to forward into.
+    function _enforceNoCircularForward(IJBTerminal terminal) internal view {
+        // Reject immediate caller cycles so router -> registry -> same router cannot recurse indefinitely.
+        if (msg.sender == address(terminal)) revert JBRouterTerminalRegistry_CircularForward(terminal);
+    }
+
     /// @notice The calldata. Preferred to use over `msg.data`.
     /// @return calldata The `msg.data` of this call.
     function _msgData() internal view override(ERC2771Context, Context) returns (bytes calldata) {
@@ -238,6 +245,29 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         return ERC2771Context._msgSender();
     }
 
+    /// @notice Reject terminal choices that would forward the project back into this registry.
+    /// @param projectId The project whose forwarding target is being validated.
+    /// @param terminal The terminal being configured or locked.
+    function _requireNonCircularTerminalFor(uint256 projectId, IJBTerminal terminal) internal view {
+        // Reject direct self-selection so the registry cannot forward a project to itself.
+        if (address(terminal) == address(this)) revert JBRouterTerminalRegistry_CircularForward(terminal);
+
+        // Externally owned accounts cannot implement `terminalOf`, so there is no forwarding route to inspect.
+        if (address(terminal).code.length == 0) return;
+
+        // If the candidate is another forwarding terminal, ask where this project would end up.
+        try IJBForwardingTerminal(address(terminal)).terminalOf({projectId: projectId}) returns (
+            IJBTerminal downstreamTerminal
+        ) {
+            // Reject one-hop forwarding cycles that bounce this project back into the registry.
+            if (address(downstreamTerminal) == address(this)) {
+                revert JBRouterTerminalRegistry_CircularForward(terminal);
+            }
+        } catch {
+            // Non-forwarding terminals are valid choices; failed interface probes should not block them.
+        }
+    }
+
     /// @notice Resolve the effective terminal for a project, falling back to the default terminal when unset.
     /// @param projectId The project whose terminal should be resolved.
     /// @return terminal The project-specific terminal, or the default terminal if no override exists.
@@ -249,13 +279,6 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         if (terminal == IJBTerminal(address(0))) terminal = defaultTerminal;
     }
 
-    /// @notice Prevent the registry from forwarding straight back into its immediate caller.
-    /// @param terminal The terminal the registry is about to forward into.
-    function _enforceNoCircularForward(IJBTerminal terminal) internal view {
-        // Reject immediate caller cycles so router -> registry -> same router cannot recurse indefinitely.
-        if (msg.sender == address(terminal)) revert JBRouterTerminalRegistry_CircularForward(terminal);
-    }
-
     //*********************************************************************//
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
@@ -357,9 +380,7 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
 
     /// @notice Lock a terminal for a project.
     /// @dev Only the project's owner or an address with the `JBPermissionIds.SET_ROUTER_TERMINAL` permission can lock.
-    /// @dev Locking a circular or self-referential terminal (e.g. one that routes back to this registry) will
-    /// permanently brick routing for the project through this registry. Because locks are irreversible, callers must
-    /// verify that the terminal is valid and non-circular before locking.
+    /// @dev Circular or self-referential terminals are rejected before the irreversible lock is written.
     /// @param projectId The ID of the project to lock the terminal for.
     /// @param expectedTerminal The terminal the caller expects to lock. Prevents race conditions where the default
     /// changes between transaction submission and execution.
@@ -384,6 +405,9 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
             revert JBRouterTerminalRegistry_TerminalMismatch(terminal, expectedTerminal);
         }
 
+        // Reject a terminal that would make this irreversible lock forward back into the registry.
+        _requireNonCircularTerminalFor({projectId: projectId, terminal: terminal});
+
         hasLockedTerminal[projectId] = true;
 
         emit JBRouterTerminalRegistry_LockTerminal(projectId, _msgSender());
@@ -467,6 +491,7 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     /// @param terminal The terminal to set as the default.
     function setDefaultTerminal(IJBTerminal terminal) external onlyOwner {
         if (address(terminal) == address(0)) revert JBRouterTerminalRegistry_ZeroAddress();
+        if (address(terminal) == address(this)) revert JBRouterTerminalRegistry_CircularForward(terminal);
 
         defaultTerminal = terminal;
 
@@ -486,6 +511,9 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
 
         if (!isTerminalAllowed[terminal]) revert JBRouterTerminalRegistry_TerminalNotAllowed(terminal);
 
+        // Reject a terminal that would forward this project back into the registry before saving it.
+        _requireNonCircularTerminalFor({projectId: projectId, terminal: terminal});
+
         // Enforce permissions.
         _requirePermissionFrom({
             account: PROJECTS.ownerOf(projectId),

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;
+    }
+}