@bananapus/router-terminal-v6 0.0.62 → 0.0.64

package/README.md

@@ -32,7 +32,7 @@ Use this repo when UX requires "pay with many tokens, settle into the right one.
 
 This repo is best understood as an execution router attached to Juicebox, not as a new accounting model.
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -40,7 +40,7 @@ This repo is best understood as an execution router attached to Juicebox, not as
 | `JBRouterTerminalRegistry` | Registry and proxy surface that lets a project choose and optionally lock its preferred router terminal. |
 | `JBPayRouteResolver` | Helper that evaluates pay-route candidates and selects the strongest route preview the router can resolve. |
 
-## Mental Model
+## Mental model
 
 There are three separate decisions on the payment path:
 
@@ -56,21 +56,21 @@ The shortest useful reading order is:
 2. `JBRouterTerminalRegistry`
 3. the downstream terminal selected through `JBDirectory`
 
-## Read These Files First
+## Read these files first
 
 1. `src/JBRouterTerminal.sol`
 2. `src/JBRouterTerminalRegistry.sol`
 3. `src/libraries/JBSwapLib.sol`
 4. the downstream terminal implementation in `nana-core-v6`
 
-## Integration Traps
+## Integration traps
 
 - projects that expose a router terminal still settle into ordinary Juicebox terminals underneath
 - route discovery and route execution are related but not identical, especially when liquidity or caller-supplied quote data moves
 - using JB project tokens as router input creates recursive path complexity that frontends and integrators should model explicitly
 - the registry changes which router a project uses, but not what downstream terminal ultimately settles the payment
 
-## Where State Lives
+## Where state lives
 
 - route-selection logic: `JBRouterTerminal`
 - per-project router choice and lock status: `JBRouterTerminalRegistry`
