@bananapus/router-terminal-v6 0.0.33 → 0.0.34

package/README.md

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

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-router-terminal-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/Deploy.s.sol",
+    "script/helpers/",
+    "src/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -17,16 +26,17 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-router-terminal-v6'"
   },
   "dependencies": {
-    "@bananapus/buyback-hook-v6": "^0.0.30",
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@uniswap/permit2": "github:Uniswap/permit2",
-    "@uniswap/v3-core": "github:Uniswap/v3-core#0.8",
-    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#0.8",
-    "@uniswap/v4-core": "^1.0.0"
+    "@bananapus/buyback-hook-v6": "0.0.36",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@bananapus/univ4-router-v6": "0.0.22",
+    "@openzeppelin/contracts": "5.6.1",
+    "@uniswap/permit2": "github:Uniswap/permit2#cc56ad0f3439c502c246fc5cfcc3db92bb8b7219",
+    "@uniswap/v3-core": "github:Uniswap/v3-core#6562c52e8f75f0c10f9deaf44861847585fc8129",
+    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#b325bb0905d922ae61fcc7df85ee802e8df5e96c",
+    "@uniswap/v4-core": "1.0.2"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/src/JBPayRouteResolver.sol

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

package/src/JBRouterTerminal.sol

@@ -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().
@@ -2333,9 +2350,12 @@ contract JBRouterTerminal is
                 // An OOB access in the try-success block panics and is NOT caught by catch{}.
                 if (tickCumulatives.length >= 2) {
                     // Derive the arithmetic mean tick: (cumulative_now - cumulative_start) / elapsed_seconds.
-                    // forge-lint: disable-next-line(unsafe-typecast)
                     int56 tickDelta = tickCumulatives[1] - tickCumulatives[0];
+                    // The TWAP window is a small protocol constant that fits in int32 and int56.
+                    // forge-lint: disable-next-line(unsafe-typecast)
                     int56 period = int56(int32(_TWAP_WINDOW));
+                    // The cumulative tick values come from Uniswap observations, whose average tick is int24-bounded.
+                    // forge-lint: disable-next-line(unsafe-typecast)
                     tick = int24(tickDelta / period);
                     // Round towards negative infinity for negative ticks (Uniswap convention).
                     if (tickDelta < 0 && (tickDelta % period != 0)) tick--;
@@ -2566,7 +2586,9 @@ contract JBRouterTerminal is
             });
 
             // Enforce the caller's minimum reclaim amount only on the first hop.
-            if (amount < minTokensReclaimed) revert JBRouterTerminal_SlippageExceeded(amount, minTokensReclaimed);
+            if (amount < minTokensReclaimed) {
+                revert JBRouterTerminal_SlippageExceeded({amountOut: amount, minAmountOut: minTokensReclaimed});
+            }
 
             // Clear the reclaim minimum after the first hop because later hops may operate in different token units.
             minTokensReclaimed = 0;
@@ -2622,6 +2644,8 @@ contract JBRouterTerminal is
             metadata: ""
         });
 
+        // Deployment config makes this router a feeless cash-out beneficiary, so previews use the terminal's raw
+        // reclaim amount and avoid carrying fee-discovery bytecode in the router.
         reclaimAmount = _effectivePreviewCashOutAmount(reclaimAmount, hookSpecifications);
     }
 

package/src/JBRouterTerminalRegistry.sol

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

package/ADMINISTRATION.md

