@bananapus/router-terminal-v6 0.0.52 → 0.0.54

package/README.md

@@ -126,7 +126,7 @@ script/
 - swap previews are best-effort estimates and depend on current pool state plus caller-supplied quote data
 - recursive cash-out routing increases complexity when the input token is itself a Juicebox project token
 - slippage and sandwich resistance depend on the quality of the chosen quote path
-- final terminal-facing ERC-20 hops must be standard tokens; lossy terminal pulls are rejected
+- `addToBalanceOf` rejects lossy terminal pulls; `pay` cannot reliably detect final-hop fee-on-transfer loss because pay hooks can consume tokens during settlement
 
 The most common reader mistake here is to stop at the router and forget to inspect the terminal that actually receives the value.
 

package/package.json

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

package/references/operations.md

@@ -9,7 +9,7 @@
 ## Change Checklist
 
 - If you edit route discovery, verify both direct acceptance and swap-based routes.
-- If you edit the cash-out loop, check credit-based flows and fork tests, not just simple payments.
+- If you edit the cash-out loop, check project-token cash-out flows and fork tests, not only simple payments.
 - If you edit slippage or quote logic, inspect [`src/JBPayRouteResolver.sol`](../src/JBPayRouteResolver.sol) and the preview tests together.
 - If you edit preview behavior, verify route ranking still normalizes buyback-hook hints and still agrees with execution.
 - If you edit refund or partial-fill handling, verify baseline snapshots and destination-terminal receipt enforcement together.
@@ -21,7 +21,7 @@
 - Preview output drifts from execution because quote and execution paths were edited independently.
 - Registry state makes a project use a different router than expected.
 - Metadata overrides force an output token or cash-out source that the caller did not intend.
-- A terminal-facing ERC-20 path reverts because the destination terminal did not actually receive the nominal amount. This now indicates a non-standard final-hop token path, not just a documentation caveat.
+- On `addToBalanceOf` paths, a terminal-facing ERC-20 receipt mismatch indicates a non-standard final-hop token path.
 
 ## Useful Proof Points
 

package/references/runtime.md

@@ -8,7 +8,7 @@
 
 ## Runtime Path
 
-1. The router accepts funds or credits.
+1. The router accepts native tokens, ERC-20s, or claimed Juicebox project-token ERC-20s.
 2. If the input is a Juicebox project token, the router may enter a cash-out loop first.
 3. The router resolves the desired output token using direct acceptance, wrap/unwrap equivalence, metadata overrides, or pool discovery.
 4. It converts value through direct forwarding, wrap/unwrap, Uniswap V3, or Uniswap V4.
@@ -17,18 +17,18 @@
 ## High-Risk Areas
 
 - Preview and execution parity: changes to quote selection or route discovery should be checked against both preview and mutative paths.
-- V4 discovery scope: the router now searches both vanilla V4 pools and pools using the configured canonical `UNIV4_HOOK`.
+- V4 discovery scope: the router searches both vanilla V4 pools and pools using the configured canonical `UNIV4_HOOK`.
 - Cash-out loop behavior: recursive routing through project tokens can create subtle loop or slippage issues.
 - Callback validation: V3 and V4 callback guards are security-critical and should not drift.
 - Leftover/refund handling: refunds can route to the original payer or fallback recipient depending on context.
 - Dynamic accounting contexts: this repo intentionally synthesizes accounting contexts instead of storing a static token list.
-- Final terminal-facing ERC-20 receipt enforcement: the router rejects lossy terminal pulls, so terminal mocks and integrations must behave like standard pull-based ERC-20 receivers. The registry does not independently enforce receipts; it relies on the router.
+- Final terminal-facing ERC-20 receipt enforcement: `addToBalanceOf` rejects lossy terminal pulls, while `pay` does not enforce receipt deltas because pay hooks can consume tokens during settlement. The registry does not independently enforce receipts; it relies on the router path it forwards into.
 - Preview normalization: buyback-hook metadata can improve the user-visible preview outcome, so route ranking must normalize hook-returned hints consistently across candidates.
 
 ## Tests To Trust First
 
 - [`test/RouterTerminalPreviewFork.t.sol`](../test/RouterTerminalPreviewFork.t.sol) for preview-path behavior.
-- [`test/RouterTerminalCashOutFork.t.sol`](../test/RouterTerminalCashOutFork.t.sol) and [`test/RouterTerminalCreditCashout.t.sol`](../test/RouterTerminalCreditCashout.t.sol) for cash-out routing.
+- [`test/RouterTerminalCashOutFork.t.sol`](../test/RouterTerminalCashOutFork.t.sol) and [`test/RouterTerminalFeeCashOutFork.t.sol`](../test/RouterTerminalFeeCashOutFork.t.sol) for project-token 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/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/script/Deploy.s.sol

@@ -172,7 +172,7 @@ contract DeployScript is Script, Sphinx {
             trustedForwarder: trustedForwarder
         });
 
