@bananapus/router-terminal-v6 0.0.58 → 0.0.60

package/README.md

@@ -26,7 +26,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. 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)`).
+Projects can use the registry to choose, and optionally lock, a project-specific router terminal or fall back to the registry's default. The first `setDefaultTerminal` serves every project that already existed when it was called — including the canonical fee project (ID 1) — so those pre-existing projects can route tokens through the default. After that, 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.
 

package/package.json

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

package/src/JBRouterTerminal.sol

@@ -2,6 +2,7 @@
 pragma solidity 0.8.28;
 
 import {IJBCashOutTerminal} from "@bananapus/core-v6/src/interfaces/IJBCashOutTerminal.sol";
+import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermitTerminal} from "@bananapus/core-v6/src/interfaces/IJBPermitTerminal.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
@@ -78,6 +79,7 @@ contract JBRouterTerminal is
     error JBRouterTerminal_CashOutDidNotDeliver(address sourceToken, address tokenToReclaim, uint256 cashOutCount);
     error JBRouterTerminal_CashOutLoopLimit(uint256 maxIterations);
     error JBRouterTerminal_InsufficientTwapHistory(address pool, uint256 twapWindow, uint256 minTwapWindow);
+    error JBRouterTerminal_ManipulationResistantQuoteRequired(PoolId poolId);
     error JBRouterTerminal_NoCashOutPath(uint256 sourceProjectId, uint256 destProjectId);
     error JBRouterTerminal_NoLiquidity(address pool, PoolId poolId);
     error JBRouterTerminal_NoMsgValueAllowed(uint256 value);
@@ -190,6 +192,19 @@ contract JBRouterTerminal is
     // ---------------------- internal stored properties ----------------- //
     //*********************************************************************//
 
+    //*********************************************************************//
+    // ------------------- transient stored properties ------------------- //
+    //*********************************************************************//
+
+    /// @notice Transient flag: when set, a quote-less swap may NOT fall back to a manipulable spot price — if the
+    /// selected pool exposes no manipulation-resistant oracle (a vanilla V4 pool) and the caller supplied no `pay`
+    /// quote, `_getV4SpotQuote` reverts and the caller must provide a quote.
+    /// @dev Set true by `addToBalanceOf` (whose swap has no downstream `minReturnedTokens` backstop) and false by
+    /// `pay` (whose top-level `minReturnedTokens` guards the entire routed result end-to-end). Read at quote time,
+    /// which is synchronous and always precedes the swap's pool callbacks, so it reflects the originating entrypoint.
+    /// Off-chain previews leave it at its default (false), so estimates still resolve. Transient, so it auto-clears.
+    bool internal transient _strictSwapQuote;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -265,6 +280,11 @@ contract JBRouterTerminal is
         payable
         override
     {
+        // This leg settles via `addToBalanceOf`, which has no `minReturnedTokens` (or any downstream) backstop, so a
+        // quote-less swap must not silently price against a manipulable spot. Require a manipulation-resistant source
+        // (a canonical-hook V4 oracle, a V3 TWAP) or an explicit `pay` quote — see `_getV4SpotQuote`.
+        _strictSwapQuote = true;
+
         // Keep a reference to the terminal that will ultimately receive the routed funds.
         IJBTerminal destTerminal;
 
@@ -354,6 +374,10 @@ contract JBRouterTerminal is
         override
         returns (uint256 beneficiaryTokenCount)
     {
+        // The top-level `minReturnedTokens` guards the entire routed result end-to-end (a bad intermediate swap
+        // yields fewer final tokens and reverts here), so this leg may use the bounded spot-quote convenience path.
+        _strictSwapQuote = false;
+
         // Keep a reference to the terminal that will receive the routed payment.
         IJBTerminal destTerminal;
 
@@ -598,7 +622,9 @@ contract JBRouterTerminal is
         return pool;
     }
 
-    /// @notice Public wrapper for V3-only _discoverPool, useful for off-chain queries.
+    /// @notice The best Uniswap V3 pool for a token pair, useful for off-chain queries.
+    /// @dev V3-only by design: returns the deepest V3 pool whenever one exists, independent of whether a deeper V4
+    /// pool exists for the same pair. Reverts only when no V3 pool exists at all.
     /// @param normalizedTokenIn The input token (wrapped if native).
     /// @param normalizedTokenOut The output token (wrapped if native).
     /// @return pool The V3 pool with the highest liquidity.
@@ -611,12 +637,10 @@ contract JBRouterTerminal is
         override
         returns (IUniswapV3Pool pool)
     {
-        PoolInfo memory info =
-            _discoverPool({normalizedTokenIn: normalizedTokenIn, normalizedTokenOut: normalizedTokenOut});
-        if (!info.isV4 && address(info.v3Pool) == address(0)) {
+        pool = _discoverV3Pool({normalizedTokenIn: normalizedTokenIn, normalizedTokenOut: normalizedTokenOut});
+        if (address(pool) == address(0)) {
             revert JBRouterTerminal_NoPoolFound({tokenIn: normalizedTokenIn, tokenOut: normalizedTokenOut});
         }
-        if (!info.isV4) pool = info.v3Pool;
     }
 
     /// @notice Preview a payment by simulating the router's routing logic in view context.
@@ -1180,6 +1204,8 @@ contract JBRouterTerminal is
                 sourceProjectId: sourceProjectId, destProjectId: destProjectId, preferredToken: preferredToken
             });
 
+            _claimRouterCreditsFor({projectId: sourceProjectId});
+
             uint256 cashOutCount = amount;
             uint256 balanceBefore = _balanceOf({token: tokenToReclaim, account: address(this)});
 
@@ -1235,6 +1261,20 @@ contract JBRouterTerminal is
         revert JBRouterTerminal_CashOutLoopLimit({maxIterations: _MAX_CASHOUT_ITERATIONS});
     }
 
+    /// @notice Converts this router's internal project-token credits into ERC-20s before a source cash-out.
+    /// @dev Core burns holder credits before ERC-20 balances. Normalizing first keeps a source cash-out scoped to
+    /// transferable token balances already visible to the router.
+    /// @param projectId The Juicebox project whose tokens are being cashed out.
+    function _claimRouterCreditsFor(uint256 projectId) internal {
+        uint256 creditCount = TOKENS.creditBalanceOf({holder: address(this), projectId: projectId});
+        if (creditCount == 0) return;
+
+        IJBController controller = IJBController(address(DIRECTORY.controllerOf(projectId)));
+        controller.claimTokensFor({
+            holder: address(this), projectId: projectId, tokenCount: creditCount, beneficiary: address(this)
+        });
+    }
+
     /// @notice Convert tokenIn to tokenOut. No-op if same, wrap/unwrap for native/wrapped-native, or swap via Uniswap.
     /// @param tokenIn The token to convert from.
     /// @param tokenOut The token to convert into.
@@ -1893,9 +1933,49 @@ contract JBRouterTerminal is
         view
         returns (PoolInfo memory bestPool)
     {
+        // Search V3 for the deepest pool and its liquidity.
         uint128 bestLiquidity;
+        (bestPool.v3Pool, bestLiquidity) =
+            _discoverV3PoolAndLiquidity({normalizedTokenIn: normalizedTokenIn, normalizedTokenOut: normalizedTokenOut});
+
+        // Search V4, promoting a V4 pool only when it is deeper than the best V3 pool found above.
+        bestPool = _discoverV4Pool({
+            normalizedTokenIn: normalizedTokenIn,
+            normalizedTokenOut: normalizedTokenOut,
+            currentBestLiquidity: bestLiquidity,
+            bestPool: bestPool
+        });
+    }
+
+    /// @notice Find the highest-liquidity Uniswap V3 pool for a token pair across the common fee tiers.
+    /// @param normalizedTokenIn The input token (wrapped if native).
+    /// @param normalizedTokenOut The output token (wrapped if native).
+    /// @return pool The V3 pool with the highest liquidity, or address(0) if none exists.
+    function _discoverV3Pool(
+        address normalizedTokenIn,
+        address normalizedTokenOut
+    )
+        internal
+        view
+        returns (IUniswapV3Pool pool)
+    {
+        (pool,) =
+            _discoverV3PoolAndLiquidity({normalizedTokenIn: normalizedTokenIn, normalizedTokenOut: normalizedTokenOut});
+    }
 
-        // Search V3.
+    /// @notice Find the highest-liquidity Uniswap V3 pool for a token pair along with its liquidity.
+    /// @param normalizedTokenIn The input token (wrapped if native).
+    /// @param normalizedTokenOut The output token (wrapped if native).
+    /// @return pool The V3 pool with the highest liquidity, or address(0) if none exists.
+    /// @return liquidity The liquidity of the returned pool, or 0 if none exists.
+    function _discoverV3PoolAndLiquidity(
+        address normalizedTokenIn,
+        address normalizedTokenOut
+    )
+        internal
+        view
+        returns (IUniswapV3Pool pool, uint128 liquidity)
+    {
         for (uint256 i; i < 4;) {
             address poolAddr = _getPool({tokenA: normalizedTokenIn, tokenB: normalizedTokenOut, fee: _feeTier(i)});
 
@@ -1908,23 +1988,15 @@ contract JBRouterTerminal is
 
             uint128 poolLiquidity = IUniswapV3Pool(poolAddr).liquidity();
 
-            if (poolLiquidity > bestLiquidity) {
-                bestLiquidity = poolLiquidity;
-                bestPool.v3Pool = IUniswapV3Pool(poolAddr);
+            if (poolLiquidity > liquidity) {
+                liquidity = poolLiquidity;
+                pool = IUniswapV3Pool(poolAddr);
             }
 
             unchecked {
                 ++i;
             }
         }
-
-        // Search V4.
-        bestPool = _discoverV4Pool({
-            normalizedTokenIn: normalizedTokenIn,
-            normalizedTokenOut: normalizedTokenOut,
-            currentBestLiquidity: bestLiquidity,
-            bestPool: bestPool
-        });
     }
 
     /// @notice Search supported V4 pools and update the best pool candidate if a deeper V4 pool exists.
@@ -2247,9 +2319,12 @@ contract JBRouterTerminal is
     }
 
     /// @notice Get an automatic V4 quote with dynamic slippage.
-    /// @dev Prefers a hook-provided geomean/TWAP quote when available. Falls back to the pool's spot tick otherwise.
-    /// This fallback is an accepted product risk for programmatic integrations that cannot provide an external quote,
-    /// but it should be understood as a bounded-convenience path rather than a fully manipulation-resistant one.
+    /// @dev Prefers a hook-provided geomean/TWAP quote when available. For a pool with no such oracle it falls back to
+    /// the pool's spot tick ONLY when `_strictSwapQuote` is false (the `pay` leg — backstopped end-to-end by
+    /// `minReturnedTokens` — and off-chain previews). When `_strictSwapQuote` is true (the `addToBalanceOf` and
+    /// cash-out-swap legs, which have no downstream backstop) it instead reverts
+    /// `JBRouterTerminal_ManipulationResistantQuoteRequired`, forcing the caller to supply a `pay` quote. The spot
+    /// fallback is a bounded-convenience path, not a fully manipulation-resistant one.
     ///
     /// SECURITY NOTE: The spot price read from `poolManager.getSlot0(id)` is an instantaneous value
     /// that can be manipulated within the same block (e.g. via sandwich attacks or flash loans). Unlike V3 pools,
@@ -2274,11 +2349,15 @@ contract JBRouterTerminal is
     ///      scales up to the 88% ceiling via a continuous sigmoid curve.
     ///   4. Pool discovery (`_discoverPool`) may select a V3 pool with TWAP if it has more liquidity, avoiding
     ///      this V4 spot-price path altogether.
+    ///   5. On legs with no downstream `minReturnedTokens` backstop (`addToBalanceOf`, and cash-out routes that
+    ///      settle via add-to-balance), `_strictSwapQuote` is set and this spot fallback is REFUSED: the call reverts
+    ///      `JBRouterTerminal_ManipulationResistantQuoteRequired` unless the caller supplied a `pay` quote.
     ///
     /// Despite these mitigations, the spot-based fallback does NOT provide full MEV protection. Integrators and
     /// front-ends should supply `pay` swap-quote metadata for V4 swaps whenever possible so the user's slippage
     /// tolerance reflects a recent, off-chain-verified price. When no external quote can be provided, this fallback
-    /// is still available as an accepted-risk convenience path.
+    /// remains available as a bounded convenience path ONLY for the backstopped `pay` leg and off-chain previews; the
+    /// un-backstopped `addToBalanceOf` and cash-out-swap legs refuse it (mitigation 5).
     /// @param key The V4 pool key describing the pool to quote against.
     /// @param normalizedTokenIn The normalized token to sell into the pool.
     /// @param normalizedTokenOut The normalized token to buy from the pool.
@@ -2331,8 +2410,14 @@ contract JBRouterTerminal is
             } catch {}
         }
 
-        // If no TWAP was available (no hook, or hook doesn't implement observe), use the instantaneous spot tick.
+        // If no TWAP was available (no hook, or hook doesn't implement observe), there is no manipulation-resistant
+        // price source for this pool. For legs with a downstream backstop (pay's `minReturnedTokens`) or for off-chain
+        // previews, fall back to the instantaneous spot tick (a bounded-convenience path). For legs with NO downstream
+        // backstop (`addToBalanceOf`, and cash-out routes that settle via add-to-balance), refuse: a self-referential
+        // spot floor against an attacker-initialized vanilla pool offers no real protection, so require the caller to
+        // supply a `pay` quote instead.
         if (!usedTwap) {
+            if (_strictSwapQuote) revert JBRouterTerminal_ManipulationResistantQuoteRequired({poolId: id});
             (, tick,,) = _getSlot0(id);
         }
 

package/src/JBRouterTerminalRegistry.sol

@@ -74,9 +74,11 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     /// @notice The `PROJECTS.count()` snapshot at the moment of the last `setDefaultTerminal` call.
     /// Projects with `ID <= defaultTerminalProjectIdThreshold` (i.e. already existing when the most
     /// recent default was set) DO NOT pick up `defaultTerminal` on fall-through; instead they
-    /// resolve against the historical entry in `_defaultTerminalHistory` that covers their ID.
+    /// resolve against the historical entry in `_defaultTerminalHistory` that covers their ID. The
+    /// first default's segment covers every project that already existed when it was set (so those
+    /// projects route through it), while later segments pin each outgoing default to its own cohort.
     /// This prevents the registry owner from silently rerouting payments for already-deployed
-    /// projects via a default change.
+    /// projects via a later default change.
     uint256 public override defaultTerminalProjectIdThreshold;
 
     /// @notice Whether the terminal for a given project has been locked against future updates.
@@ -91,10 +93,11 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     // --------------------- internal stored properties ------------------ //
     //*********************************************************************//
 
-    /// @notice Append-only history of previous defaults captured at each `setDefaultTerminal` call. Each `segment[i]`
-    /// applies to projectIds in `[<previous threshold> + 1, segment[i].maxProjectId]`. Resolution walks the array
-    /// forward and returns the first segment whose `maxProjectId` covers the queried `projectId`. New defaults push
-    /// the current default onto this history before updating `defaultTerminal`.
+    /// @notice Append-only history of default-terminal cohorts captured at each `setDefaultTerminal` call. Each
+    /// `segment[i]` applies to projectIds in `[<previous threshold> + 1, segment[i].maxProjectId]`. Resolution walks
+    /// the array forward and returns the first segment whose `maxProjectId` covers the queried `projectId`. The first
+    /// call records the projects that already existed mapped to the new default; later calls push the outgoing default
+    /// onto this history before updating `defaultTerminal`.
     DefaultTerminalSegment[] internal _defaultTerminalHistory;
 
     /// @notice The terminal explicitly configured for a project before default-terminal fallback is applied.
@@ -360,10 +363,10 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         if (projectId > defaultTerminalProjectIdThreshold) return defaultTerminal;
 
         // Older projects walk the history. Each segment covers a half-open range
-        // `(minProjectIdExclusive, maxProjectId]` — exactly the cohort that was issued while that segment's terminal
-        // was the active default. Projects whose IDs pre-date every recorded default (the cold-start cohort)
-        // do not match any segment and resolve to `address(0)` — preserving the documented "the default only applies
-        // to projects created AFTER it was set" property at registry cold-start.
+        // `(minProjectIdExclusive, maxProjectId]`. The first segment covers every project that already existed when the
+        // first default was set (mapped to that first default, so they route through it); later segments each cover the
+        // cohort issued while their terminal was the active default. A project only resolves to `address(0)` here when
+        // no default has ever been set.
         uint256 len = _defaultTerminalHistory.length;
         for (uint256 i; i < len; ++i) {
             DefaultTerminalSegment storage segment = _defaultTerminalHistory[i];
@@ -388,7 +391,7 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     }
 
     /// @notice Resolve the effective terminal for call paths that need to forward into a real terminal.
-    /// @dev `terminalOf`/`defaultTerminalFor` may intentionally return zero for the cold-start cohort. Transactional
+    /// @dev `terminalOf`/`defaultTerminalFor` return zero only when no default has ever been set. Transactional
     /// and passthrough view paths must fail before accepting funds or calling address(0).
     /// @param projectId The project to resolve the terminal for.
     /// @return terminal The project-specific terminal or threshold-resolved default.
@@ -623,12 +626,14 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
 
     /// @notice Change the registry-wide default terminal for projects created AFTER this call.
     /// @dev Only the registry owner can call this. Automatically allowlists the new default.
-    /// Existing projects (ID <= current `PROJECTS.count()` at call time) keep their historical
-    /// default — the previous `defaultTerminal` is pushed onto `_defaultTerminalHistory` so
-    /// fall-through resolution for those projects continues to return what was current when
-    /// their cohort was last addressed. This eliminates the silent-reroute attack vector
-    /// where the registry owner could redirect payments for already-deployed projects that
-    /// never set an explicit `_terminalOf` override.
+    /// The very first call also maps every project that already existed onto the new default (via a
+    /// history segment) so those pre-existing projects — including the canonical fee project (ID 1) —
+    /// can route tokens through it. Existing projects (ID <= current `PROJECTS.count()` at call time)
+    /// keep their historical default on later changes — the previous `defaultTerminal` is pushed onto
+    /// `_defaultTerminalHistory` so fall-through resolution for those projects continues to return what
+    /// was current when their cohort was last addressed. This means a later default change never
+    /// silently reroutes payments for already-deployed projects that never set an explicit
+    /// `_terminalOf` override.
     /// @param terminal The terminal to set as the default for future projects.
     function setDefaultTerminal(IJBTerminal terminal) external onlyOwner {
         if (address(terminal) == address(0)) revert JBRouterTerminalRegistry_ZeroAddress(address(terminal));
@@ -641,20 +646,20 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         // default is what unconfigured (and all-future) projects will resolve to.
         _requireNonCircularTerminalFor({projectId: count, terminal: terminal});
 
-        // Snapshot the OUTGOING default so projects whose IDs were issued while it was active keep resolving to it.
-        // The segment encodes the half-open range `(prevThreshold, currentCount]` — i.e. exactly the cohort that was
-        // assigned the outgoing default at creation time. The first call ever has `defaultTerminal == 0` and nothing
-        // to snapshot; in that case projects whose IDs already existed remain unaffected by the new default, keeping
-        // the cold-start cohort outside any retroactive routing change.
-        if (address(defaultTerminal) != address(0)) {
-            _defaultTerminalHistory.push(
-                DefaultTerminalSegment({
-                    minProjectIdExclusive: defaultTerminalProjectIdThreshold,
-                    maxProjectId: count,
-                    terminal: defaultTerminal
-                })
-            );
-        }
+        // Record a history segment for the cohort whose IDs fall in the half-open range `(prevThreshold,
+        // currentCount]`. On the first call ever (`defaultTerminal == 0`) the segment maps the projects that already
+        // existed — including the canonical fee project (ID 1) — onto the NEW default so they can route tokens
+        // through
+        // it instead of resolving to nothing. On every later call the segment instead pins the OUTGOING default to its
+        // own cohort, so projects whose IDs were issued while it was active keep resolving to it and a default change
+        // never silently reroutes an already-deployed project.
+        _defaultTerminalHistory.push(
+            DefaultTerminalSegment({
+                minProjectIdExclusive: defaultTerminalProjectIdThreshold,
+                maxProjectId: count,
+                terminal: address(defaultTerminal) != address(0) ? defaultTerminal : terminal
+            })
+        );
 
         defaultTerminal = terminal;
         defaultTerminalProjectIdThreshold = count;