@bananapus/router-terminal-v6 0.0.26 → 0.0.27

package/ADMINISTRATION.md

@@ -1,152 +1,80 @@
 # Administration
 
-Admin privileges and their scope in nana-router-terminal-v6.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| Scope | Registry-level selection of router terminal implementations plus immutable router-terminal swap and forwarding behavior. |
-| Operators | Registry owner for the global allowlist/default, project owners or `SET_ROUTER_TERMINAL` delegates for per-project selection, and users who must supply valid routing metadata. |
-| Highest-risk actions | Locking a project to the wrong terminal, changing the default terminal without understanding who inherits it, or assuming the router is an accounting-truth surface when it is not. |
-| Recovery posture | Unlocked projects can switch terminals. Locked projects keep the stored terminal choice, so recovery requires moving the project to a different admin path outside the registry. |
-
-## Routine Operations
-
-- Keep the registry allowlist limited to router terminal implementations you actually want projects to choose from.
-- Change the default terminal only when you are comfortable affecting every project that still relies on fallback resolution.
-- Encourage projects to lock their terminal only after verifying the resolved terminal address and expected routing behavior.
-- For credit-cashout routing, verify the payer has granted the router terminal the needed `TRANSFER_CREDITS` permission before relying on that path.
+| --- | --- |
+| 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 |
 
-## One-Way Or High-Risk Actions
+## Purpose
 
-- `lockTerminalFor` is irreversible.
-- The current default terminal cannot be disallowed; the registry owner must move the default first before removing the old implementation from the allowlist.
+`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`.
 
-## Recovery Notes
+## Control Model
 