@@ -78,7 +78,7 @@ The shortest useful reading order is:
 
 That separation is why a successful route can still end in downstream terminal behavior you did not expect.
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/RouterTerminal.t.sol`
 2. `test/RouterTerminalPreviewFork.t.sol`
@@ -105,11 +105,11 @@ Useful scripts:
 - `npm run deploy:mainnets`
 - `npm run deploy:testnets`
 
-## Deployment Notes
+## Deployment notes
 
 This package depends on core, address-registry, and permission-ID packages plus Uniswap V3, V4, and Permit2 integrations. It is meant to sit in front of canonical Juicebox terminals, not replace them.
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -125,7 +125,7 @@ script/
   helpers/
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - the router synthesizes accounting context for discovery and should not be treated as an accounting-truth surface
 - swap previews are best-effort estimates and depend on current pool state plus caller-supplied quote data
@@ -135,7 +135,7 @@ script/
 
 The most common reader mistake here is to stop at the router and forget to inspect the terminal that actually receives the value.
 
-## For AI Agents
+## For AI agents
 
 - Do not claim the router is the accounting source of truth after forwarding.
 - Read the preview, recursive cash-out, and registry tests before summarizing path selection behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.62",
+  "version": "0.0.64",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,10 +24,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.66",
-    "@bananapus/core-v6": "^0.0.78",
+    "@bananapus/buyback-hook-v6": "^0.0.68",
+    "@bananapus/core-v6": "^0.0.81",
     "@bananapus/permission-ids-v6": "^0.0.28",
-    "@bananapus/univ4-router-v6": "^0.0.46",
+    "@bananapus/univ4-router-v6": "^0.0.51",
     "@openzeppelin/contracts": "5.6.1",
     "@uniswap/permit2": "github:Uniswap/permit2#cc56ad0f3439c502c246fc5cfcc3db92bb8b7219",
     "@uniswap/v3-core": "github:Uniswap/v3-core#6562c52e8f75f0c10f9deaf44861847585fc8129",

package/references/operations.md

@@ -1,12 +1,12 @@
 # Router Terminal Operations
 
-## Configuration Surface
+## Configuration surface
 
 - [`src/JBRouterTerminalRegistry.sol`](../src/JBRouterTerminalRegistry.sol) is the first stop for per-project terminal choice, default terminal behavior, allowlisting, and locking.
 - [`src/JBRouterTerminal.sol`](../src/JBRouterTerminal.sol) owns the metadata-driven route selection and execution logic.
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) is the deployment entry point when the task is about current deployment wiring rather than core routing logic.
 
-## Change Checklist
+## Change checklist
 
 - If you edit route discovery, verify both direct acceptance and swap-based routes.
 - If you edit the cash-out loop, check project-token cash-out flows and fork tests, not only simple payments.
@@ -15,7 +15,7 @@
 - If you edit refund or partial-fill handling, verify baseline snapshots and destination-terminal receipt enforcement together.
 - If you touch Permit2 or metadata parsing, verify the corresponding interfaces and structs in `src/interfaces/` and `src/structs/` together with the fork tests.
 
-## Common Failure Modes
+## Common failure modes
 
 - Router behavior looks wrong, but the real issue is the downstream terminal's accepted-token or accounting behavior.
 - Preview output drifts from execution because quote and execution paths were edited independently.
@@ -23,7 +23,7 @@
 - Metadata overrides force an output token or cash-out source that the caller did not intend.
 - On `addToBalanceOf` paths, a terminal-facing ERC-20 receipt mismatch indicates a non-standard final-hop token path.
 
-## Useful Proof Points
+## Useful proof points
 
 - [`test/RouterTerminalRegistry.t.sol`](../test/RouterTerminalRegistry.t.sol) for registry rules.
 - [`test/RouterTerminalERC2771.t.sol`](../test/RouterTerminalERC2771.t.sol) for trusted-forwarder behavior.

package/references/runtime.md

@@ -1,12 +1,12 @@
 # Router Terminal Runtime
 
-## Contract Roles
+## Contract roles
 
 - [`src/JBRouterTerminal.sol`](../src/JBRouterTerminal.sol) is the main execution surface. It accepts input tokens, discovers the output token, performs conversion, and forwards settlement to the downstream terminal.
 - [`src/JBRouterTerminalRegistry.sol`](../src/JBRouterTerminalRegistry.sol) selects a per-project router terminal or falls back to the default one, while enforcing allowlist and lock rules.
 - Helper logic in [`src/JBPayRouteResolver.sol`](../src/JBPayRouteResolver.sol) and the repo's interfaces/structs define how pay-route resolution and metadata-driven routing fit together.
 
-## Runtime Path
+## Runtime path
 
 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.
@@ -14,7 +14,7 @@
 4. It converts value through direct forwarding, wrap/unwrap, Uniswap V3, or Uniswap V4.
 5. It forwards the final asset to the destination project's canonical terminal.
 
-## High-Risk Areas
+## 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 searches both vanilla V4 pools and pools using the configured canonical `UNIV4_HOOK`.
@@ -25,7 +25,7 @@
 - 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
+## 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/RouterTerminalFeeCashOutFork.t.sol`](../test/RouterTerminalFeeCashOutFork.t.sol) for project-token cash-out routing.

package/src/JBPayRouteResolver.sol

@@ -23,6 +23,8 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when no usable, non-circular terminal route can be resolved to pay the project with the input
+    /// token.
     error JBRouterTerminal_NoRouteFound(uint256 projectId, address tokenIn);
 
     //*********************************************************************//
@@ -843,7 +845,22 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @inheritdoc IJBPayRouteResolver
+    /// @notice Preview the best pay route for a router terminal.
+    /// @param router The router terminal whose preview helpers to use.
+    /// @param wrappedNativeToken The router's wrapped-native-token address, passed in so the resolver does not have to
+    /// call back into the router for it on every normalization step.
+    /// @param projectId The destination project that would receive the payment.
+    /// @param tokenIn The token currently available to route.
+    /// @param amount The amount of `tokenIn` to preview.
+    /// @param beneficiary The address whose minted token count to optimize.
+    /// @param metadata Metadata forwarded into route and pay previews.
+    /// @return destTerminal The terminal chosen for the best previewed route.
+    /// @return tokenOut The token `destTerminal` would receive.
+    /// @return amountOut The amount of `tokenOut` that would be paid.
+    /// @return ruleset The ruleset returned by the chosen terminal preview.
+    /// @return beneficiaryTokenCount The effective beneficiary token count for the chosen route.
+    /// @return reservedTokenCount The effective reserved token count for the chosen route.
+    /// @return hookSpecifications The hook specifications returned by the chosen terminal preview.
     function previewBestPayRoute(
         IJBPayRoutePreviewer router,
         address wrappedNativeToken,
@@ -1128,7 +1145,14 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         });
     }
 
