@bananapus/router-terminal-v6 0.0.24 → 0.0.25

package/ADMINISTRATION.md

@@ -2,6 +2,32 @@
 
 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.
+
+## One-Way Or High-Risk Actions
+
+- `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.
+
+## Recovery Notes
+
+- 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.
+
 ## Roles
 
 ### 1. Registry Owner (Ownable)
@@ -13,18 +39,10 @@ Admin privileges and their scope in nana-router-terminal-v6.
 ### 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` (29).
+**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. Router Terminal Owner (Ownable)
-
-**Contract**: `JBRouterTerminal`
-**Assigned via**: Constructor parameter `owner`, transferable via `Ownable.transferOwnership()`.
-**Scope**: Currently unused. `JBRouterTerminal` inherits `Ownable` but does not gate any functions behind `onlyOwner`. The owner exists for potential future use or subclass extensions. The `Ownable.renounceOwnership()` and `Ownable.transferOwnership()` functions are inherited but have no practical effect on the terminal's operation.
-
-**Risk note:** While the owner has no current powers over the terminal's operation, the `Ownable` inheritance means a future code change or subclass could introduce `onlyOwner`-gated functions. If the terminal is deployed with a specific owner address, that address retains transfer rights indefinitely.
-
-### 4. Credit Cashout Payer (Implicit)
+### 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`.
@@ -40,7 +58,7 @@ When a payment is forwarded through the registry, the terminal is resolved as fo
 
 **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.
 
-**Disallow interaction:** If the registry owner calls `disallowTerminal()` on the current default terminal, the `defaultTerminal` is automatically cleared (set to `address(0)`). Projects relying on the default (without locking) would lose their terminal resolution until a new default is set. Projects should lock their terminal to avoid disruption.
+**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.
 
 ## Privileged Functions
 
@@ -49,17 +67,10 @@ When a payment is forwarded through the registry, the terminal is resolved as fo
 | 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. Also clears `defaultTerminal` if it matches the disallowed terminal. Does NOT affect projects that have already locked their terminal. |
+| `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` (29) | 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` (29) | 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.** |
-
-### JBRouterTerminal
-
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|--------------|
-| `transferOwnership(newOwner)` | Owner | `onlyOwner` (inherited) | Global | Transfers contract ownership. No functions currently gated by ownership. |
-| `renounceOwnership()` | Owner | `onlyOwner` (inherited) | Global | Renounces contract ownership. No functions currently gated by ownership. |
+| `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.** |
 
 ### Implicit Permission Requirements (not `onlyOwner`, but enforced by external contracts)
 
@@ -76,15 +87,15 @@ The following values are set at deploy time and cannot be changed:
 
 | 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 |
 | `DIRECTORY` | Constructor | No | JB directory for terminal/controller lookups |
-| `PROJECTS` | Constructor | No | JB project NFT registry |
 | `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 |
@@ -120,7 +131,7 @@ What admins **cannot** do:
 - **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 Owner Cannot:
+### 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.

package/ARCHITECTURE.md

@@ -1,116 +1,68 @@
-# nana-router-terminal-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-Payment routing terminal for Juicebox V6. Accepts any token and dynamically discovers what each destination project accepts, then routes payment via direct forwarding, Uniswap swap (V3 or V4), JB token cashout, or a combination.
+`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.
 
-## Contract Map
+## Boundaries
 
-```
-src/
-├── JBRouterTerminal.sol         — Payment routing: swap + forward to destination terminal
-├── JBRouterTerminalRegistry.sol — Registry mapping projects to router terminal configs
-├── interfaces/
-│   ├── IJBPayerTracker.sol
-│   ├── IJBRouterTerminal.sol
-│   ├── IJBRouterTerminalRegistry.sol
-│   └── IWETH9.sol
-├── libraries/
-│   └── JBSwapLib.sol            — Uniswap V3/V4 swap helpers, pool discovery
-└── structs/
-    └── PoolInfo.sol             — Cached pool configuration
-```
-
-## Key Data Flow
-
-### Payment Routing
-```
-Payer → JBRouterTerminal.pay(projectId, token, amount)
-  │
-  ├─ Accept funds (msg.value for native, Permit2 pull for ERC-20, or credit transfer)
-  │
-  ├─ If input is a JB project token (credit or ERC-20):
-  │    → Cash out recursively via _cashOutLoop (up to 20 hops)
-  │    → Reclaimed token becomes the new tokenIn
-  │
-  ├─ Resolve tokenOut: what does the destination project accept?
-  │    1. Metadata override ("routeTokenOut")
-  │    2. Direct acceptance — project already accepts tokenIn
-  │    3. NATIVE ↔ WETH equivalence check
-  │    4. Dynamic discovery — iterate project terminals, find swappable token
-  │
-  ├─ Convert tokenIn → tokenOut via _convert:
-  │    ├─ Same token: no-op
-  │    ├─ NATIVE ↔ WETH: wrap (WETH.deposit) or unwrap (WETH.withdraw)
-  │    └─ Different tokens: Uniswap swap
-  │         │
-  │         ├─ If native ETH input: held as raw ETH until V3 callback
-  │         │   wraps (WETH.deposit) only the amount the pool consumes
-  │         │
-  │         ├─ Pool discovery (_discoverPool):
-  │         │   Search V3 pools across 4 fee tiers (0.3%, 0.05%, 1%, 0.01%)
-  │         │   Search V4 pools across same fee tiers (if PoolManager deployed)
-  │         │   Compare in-range liquidity across all candidates
-  │         │   Select the single pool with highest liquidity
-  │         │
-  │         ├─ Quote & slippage (_pickPoolAndQuote):
-  │         │   1. User-provided quote (metadata "quoteForSwap") — used as-is
-  │         │   2. V3 fallback: 10-min TWAP via OracleLibrary.consult()
-  │         │   3. V4 fallback: TWAP from oracle hook if available, else spot price from getSlot0()
-  │         │   Apply sigmoid slippage: minSlippage + range * impact/(impact+K)
-  │         │
-  │         ├─ Execute swap via V3 pool.swap() or V4 POOL_MANAGER.unlock()
-  │         │
-  │         ├─ If native ETH input: wrap any remaining raw ETH (partial fills)
-  │         ├─ If native ETH output: unwrap WETH → ETH (WETH.withdraw)
-  │         └─ Return leftover input tokens via _resolveRefundWithBackupRecipient (checks msg.sender's IJBPayerTracker.originalPayer() via try-catch, falls back to beneficiary for pay() or _msgSender() for addToBalanceOf())
-  │
-  ├─ Approve destination terminal for output tokens (or set msg.value for native)
-  └─ Forward to destTerminal.pay() → return beneficiary token count
-```
+- 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.
 