-- If the default terminal is wrong, update the registry quickly before more projects snapshot it through `lockTerminalFor`.
-- If a project already locked the wrong terminal, the registry cannot unlock it; recovery has to happen by migrating the project's broader terminal setup elsewhere.
+- `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
 
-### 1. Registry Owner (Ownable)
-
-**Contract**: `JBRouterTerminalRegistry`
-**Assigned via**: Constructor parameter `owner`, transferable via `Ownable.transferOwnership()`.
-**Scope**: Global -- controls which router terminals can be used by any project and sets the system-wide default terminal.
-
-### 2. Project Owner / SET_ROUTER_TERMINAL Delegate
-
-**Contract**: `JBRouterTerminalRegistry`
-**Assigned via**: Ownership of the project's ERC-721 NFT (via `JBProjects.ownerOf(projectId)`), or delegation via `JBPermissions` with permission ID `SET_ROUTER_TERMINAL` (30).
-**Scope**: Per-project -- controls which router terminal a specific project uses, and can permanently lock that choice.
-
-### 3. Credit Cashout Payer (Implicit)
-
-**Contract**: `JBRouterTerminal`
-**Required permission**: `TRANSFER_CREDITS` (permission ID 13) -- must be granted by the payer to the router terminal address for the source project via `JBPermissions`.
-**Scope**: Per-transaction. Required only when using the `cashOutSource` metadata key to route payments through credit cashouts.
-
-## Terminal Resolution
+| 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 |
 
-When a payment is forwarded through the registry, the terminal is resolved as follows:
+## Privileged Surfaces
 
-1. If the project has called `setTerminalFor(projectId, terminal)`, that explicit terminal is used.
-2. If no explicit terminal is set, the registry's `defaultTerminal` is used.
-3. If neither exists, the forwarding reverts.
+| 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 |
 
-**Lock semantics:** When `lockTerminalFor()` is called on a project with no explicit terminal, the current default is snapshot into `_terminalOf[projectId]` before locking. The project becomes independent of future default changes.
+## Immutable And One-Way
 
-**Disallow interaction:** The registry owner cannot disallow the current default terminal. `disallowTerminal()` reverts with `JBRouterTerminalRegistry_CannotDisallowDefaultTerminal` until `setDefaultTerminal()` has moved the default elsewhere first. Projects relying on the default therefore keep a valid fallback terminal unless the owner explicitly changes that default.
+- `lockTerminalFor(...)` is irreversible.
+- Constructor dependencies on the router are immutable.
+- The current default terminal must move before the old default can be disallowed.
 
-## Privileged Functions
+## Operational Notes
 
-### JBRouterTerminalRegistry
+- 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 operationally.
+- Distinguish configuration risk from quote-quality risk: some route-discovery paths are best-effort, and some V4 quote paths can rely on weaker spot-style assumptions when robust history is unavailable.
 
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|--------------|
-| `allowTerminal(terminal)` | Registry Owner | `onlyOwner` | Global | Adds a terminal to the allowlist (`isTerminalAllowed[terminal] = true`). Projects can only use allowlisted terminals. |
-| `disallowTerminal(terminal)` | Registry Owner | `onlyOwner` | Global | Removes a terminal from the allowlist. Reverts if `terminal` is the current `defaultTerminal`, so the owner must move the default first. Does NOT affect projects that have already locked their terminal or explicitly set another terminal. |
-| `setDefaultTerminal(terminal)` | Registry Owner | `onlyOwner` | Global | Sets the default terminal for all projects that have not set a project-specific terminal. Also auto-allows the terminal. |
-| `setTerminalFor(projectId, terminal)` | Project Owner or Delegate | `SET_ROUTER_TERMINAL` (30) | Per-project | Routes a specific project to a specific allowed terminal. Reverts if the terminal is not allowlisted or if the project's terminal is locked. |
-| `lockTerminalFor(projectId, expectedTerminal)` | Project Owner or Delegate | `SET_ROUTER_TERMINAL` (30) | Per-project | Permanently locks the terminal choice for a project. If no explicit terminal is set, snapshots the current default into `_terminalOf[projectId]`. Reverts with `TerminalMismatch` if the resolved terminal differs from `expectedTerminal` (race condition protection). **Irreversible.** |
+## Machine Notes
 
-### Implicit Permission Requirements (not `onlyOwner`, but enforced by external contracts)
+- Do not treat registry ownership as authority to override locked project choice.
+- Inspect `src/JBRouterTerminalRegistry.sol` and `src/JBRouterTerminal.sol` separately; they govern different control boundaries.
+- If the effective terminal resolution and the documented default differ, stop and resolve the 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 across all pools and states.
 
-| Operation | Required By | Permission | What Happens |
-|-----------|------------|------------|--------------|
-| Credit cashout via `cashOutSource` metadata | Payer | `TRANSFER_CREDITS` (13) granted to router terminal | `TOKENS.transferCreditsFrom()` pulls credits from payer. Reverts if payer has not granted the permission. |
-| Cashout execution | Router terminal (as holder) | None (terminal holds the tokens) | `IJBCashOutTerminal.cashOutTokensOf()` is called with the router as the holder. The router already holds the tokens from the credit transfer or prior cashout step. |
+## Recovery
 
-## Immutable Configuration
+- 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, not with an owner-only hotfix.
 
-The following values are set at deploy time and cannot be changed:
-
-### JBRouterTerminal
-
-| Property | Set At | Mutable? | Description |
-|----------|--------|----------|-------------|
-| `Trusted forwarder` | Constructor | No | ERC-2771 trusted forwarder for meta-transactions |
-| `DIRECTORY` | Constructor | No | JB directory for terminal/controller lookups |
-| `TOKENS` | Constructor | No | JB token manager for credit transfers and project token lookups |
-| `FACTORY` | Constructor | No | Uniswap V3 factory for pool discovery and callback verification |
-| `POOL_MANAGER` | Constructor | No | Uniswap V4 PoolManager (can be `address(0)` to disable V4) |
-| `PERMIT2` | Constructor | No | Permit2 contract for gasless approvals |
-| `WETH` | Constructor | No | Wrapped ETH contract |
-| `BUYBACK_HOOK` | Constructor | No | Canonical buyback hook whose metadata this router understands |
-| `UNIV4_HOOK` | Constructor | No | Canonical Uniswap V4 hook address searched during hooked-pool discovery |
-| `DEFAULT_TWAP_WINDOW` | Compile-time constant | No | 10 minutes (600 seconds) |
-| `SLIPPAGE_DENOMINATOR` | Compile-time constant | No | 10,000 (basis points) |
-| `_FEE_TIERS` | Storage (initialized) | No | `[3000, 500, 10000, 100]` -- V3 fee tiers |
-| `_V4_FEES` / `_V4_TICK_SPACINGS` | Storage (initialized) | No | V4 pool parameters |
-| `_MAX_CASHOUT_ITERATIONS` | Compile-time constant | No | 20 iterations |
-
-### JBRouterTerminalRegistry
-
-| Property | Set At | Mutable? | Description |
-|----------|--------|----------|-------------|
-| `PERMISSIONS` | Constructor | No | JB permissions registry for permission checks |
-| `Trusted forwarder` | Constructor | No | ERC-2771 trusted forwarder for meta-transactions |
-| `PROJECTS` | Constructor | No | JB project NFT registry |
-| `PERMIT2` | Constructor | No | Permit2 contract for gasless approvals |
-
-### JBPayRouteResolver
-
-| Property | Set At | Mutable? | Description |
-|----------|--------|----------|-------------|
-| `DIRECTORY` | Constructor | No | JB directory for terminal and accounting-context lookups, cached from the router at construction time |
-| `WETH` | Constructor | No | Wrapped native token used for token normalization, cached from the router at construction time |
-
-### JBSwapLib
+## Admin Boundaries
 
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `MAX_SLIPPAGE` | 8,800 (88%) | Maximum slippage tolerance ceiling |
-| `IMPACT_PRECISION` | 1e18 | Precision for impact calculations |
-| `SIGMOID_K` | 5e16 | Sigmoid curve shape parameter |
+- 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.
 
-## Admin Boundaries
+## Source Map
 
-What admins **cannot** do:
-
-### Registry Owner Cannot:
-- **Unlock a locked terminal.** `lockTerminalFor` is irreversible -- there is no `unlockTerminalFor` function.
-- **Override a project's locked terminal choice.** Once locked, the terminal is permanently stored in `_terminalOf[projectId]` and `hasLockedTerminal[projectId]` is permanently `true`.
-- **Force a project to use a specific terminal.** Only the project owner (or delegate) can call `setTerminalFor`.
-- **Access project funds.** The registry is a pass-through; it holds funds transiently during forwarding only.
-- **Modify swap parameters, slippage, or routing logic.** These are controlled by the `JBRouterTerminal` contract, not the registry.
-- **Pause payments.** There is no pause mechanism.
-
-### Router Terminal Maintainers Cannot:
-- **Modify swap slippage parameters.** The TWAP window, sigmoid constants, fee tiers, and max slippage are all immutable.
-- **Redirect funds.** The terminal is stateless between transactions and routes payments to whichever terminal the JB directory specifies.
-- **Change the Uniswap factory or PoolManager.** These are immutable constructor parameters.
-- **Override user-provided quotes.** The `quoteForSwap` metadata is decoded and used as-is.
-- **Prevent specific users from paying.** There is no blocklist mechanism.
-- **Extract stuck funds.** There is no sweep or rescue function. The terminal relies on completing all token movements within a single transaction.
-
-### Project Owner / Delegate Cannot:
-- **Change the terminal after locking.** The `setTerminalFor` function reverts with `TerminalLocked` if the terminal is locked.
-- **Set a disallowed terminal.** `setTerminalFor` reverts with `TerminalNotAllowed` if the terminal is not on the registry owner's allowlist.
-- **Affect other projects' routing.** Permission checks are scoped to the specific `projectId`.
+- `src/JBRouterTerminalRegistry.sol`
+- `src/JBRouterTerminal.sol`
+- `src/JBPayRouteResolver.sol`
+- `test/`

package/ARCHITECTURE.md

@@ -2,67 +2,92 @@
 
 ## 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, unwraps or wraps native assets when needed, optionally cashes out upstream JB project tokens, and swaps through the deepest available Uniswap V3 or V4 route before forwarding the final asset to the destination terminal.
-The router is intentionally heuristic: it does not exhaustively search every viable pool for the absolute best execution price.
+`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, unwraps or wraps 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.
 
