@bananapus/router-terminal-v6 0.0.26 → 0.0.28

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
+- distinguish configuration risk from quote-quality risk
 
-| 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 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
 
-| 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
 
-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,93 @@
 
 ## 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, 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.
 
-## 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.
 
-| 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 |
+Final accounting still happens in the downstream terminal selected through `nana-core-v6`.
 
-## Runtime Model
+## 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 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.
 
-## 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
+- recursive cashout behavior, preferred-token handling, and one-shot source overrides are tightly coupled
 
 ## 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,9 +2,10 @@
 
 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
 - under-deliver relative to quoted or minimum-return semantics
 - refund leftovers to the wrong party or trap them in the router
@@ -14,6 +15,7 @@ Find issues that:
 ## Scope
 
 In scope:
+
 - `src/JBRouterTerminal.sol`
 - `src/JBRouterTerminalRegistry.sol`
 - `src/interfaces/`
@@ -22,43 +24,55 @@ In scope:
 - deployment scripts in `script/`
 
 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
+
+- discovers what token a project's terminal accepts
 - decides whether to route via wrap/unwrap, V3, V4, Juicebox token cash-out, or a combination
 - forwards value into the destination terminal
 - optionally handles Permit2-funded transfers
 
 The registry chooses which router terminal instance a project uses and whether that choice is locked.
 
-## Critical Invariants
-
-1. User intent is preserved
-The actual destination project, beneficiary, minimum output semantics, and refund recipient must match the request and metadata.
+## Roles And Privileges
 
-2. No leftover value disappears
-Partial fills, failed paths, and overfunded inputs must either be forwarded or refunded to the intended party.
+| 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 |
 
-3. Pool discovery and settlement agree
-The quoted path, callback settlement, and final forwarded amount must all describe the same trade.
+## Integration Assumptions
 
-4. Registry controls stay narrow
-Default terminals, allowed terminals, and lock semantics must not let an unexpected router instance take over project routing.
+| 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 |
 
-## Threat Model
+## Critical Invariants
 
-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
+1. User intent is preserved.  
+   The actual destination project, beneficiary, minimum output semantics, and refund recipient must match the request and metadata.
+2. No leftover value disappears.  
+   Partial fills, failed paths, and overfunded inputs must either be forwarded or refunded to the intended party.
+3. Pool discovery and settlement agree.  
+   The quoted path, callback settlement, and final forwarded amount must all describe the same trade.
+4. Registry controls stay narrow.  
+   Default terminals, allowed terminals, and lock semantics must not let an unexpected router instance take over project routing.
 
-## Hotspots
+## Attack Surfaces
 
 - payment entrypoints and refund logic
 - V3 callback verification
@@ -66,18 +80,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 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
 
@@ -14,9 +19,9 @@ It can route through:
 - direct forwarding when the destination already accepts the input token
 - wrapping or unwrapping native ETH and WETH
 - Uniswap V3 or V4 swaps
-- recursive Juicebox token cash outs when the input itself is a project token
+- recursive Juicebox token cash outs when the input is itself 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
 
@@ -55,18 +60,26 @@ The shortest useful reading order is:
 
 ## Integration Traps
 
-- projects that expose a router terminal still settle into ordinary Juicebox terminals underneath; downstream semantics still matter
-- route discovery and route execution are related but not identical, especially when liquidity or metadata-supplied quotes move
+- 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 layer changes who a project routes through, but not what the downstream terminal ultimately is
+- the registry changes which router a project uses, but not what downstream terminal ultimately settles the payment
 
 ## Where State Lives
 
-- route-selection logic lives in `JBRouterTerminal`
-- per-project router choice and lock status live in `JBRouterTerminalRegistry`
-- accepted-token accounting and final balance changes live in the downstream terminal, usually in `nana-core-v6`
+- route-selection logic: `JBRouterTerminal`
+- per-project router choice and lock status: `JBRouterTerminalRegistry`
+- accepted-token accounting and final balance changes: the downstream terminal, usually in `nana-core-v6`
 
-That separation is the reason a successful route can still end in a downstream terminal behavior you did not expect.
+That separation is why a successful route can still end in 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
 
@@ -112,7 +125,13 @@ script/
 - 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
 - recursive cash-out routing increases complexity when the input token is itself a Juicebox project token
-- slippage and sandwich resistance depend on the quality of the quote path chosen for the route
-- final terminal-facing ERC-20 hops must be standard tokens; lossy terminal pulls are rejected on both router and registry paths
+- slippage and sandwich resistance depend on the quality of the chosen quote path
+- final terminal-facing ERC-20 hops must be standard tokens; lossy terminal pulls are rejected
 
 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`.