@@ -1,80 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | Global router terminal allowlisting and project-local terminal selection |
-| Control posture | Mixed registry-owner and project-local delegated control |
-| Highest-risk actions | Changing the default terminal, locking a project to the wrong terminal, and relying on misconfigured credit-cashout routing |
-| Recovery posture | Unlocked projects can move; locked projects and immutable router wiring limit recovery |
-
-## Purpose
-
-`nana-router-terminal-v6` splits administration between a global registry and project-local terminal selection. The router logic itself is mostly immutable. The mutable control plane lives in `JBRouterTerminalRegistry`.
-
-## Control Model
-
-- `JBRouterTerminalRegistry` is globally `Ownable`
-- project owners or delegates choose and can lock their router terminal
-- `JBRouterTerminal` has immutable routing dependencies and no owner-controlled strategy knobs
-- some transaction paths depend on project-local `JBPermissions`, such as `TRANSFER_CREDITS`
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| Registry owner | `Ownable(owner)` | Global | Controls allowlist and default terminal |
-| Project owner | `JBProjects.ownerOf(projectId)` | Per project | May delegate `SET_ROUTER_TERMINAL` |
-| Terminal delegate | `JBPermissions` grant | Per project | Usually `SET_ROUTER_TERMINAL` |
-| Payer | Per transaction | Per payment | May need `TRANSFER_CREDITS` for credit-cashout routing |
-
-## Privileged Surfaces
-
-| Contract | Function | Who Can Call | Effect |
-| --- | --- | --- | --- |
-| `JBRouterTerminalRegistry` | `allowTerminal(...)`, `disallowTerminal(...)`, `setDefaultTerminal(...)` | Registry owner | Controls global terminal availability and fallback |
-| `JBRouterTerminalRegistry` | `setTerminalFor(...)` | Project owner or `SET_ROUTER_TERMINAL` delegate | Sets a project's explicit router terminal |
-| `JBRouterTerminalRegistry` | `lockTerminalFor(...)` | Project owner or `SET_ROUTER_TERMINAL` delegate | Irreversibly locks the resolved terminal for a project |
-
-## Immutable And One-Way
-
-- `lockTerminalFor(...)` is irreversible
-- constructor dependencies on the router are immutable
-- the current default terminal must move before the old default can be disallowed
-
-## Operational Notes
-
-- keep the terminal allowlist small and explicit
-- change the default terminal carefully because unconfigured projects inherit it
-- encourage projects to lock only after validating the resolved terminal and routing behavior
-- review credit-cashout routing permissions before relying on that path
-- distinguish configuration risk from quote-quality risk
-
-## Machine Notes
-
-- do not treat registry ownership as authority to override a locked project choice
-- inspect `src/JBRouterTerminalRegistry.sol` and `src/JBRouterTerminal.sol` separately; they govern different control boundaries
-- if effective terminal resolution and the documented default differ, resolve registry state before further actions
-- if route previews are falling back to weaker discovery or quote paths, do not describe the router as offering uniform oracle-quality guarantees
-
-## Recovery
-
-- unlocked projects can switch to another allowlisted terminal
-- locked projects cannot be unlocked by the registry
-- bad immutable router behavior means replacement infrastructure, not in-place edits
-- quote-path weakness is usually mitigated operationally with better pool choice, external quoting, or replacement routing infrastructure
-
-## Admin Boundaries
-
-- the registry owner cannot unlock or override a locked project terminal
-- project operators cannot set a terminal that the registry does not allow
-- router maintainers cannot tune routing heuristics or constructor immutables post-deploy
-- there is no pause surface in the registry or router
-
-## Source Map
-
-- `src/JBRouterTerminalRegistry.sol`
-- `src/JBRouterTerminal.sol`
-- `src/JBPayRouteResolver.sol`
-- `test/`

package/ARCHITECTURE.md