-## Boundaries
+The router is intentionally heuristic. It does not search every possible route for a globally optimal price.
 
-- The router is a terminal-shaped payment adapter, not a canonical accounting terminal.
-- It owns routing, swapping, quoting, and refund behavior.
-- Final accounting still occurs at the destination terminal that actually accepts the routed token.
-- Pool selection is optimized for simple, bounded route discovery, not full best-execution search across all candidate pools.
+## System Overview
 
-## Main Components
+`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 occurs in the downstream terminal selected through `nana-core-v6`.
 
-| Component | Responsibility |
-| --- | --- |
-| `JBRouterTerminal` | Source-token intake, route discovery, swapping, and forwarding |
-| `JBRouterTerminalRegistry` | Project-level selection and locking of router terminal instances |
-| `JBPayRouteResolver` | Helper contract that evaluates pay-route preview candidates without bloating router runtime size |
-| `JBSwapLib` | Pool discovery, quoting, and slippage helpers |
-| `PoolInfo`, `CashOutPathCandidates`, and interfaces | Typed routing metadata and registry/payer integration surfaces |
+## Core Invariants
 
-## Runtime Model
+- 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 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; non-converging paths should fail instead of looping.
+- 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 terminal 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 can actually receive
-  -> pick the best direct, wrap/unwrap, or swap route
-  -> execute the route and forward the result to the destination terminal
-  -> return any leftover input to the original payer when possible
+  -> 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
 ```
 