-        // Deploy the router terminal with chain-same CREATE2 inputs; chain-specific constants
+        // Deploy the router terminal with chain-identical CREATE2 inputs; chain-specific constants
         // (WETH + Uniswap V3 factory + V4 PoolManager + V4 hook) are wired afterwards via the
         // DEPLOYER-gated one-shot setChainSpecificConstants setter on the terminal.
         require(address(buyback.hook) != address(0), "RouterTerminal: missing buyback hook");

package/src/JBPayRouteResolver.sol

@@ -39,9 +39,9 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     /// @param directory The directory storing project terminal relationships.
     /// @dev The wrapped-native-token address is intentionally NOT cached here. The router passes it in as a parameter
     /// (`address wrappedNativeToken`) on every external resolver call and the resolver threads it through internal
-    /// helpers. This keeps the resolver's constructor inputs chain-same (no chain-specific WETH baked in) so its
-    /// CREATE address (router + nonce 1) stays unified, AND avoids paying an extra external call per normalization
-    /// step inside loops like `_discoverAcceptedToken`.
+    /// helpers. This keeps the resolver's constructor inputs byte-identical across chains (no chain-specific WETH
+    /// baked in), so its deployed address (router + nonce 1) stays unified and avoids an extra external call per
+    /// normalization step inside loops like `_discoverAcceptedToken`.
     constructor(IJBDirectory directory) {
         DIRECTORY = directory;
     }

package/src/JBRouterTerminal.sol

@@ -87,6 +87,7 @@ contract JBRouterTerminal is
         address terminal, address token, uint256 expectedAmount, uint256 actualAmount
     );
     error JBRouterTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
+    error JBRouterTerminal_QuoteTokenMismatch(address quotedTokenOut, address expectedTokenOut);
     error JBRouterTerminal_SlippageExceeded(uint256 amountOut, uint256 minAmountOut);
     error JBRouterTerminal_Unauthorized(address caller);
 
@@ -121,8 +122,8 @@ contract JBRouterTerminal is
     //*********************************************************************//
 
     /// @notice The canonical buyback hook whose preview hook specification metadata this router understands.
-    /// @dev Chain-same: `JBBuybackHook` is deployed via CREATE2 to a unified address on every chain, so this stays
-    /// `immutable` without breaking the router's own chain-same CREATE2 address.
+    /// @dev `JBBuybackHook` is deployed via CREATE2 to a unified address on every chain, so this stays
+    /// `immutable` without breaking the router's own chain-identical CREATE2 address.
     address public immutable BUYBACK_HOOK;
 
     /// @notice The directory of terminals and controllers for projects.
@@ -144,10 +145,10 @@ contract JBRouterTerminal is
     address internal immutable _DEPLOYER;
 
     /// @notice The helper contract used to resolve best pay-route previews without bloating router runtime size.
-    /// @dev Deployed in the constructor with chain-same inputs (just `directory` — the resolver does NOT cache
+    /// @dev Deployed in the constructor with chain-identical inputs (only `directory` — the resolver does NOT cache
     /// `wrappedNativeToken` locally; the router passes it in on every external resolver call as a parameter to
-    /// avoid an extra external call on each normalization step). Because this router's address is chain-same via
-    /// CREATE2 and the resolver is deployed at the router's nonce 1, the resolver's address is chain-same too.
+    /// avoid an extra external call on each normalization step). Because this router's address is unified via
+    /// CREATE2 and the resolver is deployed at the router's nonce 1, the resolver's address is unified too.
     IJBPayRouteResolver internal immutable _PAY_ROUTE_RESOLVER;
 
     /// @notice Pre-computed metadata ID for "permit2".
@@ -196,7 +197,7 @@ contract JBRouterTerminal is
     /// @param directory A contract storing directories of terminals and controllers for each project.
     /// @param tokens A contract managing project token balances.
     /// @param permit2 A permit2 utility.
-    /// @param buybackHook The canonical buyback hook (chain-same across all chains).
+    /// @param buybackHook The canonical buyback hook, deployed to the same address on each supported chain.
     /// @param trustedForwarder The trusted forwarder for the contract.
     /// @param deployer The address authorized to call `setChainSpecificConstants` exactly once. Held immutable so the
     /// constructor inputs are byte-identical across chains and the CREATE2 address is unified.
@@ -909,7 +910,7 @@ contract JBRouterTerminal is
     /// @param tokenIn The token currently available to swap.
     /// @param tokenOut The token the swap should deliver.
     /// @param amount The amount of `tokenIn` to preview.
-    /// @param metadata Metadata that can provide an explicit quote override for the swap.
+    /// @param metadata Metadata that can provide an explicit `(tokenOut, minAmountOut)` quote for the swap.
     /// @return amountOut The predicted amount of `tokenOut` the router would receive.
     function _previewSwapAmountOut(
         address tokenIn,
@@ -1096,7 +1097,7 @@ contract JBRouterTerminal is
     }
 
     /// @notice Run the common post-transfer cleanup after forwarding funds into a destination terminal.