@@ -1,94 +0,0 @@
-# Architecture
-
-## Purpose
-
-`nana-router-terminal-v6` lets a payer fund a Juicebox project with a token the project does not directly accept. It discovers the destination token, wraps or unwraps native assets when needed, can recursively cash out upstream JB project tokens, and swaps through bounded Uniswap V3 or V4 routes before forwarding value to the destination terminal.
-
-The router is intentionally heuristic. It does not search every possible route for a globally optimal price.
-
-## System Overview
-
-`JBRouterTerminal` is a terminal-shaped adapter, not an accounting source of truth. `JBRouterTerminalRegistry` is both a registry and a stable project-facing proxy surface: projects can point at the registry while the registry resolves, and can later lock, the actual router terminal implementation to use. `JBPayRouteResolver` expands preview candidates without forcing the main router contract to carry all preview complexity inline.
-
-Final accounting still happens in the downstream terminal selected through `nana-core-v6`.
-
-## Core Invariants
-
-- the router's own accounting context is synthetic and must not be treated as the project ledger
-- preview route discovery and live execution must stay aligned
-- refund behavior is part of correctness, not just UX
-- registry locking prevents silent migration to untrusted router implementations
-- final terminal-facing ERC-20 hops only support standard, non-lossy transfers
-- recursive project-token cashout routing is intentionally bounded
-- caller reclaim minima only apply to the first cashout hop, because later hops may change token units
-- circular `router -> registry -> same router` forwarding remains blocked in the registry
-
-## Modules
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `JBRouterTerminal` | Intake, route discovery, swap execution, forwarding, and refunds | Main runtime surface |
-| `JBRouterTerminalRegistry` | Project-level router selection, locking, and proxy forwarding to the resolved router terminal | Governance, safety, and proxy surface |
-| `JBPayRouteResolver` | Preview candidate evaluation | Helper to keep runtime size bounded |
-| `JBSwapLib` and routing structs | Pool discovery, quoting, and route metadata | Shared routing logic |
-
-## Trust Boundaries
-
-- final accounting remains in the downstream terminal selected through `JBDirectory`
-- the router trusts Uniswap V3, Uniswap V4, Permit2, and optional payer trackers for routing-side behavior
-- fee-on-transfer tokens are only tolerated on ingress where received-balance deltas can be reconciled
-- the registry is trusted to resolve and forward into the intended router implementation for a project
-
-## Critical Flows
-
-### Route And Pay
-
-```text
-router pay call
-  -> accept native, ERC-20, or JB-token-like input
-  -> if input is a project token, recursively cash it out first
-  -> resolve the destination token the project terminal actually accepts
-  -> choose the best direct, wrap/unwrap, or swap path under the router's bounded candidate-discovery heuristic
-  -> execute the route and forward the result to the downstream terminal
-  -> refund leftover input when possible
-```
-
-## Accounting Model
-
-The router does not own project balances. It owns transient route accounting: input reconciliation, swap execution, forwarded amount, and refund resolution.
-
-Preview and execution share the same conceptual route shape: optional recursive cashout first, then destination-token resolution, then final conversion and forwarding.
-
-## Security Model
-
-- native-asset handling and refunds are the most failure-prone paths
-- V3 and V4 discovery must stay synchronized between preview and live execution
-- V4 discovery intentionally considers both vanilla pools and pools using the canonical `UNIV4_HOOK`
-- the router's "best route" claim is only as strong as its bounded discovery set and external-terminal safety checks
-- recursive cashout behavior, preferred-token handling, and one-shot source overrides are tightly coupled
-
-## Safe Change Guide
-
-- keep route discovery and route execution semantics paired
-- be conservative with native wrapping, unwrapping, and refund behavior
-- if recursive cash-out logic changes, review hop limits and failure handling together
-- if metadata semantics change, re-check first-hop reclaim minima, one-shot source overrides, and preferred-token routing together
-- do not turn the router into a persistent treasury layer
-
-## Canonical Checks
-
-- bounded recursive cash-out behavior:
-  `test/regression/CashOutLoopLimit.t.sol`
-- preview versus execution terminal alignment:
-  `test/audit/PreviewPrimaryTerminalMismatch.t.sol`
-- router-wide route and refund invariants:
-  `test/invariant/RouterTerminalInvariant.t.sol`
-
-## Source Map
-
-- `src/JBRouterTerminal.sol`
-- `src/JBRouterTerminalRegistry.sol`
-- `src/JBPayRouteResolver.sol`
-- `test/regression/CashOutLoopLimit.t.sol`
-- `test/audit/PreviewPrimaryTerminalMismatch.t.sol`
-- `test/invariant/RouterTerminalInvariant.t.sol`