-## Critical Invariants
-
-- The router's own accounting context is synthetic. Consumers should not treat it as the source of truth for project accounting.
-- Pool discovery and quote logic must stay aligned between preview and execution paths.
-- Refund resolution is part of correctness, not ergonomics. Partial fills without correct refunds create value leaks.
-- Registry locking is a security feature; it prevents projects from being silently switched to untrusted router implementations.
-- Final forwarded ERC-20 hops are only supported for standard tokens whose destination-terminal pull transfers the full nominal amount without transfer fees or burns.
-- Circular `router -> registry -> same router` forwarding is blocked in the registry, not by teaching the router about registry internals.
+## Accounting Model
 
-## Where Complexity Lives
+The router does not own project balances. It owns transient route accounting: input reconciliation, swap execution, forwarded amount, and refund resolution.
 
-- The router composes multiple route families: direct, wrap/unwrap, recursive JB cash-out, and DEX swaps.
-- Native-asset handling and refund handling are the most failure-prone parts of the implementation.
-- Liquidity discovery across V3 and V4 is simple to describe but easy to desynchronize between preview and live execution.
-- V4 discovery intentionally searches both vanilla pools and pools using the canonical `UNIV4_HOOK`, because buyback-hook and LP-split integrations rely on that hook-backed oracle path.
-- “Best route” in this system means the best route under the router's discovery heuristic, not a guarantee of globally optimal output across every live pool.
-- Fee-on-transfer or otherwise lossy ERC-20s are only tolerated on ingress where the router can reconcile the received balance delta. They are rejected on the router's final terminal-facing hop. The registry does not perform independent receipt enforcement; it relies on the downstream router terminal to reject lossy transfers.
-- The preview candidate fanout lives in `JBPayRouteResolver`, but downstream `previewPayFor(...)` calls still originate from the router so payer-sensitive previews match execution context.
+Preview and execution share the same conceptual route shape: optional recursive cashout first, then destination-token resolution, then final conversion and forwarding. `JBPayRouteResolver` narrows candidate tokens and usable external terminals so the live router does not need to brute-force every possibility inline.
 
-## Dependencies
+## Security Model
 
-- `nana-core-v6` terminal and directory surfaces
-- Uniswap V3, Uniswap V4, and Permit2
-- Optional `IJBPayerTracker` intermediaries for refund attribution
+- 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. It is not a global optimizer.
+- Recursive cashout behavior, preferred-token handling, and one-shot source overrides are tightly coupled; changing one can silently desynchronize preview from execution.
+- “Best route” means best under the bounded discovery heuristic, not globally optimal routing.
 
 ## Safe Change Guide
 