-    /// @param destTerminal The terminal that just received the forwarded call.
+    /// @param destTerminal The terminal that received the forwarded call.
     /// @param token The token that was forwarded into the destination terminal.
     function _afterTransferFor(IJBTerminal destTerminal, address token) internal {
         // Revoke any leftover allowance the destination terminal did not pull so routed calls do not leave approvals
@@ -1188,6 +1189,9 @@ contract JBRouterTerminal is
             // 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.
+            // Still forward the original metadata on the first hop so the source hook can use the same user floor
+            // when choosing between direct cash-out and its own routed cash-out path.
+            bytes memory hopMetadata = i == 0 ? metadata : bytes("");
             cashOutTerminal.cashOutTokensOf({
                 holder: address(this),
                 projectId: sourceProjectId,
@@ -1195,7 +1199,7 @@ contract JBRouterTerminal is
                 tokenToReclaim: tokenToReclaim,
                 minTokensReclaimed: 0,
                 beneficiary: payable(address(this)),
-                metadata: "",
+                metadata: hopMetadata,
                 referralProjectId: 0
             });
 
@@ -1258,7 +1262,7 @@ contract JBRouterTerminal is
         address nOut = _normalize(tokenOut);
 
         if (nIn == nOut) {
-            // Same underlying token — just wrap or unwrap.
+            // Same underlying token; wrap or unwrap.
             if (tokenIn == JBConstants.NATIVE_TOKEN) _wrapNativeToken(amount);
             else _unwrapNativeToken(amount);
             return amount;
@@ -2260,7 +2264,8 @@ contract JBRouterTerminal is
     ///
     /// Mitigations in place:
     ///   1. Users SHOULD provide a `quoteForSwap` value in the payment metadata (obtained from an off-chain
-    ///      quoter or RPC simulation). When present, this function is bypassed entirely — see `_pickPoolAndQuote`.
+    ///      quoter or RPC simulation). The quote must encode the output token and minimum output amount. When present,
+    ///      this function is bypassed entirely — see `_pickPoolAndQuote`.
     ///   2. When a hook implements `IGeomeanOracle.observe(...)`, this function uses that oracle-derived tick instead
     ///      of spot.
     ///   3. The sigmoid slippage formula (`JBSwapLib.getSlippageTolerance`) enforces a minimum 2% slippage floor
@@ -2299,7 +2304,7 @@ contract JBRouterTerminal is
 
         // If the pool has a hook, try querying it as a geomean oracle (e.g., JBUniswapV4Hook implements this).
         if (address(key.hooks) != address(0)) {
-            // Build the two-element lookback array: [_TWAP_WINDOW seconds ago, now].
+            // Build the two-element lookback array: [_TWAP_WINDOW seconds ago, current block time].
             uint32[] memory secondsAgos = new uint32[](2);
             secondsAgos[0] = _TWAP_WINDOW; // Start of the window (120 seconds ago).
             secondsAgos[1] = 0; // End of the window (current block).
@@ -2416,8 +2421,9 @@ contract JBRouterTerminal is
     /// protection. Integrators should still supply `quoteForSwap` metadata whenever they can.
     ///
     /// Priority for `minAmountOut`:
-    ///   1. **User-provided quote** — If `quoteForSwap` is present in `metadata`, it is used directly.
-    ///      This is the recommended path for MEV protection, especially for V4 pools.
+    ///   1. **User-provided quote** — If `quoteForSwap` is present in `metadata`, it is used after confirming the
+    ///      quote's output token matches the selected route. This is the recommended path for MEV protection,
+    ///      especially for V4 pools.
     ///   2. **V3 TWAP** — If the best pool is V3, uses a manipulation-resistant time-weighted average price.
     ///   3. **V4 automatic quote** — If the best pool is V4, first attempts a hook-provided oracle quote and
     ///      otherwise falls back to the instantaneous `getSlot0` tick. The spot fallback is manipulable within the
@@ -2446,11 +2452,19 @@ contract JBRouterTerminal is
             revert JBRouterTerminal_NoPoolFound({tokenIn: normalizedTokenIn, tokenOut: normalizedTokenOut});
         }
 
-        // Check for a user-provided quote.
+        // `quoteForSwap` is encoded as `(tokenOut, minAmountOut)`. Binding the quote to its output token prevents
+        // metadata quoted for one route from being replayed against another route with a weaker floor.
         (bool exists, bytes memory quote) = _getDataFor({metadata: metadata, id: _QUOTE_FOR_SWAP_ID});
 
         if (exists) {
-            (minAmountOut) = abi.decode(quote, (uint256));
+            (address quotedTokenOut, uint256 quotedMinAmountOut) = abi.decode(quote, (address, uint256));
+            // Normalize ETH/WETH before comparing because pool routes use WETH internally for native-token swaps.
+            if (_normalize(quotedTokenOut) != normalizedTokenOut) {
+                revert JBRouterTerminal_QuoteTokenMismatch({
+                    quotedTokenOut: quotedTokenOut, expectedTokenOut: normalizedTokenOut
+                });
+            }
+            minAmountOut = quotedMinAmountOut;
         }
 
         // Treat a decoded value of 0 the same as "not provided" so that a stale or default-zero quote