-    /// @inheritdoc IJBPayRouteResolver
+    /// @notice Determine what output token a project accepts for a given input token.
+    /// @param router The router whose view helpers to use.
+    /// @param wrappedNativeToken The router's wrapped-native-token address.
+    /// @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`.
     function resolveTokenOut(
         IJBPayRoutePreviewer router,
         address wrappedNativeToken,
@@ -1149,7 +1173,11 @@ contract JBPayRouteResolver is IJBPayRouteResolver {
         });
     }
 
-    /// @inheritdoc IJBPayRouteResolver
+    /// @notice Resolve a project's primary terminal only when the router can safely forward into it.
+    /// @param router The router whose forwarding-terminal rules to apply.
+    /// @param projectId The project to check the primary terminal for.
+    /// @param token The token that terminal should accept.
+    /// @return terminal The usable primary terminal, or address(0) if none is usable.
     function usablePrimaryTerminalOf(
         IJBPayRoutePreviewer router,
         uint256 projectId,

package/src/JBRouterTerminal.sol

@@ -72,25 +72,62 @@ contract JBRouterTerminal is
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the chain-specific constants have already been set and cannot be reconfigured.
     error JBRouterTerminal_AlreadyConfigured();
+
+    /// @notice Thrown when an amount exceeds the maximum width a swap quote or pool call can represent.
     error JBRouterTerminal_AmountOverflow(uint256 amount);
+
+    /// @notice Thrown when a Uniswap V3 swap callback caller is not the expected pool for the swapped token pair.
     error JBRouterTerminal_CallerNotPool(address caller);
+
+    /// @notice Thrown when an unlock callback caller is not the Uniswap V4 pool manager.
     error JBRouterTerminal_CallerNotPoolManager(address caller);
+
+    /// @notice Thrown when a non-zero cash-out hop reclaims no tokens, so the route cannot safely continue.
     error JBRouterTerminal_CashOutDidNotDeliver(address sourceToken, address tokenToReclaim, uint256 cashOutCount);
+
+    /// @notice Thrown when a cash-out route exceeds the maximum number of hops allowed.
     error JBRouterTerminal_CashOutLoopLimit(uint256 maxIterations);
+
+    /// @notice Thrown when a pool's TWAP history is shorter than the minimum window required to resist manipulation.
     error JBRouterTerminal_InsufficientTwapHistory(address pool, uint256 twapWindow, uint256 minTwapWindow);
+
+    /// @notice Thrown when a leg with no downstream slippage backstop has no manipulation-resistant TWAP and the
+    /// caller did not supply a `pay` quote.
     error JBRouterTerminal_ManipulationResistantQuoteRequired(PoolId poolId);
+
+    /// @notice Thrown when no terminal exposes a reclaimable token that can advance a cash-out route.
     error JBRouterTerminal_NoCashOutPath(uint256 sourceProjectId, uint256 destProjectId);
+
+    /// @notice Thrown when the chosen pool has no in-range liquidity to swap against.
     error JBRouterTerminal_NoLiquidity(address pool, PoolId poolId);
+
+    /// @notice Thrown when native tokens are sent on a call that does not accept them.
     error JBRouterTerminal_NoMsgValueAllowed(uint256 value);
+
+    /// @notice Thrown when a pool has no oracle observation history, so no TWAP can be formed.
     error JBRouterTerminal_NoObservationHistory(address pool);
+
+    /// @notice Thrown when no Uniswap V3 or V4 pool exists for the requested token pair.
     error JBRouterTerminal_NoPoolFound(address tokenIn, address tokenOut);
+
+    /// @notice Thrown when the amount a terminal actually received differs from the amount the router routed to it,
+    /// indicating a lossy or non-standard token path.
     error JBRouterTerminal_NonStandardTerminalToken(
         address terminal, address token, uint256 expectedAmount, uint256 actualAmount
     );
+
+    /// @notice Thrown when the payment amount exceeds the Permit2 allowance provided in the metadata.
     error JBRouterTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
+
+    /// @notice Thrown when the token a `pay` quote was bound to does not match the route's resolved output token.
     error JBRouterTerminal_QuoteTokenMismatch(address quotedTokenOut, address expectedTokenOut);
+
+    /// @notice Thrown when a swap or cash-out output falls below the caller's minimum acceptable amount.
     error JBRouterTerminal_SlippageExceeded(uint256 amountOut, uint256 minAmountOut);
+
+    /// @notice Thrown when the caller is not the deployer authorized to set chain-specific constants.
     error JBRouterTerminal_Unauthorized(address caller);
 
     //*********************************************************************//
@@ -1232,8 +1269,7 @@ contract JBRouterTerminal is
                 tokenToReclaim: tokenToReclaim,
                 minTokensReclaimed: 0,
                 beneficiary: payable(address(this)),
-                metadata: hopMetadata,
-                referralProjectId: 0
+                metadata: hopMetadata
             });
 
             // Measure the reclaimed-token balance delta so fee-on-transfer behavior cannot fake delivery.