-- Keep route selection and execution semantics paired. If preview and execution diverge, frontends will misprice user flows.
-- Be cautious with native-token handling; wrap and unwrap edge cases are where routers usually leak value.
-- If you change recursive cash-out behavior, inspect the hop limit and failure modes together.
-- Do not promote the router into a stateful treasury layer.
-- Treat any new convenience path as a new asset-conservation proof obligation.
+- 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`

package/AUDIT_INSTRUCTIONS.md

@@ -2,7 +2,7 @@
 
 This repo accepts one token and routes value into whatever token a destination project actually accepts. Audit it as a stateless router whose mistakes show up as lost value, bad slippage control, or wrong-route accounting.
 
-## Objective
+## Audit Objective
 
 Find issues that:
 - route user funds through an incorrect pool or protocol path
@@ -25,7 +25,13 @@ Key dependencies:
 - `nana-core-v6`
 - Uniswap V3 and V4 integration surfaces
 
-## System Model
+## Start Here
+
+1. `src/JBRouterTerminal.sol`
+2. `src/JBRouterTerminalRegistry.sol`
+3. `src/libraries/JBSwapLib.sol`
+
+## Security Model
 
 The router terminal:
 - discovers what token a project’s terminal accepts
@@ -35,6 +41,22 @@ The router terminal:
 
 The registry chooses which router terminal instance a project uses and whether that choice is locked.
 
+## Roles And Privileges
+
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| User or relayer | Initiate routed payment with beneficiary and slippage intent | Must receive exact refund semantics requested |
+| Registry controller | Set default or allowed router terminals | Must not redirect projects unexpectedly |
+| Router terminal | Hold funds only transiently during routing | Must not retain leftovers across flows |
+
+## Integration Assumptions
+
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `nana-core-v6` | Terminal discovery and pay semantics are accurate | Routed value lands in the wrong place |
+| Uniswap V3 and V4 | Callback settlement and pool discovery are authentic | Slippage and final forwarded amount diverge |
+| Permit2 | Allowances and deadlines reflect user intent | Unauthorized transfer or stuck routing behavior |
+
 ## Critical Invariants
 
 1. User intent is preserved
@@ -49,16 +71,7 @@ The quoted path, callback settlement, and final forwarded amount must all descri
 4. Registry controls stay narrow
 Default terminals, allowed terminals, and lock semantics must not let an unexpected router instance take over project routing.
 
-## Threat Model
-
-Prioritize:
-- V3 or V4 callback reentrancy
-- sandwiching around discovered pool liquidity
-- beneficiary versus payer refund mismatches
-- Permit2 allowance or deadline misuse
-- races around registry terminal locking
-
-## Hotspots
+## Attack Surfaces
 
 - payment entrypoints and refund logic
 - V3 callback verification
@@ -66,18 +79,8 @@ Prioritize:
 - pool discovery and best-path selection
 - registry allowlist and lock behavior
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-Current tests focus on:
-- refund edge cases
-- payer tracking
-- Permit2 failure handling
-- cash-out-assisted routes
-- reentrancy and sandwich-sensitive fork cases
-
-Strong findings in this repo usually show the router holding onto value or satisfying user slippage checks with the wrong sign, recipient, or output token.

package/README.md

@@ -1,9 +1,14 @@
 # Juicebox Router Terminal
 
-`@bananapus/router-terminal-v6` is a routing terminal for Juicebox V6. It accepts value in many input tokens, discovers what token the destination project actually accepts, and forwards the payment through the best available route.
+`@bananapus/router-terminal-v6` is a routing terminal for Juicebox V6. It accepts value in many input tokens, discovers what token the destination project actually accepts, and forwards the payment through the best previewed route it can resolve from the configured candidates.
 
-Docs: <https://docs.juicebox.money>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Docs: <https://docs.juicebox.money>  
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
@@ -16,7 +21,7 @@ It can route through:
 - Uniswap V3 or V4 swaps
 - recursive Juicebox token cash outs when the input itself is a project token
 
-Projects can use the registry contract to choose a project-specific router terminal or fall back to a default.
+Projects can use the registry to choose, and optionally lock, a project-specific router terminal or fall back to the registry's default terminal.
 
 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.
 
@@ -28,7 +33,7 @@ This repo is best understood as an execution router attached to Juicebox, not as
 | --- | --- |
 | `JBRouterTerminal` | Main routing terminal that accepts many token types and forwards value to the destination terminal. |
 | `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 best route preview for the router terminal. |
+| `JBPayRouteResolver` | Helper that evaluates pay-route candidates and selects the strongest route preview the router can resolve. |
 
 ## Mental Model
 
@@ -68,6 +73,14 @@ The shortest useful reading order is:
 
 That separation is the reason a successful route can still end in a downstream terminal behavior you did not expect.
 
