@bananapus/router-terminal-v6 0.0.33 → 0.0.35

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.33",
+  "version": "0.0.35",
   "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,13 +9,15 @@ 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 {JBForwardingCheck} from "./libraries/JBForwardingCheck.sol";
 import {IJBPayRoutePreviewer} from "./interfaces/IJBPayRoutePreviewer.sol";
 import {IJBPayRouteResolver} from "./interfaces/IJBPayRouteResolver.sol";
 import {IWETH9} from "./interfaces/IWETH9.sol";
 
-/// @notice Resolves the best pay route preview for `JBRouterTerminal`.
+/// @notice Evaluates every token a destination project accepts and returns the route that yields the most project
+/// tokens for the beneficiary, deployed as a helper to keep `JBRouterTerminal` within runtime size limits.
 contract JBPayRouteResolver is IJBPayRouteResolver {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -273,8 +275,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 +304,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;
@@ -538,8 +579,8 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @param amount The current route input amount.
     /// @param metadata Metadata that may include a cashout-source override.
     /// @param preferredToken The preferred token to target during any previewed cashout loop.
-    /// @return resolvedTerminal The terminal found by the previewed cashout loop, or address(0) if conversion should
-    /// continue. @return routedTokenIn The token that remains to be routed after the previewed cashout step.
+    /// @return resolvedTerminal The terminal found by the cashout loop, or address(0) if conversion continues.
+    /// @return routedTokenIn The token that remains to be routed after the previewed cashout step.
     /// @return routedAmountIn The amount of `routedTokenIn` that remains to be routed.
     function _previewRouteInputFromSource(
         IJBPayRoutePreviewer router,
@@ -668,6 +709,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.
@@ -698,6 +778,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

@@ -50,9 +50,9 @@ import {JBPayRouteResolver} from "./JBPayRouteResolver.sol";
 import {CashOutPathCandidates} from "./structs/CashOutPathCandidates.sol";
 import {PoolInfo} from "./structs/PoolInfo.sol";
 
-/// @notice The `JBRouterTerminal` accepts any token and dynamically discovers what token each destination project
-/// accepts, then routes the payment there — via direct forwarding, Uniswap swap, JB token cashout, or a combination.
-/// Supports both Uniswap V3 and V4 pools, choosing whichever offers better liquidity.
+/// @notice A universal payment terminal that accepts any token and automatically converts it into whatever token the
+/// destination project accepts. Routes payments via direct forwarding, Uniswap V3/V4 swaps, recursive JB token
+/// cashouts, or a combination — always selecting the path that yields the most project tokens for the beneficiary.
 /// @custom:benediction DEVS BENEDICAT ET PROTEGAT CONTRACTVS MEAM
 contract JBRouterTerminal is
     ERC2771Context,
@@ -75,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);
@@ -449,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;
@@ -805,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;
@@ -1197,6 +1199,7 @@ 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.
@@ -1216,8 +1219,20 @@ contract JBRouterTerminal is
                 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
@@ -1374,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().
@@ -1681,7 +1698,8 @@ contract JBRouterTerminal is
         if (_unwrapCurrency(currency) == address(0)) _wethDeposit(amount);
     }
 
-    /// @notice Transfers tokens.
+    /// @notice Transfer tokens from one address to another using direct approval, `safeTransfer`, or Permit2 as a
+    /// fallback.
     /// @param from The address to transfer tokens from.
     /// @param to The address to transfer tokens to.
     /// @param token The address of the token being transferred.
@@ -2333,9 +2351,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--;
@@ -2566,7 +2587,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;
@@ -2622,6 +2645,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

@@ -27,7 +27,8 @@ import {IJBForwardingTerminal} from "./interfaces/IJBForwardingTerminal.sol";
 import {IJBRouterTerminalRegistry} from "./interfaces/IJBRouterTerminalRegistry.sol";
 import {IJBPayerTracker} from "./interfaces/IJBPayerTracker.sol";
 
-/// @notice Lets projects pick, lock, and forward through a router terminal or a shared default router terminal.
+/// @notice A forwarding layer that lets each project choose which router terminal receives its payments, with an
+/// owner-managed default for projects that have not opted in. Projects can lock their choice to guarantee permanence.
 contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned, Ownable, ERC2771Context {
     // A library that adds default safety checks to ERC20 functionality.
     using SafeERC20 for IERC20;
@@ -154,9 +155,29 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         return terminal.accountingContextsOf(projectId);
     }
 
