@bananapus/router-terminal-v6 0.0.36 → 0.0.39

package/CHANGELOG.md

@@ -2,7 +2,25 @@
 
 ## Scope
 
-This file describes the verified change from `nana-swap-terminal-v5` to the current `nana-router-terminal-v6` repo.
+This file describes the verified change from `nana-swap-terminal-v5` to the current `nana-router-terminal-v6` repo. In-v6 behavior changes that have semantic implications for integrators are also captured here.
+
+## In-v6 changes
+
+### Threshold-protected `setDefaultTerminal`
+
+The registry owner's `setDefaultTerminal(IJBTerminal)` call now applies only to projects created AFTER the call. Existing projects without an explicit `setTerminalFor` override keep resolving to the default that was current when their project-ID cohort was active. The outgoing default is snapshotted into an append-only `_defaultTerminalHistory` array on every `setDefaultTerminal` call.
+
+- New view: `defaultTerminalFor(uint256 projectId)` returns the default applicable to a specific project (walks history if the project is in a legacy cohort).
+- New view: `defaultTerminalProjectIdThreshold()` returns `PROJECTS.count()` at the time of the most recent `setDefaultTerminal`.
+- New views: `defaultTerminalHistoryAt(uint256 index)` and `defaultTerminalHistoryLength()` expose the snapshot history.
+- New struct: `DefaultTerminalSegment { uint256 maxProjectId; IJBTerminal terminal; }` in `src/structs/`.
+- `lockTerminalFor` now snapshots the *cohort-correct* default into `_terminalOf` (via `_defaultTerminalFor(projectId)`) when locking a project that has no explicit terminal — not the current registry-wide default.
+
+Indexer impact: read `defaultTerminalFor(projectId)` rather than `defaultTerminal()` when computing the effective default for any specific project.
+
+Admin impact: the registry owner can no longer silently reroute payments for already-deployed projects by changing the default. See `ADMINISTRATION.md` for the updated boundary description.
+
+
 
 ## Current v6 surface
 

package/README.md

@@ -21,7 +21,7 @@ It can route through:
 - Uniswap V3 or V4 swaps
 - recursive Juicebox token cash outs when the input is itself a project token
 
-Projects can use the registry to choose, and optionally lock, a project-specific router terminal or fall back to the registry's default terminal.
+Projects can use the registry to choose, and optionally lock, a project-specific router terminal or fall back to the registry's default. The default is cohort-pinned: when the registry owner calls `setDefaultTerminal` again, the new default applies only to projects created after that call; existing projects continue to resolve against the default that was current when their ID range was active (see `defaultTerminalFor(projectId)`).
 
 Use this repo when UX requires "pay with many tokens, settle into the right one." Do not use it as a replacement for downstream terminal accounting or as an authoritative decimal source.
 
@@ -78,8 +78,8 @@ That separation is why a successful route can still end in downstream terminal b
 1. `test/RouterTerminal.t.sol`
 2. `test/RouterTerminalPreviewFork.t.sol`
 3. `test/RouterTerminalCashOutFork.t.sol`
-4. `test/audit/PreviewPrimaryTerminalMismatch.t.sol`
-5. `test/codex/CashOutCircularPrimaryTerminal.t.sol`
+4. `test/regression/PreviewPrimaryTerminalMismatch.t.sol`
+5. `test/regression/CashOutCircularPrimaryTerminal.t.sol`
 
 ## Install
 
@@ -114,7 +114,7 @@ src/
   libraries/
   structs/
 test/
-  unit, fork, registry, audit, invariant, and regression coverage
+  unit, fork, registry, review, invariant, and regression coverage
 script/
   Deploy.s.sol
   helpers/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.36",
+  "version": "0.0.39",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,10 +26,10 @@
     "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.36",
-    "@bananapus/core-v6": "0.0.39",
-    "@bananapus/permission-ids-v6": "0.0.22",
-    "@bananapus/univ4-router-v6": "0.0.22",
+    "@bananapus/buyback-hook-v6": "^0.0.36",
+    "@bananapus/core-v6": "^0.0.48",
+    "@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",