+## High-Signal Tests
+
+1. `test/RouterTerminal.t.sol`
+2. `test/RouterTerminalPreviewFork.t.sol`
+3. `test/RouterTerminalCashOutFork.t.sol`
+4. `test/audit/PreviewPrimaryTerminalMismatch.t.sol`
+5. `test/codex/CashOutCircularPrimaryTerminal.t.sol`
+
 ## Install
 
 ```bash
@@ -116,3 +129,9 @@ script/
 - final terminal-facing ERC-20 hops must be standard tokens; lossy terminal pulls are rejected on both router and registry paths
 
 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
+
+- 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.
+- If the route ends in surprising accounting, move to the downstream terminal in `nana-core-v6`.

package/RISKS.md

@@ -29,11 +29,11 @@ This file focuses on the routing, accounting-context, and liquidity-selection ri
 
 ## 2. Economic / Manipulation Risks
 
-- **V4 price manipulation.** `_getV4Quote` first attempts a 30-second TWAP from the pool's oracle hook (e.g., `IGeomeanOracle.observe()`). If no oracle hook exists or the call fails, it falls back to the instantaneous `getSlot0` tick, which is manipulable via sandwich attacks or flash loans. The sigmoid slippage formula provides a floor (min 2%) but does NOT provide full MEV protection. Without user-supplied `quoteForSwap` metadata, V4 swaps using the spot fallback are vulnerable to extraction. Front-ends MUST supply `quoteForSwap` metadata for V4 swaps without oracle hooks. Note: `_getV4Quote` normalizes WETH to `address(0)` before calling OracleLibrary, since V4 uses `address(0)` for native ETH -- without this normalization, token sorting would mismatch the pool's currency ordering and produce inverted quotes.
+- **V4 price manipulation.** `_getV4Quote` first attempts a 30-second TWAP from the pool's oracle hook (e.g., `IGeomeanOracle.observe()`). If no oracle hook exists or the call fails, it falls back to the instantaneous `getSlot0` tick, which is manipulable via sandwich attacks or flash loans. The sigmoid slippage formula provides a floor (min 2%) but does NOT provide full MEV protection. This spot-fallback path is an accepted risk for integrations that cannot source external quotes, particularly when routing routine flow through sufficiently deep pools where manipulation cost is expected to dominate likely extractable value. Deep liquidity reduces practical risk but does not eliminate the same-block manipulation surface. Thin pools, fresh pools, and unusually large swaps should not rely on this fallback. Front-ends SHOULD supply `quoteForSwap` metadata for V4 swaps whenever possible. Note: `_getV4Quote` normalizes WETH to `address(0)` before calling OracleLibrary, since V4 uses `address(0)` for native ETH -- without this normalization, token sorting would mismatch the pool's currency ordering and produce inverted quotes.
 - **Hooked V4 discovery scope.** Auto-discovery checks both vanilla V4 pools and pools using the configured canonical `UNIV4_HOOK`. That keeps buyback-hook and LP-split-hook routes discoverable, but it also means deployment misconfiguration of `UNIV4_HOOK` changes which hooked pools are even visible to the router.
 - **V3 TWAP manipulation.** Short TWAP windows (falls back to `oldestObservation` if < 10 minutes) reduce manipulation resistance. A newly created pool with minimal history can be manipulated within the TWAP window.
 - **Cashout loop value extraction.** `_cashOutLoop` iterates up to 20 times, cashing out JB project tokens recursively. Each cashout incurs bonding curve slippage. `cashOutMinReclaimed` is enforced only on the first concrete cashout hop. Later hops intentionally do not reuse or rescale that minimum, because multi-hop cashouts can change token units and a single metadata amount cannot be propagated safely across different assets. Gas cost: each cashout iteration involves `terminal.cashOutTokensOf` (external call, ~100-200k gas) plus token transfer and balance accounting. At 20 iterations maximum, the worst case is ~4M gas for the loop alone, leaving headroom within a 30M block but consuming a significant portion.
-- **Leftover token handling.** `_handleSwap` refunds the full remaining input token balance after a swap. The router is stateless and should never hold funds between transactions. If tokens are accidentally sent to the contract, they are absorbed into the next caller's refund rather than being permanently stuck — this is intentional, as recovering stuck funds is preferable to locking them forever. There is no sweep mechanism because there should be no persistent balance to sweep.
+- **Pre-existing balances are intentionally not swept into refunds.** `_handleSwap` snapshots a per-route refund baseline and only refunds the leftover input balance attributable to the current route. Tokens or ETH that were already sitting in the router before the route began are excluded from that refund calculation. This avoids gifting prior stray balances to the next caller, but it also means accidentally sent balances can remain stranded because the router has no sweep mechanism.
 - **V4 native ETH settlement.** `_settleV4` unwraps WETH to native ETH when settling a `Currency.wrap(address(0))` debt with PoolManager. This is necessary because the router may hold WETH (from ERC-20 transfers or prior wrapping) but V4 native pools require `msg.value` settlement. If `address(this).balance` is already sufficient, no unwrap occurs.
 - **Pool selection by liquidity.** `_discoverPool` selects the pool with the highest `liquidity()` value. An attacker can deploy a pool with high but concentrated (out-of-range) liquidity to win selection, then manipulate the actual swap execution at worse prices.
 - **Heuristic route selection, not best execution.** Automatic routing chooses among discovered paths using bounded heuristics, and pool discovery prefers the deepest discovered pool rather than exhaustively quoting every viable pool. This is an intentional tradeoff to keep routing predictable and gas-bounded. Integrators should treat router-selected execution as best-effort convenience, not a guarantee of the globally best obtainable output. When execution quality matters more than convenience, frontends should supply `quoteForSwap` metadata.
@@ -67,7 +67,7 @@ This file focuses on the routing, accounting-context, and liquidity-selection ri
 - **Locked bad-terminal risk.** `lockTerminalFor` protects projects from silent migrations, but it also freezes the current resolved terminal exactly as-is. If the locked terminal is malformed, recursively forwards, reverts on use, or otherwise cannot actually process routed payments, the project can be left permanently unroutable through the registry.
 - **forceApprove for terminal transfers.** `_beforeTransferFor` uses `forceApprove`, which resets the allowance to zero before setting the new value. This mitigates stale-allowance accumulation: even if a previous transaction left a non-zero allowance, `forceApprove` overwrites it rather than adding to it. The reset-then-set pattern prevents cumulative allowance drift.
 - **Callback data trust.** `uniswapV3SwapCallback` validates the caller by reconstructing the pool address from `(tokenIn, tokenOut, fee)`. The factory `getPool` lookup makes spoofing infeasible in practice.
-- **receive() function.** The contract accepts arbitrary ETH via `receive()`. This is necessary for WETH unwraps, cashout reclaims, and V4 PoolManager takes. Any ETH received is absorbed into the next swap's leftover refund. Since the router is stateless by design, this is acceptable — funds should not persist between transactions, and recovering accidentally-sent ETH is preferable to locking it permanently.
+- **receive() function.** The contract accepts arbitrary ETH via `receive()`. This is necessary for WETH unwraps, cashout reclaims, and V4 PoolManager takes. Route-specific leftover refunds only return ETH attributable to the active route; arbitrary ETH already sitting in the router before that route is not swept out automatically and can remain stranded.
 
 ## 6. MEV Surface
 
@@ -77,7 +77,7 @@ This file focuses on the routing, accounting-context, and liquidity-selection ri
 
 ## 7. Invariants to Verify
 
-- After any `pay()` or `addToBalanceOf()`, the contract should hold zero tokens (all routed to destination terminal or returned as leftovers).
+- After any `pay()` or `addToBalanceOf()`, the contract should not retain balances attributable to the just-processed route. Pre-existing stray balances may still remain because refund logic intentionally excludes them.
 - `minAmountOut` in swaps is never zero when TWAP/spot price is available (the sigmoid formula has a 2% floor).
 - Callback validation: `uniswapV3SwapCallback` only transfers tokens to verified pool addresses.
 - `unlockCallback` only executes when called by `POOL_MANAGER`.
@@ -95,7 +95,7 @@ The router terminal has no `ReentrancyGuard` or `_routing` flag. This is a consc
 - **Each call uses its own funds.** The re-entrant call would need to supply its own tokens/ETH (via `_acceptFundsFor`). It cannot consume funds belonging to the outer call because those funds are already committed to the routing pipeline.
 - **A reentrancy guard would block legitimate composition.** Projects may have terminal chains where terminal A routes through this router, which cashes out into terminal B, which itself routes through this router for a different project. A blanket reentrancy guard would break such flows.
 
-Verified in `RouterTerminalReentrancy.t.sol`: re-entrant calls via both `pay()` and `addToBalanceOf()` succeed without corrupting the outer call's ETH forwarding. The invariant suite (`RouterTerminalInvariant.t.sol`) further confirms that the router holds zero tokens and zero ETH after every operation — including operations that exercise the cashout recursion loop (`_cashOutLoop`, up to `_MAX_CASHOUT_ITERATIONS = 20`).
+Verified in `RouterTerminalReentrancy.t.sol`: re-entrant calls via both `pay()` and `addToBalanceOf()` succeed without corrupting the outer call's ETH forwarding. The invariant suite (`RouterTerminalInvariant.t.sol`) confirms that routed operations do not strand balances attributable to the active route, including operations that exercise the cashout recursion loop (`_cashOutLoop`, up to `_MAX_CASHOUT_ITERATIONS = 20`). That does not imply the router can never hold pre-existing stray balances, because refund logic intentionally excludes balances that were already present before the route began.
 
 ### 8.2 Router trusts `originalPayer()` from any `msg.sender` that implements it
 
@@ -112,3 +112,7 @@ The router and resolver no longer contain registry-specific circular-resolution
 ### 8.4 Liquidity-first pool selection is intentional
 
 The router does not attempt full best-execution search across every viable V3 and V4 pool. `_discoverPool` prefers the deepest discovered pool, and the selected pool is then quoted and executed. This can underperform an alternative pool in some market states, but it is an accepted product tradeoff: bounded route discovery, lower complexity, and predictable behavior are prioritized over exhaustive output maximization. Users who need tighter execution guarantees should provide `quoteForSwap` metadata or route externally.
+
+### 8.6 V4 spot fallback is an accepted risk for programmatic integrations
+
+Automatic V4 quoting first tries a hook-provided oracle observation and only falls back to spot when no such quote is available. That fallback remains manipulable within the block and is not equivalent to an external quote or a trusted TWAP. It is nevertheless accepted in this terminal because some programmatic integrations cannot provide `quoteForSwap` metadata and still need a bounded on-chain quoting path. The intended operating envelope is routine routing through sufficiently deep pools with moderate swap sizes, where manipulation is possible in principle but expected to be uneconomic in practice. This is a risk reduction argument, not a safety proof: deep liquidity raises attack cost, but does not remove the vulnerability class.

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## Use This File For
 
 - Use this file when the task involves routed payments or cash-outs, swap-path metadata, dynamic accepted-token discovery, route-registry selection, or router-terminal fee and slippage behavior.
-- Start here, then open the terminal, registry, swap helpers, or tests that own the exact behavior in question.
+- Start here, then decide whether the problem is route discovery, swap execution, cash-out recursion, or registry selection. Those are distinct failure modes in this repo.
 
 ## Read This Next
 
@@ -11,9 +11,11 @@
 |---|---|
 | Repo overview and routing model | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | Terminal execution path | [`src/JBRouterTerminal.sol`](./src/JBRouterTerminal.sol) |
+| Pay-route resolution helpers | [`src/JBPayRouteResolver.sol`](./src/JBPayRouteResolver.sol) |
 | Registry behavior and terminal selection | [`src/JBRouterTerminalRegistry.sol`](./src/JBRouterTerminalRegistry.sol) |
 | Shared libraries, interfaces, and metadata structs | [`src/libraries/`](./src/libraries/), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/) |
-| Forked routing behavior, preview parity, and regressions | [`test/RouterTerminalPreviewFork.t.sol`](./test/RouterTerminalPreviewFork.t.sol), [`test/RouterTerminalCashOutFork.t.sol`](./test/RouterTerminalCashOutFork.t.sol), [`test/RouterTerminalReentrancy.t.sol`](./test/RouterTerminalReentrancy.t.sol), [`test/regression/`](./test/regression/) |
+| Preview, cash-out, and buyback composition | [`test/RouterTerminalPreviewFork.t.sol`](./test/RouterTerminalPreviewFork.t.sol), [`test/RouterTerminalCashOutFork.t.sol`](./test/RouterTerminalCashOutFork.t.sol), [`test/RouterTerminalBuybackHookFork.t.sol`](./test/RouterTerminalBuybackHookFork.t.sol), [`test/RouterTerminalFeeCashOutFork.t.sol`](./test/RouterTerminalFeeCashOutFork.t.sol) |
+| Registry, multihop, and adversarial coverage | [`test/RouterTerminalRegistry.t.sol`](./test/RouterTerminalRegistry.t.sol), [`test/RouterTerminalMultihopFork.t.sol`](./test/RouterTerminalMultihopFork.t.sol), [`test/RouterTerminalReentrancy.t.sol`](./test/RouterTerminalReentrancy.t.sol), [`test/RouterTerminalSandwichFork.t.sol`](./test/RouterTerminalSandwichFork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
 
 ## Repo Map
 
@@ -36,6 +38,11 @@ Universal routing terminal for Juicebox V6. This repo accepts many input tokens,
 ## Working Rules
 
 - Start in [`src/JBRouterTerminal.sol`](./src/JBRouterTerminal.sol) for execution behavior, but verify downstream semantics in the destination terminal before treating the router as the source of truth.
+- The router intentionally synthesizes accounting contexts instead of storing a static accepted-token list. If token acceptance looks wrong, verify discovery logic before touching registry state.
 - Treat preview behavior, quote selection, and execution callbacks as tightly coupled. Changes in one usually need verification in the others.
 - When the input token is itself a Juicebox project token, follow the cash-out loop carefully. Recursive routing assumptions are where subtle bugs hide.
+- Multi-hop and buyback-assisted routes are first-class behavior here, not edge cases. Verify them explicitly when changing route selection.
+- Refund handling is route-specific state, not cleanup garnish. Baseline snapshots and partial-fill leftovers are part of correctness.
+- Final terminal-facing receipt enforcement is a real boundary. If a terminal pull or forwarding model is non-standard, prove receipt semantics still hold before weakening guards.
+- Callback guards and final-hop receipt checks are security boundaries. Do not weaken them to accommodate non-standard token paths.
 - If you touch registry behavior, verify project-specific overrides, allowlisting, and terminal locking all still match the intended governance model.