-    /// @notice Empty implementation to satisfy the interface. This terminal has no surplus.
-    /// @return currentSurplus Always returns 0 because the registry is only a forwarding layer.
-    function currentSurplusOf(uint256, address[] calldata, uint256, uint256) external pure override returns (uint256) {}
+    /// @notice Always returns 0 because the registry only forwards funds and does not hold project balances.
+    /// @param projectId Unused.
+    /// @param tokens Unused.
+    /// @param decimals Unused.
+    /// @param currency Unused.
+    /// @return currentSurplus Always 0.
+    function currentSurplusOf(
+        uint256 projectId,
+        address[] calldata tokens,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        pure
+        override
+        returns (uint256)
+    {
+        projectId;
+        tokens;
+        decimals;
+        currency;
+        return 0;
+    }
 
     /// @notice Preview a payment by forwarding the call to the terminal currently resolved for the project.
     /// @dev Uses the project-specific terminal when set, otherwise falls back to `defaultTerminal`.
@@ -226,6 +247,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 +266,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 +300,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 ---------------------- //
     //*********************************************************************//
@@ -271,13 +315,14 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         override
     {}
 
-    /// @notice Accept funds for a project and add them to the balance of the resolved terminal.
-    /// @param projectId The ID of the project for which funds are being accepted.
+    /// @notice Add funds to a project's balance by forwarding them through the project's resolved router terminal.
+    /// @dev Uses the project-specific terminal when set, otherwise falls back to `defaultTerminal`.
+    /// @param projectId The ID of the project receiving the balance addition.
     /// @param token The address of the token being paid in.
     /// @param amount The amount of tokens being paid in.
-    /// @param shouldReturnHeldFees A boolean to indicate whether held fees should be returned.
+    /// @param shouldReturnHeldFees Whether held fees should be returned based on the amount added.
     /// @param memo A memo to pass along to the emitted event.
-    /// @param metadata Bytes in `JBMetadataResolver`'s format.
+    /// @param metadata Bytes in `JBMetadataResolver`'s format (may include `permit2` allowance data).
     // slither-disable-next-line reentrancy-benign,reentrancy-eth
     function addToBalanceOf(
         uint256 projectId,
@@ -327,8 +372,8 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         originalPayer = previousPayer;
     }
 
-    /// @notice Allow a terminal.
-    /// @dev Only the owner can allow a terminal.
+    /// @notice Add a terminal to the allowlist so projects can select it as their router.
+    /// @dev Only the registry owner can call this.
     /// @param terminal The terminal to allow.
     function allowTerminal(IJBTerminal terminal) external onlyOwner {
         // Mark the terminal as selectable for future project-level configuration.
@@ -338,8 +383,8 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         emit JBRouterTerminalRegistry_AllowTerminal(terminal, _msgSender());
     }
 
-    /// @notice Disallow a terminal.
-    /// @dev Only the owner can disallow a terminal. Cannot disallow the current default terminal — call
+    /// @notice Remove a terminal from the allowlist so no new projects can select it.
+    /// @dev Only the registry owner can call this. Cannot disallow the current default terminal — call
     /// `setDefaultTerminal` to change the default first.
     /// @param terminal The terminal to disallow.
     function disallowTerminal(IJBTerminal terminal) external onlyOwner {
@@ -355,11 +400,9 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         emit JBRouterTerminalRegistry_DisallowTerminal(terminal, _msgSender());
     }
 
-    /// @notice Lock a terminal for a project.
+    /// @notice Permanently lock a project's router terminal choice so it can never be changed again.
     /// @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,31 +427,46 @@ 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());
     }
 
-    /// @notice Empty implementation to satisfy the interface.
+    /// @notice Always returns 0 because the registry holds no project balances to migrate.
+    /// @param projectId Unused.
+    /// @param token Unused.
+    /// @param to Unused.
+    /// @return balance Always 0.
     function migrateBalanceOf(
         uint256 projectId,
         address token,
         IJBTerminal to
     )
         external
+        pure
         override
-        returns (uint256 balance)
-    {}
+        returns (uint256)
+    {
+        projectId;
+        token;
+        to;
+        return 0;
+    }
 
-    /// @notice Pay a project by forwarding the payment to the resolved terminal.
+    /// @notice Pay a project by accepting the caller's tokens and forwarding them to the project's resolved router
+    /// terminal.
+    /// @dev Uses the project-specific terminal when set, otherwise falls back to `defaultTerminal`.
     /// @param projectId The ID of the project being paid.
     /// @param token The address of the token being paid in.
     /// @param amount The amount of tokens being paid in.
-    /// @param beneficiary The beneficiary address to pass along.
+    /// @param beneficiary The address that will receive any project tokens minted by the destination.
     /// @param minReturnedTokens The minimum number of project tokens expected in return.
     /// @param memo A memo to pass along to the emitted event.
-    /// @param metadata Bytes in `JBMetadataResolver`'s format.
-    /// @return result The number of tokens received.
+    /// @param metadata Bytes in `JBMetadataResolver`'s format (may include `permit2` allowance data).
+    /// @return result The number of project tokens minted for the beneficiary.
     // slither-disable-next-line reentrancy-benign,reentrancy-eth
     function pay(
         uint256 projectId,
@@ -462,11 +520,12 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         originalPayer = previousPayer;
     }
 
-    /// @notice Set the default terminal.
-    /// @dev Only the owner can set the default terminal.
+    /// @notice Change the registry-wide default terminal that all projects without an explicit override will use.
+    /// @dev Only the registry owner can call this. Automatically allowlists the new default.
     /// @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;
 
@@ -476,7 +535,7 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         emit JBRouterTerminalRegistry_SetDefaultTerminal(terminal, _msgSender());
     }
 
-    /// @notice Set the terminal for a project.
+    /// @notice Choose which router terminal a project's payments are forwarded through.
     /// @dev Only the project's owner or an address with the `JBPermissionIds.SET_ROUTER_TERMINAL` permission can set.
     /// @param projectId The ID of the project to set the terminal for.
     /// @param terminal The terminal to set for the project.
@@ -486,6 +545,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),
@@ -571,7 +633,8 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         return 0;
     }
 
-    /// @notice Transfers tokens.
+    /// @notice Transfer tokens from one address to another using direct approval, `safeTransfer`, or Permit2 as a
+    /// fallback.
     /// @param from The address to transfer tokens from.
     /// @param to The address to transfer tokens to.
     /// @param token The address of the token being transferred.