package/src/JBRouterTerminalRegistry.sol

@@ -40,19 +40,38 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when an amount exceeds the maximum width a forwarded terminal call can represent.
     error JBRouterTerminalRegistry_AmountOverflow(uint256 amount);
+
+    /// @notice Thrown when attempting to disallow the terminal that is currently set as the default.
     error JBRouterTerminalRegistry_CannotDisallowDefaultTerminal(IJBTerminal terminal);
+
+    /// @notice Thrown when a terminal would forward a project back into this registry, directly or transitively.
     error JBRouterTerminalRegistry_CircularForward(IJBTerminal terminal);
+
+    /// @notice Thrown when native tokens are sent on a call that does not accept them.
     error JBRouterTerminalRegistry_NoMsgValueAllowed(uint256 value);
+
+    /// @notice Thrown when the payment amount exceeds the Permit2 allowance provided in the metadata.
     error JBRouterTerminalRegistry_PermitAllowanceNotEnough(uint256 amount, uint256 allowanceAmount);
+
+    /// @notice Thrown when changing a project's terminal after its terminal choice has been permanently locked.
     error JBRouterTerminalRegistry_TerminalLocked(uint256 projectId);
+
+    /// @notice Thrown when the project's resolved terminal does not match the terminal the caller expected to lock.
     error JBRouterTerminalRegistry_TerminalMismatch(IJBTerminal currentTerminal, IJBTerminal expectedTerminal);
+
+    /// @notice Thrown when selecting a terminal that is not on the registry allowlist.
     error JBRouterTerminalRegistry_TerminalNotAllowed(IJBTerminal terminal);
+
+    /// @notice Thrown when a project has no explicit terminal and no default terminal has ever been set.
     error JBRouterTerminalRegistry_TerminalNotSet(uint256 projectId);
+
+    /// @notice Thrown when setting the default terminal to the zero address.
     error JBRouterTerminalRegistry_ZeroAddress(address terminal);
 
     //*********************************************************************//
-    // -------------------- public immutable properties ------------------ //
+    // ---------------- public immutable stored properties --------------- //
     //*********************************************************************//
 
     /// @notice The Juicebox project registry used to verify project existence and ownership.
@@ -108,7 +127,7 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     // -------------------- transient stored properties ------------------ //
     //*********************************************************************//
 
-    /// @inheritdoc IJBPayerTracker
+    /// @notice The original payer of the current transaction.
     address public transient override originalPayer;
 
     //*********************************************************************//
@@ -275,7 +294,9 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
         });
     }
 
-    /// @inheritdoc IJBForwardingTerminal
+    /// @notice The concrete terminal this forwarding layer would route a project's payment into.
+    /// @param projectId The project whose downstream terminal should be resolved.
+    /// @return terminal The concrete terminal the forwarder would call for `projectId`.
     function terminalOf(uint256 projectId) external view override returns (IJBTerminal terminal) {
         return _resolvedTerminalOf(projectId);
     }