package/references/operations.md

@@ -28,5 +28,5 @@
 - [`test/RouterTerminalRegistry.t.sol`](../test/RouterTerminalRegistry.t.sol) for registry rules.
 - [`test/RouterTerminalERC2771.t.sol`](../test/RouterTerminalERC2771.t.sol) for trusted-forwarder behavior.
 - [`test/RouterTerminalSandwichFork.t.sol`](../test/RouterTerminalSandwichFork.t.sol) and [`test/RouterTerminalFeeCashOutFork.t.sol`](../test/RouterTerminalFeeCashOutFork.t.sol) for adversarial routing conditions.
-- [`test/audit/LeftoverRefund.t.sol`](../test/audit/LeftoverRefund.t.sol), [`test/audit/PreviewPrimaryTerminalMismatch.t.sol`](../test/audit/PreviewPrimaryTerminalMismatch.t.sol), and [`test/codex/CashOutCircularPrimaryTerminal.t.sol`](../test/codex/CashOutCircularPrimaryTerminal.t.sol) for the route-selection and refund traps most likely to regress.
-- [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for pinned edge cases.
+- [`test/regression/LeftoverRefund.t.sol`](../test/regression/LeftoverRefund.t.sol), [`test/regression/PreviewPrimaryTerminalMismatch.t.sol`](../test/regression/PreviewPrimaryTerminalMismatch.t.sol), and [`test/regression/CashOutCircularPrimaryTerminal.t.sol`](../test/regression/CashOutCircularPrimaryTerminal.t.sol) for the route-selection and refund traps most likely to regress.
+- [`test/TestRegressionGaps.sol`](../test/TestRegressionGaps.sol) for pinned edge cases.

package/references/runtime.md

@@ -31,4 +31,4 @@
 - [`test/RouterTerminalCashOutFork.t.sol`](../test/RouterTerminalCashOutFork.t.sol) and [`test/RouterTerminalCreditCashout.t.sol`](../test/RouterTerminalCreditCashout.t.sol) for cash-out routing.
 - [`test/RouterTerminalReentrancy.t.sol`](../test/RouterTerminalReentrancy.t.sol) for callback and reentrancy-sensitive behavior.
 - [`test/RouterTerminalFork.t.sol`](../test/RouterTerminalFork.t.sol), [`test/RouterTerminalMultihopFork.t.sol`](../test/RouterTerminalMultihopFork.t.sol), and [`test/invariant/RouterTerminalInvariant.t.sol`](../test/invariant/RouterTerminalInvariant.t.sol) for live routing assumptions.
-- [`test/codex/CashOutCircularPrimaryTerminal.t.sol`](../test/codex/CashOutCircularPrimaryTerminal.t.sol), [`test/codex/CashOutFallbackPrefersRecursiveLoop.t.sol`](../test/codex/CashOutFallbackPrefersRecursiveLoop.t.sol), [`test/audit/LeftoverRefund.t.sol`](../test/audit/LeftoverRefund.t.sol), and [`test/audit/PreviewPrimaryTerminalMismatch.t.sol`](../test/audit/PreviewPrimaryTerminalMismatch.t.sol) for the misdiagnosis-prone edge cases.
+- [`test/regression/CashOutCircularPrimaryTerminal.t.sol`](../test/regression/CashOutCircularPrimaryTerminal.t.sol), [`test/regression/CashOutFallbackPrefersRecursiveLoop.t.sol`](../test/regression/CashOutFallbackPrefersRecursiveLoop.t.sol), [`test/regression/LeftoverRefund.t.sol`](../test/regression/LeftoverRefund.t.sol), and [`test/regression/PreviewPrimaryTerminalMismatch.t.sol`](../test/regression/PreviewPrimaryTerminalMismatch.t.sol) for the misdiagnosis-prone edge cases.

package/src/JBPayRouteResolver.sol

@@ -32,18 +32,18 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @notice The directory storing project terminal relationships, cached from the router at construction time.
     IJBDirectory public immutable DIRECTORY;
 
-    /// @notice The wrapped native token, cached from the router at construction time.
-    IWETH9 public immutable WETH;
+    /// @notice The ERC-20 wrapper for the chain's native token, cached from the router at construction time.
+    IWETH9 public immutable WRAPPED_NATIVE_TOKEN;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
     /// @param directory The directory storing project terminal relationships.
-    /// @param weth The wrapped native token used for router token normalization.
+    /// @param weth The ERC-20 wrapper for the chain's native token, used for router token normalization.
     constructor(IJBDirectory directory, IWETH9 weth) {
         DIRECTORY = directory;
-        WETH = weth;
+        WRAPPED_NATIVE_TOKEN = weth;
     }
 
     //*********************************************************************//
@@ -56,7 +56,6 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @param terminals The terminal list already fetched for the destination project.
     /// @return tokens The unique candidate tokens that can be paid into the project.
     /// @return count The number of populated entries in `tokens`.
-    // slither-disable-next-line calls-loop
     function _candidatePayRouteTokens(
         IJBDirectory directory,
         uint256 projectId,
@@ -145,7 +144,6 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @param tokenIn The input token to find a route from.
     /// @return tokenOut The best accepted token found.
     /// @return destTerminal The terminal that accepts `tokenOut`.
-    // slither-disable-next-line calls-loop
     function _discoverAcceptedToken(
         IJBPayRoutePreviewer router,
         uint256 projectId,
@@ -188,7 +186,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
                 // Pull the candidate token out of the accounting context being inspected.
                 address candidateToken = contexts[j].token;
 
-                // Normalize the candidate so native-vs-WETH comparisons behave the same as the router.
+                // Normalize the candidate so native-vs-wrapped comparisons behave the same as the router.
                 address normalizedCandidate = _normalizedTokenOf(candidateToken);
 
                 // Skip tokens that are equivalent to the input token because they do not require route discovery.
@@ -364,8 +362,6 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         pure
         returns (bool exists, bytes memory data)
     {
-        // slither-disable-next-line unused-return
-        // slither-disable-next-line unused-return
         return JBMetadataResolver.getDataFor({id: JBMetadataResolver.getId(key, address(router)), metadata: metadata});
     }
 
@@ -377,15 +373,15 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         // Treat exact-token matches as the same routing asset without extra normalization work.
         if (tokenA == tokenB) return true;
 
-        // Otherwise compare normalized representations so ETH and WETH share one routing identity.
+        // Otherwise compare normalized representations so native and wrapped native tokens share one routing identity.
         return _normalizedTokenOf(tokenA) == _normalizedTokenOf(tokenB);
     }
 
     /// @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 router The router whose preview path to evaluate.
+    /// @param projectId The project to resolve forwarding terminal for.
     /// @param terminal The terminal that would receive the previewed route.
     /// @return isCircular A flag indicating whether `terminal` is the router itself or forwards back into it.
     function _isCircularTerminal(
@@ -404,14 +400,14 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @param token The token to normalize.
     /// @return normalizedToken The normalized token address.
     function _normalizedTokenOf(address token) internal view returns (address normalizedToken) {
-        return token == JBConstants.NATIVE_TOKEN ? address(WETH) : token;
+        return token == JBConstants.NATIVE_TOKEN ? address(WRAPPED_NATIVE_TOKEN) : token;
     }
 
     /// @notice Preview the amount that would be routed into a specific destination token.
-    /// @param router The router terminal whose preview helpers should be used.
+    /// @param router The router terminal whose preview helpers to use.
     /// @param destProjectId The destination project the router is trying to pay.
     /// @param tokenIn The token currently available to route.
-    /// @param amount The amount of `tokenIn` being previewed.
+    /// @param amount The amount of `tokenIn` to preview.
     /// @param metadata Metadata that may encode cashout-source and route-token overrides.
     /// @param tokenOut The preferred destination token to preview.
     /// @return routedTokenIn The token that would actually be provided to the destination terminal.
@@ -454,11 +450,11 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Preview a pay route for a specific destination token.
-    /// @param router The router terminal whose preview helpers should be used.
+    /// @param router The router terminal whose preview helpers to use.
     /// @param projectId The destination project that would receive the payment.
     /// @param tokenIn The token currently available to route.
-    /// @param amount The amount of `tokenIn` being previewed.
-    /// @param beneficiary The address whose beneficiary token count is being measured.
+    /// @param amount The amount of `tokenIn` to preview.
+    /// @param beneficiary The address to measure beneficiary token count for.
     /// @param metadata Metadata forwarded into both the routing preview and terminal preview.
     /// @param tokenOut The candidate destination token to preview.
     /// @param destTerminal The terminal that accepts `tokenOut` for the destination project.
@@ -526,10 +522,10 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Preview the fallback route that would be used when no candidate token can be scored directly.
-    /// @param router The router terminal whose preview helpers should be used.
-    /// @param destProjectId The destination project being paid.
+    /// @param router The router terminal whose preview helpers to use.
+    /// @param destProjectId The destination project to pay.
     /// @param tokenIn The token currently available to route.
-    /// @param amount The amount of `tokenIn` being previewed.
+    /// @param amount The amount of `tokenIn` to preview.
     /// @param metadata Metadata forwarded into preview helpers.
     /// @return destTerminal The terminal the router would use.
     /// @return tokenOut The token `destTerminal` would receive.
@@ -573,7 +569,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Preview how the current route input would change after cashing out a project-token source if needed.
-    /// @param router The router terminal whose preview helpers should be used.
+    /// @param router The router terminal whose preview helpers to use.
     /// @param destProjectId The destination project the route is trying to reach.
     /// @param tokenIn The current route input token.
     /// @param amount The current route input amount.
@@ -602,7 +598,6 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         if (sourceProjectId == 0) return (resolvedTerminal, tokenIn, amount);
 
         // Otherwise reuse the router's own preview cashout loop so preview and execution stay aligned.
-        // slither-disable-next-line unused-return
         return router.previewCashOutLoopOf({
             destProjectId: destProjectId,
             token: tokenIn,
@@ -614,9 +609,9 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Resolve what output token a project accepts for a given input token.
-    /// @param router The router whose view helpers should be used.
-    /// @param projectId The destination project being paid.
-    /// @param tokenIn The input token being routed.
+    /// @param router The router whose view helpers to use.
+    /// @param projectId The destination project to pay.
+    /// @param tokenIn The input token to route.
     /// @param metadata Metadata forwarded into route-token resolution.
     /// @return tokenOut The token the project accepts.
     /// @return destTerminal The terminal that accepts `tokenOut`.
@@ -647,7 +642,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
                 address(destTerminal) == address(0)
                     || _isCircularTerminal({router: router, projectId: projectId, terminal: destTerminal})
             ) {
-                revert JBRouterTerminal_NoRouteFound(projectId, tokenIn);
+                revert JBRouterTerminal_NoRouteFound({projectId: projectId, tokenIn: tokenIn});
             }
             return (tokenOut, destTerminal);
         }
@@ -663,8 +658,8 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         }
 
         // Then try the native-token and wrapped-native-token equivalent form before falling back to pool discovery.
-        if (tokenIn == JBConstants.NATIVE_TOKEN || tokenIn == address(WETH)) {
-            tokenOut = tokenIn == JBConstants.NATIVE_TOKEN ? address(WETH) : JBConstants.NATIVE_TOKEN;
+        if (tokenIn == JBConstants.NATIVE_TOKEN || tokenIn == address(WRAPPED_NATIVE_TOKEN)) {
+            tokenOut = tokenIn == JBConstants.NATIVE_TOKEN ? address(WRAPPED_NATIVE_TOKEN) : JBConstants.NATIVE_TOKEN;
             destTerminal = directory.primaryTerminalOf({projectId: projectId, token: tokenOut});
             if (
                 address(destTerminal) != address(0)
@@ -682,13 +677,13 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
             address(destTerminal) == address(0)
                 || _isCircularTerminal({router: router, projectId: projectId, terminal: destTerminal})
         ) {
-            revert JBRouterTerminal_NoRouteFound(projectId, tokenIn);
+            revert JBRouterTerminal_NoRouteFound({projectId: projectId, tokenIn: tokenIn});
         }
     }
 
     /// @notice Best-effort terminal lookup that degrades to an empty list if the directory call reverts.
     /// @param directory The directory storing project terminal relationships.
-    /// @param projectId The project whose terminals should be looked up.
+    /// @param projectId The project to look up terminals for.
     /// @return terminals The terminal list, or an empty list if the directory call failed.
     function _safeTerminalsOf(
         IJBDirectory directory,
@@ -710,7 +705,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Scale a known beneficiary/reserved token split to a different total token count.
-    /// @param tokenCount The total token count being scored.
+    /// @param tokenCount The total token count to score.
     /// @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.
@@ -812,9 +807,9 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice Resolve the usable primary terminal for a discovered candidate token.
-    /// @param router The router whose circular-terminal rule should be applied.
+    /// @param router The router whose circular-terminal rule to apply.
     /// @param directory The directory used to resolve primary terminals.
-    /// @param projectId The destination project being inspected.
+    /// @param projectId The destination project to inspect.
     /// @param candidateToken The discovered accepted token candidate.
     /// @return candidateTerminal The candidate token's primary terminal, or address(0) if unusable.
     function _usablePrimaryTerminalForCandidate(
@@ -828,7 +823,6 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         returns (IJBTerminal candidateTerminal)
     {
         // Resolve the primary terminal for the candidate token so fallback discovery agrees with preview/execution.
-        // slither-disable-next-line calls-loop
         candidateTerminal = directory.primaryTerminalOf({projectId: projectId, token: candidateToken});
 
         // Drop candidates whose primary terminal disappeared or would route straight back into the router.
@@ -845,7 +839,6 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     //*********************************************************************//
 
     /// @inheritdoc IJBPayRouteResolver
-    // slither-disable-next-line calls-loop
     function previewBestPayRoute(
         IJBPayRoutePreviewer router,
         uint256 projectId,
@@ -885,7 +878,7 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
                 address(destTerminal) == address(0)
                     || _isCircularTerminal({router: router, projectId: projectId, terminal: destTerminal})
             ) {
-                revert JBRouterTerminal_NoRouteFound(projectId, tokenIn);
+                revert JBRouterTerminal_NoRouteFound({projectId: projectId, tokenIn: tokenIn});
             }
 
             // Score the explicitly requested route directly instead of scanning every accepted token.
@@ -997,10 +990,10 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// `self.previewFallbackRoute(...)` so that a revert in the fallback path (e.g. a broken terminal or
     /// price feed) is caught instead of bricking the entire best-route preview.
     /// @dev This function should only be called by this contract itself — external callers have no reason to use it.
-    /// @param routePreviewer The router terminal whose preview helpers are used to simulate the route.
-    /// @param destProjectId The project being paid through the fallback route.
+    /// @param routePreviewer The router terminal whose preview helpers to use for simulating the route.
+    /// @param destProjectId The project to pay through the fallback route.
     /// @param tokenIn The token the payer is sending.
-    /// @param amountIn The amount of `tokenIn` being routed.
+    /// @param amountIn The amount of `tokenIn` to route.
     /// @param beneficiary The address that would receive minted project tokens.
     /// @param metadata Arbitrary bytes forwarded into route and terminal pay previews.
     /// @return destTerminal The terminal the fallback route would deliver funds to.
@@ -1055,11 +1048,11 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     }
 
     /// @notice External wrapper so candidate previews can be isolated with `try/catch`.
-    /// @param router The router terminal whose preview helpers should be used.
+    /// @param router The router terminal whose preview helpers to use.
     /// @param projectId The destination project that would receive the payment.
     /// @param tokenIn The token currently available to route.
-    /// @param amount The amount of `tokenIn` being previewed.
-    /// @param beneficiary The address whose beneficiary token count is being measured.
+    /// @param amount The amount of `tokenIn` to preview.
+    /// @param beneficiary The address to measure beneficiary token count for.
     /// @param metadata Metadata forwarded into both the routing preview and terminal preview.
     /// @param tokenOut The candidate destination token to preview.
     /// @param destTerminal The terminal that accepts `tokenOut` for the destination project.