-### Preview Routing
-```
-Caller → JBRouterTerminal.previewPayFor(projectId, token, amount)
-  → Mirror source-of-funds and routing logic in view context
-  → If direct, wrap-unwrap, or exact cashout route: forward preview to destination terminal
-  → If swap route: estimate output using the same quote-selection logic used for execution bounds
-```
-
-## Extension Points
+## Main Components
 
-| Point | Interface | Purpose |
-|-------|-----------|---------|
-| Terminal | `IJBTerminal` | Acts as a terminal that routes payments |
-| Registry | `IJBRouterTerminalRegistry` | Maps projects to routing configs |
-| Payer tracker | `IJBPayerTracker` | Exposes the original payer of a forwarded call for refund resolution |
-| Permit | `IJBPermitTerminal` | Permit2 token approval support |
+| 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 |
 
-## Composition Boundary
+## Runtime Model
 
-The router terminal exposes the `IJBTerminal` surface because it needs to participate in Juicebox routing, but its
-accounting context is intentionally synthetic. `accountingContextForTokenOf()` returns `decimals = 18` for native
-tokens and probes `IERC20Metadata.decimals()` for ERC-20s (falling back to `18` if the call fails). The registry
-forwards that value unchanged. Treat the router layer as a payment router only, not as an accounting-sensitive
-terminal source for loan sizing, debt normalization, or any other decimals-dependent logic.
+```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
+```
 
-## Design Decisions
+## Critical Invariants
 
-**Why the router is a terminal, not a standalone contract.** By implementing `IJBTerminal`, the router can be set as a project's terminal in the directory. Payers and frontend integrations call the same `pay()` / `addToBalanceOf()` interface they use for any terminal — no special routing code required on the caller side. The router accepts funds, converts them, and forwards to the real destination terminal in a single transaction.
+- 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.
 
-**Why both Uniswap V3 and V4 support.** V4 pools may offer deeper liquidity for certain pairs (especially native-ETH pairs that V4 handles natively), while V3 pools have years of established liquidity. The router searches both and picks the pool with the highest in-range liquidity, giving payers the best available execution without requiring them to know which protocol version has the better pool.
+## Where Complexity Lives
 
-**Why synthetic accounting contexts.** The router accepts any token and converts it before forwarding. It never holds balances between transactions, so it has no meaningful accounting of its own. `accountingContextForTokenOf()` returns a best-effort context (probing `decimals()` with an 18-decimal fallback) purely so the directory can register it. The real accounting happens at the destination terminal.
+- 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.
 
-**Why the registry pattern.** `JBRouterTerminalRegistry` lets project owners lock a specific `JBRouterTerminal` instance for their project and manage Permit2 approvals in one place. This provides a stable entry point: if the router implementation is upgraded, the registry can be pointed to the new instance without changing the project's directory entry. It also gates which router terminals are allowed, preventing untrusted implementations from being set.
+## Dependencies
 
-**Why `IJBPayerTracker` is a separate interface.** The router terminal needs to know the original payer when called through an intermediary so it can return leftover tokens from partial swap fills to the right address. Rather than coupling the router to `IJBRouterTerminalRegistry` specifically, the refund resolution logic (`_resolveRefundWithBackupRecipient`) queries `IJBPayerTracker(msg.sender).originalPayer()` via a try-catch. This means any contract that implements `IJBPayerTracker` -- not just the registry -- can act as a forwarding intermediary. The registry inherits `IJBPayerTracker` through `IJBRouterTerminalRegistry`, keeping backward compatibility while opening the door for other intermediary patterns.
+- `nana-core-v6` terminal and directory surfaces
+- Uniswap V3, Uniswap V4, and Permit2
+- Optional `IJBPayerTracker` intermediaries for refund attribution
 
-**Why liquidity-based pool selection instead of quote comparison.** Comparing actual output quotes across V3 and V4 would require executing (or simulating) swaps on both — expensive on-chain and complex for V4 where swaps must go through `PoolManager.unlock()`. Comparing in-range liquidity is a single `liquidity()` or `getLiquidity()` read per pool, is gas-cheap, and strongly correlates with execution quality for typical swap sizes.
+## Safe Change Guide
 
-## Dependencies
-- `@bananapus/core-v6` — Terminal, directory, permissions
-- `@uniswap/v3-core` + `v3-periphery` — V3 swap routing
-- `@uniswap/v4-core` — V4 pool manager
-- `@uniswap/permit2` — Token approvals
-- `@openzeppelin/contracts` — SafeERC20, ERC2771, Ownable
+- 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.